
lp3820 - Print AFP documents on a personal laser printer

         Ken Borgendale

         Version 2.7 - 18 August 1997

Release Notes
-------------

Release 2.7
-----------

This release adds Canon BubbleJet support.

The documentation is now in the form of an HTML document.

Release 2.6
-----------

- Allow output to a TIFF file.  A new type is added: "tiff".  In this
  format, each page is placed in a separate file.

- Standalone PSEGs did not print correctly on several printers

- Add support for internal resources such as PSEGs within a FORMDEF

- Metrics for the new IBM Logo fonts are added

- Extended characters do not print correctly on some printers

- Extend the glyph mapping table size to 512

- Fix an error in form name processing for OS/2 queues

- Fix the default Brazil codepage


Introduction
------------

Most of the IBM print documents available on the IBM mainframe systems
are in the AFP (Advanced Function Print) format, designed to be printed
on the 3820, 3800-3, 3812, and all of their successor products.
These files have VM file types such as LIST3820, LIST38PP, PSEG3820 and
LISTAPA.  Most of these documents are created by DCF (Script,
BookMaster), but they are also created by other products such as GDDM
and DisplayWrite/370.  The printers which print these documents are
large printers attached to the mainframe.  PC laser printers are
supported by word processing packages on the PC, but are unable to
print host documents.  The lp3820 package attempts to bridge this gap by
allowing most AFP documents to be printed on a personal laser printer.
lp3820 can be used to print draft copies, or to print distributed
documents.

Some documents will not print correctly, and the font appearance and
spacing differ from the AFP fonts.  lp3820 is a datastream converter.
It takes in an AFP file, and puts out a personal printer datastream.  It
is not designed to help you move your data between the host and the PC
(either the input or output datastreams).  This document contains a
description of how to install and use the lp3820 package.
personal laser printer.

The following formats of AFP documents are supported:
     LIST3820 - Document for the 3820 and most other AFP printers
     LIST38PP - Document for the 3800 mod 3 and 6
     LIST4028 - Document for the 4028 (300 dpi)
     LIST4250 - Document for the 4250 (600 dpi)
     LISTAPA  - 3812 or 3816 document
     OVLY3820 - Overlay for the 3820
     PSEG3820 - Page segment for the 3820
     PSEG38PP - Page segment for the 3800-3

Page segments and Overlays are treated as one page documents.

lp3820 deals with personal laser printers in four modes:

1. PPDS - Personal Printer Datastream (native mode on the IBM
   LaserPrinter).  There are two variations of this datastream for the
   4019 and the 4029.  The 4029 mode uses scalable fonts not available
   on the 4019.

2. HPPCL - HP Printer Command Language (native mode of the HP
   LaserJet series, and emulated on most other personal laser printers).
   HPPCL for the HP LaserJet II and above is supported (PCL4).  There is
   full support for PCL5 (HP LaserJet III, HP LaserJet 4, and IBM4039).
   There is also minimal support for the IBM 4216-3x in HP emulation
   which is PCL3 with scalable fonts.

3. PostScript - Adobe printer language (used in a large number of high
   end personal printers, the IBM 4216, and available for the IBM
   LaserPrinter).

4. Raster - The page image is rasterized within the PC and downloaded
   to the printer as an image.  Download in either PPDS or HPPCL is
   supported.  This allows support of the HP DeskJet, as well as
   mixed orientation support for the 4019 and PCL4.  Output to a TIFF
   file is also supported.

In addition to these printers, lp3820 will also allow the text of an AFP
file into a flat file.  This can be used to extract the text from a
print file, or to view the contents on the display.

In order to print text within the AFP documents, lp3820 provides a large
set of soft fonts.  lp3820 can use the resident fonts (but they must be
declared).  lp3820 uses soft fonts in either PPDS or HPPCL mode, and
converts as necessary for the printer.  The soft fonts shipped with
lp3820 are in PPDS mode, but are converted to HPPCL mode when printing
in HP mode.  These fonts are not used in PostScript or text modes.
lp3820 downloads PostScript fonts in either ASCII (.pfa) or binary
(.pfb) to either a PostScript or 4029 printer.  lp3820 provides
PostScript type 3 soft fonts for the IBM logo and extended typographic
fonts.


