lp3820 - Print AFP files on a personal laser printer
Ken Borgendale - Ken@Borgendale.com
Version 2.7
Many of the IBM print documents available from IBM are in the AFP (Advanced Function Print) format, designed to be printed on the 3812, 3820, 3800-3, and all of their successor products. These files have VM file types such as LIST3820, LIST38PP, and PSEG3820. Most of these documents are created by DCF (Script, BookMaster), but they are also created by other products such as GDDM, OGL, and DisplayWrite/370. The printers which print these documents are large shared printers attached to the host.
The direction today is toward small, personal laser printers and inkjet printer attached to PCs. These 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.
This package allows AFP documents to be printed on a personal laser printer. The following formats of AFP documents are supported:
Page segments and Overlays are treated as one page documents.
Compressed images (IOCA, CCITT-G4) are not printed.
lp3820 deals with personal laser printers in several modes:
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 bitmap fonts. lp3820 uses bitmap fonts in all printing modes. The soft fonts shipped with lp3820 are in PPDS mode, but are converted to HPPCL mode when printing in HP mode.
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.
lp3820 v2.7 adds the ability to print to Canon BubbleJet and compatible printers. There are no other functional changes or fixes.
A small number of fonts are added to the font package to support the BubbleJet 360 pel characters.
If you are an expert user who does not read documentation, all you have to do is unpack the base package and optional font package into your path, customize the profile, and set up your program object. Since you are reading this document, you probably want that in just a bit more detail, so read on.
lp3820 runs on OS/2 2.0 and above. A DOS version is also available. The DOS version also runs in Windows 95 from an MS-DOS Prompt. There are also versions for RS/6000 AIX and VM/CMS.
You will need the following to run lp3820.
This consists of a large set of soft fonts, and is not needed if you only plan to run in 4029 PPDS mode or PostScript mode.
These descriptions are for installing in OS/2 and DOS. There are separate sections below for RS/6000 and VM, but the process is basically the same.
The installation of lp3820 consists of 6 steps:
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.
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:
If you get lp3820 in a .zip file, you must use some version of unzip or pkunzip to decompress the file.
If you get lp3820 uncompressed, you can use the program files directly from the CD-ROM or LAN. You may want a private copy of lp3820.pro. You cannot use the LAN or CD-ROM directory as your current directory if you want a modified copy of lp3820.pro.
The .exe file must be in your path. You can either put the directory you just created into your path, or move the .exe file to a directory which is in your path.
If you get lp382f in a .zip file, you must use some version of unzip or pkunzip to decompress the file.
If you will only be using lp3820 in PostScript, 4029, and Text modes you do not need these fonts.
When you are all done, you can delete the .zip files.
If you are using only the HP LaserJet III support, you do not need the Times or Helvetica fonts (time*.dlf, helv*.dlf).
If you get the fonts already decompressed, you can use them directly from the CD-ROM or LAN by setting the LP3820 environment variable to include the directory they are in.
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.
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:
Note: There are some additional example printer descriptions in the profile, including ps2up and ps4up.
If you are outside North America, you are probably using A4 paper and not letter size. You must tell lp3820 what paper you are using. Set the paper entry at the top of the file to the normal size paper you use. You can override this within an individual printer entry.
If your printer is not attached to lpt1, or you are are not using a printer, you should change the port entry. Make this change in the entry you have set as the default. Give the name of a device file, disk file, or a file extension starting with a dot.
In OS/2, you can use the name of a logical printer. This allows you to direct output to a particular logical printer even if it does not have a character device associated with it. The name given is a colon (:) followed by the physical name of the logical printer. This shows up in the View tab of the settings.
You can set up more than one printer by changing the entries in lp3820.pro. You can create your own printer entries with a set of options, and specify this as the second operand on the lp3820 command.
There are several other global profile settings which you may wish to change, such as the default extension for documents, and the extensions for PSEGs and overlays.
lp3820 needs to know where its files are. You can do this in several ways:
You can set the lp3820 variable to several directories, including any place you keep soft fonts.
This statement should be placed in your autoexec.bat in DOS, and in your config.sys for OS/2.
With any luck, lp3820 will now work. To test it out, a one page document is included in the package. To print it, type:
This should show you an IBM Logo 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:
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.
If you are using almcopy, you may wish to update the file ALMCOPYX NAMES to change the mapping of LIST3820 and LIST38PP files to the extension .afp, and to make this conversion an automatic binary conversion. You will also want to change the mapping of PSEG3820 and OVLY3820 to binary.
lp3820 allows you to default the afp file extension. This is normally set to '.afp', but can be changed in the profile.
Note: If you are using OS/2, you must either have the print driver set to IBMNULL, or have it set to the printer matching the datastream you tell lp3820 to create.
Before you can print a file, you have to have one. AFP files are generated on the host, so you must download them to the PC to print them.
Note: AFP files must be downloaded in binary. lp3820 also supports files downloaded with the almcopy /SOURCEBIN option.
The Windows 95 and Windows NT version of lp3820 runs is the same as the OS/2 version except that the executable is shipped as lp3820w. You may choose to rename this to lp3820.exe if you use only the win32 version.
Using the Win32 version of lp3820, you can use a UNC name for the name of the printer. This allows lp3820 to print to network printers. UNC names are in the form: \\server\\name
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).
To print in DeskJet, BubbleJet, 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. BubbleJet pages are somewhat larger.
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 or BubbleJet. This happens when printing in landscape mode, and when printing vertical lines.
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:
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 difference 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 option of qpr). No special care is needed for PostScript files.
All of the files except the executable and profile are identical between the PC and AIX versions, and may be freely moved or shared. All such files should be transferred in binary (no CRLF filtering).
The additional fonts are available on in the file LP3820F TARZBIN. Follow the directions above to load these.
In general, the output of lp3820 is much larger than the input, and thus it normally makes more sense to run the conversion on the PC rather than the host. There are some cases where this is not true, and so lp3820 is available to run on VM as well as the PC.
Most of the files are simply uploaded from the PC in binary, and 'bin' is added to the filetype to indicate this. Thus the file type .fbt on the PC becomes FTBBIN on VM. The default font file type for PPDS fonts is FONT4019. The profile is called LP3820 PROFILE and is in EBCDIC.
The font metrics file is called LP3820 FTBBIN, and must be uploaded as a fixed length record file (the record length does not matter, but 1024 is normally used).
There is no path processing in VM, but all files must be on accessed disks.
The command structure is identical to the PC, except that the three part file names may be used. Note that the file name may also be specified separated by dots. The PC-like option syntax is not normal on VM, but it does make the code the same on the PC and VM.
Standard input and output cannot be a binary file on VM, and thus PPDS and HP output should not be redirected, and stdin my not be. Output is normally directed to a file.
To run the VM versions, you need to have the C/370 runtime library available. If you get a failure, try issuing the following commands at the CMS command line.
The bitmap fonts necessary for DeskJet, BubbleJet, and 4019 conversion have the file type FONT4019.
lp3820 is a datastream converter and is designed to be run from a command file or command line. However, it is possible to set it up to run from the OS/2 desktop, and to participate in drag and drop.
To set up the program object, set the path name to the file name where you keep lp3820. This should show you the lp3820 icon which contains a page, a laser printer, and a red arrow. Set the working directory to the directory containing lp3820.pro and lp3820.ftb.
Set the Parameters field to [] %* followed by the name of your default printer (an entry in lp3820.pro). You can set up several program objects with different printer names. For instance, to set up an lp3820 program object to print in PostScript two per page you could set the Parameters field to:
lp3820 can often do a very good job at printing AFP documents on a personal laser printers. However, there are some documents which do not print correctly, and there are some cases when the appearance is wrong. To understand why this occurs, you should understand the differences between the host printers and their fonts, and the personal laser printers and fonts.
Most AFP documents are designed for the printers which print at 240 dots per inch. Personal page printers are mostly 300 dpi. Thus, the same fonts cannot be used, and images must be scaled at a 4 to 5 ratio.
Using the -ns option, you can scale the text instead of the image. This gives better looking images, but the page is only 80% of the normal size.
Using the -ni option, you can leave the text the correct size, and print the image at 1:1 pels, which reflects a 20% size reduction. The image is aligned at the upper left corner on the physical page.
It is allowed to have 300dpi or 600dpi PSEGs within a document which is otherwise 240 dpi. This would normally be done by having external PSEGs at a differing resolution, but the PSEGs may be internal to the document.
lp3820 can print documents formatted at 300 pel (4028). You should use the core interchange fonts when doing this.
The goal of lp3820 is to create the same output regardless of which output datastream is selected. However, there are several cases where this does not happen. There are also performance differences between the various datastreams.
If your printer can only do one of the datastreams, you can skip this section, and just select that one. However, there are a number of printers (such as the IBM LaserPrinter) which can do all or several of them.
The HP-PCL5 support (LaserJet III, LaserJet 4, Lexmark 4039) gives a full function support including scalable fonts and image compression.
The HP-PCL5 datastream is normally small and fast. The datastream usually contains downloaded characters, and thus must be processed in binary.
The hp3, and hp4, and 4039 entries are almost idential. The different printer entries are mostly used to describe the resident font differences between the printers.
The HP-PCL4 support can be used on almost all laser printers including all IBM LaserPrinters. It is the least functional of the various data streams and cannot support mixed orientation. You can use the HP rastermode (hpx) to get full function printing on a PCL4 printer.
HP-PCL is not able to do separate horizontal and vertical scaling of scalable fonts.
Note: If your printer default is not set to the size paper you have selected using the paper entry, you may need to force the paper size using a setup option. An example of this is shown in lp3820.pro.
PostScript is the most functional of the datastreams, but it is often the slowest. It is especially slow for image document, small document, and documents containing raster fonts.
All functions are available in PostScript. Images and margins work correctly with scaling.
If your printer handles PostScript level 2 (such as the LaserJet 4 and Lexmark Optra printers) you should use the printer description "ps2" which allows for compression of images.
The datastream contains only printable characters, and does not have to be processed as binary. The output file can be freely edited. Line lengths are kept to below 128 bytes. (Note that using the binary option will create a datastream without these characteristics).
Even though you have PostScript, you might want to set up your printer to run HP-PCL5 or PPDS mode for documents unless you use the multiup or scaling functions.
PPDS is the native datastream of the IBM LaserPrinter. lp3820 was originally designed for PPDS, and much of the font support is based on the PPDS model.
On the 4029, the only function missing from PPDS mode is the multi-up capability. On the 4019, mixed orientation documents also do not work. However, you can use the 4019 raster mode (4019x) to get mixed orientation.
Using the scale function with images sometimes gives undesired results.
If you have a 4029, image printing is by far the fastest using 4029 PPDS mode, since the images are compressed when sent to the printer.
The datastream usually contains downloaded characters, and thus must be processed in binary.
In the raster version of HPPCL and PPDS, the entire page is rasterized in the PC, and downloaded to the printer as an image. This is designed to allow printing on an HP DeskJet and Canon BubbleJet, but can also be used on the 4019 to allow rotated print.
Raster mode uses only bitmap fonts. No scalable fonts are supported.
The DeskJet has very large margins and therefore has even more problems printing output which fills the entire 3820 page. The top margin is 0.4i (10mm) and the bottom margin is 0.5i (13mm). If you are missing the footers from pages, try adding "scale 98 100" to the printer entry.
HP-PCL mode raster (hpx) files print fine on DeskJet and PCL5 printers. To print on a PCL4 printer such as a LaserJet II, it is necessary to turn off image compression. Use option noimgcomp in the printer description.
HP-PCL color raster mode will print in color (on a color printer), but requires both more time and memory on the PC.
4019 mode raster (4019x) files print on any 4019 or 4029 printer. All 4029 and some late model 4019 printers allow image compression (option imgcomp). If the output is not correct. use option noimgcomp.
BubbleJet mode (bj) files print on most Canon BubbleJet printers. All images are compressed, and the imgcomp option is ignored. Output can be monochrome or color.
TIFF mode. This outputs to a image file. Only compression is supported. A separate output file is created for each page of the document. The given file name is incremented as necessary to do this. This can be used to send the output to a fax system or other TIFF viewer.
Most of the fonts used by DCF are from the Sonoran family of fonts (Sonoran Serif and Sonoran Sans Serif). These are rasterized fonts designed for the 240 dpi printers, and separately hand tuned at each size. The metrics do not scale uniformly as the font size is increased.
The soft fonts provided with the lp3820 package are based on the industry standard font metrics which scale correctly.
Because the metrics do not match between the AFP and soft fonts, characters do not look to be correctly placed. lp3820 normally places each character at the pel (at 300 dpi) closest to the correct position in the AFP document (at 240 dpi). For PostScript, word averaging is used, which makes this look a little better.
Note: If your site has the Core Interchange Fonts available, these should be used, as the metrics of these fonts match the industry standard metrics used by lp3820.
For BubbleJet printing, lp3820 uses 300 pel fonts at 360 dpi. To do this it uses a larger actual font size. This will cause some differences in appearance between BubbleJet and other printers.
When you use DCF to create an AFP document, you format it using a set of AFP fonts which are installed on your S/370. Many sites have over 100 Mb of AFP fonts installed (they are of course shared between all users).
lp3820 has internal support for many of the fonts shipped by IBM, and a selection of Internal Use fonts. However, it is quite possible that some fonts which are available at your site are not internally supported by lp3820.
lp3820 ships a set of soft fonts, but the number of fonts were restricted to keep the size for the lp3820 package below 2Mb. lp3820 ships fonts for 8, 9, 10, 11, 12, 14, 16, 18, 20, and 24 points.
If you wish to take up more room on your disk, you can install additional soft fonts for the other sizes. You must update the lp3820 profile to tell lp3820 what fonts are available.
Any available HP or PPDS soft fonts can be used. However, it is very important that you correctly identify to lp3820 the codepage that the font is in.
AFP supports an arbitrary number of code pages, by reading the code page information from a file. The soft fonts used by lp3820 do not have enough information to use this strategy. lp3820 has internal tables for a large set of code pages.
If you are using a codepage which lp3820 does not understand, you can create a synonym using the afpcode profile entry.
lp3820 is designed to be run from a command line or command file. If lp3820 is entered with no options, it will prompt for file name, printer, page range, and output file.
Entries without a leading dash are considered to be names. The first name is the input file name, and the second is the name of the printer description.
Options begin with a hyphen(-). Additional characters of the option can be specified and are ignored.
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:
The page number range is specified by two numbers. The first operand is the count of pages from the start of the file. This must be specified. The second operand is the count of pages to print. The default is one. Be careful not to put the printer name after the start page number. These are all valid page number ranges:
These are valid copies:
Examples of valid paper source specifications are:
This section describes some of the functions of lp3820. This is designed to help you use the product correctly.
In AFP, page names are an 8 character string. The page name is given in the start and end page controls. lp3820 uses this name to show progress, and to allow selection of a range of pages to print.
Although the page names are often numeric, they are not always so. It is very common to start a document with roman numerals. When using folio by chapter, the page name contains the chapter name, and some punctuation. It is also possible to have duplicate page names.
lp3820 treats the 8 characters as a string, and matches against it in a case independent manor (thus ii and II are the same).
If there are duplicate page names, only the first one is selected as a begin page, and the first occurrence after the begin is selected as the end page.
lp3820 supports printers with hardware duplex in PCL5 and PostScript. Most personal page printers do not have a duplex function, but this can be simulated by writing every other page, and putting the paper thru the printer twice.
lp3820 allows the simulation of duplex by the use of the -even and -odd options. These specify that only half of the pages will be printed in each run. To print a duplex document, you would call lp3820 twice. Once to print the even pages, and a second time to print the odd pages.
Even or Odd is determined based on the count of pages in the page range. Using the duplex or multiup entries in the profile, it is possible to specify that sets of pages are to be thought of as even or odd.
Note: Sending the paper multiple times thru the printer is not officially supported, although it seems to work OK on most printers. If you have a problem with paper curl, using duplex will probably make it much worse.
The settings for top and left margins are an attempt to compensate for the fact that the printable area on most personal page printers is smaller than the 3820. It also compensates for the fact that printers in HP mode do not measure from the paper edge, but from the printable edge, which varies by model.
The value specifies the amount to move the page to the top or left on the paper. Since it is most normal to want to move the contents down and to the right, these values are often specified as negative.
Top and left refer to the top and left of the page as it moves thru the printer, not the top and left of the text. The exception to this is 4019 landscape mode. Since the 4019 does not correctly implement orientation, the orientation change is faked using landscape orientation, and the top and left are based on landscape orientation.
lp3820 processes files with mixed orientation on PostScript, 4029 PPDS, and PCL5 (hp3 and hp4) printers. Mixed orientation does not work in 4019 PPDS or in HPPCL4 (hp). Mixed orientation works in raster mode, and this mode can be used to print mixed orientation pages on 4019 and PCL4 printers.
A very restricted form of landscape works in 4019 PPDS mode. A page is printed landscape if the first control on the page is a Set Orientation for 90 or 270. Images are not properly rotated.
Note: For mixed orientation to work correctly, lp3820 must know the size of paper in your printer. If the page size and paper size do not match, lp3820 will attempt to align one on the other. This can cause errors if these sizes are not set correctly. You can force lp3820 to ignore the page size by using "option noalign". Other alignment options allow you to set the vertical alignment to top, center, or bottom.
When using PostScript, it is possible to print multiple logical pages on the same physical page. This is known as multi-up (as in 2-up or 4-up). This function does not work in PPDS or HPPCL mode.
A set of printer descriptions is shipped with lp3820 which use the multi-up capability of lp3820 (ps1up, ps2up, and ps4up). These can be used directly, you can modify them create additional printer entries based on these.
Several options are implemented.
The multi-up capability can also be used as an example of how to customize the PostScript by modifying some of the procedures. You can do this without completely changing the header file. The proc sets are downloaded to the printer by telling lp3820 they are fonts.
You can modify these procs, or create your own. To modify them, just extract them for lp3820.ftb (using the -x option). Change your profile to use your external version, and then make the modifications.
The traditional printers for which AFP files were directed were monochrome printers. It is very rare to have color specifications within AFP files. The laser printers on which lp3820 was first run were also monochrome printers.
There are now a class of color printers for which lp3820 works. These are basically DeskJet and BubbleJet printers with 4 color print capability, but also include some PostScript printers.
lp3820 allows the use of color in a normal AFP file by allowing a color to be specified for font families, rules, and images. The normal use of this would be to provide headlines or examples in an alternate color. This is done using the color entry in the profile.
As an example, if the text is in Times Roman, and the headlines are in Helvetica bold, you could make the headlines print in red using the following command:
Color works for HP-PCL raster (DeskJet mode), BubbleJet, PostScript, and HP-PCL5 (DeskJet 1200). To enable color, you must use option color in the profile entry. This is not defaulted on for any printer type.
In DeskJet and BubbleJet mode, using this option will require four times as much system memory (about 4Mb) and about 4 times as much processing time on the page. There is no significant change in the size of the datastream unless the document contains color. The color option should only be used on newer DeskJets which support color. You should be careful using this option on 3 color DeskJet printers (such as the 500C and 540) since they print black by overprinting cyan, yellow, and magenta.
In PostScript mode, this option has no cost. On monochrome printers, the colors will show up as shades of gray (dithered).
Many of the tables used by lp3820 are in internal files. These are contained within the file lp3820.ftb. Putting the files together reduces clutter and disk usage, and significantly increases performance. However, it causes some problems if you need to modify one of these files.
The file lp3820.ftb is created (compiled) as part of the build of lp3820. There is no mechanism to update this file, but you can extract any of the subfiles, modify it, and then use the external file instead of the internal file.
The internal files are font width tables (.fwt), font translation tables (.ftt), profiles, and fonts. Since some compression of font width tables is done as part of the compilation of lp3820.ftb, the extracted file is not exactly the same as the original .ftb file, but no material information is lost.
To extract the internal files, you must know the internal file name. You can specify the external name, or allow it to be defaulted. To extract an internal file use lp3820 with the -x option, and the internal name and optionally the external name. For instance, the command:
Internal file names are up to 8 characters long, and have no extension. Searching is done case-independent.
Font width files start with the letter C and have the name of the AFP font. Font translation tables start with a T and have the name of the associated code page. Soft fonts use the normal lp3820 soft font naming convention (four char class, two char size, one char attribute). Internal profiles and other related files start with an exclamation mark (!).
To get a list of files which can be extracted from the metrics files, use the -xl option of lp3820. With no operand, it gives a list of the internal files of the first metrics file. If the operand matches the name of an open metrics file, it uses that instead.
The extract list gives the name, type, size, and an optional comment. Internal file names are case independent. The following types are given:
The size is given as bytes in the ftb file. The extracted size may vary.
The comment is derived from the file information, and is not available for some file types.
The lp3820 profile is kept in the file lp3820.pro. For examples of the items discussed below, you should look in this file.
The file lp3820.pro is search for using the current directory, LP3820, and PATH environment variables (in that order). You will probably want a private copy of the profile, even if you normally run lp3820 directly from a CD-ROM or LAN.
The profile is made up of lines. On each line is either a comment or a profile entry. Lines starting with an blank, tab, or asterisk (*) are comments.
Profile entries have a keyword starting at the beginning of the line. The keyword can be in any case. The keyword is followed by an optional equal sign, and operands. Any characters following the last operand on a line are ignored, and can be used as comments.
The profile is broken into three sections. The first section describes the global lp3820 environment. This is followed by a set of printer descriptions. The final section describes the AFP environment, and works for all printers. The final section is normally just a single includeall of !stdafp, but this is the area for customization of the AFP environment.
Printer Description Entries exist within a printer description, and only have effect for that printer. These entries are used to describe a particular printer. These are stanzas in Unix terminology.
In some cases, entries found before the first printer description are defaults for all printer descriptions. These are documented in the individual entries.
Font Mapping Entries do not exist within an printer description, but apply to all printers.
To map a from an AFP font to a soft font, lp3820 needs the following information:
If the first character of lp3820 is an asterisk (*) then the third character is used to indicate the second option starter character for command line processing. Hyphen is always allowed, and the default second option character is selected by operating system. The second starter character can be hyphen (-), plus (+), slash (/), or exclam (!). A space retains the default.
The AFPCODE entry allows you to specify the existence of a code page not internally supported by lp3820. The operands are the name it is known by in AFP, and the file name of the .ftt file.
AFP code page names normally start with T1.
An AFPCF entry allows you to specify a coded font. DCF does not use coded fonts, but other AFP producers do. A coded font consists of a font and a codepage.
The entry is the name of the coded font (which normally starts with an X), the name of a font (which normally starts with a C) and the name of a codepage (which normally starts with a T).
An afpext entry defines the default extension for the input apf file if it has no extension. The operand is a name, and should start with a dot.
The last apfext entry before the first printer entry is used. This option is ignored if it comes after the first printer entry.
The default is to use .afp.
A afpfont entry allows the addition or modification of font entries in lp3820.ftb. This provides lp3820 with metrics and substitution information.
There are three operands, the name of the font to define, the name of a font to use for metrics, and the soft font identifier for the substitution information.
AFP font names are usually eight bytes long starting with C0. DCF mostly uses the 3800 form of the name, in which the second character indicates direction. Upright fonts thus start C1. You can use either form of the name. You can find the names of fonts by looking in the file FONT3820 LISTING which should be on the same disk that the AFP fonts are located.
A codepage entry defines the code page for subsequent font entries. This should match the actual code page of the font, and indicates both the translation and character contents of the font.
The single operand is a name.
The following values are supported internally by lp3820. These same values can be used in other locations where internally supported ASCII code pages are required.
If the operand is not one of these, it is used as a file name to find a .ftt (font translation table) file. This can be an internal file (within lp3820.ftb), or an external file. This allows you to specify soft fonts which are not in standard code pages.
A color entry allows the color for font families, rules, and images to be specified. Multiple entries are processed in order, thus generic color entries should be used before more specific entries.
For DeskJet and BubbleJet printers, it takes 4 times as much memory, and a lot more CPU time to print in color. For PostScript and PCL5, there is no additional overhead for lp3820.
There are two operands. The first gives the font family or area, and the second gives the color. The first operand can have the name of of font family followed by an attribute ('i', 'b', 'x') or by an asterisk ('*') to indicate all attributes for the family.
The color can be one of the 6 primary and secondary colors, black, and white. Colors other than these full intensity colors are not supported.
A copies entry allows the specification of the number of uncollated copies to make of each page. The operand is a single numeric value in the 1 to 99 range. This value is overridden by the /co= command line option. This value is normally left unset in the profile, and set only as a command line option.
A default entry defines the default printer entry to use if none is specified on the lp3820 command. The first printer found whose names has been specified as the default is used as the printer definition.
A single operand gives the name of the printer description.
As shipped, the default printer description is set to none This is just a normal printer description within lp3820 which generates an error message.
A defcode entry is used to specify the default codepage when resolving Coded Fonts. Coded fonts are mostly used within Overlays. The default codepage is global and the last defcode entry in the profile is used.
The operand the name of a codepage, which can be the same as the second operand in the AFPCODE entry.
A duplex entry allows the specification information concerning duplex. If this entry precedes the first printer entry, it applies to all printer entries, otherwise only to the current printer entry. The operand is one or more keywords and can be:
A family entry allows the specification of a scalable font family. This is used for PostScript, 4029, and PCL5 fonts. Each family entry has the following entries. The first 5 are required. The rest are optional, and default as specified.
All fonts names except the base can be specified as a delta from the base font name. This can be an equal sign (=) to indicate a name equal to the base, an equal plus characters which appends a hyphen and these characters to the end of the base name, or a hyphen and some characters, which replaces the final hyphenated piece of the base name with the specified characters.
For PostScript, symb and 850 are the only encoding which work. For the 4029, those code pages supported by both the 4029 and lp3820 can be used. For PCL5, you can use 850, 437, 819, 1004, 1051, or symb.
In PCL5 the font name represents a font selection field. This should contain the style, bold, and typface values. To select CG Times Bold use:
Note: In PCL5 (types hp3 and hp4) both vertical and horizontal scaling is done based on the hscale (or hscaleb). The vertical scale factor is not used. This is due to a deficiency in the HP-PCL5 font implementation which does not provide for separate horizontal and vertical scale factors.
A font entry declares the existence of a soft font, and gives the file name which contains it.
There must be a font entry for each soft font installed on your system. If you use the fonts shipped with lp3820, or rename your fonts to the default names, you do not need to specify a file name.
A soft font is identified by a name which is made up of three parts:
Example font identifiers are: time12, helv18b, xtyp08.
The font classes are derived from the HPPCL font classes, and are given a four character name. The case of the name is ignored. The following classes may be used:
Names marked with an asterisk (*) are private to lp3820. lp3820 will automatically compute the FGID from the font class. You can also use the names fnt followed by a single digit (fnt0, fnt1, etc.). These are designed to allow font mapping without using an actual font name.
The font size is given as an two digit value. When the value is less than 10, the leading zero must be used.
The font attribute is a single character, and can be one of the following:
A fontext entry defines the default extension for soft fonts for which no file name is given. The operand is a name, and should start with a dot.
The default is to use .dlf.
Only the last fontext entry found in the profile is used.
Specify the name of the formdef to use. A formdef may override the setting of left, top, and paper. This can be overridden using the -fd command line option, or by a formdef within the document.
The operand is a single file name. No extension is added, but normal path search is done.
The file is processed as a normal AFP file, and may contain more than just a formdef. It is processed before the beginning of the input document.
A glyph entry allows the mapping of missing glyphs to glyphs of similar appearance. For instance, the ring accent and the degree symbol look very similar, and the font may have one, but the other may be required. This table maps glyphs for all printers.
The operands are two numbers, a from glyph and a to glyph. These are based on the OS/2 universal glyph list.
An include entry allows you to include printer specific entries. This include is conditional in that it is only done if the current printer entry is selected.
This has a single operand, which is the file name to include. This can be an internal file name (given with no extension).
An includeall entry allows an extension of the profile. This include is done regardless of whether the current printer entry is selected. Up to four levels of includes are allowed. The include facility is used by the system to define standard definitions used by all printer entries.
A left entry moves the text horizontally on the page. This is designed to compensate for any automatic margin added by the printer. It can also be used to compensate for printers which do not print all the way to the left paper edge.
There is a single operand which is a numeric value which represents a number of 1/300i units.
The value is defaulted by printer type. Most HP printers have a non-zero default. A positive value has the effect of moving the contents to the left. A negative value has the effect of moving the contents to the right.
A metrics entry allows multiple .ftb files to be used. You should normally include lp3820 as the first entry in the list. You may have up to four metrics entries in the list.
This entry must precede the first include or printer description.
It is a fatal error if the first metrics entry is not found, all others give error messages. If lp3820.ftb is not in the list, or is not found, lp3820 will probably not work correctly.
A morefont entry allows the specification of the additional fonts families which are to be used to satisfy characters which are not found in the base font. This is done on a per printer description basis. The default is to use xtyp, and symb. For base fonts not in a standard code page, the alternate font in codepage 850 is also used.
In most cases, the default morefont selection is correct and should not be changed. If you include another font family in the list, be sure to have at least one font entry for this family, which is used to derive the proper codepage.
A multiup entry allows you to control the PostScript multi-up facility.
The entry consist of a number (1, 2, 3, 4, or 8) giving the number of pages on the paper, followed by keywords and values. The value is optional, and some keywords do not allow a value.
The following keywords exist, along with the default and possible values.
Examples of the multiup control are:
An option entry specifies variations on the type. If this entry precedes the first printer entry, it applies to all printer entries, otherwise only to the current printer entry.
There can be multiple options specified in one entry, and there can be multiple option entries in a printer description. If they conflict, the last one specified is used.
The following options are allowed: :dl tsize=12.
A ovlyext entry specifies the extension to be used for external overlays. The operand is a name, and should start with a dot. The default is to use .ovl which is the default extension created by the download.
Only the last ovlyext entry found in the profile is used.
A paper entry allows the specification of the paper size in a printer. lp3820 must know the paper size to properly align documents. It is especially important for rotated documents. If this entry precedes the first printer entry, it applies to all printer entries, otherwise only to the current printer entry.
The operands are up to four paper sizes. The first is the default and paper source 1. The second indicates the size of the second paper source, the third indicates the size of the manual paper source, and the fourth indicates the third paper source (envelope feeder). Missing operands default to the first size specified. If no paper size is specified, the default is letter
The following are valid paper sizes:
A path entry allows an additional path for file searches to be specified. This is mostly useful to specify where the fonts are placed in a LAN or CD-ROM environment.
A port entry gives the name of the file to which the output is to be written. This is normally the name of a printer device file, but may be any disk file.
This is a single operand, which is a file name.
If the name begins with a period, it is treated as an extension, and this extension replaces the extension of the input file to create the output file name. This is normally used when the output is to a disk file.
In OS/2, if the name begins with a colon it is treated as the name of a Queue (logical printer object). The name is the physical name of the printer which shows up in the View tab of the printer object settings. When using a queue, you can also specify the SPOOLFORM and SPOOLUSER options. The specified queue must have IBMNULL defined as one of its available print drivers.
Note: This name cannot be changed once the printer object is created, and can only be specified when the printer object is created from a template.
A single hyphen (-) indicates that the output should be sent to standard output.
This entry is overridden by the -f option on the command line.
A printer entry defines a printer description. The printer description starts with a printer entry, and continues until the next printer entry or end of file.
There is a single operand, which is the name of the printer description. This can be 1 to 16 characters, and case is ignored. You can have as many printer descriptions as desired.
A particular printer description may be used by giving this name as the second name on the lp3820 command.
A psegext entry specifies the extension to be used for external PSEGs found in the datastream. The operand is a name, and should start with a dot.
The default is to use .pse which is the default extension created by the download.
Only the last psegext entry found in the profile is used.
A psegpos entry allows the specification of the placement of standalone PSEGs. Since there is no page or include controls for these, this information is necessary to properly position the PSEG.
The operands consist of up to two positions. The first is the left, and the second is the top. If only one is given, both positions are set equal. The positions are in 1/240 inch units. The default is 120 (12.7 mm) for both positions.
A psfont entry allows the specification of a PostScript, 4029 type 1, or PCL5 scalable font to be downloaded to the printer.
All PSFONT entries in the printer description are downloaded in the prolog for PostScript. For 4029 PPDS and PCL5, they are downloaded only if they are used in the job.
There are two operands. The first consists of a soft font identifier without the size field, and the second is a file name. An attribute of asterisk (*) can be used to indicate that this applies to all font attributes. The font class is used in 4029 PPDS. In PostScript, this operand is required, but it is ignored.
The second operand consists of a file name of the font to be downloaded.
psfont entries apply to a single printer.
Note: In PostScript, the fonts are loaded as part of the prolog. This can consist of any valid PostScript statements, and do not need to define a font. This mechanism is used to implement the PostScript multi-up facility.
A psheader entry allows the PostScript header file to be modified on a per printer basis. You should not update this unless you know what you are doing.
This is here to allow you to specify either the internal or an external version of the header. If this entry precedes the first printer entry, it applies to all printer entries, otherwise only to the current printer entry.
A reserve entry allows font IDs to be reserved. This should be used when the printer has permanent soft fonts already loaded in the printer. By default, lp3820 reserves locations 1 thru 7.
The operands are a list of values in the 1 to 99 range, indicating the font IDs which lp3820 should not use. lp3820 will use values above 100 for scalable fonts.
A resident entry defines a resident font of the printer. This can be a builtin font, font card font, or a permanent soft font which is always loaded before lp3820 is run.
There is a single operand which is a soft font identifier. The resident fonts are normally of minimal use to lp3820, and very little is gained by specifying them.
A scale entry allows a vertical and horizontal scale factor to be applied to line positions. This can be used to print a document which is a little too large for the paper. This can be because the 3820 page size is a little larger, or just because it was formatted for A4, and you are printing on US paper.
There are one or two operands, and each is an integer in the range 50 to 200, and is a percent scale of the vertical and horizontal axis. The default if not specified is 100.
The best use of this feature is to allow the printing of documents formatted for A4 on US 8.5x11 (letter) paper. Since the A4 page is longer, the contents at the end of the page are often lost. By using a scale factor of about 94, it is possible to get the entire A4 page onto a letter page.
Note: You should not use scale with documents containing images unless you are using PostScript, since the image placement will not be correct.
The setup options allow the specification of printer specific controls to be added to the datastream. This should be done with care as it could cause the file not to print. Three setup string locations are supported: :ol compact.
There are two operands to the setup option. The first specifies which string. The second gives the string to send to the printer. This can be flat text, or escape sequences. An escape sequence consists of a backslash followed by either two hex digits, or the a special character from the list below:
A source entry allows the specification of alternate paper source. If no paper source is specified, then the current paper source is used.
The operands consist of up to two paper sources. The first indicates the source for the first page. The second indicates the source for all subsequent pages.
Only the first character of the paper source is used. This can be:
A spoolform entry defines the form name to send to the print queue. This works only in OS/2 when a queue name is specified as the port.
There is a single operand which is the name of a form. This must be known to the IBMNULL print driver. This works only in OS/2 when a queue name is specified as the port.
A spooluser entry defines the user name to send to the print queue. This shows up in the spool information, and is often printed in separator pages.
There is a single operand which is the name.
A sync entry allows the specification of when to synchronize character position. The soft fonts supplied do not match perfectly the fonts used on the host such as Sonoran Serif. The resolution of the AFP devices (240) is also different from the resolution of personal laser printer devices (300). It is therefore necessary to synchronize positions. This can be done in three ways:
The operand is a name. Only the first character is used. This can be a for average, c for character, and n for no synchronize. This entry can be overridden by the /a, /c and /n command line options.
A top entry moves the text vertically on the page. This is designed to compensate for any automatic margin added by the printer. It can also be used to compensate for the fact that many printers do not allow marking in the top .25 inch of the page. This can also be used to match the compensation of the 3800-3 printer.
There is a single operand which is a numeric value which represents a number of 1/300i units.
The value is defaulted by printer type, but is zero for most printers. A positive value has the effect of moving the contents up on the page. A negative value has the effect of moving the contents down on the page. Remember that moving the contents so that the top line shows, may cause the bottom to be not shown. This is because the 3820 has a longer page than can be printed on most personal laser printers.
A type entry defines the type of printer, which is used to create different data streams. If an incorrect type is used, the result will probably be garbage on the screen.
There is a single operand, which gives the type. The following types may be used:
On the host, there is a system programmer to set up the printers, and get everything installed right. Even so, it is considered somewhat of a black art. On your PC, you get to do all this yourself.
This section describes a set of common problems, and what to do about them. Try looking in here first, and if you still cannot get something to work, look in LP3820 FORUM on IBMPC. If you cannot find your problem append an entry in the forum, and you will probably get an answer.
lp3820 does not do a lot of checking of the datastream, but it does minimal checking to protect itself. In AFP each record starts with an optional introducer (0x5a) and a length field. The length must be at least 8. lp3820 checks these items and gives the "Not a valid AFP file" error message if they are not correct. The message also tells which record this was found on.
The most common problem here is that the AFP file was not downloaded in binary. Some downloaders default to doing EBCDIC/ASCII translation, and this makes the file unreadable. Also be sure you got the correct file. Some people have downloaded the SCRIPT file which an .afp extension, and then wondered why it did not print. These type of error will be found on the first record.
Another possible problem is that the file was processed using XEDIT on the host, which truncated trailing blanks from the line. This causes incorrect structured field lengths. This commonly shows up at about record 3 or 4, but could be later in the document.
In some cases, printing directly to LAN or communications attached printers does not work. lp3820 treats the output device as a simple file, and writes to it as fast as possible without any retry logic. This is normally not a problem for local spooled printers, but may be a problem for others printers.
You can try setting the retry parameter of the port you are using, or use lp3820 to print to a file, and use the copy command (use the /b (binary) option) to copy the file to the printer.
The datastream created by lp3820 for PPDS and HPPCL is a binary datastream, and cannot be processed thru a text mode CR/LF processing. The default in most cases is to process device files thru such a text filter. In some cases this is just a bug in the device drivers. This problem does not exist for PostScript files, unless you have specified the PostScript BINARY option.
In both DOS and OS/2, if you create a file, you need to use the binary mode copy to send it to the printer for PPDS and HPPCL datastreams.
The print area of the IBM LaserPrinter and other personal laser printers is not as large as the 3820. The IBM LaserPrinter has a .25i unprintable area on all sides of the paper. lp3820 has profile options which allow you to move the image across the paper to align the page as necessary. The left option moves the contents to the left (a negative value moves the contents to the right) on the page. The top option moves the contents to the top on the page.
The IBM LaserPrinters have a "feature" in which when any text or image would be placed outside the printable area it is moved into the printable area. Thus moving the contents of the page to the top or left would cause overlapping text since one line is moved, and the next line is not (since it is already in the printable area). I consider this feature to be a bug in the printer (this was partially fixed in the 4029).
One fix for this is to use a printer entry with SCALE specified.
AFP images are often made up of a number of small squares of image. Scrambled or misaligned images are normally caused by the same "feature" as the overlapping lines above. The squares at the top and/or left are moved, but the other squares are not, causing the misalignment.
lp3820 gives a termination message, and also returns a return code which can be checked by the caller. The following return codes are possible:
Most errors in the command line options are reported and ignored. Most errors in the profile are ignored, and some are reported only when the debug options (-d) is used. The quiet flag (-q) will suppress just about all messages other than terminating error messages.
Invalid input data (Not an AFP document) causes termination in the base document, but is ignored when found in an included document.