Next Previous Contents

3. Configuration Tutorial

This section is a basic tutorial on using many of the features of the ifhp filter. If you plan to make use of any of the advanced filter options or modify the configuration, you should read and try out several of the configuration exercises.

3.1 Configuration Files and Testsupport Directory

These exercises require the use of several configuration files that have predefined values as well as the default ifhp.conf file. The test files are normally located in the distribution testscripts directory. It is assumed that these exercises will be done in that directory.

The config=path;path;path option specifies the list of configuration files for ifhp to read. Here is a sample of the configuration file t1.conf:

# modify the next line to contain
#  the name, IP address, or pathname of the printer
dev=CHANGE_THIS
debug=3
stty=38400 -echo -crmod -raw -oddp -evenp ixon pass8 -ixany cbreak crtscts
trace
ps@ 
pjl@
pcl@
text

The command

ifhp "-Tconfig=/usr/local/etc/ifhp.conf"
will cause the /usr/local/etc/ifhp.conf and file to be read and configuration information extracted.

The various options in this file are quite important for debugging and testing. The debug and trace options can also be specified on the command line, and cause the debug facilities to be turned on and debug trace output to be put to STDERR. Normally, trace output is written only to the statusfile specified by the command line -s option or the configuration file statusfile=path entry.

The text entry causes the filter to accept text files and simply pass them through without processing, and the ps@ pjl@ pcl@ entries disable related processing.

3.2 Output Device Specification

In normal operation, ifhp sends its output to STDOUT or file descriptor 2. However, when testing or using the ifhp filter in standalone mode, it is useful to have the filter open the connection to a file or device directly.

3.3 Output to a File

This method is useful when trying to debug a set of configuration options and you want to capture output to a file. The dev=path option is used to specify the output pathname.

  1. In the testscripts directory, copy the t1.conf file to ifhp.conf and edit ifhp.conf so it has the following lines:
    ps@ 
    pjl@
    pcl@
    text
    
  2. Run the command shown below and you should see similar output:
    ##> ifhp -Tconfig=./ifhp.conf,trace,debug=1 < hi.txt
    ifhp 12:28:20.603 [6089] Process_job: setting up printer
    ifhp 12:28:20.605 [6089] Do_accounting: accounting at start, pagecount 0, pages 0
    ifhp 12:28:20.605 [6089] Process_job: sending job file
    ifhp 12:28:20.605 [6089] Send_job: starting transfer
    Hello World
    
    ifhp 12:28:20.606 [6089] Send_job: finished writing file, cleaning up
    ifhp 12:28:20.606 [6089] Process_job: sent job file
    ifhp 12:28:20.606 [6089] Process_job: doing cleanup
    ifhp 12:28:20.606 [6089] Do_accounting: accounting at end, pagecount 0, pages 0
    ifhp 12:28:20.606 [6089] Process_job: done
    
  3. Run indicated commands and you should see similar output:
    ##> ifhp -Tconfig=./ifhp.conf,trace,debug=1,dev=/tmp/out < hi.txt
    ifhp 12:33:39.504 [6155] Open_device: device '/tmp/out'
    ifhp 12:33:39.505 [6155] Open_device: device '/tmp/out', attempt 1
    ifhp 12:33:39.506 [6155] Open_device: success
    ifhp 12:33:39.506 [6155] main: fd 1 device 0100000
     ...
    
  4. Clearly this is very verbose diagnostic or trace output. However, if you use cat /tmp/out you will see the output has been written correctly. Try using the following command to redirect trace and error output to a file for later examination.
    CSH                     SH
    ifhp ... <in >&out      ifhp ... <in 2>out
    

3.4 Default ifhp.conf File and Simple CRLF Filter

The default ifhp.conf file has a complex and complete setup for a wide range of printers. You can add your own printer setup by naming it and appending it to the ifhp.conf file.

  1. Copy the ifhp.conf file, usually found in /usr/local/etc or /etc to your current directory, and add the following lines:
    [ myprinter ]
    ps@ 
    pjl@
    pcl@
    text
    
    Now try the commands
    ##> ifhp -Tconfig=./ifhp.conf,trace,debug=1,model=myprinter < hi.txt
    
  2. It now reads the configuration information, selects the section for your printer, and does its work.
  3. Now add the indicated line to the end of the ifhp.conf file:
    [ myprinter ]
    ps@ 
    pjl@
    pcl@
    text
    # add this
    crlf
    
    and do
    ##> ifhp -Tconfig=./ifhp.conf,trace,debug=1,model=myprinter < hi.txt
  4. If you examine /tmp/outoutput using the od or hexdump file dump programs or the vi text editor, you will find that the LF (\n) character has been replaced by CR LF (\r\n).

