The Retrieve API List Information (RTVLSTIXCL) command works with user spaces that have been formatted by a system List API. RTVLSTIXCL can retrieve information such as the status of the list in the user space, the number of list entries in the user space, etc.

This function is also available with command RTVLSTINF in library VC2XCL. Any use of this alternative command name should be library qualified in case the i operating system were to use this command name in a future release.

Restrictions:

• The user space must have been formatted by a system API of the List family.
• You must have *EXECUTE authority to the library where the user space is located.
• You must have *USE authority to the user space.

Parameters

User space (USRSPC)

Specifies the qualified name of the user space.

This is a required parameter.

Qualifier 1: User space

name

Specify the name of the user space.

Qualifier 2: Library

*LIBL

All libraries in the library list for the current job are searched until the first match is found.

*CURLIB

The current library for the job is searched. If no library is specified as the current library, the QGPL library is searched.

name

Specify the name of the library to search.

Status (STATUS)

Specifies the CL variable to recieve information about the status of the list. The possible values returned are:

• C - Complete and accurate
• I - Incomplete
• P - Partial but accurate

character-value

Specify the name of a CL variable declared as TYPE(*CHAR) LEN(1)

Offset to first entry (OFSENT)

Specifies the CL variable to recieve information about the offset within the user space where the first list entry can be located.

integer

Specify the name of a CL variable declared as TYPE(*INT)

Number of entries (NBRENT)

Specifies the CL variable to recieve information about the number of list entries within the user space.

integer

Specify the name of a CL variable declared as TYPE(*INT)

Size of one entry (SIZENT)

Specifies the CL variable to recieve information about the size of each list entry within the user space. If a value of 0 is returned then each list entry is variable in size. Each list entry in this case will identify its own length.

integer

Specify the name of a CL variable declared as TYPE(*INT)

API creating list (APIUSED)

Specifies the CL variable to recieve information about the name of the API that generated the list found in the user space.

If the list is generated by a *PGM API the first ten bytes of the returned name are the name of the API. If the list is generated by a *SRVPGM API the returned name is the name of the API procedure.

character-value

Specify the name of a CL variable declared as TYPE(*CHAR) LEN(256)

API format used (APIFMT)

Specifies the CL variable to recieve information about the list format used by the API when writing the list entries.

character-value

Specify the name of a CL variable declared as TYPE(*CHAR) LEN(8)

List creation time (LSTCRTTIM)

Specifies the CL variable to recieve information about the date and time the list was generated. The date and time is formatted as CYYMMDDHHMMSS.

character-value

Specify the name of a CL variable declared as TYPE(*CHAR) LEN(13)

Offset to input values (OFSINP)

Specifies the CL variable to recieve information about the offset within the user space where the input parameter section can be located.

integer

Specify the name of a CL variable declared as TYPE(*INT)

Size of input values (SIZINP)

Specifies the CL variable to recieve information about the size of the input parameter section.

integer

Specify the name of a CL variable declared as TYPE(*INT)

Offset to header values (OFSHDR)

Specifies the CL variable to recieve information about the offset within the user space where the header section can be located.

integer

Specify the name of a CL variable declared as TYPE(*INT)

Size of header values (SIZHDR)

Specifies the CL variable to recieve information about the size of the header section.

integer

Specify the name of a CL variable declared as TYPE(*INT)

User data (USRDTA)

Specifies the CL variable to recieve user information stored in the user space. The format of this data is entirely under the control of the user.

character-value

Specify the name of a CL variable declared as TYPE(*CHAR) LEN(64)f

Examples for RTVLSTIXCL

Example 1: Retrieve the Status and Number of Entries in a List

Dcl        Var(&Status)    Type(*Char) Len(1)
Dcl        Var(&NbrEnt)    Type(*Int)
Dcl        Var(&NbrEntChr) Type(*Char) Len(10)
CrtUSXCL   UsrSpc(QTEMP/FILELIST)
Call       Pgm(QUSLOBJ) +
             Parm('FILELIST  QTEMP     ' +
                  OBJL0100               +
                  '*ALL      QTEMP     ' +
                  *FILE)
RtvLstIXCL UsrSpc(QTEMP/FILELIST) Status(&Status) +
             NbrEnt(&NbrEnt)
Select
   When    Cond((&Status = C) *Or (&Status = P)) Then(Do)
           ChgVar Var(&NbrEntChr) Value(&NbrEnt)
           SndPgmMsg Msg( +
               &NbrEntChr *BCat +
               'files found with a list status of' +
               *BCat &Status)
           EndDo
   OtherWise Cmd(SndPgmMsg Msg( +
               'Error found, list status is' +
               *BCat &Status))
EndSelect

This example runs the List Objects (QUSLOBJ) API to generate a list of all *FILE objects in the QTEMP library. The RTVLSTIXCL command is used to retrieve the status of the list and the number of list entries. This information is sent as a message to the user.

Error messages for RTVLSTIXCL

*ESCAPE Messages

XCL500D

Function did not complete. See previously listed messages related to possible user errors.

XCL501C

User space not formatted by system List API.

XCL9002

Function did not complete. See previously listed messages related to possible user errors.

XCL9003

Function did not complete. See previously listed messages for possible cause.

XCL9004

Function did not complete. See previously listed messages for possible cause.

XCL9005

Function did not complete. Contact your service provider.