Retrieve User Space (QUSRTVUS) API

  Required Parameter Group:

  Optional Parameter Group:

  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
User Space Authority
User Space Lock

Required Parameter Group

Qualified user space name

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

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

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

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

API introduced: V1R3

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