PSfilter Setup for HP Unix on HP Workstations
=============================================

1.   Overview
2.   dumb_int.sh
3.   Running install.sh
4.   PSfilter Parameters and Options
5.   PSfilter Direct Printing
6.   Troubleshooting


==============================================================
1. OVERVIEW
==============================================================

PSfilter is a proprietary printing protocol that provides the
user with many print options, while allowing use of the standard
lp printing subsystem.

To use the PSfilter program, you must have a C compiler on the
host so that psfilter.c can be compiled to an executable file.

Install.sh is provided to compile PSfilter and install printers
to use PSfilter.

Once PSfilter is compiled and installed, it is executed by the
printer's interface script whenever a job is printed. PSfilter
will then send the job to the Print Server, applying any options
which have been set. The supplied dumb_int.sh is the recommended
printer interface script.

* For more details on dumb_int.sh, see the following section
  DUMB_INT.SH

* To compile and install PSfilter, run the supplied INSTALL.SH
  program. This program will create the desired system printer
  objects. Print jobs will then be routed through PSfilter to
  the Print Server's printers. See USING INSTALL.SH for more
  information.

* Refer to PSfilter PARAMETERS & OPTIONS for details of using
  PSfilter to set print job parameters. This should only be
  necessary if you wish to modify the printer interface script
  file.

* To test PSfilter, print a file directly to the Print Server,
  ignoring the system printing process. See PSfilter DIRECT
  PRINTING for more information.

* To print normally (through PSfilter), use the normal system
  printing commands, such as lp.

* Note that is it not necessary to define LOGICAL PRINTERS on
  the Print Server, and it fact PSfilter cannot send jobs to a
  logical printer, but only to a physical port.

* Refer to the TROUBLESHOOTING section if you have any problems



================================================================
2.   DUMB_INT.SH
================================================================

The supplied file dumb_int.sh is the recommended printer
interface script. When install.sh is run (see next section), you
will be asked if you want to use this script. It is recommended
that you do use this script.

Dumb_int.sh provides 2 options, as follows:
nb            No Banner. If specified, no banner page is
              printed.
nfb           No File Break. If specified, no form feed is sent
              after the print job.

These options are specified with the lp -o switch.
e.g.
     lp -dEpsonFX -o nfb part1
     lp -dEpsonFX -o nb part2
Where the printer is named "EpsonFX" and the files are "part1"
and "part2".



================================================================
3. RUNNING INSTALL.SH
================================================================

Overview
========
Install.sh needs to be run for each printer you wish to create.
Install.sh will prepare your system for printing using PSfilter
by:
* Obtaining the necessary information from you to create a new
  printer.
* Compiling PSfilter if it is not already compiled.
* Invoking lpadmin to create the necessary printer.
* Modifying the printer interface script so that PSfilter is
  invoked, with the necessary options, for each print job sent
  to this printer.

There are 2 methods of running install.sh - Quickset and
Interactive.


Quickset Method
===============
1. Copy files
   Insert the TCP/IP Support CD in your CD-ROM drive and use
   the Unix program tar to copy all of the files to the desired
   directory.
  
2. Execute install.sh with the following command.
   ./install.sh  printer_name  PS_NAME  pn=#\
   im=IF_script  port=r_port  d=n  text
  
Printer_name  Name of the printer to be created.
PS_NAME       Name of the Print Server, as entered in \etc\hosts
pn=#          # is the port number on the Print Server used by
              this printer. Use 1 to 3 as appropriate.
Im=IF_script  If you don't want to use the dumb_int.sh interface
              provided with the Print Server, then IF_SCRIPT is
              the full pathname of the printer interface file.
              Dumb_int.sh is the recommended interface script.
port=r_port   r_port is the port to be used for redirection, if
              pn is busy. Valid values are 1, 2, 3, (parallel
              ports) or S (serial port) as appropriate.
d=n           n is the number of minutes allowed before the
              print job is aborted due to printer faults. If n
              is -1, the print job will not be aborted. Not
              specifying this option will cause the default
              value -1 to be used.
text          If provided, this parameter causes each LF to be
              converted to CR+LF


Interactive Method
==================
1. Copy files
   Insert the TCP/IP Support CD in your CD-ROM drive and use
   the Unix program tar to copy all of the files to the desired
   directory.
  
2. Execute install.sh with the following command.
         ./install.sh

3. The install.sh program will ask you to input the following
   information:

Model         Select your Print Server model from the menu

UNIX system   Select your system from the menu.

Printer name  Enter the name for the printer you wish to create.
              The name will be used by the lp print sub-system

Host Name     The Print Server name as entered in /etc/hosts

PSfilter path The directory to which you copied the files from
              the floppy.

Port          Port on the Print Server to which the printer is
              connected. Enter 1, 2, or 3 to indicate the port.
              3 means either the serial port or parallel port 3,
              depending on which is fitted.

Re-routing?   If, yes, print jobs for this printer will be
              switched to another port if the printer is busy.

Routing port  The port to which print jobs will be re-routed if
              pn is bush. Select from the menu.

