442 lines
15 KiB
HTML
442 lines
15 KiB
HTML
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||
|
|
<html>
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
||
|
|
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
|
||
|
|
<title>Qp2CallPase()--Call an i5/OS PASE Procedure</title>
|
||
|
|
<!-- Begin Header Records -->
|
||
|
|
<!-- All rights reserved. Licensed Materials Property of IBM -->
|
||
|
|
<!-- US Government Users Restricted Rights -->
|
||
|
|
<!-- Use, duplication or disclosure restricted by -->
|
||
|
|
<!-- GSA ADP Schedule Contract with IBM Corp. -->
|
||
|
|
<!-- Change History: -->
|
||
|
|
<!-- YYMMDD USERID Change description -->
|
||
|
|
<!-- Edited by Kersten Jan 02 -->
|
||
|
|
<!-- Created by V2DCIJB on 23 Nov 1999 -->
|
||
|
|
<!-- End Header Records -->
|
||
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<a name="Top_Of_Page"></a>
|
||
|
|
<!--Java sync-link-->
|
||
|
|
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
|
||
|
|
</script>
|
||
|
|
|
||
|
|
<h2>Qp2CallPase()--Call an i5/OS PASE Procedure</h2>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<div class="box" style="width: 70%;">
|
||
|
|
<br>
|
||
|
|
Syntax
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
#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);
|
||
|
|
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
Service Program Name: QP2USER<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Default Public Authority: *USE<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Threadsafe: Yes<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Parameters</h3>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong>target</strong></dt>
|
||
|
|
|
||
|
|
<dd>(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.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>arglist</strong></dt>
|
||
|
|
|
||
|
|
<dd>(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.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>signature</strong></dt>
|
||
|
|
|
||
|
|
<dd>(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:<br>
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<table cellpadding="5">
|
||
|
|
<!-- cols="25 75" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>QP2_ARG_END (0)</em></td>
|
||
|
|
<td align="left" valign="top">The end of the list of argument type values.<br>
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>QP2_ARG_WORD (-1)</em></td>
|
||
|
|
<td align="left" valign="top">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.<br>
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>QP2_ARG_DWORD (-2)</em></td>
|
||
|
|
<td align="left" valign="top">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.<br>
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>QP2_ARG_FLOAT32 (-3)</em></td>
|
||
|
|
<td align="left" valign="top">A 4-byte floating point number.<br>
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>QP2_ARG_FLOAT64 (-4)</em></td>
|
||
|
|
<td align="left" valign="top">An 8-byte floating point number.<br>
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>QP2_ARG_PTR32 (-5)</em></td>
|
||
|
|
<td align="left" valign="top">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.<br>
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>QP2_ARG_PTR64 (-6)</em></td>
|
||
|
|
<td align="left" valign="top">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.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>result_type</strong></dt>
|
||
|
|
|
||
|
|
<dd>(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:<br>
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<table cellpadding="2">
|
||
|
|
<!-- cols="25 75" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>QP2_RESULT_VOID (0)</em></td>
|
||
|
|
<td align="left" valign="top">No function result returned.<br>
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>QP2_RESULT_WORD (-1)</em></td>
|
||
|
|
<td align="left" valign="top">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.<br>
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>QP2_RESULT_DWORD (-2)</em></td>
|
||
|
|
<td align="left" valign="top">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.<br>
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top" nowrap><em>QP2_RESULT_FLOAT64 (-4)</em></td>
|
||
|
|
<td align="left" valign="top">An 8-byte floating point number.<br>
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>QP2_RESULT_PTR32 (-5)</em></td>
|
||
|
|
<td align="left" valign="top">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.<br>
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top" nowrap><em>QP2_RESULT_PTR64 (-6)</em></td>
|
||
|
|
<td align="left" valign="top">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.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>buf</strong></dt>
|
||
|
|
|
||
|
|
<dd>(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).<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>bufLenIn</strong></dt>
|
||
|
|
|
||
|
|
<dd>(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.</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Authorities</h3>
|
||
|
|
|
||
|
|
<p>None.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Return Value</h3>
|
||
|
|
|
||
|
|
<p>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:</p>
|
||
|
|
|
||
|
|
<table cellpadding="5">
|
||
|
|
<!-- cols="35 65" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>QP2CALLPASE_NORMAL (0)</em></td>
|
||
|
|
<td align="left" valign="top">The i5/OS PASE procedure ran to completion and
|
||
|
|
its function result (if any) was stored in the location identified by the buf
|
||
|
|
parameter.<br>
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>QP2CALLPASE_RESULT_ERROR (1)</em></td>
|
||
|
|
<td align="left" valign="top">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.<br>
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top" nowrap><em>QP2CALLPASE_ENVIRON_ERROR
|
||
|
|
(2)</em></td>
|
||
|
|
<td align="left" valign="top">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.<br>
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>QP2CALLPASE_ARG_ERROR (4)</em></td>
|
||
|
|
<td align="left" valign="top">One or more values in the signature array are not
|
||
|
|
valid.<br>
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>QP2CALLPASE_TERMINATING (6)</em></td>
|
||
|
|
<td align="left" valign="top">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.<br>
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>QP2CALLPASE_RETURN_NOEXIT (7)</em></td>
|
||
|
|
<td align="left" valign="top">The i5/OS PASE program returned without exiting
|
||
|
|
by calling the i5/OS PASE <strong>_RETURN</strong> function. No function
|
||
|
|
result was returned.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Usage Notes</h3>
|
||
|
|
|
||
|
|
<ol>
|
||
|
|
<li>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.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>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.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>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 <strong>exit</strong> runs or
|
||
|
|
i5/OS PASE processing terminates for a signal).<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>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).<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>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.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>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.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>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.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>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.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>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.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>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).</li>
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Related Information</h3>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li><a href="qp2runpase.htm">Qp2RunPase()</a>--Run an i5/OS PASE Program</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<hr>
|
||
|
|
API introduced: V4R5
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
<center>
|
||
|
|
<table cellpadding="2" cellspacing="2">
|
||
|
|
<tr align="center">
|
||
|
|
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
|
||
|
|
"pase1.htm">i5/OS PASE APIs</a> | <a href="aplist.htm">APIs by category</a>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</center>
|
||
|
|
</body>
|
||
|
|
</html>
|
||
|
|
|