
		       New "appx_print" Scripts
                       ========================


OVERVIEW:

The new appx_print script combines parts of all of our existing print
scripts into a single script.  This new script can handle printing
files on systems using "lp", "lpr", and "ulp" as their printing
subsystem.

In addition to combining this functionality into one script, we have
added the ability for the script to pass print files through unix
filter scripts before routing on to the output device.  These filter
scripts can wrap the report in special codes for adjusting the printer
before and after printing.  They can also be extended to process
embedded codes, completely reformat, merge with a template, etc.


APPX_PRINT:

This is a walkthrough on the significant changes made to the appx_print
script itself.  By default, the new appx_print script should perform the
same functions that the old appx_print script performed.

[Script Modules]

appx_print is now broken up into the following logical subroutine modules:

BUILD_LP_OPTIONS()
BUILD_LPR_OPTIONS()
BUILD_ULP_OPTIONS()
PROCESS_CONFIG( config_file_name )
PROCESS_OPTION( option )

{MAIN} -config=configfilename printfilename

As you can see, where we had a single function in the past called
BUILD_OPTIONS() we now have three functions.  One for LP, one for LPR,
and one for ULP.  This is where we inspect the values that were parsed
from the configprintfile and create command line arguments for the OS
printing command in use.

[Detection of OS printing command]

Since the new appx_print script needs to know how to print using a
variety of different OS printing commands, it must first determine
which OS printing command it will be using.  

To do this, it first checks for a special environment variable called
APPX_LP_CMD.  If this variable is set, then its value is used as the
pathname when it comes time to print the file.  The variable can be a
full pathname including extra command line options you might want to
always pass along.  Just make sure that if you set this, that the
pathname end with either "lp", "lpr", or "ulp".  The script will take
the first space delimited value of the variable data and inspect the
trailing characters for one of these value to determine how to
generate the argument list..

If the APPX_LP_CMD variable is not set, then the appx_print script
will perform the following search in the represented order until it
finds a printing command it understands: "ulp", "lp", then "lpr".
For it to find these commands, they must exist in the PATH.

[Printer Filters]

Printer filters can be designated in several ways.

1) You can set the PRINTER FORMAT in the Appx Printers file in
System Administration.  Then any report spooled to this printer
will pick up the defined filter automatically.

2) Set the FORMAT field on the Disposition screen at runtime.

3) Set the --- PRINT FILE FORMAT pdf from ILF code.

4) pass appx_print a -format= argument.

The first method is probably the most useful.  Since a printer
filter is printer specific in most cases, assigning it at the
printer level in APPX makes sure you have a filter matched to
you printer at all times.

How appx_print finds a filter is based on a search.  First,
appx_print will try to locate an executable file or script
of the same name as the filter in the following places.

1) $APPXPATH/filters/
2) $APPXPATH/filters/ASI/

All of our default filters are shipped in $APPXPATH/filter/ASI/.  That
way, if you would like to modify these or create your own filters, you
can place them in the $APPXPATH/filters/ directory and they will be
found before ours.  Also, when installing a new version of APPX, your
filters will not be replaced.  We will only ship filters in the
$APPXPATH/filters/ASI/ directory.

Currently we ship 2 default filters.

$APPXPATH/filters/ASI/MPAGE
$APPXPATH/filters/ASI/PCL

The MPAGE filter is a script that will convert a set of appx generic
arguments into command line options for the unix "mpage" command that
ships on Linux servers.  "mpage" is a unix utility that converts a
text file into postscript using command line arguments to control the
formatting of the page.  This script should work for any printer
defined on a Linux server.  When Linux installs a printer, it sets up
the printer to always accept postscript input and then it uses the
ghostscript utility to convert the postscript to a format the the real
printer device can use. So, any printer on a Linux system can accept
postscript input.  If you would like to use this filter on a non-linux
server, then you will need to download a copy of "mpage" for your OS.
And, your printer will likely need to be a postscript printer to use
this filter since most other unix operating systems do not set up
non-postscript printer to accept postscript.

The PCL filter is a script that will convert a set of appx generic
arguments into PCL codes and prepend them to the beginning of the
report data as it is passed through the filter script.

Both of these filters could be extended to process more options and
the PCL script could easily be cloned and changed to convert appx
options to some other set of escape codes like Epson, Canon, etc.

Currently both of these filter scripts understand the following common
options:

--------------------------------------------------------------------
 OPTIONS RECOGNIZED: ( all must be preceded by a "-" )                 
                                                                       
 Page Orientation: (Default portrait)	                                 
       -orientation= 'portrait' or 'landscape'                       
                                                                       
 Horizontal Pitch Selection                                            
       -pitch=       numeric cpi value                  
                                                                       
 Vertical Pitch Selection                                              
       -lpi=         numeric lines per inch setting                  
       -vsi=         Vertical Space Increment # in 1/48's of an inch 
                                                                       
 Page Layout Selection                                                 
	-lpp=	       set text length of page to nnn lines             
--------------------------------------------------------------------

