This sample program shows the correct way of using the offset in a user space in RPG.
In this section, the JOBDAPI program accesses a variable-length array. The variable-length array is the initial library list for the job description.
The discussion of the initial library list field in the job description format, JOBD0100 Format, indicates that the initial library list field is 11 bytes per entry, where each entry is a library name followed by a blank. Depending on how many libraries are named for the initial library list, the actual amount of space used varies (by multiples of 11).
The format does not have an entry in the Offset columns for initial library list. It may begin in offset 390, but you should not rely on this. For example, if a new field is added to the job description format, it will probably be placed at offset 390, and the initial library list information will be shifted.
To access the initial library list field, use the following two fields found in the format:
If you use these field values in the format instead of hard coding an offset and a number of libraries, your program can work on any future release of a business computing system, even if more job description attributes are defined in the format. This is an important upward compatibility approach that you will want to use whenever you code for a list of entries.
The following RPG code sends a message for each library found in the initial library list field. Exceptions are handled by the RPG program. Although a library name cannot exceed 10 bytes, each entry is 11 bytes long.
I*****************************************************************
I*****************************************************************
I*
I*Program Name: JOBDAPI
I*
I*Language: OPM RPG
I*
I*Descriptive Name: Get Job Description
I*
I*Description: This sample program shows the correct
I* way of using the offset in a user space in RPG.
I*
I*Header Files Included: QUSEC - Error Code Parameter
I* (Copied into Program)
I* QWDRJOBD - Retrieve Job Description API
I* (Copied into Program)
I*
I*****************************************************************
I*****************************************************************
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
I* fixed length.
I*
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 defines only the fixed
I* portion of the format. Varying-length field exception
I* data is not 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* Varying length, had to define len
I 17 100 QUSBNG
I*
I* Retrieve Job Description API Include
I*
I* The following QWDRJOBD include is copied into this program
I* so that the variable-length field can be defined as fixed
I* length.
I*
I*
I*** START HEADER FILE SPECIFICATIONS ****************************
I*
I*Header File Name: H/QWDRJOBD
I*
I*Descriptive Name: Retrieve Job Description Information API
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: The Retrieve Job Description Information API
I* retrieves information from a job description
I* object and places it into a single variable in the
I* calling program.
I*
I*Header Files Included: None.
I*
I*Macros List: None.
I*
I*Structure List: Qwd_JOBD0100_t
I*
I*Function Prototype List: QWDRJOBD
I*
I*Change Activity:
I*
I*CFD List:
I*
I*FLAG REASON LEVEL DATE PGMR CHANGE DESCRIPTION
I*---- ------------ ----- ------ --------- ----------------------
I*$A0= D2862000 3D10 940424 ROCH: 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*Prototype for QWDRJOBD API
I*****************************************************************
I 'QWDRJOBD' C QWDBGB
I*****************************************************************
I*Type Definition for the JOBD0100 format.
I**** ***
I*NOTE: The following type definition defines only the fixed
I* portion of the format. Any varying-length fields have
I* to be defined by the user.
I*****************************************************************
IQWDBH DS 5000
I* Qwd JOBD0100
I B 1 40QWDBHB
I* Bytes Returned
I B 5 80QWDBHC
I* Bytes Available
I 9 18 QWDBHD
I* Job Description Name
I 19 28 QWDBHF
I* Job Description Lib Name
I 29 38 QWDBHG
I* User Name
I 39 46 QWDBHH
I* Job Date
I 47 54 QWDBHJ
I* Job Switches
I 55 64 QWDBHK
I* Job Queue Name
I 65 74 QWDBHL
I* Job Queue Lib Name
I 75 76 QWDBHM
I* Job Queue Priority
I 77 86 QWDBHN
I* Hold Job Queue
I 87 96 QWDBHP
I* Output Queue Name
I 97 106 QWDBHQ
I* Output Queue Lib Name
I 107 108 QWDBHR
I* Output Queue Priority
I 109 118 QWDBHS
I* Printer Device Name
I 119 148 QWDBHT
I* Print Text
I B 149 1520QWDBHV
I* Syntax Check Severity
I B 153 1560QWDBHW
I* End Severity
I B 157 1600QWDBHX
I* Message Log Severity
I 161 161 QWDBHY
I* Message Log Level
I 162 171 QWDBHZ
I* Message Log Text
I 172 181 QWDBH0
I* Log CL Programs
I 182 191 QWDBH1
I* Inquiry Message Reply
I 192 204 QWDBH2
I* Device Recovery Action
I 205 214 QWDBH3
I* Time Slice End Pool
I 215 229 QWDBH4
I* Accounting Code
I 230 309 QWDBH5
I* Routing Data
I 310 359 QWDBH6
I* Text Description
I 360 360 QWDBH7
I* Reserved
I B 361 3640QWDBH8 (1)
I* Offset Initial Lib List
I B 365 3680QWDBH9 (2)
I* Number Libs In Lib list
I B 369 3720QWDBJB
I* Offset Request Data
I B 373 3760QWDBJC
I* Length Request Data
I B 377 3800QWDBJH
I* Job Message Queue Max Size
I 381 390 QWDBJJ
I* Job Message Queue Full Actio
I* 391 391 QWDBJD
I*
I* Varying length
I* 392 402 QWDBJF
I*
I* Varying length
I* 403 403 QWDBJG
I*
I*
I* Command String Data Structure
I*
ICMDSTR DS
I I 'SNDMSG MSG(''LIBRARY- 1 22 CMD1
I ' - '
I 23 32 LIB
I I ''') TOUSR(QPGMR)' 33 47 CMD2
I*
I* Miscellaneous Data Structure
I*
I DS
I I 5000 B 1 40RCVLEN
I I 0 B 5 80X
I I 'JOBD0100' 9 16 FORMAT
C*
C* Beginning of Mainline
C*
C* Two parameters are being passed into this program.
C*
C *ENTRY PLIST
C PARM JOBD 10
C PARM JOBDL 10
C*
C* Move the two parameters passed into LFNAM.
C*
C JOBD CAT JOBDL LFNAM 20
C*
C* Error code Parameter is set to 100
C*
C Z-ADD100 QUSBNB
C*
C* Instead of specifying 'QWCRJOBD', I could have used the
C* constant QWDBGB that was defined in the QWDRJOBD include.
C*
C CALL 'QWDRJOBD'
C PARM QWDBH Receiver Var.
C PARM RCVLEN Length RCVVAR
C PARM FORMAT Format Name
C PARM LFNAM Qual. Job Desc
C PARM QUSBN Error Code
C* See if any errors were returned in the error code parameter.
C EXSR ERRCOD
C*
C N01 Z-ADD47 LENSTR 155
C*
C N01 QWDBH8 ADD 1 X
C N01 1 DO QWDBH9
C 10 SUBSTQWDBH:X LIB
C*
C* Let's tell everyone what the library value is.
C*
C CALL 'QCMDEXC'
C PARM CMDSTR
C PARM LENSTR
C ADD 11 X
C X IFGE RCVLEN
C LEAVE
C ENDIF
C ENDDO
C*
C SETON LR
C RETRN
C*
C* End of MAINLINE
C*
C*
C* Subroutine to handle errors returned in the error code
C* parameter.
C*
C ERRCOD BEGSR
C QUSBNC IFGT 0
C SETON 01 Error on API Call
C*
C* Process errors returned from the API.
C*
C END
C ENDSR
The output for this program example is as follows:
+--------------------------------------------------------------------------------+ | | | Display Messages | | | | System: GENSYS90 | | Queue . . . . . : QPGMR Program . . . . : *DSPMSG | | Library . . . : QUSRSYS Library . . . : | | Severity . . . : 00 Delivery . . . : *HOLD | | Type reply (if required), press Enter. | | LIBRARY - SMITH | | From . . . : SMITH 07/23/94 12:29:38 | | LIBRARY - QTEMP | | From . . . : SMITH 07/23/94 12:29:38 | | LIBRARY - QGPL | | From . . . : SMITH 07/23/94 12:29:38 | | LIBRARY - QBLDCPF | | From . . . : SMITH 07/23/94 12:29:38 | | LIBRARY - UTIL | | From . . . : SMITH 07/23/94 12:29:38 | | LIBRARY - OPENTEST | +--------------------------------------------------------------------------------+
The handling of the initial library list field is typical of what you will find in many APIs.
See the following for the same example in different languages: