The Retrieve User Space Pointer (RTVUSPXCL) command retrieves a pointer to the first byte of a user space.

This function is also available with command RTVSPCPTR 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 *USE authority to the user space and *EXECUTE authority to the library where the user space is located.

Parameters

User space (USRSPC)

Specifies the qualified name of the user space to be accessed.

This is a required parameter.

Qualifier 1: User space

name

Specify the name of the user space.

Qualifier 2: Library

*LIBL

The library list for the job is used.

*CURLIB

The current library for the job is used. If no current library entry exists in the library list, QGPL is used.

name

Specify the name of the library.

Pointer (PTR)

Specifies the CL variable to receive a pointer to the first byte of the user space.

Due to CL commands not allowing CL variables of TYPE(*PTR) to be passed as a parameter the CL pointer variable must be passed indirectly by declaring the pointer variable as being defined on a character variable. The following demonstrates how to do this.

Dcl        Var(&Chr_Ptr) Type(*Char) Len(16)
Dcl        Var(&Pointer) Type(*Ptr) Stg(*Defined) +
             DefVar(&Chr_Ptr)
RtvUSPXCL  UsrSpc(MySpace) Ptr(&Chr_Ptr)

After the RTVUSPXCL command runs the pointer variable &Pointer will address the first byte of the user space.

The defined on variable (DEFVAR) must be declared with a minimum length of 16 bytes. The CL pointer variable, declared with TYPE(*PTR), must be defined on a base 1 16-byte boundary of the DEFVAR variable.

This is a required parameter.

character-value

Specify the name of the CL variable to receive the pointer value.

Examples for RTVUSPXCL

Example 1: Simple Command Example

Dcl        Var(&Chr_Ptr) Type(*Char) Len(16)
Dcl        Var(&Pointer) Type(*Ptr) Stg(*Defined) +
             DefVar(&Chr_Ptr)
Dcl        Var(&Byte)    Type(*Char) Len(1) +
             Stg(*Based) BasPtr(&Pointer)
RtvUSPXCL  UsrSpc(QTemp/MySpace) Ptr(&Chr_Ptr)
SndPgmMsg  Msg('1st byte is' *BCat &Byte)

This example retrieves a pointer to the first byte of the user space MYSPACE in library QTEMP. The first byte is then displayed using the SNDPGMMSG command.

Error messages for RTVUSPXCL

*ESCAPE Messages

XCL500D

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

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.