.
Eloquence B.08.30 contact contact

Documentation / Eloquence eqpcl utility

Eloquence eqpcl utility

 
.
 

Introduction

The eqpcl utility allows converting PCL documents to PDF or PostScript. It implements a commonly used subset of PCL functionality and is expected to work with a majority of the existing documents. In addition, eqpcl makes it easy to create custom forms.

The eqpcl utility internally translates the PCL command sequences and text into Postscript and uses GNU Ghostscript to create the PDF output.

Content:


Prerequisites:

Creation of PDF documents depends on the GNU Ghostscript utility which must be present on the system.

Linux
GNU Ghostscript is is available from your Linux distribution.

HP-UX
GNU Ghostscript for HP-UX is available for download from the HP-UX porting center. GNU Ghostscript

Windows
GNU Ghostscript for Windows is available for from a number of sources, including: gs927w32.exe (GS 9.27) and other versions

When running the install program, please consider to enable the option "All users" so Ghostscript is available for all users on the system.


Command Line Options

The eqpcl utility supports the following command line options:
usage: eqpcl [options] [pcl files ...]

output options:
 -help    This usage information
 -p       create PDF output (-pp for PDF/A)
 -s       create postscript output
 -a       analyze pcl data (-aa more verbose)
 -g       create postscript and pass to ghostscript

options:
 -c cfg   specify config file (default is eqpcl.cfg, ~/.eqpcl)
 -o out   specify output file (default is stdout)
 -m file  specify file with PDF marks
 -G opt   additional ghostscript options
 -C opt   define config option ([section:]item=value)
 -V       output version and exit
Any number of PCL command files may be specified on the command line, which are then combined to a single document, each file is separated by an internal PCL reset. If no file name is present, the input is read from stdin. This allows to use eqpcl in a pipe.

The option -c is used to specify a config file that defines some configuration and PCL defaults.

If no configuration file is specified:

  1. First, the eqpcl utility will look for a file named eqpcl.cfg in the current directory.

  2. On HP-UX and Linux, the eqpcl utility will then look for a file named .eqpcl in the home directory (~/.eqpcl).

  3. Finally, eqpcl will look for a file named eqpcl.cfg in the etc subdirectory of your Eloquence installation.

The option -o is used to specify the name of an output file. If not present, the output is written to stdout so that eqpcl may be used in a pipe.

The option -p is is used to create a PDF file as a result. In this case, eqpcl internally creates an intermediate Postscript result which is passed to Ghostscript to create the PDF. The option -pp is is used to create a PDF/A compliant PDF file.

The option -s specifies to create a Postscript output instead.

The option -a is used to analyze the PCL command stream. If specified twice (-aa) the output is more verbose. The results are output to stdout.

The option -m specifies a text file containing PDFmarks. The file content is added verbatim to the postscript output. This allows to specify PDF meta information (such as title, author or bookmarks). This file must comply with the PDFmarks syntax. Please refer to the pdfmark Reference manual for details.

The option -g translates the PCL input and passes it to Ghostscript. This option does NOT create a PDF file but allows to use eqpcl as a simple frontend to Ghostscript (for example, to print the resulting document).

Typical use:

eqpcl -c eqpcl.cfg -p -o sample.pdf sample.pcl
This creates a PDF document (sample.pdf) from PCL file sample.pcl. The config file eqpcl.cfg is used.
cat sample.pcl | eqpcl -c eqpcl.cfg -p > sample.pdf
The PCL data is read from stdin and converted to PDF on stdout.
eqpcl -a sample.pcl
Analyze the file sample.pcl. This decodes the PCL commands and text. Outputs the results to stdout.


Using the eqpcl utility in an application

