Tribblix: manual page: lpforms.8

LPFORMS(8) Maintenance Commands and Procedures LPFORMS(8)

NAME

lpforms - administer forms used with the LP print service

SYNOPSIS

lpforms -f form-name option

lpforms -f form-name -A alert-type [-P paper-name [-d]]
[-Q requests] [-W minutes]

DESCRIPTION

The lpforms command administers the use of preprinted forms, such as
company letterhead paper, with the LP print service. A form is
specified by its form-name. Users may specify a form when submitting
a print request (see lp(1)). The argument all can be used instead of
form-name with either of the command lines shown above. The first
command line allows the administrator to add, change, and delete
forms, to list the attributes of an existing form, and to allow and
deny users access to particular forms. The second command line is
used to establish the method by which the administrator is alerted
that the form form-name must be mounted on a printer.

OPTIONS

The following options are supported:

-f form-name
Specify a form.

The first form of lpforms requires that one of the following options
(-, -l, -F, -x) must be used:

-F pathname
To add or change form form-name, as specified by the
information in pathname.

-
To add or change form form-name, as specified by the
information from standard input.

-l
To list the attributes of form form-name.

-x
To delete form form-name (this option must be used
separately; it may not be used with any other option).

The second form of the lpforms command requires the -A alert-type
option. The other options are optional.

-A alert-type
Defines an alert to mount the form when there
are queued jobs which need it.

-P paper-name [ -d ]
Specify the paper name when creating the
form. If -d is specified, this paper is the
default.

-Q requests
An alert will be sent when a certain number
of print requests that need the form are
waiting.

-W minutes
An alert will be sent at intervals specified
by minutes.

USAGE

Adding or Changing a Form

The -F pathname option is used to add a new form, form-name, to the
LP print service, or to change the attributes of an existing form.
The form description is taken from pathname if the -F option is
given, or from the standard input if the - option is used. One of
these two options must be used to define or change a form.

pathname is the path name of a file that contains all or any subset
of the following information about the form.

Page length: scaled-decimal-number1
Page width: scaled-decimal-number2
Number of pages: integer
Line pitch: scaled-decimal-number3
Character pitch: scaled-decimal-number4
Character set choice: character-set/print-wheel [mandatory]
Ribbon color: ribbon-color
Comment:
comment
Alignment pattern: [content-type]
content

The term ``scaled-decimal-number'' refers to a non-negative number
used to indicate a unit of size. The type of unit is shown by a
``trailing'' letter attached to the number. Three types of scaled
decimal numbers can be used with the LP print service: numbers that
show sizes in centimeters (marked with a trailing c); numbers that
show sizes in inches (marked with a trailing i); and numbers that
show sizes in units appropriate to use (without a trailing letter);
lines, characters, lines per inch, or characters per inch.

Except for the last two lines, the above lines may appear in any
order. The Comment: and comment items must appear in consecutive
order but may appear before the other items, and the Alignment
pattern: and the content items must appear in consecutive order at
the end of the file. Also, the comment item may not contain a line
that begins with any of the key phrases above, unless the key phrase
is preceded with a > sign. Any leading > sign found in the comment
will be removed when the comment is displayed. There is no case
distinction among the key phrases.

When this command is issued, the form specified by form-name is added
to the list of forms. If the form already exists, its description is
changed to reflect the new information. Once added, a form is
available for use in a print request, except where access to the form
has been restricted, as described under the -u option. A form may
also be allowed to be used on certain printers only.

A description of each form attribute is below:

Page length and Page Width

Before printing the content of a print request needing this form,
the generic interface program provided with the LP print service
will initialize the physical printer to handle pages scaled-
decimal-number1 long, and scaled-decimal-number2 wide using the
printer type as a key into the terminfo(5) database. The page
length and page width will also be passed, if possible, to each
filter used in a request needing this form.

Number of pages

Each time the alignment pattern is printed, the LP print service
will attempt to truncate the content to a single form by, if
possible, passing to each filter the page subset of 1-integer.

