Retrieve User Index Entries (QUSRTVUI) API


  Required Parameter Group:


  Default Public Authority: *USE

  Threadsafe: Yes

The Retrieve User Index Entries (QUSRTVUI) API retrieves user index entries that match the criteria specified on the search criteria parameter.

The entries are always returned starting with the entry that is closest to or equal to the search criteria parameter and then proceeding away from the search criteria. The number of entries returned parameter will never exceed the value specified in the maximum number of entries parameter. Each entry retrieved from the user index is based on the binary value of the search criteria parameter. No other collating sequence is supported.

Every entry retrieved causes the number of retrieve operations to be incremented by 1.

The QSYS2.USER_INDEX_ENTRIES table function can be used as an alternative to this API. See USER_INDEX_ENTRIES table function for more information.


Authorities and Locks

User Index Library Authority
*EXECUTE
User Index Authority
*USE
User Index Lock
*SHRUPD

Required Parameter Group

Receiver variable
OUTPUT; CHAR(*)

The variable that is to receive the information requested. You can specify the size of this 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.

Use the entry lengths and entry offsets parameter to parse through this parameter. If the number of entries returned parameter is 0, then only the bytes available and the bytes provided have been changed.

To determine if all the entries are valid in the receiver variable, compare the bytes returned and bytes available fields. If the bytes returned are less than the bytes available, your receiver variable is not large enough to hold all the entries that match the search criteria parameter. While processing the entries, you need to make sure that both:

  • Your current offset in the receiver variable plus the entry offset is less than the length of the receiver variable
  • Your current offset in the receiver variable plus the entry offset plus the entry length is less than the length of the receiver variable.

The size of the receiver variable parameter should be greater than or equal to:

 8 + (the maximum number of entries parameter
       * the maximum entry length)

The maximum entry length was defined when the index was created. It can be obtained by using the Retrieve User Index Attributes (QUSRUIAT) API.

Refer to the IDXE0100 Format for the layout of this parameter.

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.

Entry lengths and entry offsets
OUTPUT; ARRAY(*) of CHAR(8)

A data structure containing entry lengths and entry offsets for all entries found that met the search criteria. An entry length and entry offset exist for every entry returned in the receiver variable. These entry lengths and entry offsets are used to parse through the receiver variable.

The size of the entry lengths and entry offsets parameter should be at least:

 8 + (the maximum number of entries parameter * 8)

You must provide enough space in both the receiver variable and the entry lengths and entry offsets parameter for this API to return this information to you. You will not receive complete information in the following two situations.

  • You provide enough space in the receiver variable parameter for the API to return all index entries, but there is not enough space in the entry lengths and entry offset parameter to return the lengths and offsets for all entries. You will be unable to parse through all of the entries in the receiver variable parameter. Check the bytes returned and bytes available fields in the entry lengths and entry offsets parameter to ensure that the information is complete.
  • You provide enough space in the entry lengths and entry offsets parameter to return all lengths and offsets, but there is not enough space in the receiver variable parameter to return all index entries retrieved. Some of the entry lengths and entry offsets will not be valid; they will refer to index entries that could not be returned to you. Check the bytes returned and bytes available fields in the receiver variable parameter to ensure that the information is complete.

See the Format for Entry Lengths and Entry Offsets for details about the data structure.

Length of entry lengths and entry offsets
INPUT; BINARY(4)

The length of the entry lengths and entry offsets parameter. If the length is longer than the entry lengths and entry offsets parameter, the results may not be predictable. The minimum length is 8.

If the receiver variable cannot hold all the entries that satisfy the search criteria:

  • The entries are truncated.
  • Not all the information in the entry lengths and entry offsets parameter is valid.
Number of entries returned
OUTPUT; BINARY(4)

The total number of index entries found that satisfy the search criteria. If this field is 0, no entries satisfied the search criteria. This value can never be greater than the maximum number of entries parameter.

Returned library name
OUTPUT; CHAR(10)

The name of the library that contains the user index from which the entries were successfully retrieved. This parameter is not set if an error occurs.

Qualified user index name
INPUT; CHAR(20)

The user index for which you want to retrieve information, and the library in which it is located. The first 10 characters contain the user index name, and the second 10 characters contain the library name.

You can use these special values for the library name:


Format
INPUT; CHAR(8)

The format of the receiver variable.

The format name supported is:

Refer to IDXE0100 Format for details about the format.

Maximum number of entries
INPUT; BINARY(4)

The maximum number of index entries to be returned that match the search criteria. Valid values are 1 through 4095.

Search type
INPUT; BINARY(4)

The type of search that is to be performed.

Valid values are:


Search criteria
INPUT; CHAR(*)

The criteria used to find matches in the user index.

If the search type is 8 (between), both search elements must have the same length. When the search type is 8 (between), this parameter contains two search elements. The first element is considered the starting element, and the second element is the ending element.

This parameter is ignored when the search type parameter is 6 (first) or 7 (last).

Length of search criteria
INPUT; BINARY(4)

The length of the search criteria that is to be used. This parameter is ignored when the search type is 6 (first) or 7 (last).

If the search type is 8 (between), this parameter specifies the length of the first element. The second element must have the same length as the first element. Valid values are 1-2000, depending on how the user index was created.

For a fixed and keyed user index, the length of the search criteria:

  • Can be greater than the length of the key
  • Must be less than or equal to the entry length

Search criteria offset
INPUT; BINARY(4)

The offset of the second search element from the beginning of the search criteria parameter. This parameter is ignored unless the search type is 8 (between).

Error code
I/O; CHAR(*)

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


Format for Entry Lengths and Entry Offsets

The following information is returned in the entry lengths and entry offsets parameter. The information is needed to parse through the receiver variable. For detailed descriptions of the fields in the table, see Field Descriptions.



IDXE0100 Format

The following index information is returned for the IDXE0100 format in the receiver variable parameter. For detailed descriptions of the fields in the table, see Field Descriptions.



Field Descriptions

Bytes available. The length of all data available to return. All available data is returned if enough space is provided.

Bytes returned. The length of the data actually returned.

Entry length. The length of the entry retrieved from the index. Valid values are 1-2000, depending on how the user index was created.

Entry offset. The number of bytes from the beginning of the immediately preceding entry to the first byte of the entry returned. For the first entry, the offset is the number of bytes from the beginning of the receiver variable to the first byte of the first entry.

Entry 1-n. All entries that satisfy the search criteria (up to the maximum number of entries parameter) are returned. User indexes are created to contain only scalar data, which results in the index entries being contiguous. Use the entry length and entry offset values to parse this field.

This field is repeated by the value in the number of entries returned parameter if the receiver variable is large enough to hold all of the entries found.


Error Messages


API introduced: V2R3

[ Back to top | Object APIs | APIs by category ]