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.
The use of IBM-supplied data structures eliminates having to create your own data
structures. For information on IBM-supplied data structures that are contained in
library QSYSINC, see “APIs and the QSYSINC Library” on page 2-28.
Defining a Data Structure—Example of Incorrect Coding
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 .5/ on page 9-5. The data displayed (JNAME vari-
able) will be incorrect. The correct coding is shown at .6/ on page 9-7.
\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
\
\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 1ð JOB
I I '\ALL ' 11 2ð USER
I I '\ALL ' 21 26 JOBNUM
\\ JOBLð1ðð FORMAT RETURNED FROM QUSLJOB API
\\ INCORRECTLY CODE THE JNAME/USRNAM LENGTHS
IRECVR DS
I 1 12 JNAME .5/
Chapter 9. Common API Programming Errors 9-5