Oasys.PRIMER functions

AllocateFlag()

Allocate a flag for use in the script. See also ReturnFlag() and Model.PropagateFlag(). Once allocated the flag is automatically cleared for all the models currently in PRIMER

Returns:

Flag

Return type:

int

Example

To allocate a flag

flag = Oasys.PRIMER.AllocateFlag()
BatchMode()

Check if PRIMER is running in “batch mode” (i.e. menus are not active). Menus will not be active if PRIMER is started with the -d=tty command line argument. Note that this is different to starting PRIMER with the -batch command line argument. When using -batch, the menu system is still running, but the main PRIMER window is not shown

Returns:

True if in batch mode, False if not

Return type:

bool

Example

To test if PRIMER is in batch mode

batch_mode = Oasys.PRIMER.BatchMode()
DialogueFunction(name)

Set the function for dialogue callback. This function can be used to make PRIMER return any dialogue messages that are printed. This may be useful for you to know if a particular dialogue message has been printed or a particular event has taken place.
The function will be called with 1 argument which is a string containing the dialogue message. To remove the dialogue function use DialogueFunction(None)

Parameters:

name (function) – The name of the function (or None to remove the function)

Returns:

No return value

Return type:

None

Example

To set function MyDialogueFunction as the dialogue function:

Oasys.PRIMER.DialogueFunction(MyDialogueFunction)
DialogueInput(*command)

Execute one or more lines of command line dialogue input

Parameters:

command (string) – Command to execute (as if it had been typed into the dialogue box) This argument can be repeated if required. Alternatively a single array argument containing the multiple values can be given

Returns:

0: No errors/warnings.
> 0: This number of errors occurred.
< 0: Absolute number is the number of warnings that occurred

Return type:

int

Example

To read two models:

Oasys.PRIMER.DialogueInput("/re dk model_1.key 1", "/re dk model_2.key 2")

Note that each call to DialogueInput starts afresh at the top of the PRIMER command line “tree”, so where multiple commands need to be given at sub-menu levels they need to be included in a single call. For example to restrain degrees of a mechanism assembly, and then move it by some amount:

Oasys.PRIMER.DialogueInput("/mech assy " + assy_number, "fix 123", "done", "point " + point_name, delta_x + " \* \*", "accept")

NOT:

Oasys.PRIMER.DialogueInput("/mech assy " + assy_number)

Oasys.PRIMER.DialogueInput("fix 123")

etc

DialogueInputNoEcho(*command)

Execute one or more lines of command line dialogue input with no echo of commands to dialogue box

Parameters:

command (string) – Command to execute (as if it had been typed into the dialogue box) This argument can be repeated if required. Alternatively a single array argument containing the multiple values can be given

Returns:

0: No errors/warnings.
> 0: This number of errors occurred.
< 0: Absolute number is the number of warnings that occurred

Return type:

int

Example

To read two models:

Oasys.PRIMER.DialogueInputNoEcho("/re dk model_1.key 1", "/re dk model_2.key 2")

As with DialogueInput above each call starts at the top of the PRIMER command tree structure, so any commands destined for sub-menus must all be arguments to a single call

ErrorMessage(string)

Print an error message to the dialogue box adding a carriage return

Parameters:

string (Any valid javascript type) – The string/item that you want to print

Returns:

No return value

Return type:

None

Example

To print the title of model object m as an error to the dialogue box

Oasys.PRIMER.ErrorMessage("The title is " + m.title)
Execute(data)

Execute a program or script outside PRIMER and get the standard output and error streams

Parameters:

data (dict) –

Execute data

arguments (optional):

(Array of strings) The arguments to pass to program

program:

(string) The program you want to run. Note that on Linux this will consider PATH when resolving executable filenames without an absolute path. If you want to run something from the current directory and you do not have ‘.’ in your PATH then you will need to write ‘./something’ as the program

Returns:

Dict with properties

status:

(integer) The exit code from the program/script

stderr:

(string) The standard error output from the program/script

stdout:

(string) The standard output from the program/script

Return type:

dict

Example

To run script “example.bat” with arguments “foo” and “bar”:

output = Oasys.PRIMER.Execute( { "program": 'example.bat', "arguments": [ 'foo', 'bar' ]} )
text   = output["stdout"]
errors = output["stderr"]
ecode  = output["status"]
Exit(write_hook_interrupt=Oasys.gRPC.defaultArg)

Exit script

Parameters:

