Pcl2pdf V6.9 User Guide

Pcl2pdf ™

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

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

User Guide

Contents

Overview
New with Pcl2pdf V6.9
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 settings
PDF Print settings
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 8.0 through to Acrobat X 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 Windows XP, Vista, Windows 7 and Windows Server 2003, 2008 the 32 bit command line convertor is PCL2PDF32.EXE. As a command line application this can be used with batch files for unattended operations.
The Windows GUI user interface application is called Visual PDF. In this version many of the command line switches can be set using standard dialog based screens.
The Linux and Unix versions are all command line based and ideal for batch mode operation.
Windows 32 bit DLL and ActiveX OCX control components are available for developer use.
A version is available for HP3000/MPE, from Open Seas, called OpenPDF.
A version is available for AS/400, from RJS Software.
Versions are available also for OpenVMS and Tandem Guardian.

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

Introduced with Pcl2pdf V6.9

Support for user specified temporary file directory using -TEMP:"..." switch

Implemented new -IFF switch to suppress blank page generation on form feed when no data on page
Implemented 24-bit RGB PCL colour support, in conjunction with LBM Systems' AXIAR Imaging, with opacity and transparency and within macros
New -PC switch for print copies, -PS and -PE for print range start and end and -PM for PDF Print Settings
Implemented “IBM DOS” style line and box drawing character support
Implemented Euro character in HP 9N and 13U symbol sets
Implemented right and centre justified text printing using HP-GL/2 LO command
Implemented “white text” printing
Implemented PCL raster graphics “mode 5” adaptive compression
Implemented various PCL code fixes and enhancements
Improved PCL duplex paper handling support
Improved PCL “offset registration” support, including for 90 degree rotated portrait pages
Improved HP-GL/2 support
Developed using Microsoft Visual Studio 2010

Introduced with Pcl2pdf V6.0

Support for PDF 128 bit encryption

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

Support for custom page sizes using -CUSTOM -CPW:# and -CPH:# switches

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

Support for different PDF document file versions using -PDF:"..." switch

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. Some third party readers and applications expect a given PDF document file version so using this switch can be helpful
Continued code fixes relating to:-

Character spacing and kerning, top offset registration, unit of measure switching, shaded bitmapped soft fonts with PDF data compression and more

Introduced with Pcl2pdf V5.5

Support for PDF initial view settings using -IV:"..." switch

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

Support for the pre-compilation of PCL forms overlay macros using -FX:"..." switch

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

Significant power, performance and stability improvements

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

Support for piping in PCL print data from the stdin console added

Pcl2pdf can now accept PCL print data piped in from the stdin console. This can be particularly useful for Unix developers wishing to script the conversion process and avoid unnecessary temporary files. Example console command line usages are:-

C> type test.pcl | PCL2PDF con test.pdf -pages (Windows)

cat test.pcl | ./PCL2PDF con test.pdf -pages (Unix)

The pseudo filename "con" instructs Pcl2pdf to read the PCL print data from stdin instead of a disk based file. Note that Pcl2pdf cannot write the output PDF document data to stdout due to the highly structured and cross referenced nature of the PDF file format specification.

Support for non-overlapped, synchronous processing added to 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

Support for basic conversion timing information using -TIME switch

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

Basic support for the HP 11U PC-8 Danish/Norwegian, 19U Windows 3.1 Latin 1 symbol sets added

The formerly undocumented -RUF command line switch has been removed as the functionality provided has been replaced

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 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:# Specifies the custom paper size width to use with the -CUSTOM page size switch, from 4 to 100 inches.

-CPH:# 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 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:"..." 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

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" 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:"..."
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 older 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:"..." 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.

PDF Print Settings

-PM:"..." Specifies the print options to be applied when the print dialog is open for this PDF document. The following combinations can be used:-

N (the Adobe® Acrobat® Page Scaling option should be set to None to reflect no page scaling)

S (simplex, single sided printing)

H (duplex, flip on the short edge of the paper)

L (duplex, flip on the long edge of the paper)

T (select the paper tray for printing based on the PDF document page size. The Adobe® Acrobat® Choose paper source by PDF page size option should be checked. The PDF specification indicates this option has no effect on Mac OS systems, which do not provide the ability to pick the input tray by size)

Lower or uppercase is allowed. Example usages are:-

C> PCL2PDF test.pcl test.pdf -pm:n

C> PCL2PDF test.pcl test.pdf -pm:nl

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