3.5 HP JetDirect or Compatible Network Interface

If a printer has HP JetDirect compatibility, then the printers TCP/IP port 9100 will accept jobs for printing and provide printer status.

Other manufacturers make similar products, and may support equivalent functionality on different ports. If you are using a Network Printer Box with multiple printer ports, then each printer port is accessible using a specific TCP/IP port. For example, parallel ports P1, P2, and P3 and on a JetDirect box are usually accessed using TCP/IP ports 9100, 9101, and 9102 respectively.

If you are using a Network Printer Box and are connecting to a parallel port printer, then you may not get status or error messages back from the printer unless both the printer and the Network Printer Box use bi-directional communication.

In the following discussions, we will assume that you have assigned an IP address to the printer, and that it is nwpr, and that status and error information is returned over the network connection.

  1. First, verify that your printer is accessible on the network by using ping. It is amazing how many problems are caused by erroneous network addresses.
    astart: % ping nwpr
    PING nwpr.astart.com (10.0.0.10): 56 data bytes
    64 bytes from 10.0.0.10: icmp_seq=0 ttl=60 time=4.286 ms
  2. Now use telnet to check that you can connect to port 9100.
    astart: % telnet nwpr 9100
    Trying 206.71.174.206...
    Connected to nwpr.astart.com.
    Escape character is '^]'.
    ...
    
  3. If you have a PostScript printer, then you might want to play with the PostScript Interactive mode, described in Appendix D.5 of the PostScript Language Reference Manual by Adobe Systems. Simply type the command
    executive
    as the first characters that are sent. You should see:
    >># telnet nwpr
    Connected to nwpr.astart.com.
    Escape character is '^]'.
    executive
    PostScript(r) Version 2013.111
    (c) Copyright 1984-1993 Adobe Systems Incorporated.
    Typefaces (c) Copyright 1981 Linotype-Hell AG and/or its subsidiaries.
    All Rights Reserved.
    PS>
    
  4. You may want to try sending a simple file to the printer and examining what happens. This is easily done using the netcat program by Mudge. See http://www.l0pht.com/~weld/netcat/index.html for general information.
  5. The hi.txt file contains
    Hello World
    ^L
    where ^L is the form feed character You can send this file to the printer using:
    nc printer 9100 <hi.txt

    The printer should start up and print a single page of output. You may need to use CTRL-C to terminate the nc program.

  6. If you have a PostScript printer, you might try sending a simple PostScript test program to the printer as well. The ellipse.ps file can be sent using:
    nc printer 9100 </tmp/hi1.txt
  7. You can now test the basic ifhp functionality.
  8. Do the indicated command:
    astart: % ifhp -Tdev=ip.addr.printer%9100,trace,debug=1 <hi.txt
    ifhp 16:44:16.541 [3199] Process_job: setting up printer
    ifhp 16:44:16.545 [3199] Do_sync: starting sync using 'pjl'
    ifhp 16:44:17.935 [3199] Check_device_status: device = 'Toner Low'
    ifhp 16:44:18.116 [3199] Do_sync: sync done
    ifhp 16:44:18.117 [3199] Do_pagecount: getting pagecount using 'pjl'
    ifhp 16:44:20.011 [3199] Do_pagecount: final pagecount 63304
    ifhp 16:44:20.013 [3199] Do_accounting: accounting at start, pagecount 63304, pages 0
    ifhp 16:44:20.013 [3199] Process_job: sending job file
    ifhp 16:44:20.014 [3199] Send_job: starting transfer
    ifhp 16:44:20.115 [3199] Use_file_util: file identified as 'ascii text ', assigned type 'text'
    ifhp 16:44:20.119 [3199] Send_job: finished writing file, cleaning up
    ifhp 16:44:20.119 [3199] Process_job: sent job file
    ifhp 16:44:20.119 [3199] Process_job: doing cleanup
    ifhp 16:44:20.120 [3199] Do_sync: starting sync using 'pjl'
    ifhp 16:44:22.175 [3199] Do_sync: sync done
    ifhp 16:44:22.176 [3199] Do_waitend: getting end using 'pjl'
    ifhp 16:44:22.529 [3199] Check_device_status: device = 'Warming Up'
    ifhp 16:45:04.669 [3199] Check_device_status: device = 'Toner Low'
    ifhp 16:45:21.361 [3199] Do_pagecount: getting pagecount using 'pjl'
    ifhp 16:45:23.241 [3199] Do_pagecount: final pagecount 63305
    ifhp 16:45:23.243 [3199] Do_accounting: accounting at end, pagecount 63305, pages 1
    ifhp 16:45:23.243 [3199] Process_job: done
    
  9. Please see the section on Printcaps and Fine Tuning Configurations in order to use this in the LPRng printcap file.