Getting Started
---------------

If you are an expert user who does not read documentation, all you have
to do in download lp3820 (and optional font package), extract the fonts,
and make sure everything is in the path.  Since you are reading this
document, you probably want that in just a bit more detail, so read on.

Note:  The directions below are for the PC version.  Many of them are
modified for the AIX and VM versions.  See the AIX section below for
a description of the AIX differenced.

You will need the following to run lp3820.

1. One of the following operating environments:
   OS/2 2.x, 3.0, or 4.0
   DOS 3.3 and above with at least 286 and 500K available memory
   RS/6000 AIX
   VM/CMS

   The DOS version runs in Windows 95 from the MS-DOS prompt

2. A printer of one of the following types:
   PPDS (4019, 4029, 4037)
   HP-PCL4 (LaserJet II, 4019)
   HP-PCL5 (LaserJet III, LaserJet IV, DeskJet 1200)
   HP DeskJet or Lexmark 4076 (ExecJet II)
   PostScript

3. Disk space (you will need extra during install)
   4029 PPDS, PostScript, LaserJet 4    600K
   4039 PCL5, LaserJet III              850K
   4019 PPDS, HPPCL4, Raster           2000K

4. LP3820 PACKAGE
   LP3820  PACKAGE on OS2TOOLS - OS/2 32 bit code
   LP3820X PACKAGE on AIXTOOLS - AIX code
   LP3820  PACKAGE on VMTOOLS  - VM/CMS code
   LP3820  PACKAGE on PCTOOLS  - DOS executable only.  You will need
                                 the other files from OS2TOOLS.

5. If you are running an IBM LaserPrinter 4019 in PPDS mode, or any
   printer in HPPCL4 mode, you will also need the softfont package
   LP3820F PACKAGE.  For the LaserJet III and compatibles you will
   need the Letter Gothic or BookMaster Gothic fonts from either
   LP3820F PACKAGE or LPBGOT PACKAGE.

   Note:  Three versions of the package exist on various tools disks.
   The fonts are the same and can be interchanged.  The packing is
   done differently for the various tools disks:
   LP3820F  on PCTOOLS  - lp382f.zip      (unzip or pkunzip to unpack)
   LP38AIXF on AIXTOOLS - LP3820F PACKLIB (FCOPY to unpack)
   LP3820F  on VMTOOLS  - lp3820.tar.Z    (uncompress and tar to unpack)

6. Some AFP files to print. The package is very dull if you do not
   have anything to print.

Installing LP3820

The installation of LP3820 consists of 5 steps:
 1. Making a directory to put it in
 2. Unpacking lp3820
 4. Updating the profile
 5. Setting the LP3820 environment variable
 6. Making sure it all works

Note:  The example commands shown here may have to be changed based on
what tools you have installed, and what directories you put things in.

Making a directory
------------------

Select a drive which has enough space (2.5 meg for install, 2 meg to
run) and create a directory.  If you are not going to install the fonts,
you might want to install lp3820 in an existing directory in your path
instead.  For example, the command:
    md c:\lp cd c:\lp
will make a directory called lp on your c drive.  This name will be used
in the following examples, but you may put it on any drive and in any
directory.  This directory should either be in your PATH, our you must
change directory to it before using lp3820.

Unpacking lp3820
----------------

lp3820 comes as a package on PCTOOLS which includes this document.  You
should download the files in the package.  The files do not have to be
all in the same directory, but must be in the path or the current
directory.  You should get the following files:
   lp3820.exe  - OS/2 executable
   lp3820.pro  - user profile
   lp3820.ftb  - font metrics tables
   lptest.afp  - small test page
   lp3820.doc  - this file

Note: The name of the executable in other operating systems is:
   DOS:     lp3820d.exe
   RS/6000: lp3820
   VM/CMS:  LP3820 MODULE

The soft fonts are quite large, and must be unpacked before they can be
used.  Use pkzip to install them.  The fonts are not necessary if your
printer is a 4029 or PostScript.  You will get a large number of files
with the extension .dlf.

Note: The font packages may be in the form of a self-extracting .exe
file.  You can either run the .exe, or use PKUNZIP to extract them.


