Manipulating a User Space without Pointers
When programming in a language that does not support pointers, you can use the
Change User Space (QUSCHGUS) and Retrieve User Space (QUSRTVUS) APIs
to manipulate data. However, you must first understand how to use positions and
lengths with these APIs.
Position Values
Some APIs return offset values into a user space. To use other APIs, such as the
Retrieve User Space (QUSRTVUS) API, you must use position values to locate
bytes.
Position values and offset values are different ways to express the same thing. An
offset value is the relative distance of a byte from the first byte of the user space,
which has an offset value of 0. A position value is the offset value plus 1.
For examples of HLL programs that use positions, see “List Object API—OPM RPG
Example” on page 5-4.
Lengths
List APIs return the length of the information in the different sections of the user
space, as well as the length of the list entries in the user space. You should code
your application using the lengths returned instead of specifying the current length
returned by the API or the size of a data structure in the data structure files. The
amount of information returned for any format may increase in future releases, but
the information will be placed at the end of the existing information. In order for
your application to function properly, it should retrieve the length of the information
returned and add that length to a pointer or to a starting position.
Using Offset Values with the Change and Retrieve User Space
APIs
When you use the Change User Space (QUSCHGUS) or Retrieve User Space
(QUSRTVUS) API, your application program should first retrieve the offset value for
the information you want. You must then add one to the offset value to get the
starting position for the information.
Changing a User Space—Example
Before and after illustrations show how the QUSCHGUS API changes a user
space. The following is a user space before you change it with one of the change
examples.
Chapter 2. Getting Started with APIs 2-17