LPRng-HOWTO: Job Processing

12. Job Processing

Much of the flexibility of the LPRng software is obtained from the ability to control the details of each step of job processing. The following section details each step in the processing of a job, and explains the printcap options used to control each operation.

Assume the pr printcap entry has the form:


pr
    :lp=/dev/lp  OR  :lp=rp@rm
    :sd=/var/spool/lpd/pr
    :lf=log
    :of=/usr/local/bin/lpf
    :if=/usr/local/bin/lpf

Assume that we have used the following command to print a set of files.


lpr -Ppr file1 file2

This will create a control file in the /var/spool/lpd/pr directory with the following contents (this is an example - in practice there may be minor differences between the example and an actual control file):


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

12.1 Opening the Output Device

Options used:

achk Accounting check at start
af=Accounting File
ar Remote printer accounting enabled
as=Accounting at start
connect_grace# Time between jobs
connect_interval# Connection interval
connect_timeout# Connection timeout
control_filter=Control file filter
ff form feed
fo form feed on open
la Local printer accounting enabled
ld=leader on open (initialization string)
lk Lock IO device
lp=IO device pathname
nb Nonblocking device open
network_connect_grace# Time between jobs
of=of filter
retry_econnrefused# Retry if open failed
retry_nolink# Retry if open failed
rm the remote machine to send the job to
rp the remote print queue to send the job to
rw device opened RW flag
server_tmp_dir=temporary directory

Sequence of Operations:

During the server operations, it will try to create temporary files in the print queue spool directory. If this is not desirable, it will create them in the server_tmp_dir directory.
If the accounting file specified by af exists, it is opened (af_fd) and the af_fd is passed as file descriptor 3 to all filters. If the af value has the form af=|/program then the program is started and the program STDIN is used as af_fd. If the af value has the form af=host%port, then a TCP/IP connection to the corresponding port on the remote host is made and the port used as af_fd. In the latter two cases, the filter STDIN (file descriptor 0) is actually opened read/write, and is used when information is needed from the accounting filter or remote server. See Accounting Printcap Options for more information on the LPRng accounting support.
If the connect_grace value is non-zero and the server is opening a device or network_connect_grace is non-zero and a network connection is being made, the server will pause the specified time. This is to accommodate devices which need a recovery time between jobs.

The lp option is checked to determine the type of IO device.

Format	Meaning
`/pathname`	Absolute pathname of IO device
`pr@host`	transfer to `pr` on remote `host`
`host%port`	open a TCP/IP connection to port on host. host can be name or IP address
`\|filter`	run the filter program; it STDIN will be used as device

The IO device specified by lp is opened write-only or read-write if the rw flag is true, and the resulting file descriptor is io_fd. If the nb flag is set, a non-blocking open will be done as well. If the lk (lock device) flag is true, the device will be locked against use by other LPD servers.
If a host%port combination, a TCP/IP connection will be opened to the remote port and the connection will be used as io_fd.
If a filter program is specified, the filter program will be run and the STDIN of the filter will be used as the device file descriptor.
If a rp@rm combination, or none of the above combinations are true and the rm and rp values are non-zero, then the job will be transferred to a remote printer. The type of operation will be a job transfer, rather than printing operation.
If the connect_timeout value is non-zero, a timeout is setup for the device or socket open. If the device or connection open does not succeed within the timeout, then the open operation fails.
If a connection is to a network address (i.e. - connect() system call) and the connection attempt fails with an ECONNREFUSED error, if the retry_econnrefused flag is set then the connection attempt is retried, but this time using an alternative port number. See RFC1179 for details. This is repeated until all of the possible originating port numbers are exhausted.
If the open or connect operation fails, and the retry_nolink flag is set, then the server will pause for a minimum of connect_grace plus a multiple of connect_interval seconds based on the number of attempts before retrying the open operation. Note that the interval may increase as the number of attempts increases.
If printing a job and the of filter is specified, it is created with its STDOUT (fd 1) attached to the io_fd. Its stdin (of_fd) will be used in the steps listed below. If there is no of filter, then the of_fd value will be the io_fd descriptor.
If transferring a job and the control_filter option is specified, then the program specified by the control_filter value will be run. It will have its STDIN set to the control file, and its STDOUT output will be used as the new value of the control file to transfer to the remote host. See Filter Command Line Flags for details of options passed to the control filter, and errorcodes for the exit codes of the filter.
If la (local accounting) is true and we are printing a job or ar (remote accounting) is true and we are transferring a job, the as value is examined. If it is a filter (program) specification, then the program is started with its STDIN attached to /dev/null and STDOUT to the io_fd, STDERR to the error file, and file descriptor 3 to the accounting file descriptor af_fd. The lpd program will wait until it terminates, and examine the error code for action, as for the filters (see errorcodes below). If it is a string, then it is interpreted, the escape sequences replaced with the appropriate information, and written to the accounting file.
If the achk (accounting check) flag is set, a line is read from the accounting filter af_fd file descriptor. This line should be accept, otherwise the job processing terminates with a JFAIL indication.
If the operation is a job transfer, the operation proceeds as outlined in RFC1179, and then the Normal Termination operations are carried out.
If the operation is a print operation and the ld (leader on open) value is provided, the string is translated (escapes removed) and written to the of_fd file descriptor.
If the fo (form feed on open) flag is true, then the ff (form feed) string is translated (escapes removed) and written to the of_fd file descriptor.

