NAME
irSubProgp, irSubProgl, irSubProgv, irSubProgle, irSub-
Progve, irSubProglp, irSubProgvp, irSubProgService -
transfer ownership of a channel to another Intuity Response
application
SYNOPSIS
#include <irapi.h>
int irSubProgp (channel_id cid, int tag, const char
*service, const char *name, const void *pdata, int psize);
int irSubProgl (channel_id cid, int tag, const char
*service, const void *pdata, int psize, const char *path,
const char *arg0, ..., const char *argn, (char *)0);
int irSubProgv (channel_id cid, int tag, const char
*service, const void *pdata, int psize, const char *path,
const char *argv);
int irSubProgle (channel_id cid, int tag, const char
*service, const void *pdata, int psize, const char *path,
const char *arg0, ..., const char *argn, (char *)0, const
char *envp[]);
int irSubProgve (channel_id cid, int tag, const char
*service, const void *pdata, int psize, const char *path,
char *const *argv, const char *envp);
int irSubProglp (channel_id cid, int tag, const char
*service, const void *pdata, int psize, const char *file,
const char *arg0, ..., const char *argn, (char *)0);
int irSubProgvp (channel_id cid, int tag, const char
*service, const void *pdata, int psize, const char *file,
char *const *argv);
int irSubProgService (channel_id cid, int tag, const char
*service, const void *pdata, int psize);
DESCRIPTION
The irSubProg functions pass control of channel_id cid from
the process invoking the irSubProg function to the process
specified by name in the case of permanent processes, or
path and file in the case of transient processes and tag is
an arbitrary value to be returned with the subsequent
IRE_RETURN event. The semantics of irSubProg are similar to
the semantics of the irExec functions. In particular, the
process invoking the irSubProg function will have control of
the channel_id returned to it when the application invoked
through irSubProg terminates. Rather than blocking until
the invoked application terminates, these routines return
immediately. The calling application is notified of the
invoked applications termination through the IRE_RETURN
event.
The irSubProgp function is used to pass control of the chan-
nel with cid to the permanent IRAPI process which used name
as the argument to irRegister [see irRegister(3IRAPI)]. The
process specified by the name receives a IRE_EXEC event [see
IrEVENTS(4IRAPI)] for channel with cid. It must then
irInit(3IRAPI) the channel cid.
The irSubProgl, irSubProgv, irSubProgle, irSubProgve, irSub-
Proglp, and irSubProgvp functions are used to pass control
of the cid to the transient IRAPI process specified by path
or file. These functions fork and exec process path or file
using the corresponding exec(2) system call with the same
set of arguments passed to the irSubProg function. See
exec(2) for more details on the arguments and differences
between exec(2) calls. When the process calls irRegister
upon startup, it receives a IRE_EXEC event for channel cid
with event_mod2 set to IREM_SUBPROG. It must then irInit
the channel cid.
The irSubProgService function may be used to run a service
without having to know the process name associated with the
service or whether that process is permanent or transient.
The function will determine this information and make the
appropriate irSubProg call. This version of the function
will also pass a "-C <chan>" command line option to the pro-
cess (if it is a transient process), where <chan> is the
channel number for which the application process is being
executed. This channel number may be appended to the pro-
cess name to uniquely register the process for the specific
channel (see irRegister(3IRAPI). NOTE: The bulletin board
is limited to 255 entries so be careful in the use of this
technique. For irSubProgService, if service is the NULL
string or the NULL pointer, the service assigned to the
channel is started (see iraQueryAD(3IRAPI-AD)).
If the process that receives the IRE_EXEC event fails to
call irInit for channel cid within a set time limit, the
ownership of cid is returned to the invoking process. The
invoking process receives a IRE_RETURN event for cid with
event_mod1 set to IREM_ERROR.
Before passing control of cid, the irSubProg functions set
the IRP_SERVICE_NAME parameter for cid to be service [see
irParam(3IRAPI) and IrPARAMETERS(4IRAPI)]. IRAPI applica-
tions can use the IRP_SERVICE_NAME parameter to pass infor-
mation.
A generalized data passing mechanism is provided by the
irSubProg functions. A data buffer address pdata and its
size psize can be passed as arguments to the irSubProg func-
tions. The size of the data buffer must be
IRD_MAXDATABUFFER, but the actual data contained within the
buffer can be of any size less than or equal to
IRD_MAXDATABUFFER. The data buffer can contain any data
that a process would like to transfer to the new owner of
cid. There is no limitation on the format of the data
buffer as its contents is determined by the process invoking
the irSubProg function. If no data is to be transferred,
then pdata must be NULL and psize must be zero. The irSub-
Prog functions use the pdata pointer to set the IRP_EXEC_BUF
parameter and the psize argument to set the IRP_EXEC_BUF_LEN
parameter. If the application simply wants to pass on the
current values of these parameters through irSubProg, psize
should be set to -1 (pdata will be ignored in this case).
When a process receives an IRE_EXEC event, it can use the
irGetParam(3IRAPI) function to check the IRP_EXEC_BUF_LEN
parameter to see if there is any data in the IRP_EXEC_BUF
parameter. If so, it can use the irGetParamStr(3IRAPI)
function to access the data. The process must interpret the
information contained in the data buffer. To facilitate
this, calling and called processes may use the
irExecBuf(3IRAPI) routines to store and retrieve arbitrary
name=value pairs of information in the data buffer.
Processes can also pass data across irSubProg's using the
irSetParam(3IRAPI) and irGetParam(3IRAPI) functions to set
and get the IRP_REGISTER<n> parameters for channel cid [see
IrPARAMETERS(4IRAPI)].
All events for cid on the queue of the process invoking the
irSubProg function are passed to the new owner of cid with
the sequence of the events preserved. Events for channel
cid that occur between the time irSubProg is called and when
the new process calls irInit are placed on the end of the
event queue for channel cid.
The first event the process specified by name, path, or file
receive is an IRE_EXEC event. The IRE_EXEC event fields
contains event_mod1 which is channel number for the cid, and
event_mod2 set to IREM_SUBPROG.
EVENT
Upon success, an IRE_RETURN event is returned with appropri-
ate modifiers to indicate the success or failure of the
function and the return status (see irReturn(3IRAPI) of the
called application. The tag of the IRE_RETURN event is the
tag passed to irSubProg(3IRAPI) (NOTE: TSM will use the
exit status of the script [see the quit() instruction] as
the return status of the application.)
RETURN VALUE
The irSubProg functions return:
IRR_OK if the request is successful.
IRR_FAIL if an error occurs.
ERROR
irError is set as follows if an error occurs:
IRER_INVALID if an invalid argument is passed
IRER_NOTFOUND if the permanent process is not found for
irSubProgp
IRER_BADSTATE if the cid is not in the IDLE state
IRER_INTERNAL if an internal error occurs
IRER_SYSERROR if a system error occurs (irSysError is set to
the corresponding errno)
CAVEAT
Note that once the processing for the irSubProg functions
progress so far, it is impossible for the irSubProg function
to return failure. So there are cases where the irSubProg
function returns success, but the requested action actually
fails. An error message is placed in the error log if this
occurs.
SEE ALSO
irInit(3IRAPI), irExec(3IRAPI),
irParam(3IRAPI), irRegister(3IRAPI), irExecBuf(3IRAPI),
irReturn(3IRAPI), IRAPI-AD(4IRAPI-AD), IrDEFINES(4IRAPI),
IrEVENTS(4IRAPI), IrPARAMETERS(4IRAPI)
VERSION
This is version 11/25/02 of this man page.