Call Service Program Procedure (QZRUCLSP) API

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".

Authorities and Locks

Service Program Authority

*EXECUTE

Service Program Library Authority

*EXECUTE

Service Program Lock

*SHRRD

Required Parameter Group

Qualified service program name

INPUT; CHAR(20)

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

Export name

INPUT; CHAR(*)

A null terminated string containing the name of the exported identifier. The name is matched exactly, without CCSID conversion or folding to uppercase.

Return Value Format

INPUT; BINARY(4)

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.

Parameter Formats

INPUT; ARRAY(*) of BINARY(4)

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.

Number of parameters

INPUT; BINARY(4)

The number of parameters that will be passed to the procedure. Up to seven parameters are supported.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

Optional Parameters

Return value

OUTPUT; CHAR(*)

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.

Parameter 1

I/O; CHAR(*)

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.

Parameter 2

I/O; CHAR(*)

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.

Parameter 3

I/O; CHAR(*)

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.

Parameter 4

I/O; CHAR(*)

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.

Parameter 5

I/O; CHAR(*)

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.

Parameter 6

I/O; CHAR(*)

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.

Parameter 7

I/O; CHAR(*)

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.

Usage Notes

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.

Error Messages

Example

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        */

   ...
}