| 1 | Qualified service program name | Input | Char(20) |
| 2 | Export Name | Input | Char(*) |
| 3 | Return Value Format | Input | Binary(4) |
| 4 | Parameter Formats | Input | Array(*) of Binary(4) |
| 5 | Number of Parameters | Input | Binary(4) |
| 6 | Error code | I/O | CHAR(*) |
| 7 | Return Value | Output | Char(*) |
| 8 | Parameter 1 | I/O | Char(*) |
| 9 | Parameter 2 | I/O | Char(*) |
| 10 | Parameter 3 | I/O | Char(*) |
| 11 | Parameter 4 | I/O | Char(*) |
| 12 | Parameter 5 | I/O | Char(*) |
| 13 | Parameter 6 | I/O | Char(*) |
| 14 | Parameter 7 | I/O | Char(*) |
The Call Service Program Procedure (QZRUCLSP) API allows an unbound call to an ILE procedure exported by a service program.
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.
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.
All of the parameter values given to this API to be subsequently passed to the procedure are passed by reference.
This API does not support calling procedures that have been defined using "#pragma argopt".
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.
The library name can be these special values:
| *CURLIB | The job's current library |
| *LIBL | The library list |
A null terminated string containing the name of the exported identifier. The name is matched exactly, without CCSID conversion or folding to uppercase.
The format of the returned data.
This value must be one of the following:
| 0 | The procedure does not return a value. The "Return Value" parameter is ignored. |
| 1 | The procedure returns an integer. The "Return Value" parameter should address a location to receive a BINARY(4) value. |
| 2 | The procedure returns a pointer. The "Return Value" parameter should address a location to receive a 16 byte pointer. |
| 3 | 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. |
The format of the parameters. This length of this array is specified in the "Number of parameters" value.
Each array entry should be one of the following:
| 1 | The parameter is a BINARY(4) argument to be passed to the procedure by value. |
| 2 | The parameter is a pointer value. |
The number of parameters that will be passed to the procedure. Up to seven parameters are supported.
The structure in which to return error information. For the format of the structure, see Error code parameter.
For procedures that return a value, this parameter points to the space to receive the data.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Since this API is implemented as a program, it adds an additional control boundary between the caller and the service program procedure.
Any exceptions generated by the service program procedure are either returned in the error code structure, if provided, or resignalled to the caller.
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C1D E | Length specified in parameter &1 not valid. |
| CPF3C1E E | Required parameter &1 omitted. |
| CPF3C24 E | Length of the receiver variable is not valid. |
| CPF3C3A E | Value for parameter &2 for API &1 not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| MCH3402 E | The argument being tested is not an address. |
| MCH4421 E | At least one field in the allocation strategy is not valid. |
| MCH4422 E | &1 cannot be called in the default activation group. |
| MCH4430 E | The exit priority value provided for &1 is not valid. |
The following is an example of a program calling the Qp0lGetAttr() API. That API takes the following parameters:
int Qp0lGetAttr (Qlg_Path_Name_T *Path_Name, Qp0l_AttrTypes_List_t *Attr_Array_ptr, char *Buffer_ptr, uint Buffer_Size_Provided, uint *Buffer_Size_Needed_ptr, uint *Num_Bytes_Returned_ptr, uint Follow_Symlnk, ...);
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.
#include <QZRUCLSP.H>
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 */
&rc, /* return value */
&lpath, /* pointer */
attrreq, /* pointer */
buffer, /* pointer */
sizeof(buffer), /* integer */
&needed, /* pointer */
&returned, /* pointer */
0); /* integer */
...
}
[ Back to top | Program and CL Command APIs | APIs by category ]