|
|
|
|
|
The exec instruction allows a script to start another script.
Synopsis
exec(ctype.src [,type.data,type.nbytes][,exitval])
Description
The exec instruction allows a script to execute another script.
The ctype.src argument is the name of the script to be executed. The type.data and type.nbytes arguments are used to pass a block of data to the new script. The type.data argument specifies the location of the data, and type.nbytes specifies the size in bytes of that data. If type.data is a register or immediate type, type.nbytes is ignored and the size of an integer (4 bytes) is assumed. These two optional arguments work like the last two arguments of the dbase instruction. The exitval argument is an optional exit value that is used when the parent script is terminated before the new child script is run. It is used in the same way as the argument to the quit script instruction and may be specified without specifying the type.data and type.nbytes arguments. If no exitval is given, -1 is used by default.
The exec instruction only returns if the script name specified is invalid or the size of the data being passed exceeds the 2-Kbyte default limit. In these cases, register 0 is set to -1. Otherwise, the script exits and the actions in the following table are performed:
Action |
Comments |
If the exitval used is 0 or negative or if no exitval is given, a CALLDATA message is sent to CDH (as is done when the quit instruction is called) |
If the exitval is greater than 0, the CALLDATA record is not written to CDH. In this case, the start time of the call is preserved for the next script, which may send the record out when it executes another exec or a quit. CALLDATA events cannot be preserved across an exec since each script may define those events differently. |
SCRIPTTERM messages are sent to all DIPs for which the dipterm instruction is executed by the script |
An array of four long integers is passed as data with the SCRIPTTERM message. The first of these is set to NORMALTERM in the case of quit but is set to EXECTERM in the case of exec. The second integer in the array is set to whatever value is given to the quit instruction or in the exitval argument to the exec instruction. In each case, it is set to -1 if this value is not provided. |
Normally, TSM sets all script registers to zero (0) when a new script starts. When a script is run with exec, however, the register values set by the old script are preserved for the new script. If any speech has been queued with the talk, tnum, tchar, or say instruction, the exec causes this speech to be played before the new script is executed.
The system monitor shows the transition when a new script is executed by displaying the new script name under the Voice Service heading for the channel. The number under the Calls Today heading is not incremented when a new script is started with exec unless the new script executes a tic('a') instruction.
As was mentioned previously, the optional second and third arguments to exec may be used to pass a block of data to the new script. This data is not stored in the user data space of the script because that space is usually freed and the new script data space takes its place. This means that the new script cannot get the passed data directly as a script variable. Instead a new access code argument, X.0, was introduced to reference this data and some existing instructions have been modified to support this code. The X.0 code may be used as the second argument to the strcpy instruction to copy the exec data into the script data space. When this argument is used, strcpy performs a block copy of the exec data to the place specified by the first argument to strcpy. Enough space should be set aside by the script to accommodate the data. strcpy uses the size that is passed by the exec instruction in copying the data. It does not look for a null character at the end of the data, as is done normally.
The strcmp and strlen instructions also accept X.0 for their arguments. In this case, strcmp does a byte-by-byte comparison using the size of the exec data as a limit (instead of looking for a null-character termination) and returns in register 0 a value with the same meaning as strcmp has had previously (that is, a value less than, equal to, or greater than zero depending on whether the data indicated by the first argument is lexicographically less than, equal to, or greater than that indicated by the second argument). strlen simply returns in register 0 the size of the exec data as it is passed to the exec instruction.
The exec data also may be passed directly to a DIP by using the X.0 code as the fifth argument to the dbase instruction. The sixth argument indicating the size is ignored in this case since TSM uses the size originally passed to exec. The exec instruction similarly supports the X.0 code for its type.data argument. The type.nbytes argument also is ignored in this case.
These instructions are the only ones that have been modified to support the X.0 argument code. The TAS script compiler has been changed to do some checking of the arguments to the dbase and strcpy instructions to ensure that X.0 is not allowed for the first argument of strcpy and the third argument to dbase. There has been no effort made to do such checking for any other instruction. Use of X.0 elsewhere may have unpredictable results.
Example
The following example quits the script with an exit value of 1 and starts executing the test.script script.
exec("test.script",1)
See also
