ppad.8


NAME

ppad - PPR administrator's utility


SYNOPSIS

ppad [--help] [--help] [-M] [-d debuglevel] [subcommand] [parameters ...]


DESCRIPTION

Ppad is the utility used to manage PPR, that is, to create and delete printers and groups, to set their parameters, and to define known types of media.

The --version switch prints the PPR version number.

The --help switch prints abreviated instructions for use and direction for obtaining additional help.

The -d option can be used to turn on messages which describe what ppad is doing. The default level is 0. Using -d 1 will cause ppad to tell what printer and group configuration files it is examining and editing. Higher levels display more information. A level 2 and above ppad will display information about what it learns from PPD files and /etc/ppr/mfmodes.conf. At level 3 and above it will display every mode line in /etc/ppr/mfmodes.conf and every line read from or written to the printer or group configuration file. Level 6 and above shows most of the lines in every PPD file that is read.

Most operations performed by this command require PPR administrator privileges. Only those operations which make no changes to the spooler configuration 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 ``ppad''.

Ppad has a number of subcommands. Each subcommand has zero or more parameters. The subcommands are described below.

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.

If the -M switch is used, ppad will adopt a terser style of output, more suitable to parsing by other programs.

Media Management

The media management subcommands operate on the media database which is contained in the file /usr/ppr/conf/media. The media database is the the definitive list of media types recognized by PPR.

If you fail to supply enough parameters to any media subcommand, you will be prompted for the missing parameters. These are the media subcommands:

ppad media show {medianame, all}
Displays a media database entry. You can request a specific entry by specifying the media name or you can see all entries by using the word ``all'' instead of a media name. If you do not specify a media name or ``all'', you will be prompted.

ppad media put [medianame] [width] [height] [weight] [colour] [type] [flag_suitability]
Adds a record or modifies a record in the media database. If you do not supply enough parameters, you will be prompted for the missing ones. If you are modifying an existing record and you are prompted for a parameter, the current value will be displayed; if you press return then the value will not be changed. When entering heights and widths, the units are inches unless you specify otherwise by putting a unit specifier such as ``pt'' or ``points'', or ``cm'' or ``centimetres'' or ``centimeters''. The weight is the weight of the paper in grams per square metre; if you don't know it, you may enter 0. ``Basis weight'' or ``ream weight'' measured in pounds can be converted to grams per square meter by multiplying it by 3.76. The colour parameter specifies the colour of the paper, by convention, these names are in all lower case. The type describes the basic type of the media, such as ``Letterhead''; if ppad prompts you for the type, it will give a list of those types currently registered with Adobe. The flag_suitability is used to indicate whether this kind of media is suitable for printing flag (banner and trailer) pages. 1 means entirely unsuitable, 10 means most suitable. When it comes time to print a flag page, PPR prints it on the currently mounted for having the highest suitability rating, unless all mounted forms have a rating of 1, in which case no flag page is printed.

ppad media delete medianame
Deletes the indicated media record from the media database.

ppad media export
This command causes ppad to write a shell script to stdout. This shell script can be used to re-create the file /usr/ppr/conf/media. It contains a series for ppad media put commands. This can be useful for moving the media database to a different type of machine since the binary file /usr/ppr/conf/media is not portable.

Printer Management Subcommands

ppad show printer
Displays the configuration of the indicated printer. The option selections described by the output of this command may be changed using the commands described below.

ppad comment printer comment
Sets the comment field of the indicated printer. Highly recommended!

ppad interface printer interface address
specifies the means by which PPR will send the jobs to the printer and the physical address of the printer. If the print queue printer does not already exist, it is created. The interface is the name of a program in /usr/ppr/interfaces which can open a connection to the printer, perhaps over the network or over a serial cable. The address is a parameter which is passed to the interface program. The precise meaning and format of the address parameter depend on the interface program selected. It might be the device name of a serial port, or the AppleTalk name of the printer.

Interfaces supplied with the current distribution include atalk , client , simple , serial , tcpip , lpr , dummy , gssimple , gstcpip , and gsatalk .

atalk
The interface atalk sends the job to an AppleTalk printer using the Printer Access Protocol. The address is the AppleTalk address of the printer in the form ``Name:Type@<EM>Zone''. The Name is the name that appears in the chooser. The Type is usually ``LaserWriter'' but it may be anything including ``LaserJet 4M'' and ``LaserShared''. If the printer is not found using the indicated Type, then it is tried again with a type of ``LaserWriter''; if it is found that time, PPR changes the printer's type to the Type originally specified. This ``hides'' or ``captures'' the printer, preventing Macintosh user's from sending jobs to it directly.

