Retrieve Pointer to User Space (QUSPTRUS) API
Required Parameter Group:
| 1 | Qualified user space name | Input | Char(20) |
| 2 | Return pointer | Output | PTR(SPP) |
Optional Parameter:
| 3 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: Yes
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.
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
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3C05 E | One or more errors found while trying to retrieve a pointer. |
| CPF3C18 E | Pointer parameter is not on a 16-byte boundary. |
| CPD3C18 D | Pointer parameter is not on a 16-byte boundary. |
| CPF3C36 E | Number of parameters, &1, entered for this API was not valid. |
| CPF3C48 E | Operation not valid on system domain object. |
| 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. |
| 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: V2R3
[ Back to top | Object APIs | APIs by category ]