An offset indicates the point 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.
Using offsets incorrectly can produce errors when coding in a base 1 language such as RPG and COBOL. One way to determine the base of a language is to determine how the first element of an array is specified. 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. However, APIs produce information using a base of 0. To compensate, the API user must add 1 to all decimal and hexadecimal offsets to the formats.
The beginning point for reading a user space is shown at (1). The data is read and placed into a user space. However, the data in the user space is incorrect because the 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 (2).
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.
I*
I*** START HEADER FILE SPECIFICATIONS ****************************
I*
I*Header File Name: H/QUSEC
I*
I*Descriptive Name: Error Code Parameter.
I*
I*5763-SS1 (C) Copyright IBM Corp. 1994,1994
I*All rights reserved.
I*US Government Users Restricted Rights -
I*Use, duplication or disclosure restricted
I*by GSA ADP Schedule Contract with IBM Corp.
I*
I*Licensed Materials-Property of IBM
I*
I*
I*Description: Include header file for the error code parameter.
I*
I*Header Files Included: None.
I*
I*Macros List: None.
I*
I*Structure List: Qus_EC_t
I*
I*Function Prototype List: None.
I*
I*Change Activity:
I*
I*CFD List:
I*
I*FLAG REASON LEVEL DATE PGMR CHANGE DESCRIPTION
I*---- ------------ ----- ------ --------- ----------------------
I*$A0= D2862000 3D10 931201 DPOHLSON: New Include
I*
I*End CFD List.
I*
I*Additional notes about the Change Activity
I*End Change Activity.
I*** END HEADER FILE SPECIFICATIONS ******************************
I*****************************************************************
I*Record structure for Error Code Parameter
I**** ***
I*NOTE: The following type definition only defines the corrected
I* portion of the format. Varying length field Exception
I* Data will not be defined here.
I*****************************************************************
IQUSBN DS
I* Qus EC
I B 1 40QUSBNB
I* Bytes Provided
I B 5 80QUSBNC
I* Bytes Available
I 9 15 QUSBND
I* Exception Id
I 16 16 QUSBNF
I* Reserved
I* 17 17 QUSBNG
I*
I* Varying length
I 17 100 QUSBNG
I*
I* List Objects API Include
I*
I/COPY QSYSINC/QRPGSRC,QUSLOBJ
I*
I* Qualified User Space Data Structure
I*
IUSERSP DS
I I 'APIUG1 ' 1 10 USRSPC
I I 'QGPL ' 11 20 SPCLIB
I* Qualified Object Name Data Structure
IOBJECT DS
I I '*ALL ' 1 10 OBJNAM
I I 'QGPL ' 11 20 OBJLIB
I*
I* Miscellaneous Data Structure
I*
I DS
I* Set up parameters for the Create User Space API
I I 'TESTUSRSPC' 1 10 EXTATR
I I X'00' 11 11 INTVAL
I 12 12 RSVD1
I I 256 B 13 160INTSIZ
I I '*USE ' 17 26 PUBAUT
I I 'TEXT DESCRIPTION - 27 76 TEXT
I 'FOR USER SPACE -
I 'CALLED APIUG1 '
I I '*YES ' 77 87 REPLAC
I* Set up parameters for the List Objects API
I I 'OBJL0100' 88 95 FORMAT
I I '*ALL ' 96 105 OBJTYP
I 106 108 RSVD2
I* Set up parameters for the Retrieve User Space API
I I 1 B 109 1120STRPOS
I I 192 B 113 1160LENDTA
I B 117 1200COUNT
C*
C* Create a user space called APIUG1 in library QGPL.
C*
C Z-ADD100 QUSBNB
C CALL 'QUSCRTUS'
C PARM USERSP
C PARM EXTATR
C PARM INTSIZ
C PARM INTVAL
C PARM PUBAUT
C PARM TEXT
C PARM REPLAC
C PARM QUSBN
C* See if any errors were returned in the error code parameter.
C EXSR ERRCOD
C*
C* Get a list of all objects in the QGPL library.
C*
C CALL 'QUSLOBJ'
C PARM USERSP
C PARM FORMAT
C PARM OBJECT
C PARM OBJTYP
C PARM QUSBN
C* See if any errors were returned in the error code parameter.
C EXSR ERRCOD
C*
C* Look at the generic header.
C* The generic header contains information
C* about the list data section that is needed when processing
C* the entries.
C*
C CALL 'QUSRTVUS'
C PARM USERSP
C PARM STRPOS
C PARM LENDTA
C PARM QUSBP
C PARM QUSBN
C* See if any errors were returned in the error code parameter.
C EXSR ERRCOD
C*
C* Check the information status field, QUSBPJ, to see if
C* the API was able to return all the information.
C* Possible values are:
C* C -- Complete and accurate
C* P -- Partial but accurate
C* I -- Incomplete
C*
C QUSBPJ IFEQ 'C'
C QUSBPJ OREQ 'P'
C*
C* Check to see if any entries were put into the user space.
C*
C QUSBPS IFGT 0
C Z-ADD1 COUNT
C Z-ADDQUSBPQ STRPOS (1)
C Z-ADD30 LENDTA
C* Walk through all the entries in the user space.
C COUNT DOWLEQUSBPS
C CALL 'QUSRTVUS'
C PARM USERSP
C PARM STRPOS
C PARM LENDTA
C PARM QUSDM
C PARM QUSBN
C* See if any errors were returned in the error code parameter.
C EXSR ERRCOD
C*
C*
C* Process the objects.
C*
C ADD 1 COUNT
C ADD QUSBPT STRPOS
C ENDDO
C ENDIF
C*
C* Information in the user space is not accurate
C*
C ENDIF
C*
C* Delete the user space called APIUG1 in library QGPL.
C*
C CALL 'QUSDLTUS'
C PARM USERSP
C PARM QUSBN
C* See if any errors were returned in the error code parameter.
C EXSR ERRCOD
C*
C SETON LR
C RETRN
C*
C* End of MAINLINE
C*
C* Subroutine to handle errors returned in the error code
C* parameter.
C*
C ERRCOD BEGSR
C QUSBNC IFGT 0
C*
C* Process errors returned from the API.
C*
C END
C ENDSR
The following example program has code in it that compensates for the API offset convention of that starts at 0. The code adds 1 to the starting position (STRPOS) offset. This is shown at (2).
I*
I*Program Name: APIUG2
I*
I*Programming Language: RPG
I*
I*Description: This sample program illustrates the correct
I* way of using offsets in 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.
I*
I*** START HEADER FILE SPECIFICATIONS ****************************
I*
I*Header File Name: H/QUSEC
I*
I*Descriptive Name: Error Code Parameter.
I*
I*5763-SS1 (C) Copyright IBM Corp. 1994,1994
I*All rights reserved.
I*US Government Users Restricted Rights -
I*Use, duplication or disclosure restricted
I*by GSA ADP Schedule Contract with IBM Corp.
I*
I*Licensed Materials-Property of IBM
I*
I*
I*Description: Include header file for the error code parameter.
I*
I*Header Files Included: None.
I*
I*Macros List: None.
I*
I*Structure List: Qus_EC_t
I*
I*Function Prototype List: None.
I*
I*Change Activity:
I*
I*CFD List:
I*
I*FLAG REASON LEVEL DATE PGMR CHANGE DESCRIPTION
I*---- ------------ ----- ------ --------- ----------------------
I*$A0= D2862000 3D10 931201 DPOHLSON: New Include
I*
I*End CFD List.
I*
I*Additional notes about the Change Activity
I*End Change Activity.
I*** END HEADER FILE SPECIFICATIONS ******************************
I*****************************************************************
I*Record structure for Error Code Parameter
I**** ***
I*NOTE: The following type definition only defines the corrected
I* portion of the format. Varying length field Exception
I* Data will not be defined here.
I*****************************************************************
IQUSBN DS
I* Qus EC
I B 1 40QUSBNB
I* Bytes Provided
I B 5 80QUSBNC
I* Bytes Available
I 9 15 QUSBND
I* Exception Id
I 16 16 QUSBNF
I* Reserved
I* 17 17 QUSBNG
I*
I* Varying length
I 17 100 QUSBNG
I*
I* List Objects API Include
I*
I/COPY QSYSINC/QRPGSRC,QUSLOBJ
I*
I* Qualified User Space Data Structure
I*
IUSERSP DS
I I 'APIUG1 ' 1 10 USRSPC
I I 'QGPL ' 11 20 SPCLIB
I* Qualified Object Name Data Structure
IOBJECT DS
I I '*ALL ' 1 10 OBJNAM
I I 'QGPL ' 11 20 OBJLIB
I*
I* Miscellaneous Data Structure
I*
I DS
I* Set up parameters for the Create User Space API
I I 'TESTUSRSPC' 1 10 EXTATR
I I X'00' 11 11 INTVAL
I 12 12 RSVD1
I I 256 B 13 160INTSIZ
I I '*USE ' 17 26 PUBAUT
I I 'TEXT DESCRIPTION - 27 76 TEXT
I 'FOR USER SPACE -
I 'CALLED APIUG2 '
I I '*YES ' 77 87 REPLAC
I* Set up parameters for the List Objects API
I I 'OBJL0100' 88 95 FORMAT
I I '*ALL ' 96 105 OBJTYP
I 106 108 RSVD2
I* Set up parameters for the Retrieve User Space API
I I 1 B 109 1120STRPOS
I I 192 B 113 1160LENDTA
I B 117 1200COUNT
C*
C* Create a user space called APIUG1 in library QGPL.
C*
C Z-ADD100 QUSBNB
C CALL 'QUSCRTUS'
C PARM USERSP
C PARM EXTATR
C PARM INTSIZ
C PARM INTVAL
C PARM PUBAUT
C PARM TEXT
C PARM REPLAC
C PARM QUSBN
C* See if any errors were returned in the error code parameter.
C EXSR ERRCOD
C*
C* Get a list of all objects in the QGPL library.
C*
C CALL 'QUSLOBJ'
C PARM USERSP
C PARM FORMAT
C PARM OBJECT
C PARM OBJTYP
C PARM QUSBN
C* See if any errors were returned in the error code parameter.
C EXSR ERRCOD
C*
C* Look at the generic header. This contains information
C* about the list data section that is needed when processing
C* the entries.
C*
C CALL 'QUSRTVUS'
C PARM USERSP
C PARM STRPOS
C PARM LENDTA
C PARM QUSBP
C PARM QUSBN
C* See if any errors were returned in the error code parameter.
C EXSR ERRCOD
C*
C*
C* Check the information status field, QUSBPJ, to see if the
C* API was able to return all the information. Possible values
C* are: C -- Complete and accurate
C* P -- Partial but accurate
C* I -- Incomplete.
C*
C QUSBPJ IFEQ 'C'
C QUSBPJ OREQ 'P'
C*
C* Check to see if any entries were put into the user space.
C*
C QUSBPS IFGT 0
C Z-ADD1 COUNT
C* Because RPG is Base 1, the offset must be increased by one.
C*
C QUSBPQ ADD 1 STRPOS (2)
C Z-ADD30 LENDTA
C* Walk through all the entries in the user space.
C COUNT DOWLEQUSBPS
C CALL 'QUSRTVUS'
C PARM USERSP
C PARM STRPOS
C PARM LENDTA
C PARM QUSDM
C PARM QUSBN
C* See if any errors were returned in the error code parameter.
C EXSR ERRCOD
C*
C*
C* Process the objects.
C*
C ADD 1 COUNT
C ADD QUSBPT STRPOS
C ENDDO
C ENDIF
C*
C* Information in the user space is not accurate.
C*
C ENDIF
C*
C*
C* Delete the user space called APIUG1 in library QGPL.
C*
C CALL 'QUSDLTUS'
C PARM USERSP
C PARM QUSBN
C* See if any errors were returned in the error code parameter.
C EXSR ERRCOD
C*
C SETON LR
C RETRN
C*
C* End of MAINLINE
C*
C* Subroutine to handle errors returned in the error code
C* parameter.
C*
C ERRCOD BEGSR
C QUSBNC IFGT 0
C*
C* Process errors returned from the API.
C*
C END
C ENDSR