LPRng-HOWTO: Spool Queues and Files

Next Previous Contents

## 10. Spool Queues and Files

When files are accepted by the `lpd` server for printing, they are stored in a spool queue directory, together with other files controlling the print operation. This section describes these files and how the LPRng software uses them.

For descriptive purposes, we will use the following printcap entry as a guide:

> `

>     pr|alias
>       :sd=/var/lpd/pr_public
>       :cd=/var/lpd/pr

> `

## 10.1 Spool Queue

- `sd=`Spool queue directory name

The `sd` option in the printcap entry specifies the spool queue directory. If there is no `sd` entry or value, then the printer can only be used by the clients such as `lpr` to locate the destination for a print job. All information, files, etc., for a print queue is stored in the spool directory.

## 10.2 Queue Lock File

- `spool_lock_file` spool queue lock file - default %P

When the `lpd` server starts printing, it will fork individual worker processes to service each queue. To prevent multiple processes from working on the same queue, a printer lock file specified by the `queue_lock_file` option (default `%P` - the %P is expanded to the print queue name) is used. In our example, the lock file would be: `/var/lpd/pr/pr`.

The process ID of the currently active printer is stored in the lock file. By reading the lock file and testing to see if the process is still active, programs such as `lpq` can determine queue activity.

Similarly, the worker process may need to create other processes to assist it. These in turn will create lock or temporary files in the spool directory as well.

## 10.3 Spool Control File

- `spool_control_file` spool queue control file - default control.%P

The spool control file is used to control the operations of the spooler, and is in the spool or control directory. The file name specified by the `queue_control_file` option (default `control.%P` - the %P is expanded to the print queue name); in our example, the control file would be: `/var/lpd/pr/control.pr`.

The `lpc` program sends spool control requests to the `lpd` daemon, which updates the control file and then signals the appropriate spool server processes that an update has been performed. The control file contents have the form:

> `

>     key value

> `

The following keys and their values are currently supported.

`printing_disabled` `0 or 1` `disable printing of jobs in queue`
`spooling_disabled` `0 or 1` `disable placing jobs in queue`
`holdall` `0 or 1` `hold jobs until released`
`redirect` `printer` `transfer jobs to indicated printer`
`class` `glob expression` `print only jobs whose class matches glob expression`
`server_order` `printer name list` `preferred order of printer use`
`debug` `debugging options` `debugging and tracing`

The `printing_disabled` and `spooling_disabled` are managed using the `lpc start`, `lpc stop`, `lpc enable` and `lpc disable` commands. Similarly, `holdall` is enabled and disabled by `holdall` and `noholdall` commands respectively. When holdall is enabled, jobs placed in the print queue will be held until they are explicitly released for printing by an `lpc release` command.

The `redirect` entry is used to redirect or transfer jobs which are spooled to this queue to another queue, and is managed by the redirect command. The `lpc redirect off` removes the redirect entry from the control file.

The `class` entry is similar in operation to the `holdall`, but allows jobs whose class identification matches the glob expression to be printed. This can be useful when you have special forms or paper required for a print job, and want to run only these jobs when the paper is in the printer.

The `server_order` entry is created and updated for a multiple printer queue. It records the order in which printers should next be used for normal print operations. This allows round robin use of printers, rather than having all jobs printed to the first printer in the list of printers.

The `debug` entry is set by the `lpc debug` command, and is used to enable or disable debugging and tracing information for a spool queue. This facility is for diagnostic purposes only.

## 10.4 Log and Status Files

- `create_files` create log, accounting and status files
- `lf=`log file name (default: log)
- `max_log_file_size#` maximum log file size (Kbytes)
- `min_log_file_size#` minimum log file size (Kbytes)
- `max_status_line#` maximum status line length (characters)
- `max_status_size#` maximum status file size (Kbytes)
- `min_status_size#` minimum status file size (Kbytes)
- `ps=`filter status file name (default: status)
- `queue_status_file=`queue status file (default: status.%P)
- `short_status_date=`display short (hh:mm) timestamp (default: true)

