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 /etc/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 -T/etc/ifhp.conf;t1.conf
will cause the /etc/ifhp.conf and then the t1.conf 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 specifed 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 desciptor 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. The following sections discuss how to modify the configuration file to do this, as well as how to implement a simple a

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:
    # dev=/tmp/out
    # debug=3
    stty=38400 -echo -crmod -raw -oddp -evenp ixon pass8 -ixany cbreak crtscts
    trace
    ps@ 
    pjl@
    pcl@
    text
    
  2. Run the indicated commands and you should see similar output:
    ##> ifhp -Tconfig=./ifhp.conf < 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. Now modify the ifhp.conf file to look like:
    dev=/tmp/out
    debug=3
    trace
    ps@ 
    pjl@
    pcl@
    text
    
  4. Run indicated commands and you should see similar output:
    ##> ifhp -Tconfig=./ifhp.conf < 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
     ...
    
  5. 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

In order to simplify operation, if there is a ifhp.conf file in the current directory, then the ifhp program will read this file first, followed by /etc/ifhp.conf and then rereads the ifhp.conf This has the effect of extracting critical option information on the first pass through ifhp.conf, then reading the default information from /etc/ifhp.conf, and finally re-reading ifhp.conf to override any defaults.

  1. Try the simple commands
    echo >/tmp/out
    ifhp <hi.txt
    
    and note that it produces the same output as befoe.
  2. Now modify the ifhp.conf file to contain:
    dev=/tmp/out
    debug=3
    trace
    ps@ 
    pjl@
    pcl@
    text
    crlf
    
    and do
    ifhp <hi.txt
    again, without clearing the output file.
  3. 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).
  4. You can use the ifhp program as a simple CRLF filter by specifying:
    ifhp -Tcrlf,language=unknown <hi.txt

    The language=unknown option specifies that the ifhp program is not to guess at the language type, and then does CRLF translation.

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. Copy the t1.conf file to ifhp.conf and edit is so it has the correct network printer information.
    # modify the next line to contain
    # the name, IP address, or pathname of the printer dev=nwpr%9100
    debug=3
    trace_to_stderr
    ps@ pjl@ pcl@ text
  9. Now do the indicated command; you should get similar output
    astart: % ifhp <hi.txt
    
    Note the extreme verbosity of output.
  10. At this point you might want to try getting page numbers and doing synchronization. If you have a HP printer that supports PJL, then modify t2hp.conf as above. This file has the contents:
    # modify the next line to contain <newline>
    #  the name, IP address, or pathname of the printer
    dev=<it/nwpr/%9100 <newline>
    #debug=3 <newline>
    trace_to_stderr <newline>
    text <newline>
    pjl <newline>
    sync=pjl <newline>
    pagecount=pjl <newline>
    
    Now use the following command and you should see similar output.
    ifhp '-Tconfig=t2hp.conf;/etc/ifhp.conf;t2hp.conf' < hi1.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
    
  11. At this point, you should be able to send jobs to the printer, and now need to put these options into the printcap file. Please see the section on Printcaps and Fine Tuning Configurations

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 /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:

option
 ...

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

status@
pjl@
pcl
ps
text@
text_converter=/usr/local/bin/a2ps -o-
text_converter_output=ps

An alternative to this method is to create a new entry in the /etc/ifhp.conf file and reference this. This method has the benefit of centralizing management of the printing configuration. You usually put such an entry at the end of the /etc/ifhp.conf file, and it would have the form:

[ hp3_parallel ]
status@
pjl@
pcl
ps
text@
text_converter=/usr/local/bin/a2ps -o-
text_converter_output=ps

You would modify the printcap so that the model was passed 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
  :ifhp=model=hp3_parallel

3.10 Extending ifhp Capabilties

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 /etc/ifhp.conf.

3.11 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