Qp2CallPase() and Qp2CallPase2()--Call an IBM PASE for i Procedure
Syntax
#include <qp2user.h> int Qp2CallPase(const void *target, const void *arglist, const QP2_arg_type_t *signature, QP2_result_type_t result_type, void *buf); int Qp2CallPase2(const void *target, const void *arglist, const QP2_arg_type_t *signature, QP2_result_type_t result_type, void *buf, short bufLenIn);Service Program Name: QP2USER
Default Public Authority: *USE
Threadsafe: Yes
The Qp2CallPase() and Qp2CallPase2() functions call a procedure in an IBM® i Portable Application Solutions Environment (IBM PASE for i) program in a job that is already running the IBM PASE for i program.
Parameters
- target
- (Input) Pointer to a function descriptor for the procedure (in the IBM PASE for i
program) to call. The format and contents of a function descriptor are
specified by the PowerPC® Application Binary Interface (ABI) for AIX. A function
descriptor contains three IBM PASE for i addresses (not MI pointers) that point to
the executable instructions, table of contents (TOC), and environment for the
target procedure.
- arglist
- (Input) Pointer to the argument list for the IBM PASE for i procedure. The
format and contents of a PASE argument list generally are specified by the
PowerPC ABI for AIX. The specific argument list structure for the IBM PASE for i
procedure identified by the target parameter is determined by the list of
argument data types specified by the signature parameter.
- signature
- (Input) Pointer to an array of values that specify the sequence and type of
arguments passed to the IBM PASE for i procedure. Each element in the array is
either a special value defined in header file qp2user.h or a positive number
that is the length in bytes of a structure or union argument passed by value.
The last value in the array must be QP2_ARG_END. Header file qp2user.h defines
the following constants for the data types supported as arguments for an IBM PASE for i
procedure:
QP2_ARG_END (0) The end of the list of argument type values.
QP2_ARG_WORD (-1) A 4-byte signed or unsigned integer, or a structure or union no longer than four bytes. This value is allowed only when calling a procedure in a 32-bit IBM PASE for i program.
QP2_ARG_DWORD (-2) An 8-byte signed or unsigned integer, or a structure or union no longer than eight bytes. This value is allowed only when calling a procedure in a 64-bit IBM PASE for i program.
QP2_ARG_FLOAT32 (-3) A 4-byte floating point number.
QP2_ARG_FLOAT64 (-4) An 8-byte floating point number.
QP2_ARG_FLOAT128 (-9) A 16-byte floating point number.
QP2_ARG_PTR32 (-5) A 4-byte pointer. The value in the arglist buffer is passed unchanged unless its high-order bits (excluding the lower 16 bits) match the corresponding part of constant QP2_ARG_PTR_TOSTACK (0x0fff0000). In that case, the arglist value is changed to the memory address used for a copy of the buf area plus an offset in the lower 16 bits of the arglist value, and the updated value is passed to the IBM PASE for i procedure. QP2_ARG_PTR32 is allowed only when calling a procedure in a 32-bit IBM PASE for i program.
QP2_ARG_PTR64 (-6) An 8-byte pointer. The value in the arglist buffer is passed unchanged unless its high-order bits (excluding the lower 16 bits) match the corresponding part of constant QP2_ARG_PTR_TOSTACK (0x000000000fff0000). In that case, the arglist value is changed to the memory address used for a copy of the buf area plus an offset in the lower 16 bits of the arglist value, and the updated value is passed to the IBM PASE for i procedure. QP2_ARG_PTR64 is allowed only when calling a procedure in a 64-bit IBM PASE for i program. QP2_ARG_TS64 (-7) An 8-byte teraspace pointer (must be 8-byte aligned). The value in the arglist buffer is converted to an IBM PASE for i 32-bit or 64-bit IBM PASE for i memory address that is passed as the argument value. The argument passed to the IBM PASE for i function is zero if the teraspace pointer addresses memory at teraspace offset zero, or -1 if the pointer addresses storage the IBM PASE for i program cannot reference. QP2_ARG_SPCPTR (-8) A 16-byte space pointer (must be 16-byte aligned). The value in the arglist buffer is converted to an IBM PASE for i 32-bit or 64-bit IBM PASE for i memory address that is passed as the argument value. The argument passed to the IBM PASE for i function is zero if the 16-byte pointer is not a valid space pointer, or -1 if the pointer addresses storage the IBM PASE for i program cannot reference.
- result_type
- (Input) The data type of the function result returned by the IBM PASE for i
procedure. Result_type is either a special value defined in header file qp2user.h or a positive
number that is the length in bytes of by-address result data copied from the IBM PASE for i stack
to the buf area after the IBM PASE for i procedure returns. Header file qp2user.h defines the
following constants for function result data types:
QP2_RESULT_VOID (0) No function result returned.
QP2_RESULT_WORD (-1) A 4-byte signed or unsigned integer, or a structure or union no longer than four bytes. This value is allowed only when calling a procedure in a 32-bit IBM PASE for i program.
QP2_RESULT_DWORD (-2) An 8-byte signed or unsigned integer, or a structure or union no longer than eight bytes returned by a procedure in a 64-bit IBM PASE for i program.
QP2_RESULT_FLOAT64 (-4) An 8-byte floating point number.
QP2_RESULT_FLOAT128 (-9) A 16-byte floating point number.
QP2_RESULT_PTR32 (-5) A 4-byte pointer. A pointer result from the IBM PASE for i procedure is returned unchanged. This value is allowed only when calling a procedure in a 32-bit IBM PASE for i program.
QP2_RESULT_PTR64 (-6) An 8-byte pointer. A pointer result from the IBM PASE for i procedure is returned unchanged. This value is allowed only when calling a procedure in a 64-bit IBM PASE for i program. QP2_RESULT_TS64 (-7) An 8-byte teraspace pointer. A 32-bit or 64-bit IBM PASE for i memory address returned by the called function is converted to an 8-byte teraspace pointer. The teraspace pointer value is zero if the IBM PASE for i function returns zero. QP2_RESULT_SPCPTR (-8) A 16-byte space pointer. A 32-bit or 64-bit IBM PASE for i memory address returned by the called function is converted to a 16-byte space pointer (or null). The 16-byte pointer value is null if the IBM PASE for i function returns zero. The address specified by the buf argument must be 16-byte aligned to avoid an alignment exception.
- buf
- (Input/Output) Pointer to a buffer that contains by-address argument data
and the function result. buf is ignored if result_type is QP2_RESULT_VOID and
bufLenIn is either zero or omitted (for Qp2CallPase).
- bufLenIn
- (Input) Length of by-address argument input data. A positive number specifies the number of bytes copied from the buf area to the IBM PASE for i stack before the IBM PASE for i procedure is called.
Authorities
None.
Return Value
The function result is an integer that indicates whether the IBM PASE for i function was called successfully. Header file qp2user.h defines the following constants for the return code from Qp2CallPase and Qp2CallPase2:
QP2CALLPASE_NORMAL (0) | The IBM PASE for i procedure ran to completion and
its function result (if any) was stored in the location identified by the buf
parameter. |
QP2CALLPASE_RESULT_ERROR (1) | The IBM PASE for i procedure ran to completion, but
its function result could not be stored at the location identified by the buf
parameter. buf may be a null pointer value, or the space addressed by buf may
be damaged or destroyed. |
QP2CALLPASE_ENVIRON_ERROR (2) | The operation is not allowed because no IBM PASE for i
program is running in the job, or the thread that called Qp2CallPase or
Qp2CallPase2 was neither the initial IBM PASE for i thread nor a thread created
using IBM PASE for i pthread interfaces. |
QP2CALLPASE_ARG_ERROR (4) | One or more values in the signature array are not
valid. |
QP2CALLPASE_TERMINATING (6) | The IBM PASE for i program is terminating. No
function result was returned. The IBM PASE for i program may have run the exit
function, or a signal might have caused the program to terminate. |
QP2CALLPASE_RETURN_NOEXIT (7) | The IBM PASE for i program returned without exiting by calling the IBM PASE for i _RETURN function. No function result was returned. |
Usage Notes
- Qp2CallPase and Qp2CallPase2 are supported only when an IBM PASE for i program
is currently running in the job. This means that Qp2RunPase must be running
actively in the job, or the job must be a fork child process.
- You can run Qp2CallPase and Qp2CallPase2 only in the initial thread that started the IBM PASE for i
program or in a thread created using IBM PASE for i pthread interfaces, unless IBM PASE for i
environment variable PASE_THREAD_ATTACH was set to Y when a thread-enabled
IBM PASE for i program was started.
- Once an ILE thread has attached to IBM PASE for i (by calling an IBM PASE for i procedure), that thread
is subject to asynchronous interruption for IBM PASE for i functions such as signal
handling and thread cancellation. In particular, the thread will be canceled as
part of ending the IBM PASE for i program (when exit runs or
IBM PASE for i processing terminates for a signal).
- An IBM PASE for i procedure called by Qp2CallPase or Qp2CallPase2 must return
to its caller. Unpredictable results occur if the IBM PASE for i procedure
attempts to longjmp to an older call or if it performs an operation that
terminates the thread or process (such as calling the exit function). If a
signal handler is on the IBM PASE for i stack when Qp2CallPase or Qp2CallPase2 is
called, the called IBM PASE for i procedure must also honor restrictions on
runtime functions allowed in signal handlers (see AIX signal handling
documentation for details).
- A pointer to any function in an IBM PASE for i program is really a pointer to
a function descriptor for the procedure. An IBM PASE for i program can easily
provide a function descriptor to ILE code by passing an IBM PASE for i function
pointer value converted to an ILE memory address. The conversion can be done
using the _SETSPP function or the ARG_MEMPTR argument type on the _ILECALLX or
_ILECALL function.
- Qp2CallPase and Qp2CallPase2 support arguments and results passed by-address through
the use of QP2_ARG_PTR32 or QP2_ARG_PTR64 values in the signature array and positive
numbers for the result_type and/or bufLenIn arguments.
- If the buf area is 16-byte aligned, any tagged ILE pointers are preserved in by-address (input)
argument data copied from the buf area to IBM PASE for i memory, and in by-address result
data copied from IBM PASE for i memory to the buf area.
- A structure or union function result returned by-value that is short enough to fit into a
register must be handled as QP2_RESULT_WORD for a 32-bit IBM PASE for i program or as
QP2_RESULT_DWORD for a 64-bit IBM PASE for i program. Longer structure or union
function results returned by-value are actually returned by-address through a
buffer pointer passed as the first (hidden) argument to the IBM PASE for i
procedure.
- You may need to limit result_type and bufLenIn to avoid overrunning the end of the IBM PASE for i
stack. Arguments and results that are too large for the stack can be passed by-address
using argument pointers to IBM PASE for i heap storage.
- The PowerPC ABI for AIX requires 4-byte alignment for each argument passed to a procedure in a 32-bit program, and 8-byte alignment for each argument passed to a procedure in a 64-bit program. Qp2CallPase and Qp2CallPase2 assume the caller provides an arglist data structure that provides this alignment, including any necessary pad bytes following a structure or union argument and following a QP2_ARG_FLOAT32 argument passed to a 64-bit IBM PASE for i program. The arglist structure also needs to store any 64-bit integer or floating point argument on a 4-byte boundary when the target procedure is in a 32-bit IBM PASE for i program (rather than the 8-byte boundary used as the default for these types in ILE C and C++ compilers).
Related Information
API introduced: V4R5