Qp2CallPase()--Call an i5/OS PASE 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 i5/OS Portable Application Solutions Environment (i5/OS PASE) program in a job that is already running the i5/OS PASE program.

Parameters

target

(Input) Pointer to a function descriptor for the procedure (in the i5/OS PASE 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 i5/OS PASE 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 i5/OS PASE 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 i5/OS PASE 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 i5/OS PASE 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 i5/OS PASE 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 i5/OS PASE 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 i5/OS PASE program.
QP2_ARG_FLOAT32 (-3)	A 4-byte floating point number.
QP2_ARG_FLOAT64 (-4)	An 8-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 i5/OS PASE procedure. QP2_ARG_PTR32 is allowed only when calling a procedure in a 32-bit i5/OS PASE 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 i5/OS PASE procedure. QP2_ARG_PTR64 is allowed only when calling a procedure in a 64-bit i5/OS PASE program.

result_type

(Input) The data type of the function result returned by the i5/OS PASE 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 i5/OS PASE stack to the buf area after the i5/OS PASE 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 i5/OS PASE 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 i5/OS PASE program.
QP2_RESULT_FLOAT64 (-4)	An 8-byte floating point number.
QP2_RESULT_PTR32 (-5)	A 4-byte pointer. A pointer result from the i5/OS PASE procedure is returned unchanged. This value is allowed only when calling a procedure in a 32-bit i5/OS PASE program.
QP2_RESULT_PTR64 (-6)	An 8-byte pointer. A pointer result from the i5/OS PASE procedure is returned unchanged. This value is allowed only when calling a procedure in a 64-bit i5/OS PASE program.

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 i5/OS PASE stack before the i5/OS PASE procedure is called.

Authorities

None.

Return Value

The function result is an integer that indicates whether the i5/OS PASE function was called successfully. Header file qp2user.h defines the following constants for the return code from Qp2CallPase and Qp2CallPase2:

QP2CALLPASE_NORMAL (0)	The i5/OS PASE 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 i5/OS PASE 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 i5/OS PASE program is running in the job, or the thread that called Qp2CallPase or Qp2CallPase2 was neither the initial i5/OS PASE thread nor a thread created using i5/OS PASE pthread interfaces.
QP2CALLPASE_ARG_ERROR (4)	One or more values in the signature array are not valid.
QP2CALLPASE_TERMINATING (6)	The i5/OS PASE program is terminating. No function result was returned. The i5/OS PASE program may have run the exit function, or a signal might have caused the program to terminate.
QP2CALLPASE_RETURN_NOEXIT (7)	The i5/OS PASE program returned without exiting by calling the i5/OS PASE _RETURN function. No function result was returned.

Usage Notes

Qp2CallPase and Qp2CallPase2 are supported only when an i5/OS PASE 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 i5/OS PASE program or in a thread created using i5/OS PASE pthread interfaces, unless i5/OS PASE environment variable PASE_THREAD_ATTACH was set to Y when a thread-enabled i5/OS PASE program was started.
Once an ILE thread has attached to i5/OS PASE (by calling an i5/OS PASE procedure), that thread is subject to asynchronous interruption for i5/OS PASE functions such as signal handling and thread cancellation. In particular, the thread will be canceled as part of ending the i5/OS PASE program (when exit runs or i5/OS PASE processing terminates for a signal).
An i5/OS PASE procedure called by Qp2CallPase or Qp2CallPase2 must return to its caller. Unpredictable results occur if the i5/OS PASE 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 i5/OS PASE stack when Qp2CallPase or Qp2CallPase2 is called, the called i5/OS PASE 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 i5/OS PASE program is really a pointer to a function descriptor for the procedure. An i5/OS PASE program can easily provide a function descriptor to ILE code by passing an i5/OS PASE 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 i5/OS PASE memory, and in by-address result data copied from i5/OS PASE 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 i5/OS PASE program or as QP2_RESULT_DWORD for a 64-bit i5/OS PASE 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 i5/OS PASE procedure.
You may need to limit result_type and bufLenIn to avoid overrunning the end of the i5/OS PASE stack. Arguments and results that are too large for the stack can be passed by-address using argument pointers to i5/OS PASE 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 i5/OS PASE 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 i5/OS PASE 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 i5/OS PASE Program

API introduced: V4R5

Top | i5/OS PASE APIs | APIs by category