friedkiwi/ibm-information-center
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
14ed2849c6
ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/qzruclsp.htm

613 lines
18 KiB
HTML
Raw Blame History

<!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>Call Service Program Procedure (QZRUCLSP) API</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. -->
<!-- QZRUCLS SCRIPT A converted by B2H R4.1 (346) (CMS) by HOLTJM at -->
<!-- RCHVMW2 on 5 Feb 1999 at 14:58:06 -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!--Edited by Kersten Nov 2001 -->
<!--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 language="Javascript" src="../rzahg/synch.js" type="text/javascript">
</script>
<h2>Call Service Program Procedure (QZRUCLSP) API</h2>
<div class="box" style="width: 80%;">
<br>
&nbsp;&nbsp;Required Parameter Group:<br>
<!-- iddvc RMBR -->
<br>
<table width="100%">
<tr>
<td align="center" valign="top" width="10%">1</td>
<td align="left" valign="top" width="45%">Qualified service program name</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="25%">Char(20)</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">Export Name</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">3</td>
<td align="left" valign="top">Return Value Format</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="left" valign="top">Parameter Formats</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Array(*) of Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">5</td>
<td align="left" valign="top">Number of Parameters</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">6</td>
<td align="left" valign="top">Error code</td>
<td align="left" valign="top">I/O</td>
<td align="left" valign="top">CHAR(*)</td>
</tr>
</table>
<br>
&nbsp;&nbsp;Optional Parameters:<br>
<!-- iddvc RMBR -->
<br>
<table width="100%">
<tr>
<td align="center" valign="top" width="10%">7</td>
<td align="left" valign="top" width="45%">Return Value</td>
<td align="left" valign="top" width="20%">Output</td>
<td align="left" valign="top" width="25%">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="left" valign="top">Parameter 1</td>
<td align="left" valign="top">I/O</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">9</td>
<td align="left" valign="top">Parameter 2</td>
<td align="left" valign="top">I/O</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">10</td>
<td align="left" valign="top">Parameter 3</td>
<td align="left" valign="top">I/O</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">11</td>
<td align="left" valign="top">Parameter 4</td>
<td align="left" valign="top">I/O</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">12</td>
<td align="left" valign="top">Parameter 5</td>
<td align="left" valign="top">I/O</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">13</td>
<td align="left" valign="top">Parameter 6</td>
<td align="left" valign="top">I/O</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">14</td>
<td align="left" valign="top">Parameter 7</td>
<td align="left" valign="top">I/O</td>
<td align="left" valign="top">Char(*)</td>
</tr>
</table>
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: No<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Call Service Program Procedure (QZRUCLSP) API allows an unbound call to
an ILE procedure exported by a service program.</p>
<p>The name of the service program, and the name of the exported procedure are
passed in as parameters. This API runs in the callers activation group and if
the specified service program also specifies that it run in the caller's
activation group, it too will run in the same group. All dependent service
programs are activated, and all initialization of the newly activated service
programs is done.</p>
<p>Since the QZRUCLSP API has no way of determining the parameters that the
called procedure expects, the layout of those parameters must be described by
the caller in a "Parameter Format" array.</p>
<p>All of the parameter values given to this API to be subsequently passed to
the procedure are passed by reference.</p>
<p>This API does not support calling procedures that have been defined using
"#pragma argopt".</p>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>Service Program Authority</em></dt>
<dd>*EXECUTE</dd>
<dt><em>Service Program Library Authority</em></dt>
<dd>*EXECUTE</dd>
<dt><em>Service Program Lock</em></dt>
<dd>*SHRRD</dd>
</dl>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Qualified service program name</strong></dt>
<dd>INPUT; CHAR(20)
<p>The name of the service program for which the information is to be listed.
The first 10 characters contain the service program name. The second 10
characters contain the name of the library where the service program is
located.</p>
<p>The library name can be these special values:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*CURLIB</em></td>
<td align="left" valign="top">The job's current library</td>
</tr>
<tr>
<td align="left" valign="top"><em>*LIBL</em></td>
<td align="left" valign="top">The library list</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Export name</strong></dt>
<dd>INPUT; CHAR(*)
<p>A null terminated string containing the name of the exported identifier. The
name is matched exactly, without CCSID conversion or folding to uppercase.</p>
</dd>
<dt><strong>Return Value Format</strong></dt>
<dd>INPUT; BINARY(4)
<p>The format of the returned data.</p>
<p>This value must be one of the following:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">The procedure does not return a value. The
"Return Value" parameter is ignored.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">The procedure returns an integer. The "Return
Value" parameter should address a location to receive a BINARY(4) value.</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td align="left" valign="top">The procedure returns a pointer. The "Return
Value" parameter should address a location to receive a 16 byte pointer.</td>
</tr>
<tr>
<td align="left" valign="top"><em>3</em></td>
<td align="left" valign="top">The procedure returns an integer and the "errno"
return value set by many program calls. The "Return Value" parameter should
address a location to receive two BINARY(4) values. The first is the four byte
return value, and the second is the four byte errno value.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Parameter Formats</strong></dt>
<dd>INPUT; ARRAY(*) of BINARY(4)
<p>The format of the parameters. This length of this array is specified in the
"Number of parameters" value.</p>
<p>Each array entry should be one of the following:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">The parameter is a BINARY(4) argument to be
passed to the procedure by value.</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td align="left" valign="top">The parameter is a pointer value.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Number of parameters</strong></dt>
<dd>INPUT; BINARY(4)
<p>The number of parameters that will be passed to the procedure. Up to seven
parameters are supported.</p>
</dd>
<dt><strong>Error code</strong></dt>
<dd>I/O; CHAR(*)
<p>The structure in which to return error information. For the format of the
structure, see <a href="../apiref/error.htm#hdrerrcod">Error Code Parameter</a>.</p>
</dd>
</dl>
<br>
<h3>Optional Parameters</h3>
<dl>
<dt><strong>Return value</strong></dt>
<dd>OUTPUT; CHAR(*)
<p>For procedures that return a value, this parameter points to the space to
receive the data.</p>
<p>If this parameter is not passed, or is passed using a null pointer, no value
is returned regardless of the value of the "Return value format" parameter.</p>
</dd>
<dt><strong>Parameter 1</strong></dt>
<dd>I/O; CHAR(*)
<p>The first parameter passed to the procedure. If the corresponding entry in
the parameter format array is a 1, this parameter should address a BINARY(4)
value. If the corresponding entry in the parameter format array is a 2, this
parameter should address the storage being referenced.</p>
<p>If the parameter format array indicates that a parameter should be passed to
the exported procedure in this position, but Parameter 1 is not passed to the
QZRUCLSP API, then zero or a null pointer, depending on the parameter format
array entry, is passed to the procedure.</p>
</dd>
<dt><strong>Parameter 2</strong></dt>
<dd>I/O; CHAR(*)
<p>The second parameter passed to the procedure. If the corresponding entry in
the parameter format array is a 1, this parameter should address a BINARY(4)
value. If the corresponding entry in the parameter format array is a 2, this
parameter should address the storage being referenced.</p>
<p>If the parameter format array indicates that a parameter should be passed to
the exported procedure in this position, but Parameter 2 is not passed to the
QZRUCLSP API, then zero or a null pointer, depending on the parameter format
array entry, is passed to the procedure.</p>
</dd>
<dt><strong>Parameter 3</strong></dt>
<dd>I/O; CHAR(*)
<p>The third parameter passed to the procedure. If the corresponding entry in
the parameter format array is a 1, this parameter should address a BINARY(4)
value. If the corresponding entry in the parameter format array is a 2, this
parameter should address the storage being referenced.</p>
<p>If the parameter format array indicates that a parameter should be passed to
the exported procedure in this position, but Parameter 3 is not passed to the
QZRUCLSP API, then zero or a null pointer, depending on the parameter format
array entry, is passed to the procedure.</p>
</dd>
<dt><strong>Parameter 4</strong></dt>
<dd>I/O; CHAR(*)
<p>The fourth parameter passed to the procedure. If the corresponding entry in
the parameter format array is a 1, this parameter should address a BINARY(4)
value. If the corresponding entry in the parameter format array is a 2, this
parameter should address the storage being referenced.</p>
<p>If the parameter format array indicates that a parameter should be passed to
the exported procedure in this position, but Parameter 4 is not passed to the
QZRUCLSP API, then zero or a null pointer, depending on the parameter format
array entry, is passed to the procedure.</p>
</dd>
<dt><strong>Parameter 5</strong></dt>
<dd>I/O; CHAR(*)
<p>The fifth parameter passed to the procedure. If the corresponding entry in
the parameter format array is a 1, this parameter should address a BINARY(4)
value. If the corresponding entry in the parameter format array is a 2, this
parameter should address the storage being referenced.</p>
<p>If the parameter format array indicates that a parameter should be passed to
the exported procedure in this position, but Parameter 5 is not passed to the
QZRUCLSP API, then zero or a null pointer, depending on the parameter format
array entry, is passed to the procedure.</p>
</dd>
<dt><strong>Parameter 6</strong></dt>
<dd>I/O; CHAR(*)
<p>The sixth parameter passed to the procedure. If the corresponding entry in
the parameter format array is a 1, this parameter should address a BINARY(4)
value. If the corresponding entry in the parameter format array is a 2, this
parameter should address the storage being referenced.</p>
<p>If the parameter format array indicates that a parameter should be passed to
the exported procedure in this position, but Parameter 6 is not passed to the
QZRUCLSP API, then zero or a null pointer, depending on the parameter format
array entry, is passed to the procedure.</p>
</dd>
<dt><strong>Parameter 7</strong></dt>
<dd>I/O; CHAR(*)
<p>The seventh parameter passed to the procedure. If the corresponding entry in
the parameter format array is a 1, this parameter should address a BINARY(4)
value. If the corresponding entry in the parameter format array is a 2, this
parameter should address the storage being referenced.</p>
<p>If the parameter format array indicates that a parameter should be passed to
the exported procedure in this position, but Parameter 7 is not passed to the
QZRUCLSP API, then zero or a null pointer, depending on the parameter format
array entry, is passed to the procedure.</p>
</dd>
</dl>
<br>
<h3>Usage Notes</h3>
<p>Since this API is implemented as a program, it adds an additional control
boundary between the caller and the service program procedure.</p>
<p>Any exceptions generated by the service program procedure are either
returned in the error code structure, if provided, or resignalled to the
caller.</p>
<br>
<h3>Error Messages</h3>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<th align="left" valign="top">Message ID</th>
<th align="left" valign="top">Error Message Text</th>
</tr>
<tr>
<td width="15%" valign="top">CPF24B4 E</td>
<td width="85%" valign="top">Severe error while addressing parameter list.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C1D E</td>
<td align="left" valign="top">Length specified in parameter &amp;1 not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C1E E</td>
<td align="left" valign="top">Required parameter &amp;1 omitted.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C24 E</td>
<td align="left" valign="top">Length of the receiver variable is not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C3A E</td>
<td align="left" valign="top">Value for parameter &amp;2 for API &amp;1 not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C90 E</td>
<td align="left" valign="top">Literal value cannot be changed.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3CF1 E</td>
<td align="left" valign="top">Error code parameter not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3CF2 E</td>
<td align="left" valign="top">Error(s) occurred during running of &amp;1
API.</td>
</tr>
<tr>
<td align="left" valign="top">MCH3402 E</td>
<td align="left" valign="top">The argument being tested is not an address.</td>
</tr>
<tr>
<td align="left" valign="top">MCH4421 E</td>
<td align="left" valign="top">At least one field in the allocation strategy is
not valid.</td>
</tr>
<tr>
<td align="left" valign="top">MCH4422 E</td>
<td align="left" valign="top">&amp;1 cannot be called in the default activation
group.</td>
</tr>
<tr>
<td align="left" valign="top">MCH4430 E</td>
<td align="left" valign="top">The exit priority value provided for &amp;1 is
not valid.</td>
</tr>
</table>
<br>
<br>
<h3>Example</h3>
<p>The following is an example of a program calling the <strong>
Qp0lGetAttr()</strong> API. That API takes the following parameters:</p>
<pre>
int Qp0lGetAttr
(Qlg_Path_Name_T *<em>Path_Name</em>,
Qp0l_AttrTypes_List_t *<em>Attr_Array_ptr</em>,
char *<em>Buffer_ptr</em>,
uint <em>Buffer_Size_Provided</em>,
uint *<em>Buffer_Size_Needed_ptr</em>,
uint *<em>Num_Bytes_Returned_ptr</em>,
uint <em>Follow_Symlnk, ...</em>);
</pre>
<br>
<br>
<p>The procedure returns an integer, and its parameters are pointer, pointer,
pointer, integer, pointer, pointer, integer. The parameter format array for
calling this procedure is 2, 2, 2, 1, 2, 2, 1.</p>
<pre>
#include &lt;QZRUCLSP.H&gt;
int main(int argc, char **argv)
{
int rc; /* return code */
struct {
Qlg_Path_Name_T lg;
char *path;
} lname; /* the path name parameter */
int attrreq[2]; /* the attributes requested */
char buffer[32]; /* returned information */
int needed; /* bytes needed */
int returned; /* bytes returned */
int parm_format[7] = {2, 2, 2, 1, 2, 2, 1};
...
QZRUCLSP("QP0LLIB2 QSYS ", /* SRVPGM */
"Qp0lGetAttr", /* Procedure */
1, /* Return integer */
parm_format, /* parm formats */
7, /* Seven parms */
NULL, /* error code */
&amp;rc, /* return value */
&amp;lpath, /* pointer */
attrreq, /* pointer */
buffer, /* pointer */
sizeof(buffer), /* integer */
&amp;needed, /* pointer */
&amp;returned, /* pointer */
0); /* integer */
...
}
</pre>
<br>
<hr>
API introduced: V4R4
<hr>
<center>
<table cellpadding="2" cellspacing="2">
<tr align="center">
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
"pgm1.htm">Program and CL Command APIs</a> | <a href="aplist.htm">APIs by
category</a></td>
</tr>
</table>
</center>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink