The spool: printing and output queues

A program that prints does not talk to a printer. It produces a spooled file, an object holding the document, which stays on the system until somebody prints it, converts it, or deletes it.

Two things follow. The first is that the document exists even when the printer does not: you can view it, send it later, move it, save it as PDF. The second is that the document takes disk space, and nobody deletes it for you.

How it is organised

• A spooled file is a single document produced by a job.
• An output queue (*OUTQ) is an object in a library, collecting spooled files. Every job has a default one, coming from its job description or from the user profile.
• A writer is the job that takes documents from a queue and sends them to a printer. With no writer started, the queue fills and nothing prints.

WRKSPLF
WRKOUTQ OUTQ(PRODLIB/PRINTS)
STRPRTWTR DEV(PRT01)
WRKWTR

What can be done to a document

A spooled file is identified by name, number and producing job, because the same job can produce many with the same name:

CHGSPLFA FILE(QSYSPRT) JOB(123456/JSMITH/INVOICES) SPLNBR(3) OUTQ(PRODLIB/REPRINTS)
HLDSPLF  FILE(QSYSPRT) JOB(123456/JSMITH/INVOICES) SPLNBR(3)
DLTSPLF  FILE(QSYSPRT) JOB(123456/JSMITH/INVOICES) SPLNBR(3)

From release 7.3 the contents can also be read in SQL, which makes a document searchable without scrolling through it:

SELECT ORDINAL_POSITION, SPOOLED_DATA
  FROM TABLE(SYSTOOLS.SPOOLED_FILE_DATA(
       JOB_NAME          => '123456/JSMITH/INVOICES',
       SPOOLED_FILE_NAME => 'QSYSPRT',
       SPOOLED_FILE_NUMBER => 3))

Why the disk fills up

This is why the chapter exists. On a system in production for years, spool along with the IFS is the first cause of consumed space, for a mundane reason: documents do not expire. A nightly report produced every day and never deleted is an archive growing by 365 documents a year, without anyone having decided to keep them.

Seeing where you stand:

SELECT USER_NAME, COUNT(*) AS DOCUMENTS,
       SUM(SIZE) / 1024 / 1024 AS MB
  FROM QSYS2.OUTPUT_QUEUE_ENTRIES_BASIC
 GROUP BY USER_NAME
 ORDER BY MB DESC

There are three defences, in order of how well they hold up over time:

1. The system's automatic cleanup. GO CLEANUP configures periodic removal of job logs and system output queues. It is the minimum, and on many systems it was never turned on.
2. An expiry on documents. The EXPDATE / DAYS attribute makes spooled files expire, and DLTEXPSPLF deletes the expired ones. Retention then becomes a written rule instead of a cleanup somebody remembers to do.
3. Not producing what nobody reads. On an older system a share of the nightly reports has not been looked at for years. Removing them beats any cleanup, and it is done by asking, not by inferring.

Getting a document out

The three routes actually used:

• To PDF, with CPYSPLF ... TOSTMF(...) WSCST(*PDF) or through print transformation, landing on the IFS ready to be sent;
• To a text file, with CPYSPLF into a physical file or an IFS file, when the contents are for another program;
• With ACS, which downloads a document to the PC from the graphical interface and is the simplest route for a one-off.