AS/400-iSeries Starter Kit

In applications that must handle spooled files, you may need a way to determine when spooled files arrive on an output queue. For instance, your application may need to automatically transfer any spooled file that arrives on a particular local output queue to a user on a remote system. Or perhaps you want to automatically distribute copies of a particular spooled file to users in the network directory. You may even want to provide a simple function that transfers all spooled files from one output queue to another while one of your printers is being repaired. In any case, you must find a way to monitor an output queue for new entries.

The Old Solution

If you are running pre-V2R2 OS/400, you can write a program that uses the following tried-and-true approach:

• Wake up periodically and perform a WRKOUTQ (Work with Output Queue) command specifying OUTPUT(*PRINT)
• Copy the output to a database file
• Read the database file and look for spooled file entries
• Determine whether an entry is new on the queue (you must be creative here)
• Perform the appropriate action for any new spooled files

Another option is to use the CVTOUTQ tool from the QUSRTOOL library or the version offered in Chapter 24, "CL: You're Stylin' Now!" Both of these utilities convert the entries on an output queue to a database file, which you can then read and search for new spooled file entries.

If you simply want to take a snapshot of all the entries on an output queue at any given time, you can do so easily with the approach outlined above or with either of the CVTOUTQ tools. Such a capability is useful when you want to perform a function against some or all of the spooled files on a queue and then delete those spooled files before taking the next snapshot. However, all these methods lack one fundamental ability that some applications require: the ability to easily identify new spooled file entries as they arrive on the output queue.

A Better Solution

With V2R2, you can easily determine when a new spooled file arrives on an output queue. The V2R2 versions of the CRTOUTQ (Create Output Queue) and CHGOUTQ (Change Output Queue) commands let you associate a data queue with an output queue. When you do, and a spooled file becomes ready (a "RDY" status) on the output queue, OS/400 will send an entry to the associated data queue. The entry identifies the new spooled file, so your program can monitor the data queue and take appropriate action whenever a new spooled file appears.

A spooled file is always in one of several statuses on an output queue (e.g., RDY = ready, HLD = held). We are interested in the "RDY" or "ready" status. The "ready" status signifies that a spooled file is ready to print. When a spooled file arrives on the output queue and is in the "RDY" status, OS/400 sends an entry to the attached data queue (if one is attached). If you then hold that spooled file entry and again release the entry, another data queue entry is sent to the data queue. Each time a spooled file becomes ready to print on the output queue, an entry is sent to the data queue.

Figure 11.1 shows the prompt screen for the CHGOUTQ (Change Output Queue) command. For the DTAQ keyword, a value of *NONE indicates that no data queue is associated with the output queue. If you enter the name of a data queue, OS/400 will send an entry to that data queue when a spooled file arrives on the associated output queue. The only requirement for entering a data queue name is that the data queue exist. The value *SAME for the DTAQ parameter indicates no change to the existing parameter value.

Figure 11.2 shows the prompt screen for the CRTDTAQ (Create Data Queue) command. A data queue associated with an output queue must have a MAXLEN value of at least 128. You can specify a longer MAXLEN, but the data queue entry that describes the spooled file will occupy only the first 128 positions. After you create the data queue and use the CHGOUTQ command to associate the data queue with an output queue, OS/400 will create a data queue entry for every spooled file that arrives on that output queue until you again execute the CHGOUTQ command and specify DTAQ(*NONE) to stop the function.

Figure 11.3 represents the field layout of the spooled file data queue entry as documented in the Guide to Programming and Printing (SC41-8194). You can use a data queue defined longer than 128 bytes, but not shorter, since the entry uses 128 bytes for each entry.

The STRTFROUTQ Utility

One way you could use this new feature is to automatically transfer spooled files arriving on one output queue to another output queue. Such a utility is useful when a printer breaks and you want to reroute the broken printer's output to another printer. Because a printer can have only one output queue, you can't simply have another printer print the broken printer's output queue as well as its own. Formerly, an operator would have had to monitor the output queue and manually transfer the spooled files to another output queue. Users waiting for reports (especially if they have to walk to a remote printer to get them) don't like having to wait for the operator to transfer the spooled files or having to transfer the files themselves.

