ppop - PPR operator's utility
ppop [switches] [subcommand ... ] [arguments]
If the ppop command is invoked without sub-command arguments it will enter
interactive mode. In interactive mode it reads commands from stdin and
executes them.
The --version switch prints the PPR version number.
The --help switch prints abbreviated instructions for use. It will suggest that
the user type ``ppop help'' for further instructions.
There are other switches which may be used when invoking ppop, either
with a subcommand on the command line or without one (for interactive mode).
The -X or --proxy-for switch can be used to submit a proxy-for
identification string. Such a string is used when dealing with jobs which a
Unix user has submited as proxy for other users. This may be when a a network
print server accepts jobs from remote clients.
If an -X switch was used when submitting the job and a subsequent
ppop command includes an -X switch, the proxy-for strings must match.
If they do not, permission to perform the operation will be denied. A network
print server such as Samba can use this to make sure a remote user can delete
only the jobs he submitted.
The ppop command has some limited support for wildcards in principal
strings. For principal strings in the form ``username@hostname'', the
username, the hostname, or both may be replaced with ``*'' which will
match any user name or any host name. For example,
``ppop -X 'smith@*' cancel myprn
'' will cancel all proxy jobs queued for
``myprn'' which were submitted on behalf of the user ``smith'' from any
host. The command ``ppop -X '*@*' cancel myprn
'' will cancel proxy jobs
submitted on the behalf of any user from any host, but it will not
delete any non-proxy jobs, nor will it delete proxy jobs with principal
strings that do not contain an ``@''. These wildcards are employed by
lprsrv. Careful reading of the above rules will reveal that a remote
lprm can generally only be used to remove jobs submitted with a remote
lpr.
The -M switch should be used when another program will be parsing ppop's
output. The -M switch simplifies the output format as follows: Banner
lines which give column names are suppressed. In interactive mode, the ppop
banner is changed to a terse one, the prompt is suppressed, and after each
command is executed a line in the form ``*DONE\t%d\n
'' is printed where %d
is the return code of the command. For some subcommand which output text
in columns, columns which would ordinarily be separated by a varying number of
spaces may be separated by lone tabs.
The --su switch can be used by an operator to cause ppop to behave as
though it had been invoked by another user. For example,
ppop --su smith cancel chipmunk
will cancel all jobs belonging to user
``smith'' which are queued for ``chipmunk''. Note that `becoming' another user
in this manner is quite different than serving as a proxy for another user.
A user maintains its own identity while serving as a proxy.
The -A switch can cause arrested jobs to be ommited from queue listings on the
theory that they are unimportant. It takes an integer as its argument.
This integer is an interval in seconds. Jobs which were arrested more than
integer seconds ago are ommited from queue listings.
The --magic-cookie switch can be used to specify magic cookie (a secret
token) which the spooler has associated with the job. The spooler assigns
a magic cookie to each job when it is created. If the magic cookie
supplied to ppop is not correct, access to the job will be denied even if
it would have been granted if a magic cookie were not specified. The spooler
reveals this magic cookie when sending questions as directed by ppr's
--question option. The user's answer will include this magic cookie. A
question CGI script will use the magic cookie supplied with the answer in order to make
sure it doesn't act on answers from people other than the one to whom the
question was sent.
The --verbose switch will cause some subcommands to display more
detailed information. The ppop status subcommand is one such.
Most operations performed by the ppop command require PPR operator privileges.
Only those operations which do not alter the spooler state (such as listing
the queue) or only affect a user's own jobs may be performed by
non-privileged users. This command defines a privileged user as the
user ``ppr'', a user with a UID of 0 (root), a user who is listed in
the file ``/etc/ppr/acl/ppop.allow'', or (for compatibility with
previous versions of PPR) a user who is a member of the group ``ppop''.
- ppop destination {destination, all}
=item ppop dest {destination, all}
-
displays information about the indicated Idestination>
(printer or group). This information includes whether it is a printer or a
group, whether it is currently accepting jobs, and whether it is
``protected''. If you specify ``all'' instead of a destination name, you will
be shown the aforementioned information for all destinations.
- ppop destination-comment {destination, all}
=item ppop ldest {destination, all}
-
This command is identical to the ppop destination command, except that
this command also displays the comment which is attached to each printer or
group.
- ppop destination-comment-address {destination, all}
-
This command is identical to the ppop destination-comment command, except
that this command also displays the interface program name and the interface
address. (Both are displayed in a single field with a space separating them.)
- ppop accept destination
-
Instruct the indicated destination to begin accepting new print jobs.
- ppop reject destination
-
Instructs the indicated destination to reject new print jobs. Any jobs a
user attempts to submit will be discarded and the user will be notified.
Notice that setting a printer destination to ``reject'' does not prevent it
from printing jobs for any group of which it happens to be a member, nor
does setting a group to reject prevent its members from printing jobs
explicitly sent to them or for other groups of which they happen to be
members, nor
does setting a printer or group to reject stop it from printing those
jobs which have already been accepted.
- ppop list {destination-name, all}
-
Display a somewhat detailed list of those jobs queued for the indicated
destination or for all destinations. If a single job name is specified,
information is displayed for only that job.
- ppop short {destination-name, all}
-
Display a terser queue listing than that displayed by ppop list.
- ppop details {destination-name, job-id, all}
-
Display an extremely verbose queue listing. This command is used for
debugging PPR and for the World Wide Web interface.
-
The output format of this command is likely to change in the future.
- ppop lpq destination-name [job# ...] [username ...]
-
Display a queue listing in a format similar to Berkeley's lpq. If there
are no jobs in the queue, ``no entries'' is displayed. If there are jobs in
the queue, the status of the printer indicated by destination-name or
each member of destination-name if it is a group is displayed. Then,
a line is emmited describing each job queued for the destination.
-
Additional parameters are interpreted as BSD style job numbers and as user
names. If such additional parameters appear, only jobs which match one or
more of them will be displayed. A job number will match any job for which
it equals the numberic portion of the PPR job-id. The way username
matching is done depends on whether the job is a proxy job. If ppr's
-X switch was used when submitting it, the username must match the
portion of the jobs principal id before the first ``@''. If it is not a proxy
job, the username must match the user identity as established by ppr's
-f switch and the PostScript ``%%For:'' comment.
-
The ppop lpq command is designed primarily for use with Samba and
lprsrv.
- ppop progress job-id
-
This command reports the percentage of an indicated job which has been printed.
The output is terse because it is intended for use by GUI front ends.
- ppop qquery {destination-name, job_id, all} field1 ... fieldN
-
This command is designed for use by programs such as GUI front ends which
might wish to invoke ppop in order to get information about print queues.
-
The first parameter is name name of the queue to be listed, the name of a
job to be listed or ``all''.
-
The output is a table. The columns of the table are separated by tabs. The
second and subsequent parameters are the names of the columns to be
displayed in the output. These are the valid column names:
- jobname
-
The PPR job id. If the subid is zero it is ommited. If the destination
node is this node, it is ommited. If the home node is this node it is
ommited. (In the current version of PPR, the last two conditions will
always be true.) A typical jobname will be ``chipmunk-2001''.
- for
-
The DSC ``%%For:'' line data. This is the submitter identification as it
appears in normal queue listings.
- title
-
The DSC ``%%Title:'' line data.
- status
-
A string describing the job status. Typical values are ``printing'', ``waiting
for printer'', and ``arrested''.
- explain
-
A string which gives furthur information about the job status. If the job
status is ``waiting for media'' then this field will contain a space delimited
list of the required media. If this job status is ``arrested'', this field
may contain the reason. If the job status is ``printing'', the explain field
will contain ``on printer''. There may be other possible values. This
field should be displayed near the ``status'' field.
- copies
-
The number of copies desired. If the number of copies was not specified
then this field will contain ``1?''. The reflects the fact that the number of
copies is probably 1 but there may be PostScript code which selects a
different number of copies.
- copiescollate
-
Either ``true'' or ``false'' to indicate whether multiple copies should be collated.
- pagefactor
-
The number of page descriptions per sheet. For duplex mode this will be 2.
For 4-Up this will be 4. For 4-Up and duplex it will be 8.
- routing
-
The DSC routing string. If there is not ``%%Routing:'' line in the PostScript
file, this field will be blank.
- creator
-
The DSC creator string. If there is not ``%%Creator:'' line in the PostScript
file, this field will be blank.
- nupn
-
The number if page descriptions which will be printed on each side of the sheet.
- nupborders
-
Either ``true'' or ``false'' to indicate whether borders will be printed
around virtual pages when printing in N-Up mode.
- sigsheets
-
The number of sheets per signature when printing in signature mode, 0 if not
printing in signature mode.
- sigpart
-
The part of each signature which should be printed. The values are
``Fronts'', ``Backs'', and ``Both''. This is specified at the time a job is
submitted by using ppr's -s switch.
- pageorder
-
The DSC ``%%PageOrder:'' value. The possible values are ``Ascend'', ``Descend'',
and ``Special''.
- proofmode
-
The DSC ``%%ProofMode:'' argument. The values are ``NotifyMe'', ``Substitute'', and
``TrustMe''. If no ``%%ProofMode:'' line appears in the PostScript file and
ppr's -P switch is not used then the value will be ``Substitute''.
- priority
-
The current priority of the job. This is a number between 0 and 39
inclusive with lower numbers indicating higher priority. A queued job's
priority number will drop periodically.
- opriority
-
The job's priority at the time it was submitted. This is a number between 0
and 39 inclusive with lower number indicating higher priority. The default
priority is 20, but other values may be specified with ppr's -q
switch.
- banner
-
The submitter's stated preference as to banner pages. The possible values
are ``Yes'', ``No'', and ``Unspecified''.
- trailer
-
The submitter's stated preference as to trailer pages. The possible values
are ``Yes'', ``No'', and ``Unspecified''.
- inputbytes
-
The number of bytes in the input file if it was not PostScript. If the
input file was PostScript, this value will be 0.
- postscriptbytes
-
The number of bytes in the input file if it was PostScript, or the number of
bytes in the PostScript filter output if it was not.
- prolog
-
Either ``true'' or ``false'' to indicate whether a DSC prolog section exists.
- docsetup
-
Either ``true'' or ``false'' to indicate whether a DSC document setup section
exists.
- script
-
Either ``true'' or ``false'' to indicate whether DSC comments delineate at least
one page description.
- orientation
-
The orientation of the document, if known. The values are ``Portrait'',
``LandScape'', and ``Unknown''.
- draft-notice
-
The `draft' notice. This is a message such as ``Draft'' or ``Confidential''
which is overlaid diagonally on the page.
- username
-
The name of the unix user who invoked ppr.
- userid
-
The numberic unix id of the user who invoked ppr.
- proxy-for
-
The proxy for string. When a user has submitted a job on behalf of another
user, generally on a remote machine, this field will often contain a string
identifying the user for whom the job was submitted. (This is the value
passed to the ppr -X or --proxy-for switch.
- longsubtime
-
The time the job was submitted.
- subtime
-
The time the job was submitted in the abreviated format used by ppop
list. For times less than 24 hours in the past, the hours and minutes are
shown. For jobs older than that, the day, month, and year are shown.
- pages
-
The number of page descriptions in the document. (This should not be
confused with the number of printed sides or the number of sheets of paper
that will be used. The value in this field does not take into account the
number of copies to be printed, duplex, or N-Up.)
- lpqfilename
-
For jobs received through lprsrv, the name of the origional input file, if known.
If it is unknown, this field will contain the same string as the title
field. This is the information that the ppop lpq command displays in the
``Files'' column.
- totalpages
-
The number of page descriptions in the document multiplied by the number of
pages. (This field and the two that follow are provided for convenience.
It is possible to derive their values from other fields.)
- totalsides
-
The number of printed sides in all copies of this document. (That is, totalpages
divided by the N-Up factor and rounded up to the next whole number.)
- totalsheets
-
The number of sheets of paper which will be used to print this job. (That
is, totalpages divided by the N-Up factor and furthur divided by two for
duplex mode, the whole being rounded up to the next whole number.)
- fulljobname
-
The PPR job id in long form. A typical fulljobname will be
``mouse:chipmunk-2001.0(mouse)''.
- filters
-
A space-separated list of the filters that were run on the input file in order
to produce PostScript.
- commentary
-
This is a bitmap expressed as a binary number. It indicates which categories
of commentary messages should be sent to the user while this job is being
printed. See ppr --commenatary.
- destname
-
This is the name of the printer or group to which the job was submitted.
If the destination node is this node, it is ommited.
- responder
-
This is the name of the responder program which will be used to tell the user
what happens to this job. See ppr --responder,
- responder-address
-
This is the address which will be passed to the responder program. See
ppr --responder-address.
- responder-options
-
This is the space-separated list of options which will be passed to the
responder program. See ppr --responder-options.
- status-explain
-
The value of status with the value of explain (if not empty) added to
it, separated by a space, and enclosed in parentheses.
- pagesxcopies
-
The value of filed pages multiplied by the value of field copies.
- page-list
-
The list of pages to be printed, if the user has chosen to print only a
subset of the pages.
- ppop move {job-id, destination-name} new_destination-name
-
Move the indicated job or all jobs queued for the destination named in the
first parameter to the destination indicated by the second parameter. An
ordinary user may move any job that belongs to him but may not move all jobs
queued for a destionation.
- ppop hold job-id ...
-
Place the indicated job in the ``held'' state. If you hold a job which is
currently being printed then printing will be stopt. Prior to version 1.30
it was not possible to hold a job that was being printed.
- ppop release job-id ...
-
Change the state of the indicated job from ``held'' or ``arrested'' to a state
which allows it to print.
- ppop cancel {job-id, destination-name, all} ...
-
This commadn cancels the indicated jobs or all jobs owned by the user
who runs ppop which are queued for the indicated destination or
destinations. An exception is that an operator may use the --su switch
to cancel all jobs queued by another user on the indicated destination or
destinations.
-
It is permissible to cancel a job
which is currently printing. Note that canceling all jobs queued for a
group will not cancel jobs queued specifically for the individual printers
which are members of that group. (Prior to version 1.30, ppop cancel
destination-name performed the action that is now performed by ppop
purge destination-name.)
- ppop scancel {job-id, destination-name, all} ...
-
Just like ppop cancel except it does not notify the owners of
the canceled jobs
- ppop purge {destination-name, all} ...
-
This command may be used by an operator to delete all jobs from the
indicated queues or from all queues if the special destination name ``all'' is
used. Note that canceling all jobs queued for a group will not cancel jobs
queued specifically for the individual printers which are members of that
group. (Prior to version 1.30, this function was performed by ppop
cancel destination-name.)
- ppop spurge {destination-name, all} ...
-
Just like ppop purge except it does not notify the owners of the
canceled jobs.
- ppop cancel-active {destination-name, all} ...
-
Cancel any jobs queued for the indicated destination or destinations that are
printing.
- ppop cancel-my-active {destination-name, all} ...
-
Cancel any jobs queued for the indicated destination or destinations that
are printing and are owned by the invoking user. If a principal identification
string is specified with the -X or --proxy-for switch, it must match the
job too.
- ppop clean {destination-name, all} ...
-
This cammand may be used by an operator to delete all arrested jobs in the
indicated queue or queues. The special queue name ``all'' may be used to
delete all arrested jobs from all queues.
- ppop rush job_name ...
-
Move the indicated job or jobs to the head of the queue. This command will
not interrupt any currently printing job, is simply moves each indicated job
to the head of its queue so that it will be started as soon as a printer
queue's printer or one of a group's member printers becomes idle.
- ppop last job_name ...
-
Move the indicated job or jobs to the tail of the queue. Otherwise it works
just as ppop rush does. In other words it will not interupt the job if
it is already printing.
- ppop log job_name
-
Display the log of the indicated job. This log will include DSC comment
warnings if the ``-w log'' switch was used when ppr was invoked and it will
include any messages received from the printer while the jobs was being
printed. If a banner or trailer page is printed, the contents of the log
are printed on it and the log is deleted. The log is deleted when a job is
removed from the queue. Also, if a job is arrested because the printer is
incapable of printing it, the log will contain messages indicating the
precise reason.
- ppop modify job_name name=value
-
This is a new command which can be used to modify existing jobs. Because
it is not yet finished, there is no documentation for it yet.
- ppop status {destination-name, all}
-
Display the status of the indicated printer, or, if destination-name is a
group, of all printers in the indicated group, or, if ``all'' is used, all
printers known to PPR.
-
The printer status has multiple parts. It is important to understand to what
each part applies if one is to interpret them correctly.
-
The first part is displayed on the same line as the name of the printer. It
explains what PPR is doing to the printer, or if it is doing nothing,
explains why. Examples include ``printing'', ``idle'', or ``fault, retry 5 in 60
seconds''.
-
When PPR is attempting to print a job, is will display a piece of status
information labeled ``Operation''. Print a job involves many steps, such as
connecting, sending the data, and waiting for the printer to indicate that
it is done. The Operation indicate the current state of the operation.
-
Another aspect is the state of the printer hardware as described to PPR by
the printer's controller. Different printers have different ways of
reporting this information. These include specially formatted
LaserWriter-style message sent over the normal communications channel, PJL
status messages, SNMP messages, and status AppSocket messages. PPR will
examine these message as they arrive and look them up in directories of
known messages. It will then attempt to integrate them into a unified
understanding of the printer's current status. This unified understanding
will appear in the ppop status output on lines labeled ``Printer Status''
and ``Printer Problem''.
-
If PPR is using the pjl or signal/pjl jobbreak method (see ppad
jobbreak), and the printer is connected over a bidirectional communications
channel, it may (if if implements PJL to a sufficient degree) report to PPR
whenever it drops a sheet of paper into the output tray. If PPR is
receiving such messages, then ppop status will display a ``Page Clock''.
The page clock indicate the number of seconds that have elapsed since the
last page was dropt. This excludes time when the printer reported that it
was off line.
-
This command will display more detailed information if the --verbose
option is used. In particular it will show the raw status messages received
from the printer. Without --verbose it will generally display only a
unified status description which reflects its (possibly imperfect)
understanding of the status messages it has received.
- ppop message printer
-
This command is new and experimental. It is designed for use by
programs which might wish to read the last error message received from
a printer. This command will eventually be documented in an appendix of
PPR, a PostScript Print Spooler.
- ppop start printer ...
-
Start a printer or printers which were previously stopt, are in an error
state, or in the otherwise engaged state.
- ppop stop printer ...
-
Stop the indicated printer or printers as soon as the current job (if any)
is done printing.
- ppop wstop printer
-
Stop the indicated printer as soon as the current job (if any) is done
printing. Does not return until the printer is stopped. Good for use in
shell scripts when the next operation (such as changing the mounted media)
can not be done until the printer has stopt.
- ppop halt printer ...
-
Stop the indicated printer or printers immediately, aborting printing of any
jobs currently being printed. A job whose printing is aborted is returned
to the queue and will start again from the begining as soon as a printer
becomes available. This means that if the job was submitted to a group and another
member of the group is idle, one of the idle printers will immediately begin
printing it.
- ppop alerts printer
-
Display the most recent alert messages concerning the indicated printer.
By ``recent'' we mean that this log is cleared and started over when an
alert is posted and the previous alert was posted more than one hour before.
In such a case, the previous alert presumably was the result of another
problem.
- ppop media {destination-name, all}
-
Display the name of the media mounted on each input bin of the indicated
printer, or, if destination-name is a group, each member of the
indicated group, or, if ``all'' is used, all printers on the system.
- ppop mount printer bin medium
-
Mount the indicated medium on the indicated bin of the indicated
printer. All of the parameters are case sensitive.
-
In general, a job which requires a specific type of medium will not be
printed until that medium is mounted on one or more bins.
-
The first exception to this rule occurs when a printer has no bins in its
bin list. In this case, it will print any job immediately without regard
to the job's media requirments.
-
The second exception is the bin name ``AutoSelect'' which has a special
status. Regardless of what medium is mounted on it, all jobs will be printed
immediately even if the proper medium is not explicitly mounted. Pages which
require a media which is not among those explicitly mounted will be directed
to the AutoSelect bin.
-
In order to dismount a medium without mounting another, leave off the
medium parameter. This is a reasonable thing to do if the bin will be
left empty.
Exit codes for ppop(1)
are defined in the source file
include/util_exits.h.
the ppr.1 manpage, the pprd.8 manpage, the ppad.8 manpage
``PPR, a PostScript Print Spooler'',
and ``Installing and Using PPR''.
PPR was written at Trinity College during 1993--2003.
It was first released to the public on 26 April 1995.
David Chappell, Trinity College Computing Center, Hartford, Connecticut.