Manipulating a user space with pointers

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 application 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 Example: Changing a user space with an ILE RPG program 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 programs 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 operation to the user space, but you should do this once within each application program to maintain accurate usage data information.