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

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 with the cannonical spool 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

The spool control file is used to control the operations of the spooler, and is in the spool or control directory. The file name has the form control.printer; 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. Similary, 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)

During operation, the lpd server records the current printing operations in the status.printer file. 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 log file (lf) is opened and used as the STDERR output for filters and debugging information from the lpd server.

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.

10.5 Job Files

• longnumber   long job number
• default_priority=default job priority

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.

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. 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.