This interface has some options which may be set with the ppad options command. (None of these options are implemented yet in the CAP version of the interface.)

Two of the options, ``lookup_retries='' and ``lookup_interval='' control how many times the interface will atempt to look up the printer's AppleTalk name and how many seconds it will pause between attempts. The default values are 8 and 1 respectively.

The option ``open_retries='' controls how many times the interface will attempt to open a connexion to the printer when the printer is busy. These attempts are made a two second intervals. The default is 10. If open_retries is set to -1, then the interface will keep trying until it is connected. Setting open_retries for infinite retries will prevent the spooler from correctly reporting that the printer is "otherwise engaged or off-line".

The option ``status_update_interval='' is 0 by default. If it is set to a possitive value in seconds then the interface will attempt the retrieve the most current printer status approximately that often. (The timing is actually rather erratic.)

The option ``address_cache='' controls whether the interface caches the AppleTalk address of the printer. This feature is on by default. The address is cached at the end of each sucessful printing run. At the start of a new run, if the address was cached less than 20 seconds ago it is used without doing another name lookup. If the cached address is older than that then a message is sent to the address to confirm that it is still good and it is used if the response is positive. The address cache is considered invalid if the interface or the address has changed.

client
The interface client sends the job to an MS-DOS client spooler. This is compatible with the client spooling found in AT&T's LAN Manager for Unix. The address is the NetBIOS name of the client spooler process, but without the trailing ``.P''.

simple
The interface simple is a shell script which sends the job to a Unix port. The address is the port name, such as /dev/lp0. It has no provision for setting baud rate or other port options as the serial interface does. By default, this interface uses the jobbreak method control-d, however, the method control-d/pjl is also suitable if the printer understands the HP PJL. See the ppad jobbreak section of this document. This interface not been extensively tested. PostScript errors will not be detected when using this interface.

serial
The interface serial sends the job to a serial port on the server. The address is the port name, such as /dev/ttyS00.

The options are ``speed=xxxxx'', ``xonxoff=[yes,no]'', "bits=[7,8], ``parity=[even,odd,none]'', ``wait=[yes,no]'', and online=[dsr,cts,cd,none]. The ``speed='' option sets the baud rate. The ``xonxoff'' option enables or disables XON/XOFF flow control. You should only disable XON/XOFF flow control if your serial port driver supports some other sort of flow control such as DSR or CTS flow control. The ``bits'' option sets the number of data bits. Given a choice, you should choose eight bits. The ``parity='' option sets the parity checking mode. Many serial interfaces do not support parity checking with eight data bits so you will have to choose ``none'' in those cases. The ``wait='' option controls whether the interface will wait to receive a control-D from the printer after it sends one. The ``online='' option can be used to name a modem control line. If this option is used, immediately after opening the serial port the interface will check that the indicated modem control line is is a state indicating readiness. If it is not, the interface will exit and PPR will place the printer in the state ``otherwise engaged or off-line'' for 60 seconds before trying again. For this feature to work, your printer must make one of its modem control lines go false when it is taken off-line and your null modem cable must feed this signal to one of the receiving modem control lines on your print server and you must indicate the correct receiving line as the option to the ``online'' option. Setting this up correctly will generally require the use of an RS-232 breakout box. The default options are expressed by the string ``speed=9600 xonxoff=yes bits=8 parity=none wait=yes online=none''.

By default, this interface uses the jobbreak method control-d, however, the method pjl is also suitable if the printer understands the HP PJL. See the ppad jobbreak section of this document.

This interface has not been extensively tested.

tcpip
The interface tcpip opens a TCP/IP connection to a specific socket on a specific host and sends the data. HP JetDirect cards and Extended Systems PockPrintServers will accept jobs sent in this manner. The address is in the form ``host:port''. For example: ``bigjohn.prn.trincoll.edu:9100''.

This interface currently supports all jobbreak methods except signal and signal/pjl. (See the ppad jobbreak section of this man page.)

By default the ``feedback='' parameter is set to ``True'' for this interface. This is appropriate for HP printers with JetDirect cards. If however the interface is a separate device connected to the parallel port of the printer, it will probably be unable to return printer messages and control-D's. In this case, it is essential that you use the ppad feedback command to set this parameter to ``False''.

Whether PostScript errors will be detected when using the tcpip interface depends on whether or not the print server supports two way communication.

The interface tcpip has many options.