Updating the LP3820 profile
---------------------------

Before you can print using lp3820, you must tell it what kind of printer
you have.  As shipped, lp3820 has no default, and so you must either
update the profile or specify a printer name each time you invoke
lp3820.  Using your favorite editor, edit the file lp3820.pro.  This is
the profile for lp3820, and it allows you to customize lp3820.
   e lp3820.pro

You should see the entry:
    default = none

This specifies which of the printer entries below is the correct one.
You can override this on the command line, but this line specifies which
printer entry to use by default. You should set this default to match
your printer.  This is the name of a printer entry later in the
file.  Set it to one of the following:

   hp3     =  HP LaserJet III
   hp4     =  HP LaserJet 4
   dj      =  DeskJet
   ps      =  Any printer in PostScript mode
   psf     =  PostScript sent to a file
   ps2     =  PostScript level 2
   djcolor = DeskJet in color mode
   hpx     =  HP LaserJet in raster mode
   4019    =  IBM LaserPrinter 4019 in PPDS mode.
   4029    =  IBM LaserPrinter 4029 in PPDS mode.
   4039    =  IBM 4039 in PCL5 mode.
   hp      =  HP LaserJet II or compatible (including 4019 in HP mode)
   4019x   =  IBM 4019 in raster mode
   tiff    =  Create TIFF image files

You should also change the default paper size to match the paper you
have in your printer.  If you are outside North America, you are
probably using A4 paper and not letter size.  You can set the default
paper size to:

   a4     = 211mm x 297mm
   letter = 8.5i x 11i       (default if not specified)
   legal  = 8.5i x 14i
   exec   = 7.25i x 10.5i
   b5     = 182mm x 257mm
   a5     = 148.5mm x 211mm

Each printer description consists of a few lines describing the printer.
The first line is a "printer" entry, and gives the name of the printer.
The next is a line for the printer type, and below that a line for the
printer port.  If your printer is not attached to lpt1, you will need
to update the printer entry.  You can create more printer descriptions
if you like, but you should model them on one of the existing entries.

For the port, you can give the name of a device file, disk file, or a
file extension starting with a dot.  You can use the name of an OS/2
Queue by starting the name with a colon (:).  The name is the physical
name which shows up on the View page of the Print Object settings.
   port :postscri


Setting the LP3820 environment variable
---------------------------------------

lp3820 needs to know where its files are.  You can do this in several
ways:
    1. Run with all files lp3820 needs in the PATH.
    2. Run with all files lp3820 needs in the current directory.  (This
       is actually just a subset of the first).
    3. Set an environment variable LP3820 giving a path to locate the
       files.  The .exe files must still be in the path.  This option
       gives maximum flexibility.  You can set the lp3820 variable to
       several directories, including any place you keep soft fonts.
          set lp3820=c:\lp;c:\pclfonts
       This statement should be placed in your config.sys.

Testing the installation
------------------------

With any luck, lp3820 will now work.  To test it out, a one page
document is included in the package.  To print it, type:
    lp3820 lptest

Note: In OS/2, you must either use the datastream matching your print
driver, or use the print driver IBMNULL.  If you use the

This should show you an title line, and several normal fonts, including
some symbols (left arrow, theta, right arrow) on the last line.  This
will also show the version of lp3820.

Now extract the text from the file by typing:  lp3820 lptest.afp text
You should have the file lptest.doc on your disk.  You should also try
lp3820 out on one of your own documents.  To do this, download any
LIST3820 document.  Remember to download the file in binary (without
doing EBCDIC to ASCII translation).

If you are using Almcopy, you should add lines to your ALMCOPYX NAMES
file to map LIST3820 in to PC file extension .afp, and in binary.


The DOS verion of lp3820
------------------------

The DOS version of lp3820 runs in DOS 3.3 and above.  It requires at
least a 80286.  It requires about 400KB of memory, but this varies
based on which printer is used and the complexity of the document.

The DOS executable is shipped as lp3820d.exe.  It can be used with
that name, or renamed to lp3820.exe.  If you get just the DOS
executable, you will need to get the rest of the OS/2 package.
(lp3820.pro and lp3820.ftb).