12.2 Printing Banner At Beginning

Options used:

ab Always print banner (default FALSE)
be=End banner generator program
bl=Short banner line format
bp=Banner generator program
bs=Start banner generator
hl Banner (header) Last
of=Banner and File Separator Filter
sb Short banner (default FALSE)
sh Suppress header (banners) (default FALSE)

Sequence of Operations:

If the sh (suppress header) flag is true, no banner is printed, and the actions in this section are skipped.
If the hl (header last) flag is true, the banner is printed at the end of the job, and the actions in this section are skipped.
If the user does not want banner pages and uses lpr -h then the L line in the control file will be missing. This is a signal not to print a banner. If there is no L line in the control file and ab (always print a banner) is false (the default), then no banner is printed. If there is no L line and ab is true, then ANONYMOUS is used.
LPRng generates banners by using either a banner printing program specified by bp, ttbs, or be options. For historical compatibility, if the sb flag is set, then the bl (banner line) contents are sent directly to the of_fd; By default the bl value is: bl=$-'C:$-'n Job: $-'J Date: $-'t (See Filter Command Line Flags for details.) This will get translated to:
papowell:A Job: file1 file2 Date: Thu Nov 27 23:02:04 PST 1997
If bs (start banner) program is specified, then it is used to generate a banner, otherwise if the bp (banner) program is specified, then it is used to generate a banner. If no program is available, we skip the banner generation. The banner generator program is started with the normal command line flags (see Filter Command Line Flags), with its STDOUT attached to the of_fd descriptor. The short banner string described in the previous step is written to the STDIN. The banner printer is responsible for generating a banner appropriate to the printing device.

12.3 Printing Job Files

Options used:

Xf=Format Filter
if=Default F Format Filter
pr=pr formatting program
send_job_rw_timeout= print job read/write timeout
send_query_rw_timeout= status query operation read/write timeout
sf Suppress FF Print File Separators

Sequence of Operations: for each job in listed in the control file, the following operations are done in turn.

If there is an of filter present, the suspend string \031\001 is written to of_fd and the no further action is taken until the of filter is suspended.
The control file line for the job is examined, and the first letter of the data file specification is used as the format.
If the format is p, the job is first processed by the program specified by the pr program, and the program output used as the print file.
If the format is f, l, or p then the if filter is used, otherwise the keyword Xf is used. Note that certain formats such as p, a, l, may not be used as formats.
The filter program is started with an appropriate set of command line options (see Filter Command Line Flags), and with its STDOUT attached to the printing device (io_fd), STDERR to the log file (lf), and file descriptor 3 to the accounting fd af_fd.
When doing a read/write operation to a device or remote system, a timeout can be specified. When doing a print or job transfer operation, the send_job_rw_timeout value is used. When doing a status or query operation, the send_query_rw_timeout value is used. If a write or write operation does not complete within the specified timeout seconds, then we have an error condition and job processing or the query operation is terminated with JFAIL status. If the timeout value is 0, then no timeout is done.

lpd will then wait for the filter to exit. The exit status can be as follows:


Key      Value   Meaning
JSUCC    0       Successful
JFAIL    1, 32   Failed - retry later
JABORT   2, 33   Abort - terminate queue processing
JREMOVE  3, 34   Failed - remove job
JHOLD    6, 37   Failed - hold this job
Other            Abort - terminate queue processing