The option ``sleep='' is the number of seconds the interface should wait after closing the connection and before exiting. Some TCP/IP printers may need a few seconds to recover before printing the next job. Without the ``sleep'' option, if another job is printed immediately, it may incur a fault with a retry 10 seconds later. This is not disastrous, however, the ``sleep='' option is intended to prevent this. The default is ``sleep=0''.

The option ``eof_timeout='' specifies the maximum number of seconds the interface should wait for acknowledgment of the last control-D that was sent to the printer. The default is ``eof_timeout=0'' which means to wait indefinitely.

The option ``connect_timeout='' controls how long the tcpip interface will wait for the printer to respond to a connexion request. The default is 20 seconds.

The option ``sndbuf_size='' can be used to set the value of the socket option SO_SNDBUF. If this option is ommited, the system default is accepted.

The option ``write_size='' controls the size in bytes of the block size for the write() system call. The default is 4096.

There have been some reports that with ``feedback=true'', this interface will sometimes fail to detect that the job is done.

lpr
The interface lpr sends the job to another system using the Berkeley LPR/LPD protocol. The address is in the form ``printer@system''. For example: ``pooh@sanders.trincoll.edu''. If you really want to, you can specify a port to connect to instead of the normal lpd port. Do it like this: ``pooh@sanders.trincoll.edu:2000''.

If the remote system is a full Unix system and not job a mini print server box, jobs could disappear from PPR's queue long before they are printed.

This interface supports all jobbreak methods except signal and signal/pjl. The suitability of any given jobbreak method depends much on the remote system. The default is control-d which is suitable for simple devices such as Ethernet devices which attached directly to the printer. When sending to a real spooler it is sometimes necessary to choose a jobbreak method of newinterface because the remote spooler objects to the control-d's in the data stream. In such a case, the remote spooler will itself insert whatever control codes are necessary.

PostScript errors will not be detected when using this interface.

This interface has an option called ``banner=''. This tells the remote printer whether or not to attach its own banner page to the job. The default is ``banner=no''. Remote systems have been known to refuse to print the job unless ``banner=yes'' is used.

Another option is ``lpr_typecode=''. This is the file type code which should be used when submitting the file. The preferable code is ``o'' which means that the file is PostScript, however many lpd implementations do not understand this code so ``f'' is the default.

dummy
The interface dummy is for testing purposes. It is a shell script which copies the job to a file. The address is the name of the file.

This interface has an option ``sleep=''. This tells the interface how many seconds to wait after printing the jobs before exiting. This can be used to simulate the time requirements of printing on an actual printer.

gssimple
The interface gssimple using Ghostscript to rasterize the file and send it to a printer directly connected to the server. The address is the name of the port.

The option parameter (described below under ppad options ) is used to set certain Ghostscript options. The gssimple interface has the following option values which can be set:

The option ``gs='' sets the path of the Ghostscript executable, the default is /usr/bin/gs.

The option ``device='' sets the Ghostscript device name. Common values are ``device=ljet3'' and ``device=djet500''.

The option ``resolution='' is passed as the argument to Ghostscript's -r switch.

Every instance of the option ``gsopt='' specifies an argument to be appended to the Ghostscript command line. For example, ``gsopt=-sDepletion=1''.

gstcpip
The interface gstcpip is similar to the gssimple interface described above, however, it uses the tcpip interface to send the Ghostscript output file to a remote TCP/IP print server. The address is as described above for the tcpip interface.

This interface takes all the options accepted by the gssimple interface as well as all those accepted by the tcpip interface.

gsatalk
The interface gsatalk is similar to the gssimple interface described above, however, it uses the atalk interface to send the Ghostscript output file to the printer. The address is as described above for the atalk interface. This interface might be used with HP DeskWriters.

If you use the ppad interface command to change a printer's interface program, then ppad will delete any options set with ppad options ; it will also set the jobbreak and feedback parameters to the default for the new interface selected. If you use the ppad interface command to change the printer address, but not the interface program, then the aforementioned parameters are not modified.

This interface takes all the options accepted by the gssimple interface as well as all those accepted by the atalk interface.

.

.

ppad options printer options
sets the options string which will be passed to the interface program. Most interface programs ignore this parameter. The options string is a sequence of space separated name=value pairs. The name=value pair recognized by each interface supplied with PPR are described in the ppad interface section of this man page.

Here is a sample ``ppad options'' command. This one sets the options for a printer with a serial interface:

$ ppad options myprn 'speed=19200 bits=7 parity=even'

