Retrieve Pointer to User Space (QUSPTRUS) API

The Retrieve Pointer to User Space (QUSPTRUS) API retrieves a pointer to the contents of a user-domain user space. The data in that user space then can be directly manipulated by high-level language programs that support pointers, such as C or COBOL. The QUSPTRUS API will not return a pointer to a system-domain user space; you must use system APIs to access system-domain user spaces. If you attempt to retrieve the pointer to a system-domain user space, an error will be returned.

The QUSPTRUS API even returns a pointer to an object that is subject to an exclusive (*EXCL) lock. If you create application programs using HLLs that can directly update user spaces using pointers (instead of using the Change User Space (QUSCHGUS) API), you should use your own synchronization data methods. You can use one of the following methods to avoid updates at the same time to the same location within a user space:

• CMPSW MI instruction
• CMPSWP MI instruction
• LOCK MI instruction
• LOCKSL MI instruction
• Allocate Object (ALCOBJ) command

Use of the QUSPTRUS API does not update the object usage information (such as last changed date, last date used, and so on). You should use the Change User Space or the Retrieve User Space API to update the object usage information if needed.

Examples of the API are in Examples: Defining queries, Example: Deleting old spooled files, and Example: Using the user-defined communications programs for file transfer in API examples.

Authorities and Locks

Library Authority

*EXECUTE

User Space Authority

*USE

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.

Return pointer

OUTPUT; PTR(SPP)

The variable containing the pointer to the user space after the QUSPTRUS API has completed running. This parameter must be on a 16-byte boundary alignment.

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