global class

The global class is the main JavaScript class. More...

The T/HIS JavaScript API provides many class constants, properties and methods. For Arup to be able to extend and enhance the API in the future any constant, property or method names beginning with a lowercase or uppercase letter are reserved.
If you need to add your own properties or methods to one of the existing classes then to avoid any potential future conflict you should ensure that the name begins with either an underscore (_) or a dollar sign ($) or the name is prefixed with your own unique identifier.
For example if company 'ABC' need to add a property called 'example' then to avoid any potential future conflict use one of:

Class functions

Detailed Description

The global class declares the global object in JavaScript that contains the global properties and methods. As well as the core JavaScript methods, T/HIS also defines other additional ones. e.g. Message(), Print() etc. See the documentation below for more details.

Details of functions

AllocateFlag() [static]

Description

Allocate a flag for use in the script. See also ReturnFlag() and Once allocated the flag is automatically cleared for all entity types and all the curves currently in T/HIS.

Arguments

No arguments

Returns

Flag (integer)

Return type

Number

Example

To allocate a flag 

var flag = AllocateFlag();

ClearFlag(flag[Flag]) [static]

Description

Clears a flag on all curves and entity types.

Arguments

  • flag (Flag)

    The flag to return.

    Returns

    No return value.

    Example

    To clear flag f: 

    ClearFlag(f);

    DialogueInput(command[string]) [static]

    Description

    Execute one or more lines of command line dialogue input.

    Arguments

  • 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

    No return value

    Example

    To mulitply curves 1 and 2 by 10: 

    DialogueInput("/op mul #1 10 #", "/op mul #2 10 #");

    Note that each call to DialogueInput starts afresh at the top of the T/HIS command line "tree", so where multiple commands need to be given at sub-menu levels they need to be included in a single call.

    DialogueInputNoEcho(command[string]) [static]

    Description

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

    Arguments

  • 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

    No return value

    Example

    To mulitply curves 1 and 2 by 10: 

    DialogueInputNoEcho("/op mul #1 10 #", "/op mul #2 10 #");

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

    DisableGraphWindowUpdates() [static]

    Description

    Disable Graph Window updates.

    Arguments

    No arguments

    Returns

    No return value

    Example

    Turn off graph window updates 

    DisableGraphWindowUpdates();

    DisableMenuUpdates() [static]

    Description

    Disable menu system updates.

    Arguments

    No arguments

    Returns

    No return value

    Example

    Disable menu system updates 

    DisableMenuUpdates();

    EnableGraphWindowUpdates() [static]

    Description

    Enable Graph Window updates.

    Arguments

    No arguments

    Returns

    No return value

    Example

    Turn off graph window updates 

    EnableGraphWindowUpdates()

    EnableMenuUpdates() [static]

    Description

    Enable menu system updates.

    Arguments

    No arguments

    Returns

    No return value

    Example

    Enable menu system updates 

    EnableMenuUpdates();

    ErrorMessage(string[Any valid javascript type]) [static]

    Description

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

    Arguments

  • string (Any valid javascript type)

    The string/item that you want to print

    Returns

    No return value

    Example

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

    ErrorMessage("The title is " + m.title);

    Execute(data[object]) [static]

    Description

    Execute a program or script outside T/HIS and get the standard output and error streams.

    Arguments

  • data (object)

    Execute data

    Object has the following properties:

    Name Type Description
    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

    Object with the following properties:

    Name Type Description
    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

    object

    Example

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

    var output = Execute( { program: 'example.bat', arguments: [ 'foo', 'bar' ]} );