During operation, the `lpd` server records the current printing operations in the spool queue status file specified by the `spool_status_file` option (default `status.%P` - the %P is expanded to the print queue name); for our example, this would be `/var/lpd/pr/status.pr`. In order to prevent this file from growing too large, the server will periodically truncate the file. You can force creation of these files by setting the `create_files` option. The `max_status_size` configuration or printcap option sets the maximum size (in Kbytes) of the status file; if the file exceeds this, only the last `min_status_size` bytes or 25% of the maximum size (default if not specified) will be preserved.

Similarly, the server logs its operations in the log file specified by the `lf` (log file) option (default is `lf=log`). The `max_log_file_size` value (default 0) specifies the maximum length of the log file in Kbytes. If this value is non-zero, then the log file is truncated to `min_log_file_size` bytes or 25% of the maximum file size. Again, the last portion of the log file is preserved. If the `max_log_file_size` value is 0, then the log file grows without limit.

Some filters require an additional filter status file that they use for recording additional filter status or other operational information. The `ps` names this file, and it is passed to a print filter using the `$s` option (see Filter Command Line Flags).

The STDERR output for filters is put into the printer status file. This allows the filter to produce informative messages that can be displayed as part of the user status. In addition, a separate status file specified by the `ps` (Printer Status) can be used as well. This file is not truncated by the LPRng system.

When reporting status information, the length of line returned can be a problem. The `max_status_line#79` option restricts the status line to a maximum of 79 characters.

The `short_status_date` (default is true) option causes short (hour:minute) timestamps to be displayed on status queries.

## 10.5 Job Files

- `longnumber` long job number
- `default_priority=`default job priority
- `nline_after_file=`N line after data file

A print job consists of a control file and one or more data files. RFC1179 specifies the general format of these files and how they are to be transfered between servers. LPRng has extended the contents of the control files and the transfer protocol to provide a more powerful set of features, but has extensive provisions for backwards compatibility with non-LPRng software. A sample control file is shown below:

> `

>     Hastart4.astart.com
>     J/tmp/file1 /tmp/file2
>     CA
>     Lpapowell
>     Ppapowell
>     fdfA002230astart4.astart.com
>     N/tmp/file1
>     UdfA002230astart4.astart.com
>     fdfB002230astart4.astart.com
>     N/tmp/file2
>     UdfB002230astart4.astart.com

> `

The first part of the control file contains general information generated by the `lpr` or other spooling program. The information lines start with an uppercase letter or digit. Some other spooling systems also start information lines with various punctuation marks such as underscores (_) or periods (.).

Following this are a set of entries about each of the various files to be printed. These lines start with a lower case letter, followed by the print file name. The lower case letter is the format to be used to process the file. See print file formats for more information about its use.

Key | Meaning | Generated By
A | identifier * | LPRng internal
C | class | lpr -C class
D | date | lpr
H | originating host | lpr
I | indent | lpr -i indent
J | jobname | lpr -J jobname (default: list of files)
L | bnrname | lpr -U username
N | filename | (see text)
M | mailname | lpr -m mailname
P | logname | lpr
Q | queuename | lpr -Q
R | accntname | lpr -R accntname
S | slinkdata * | lpr
T | prtitle | lpr -T prtitle
U | unlnkfile | (see text)
W | width | lpr -w width
Z | zopts * | lpr -Z zopts
1 | font1 | lpr -1 font1
2 | font2 | lpr -2 font2
3 | font3 | lpr -3 font3
4 | font4 | lpr -4 font4

The entries marked with * are used only by LPRng. `N` and `U` lines are associated with a print file. The `N` line is the original name of the print file. By default, LPRng places this line before the corresponding data file. You can use the `nline_after_file` option to have LPRng place the N line after the data file line. The `U` line originally was used to indicate that the named file was to be unlinked after printing. This information is now ignored by LPRng. These lines are always grouped with a print file entry.

The names of control and data files follow a very strict pattern. Control files have the format `cfXnumberhost`, where X is an upper case letter, number is (usually) a 3 digit number, and host is the host name. RFC1179 restricted the total length of the control file name to 32 characters; LPRng has a much looser limit.

Data file names must follow the same pattern as the control file name, and have the format `dfXnumberhost`. The X can be in the range A-Za-z, allowing at most 52 data files for a job. The number and host must be identical to the corresponding control file.

