Open List of Validation List Entries (QSYOLVLE) API
Required Parameter Group:
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | List information | Output | Char(80) |
| 4 | Number of records to return | Input | Binary(4) |
| 5 | Format name | Input | Char(8) |
| 6 | Qualified validation list name | Input | Char(20) |
| 7 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: No
The Open List of Validation List Entries (QSYOLVLE) API returns a list of validation list entries in a validation list object. Upon successful completion of this API, a handle is returned in the list information parameter. You may use this handle on subsequent calls to the following APIs:
- Get List Entries (QGYGTLE)
- Find List Entry (QGYFNDE)
- Close List (QGYCLST)
Authorities and Locks
- Authority to Validation List
- *USE
- Authority to Validation List Library
- *EXECUTE
Required Parameter Group
- Receiver variable
- OUTPUT; CHAR(*)
The receiver variable that receives the information requested. You can specify the size of the area to be smaller than the format requested as long as you specify the length parameter correctly. As a result, the API returns only the data that the area can hold.
- 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 are not predictable.
- List Information
- OUTPUT; CHAR(80)
Information about the list that is created by this program. See Format of List information for a description of the layout of this parameter.
- Number of records to return
- INPUT; BINARY(4)
The number of records in the list to put into the receiver variable. Possible values follow:
-1 The entire list is built synchronously. 0 The entire list is built asynchronously in a server job. Positive number of records At least that many records will be built synchronously and the remainder will be built asynchronously in a server job.
- Format name
- INPUT; CHAR(8)
The name of the format that is used to return information about the validation list entries.
You can specify these formats:
VLDE0100 The order and format of the data that is returned in the receiver variable for each validation list entry in the list.
- Qualified validation list name
- INPUT; CHAR(20)
The qualified object name of the validation list that contains the entries to return. The first 10 characters specify the validation list name, and the second 10 characters specify the library. You can use these special values for the library name:
*CURLIB The current library is used to locate the validation list. If there is no current library, QGPL (general purpose library) is used. *LIBL The library list is used to locate the validation list.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Format of List information
For detailed descriptions of the fields in the tables, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Total records |
| 4 | 4 | BINARY(4) | Records returned |
| 8 | 8 | CHAR(4) | Request handle |
| 12 | C | BINARY(4) | Record length |
| 16 | 10 | CHAR(1) | Information complete indicator |
| 17 | 11 | CHAR(13) | Date and time created |
| 30 | 1E | CHAR(1) | List status indicator |
| 31 | 1F | CHAR(1) | Reserved |
| 32 | 20 | BINARY(4) | Length of information returned |
| 36 | 24 | BINARY(4) | First record in buffer |
| 40 | 28 | CHAR(40) | Reserved |
Field Descriptions
Date and time created. The date and time when the list was created. The 13 characters are:
| 1 | Century, where 0 indicates years 19xx and 1 indicates years 20xx. |
| 2-7 | The date, in YYMMDD (year, month, and day) format. |
| 8-13 | The time of day, in HHMMSS (hours, minutes, and seconds) format. |
First record in buffer. The number of the first record in the receiver variable.
Information complete indicator. Whether all information that was requested has been supplied.
| I | Incomplete information. An interruption causes the list to contain incomplete information about a buffer or buffers. |
| P | Partial and accurate information. Partial information is returned when the maximum space was used and not all of the buffers requested were read. |
| C | Complete and accurate information. All the buffers requested are read and returned. |
Length of information returned. The size in bytes of the information returned in the receiver variable.
List status indicator. The status of building the list. Possible values follow:
| 0 | The list building is pending. |
| 1 | The list is in the process of being built. |
| 2 | The list has been completely built. |
| 3 | An error occurred when building the list. An error will be signalled to the caller of the QGYGTLE API. |
| 4 | The list is primed and ready to be built. |
Record length. The length of each record of information returned. This value will be set to 0 because the record lengths are variable. You can obtain the length of individual records from the records themselves.
Records returned. The number of records returned in the receiver variable.
This is the smallest of the following three values:
- The number of records that fit into the receiver variable.
- The number of records in the list.
- The number of records that are requested.
Request handle. The handle of the request that can be used for subsequent requests of information from the list. The handle is valid until the Close List (QGYCLST) API is called to close the list, or until the job ends.
Note: This field should be treated as a hexadecimal field. It should not be converted from one CCSID to another, for example, EBCDIC to ASCII, because doing so could result in an unusable value.
Reserved. An ignored field.
Total records. The total number of records available in the
list.
VLDE0100 Format
The following table describes the order and format of the data that is
returned in the receiver variable for each validation list entry in the list.
For detailed descriptions of the fields in the table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of entry |
| 4 | 4 | BINARY(4) | Displacement to entry ID |
| 8 | 8 | BINARY(4) | Length of entry ID |
| 12 | C | BINARY(4) | CCSID of entry ID |
| 16 | 10 | BINARY(4) | Displacement to encrypted data |
| 20 | 14 | BINARY(4) | Length of encrypted data |
| 24 | 18 | BINARY(4) | CCSID of encrypted data |
| 28 | 1C | BINARY(4) | Displacement to entry data |
| 32 | 20 | BINARY(4) | Length of entry data |
| 36 | 24 | BINARY(4) | CCSID of entry data |
| CHAR(*) | Entry ID | ||
| CHAR(*) | Encrypted data | ||
| CHAR(*) | Entry data | ||
Field Descriptions
CCSID of encrypted data. The CCSID of the encrypted data that was specified when the validation list entry was added or changed.
CCSID of entry data. The CCSID of the entry data that was specified when the validation list entry was added or changed.
CCSID of entry ID. The CCSID of the entry ID that was specified when the validation list entry was added.
Displacement to encrypted data. The displacement in the entry to the start of the encrypted data.
Displacement to entry data. The displacement in the entry to the start of the entry data.
Displacement to entry ID. The displacement in the entry to the start of the entry ID.
Encrypted data. The encrypted data associated with the validation list entry. This data is only returned if the entry specifies that the encrypted data is two way encrypted, the QRETSVRSEC system value is '1', and the user has *USE, *ADD, and *UPD authority to the validation list. If the data is to be returned, it is decrypted and returned in this field.
Entry data. The data associated with the validation list entry.
Entry ID. The entry ID for the validation list entry.
Length of encrypted data. The length (in bytes) of the encrypted data. If the data is one-way encrypted, the QRETSVRSEC system value is '0', or the user is not authorized to have the encrypted data returned, this value will be 0.
Length of entry. The length (in bytes) of the current entry. This length can be used to access the next entry.
Length of entry data. The length (in bytes) of the entry data.
Length of entry ID. The length (in bytes) of the entry
ID.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF226B E | Validation list entry does not exist. |
| CPF3C19 E | Error occurred with receiver variable specified. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF9801 E | Object &2 in library &3 not found. |
| CPF9802 E | Not authorized to object &2 in &3. |
| CPF9803 E | Cannot allocate object &2 in library &3. |
| CPF9804 E | Object &2 in library &3 damaged. |
| CPF9821 E | Not authorized to program &1 in library &2. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
| GUI0002 E | &2 is not valid for length of receiver variable. |
| GUI0027 E | &1 is not valid for number of records to return. |
API introduced: V4R2
[ Back to top | Security APIs | APIs by category ]