Pcl2pdf ™

LaserJet PCL to PDF (Portable Document Format) Conversion
Version 6.0

Copyright © 1996-2007 G-Futures Limited t/as Visual Software
All rights reserved.

Visual Software
PO Box 399, DORKING RH5 4WX
United Kingdom
http://www.visual.co.uk

 

User Guide

 

Contents

Overview
New with Pcl2pdf V6.0
Platform Considerations
Running Pcl2pdf
Command Line Options

General
Text Rendering
PDF Document Information
PDF Data Compression
PDF Encryption, passwording, user access permissions
PCL Runtime forms merging
PDF Initial View
Forms Overlay Macro Pre-compilation
Miscellaneous

Error Return Codes
Temporary Files
Recommendations and Advice

Pcl2pdf Developer API Support
Pcl2pdf 32 bit Windows DLL
Pcl2pdf ActiveX OCX Control

 

Overview

Pcl2pdf converts LaserJet PCL print files to industry standard PDF (Portable Document Format) documents. These output documents are fully PDF compliant meaning that the PDF documents can be viewed and printed using the Adobe® Acrobat® range of products, versions 5.0, 6.0, 7.0 and later. Adobe, the Adobe logo, Acrobat, the Acrobat logo, are trademarks of Adobe Systems Incorporated. PDF documents can be fully searched and indexed using 3rd party products. Pcl2pdf supports the conversion of most PCL4 (LaserJet II), PCL5 (LaserJet III) and PCL5e (LaserJet 4/5) print files.

There are several implementations of Pcl2pdf for different operating systems including command line, interactive and component based:-

For the rest of this User Guide, unless otherwise stated, we'll refer to the Pcl2pdf executable simply as PCL2PDF.

 

New with Pcl2pdf V6.0

128 bit encryption is used in many products, including PDF and web browsers, and is now considered to be the minimum acceptable level of encryption security required for serious, professional use. For PDF documents 128 bit encryption also provides more document related options with regard to permitting or disallowing certain form field fill-in and document content extraction operations. More power and control for the author to specify.

Use the new Pcl2pdf V6.0 -EF:X switch to specify the maximum level of restriction

For print files that do not use any PCL page size commands Pcl2pdf V6.0 can generate custom PDF page sizes using paper size values defined by the -CPW:# and -CPH:# switches. This new functionality is enabled by the -CUSTOM switch. Custom page sizes are useful for documents representing cheque or bank statements

Previously new with Pcl2pdf V5.5

Pcl2pdf can apply settings to the output PDF document to control the initial appearance of the document in Adobe® Acrobat®. Such settings include hiding the menu, tool bar, scrolls bars, navigation controls, resizing the windows, displaying pages in columns, hiding or showing document outlines or thumbnails. Some options are mutually exclusive and not intended for use together. Ultimately their usage is dependent on the viewer's ability to implement them. There will be implementation differences between full and Reader® versions of Adobe® Acrobat® as well as documents embedded within browser windows

Pcl2pdf can now pre-compile PCL forms overlay macros at runtime into PDF "XObjects". For some PCL print files of the traditional form plus data report format this may provide significant conversion performance increases and reduction in output PDF file sizes. Such types of PCL print files typically include the background form once as a PCL macro and call it to be printed on each subsequent page. Up until V5.0 Pcl2pdf was forced to render the form on every page of the PDF document output. Now Pcl2pdf can often generate a single PDF XObject for the form and then call it to be rendered by the viewer on each page of the output

Temporary file usage has been significantly reduced during conversion increasing overall performance and also reliability

The former -R:# "RAM" buffer switch has been removed as the functionality provided has been replaced

The conversion performance for long PCL print files has been significantly improved. This should be noticeable on files of more than a few '000 pages.

PCL forms overlay macro pre-compilation implemented offering significant conversion performance increases and reduction in output PDF file sizes

Internal memory leak fixed reducing and stabilising memory footprint on Windows servers. Resource usage reduced also.

Non-overlapped, synchronous processing added to the Pcl2pdf 32 bit Windows DLL and ActiveX OCX components providing additional stability for web server based installations

Generally the Pcl2pdf 32 bit Windows DLL and ActiveX OCX components are not thread safe and so not recommended for use in multiple instance environments without careful implementation. The DLL itself is not multithreaded. A lock is now available though with the DLL to ensure no overlapped processing when conditions make this necessary, for example in web server based installations

This lock is implemented by way of a Windows "Mutex". This can force synchronous access to the PCL to PDF conversion routine. When enabled the DLL will wait a specified number of seconds if access is blocked (the convertor is already busy) returning codes 5 or 6 if access to the conversion routine cannot then be obtained. It is understood that the mutex will synchronise access across processes and threads, not just across threads within a single process

Note that by default the Pcl2pdf 32 bit Windows DLL and ActiveX OCX components will continue to function the same way as with Pcl2pdf V5.0; using no mutex or timeout

The Pcl2pdf ActiveX OCX control calls down to the DLL and a method is provided to enable this functionality. To enable the mutex you must additionally call the method UseMutexWithTimeout passing the timeout value (in milliseconds). This value corresponds to that used by the Windows WaitForSingleObject function. Calling the OCX UseMutexWithTimeout function enables the use of the mutex. Once called you cannot disable use of the mutex without instantiating the Pcl2pdf object again. Calling the method ResetDefaults subsequently will not affect it either. An example Visual Basic usage is:-

Dim oPCl2PDF As Object
oPCl2PDF = CreateObject("PCL2PDFDEVLIB.Pcl2pdfDevLibCtrl.1")
oPCl2PDF.UseMutexWithTimeout(5000) ' 5 seconds timeout
Err = oPCl2PDF.ConvertPcl2Pdf(InPCL,outPDF)

If the Pcl2pdf mutex times out or fails ConvertPcl2Pdf will return 5 or 6, normally 5. You can check this return value from your application and decide what action to take

Information is provided in terms of pages converted per minute based on the elapsed clock and cpu time

 

Platform Considerations

Large print file conversions can be memory and disk intensive. The Unix versions of Pcl2pdf are built with this in mind and are capable of converting files of many 000's of pages. Also note the command line switch -LT:2 which can be useful for converting Unix print files that use just linefeeds <0A> for line endings.