var text   = output.stdout;
var errors = output.stderr;
var ecode  = output.status;

    Exit(write hook interrupt (optional)[boolean]) [static]

    Description

    Exit script

    Arguments

  • write hook interrupt (optional) (boolean)

    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

    Example

    Exit with 

    Exit();

    GetCurrentDirectory() [static]

    Description

    Get the current working directory

    Arguments

    No arguments

    Returns

    String containing current working directory

    Return type

    String

    Example

    To get the current directory: 

    var cwd = GetCurrentDirectory();

    GetFtcfVar(name[string]) [static]

    Description

    Get the value of a FAST-TCF variable

    Arguments

  • name (string)

    The FAST-TCF variable name (case independent)

    Returns

    String containing variable value or null if variable does not exist

    Return type

    String

    Example

    To get the value for FAST-TCF variable Job 

    var job_name = GetFtcfVar("Job");

    GetInstallDirectory() [static]

    Description

    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 NULL if not found

    Arguments

    No arguments

    Returns

    string

    Return type

    String

    Example

    To get the install directory: 

    var install_dir = GetInstallDirectory();

    GetPreferenceValue(program[string], name[string]) [static]

    Description

    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

    Arguments

  • 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 null 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

    String

    Example

    To get the preference value: 

    var pref_list = GetPreferenceValue('All', "font_size");

    GetStartInDirectory() [static]

    Description

    Get the directory passed to T/HIS by the -start_in command line argument

    Arguments

    No arguments

    Returns

    String containing start_in directory or NULL if not set

    Return type

    String

    Example

    To get the start_in directory: 

    var start_in = GetStartInDirectory();

    Getenv(name[string]) [static]

    Description

    Get the value of an environment variable

    Arguments

  • name (string)

    The environment variable name

    Returns

    String containing variable value or null if variable does not exist

    Return type

    String

    Example

    To get the value for environment variable HOME 

    var home = Getenv("HOME");

    Message(string[Any valid javascript type]) [static]

    Description

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

    Arguments

  • 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

    Example

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

    Message("The title is " + m.title);

    MilliSleep(time[integer]) [static]

    Description

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

    Arguments

  • time (integer)

    Number of milliseconds to pause for

    Returns

    No return value

    Example

    To pause for 500 milliseconds 

    MilliSleep(500);

    NumberToString(number[integer/real], width[integer], pref_int (optional)[boolean]) [static]

    Description

    Formats a number to a string with the specified width.

    Arguments

  • number (integer/real)

    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 (optional) (boolean)

    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

    String

    Example

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

    var str = NumberToString(1.2345e+6, 10);

    OpenManual(program[string], page[string]) [static]

    Description

    Open the Oasys manuals at a requested page

    Arguments

  • 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

    Boolean

    Example

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

    OpenManual("this", "running-this.html");

    Plot() [static]

    Description

    Updates all the T/HIS graphs.

    Arguments

    No arguments

    Returns

    No return value

    Example

    Update all graphs 

    Plot();

    Print(string[Any valid javascript type]) [static]

    Description

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

    Arguments

  • string (Any valid javascript type)

    The string/item that you want to print

    Returns

    No return value

    Example

    To print string "Hello, world!" 

    Print("Hello, world!");

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

    print("The title is " + m.title + "\n");

    Println(string[Any valid javascript type]) [static]

    Description

    Print a string to stdout adding a carriage return.

    Arguments

  • string (Any valid javascript type)

    The string/item that you want to print

    Returns

    No return value

    Example

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

    Println("Hello, world!");

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

    Println("The title is " + m.title);

    ReturnFlag(flag[Flag]) [static]

    Description

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

    Arguments

  • flag (Flag)

    The flag to return.

    Returns

    No return value.

    Example

    To return flag f: 

    ReturnFlag(f);

    SetCurrentDirectory(directory path[string]) [static]

    Description

    Sets the current working directory.

    Arguments

  • directory path (string)

    Path to the directory you would like to change into.

    Returns

    true if successful, false if not

    Return type

    Boolean

    Example

    To change into the directory "/data/test" exists 

    SetCurrentDirectory("/data/test")

    SetFtcfVar(name[string]) [static]

    Description

    Set the value of a FAST-TCF variable. If the variable already exists then it's value is updated

    Arguments

  • name (string)

    The FAST-TCF variable name (case independent)

    Returns

    String containing variable value or null if variable does not exist

    Return type

    String

    Example

    To create a new FAST-TCF variable called run_number with the value "10" 

    var home = SetFtcfVar("run_number","10");

    Sleep(time[integer]) [static]

    Description

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

    Arguments

  • time (integer)

    Number of seconds to pause for

    Returns

    No return value

    Example

    To pause for 2 seconds 

    Sleep(2);

    System(string[Any valid javascript type]) [static]

    Description

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

    Arguments

  • 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

    Number

    Example

    To make the directory "example" 

    System("mkdir example");

    Unix() [static]

    Description

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

    Arguments

    No arguments

    Returns

    true if Unix/Linux, false if not

    Return type

    Boolean

    Example

    To test if the OS is Unix 

    if ( Unix() )

    UpdateCurveMenu() [static]

    Description

    Updates the scroll bar in the Curve Manager. Useful if your script has created lots of new curves and you want to update the menu (otherwise, the scroll bar range will only be updated when the script exits).

    Arguments

    No arguments

    Returns

    No return value

    Example

    Update curve slider 

    UpdateCurveMenu();

    WarningMessage(string[Any valid javascript type]) [static]

    Description

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

    Arguments

  • string (Any valid javascript type)

    The string/item that you want to print

    Returns

    No return value

    Example

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

    WarningMessage("The title is " + m.title);

    Windows() [static]

    Description

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

    Arguments

    No arguments

    Returns

    true if Windows, false if not

    Return type

    Boolean

    Example

    To test if the OS is Windows 

    if ( Windows() )