NAME

ppop - PPR operator's utility


SYNOPSIS

ppop [switches] [subcommand ... ] [arguments]


DESCRIPTION

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.

Informative Switches

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.

Other Switches

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.

Access Control

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

Destination Commands

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.

Job Commands

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.

Printer Commands

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.

Media Commands

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.


DIAGNOSTICS

Exit codes for ppop(1) are defined in the source file include/util_exits.h.


SEE ALSO

the ppr.1 manpage, the pprd.8 manpage, the ppad.8 manpage ``PPR, a PostScript Print Spooler'', and ``Installing and Using PPR''.


HISTORY

PPR was written at Trinity College during 1993--2003. It was first released to the public on 26 April 1995.


AUTHOR

David Chappell, Trinity College Computing Center, Hartford, Connecticut.