The DOS version runs in Windows 95 from the MS-DOS Prompt.

To print in DeskJet and rasterized 4019 mode while in DOS, lp3820 uses
Extended Memory (XMS).  You must have himem.sys or a similar memory
manager in your config.sys for this to run.  You must have 1.1Mb of
XMS memory available to run a normal DeskJet page.  To print in color
you need 4.4Mb or XMS memory.

While in DOS, the amount of XMS memory available is based on the real
memory of your machine above the 640K limit.  In a command prompt from
within Windows, and in an OS/2 DOS session, the amount of XMS memory
can be specified using DOS settings.

The use of extended memory can cause lp3820 to run slowly when
printing for a DeskJet.  This happens when printing in landscape mode,
and when printing vertical lines.

You can view documentation in lp3820.inf using the view command which
comes with DOS 7.0 and OS/2.


lp3820 on RS/6000 AIX
---------------------

The AIX version is a direct port of the PC version with only the
changes necessary to support AIX.  The RS/6000 AIX version contains
basically the same files as the PC version.  Only the .exe file has a
different name.

The files are in tar.Z format.  First download in binary the file
LP3820 TARZBIN to the AIX file lp3820.tar.Z.  Then do the following:
    uncompress lp3820.tar.Z
    tar -xvf lp3820.tar
    rm lp3820.tar

In AIX, the case of file names is significant.  All file names should
be in lower case.  In most cases, lp3820 will maintain the case of
user specified file names.  Generated file names will be in lower
case.  Normally, the same three character extensions used in the PC
are used in AIX.  The exception is the binary which has no extension.
The variable names PATH and LP3820 are in upper case.

Command options can begin with '-' and '+'.  There is no difference in
meaning between the two.

In AIX it is not possible to directly copy the file to a printer
device file.  The default action in AIX is to direct the output to
standard output, and to redirect it using lpr or qpr.  This is the
primary differnence between the PC and RS/6000 profiles.  lp3820 can
be used as a true filter by specifying the input file name as a single
hyphen (lp3820 -).

Unix systems try as hard as possible to filter the datastream while
printing.  The PPDS or HPPCL output is binary, and will not survive
such filtering.  Use the binary or plotter option on the print support
(such as the -db opton of qpr).  No special care is needed for
PostScript files.

All of the files except the executable and profile are idential
between the PC and AIX versions, and may be freely moved or shared.
All such files should be transfered in binary (no CRLF filtering).

The additional fonts are available on VM in the file LP3820F TARZBIN.
Follow the directions above to load these.


The lp3820 command
------------------

lp3820 basically runs as a command line filter.  You can integrate it
into other programs using REXX.  If no operands are given, lp3820 will
prompt for some basic options.

