|
|
|
|
|
The subprog instruction executes a TSM script or IRAPI application as a subprogram, and then returns to the parent script with data.
Synopsis
subprog(ctype.appname [, type.data, type.nbytes ])
Description
The subprog() instruction is similar to the exec instruction. It may be used to run another TSM script or IRAPI application. When an application is run with subprog(), however, the calling script (parent) is not replaced by the new application. Instead it is run as a subprogram and returns to the point where subprog() was called when the called application terminates. Data may also be passed in both directions using subprog().
Note:
Use of subprog() involves a process level context switch that may decrease system performance if used excessively. Do not use subprog() if you can use a script subroutine to do the same thing. See the label() instruction.
TSM scripts that are run with subprog() have direct access to parent script data using the special &ch., &int., and &short. data type specifiers. When one of these data types is used, they must be followed by a TSM register number containing an offset into the parent script data space which references the desired data. The name of the parent script may be obtained with the special &script.0 argument. The value of this argument is a null string if there is no parent script.
Note:
If the parent is an IRAPI application that calls a TSM script with irSubProg, this method cannot be used to obtain access to data in that application. Using the & data types always goes to the nearest ancestor TSM script (if any). For example, if TSM script A subprog()s IRAPI application B, and B in turn irSubProg()s TSM script application C, then A is the nearest ancestor TSM script to C. In this case, when using the & argument data types, C obtains data from A, not from B. If there is no ancestor TSM script, the instruction using these argument types fails. It is best to check the &script.0 value first to see if there is a parent script and get its name. Note that a running script can get its own name through the script.0 argument.
The ctype.appname argument is the the name of the application to be executed.
The optional type.data and type.nbytes arguments are used to pass a block of data to the new application. The type.data argument specifies the location of the data and type.nbytes specifies the size of the data in bytes. If type.data is a register or immediate, type.nbytes is ignored and the size of an integer (4 bytes) is assumed.
The data passed to the new application using the type.data argument is available to a TSM script using the special X.0 argument, just as if the exec instruction were used to pass the data. IRAPI applications have access to this data through the IRP_EXEC_BUF parameter. If the called application modifies X.0 (or IRP_EXEC_BUF), that modification is accessible by the calling application when subprog() returns.
All TSM register values are also passed to the new application. Script applications use these values in their own registers (r.REGNUM argument type). IRAPI applications may use these values through the IRP_REGISTER parameter.
Note:
The subprogram stack is limited by the system tunable parameter NCONTEXTSTACK, which is set to three by default. This limits the use of subprog() to three levels per application unless you tune NCONTEXTSTSACK to a higher value (limit of 10) by using the idtune command.
Return values
subprog() returns values in both register 0 (r.0) and register 1 (r.1). r.0 is 0 if subprog() is successful. It contains a negative value to indicate failure. If successful, subprog() also returns in r.1 whatever value is passed to the quit() instruction by a called TSM script application, or whatever value is passed to irReturn by a called IRAPI application.
Examples
The following example executes an application called APPL, passing it 100 bytes of data and checking return values:
subprog("APPL", ch.DATA, 100)
jmp(r.0 < 0, L_Failure)
quit(r.1) /* quit with return value from APPL */ L_Failure:
talk("failed to execute application")
quit(-1)
See also
