ppop.1


NAME

ppop - PPR operators 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 switch can be used to submit a principal identification string. A principal identification string is used when dealing with jobs which a Unix user has submited on the behalf of other users. This may be apply in the case of a network print server process which accepts jobs from remote clients. The remote users may be either real Unix users or anything other sort of entity which may be identified by a short unique string.

If an -X switch was used when submitting the job and a subsequent ppop command includes an -X switch, the principal string must be the same or permission to perform the operation will be denied. A network print server such as Samba can use this to prevent a remote user from deleting any but the jobs he submitted.

The ppop command has some limited support for wildcards in principal strings. For principal strings containing an ``@'', the user name, the host name, 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 jobs for queued for ``myprn'' which were submitted on behalf of the user ``smith'' from any host. The command `` ppop -X '*@*' cancel myprn '' will cancel 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 exploited by lprsrv. Careful reading of the above rules will reveal that lprm can generally only be used to remove jobs submitted with lpr.

The -M switch should be used when another program will be parsing ppop's output. The -M switch simplifies the output format. Banner lines which give column names are suppressed. In interactive mode the 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. Columns which would ordinarily be separated by a varying number of spaces may be separated by tabs.

The -u switch can be used by an operator to cause ppop to behave as though he were another user. For example, ppop -u smith cancel chipmunk will cancel all jobs belonging to user ``smith'' which are queued for ``chipmunk''.

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

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), or a user who is a member of the group ``ppop''.

Destination Commands

ppop destination {destination, all}
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 ldest {destination, all}
This command is identical to the ppop dest command, except that this command also displays the comment which is attached to each printer or group.

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 is new and experimental. It reports the amount 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 new and experimental. It 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 columns desired 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''.

fulljobname
The PPR job id in long form. A typical fulljobname will be ``mouse:chipmunk-2001.0(mouse)''.

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.

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 signiture when printing in signiture mode, 0 if not printing in signiture mode.

sigpart
The part of each signiture 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
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
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 switch.

longsubtime
The time the job was submitted.

subtime
The time the job was submitted in the abreviated format used by B
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.)

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

.

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} ...
Cancel the indicated jobs or all jobs owned by the user who runs ppop which are queued for the indicated destination or destinations. An operator may use the -u 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 Bdestination-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 Bdestination-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 proxy-for string is specified with the -X 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 the indicated jobs to the head of their queues so that they will be started as soon as the printer or one of the group's member printers becomes idle.

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.

.

Printer Commands

ppop status {destination-name, all}
Display the status of the indicated printer, or, if destination-name is a group, all printers in the indicated group, or, if ``all'' is used, all printers known to PPR.

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 media
Mount the indicated media 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 media will not be printed until that media 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 media is mounted on it, all jobs will be printed immediately even if the proper media is not explicitly mounted. Pages which require a media which is not among those explicitly mounted will be directed to the AutoSelect bin.

.


FILES

This command writes to the spooler communications FIFO /var/spool/ppr/PIPE. It also uses temporary files in /var/tmp.


DIAGNOSTICS

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


SEE ALSO

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


HISTORY

PPR was written at Trinity College during 1993, 1994, 1995, and 1996. It was first released to the public on 26 April 1995.


AUTHOR

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