There are several ways how to use eqpcl from an Eloquence application:
  • eqpcl may be used as the printer destination using a pipe. For example,
    PRINTER IS "|eqpcl -p -o out.pdf"
    PRINT "HELLO WORLD"
    PRINTER IS 8
    
    This creates the output file out.pdf in the current directory.

  • As an alternative, eqpcl may be configured as a printer in the eloqcore configuration file. For example, the following .eloqrc file defines a printer 90 that creates a PDF document in the user home directory:
    PRINTER 90 PIPE "eqpcl -p -o $HOME/output.pdf"
    
    A simple program as below
    PRINTER IS 90
    PRINT "HELLO WORLD"
    PRINTER IS 8
    
    then creates the PDF document output.pdf in the user home directory.

  • Create a PCL text file and use the COMMAND statement to create the PDF document. For example,
    PRINTER IS "out.pcl"
    PRINT "HELLO WORLD"
    PRINTER IS 8
    COMMAND "!eqpcl -p -o out.pdf "&MAPFNAME$("out.pcl.DATA")
    
    This first creates the output file out.pcl.DATA and then uses eqpcl to convert it to the PDF format.


Configuration file

The eqpcl utility uses a config file to define custom settings. The config file is a text file with sections marked in square brackets and items and values separated by an equal sign. A hash sign (#) or semicolon (;) denotes a comment. Values can be enclosed in single or double quotes. In this case leading and trailing spaces are preserved. Section names and items are case insensitive.

Unless specified on the command line, the config file is searched in the following locations:

  • The file eqpcl.cfg in the current directory
  • The file .eqpcl in the home directory of the user (HP-UX and Linux)
  • The config directory of the installed Eloquence release

Section [config]

This section specifies some global settings for the eqpcl utility.
ps.include = 
This specifies the path to the eqpcl ps include directory. It defaults to the share/eqpcl/ps directory in the Eloquence installation directory (e.g. /opt/eloquence/8.1/share/eqpcl/ps) and typically does not need to be specified.
barcode = 1
A non-zero value enables barcode support. By default, barcode support is disabled. Please refer to the section on barcode support for details.
overlay = 1
A value of 1 or 2 enables overlays from virtual trays. A zero value disables support of overlays. If overlay is set to one (default), the overlay is processed before rendering the page. If overlay is set to two then the overlay is applied when the page is completed. The default value is 1 and typically does not need to be specified.
gs = /usr/bin/gs
The gs option specifies the path to the Ghostscript executable. By default (unless configured), the current PATH is used. On HP-UX and Linux, the default executable is gs.

On Windows, the default executable is gswin32c.exe, but the Ghostscript installation directory is usually not located in the PATH. Therefore, the gs option should be explicitly configured, for example: gs = C:\Program Files\gs\gs9.00\bin\gswin32c.exe

gs.paper.size =
Allows to specify the paper size assumed by Ghostscript. Unless specified Ghostscript assumes a site specific default paper format. This config item should be specified if your PCL documents depend on a specific paper size.
Typical values are "a4" or "letter" (both lower case). When specified, the Ghostscript -sPAPERSIZE option is used. Please refer to the Ghostscript documentation for details (Ghostscript paper sizes).
gs.opt = 
This allows to specify custom Ghostscript command line options. Please refer to the Ghostscript documentation for details.

gs.pdf.opt = -dCompatibilityLevel=1.4 -dPDFSETTINGS=/printer
This allows to specify custom Ghostscript command line options that are used when creating PDF documents (eqpcl -p option).

gs.pdfa.opt = -sColorConversionStrategy=/RGB \
              -sOutputICCProfile=srgb.icc \
              -sProcessColorModel=DeviceRGB \
              -dPDFACompatibilityPolicy=1
This allows to specify custom Ghostscript command line options that are used when creating PDF/A documents (eqpcl -pp option).

gs.print.opt = 
This allows to specify custom Ghostscript command line options that are used when passing document to Ghostscript (eqpcl -g option).

gs.fontpath = 
This allows to specify custom Ghostscript font path. It is equivalent to setting the GS_FONTPATH environment variable. Please refer to the Ghostscript documentation for details.

include = 
This allows to specify a list custom postscript files that are included in the intermediate PostScript result. A comma separated list of files may be specified, a file extension of ".ps" is implied. Postscript files must be located in the location specified by ps.include config item (by default the eqpcl/ps directory).

ps.pdfa_def = 
This may be used to specify a prefix file when creating PDF/A output. If specified, it replaces the builtin PDF/A setup.

Section [default]

This section specifies the PCL defaults.
paper.source = 1
paper.source specifies the default paper tray. If a virtual tray is configured for this paper source then the defined overlay is applied to each page.
paper.size = 26
This specifies the default PCL paper size. The following values are recognized:
  1 = EXECUTIVE
  2 = LETTER
  3 = LEGAL
  6 = LEDGER
 26 = ISO A4
 27 = ISO A3
The default is 26 (A4)
symset = 4U
symset specifies the default symbol set. The following values are recognized.
  8U = HP Roman-8
  4U = HP Roman-9 (HP Roman8 with EUR sign)
  9U = CP1252
 10U = CP437
 12U = CP850
 19U = CP1252
  0N = Latin 1 (ISO-8859-1, subset of cp1252)
  2N = Latin 2 (ISO 8859-2)
  3N = Latin 3 (ISO 8859-3)
  4N = Latin 4 (ISO 8859-4)
  5N = Latin 5 (ISO 8859-5)
  9N = Latin 9 (ISO-8859-15)
 18N = Unicode (implies UTF-8 encoding)
The default is 4U (HP Roman9)
eolterm = 0
eolterm specifies the default for the PCL CR/LF handling. The following values are recognized:
 0 - CR = CR, LF = LF, FF = FF
 1 - CR = CR+LF, LF = LF, FF = FF
 2 - CR = CR, LF = CR+LF, FF = CR+FF
 3 - CR = CR+LF, LF = CR+LF, FF = CR+FF
The default is 0. A value of 2 would be used to print UNIX text files.

Section [tfN]

The tf sections are used to specify a mapping of PCL typefaces to PostScript fonts. A separate section is defined for each typeface.
[tfN]
width = font height/width ratio (percent)
#b#s = font name
  • The section name [tfN] identfies the PCL typeface. It consists of the literal "tf" and a numeric value N that specifies the PCL typeface id. For example, [tf4102] specifies the PCL typeface 4102 (LetterGothic).

  • width specifies the font width/hight ratio (in percent). This is used to scale monotype fonts. The default is 60, indicating the width is 60% of the height.

  • The other entries are used to map stroke and style values to a specific Postscript font name.
    #b#s = font name
    Where # specifies the stroke and style value and font name specifies the name of the PostScript font.
Please note the default font replacement mechanism applies if a font typeface is not mapped (including the exact stroke and style values).

The example below maps the PCL 4102 typeface id to the LetterGothic PostScript font.

[tf4102]
width = 54
0b0s = LetterGothic
1b0s = LetterGothic
3b0s = LetterGothic-Bold
0b1s = LetterGothic-Italic

Section [barcode]

This section is used to define the mapping of barcode and font id. Please refer to the section barcode support for details.

Section [trayN]

The Tray sections are used to define virtual trays. Please refer to the section virtual tray for details.


Limitations

The eqpcl utility implements a commonly used subset of the PCL functionality. Any unsupported functions are silently ignored.

The following PCL functionality is not supported:

  • User defined fonts
  • User defined symbol sets
  • User defined patterns
  • PCL area fill with patterns
  • HP GL/2
  • Raster graphics (other than PCL area fill)
The following fonts are currently supported:
  • Times-Roman
  • Courier
  • Helvetica
  • Symbol
This follows the default PS/PDF font list. Addional fonts may be mapped in the configuration.

The following symbol sets are supported:

  • 8U = HP Roman-8
  • 4U = HP Roman-9 (HP Roman8 with EUR sign)
  • 9U = CP1252
  • 10U = CP437
  • 12U = CP850
  • 19U = CP1252
  • 0N = Latin-1 (ISO-8859-1, subset of cp1252)
  • 2N = Latin2 (ISO 8859-2)
  • 3N = Latin3 (ISO 8859-3)
  • 4N = Latin4 (ISO 8859-4)
  • 5N = Latin5 (ISO 8859-5)
  • 9N = Latin9 (ISO-8859-15)
  • 18N = Unicode (implies UTF-8 encoding)
  • 5M = PS math symbol
  • 19M = Symbol
  • 14L = ZAPF DINGBATS
  • 0B = Line draw
  • 0L = Line draw
Commonly used PCL fonts are mapped as below:
Type face ID Mapped to...

0 (Line Printer)Courier
1Courier
2Courier
3Courier
4Helvetica
5Times-Roman
6Courier
4101 (CG Times)Times-Roman
25093 Times)Times-Roman
4148 (CG Univers)Helvetica
16602 (Arial)Helvetica
24580 (Helvetica)Helvetica
4099 (Courier)Courier
24579 (Courier PS)Courier
Any unrecognized proportial fonts are mapped to Times-Roman, fixed space fonts are mapped to Courier.