write_hook_interrupt (boolean) – Optional. If Exit() is called from a write_hook.js script, the first argument will be processed as in the following: If the argument is provided and set to “true”, it is used to interrupt the write out of the model, so that the script exits without anything being written out. An argument value of “false” exits the script and allows the model to be written out as normal. An example of this function’s use in a Write Hook script can be found at $OA_INSTALL/primer_library/scripts/hooks/example_write_hook.js

Returns:

No return value

Return type:

None

Example

Exit with

Oasys.PRIMER.Exit()
FlagsAvailable()

Number of flags available to be used for AllocateFlag()

Returns:

Number of flags available

Return type:

int

Example

To get the number of flags available:

flags = Oasys.PRIMER.FlagsAvailable()
GetCurrentDirectory()

Get the current working directory

Returns:

String containing current working directory

Return type:

str

Example

To get the current directory:

cwd = Oasys.PRIMER.GetCurrentDirectory()
GetInstallDirectory()

Get the directory in which executables are installed. This is the OA_INSTALL environment variable, or if that is not set the directory in which the current executable is installed. Returns None if not found

Returns:

string

Return type:

str

Example

To get the install directory:

install_dir = Oasys.PRIMER.GetInstallDirectory()
GetPreferenceValue(program, name)

Get the Preference value with the given string in the any of admin (“OA_ADMIN”) or install (“OA_INSTALL”) or home (“OA_HOME”) directory oa_pref

Parameters:

  • program (string) – The program name string : Valid values are ‘All’, ‘D3PLOT’, ‘PRIMER’, ‘REPORTER’, ‘SHELL’,
    ‘T/HIS’

  • name (string) – The preference name string

Returns:

: String containing preference value or None if preference string is not present in any oa_pref. Also if none of the above environment variables are not present, then API simply returns null. While returning preference value, locked preference value in admin and then install oa_pref takes precedence over home oa_pref. If preference is not locked in any of these oa_pref, preference in home directory oa_pref is returned

Return type:

str

Example

To get the preference value:

pref_list = Oasys.PRIMER.GetPreferenceValue('All', "font_size")
GetStartInDirectory()

Get the directory passed to PRIMER by the -start_in command line argument

Returns:

String containing start_in directory or None if not set

Return type:

str

Example

To get the start_in directory:

start_in = Oasys.PRIMER.GetStartInDirectory()
Getenv(name)

Get the value of an environment variable

Parameters:

name (string) – The environment variable name

Returns:

String containing variable value or None if variable does not exist

Return type:

str

Example

To get the value for environment variable HOME

home = Oasys.PRIMER.Getenv("HOME")
Labels(type, state=Oasys.gRPC.defaultArg)

Set or get labelling of items in PRIMER

Parameters:

  • type (string) – The type of the item (for a list of types see Appendix I of the PRIMER manual). Additionally, to change the visibility of attached or unattached nodes you can use the types “ATTACHED_NODE” and “UNATTACHED_NODE”

  • state (boolean) – Optional. If it is provided it is used to set the labelling status of entity. “true” to make items labelled and “false” to make them not labelled

Returns:

Boolean

Return type:

bool

Example

To turn on beam labels

Oasys.PRIMER.Labels("BEAM", True)

To get the labelling status of beams

lab = Oasys.PRIMER.Labels("BEAM")
MacroFunction(name)

Set the function for macro callback. This function can be used to make PRIMER return the macro command that would be recorded if macro recording was active for every button press etc. This may be useful for you to know if a particular action has been done by the user.
The function will be called with 1 argument which is a string containing the macro command. To remove the macro function use MacroFunction(None)

Parameters:

name (function) – The name of the function (or None to remove a function)

Returns:

No return value

Return type:

None

Example

To set function MyMacroFunction as the macro function:

Oasys.PRIMER.MacroFunction(MyMacroFunction)
Message(string)

Print a message to the dialogue box adding a carriage return

Parameters:

string (Any valid javascript type) – The string/item that you want to print. If ‘r’ is added to the end of the string then instead of automatically adding a carriage return in the dialogue box, the next message will overwrite the current one. This may be useful for giving feedback to the dialogue box when doing an operation

Returns:

No return value

Return type:

None

Example

To print the title of model object m as a message to the dialogue box

Oasys.PRIMER.Message("The title is " + m.title)
MilliSleep(time)

Pause execution of the script for time milliseconds. See also Sleep()

Parameters:

time (integer) – Number of milliseconds to pause for

Returns:

No return value

Return type:

None

Example

To pause for 500 milliseconds

Oasys.PRIMER.MilliSleep(500)
NumberToString(number, width, pref_int=Oasys.gRPC.defaultArg)

Formats a number to a string with the specified width