Some options are mutually exclusive and not intended for use together. Ultimately their usage is dependent on the viewer's ability to implement them, the printer driver's capabilities and their support by the operating system. Duplex printing options may only be effective with PostScript compatible printers.

-PC:# Specifies the number of copies to be printed when the print dialog is open for this PDF document. Adobe® Acrobat® version 8 and later supported values are 2 through 5 and values outside this range are ignored. For example, to specify printing two copies use:-

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

-PS:# Specifies the starting page number used when the print dialog is open for this PDF document. Values from 1 through to be last page in the document can be used. The switch must be used together with the -PE:# switch to specify the end page number. For example, to specify printing pages 2 through 10 use:-

C> PCL2PDF test.pcl test.pdf -ps:2 -pe:10

-PE:# Specifies the ending page number used when the print dialog is open for this PDF document. Values from 1 through to be last page in the document can be used. The switch must be used together with the -PS:# switch to specify the starting page number. For example, to specify printing pages 1 through 5 use:-

C> PCL2PDF test.pcl test.pdf -ps:1 -pe:5

Forms Overlay Macro Pre-compilation

-FX:"..." 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.

-IFF Suppress any blank pages generated by <FF> form feeds if there is no data to be printed on the page.

-TEMP:# Specifies the directory to be used for temporary files created by Pcl2pdf. The directory must already exist with both read and write access. For example, to specify a temporary file directory C:\Users\Temp use:-

C> PCL2PDF test.pcl test.pdf -temp:C:\Users\Temp

To specify a temporary file directory /usr/joe/docs on a Unix system use:-

C> PCL2PDF test.pcl test.pdf -temp:/usr/joe/docs

Take care when using pathnames that include spaces. Double quotes may be used:

C> PCL2PDF test.pcl test.pdf -temp:"C:\Documents and Settings\Joe\Temp"

On older Windows/DOS systems you may need to use the short 8.3 equivalent pathname instead.

See the discussion on temporary files elsewhere in this guide.

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

7 Unsupported operating system platform

Temporary Files

During processing the program reads and writes temporary files. These are typically named PDF*, BIN* or MAC*. The program first checks whether a temporary file directory has been specified using the -TEMP:# command line switch. If yes, this directory is used, otherwise the program next checks to see if an environment variable TMP has been set. If yes 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. Last, failing all these 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:-

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.

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 Pcl2pdf -EF:X switch to specify the maximum level of restriction.

For definitive reading the Adobe PDF Reference, Sixth Edition, Version 1.7 is available at http://www.adobe.com/devnet/pdf

Where possible use PCL Rule commands for lines, boxes and shadings. Pcl2pdf supports this technique and full details are available in the HP PCL5 Technical Reference manual. For other graphics objects use bitmapped raster data.

If you go to HP's Solution Programs Portal at http://www.hpdevelopersolutions.com/ you can submit a business proposal to apply to join the HP Primary Solutions Partner program for LaserJets. Once accepted look under "SDK's and Information" for "LaserJet", "Printer Languages", "PCL 5", "PCL 5 Documents". The PCL 5 Printer Language Technical Reference Guide references Rule commands for drawing lines, boxes and shadings. Here's some examples from the HP documentation (replace <esc> with ASCII 27, the escape character):-

<esc>*p300x400Y<esc>*c900a1500b0P (draws a black square)

<esc>*p300x400Y<esc>*c900a1500b25g2P (draws a 25% gray shaded rectangle)

For lines just make the rectangles thin in one direction.
For grey fills use the <esc>*c#g2P syntax and specify the percentage fill (#=0-100). Pcl2pdf translates these percentage fills into pure, smooth PDF greyscales. These display very well in Acrobat and print evenly also.

Avoid using <esc>*c#g4P "user defined pattern fills" which lead to worse results in the PDF output. PCL user defined pattern fills are based on bitmapped patterns - dot images. Generally outputting patterns like these as PDF raster bitmapped fills produces documents with hard to view shaded areas. Adobe® Acrobat® unfortunately tries to optimise and smooth such pattern fills with poor results.

Pcl2pdf supports only a basic subset of colour PCL5C. The PCL output from drivers such as the Windows Color LaserJet printer driver is generally too complex for Pcl2pdf. Pcl2pdf can use the basic PCL5C <esc>*r3U RGB and <esc>*r-3U CMY colour models. For example basic colour commands such as <esc>*r3U<esc>*v1S to select colours from a fixed palette.