The eqpcl utility does does not read the font metrics and consequently can't use the actual character width of proportial spaced fonts.


Virtual Trays

The eqpcl utility provides a virtual tray that may be configured in the config file. A tray config may specify eps include files along with position and scaling options.

This is intended to ease the creation of custom forms. Instead of converting a custom form or logo into PCL format you may specify one or more EPS files (single page PS files _may_ work) to be used as overlay when the tray is used as a media source. An EPS file is a special postscript format that can only hold a single page.

[trayN]
# eps.file = path to include file (absolute path)
# xofs = move object x position (in decipoints, from left)
# yofs = move object y position (in decipoints, from bottom)
# scale = scale factor (in percent)
# align = align to paper edge (0=tl, 1=tr, 2=bl, 3=br, 4=orig)
# onpage = apply eps overlay on page (#|>#|!#|even|odd)
# multiple objects are allowed, each starting with eps.file
  • The section name [trayN] identfies the tray. It consists of the word "tray" and a numeric value N that specifies the tray number in the PCL command. For example, [tray1] specifies the tray number one.

  • eps.file designates the absolute path to an EPS file that is used to overlay the page. Multiple overlays are supported, each starting with eps.file. On the Windows platform a slash is used instead of a backslash.

  • scale may be used to specify a percentage by which the EPS file is scaled. If not present, the original size is used. A value of 50 scales the EPS file to 50%.

  • align may be used to specifiy the alignment of the EPS content, relative to the paper edges. The following values are supported:
    • 0 = top/left
    • 1 = top/right
    • 2 = bottom/left
    • 3 = bottom/right
    • 4 = Use the position as specified in the EPS bounding box (relative to the Postscript reference point, the bottom left).
    The default is 0 which positions a EPS file releative to the top/left paper edge. This has no effect if the EPS file does not specify a bounding box.

  • xofs and yofs may be used to specify an offset of the placement of the EPS file content. The EPS file content is positioned to a paper edge, based on the information in the EPS bounding box. Any position specified in the bounding box is ignored. The xofs and yofs allow to move the object accordingly, relative to the original position. The value is denoted in decipoints, that is 1/720 inch (or 1/10 point, ~0.0353 mm). An offset of 1000 would indicate 1.38 inch or 35.28 mm.

  • onpage may be used to apply the eps overlay on specific pages. The following values are supported:
    • page number (onpage = 1)
    • not on page number (onpage = !1)
    • page number larger than (onpage > 1)
    • even or odd page number (onpage = even)