MPAGE will also understand any "mpage" command line arguments as
defined in the "mpage" man pages or other documentation.

Using any form options that are not defined in the filter script will
have unpredicatable results.  If you think you might have a problem
with a bad form option, please check the log file appx_print.last as
it will log any complaints "mpage" may report.

Each of these filter scripts can be run from the command line with 
the same special command line arguments that were added to appx_print.
Namely, --help, --version, and --history.

[What options are sent where]

In APPX you can defined printing options in two places.  for a Printer
and for a Form.  appx_print will handle these differently depending on
if a filter script is being used or not.

If no filter script is used, then both the printer options and the
form options are sent to the lp|lpr|ulp command.

If a filter IS used, then the printer options are used as command line
arguments for the lp|lpr|ulp command and the form options are used as
command line arguments for the filter script.

So, you can set the Printer Options to supress banner pages, etc for
the printing subsystem and the Form Options to set Orientation, Pitch,
etc.

[Some extra command line arguments]

appx_print now understands some new command line arguments when run
manually from a command line prompt:

--help or -?  will display help about the appx_print script usage.
--version     will display the version information of the script.
--history     will display revision history for the script.

[More logging]

The new appx_print script has a bunch more logging built in.  It still
logs to the standard /tmp/appx_print.last file.  But it includes many
more details on what is going on.  Here is a sample of what was produced
in the appx_print.last log file from a simple print request.

{log file dump:starts here}

=============================================================================
APPX_PRINT - Appx Printer Interface Script for Unix         Updated: 03/21/01
=============================================================================

............. Parameters passed on command line ...........
-config=/tmp/SYSADMI5.cfg /tmp/SYSADMI5

APPX_LP_CMD variable not set.  Looking for a spooler to use...
    'ulp' not found in the current PATH...
    'lp'  not found in the current PATH...
    'lpr' found!  Setting APPX_LP_CMD=lpr

Running Print Script: /work/appx/415/data/appx_print
 Current script path: /work/appx/415/data
     Current OS Name: Linux
    System Data/Time: Mon Jun 11 12:39:49 EDT 2001
  configuration file: /tmp/SYSADMI5.cfg
         print files: /tmp/SYSADMI5 
     other arguments: 

   Value of 'whoami': pete
   Value of   LOGIN : 
   Value of LOGNAME : root
   Value of     'id': uid=504(pete) gid=0(root) groups=0(root),1(bin),2(daemon),3(sys),4(adm),6(disk),10(wheel)

Dump of the first 10 lines of the report...
vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv

APPX System Administration                                               Page: 1

PHB 06/11/01 12:39                                                      Printers
================================================================================

Printer Name:      HP4500DN
Descriptive:       HP 4500 Color Laser
System ID:         lp
Location:          Jacksonville, FL
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Processing config file /tmp/SYSADMI5.cfg...
      PROCESS_OPTION:  -mode=SPOOL
      PROCESS_OPTION:  -disposition=SCRATCH
      PROCESS_OPTION:  -copies=1
      PROCESS_OPTION:  -notify=No
      PROCESS_OPTION:  -banner=No
      PROCESS_OPTION:  -format=MPAGE
      PROCESS_OPTION:  -priority=
      PROCESS_OPTION:  -date=
      PROCESS_OPTION:  -user=pete
      PROCESS_OPTION:  -printer_name=HP4500DN
      PROCESS_OPTION:  -printer_id=lp
      PROCESS_OPTION:  -printer_ctl=
      PROCESS_OPTION:  -printer_queue=lp
      PROCESS_OPTION:  -form_name=LAND16
      PROCESS_OPTION:  -form_id=
      PROCESS_OPTION:  -form_ctl=-orientation=Landscape -cpi=16
      PROCESS_OPTION:  -rpt_options=

Building spooler options for 'lpr'...
     Spooler Options: -h -Plp 

-format=MPAGE, checking for a filter script...
    Filter /work/appx/415/data/filters/MPAGE not found...
        Using Filter: /work/appx/415/data/filters/ASI/MPAGE

## Final Invocation of lpr:
cat /tmp/SYSADMI5 | /work/appx/415/data/filters/ASI/MPAGE -orientation=Landscape -cpi=16 | lpr -h -Plp  

==========[ Starting filter ]================================================
MPAGE      - Generic MPage based filter script              Updated: 03/21/01
=============================================================================

Filter Script Pathname: /work/appx/415/data/filters/ASI/MPAGE
Command line arguments: -orientation=Landscape -cpi=16

Current settings to use when formatting, def means Default.
    Orientation: landscape
            Lpp: def
          Pitch: 16
            Lpi: def
            Vsi: def
           Font: def
        Collate: def
    Pages/Sheet: def
Extra Arguments: 

mpage cmd: mpage  -1 -o -l -W176 -L60 

==========[ Exiting filter ]================================================

The Disposition was set to SCRATCH
    Removing /tmp/SYSADMI5 
    Removing /tmp/SYSADMI5.cfg

/work/appx/415/data/appx_print script completed
============================================================================

{log file dump:ends here}












