TITLE: #155 - Configuring and using the Line Printer Intercept on SCO KEYWORDS: lpfax line printer intercept LPI RELEASE: Faximum Client/Server for SCO UNIX and Open Server (1.0 and 2.3) Faximum ELS and Faximum PLUS (v2.2 & 4) for SCO CLASSIFICATION: SCO-CS SCO-PLUS PROBLEM: Customer wishes to install and use the line printer intercept feature CAUSE: N/A SOLUTION: NOTE -- This Technote applies to SCO UNIX and related systems. Please see TN#230 for Faximum ELS/PLUS on Linux. To install the Line Printer Intercept on your SCO UNIX, SCO Open Server 5, SCO (Caldera) UnixWare 7, or Caldera Open UNIX 8 system: 1. Disable the line printer scheduler by typing: /usr/lib/lpshut Check that no printing is happening before you type this command so as to minimise any disruption to other print jobs. 2. Create a "null" file by typing: touch /dev/lpnull chown lp /dev/lpnull chgrp lp /dev/lpnull chmod 660 /dev/lpnull The "chgrp" command may return an error which may be ignored. This file is needed to fool the UNIX line printer administration command intot thinking a device is associated with the printer we are about to define. 3. If you are configuring the Faximum Line Printer Intercept on SCO UnixWare 7 or Caldera Open UNIX 8 then you must edit the interface script prior to proceeding to the next step. Please edit the file /opt/faximum/lp/fax and add the following line as the first line of the file (without any white space before the # character): #!/usr/bin/sh 4. Add a new printer to the line printer spooling system by typing one of the following: [for Faximum Client/Server] /usr/lib/lpadmin -p fax -i /opt/FAXclient/lp/model -v /dev/lpnull [for Faximum ELS or PLUS] /usr/lib/lpadmin -p fax -i /opt/faximum/lp/fax -v /dev/lpnull Do not be concerned if you see an error of the form: UX:lpadmin: WARNING: "/dev/lpnull" is accessible by others. TO FIX: If other users can access it you may get unwanted output. If this is not what you want change the owner to "lp" and change the mode to 0600. Processing continues. 4. Enable the line printer scheduler and fax printer by typing the following: /usr/lib/lpsched enable fax /usr/lib/accept fax You ought to see a sequence of responses similar to the following: # /usr/lib/lpsched Print services started. # enable fax printer "fax" now enabled # /usr/lib/accept fax destination "fax" now accepting requests To use the Line Printer Intercept on your SCO system follow the instructions in the attached document. TROUBLESHOOTING =============== 1. Examine the Faximum system log (normally in /var/opt/faximum/log) for error messages that might indicate the source of the problem. If there are no entries in the log then proceed with the following steps. If there are entries showing that the fax has been queued but is not being sent out then the most likely possibility is that the default class specified in the fax script is to send the fax out overnight. Edit the fax script and change the default class to something more appropriate to your needs (for example, "Rush (Highest Cost)"). This script can be found in the directory "/usr/spool/lp/admins/lp/interfaces". 2. If nothing appears to be queued when you submit a request to the Line Printer Intercept, then edit the fax script in the directory "/usr/spool/lp/admins/lp/interfaces" and add the following line as the second line in the file: exec > /tmp/lpi.$$ 2>&1 3. Submit a request to the Line Printer Intercept and then examine any files in /tmp that start with the sequence "lpi." followed by a number. These files may contain error messages that indicate the cause of the problem. If the messages in these files are not obvious, please email them to email@example.com for analysis. ============================================================================== The Line Printer Intercept Introduction ---------------------------------------------------------------------- Faximum's line printer intercept makes it possible to "fax-enable" existing software applications easily. For example, using the line printer intercept you can link your existing accounting application to Faximum and automatically fax out your invoices-without having to write any code. The line printer intercept to Faximum provides a very simple and straightforward mechanism for sending faxes automatically. All that is necessary is that the document to be faxed (letter, invoice, etc.) contain within it the information Faximum needs to prepare the fax. In the simplest case, just the fax number. For example, including the string //FAX(fax=1 604 926 8182) somewhere in the document is enough. The document is then sent to the standard UNIX spooler (using the lp command and specifying the fax pseudo-printer): lp -dfax < document. Faximum extracts the fax number and other information (such as the business form to use as an overlay as well as the priority of the fax) from the //FAX parameter list and then removes the //FAX lines so they do not appear on the faxed document. The faxes are then prepared and sent just like any other fax request. Not only can the line printer intercept take single documents, it can automatically process single print files which contain faxes to multiple destinations. It can handle an entire invoice run, with hundreds of invoices, and correctly deliver each invoice to the appropriate fax machine. In many cases, your accounting system can be easily set up to include the necessary information in the print files and to send it to the fax printer. You can also use this mechanism through your word processing package (WordPerfect, Word, or other) to send faxes from your WP program. You can even broadcast faxes using the mail merge features of your existing word processing software! The line printer intercept can also handle overlays so that the fax can appear as if printed on an invoice, purchase order, letterhead, or other pre-printed business form. Overview The line printer intercept operates by examining the information sent to the fax pseudo-printer looking for the sequence "//FAX(". The line printer intercept then extracts the parameters that follow and uses the information to prepare the fax. For example, one could fax a letter to someone by preparing the following file: //FAX(fax=1 602 926 8182;style=Company Letterhead) 14 December 1992 Dear Sirs: ..... And then by sending this file to the fax pseudo-printer: lp -dfax < file Note that the line //FAX(fax....) is removed by Faximum before the fax is prepared and therefore does not appear on the fax itself. As we will see below, there are a number of parameters that can be set in order to tell Faximum exactly how to prepare the fax. In addition, defaults can be set up so that commonly used parameters need not be specified each time. Indeed, one can have multiple fax pseudo-printers, each with its own set of parameters. For example, the fax_invoice pseudo-printer could be set up to overlay the invoice form automatically, while fax_letter could be set up to use letterhead. As many //FAX lines may be included as necessary to provide all of the parameters to Faximum. Since there is no limit on the length of a line, it is also possible to specify all of the parameters on a very long line. Many parameters will be set by default if not specified so that it is not necessary to include every parameter. Note, however, that all of the //FAX lines related to a single fax must appear on the same page. If the line printer detects a page break (i.e. a formfeed or CTRL-L character) and then sees a line containing //FAX, it will assume that this is the first page of a new fax to a different destination. The //FAX sequence need not be on the first line of the fax, nor need it be the only thing on the line. Fax Parameters The general format of a line printer fax command line is: //FAX(parameter;parameter;parameter...) There is no limit to the number of parameters permitted on a single fax command line nor is there a limit on the number of fax command lines that may be present. The closing parenthesis of the fax command line must appear on the same line as the opening sequence //FAX(. If more than one fax command line is present, they must all appear on the same page. Parameters must be separated by a semi-colon and the last parameter terminated by a closing parenthesis. If it is necessary to include a semi-colon or closing parenthesis in the string defining the value for a parameter, then they must be escaped using a back-slash (`\'). For example: //FAX(message=Invoices\; Statements\; and other stuff) Matched or escaped parentheses may be used within parameters strings. For example: //FAX(message=Look at (this) or try \) a right paren) Finally, quotation marks (single or double) may be used to escape the entire contents of the parameters string: //FAX(message="Anything goes including ;) characters") The following parameter names may be specified in either upper or lower case. fax The fax number. If intelligent dialling is enabled and this number does not consist of four components, then the default country code and area code will be added automatically. file The name of a file to be attached to the end of the fax. The line printer intercept will determine the type of the file based on an examination of the first several characters of the file. Up to four files may be attached by specifying the parameters file.1, file.2, etc. from The information about the sender to include on the cover sheet (if a cover sheet is to be generated according to the style specified). If this information is missing then the from information on the cover sheet will remain blank. This field may specify a single value, or may provide up to three sub-fields: from.name, from.title, and from.dept. mailaddr The name of the user to whom mail is to be sent if the request is unsuccessful. By default, mail will be sent to the user who ran the line printer spooler command. message The text of a short message to be placed on the cover sheet. For example: //FAX(fax=555 1212) //FAX(message=Confirmation of Verbal Order) Alternatively, a text file containing the coversheet message that is readable by all (i.e. r permission for everyone) may be referenced using the messagefile parameter. For example: //FAX(fax=555 1212;messagefile=/u/ar/msg/dunning) print Specifies that the fax ought to be sent to the printer before being transmitted. It is possible to specify any or all of the cover sheet (COVER), attachments (FILES or ATTACHMENTS), or confirmation (CONFIRM). The case of the keywords is not important. For example, print = Cover + Confirm. The confirmation print-out consists of a reduced-size image of the first page of the fax along with information confirming the successful transmission of the fax. To support previous software, the values No and Yes are also supported (yes is equivalent to Cover + Files). If more than one destination has been specified, only the cover sheet and attachments for the first destination will be printed (confirmations, if requested, will be printed for each destination). If yes, then the printer parameter (below) must be specified. Optional (default is no). printer The name of the printer (from the printer database) to use to print the fax (the printer database specifies the command to use to access a printer on your UNIX system). Required if the print parameter (above) is set to yes. subject The text of the subject line to be placed on the cover sheet (if a cover sheet is to be generated according to the style specified). If this information is missing then the subject information on the cover sheet will remain blank. to The addressing information to place on the cover sheet (if a cover sheet is to be generated according to the style specified). If this information is missing then the to information on the cover sheet (if present) will remain blank. This field may specify a single value, or may provide up to four sub-fields: to.name, to.title, to.dept, and to.company. For example: //FAX(to.name=John Doe;to.dept=Accounting) //FAX(to.company=ACME Concrete) The following three parameters are related to the database that control the operation of Faximum. More information on these databases may be found in Chapter 2 of the Faximum PLUS Reference Manual, or in the online help. account The account the fax is to be charged to.* class The class of service to be used. The class of service specifies various scheduling parameters that affect when the fax will be sent (and if long distance, how much it will cost). * style The style of the fax to be used. The style of a fax specifies various parameters that affect the appearance of the fax. Included are such things as: the design and layout of the cover sheet; the resolution and page length; and the form overlay (if any) to use. * * If these fields are blank then a default value will be used if the fax is submitted through the UNIX line printer spooler. If, however, you are using the Line Printer Intercept through a word processing program such as Word Pefect, then you must specify values for each of these three parameters as no defaults are available. Note also that the account and class parameters are only available with Faximum PLUS and Client/Server (but not Faximum ELS). //FAX versus //-FAX As mentioned earlier in this document, the Faximum line printer intercept strips out the //FAX sequence and following parameters so they do not appear on the fax. An obvious question is what effect this has on the alignment of the other printed information. If the parameters information is introduced with //FAX, then each character of the //FAX sequence along with the following parameters will be replaced with a space character and the new-line at the end of the line will be kept. This means that the position of other information on the page (including information on the same line as the //FAX sequence) will be the same as if the document were printed with the //FAX sequence. In some cases this is not what is desired. In certain circumstances it is desirable to add the //FAX sequence as a new line before the body of the (say) invoice and have the entire //FAX line, including the new-line character, removed. If this behaviour is desired, then (a) use the sequence //-FAX instead of //FAX, and (b) start the //-FAX sequence in column one and do not include any non-blank characters after the closing `)'. In general, //FAX ought to be used with programs such as word processing programs where the line containing //FAX is counted by the application as one of the printed lines. For applications in which the line containing the //-FAX is extra and not counted when determining page breaks etc., then the //-FAX form ought to be used. Form Alignment One of the problems that will probably have to be addressed when setting up the line printer intercept to print, (say) invoices, is the alignment of the data on the form. The positioning of the data on the form can be changed by varying the top and left margins as well as changing the horizontal and vertical spacing (i.e. the character per inch horizontally and the line per inch vertically). If your version of Faximum that supports the faxing of PCL files, this can be done either by inserting the appropriate HP PCL control sequence before each page of data as it is printed, or by modifying the line printer interface script itself. If your system does not support PCL, then you can use asciitiff commands instead to adjust the margins (see the manual page for the asciitiff command for the details). The advantage of modifying the line printer interface script is that the application itself does not have to be changed. The disadvantage is that should you be using more than one type of form it will probably be necessary to define a different line printer interface for each form since the alignment of each form will differ (and the interface script will be tuned for one type of form only). Should you decide to edit the line printer interface script, complete instructions may be found in the comments to the script itself. Once the line printer interface has been installed (see below), look in the directory "/usr/spool/lp/admins/lp/interfaces" for a file with the name you chose during installation for the line printer intercept pseudo-printer. Should you decide to include the PCL control sequences in your printed output, the sequences to use include (where \E represents the ESC character and # any decimal number): \E&l#C height of each row of print (where # is in units of 1/48 in.) \E&k#H width of each column of print (where # is in 1/120 in. units) \E&l#F number of lines on each page before jumping to a new page \E&a#P page orientation (0=portrait, 90=landscape...) \E&a#L left margin (where # is the column number) \E&l#E top margin (where # is the line number) More information on available PCL sequences may be found in your HP LaserJet printer manual. Defaults Should you be using one or a small number of forms with the line printer intercept, you can edit the line printer interface script (see the file /usr/spool/lp/admins/lp/interfaces/fax on UNIX systems or the file /usr/spool/lp/interface/fax on SCO XENIX systems) to define defaults to use in the event that your print file does not explicitly define certain parameters. The three parameters that can be set by default are the account, class, and style parameters. See the comments in the line printer interface script for more information. Note that default values are not available when using the line printer intercept through WordPerfect. Overlays The overlays (i.e. images of pre-printed forms) can be prepared in a number of ways. First, one can either scan in an existing form or, if a scanner is not available, fax it to your Faximum system. The overlay can also be prepared using a forms or desk-top publishing package that produces PCL or PostScript output. While scanning (or faxing) an existing form is the easiest method, the quality of the overlay image will be lower than if produced by a DTP system and converted directly into TIFF format. If the form is faxed in, the tiffcut utility can be used to remove the top-of-page banner that may appear on the top of the received fax. For example, to remove the top half-inch from a TIFF file use: /opt/faximum/bin/tiffcut -x 0.5i -o form.tif inbox-254 If the form has been produced using a DTP package (such as FrameMaker), the PostScript file can be converted into TIFF format by using the appropriate conversion script: /opt/faximum/convert/ps -o form.tif form.ps This assumes that you have installed a PostScript emulator for Faximum. Should your DTP package produce PCL output (instead of PostScript), use the /opt/faximum/convert/pcl instead in the example above. Once the overlay TIFF file has been created, it needs to be moved to a known directory (/etc/opt/faximum/coversheet is recommended) and then referenced in a new style. For more information on the Style database please see the on-line help, or, in the case of Faximum PLUS, see Chapter 8 of the Faximum PLUS Reference Manual for a discussion on how to create new entries in system databases and Chapter 2 for information on the style database in particular. Installation Installing the line printer intercept to Faximum requires that you create a new line printer destination for your UNIX line printer spooler and then adjust it to point to Faximum rather than to a real physical printer. The detailed instructions on how to do this may be found in the Installation Guide and Release Notes in the section titled Line Printer Intercept. Word Processors The line printer intercept for Faximum is not limited to faxing invoices and other financial documents from accounting applications. It can also be used for sending faxes directly from your word processing program. Indeed, you can use the mail merge facility from within your word processing program to broadcast to multiple destinations. NOTE that the ability to access the line printer intercept through your word processor is different and in addition to the fax macro provided for WordPerfect and Microsoft Word. To differentiate between the two mechanisms: - the fax macro does not require that you make any changes to your document, rather, when you invoke the fax macro, the document is passed to Faximum and you are placed in the Faximum user interface to address the fax; - the line printer intercept, on the other hand, does not utilise the Faximum user interface. Rather, you must include the addressing information within the document you are preparing. The advantage of the fax macro is that you do not need to make any changes to the document since the addressing information (the fax number etc.) is entered separately. The advantage of the line printer intercept is that it can extract the addressing information (i.e. the fax number etc.) from the documents Current Limitations The current implementation of the line printer intercept will only work with ASCII and PCL files (not PostScript). ============================================================================== TechNote: 155 - Copyright 1996-2003 Faximum Software Inc., All Rights Reserved. Last Updated: Mon Mar 24 14:25:06 PST 2003 Find all Faximum TechNotes at http://www.faximum.com/support
© Copyright 2003 Faximum Software Inc. All Rights Reserved.