PSfilter Setup for IBM AIX
==========================
1.   Overview
2.   Setup
3.   PSfilter Parameters and Options
4.   PSfilter Direct Printing
5.   Trouble shooting

==============================================================
1. Overview
==============================================================
PSfilter is a proprietary printing protocol that provides the
user with many print options. 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.

* To install and configure your system, create each required
  printer by following the instructions in SETUP.

* Refer to PSfilter PARAMETERS & OPTIONS for details of using
  PSfilter to set print job parameters.

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

* Refer to the TROUBLESHOOTING section if you have any
  problems



================================================================
2. SETUP
================================================================

Overview
========
On other Unix systems, a script file install.sh is used to
compile and install PSfilter. This script DOES NOT WORK on IBM
AIX, and MUST NOT be used. Instead, the mycc script is used to
compile PSfilter.c. Installation must then be completed
manually. The complete procedure is listed below.


2.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.2  Compile psfilter.c
-----------------------
To compile PSfilter, cd to the directory to which the files were
copied, and run the mycc script.
     ./mycc
The PSfilter executable will be generated in the directory:
     ./LPsource


2.3  Create a fake printer device
--------------------------------
Create a fake printer device for each printer attached to the
Print Server by entering:
      cp /dev/null /dev/PRINTER_NAME
Where PRINTER_NAME is the name of the printer you wish to
create.


2.4  Change the access permission of the print device(s)
------------------------------------------------------
Change the access permission of each print device by using the
following command:
     chmod 666 /dev/PRINTER_NAME
Where PRINTER_NAME is the name of the printer created in 2.3.


2.5  Create virtual printer(s)
-----------------------------
For each printer device created in 2.3, create a virtual printer
with the command:

     smit mkvirprt

The smit administration tool will ask the following questions:

Specify where the printer is attached:
     Select 1: Printer or plotter attached to host.
Specify a device name:
     Enter the name you assigned to the printer in 2.3.
     
Answer the rest of the questions as normal to setup the printer.

When prompted for POSTSCRIPT enter a printer queue name if using
a postscript printer. The queue name can be any name which is a
valid filename. To bypass this option enter !

When prompted for PCL, enter a printer queue name if using a PCL
printer. The queue name can be any name which is a valid
filename. To bypass this option, enter !


2.6  Create a backend script file
--------------------------------
A backend script file needs to be created for each printer. Each
printer can have different PSfilter options specified in this
file.
This file should contain the following lines:
*** Do NOT enter the [] ***

#!/bin/sh
/usr/lib/lpd/piobe $* | [path]PSfilter -D[PS_NAME] [options]

Where
     [path] is the location of the PSfilter program.
     [PS_NAME] is the name of the Print Server, as entered in
     /etc/host.
     [options] are PSfilter options, as described in the
     following section.
     
Save the file(s) in the PSfilter directory. Each file should
have a name which indicates which printer it belongs to.


2.7.  Add execution permission to the backend script file
---------------------------------------------------------
Make each backend script file executable with the following
command:
     chmod +x file_name


2.8  Associate the printer with the script file
------------------------------------------------
For each printer, the queue must be associated with the script
file, by the following procedure:

If using AIX 3.X, enter:
      smit chquedev

If using AIX 4.X, enter:
     smit pq_chquedev

* Find the printer name and select it. A "Change/Show
  Characteristics of Queue Device" menu will appear.
* Move the cursor to "Backend Program".
* Type the full path name of the new script file for this
  printer.


2.9  Check the /etc/qconfig file
-------------------------------
Check the /etc/qconfig file to see whether the backend program
of the queue device is correctly modified. The /etc/qconfig file
should include the following:

printer queue:
     device = printer_name
     
printer_name:
     file=/dev/printer_name
     header= never
     trailer= never
     access= both
     backend = [path]backend_script_file



===============================================================
3. 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, you can modify the PSfilter command in the
backend script file for that printer.

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.



================================================================
4. 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.



================================================================
5. 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 are not printed.
  
Solution 2
----------
* Check the backend shell script. Make sure that the newly
  created backend shell script calls PSfilter correctly. See
  System V Manual Setup, IBM AIX in Chapter 5 for more
  information.
* Make sure that the new backend shell script has execution
  permission.
* Check /etc/qconfig. Make sure that the /etc/qconfig file
  contains the correct modification of the queue device backend
  program. The queue device backend program is the file name of
  the new backend shell script.