Parameters:

  • number (integer/float) – The number you want to format

  • width (integer) – The width of the string you want to format it to (must be less than 80)

  • pref_int (boolean) – Optional. By default only integer values inside the single precision 32 bit signed integer limit of approximately +/-2e9 are formatted as integers, all other numeric values are formatted as floats. With this argument set to TRUE then integer values up to the mantissa precision of a 64 bit float, approximately +/-9e15, will also be formatted as integers

Returns:

String containing the number

Return type:

str

Example

To write the number 1.2345e+6 to a string 10 characters wide

str = Oasys.PRIMER.NumberToString(1.2345e+6, 10)
OpenManual(program, page)

Open the Oasys manuals at a requested page

Parameters:

  • program (string) – The program manual to open. Can be “primer”, “d3plot” or “this”

  • page (string) – The page to open in the manual, e.g. “running-this.html”

Returns:

True if successful, False if not

Return type:

bool

Example

To open the T/HIS manual on the running-this.html page

Oasys.PRIMER.OpenManual("this", "running-this.html")
PlayMacro(filename, options=Oasys.gRPC.defaultArg)

Play a macro in PRIMER

Parameters:

  • filename (string) – The name of the macro file to play

  • options (dict) –

    Optional. Options specifying how the macro file should be replayed. If omitted the default values below will be used

    delay:

    (integer) Delay in ms between commands when replaying. If omitted the current value from macro window will be used

    pick:

    (boolean) If picks/drags from the macro file should be replayed. If omitted the current value from macro window will be used

    terminate:

    (boolean) If the script should be terminated if an error occurs when playing the macro. If omitted the script will be terminated

    utf8:

    (boolean) If the script is UTF-8 encoded. If omitted or false the script is assumed to be ASCII text

    variables:

    (object) Object containing names and values for variables in the macro. If None or omitted no variables are used

    view:

    (boolean) If views encoded in the macro file for picks/drags should be replayed. If omitted the current value from macro window will be used

Returns:

True if an error occured during playback, False otherwise

Return type:

bool

Example

To play a UTF-8 encoded macro file /data/test/example.prm using the default options for picking/dragging and a delay of 500ms:

Oasys.PRIMER.PlayMacro("/data/test/example.prm", { "delay":500, "utf8":True} )

To play macro file /data/test/example.prm, defining values for variables A, B and C in the macro:

Oasys.PRIMER.PlayMacro("/data/test/example.prm", { "variables": { "A":10.0, "B":0, "C":"Example"} } )
Print(string)

Print a string to stdout. Note that a carriage return is not added

Parameters:

string (Any valid javascript type) – The string/item that you want to print

Returns:

No return value

Return type:

None

Example

To print string “Hello, world!”

Oasys.PRIMER.Print("Hello, world!")

To print the title of model object m with a carriage return

Oasys.PRIMER.print("The title is " + m.title + "\n")
Println(string)

Print a string to stdout adding a carriage return

Parameters:

string (Any valid javascript type) – The string/item that you want to print

Returns:

No return value

Return type:

None

Example

To print string “Hello, world!” automatically adding a carriage return

Oasys.PRIMER.Println("Hello, world!")

To print the title of model object m, automatically adding a carriage return

Oasys.PRIMER.Println("The title is " + m.title)
Requires(build)

Checks to see if the build number of PRIMER is high enough to run this script. If your script requires features that are only present in builds of PRIMER greater than a certain value Require can test this and only run the script if the build is high enough

Parameters:

build (integer) – The minimum build number that is required

Returns:

No return value (if the build is not high enough the script will terminate)

Return type:

None

Example

To only allow a script to run if the build is >= 2000

Oasys.PRIMER.Requires(2000)
ReturnFlag(flag)

Return a flag used in the script. See also AllocateFlag() and Model.PropagateFlag()

Parameters:

flag (Flag) – The flag to return

Returns:

No return value

Return type:

None

Example

To return flag f:

Oasys.PRIMER.ReturnFlag(f)
RunScript(filename, separate=Oasys.gRPC.defaultArg)

Run a script

Parameters:

  • filename (string) – The name of the script file to run. If the filename is relative then the file will be searched for relative to this script. If not found then the script_directory preference will be used

  • separate (boolean) – Optional. If the script will use separate memory from the current script. If it uses separate memory (true) then the ‘child’ script is completely separated from this script and knows nothing about variables in this script. If it does not use separate memory (false) then the ‘child’ script will have access to all of the variables in the current script and hence variables must not clash. It is strongly recommended that you use namespaces to stop variable names from clashing. If omitted the script will use separate memory