3.6 Serial Port

If your printer is attached using a serial port, then you must make sure that the communication channel is configured correctly. The dev=/dev/ttyxxx and stty=... configuration options will open the serial port and configure the line in an appropriate manner. For details on the exact form of the stty options, please consult the LPRng-HOWTO documentation.

  1. Copy the t1.conf file to ifhp.conf and edit it so it has the following lines:
    # modify the next line to contain
    # the name, IP address, or pathname of the printer dev=/dev/serialport
    #debug=3
    stty=38400 -echo -crmod -raw -oddp -evenp ixon pass8 -ixany cbreak crtscts trace_to_stderr
    text

    Now run the ifhp program as shown below. You should see output similar to:

    astart: % ifhp <h11.txt
    ifhp 15:57:23.734 [3096] Process_job: setting up printer
    ifhp 15:57:23.736 [3096] Do_accounting: accounting at start, pagecount 0, pages 0
    ifhp 15:57:23.736 [3096] Process_job: sending job file
    ifhp 15:57:23.736 [3096] Send_job: starting transfer
    ifhp 15:57:23.737 [3096] Send_job: finished writing file, cleaning up
    ifhp 15:57:23.737 [3096] Process_job: sent job file
    ifhp 15:57:23.738 [3096] Process_job: doing cleanup
    ifhp 15:57:23.738 [3096] Do_accounting: accounting at end, pagecount 0, pages 0
    ifhp 15:57:23.738 [3096] Process_job: done
    
    and you should get a printed page.
  2. If you do not get communication, then you will have to start a long and painful process of debugging. First, check that the various modem control signals are correct. You should invest a small amount of time and energy and purchase a breakout box that shows the status of the various control signals. If only the XMIT Data signal is active, you will need to put a crossover (null modem) between the printer and your serial port.

    Check the DTR (Data Terminal Ready), DCD (Data Carrier Detect), RTS (Request To Send), and CTS (Clear To Send). These should all be ON or active. Some systems will use RTS (Request To Send) and CTS (Clear To Send) for hardware flow control and it is possible that these signals will become stuck. It is strongly recommended that flow control on the host be turned off, and let the printer do flow control using RTS and CTS.

  3. Once you get the basic configuration working, then you should follow the basic steps in the previous section on Network Interfaces, and try sending files of different types.

3.7 Parallel Port

The parallel port configuration is the easiest to implement, but the most limited in abilities.

  1. Copy the t1.conf file to ifhp.conf and edit it so it has the following lines, with the dev value replaced by the correct pathname.
    # modify the next line to contain
    # the name, IP address, or pathname of the printer
    dev=/dev/lp
    debug=3
    stty=38400 -echo -crmod -raw -oddp -evenp ixon pass8 -ixany cbreak crtscts
    trace
    ps@
    pjl@
    pcl@
    text
  2. Now run the ifhp program:
    ifhp <hi.txt
  3. You should see output similar to:
    astart: % ifhp -Tconfig=.../testscripts/t1.conf <h11.txt
    ifhp 15:57:23.734 [3096] Process_job: setting up printer
    ifhp 15:57:23.736 [3096] Do_accounting: accounting at start, pagecount 0, pages 0
    ifhp 15:57:23.736 [3096] Process_job: sending job file
    ifhp 15:57:23.736 [3096] Send_job: starting transfer
    ifhp 15:57:23.737 [3096] Send_job: finished writing file, cleaning up
    ifhp 15:57:23.737 [3096] Process_job: sent job file
    ifhp 15:57:23.738 [3096] Process_job: doing cleanup
    ifhp 15:57:23.738 [3096] Do_accounting: accounting at end, pagecount 0, pages 0
    ifhp 15:57:23.738 [3096] Process_job: done
    
    and you should get a printed page.

    If you happen to have an operating system that support bi-directional parallel ports, you can add to the ifhp

    read_write
    which will cause ifhp to open the port read/write.

3.8 Fine Tuning A Configuration and Printcap Entries

If you have followed the above directions, you should now be able to use the IFHP filter with very little additional configuration. You can now set up your printcap to use the ifhp filter. The following discussion assumes that you are using LPRng.

3.9 ifhp.conf Defaults

While the above set of exercises are useful for debugging and testing, you should always let the LPRng spooler open the printing device or make the network connection.

Examine the /usr/local/etc/ifhp.conf or /etc/ifhp.conf file. The default configuration is for a HP family printer which supports pagecounting using PJL, synchronization using PJL, and other standard items.

