Defining data structures
When a data structure is defined for use with an API, the structure must be built to receive what the API returns. Here are the program examples that show the incorrect and correct ways of defining data structures. You can prevent errors by using IBM-supplied data structures rather than creating your own data structures.
For information about IBM-supplied data structures that are contained in the QSYSINC library, see Include files and the QSYSINC library.
Incorrect program example: Defining a data structure
When the program that defines a data structure is run, it does the following:
- Creates a user space
- Retrieves a list of active jobs
- Displays the first part of a job name
- Deletes the user space that held the data
In this example, the data structure to be used with the QUSLJOB API has been defined incorrectly. The incorrectly defined variables are JNAME and USRNAM. The JNAME length is defined as 1 through 12 and the USRNAM length as 13 through 20. This is shown at (1). The data displayed (JNAME variable) will be incorrect. The correct coding is shown at (2).
*****************************************************************
*
*Program Name: PGM1
*
*Program Language: RPG
*
*Description: This sample program illustrates the incorrect
* way of defining data structures.
*
*Header Files Included: QUSEC - Error Code Parameter
* QUSGEN - User Space Format for Generic Header
*
*APIs Used: QUSCRTUS - Create User Space
* QUSLJOB - List Job
* QUSRTVUS - Retrieve User Space
* QUSDLTUS - Delete User Space
*****************************************************************
* THIS PROGRAM WILL CREATE THE NECESSARY SPACE AND THEN CALL
* THE QUSLJOB API TO GET A LIST OF ALL ACTIVE JOBS ON THE SYSTEM.
* THE FIRST JOB NAME/USER WILL BE DISPLAYED TO THE USER.
*
* BRING IN THE USER SPACE GENERIC HEADER
I/COPY QSYSINC/QRPGSRC,QUSGEN
* BRING IN THE ERROR STRUCTURE FROM QSYSINC
I/COPY QSYSINC/QRPGSRC,QUSEC
** JOB NAME STRUCTURE FOR CALLING QUSLJOB
IJOBNAM DS
I I '*ALL ' 1 10 JOB
I I '*ALL ' 11 20 USER
I I '*ALL ' 21 26 JOBNUM
** JOBL0100 FORMAT RETURNED FROM QUSLJOB API
** INCORRECTLY CODE THE JNAME/USRNAM LENGTHS
IRECVR DS
I 1 12 JNAME (1)
I 13 20 USRNAM (1)
I 21 26 JOBNBR
I 27 42 JOBID
I 43 52 JSTAT
I 53 53 JTYPE
I 54 54 JSUBT
I 55 56 RESRV
**
ISPCNAM DS
I I 'SPCNAME ' 1 10 SPC
I I 'QTEMP ' 11 20 LIB
** OTHER ASSORTED VARIABLES
I DS
I I 2000 B 1 40SIZ
I I B 5 80START
I I B 9 120LENDTA
I I X'00' 13 13INTVAL
*
* SET UP TO ACCEPT EXCEPTIONS
C Z-ADD*ZEROS QUSBNB
*
* CREATE THE SPACE TO HOLD THE DATA
C CALL 'QUSCRTUS'
C PARM SPCNAM
C PARM 'EXT_ATTR'EXTATR 10
C PARM SIZ
C PARM INTVAL
C PARM '*ALL 'PUBAUT 10
C PARM 'TEXT DSC'TXTDSC 50
C PARM '*YES 'REPLAC 10
C PARM QUSBN
*
* CALL THE API TO LIST THE ACTIVE JOBS
C CALL 'QUSLJOB'
C PARM SPCNAM
C PARM 'JOBL0100'FORMAT 8
C PARM JOBNAM
C PARM '*ACTIVE 'STAT 10
C PARM QUSBN
*
* RETRIEVE THE OFFSET OF THE FIRST LIST ENTRY FROM THE SPACE
C Z-ADD1 START
C Z-ADD140 LENDTA
C CALL 'QUSRTVUS'
C PARM SPCNAM
C PARM START
C PARM LENDTA
C PARM QUSBP
C PARM QUSBN
*
* RETRIEVE THE FIRST LIST ENTRY
C QUSBPQ ADD 1 START
C Z-ADD56 LENDTA
C CALL 'QUSRTVUS'
C PARM SPCNAM
C PARM START
C PARM LENDTA
C PARM RECVR
C PARM QUSBN
*
* DISPLAY THE JOB NAME
C DSPLY JNAME
****************************
* When displayed, JNAME *
* will look something like *
* 'QCPF QS' *
****************************
* DELETE THE SPACE THAT HELD THE DATA
C CALL 'QUSDLTUS'
C PARM SPCNAM
C PARM QUSBN
**
C SETON LR
Correct program example: Defining a data structure
The following program uses a data structure that is supplied from the QSYSINC library. When you use this data structure, you can prevent errors in data structure creation from happening. If the data structures change from release to release, updates to programs do not have to be done. The application program would have to be updated only if a new field was added to the data structure and you wanted to use the field. The copying of the QSYSINC data structure is shown at (2).
*
*
*****************************************************************
*
*Program Name: PGM2
*
*Program Language: RPG
*
*Description: This sample program illustrates the correct
* way of defining data structures.
*
*Header Files Included: QUSEC - Error Code Parameter
* QUSGEN - User Space Format for Generic Header
* QUSLJOB - List Job API
*
*APIs Used: QUSCRTUS - Create User Space
* QUSLJOB - List Job
* QUSRTVUS - Retrieve User Space
* QUSDLTUS - Delete User Space
*
*
* THIS PROGRAM WILL CREATE THE NECESSARY SPACE AND THEN CALL
* THE QUSLJOB API TO GET A LIST OF ALL ACTIVE JOBS ON THE SYSTEM.
* THE FIRST JOB NAME/USER WILL BE DISPLAYED TO THE USER.
*
I/COPY QSYSINC/QRPGSRC,QUSGEN
I/COPY QSYSINC/QRPGSRC,QUSEC
I/COPY QSYSINC/QRPGSRC,QUSLJOB (2)
** JOB NAME STRUCTURE FOR CALLING QUSLJOB
IJOBNAM DS
I I '*ALL ' 1 10 JOB
I I '*ALL ' 11 20 USER
I I '*ALL' 21 26 JOBNUM
** JOBL0100 FORMAT RETURNED FROM QUSLJOB API
**
**
ISPCNAM DS
I I 'SPCNAME ' 1 10 SPC
I I 'QTEMP ' 11 20 LIB
** OTHER ASSORTED VARIABLES
I DS
I I 2000 B 1 40SIZ
I I B 5 80START
I I B 9 120LENDTA
I I X'00' 13 13 INTVAL
*
* SET UP TO ACCEPT EXCEPTIONS
C Z-ADD*ZEROS QUSBNB
*
* CREATE THE SPACE TO HOLD THE DATA
C CALL 'QUSCRTUS'
C PARM SPCNAM
C PARM 'EXT_ATTR'EXTATR 10
C PARM SIZ
C PARM INTVAL
C PARM '*ALL 'PUBAUT 10
C PARM 'TEXT DSC'TXTDSC 50
C PARM '*YES 'REPLAC 10
C PARM QUSBN
*
* CALL THE API TO LIST THE ACTIVE JOBS
C CALL 'QUSLJOB'
C PARM SPCNAM
C PARM 'JOBL0100'FORMAT 8
C PARM JOBNAM
C PARM '*ACTIVE 'STAT 10
C PARM QUSBN
*
* RETRIEVE THE OFFSET OF THE FIRST LIST ENTRY FROM THE SPACE
C Z-ADD1 START
C Z-ADD140 LENDTA
C CALL 'QUSRTVUS'
C PARM SPCNAM
C PARM START
C PARM LENDTA
C PARM QUSBP
C PARM QUSBN
*
* RETRIEVE THE FIRST LIST ENTRY
C QUSBPQ ADD 1 START
C Z-ADD56 LENDTA
C CALL 'QUSRTVUS'
C PARM SPCNAM
C PARM START
C PARM LENDTA
C PARM QUSDD
C PARM QUSBN
*
* DISPLAY THE JOB NAME
C DSPLY QUSDDB
*************************
* Correct job name *
* will now show as *
* 'QCPF ' *
*************************
* DELETE THE SPACE THAT HELD THE DATA
C CALL 'QUSDLTUS'
C PARM SPCNAM
C PARM QUSBN
**
C SETON LR