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