Returns:

No return value

Return type:

None

Example

To run script /data/test/child.js using separate memory for the child script

Oasys.PRIMER.RunScript("/data/test/child.js")
SetCurrentDirectory(directory_path)

Sets the current working directory

Parameters:

directory_path (string) – Path to the directory you would like to change into

Returns:

True if successful, False if not

Return type:

bool

Example

To change into the directory “/data/test” exists

Oasys.PRIMER.SetCurrentDirectory("/data/test")
SetPreferenceValue(program, name, value, refresh=Oasys.gRPC.defaultArg)

Save the preference string and its value into oa_pref of home directory. If the preference is locked in admin (“OA_ADMIN”) or install (“OA_INSTALL”) oa_pref, then API is unsuccessful. Home directory is defined by environment variable OA_HOME. If OA_HOME is not defined then API is unsuccessful

Parameters:

  • program (string) – The program name string : Valid values are ‘All’, ‘D3PLOT’, ‘PRIMER’, ‘REPORTER’, ‘SHELL’,
    ‘T/HIS’

  • name (string) – The preference name string

  • value (string) – The preference value string. If “value” is of zero length, then the option is simply removed from the file if present, and no new entry is made.This argument cannot be None

  • refresh (boolean) – Optional. If the saved preference should be refreshed. If omitted, the preference will NOT be refreshed. This argument is currently only available in PRIMER JS API and ignored in D3PLOT and T/HIS

Returns:

An integer. Returns 0 if the preference is saved succesfully or 1 if unsuccessful

Return type:

int

Example

To save the preference value:

ierr = Oasys.PRIMER.SetPreferenceValue( 'All', "font_size", 'Default')
Sleep(time)

Pause execution of the script for time seconds. See also MilliSleep()

Parameters:

time (integer) – Number of seconds to pause for

Returns:

No return value

Return type:

None

Example

To pause for 2 seconds

Oasys.PRIMER.Sleep(2)
System(string)

Do a system command outside PRIMER. To run an external command and get the output then please use Execute() instead

Parameters:

string (Any valid javascript type) – The system command that you want to do

Returns:

integer (probably zero if command successful but is implementation-dependant)

Return type:

int

Example

To make the directory “example”

Oasys.PRIMER.System("mkdir example")
Unix()

Test whether script is running on a Unix/Linux operating system. See also Windows()

Returns:

True if Unix/Linux, False if not

Return type:

bool

Example

To test if the OS is Unix

if ( Oasys.PRIMER.Unix() )
Use(filename)

Use script from a separate file

Parameters:

filename (string) – Use allows you to include a script from a separate file. This may be useful if your script is very large and you want to split it up to help with maintenance. Alternatively you may have a ‘library’ of common functions which you always want to include in your scripts. Including the ‘library’ with Use means that any changes only have to be done in one place. PRIMER will look for the file in the same directory as the main script. If that fails then it will look in $OA_INSTALL/primer_library/scripts directory and the script directory specified by the primer*script_directory preference.
Note that the file is included when the script is compiled, NOT at runtime

Returns:

No return value

Return type:

None

Example

To include script from file library.js

Oasys.PRIMER.Use("library.js")
UuidCreate()

Create a UUID (Universally unique ID)

Returns:

string

Return type:

str

Example

To create a UUID:

uuid = Oasys.PRIMER.UuidCreate()
Visibility(type, state=Oasys.gRPC.defaultArg)

Set or get visibility of items in PRIMER

Parameters:

  • type (string) – The type of the item (for a list of types see Appendix I of the PRIMER manual). Additionally, to change the visibility of attached or unattached nodes you can use the types “ATTACHED_NODE” and “UNATTACHED_NODE”

  • state (boolean) – Optional. If it is provided it is used to set the visibility. “true” to make items visible and “false” to make them not visible

Returns:

Boolean

Return type:

bool

Example

To make beams visible

Oasys.PRIMER.Visibility("BEAM", True)

To get the visibility status of beams

vis = Oasys.PRIMER.Visibility("BEAM")
WarningMessage(string)

Print a warning message to the dialogue box adding a carriage return

Parameters:

string (Any valid javascript type) – The string/item that you want to print

Returns:

No return value

Return type:

None

Example

To print the title of model object m as a warning to the dialogue box

Oasys.PRIMER.WarningMessage("The title is " + m.title)
Windows()

Test whether script is running on a Windows operating system. See also Unix()

Returns:

True if Windows, False if not

Return type:

bool

Example

To test if the OS is Windows

if ( Oasys.PRIMER.Windows() )