Faximum TechNote #230

Faximum TechNote #230

(http://www.faximum.com/technotes/230)

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 support@faximum.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
support@faximum.com

==============================================================================

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.