This example shows the steps necessary to process keyed output from an API.
This section introduces a new program named LSTSPL. Program LSTSPL uses the List Spooled Files (QUSLSPL) API to determine the spooled file name, date created, and number of pages for all spooled files created by the current user of the LSTSPL program. Unlike the earlier JOBDAPI program examples, where format JOBD0100 of the Retrieve Job Description (QWDRJOBD) API returned dozens of fields while we were only interested in the HOLD field, the QUSLSPL API provides a keyed interface that allows LSTSPL to request that only the relevant fields (spooled file name, date created, and number of pages) be returned. In addition to providing a keyed interface, QUSLSPL also differs from QWDRJOBD in that the QUSLSPL API retrieves a list of all spooled files into a User Space (*USRSPC) while QWDRJOBD retrieves information about one specific job description into a program variable.
In the following program example, all the pieces have been put together with an OPM RPG program that accesses specific information related to spooled files. A report listing this information is created. The program example does not handle API-related errors. Any errors that are received are returned as exception messages, as shown at 1.
F***************************************************************
F*
F* Program Name: LSTSPL
F*
F* Program Language: OPM RPG
F*
F* Descriptive Name: List Spooled Files for Current User
F*
F* Description: This example shows the steps necessary
F* to process keyed output from an API.
F*
F* Header Files Included: QUSEC - Error Code Parameter
F* QUSGEN - User Space Generic Header
F* QUSLSPL - List Spooled Files
F*
F* APIs Used: QUSLSPL - List Spooled Files
F* QUSCRTUS - Create User Space
F* QUSRTVUS - Retrieve User Space
F*
F***************************************************************
FQSYSPRT O F 132 OF PRINTER
I*
I* Copy User Space Generic Header
I*
I/COPY QSYSINC/QRPGSRC,QUSGEN (11)
I*
I* Copy API Error Code parameter
I*
I/COPY QSYSINC/QRPGSRC,QUSEC
I*
I* Copy List Spooled Files API include
I*
I/COPY QSYSINC/QRPGSRC,QUSLSPL
I*
I* Data structure to hold space name
I*
ISPCNAM DS
I I 'SPCNAME ' 1 10 SPC
I I 'QTEMP ' 11 20 LIB
I*
I* Data structure to hold requested key values
I*
IKEYARA DS (7)
I I 201 B 1 40KEY1
I I 216 B 5 80KEY2
I I 211 B 9 120KEY3 (8)
I*
I* Receiver variable for QUSRTVUS
I*
IRECVR DS 1000
I*
I* Other assorted variables
I*
I DS
I B 1 40SIZ
I B 5 80START
I B 9 120LENDTA
I B 13 160KEY#
I B 17 200PAGES#
I 17 20 PAGESA
I I X'00' 21 21 INTVAL
C*
C* Initialize Error Code structure to accept exceptions
C*
C Z-ADD0 QUSBNB (1)
C*
C* Create the User Space to hold the QUSLSPL API results
C*
C CALL 'QUSCRTUS' (2)
C PARM SPCNAM
C PARM 'quslspl' EXTATR 10
C PARM 2000 SIZ
C PARM INTVAL
C PARM '*ALL' PUBAUT 10
C PARM TXTDSC 50
C PARM '*YES' REPLAC 10
C PARM QUSBN
C*
C* Call QUSLSPL to get all spooled files for *CURRENT user
C*
C CALL 'QUSLSPL' (3)
C PARM SPCNAM
C PARM 'SPLF0200'FORMAT 8 (4)
C PARM '*CURRENT'USRNAM 10
C PARM '*ALL' OUTQ 20
C PARM '*ALL' FRMTYP 10
C PARM '*ALL' USRDTA 10
C PARM QUSBN
C PARM JOBNAM 26
C PARM KEYARA (5)
C PARM 3 KEY# (6)
C*
C* Retrieve information concerning the User Space and its contents
C*
C CALL 'QUSRTVUS' (9)
C PARM SPCNAM
C PARM 1 START Start Rtv at 1
C PARM 192 LENDTA for length =192
C PARM QUSBP (10)
C PARM QUSBN
C*
C* Check User Space status for good information
C*
C QUSBPD IFEQ '0100' (12) Header Fmt
C QUSBPJ IFEQ 'C' (14) Complete
C QUSBPJ OREQ 'P' or Partial
C*
C* Check to see if any entries were put into User Space
C*
C QUSBPS IFGT 0 (16)
C*
C* Keep count of how many list entries we have processed
C*
C Z-ADD0 COUNT 90 (17)
C*
C* Adjust Offset value to Position value
C*
C QUSBPQ ADD 1 START (18)
C*
C* Retrieve the lesser of allocated storage or available data
C*
C QUSBPT IFLT 1000 (19)
C Z-ADDQUSBPT LENDTA
C ELSE
C Z-ADD1000 LENDTA
C ENDIF
C*
C* Process all entries returned
C*
C COUNT DOWLTQUSBPS (20)
C*
C* Retrieve spooled file information
C*
C CALL 'QUSRTVUS' (21)
C PARM SPCNAM
C PARM START
C PARM LENDTA
C PARM RECVR
C PARM QUSBN
C*
C* Loop through returned fields
C*
C 4 SUBSTRECVR QUSFV (22)
C Z-ADD5 X 40
C DO QUSFVB (23)
C*
C* Get header information
C*
C 16 SUBSTRECVR:X QUSKR (24)
C*
C* Set Y to location of actual data associated with key
C*
C X ADD 16 Y 40
C*
C* Process the data based on key type
C*
C QUSKRC CASEQ201 FILNAM (25)
C QUSKRC CASEQ211 PAGES
C QUSKRC CASEQ216 AGE
C CAS ERROR
C END
C*
C* Adjust X to address next keyed record returned
C*
C ADD QUSKRB X
C ENDDO
C*
C* Output information on spooled file
C*
C EXCPTPRTLIN (26)
C*
C* Adjust START to address next entry
C*
C ADD 1 COUNT (27)
C ADD QUSBPT START
C ENDDO
C ENDIF
C ELSE (15)
C EXCPTLSTERR
C ENDIF
C ELSE (13)
C EXCPTHDRERR
C ENDIF
C MOVE '1' *INLR (28)
C RETRN
C*
C* Various subroutines
C*
C***************************************************************
C FILNAM BEGSR
C*
C* Extract spooled file name for report
C*
C MOVE *BLANKS PRTFIL 10
C QUSKRG SUBSTRECVR:Y PRTFIL
C ENDSR
C***************************************************************
C PAGES BEGSR
C*
C* Extract number of pages for report
C*
C QUSKRG SUBSTRECVR:Y PAGESA
C ENDSR
C***************************************************************
C AGE BEGSR
C*
C* Extract age of spooled file for report
C*
C MOVE *BLANKS OPNDAT 7
C QUSKRG SUBSTRECVR:Y OPNDAT
C ENDSR
C***************************************************************
C ERROR BEGSR
C*
C* If unknown key value, then display the value and end
C*
C DSPLY QUSKRC
C MOVE '1' *INLR
C RETRN
C ENDSR
O*
OQSYSPRT E PRTLIN
O PRTFIL 10
O PAGES# 25
O OPNDAT 40
OQSYSPRT E LSTERR
O 22 'List data not valid '
OQSYSPRT E HDRERR
O 22 'Unknown Generic Header'
List APIs do not automatically create the user space (*USRSPC) to receive the list. You must first create one using the Create User Space (QUSCRTUS) API (2). Similar to CL create commands, the QUSCRTUS API has several parameters that identify the name of the object, the public authority, the object description text, and so forth.
After creating the user space, you can call the QUSLSPL API to return spooled file information into the user space (3). The QUSLSPL API supports two formats: SPLF0100, which returns a fixed set of information about each selected spooled file, and SPLF0200, which returns only user-selected fields. LSTSPL uses SPLF0200 (4) and passes to the QUSLSPL API a list of keys to identify the selected fields (5) and the number of keys (6). Because OPM RPG does not support an array (list) of binary values, LSTSPL defines the key array (KEYARA) as a data structure comprised of contiguous binary(4) fields (7). The fields are initialized to 201, 216, and 211, which correspond to the keys named spooled file name, date file was opened, and total pages, respectively (8). Note that while the user space was created with an initial size of 2000 bytes (2), most List APIs implicitly extend the user space (up to a maximum of 16MB) in order to return all available list entries. The reverse, truncation when the user space is too large, is not performed by list APIs.
Having generated the list, you can now process the user space data.
List APIs (like QUSLSPL) generally provide a generic list header at the beginning of the user space, which provides information such as the API that created the list, the number of entries (spooled files for this example) in the list, the size of each entry, and so on. See User spaces for further information. To access the generic list header, use the Retrieve User Space (QUSRTVUS) API (9). Program LSTSPL retrieves the generic list header into the data structure QUSBP (10), which is defined in the QUSGEN QSYSINC /COPY (include) file (11). Note that languages, such as ILE RPG, COBOL, and C, which support pointers, can avoid this call to QUSRTVUS (and the resulting movement of data) by using the Retrieve Pointer to User Space (QUSPTRUS) API. See Examples: List Object API for examples.
Program LSTSPL now checks that the format of the generic list header is the one expected (12), and if not, prints an error line (13). Having verified the header format, LSTSPL now checks the information status of the list (14) (and if it is not accurate, prints an error line (15)) and that at least one list entry is available (16).
Having determined that accurate list entries are available, LSTSPL does the following:
Within this loop, LSTSPL retrieves each list entry (21), extracts the number of fields returned (22), and enters an inner DO loop to process all of the available list entry fields (23).
Within this inner loop, the program extracts the field information (24) and processes the field data based on the key field (25).
When all fields for a given list entry have been processed, LSTSPL generates a print line (26) and proceeds to the next list entry (27).
When all the list entries have been processed, LSTSPL ends (28).
See the following for the same example in different languages: