Data Queue APIs--Categories - FTP Directory Listing - IBM

Retrieve Pointer to User Space (QUSPTRUS) API
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(*)
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 API examples.
http://infocntr.rchland.ibm.com/pubs/html/as400/v4r5/ic2924/info/apis/qusptrus.htm (1 of 3) [10/4/1999 2:35:05 PM]