You can only use colour PCL5C commands in overlay macros provided that you do not use HP-GL/2 vector graphics also. This is due to firmware limitations in the HP Color LaserJet printers themselves. PCL5C has real problems using colour commands and HP-GL/2 graphics in overlay macros at the same time. Unfortunately most Windows Color LaserJet printer drivers output HP-GL/2 so it is very hard or impossible to use these drivers to create colour macros.

PCL and PDF are not 100% compatible document languages. There will inevitably be some typeface differences as PDF is based on the PostScript language using Type 1 fonts.

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.

Despite it's similar name PCL6 is as different to PCL5 as PostScript is. Hewlett-Packard invented PCL6 (formerly named PCL-XL) for additional compatibility when printing from Windows. Printers that support PCL6 also support PCL5/5e so you can use these drivers with confidence.

Pcl2pdf will default to using European A4 paper size unless it meets PCL commands in the print file to switch to other paper sizes. If a PCL print file does not specify a paper size for printing with you can use the Pcl2pdf -LETTER switch to change the default to US Letter 8.5x11" paper instead.

Some PCL print files simulate landscape printing by creating pages in portrait orientation with all the text printed rotated through 90 degrees. This can cause Pcl2pdf some problems. The best solution is to create a true landscape PCL print file.

Pcl2pdf will default to using the Roman-8 symbol set unless it meets PCL commands in the print file to switch to other symbol sets. Pcl2pdf supports most accented (alphanumeric) characters in the 8U Roman-8, 9U, 10U PC-8, 12U PC-850 and 1G ISO-21 symbol sets.

Pcl2pdf can create PDF documents with mixed paper sizes and orientations and this can be seen in the Adobe® Acrobat® on-screen document view. Unfortunately versions of Adobe® Acrobat® up to and including 4.0 are less than intelligent in this respect when it comes to printing. They will default to using the current printer driver settings for all pages and this cannot be overridden. Later versions of Adobe® Acrobat® are much improved in this respect and can use this information when printing, though it's hard to find. Go to "File" and "Print..." then enable the checkbox Choose Paper Source by PDF page size (with Adobe® Acrobat® 5.0 use the "Advanced..." button and then the Choose Output Tray by PDF page size checkbox).

Pcl2pdf has no way to influence or control PDF duplexing. Whilst Pcl2pdf does parse and interpret HP PCL duplexing commands it is not possible to embed printer control information like this into the PDF document output. Unfortunately the PDF technical specification does not allow for this. How your PDF document prints, with regard to duplexing, depends entirely on Adobe® Acrobat® and your Windows printer driver.

All versions of Pcl2pdf convert a single PCL print file to a single PDF document. The files themselves can be many 000's of pages long. To convert more files you need to run Pcl2pdf again for each one. You could use a "DOS" style batch file or some other scripting front-end to control this, perhaps a Visual Basic application. A simple example "DOS" batch might be:-

md pdf
for %%a in (*.pcl) do pcl2pdf32 %%a pdf\%%a
cd pdf
ren *.pcl *.pdf
cd ..

Alternatively consider using the Pcl2pdf Developer APIs which can be programmed and scripted by other applications.

Pcl2pdf has no facilities or options to automatically monitor input directories either.

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);

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

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
UseMutexWithTimeout
Events

PageEnd
Properties

Orientation
PageSize
CustomPaperWidth
CustomPaperHeight
BottomMargin
LineTermination
MaxPages
Logging
RamFileSize
RasterizeAll
RasterizeLower
RasterizeUpper
Compression
MultipleMaster
NoPre
ScaleFactor
DocInfoAuthor
DocInfoCreator
DocInfoKeywords
DocInfoSubject
DocInfoTitle
OwnerPassword
UserPassword
RC40
Permissions
PreLoadFile
FormId
ReverseFormId
CoverFormId
HPGL2
NoWin
NoUni
Options
InitialView
PdfVersion

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

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

p2p.ResetDefaults
p2p.DocInfoTitle = "Quarterly report on South East Asia sales"

Dim Err
Dim Dir
Dir = "C:\Inetpub\Pcl2pdfDevLib\"
Err = p2p.ConvertPcl2pdf(Dir + "test.pcl", Dir + "test.pdf")
Response.Write "<p>ConvertPcl2pdf returned " + FormatNumber(Err,0) + "</p>"

