Call Service Program Procedure (QZRUCLSP) API

Required Parameter Group:

Qualified service program name

Input

Char(20)

Export Name

Input

Char(*)

Return Value Format

Input

Binary(4)

Parameter Formats

Input

Array(*) of Binary(4)

Number of Parameters

Input

Binary(4)

Error code

I/O

CHAR(*)

Optional Parameters:

Return Value

Output

Char(*)

Parameter 1

I/O

Char(*)

Parameter 2

I/O

Char(*)

Parameter 3

I/O

Char(*)

...

253

Parameter 246

I/O

Char(*)

254

Parameter 247

I/O

Char(*)

255

Parameter 248

I/O

Char(*)

Default Public Authority: *USE

Threadsafe: No

The Call Service Program Procedure (QZRUCLSP) API allows an unbound call to an ILE procedure exported by a service program. Start of change The exported procedure may have up to 248 parameters and return a value. End of change

The name of the service program, and the name of the exported procedure are passed in as parameters. This API runs in the caller's 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 Start of change that contains the exported procedure to be called. End of change . 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:

The procedure does not return a value. The "Return Value" parameter is ignored.

The procedure returns an integer. The "Return Value" parameter should address a location to receive a BINARY(4) value.

The procedure returns a pointer. The "Return Value" parameter should address a location to receive a 16 byte pointer.

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. The length of this array is specified in the "Number of parameters" value.

Each array entry should be one of the following:

The parameter is a BINARY(4) argument to be passed to the procedure by value.

The parameter is a pointer value.

Start of change If the number of parameters being passed to the exported procedure is less than or equal to 7, this API supports passing a BINARY(4) or pointer value as the argument type. Therefore, the parameter formats array must be passed to the QZRUCLSP API so it knows how to handle each parameter.

However, if the number of parameters being passed to the exported procedure is between 8 and 248, inclusive, then all parameters are required to be passed as pointer values. In that case, the parameter formats array is not used, and NULL can be passed. End of change

Number of parameters

INPUT; BINARY(4)

The number of parameters that will be passed to the procedure. Up to Start of change 248 End of change parameters are supported.

Start of change If seven or less parameters are passed to the procedure, a parameter formats array indicates if each parameter is BINARY(4) or pointer. If more than seven parameters are passed, each parameter is assumed to be a pointer. See Parameter Formats. End of change

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 through Parameter 7

I/O; CHAR(*)

Start of change The first through the seventh parameters passed to the procedure.

If the number of parameters passed to the procedure is seven or less, the corresponding entry in the parameter format array indicates how this parameter should be passed. End of change If the corresponding entry is a 1, the parameter should address a BINARY(4) value. If the corresponding entry is a 2, the parameter should address the storage being referenced. If the parameter format array indicates that any of these parameters should be passed to the exported procedure, but the corresponding parameter 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.

Start of change If the number of parameters passed to the procedure is greater than seven, each parameter is considered a pointer parameter and should address the storage being referenced. If the corresponding parameter is not passed to the QZRUCLSP API, then a null pointer is passed to the procedure. End of change

Parameter 8 through Parameter 248

I/O; CHAR(*)

Start of change The eigth through the 248^th parameters passed to the procedure.

Each of these parameters is considered a pointer parameter and should address the storage being referenced. If the corresponding parameter is not passed to the QZRUCLSP API, then a null pointer is passed to the procedure. End of change

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

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.

Example with Seven Parameters

The following is an example of a program calling the Qp0lGetAttr() API. Start of change Since there are less than or equal to seven parameters, a parameter formats array is required to indicate how each parameter should be passed. End of change The Qp0lGetAttr() 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        */

   ...
}

Example with Eight Parameters

The following is an example of a program calling a service program's exported procedure that returns a BINARY(4) that is the sum of all of its parameters. Since there are greater than seven parameters, a parameter formats array is not required since each parameter will be considered to be a pointer value. Since each parameter is a pointer value, the API takes the following parameters, all of which are pointers to integers:

int Sum
  (int  *p1,
   int  *p2,
   int  *p3,
   int  *p4,
   int  *p5,
   int  *p6,
   int  *p7,
   int  *p8);

The procedure returns an integer, and its parameters are assumed to be pointers since there are more than seven parameters; therefore, NULL can be passed in place of the parameter formats array.

#include <QZRUCLSP.H>

int main(int argc, char **argv)
{
   int sum;         /* the sum returned          */
   int a=1, b=2, c=3, d=4, e=5, f=6, g=7, h=8;
                    /* these parms get summed    */

   ...

   QZRUCLSP("MATH      EXAMPLE   ", /* SRVPGM         */
            "Sum",                  /* Procedure      */
            1,                      /* Return integer */
            NULL,                   /* parm formats   */
            8,                      /* Eight parms    */
            NULL,                   /* error code     */
            &sum,                   /* return value   */
	    &a,                     /* pointer        */
            &b,                     /* pointer        */
            &c,                     /* pointer        */
            &d,                     /* pointer        */
            &e,                     /* pointer        */
            &f,                     /* pointer        */
            &g,                     /* pointer        */
            &h);                    /* pointer        */

   ...
}

After the call to QZRUCLSP, the variable sum will hold the value of 36. End of change

API introduced: V4R4

[ Back to top | Program and CL Command APIs | APIs by category ]