lpforms(ADM) 19 June 1992 lpforms(ADM) Name lpforms - administer forms used with the print service Syntax /usr/lib/lpforms -f formnameoption /usr/lib/lpforms -f formname -A alert-type [ -Q integer ] [ -W integer ] /usr/lib/lpforms -f formname -A list /usr/lib/lpforms -f formname -A quiet /usr/lib/lpforms -f formnamer -A none Description The lpforms command is used to administer forms. (The functions of lpforms are also accessible through the sysadmsh(ADM) Printers - > Auxiliary -> Forms selection.) 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, and + 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, and + mount a form. 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 informa- tion 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. sysadmsh(ADM) selections are referenced where possible to simplify the task of administering forms. 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-number Page width: scaled-decimal-number Number of pages: integer Line pitch: scaled-decimal-number Character pitch: scaled-decimal-number 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 align- ment 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 align- ment 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 avail- able 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-number long, and scaled-decimal-number 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 uns- caled 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 possi- ble, 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(F) database. Also, the pitches will be passed, if possible, to each filter used in a request needing this form. Scaled-decimal-number is in lines per centimeter if a `c' is appended, and lines per inch otherwise; similarly, scaled-decimal-number is in columns per centimeter if a `c' is appended, and columns per inch oth- erwise. 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 dif- ferent 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 con- tent 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 - <DELTA> sysadmsh users select: Printers -> Auxiliary -> PPforms -> Con- figure Provide the pathname for the form as directed. The first command gets the form definition from a file; the second command gets the form defini- tion 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 <DELTA> sysadmsh users select: Printers -> Auxiliary -> PPforms - > Remove Listing form attributes The -l option is used to list the attributes of the existing form speci- fied by formname. The attributes listed are those described under ``Add- ing 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(C) 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 <DELTA> sysadmsh users select: Printers -> Auxiliary -> PPforms -> List 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 -fformname -u allow: user-list /usr/lib/lpforms -fformname -u deny:user-list sysadmsh users select: Printers -> Auxiliary -> PPforms -> Users 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 (includ- ing 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 integer 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 integer 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(C) 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 (integer r requests) integer 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 speci- fied were candidates for this form. The number (integer) listed next to each printer is the number of requests eligible for the printer. The number (integer) 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 <DELTA> sysadmsh users select: Printers -> Auxiliary -> PPforms - > Alerts -> Specify The first two commands direct the print service to send you a mail mes- sage 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 condi- tion 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 integer (the -W integer) 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 integer pending requests. Once you start receiving repeated alerts, you can direct the print ser- vice to stop sending you alerts for the current case only by giving the following command: /usr/lib/lpforms -f formname -A quiet <DELTA> sysadmsh users select: Printers -> Admin -> PPforms -> Alerts - > Terminate 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 thresh- old again, as when waiting requests are canceled or if the type of alert- ing is changed. Removing an alert definition No messages will be sent until the none option is given again with a dif- ferent alert-type. This can be used to permanently stop further messages from being sent. See also lp(C), lpadmin(ADM), terminfo(F) Authorization Permission to use this utility requires the lp authorization.