'\" te
.\"  Copyright 1989 AT&T  Copyright (c) 1997 Sun Microsystems, Inc.  All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH LPFORMS 8 "Apr 3, 1997"
.SH NAME
lpforms \- administer forms used with the LP print service
.SH SYNOPSIS
.LP
.nf
\fBlpforms\fR \fB-f\fR \fIform-name\fR \fIoption\fR
.fi

.LP
.nf
\fBlpforms\fR \fB-f\fR \fIform-name\fR \fB-A\fR \fIalert-type\fR [\fB-P\fR \fIpaper-name\fR [\fB-d\fR]]
     [\fB-Q\fR \fIrequests\fR] [\fB-W\fR \fIminutes\fR]
.fi

.SH DESCRIPTION
.sp
.LP
The \fBlpforms\fR command administers the use of preprinted forms, such as
company letterhead paper, with the LP print service. A form is specified by its
\fIform-name\fR. Users may specify a form when submitting a print request (see
\fBlp\fR(1)). The argument \fBall\fR can be used instead of  \fIform-name\fR
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 \fIform-name\fR must be mounted on a printer.
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-f\fR \fIform-name\fR\fR
.ad
.RS 16n
Specify a form.
.RE

.sp
.LP
The first form of \fBlpforms\fR  requires that one of the following
\fIoption\fRs  (\fB\(mi\fR, \fB-l\fR, \fB-F\fR, \fB-x\fR) must be used:
.sp
.ne 2
.na
\fB\fB-F\fR \fIpathname\fR\fR
.ad
.RS 15n
To add or change form \fIform-name\fR, as specified by the information in
\fIpathname\fR.
.RE

.sp
.ne 2
.na
\fB\fB\(mi\fR\fR
.ad
.RS 15n
To add or change form \fIform-name\fR, as specified by the information from
standard input.
.RE

.sp
.ne 2
.na
\fB\fB-l\fR\fR
.ad
.RS 15n
To list the attributes of form \fIform-name\fR.
.RE

.sp
.ne 2
.na
\fB\fB-x\fR\fR
.ad
.RS 15n
To delete form \fIform-name\fR (this option must be used separately; it may not
be used with any other option).
.RE

.sp
.LP
The second form of the \fBlpforms\fR command requires the  \fB-A\fR
\fIalert-type\fR option. The other options are optional.
.sp
.ne 2
.na
\fB\fB-A\fR \fIalert-type\fR\fR
.ad
.RS 24n
Defines an alert to mount the form when there are queued jobs which need it.
.RE

.sp
.ne 2
.na
\fB\fB-P\fR \fIpaper-name\fR [ \fB-d\fR ]\fR
.ad
.RS 24n
Specify the paper name when creating the form. If \fB-d\fR is specified, this
paper is the default.
.RE

.sp
.ne 2
.na
\fB\fB-Q\fR \fIrequests\fR\fR
.ad
.RS 24n
An alert will be sent when a certain number of print requests that need the
form are waiting.
.RE

.sp
.ne 2
.na
\fB\fB-W\fR \fIminutes\fR\fR
.ad
.RS 24n
An alert will be sent at intervals specified by minutes.
.RE

.SH USAGE
.SS "Adding or Changing a Form"
.sp
.LP
The \fB-F\fR \fIpathname\fR option is used to  add a new form, \fIform-name\fR,
to the LP print service, or to change the attributes of an existing form. The
form description is taken from \fIpathname\fR if the \fB-F\fR option is given,
or from the standard input if the \fB\(mi\fR option is used. One of these two
options must be used to define or change a form.
.sp
.LP
\fIpathname\fR is the path name of a file that contains  all or any subset of
the following information about the form.
.sp
.in +2
.nf
\fBPage length\fR: \fIscaled-decimal-number1\fR
\fBPage width\fR: \fIscaled-decimal-number2\fR
\fBNumber of pages\fR: \fIinteger\fR
\fBLine pitch\fR: \fIscaled-decimal-number3\fR
\fBCharacter pitch\fR: \fIscaled-decimal-number4\fR
\fBCharacter set choice\fR: \fIcharacter-set/print-wheel\fR [\fBmandatory\fR]
\fBRibbon color\fR: \fIribbon-color\fR
\fBComment:\fR
\fIcomment\fR
\fBAlignment pattern\fR: [\fIcontent-type\fR]
\fIcontent\fR
.fi
.in -2
.sp

.sp
.LP
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 \fBc\fR); numbers that show sizes in inches (marked with a trailing
\fBi\fR); and numbers that show sizes in units appropriate to use (without a
trailing letter); lines, characters, lines per inch, or characters per inch.
.sp
.LP
Except for the last two lines, the above lines may appear in any order. The
\fBComment:\fR and \fIcomment\fR items must appear in consecutive order but may
appear before the other items, and the \fBAlignment pattern:\fR and the
\fIcontent\fR items must appear in consecutive order at the end of the file.
Also, the \fIcomment\fR item may not contain a line that begins with any of the
key phrases above, unless the key phrase is preceded with a \fB>\fR sign. Any
leading > sign found in the \fIcomment\fR will be removed when the comment is
displayed. There is no case distinction among the key phrases.
.sp
.LP
When this command is issued, the form specified by \fIform-name\fR 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 \fB-u\fR option. A form may also be allowed to be used on certain
printers only.
.sp
.LP
A description of each form attribute is below:
.sp
.ne 2
.na
\fB\fBPage length\fR and \fBPage Width\fR\fR
.ad
.sp .6
.RS 4n
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 \fIscaled-decimal-number1\fR long, and
\fIscaled-decimal-number2\fR wide using the printer type as a key into the
\fBterminfo\fR(5) database. The page length and page width will also be passed,
if possible, to each filter used in a request needing this form.
.RE

.sp
.ne 2
.na
\fB\fBNumber of pages\fR\fR
.ad
.sp .6
.RS 4n
Each time the alignment pattern is printed, the LP print service will attempt
to truncate the \fIcontent\fR to a single form by, if possible, passing to each
filter the page subset of 1-\fIinteger\fR.
.RE

.sp
.ne 2
.na
\fB\fBLine pitch\fR and \fBCharacter pitch\fR\fR
.ad
.sp .6
.RS 4n
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
\fBterminfo\fR(5) database.  Also, the pitches will be passed, if possible, to
each filter used in a request needing this form. \fIscaled-decimal-number3\fR
is in lines-per-centimeter if a \fBc\fR is appended, and lines-per-inch
otherwise; similarly, \fIscaled-decimal-number4\fR is in
characters-per-centimeter if a \fBc\fR is appended, and characters-per-inch
otherwise. The character pitch can also be given as \fBelite\fR (12
characters-per-inch), \fBpica\fR (10 characters-per-inch), or \fBcompressed\fR
(as many characters-per-inch as possible).
.RE

.sp
.ne 2
.na
\fB\fBCharacter set choice\fR\fR
.ad
.sp .6
.RS 4n
When the LP print service alerts an administrator to mount this form, it will
also mention that the print wheel \fIprint-wheel\fR 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 \fBmandatory\fR 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.
.RE

.sp
.ne 2
.na
\fB\fBRibbon color\fR\fR
.ad
.sp .6
.RS 4n
When the LP print service alerts an administrator to mount this form, it will
also mention that the color of the ribbon should be \fIribbon-color\fR.
.RE

.sp
.ne 2
.na
\fB\fBComment\fR\fR
.ad
.sp .6
.RS 4n
The LP print service will display the \fIcomment\fR unaltered when a user asks
about this form  (see \fBlpstat\fR(1)).
.RE

.sp
.ne 2
.na
\fB\fBAlignment pattern\fR\fR
.ad
.sp .6
.RS 4n
When mounting this form,  an administrator can ask for the \fIcontent\fR to be
printed repeatedly, as an aid in correctly positioning the preprinted form. The
optional \fIcontent-type\fR defines the type of printer for which \fIcontent\fR
had been generated. If \fIcontent-type\fR is not given, \fBsimple\fR is
assumed. Note that the \fIcontent\fR is stored as given, and will be readable
only by the user \fBlp\fR.
.RE

.sp
.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:
.sp
.in +2
.nf
Page Length: \fB66\fR
Page Width: \fB80\fR
Number of Pages: \fB1\fR
Line Pitch: \fB6\fR
Character Pitch: \fB10\fR
Character Set Choice: \fBany\fR
Ribbon Color: \fBany\fR
.fi
.in -2
.sp

.SS "Deleting a Form"
.sp
.LP
LP print service" The \fB-x\fR option is used to  delete the form
\fIform-name\fR from the LP  print service.
.SS "Listing Form Attributes"
.sp
.LP
The \fB-l\fR option is used to  list the attributes of the existing form
\fIform-name\fR. The attributes listed are those described under \fBAdding and
Changing a Form,\fR 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  \fBlpstat\fR(1) command to examine the
non-sensitive part of the form description.
.SS "Allowing and Denying Access to a Form"
.sp
.LP
The  \fB-u\fR option, followed by the argument \fBallow:\fR\fIlogin-ID-list\fR
or \fB\fR\fB-u\fR \fBdeny:\fR\fIlogin-ID-list\fR lets you determine which users
will be allowed to specify a particular form with a print request. This option
can be used  with the \fB-F\fR or \fB\(mi\fR option, each of which is described
above under \fBAdding or Changing a Form\fR.
.sp
.LP
The \fIlogin-ID-list\fR argument may include any or all of the following
constructs:
.sp
.ne 2
.na
\fB\fIlogin-ID\fR\fR
.ad
.RS 24n
A user on any system
.RE

.sp
.ne 2
.na
\fB\fIsystem_name\fR\fB!\fR\fIlogin-ID\fR\fR
.ad
.RS 24n
A user on system \fIsystem_name\fR
.RE

.sp
.ne 2
.na
\fB\fIsystem_name\fR\fB!all\fR\fR
.ad
.RS 24n
All users on system \fIsystem_name\fR
.RE

.sp
.ne 2
.na
\fB\fBall!\fR\fIlogin-ID\fR\fR
.ad
.RS 24n
A user on all systems
.RE

.sp
.ne 2
.na
\fB\fBall\fR\fR
.ad
.RS 24n
All users on all systems
.RE

.sp
.LP
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 \fB\fR\fB-u\fR \fBallow\fR option, the users listed are
added to the allow-list and removed from the deny-list. With the \fB\fR\fB-u\fR
\fBdeny\fR option, the users listed are  added to the deny-list and removed
from the allow-list. (Both forms of the \fB-u\fR option can be run together
with the \fB-F\fR or the \fB\(mi\fR option.)
.sp
.LP
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 \fB\fR\fB-f\fR \fBdeny:all\fR. All users can be allowed access to a
form  by specifying \fB\fR\fB-f\fR \fBallow:all\fR. (This is the default.)
.SS "Setting an Alert to Mount a Form"
.sp
.LP
The \fB\fR\fB-f\fR \fIform-name\fR option is used with the \fB\fR\fB-A\fR
\fIalert-type\fR 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.
.sp
.LP
The method by which the alert is sent depends on the value of  the
\fIalert-type\fR argument specified with the \fB-A\fR option. The
\fIalert-types\fR are:
.sp
.ne 2
.na
\fB\fBmail\fR\fR
.ad
.RS 17n
Send the alert message using the \fBmail\fR command to the administrator.
.RE

.sp
.ne 2
.na
\fB\fBwrite\fR\fR
.ad
.RS 17n
Write the message, using the \fBwrite\fR command, to the terminal on which the
administrator is logged in. If the administrator is logged in on several
terminals, one is arbitrarily chosen.
.RE

.sp
.ne 2
.na
\fB\fBquiet\fR\fR
.ad
.RS 17n
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 \fIform-name\fR has been mounted and subsequently unmounted,
messages will again be sent when the number of print requests reaches the
threshold specified by the \fB-Q\fR option.
.RE

.sp
.ne 2
.na
\fB\fBshowfault\fR\fR
.ad
.RS 17n
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  \fB/etc/lp/alerts/form\fR. It is
invoked with three parameters:  \fIform_name\fR, \fBdate\fR, \fIfile_name\fR.
\fIfile_name\fR is the name of a file containing the form alert message.
.RE

.sp
.ne 2
.na
\fB\fBnone\fR\fR
.ad
.RS 17n
Do not send messages until the \fB-A\fR option is given again with a different
\fIalert-type\fR (other than \fBquiet\fR).
.RE

.sp
.ne 2
.na
\fB\fIshell-command\fR\fR
.ad
.RS 17n
Run the \fIshell-command\fR 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
\fBmail\fR and \fBwrite\fR values for this option are equivalent to the values
\fBmail\fR \fIlogin-ID\fR and \fBwrite\fR  \fIlogin-ID\fR respectively, where
\fIlogin-ID\fR 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
\fBsu\fR command to change to another login-ID. If the \fBsu\fR command has
been used  to change the user ID, then the \fIuser-name\fR  for the new ID is
used.
.RE

.sp
.ne 2
.na
\fB\fBlist\fR\fR
.ad
.RS 17n
Display the type of the alert for the form on standard output. No change is
made to the alert.
.RE

.sp
.LP
The message sent appears as follows:
.sp
.in +2
.nf
The form \fIform-name\fR needs to be mounted
on the printer(s):\fIprinter\fR (\fIinteger1\fR \fBrequests)\fR.
\fIinteger2\fR print requests await this form.
Use the \fIribbon-color\fR ribbon.
Use the \fIprint-wheel\fR print wheel, if appropriate.
.fi
.in -2
.sp

.sp
.LP
The printers listed are those that the administrator has specified as
candidates for this form. The number \fIinteger1\fR listed next to each printer
is the number of requests eligible for the printer. The number \fIinteger2\fR
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 \fIribbon-color\fR and \fIprint-wheel\fR
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.
.sp
.LP
Where any color ribbon or any print wheel can be used, the statements above
will read:
.sp
.in +2
.nf
\fBUse any ribbon.\fR
\fBUse any print-wheel.\fR
.fi
.in -2
.sp

.sp
.LP
If \fIform-name\fR is \fBany\fR, the \fIalert-type\fR defined in this command
applies to any form for which an alert has not yet been defined. If
\fIform-name\fR is \fBall\fR, the \fIalert-type\fR defined in this command
applies to all forms.
.sp
.LP
If the \fB-W\fR \fIminutes\fR option is not given,  the default procedure is
that  only one message will be sent per need to mount the form. Not specifying
the \fB-W\fR option is equivalent to specifying \fB\fR\fB-W\fR \fBonce\fR or
\fB-W\fR \fB0\fR. If \fIminutes\fR is a number greater than  \fB0\fR, an alert
will be sent at intervals specified by \fIminutes\fR.
.sp
.LP
If the \fB-Q\fR  \fIrequests\fR option is also given, the alert will be sent
when a certain number (specified by the argument \fIrequests\fR) of print
requests that need the form are waiting. If the \fB-Q\fR option is not given,
or the value of \fIrequests\fR is \fB1\fR or \fBany\fR (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.
.SS "Listing the Current Alert"
.sp
.LP
The \fB-f\fR option, followed by the \fB-A\fR option and the argument
\fBlist\fR is used to list the \fIalert-type\fR that has been defined for the
specified form \fIform-name\fR. No change is made to the alert. If
\fIform-name\fR 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.
.sp
.ne 2
.na
\fB\(mi\fR
.ad
.RS 8n
\fBWhen\fR \fIrequests\fR \fBrequests are queued:\fR \fBalert
with\fR\fIshell-command\fR \fBevery\fR \fIminutes\fR \fBminutes\fR
.RE

.sp
.ne 2
.na
\fB\(mi\fR
.ad
.RS 8n
\fBWhen\fR  \fIrequests\fR \fBrequests are queued:\fR \fBwrite to\fR
\fIuser-name\fR \fBevery\fR \fIminutes\fR \fBminutes\fR
.RE

.sp
.ne 2
.na
\fB\(mi\fR
.ad
.RS 8n
\fBWhen\fR \fIrequests\fR \fBrequests are queued:\fR \fBmail to\fR
\fIuser-name\fR \fBevery\fR \fIminutes\fR \fBminutes\fR
.RE

.sp
.ne 2
.na
\fB\(mi\fR
.ad
.RS 8n
\fBNo alert\fR
.RE

.sp
.LP
The phrase \fBevery\fR \fIminutes\fR \fBminutes\fR is replaced with \fBonce\fR
if \fIminutes\fR (\fB-W\fR\fI\fR\fIminutes\fR) is 0.
.SS "Terminating an Active Alert"
.sp
.LP
The \fB-A\fR \fBquiet\fR 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 \fIrequests\fR.
.SS "Removing an Alert Definition"
.sp
.LP
No messages will be sent after the \fB-A\fR \fBnone\fR option is used until the
\fB-A\fR option is given again with a different \fIalert-type\fR. This can be
used  to permanently stop further messages from being sent as any existing
alert definition for the form will be removed.
.SS "Large File Behavior"
.sp
.LP
See \fBlargefile\fR(7) for the description of the behavior of \fBlpforms\fR
when encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).
.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 12n
Successful completion.
.RE

.sp
.ne 2
.na
\fBnon-zero\fR
.ad
.RS 12n
An error occurred.
.RE

.SH FILES
.sp
.ne 2
.na
\fB\fB/etc/lp/alerts/form\fR\fR
.ad
.RS 23n
Fault handler for \fBlpform\fR.
.RE

.SH SEE ALSO
.sp
.LP
.BR lp (1),
.BR lpstat (1),
.BR terminfo (5),
.BR attributes (7),
.BR largefile (7),
.BR lpadmin (8)
.sp
.LP
\fI\fR