lp3820  file printer -options

  file     - Gives a name of a file to print.  This can be - to
             indicate stdin.  Running as a filter does not work in VM.

  printer  - Gives the name of the printer.  This is one of those
             named by a printer entry in lp3820.pro.

  -?    Show a brief help

  -??   About lp3820. Show the author and copyright notices for lp3820.

  -f file:  Override the printer port. The operand is a filename.
        The file name can be either the next operand, or part of the
        current operand following a colon or equals.  The following
        are all valid:
          -f outfile.ps
          -file:lpt2
          /f=c:\temp\out.pcl
          -f :postscri
          -f -

  -p Page range: Specify a range of pages to print. This takes one or
        two page names as operands. These can be specified as * to
        indicate the start or end of the document. If only one page is
        specified, then only that page is printed. The pages must be
        separate operands. Be careful not to put the printer name after
        a single page, it will be considered the ending page number.
        These are all valid page ranges:
          -p 2
          -p 3 5
          -page iii 3-19
          /p 5 *

  -pn Page number range: Specify a range of pages to print as a start
        number and count.  This can be combined with the -p option to
        create a full set of possibilities.  The first operand is the
        number of the page to start with.  The second operand is the
        count of pages.  If the count is not given, it defaults to one.
        These are all vaid page number ranges:
          -pn 2
          -p 2 -pn 1 5
          /pn 5 2

  -co Copies: Specify a number of copies. The copy count is a separate
         operand, or follows a equal (=) or colon (:). This value is put
         into the datastream, and it is up to the printer to honor this
         count. Normally, this will cause the copies to come out
         uncollated (n copies of each page).
         These are valid copies:
           -co=3
           -co:2
           /copies 3

  -q Quiet: Do not give status information. If this is selected, only
         fatal error messages will cause any output. This is designed to
         be used when lp3820 is being used without the user being aware
         of it.

  -d Debug: Show additional messages. This should be used when modifying
         the profile, or when trying to determine why lp3820 is not
         giving you the expected results. Normally errors in the profile
         are just ignored.

  -dx Duplex: Set hardware duplex option

  -s Source: Specify the paper source as 1, 2, or M. Two sources can be
         specified, the first is used for the first page, and the second
         from subsequent pages. If only one paper source is given, it is
         used for all pages. The value is put into the data stream, and
         it is up the the printer to use it. By default, the hardware
         default paper source is used. Examples of valid paper source
         specifications are:
           -s2
           -s21
           /sm1

  -odd  Print only odd pages.  This can be used as part of a two pass
        duplex.

  -even Print only even pages.  This can be used as part of a two pass
        duplex.

  -a    Average sync: this gives the best appearance and smaller data
        stream, and is thus the default, but it only works for PostScript.
        For other datastreams this is the same as char sync.

  -c    Character sync: set cursor position for each character This is
        the normal default, and need not be specified unless the printer
        entry was changed.

  -n    No sync: set cursor position only on absolute moves. This
        creates a smaller output file, but the results can look very
        strange if the font substitution is not exact.

  -ns   No scale: Do not scale the image, but put out the entire page
        as if it were a 300 dpi document.  This is useful for documents
        with full page images such as the output from PS/370.  This
        option also sets a -200 left margin.  This should only be used
        on LIST3820 documents.

  -ni   Small images: Do not scale the image, leaving it smaller, but
        make the text the normal size.  The image is aligned at the
        upper left corner on the physical page.  This should only be
        used on LIST3820 documents.

  -nx   No automatic extension.  Do no automatically append the
        extension for the input file name.  This allows file names
        without an extension to be used.

  -cg=# Copy group: This is used for suppression support, and specified
        which copy this represents.

  -x    Extract:  This allows files within lp3820.ftb to be extracted.
        This is useful to see or modify the internal files.  For
        instance to see the standard 4029 profile you can do:
          lp3820 -x !std4029
        This creates the file !std4029.pro.  You can modify this and
        update your profile entry to use the new file instead of the
        internal !std4029.

        Note: In VM you must be careful when specifying the internal
        name to put an option or end of command after the name.  The
        optional output name must be specified with a dot separator.
        For instance:  "lp3820 !std4029 -x std4029.pro" works fine.

  -xl   Give a list of extractable files.  An operand if specified gives
        the name of the metrics file.  This must be one of the ones
        specified by a METRICS entry in the profile.  The list gives
        the name, type, size, and a comment.
          lp3820 -xl lp3820 out

  -z    Send messages to stdout:  Normally messages are sent to stderr
        so that output can be redirected to stdout.  However, in some
        operating systems, stderr cannot be redirected to a file.
        This option causes all printout normally sent to stderr to be
        sent to stdout instead.  Note that messages generated before
        this option is processed are still sent to stderr.


LP3820 Reference
----------------

The external documenation for lp3820 is available in lp3820.inf which
can be viewed using the "view" commands of OS/2 or DOS.

More information is available in lp3820.afp which is included in the
package.  You can print it using lp3820.  If other options are failing,
you should still be able to get the ASCII flat file by doing:
    lp3820  lp3820.afp  text -f lp3820.txt

The documentation is also available in .inf file which can be viewed
using the OS/2 view command.

Note: lp3820.afp is called LP3820 LIST3820 on the host.

Note: lp3820.afp uses the IBM core interchange fonts.  Some sites do
not have these installed.  The document prints fine using lp3820.

Ken Borgendale -  9 August 1996

    KWB at BCRVM1
    kwb at austin
    kwb@vnet.ibm.com
    USIB4KWB at IBMMAIL
