13.3 The AIX Spooling Facility

AIX offers a third approach toprinting and spooling. It is based on AIX's general queueing system; printing is just one predefined way to use it. The queueing system's general operation is illustrated in Figure 13-5.

Figure 13-5. The AIX queueing system

Jobs are submitted to a queue by users using the qprt or enq commands (or another user command that calls them). A file printed using these commands is linked to the spooling area by default, so if the file changes or is deleted before the job actually prints, the output will be affected (the -c option may be used to copy the file to the spooling area with either command). Print requests are stored in /var/spool/lpd/qdir, and any spooled files are stored in /var/spool/qdaemon.

AIX also supports the BSD and System V user print commands for ease-of-use purposes: lp, cancel, lpstat, lpr, lpq, and lprm.

The queues are monitored by the qdaemon daemon, which schedules and initiates jobs. When it is time for a job to execute, qdaemon sends the corresponding file to the queue's backend program for processing. In the case of printing on the local system, the program is /usr/lib/lpd/piobe, but in theory, any program may be used as a backend (this is discussed further later in this section). The output of the backend program is then sent to a specified physical device in the case of local printing. It may also be directed to a file.

SMIT provides an excellent interface to the queueing system, and it is usually the easiest way to create and configure queues and their associated devices. In this section, we will look at all of the components of the queuing system individually so that you will understand how the system works, even if you choose to use SMIT to make administering it easier. The SMIT fastpaths mkpq and chpq will take you directly to the forms to create and modify queues and their associated printing devices.

13.3.1 Manipulating Print Jobs

The enq command is the main interface to the printing system. It can be used by users to initiate print requests and by the system administrator to alter the status of print jobs and queues. AIX also provides a series of more intuitively named utilities, which are effectively aliases to subsets of enq's functionality: qprt (print), qcan (cancel a job), qchk (check the status of a job or queue), qmov (move jobs from one queue to another), qadm (administer the subsystem), and others. Their options work the same as the corresponding enq options.

13.3.1.1 Job numbers

Each print job is assigned a unique job number within the queueing system, by which it may be referred to in subsequent commands. Unfortunately, it is often not displayed by default. However, the print submission commands enq -j, lpr -j, and qprt -#j will all display the job number assigned to a print job at the time it is submitted. lp displays job numbers by default. Alternatively, the job number may be determined via the qchk command (described in a bit).

13.3.1.2 The default print queue under AIX

On all AIX printing-related commands, the -P option is used to specify the desired queue; if it is omitted, then the system default queue the first one listed in /etc/qconfig will be used. Users can set their own default printer via the PRINTER or LPDEST environment variables. Note that the latter always takes precedence over the former, even when the BSD-compatible lpr command is used to submit the print job.

13.3.1.3 Displaying job and queue status information

The qchk command display status information about print jobs and queues. Its -q option may be used to display the status of a specified queue. For example, the following command lists the status of the queue laser3:

$ qchk -q -P laser3  Queue   Dev     Status    Job  Files   User     PP  %    Blks Cp Rnk  ------- -----   --------  ---  ------  -------- --- --  ----- -- ---  laser3  dlas3   RUNNING    30  l213.f  chavez    10 43    324  1   1                 QUEUED     31   hpppp  harvey              41  1   2                 QUEUED     32   fpppp  harvey              83  1   3                 QUEUED     33  x27j.c  king               239  1   4

The columns in the report hold the queue name and device (which are not repeated on subsequent lines), the job status, job number, file to be printed, submitting user, pages printed so far, percentage of the job printed so far, job size in blocks, number of copies requested, and rank within the queue for each job in the queue.

When a queue is down, the first line of the display will look like this:

laser3 dlas3   DOWN

Other useful options to qchk for listing queue contents are -A (replaces -q to list all queues), -L (for a long listing format), and -u followed by a list of users to limit the display to jobs submitted by those users. For systems with large numbers of print jobs, where three-digit job numbers are not sufficient, add -W to the qchk command to display the full job numbers.

13.3.1.4 Deleting print jobs

To delete a job in a print queue, use the qcan command:

# qcan -x job-number

where job-number is the number of the job to be removed; since job numbers are unique across the entire queueing system, the queue name isn't needed. All jobs in a queue may be deleted with the -X option:

# qcan -P laser -X

When run as the administrator, this command removes all jobs from queue laser. If the specified queue is used for remote printing (described later in this section), the command will affect only jobs that haven't yet been transferred to the remote system.

13.3.1.5 Moving jobs between queues

