Built-in functions

The terminal script language has a set of built-in functions that can be used to manipulate data as well as to control the navigation through a terminal session. Because these functions are already defined internally, they do not have to be declared before using them. Simply type the name of the function.

The following sections describe the built-in functions and their parameters and return values.

Upper

Upper converts a string to upper case.

Parms: String to be converted
Return: Returns a new string, converted to uppercase. Follows the rules of the language in use.

Example:

Str = "abc"; 
Str2 = upper(str); // str2 will contain "ABC"

Lower

Lower converts a string to lower case.

Parms: String to be converted
Return: Returns a new string, converted to lowercase. Follows the rules of the language in use.

Example:

Str = "ABC"; 
Str2 = lower(str); // str2 will contain "abc"

Index

Index returns the position (index relative to one) of a substring within a String.

Parms: Target string - string to be searched
Return: Returns the position of the search string or zero if not found

Example:

Str = "abcdef"; 
Val = index(str,"def"); // val will contain 4

Length

Length returns the length of the string.

Parms: String to be inspected
Return: Returns a numeric value of the length of the string (in characters), or 0 if null string

Example:

Str = "abc"; 
Val = length(str); // val will be 3

Substring

Substring returns the portion of the string as specified by the offset and length. It can be abbreviated as Substr.

Parms: Target string - string to be searched
Starting offset - offset within the string to start the selection Length - length of the data wanted
Return: Returns the string that represents the selection

Note: The length parameter is optional, and if not specified will assume the length up to the end of the target string. If the length exceeds the length of the target string, an error is raised.

Example:

Str = "abcdef"; 
Str2 = substring(str,3,3); // str2 will contain "def"  
Str3 = substr(str,1); // str3 will contain "bcdef"

Min

Min compares two numbers and returns the value equal to the lesser of the two numbers.

Parms: Number 1 - the first value to compare
Number 2 - the second value to compare
Return: Returns either Number 1 or Number 2 depending upon which is less

Example: Val1 = 10; Val2 = 20; Val3 = min(val1,val2); // val3 will contain 10;

Max

Max compares two numbers and returns the value equal to the greater of the two numbers.

Parms: Number 1 - the first value to compare
Number 2 - the second value to compare
Return: Returns either Number 1 or Number 2 depending upon which is greater

Example:

Val1 = 10; 
Val2 = 20; 
Val3 = max(val1,val2); // val3 will contain 20;

Prompt

Prompt allows the script to gather data from a user interactively by asking a user to enter data. This presents a window with message text and an edit field. It prompts you to enter data. You can either enter data and click OK or click Cancel to ignore the prompt.

Parms: MsgText - text of the message to be displayed in the window
PSWD - optional second parm. The keyword PSWD indicates that this is a password type field. The data entered by you does not display, but is represented by a series of asterisks(*) for each character typed.
Return: Returns the string value of the data entered. If you click Cancel, a null value will be returned. This is different from a null string.

Example:

Userid = prompt("Enter your userid") 
Pswd = prompt("Enter password","PSWD");

If you enter a value, it is placed in the variable userid. If you do not enter any data, and click OK, a null (zero length) string is returned.

If you click Cancel, a null pointer value is returned.

MsgBox

MsgBox displays a text message on the screen. A message severity type can be associated with the message. This causes the system-defined messageType icons to be displayed. You can control the type of buttons to appear with the OptionType parameter.

Parms

arg 1 = message string

arg 2 = msg type - a numeric value indicating the type of ICON to display

        0 = ERROR_MESSAGE;
        1 = INFORMATION_MESSAGE;
        2 = WARNING_MESSAGE;
        3 = QUESTION_MESSAGE;
       -1 = PLAIN_MESSAGE (Default)

arg 3 = optionType - a numeric value indicating the types of buttons

        0 = YES_NO buttons;
        1 = YES_NO_CANCEL buttons;
        2 = OK_CANCEL buttons;
       -1 = DEFAULT ok /cancel button(default);

@return = a numeric value representing the button that was pressed to dismiss the window

        0 = YES button or OK button;
        1 = NO button;
        2 = CANCEL button;
       -1 = CLOSED. The dialog was dismissed by closing
            the dialog window - no button was pressed.
       -2 = The message box was not responded to and the
            timeout value was exceeded

Example:

msgBox("The system is running"); // this will display a plain message, 
with OK cancel button 
Val = msgBox("Invalid signon. Retry?",0,1); // this will present an 
Error type message, with the YES,NO,CANCEL buttons;

Note: Because the msgBox is waiting for a user response, it could take a long time before the user responds. If it is running unattended, the user will never respond, and the script will stall. For this reason, there is a timeout value associated with this function. If the user does not respond within 10 minutes, the dialog is automatically dismissed and a value of -2 returned.

Sleep

Sleep suspends the execution for the time interval specified

Parms: Time interval1 - the number of milliseconds to wait
Return: Returns zero if successful; minus one if an error

Example:

Sleep(1000); // sleep for 1 second; 
Sleep(1000*60); // sleep for 1 minute

Note: The maximum amount of time permitted is 15 minutes (1000 * 60 * 15). If it is necessary to wait longer, multiple sleep() functions can be issued.

Note: The sleep is an Active wait. The actual internal value is a 1 second wait. The implementation uses a loop counter to issue the 1 second sleep. This prevents a stall condition and allows the script to be stopped.