Set p2p = Nothing
%>

Windows Scripting Host Example (save with .WSF file extension)

<Job id="Pcl2pdfWshExample">
<script language="VBScript">

Option Explicit

Dim Pcl2pdfDevLib1
Set Pcl2pdfDevLib1 = CreateObject("PCL2PDFDEVLIB.Pcl2pdfDevLibCtrl.1")

Pcl2pdfDevLib1.AboutBox

Dim Version
Version = Pcl2pdfDevLib1.GetVersion
MsgBox "Pcl2pdf version is '" + Version + "'"

' Pcl2pdfDevLib1.ResetDefaults
Pcl2pdfDevLib1.Compression = "SIZE"

Dim Err
Err = Pcl2pdfDevLib1.ConvertPcl2pdf("c:\data\pcl\test.pcl", "c:\data\pcl\test.pdf")
MsgBox "ConvertPcl2pdf returned " + FormatNumber(Err,0)

Set Pcl2pdfDevLib1 = Nothing

</Script>
</Job>

StopProcessing Method

Stops PCL to PDF processing during a call to the ConvertPcl2pdf method

Syntax

object.StopProcessing

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

Arguments

None

Remarks

This method can be called from a PageEnd event handler to terminate PCL to PDF processing by the ConvertPcl2pdf method prior to completion

Return Value

None

Visual Basic Example

See PageEnd

AddPrecompilationFormId Method

Adds a macro id to the list of those to be pre-compiled at runtime

Syntax

object.AddPrecompilationFormId FormId

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

Arguments

Parameter Data Type Setting

FormId Long The macro id to be added to the list for pre-compliation

Remarks

See the Forms Overlay Macro Pre-compilation section of this User Guide for full details

Return Value

None

Visual Basic Example

See ConvertPcl2pdf

UseMutexWithTimeout Method

Stops PCL to PDF processing during a call to the ConvertPcl2pdf method

Syntax

object.UseMutexWithTimeout dwMilliseconds

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

Arguments

Parameter Data Type Setting

dwMilliseconds Unsigned Long The timeout value in milliseconds

Remarks

See the SetMutexTimeout subsection of the Pcl2pdf 32 bit Windows DLL section of this User Guide for full details

Return Value

None

Visual Basic Example

See ConvertPcl2pdf

PageEnd Event

Generated whenever the ConvertPcl2pdf method completes processing a PCL page

Syntax

Private Sub object_PageEnd (CurPage, CharsRead)

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

Arguments

Parameter Data Type Setting

CurPage Long The page number of the PCL print file just converted

CharsRead Long The number of characters read in from the PCL print file

Remarks

The PageEnd event is generated whenever the ConvertPcl2pdf method completes processing a page from the input LaserJet PCL print file. With this version of the ActiveX OCX control for the last page in the PCL print file this event is generated twice. This is subject to change. CurPage will be 1 for the first page in the PCL print file. CharsRead does not include characters processed during calls to PCL macros.

Call the StopProcessing method during the PageEnd event to have the program stop processing as soon as possible

Visual Basic Example

Private Sub Pcl2pdfDevLib1_PageEnd(ByVal CurPage As Long, ByVal CharsRead As Long)
MsgBox "PageEnd: CurPage = " + Str$(CurPage) + " and CharsRead = " + Str$(CharsRead)
' uncomment call below to stop processing asap
' Pcl2pdfDevLib1.StopProcessing
End Sub

Orientation Property

Sets and returns the default "front panel" page orientation

Syntax

object.Orientation[ = value ]

The Orientation property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list

value A string value specifying the page orientation

Remarks

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. You can set value to either "P" or "L" (the default is "P"). This is equivalent to the Pcl2pdf command line switches -P and -L

Data Type

String

PageSize Property

Sets and returns the default "front panel" page size

Syntax

object.PageSize[ = value ]

The PageSize property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list

value A string value specifying the page size

Remarks

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. You can set value to "A3", "A4", "LETTER", "LEGAL" or "CUSTOM" (the default is "A4"). This is equivalent to the Pcl2pdf command line switches -A3, -A4, -LETTER, -LEGAL and -CUSTOM. For custom page sizes use the CustomPaperWidth and CustomPaperHeight properties also

Data Type

String

CustomPaperWidth Property

Sets and returns the custom paper width

Syntax

object.CustomPaperWidth[ = value ]

The CustomPaperWidth property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list