Pending print jobs may be moved between print queues using the qmov utility. Here are some examples using qmov:

# qmov -m laser -# 8 # qmov -m laser -P inkjet # qmov -m laser -P inkjet -u chavez

The first qmov command moves job 8 from its present queue to the laser queue. The second command moves all jobs currently in the inkjet queue to the laser queue. The third command moves all of user chavez's jobs in the queue inkjet to the queue laser. qmov will not move a currently printing job, and you'll get an error if there are no jobs matching your specifications in the source queue.

13.3.1.6 Suspending print jobs

The qhld command holds and releases jobs in print queues. For example, this command places print job 8 on hold:

# qhld -# 8

This command places all jobs currently waiting in the queue laser on hold:

# qhld -P laser

qhld's -r option releases a previously held job:

# qhld -r -# 8 # qhld -r -P laser

The qprt -#h and enq -H commands may be used to submit a job to a queue in an initial held status.

13.3.1.7 Print job priorities

Jobs are assigned priorities within the queue. Together with the queue discipline parameter (described below), these priorities determine the order of printing. Priorities range from 0 to 20 for ordinary users (the default is 15); users in the group system may use priorities up to 30. Any user may alter the values for his own jobs; the system level (21-30) is the only way for an administrator to guarantee that a job she moves up will stay above the others. Higher-numbered jobs print sooner.

Users can assign a priority to a job when they submit it with qprt's -R option. To change the priority of a pending job, use the enq -R command:

# enq -# job-number -R new-priority

For example, the following command changes the priority of job number 45 to 22:

# enq -# 45 -R 22

13.3.2 Managing Queues and Devices

AIX makes a distinction between queues and devices and requires them to be configured and managed as separate objects. Each queue has one or more associated devices, which are the entities that map one-to-one with physical printers. Similarly, a printing device can have more than one queue feeding it.

The following qadm options control individual device status:

-D dev: Designate a device as down; no more jobs will be sent to it, but current jobs will finish.
-U dev: Bring a device back up.
-K dev: Same as -D, but current jobs are killed.

If a queue has only one device associated with it, the queue name alone will suffice to designate the device. If more than one device is controlled by the queue, you must specify which one you want by appending its name to the queue name, using a colon as separator. For example, the following command brings the lp0 device of the queue laser down:

# qadm -D laser:lp0

Jobs can still be sent to the queue even when its device(s) are down. An entire queue may be disabled by changing its up attribute in /etc/qconfig to FALSE, a task that can be accomplished with the chque command. For example, the following command disables the queue laser:

# chque -q laser -a "up = FALSE"

The spaces around the equal sign, the quotation marks, and the uppercase letters on the keyword are all required.

When a queue has been disabled, its devices are automatically taken down; they will need to be brought back up (with qadm -U) when the queue is reenabled.

Current AIX documentation still states that the queueing system should be shut down before changes like disabling a queue are performed, using these commands:

# chgsys -s qdaemon -O      Turn off autorestarting # enq -G                  Stop the queueing subsystem

However, these commands no longer seem to be effective under AIX 5, and the qdaemon process is immediately restarted anyway. Nevertheless, it is only prudent to wait to make major configuration changes to a print queue until current jobs have completed, pending jobs have been deleted or moved, and the associated device(s) have been disabled with qadm -D.

13.3.3 The qdaemon Server Process

The qdaemon server is managed by the System Resource Controller. It is started from the inittab file via an entry like this one:

qdaemon:23456789:wait:/usr/bin/startsrc -sqdaemon

You can check its status with the following command:

# lssrc -s qdaemon Subsystem        Group            PID      Status qdaemon          spooler          311412   active

13.3.4 Configuring Queues: The /etc/qconfig File

Queues are defined in the /etc/qconfig file. Each queue has one or more associated devices, which are the entities that map one-to-one with physical printers. The linked pair of a queue and a device is sometimes referred to as a virtual printer. We'll begin by looking at the structure of the queue configuration file and then go on to consider the commands that are typically used to manipulate it.

The queue configuration file is an ordinary text file, but it should be edited directly only with great caution and by administrators who are intimately familiar with the entire qdaemon subsystem. Very minor setting changes are usually safe to make, but adding new queues and devices should be done with the commands provided or with SMIT, as they create or modify entries in the ODM which are not easy to perform manually.

In general, a print queue definition has the following form:

queue-name:     device = qdev1[,qdev2  . . . ]     attribute = value      . . .  qdev1:     backend = /usr/lpd/piobe     attribute = value      . . .   [qdev2:     backend = /usr/lib/lpd/piobe     attribute = value      . . . ]

