CALL SCRIPT Command

Description:

This command calls a script from another script. When the command is executed, control is transferred to the called script; when the called script exits, control is returned to the calling script, optionally returning a status from the called script. There is no limit on the number of scripts that may be referenced by any one script.

In general, a called script is considered as an extension to the calling script, and any changes made in the called script are propagated back to the calling script on exit. However, certain changes (e.g. further ON ERROR handlers) only remain in force for the duration of the called script (or scripts called by it); the original condition is reestablished when control is returned to the calling script.

For scripts, a maximum of eight parameters may be passed from the calling script to the called script. An omitted parameter is specified by two consecutive commas ",,". The calling script must pass exactly the same number of parameters to the called script as the called script has defined in its ENTRY statement (accounting for any omitted parameters). In addition, the data types of each of the parameters must match. Failure to comply with these conditions will result in a script error being generated.

The values of the parameters are passed from the caller into the variables defined within the ENTRY statement of the called script. Any modifications to the values of the variables are copied back to the caller on return from the called script.

An optional status value can be returned from the called script by using the "RETURNING" clause to specify the integer variable which is to hold the return status value.

By default, if an error occurs in a called script, an error message is written to the audit log and the thread aborts; control is not returned to the calling script. However, if error trapping is enabled in the calling script and the error was a script error, then control will be returned to the calling script's error handling code.

The "ON ERROR GOTO err_label" clause can be specified to define a label to which control should be transferred in the event of an error while attempting to call the script.

Format:

 CALL SCRIPT name {&}
 	 {[parameter{, parameter ...}]} {&}
 	 {RETURNING status} {ON ERROR GOTO err_label}

Parameters:

name

A character variable or quoted character string defining the name of the script to be called. The name must be a valid OpenSTA Dataname.

parameter

A character variable, integer variable, quoted character string, integer value or file ID to be passed to the called script. A maximum of 8 parameters may be passed between scripts.

status

An integer variable to receive the returned status from the called script. If no status is returned from the called script, then this variable will contain the last status returned from any called script.

err_label

A label defined within the current scope of the script, to which control branches if an error occurs.

Examples:

 CALL SCRIPT Script-Name
 CALL SCRIPT "TEST"
 CALL SCRIPT "CALC_TAX" [COST, RATE, TAX]
 CALL SCRIPT "GET_RESPONS" returning Response &
 	 ON ERROR GOTO Problem

See also:

Flow Control Commands