NAME
irExtendInit, irExtendStart, irExtendExit, irExtendExecute,
irExtendQuit, irExtendTrace - IRAPI extension functions
SYNOPSIS
#include <irapi.h>
int irExtendInit ( int id... );
int irExtendStart ( int id... );
int irExtendExecute ( int id... );
int irExtendExit ( int id... );
int irExtendQuit ( int id... );
int irExtendTrace ( int id... );
DESCRIPTION
The irExtend family of functions support execution
of functions added to the IRAPI dynamic switch tables docu-
mented in IrEXTEND(4SPI).
The function irExtendInit calls each function in the IRAPI
dynamic switch table Iri_ExtendInit_table with the argument
list id , args where args is a pointer to the irExtendInit
function stack after the id argument. Each function called
must return either IRR_OK or IRR_FAIL.
The function irExtendStart calls each function in the IRAPI
dynamic switch table Iri_ExtendStart_table with the argument
list id, args where args is a pointer to the irExtendStart
function stack after the id argument. Each function called
must return either IRR_OK or IRR_FAIL.
The function irExtendExecute calls one function in the IRAPI
dynamic switch table Iri_ExtendExecute_table with the argu-
ment list id, args where args is a pointer to the
irExtendExecute function stack after the id argument. The
function chosen for execution has a IRAPI dynamic switch
table val field equal to id. The function called must
return either IRR_OK or IRR_FAIL.
The function irExtendExit calls each function in the IRAPI
dynamic switch table Iri_ExtendExit_table with the argument
list id, args where args is a pointer to the irExtendExit
function stack after the id argument. Each function called
must return either IRR_OK or IRR_FAIL.
The function irExtendQuit calls each function in the IRAPI
dynamic switch table Iri_ExtendQuit_table with the argument
list id, args where args is a pointer to the irExtendQuit
function stack after the id argument. Each function called
must return either IRR_OK or IRR_FAIL.
The function irExtendTrace calls each function in the IRAPI
dynamic switch table Iri_ExtendTrace_table with the argument
list id, args where args is a pointer to the irExtendTrace
function stack after the id argument. Each function called
must return either IRR_OK or IRR_FAIL.
The stack arguments may be retrevied via the va_arg macro in
the include file <stdarg_iso.h>
This indirection is necessary because it is not possible in
the C language to pass a variable argument list from one
function to another function.
EVENTS
No events result from a call to the irExtend(3IRAPI) func-
tions. No events may result from a call to any subfunction.
PARAMETERS
The parameter IRP_EXTEND_BUF may be used to communicate
between TSM scripts and the C language functions called via
irExtend(3IRAPI).
RETURN VALUE
The functions irExtendInit, irExtendStart,
irExtendExit, irExtendQuit and irExtendTrace
return IRR_OK if all functions in
their respective IRAPI dynamic switch table return IRR_OK.
The function irExtendExecute returns IRR_OK if the
function in the IRAPI dynamic switch Iri_ExtendExecute_table
identifed by id returns IRR_OK, or IRR_FAIL otherwise.
TSM
The TSM process executes the function call:
irExtendInit( 0 )
when TSM is initializing prior to executing any script. The
customer written extension function must have the following
prototype and perform the following operations:
int your_extension_init_function(int id, va_list args)
{
/* whatever you need to do */
return( IRR_OK );
}
There is no need for the customer written extension initial-
ization function to examine the argument list since id is
always zero, and args contains nothing meaningful. Since
this function is called when TSM process initializes the
customer written extension function may do any initializa-
tion that is appropriate in this context, i.e., memory allo-
cation, initializing data structures, etc.
The TSM process executes the function call:
irExtendStart( 0, (channel_id)cid, (char *)script )
when TSM starts a script. This function is called prior to
executing the first instruction of the script. The customer
written extension function should have the following proto-
type, and perform the following operations:
int your_extension_start_function( int id, va_list args )
{
channel_id cid;
char *script;
int chan;
cid = va_arg(args, channel_id);
script = va_arg(args, char *);
chan = irCid2Chan(args, char *);
/* whatever you need to do */
return( IRR_OK );
}
The TSM process executes the function call:
irExtendExecute( id, (channel_id)cid, (char *)script, (long *)reg )
extend( id )
The customer written extension execute function should have
the following prototype and perform the following opera-
tions:
int your_extension_execute_function( int id, va_list args )
{
channel_id cid;
char *script;
long *reg;
cid = va_arg(args, channel_id);
script = va_arg(args, char *);
reg = va_arg(args, long *);
chan = irCid2Chan( cid );
/* whatever you need to do */
return( IRR_OK );
}
The IRAPI parameter IRP_EXTEND_BUF, and the registers
r.1,~...,~r.15 are the means by which TAS scripts and C
language extension functions exchange information.
The TAS script may get and set the IRAPI parameter
IRP_EXTEND_BUF with the instruction:
setIRAPIparamstr( IRP_EXTEND_BUF, buffer, length )
and
getIRAPIparamstr( IRP_EXTEND_BUF, buffer, length )
The C language extension execute function may get and set
this IRAPI parameter with:
irGetParamStr(cid, IRP_EXTEND_BUF, buffer, length );
and
irSetParamStrCnt(cid, IRP_EXTEND_BUF, buffer, length );
The TAS script may get and set script registers r.1, ...,
r.15 with the load instruction.
The C language extension execute function may get and set
the script registers by getting and setting
reg[7] = 43;
when the extension execute function returns the TAS script
register r.7 will contain a value of 43.
The TSM process executes the function call:
irExtendExit( 0, (channel_id)cid, (char *)script )
when TSM terminates a script. The customer written exten-
sion function should have the following prototype, and per-
form the following operations:
int your_extension_exit_function( int id, va_list args )
{
channel_id cid;
char *script;
int chan;
cid = va_arg(args, channel_id );
script = va_arg(args, char *);
chan = irCid2Chan( cid );
/* whatever you need to do */
return( IRR_OK );
}
The TSM process executes the function call:
irExtendQuit( 0 )
when TSM terminates. The customer written extension func-
tion should have the following prototype, and perform the
following operations:
int your_extension_quit_function( int id, va_list args )
{
/* whatever you need to do */
return( IRR_OK );
}
There is no need for this function to examine the argument
list since id is always 0, and args contains nothing mean-
ingful.
when TSM receives a SIGUSR1 signal. The customer written
extension function should have the following prototype, and
perform the following operations:
int your_extension_trace_function( int id, va_list args )
{
/* whatever you need to do */
return( IRR_OK );
}
There is no need for this function to examine the argument
list since id is always 0, and args contains nothing mean-
ingful.
The id argument to irExtendExecute is the extension function
identifier as passed to the TAS extend instruction. The id
argument to all other irExtend(3IRAPI) functions is always
0.
The cid argument in all the above function calls is the
channel_id for the channel.
The script argument in all the above function calls is the
script name running on the channel.
The reg argument to irExtendExecute is the array of
IRD_NUMREG TSM registers. All of the TSM registers may be
read and/or written, however register zero, reg[0], aka r.0,
will be set by TSM according to the return code of the C
function called.
There is no requirement for a customer written extension
library to provide a function to each of the
IrEXTEND(4IRAPI) tables. As can be seen by the example in
the file util_fcns.c there is one extension init function
for the entire library. Similarly, there is one start, one
exit, one quit, and one trace function for the entire
library. There are separate execute functions for each
utility function.
This design was chosen to minimize the number of functions
written. It could just as well have had a seperate init.
There is no need for a customer written extension function
to call va_start or va_end, that is done by the correspond-
ing irExtend(3IRAPI). function.
TSM is multi-threaded with one thread per channel. It is
possible for TSM to alternate thread execution between TAS
instructions. This impacts extend instruction execution in
that if it is necessary to save an intermediate result
between extend instructions the intermediate result should
be saved in a persistent data structure accessed by channel
number.
WARNING
The TSM extend instruction, and the functions it invokes via
the irExtend(3IRAPI) functions are intended only for fast C
functions and should not block or otherwise slow down TSM.
These functions may not generate IRAPI events. These func-
tions may not not call database functions. Any database
functions should continue to be done through a DIP. Only
computationally simple, and inexpensive, DIPs should be
replaced with extend functions.
EXAMPLE
See /vs/examples/IRAPI/util_fcns.c for a sample extension
library which implements simple utility functions.
ERROR
irError may be set by the functions called through the IRAPI
dynamic switch tables.
SEE ALSO
irSPIRegister, IrDEFINES(4IRAPI),
IrPARAMETERS(4IRAPI)
VERSION
This is version 11/11/02 of this man page.