Oasys.D3PLOT functions

AllocateFlag()

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

Returns:

Flag to use

Return type:

Flag

Example

To allocate a flag

flag = Oasys.D3PLOT.AllocateFlag()
DialogueInput(*command)

Executes one or more command-line syntax commands. There is no limit to the number of lines that may be specified in a single call. See Dialogue Command Syntax for a full list of command-line commands The DialogueInputNoEcho variant is identical, except that it suppresses the echo of the commands to the dialogue box. D3PLOT provides a full command-line syntax as an alternative to graphical user interface commands, and a sequence of such commands may be provided here. Note that: Each call to DialogueInput starts at the top of the D3PLOT command-line “tree”, at the D3PLOT_MANAGER>>> prompt Each call is autonomous, there is no “memory” of where in the command-line tree previous commands finished. However within a single call the current command-line tree is remembered from one line to the next. Commands are not case-sensitive, although filenames and titles in command strings are. Therefore commands which require more than one line of input to complete must be specified in a single call; and it makes sense to group a sequence of related commands together in a single call, although this is not mandatory. If this succeeds it returns true, otherwise false.

Parameters:

command (string) – Command to be executed (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:

No return value

Return type:

None

Example

# Blanks all solids.
# Unblanks solids 1 to 10.
# Performs a hidden line plot.
# All commands are echoed to the dialogue box
Oasys.D3PLOT.DialogueInput("BLANK SOLID ALL", "UNBLANK SOLID 1 to 10", "HIDDEN")
DialogueInputNoEcho(*command)

Executes one or more command-line syntax commands. There is no limit to the number of lines that may be specified in a single call. See Dialogue Command Syntax for a full list of command-line commands This does not echo the commands to the dialogue box. See DialogueInput for more information.

Parameters:

command (string) – Command to be executed (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:

No return value

Return type:

None

Example

# Read state 10
# Performed a shaded ("greyscale" in command-line syntax)plot
# Create a JPEG format file "image.jpg"
# Command is not echoed to the dialogue box.
Oasys.D3PLOT.DialogueInputNoEcho("STATE10", "/GREY GO", "/IMAGE jpeg image.jpg")
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.D3PLOT.ErrorMessage("The title is " + m.title)
Execute(data)

Execute a program or script outside D3PLOT 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.D3PLOT.Exit()

Exits the T/HIS link from D3PLOT

Returns:

No return value

Return type:

None

GetCurrentDirectory()

Get the current working directory

Returns:

String containing current working directory

Return type:

str

Example

To get the current directory:

cwd = Oasys.D3PLOT.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.D3PLOT.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.D3PLOT.GetPreferenceValue('All', "font_size")
GetStartInDirectory()

Get the directory passed to D3PLOT 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.D3PLOT.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.D3PLOT.Getenv("HOME")
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.D3PLOT.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.D3PLOT.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.D3PLOT.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.D3PLOT.OpenManual("this", "running-this.html")
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.D3PLOT.Print("Hello, world!")

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

Oasys.D3PLOT.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.D3PLOT.Println("Hello, world!")

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

Oasys.D3PLOT.Println("The title is " + m.title)
ReturnFlag(flag)

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

Parameters:

flag (Flag) – The flag to return

Returns:

No return value

Return type:

None

Example

To return flag f:

Oasys.D3PLOT.ReturnFlag(f)
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.D3PLOT.SetCurrentDirectory("/data/test")
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.D3PLOT.Sleep(2)

Starts the T/HIS link from D3PLOT

Returns:

No return value

Return type:

None

System(string)

Do a system command outside D3PLOT. 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.D3PLOT.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.D3PLOT.Unix() )
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.D3PLOT.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.D3PLOT.Windows() )