CALL SCRIPT Command

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 re-established when control is returned to the calling Script.

For Scripts, a maximum of 8 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 should be copied back to the caller on return from the called Script - except this feature is broken (see bug# 573365).

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. The called Script passes a value back using the EXIT command. This feature is also broken, check bug# 573365 for any updates.

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.

Command Definition:

CALL SCRIPT name {[parameter{, parameter ...}]}
	 {RETURNING status} {ON ERROR GOTO err-label}

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 or 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. This feature is broken, check bug# 573365 for any updates.

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_RESP" RETURNING Response &
	 ON ERROR GOTO ERR_LABEL

Related:

• Broken & Useless SCL Features