TITLE: #230 - Configuring, Using, and Troubleshooting the LPI on Linux KEYWORDS: line printer intercept spooler lpi lpr linux RELEASE: Faximum ELS/PLUS 4 for Linux CLASSIFICATION: All PROBLEM: Customer wishes to configure the Faximum Line Printer Intercept feature with Linux. CAUSE: N/A SOLUTION: Note that there are a number of different line printer spoolers available for Linux. The two most popular are LPRng (www.lprng.org) and CUPS (www.cups.org). You need to determine which spooler you are running since the instructions differ. If you have a directory /etc/cups/ then you are running CUPS. Otherwise you are probably running LPRng. CONFIGURING LPRng ================= The following steps must be executed as the administrative user (i.e. either as root or after running the "su" command). 1. Download a copy the new Faximum Line Printer Intercept script for Linux from ftp://ftp.faximum.com/pub/software/linux-fms/updates/lprngfax.Z 2. Uncompress this file and put it in /opt/faximum/lp with permissions 755 (i.e. rwxr-xr-x). Change the pathname appropriately if you have installed the Faximum ELS or PLUS product in a directory other than /opt/faximum 3. Create a directory called /var/spool/lpd/lprngfax with permissions 700 (rwx------), owned by user "lp" and group "lp". 4. Edit your /etc/printcap.local file and add at the end of the file the following lines. If your Linux system does not have and /etc/printcap.local file then edit your /etc/printcap file. ============================================= fax:\ :if=/opt/faximum/lp/lprngfax:\ :lp=/dev/null:\ :br#57600:\ :rm=:\ :rp=:\ :sd=/var/spool/lpd/lprngfax:\ :mx#0:\ :sh: ============================================= Note that if in step 2 you put the script in a directory other than /opt/faximum/lp then you will have to adjust the if= parameter above appropriately. 5. Check that the changes to the printcap file and related directories are correct by running the checkpc utility. On Red Hat 7.2 this utility is in /usr/sbin (you may need to use the whereis command to locate this utility on your Linux system. Just type: /usr/sbin/checkpc If there are any errors they will be displayed. If no problems are detected then checkpc will not display anything. 6. Restart your line printer spooler: /etc/rc.d/init.d/lpd stop /etc/rc.d/init.d/lpd start Do not be concerned if your attempt to "stop" the lpd service results in an error or failure indication. Note: You can define more than one "fax" virtual printer, each with different default fonts, styles, or other settings. To do this: - make a copy of the /opt/faximum/lp/lprngfax file and call it something else - create another entry in the printcap.local file similar to the example above but with a different name and referencing the copy of the lprngfax file you created above - edit your copy of the lprngfax file to specify the desired default font, style, etc. For more information on changing the default font used by a "fax" virtual printer please see TechNote #116. CONFIGURING CUPS ================= The following steps must be executed as the administrative user (i.e. either as root or after running the "su" command). 1. Download a copy the new Faximum Line Printer Intercept script for Linux CUPS from ftp://ftp.faximum.com/pub/software/linux-fms/updates/cupsfax.Z 2. Uncompress this file and put it in /opt/faximum/lp with permissions 755 (i.e. rwxr-xr-x). Change the pathname appropriately if you have installed the Faximum ELS or PLUS product in a directory other than /opt/faximum 3. Enter the following commands: cd /opt/faximum/lp lpadmin -p fax -i cupsfax lpadmin -p fax -E Note: You can define more than one "fax" virtual printer, each with different default fonts, styles, or other settings. To do this: - make a copy of the /opt/faximum/lp/cupsfax file and call it something else - run the lpadmin commands shown above with a different printer name (i.e. "-p fax2") and specifying the name of the cupsfax copy For more information on changing the default font used by a "fax" virtual printer please see TechNote #116. TESTING ======= 1. Create a file called /tmp/lpitest that contains: ----------------------------------------------------------------- This is a simple LPI test //Fax(FAX=1234567) ----------------------------------------------------------------- 2. Submit the test file to the Line Printer Intercept by running: lp -d fax /tmp/lpitest TROUBLESHOOTING with LPRng ========================== 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 lprngfax script is to send the fax out overnight. Edit the lprngfax script and change the default class to something more appropriate to your needs (for example, "Rush (Highest Cost)"). 2. Check that the printcap files and related directories are correct by running the checkpc utility (see step 5 above). 3. Look at the file /var/spool/lpd/lprngfax/status.pr for messages that might indicate why requests are not being successfully passed to Faximum. 4. Edit the /opt/faximum/lp/lprngfax script and add the following line as the second line in the file: exec > /tmp/lpi.$$ 2>&1 5. 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. USING ===== ============================================================================== 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: lpr -Pfax < 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. Look in the file /opt/faximum/lp/lprngfax or /opt/faximum/lp/cupsfax 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 /opt/faximum/lp/lprngfax or /opt/faximum/lp/cupsfax) 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. 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). A PostScript version is in development and those wishing to try it are invited to contact firstname.lastname@example.org ============================================================================== TechNote: 230 - Copyright 2004 Faximum Software Inc., All Rights Reserved. Last Updated: Sat Jan 17 01:08:44 PST 2004 Find all Faximum TechNotes at http://www.faximum.com/support
© Copyright 2004 Faximum Software Inc. All Rights Reserved.