value A double value specifying the custom paper width

Remarks

Specifies the custom paper size width to use with the PageSize property set to "CUSTOM", valid from 4 to 100 inches. This is equivalent to the Pcl2pdf command line switch -CPW:#

Data Type

Double

CustomPaperHeight Property

Sets and returns the custom paper height

Syntax

object.CustomPaperHeight[ = value ]

The CustomPaperHeight property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list

value A double value specifying the custom paper height

Remarks

Specifies the custom paper size height to use with the PageSize property set to "CUSTOM", valid from 4 to 100 inches. This is equivalent to the Pcl2pdf command line switch -CPH:#

Data Type

Double

BottomMargin Property

Sets and returns the default bottom margin

Syntax

object.BottomMargin[ = value ]

The BottomMargin property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list

value A double value specifying the default bottom margin

Remarks

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 formfeeds <0C> as page ends. You can use positive or negative values. Negative values will extend the page downwards. This is equivalent to the Pcl2pdf command line switch -BM:#

Data Type

Double

LineTermination Property

Sets and returns the default line termination

Syntax

object.LineTermination[ = value ]

The LineTermination property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list

value A long value specifying the default line termination

Remarks

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 a value of 2. This is equivalent to the Pcl2pdf command line switch -LT:#

Data Type

Long

MaxPages Property

Sets and returns the maximum number of pages to process

Syntax

object.MaxPages[ = value ]

The MaxPages property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list

value A long value specifying the maximum number of pages

Remarks

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 use a value of 2. This is equivalent to the Pcl2pdf command line switch -M:#

Data Type

Long

Logging Property

Enables and disables message logging

Syntax

object.Logging[ = value ]

The Logging property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list

value A boolean value specifying whether message logging is enabled or disabled

Remarks

Outputs error messages to a PCL2PDF.LOG disk file. This file will be created in the current working directory at the time the program is run (or VB system directory when in development mode). By default this option is disabled. This property can be useful to help debug print file conversions. This is equivalent to the Pcl2pdf command line switch -LOG

Data Type

Boolean

RamFileSize Property

Sets and returns a value

Syntax

object.RamFileSize[ = value ]

The RamFileSize property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list

value A long value

Remarks

This switch is now obsolete as the functionality provided has been replaced

Data Type

Long

RasterizeAll Property

Enables and disables all soft font text rasterization

Syntax

object.RasterizeAll[ = value ]

The RasterizeAll property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list

value A boolean value specifying whether all soft font text rasterization is enabled or disabled

Remarks

Specifies that all text from downloaded bitmapped PCL soft fonts will be rendered as bitmaps. This is equivalent to using the combination of options RasterizeLower=20 and RasterizeUpper=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. Using 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. This is equivalent to the Pcl2pdf command line switch -RA

Data Type

Boolean

RasterizeLower Property

Sets and returns the soft font text rasterization lower limit

Syntax

object.RasterizeLower[ = value ]

The RasterizeLower property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list

value A double value specifying the soft font text rasterization lower limit

Remarks

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 a value of 2. This is equivalent to the Pcl2pdf command line switch -RL:#

Data Type

Double

RasterizeUpper Property

Sets and returns the soft font text rasterization upper limit

Syntax

object.RasterizeUpper[ = value ]

The RasterizeUpper property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list

value A double value specifying the soft font text rasterization upper limit

Remarks

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 a value of 40. This is equivalent to the Pcl2pdf command line switch -RU:#

Data Type

Double

Compression Property

Sets and returns the PDF document compression level

Syntax

object.Compression[ = value ]

The Compression property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list

value A string value specifying the PDF document compression level

Remarks

The program uses Flate compression algorithms to dramatically compress the output PDF documents. This is the same alogorithm 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 the value "SIZE" to specify the output PDF documents should be created as small as possible. Use the value "SPEED" to specify the output PDF documents should be created compressed but as fast as possible. This is equivalent to the Pcl2pdf command line switches -CSIZE and -CSPEED

Data Type

String

MultipleMaster Property

Enables and disables the use of Adobe Multiple Master typefaces

Syntax

object.MultipleMaster[ = value ]

The MultipleMaster property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list

value A boolean value specifying whether the use of Adobe Multiple Master typefaces is enabled or disabled

Remarks

Previous 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. This is equivalent to the Pcl2pdf command line switch -MM

Data Type

Boolean

NoPre Property