Here are two sample print queue entries from /etc/qconfig:

lpt:                                A queue named lpt    device = lp0 lp0:                                Its associated device    file = /dev/lp0    header = never    trailer = never    access = both    backend = /usr/lib/lpd/piobe  laser:                              A queue named laser    device = lp0,lp1                 Queue laser's two devices    acctfile = /var/adm/qacct  lp0:        file = /dev/lp0                  The first device, listed again    header = always    trailer = never    access = both    backend = /usr/lib/lpd/piobe lp1:                                The second device    file = /dev/lp1    header = never    trailer = never    access = both    backend = /usr/lib/lpd/piobe

Each full definition has several parts. The first is the queue definition, beginning with a header line consisting of the queue name followed by a colon. In the example, lpt and laser are the two queue header lines. Next, indented with respect to the header, are queue attribute definitions. The queue lpt has only one attribute defined: its device, lp0. laser's stanza specifies two devices, lp0 and lp1, and defines a file in which to place accounting data.

The definitions for a queue's device(s) must immediately follow the queue definition. Hence, lp0 is defined after lpt, and lp0 and lp1 are defined after laser. Although both queues use device lp0, its definition must still be repeated in each queue definition. In fact, as in our example, the settings for the device may differ, and each set will apply only to jobs printed on that device from the corresponding queue.

When a queue has multiple associated queue devices, it is used to feed jobs to all the devices, which are assumed to be equivalent. When it is time for a job to be spooled, qdaemon will send it to the first available device for its queue. When more than one queue services the same device, as in the preceding example, then the spooler alternates among them, regardless of the relative sizes, priorities and age of the jobs within them (such characteristics are compared only among jobs in the same queue to determine printing order, not across queues).

The most important queue and device attributes are listed in Table 13-5.