Line pitch and Character pitch

Before printing the content of a print request needing this form,
the interface program provided with the LP print service will
initialize the physical printer to handle these pitches, using
the printer type as a key into the terminfo(5) database. Also,
the pitches will be passed, if possible, to each filter used in a
request needing this form. scaled-decimal-number3 is in lines-
per-centimeter if a c is appended, and lines-per-inch otherwise;
similarly, scaled-decimal-number4 is in characters-per-centimeter
if a c is appended, and characters-per-inch otherwise. The
character pitch can also be given as elite (12 characters-per-
inch), pica (10 characters-per-inch), or compressed (as many
characters-per-inch as possible).

Character set choice

When the LP print service alerts an administrator to mount this
form, it will also mention that the print wheel print-wheel
should be used on those printers that take print wheels. If
printing with this form is to be done on a printer that has
selectable or loadable character sets instead of print wheels,
the interface programs provided with the LP print service will
automatically select or load the correct character set. If
mandatory is appended, a user is not allowed to select a
different character set for use with the form; otherwise, the
character set or print wheel named is a suggestion and a default
only.

Ribbon color

When the LP print service alerts an administrator to mount this
form, it will also mention that the color of the ribbon should be
ribbon-color.

Comment

The LP print service will display the comment unaltered when a
user asks about this form (see lpstat(1)).

Alignment pattern

When mounting this form, an administrator can ask for the
content to be printed repeatedly, as an aid in correctly
positioning the preprinted form. The optional content-type
defines the type of printer for which content had been generated.
If content-type is not given, simple is assumed. Note that the
content is stored as given, and will be readable only by the user
lp.

When an existing form is changed with this command, items missing in
the new information are left as they were. When a new form is added
with this command, missing items will get the following defaults:

Page Length: 66
Page Width: 80
Number of Pages: 1
Line Pitch: 6
Character Pitch: 10
Character Set Choice: any
Ribbon Color: any

Deleting a Form

LP print service" The -x option is used to delete the form form-name
from the LP print service.

Listing Form Attributes

The -l option is used to list the attributes of the existing form
form-name. The attributes listed are those described under Adding and
Changing a Form, above. Because of the potentially sensitive nature
of the alignment pattern, only the administrator can examine the
form with this command. Other people may use the lpstat(1) command
to examine the non-sensitive part of the form description.

Allowing and Denying Access to a Form

The -u option, followed by the argument allow:login-ID-list or -u
deny:login-ID-list lets you determine which users will be allowed to
specify a particular form with a print request. This option can be
used with the -F or - option, each of which is described above under
Adding or Changing a Form.

The login-ID-list argument may include any or all of the following
constructs:

login-ID
A user on any system

system_name!login-ID
A user on system system_name

system_name!all
All users on system system_name

all!login-ID
A user on all systems

all
All users on all systems

The LP print service keeps two lists of users for each form: an
``allow-list'' of people allowed to use the form, and a ``deny-list''
of people that may not use the form. With the -u allow option, the
users listed are added to the allow-list and removed from the deny-
list. With the -u deny option, the users listed are added to the
deny-list and removed from the allow-list. (Both forms of the -u
option can be run together with the -F or the - option.)

If the allow-list is not empty, only the users in the list are
allowed access to the form, regardless of the content of the deny-
list. If the allow-list is empty but the deny-list is not, the users
in the deny-list may not use the form, (but all others may use it).
All users can be denied access to a form by specifying -f deny:all.
All users can be allowed access to a form by specifying -f
allow:all. (This is the default.)

Setting an Alert to Mount a Form

The -f form-name option is used with the -A alert-type option to
define an alert to mount the form when there are queued jobs which
need it. If this option is not used to arrange alerting for a form,
no alert will be sent for that form.

The method by which the alert is sent depends on the value of the
alert-type argument specified with the -A option. The alert-types
are:

mail
Send the alert message using the mail command to the
administrator.

write
Write the message, using the write command, to the
terminal on which the administrator is logged in. If
the administrator is logged in on several terminals,
one is arbitrarily chosen.

