|
|
|
|
|
The extend instruction executes customer defined C language functions on behalf of TAS scripts.
Writing a script that uses this instructions also requires knowledge of C language programming and some basic knowledge of the IRAPI.
Synopsis
#include "irapi.h"
extend(type.src)
Description
The extend instruction differs from all other TSM instructions in that customer written C language functions are executed. Moreover, there are many contexts from which the customer C language functions may be executed.
The TSM process executes (optional) TAS instruction specific code in each of the following contexts:
During TSM process initialization the TSM program calls:
irExtendInit(0)
The irExtendInit (3IRAPI) function executes all functions in the IRAPI dynamic switch table Iri_ExtendInit_table using a call to irVADynSwitchAll (3IRAPI).
The return codes from the functions in this dynamic switchtable are always ignored and do not affect the behavior of IRAPI or TSM.
When TSM first starts executing a script the TSM program calls:
irExtendStart(0, cid, script)
where
The irExtendStart (3IRAPI) function executes all functions in the IRAPI dynamic switch table Iri_ExtendStart_table using a call to irVADynSwitchAll (3IRAPI).
The return codes from the functions in this dynamic switch table are always ignored and do not affect the behavior of IRAPI or TSM.
When TSM encounters the extend instruction in a TAS script the TSM program calls:
irExtendExecute(id, cid, script, reg)
where
The irExtendExecute (3IRAPI) function returns the value returned by the customer defined C-language function. If irExtendExecute returns IRR_OK, then extend sets Register 0 to 0. If irExtendExecute does not return IRR_OK, then extend sets Register 0 to -1.
The irExtendExecute (3IRAPI) function executes the function in the IRAPI dynamic switch table Iri_ExtendExecute_table that corresponds to id using a call to irVADynSwitch (3IRAPI).
The customer defined C-language function may get and set any of the IRD_NUMREG registers passed to it. The TSM program sets Register 0 to either 0 or -1, according to the return code of the C language function executed, therefore that register should not be written to.
The new IRAPI parameter IRP_EXTEND_BUF is a character buffer of 2048 bytes. The TAS script instructions setIRAPIparamstr and getIRAPIparamstr may be used to get or set this IRAPI parameter. The customer defined C-language functions executing in the context of the extend instruction may use the IRAPI functions irSetParamStr and irGetParamStr to get or set this IRAPI parameter.
When TSM terminates a script program the TSM program calls:
irExtendExit(0, cid, script)
where
The irExtendExit (3IRAPI) function executes all functions in the IRAPI dynamic switch table Iri_ExtendExit_table using a call to irVADynSwitchAll (3IRAPI).
The return codes from the functions in this dynamic switch table are always ignored and do not affect the behavior of IRAPI or TSM.
When TSM process quits the TSM program calls:
irExtendQuit(0)
The irExtendQuit (3IRAPI) function executes all functions in the IRAPI dynamic switch table Iri_ExtendQuit_table using a call to irVADynSwitchAll (3IRAPI). The return codes from the functions in this dynamic switch table are always ignored and do not affect the behavior of IRAPI or TSM.
When TSM process receives a SIGUSR1 the TSM program calls:
irExtendTrace(0)
The irExtendTrace (3IRAPI) function executes all functions in the IRAPI dynamic switch table Iri_ExtendTrace_table using a call to irVADynSwitchAll (3IRAPI). The return codes from the functions in this dynamic switch table are always ignored and do not affect the behavior of IRAPI or TSM.
There are some limitations on what can be done within the functions called by the extend instruction. TSM is a multi-channel application. Because of this C-language functions written for the extend instruction must be able to execute in the context of many channels.
Memory allocation, initialization, and access to data structures may need to be done on a per channel basis. After TSM completes execution of an instruction TSM is free to execute another instruction for that script, or it may suspend execution of the script and execute an instruction in another script. Therefore no assumptions should be made that two extend instructions immediately following each other will indeed be executed immediately one after the other.
There are two other constraints on the C-language functions executed by the extend instruction. These functions must not generate IRAPI events. TSM does not know what to do with these events, and they are discarded. These functions must not consume so much time that they cause TSM to fall behind in processing its event queue. Any time consuming operations, such as database operations or network communication, must not be done with this mechanism. Use a DIP for any time consuming processes. Do not use the extend instruction.
The primary purpose of the extend instruction is to allow TSM to execute fast C-language functions that would otherwise be difficult or impossible to write in the TAS script language.
Avaya cannot guarantee that add-on packages implementing extend instructions written by other than Avaya will work correctly, or without damage to your system.
Examples
In the following section several sample scripts calling extend instructions are presented in detail. All these examples are on-line in the directory /vs/examples/IRAPI.
Example 1
/*
* FUNCTION:
* get_rand - get the value returned by rand()
* and store it in the passed in integer buffer
*
* INPUT: integer buffer to store random number
*
* RETURNS: return code from extend(TSM)
*/
#include "irapi.h"
DEFARG_COUNT(1)
DEFARG(rand,num,both) /*passed in via r.3 */
L__get_rand:
extend(IRX_RAND) /*set r.1 to rand() */
load(*int.3, r.1) /*set script parameter to r.1 */
rts() /*return to script */
Example 2
/*
* FUNCTION:
* get_lbolt - get the irLBolt(3IRAPI) value and store it
* in the passed in integer buffer
*
* INPUT: integer buffer to store irLBolt() return value
*
* RETURNS: return code from extend(TSM)
*/
#include "irapi.h"
DEFARG_COUNT(1)
DEFARG(lbolt,num,both) /*passed in via r.3 */
L__get_lbolt:
extend(IRX_LBOLT) /*set r.1 to irLBolt() */
load(*int.3, r.1) /*set script parameter to r.1 */
rts() /*return to script */
Example 3
/*
* FUNCTION: get_time - get current time()
*
* OUTPUT:
* time: time in seconds since midnight 1/1/70 UTC
*/
#include "irapi.h"
DEFARG_COUNT(1)
DEFARG(time,num,both) /* passed in via r.3 */
L__get_time:
extend ( IRX_TIME )
load ( *int.3, r.1 )
rts()
Example 4
/*
* FUNCTION: get_ctime - get the ctime() equivalent of
* the time, e.g., "Thu Sep 25 12:25:48 1997"
*
* INPUT:
* destination: field that result is placed in
* time: time in seconds since midnight 1/1/70 UTC
*/
#include "irapi.h"
DEFARG_COUNT(2)
DEFARG(destination,char,out) /* passed in via r.3 */
DEFARG(time,num,in) /* passed in via r.2 */
L__get_ctime:
load (r.1, r.2)
extend (IRX_CTIME)
/* get string up to but not including the \n */
getIRAPIparamstr( IRP_EXTEND_BUF, *ch.3, 24 )
incr (r.3, 24)
load (r.3, 0) /* null terminate the string */
rts()
Install sample scripts
Use the following procedure to install the example scripts above:
