The Retrieve User Space Data (RTVUSDXCL) command retrieves data from a user space.

This function is also available with command RTVSPCDTA 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:

• You must have *EXECUTE authority to the library containing the user space.
• 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.

Offset into user space (OFS)

Specifies the offset of the first byte of the user space to be retrieved. The value of 0 identifies the first byte. This is consistent with system API use of offsets.

This is a required parameter.

integer

Specify the byte offset into the space to start reading from.

Variable for user space data (VAR)

Specifies the CL variable which will receive the data read from the user space.

This is a required parameter.

character-value

Specify the CL variable to receive the read data.

Length of VAR variable (VARLEN)

Specifies how many bytes of data are to be read from the user space and placed in the CL variable identified by the VAR parameter.

*VAR

The amount of data read will equal the declared size of the VAR parameter.

integer

Specify the number of bytes to read into the VAR variable. The value must be less than or equal to the declared size of the VAR variable.

Examples for RTVUSDXCL

Example 1: Simple Command Example

Dcl        Var(&Header) Type(*Char) Len(192)
RtvUSDXCL  UsrSpc(QTEMP/LSTUSRSPC) Ofs(0) Var(&Header)

This example reads the first 192 bytes of the user space LSTUSRSPC in library QTEMP into CL variable &Header.

Example 2: Retrieving API List Entries

Dcl        Var(&Status)   Type(*Char) Len(1)
Dcl        Var(&OfsEnt)   Type(*Int)
Dcl        Var(&NbrEnt)   Type(*Int)
Dcl        Var(&SizEnt)   Type(*Int)
Dcl        Var(&FileName) Type(*Char) Len(10)
Dcl        Var(&X)        Type(*Int)
Dcl        Var(&Y)        Type(*Int)
CrtUSXCL   UsrSpc(QTEMP/FILELIST)
Call       Pgm(QUSLOBJ) +
             Parm('FILELIST  QTEMP     ' +
                  OBJL0100               +
                  '*ALL      QTEMP     ' +
                  *FILE)
RtvLstIXCL UsrSpc(QTEMP/FILELIST) Status(&Status) +
             OfsEnt(&Y) NbrEnt(&NbrEnt) SizEnt(&SizEnt)
Select
   When    Cond((&Status = C) *Or (&Status = P)) Then(Do)
           DoFor Var(&X) From(1) To(&NbrEnt)
                 RtvUSDXCL UsrSpc(QTEMP/FILELIST) +
                    Ofs(&Y) Var(&FileName)
                 SndPgmMsg Msg(&FileName)
                 ChgVar Var(&Y) Value(&Y + &SizEnt)
                 EndDo
           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, offset to the first list entry, the number of entries, and the size of each entry. Each file name found is then displayed.

Though the size of each entry is 30 bytes only 10 bytes of data is returned to the &FileName CL variable due to the default use of VARLEN(*VAR). The size of each entry (&SizEnt) is used to step through each 30-byte list entry.

Error messages for RTVUSDXCL

*ESCAPE Messages

XCL501B

VARLEN value of &1 is greater than the declared length of the VAR parameter.

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.

CPF3C06

Information not retrieved from user space &1.

CPF3C0F

Value &1 for starting position parameter is not valid.

CPF3C12

Length of data is not valid.

CPF3C14

Starting position &1 and length &2 cause space overflow.

CPF9801

Object &2 in library &3 not found.

CPF9802

Not authorized to object &2 in &3.

CPF9803

Cannot allocate object &2 in library &3.

CPF9810

Library &1 not found.

CPF9820

Not authorized to use library &1.