Enables and disables the use of shading re-ordering

Syntax

object.NoPre[ = value ]

The NoPre property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list

value A boolean value specifying whether the use of shading re-ordering is enabled or disabled

Remarks

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. This is equivalent to the Pcl2pdf command line switch -NOPRE

Data Type

Boolean

ScaleFactor Property

Sets and returns the PDF document scaling

Syntax

object.ScaleFactor[ = value ]

The ScaleFactor property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list

value A double value specifying the PDF document scaling

Remarks

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 a value of 0.95. This is equivalent to the Pcl2pdf command line switch -SC:#

Data Type

Double

DocInfoAuthor Property

Sets and returns the PDF Document Information Author value

Syntax

object.DocInfoAuthor[ = value ]

The DocInfoAuthor property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list

value A string value specifying the PDF Document Information Author value

Remarks

Use this option to specify the document author to be included in the PDF output. Normally the program will use a default author name. An example value is "Joe Bloggs". This is equivalent to the Pcl2pdf command line switch -DIA:"..."

Data Type

String

DocInfoCreator Property

Sets and returns the PDF Document Information Creator value

Syntax

object.DocInfoCreator[ = value ]

The DocInfoCreator property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list

value A string value specifying the PDF Document Information Creator value

Remarks

Use this option to specify the document creator to be included in the PDF output. Normally the program will leave this value unspecified. An example value is "Report Generator/2000". This is equivalent to the Pcl2pdf command line switch -DIC:"..."

Data Type

String

DocInfoKeywords Property

Sets and returns the PDF Document Information Keywords value

Syntax

object.DocInfoKeywords[ = value ]

The DocInfoKeywords property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list

value A string value specifying the PDF Document Information Keywords value

Remarks

Use this option to specify the document keywords to be included in the PDF output. Normally the program will leave this value unspecified. An example value is "invoice, january, manufacturing". This is equivalent to the Pcl2pdf command line switch -DIK:"..."

Data Type

String

DocInfoSubject Property

Sets and returns the PDF Document Information Subject value

Syntax

object.DocInfoSubject[ = value ]

The DocInfoSubject property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list

value A string value specifying the PDF Document Information Subject value

Remarks

Use this option to specify the document subject to be included in the PDF output. Normally the program will leave this value unspecified. An example value is "Sales summary for Q4 1999". This is equivalent to the Pcl2pdf command line switch -DIS:"..."

Data Type

String

DocInfoTitle Property

Sets and returns the PDF Document Information Title value

Syntax

object.DocInfoTitle[ = value ]

The DocInfoTitle property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list

value A string value specifying the PDF Document Information Title value

Remarks

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. An example value is "Quarterly report on South East Asia sales". This is equivalent to the Pcl2pdf command line switch -DIT:"..."

Data Type

String

OwnerPassword Property

Sets and returns the PDF Owner Password value

Syntax

object.OwnerPassword[ = value ]

The OwnerPassword property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list

value A string value specifying the PDF Owner Password value

Remarks

Use this option to specify the owner password to be applied to the PDF document. Use this to restrict a user from altering the security settings from within Adobe® Acrobat®. 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.
This is equivalent to the Pcl2pdf command line switch -EO:".."
Data Type

String

UserPassword Property

Sets and returns the PDF User Password value

Syntax

object.UserPassword[ = value ]

The UserPassword property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list

value A string value specifying the PDF User Password value

Remarks

Use this option to specify the user password to be applied to the PDF document. In some documentation Adobe refers to the user password as the open 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.
This is equivalent to the Pcl2pdf command line switch -EU:".."
Data Type

String

RC40 Property

Enables and disables PDF 40 bit encryption

Syntax

object.RC40[ = value ]

The RC40 property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list

value A boolean value specifying whether PDF 40 bit encryption is enabled or disabled

Remarks

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.

This is equivalent to the Pcl2pdf command line switch -EB:"40"

Data Type

Boolean

Permissions Property

Sets and returns the PDF access permissions value

Syntax

object.Permissions[ = value ]

The Permissions property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list

value A string value specifying the PDF access permissions value

Remarks

Use this option to specify the access permissions (restrictions) to be applied to the PDF document. Any of the following combinations 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. Combinations of permissions can be used. Example usages are "pm" and "pmca".

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 in Adobe® Acrobat® use the File/Document Properties... menu option, Security tab and then Display Settings. The security information for the document will be displayed.

