Retrieve Exit Information (QUSRTVEI, QusRetrieveExitInformation) API
Required Parameter Group:
| 1 | Continuation handle | Input | Char(16) |
| 2 | Receiver variable | Output | Char(*) |
| 3 | Length of receiver variable | Input | Binary(4) |
| 4 | Format name | Input | Char(8) |
| 5 | Exit point name | Input | Char(20) |
| 6 | Exit point format name | Input | Char(8) |
| 7 | Exit program number | Input | Binary(4) |
| 8 | Exit program selection criteria | Input | Char(*) |
| 9 | Error code | I/O | Char(*) |
Service Program Name: QUSRGFA2
Default Public Authority: *USE
Threadsafe: Yes
The Retrieve Exit Information (OPM, QUSRTVEI; ILE, QusRetrieveExitInformation) API retrieves information about one or more exit points and their associated exit programs. This API returns information similar to the Work with Registration Information (WRKREGINF) command.
Authorities and Locks
- API Public Authority
- *USE
- Exit Registration Lock
- *SHRNUP
Required Parameter Group
- Continuation handle
- INPUT; CHAR(16)
The value returned to the user in the receiver variable when only partial exit information is returned. This parameter must be set to blanks on the first call to this API. This parameter is used when more information is available to return than what could fit in the receiver variable. When you specify a continuation handle for this parameter, all other parameters must have the same values as the call to the API that generated the continuation handle. Failure to do so may result in incomplete or inaccurate information.
Entries are only returned in their entirety; the API never returns anything less. If there is not enough space for the entire entry, the continuation handle is set to something other than blanks.
- Receiver variable
- OUTPUT; CHAR(*)
The variable that is to receive the exit information requested.
- Length of receiver variable
- INPUT; BINARY(4)
The length of the receiver variable. If the length is larger than the size of the receiver variable, the results may not be predictable. The minimum length is 8 bytes.
- Format name
- INPUT; CHAR(8)
The format of the exit information to be returned. You must use one of the following format names:
EXTI0100 Exit point information EXTI0200 Basic exit program information EXTI0300 Complete exit program information Refer to EXTI0100 Format, EXTI0200 Format, and EXTI0300 Format for more information.
- Exit point name
- INPUT; CHAR(20)
The name of the exit point for which information is being retrieved. You must use one of the following values.
Note: The specified values in these value descriptions pertain to the exit point format name, exit program number, and exit program selection criteria fields.
*ALL All registered and unregistered exit point names that meet the specified values will be returned. *REGISTERED All registered exit point names that meet the specified values will be returned. *UNREGISTERED All unregistered exit point names that meet the specified values will be returned. generic* All registered and unregistered exit point names that have names beginning with the generic string and meet the specified values will be returned. exit point name The registered or unregistered exit point name that was specified that meets the specified values will be returned.
- Exit point format name
- INPUT; CHAR(8)
The exit point format name associated with an exit point. You must use one of the following values.
Note: The specified values in these value descriptions pertain to the exit point name, exit program number, and exit program selection criteria fields.
*ALL All exit point format names that meet the specified values will be returned. generic* All exit point format names that have names beginning with the generic string and meet the specified values will be returned. exit point format name The exit point format name that was specified that meets the specified values will be returned.
- Exit program number
- INPUT; BINARY(4)
The number of the exit program. If you specify format EXTI0100, this parameter is ignored. You must use one of the following values.
Note: The specified values in these value descriptions pertain to the exit point name, exit point format name, and exit program selection criteria fields.
-1 All exit programs that meet the specified values will be returned. exit program number The exit program number to be returned. The entry must meet the specified values to be returned. The valid range is 1 through 2 147 483 647.
- Exit program selection criteria
- INPUT; CHAR(*)
The selection criteria to be used when selecting which exit programs associated with the exit point are returned. The comparison data is compared against the exit program data. The comparison data and the exit program data to compare it to must be from 1 through 256 characters, and no CCSID normalization is performed. Using characters from the invariant character set for the comparison data is recommended.
For format EXTI0100, this parameter is ignored.
The information must be in the following format:
- Number of selection criteria
- BINARY(4)
- The total number of selection criteria. Specify 0 if no selection criteria are specified. The maximum value for this field is 1.
- Selection criteria array
- CHAR(*)
- The selection criteria. Refer to Format for Exit Program Selection Criteria for more information.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
EXTI0100 Format
The following information is returned for the EXTI0100 format. This format provides information on an exit point. For a detailed description of each field, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | CHAR(16) | Continuation handle |
| 24 | 18 | BINARY(4) | Offset to first exit point entry |
| 28 | 1C | BINARY(4) | Number of exit point entries returned |
| 32 | 20 | BINARY(4) | Length of exit point entry |
| 36 | 24 | CHAR(*) | Reserved |
| Note: Exit point entry information. These fields are repeated for each exit point entry returned. | |||
| CHAR(20) | Exit point name | ||
| CHAR(8) | Exit point format name | ||
| BINARY(4) | Maximum number of exit programs | ||
| BINARY(4) | Current number of exit programs | ||
| CHAR(1) | Allow deregistration | ||
| CHAR(1) | Allow change of exit point controls | ||
| CHAR(1) | Registered exit point | ||
| CHAR(10) | Preprocessing exit program name for adding an exit program | ||
| CHAR(10) | Preprocessing exit program library name for adding an exit program | ||
| CHAR(8) | Preprocessing exit program format name for adding an exit program | ||
| CHAR(10) | Preprocessing exit program name for removing an exit program | ||
| CHAR(10) | Preprocessing exit program library name for removing an exit program | ||
| CHAR(8) | Preprocessing exit program format name for removing an exit program | ||
| CHAR(10) | Preprocessing exit program name for retrieving exit information | ||
| CHAR(10) | Preprocessing exit program library name for retrieving exit information | ||
| CHAR(8) | Preprocessing exit program format name for retrieving exit information | ||
| CHAR(1) | Exit point description indicator | ||
| CHAR(10) | Exit point description message file name | ||
| CHAR(10) | Exit point description message file library name | ||
| CHAR(7) | Exit point description message ID | ||
| CHAR(50) | Exit point text description | ||
| CHAR(*) | Reserved | ||
EXTI0200 Format
The following information is returned for the EXTI0200 format. This format provides basic information on an exit program. The exit programs will be in ascending sequence based on the exit point name, exit point format name, and exit program number. For a detailed description of each field, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | CHAR(16) | Continuation handle |
| 24 | 18 | BINARY(4) | Offset to first exit program entry |
| 28 | 1C | BINARY(4) | Number of exit program entries returned |
| 32 | 20 | BINARY(4) | Length of exit program entry |
| 36 | 24 | CHAR(*) | Reserved |
| Note: Exit program entry information. These fields are repeated for each exit program entry returned. | |||
| BINARY(4) | Offset to next exit program entry | ||
| CHAR(20) | Exit point name | ||
| CHAR(8) | Exit point format name | ||
| CHAR(1) | Registered exit point | ||
| CHAR(1) | Complete entry | ||
| CHAR(2) | Reserved | ||
| BINARY(4) | Exit program number | ||
| CHAR(10) | Exit program name | ||
| CHAR(10) | Exit program library name | ||
| BINARY(4) | Exit program data CCSID | ||
| BINARY(4) | Offset to exit program data | ||
| BINARY(4) | Length of exit program data | ||
| CHAR(1) | Threadsafe | ||
| CHAR(1) | Multithreaded job action | ||
| CHAR(1) | QMLTTHDACN system value | ||
| CHAR(1) | Reserved | ||
| CHAR(*) | Reserved | ||
| Note: Exit program data | |||
| CHAR(*) | Exit program data | ||
EXTI0300 Format
The following information is returned for the EXTI0300 format. This format provides complete information on an exit program. The exit programs will be in ascending sequence based on the exit point name, exit point format name, and exit program number. For a detailed description of each field, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | CHAR(16) | Continuation handle |
| 24 | 18 | BINARY(4) | Offset to first exit program entry |
| 28 | 1C | BINARY(4) | Number of exit program entries returned |
| 32 | 20 | BINARY(4) | Length of exit program entry |
| 36 | 24 | CHAR(*) | Reserved |
| Note: Exit program entry information. These fields are repeated for each exit program entry returned. | |||
| BINARY(4) | Offset to next exit program entry | ||
| CHAR(20) | Exit point name | ||
| CHAR(8) | Exit point format name | ||
| CHAR(1) | Registered exit point | ||
| CHAR(1) | Complete entry | ||
| CHAR(2) | Reserved | ||
| BINARY(4) | Exit program number | ||
| CHAR(10) | Exit program name | ||
| CHAR(10) | Exit program library name | ||
| CHAR(1) | Exit program description indicator | ||
| CHAR(10) | Exit program description message file name | ||
| CHAR(10) | Exit program description message file library name | ||
| CHAR(7) | Exit program description message ID | ||
| CHAR(50) | Exit program text description | ||
| CHAR(2) | Reserved | ||
| BINARY(4) | Exit program data CCSID | ||
| BINARY(4) | Offset to exit program data | ||
| BINARY(4) | Length of exit program data | ||
| CHAR(1) | Threadsafe | ||
| CHAR(1) | Multithreaded job action | ||
| CHAR(1) | QMLTTHDACN system value | ||
| CHAR(1) | Reserved | ||
| CHAR(*) | Reserved | ||
| Note: Exit program data | |||
| CHAR(*) | Exit program data | ||
Field Descriptions
Allow change of exit point controls. Whether the exit point controls can be changed. The possible values follow:
| 0 | The exit point controls cannot be changed. |
| 1 | The exit point controls can be changed. |
Allow deregistration. Whether the exit point can be deregistered. The possible values follow:
| 0 | The exit point cannot be deregistered. |
| 1 | The exit point can be deregistered. |
Bytes available. The number of bytes of data available to be returned. All available data is returned if enough space is provided.
If the continuation handle is set to a value other than blanks, this field contains an approximation of the total bytes available. At a minimum, this field contains the actual number of bytes available.
Bytes returned. The number of bytes of data returned.
Complete entry. Whether the information returned for the exit point is complete and accurate. Incomplete information may occur when an exit point's provider is storing the exit program information instead of having the registration facility store it. The exit point notifies the API that the information it returned to the API is incomplete or inaccurate.
All information for the exit program entry up to this field is complete and accurate. All information for the exit program entry following this field should be ignored.
The possible values follow:
| 0 | The exit point entry information is not complete or accurate. |
| 1 | The exit point entry information is complete and accurate. |
Continuation handle. The handle that is returned when more data is available to return, but the receiver variable is not large enough. The handle indicates the point in the repository that the retrieval stopped. If the handle is used on the next call to the API, the API returns more data starting at the point that the handle indicates. This field is set to blanks when all information is returned.
Current number of exit programs. The current number of exit programs associated with the exit point.
Exit point description indicator. Whether the exit point description is contained in a message file or text. The possible values follow:
| 0 | The exit point description is contained in a message file. |
| 1 | The exit point description is text. |
Exit point description message file name. The name of the message file that contains the exit point description. This field will contain blanks when a text description is provided for the exit point description.
Exit point description message file library name. The name of the library in which the exit point description message file resides. This field will contain blanks when a text description is provided for the exit point description.
Exit point description message ID. The message identifier for the exit point description. This field will contain blanks when a text description is provided for the exit point description.
Exit point format name. The exit point format name associated with the exit point.
Exit point name. The exit point name.
Exit point text description. The text for the exit point description. This field will contain blanks when a message file and message identifier are provided for the exit point description.
Exit program data. The data that is associated with the exit program.
Exit program data CCSID. The coded character set identifier (CCSID) that is used in working with the exit program data.
Exit program description indicator. Whether the exit program description is contained in a message file or text. The possible values follow:
| 0 | The exit program description is contained in a message file. |
| 1 | The exit program description is text. |
Exit program description message file name. The name of the message file that contains the exit program description. This field will contain blanks when a text description is provided for the exit program description.
Exit program description message file library name. The name of the library in which the exit program description message file resides. This field will contain blanks when a text description is provided for the exit program description.
Exit program description message ID. The message identifier for the exit program description. This field will contain blanks when a text description is provided for the exit program description.
Exit program library name. The library in which the exit program resides.
Exit program name. The name of the exit program.
Exit program number. The exit program number associated with the exit program. This number determines the processing sequence of the exit programs associated with the exit point, where the lowest number should be processed first.
Exit program text description. The text for the exit program description. This field will contain blanks when a message file and message identifier are provided for the exit program description.
Length of exit point entry. The length of an exit point entry that is returned. This value should be used in determining the offset to the next exit point entry.
Length of exit program data. The length of the exit program data that is returned.
Length of exit program entry. The length of an exit program entry, not including the exit program data, that is returned.
Maximum number of exit programs. The maximum number of exit programs that the exit point allows.
Multithreaded job action. The action to take when calling an exit program in a multithreaded job. The possible values follow:
| 1 | Run the exit program in the current multithreaded job. |
| 2 | Run the exit program in the current multithreaded job, but send an informational message. CPI3C80 can be used as the informational message. |
| 3 | Do not run the exit program in the current
multithreaded job. Depending on the exit point, do one of the following:
|
Number of exit point entries returned. The number of exit point entries returned. If the receiver variable is not large enough to hold all of the information, this number contains only the number of exit point entries actually returned.
Number of exit program entries returned. The number of exit program entries returned. If the receiver variable is not large enough to hold all of the information, this number contains only the number of exit program entries actually returned.
Offset to exit program data. The offset to the exit program data. The offset is from the beginning of the structure.
Offset to first exit point entry. The offset to the first exit point entry returned. The offset is from the beginning of the structure. If no entries are returned, the offset is set to zero.
Offset to first exit program entry. The offset to the first exit program entry returned. The offset is from the beginning of the structure. If no entries are returned, the offset is set to zero.
Offset to next exit program entry. The offset to the next exit program entry returned. The offset is from the beginning of the structure. If there are no more exit program entries, this value is zero.
Preprocessing exit program format name for adding an exit program. The format name for the Preprocessing Exit Program for Add.
Preprocessing exit program format name for removing an exit program. The format name for the Preprocessing Exit Program for Remove.
Preprocessing exit program format name for retrieving an exit program. The format name for the Preprocessing Exit Program for Retrieve.
Preprocessing exit program library name for adding an exit program. The library in which the Preprocessing Exit Program for Add resides.
Preprocessing exit program library name for removing an exit program. The library in which the Preprocessing Exit Program for Remove resides.
Preprocessing exit program library name for retrieving an exit program. The library in which the Preprocessing Exit Program for Retrieve resides.
Preprocessing exit program name for adding an exit program. The preprocessing exit program name that is called by the registration facility when the Add Exit Program API is called for the exit point.
Preprocessing exit program name for removing an exit program. The preprocessing exit program name that is called by the registration facility when the Remove Exit Program API is called for the exit point.
Preprocessing exit program name for retrieving exit information. The preprocessing exit program name that is called by the registration facility when the Retrieve Exit Information API is called for the exit point.
QMLTTHDACN system value. A flag that indicates whether the QMLTTHDACN system value was used in determining the multithreaded job action.
| 0 | The QMLTTHDACN system value was not used to determine the multithreaded job action. |
| 1 | The QMLTTHDACN system value was used to determine the multithreaded job action. |
Registered exit point. Whether the exit point is registered or unregistered. The possible values follow:
| 0 | The exit point is unregistered. |
| 1 | The exit point is registered. |
Reserved. An ignored field.
Threadsafe. The thread safety status of the exit program entry. The possible values follow:
| 0 | The exit program entry is not threadsafe. |
| 1 | The threadsafe status of the exit program entry is not known. |
| 2 | The exit program entry is threadsafe. |
Format for Exit Program Selection Criteria
This table shows the format for the exit program selection criteria parameter. For a detailed description of each field, see Field Descriptions.
| Type | Field |
|---|---|
| BINARY(4) | Size of criteria entry |
| BINARY(4) | Comparison operator |
| BINARY(4) | Start position in exit program data |
| BINARY(4) | Length of comparison data |
| CHAR(*) | Comparison data |
Field Descriptions
Comparison data. The data to compare to the exit program data.
Comparison operator. The comparison value to be used when comparing the exit program data with the comparison data. The following value can be specified:
| 1 | The comparison data equals the exit program data. |
Length of comparison data. The length of the data to compare to the exit program data. The length of the comparison data must be between 1 and 256.
Size of criteria entry. The size of the selection criteria entry, including this field.
Start position in exit program data. The starting position of the exit program data against which the comparison data is matched. The starting position is based on 0. Valid starting positions are from 0 through 2047.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C19 E | Error occurred with receiver variable specified. |
| CPF3C1E E | Required parameter &1 omitted. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C24 E | Length of the receiver variable is not valid. |
| CPF3C36 E | Number of parameters, &1, entered for this API was not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CD2 E | Exit point name &1 not valid. |
| CPF3CD3 E | Exit point format name &1 not valid. |
| CPF3CD9 E | Requested function cannot be performed at this time. |
| CPF3CDA E | Registration facility repository not available for use. |
| CPF3CDB E | Exit point &1 with format &2 does not exist. |
| CPF3CE1 E | Exit program number &1 not valid. |
| CPF3CE2 E | Continuation handle not valid |
| CPF3CE3 E | Continuation handle no longer valid. |
| CPF3CE4 E | Comparison operator &1 not valid for exit program selection criteria. |
| CPF3CE6 E | Search criteria start position and length exceed boundary. |
| CPF3CE7 E | Number of selection criteria entries not valid. |
| CPF3CE8 E | Start position not valid. |
| CPF3CE9 E | Length of comparison data not valid. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF8100 E | All CPF81xx messages could be returned. xx is from 01 to FF. |
| CPF9802 E | Not authorized to object &2 in &3. |
| CPF9810 E | Library &1 not found. |
| CPF9811 E | Program &1 in library &2 not found. |
| CPF9820 E | Not authorized to use library &1. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V3R1
[ Back to top | Registration Facility APIs | APIs by category ]