The Pcl2pdf V4 DOS 16 bit convertor, PCL2PDF.EXE, is no longer available or supported due to 640KB memory restrictions.

 

Running Pcl2pdf

Pcl2pdf is normally run from the command line prompt passing the names of the input PCL and output PDF filenames as parameters. For example:-

C> PCL2PDF TEST.PCL TEST.PDF

This is the standard way of running the command line versions of Pcl2pdf.

On some Unix systems you may need to use ./PCL2PDF to run Pcl2pdf from the current directory due to path considerations.

 

Command Line Options

The full command line usage and switches are shown below. These should be self-explanatory for normal use of the program. Again substitute the appropriate executable filename (PCL2PDF32.EXE, aixpcl2pdf etc.) for PCL2PDF shown here.

Usage: PCL2PDF [PclFilename] [PdfFilename]
[-PAGES] [-P] [-L] [-A3] [-A4] [-LEGAL] [-LETTER]
[-CUSTOM] [-CPW:#] [-CPH:#] [-PDF:"..."] [-LOG]
[-@:"..."] [-BM:#] [-LT:#] [-M:#] [-RA] [-RL:#] [-RU:#]
[-CSIZE] [-CSPEED] [-FLAT] [-MM] [-NOPRE] [-S]
[-SC:#] [-DIA:"..."] [-DIC:"..."] [-DIK:"..."]
[-DIS:"..."] [-DIT:"..."] [-T:"..."] [-NOWIN] [-NOUNI]
[-EO:"..."] [-EU:"..."] [-EF:"PMCAFEDLX"] [-EB:40]
[-LOAD:"..."] [-F:#] [-FC:#] [-FR:#]
[-IV:#] [-FX:#] [-TIME]

PclFilename

The input LaserJet PCL print filename to convert from.

PdfFilename

The output PDF (Portable Document Format) filename to convert to.

The options and switches are not listed alphabetically here, rather they are in approximate logical groupings. Use a leading '-' except on OpenVMS where '/' must be used instead. The switches are case-insensitive, that is you can use uppercase, lowercase or a mixture of each.

Note on Quotes:-

Some switches can take text values or arguments, for example -DIA to specify the PDF document author setting. If the value includes spaces or non-alphabetic characters enclose the whole value within quote marks:-

C> PCL2PDF test.pcl test.pdf -dia:"Joe Bloggs"

Make sure there are no spaces between the colon ':' and the first quote mark. If the switch value is a simple word you can leave out the quote marks:-

C> PCL2PDF test.pcl test.pdf -dia:John

On operating systems that support long filenames, such as Windows, you can enclose filenames that include spaces with double quotes:-

C> PCL2PDF "d:\my applications\visual\my long file.pcl" "e:\my documents\pdf\my long document.pdf"

 

General Options    
  -PAGES Normally the program shows no indication of its progress whilst processing through a LaserJet PCL print file. Use this switch to show each page end as it is reached. This option is most useful for large PCL files which may take some time to process, for example:-

C> PCL2PDF test.pcl test.pdf -pages
  -P The program defaults to assuming a "front panel" condition of portrait orientation. Of course it will react correctly to any PCL page orientation commands it finds in the PCL print file. Use this switch to set the default orientation to portrait for those files which don't explicitly set it, for example:-

C> PCL2PDF test.pcl test.pdf -p
  -L The program defaults to assuming a "front panel" condition of portrait orientation. Of course it will react correctly to any PCL page orientation commands it finds in the PCL print file. Use this switch to set the default orientation to landscape for those files which don't explicitly set it.
  -A3 The program defaults to assuming a "front panel" condition of A4 paper size. Of course it will react correctly to any PCL page size commands it finds in the PCL print file. Use this switch to set the default page size to A3 (420 x 297 mm) for those files which don't explicitly set it, for example:-

C> PCL2PDF test.pcl test.pdf -a3
  -A4 The program defaults to assuming a "front panel" condition of A4 (297 x 210 mm) paper size. Of course it will react correctly to any PCL page size commands it finds in the PCL print file.
  -LEGAL The program defaults to assuming a "front panel" condition of A4 paper size. Of course it will react correctly to any PCL page size commands it finds in the PCL print file. Use this switch to set the default page size to Legal (14 x 8.5 inches) for those files which don't explicitly set it.
  -LETTER The program defaults to assuming a "front panel" condition of A4 paper size. Of course it will react correctly to any PCL page size commands it finds in the PCL print file. Use this switch to set the default page size to US Letter (11 x 8.5 inches) for those files which don't explicitly set it.
  -CUSTOM

New with Pcl2pdf V6.0

 The program defaults to assuming a "front panel" condition of A4 paper size. If the PCL print file does not include any PCL page size commands you can use this switch to specify a custom page size with the paper size values defined by the -CPW:# and -CPH:# switches. For example, to specify a custom page size of 6.5 inches wide by 8.25 inches high use:-

C> PCL2PDF test.pcl test.pdf -custom -cpw:6.5 -cph:8.25
  -CPW:#

New with Pcl2pdf V6.0

 Specifies the custom paper size width to use with the -CUSTOM page size switch, from 4 to 100 inches.
  -CPH:#

New with Pcl2pdf V6.0

 Specifies the custom paper size height to use with the -CUSTOM page size switch, from 4 to 100 inches.
  -@:"..." If several switches are used together the command line can become long or unwieldy. DOS, for example, imposes a maximum length for a command line. Use this switch to redirect input instead from a command file. A command file is a simple ASCII text file with one switch only on each line. Each switch must start with '-' or '/' as usual. Blank lines and lines not starting with a switch will be ignored. Here is a sample command file, cmd.txt:-

-pages
-letter
-p

You would specify it's use by using:-

C> PCL2PDF test.pcl test.pdf -@:cmd.txt

Do not put either the input PCL or output PDF filenames in the command file. Though it will work with current releases of PCL2PDF it may not be supported in the future. Nor should you further redirect input by way of a second command file specified in the first. Again, though it may work with current releases of PCL2PDF it may not be supported in the future. You can include additional switches on the command line though:-

$ PCL2PDF test.pcl test.pdf -log -@:"/usr/jim/cmd.txt" -s
  -M:# Specifies the maximum number of pages to process (PDF pages to produce). The default is to process the whole input PCL file. For example, to process the first 2 pages only use:-

C> PCL2PDF test.pcl test.pdf -m:2
  -S This switch puts the program into silent mode suppressing the display of any copyright or usage notes. This is most useful when the program is used in batch operation.
  -SC:# This option scales the PDF output on the page. Pass a scaling value as a percentage of the original size (100%). You can use values greater than 1 to increase the scale of a document. It can be useful sometimes when printing from Adobe® Acrobat® to reduce a document to fit within the (Windows) printer driver’s unprintable area. Scaling and reduction is performed around the centre of the document. For example, to reduce to 95% of the original size use:-

C> PCL2PDF test.pcl test.pdf -sc:0.95
  -TIME

New with Pcl2pdf V5.5

 This switch provides basic conversion timing information in terms of pages converted per minute based on the elapsed clock and cpu time. It is best used with the -PAGES switch also:-

C> PCL2PDF test.pcl test.pdf -pages -time
  -PDF:"..."

New with Pcl2pdf V6.0

 Previous versions of Pcl2pdf up to and including V5.5 generated PDF documents defined as version 1.2. Pcl2pdf V6.0 now defines the output PDF documents as version 1.4. Use this switch to specify a different PDF version to be written into the document output, for example version 1.3:-

C> PCL2PDF test.pcl test.pdf -pdf:1.3

In reality the PDF document file version makes no practical difference. It's just an indicator to Adobe® Acrobat® (or whatever PDF viewer is being used) as to the kind of object contents to expect. Adobe® Acrobat® readers all the way up to 7.0 can open and work with PDF documents of any version. Some third party readers and applications however expect a given PDF document file version so using this switch can be helpful.
Text Rendering Options    
  -LT:# This options corresponds to the PCL Line Termination escape sequence <esc>&k#G and can be useful for converting print files produced on Unix systems. Sometimes Unix files use just linefeeds <0A> for line endings. This can be noticed in PDF documents where the text appears to be on one line only, extending far off the page to the right. To have the program translate linefeeds <0A> to carriage-return linefeed pairs <0D><0A> use:-

C> PCL2PDF test.pcl test.pdf -lt:2
 

-MM

Be advised that this switch may become obsolete in future releases

 Older versions of the program used special, optional command line switches to specify control over the typefaces used in the output PDF documents. Two of these switches, -FM:# and -TT, have now been discontinued. The program should now optimally specify correct PDF typefaces to use for display and printing. Use this option instead to force Adobe® Acrobat® to display typefaces using only Adobe® Multiple Master typefaces.
  -RA By default Pcl2pdf will specify the use of Times, Arial and Courier New typefaces (in all variations) in the PDF output. These will be formatted and spaced out to match the original PCL typefaces. If you wish to see other characters and typefaces in detail then you must include HP LaserJet PCL "bitmapped" soft fonts in the print files you convert.

Specifies that all text from downloaded bitmapped PCL soft fonts will be rendered as bitmaps. This is equivalent to using the combination of switches -rl:20 -ru:10. Use this option to see which text in the print file comes from downloaded soft fonts and which comes from internal printer resident typefaces. In Adobe® Acrobat® you will be able to zoom in close on the bitmapped text to see the dot patterns. Note that using this option may dramatically increase the size of the output PDF documents.
  -RL:# Specifies the point size below which text from downloaded bitmapped PCL soft fonts will be rendered as bitmaps. The default is to bitmap text equal to or below 4 point. Text above this size will be printed using Adobe® Acrobat® resident typefaces. This option is useful to enable some downloadable fonts with poorly specified font headers to be displayed. For example, to specify 2 point or below use:-

C> PCL2PDF test.pcl test.pdf -rl:2
  -RU:# Specifies the point size above which text from downloaded bitmapped PCL soft fonts will be rendered as bitmaps. The default is to bitmap text equal to or above 36 point. Text below this size will be printed using Adobe® Acrobat® resident typefaces. This option is useful for displaying some logos (images) printed using downloadable soft fonts. For example, to specify 40 point or above use:-

C> PCL2PDF test.pcl test.pdf -ru:40
PDF Document Information Options    
  -DIA:"..." Use this option to specify the document author to be included in the PDF output. Normally the program will use a default author name. On PC and Unix systems be sure to enclose the title within single or double quotes to keep it separate from other command line switches. Note that the quote marks are not required or used with Developer Library versions of the program. If the command line gets long consider using the command file option -@:"..." above. An example usage is:-

C> PCL2PDF test.pcl test.pdf -dia:"Joe Bloggs"
  -DIC:"..." Use this option to specify the document creator to be included in the PDF output. Normally the program will leave this value unspecified. Note the comments above regarding quote marks and command line length. An example usage is:-

C> PCL2PDF test.pcl test.pdf -dic:"Report Generator/2000"
  -DIK:"..." Use this option to specify the document keywords to be included in the PDF output. Normally the program will leave this value unspecified. Note the comments above regarding quote marks and command line length. An example usage is:-

C> PCL2PDF test.pcl test.pdf -dik:"invoice, january, manufacturing"
  -DIS:"..." Use this option to specify the document subject to be included in the PDF output. Normally the program will leave this value unspecified. Note the comments above regarding quote marks and command line length. An example usage is:-

C> PCL2PDF test.pcl test.pdf -dis:"Sales summary for Q4 1999"
  -DIT:"..."

Be advised that the old -T:"..." switch may become obsolete in future releases

 Use this option to specify the document title to be included in the PDF output. Normally the program will produce a default title based on the input PCL filename. Note the comments above regarding quote marks and command line length. An example usage is:-

C> PCL2PDF test.pcl test.pdf -dit:"Quarterly report on South East Asia sales"
PDF Data Compression Options    
  -CSIZE The program uses Flate compression algorithms to dramatically compress the output PDF documents. This is the same algorithm as used by the PKZIP (R) data compression utilities. By default the program will use a standard level of compression as a compromise between conversion time and PDF file size. Use this option to specify the output PDF documents should be created compressed as small as possible:-

C> PCL2PDF test.pcl test.pdf -csize
  -CSPEED The program uses Flate compression algorithms to dramatically compress the output PDF documents. This is the same algorithm as used by the PKZIP (R) data compression utilities. By default the program will use a standard level of compression as a compromise between conversion time and PDF file size. Use this option to specify the output PDF documents should be created compressed but as fast as possible.
  -CNONE The program uses Flate compression algorithms to dramatically compress the output PDF documents. This is the same algorithm as used by the PKZIP (R) data compression utilities. By default the program will use a standard level of compression as a compromise between conversion time and PDF file size. Use this option to specify the output PDF documents should not be compressed. This can be useful for 3rd party applications that need to parse the PDF output for text retrieval.
PDF Encryption, passwording and user access permissions    
 

Enhanced with Pcl2pdf V6.0

Pcl2pdf can apply data encryption, passwords and permissions to PDF (Portable Document Format) documents created at runtime. Pcl2pdf V6.0 defaults to using the standard 128 bit security handler.

Options available include:-

  • Requiring a password to open a document
  • Requiring a password to change the security settings
  • Disallowing printing
  • Disallowing changing of the document
  • Disallowing selecting text or graphics
  • Disallowing adding or changing notes or form fields
  • Disallowing the fill-in of existing interactive form fields
  • Disallowing the extraction of text and graphics in support of accessibility
  • Disallowing the assembly of the document
  • Limiting printing to a low level representation of the appearance
  -EO:"..." Use this option to specify the owner password to restrict a user from altering the security settings from within Adobe® Acrobat®. On PC and Unix systems be sure to enclose the password within single or double quotes to keep it separate from other command line switches. Note that the quote marks are not required or used with Developer Library versions of the program. If the command line gets long consider using the command file option -@:"...". An example usage is:-

C> PCL2PDF test.pcl test.pdf -eo:"apple"

An owner password only restricts a user from altering the PDF security settings. You are only prompted for this password when using Adobe® Acrobat®'s File/Document Properties... menu option, Security tab and then Change Settings.

Pcl2pdf can set both a owner and user password. If a document has both types of passwords, it can be opened with either one, but the restricted features may only be changed with the owner password.

Choose passwords carefully. Passwords cannot normally be recovered from PDF documents. Though there are some specialised companies offering services to do this they do not guarantee success. PDF passwords are case-sensitive.
  -EU:"..." Use this option to specify the user password to enable a user to open the PDF document within Adobe® Acrobat®. On PC and Unix systems be sure to enclose the password within single or double quotes to keep it separate from other command line switches. Note that the quote marks are not required or used with Developer Library versions of the program. If the command line gets long consider using the command file option -@:"...". An example usage is:-

C> PCL2PDF test.pcl test.pdf -eu:"orange"

In some documentation Adobe® refers to the user password as the open password.
  -EB:"40"

New with Pcl2pdf V6.0

 By default Pcl2pdf V6.0 will use the standard 128 bit security handler. Use this option to lower the security setting to 40 bits for compatibility with Adobe® Acrobat® version 4 and older. An example usage is:-

C> PCL2PDF test.pcl test.pdf -eu:"orange" -eb:"40"
  -EF:"..."

Enhanced with Pcl2pdf V6.0

Specifies the permissions (restrictions) flags to be applied to the PDF document created. Combinations of the following can be used:-

P ("printing" - disallow printing, or restrict output quality depending on whether L is set)

M ("modify" - disallow changing of the document by operations other than those controlled by A, F and D)

C ("copy" - disallow selecting text or graphics by operations other than that controlled by E)

A ("add" - disallow adding or changing notes or form fields)

The following permission flags are not available for 40 bit encryption use:-

F ("fill-in" – disallow the fill-in of existing interactive form fields, including signature fields, with regard to A)

E ("extract" – disallow extraction of text and graphics in support of accessibility to users with disabilities or for other purposes)

D ("document" – disallow the assembly of the document (insert, rotate, or delete pages and create bookmarks or thumbnail images) with regard to M)

L ("low" – limit printing to a low level representation of the appearance, possibly of degraded quality, with regard to P)

Note: Use X alone to specify all of the above permission flags. Lower or uppercase is allowed.

Example usages are:-

C> PCL2PDF test.pcl test.pdf -ef:x

Applies all possible restrictions and options

C> PCL2PDF test.pcl test.pdf -ef:maf

Allows secure viewing of pre-filled PDF forms, restricting users to change the value of the fields. Fields also appear to be merged with the document

C> PCL2PDF test.pcl test.pdf -ef:med

Disallows modifying the document

C> PCL2PDF test.pcl test.pdf -ef:mafed

Locks down a PDF form with its values combining the two examples above. Users are not able to change the PDF document or the value of the form fields. Printing is allowed though

These options are usually best applied with passwords. The easiest way to check that the security features have been applied correctly is to view the security information in Adobe® Acrobat®. When the PDF document is open use the File/Document Properties... menu option, Security tab and then view the Security tab The security information for the document will be displayed.
PCL Runtime Forms Merging    
   

Pcl2pdf can load and merge in forms at runtime when converting LaserJet PCL print files to PDF. This provides the ability to simulate pre-printed stationary, letterheads, terms and conditions, add logos and watermarks and otherwise enhance plain report listings. PCL2PDF can preload resource files containing PCL forms overlay macros and downloaded soft fonts. Such macros can easily by created using Visual Software's Forms Electric printing utility.

There are more notes available at Pcl2pdf Runtime Forms Support

Options are available for a variety of forms control including:-

  • A single form on all pages
  • Alternate forms on odd and even pages
  • Cover page only form (letterhead?)
  • Cover and continuation page forms
  • Even/reverse page only form (terms and conditions?)
  • Other combinations as given below

By using a combination of switches a wide variety of forms combinations can be achieved. Here is a table showing how the different possible combinations will affect the first 6 pages of a PDF document:-

-F:# -FR:# -FC:# Page 1 2 3 4 5 6 Example use
- - - - - - - - - No runtime merging
a - - a a a a a a Single form on all pages
a b - a b a b a b Alternate forms on odd and even pages
a - c c a a a a a Cover and continuation page forms
a b c c b a b a b Cover page and odd/even continuation page forms
- b - - b - b - b Even/reverse page only form (terms and conditions?)
- b c c b - b - b Cover page and even/reverse continuation page forms
- - c c - - - - - Cover page only (letterhead?)

 
  -LOAD:# Specifies the LaserJet PCL preload file to use. This file is merged in first, before the main input PCL file, and can contain forms overlay macros and downloaded soft fonts. For example, to specify a preload file macros.pcl use:-

C> PCL2PDF test.pcl test.pdf -load:macros.pcl

Care must be taken to ensure that Pcl2pdf locates the preload file from the correct directory. If no directory is specified Pcl2pdf will look in the default current directory. This may not be the same as that where Pcl2pdf is installed. You can specify a directory name in the usual way:-

C> PCL2PDF test.pcl test.pdf -load:"c:\data\macros.pcl"

Take care when using pathnames that include spaces. On Windows/DOS systems you may need to use the short 8.3 equivalent pathname instead.
  -F:# Specifies the LaserJet PCL forms overlay macro to be merged on all pages at runtime. The value passed is the PCL macro id of the form, from 0 to 32767. For example, to specify macro id 1 use:-

C> PCL2PDF test.pcl test.pdf -load:macros.pcl -f:1
  -FR:# Specifies the LaserJet PCL forms overlay macro to be merged on even (reverse) pages at runtime. The value passed is the PCL macro id of the form, from 0 to 32767. For example, to specify macro id 1 use:-

C> PCL2PDF test.pcl test.pdf -load:macros.pcl -fr:1
  -FC:# Specifies the LaserJet PCL forms overlay macro to be merged on the cover (first) page at runtime. The value passed is the PCL macro id of the form, from 0 to 32767. For example, to specify macro id 1 use:-

C> PCL2PDF test.pcl test.pdf -load:macros.pcl -fc:1
PDF Initial View Settings    
  -IV:"..."

New with Pcl2pdf V5.5

 Specifies the initial view options (viewer preferences) to be applied to the PDF document created. Any of the following combinations can be used together:-

T (hide the Adobe® Acrobat® tool bar when the document is active)

M (hide the menu bar)

W (hide the document window's user interface elements (scroll bars, navigation controls)

F (resize the document's window to fit the size of the first displayed page)

C (position the document's window in the centre of the screen)

D (display the document's title in the window's title bar)

In addition, one of the following options can be specified to control the document's page layout:-

S (display one page at a time)

C (display the pages in one column)

L (display the pages in two columns, with odd-numbered columns on the left)

R (display the pages in two columns, with odd-numbered columns on the right)

In addition, one of the following options can be specified to control the document's page mode:-

N (neither document outline or thumbnail images visible)

O (document outline visible)

H (thumbnail images visible)

U (full-screen mode, with no menu bar, windows controls or any other window visible)

Lower or uppercase is allowed. Example usages are:-

C> PCL2PDF test.pcl test.pdf -iv:t

C> PCL2PDF test.pcl test.pdf -iv:tmw

C> PCL2PDF test.pcl test.pdf -iv:c

C> PCL2PDF test.pcl test.pdf -iv:u

C> PCL2PDF test.pcl test.pdf -iv:tmlh

These options determine the initial view, page layout and page mode of the PDF document when opened in Adobe® Acrobat®. Some options are mutually exclusive and not intended for use together. Ultimately their usage is dependent on the viewer's ability to implement them.
Forms Overlay Macro Pre-compilation    
  -FX:"..."

New with Pcl2pdf V5.5

 PCL2PDF can now pre-compile PCL forms overlay macros at runtime into PDF "XObjects". For some PCL print files of the traditional form plus data report format this may provide significant conversion performance increases and reduction in output PDF file sizes. Such types of PCL print files typically include the background form once as a PCL macro and call it to be printed on each subsequent page. Up until V5.0 PCL2PDF was forced to render the form on every page of the PDF document output. Now PCL2PDF V5.5 can often generate a single PDF "XObject" for the form and then call it to be rendered by the viewer on each page of the output.

PCL and PDF are not 100% compatible document languages however and so this technique is not always practical. This technique is best used by software developers and OEMs with intimate knowledge of the format of the PCL files they create. It is recommended that this process is only used with traditional PCL forms macros that correspond to photocopier transparencies in functionality.

Use the -FX:# command line switch to specify the ids of the macros to be pre-compiled, from 0 to 32767. For example:-

C> PCL2PDF test.pcl test.pdf -fx:1

C> PCL2PDF test.pcl test.pdf -fx:0 -fx:1 -fx:2

The second command line pre-compiles the 3 form macros with ids 1, 2 and 3. Up to 6 macro ids can be specified this way. Pcl2pdf will use "just in time" compilation to generate PDF Xobjects once only the first time the macros are called. The XObjects will then be called using PDF "Do" commands.

This technique is an optimisation and may under some circumstances not generate 100% faithful forms overlay output. Should problems be met the first test should be to generate the PDF output without using any -FX:# switches. Some PCL macros sometimes contain codes that alter the general state of a document, for example font downloading, page setup, resolution and so on. These may not translate well into static PDF XObjects. Do not use this technique with small macros that just enclose frequently used PCL codes.

We advise that you test carefully and only use this technique with those forms macros that render faithfully.
Miscellaneous Options    
  -BM:# Specifies the point size of the default bottom margin to use. There are 72 points to an inch. The default is a bottom margin of 35 points. This option is useful should the program mistakenly split a page into two across a page boundary for print files that don't use form feeds <0C> as page ends. You can use positive or negative values. Negative values will extend the page downwards. For example, to specify a bottom margin of 20.5 points use:-

C> PCL2PDF test.pcl test.pdf -bm:20.5
  -R:# This switch is now obsolete as the functionality provided has been replaced
  -LOG Redirects error messages to a PCL2PDF.LOG disk file instead of the default stderr. This file will be created in the current working directory at the time the program is run.
  -FLAT This option is only available for OpenPDF on HP3000/MPE systems. If the input file is a MPE ASCII file use this option to setup special file mode processing. As a side effect this option also sets the line termination to -LT:2.
  -NOPRE PDF, being based on PostScript, is essentially an opaque document format. This means that many PDF objects will always obscure other objects placed underneath. When converting PCL print files this can sometimes be problematical. In general, grey shading used in PCL files is transparent and will show through any text printed below. This is often intentional and desirable. To cater for this the program will re-order any grey shaded areas found to be displayed first, before other objects on the page. For the vast majority of print files this process works correctly and as intended.

There are some types of PCL files where it is intended that grey shading should mask out or obscure text beneath. (A delivery note may not want to show items prices.) If you meet conversion problems like this try using this switch to disable the program's re-ordering process.
  -NOWIN

Be advised that this switch may become obsolete in future releases

 The program is usually able to detect and correctly handle soft fonts downloaded by the Windows LaserJet printer drivers. Some of these drivers, however, do not always produce fonts correctly formatted and fully conforming to the PCL specifications. If you find that some text in the output PDF files looks like "Egyptian hieroglyphics" then using this switch may help to make the text readable. Also, try using the -RA switch above.
  -NOUNI

Be advised that this switch may become obsolete in future releases

 In addition to the -NOWIN switch this option can also be used to help the program identify fonts downloaded by the Windows Unidriver printer driver. This and the -NOWIN option should not be required in normal use.
  -I2 By default Pcl2pdf will attempt to parse interpret HP-GL/2 vector graphics commands found within the PCL file being processed. Use this option to disable or turn off HP-GL/2 processing should you experience any problems or unwanted side effects.

 

Error Return Codes

The program returns a standard DOS or Unix error code to indicate success or failure:-

Code Interpretation
0 Success
1 Cannot open input PCL print file
2 Cannot create output PDF file
3 Reserved
4 Windows DLL security error
5 Windows DLL mutex or timeout error
6 Windows DLL mutex or timeout error

 

Temporary Files

During processing the program reads and writes temporary files. These are typically named PDF*, BIN* or MAC*. The program first checks to see if an environment variable TMP has been set. If so it will create its temporary files in the directory specified by this variable. If this is not set then the program tries using the environment variable PDFTMP (documentation updated 29 January 2007). Last, failing the first two cases, the program will use the current working directory (not necessarily the program’s installation directory) for its temporary files. Both read and write access will be required for the temporary directory used.

 

Recommendations and Advice

The following are some general recommendations and advice for Pcl2pdf, in no particular order:-

The combination of document access permissions available with PDF 128 bit encryption is surprisingly complex and it can be confusing for users to work with them. You will find that experimenting with different combinations of the Pcl2pdf -EF:# flags may be required to produce the results you need. Use the new Pcl2pdf V6.0 -EF:X switch to specify the maximum level of restriction.

For definitive reading the Adobe PDF Reference, Fifth Edition, Version 1.6 is available at http://partners.adobe.com/public/developer/pdf/index_reference.html

By default Pcl2pdf will specify the use of Times, Arial and Courier New typefaces (in all variations) in the PDF output. These will be formatted and spaced out to match the original PCL typefaces. If you wish to see other characters and typefaces in detail then you must include HP LaserJet PCL "bitmapped" soft fonts in the print files you convert. Then, by using some of the -RA style switches Pcl2pdf can usually output these characters and typefaces as PDF raster graphics.

Further advice on configuring Windows HP LaserJet PCL printer drivers for use with Pcl2pdf is available.

 

Pcl2pdf Developer API Support

Pcl2pdf offers a 32 bit Windows DLL and an ActiveX OCX control for use with Microsoft Visual Studio .NET and other modern application development environments. These components can also be used with web based Active Server Pages (ASP) applications on Microsoft Internet Information Server. The 32 bit Windows DLL is named pcl2pdf32.dll and the ActiveX OCX control pcl2pdfdevlib.ocx.

pcl2pdfdevlib.ocx calls down to pcl2pdf32.dll to make the PCL to PDF conversions and so requires this DLL to be already installed. Which component of the Pcl2pdf Developer API you use depends on the applications you are developing and the development environment and language you prefer to work with.

 

Pcl2pdf 32 bit Windows DLL

The Pcl2pdf 32 bit Windows DLL component is named pcl2pdf32.dll and is the component that performs the PCL to PDF conversions. This component is suitable for use with 32 bit Windows C, C++, Delphi and Visual Basic applications. pcl2pdf32.dll exports four functions - GetPcl2PdfVersion, ConvertPcl2Pdf, ConvertPcl2PdfNt and SetMutexTimeout.

Formal C++ declarations for these functions are:-

extern "C" void __stdcall GetPcl2PdfVersion(char *pStr);

extern "C" int __stdcall ConvertPcl2Pdf(int argc,char *argv[ ],HWND hWnd,UINT Message);

extern "C" int __stdcall ConvertPcl2PdfNt(char *InPclFilename,char *OutPdfFilename,char *par1,char *par2,char *par3,char *par4);

extern "C" void __stdcall SetMutexTimeout(DWORD dwMilliseconds); // New with Pcl2pdf V5.5

 

GetPcl2PdfVersion returns a null ('/0') terminated C string containing date and version number information for the converter. This can be used to display version information within your own application. This function does not return any values.

ConvertPcl2Pdf converts a LaserJet PCL print file to PDF format. It uses the same parameters as any standard C main() function. argc is the number of parameters passed and argv is a pointer to an array of strings, argc in number. To see details of the parameters that can be passed in refer to the main Pcl2pdf User Guide documentation for the parameters used by the command line version of Pcl2pdf. In the PC command line version of Pcl2pdf main() simply calls an internal function PCL2PDF_ProcessPcl2pdf as below. (This function is not directly exported).

int main(int argc,char *argv[ ])
{
return (int) PCL2PDF_ProcessPcl2Pdf(argc,argv);
}

ConvertPcl2Pdf works in the same way:-

int __declspec(dllexport) __stdcall ConvertPcl2Pdf(int argc,char *argv[ ],HWND hWnd,UINT Message)
{
// lines omitted here for clarity

return PCL2PDF_ProcessPcl2Pdf(argc,argv);
}

Additionally ConvertPcl2Pdf takes two parameters hWnd and Message. These can be used to have the component call back into your application at the completion of each page of processing. If you need further details on how to implement this feature please contact us for more information. To disable this feature simply pass NULL (0) for hWnd and 0 for Message.

ConvertPcl2PdfNt is provided to give an easy to use wrapper function that in turn calls ConvertPcl2Pdf. We recommend that this function be used in preference to the more complex ConvertPcl2Pdf function (unless page call backs are required).

The full C++ source code for this function is given below:-

#define ARGSIZE 32

int __declspec(dllexport) __stdcall ConvertPcl2PdfNt(char *InPclFilename,char *OutPdfFilename,char *par1,char *par2,char *par3,char *par4)
{
int SC;
char q1[16];
char *Args[ARGSIZE];
char buf1[512];
char buf2[512];
char buf3[512];
char buf4[512];

int c = 0;
Args[c++] = "Pcl2PdfNt"; // choose any name you like
Args[c++] = InPclFilename;
Args[c++] = OutPdfFilename;

// setup DLL security code
SC = 4102;
wsprintf(q1,"/Q:%i",SC);
Args[c++] = q1;

// add user specified parameters
if (par1 != (char*) NULL) strcpy(buf1,par1); else *buf1 = '\0';
if (par2 != (char*) NULL) strcpy(buf2,par2); else *buf2 = '\0';
if (par3 != (char*) NULL) strcpy(buf3,par3); else *buf3 = '\0';
if (par4 != (char*) NULL) strcpy(buf4,par4); else *buf4 = '\0';

ParseParameters(&c,buf1,Args);
ParseParameters(&c,buf2,Args);
ParseParameters(&c,buf3,Args);
ParseParameters(&c,buf4,Args);

return ConvertPcl2Pdf(c,Args,NULL,0);
}

ConvertPcl2PdfNt declares an array of string pointers and builds these up with the passed input PCL and output PDF filenames to use. In addition it passes in a security parameter "-Q:4102". Without this parameter the Pcl2pdf DLL will return error code 4 (security error) and not convert. The extra parameters par1..par4 can be used for additional command line switches, such as "-LETTER", "-P", "-SC:05" and so on. Again, for details of these refer to the main Pcl2pdf User Guide documentation.

The parameters par1..par4 can each take multiple values. Values that can include spaces or non-alphabetic characters should be enclosed with quote marks. For example "-SC:0.95 -DIA:'Joe Bloggs' -EU:'apple pie' -RA"

A typical function call to ConvertPcl2PdfNt() might be:-

int Err = ConvertPcl2PdfNt("test.pcl","test.pdf","-letter","-DIA:'Joe Bloggs'","-EU:'apple pie' -EF:P","");

This would instruct the component to create the PDF file test.pdf from the existing PCL print file test.pcl. ConvertPcl2PdfNt returns the same error codes as ConvertPcl2Pdf and PC command line version of Pcl2pdf. Successful conversion is indicated by a return code of 0. Non-zero return codes indicate errors, again refer to the Pcl2pdf User Guide documentation for further details.

To use GetPcl2PdfVersion() use:-

char Version[255];
GetPcl2PdfVersion(Version);
printf("The version is %s\n",Version);

Visual Basic declarations and example code are given here:-

Private Declare Sub GetPcl2PdfVersion Lib "pcl2pdf32.dll" (ByVal Version As String)
Private Declare Sub SetMutexTimeout Lib "pcl2pdf32.dll" (ByVal Milliseconds As Long)
Private Declare Function ConvertPcl2PdfNt Lib "pcl2pdf32.dll" (ByVal InPclFilename As String, ByVal OutPdfFilename As String, ByVal par1 As String, ByVal par2 As String, ByVal par3 As String, ByVal par4 As String) As Long

Private Sub Command1_Click()
Dim Version As String
Version = String(255, 0)
GetPcl2PdfVersion (Version)
MsgBox (Version)
End Sub

Private Sub Command2_Click()
Dim InPclFilename As String
Dim OutPdfFilename As String
Dim par1 As String
Dim par2 As String
Dim par3 As String
Dim par4 As String
Dim Err As Long

InPclFilename = "oldfile.pcl"
OutPdfFilename = "newfile.pdf"
par1 = ""
par2 = ""
par3 = ""
par4 = ""

Err = ConvertPcl2PdfNt(InPclFilename, OutPdfFilename, par1, par2, par3, par4)
MsgBox ("ConvertPcl2PdfNt returned " + Str$(Err))
End Sub

Visual FoxPro declarations:-

DECLARE GetPcl2PdfVersion IN pcl2pdf32.dll string @Version
DECLARE ConvertPcl2PdfNt IN pcl2pdf32.dll string @InFile, string @OutFile, string @parm1, string @parm2, string @parm3, string @parm4

lcVersion = space(255)
IF GetPcl2PdfVersion(lcVersion)
= MESSAGEBOX(lcVersion)
ENDIF

lcInFileName = "c:\temp\input.pcl"
lcOutFileName = "c:\temp\output.pdf"

IF !ConvertPcl2PdfNt(@lcInFileName,@lcOutFileName,"-LETTER","","","")
= MESSAGEBOX("Could Not Convert The File") ENDIF

New with Pcl2pdf V5.5

SetMutexTimeout implements support for non-overlapped, synchronous processing in the Pcl2pdf 32 bit Windows DLL and ActiveX OCX components. Generally the Pcl2pdf 32 bit Windows DLL and ActiveX OCX components are not thread safe and so not recommended for use in multiple instance environments without careful implementation. The DLL itself is not multithreaded. A lock is now available though with the DLL to ensure no overlapped processing when conditions make this necessary, for example in web server based installations

This lock is implemented by way of a Windows "Mutex". This can force synchronous access to the PCL to PDF conversion routine. When enabled the DLL will wait a specified number of seconds if access is blocked (the convertor is already busy) returning codes 5 or 6 if access to the conversion routine cannot then be obtained. It is understood that the mutex will synchronise access across processes and threads, not just across threads within a single process

Note that by default the Pcl2pdf 32 bit Windows DLL and ActiveX OCX components will continue to function the same way as with Pcl2pdf V5.0; using no mutex or timeout

The Pcl2pdf ActiveX OCX control calls down to the DLL and a method is provided to enable this functionality. To enable the mutex you must additionally call the method UseMutexWithTimeout passing the timeout value (in milliseconds). This value corresponds to that used by the Windows WaitForSingleObject function. Calling the OCX UseMutexWithTimeout function enables the use of the mutex. Once called you cannot disable use of the mutex without instantiating the Pcl2pdf object again. Calling the method ResetDefaults subsequently will not affect it either. An example Visual Basic usage is:-

Dim oPCl2PDF As Object
oPCl2PDF = CreateObject("PCL2PDFDEVLIB.Pcl2pdfDevLibCtrl.1")
oPCl2PDF.UseMutexWithTimeout(5000) ' 5 seconds timeout
Err = oPCl2PDF.ConvertPcl2Pdf(InPCL,outPDF)

If the Pcl2pdf mutex times out or fails ConvertPcl2Pdf will return 5 or 6, normally 5. You can check this return value from your application and decide what action to take.

 

Pcl2pdf ActiveX OCX Control

The Pcl2pdf ActiveX control component is named pcl2pdfdevlib.ocx. This component can be used with Visual Basic, Visual C++ and Delphi applications and also web based Active Server Pages (ASP) applications on Microsoft Internet Information Server.

Installation

pcl2pdfdevlib.ocx is a self-registering OCX as so can easily be installed using InstallShield and other industry standard installation systems. If you need to register the control manually then use regsvr32.exe, a Microsoft utility provided with Visual Studio and installed as standard with newer versions of Windows. If regsvr32.exe is not in the current path it may be found in the Windows or Windows System32 directories:-

C> regsvr32 pcl2pdfdevlib.ocx

The ActiveX OCX control is fully 32 bit and calls down to pcl2pdf32.dll to make the LaserJet PCL to PDF conversions. pcl2pdf32.dll is always required when using pcl2pdfdevlib.ocx and should be installed (located) in the same directory. They do not need to be placed in the Windows or Windows System32 special directories however.

 

The following methods, events and properties available with pcl2pdfdevlib.ocx:-

Methods

AboutBox
GetVersion
ResetDefaults
ConvertPcl2Pdf
StopProcessing
AddPrecompilationFormId New with Pcl2pdf V5.5
UseMutexWithTimeout New with Pcl2pdf V5.5

 Events

PageEnd

 Properties

Orientation
PageSize
CustomPaperWidth New with Pcl2pdf V6.0
CustomPaperHeight New with Pcl2pdf V6.0
BottomMargin
LineTermination
MaxPages
Logging
RamFileSize
RasterizeAll
RasterizeLower
RasterizeUpper
Compression
MultipleMaster
NoPre
ScaleFactor
DocInfoAuthor
DocInfoCreator
DocInfoKeywords
DocInfoSubject
DocInfoTitle
OwnerPassword
UserPassword
RC40 New with Pcl2pdf V6.0
Permissions Enhanced with Pcl2pdf V6.0
PreLoadFile
FormId
ReverseFormId
CoverFormId
HPGL2
NoWin
NoUni
Options
InitialView New with Pcl2pdf V5.5
PdfVersion New with Pcl2pdf V6.0

 

AboutBox Method

Displays the About box for the control

Syntax

object.AboutBox

The object placeholder represents an object expression that evaluates to an object in the Applies To list

Arguments

None

Remarks

This method display a dialog box containing copyright and version information. It should only be used with client side applications, do not use with server or web applications

Return Value

None

Visual Basic Example

Private Sub ShowAbout_Click()
Pcl2pdfDevLib1.AboutBox
End Sub

 

GetVersion Method

Returns version information for the Pcl2pdf 32 bit Windows DLL

Syntax

object.GetVersion

The object placeholder represents an object expression that evaluates to an object in the Applies To list

Arguments

None

Remarks

This method returns a string containing version information from pcl2pdf32.dll

Return Value

String

Visual Basic Example

Private Sub ShowVersion_Click()
Dim Version As String
Version = Pcl2pdfDevLib1.GetVersion
MsgBox "Pcl2pdf version is '" + Version + "'"
End Sub

Active Server Pages vbscript Example

<%
Dim p2p
Set p2p = Server.CreateObject("PCL2PDFDEVLIB.Pcl2pdfDevLibCtrl.1")

Dim Version
Version = p2p.GetVersion
Response.Write "<p>Pcl2pdf DLL version is '" + Version + "'</p>"

Set p2p = Nothing
%>

 

ResetDefaults Method

Resets the control's properties to their default values

Syntax

object.ResetDefaults

The object placeholder represents an object expression that evaluates to an object in the Applies To list

Arguments

None

Remarks

Once a property is set it remains in effect for use with the subsequent calls to the ConvertPcl2Pdf method. This method resets the control's properties to their default values

Return Value

None

Visual Basic Example

See ConvertPcl2pdf

 

ConvertPcl2Pdf Method

Converts an input LaserJet PCL print file to an output PDF document

Syntax

object.ConvertPcl2pdf InPclFilename, OutPdfFilename

The object placeholder represents an object expression that evaluates to an object in the Applies To list

Arguments

Parameter Data Type Setting
InPclFilename String The fully-qualified pathname of the input LaserJet PCL print file to convert
OutPdfFilename String The fully-qualified pathname of the output PDF document to create

Remarks

This method calls the ActiveX OCX control to convert the specified LaserJet PCL print file to a PDF document. Any control properties set are used to affect the conversion and resulting PDF output. PageEnd events are generated whenever this method completes processing a page from the input LaserJet PCL print file. Use the StopProcessing method to terminate processing prior to completion. Possible return values are listed in the Error Return Codes section of this User Guide.

Return Value

Long

Visual Basic Example

Private Sub ConvertPcl2pdf_Click()
Dim Err As Long

' optional properties provided here as examples only
Pcl2pdfDevLib1.ResetDefaults
Pcl2pdfDevLib1.Compression = "SPEED"
Pcl2pdfDevLib1.MultipleMaster = True
Pcl2pdfDevLib1.ScaleFactor = 0.95
Pcl2pdfDevLib1.DocInfoTitle = "Quarterly report on South East Asia sales"
Pcl2pdfDevLib1.Options = "-ra"

' the following method calls are provided here as a guide for developer use only
Pcl2pdfDevLib1.AddPrecompilationFormId(20) ' add macro ids 20 and 21 for pre-compilation
Pcl2pdfDevLib1.AddPrecompilationFormId(21)
Pcl2pdfDevLib1.UseMutexWithTimeout(5000) ' 5 seconds timeout

Err = Pcl2pdfDevLib1.ConvertPcl2pdf("c:\data\pcl\test.pcl", "c:\data\pcl\test.pdf")
MsgBox "ConvertPcl2pdf returned " + Str$(Err)
End Sub

Active Server Pages vbscript Example