This is equivalent to the Pcl2pdf command line switch -EF:".."
Data Type

String

PreLoadFile Property

Sets and returns the LaserJet PCL preload file value

Syntax

object.PreLoadFile[ = value ]

The PreLoadFile property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list

value A string value specifying the LaserJet PCL preload file value

Remarks

Use this option to specify 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. 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.

This is equivalent to the Pcl2pdf command line switch -LOAD:"..."
Data Type

String

FormId Property

Sets and returns the LaserJet PCL forms overlay macro to be merged on all pages

Syntax

object.FormId[ = value ]

The FormId property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list

value A long value specifying the LaserJet PCL forms overlay macro to be merged on all pages

Remarks

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 a value of 1. This is equivalent to the Pcl2pdf command line switch -F:#

Data Type

Long

ReverseFormId Property

Sets and returns the LaserJet PCL forms overlay macro to be merged on even (reverse) pages

Syntax

object.FormId[ = value ]

The FormId property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list

value A long value specifying the LaserJet PCL forms overlay macro to be merged on even (reverse) pages

Remarks

Specifies the LaserJet PCL forms overlay macro to be merged on 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 a value of 1. This is equivalent to the Pcl2pdf command line switch -FR:#

Data Type

Long

CoverFormId Property

Sets and returns the LaserJet PCL forms overlay macro to be merged on the cover (first) page

Syntax

object.FormId[ = value ]

The FormId property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list

value A long value specifying the LaserJet PCL forms overlay macro to be merged on the cover (first) page

Remarks

Specifies the LaserJet PCL forms overlay macro to be merged on 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 a value of 1. This is equivalent to the Pcl2pdf command line switch -FC:#

Data Type

Long

HPGL2 Property

Enables and disables the parsing and interpretation of HP-GL/2 vector graphics

Syntax

object.HPGL2[ = value ]

The HPGL2 property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list

value A boolean value specifying whether the parsing and interpretation of HP-GL/2 vector graphics is enabled or disabled

Remarks

By default Pcl2pdf will attempt to parse interpret HP-GL/2 vector graphics commands found within the PCL file being processed. Set this property to False to disable or turn off HP-GL/2 processing should you experience any problems or unwanted side effects. This is equivalent to the Pcl2pdf command line switch -I2

Data Type

Boolean

NoWin Property

Enables and disables the use of special Windows soft font logic

Syntax

object.NoWin[ = value ]

The NoWin property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list

value A boolean value specifying whether the use of special Windows soft font logic is enabled or disabled

Remarks

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 heiroglyphics" then using this switch may help to make the text readable. Also, try using the RasterizeAll option above. This is equivalent to the Pcl2pdf command line switch -NOWIN

Data Type

Boolean

NoUni Property

Enables and disables the use of special Unidriver soft font logic

Syntax

object.NoUni[ = value ]

The NoUni property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list

value A boolean value specifying whether the use of special Unidriver soft font logic is enabled or disabled

Remarks

In addition to the NoWin option described above 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. This is equivalent to the Pcl2pdf command line switch -NOUNI

Data Type

Boolean

Options Property

Sets and returns additional runtime options

Syntax

object.Options[ = value ]

The Options property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list

value A string value specifying additional runtime options

Remarks

Additional Pcl2pdf runtime options can be specified using this option. Options should be given in command line format using leading '-' characters and be separated by spaces. This option is processed after any other property options that may be set. An example value is "-SC:0.95 -RA". There is no direct equivalent Pcl2pdf command line switch. 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"

Data Type

String

InitialView Property

Sets and returns initial view options

Syntax

object.InitialView[ = value ]

The InitialView property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list

value A string value specifying initial view options

Remarks
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 "tmw" and "u"

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

This is equivalent to the Pcl2pdf command line switch -IV:"..."
Data Type

String

PdfVersion Property

Sets and returns the PDF document file version

Syntax

object.PdfVersion[ = value ]

The PdfVersion property syntax has these parts:

Part Description

object An object expression that evaluates to an object in the Applies To list

value A string value specifying the PDF document file version

Remarks
Specifies the file version to be written into the PDF document output, for example "1.3". The default is PDF version 1.4.
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.

This is equivalent to the Pcl2pdf command line switch -PDF:"..."
Data Type

String

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
7	Unsupported operating system platform

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

Part	Description
object	An object expression that evaluates to an object in the Applies To list
value	A string value specifying the page orientation