Solutions for cleaning up an output queue don’t come easily. IBM’s CLROUTQ deletes everything, and pressing 4 and Page Down multiple times on the WRKOUTQ command is time-consuming. However, now you have another option to consider. The utility outlined in this article allows you to use the QUSLSPL API to delete selective entries out of an output queue by form type, user data, user profile, or date.

Things have been quiet in the office for a while. There have not been many cases to solve in quite some time. Then, my system operator storms in, piercing the quiet with the shrill tone of frustration in her voice.

“There has got to be a better way of cleaning up these pick slips in my output queue besides typing a 4 beside the ones I want to remove and paging up and down. That takes too much time.”

My system operator is normally a quiet, hard-working woman. When the tone of her voice rises, I know something is wrong. You see, I am an information services manager, and she works for me. One thing I do not want is an unhappy employee, especially when I can do something about the cause of her unhappiness.

But first, let me explain her comment. In our office, we print the pick slips each morning for that particular day, and then we pass them on to different departments. Sales takes its stock orders and passes them directly to shipping. Materials control takes its regular orders, filing them in the appropriate boxes, and the shop supervisors come and get what they need.

With this many people handling paper, things tend to get lost. Eventually, someone will storm in claiming that he did not get a particular pick slip. We keep the spooled entries on a save status (OVRPRTF FILE(...) SAVE(*YES)) and then delete the entries after a few days. That way, we can look and see what pick slips have been printed and save ourselves potential problems with duplicate pick slips. On a heavy day, deleting these entries takes several Page Downs on a Work with Output Queue (WRKOUTQ) screen, as shown in Figure 1. The point my operator was making was that she was sick and tired of all this

paging up and down while pressing 4. It was a good point, so I called one of my programmers into the office.

“Did you hear that?” I asked. “Yes, I did. It seems like there’s something we should be able to do.” “There is. Ever work with APIs?” “Nope, but I think I am about to,” replied the programmer.

On the Case

We decided that building a utility to selectively clean an output queue would be best served by using an API as opposed to printed output or output files from a command. The printed output and output files tend to change from release to release, but APIs are more consistent. Looking through the API manuals, lo and behold, we found an API called List User Spooled Files (QUSLSPL). As is the case with a lot of APIs, QUSLSPL writes to a different kind of animal called a user space. So, we also had to look up two other APIs: Create User Space (QUSCRTUS) and Retrieve User Space (QUSRTVUS).

The reason I call the user space “a different kind of animal” is that it’s a space for data, similar to a file, but there is no database overhead for the file. It’s missing the clear and defined fields and record lengths that you are used to when reading and writing file data. To “read” a user space, you need to use the QUSRTVUS API to retrieve some parameters from the header portion of the user space—such as header length, data offset, number of entries, and entry length—and then read the data with the same API.

This utility inputs an output queue, a form type, user data, a user profile, and a date. It then deletes entries in an output queue that match those values. The utility is designed so that someone like my system operator can clean out her pick slips by a session date format (which is exactly what she does with the press-4-Page-Down option of the WRKOUTQ screen). I also threw in some other goodies so that others could use the same utility for additional purposes, such as deleting certain form types, output of one user, and so on.

To start the utility, a command processing program (CPP) called HAP056C checks for the existence of an output queue. If the queue is not found, an error message is issued. If the queue is present, HAP056C continues on to perform the desired tasks.

The CPP then calls HAP056 (see Figure 2), an RPG program that uses the QUSLSPL API to list all spooled files to a data area. HAP056 meets most of the criteria passed to it from the command. The only parameter that QUSLSPL will not process is the date of the spooled entry. For that, I pass key 216 to the QUSLSPL API (the keys determine what information you need from the API). Key 216 specifies that I want the date of the spooled file for later comparison. The other keys (201, 202, 203, 204, and 205, which are for the spooled file name, job number, user, job name, and spool file number) are meant to build the parameters for the Delete Spooled Files (DLTSPLF) command. Other than the date, QUSLSPL creates a clean list of the files in that output queue with those parameters. To include the date, I compare the date of the spooled file with the date of the delete request. If they are equal, then I call a second CL program (HAP056AC) to perform the actual delete.