By convention, LPRng uses the X of the control file name to set a priority for the job. A job with control file name `cfA...` will have lower format than a job with format `cfB...`, and so forth. The `lpr` program uses the first letter of the class name or an explicit priority indication to set the letter value. If none of these are specified, then the `default_priority` value from the configuration or printcap entry is used.

The job number is usually a 3 digit value. However, in systems where a large number of jobs are spooled and need to be kept for printing at scheduled times, this can lead to problems. The `longnumber` option will use 6 digit job numbers. This must be used with care when operating with non-LPRng software.

## 10.6 Job Hold File

Associated with each control file is a hold file that has additional information controlling the printing operations. The entries in this file have the form:

> `

>     key [value]

> `

The following is an example of a hold file:

> `

>     server 0
>     subserver 0
>     attempt 3
>     error cannot open printer
>     hold 0
>     priority 0
>     remove 0
>     routed 0

> `

The `server` and `subserver` entry records the process ID of the server process and the subserver process that is printing the job. The `attempt` field records the total number of attempts to print the job. The `error` field records any error that would prevent the job from being printed. This information is reported by the `lpq` program.

The `hold` field is non-zero when the `lpc hold` command is used to explicitly prevent the job from being printed; `lpc release` will clear the field and allow the job to be printed.

The `priority` field is modified by the `lpc topq` command and is used to provide an overriding priority to printing the file.

The `remove` field is non-zero when the file has been printed and should be removed.

The `routed` field is used to indicate that there is routing information present in the hold file, and that special handling is needed. The routing information is provided by a routing filter. The information is recorded by information in the hold file. The following is an example of routing information. Normally this information is stored in a URL escaped format, with one line per destination, but for clarity this has been broken out into plain text form:

> `

>     active 0
>     attempt 0
>     done 0
>     hold 0
>     priority 0
>     remove 0
>     routed 880892602
>     route 1
>       dest t1
>       ident papowell@astart4+705.1
>       error
>       copies 1
>       copy_done 0
>       status 0
>       active 0
>       attempt 0
>       done 0
>       hold 0
>       sequence 0
>       priority B
>       CB
>       end
>     route 2
>       dest t1
>       ident papowell@astart4+705.2
>       error
>       copies 0
>       copy_done 0
>       status 0
>       active 0
>       attempt 0
>       done 0
>       hold 0
>       sequence 1
>       end

> `

Routing information lines start with `route` followed by individual routing entry information. The `route` `dest`, `copies`, `priority`, and `Xnnnn` entries are derived from the output of the router program; other fields are used during the printing process. The `copy_done` records the numbers of copies done, while the `done` records that the entry has been completed. The `status` is the process ID of the server process doing the printing.

The output from route filter that generated the above file was:

> `

>     dest t1
>     copies 1
>     priority B
>     CB
>     end
>     dest t1
>     end

> `

## 10.7 Job State

Options used:

- `ah` Automatically hold jobs

A job can be in the following state:

1. Initial. This is the state during job submission. Jobs in the initial state do not have any status displayed for them.
2. Held. Once a job is submitted, it can either be printed or held. The `ah` printcap option specifies that all jobs are automatically held on submission. The `lpc release` and `lpc redo` command will cause these jobs to be printed and the `lprm` command can remove these jobs.
3. Active. The job is being processed for printing or transfer to another queue.
4. Pending. Jobs which can be printed but are not active. This can be due to the printer being busy or the job class not being printed.
5. Error. Jobs which have encountered an error during printing. The `lpc release` and `lpc redo` command will cause these jobs to be printed and the `lprm` command can remove these jobs.
6. Done. Jobs which have completed printing, but which are not yet removed from the print queue. See the `save_when_done` flag for more information. The `lprm` command can remove these jobs.

Normally the job sequences is initial, pending, active, and done. However, a job may be put in the error state by problems processing the job or by actions of the `lpc` command.

## 10.8 Job Identifier

Options:

- `use_identifier` put job identifier in control file

For each job in a spool queue, the LPRng software creates a unique identifier. This identifier is recorded in the control file `A` line. It can be used by the various client programs for identifying jobs, and is displayed by the `lpq` program as status information.

Next Previous Contents