NAME
irExecp, irExecl, irExecv, irExecle, irExecve, irExeclp,
irExecvp, irExecService, irExecDefOwn - transfer ownership
of a channel to another Intuity Response application
SYNOPSIS
#include <irapi.h>
int irExecp (channel_id cid, const char *service, const char
*name, const void *pdata, int psize);
int irExecl (channel_id cid, const char *service, const void
*pdata, int psize, const char *path,...);
int irExecv (channel_id cid, const char *service, const void
*pdata, int psize, const char *path, const char *argv);
int irExecle (channel_id cid, const char *service, const
void *pdata, int psize, const char *path,...);
int irExecve (channel_id cid, const char *service, const
void *pdata, int psize, const char *path, char *const *argv,
const char *envp);
int irExeclp (channel_id cid, const char *service, const
void *pdata, int psize, const char *file,...);
int irExecvp (channel_id cid, const char *service, const
void *pdata, int psize, const char *file, char *const
*argv);
int irExecService (channel_id cid, const char *service,
const void *pdata, int psize);
int irExecDefOwn (channel_id cid, int service_type, const
void *pdata, int psize);
DESCRIPTION
The irExec functions pass control of channel_id cid from the
process invoking the irExec function to the process speci-
fied by name in the case of permanent processes, or path and
file in the case of transient processes. The semantics of
irExec differ slightly from the semantics of exec. In par-
ticular, the process invoking the irExec function is not
replaced by the image of another process; the irExec call is
return.
The irExecp function is used to pass control of the channel
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 with cid.
The irExecl, irExecv, irExecle, irExecve, irExeclp, and
irExecvp 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 argu-
ments passed to the irExec 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. It must then
irInit the channel cid.
The irExecService 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 irExec call. This version of the function will
also pass a "-C <chan>" command line option to the process
(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 process name to
uniquely register the process for the specific channel (see
irRegister(3IRAPI). For irExecService, if service is the
NULL string or the NULL pointer, the service assigned to the
channel is started.
The function irExecDefOwn will exec the service type speci-
fied by service_type to the default owner for the channel
(usually AD). This is typically done when an application
has received an unexpected new call (for example, in a glare
condition). (See irInitCall for an automatic technique for
handling glare). The default owner is expected to respond
to the exec request by starting the application suggested by
the current call profile. service_type may be either
IRD_AD_STARTUP (the service run in response to a new call)
or IRD_AD_STANDARD (the service normally run when the
default owner is exec'ed or in response to a new call if no
startup service is defined). These values are defined in
irapi-ad.h.
This function should be used with care, as it can cause an
application and the default owner to play catch with the
channel very, very fast. If an application execs the
default owner and the call profile is the same as it was
when the application was first exec'd, the default owner
will almost certainly respond by immediately re-exec'ing the
application. If the application responds to the exec
request with irExecDefOwn, then the channel will bounce back
between the application and the default owner indefinitely.
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 its default owner. The
default owner receives a IRE_DEFOWNER event for cid.
Before passing control of cid, the irExec 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. For example, the Application Dispatch (AD) process
always passes the service name of the application to the
irExec functions when passing control of cid in response to
a new call.
A generalized data passing mechanism is provided by the
irExec functions. A data buffer address pdata and its size
psize can be passed as arguments to the irExec functions.
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 irExec function. If no data is
to be transferred, then pdata must be NULL and psize must be
zero. The irExec 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
irExec, 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 pro-
cess 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 irExec'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
irExec 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 irExec 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_EXEC.
RETURN VALUE
The irExec 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
irExecp
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 irExec functions pro-
gress so far, it is impossible for the irExec function to
return failure. So there are cases where the irExec func-
tion returns success, but the requested action actually
fails. An error message is placed in the error log if this
occurs.
SEE ALSO
irInit(3IRAPI), irParam(3IRAPI),
irRegister(3IRAPI), irExecBuf(3IRAPI), irSubProg(3IRAPI),
IRAPI-AD(4IRAPI-AD), IrDEFINES(4IRAPI), IrEVENTS(4IRAPI),
IrPARAMETERS(4IRAPI)
VERSION
This is version 10/24/02 of this man page.