ppad jobbreak I {none, signal, signal/pjl, control-d, pjl, save/restore, newinterface}>>
Specifies the method used to indicate the end of one job and the start of another to the interface program. A printer considers a banner page and the print job proper to be two separate print jobs. PPR knows reasonable default job break methods for the standard set of interfaces, but if you supply your own interface you may have to set this parameter.

The possible settings are as follows:

``none'', do not indicate job breaks (which makes flag pages and, in certain instances, multiple copies, unreliable).

``signal'', the default for the interface atalk , uses a call and response protocol involving SIGUSR1.

``signal/pjl'', the SIGUSR1 protocol with the addition of certain HP PJL commands which do such things as set the printer display panel message to the name of the user.

``control-d'', send a control-D character at the start and end of the job and to indicate a job break.

``pjl'', send control-d's and HP PJL commands to indicate job breaks and to set the display message.

``save/restore'', enclose each section of the job in save/restore. This is not likely to be very effective.

``newinterface'', launches a new copy of the interface program for each segment of the job. This is the default for the gs and gstcpip interfaces.

ppad feedback printer {true, False}
Indicates whether the interface program is capable of returning messages from the printer. Sometimes this is not possible, as in the case of a unidirectional interface. PPR has default feedback settings for the standard set of interfaces.

ppad ppd printer filename
specifies the PPD file name for the printer. If filename does not begin with a slash, then it is relative to the directory /usr/ppr/PPDFiles. If you create a printer queue with the ppad interface command but do not set the PPD file, PPR will will use a default PPD file, however, it probably will not deal with bins properly, may print the pages in the wrong order, and may attempt to use fonts the printer does not possess and fail to recognized the presence of fonts it has.

Using the ``ppad ppd'' command has the side effect of undoing any previous ``ppad ppdopts'' command. Therefor, you should run "ppad ppdopts`` after using ''ppad ppd" to set the PPD file.

ppad alerts printer frequency method address
This command specifies how PPR is to get printer error alert messages to an operator. This parameter is set on a per-printer basis. For the specified printer, alerts are dispatched after every frequency faults. They are dispatched by method method for which the only currently defined value is ``mail''. The message is mailed the the address address. When a new printer queue is created with the "ppad interface" command, a default alert setting is copied into its definition. This default setting is set with the ``ppad new alerts'' command.

If the alert frequency is negative, it has special meaning. The absolute value is used. When that many alerts have been posted, a message is despatched by the method described above. The posting of additional alerts do not result in more messages. When and if the printer successfully prints a job, a message is sent indicating that the error has cleared up.

ppad frequency printer frequency
Sets the alert frequency for the specified printer without changing any of the other alert parameters.

ppad flags I {never, no, yes, always} {never, no, yes, always}>
Indicates whether flag pages should be printed. The first parameter after printer is for banner pages, the second is for trailer pages. A setting of ``never'' means to not print the flag page even if the user requests it. A setting of ``no'' means to not print the flag page unless the user specifically requests it. A setting of ``yes'' means to print the flag page unless the user specifically requests that be suppressed. A setting of ``always'' means to print the flag page even if the user tries to suppress it.

ppad outputorder I {Normal, Reverse, PPD}>
Sets the order in which pages will be printed so as to achieve correct collation. If your printer stacks printed pages face up, you might want to set outputorder to ``Reverse''. If you set outputorder to ``PPD'', then the setting of the output order will be determined by information in the printer's PPD file.

ppad bins ppd I >
Sets the printer's list of bins to all the bins listed in its PPD file. You might create a new print queue and set its bin list with these steps: 1) use ``ppad interface'' to create the queue, 2) use ``ppad ppd'' to set the PPD file, 3) use ``ppad bins ppd'' 4) use ``ppad show'' to see what bin names were copied from the PPD file, 5) use ``ppad bins delete'' to remove the names of bins that are not actually installed on the printer.

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.

ppad bins add printer Ibin>
Adds bin to the indicated printer.

ppad bins delete printer bin
Deletes the indicated bin from the indicated printer.

ppad delete printer
Deletes the indicated printer.

ppad touch printer
Sends a notification to pprd which causes it to re-read the configuration file for the indicated printer. You should use this command after editing or creating a printer configuration file by hand while pprd is running.

ppad switchset printer switches
Stores the indicated switches as a macro in the printer configuration file. The macro's value may be inserted in a ppr command line by using the -I switch. See the ppr(1) man page for examples.

ppad deffiltopts printer
Instructs ppad to re-read the printer's PPD file and generate a new ``DefFiltOpts:'' line. Normally, this operation is invoked automatically whenever necessary. You might want to use command if you have modified the PPD file, have manually changed the printer's ``PPDFile:'' line, or are upgrading from a version of PPR which did not automatically generate ``DefFiltOpts:'' lines (version 1.10 or earlier).

