Retrieve User Space (QUSRTVUS) API

Required Parameter Group:

Qualified user space name

Input

Char(20)

Starting position

Input

Binary(4)

Length of data

Input

Binary(4)

Receiver variable

Output

Char(*)

Optional Parameter Group:

Error code

I/O

Char(*)

Default Public Authority: *USE

Threadsafe: Yes

The Retrieve User Space (QUSRTVUS) API allows you to retrieve the contents of a user space. The QUSRTVUS API does not retrieve descriptive information about the user space object, such as its size. To retrieve information about the attributes of a user space, see Retrieve User Space Attributes (QUSRUSAT) API.

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

If you are repeatedly accessing the contents of a user space and are using an HLL that supports pointers, see Retrieve Pointer to User Space (QUSPTRUS) API. This API provides a pointer to the user space for improved performance. When you have obtained a pointer, you use pointer arithmetic to access the contents of a user space.

Note: To determine the starting position for the QUSRTVUS API, you must add 1 to the offset value. In contrast to the IBM^® i list APIs, which use an offset value based on 0 for the starting position, the QUSRTVUS API uses a value based on 1. For the QUSRTVUS API, the first character in the user space is at position 1.

Authorities and Locks

Library Authority: *EXECUTE
User Space Authority: *USE
User Space Lock: *SHRNUP

Required Parameter Group

Qualified user space name: INPUT; CHAR(20)
The first 10 characters contain the user space name, and the second 10 characters contain the name of the library where the user space is located. The special values supported for the library name are *LIBL and *CURLIB.
Starting position: INPUT; BINARY(4)
The first byte of the user space to be retrieved. A value of 1 will identify the first character in the user space.
Length of data: INPUT; BINARY(4)
The length of the data to retrieve. This length must not be larger than the size of the variable that is to receive the data. It must also be greater than 0.
Receiver variable: OUTPUT; CHAR(*)
The variable that will receive the contents of the user space being retrieved.

Optional Parameter

Error code: I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter. If this parameter is omitted, diagnostic and escape messages are issued to the application.

Error Messages

Message ID

Error Message Text

CPF24B4 E

Severe error while addressing parameter list.

CPF3CF1 E

Error code parameter not valid.

CPF3C0F E

Value &1 for starting position parameter is not valid.

CPF3C06 E

Information not retrieved from user space &1.

CPD3C0F D

Value &1 for starting position parameter is not valid.

CPD3C12 D

Length of data is not valid.

CPD3C14 D

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

CPD3C16 D

Receiver area too small for length of data &1 specified.

CPD3C20 D

Error occurred with receiver variable specified.

CPF3C12 E

Length of data is not valid.

CPF3C14 E

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

CPF3C16 E

Receiver area too small for length of data &1 specified.

CPF3C19 E

Error occurred with receiver variable specified.

CPF3C36 E

Number of parameters, &1, entered for this API was not valid.

CPF3C90 E

Literal value cannot be changed.

CPF8100 E

All CPF81xx messages could be returned. xx is from 01 to FF.

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.

CPF9807 E

One or more libraries in library list deleted.

CPF9808 E

Cannot allocate one or more libraries on library list.

CPF9810 E

Library &1 not found.

CPF9820 E

Not authorized to use library &1.

CPF9830 E

Cannot assign library &1.

CPF9872 E

Program or service program &1 in library &2 ended. Reason code &3.

API introduced: V1R3

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