(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.