Retrieve Program Associated Space (QCLRPGAS) API

The Retrieve Program Associated Space (QCLRPGAS) API allows you to retrieve information from the associated space of an original program model (OPM), user-state program in the user domain. This API is intended to be used only on programs created by the Create Program (QPRCRTPG) API.

This API is used to retrieve information that was previously stored in the associated space. For example, it can be used by compilers at run time to retrieve information about the compilation process that was previously stored. The associated space of a program object is not a replacement for data areas or user spaces. It is recommended for static data only.

Authorities and Locks

Program Library Authority

*USE

Program Authority

*ALL

Program Lock

*EXCLRD

Required Parameter Group

Output data buffer

OUTPUT; CHAR(*)

The information retrieved from the associated space. This information contains scalar data only. If information that was previously stored contained pointer data, the pointer data was not preserved.

Length of output data buffer

INPUT; BINARY(4)

The length of the output data buffer, in bytes. If this value is larger than the actual size of the output data buffer, the results may not be predictable.

Qualified program name

INPUT; CHAR(20)

The program object for which you want to retrieve data from the associated space. This must be an OPM, user-state program in the user domain. An error is returned if the program is an Integrated Language Environment (ILE) program, or if it is a system-state or system-domain program. The first 10 characters contain the program name, and the second 10 characters contain the library name.

You can use the following special value for the program name:

*	Use a program in the call stack. The call stack counter contains the number of programs up the stack from the calling program to look for the program from which to retrieve data.

You can use these special values for the library name:

*CURLIB	The job's current library
*LIBL	The library list

Call stack counter

INPUT; BINARY(4)

A number greater than zero identifying the location in the call stack for the program if * is specified for the program name. This number is relative to the program that called this API. This parameter is ignored if the program name is not *.

Data handle

INPUT; CHAR(16)

The identifier to retrieve the information from in the associated space. Specify the data handle that was previously used on the Store Program Associated Space (QCLSPGAS) API to store information in the associated space. If no data was previously stored at this data handle, no error is returned. The length of data available parameter will be set to 0 indicating no data was available.

Length of data available

OUTPUT; BINARY(4)

Either the length of the data actually returned or the length of data available.

The possible values follow:

0	No data was previously stored at the data handle specified.
From 1 to the value of the length of output data buffer parameter	The length of information available and successfully returned in the output data buffer.
Greater than the value of the length of output data buffer parameter	The total length of data available. If the output data buffer is too small to hold all of the information available, the information is truncated to fit the available space.

Error code

I/O; CHAR(*)

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

Error Messages