Retrieve Program Associated Space (QCLRPGAS) API
Required Parameter Group:
| 1 | Output data buffer | Output | Char(*) |
| 2 | Length of output data buffer | Input | Binary(4) |
| 3 | Qualified program name | Input | Char(20) |
| 4 | Call stack counter | Input | Binary(4) |
| 5 | Data handle | Input | Char(16) |
| 6 | Length of data available | Output | Binary(4) |
| 7 | Error code | I/O | Char(*) |
Default Public Authority: *EXCLUDE
Threadsafe: No
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
| Message ID | Error Message Text |
|---|---|
| CPF0301 E | Length of data buffer is not valid. |
| CPF0302 E | Value for call stack counter not valid. |
| CPF0304 E | Operation not allowed for program &1 in library &2. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF8100 E | All CPF81xx messages could be returned. xx is from 01 to FF. |
| CPF9803 E | Cannot allocate object &2 in library &3. |
| CPF9807 E | One or more libraries in library list deleted. |
| CPF9808 E | Cannot allocate one or more libraries on library list. |
| CPF9810 E | Library &1 not found. |
| CPF9811 E | Program &1 in library &2 not found. |
| CPF9820 E | Not authorized to use library &1. |
| CPF9821 E | Not authorized to program &1 in library &2. |
| CPF9830 E | Cannot assign library &1. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V2R3
[ Back to top | Program and CL Command APIs | APIs by category ]