lpforms(ADM)
lpforms --
administer forms used with the print service
Syntax
/usr/lib/lpforms -f formname option
/usr/lib/lpforms -f formname -A
alert-type
[ -Q integer1 ]
[ -W integer2 ]
/usr/lib/lpforms -f formname -A list
/usr/lib/lpforms -f formname -A quiet
/usr/lib/lpforms -f formname -A none
Description
The lpforms command is used to administer forms.
(The functions of lpforms are also accessible through the
Printer Manager.)
A preprinted form is a paper image of a blank form
that you can load into your printer.
An application typically generates a file that,
when printed on the blank form, fills out the form.
Common examples of forms are:
-
blank checks
-
vouchers
-
receipts
-
labels
-
company letterhead
-
special paper stock
Typically, several copies of the blank form are loaded into the printer
either as a tray of single sheets or as a box of fan-folded paper.
The print service helps you manage the use of preprinted forms
but does not provide your application any help in filling out a form.
This is solely your application's responsibility.
The print service, however, keeps track of which print requests need
special forms mounted and which forms are currently mounted,
and it can alert you to the need to mount a new form.
Using this command you can:
-
define a new form
-
change an old form
-
remove a form
-
examine a form
-
restrict user access to a form
-
arrange alerting to the need to mount a form
The
lpadmin(ADM)
command is used to mount forms.
Options
The following options are available with the first form of the
command, /usr/lib/lpforms -f formname option:
-F pathname-
to add or change a form as specified by the information in pathname.
--
to add or change a form, and supply information from standard input.
-x-
to delete a form. This option must be used separately;
it cannot be used with any other option.
-l-
to list the attributes of a form. This option must be used separately;
it cannot be used with any other option.
-u allow:user-list-
to allow users to request a form. This option can be used
with the -F or - option.
-u deny:user-list-
to deny users access to a form.
This option can be used with the -F or - option.
-A alert-type-
to define the type of alerting method to be used. The values are
list, quiet, none, mail,
write, and `command'.
-Q number-
defines the threshold in number of requests waiting, that is, used
to restart the alert. Must be used with -A.
-W minutes-
defines the number of minutes between alerts. Must be used
with -A.
Each of these options is explained in the sections that follow.
Adding or changing a form
The -F pathname option is used to
add a new form 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 given.
One of the two options must be given to define or change a form.
pathname is the pathname 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
Except for the last two lines, the above lines can appear in any order.
The Comment: and comment items must appear in
consecutive order but can 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 cannot 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.
Case distinctions in the key phrases are ignored.
The print service does not try to mask sensitive information in an
alignment pattern.
If you do not want sensitive information printed on sample
forms -- probably the case when you align checks, for
instance -- then you should mask the appropriate data.
The print service keeps the alignment pattern stored in a safe
place, where only you (that is, the user lp and the super user
root) can read it.
Upon issuing this command, the form named in formname
is added to the list of forms.
If the form already exists, its description is changed to reflect
the new information in the input.
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 allow: option.
A form may also be allowed to be used on certain printers only.
A description of each form attribute is given 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(F)
database.
A scaled-decimal-number is an optionally
scaled decimal number that gives a size in lines,
columns, inches, or centimeters, as appropriate.
The scale is indicated by appending the letter ``i'', for inches,
or the letter ``c'', for centimeters. For length or width settings,
an unscaled number indicates lines or columns;
for line pitch or character pitch settings, an unscaled number indicates
lines per inch or characters per inch (the same as a number scaled
with ``i'').
For example, length=66 indicates a page length of 66 lines,
length=11i indicates a page length of 11 inches, and
length=27.94c indicates a page length of 27.94 centimeters.
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 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 programs 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
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 columns per centimeter if a ``c'' is appended,
and columns 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(C)).
Alignment pattern-
When mounting this form, an administrator can ask that the
content be repeatedly printed
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
Comment: no default
Alignment Pattern: no default
Use one of the following commands to define the form:
/usr/lib/lpforms -f formname -F filename
/usr/lib/lpforms -f formname -
Provide the pathname for the form as directed.
The first command gets the form definition from a file;
the second command gets the form definition from you
through the standard input.
The formname can be anything you choose.
If you need to change a form, just re-enter one of the same commands.
You need only give the changed information;
information you leave out stays the same.
Deleting a form
The -x option is used to delete the form specified
in formname from the lp print service.
Use the following command to remove a form:
/usr/lib/lpforms -f formname -x
Listing form attributes
The -l option is used to list the attributes of the existing
form specified by formname. The attributes listed are those
described under ``Adding or changing a form''.
Because of the potentially sensitive nature of the alignment pattern,
only the administrator can examine the form with this command.
Other people can use the
lpstat
command to examine the non-sensitive part of the form description.
Use one of the following commands to examine a defined form:
/usr/lib/lpforms -f formname -l
/usr/lib/lpforms -f formname -l >filename
lpstat -f formname
lpstat -f formname -l
The first two commands present the definition of the form;
the second command captures this definition in a file,
which can later be used to redefine the form if you
inadvertently remove the form from the print service.
The last two commands present the status of the form,
with the second of the two giving a long form of output
similar to the output of lpforms -l.
Allowing and denying access to a form
The lp print service keeps two lists of users for each form,
an allow-list and a deny-list of people denied
access to 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 removed from
the allow-list and added to the deny-list.
The rules are as follows:
-
An allow list contains those users allowed to use the form.
A deny list contains those users denied access to the form.
-
If the allow list is not empty, the deny list is ignored.
If the allow list is empty, the deny list is used.
If both lists are empty, there are no restrictions on who can use the form.
-
Putting any or all into the allow list allows everybody
to use the form; putting any or all into the deny list
denies everybody use of the form, except the user lp
and the super user root.
You can define who can use the form using the following commands:
/usr/lib/lpforms -f formname -u allow:user-list
/usr/lib/lpforms -f formname -u deny:user-list
The user-list is a list of names of users separated by a
comma or space.
If you use spaces to separate the names, enclose the entire list (including
the allow: or deny: but not the -u) in quotes.
The first command adds the names to the allow list and removes
them from the deny list.
The second command adds the names to the deny list and removes
them from the allow list.
Using allow:all allows everybody; using deny:all
denies everybody.
If you do not add user names to the allow or deny lists,
the print service assumes that everybody can use the form.
Alerting to mount forms
The second variation of the lpforms command is used to arrange
for the alerting to mount forms on a printer.
When integer1
print requests needing the preprinted form formname
become queued because no printer satisfying all the needs of
the requests has the form mounted, and for as long as this condition remains,
an alert is sent to the administrator every integer2
minutes until the form is mounted on a qualifying printer.
If the formname is all, the alerting defined in this command
applies to all existing forms.
No alerting is done for a backlog of print requests
needing a form if the administrator does not use this option.
You can choose one of several ways to receive an alert:
-
You can receive an alert via electronic mail (see
mail(C)).
-
You can receive an alert written to whatever terminal
on which you are logged in (see
write(C)).
-
You can receive an alert through a program of your choice.
-
You can receive no alerts.
The method for sending the alert depends on the value of the -A
option.
write-
The message is sent via
write
to the terminal on which the administrator is logged in when the alert arises.
If the administrator is logged in on several terminals, one is chosen
arbitrarily.
mail-
The message is sent via mail to the administrator who issues this
command.
The message sent appears as follows:
The form form-name needs to be mounted on the printer(s).
printer-list (integer3 requests)
integer4 print request awaits this form.
Use the ribbon-color ribbon.
Use the print-wheel print wheel, if appropriate.
The printers listed are those that the administrator had earlier specified
were candidates for this form.
The number (integer3
listed next to each printer is the number of requests eligible for the printer.
The number (integer4 shown after the printer
list 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 given in the form description.
The last line in the message is given
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.
shell-command-
The shell-command is run each time the alert needs to be sent.
The shell command should expect the message as standard input.
Note that the mail and write values for the -A
command are equivalent to the values mail username
and write username, respectively, where username
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(C)
command to change to another user ID.
If the su command has been used to change the user ID,
then the username for the new ID is used.
If you elect to receive no alerts, you are responsible for checking to see
if any print requests have not printed because the proper form is not mounted.
In addition to the method of alerting, you can also set the number of
requests that must be queued before you are alerted, and you can arrange
for repeated alerts every few minutes until the form is mounted.
You can choose the rate of repeated alerts, or you can choose to receive
only one alert per form.
To arrange for alerting to the need to mount a form,
enter one of the following commands:
/usr/lib/lpforms -f formname -A mail -Q integer -W minutes
/usr/lib/lpforms -f formname -A write -Q integer -W minutes
/usr/lib/lpforms -f formname -A 'command' -Q integer -W minutes
/usr/lib/lpforms -f formname -A none
The first two commands direct the print service to send you a mail
message or to write the message directly to your terminal, respectively,
for each alert. The third command directs the print service to run
command for each alert.
The shell environment currently in effect when you enter the third
command is saved and restored for the execution of command;
this includes the environment variables, user and group IDs,
and current directory.
The fourth command directs the print service not to send you an
alert when the form needs to be mounted.
integer is the number of requests that need to be waiting
for the form, and minutes
is the number of minutes between repeated alerts.
If you want mail sent or a message written to another person
when a printer fault occurs, you must use the third command listed.
Use the
-A 'mail username' or
-A 'write username' option.
If formname is all in any of the previous commands,
the alerting condition applies to all forms.
If you do not define an alert method for a form,
you do not receive an alert for it.
If you do define a method but do not give the -W option,
you are alerted once for each occasion.
Listing the current alert
The following lpforms syntax is used to
list the type of the alert for the specified form:
/usr/lib/lpforms -f formname -A list
No change is made to the alert.
If formname 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 integer are queued:
alert with shell-command every integer minutes
When integer are queued:
write to username every integer minutes
When integer are queued:
mail to username every integer minutes
No alert
The phrase ``every integer minutes'' is
replaced with ``once'' if
integer2
(the -W integer2) is 0.
Terminating an active alert
The 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 queue size reaches
integer2 pending requests.
Once you start receiving repeated alerts,
you can direct the print service to stop sending you alerts for the
current case only by giving the following command:
/usr/lib/lpforms -f formname -A quiet
Once the form is mounted and unmounted again,
alerts start again if too many requests are waiting.
Alerts also restart if the number of requests waiting falls
below the -Q threshold and then rises up to the
-Q threshold again, as when waiting requests are canceled
or if the type of alerting is changed.
Removing an alert definition
No messages will be sent until the none option is given again with
a different alert-type.
This can be used to permanently stop further messages from being sent.
Authorization
Permission to use this utility requires the lp authorization in
authorize(F).
See also
lp(C),
lpadmin(ADM),
terminfo(F)
© 2003 Caldera International, Inc. All rights reserved.
SCO OpenServer Release 5.0.7 -- 11 February 2003