Administering an IBM i: how the system works · Chapter 8 of 10

The spool: printing and output queues

6 min read · Software

Reviewed on Verified on IBM i 7.5

Log in to save

A program that prints does not talk to a printer. It opens a printer file, and if that file's SPOOL parameter says so, the system puts the output in a spooled file: a document that stays on the system until somebody prints it, converts it or deletes it.

Two things follow. First, the document exists even if the printer does not: it can be viewed on screen, resent, moved, saved as PDF. Second, the document takes disk space, and stays there until someone or something removes it.

How it is organised

  • A spooled file is the single document. It usually has the name of the printer file that produced it: the Print key produces QSYSPRT. The data lives in database members of library QSPL (or QSPLxxxx for an ASP).
  • An output queue (*OUTQ) is an object in a library, and collects spooled files. When a printer is configured, the system creates its default queue in QUSRSYS.
  • A writer is the job that takes documents from a queue and sends them to a printer. It runs in the QSPL subsystem, which has to be active. With no writer started, the queue fills and nothing prints.
WRKSPLF
WRKOUTQ OUTQ(PRODLIB/STAMPE)
STRPRTWTR DEV(PRT01)
WRKWTR

Which queue a document ends up in: if the printer file says OUTQ(*JOB), the job's queue, which comes from the job description; if the job description says *USRPRF, from the user profile; and the profile in turn may say *WRKSTN, the workstation's queue.

Note

"the printout does not come out" has three causes to rule out in this order: the document was never produced (check the job log), the document is queued but the writer is not started (WRKWTR), or the document is in another queue. The chain above is why the third happens when a job description or a profile is changed.

What you can do to a document

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

CHGSPLFA FILE(QSYSPRT) JOB(123456/MROSSI/FATTURE) SPLNBR(3) OUTQ(PRODLIB/RISTAMPE)
HLDSPLF  FILE(QSYSPRT) JOB(123456/MROSSI/FATTURE) SPLNBR(3)
DLTSPLF  FILE(QSYSPRT) JOB(123456/MROSSI/FATTURE) SPLNBR(3)

The content can also be read in SQL, with SYSTOOLS.SPOOLED_FILE_DATA. Without a number it takes the highest-numbered file with that name:

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

Why the disk fills up

Documents do not expire on their own. A nightly report produced every day and never deleted is an archive growing by 365 documents a year, without anybody having decided to keep them.

Seeing the situation per user, in documents, pages and kilobytes:

SELECT USER_NAME, COUNT(*) AS DOCUMENTI,
       SUM(TOTAL_PAGES) AS PAGINE, SUM(SIZE) AS KB
  FROM QSYS2.OUTPUT_QUEUE_ENTRIES
 GROUP BY USER_NAME
 ORDER BY KB DESC

SIZE is in kilobytes, TOTAL_PAGES in pages. Pages are the unit used by whoever decides whether a report is kept; kilobytes are what deleting gets back.

There are three defences:

  1. Automatic cleanup. GO CLEANUP, or the CHGCLNUP command, decides whether cleanup runs, at what time, and after how many days to remove messages, job logs and system output (SYSPRT). Changing it needs *ALLOBJ, *SECADM and *JOBCTL. Once it is on, job logs go to queue QUSRSYS/QEZJOBLOG and dumps to QUSRSYS/QEZDEBUG: whoever looks for them in the old queue no longer finds them.
  2. An expiry on documents. The EXPDATE attribute (with *DAYS and DAYS, 1 to 366) gives a spooled file a date after which it can be removed, and DLTEXPSPLF deletes the expired ones. IBM suggests running it once a day from a job schedule entry. Retention becomes a written rule.
  3. Not producing what nobody reads. Dropping a useless report beats any cleanup, and it is done by asking whoever receives it, not by guessing.

Expired documents can also be seen in SQL, since OUTPUT_QUEUE_ENTRIES has an EXPIRATION_DATE column:

SELECT OUTPUT_QUEUE_NAME, USER_NAME, SPOOLED_FILE_NAME, EXPIRATION_DATE
  FROM QSYS2.OUTPUT_QUEUE_ENTRIES
 WHERE EXPIRATION_DATE < CURRENT DATE

Warning

when spooled files are deleted, the database members that held them stay empty, available for new documents. The system value QRCLSPLSTG says for how many days: 8 by default, then the system deletes them. IBM advises against *NONE (deleting them at once), which adds work to every spooled file creation and can seriously degrade performance. To get the space back at once there is RCLSPLSTG DAYS(*NONE). These are the only two permitted ways to remove those members from the QSPL libraries: IBM warns that any other can cause severe problems.

Getting a document out

  • As PDF, with CPYSPLF ... TOFILE(*TOSTMF) TOSTMF('/path/file.pdf') WSCST(*PDF): the file lands on the IFS, ready to send. Conversion applies to spooled files of type *SCS or *AFPDS.
  • As a text file, with CPYSPLF to a physical file or an IFS file without conversion, when the content is needed by another program. IBM warns that some print information is lost or changed this way.
  • With ACS, downloading the document from the graphical interface, when it is just one.

Sources

Back to the guide index

#spool #stampe #disco
← Back to blog

You might also like

Comments

No comments yet. Be the first to comment!

You need an account to comment. Log in · Sign up