Manipulating a User Space with Pointers
Some languages, such as ILE C', VisualAge C++ for OS/400, ILE COBOL, ILE
RPG, COBOL, Pascal, and PL/I, support pointers. Pointers allow you to manipulate
information more rapidly from the user space. To use pointers with the OS/400
APIs, you should understand how to:
Synchronize between two or more jobs
Use offset values with pointers
Update usage data
Synchronizing between Two or More Jobs
If you are using the Change User Space (QUSCHGUS) or Retrieve User Space
(QUSRTVUS) API to manipulate user spaces, you do not need to synchronize
update and retrieve operations when multiple jobs access the user space. The
APIs already do that for you. However, if you are using space pointers to retrieve
the information directly from the user space, you should synchronize your applica-
tion programs to avoid data errors. This ensures that no two users update the
space at the same time, which can cause unpredictable results.
Locks are typically used to synchronize two jobs on the system, and you can lock
user spaces. To synchronize multiple jobs, you can use one of the following:
Compare and swap (CMPSWP MI instructions)
Space location locks (LOCKSL and UNLOCKSL MI instructions)
Object locks (LOCK and UNLOCK MI instructions)
Allocate Object (ALCOBJ) and Deallocate Object (DLCOBJ) commands
The preceding list is ordered by relative performance where CMPSWP is the
fastest. If you do not synchronize two or more jobs, multiple concurrent updates to
the user space or read operations can occur while information is being updated.
As a result, the data may not be accurate.
Using Offset Values with Pointers
When using a pointer to manipulate the user space, you must:
1. Get a space pointer to the first byte (offset value of zero) of the user space.
2. Retrieve the offset value of the information you want to use from the user
space.
3. Add that offset value to the space pointer value.
4. Use the space pointer value to directly refer to the information in the user
space.
See “Changing a User Space with an ILE RPG Program—Example” on page 2-20
for an example of this procedure.
Updating Usage Data
If you are using the Change User Space (QUSCHGUS) or Retrieve User Space
(QUSRTVUS) API to manipulate user spaces, you do not need to update usage
data information. If you directly retrieve data using pointers, your application pro-
grams should update the usage data information. To do this, use the QUSCHGUS
API to update the date last changed and use the QUSRTVUS API to update the
date last retrieved. You do not need to do this for each retrieve or change opera-
tion to the user space, but you should do this once within each application program
to maintain accurate usage data information.
2-16 System API Programming V4R1