The ``DefFiltOpts:'' line contains a list of default options which will be passed to filters which are invoked to convert other file formats to PostScript. These default options are amoung the information displayed by the ``ppad show'' command.

ppad ppdopts printer
This command examines a printers PPD file and asks for information on the presence or absence of optional printer features. Obviously, a PPD file should be selected with the ``ppad ppd'' command before this command is used. The information which the user supplies is used to answer queries from Macintosh clients. It is likely that this information will be used for other purposes in the future. the papsrv manpage will not pick up new information until it is restarted. Running ``ppad ppd'' will undo ``ppad ppdopts'', leaving all of the feature information unspecified.

ppad charge printer amount [amount]
This command sets the per-sheet charge for a printer. The parameter amount is the amount of money to be charged per sheet. The amount may be expresed in standard decimal currency notation. For instance, ``0.05'' could represent 5 cents or 5 new pence sterling.

If you wish to charge a different amount for a duplex sheet as opposed to a simplex sheet you may specify two amounts. The first is the amount to charge for each sheet printed on both sides, the second is the amount to charge for each sheet printed on one side. For instance, if you want to provide a small incentive to use duplex mode you can do this:

$ ppad charge myprn 0.07 0.05

On the other hand, if you want to charge per side you can do this:

$ ppad charge myprn 0.10 0.05

If a printer has a per-page charge, even if it is zero, it is considered a protected printer. If a printer is protected, then only users who appear in the PPR accounts database may print on it.

The per page charge may be removed from a printer by setting it to ``none''.

Group Management Subcommands

These subcommands are used to create, modify and destroy printer groups.

ppad group show group
Shows the configuration of the indicated group. The configuration is modified by the commands described below.

ppad group comment group comment
Sets a group's comment field. Highly recommended!

ppad group rotate group {true, false}
Sets the rotate option of the indicated group. If rotate is true, then PPR will attempt to evenly distribute the printing load; if rotate is false, it will use the printers at the start of the group list more heavily since printers at the end of the list will only be used when those at the head of the list are busy. By default, rotate is true.

ppad group add group printer
Adds the indicated printer to the indicated group. Even though all members may be deleted from a group, it will continue to exist and jobs may still be queued for it, they just won't print until it has some idle members again.

ppad group remove group printer
Removes the indicated printer from the indicated Igroup>.

ppad group delete I >
Deletes the indicated group. Any pending jobs will be deleted.

ppad group touch I >
Sends pprd a notification which causes it to re-read the configuration file for the indicated group. You should use this command after manually editing or creating a group configuration file if you edit or create it while pprd is running.

ppad group switchset group switches
stores the indicated switches as a macro in the group's configuration file. They may be inserted in a ppr command line by using the -I switch.

ppad group deffiltopts group
Instructs ppad to re-read all PPD files for all the member printers and generate a new ``DefFiltOpts:'' line. You might want to use this if you have modified the PPD file; have manually edited the group configuration file, changing the group membership; or have manually changed the ``PPDFile:'' line in one of the member printer configuration file; or are upgrading from a version of PPR which did not automatically generate ``DefFiltOpts:'' lines (version 1.10 or earlier).

Error Notice Commands

ppad new alerts I >
defines a default set of alert settings which will be copied into new printer definitions created with the ``ppad interface'' command. See the ``ppad alerts'' command for an explanation of the meaning of the parameters.

ppad remind
if any printers are in a fault state, this command sends a mail message, to the user ``ppr'', summarizing the problems. You might want to invoke this command periodically from cron and put a list of people to receive the messages in ~ppr/.forward. For instance, this command could be invoked at 10 AM so that the system administrator could be reminded of any printers that are not working at the beginning of the work day and again at 4 PM so that before he goes home he can fix any printer problems so that people who are working late will have working printers.


FILES

This program edits files in /usr/ppr/conf/printers and /usr/ppr/conf/groups. It creates and uses the file /etc/ppr/newprn.conf. It also writes to the spooler communications FIFO /var/spool/ppr/PIPE. The ppad media commands edit the media database file, /usr/ppr/conf/media. This program will sometimes invoke ppop to get some of its work done.


DIAGNOSTICS

Exit codes for ppad are defined in the source code file include/util_exits.h.


SEE ALSO

ppop(1), ppr(1), papsrv.conf(5), mfmodes.conf(5), papsrv(8), papsrv(8), lprsrv(8), ppuser(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.