Soft-Coded Report Distribution
February 11, 2004 Bruce Guetzkow
[The code for this article is available for download.]
Printer files let programmers separate one type of output from program processing. When a printer file is created, several attributes can be specified (like output queue, copies) to simplify report routing instructions. But over time things change. You may, for instance, need to send reports to a different output queue or change the number of copies. The typical response is to update the affected printer files, provided you have the authority. This article presents an alternative: soft-coded report distribution.
Soft-coded report distribution lets you change printer file attributes and routing without changing the printer file itself. With this template, you can tailor the process to your specific needs.
THE PROCESS
For this method of automating report distribution, we will create a data queue and associate it with an output queue. As spool files are created and placed in this output queue (in RDY status), entries describing the spool files are added to the associated data queue automatically by the system. Report distribution information will be stored in a file. We will create a program to retrieve the data queue entries and distribution information, then process the spool file accordingly.
To simplify the process, I’ve made a few assumptions. First, I’ve assumed that spool files are to be routed to a single output queue and that the only attributes that can be changed are form type, number of copies, whether a report is to be saved after printing, and the user data attribute. Obviously, these assumptions are not sufficient to all needs; however, my purpose is to build a template that can be easily modified as needed.
PHYSICAL FILE
I’ve created this file to allow limited changes to spool files. It can easily be modified based on your needs. Click here to view the DDS for the physical file.
The file is uniquely keyed by the spool file name. Therefore, only a single action can be done to each spool file.
DATA QUEUE AND OUTPUT QUEUE
The next step in automating the report distribution process is to create a data queue and associate it with an output queue. (I’m not going to cover data queues at length in this article. For more information, check out “Data Queue Basics.”
To create a data queue, use the following command:
CRTDTAQ DTAQ(library/dataqueue) MAXLEN(222)
The length of the data queue entry is based on the amount of data the system places into it.
The data queue then needs to be associated with the output queue used. This can be done using either of the following commands. If creating a new output queue, use this command:
CRTOUTQ OUTQ(library/outq) DTAQ(library/dataqueue)
If modifying an existing output queue, use this command:
CHGOUTQ OUTQ(library/outq) DTAQ(library/dataqueue)
PROCESSING THE DATA QUEUE ENTRIES
The program to process the data queue entries (and therefore the spool files) consists of two modules. The first is of type CLLE and it’s the program’s entry module. It uses the API QRCVDTAQ to receive the data queue entry. (Specifics on this API can be found at IBM’s iSeries Information Center. Select Programming, APIs, APIs by category, Object, Data Queue APIs, then Receive Data Queue, or the link to the article above.)
The wait parameter is set to -1, which means the program will wait forever until the next data queue entry arrives. It then calls a procedure (described below) to determine what spool file attributes to change, then processes the change using the Change Spooled File Attributes (CHGSPLFA) command. As each data queue entry is received, the system automatically removes it from the data queue. To see all spool file attributes available from the data queue entry, go to the iSeries Information Center. On the left-hand panel, select Programming, Programming support, and Related information. Click Printer Device Programming (PDF format) and open Chapter 3, then scroll down to the section called “Record type 01 data queue entry format.”
Click here to open the source for the entry module.
The second module is of type SQLRPGLE. It contains the procedure used to determine the spool file attributes stored in physical file REPTDISTPF. Those attributes are then returned to the calling module for processing. Click here to open the source for that procedure.
ENDING THE PROCESS GRACEFULLY
The program processes all entries with *SPOOL in the first 10 characters of the data queue entry. While it is possible to simply end the program via the ENDJOB command, I am a firm believer that programs should be ended gracefully whenever possible. For that reason, the following module can be used to send a blank entry to the same data queue using API QSNDDTAQ. (Specifics on this API can be found at the iSeries Information Center. Select Programming, APIs, APIs by category, Object, Data Queue APIs, then Send Data Queue.)
This entry will not contain *SPOOL in the first 10 characters, so the IF statement following the receive data queue entry step will cause the program to branch to the end and terminate.
Click here to open the source for this module.
OPTIONS
This example is, perhaps, the simplest possible form of report distribution: changing a handful of spool file attributes. You may have other needs that can be accommodated by modifying file REPTDISTPF, procedure #rtvsplfdist, and the processing steps in CLLE REPTDISTCM. You could, for example, send copies to multiple output queues; use command SNDNETSPLF or SNDTCPSPLF instead of CHGSPLFA to send a copy to each user or output queue. You could also save the report as .txt or .pdf file on the Integrated File System (IFS), then modify CLLE REPTDISTCM to call a program (freeware, shareware or commercial) to convert the spool file to the appropriate format. Or you could send the report in an e-mail. Use the previous step to convert the spool file to the appropriate format, then use a command or a program (again, freeware, shareware, or commercial) to send the e-mail with the report attached.
You can even do combinations of the above–send the report to multiple output queues, save the report on the IFS, and send the report as an e-mail attachment–by setting up the right combination of fields in file REPTDISTPF, returning those fields to the calling program, and adding processing steps to handle those steps.
Your challenge is to use this template to develop a process to fit your needs.
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: bruceg@unitedcreditservice.com
This article has been corrected since it was first published. The code for the physical file (code01.txt) and the SQLRPGLE member (code03.txt) described in the article have been replaced. Both files contained several incorrect fields and field lengths. Guild Companies regrets the errors. [Correction made 2/12/04.]