To create an EPS file, save or export your image or document as EPS file. A single page Postscript file may work as well (but is not supported as there could be side effects). On Linux or HP-UX the ImageMagick conversion utility or the netpbm utilities may be used to convert a variety of image formats to an eps file. For example:

giftopnm sample.gif | pnmtoeps > sample.eps
jpegtopnm sample.jpeg | pnmtoeps > sample.eps
convert sample.png sample.eps


Barcode Support

The eqpcl utility provides support for the Postscript barcode writer created by Terry Burton. When the barcode functionality is enabled in the configuration, the barcode code is included in the PS output and eqpcl creates calls from the PCL data.

Please refer to http://bwipp.terryburton.co.uk/ for more information on supported barcode types ("Symbologies") and their options.

When enabled, the barcode is identified by a font id (type face) and mapped to a barcode encoding and option. The barcode height is automatically scaled according to the font height. The barcode encoding and any number of options may be specified, separated by a space. Any number of barcode definitions may be present.

To enable barcode support the following setting in the configuration is required:

[config]
barcode = 1
The following setting defines the font 9900 as code39 with the option "includetext". The font 9901 is defined as code93 with the additional options "includetext" and "includecheck".
[barcode]
9900 = code39 includetext
9901 = qrcode
Various barcode types are supported, including Code 39, Code 128, EAN and 2D codes such as QR-Code and Data Matrix.

