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: 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:

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:

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:

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)
© 2005 The SCO Group, Inc. All rights reserved.
SCO OpenServer Release 6.0.0 -- 03 June 2005