Find Validation List Entry (QSYFDVLE) API
Required Parameter Group:
| 1 | Qualified validation list name | Input | Char(20) |
| 2 | Entry ID information | Input | Char(*) |
| 3 | Attribute information | Input | Char(*) |
| 4 | Return entry | Output | Char(1724) |
| 5 | Return attributes | Output | Char(*) |
| 6 | Error Code | I/O | Char(*) |
Service Program Name: QSYVLDL
Default Public Authority: *USE
Threadsafe: Yes
The Find Validation List Entry (QSYFDVLE) API finds an entry in a validation list object and returns it. Also, any attributes associated with the entry can be returned. To find an entry, there must be an exact match in the entry for the value that is specified in the entry ID parameter and the length of the entry ID. For example, an entry ID value of SMITH with a length of 5 would not find an entry where the entry ID is SMITH and the length is 7.
Authorities and Locks
- Validation List Object
- *USE
- Validation List Object Library
- *EXECUTE
Note: If the QsyEncryptData attribute is set to 1, then the user must have *USE, *ADD, and *UPD authorities to the validation list to get the data to be encrypted returned in the encrypted data field.
Required Parameter Group
- Qualified validation list name
- INPUT; CHAR(20)
The qualified object name of the validation list in which to find the entry. 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.
- Entry ID information
- INPUT; CHAR(*)
The format of the entry ID information is as follows. See Field Descriptions for more information.
-
Offset Type Field Dec Hex 0 0 BINARY(4) Length of entry ID 4 4 BINARY(4) CCSID of entry ID 8 8 CHAR(*) Entry ID
- Attribute information
- INPUT; CHAR(*)
The format of the attribute information is as follows. See Field Descriptions for more information.
Offset Type Field Dec Hex 0 0 BINARY(4) Number of attributes 4 4 CHAR(*) Attribute structures
The format of the attribute structure is as follows. See Field Descriptions for more information.
Offset Type Field Dec Hex 0 0 BINARY(4) Length of attribute entry 4 4 BINARY(4) Attribute location 8 8 BINARY(4) Attribute type 12 C BINARY(4) Displacement to attribute ID 16 10 BINARY(4) Length of attribute ID 20 14 BINARY(4) Bytes provided for attribute CHAR(*) Attribute ID
- Return entry
- OUTPUT; CHAR(1724)
The format of the return entry information is as follows. See Field Descriptions for more information.
-
Offset Type Field Dec Hex 0 0 BINARY(4) Length of entry ID 4 4 BINARY(4) CCSID of entry ID 8 8 CHAR(100) Entry ID 108 6C BINARY(4) Length of encrypted data 112 70 BINARY(4) CCSID of encrypted data 116 74 CHAR(600) Encrypted data 716 2CC BINARY(4) Length of data 720 2D0 BINARY(4) CCSID of data 724 2D4 CHAR(1000) Data 1724 6BC CHAR(20) Reserved
- Return attributes
- OUTPUT; CHAR(*)
The format of the return attributes information is as follows. See Field Descriptions for more information.
-
Offset Type Field Dec Hex 0 0 BINARY(4) Length of attribute entry 4 4 BINARY(4) Bytes returned 8 8 BINARY(4) Bytes available 12 C BINARY(4) Length of attribute 16 10 BINARY(4) CCSID of attribute 20 14 CHAR(*) Attribute value
The size of this buffer must be 24 bytes multiplied by the number of attributes, plus the bytes provided in the buffer for each attribute. For example, if you are requesting 2 attributes and providing 8 bytes for one attribute and 5 bytes for the other attribute, you would need a 61-byte buffer. If the buffer is not large enough, the results are unpredictable.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Field Descriptions
Attribute ID. The ID of the attribute. For system-defined attributes, the allowed values are:
| String value | Description |
|---|---|
| QsyEncryptData | This is the attribute that is associated with the data to encrypt. |
| QsyEntryUsage | This is the entry usage information attribute. |
| QsyX509Cert | This is the X.509 certificate attribute for the entry. |
Attribute location. Where the attribute is stored. The allowed value is:
| 0 | The attribute is stored in the validation list object. |
Attribute structures. Zero or more attribute structures that define the attributes that are associated with the entry.
Attribute type. The type of attribute. The allowed value follows:
| 0 | This is a system-defined attribute. |
Attribute value. The value of the returned attribute. If the attribute ID is QsyEncryptData or QsyX509Cert, the data will be in the form of variable length character array. If the attribute ID is QsyEntryUsage, the data will be in the form of Qsy_Rtn_Entry_Usage_Attr_T.
The format of the Qsy_Rtn_Entry_Usage_Attr_T structure is as follows. See Field Descriptions for more information.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(8) | Create date |
| 8 | 8 | CHAR(8) | Last used date |
| 16 | 10 | CHAR(8) | Encrypted data change date |
| 24 | 18 | BINARY(4) | Not valid verify count |
Bytes available. The number of bytes of data that is available to be returned to the user for the current attribute. If all data is returned, bytes available is the same as the number of bytes returned. If the bytes available is 16, then the specified attribute is not defined for this entry.
Bytes provided for attribute. The number of bytes provided in the return attributes buffer for the attribute value. The minimum length is 0. If 0 is specified, the bytes available will indicate if the attribute exists and how many bytes of data are needed to return the attribute.
Bytes returned. The number of bytes of data that is returned to the user for the current attribute. This is the lesser of the number of bytes available to be returned and bytes provided for attribute plus 20.
CCSID of attribute. An integer that represents the CCSID for the attribute. Valid CCSID values are in the range 0 through 65535. This value is the CCSID value that was specified when the attribute was added or changed. If the value is 0, then no CCSID value was stored with the attribute.
CCSID of encrypted data. An integer that represents the CCSID for the encrypted data.
CCSID of data. An integer that represents the CCSID for the data.
CCSID of entry ID. An integer that represents the CCSID for the entry ID. Valid CCSID values are in the range 0 through 65535. This field is not used to find the entry. The value is returned in the return entry.
Create date. The date the entry was added to the validation list, in *DTS (date-time stamp) format.
Data. The data that is stored in the validation list entry.
Displacement to attribute ID. The displacement in the attribute entry to the start of the attribute ID.
Encrypted data. If the QsyEncryptData attribute for this entry is 1 and the QRETSVRSEC system value is '1', then the encrypted data that is stored in the entry will be decrypted and returned in this field. If the QsyEncryptData attribute is 0 or the QRETSVRSEC system value is '0', then the encrypted data cannot be returned and the contents of this field are unpredictable.
Encrypted data change date. The date the encrypted data was last changed, in *DTS (date-time stamp) format.
Entry ID. The data that is used to find the entry in the validation list.
Last used date. The date of the last successful verify, in *DTS (date-time stamp) format.
Length of attribute. The length (in bytes) of the returned attribute value. This value will be less than or equal to the bytes provided for attribute.
Length of attribute entry. The length (in bytes) of the current entry. This length can be used to access the next entry, and must be a multiple of 4.
Length of attribute ID. The number of bytes of data in the attribute ID. The length must be greater than 0.
Length of data. The number of bytes of data that is stored in this validation list entry. Possible values are 0 to 1000.
Length of encrypted data. The number of bytes of encrypted data that is stored in this validation list entry. Possible values are 0 to 600. If the QsyEncryptData attribute is 0 or the QRETSVRSEC system value is '0', then the length will always be 0.
Length of entry ID. The number of bytes of data that is provided as the entry ID. Possible values are 1 through 100.
Not valid verify count. The number of times that incorrect encrypted data has been specified on a verify since the last successful verify.
Number of attributes. The number of attributes to be returned. This value must be greater than or equal to 0. If the value is 0, then no attributes will be returned.
Reserved. This is an ignored field.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPFA0AA E | Error occurred while attempting to obtain space. |
| CPF226B E | Validation list entry does not exist. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3C36 E | Number of parameters, &1, entered for this API was not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| 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. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V4R2
[ Back to top | Security APIs | APIs by category ]