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

Qp2RunPase()--Run an IBM PASE for i Program

API introduced: V4R5

[ Back to top | IBM PASE for i APIs | APIs by category ]