Table 13-5. Important AIX queue and device attributes
Attribute	Meaning
Queue attributes
acctfile	Accounting file pathname (the default is not to use any accounting file).
device	List of associated device names.
discipline	Job selection algorithm: fcfs for first come, first served or sjn for shortest job next (the default is fcfs).
up	Set to TRUE or FALSE, depending on whether the queue is enabled or disabled.
Device attributes
access	Available access to printer device: one of write (meaning only write access) or both (read-write access). The latter is the default.
align	Whether to send a form feed before starting a job if the printer is idle (default = TRUE).
backend	Path to the backend program.
file	Special file associated with the device as defined in the ODM (which is not the same as the raw port's special file).
header	When a header page should be placed before a job. Valid keywords are: never (the default setting), always, and group (print header only once for multifile print jobs).
trailer	When a trailer page should be sent (same keywords and default value as for header).

The easiest way to view the attributes of a queue or queue device is to view the queue configuration file.

If you'd like all of the gory details about a printer, use the following command:

# lsvirprt -q queue -d device | more

13.3.4.1 Creating and modifying print queues

SMIT provides the easiest method for creating and modifying print queues. Its use is illustrated in Figure 13-6.

Figure 13-6. Creating a print queue with SMIT

If you follow the stack of dialogs from the bottommost (at the top left) to topmost (top right), you will see the successive prompts generated by SMIT to obtain the information necessary to create a new printer device and queue(s) to feed it. Here we add a new local printer, attached via a serial port (specifically, port 0 attached to the sa0 adapter). The printer is an IBM 4076 inkjet printer, and we create a queue for PostScript jobs named color_ps. Optionally, we could have created several different queues for this printer, each designed to handle a different type of print job. The final dialog also allows you to configure various serial line settings.

AIX provides several commands that may be used to create and configure printer devices and queues in a similar manner. For example, the following command may be used to create a queue and device similar to what we just accomplished with SMIT (in this case, we add a generic type printer):

# /usr/lib/lpd/pio/etc/piomkpq \      -A local \                 A local printer      -p generic \               Generic printer type      -v osp \                   ODM data type (list with lsdev -P -c printer)      -s rs232 -r sa0 -w 0 \     Uses the specified serial adapter and port      -D asc -q text1 \          A queue for ASCII data      -D ps -q ps1               Another queue for PostScript data

Printer type definitions are stored in /usr/lib/lpd/pio/predef. The entire collection might not be included in the operating system installation and often must be installed manually later.

Here is the command for adding a similar printer attached to a parallel port:

# /usr/lib/lpd/pio/etc/piomkpq -A local -p generic -v osp \      -s parallel -r ppa0 -w 0   Parallel port information      -D asc -q text2

The following command adds an additional, previously defined device to an existing queue:

# /usr/lib/lpd/pio/etc/piomkpq -A local -p generic \      -d lp2 -D asc -Q text0     Both the device and the queue already exist.

The device options are replaced by -d, and the queue is specified with -Q rather than -q.

The chque and chquedev commands may be used to change the attributes of queues and devices, respectively, as in these examples:

# chque -q laser -a "discipline = sjn" # chquedev -q laser -d lp0 -a "header = never"

The first command changes the discipline attribute for queue laser to sjn (shortest job next). The spaces around the equal sign are required. The second command changes the header attribute for the laser queue's device lp0 to the value never. Be aware that this change will affect the printer on that device only when it is accessed from queue laser.

The rmquedev and rmque commands may be used to remove devices and queues (respectively):

# rmquedev -q tek -d lp2 # rmque -q tek

These commands remove the device for the queue tek and then the queue itself (queues can be deleted with rmque only after all their devices are gone). However, the device lp2 is still defined in the ODM. If you should ever need to remove it, you can verify its existence and then remove it with these commands:

# lsdev -C -l lp2 lp2 Available 01-S3-00-00 Other serial printer # rmdev -l lp2 -d

These commands should be used with caution and only when no queue is referencing device lp2.

If you use SMIT to remove a queue and its device(s), the ODM objects are removed as well.

13.3.5 Remote Printing

The following queue form in /etc/qconfig is used to define a queue for a printer on another host:

rem0:  device = @laertes  host = laertes  up = TRUE s_statfilter = /usr/lib/lpd/aixshort  l_statfilter = /usr/lib/lpd/aixlong  rq = laser  @laertes:  backend = /usr/lib/lpd/rembak

The rem0 queue will send remote print jobs to the queue laser on the system laertes. The backend program for remote printing is /usr/lib/lpd/rembak. If the remote system is a BSD system, the filters /usr/lib/lpd/bsdshort and /usr/lib/lpd/bsdlong should be substituted for the AIX filters in the queue definition, and the filters /usr/lpd/att{short,long} are used for System V systems supporting remote printing (i.e., serving as print servers).

For incoming LPD-based print jobs, AIX runs the BSD lpd daemon and uses the normal /etc/hosts.lpd (or /etc/hosts.equiv) file to allow remote BSD systems to send print jobs to its queues, as described previously in the BSD section of this chapter. However, you may need to start the lpd daemon manually:

# startsrc -s lpd

Incoming jobs also require the writesrv service to be running. It is usually started from /etc/inittab, but you can verify that it is running with lssrc.

13.3.6 Adding a New Printer

To add a printer to the queueing system, these steps must be taken:

Physically connect the device to the system.
Make a device and queue for that printer. I find it's easiest to use SMIT for this step. Enter the command smit mkpq to perform this process. Choose the correct printer type from the list; then specify the controller and line to which the printer is attached.
Test the printer. Printer troubleshooting tips are discussed later in this chapter.

13.3.7 Using the Queueing System as a Batch Service

The printing system represents but one use of the AIX queueing system. Since potentially any program may be used as a queue backend program, many other uses are possible, such as a simple batch system. Here is a sample configuration:

batch:      device = batdev      discipline = fcfs  batdev:  backend = /bin/csh

With a shell specified as the backend program, users may submit shell scripts to the queue. The qdaemon will manage this queue, sending one script at a time to be processed by the shell. Shell scripts could be used to run any desired program. For example, the following script could be used to run a program bigmodel:

#!/bin/csh  ln -s ~chavez/output/bm.scr fort.8  ln -s ~chavez/output/bm.out fort.6  bigmodel <<END &> ~chavez/output/bm.log  140000  C6H6N6  Na  Hg  END

This file illustrates several important features about running programs from shell scripts (in this case, a Fortran program):

The symbolic links set up at the beginning of the file are used to associate Fortran unit number and files. By default, I/O to unit n uses a file named fort.n. Symbolic links allow a user to specify any desired paths.
The form <<END is used to place standard input for a command or program within the shell script. All subsequent lines prior to one containing just the string specified after the << are interpreted as input to the command or program.
The queueing system has no provision for saving job output, so the script must handle this itself.

Once set up, the enq command may be used as an interface to such a batch queue, allowing users to submit jobs to the queue and the administrator to delete them, alter their priority, and manage the status of the batch queue in the same manner as for print queues.