Figure 11.4 shows the source for the STRTFROUTQ command, a utility that incorporates the V2R2 data queue feature to automatically transfer spooled files from one output queue to another. Besides transferring spooled files, this simple, useful utility illustrates the use of the data queue capability.

To use STRTFROUTQ, you enter both a source and a target output queue. The source output queue is the one the program will monitor for new arrivals. The target output queue is the one to which the spooled files will be transferred.

Figure 11.5 (41 KB) is the source for command processing program (CPP) STRTFROTQC. This program is the workhorse that actually identifies and transfers the spooled files. STRTFROTQC first checks that both the source and target output queues exist. If either does not, the program sends a message to the program queue and then ends, which causes the error message to be sent to the calling program. (Because you would normally be running this job in batch, the message would then be forwarded to the external queue -- the system operator.)

When both the source and target output queues exist, the program associates a data queue with the source output queue. If a data queue with the same name as the source output queue already exists in library QGPL, the program uses it. If such a data queue does not exist, the program creates one. I chose to put the data queue in library QGPL because all AS/400s have a library named QGPL, but you can use any other available library instead. After making sure the data queue exists, the program uses the CHGOUTQ command to associate the data queue with the source output queue.

At this point, the program enters "polling" mode. At B in Figure 11.5, the program executes the RCVDTAQE command, a front end I wrote for the QRCVDTAQ API (for the code for my front ends to the data queue APIs, see "A Data Queue Interface Facelift" — 151 KB). There is no equivalent OS/400 command. The four parameters listed at B are required; five optional parameters also exist for RCVDTAQE, but we don't need them here. The required parameters are

• DTAQ, the qualified data queue name (20 alphanumeric)
• DTALEN, the length of the data queue entry (5,0 decimal)
• DATA, the data queue entry (i.e., the data) (n alphanumeric; length as defined in previous parameter)
• WAIT, how long the program should wait for an entry to arrive on the data queue (1,0 decimal; negative for a never-ending wait, n for number of seconds to wait, or 0 for no wait at all)

After receiving the data for an entry, STRTFROTQC extracts the needed fields. The first field it extracts is the &end_flag field. This field, which is used later to end the program, is not part of the OS/400-supplied spooled file data queue entry. I'll explain the use and significance of this field in a moment.

The values for &job, &user, &jobnbr, and &splf are all extracted from the data queue contents and transferred to character variables using the CHGVAR (Change Variable) command. Because the spooled file number is stored in binary, the CHGVAR command that extracts it uses the V2R2 %BIN or %BINARY function (D) to extract the value into a decimal field. Once the field values are extracted, the program executes the CHGSPLFA (Change Spooled File Attributes) command to move the spooled file identified in the data queue entry to the target output queue.

Now back to that &end_flag field. After you execute the STRTFROUTQ command, the job will wait indefinitely for new data queue entries because STRTFROTQC assigned variable &wait a negative value (A). You could use the ENDJOB (End Job) command to end the job, but this solution is messy: It doesn't clean up the data queue or the associated output queue. When you use data queues, you must be a careful housekeeper. Data queue storage accumulates constantly and is not freed until you delete the data queue.

A more elegant ending to such an elegant solution is the ENDTFROUTQ command and its CPP, ENDTFROTQC, shown in Figure 11.6 and Figure 11.7 (20 KB), respectively. When you are ready to end the STRTFROUTQ job, just enter the ENDTFROUTQ command and specify the name of the source output queue for the SOUTQ parameter. The CPP then sends a special data queue entry to the associated data queue; this entry has the value *TFREND in the first seven positions. Program STRTFROTQC checks each received data queue entry for the value *TFREND (C in Figure 11.5). When it detects this value, the program ends gracefully after deleting the data queue and disassociating the output queue so that no more data queue entries are created (E).

If you collect utility programs, you will want to have the STRTFROUTQ and ENDTFROUTQ utilities in your toolkit. By taking advantage of a little-known OS/400 function, these commands make spooled file management a little easier and more efficient.