The supported options depend on the barcode type. The includetext option is typically supported and results in printing the clear text beneath the barcode. The includecheck option is supported with some barcode types and causes an extra check digit to be generated.

The barcodes and options may be tried interactively on the web site http://www.terryburton.co.uk/barcodewriter/generator/


PDF/A Support

eqpcl implements the PDF/A-1b version of the PDF/A standard. The command line option -pp specifies to create a PDF/A compliant PDF output (instead of -p to create PDF output). Please note that PDF/A documents require more disk space as any resources (such as fonts) must be embedded in the PDF file.

PDF/A is a variant of PDF file format designated for for the archival of electronic documents. A PDF/A file is a PDF file but must follow additional requirements specified in the ISO 19005-1:2005 standard.

The config item [config] gs.pdfa.opt may be used to define GhostScript options used when creating PDF/A output files.

The config item [config] ps.pdfa_def may be used to specify a prefix file when creating PDF/A output. If specified, this replaces the builtin PDF/A setup. For an example, please refer to the lib/PDFA_def.ps file in your GhostScript installation.


Acknowledgements and Third Party Software

The Postscript code in ps/barcode.ps is provided under the following license:

Barcode Writer in Pure PostScript https://bwipp.terryburton.co.uk/

Copyright (c) 2004-2011 Terry Burton

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


Changes

Summary of changes since the B.08.30 release
  • Fixed PJL handling. PJL is now ignored w/o affecting the output.
  • Fixed HP-GL2 content in macro. Any HP-GL2 content is ignored.
  • Default unknown proportional fonts to Times Roman instead of Courier.
  • Handle negative sizes in PCL Area fill. This follows the LaserJet behaviour.
  • Use shade groups in PCL area fill instead of gray percentage.
  • Handle PCL ESC&a#G command (Duplex Page Side Selection).
    eqpcl assumes simplex behavior and ejects the current page.
  • Fix PCL cusor row offset to be consistent with top offset.
    The config:bcompat=1 config item may be used to retain the previous behaviour.
  • The ONPAGE tray option may be used to limit the page overlay to specific pages.
  • The command line option -C allows specifying config options from the command line.
    For example, -C paper.source=1 or -C tray1:onpage=even).
  • Improve internal resolution to improve font scaling and positioning.
  • Correctly reset HMI value on font property changes.
  • Return exit code if ghostscript fails.
  • The eqpcl version was changed to B.08.03.01
Enhancements included with the B.08.30 release
  • Added support for Unicode characters.
  • Added support for additional symbol sets.
Summary of changes since the B.08.20 release
  • Fixed wrong handling of PCL SI/SO commands. The eqpcl version was changed to B.08.20.07
  • Added support for scaling barcode.
  • Added PCL simple color support (RGB).
  • PDF/A support.


 
 
 
  Privacy | Webmaster | Terms of use | Impressum Revision: 2019-05-02  
  Copyright © 1995-2024 Marxmeier Software AG