If the default configuration does not meet your needs, and you do not want to use the printcap :ifhp entry or pass options using the -T command line entries, you can create your own entry in a /... spooldir .../ifhp.conf file. This entry should have the form below, and be appended to the default ifhp.conf file.

[ modelname ]
option
 ...

For example, we might want to configure a printer that supports PCL and PostScript, needs to convert Text to PostScript using the a2ps command, and does not have status capability. This is similar to an HP3 with a PostScript cartridge on a parallel port.

[ hp3_parallel ]
status@
pjl@
pcl
ps
text@
# turn off automatic conversion
forceconversion@
file_output_match@
# add our own text to PostScript conversion
text_converter=/usr/local/bin/a2ps -o-
text_converter_output=ps

To use this with LPRng, the model information used to select the configuration entry is specified either in the :ifhp information or as a command line option:

printer:...<newline>
  :if=/.../ifhp -Tmodel=hp3_parallel<newline>
  :of=/.../ifhp -Tmodel=hp3_parallel<newline>

# or you can use this
printer:...<newline>
  :ifhp=model=hp3_parallel
  :if=/.../ifhp<newline>
  :of=/.../ifhp<newline>

3.10 Adding and Overriding Configuration Entries

In order to simplify adding new entries and overriding default distribution files, the following method is used.

  1. The last line of the ifhp.conf file will have ### XXX END XXX ###.
  2. If you have new entries, you can simply add them to then end of the ifhp.conf file.
  3. If your new entry conflicts with an existing entry, simply rename the existing entry name, and then append your new entry to the end. An alternative is to simply copy the existing entry to the end of the ifhp.conf file, and edit the values you wish to change.
  4. If you wish to override the defaults, then you can use a [ default ] configuration entry to do so.

3.11 Extending ifhp Capabilities

One problem faced by system administrators is the need to allow users to configure various options in a job specific manner. In order to support this, the LPRng print spooler passes the lpr -Z command line options through to the print spooler, where they are used by the ifhp filter.

The details of how these options are used are explained in detail in the following sections, but here is an overview of how commands can be added.

The pjl_user_opts=[ ... ], pcl_user_opts=[ ... ], and ps_user_opts=[ ... ] are options with predefined meanings. The values of these options specify -Z and -T command line options that will be processed by the ifhp filter when pjl, pcl, or ps configuration needs to be done. Here is a sample configuration file section, and an example.

# we add the upper and lower keywords
#  lpr -Zupper  or lpr -Zlower will be specified by the user
pjl_user_opts=[ upper lower ]
pjl_upper=@PJL SET INTRAY=TRAY1
pjl_lower=@PJL SET INTRAY=TRAY2

#  lpr -Zpagesetup
pcl_user_opts=[ pagesetup ]
pcl_pagesetup=[ lines=12 cols=4 ]
lines=20
pcl_lines=\033*(\%{lines}L
cols=2
pcl_cols=\033*(\%{cols}C

If the user specifies lpr -Zupper, if PJL is available on the printer (pjl is set), then the -Z option list is scanned for an option that is also in the pjl_user_opts. The upper option is found, and then the value for pjl_upper is located and sent to the printer. By prefixing the context or language that is needed, we can have multiple language dependent actions for the same option.

The lpr -Zpagesetup option is more complex, mainly due to the range of possibilities the PCL offers. The pagesetup option is found in the pcl_user_opts list, but when pcl_pagesetup is found, it turns out to be a list of values.

The list values are expanded in turn, resulting in pcl_lines and pcl_cols being expanded in turn. The pcl_lines=\033*(\%{lines}L uses the common C/C++/Perl escape sequences, with the following addition: \%{name} is replaced by the value for the option name found by searching in order a a stack of values that have been set by the recursive expansion, the -Z options, -T options, and the configuration file. In this example, we would produce the output string

\033*(12L\033*(4C

For examples of how to add these commands, please examine the default ifhp.conf file.

3.12 PCL and PostScript End of Job Sequences

One of the more troublesome problems with printing PCL and PostScript jobs is to initialize the printer when a previous job has failed. This is commonly done by prefixing a job file with a end of job sequence for the particular language. For PostScript, this the the Control-D (\004) character, and for PCL the ESCAPE E (\033E) sequence.

One problem with using this approach is that when you want to prefix a job with additional PCL or PostScript, you need to remove the existing end of job sequences, or the prefixed commands will have no effect. By default, the ifhp filter will do this. In addition, it will also prefix the new commands with an appropriate end of job sequence.

However, there are certain models of printers which do not like to have end of job sequences at the start of jobs. To suppress the prefixing of PostScript jobs with the PostScript end of job, set the no_ps_eoj flag, and to suppress the prefixing of PCL jobs with the PCL end of job, set the no_pcl_eoj flag.


Next Previous Contents