If the filter exit status was JSUCC (0), or no error indicated, then processing will continue otherwise the job termination takes (see Abnormal Termination).
If the of filter is present, then it is reactivated with a kill -CONT signal.
If the sf (suppress FF print file separators ) is false, then the ff (form feed) string will be interpreted and sent to the of_fd.

12.4 Printing Banner At End

Options used:

hl Header (Banner) Last

The actions taken in this step are identical to those for the Printing Banner At Beginning, with the exception that the be (end banner program) is used to select the banner generation program rather than the bs (start banner program).

If we have hl true, then we print a banner at the end of the job, rather than start.

12.5 Normal Termination

Options used:

fq Form Feed on Close
la Local Printer Accounting
tr=Trailer on Close
ae=Accounting at end
save_when_done Save when done

Sequence of Operations:

If we are printing and the fq flag is set and the sf (suppress interfile FF) flag is set, then the ff (form feed) string will be interpreted and sent to the of_fd.
If we are printing, the tr (trailer) string will be interpreted and sent to the of_fd.
If printing and the la (local printer accounting) flag is set or transferring a job and the ar (remote accounting) flag is set, the ae is examined and accounting is done as described for the as field.
If the of filter is present, its STDIN is closed, and the lpd server waits for it to exit. The exit status is used as described above.
The device (io_fd) is closed.
The job is marked as completed in the spool queue.
If the save_when_done flag is not specified, the job is removed.

12.6 Abnormal Termination

Options used:

mail_from=Mail from user name
mail_operator_on_error=Mail to operator on error
send_try# Maximum Print or Transfer Attempts
save_on_error Do not delete on error
send_failure_action=Action on Failure
sendmail=sendmail path name and options
stop_on_abort Stop processing queue on filter abort

If the job processing terminates abnormally, the following sequence of events occurs:

The job is marked as having an error during processing.
The LPD server will attempt to kill all filters and other associated process by using a sequence of kill -INT, kill -QUIT, and finally kill -KILL operations.
If there is a mail_operator_on_error value, the specified operator will be mailed an error indication. The sendmail option specifies the pathname of the sendmail program and the options needed to have it read mail addresses from its standard input. For example, sendmail=/usr/sbin/sendmail -oi -t is a commonly used set of options.
The mail_from value specifies the user name used for mail origination. If not specified, the default is to use the print spool queue or printer name.
If there is a send_failure_action specified, then it is decoded and the corresponding action taken. If the value is remove, hold, abort, or retry, then the job is removed, held, aborted, or retried. If the value is |/program, the program is executed and the number of attempts are written to the filter STDIN. The exit status of the filter will be used to determine the consequent actions. That is, JSUCC (0) will be success, and the standard success action will be taken; JFAIL will cause retry, JREMOVE will cause the job to be removed, JHOLD will cause the job to be held, JABORT or other status will abort processing.
If the status is ABORT and the stop_on_abort flag is set, then further processing of jobs is terminated. The job is not removed from the queue.
If the error status indicates removal, and the save_on_error flag is clear then the job is removed from the spool queue.
If the error status indicates that no further operations should be performed on the queue, then the lpd server will stop processing jobs.
If the error code indicated that the job should be retried, and the send_try value is 0 or the number of attempts is less than the send_try value, then the job is retried. Between each attempt to transfer a job to a remote site. This pause will double after each attempt, reaching a maximum of max_connect_interval seconds. If max_connect_interval is 0, there is no limit on the interval value.

12.7 LPD Spool Queue Processing

Options used:

lpd_force_poll=Force LPD to periodically poll print queues
lpd_poll_time#Time between polls
max_servers_active#Maximum number of active servers

When the lpd server starts, it will fork a set of subserver processes, each which will handle an individual queue.

If a system has a large number of queues, then this forking operation may result in the lpd server exhausting the process resources. To control this, the max_servers_active value restricts the number of active children to the specified value. If this value is 0, then 50% of the maximum system processes value will be used.

Due to the limits on the number of processes, there may be times when a job is placed in a queue, but the lpd server is unable to start handling the job. When all of the children of the main lpd server have exited, the server starts a timer. After lpd_poll_time seconds, it will scan the queues, looking for jobs to process, and starts a process to service them. If it does not find any jobs it remains idle.

The lpd_force_poll flag causes the server to periodically poll the queues. This is useful when there is a high possibility that jobs could fail to be printed due to high loads on the server.

Next Previous Contents