Listing Spool Files
August 11, 2004 Bruce Guetzkow
The code for this article is available for download.
Changing spool file attributes can be a tedious chore. IBM provides the Change Spooled File Attributes (CHGSPLFA) command to simplify this task, allowing you to select a collection of spool files based on several characteristics, but, curiously, output queue is not one of the selection criteria. The solution is the List Spooled Files API (QUSLSPL), used as a front-end to CHGSPLFA. With this API you can select spool files by any combination of user name, output queue, form type, or user data.
CREATING THE LIST
The List Spooled Files API has six required parameters, as well as another 10 that are optional. I will only describe the required parameters and the first optional parameter:
- Qualified user space name (input, 20 bytes, character). Like most IBM list APIs, the results of this API are sent to a user space. The first 10 bytes contain the user space name; the last 10 contain the library name (or *CURLIB or *LIBL).
- Format name (input, 8 bytes, character). There are three options: SPLF0100, SPLF0200, and SPLF0300. I am using the last option, as it is the fastest.
- User name (input, 10 bytes, character). This is the name of the user whose spool files are being selected (or *CURRENT or *ALL).
- Qualified output queue name (input, 20 bytes, character). Specify the name of the output queue containing the spool files you are selecting. The first 10 bytes contain the name of the output queue (or *ALL); the last 10 is the library name (or *CURLIB or *LIBL).
- Form type (input, 10 bytes, character). Specify the form type of the spool files you are selecting (or *ALL).
- User-specified data (input, 10 bytes, character). Specify the user data of the spool files you are selecting (or *ALL).
- Error code (input/output, variable size, character). The standard API error data structure.
I’ve placed the call to this API in a service program as procedure #lstsplf in RPGLE source member SPLFLAPIRM to simplify how it is accessed. The parameter list for the procedure is as follows:
- User space name (input, 10 bytes, character)
- User space library (input, 10 bytes, character)
- User name (input, 10 bytes, character)
- Output queue name (input, 10 bytes, character)
- Output queue library (input, 10 bytes, character)
- Form type (input, 10 bytes, character)
- User data (input, 10 bytes, character)
Procedure #lstsplf returns the message ID from the standard API error data structure, along with 100 bytes of message data. The message ID can be checked in the calling program to determine the success of the call. The prototype for this procedure is found in RPGLE source member SPLFLAPIPR, which I have placed in source file QCPYSRC. If you use a different source file for your copy books, you will need to change the source member accordingly.
To compile, execute the following commands:
CRTRPGMOD MODULE(library/SPLFLAPIRM)
SRCFILE(library/QRPGLESRC)
SRCMBR(SPLFLAPIRM)
CRTSRVPGM SRVPGM(library/SPLFLAPISV)
MODULE(SPLFLAPIRM)
EXPORT(*ALL)
A NEW COMMAND
To demonstrate how to use this API, I’ve created a program and command as an alternative to the CHGSPLFA command. I’ve named this new command CHGSPLFATR and given it the following parameters:
- From User Name (input, 10 bytes, character). Specify the name of the user whose spooled files are being selected (or *CURRENT or *ALL).
- From Output Queue (input, 20 bytes, character). Specify the name of the output queue containing the spool files you are selecting (or *ALL). The library may be *CURLIB or *LIBL.
- From Form Type (input, 10 bytes, character). Specify the form type of the spool files you are selecting (or *ALL).
- From User Data (input, 10 bytes, character). Specify the user data of the spool files you are selecting (or *ALL).
- To Copies (input, 5 bytes, character). Specify the number of copies to change the selected spool files to.
- To Output Queue (input, 20 bytes, character). Specify the output queue to move the selected spool files to.
- To Save File (input, 5 bytes, character). Indicate whether the selected spool files should be saved after printing.
RPGLE source member CHGSPLFATR receives the above parameters, selects spool files based on the “from” parameters, then executes command CHGSPLFA for each, changing the attributes specified on the “to” parameters. I intentionally made this command quite simple, only allowing three attributes to be changed. You can easily change my example to allow additional attributes to be changed if you wish. Let’s review the RPGLE source to see how this is done.
Before any processing can be done, you must first create a user space to place the spool file selections into by executing procedure #crtusrspc. (See “Putting User Spaces in Your Toolbox” for more information on user spaces; the code for this article is available for download here.) I’ve specified user space CHGSPLFATR, in library QTEMP, though any valid name and library will do. The message ID is checked, and if there are any problems, an error message is sent to the user. Since this command is only for demonstration purposes, I’ve chosen to use the DSPLY op code.
Next the program uses the “from” parameters to execute procedure #lstsplf (and API QUSLSPL), to load the user space with a list of spool files matching the selection values. The user space header is then retrieved to get information on how to read the entries from the user space. The “for” loop processes the list of entries from the user space. Data from the receiver variable (rtnds02.rcvvar) is placed in data structure splf0300ds, which identifies the current attributes of each spool file. For this program, I am using attributes that uniquely identify the spool file: spool file name, job name, user name, job number, and spool file number.
Three parameters need special consideration before they can be used with the CHGSPLFA command. The FromOutQ Library parameter must be blanks if the FromOutQ is *ALL. The command definition for the ToCopies parameter indicates that if *SAME is specified, a value of -1 is passed to the program. If this value is received, it must be changed back to *SAME to be used with the CHGSPLFA command. The ToOutputQueue parameter must be formatted to pass either :library/outq or *SAME (no library).
Now that everything is properly formatted, the CHGSPLFA command is constructed by concatenating the command name, keywords, and requested values. When the “for” loop is finished, the user space is deleted and the program ends.
This program uses four copy books, again in QCPYSRC:
- splf0300ds–layout of spool file information returned from QUSLSPL API.
- usrspchdds–layout of user space header.
- splflapipr–prototype of procedure #lstsplf (also used in service program).
- usrspapipr–prototype of user space procedures.
To compile, execute the following commands:
CRTRPGMOD MODULE(library/ CHGSPLFATR)
SRCFILE(library/QRPGLESRC)
SRCMBR(CHGSPLFATR)
CRTPGM PGM(library/CHGSPLFATR)
BNDSRVPGM(SPLFLAPISV USRSPAPISV)
CRTCMD CMD(library/CHGSPLFATR)
PGM(library/CHGSPLFATR)
SRCFILE(library/QCMDSRC)
SRCMBR(CHGSPLFATR)
TRY IT FOR YOURSELF
Now that you can create and process a list of spool files, you can manipulate them as needed. My favorite method is to select spool files by output queue and form type, and then move those files to an output queue that is attached to a printer. This way I can more accurately control which forms are being printed. I’m sure you’ll find this API and service program equally useful.
Bruce Guetzkow has programmed on the AS/400 and iSeries since 1990, in manufacturing, distribution, and other industries. He is currently the IS director at United Credit Service in Elkhorn, Wisconsin. E-mail: bguetzkow@itjungle.com