The RPG code is not complicated, but you need to do a lot of setup. You need to create data structures for error routines, reading the user space header and detail, a list of items you want from the API, and some miscellaneous binary variables. There are parameter lists for everything from the parameters passed to the program (*ENTRY) to creating the user space.

It’s Elementary!

I sent the programmer to work on what we talked about, and he came up with a number of programs. (To see all of the programs, go to MC’s Web site at http://www.midrangecomputing.com/mc/98/12.) HAP056C is the CPP for the CLNOUTQ command. HAP056 is the RPG program that creates a list of the spooled files that match the selection criteria, and HAP056AC does the delete.

I made sure that the programmer tested the code thoroughly. Unbeknownst to him, I also helped to test it. Like a good manager, I let that programmer take all of the accolades for his work. I sat back, confident in the knowledge that he had won this one small battle with an irate user. And from here, the war is looking good, too.

Reference

OS/400 Print APIs V4R2 (SC41-5874-01, CD-ROM QB3AMZ01)

Queue: PRT03PCS Library: QUSRSYS Status: RLS/WTR

Type options, press Enter.

1=Send 2=Change 3=Hold 4=Delete 5=Display 6=Release 7=Messages

8=Attributes 9=Work with printing status

Opt File User User Data Sts Pages Copies Form Type Pty

4 HAE275O BARBARA HAE276 SAV 1 1 2PT11X8 5

4 ORD561Z BARBARA HAE202 SAV 1 1 2PT11X8 5

4 ORD561Z TIM HAE202 SAV 1 1 2PT11X8 5

4 HAE275O TIM HAE276 SAV 1 1 2PT11X8 5

4 ORD561Z TIM HAE202 SAV 1 1 2PT11X8 5

4 HAE275O TIM HAE276 SAV 1 1 2PT11X8 5

4 ORD561Z TIM HAE202 SAV 1 1 2PT11X8 5

4 HAE275O TIM HAE276 SAV 1 1 2PT11X8 5

4 HAE275O TIM HAE276 SAV 1 1 2PT11X8 5

More...
Parameters for options 1, 2, 3 or command
===>

F3=Exit F11=View 2 F12=Cancel F20=Writers F22=Printers
F24=More keys

*===============================================================

* To Compile:

*

* CRTRPGPGM PGM(XXX/HAP056) SRCFILE(XXX/QRPGSRC)

*

*===============================================================

F/TITLE HAP056 - Clear from Output Queue

*IAPIERR DS

I B 1 40ERRPRV

I B 5 80ERRAVL

I 9 15 ERRID

I 17 96 ERRPDT

* API General Header

IAPIHDR DS

I B 125 1280GUSOFF

I B 133 1360GUSNBE

I B 137 1400GUSLEN

* Spool File Header Data (SPLF0200)

ISPLHDR DS

I 1 10 SPHUSR

I 11 20 SPHOTQ

I 21 30 SPHOQL

I 31 40 SPHFRM

I 41 50 SPHUDT

I B 83 860SPHNKY

I 87 102 SPHNU1

I 103 112 SPHNAM

* Spool File Header Data for fields

ISPLHD2 DS

I 21 30 SPANAM

I 49 58 SPAJOB

I 77 86 SPAUSR

I 105 110 SPAJBN

I B 129 1320SPANUM

I 149 155 SPDATE

* Data Structure for binary variables

I DS

I B 1 40SPLKEY

I B 5 80GUSSPO

I B 9 120GUSHLN

I B 13 160SPSIZE

Figure 1: Deleting multiple spool files off the Work with Output Queue (WRKOUTQ) display can be tedious

I B 17 200SPALRV

* Binary DS for QUSLSPL list of keys

I DS

I 1 24 SPLK

I B 1 40SPLK1

I B 5 80SPLK2

I B 9 120SPLK3

I B 13 160SPLK4

I B 17 200SPLK5

I B 21 240SPLK6

*

I 'HAP056 QTEMP 'C USRSPN

I 'SPLF0200' C FORMAT

I X'00' C INTVAL

I 'User Space/CLROUTQ' C TEXT

* First, create the user space

C CALL 'QUSCRTUS'USRSPC

* Now, let's list the spooled files to a data area

C CALL 'QUSLSPL' SPLIST

*Get header data from user space *

C Z-ADD1 GUSSPO

C CALL 'QUSRTVUS'GTUSHD

C GUSOFF ADD 1 GUSSPO

*

C CALL 'QUSRTVUS'GTUSDT

* Loop around until the number of entries are exhausted in

* the user space

C DO GUSNBE

** Get the attributes of the spooled file

C CALL 'QUSRTVUS'GTUSD2

* Check dates

C SPDATE IFLE SPCYMD

* Work Field for the spooled file number

C MOVE SPANUM WRKFL6 6

* Call program to do the delete (DLTSPLF)

C CALL 'HAP056AC'HAP056

C ENDIF

C ADD GUSLEN GUSSPO

C ENDDO

C MOVE *ON *INLR

*

C *INZSR BEGSR

* initialize user space creation variables

C MOVELUSRSPN SPACNM

C Z-ADD8192 SPSIZE

C MOVE INTVAL SPIVAL

C MOVEL'*CHANGE' SPAUTH

C MOVELTEXT SPTEXT

C MOVEL'*YES' SPREPL

* initialize user space list variables

C MOVELFORMAT SPFMT

C MOVEL'*ALL' SPUSNM

C Z-ADD6 SPLKEY

C Z-ADD201 SPLK1

C Z-ADD202 SPLK2

C Z-ADD203 SPLK3

C Z-ADD204 SPLK4

C Z-ADD205 SPLK5

C Z-ADD216 SPLK6

* Get User Space Detail Parameter list

**

C Z-ADD140 GUSHLN

C CLEARAPIHDR

C HAP056 PLIST

C PARM SPANAM

C PARM SPAJBN

C PARM SPAUSR

C PARM SPAJOB

C PARM WRKFL6

C GTUSDT PLIST

C PARM SPACNM

C PARM GUSSPO

C PARM GUSHLN

C PARM SPLHDR

C PARM APIHDR

* Get User Space Header Parameter list

C GTUSHD PLIST

C PARM SPACNM

C PARM 1 GUSSPO

C PARM GUSHLN

C PARM APIHDR

* Get User Space Detail Parameter list - 2

C GTUSD2 PLIST

C PARM SPACNM

C PARM GUSSPO

C PARM GUSLEN

C PARM SPLHD2

C PARM APIHDR

* List spooled files parameter list

C SPLIST PLIST

C PARM SPACNM 20 usrspc name

C PARM SPFMT 8 format

C PARM SPUSNM 10 user name

C PARM SPOUTQ 20 output queu

C PARM SPFORM 10 formtype

C PARM SPUSRD 10 user data

C PARM APIERR

C PARM SPLJBN 36 job name

C PARM SPLK

C PARM SPLKEY

*

* Create User Space Parameter list for List of spooled files

C USRSPC PLIST

C PARM SPACNM

C PARM SPATTR 10

C PARM SPSIZE

C PARM SPIVAL 1

C PARM SPAUTH 10

C PARM SPTEXT 50

C PARM SPREPL 10

C PARM APIERR

*

C *ENTRY PLIST

C PARM SPOUTQ

C PARM SPFORM

C PARM SPUSRD

C PARM SPUSNM

C PARM SPCYMD 7

C ENDSR

Figure 2: The RPG program that determines whether or not to delete a spooled file based on the input date