quiet
Do not send messages for the current condition. An
administrator can use this option to temporarily
stop receiving further messages about a known
problem. Once the form form-name has been mounted
and subsequently unmounted, messages will again be
sent when the number of print requests reaches the
threshold specified by the -Q option.

showfault
Attempt to execute a form alert handler on each
system that has a print job for that form in the
queue. The fault handler is /etc/lp/alerts/form.
It is invoked with three parameters: form_name,
date, file_name. file_name is the name of a file
containing the form alert message.

none
Do not send messages until the -A option is given
again with a different alert-type (other than
quiet).

shell-command
Run the shell-command each time the alert needs to
be sent. The shell command should expect the message
in standard input. If there are blank spaces
embedded in the command, enclose the command in
quotes. Note that the mail and write values for this
option are equivalent to the values mail login-ID
and write login-ID respectively, where login-ID is
the current name for the administrator. This will be
the login name of the person submitting this command
unless he or she has used the su command to change
to another login-ID. If the su command has been used
to change the user ID, then the user-name for the
new ID is used.

list
Display the type of the alert for the form on
standard output. No change is made to the alert.

The message sent appears as follows:

The form form-name needs to be mounted
on the printer(s):printer (integer1 requests).
integer2 print requests await this form.
Use the ribbon-color ribbon.
Use the print-wheel print wheel, if appropriate.

The printers listed are those that the administrator has specified as
candidates for this form. The number integer1 listed next to each
printer is the number of requests eligible for the printer. The
number integer2 shown after the list of printers is the total number
of requests awaiting the form. It will be less than the sum of the
other numbers if some requests can be handled by more than one
printer. The ribbon-color and print-wheel are those specified in the
form description. The last line in the message is always sent, even
if none of the printers listed use print wheels, because the
administrator may choose to mount the form on a printer that does use
a print wheel.

Where any color ribbon or any print wheel can be used, the statements
above will read:

Use any ribbon.
Use any print-wheel.

If form-name is any, the alert-type defined in this command applies
to any form for which an alert has not yet been defined. If form-name
is all, the alert-type defined in this command applies to all forms.

If the -W minutes option is not given, the default procedure is that
only one message will be sent per need to mount the form. Not
specifying the -W option is equivalent to specifying -W once or -W 0.
If minutes is a number greater than 0, an alert will be sent at
intervals specified by minutes.

If the -Q requests option is also given, the alert will be sent when
a certain number (specified by the argument requests) of print
requests that need the form are waiting. If the -Q option is not
given, or the value of requests is 1 or any (which are both the
default), a message is sent as soon as anyone submits a print
request for the form when it is not mounted.

Listing the Current Alert

The -f option, followed by the -A option and the argument list is
used to list the alert-type that has been defined for the specified
form form-name. No change is made to the alert. If form-name is
recognized by the LP print service, one of the following lines is
sent to the standard output, depending on the type of alert for the
form.

-
When requests requests are queued: alert withshell-command
every minutes minutes

-
When requests requests are queued: write to user-name every
minutes minutes

-
When requests requests are queued: mail to user-name every
minutes minutes

-
No alert

The phrase every minutes minutes is replaced with once if minutes
(-Wminutes) is 0.

Terminating an Active Alert

The -A quiet option is used to stop messages for the current
condition. An administrator can use this option to temporarily stop
receiving further messages about a known problem. Once the form has
been mounted and then unmounted, messages will again be sent when the
number of print requests reaches the threshold requests.

Removing an Alert Definition

No messages will be sent after the -A none option is used until the
-A option is given again with a different alert-type. This can be
used to permanently stop further messages from being sent as any
existing alert definition for the form will be removed.

Large File Behavior

See largefile(7) for the description of the behavior of lpforms when
encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).

EXIT STATUS

The following exit values are returned:

0
Successful completion.

non-zero
An error occurred.

FILES

/etc/lp/alerts/form
Fault handler for lpform.