Pre-string    String to send before a print job. This string
              must be text only - no control characters. To use
              control characters, you must use headfile.

Post-string   String to send after a print job. This string must
              be text only - no control characters. To use
              control characters, you must use tailfile.

Headfile      File to be sent before a print job. The file can
              contain control characters. Enter the full
              pathname.

Tailfile      File to be sent before a print job. The file can
              contain control characters. Enter the full
              pathname.

Delay         Delay time in minutes before the print job aborts
              after a printer fault. A value of -1 means do not
              abort.

Convert CR    If YES, CR are converted to CR+LF.

dumb_int.sh?  Dumb_int.sh is provided with the Print Server, and
              is the recommended printer interface script. Enter
              y or n.

Path          Path to dumb_int.sh, if "Yes" to above.

Model         Model interface script to be used instead of
              dumb_int.sh. (If "No" to using dumb_int.sh)



===============================================================
4. PSFILTER PARAMETERS & OPTIONS
===============================================================

PSfilter should not be executed directly, because this bypasses
the lp spooler mechanism. However, if you wish to change the
printer settings, go to the printer's interface script file,
find the line which sets a value to PMFILTER_CMD (i.e.
PMFILTER_CMD= ) and modify the PSfilter command.

Use the following syntax:  ( Do NOT enter the [] )

PSfilter -D[PS_NAME] [Options]

Where [PS_NAME] is the name of the Print Server
and the [Options] are chosen from the following list.

OPTIONS
=======
-P            Selected print port is parallel port 2.
-o3           Selected print port is parallel port 3.
-S            Selected print port is serial port.
-T            Text mode. LF will be converted to CR + LF.
-a [AP]       Send the print job to AP (Another Port) if the
              selected printer is busy. AP can have the
              following values:
                  serial             serial port
                  para1              parallel port 1
                  para2              parallel port 2
                  all                any of these ports.
-b            If the network traffic is very heavy, PSfilter
              will retry more times and wait twice as long as
              usual before the print job is aborted.
-d[n]         The number of minutes allowed before the print job
              is aborted due to printer faults. If n is -1, the
              print job will NOT be aborted and PSfilter will
              continue to wait for the printer fault to recover.
              The default is -1.
-h[head_file] Send head_file before the print job to initialize
              the printer. Head_file must be specified with a
              full path.
-p[string]    Send string before the print job to initialize the
              printer.
-s[string]    Send string after the print job to reset the
              printer.
-t[tail_file] Send tail_file after the print job to reset the
              printer. Tail_file must be specified with a full
              path.

Note:Default Port
     The default print port is parallel port 1. This will be
     used if no port is specified.

Note:Prefix Strings
     The string should be placed in single or double quotes. A
     string may only contain printable characters; control
     characters are NOT allowed.
     To use control characters, the -h<head_file> or -
     t<tail_file> options must be used.

Example:
=======
PSfilter -DMarketing -S -T -p"This is a prefix string"

This example would make PSfilter reroute the printing job to the
serial port of the Print Server, "Marketing", with the pre-
string "This is a prefix string" and convert all LF codes into
LF+CR codes.



================================================================
5. PSFILTER DIRECT PRINTING
================================================================

PSfilter Direct Printing means invoking the PSfilter program
directly, bypassing the lp printing sub-system. This means no
queue is used, so direct printing should only be used to test
that PSfilter is working properly.

Syntax ( Do NOT enter the [ ] )
======
PSfilter -D[PS_name] [options] < [filename]&

Where
  [PS_name] is the name of the Print Server, as entered in the
  /etc hosts file
  
  [options] are as described in PSfilter PARAMETERS & OPTIONS
  above. If no options are specified, the defaults are used.
  (For example, parallel port 1 is used.)
  
  [filename] is the file to be printed.

If the command fails, check for an error log file
(PSErrLogXXXXX) in the /tmp directory.



================================================================
6.   TROUBLE SHOOTING
================================================================

Problem 1
--------
  When the interface program detects that the printer device is
  not a printer, a printer error message appears on the screen.
  
Solution 1
----------
  Mark out all stty commands in the interface script.

Problem 2
---------
Jobs do not print

Solution 2
----------
* Check the Printer Interface Script. Make sure that the
  printer interface script contains the correct lines to call
  PSfilter. See Modifying the System V Printer Interface Script in
  Chapter 4 for the file name of the printer interface script.
* Run the Printer Interface Script directly. The Printer
  Interface Script has the same name as the printer, as is usually
  in the directory:
     lp/usr/spool/lp/interface
  
  It can be run with the command:
  ./printer_name Job_ID user_name title 1 "" file_name

Where:

printer_name  The printer interface script associated with the
              printer.
Job _ID       Any string. It will be printed on the banner page.
user_name     Any string. It will be printed on the banner page.
title         The title to be printed on the banner page.
1             Specifies the number of copies to be printed.
""            Options - No options.
file_name     The file to be printed.

If there still is no output, add another printer to the UNIX
system using as dumb_int.sh (shipped with Print Server) as the
interface script and try again.

