_ILECALLX() and _ILECALL()--Call an ILE Procedure for IBM PASE for i
Syntax
#include <as400_protos.h>
int _ILECALLX(const ILEpointer *target,
ILEarglist_base *ILEarglist,
const arg_type_t *signature,
result_type_t result_type,
int flags);
int _ILECALL(const ILEpointer *target,
ILEarglist_base *ILEarglist,
const arg_type_t *signature,
result_type_t result_type);
Default Public Authority: *USE
Library: Standard C Library (libc.a)
Threadsafe: Yes
Note: These functions can only be used in an IBM® i PASE program. See the IBM PASE for i topic collection for more information.
The _ILECALLX() and _ILECALL() functions call an ILE procedure from an IBM PASE for i program. They transfer control to an ILE procedure specified by a 16-byte tagged ILE procedure pointer, passing arguments and returning the function result.
Parameters
- target
- (Input) Pointer to a tagged procedure pointer that addresses the ILE
procedure to call. target must be a 16-byte aligned IBM PASE for i memory
address.
- ILEarglist
- (Input/Output) Pointer to a 16-byte aligned ILE argument list structure.
ILEarglist is the address of the structure that contains any argument values to
pass to the ILE procedure, as well as memory for a function result returned by
the ILE procedure. ILEarglist must be long enough to contain all arguments
required by the target ILE procedure to avoid unpredictable results.
The base structure of an ILE argument list (including a function result area) is specified by type ILEarglist_base. Any argument values for the ILE procedure are stored in memory immediately following the ILEarglist_base type. The specific format of the argument list is determined by the list of arg_type_t values addressed by the signature argument. The alignment requirements for each argument value in the ILE argument list depends on its length:
Argument Length Alignment 1 byte any 2 bytes 2 bytes 3-4 bytes 4 bytes 5-8 bytes 8 bytes 9 or more bytes 16 bytes - signature
- (Input) Pointer to a list of arg_type_t values that specify the sequence
and type of arguments passed to the ILE procedure. ILE procedures can accept a
maximum of 400 arguments. The actual number of arguments processed by the
_ILECALLX or _ILECALL function is determined by the number of entries in the
signature list, which is determined by the location of the first ARG_END value
in the list. The following values are supported in the signature list:
ARG_END (0) Specifies the end of the signature list. ARG_INT8 (-1) Signed 1-byte integer argument. ARG_UINT8 (-2) Unsigned 1-byte integer argument. ARG_INT16 (-3) Signed 2-byte integer argument. ARG_UINT16 (-4) Unsigned 2-byte integer argument. ARG_INT32 (-5) Signed 4-byte integer argument. ARG_UINT32 (-6) Unsigned 4-byte integer argument. ARG_INT64 (-7) Signed 8-byte integer argument. ARG_UINT64 (-8) Unsigned 8-byte integer argument. ARG_FLOAT32 (-9) 4-byte floating-point argument. ARG_FLOAT64 (-10) 8-byte floating-point argument. ARG_FLOAT128 (-18) 16-byte floating-point argument. ARG_MEMPTR (-11) The argument is a field of type ILEpointer into which the caller has stored an IBM PASE for i memory address (in member address). _ILECALLX and _ILECALL convert the IBM PASE for i memory address to an equivalent teraspace address, except that address zero is converted to a special value for a null pointer. The converted result is passed as the argument value to the target ILE procedure. Both functions may update the ILEpointer value so it contains a tagged space pointer. ARG_SPCPTR (-12) The argument is a field of type ILEpointer where the IBM PASE for i program has stored a tagged space pointer (or an untagged or null pointer). ARG_SPCPTRI (-16) The argument is a field of type ILEpointer into which the caller has stored the IBM PASE for i memory address (in member address) of a tagged space pointer (or an untagged or null pointer) that is passed to the target ILE procedure. The ILEpointer in the argument list may be overlayed with a copy of the space pointer. ARG_OPENPTR (-13) The argument is a field of type ILEpointer where the IBM PASE for i program has stored a 16-byte pointer of any type (including possibly an untagged or null pointer). ARG_OPENPTRI (-17) The argument is a field of type ILEpointer into which the caller has stored the IBM PASE for i memory address (in member address) of a 16-byte pointer of any type (including possibly an untagged or null pointer) that is copied into the argument list (overlaying the original ILEpointer value) and passed as the argument to the target ILE procedure. ARG_MEMTS64 (-14) The argument is a field of type ts64_t into which the caller has stored an IBM PASE for i memory address. _ILECALLX and _ILECALL convert the IBM PASE for i memory address to an equivalent 64-bit teraspace pointer, except that null (address zero) is unchanged. The converted result is passed as the argument value to the target ILE procedure. The ts64_t value in the argument list may be overlayed with the converted address. ARG_TS64PTR (-15) The argument is a field of type ts64_t where the IBM PASE for i program has stored a 64-bit teraspace address. Any positive number
(1-32767)The argument is an aggregate (structure or union). The value in the signature list is the length, in bytes, of the aggregate.
- result_type
- (Input) Specifies the type of function result returned by the ILE
procedure.
The following values are supported:
RESULT_VOID(0) No function result. RESULT_INT8 (-1) Signed 1-byte integer result, returned in field result.s_int8.r_int8 in the ILEarglist argument. RESULT_UINT8 (-2) Unsigned 1-byte integer result, returned in field result.s_uint8.r_uint8 in the ILEarglist argument. RESULT_INT16 (-3) Signed 2-byte integer result, returned in field result.s_int16.r_int16 in the ILEarglist argument. RESULT_UINT16 (-4) Unsigned 2-byte integer result, returned in field result.s_uint16.r_uint16 in the ILEarglist argument. RESULT_INT32 (-5) Signed 4-byte integer result, returned in field result.s_int32.r_int32 in the ILEarglist argument. RESULT_UINT32 (-6) Unsigned 4-byte integer result, returned in field result.s_uint32.r_uint32 in the ILEarglist argument. RESULT_INT64 (-7) Signed 8-byte integer result, returned in field result.r_int64 in the ILEarglist argument. RESULT_UINT64 (-8) Unsigned 8-byte integer result, returned in field result.r_uint64 in the ILEarglist argument. RESULT_FLOAT64 (-10) 8-byte floating-point result, returned in field result.r_float64 in the ILEarglist argument. RESULT_FLOAT128 (-18) 16-byte floating-point result, returned in field result.r_float128 in the ILEarglist argument. Any positive number
(1-32767)The function result is an aggregate (structure or union). result_type is the length, in bytes, of the aggregate. An aggregate function result is returned in a buffer allocated by the caller and passed to the target ILE procedure using a special field in the argument list. The caller must provide a buffer large enough for the result returned by the target ILE procedure to avoid unpredictable results. An IBM PASE for i program must set field result.r_aggregate.addr in type ILEarglist_base to the IBM PASE for i memory address of the result buffer before calling an ILE procedure that returns an aggregate result. _ILECALLX and _ILECALL convert the IBM PASE for i memory address to a teraspace address the same way they convert ARG_MEMPTR arguments.
- flags
- (Input) Specifies options to control how the ILE procedure program is
called. The flags argument is a bitwise logical-or of one or more of the
following values:
ILECALL_NOINTERRUPT
(0x00000004)Specifies that IBM PASE for i signals will not interrupt the called ILE procedure. Some system functions (such as select) can be interrupted by signals. Normally either an ILE signal or an IBM PASE for i signal can interrupt such an operation, but ILECALL_NOINTERRUPT delays IBM PASE for i signal processing until control returns from the called ILE procedure. This option has no effect on ILE signal handling. ILECALL_EXCP_NOSIGNAL
(0x00000020)Suppresses signals for IBM i exceptions. This option causes the system to return a function result of -1 (and set errno to 3474) instead of raising a signal for any exception during the call. You can use the QMHRCVPM()--Receive Program Message for IBM PASE for i function specifying message type *EXCP to determine what exception occurred.
Authorities
_ILECALL and _ILECALLX require no authority.
Return Value
Most errors from _ILECALLX and _ILECALL are reported with IBM i exception messages that are converted to IBM PASE for i signals unless ILECALL_EXCP_NOSIGNAL is specified. See IBM PASE for i Signal Handling for information about handling IBM i exceptions.
If no IBM PASE for i signal is sent, one of these values is returned:
| ILECALL_NOERROR(0) | The target ILE procedure was called and returned normally. |
| ILECALL_INVALID_ARG (1) | An invalid value was found in the signature list. |
| ILECALL_INVALID_RESULT (2) | The result_type value is invalid. |
| ILECALL_INVALID_FLAGS (3) | The flags value is invalid. |
Usage Notes
- _ILECALLX
and _ILECALL can only call ILE procedures in an IBM i bound
program. If your IBM PASE for i program needs to call an IBM i program object
(object type *PGM), you must use the _PGMCALL function or use
the systemCL function to run the CL CALL command.
- _ILECALLX and _ILECALL do no character
encoding conversions, so the IBM PASE for i program may need to convert argument
and result character strings between ASCII and EBCDIC. IBM PASE for i runtime
function iconv can be used for character conversions.
- An IBM PASE for i program can pass tagged space pointer arguments to an ILE
procedure using either ARG_SPCPTR or ARG_OPENPTR unless the target ILE
procedure uses ARGOPT linkage, in which case ARG_SPCPTR must be used.
ARG_MEMPTR can be used for space pointer arguments regardless of what linkage
is used by the target ILE procedure.
- ILE procedure pointers address resources inside an ILE activation group.
The machine prohibits use of activation group resources from a process other
than the owner of the activation group. This means that the child process of a
fork cannot use ILE procedure pointers inherited from the
parent process. The child process can, however, use _ILELOADX
to load the bound program (creating a new activation in the child process) and
then use _ILESYMX to obtain ILE procedure pointers into the new
activation.
- See Set Space Pointer for IBM PASE for i
(_SETSPP) for more information about tagged space pointers and sharing tagged
pointers between processes.
- _ILECALL is
equivalent to _ILECALLX with the
ILECALL_NOINTERRUPT flag.
Related Information
- _PGMCALL()--Call an IBM i Program for IBM PASE for i
- _ILESYMX()--Find an Exported ILE Symbol for IBM PASE for i
- _ILELOADX()--Load an ILE Bound Program for IBM PASE for i
- size_ILEarglist()--Compute ILE Argument List Size for IBM PASE for i
- build_ILEarglist()--Build an ILE Argument List for IBM PASE for i
- QMHRCVPM--Receive Program Message for IBM PASE for i
- _CVTSPP()--Convert Space Pointer for IBM PASE for i
- _CVTTS64()--Convert Teraspace Address for IBM PASE for i
- _GETTS64() and _GETTS64_SPP--Get Teraspace Address for IBM PASE for i
- _GETTS64M()--Get Multiple Teraspace Addresses for IBM PASE for i
- _SETSPP() and _SETSPP_TS64()--Set Space Pointer for IBM PASE for i
- _SETSPPM()--Set Multiple Space Pointers for IBM PASE for i
- systemCL()--Run a CL Command for IBM PASE for i
API introduced: V4R5