Using Offsets in a User Space
An offset indicates where in a structure that specific information should start. When
offsets are correctly used, programs can extract specific pieces of data from a
structure and perform actions on that data.
Incorrectly working with offsets can produce errors by API users when coding in a
base 1 language such as RPG and COBOL. One way to determine the base of a
language is how a programmer specifies the first element of an array. In a base 0
language, the first element is number 0. In base 1 languages, the first element is
number 1.
The example programs in the following topics are coded using RPG. RPG is a
base 1 language while the APIs produce information using a base of 0. To com-
pensate for APIs producing information at base 0, the API user must add 1 to all
decimal and hexadecimal offsets to formats that are contained in the
System API
Reference
book.
Using Offsets in a User Space—Example of Incorrect Coding
The point for beginning to read a user space is shown at .18/ on page 9-30. The
data is read and placed into a user space. However, the data in the user space is
incorrect because the starting position to start was off by 1. This program started
to retrieve the data one character (or position) too soon. The correct coding is
shown at .19/ on page 9-34.
I\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
I\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
I\
I\Program Name: APIUG1
I\
I\Programming Language: RPG
I\
I\Description: This sample program illustrates the incorrect
I\ way of using the offset in a user space.
I\
I\Header Files Included: QUSGEN - Generic Header of a User Space
I\ QUSEC - Error Code Parameter
I\ (Copied into Program)
I\ QUSLOBJ - List Objects API
I\
I\APIs Used: QUSCRTUS - Create User Space
I\ QUSLOBJ - List Objects
I\ QUSRTVUS - Retrieve User Space
I\ QUSDLTUS - Delete User Space
I\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
I\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
I\
I\ Generic Header of a User Space Include
I\
I/COPY QSYSINC/QRPGSRC,QUSGEN
I\
I\ Error Code Parameter Include for the APIs
I\
I\ The following QUSEC include is copied into this program
I\ so that the variable length field can be defined as a
I\ fixed length.
Chapter 9. Common API Programming Errors 9-27