# Special File Handling

*PDF* | PDF Print Interface

## Formats

1. | Open PDF File: | OPEN (chan[,fileopt])"*PDF*[;option][;option] [...]"
2. | PDF via WindX: | OPEN [INPUT] (chan[,fileopt])"[WDX]*PDF*[;option][;option] [...]"

Where:

chan | Channel or logical file number.
fileopt | File options. Supported options for opening *PDF* include:
ERR=stmtref | Error transfer
OPT=option string | PDF output parameters (see Output Parameters). To obtain the current OPT= value, use the OPT( ) function.
option | Supported parameters for defining PDF output (see Output Parameters).
*PDF* | Keyword, not case-sensitive. Special device filename, enclosed in quotation marks within the OPEN directive. (Include * asterisks in syntax)
[WDX] | File tag for directing output to a PDF on a WindX client machine instead of the server.

For information on creating hyperlinks using text, pictures and rectangles, see Hyperlinks.

## Description

Use *PDF* for directing output to a PDF (Postscript Document Format) compatible file. The interface to the PDF output is fundamentally the same as the interface to the Window's print spooler – an application opens the logical file *PDF* instead of *WINPRT*.

The OPEN pathname may specify a number of semi-colon separated options for the PDF file. A number of semi-colon separated options for the PDF file may be included as part of the pathname or as part of the OPT= clause:

> OPEN(chan)"PDF* [;option] [;option] […]"
> OPEN(chan,OPT="option; option;…")"*PDF*"

*PDF* Output Parameters

The following options can be used to define PDF output:

Option | Description
ASIS | Uses last defined settings and does not present the user with a window to enter parameters. If the output file already exists, it will be overwritten.
AUTHOR=string | Adds an Author tag to the PDF document.
CREATOR=string | Adds a Creator tag to the PDF document.
DISPLAY | Brings up an input window for the user to enter information, regardless if it is needed.
DPI=num | Dots per inch used only when PIXELPOS is On. Defaults to 150. (added in PxPlus 2020)
EMBED= YES | NO | ALL ¹ | Determines if font can be embedded (YES), cannot be embedded (NO, thus only the 14 standard fonts supported), or mandates all fonts must be embedded (ALL, which results in a PDF/A-1b compliant file -- see below). This default value for this option can be set in the [Config] section of the INI using a PDFEMBED=xxx option. (added in PxPlus v8.30)
ENCRYPT ¹ | Encrypts document. By default, a password is required; therefore, if no owner password is provided, the system will default to 'password'. (added in PxPlus v8.30)
FILE=filename | Allows specification of output file pathname.
FORM=formname | Allows specification of forms names. Default is LETTER size (8.5" x11"). See Forms Handling.
INLINE | Can be used in conjunction with the VIEW option to have the system run the PDF viewer in line that is when the execution will be suspended until after the PDF viewer task is closed. (added in PxPlus v11.00)
KEYWORDS=string | Adds a Keywords tag to the PDF document.
MARGINS=top: left: right: bottom or MARGIN=top: left: right: bottom | Defines margins. See Margin Settings.
METRIC | Indicates that the PDF is to default to Metric paper size (A4) instead of 8.5 x11 (Letter) sized paper. (added in PxPlus v8.30)
NOCOMPRESSION | Disable compression of the PDF file.
NOCOPY ¹ | Disable document copy. (added in PxPlus v8.30)
NOEDIT ¹ | Disable document editing. (added in PxPlus v8.30)
NOENTRY ¹ | Disable form entry and annotation. (added in PxPlus v8.30)
NOPRINT ¹ | Disable document printing. (added in PxPlus v8.30)
OPENPSWD=password ¹ | Sets password required to open/view the document. To function, the document must also have an OWNERPSWD. (added in PxPlus v8.30)
ORIENTATION=LANDSCAPE | PORTRAIT | Defines how the report is intended to print. Default is PORTRAIT.
OVERWRITE | Indicates that overwriting the output file is OK, no need to verify with the user.
OWNERPSWD=password ¹ | Sets the password to be used to identify the user as the document owner. (added in PxPlus v8.30)
PAPERSIZE=formnumber | Allows specification of form given internal form number. See Forms Handling.
PIXELPOS | Set for pixel positioning instead of PDF positioning when using @X/Y(=num). Set DPI= to define pixel size. (added in PxPlus 2020)
PRODUCER=string | Adds a Producer tag to the PDF document.
SUBJECT=string | Adds a Subject tag to the PDF document.
TITLE=string | Adds a Title tag to the PDF document.
VIEW | (Only Available on Windows or When Using a WindX-based Client Server Interface) Launches a PDF viewer when the PDF file is closed. If no FILE= is specified, a temporary file is created and deleted when the user exits the PDF viewer. (added in PxPlus v8.30)
WATERMARK=xxx | Allows for the specification of an image that is to be printed on each page of the PDF output prior to any application-generated data. The image will be scaled and centered on the page. (added in PxPlus 2014 - Feature Pack 1)

> ¹ These options require the use of the Haru PDF library and thus require that the 'HP' system parameter be set.

PDF/A Compliant Output

To create a PDF/A compliant output file, you must declare that all fonts be embedded (EMBED=ALL). The PDF file must also not be encrypted or have a password, as these would violate the ISO standards for PDF/A.

Margin Settings

Values for margin settings are typically given in 1000ths of an inch; however, the following also applies:

- If the value contains the letter I, it is considered inches.
- If the value contains the letter M, it is considered millimetres.
- If the value contains a decimal point or the value is less than 25, it is considered not as 1/1000 but as either inches or millimetres.

Example:

| MARGINS="250:250:250:250" | All 4 margins are 250/1000's (1/4 inch).
| MARGINS="1:1:1:1" | All margins are 1 inch.
| MARGINS="1i:1i:1i:1i" | All margins are 1 inch.
| MARGINS="1.25:1.25:1.25:1.25" | All margins are 1-1/4 inches.
| MARGINS="20m:20m:20m:20m" | All margins are 20 millimeters.

## General Information

If neither the FORM= or PAPERSIZE= is given, or the value for either of these two parameters cannot be found in the Forms Library, then the default LETTER size (8.5" x11") is assumed.

If both FORM= and PAPERSIZE= are given, the FORM= option has priority. See Forms Handling.

If FORM= or PAPERSIZE= and ORIENTATION= is given, then the width and height as specified by FORM= or PAPERSIZE= is used. If the width is greater than the height and PORTRAIT was specified, then the width and height are swapped. If the height is greater than the width and LANDSCAPE was specified, then the height and width are swapped.

If the ASIS or DISPLAY options are not specified and no FILE= is given, then the system prompts the user for the file. If ASIS is specified, but no FILE= has been defined by a prior open to *PDF*, then the system will generate an Error #12: File does not exist (or already exists). The filename specified by FILE= cannot have a [WDX] prefix. If the user wants output to go to a remote file, he/she should issue the OPEN as follows:

> OPEN (nnn) "[WDX]*PDF*…"

To simplify the logic behind this process and allow for developer customization, whenever *PDF* is opened, the input pathname is forwarded for processing to the user-defined program *ext/pdf (if it exists) or the PxPlus-supplied program *ext/system/pdf. It determines if the selection window should be presented and validates the FORM= and PAPERSIZE= options.

These options passed may be retrieved via PTH( ) and OPT( ).

Example:

> open (1)"*PDF*;FILE=/tmp/pvx.pdf; FORM=Letter:8.5in:11in"

If using the native *PDF* interface, i.e. 'HP' is Off, then the 'FONT' mnemonic only supports the following 14 basic PDF fonts:

> "Courier", "Courier-Bold", "Courier-BoldOblique", "Courier-Oblique", "Helvetica", "Helvetica-Bold", "Helvetica-BoldOblique", "Helvetica-Oblique", "Times-Roman", "Times-Bold", "Times-Italic", "Times-BoldItalic","Symbol" and "ZapfDingbats".

#### Note:
These 14 basic PDF fonts are case sensitive, unlike using the fonts installed on the system, which are case insensitive.

Font Mapping

To simplify the mapping of common Windows fonts to the standard PDF fonts, the system automatically performs the following font translation:

Windows Font | PDF Font
Arial | Helvetica
MS Sans Serif | Helvetica
Microsoft Sans Serif | Helvetica
Tahoma | Helvetica
Verdana | Helvetica
Times New Roman | Times
Courier New | Courier

If using the native *PDF* interface, i.e. 'HP' is Off, then font mapping will always occur.

If using the LibHaru *PDF* interface, i.e. 'HP' is On, then font mapping will occur only if the font is not found; otherwise, the standard PDF font or the font installed on the system will be used. The 'FONT' mnemonic supports the 14 basic PDF fonts, as well as any TrueType font installed on the system. You can also use the 'FONT'(list*, chan) on the open *PDF* channel to list the fonts available.

#### Note:
Prior to PxPlus 2017: If using the LibHaru *PDF* interface, i.e. 'HP' is On, font mapping is not supported. The Helvetica font is used as the default even if EMBED=ALL is specified. This will result in a non-embedded font being used, in which case the PDF file will not be PDF/A compliant. See PDF/A Compliant Output.
PxPlus 2017 or later: If a font name is given that does not match a standard PDF font or a font installed on the system, then font mapping will occur, and the mapped font will be used (rather than the Helvetica font).

Mnemonics and Functions

The following mnemonics are supported with *PDF*:

> 'TEXT', 'FONT', 'PEN', 'FILL', 'PICTURE', 'PIE', 'POLGON', 'ARC', 'RECTANGLE', 'LINE', 'CIRCLE', 'OFFSET', 'LPI', 'CPI', 'MODE', 'Fn' and 'Bn' (Foreground and Background Color), 'WHITE' and '_WHITE' and other named colors, 'COLOUR' and 'COLOR', 'LF', 'CR', 'LM', 'PM' and 'FF'.

If using the 'TEXT' mnemonic to specify the vertical alignment options (Top, Middle, Bottom), the 'HP' system parameter must be set to On ('HP'=1) to use the LibHaru *PDF* interface; otherwise, if 'HP' is Off, the vertical alignment options will not be supported.

*PDF* also supports language functions such as:

> FIB( ), FIN( ), FID( ), PTH( ), OPT( ), MXC( ), MXL( ), etc.

UTF-8

If PxPlus UTF-8 mode is On, i.e. 'U8' is On, then the following is true:

- If using the native *PDF* interface, i.e. 'HP' is Off, then only ASCII characters are supported outputting to a PDF. Non-ASCII UTF-8 characters will not be displayed correctly.
- If using the LibHaru *PDF* interface, i.e. 'HP' is On, then UTF-8 characters are supported outputting to a PDF.

#### Note:
You must also use a font that supports the characters you want to display in the PDF; i.e. simplified Chinese characters will not display using Arial. Instead, you must use a font like SimSun.

(UTF-8 support was added in PxPlus 2016.)

Page Orientation

If using the LibHaru *PDF* interface, i.e. 'HP' is On, then it is possible to specify the page orientation for each page using the 'LM' mnemonic or a landscape orientation and using the 'PM' mnemonic for a portrait orientation.

You can switch between portrait and landscape modes when outputting PDF files using the 'LM' and 'PM' mnemonics if the mnemonic is issued prior to outputting any data to the page.

#### Note:
Issuing either of these mnemonics before or immediately after issuing the 'FF' mnemonic switches the orientation of the page.

(Support for changing page orientation was added in PxPlus 2016.)

Text Mode Printing

*PDF* accepts character mode text.

Example:

> print (chan)"This is a sentence to output."

Some Limitations

The following are known limitations that control options under the PxPlus PDF interface:

| • | Invalid mnemonics are ignored.
| • | 'BO' and 'EO' and user-defined mnemonics are ignored.
| • | Only 'PEN' Solid, Dashed, or No Pen style options are supported.
| • | Only 'FILL' Solid and No Fill options are supported (no gradient fills, lines, or hashes).
| • | 'PICTURE' support applies to the .jpg image format on macOS and AIX and to the .jpg and full color .png image formats on Linux. Transparency options are also only supported on Windows. (Support for .jpg and .png images on Linux was added in PxPlus 2019.)
| • | 'RECTANGLE' Rounded options are not supported.
| • | Compression is not supported for PDF files.
| • | Output element skipping is applied instead of truncate; i.e. PDF documents skip the processing of output elements that exist outside the page borders or flow over a page border. *WINPRT* displays as much of the element as possible while truncating the portion that flows over a border.
| • | There is a limit of 8192 pages with the PDF LibHaru interface. Attempting to print beyond this limit will report an Error #2: END-OF-FILE on read or File full on write.

## Forms Handling

The PxPlus-supplied utility program *ext/system/pdf is embedded with a forms handling mechanism that validates and displays dialogues to the end user. To provide consistency with Windows forms handling, the PDF output paper size is determined via form name rather than by the physical dimensions of the paper.

For the purposes of the PDF handler, the FORM= option provides a form name followed by a colon and includes the paper size in terms of width and height. The paper size values are assumed to be in thousandths of an inch unless followed by the letter I (for inches) or the letter M (for millimetres).

The PDF processor within the system will only utilize the width and height portions of the FORM= option. The form name is provided strictly as a reference for the display.

The Form Library is a keyed file. The PDF utility program will search for *ext/forms.xx then for *ext/system/forms.xx, where xx is a language code. The properties for this file are:

| Form Number | Primary key, 3 digits (explained below).
| Name of Form | Alternate key, 24 characters.
| Width | This field contains the width of the paper in the units specified below.
| Height | This field contains the height of the paper in the units specified below.
| Units of Measure | Contains "I" for inches or "M" for mm.
| Priority | Alternate key, Priority$+ Form number.

The *ext/system/forms.en file is pre-loaded with standard form sizes. The PDF selector window allows additional forms to be added to the file. When the first form is added to this file by the end user, a copy of the file *ext/system/forms.xx is made in *ext/forms.xx, which is then used.

To simplify installation of applications with custom forms, when the selection window is presented and a FORM= is specified, the form name will be automatically added if it does not already exist in the Forms Library. This allows applications to be created with hard-coded FORM= clauses in their OPEN command – the system automatically creates the required form entry.

Form numbers are based on pre-defined form numbers used by MS Windows. As user-defined forms are added, new numbers will be assigned sequentially starting no lower than 256 (form numbers 0 to 255 are reserved).

Should the OPEN include a PAPERSIZE= option but no FORM= specification, the system will look up the form using the PAPERSIZE= value to determine what the proper form is. If there is neither a FORM= specification nor a valid PAPERSIZE= value, LETTER (8.5x11 inch) will be assumed. The PAPERSIZE= is ignored when a FORM= option is present.

The priority field is used to determine the load sequence for lists used to display the available forms in the system. By default, Letter, Legal, A4, A5, and a number of other standard form sizes are priority "0". All other forms have a priority of "5". User forms are added with a priority of "1" and appear near the top of the list when displayed, just below the standard form sizes.

## Hyperlinks

Text Hyperlinks

A hyperlink can be outputted to a PDF document by printing using the 'TEXT' mnemonic with the <URL> attribute where URL is the destination of the hyperlink. The text will be underlined and displayed in blue to distinguish it as hyperlink text unless the style=inherit option was specified with the URL. In that case, the current font and foreground color will determine the look of the hyperlink text.

Example:

> print (pdf_chan)'text'(240,420,"Google","C<http://www.google.com>")

(Support for text hyperlinks was added in PxPlus 2018.)
(The style=inherit option was added in PxPlus 2019.)

Picture Hyperlinks

A picture can be created as a hyperlink that can be outputted to a PDF document by using the 'PICTURE' mnemonic with the <URL> attribute where URL is the destination of the hyperlink.

Example:

> open (pdf_chan)"*PDF*;file=C:\my_app\abc\report.pdf"
> print (pdf_chan)'picture'(1,1,100,100,"C:\my_app\abc\resources\mylogo.png,<https://www.mycompany.com>",2)
> print (pdf_chan)'picture'(500,800,700,880,"C:\my_app\resources\mapbutton.png,<file:///c:/my_app/abc/map.pdf>")
> close (pdf_chan)

(Support for picture hyperlinks was added in PxPlus 2019.)

Rectangle Hyperlinks

A rectangle can be created as a hyperlink that can be outputted to a PDF document by using the 'RECTANGLE' mnemonic with the <URL> attribute where URL is the destination of the hyperlink. This can also be used to create an arbitrary region in the PDF that is a hyperlink. By setting 'PEN' to 0, the rectangle will not be drawn; however, the hyperlink will be created.

Example:

> open (pdf_chan)"*PDF*;file=C:\my_app\abc\report.pdf"
> print (pdf_chan)'pen'(1,3,8),'fill'(2,6)
> print (pdf_chan)'rectangle'(200,200,600,600,0,"<https://www.pvxplus.com>")
> print (pdf_chan)'pen'(0,0,0)
> print (pdf_chan)'rectangle'(800,100,900,400,0,"<file:///C:/my_app/abc/map.pdf>")
> close (pdf_chan)

(Support for rectangle hyperlinks was added in PxPlus 2019.)

## Utility for Processing PDF Options

PxPlus includes PDF utility programs for processing options on an OPEN:

| *ext/system/pdf | PxPlus-supplied program
| *ext/pdf | User-defined program

Both utility programs have the following format:

> ENTER NewParameters$, OldParameters$, ERR=*next

The utility will handle most PDF option string validation and forms processing internally. It ensures that the string that it gets passed to process has a valid FORM= option before it is returned to the actual PDF interface. It is basically a pre-processor for the PDF string.

Once the PDF string is accepted, the utility program returns it to PxPlus, which saves it as the default setting. To allow for application designers to access this default setting, the OPEN logic for *PDF* files allows the developer to issue:

> OPEN INPUT (chan) "*PDF*;ASIS"

Then, query the PTH( ) and OPT( ) of the PDF file in order to obtain the settings. The INPUT clause prevents the system from erasing the output file. Optionally, to set default settings, the developer can issue:

> OPEN INPUT(chan) "*PDF*;new settings"

PDF Message Selection Box (Graphical)

The user will be presented with a dialogue box to allow for selection of the output file, form and orientation. When a file pathname has been given, the system checks to see if the file exists, and if so, the user is asked if he/she wishes to overwrite the output file. The Form drop box contains the list of all the known form sizes in the system with the currently selected form name highlighted/selected (the default being Letter). The dialogue also has a New button for adding a new form description.

Selecting the Accept button in the message box results in the form description being saved/added to the form library and the identified form being set as the output form type.

PDF Message Selection Box (Text Mode)

The user will be presented with a character-mode window. When a file pathname has been given, the system checks to see if the file exists, and if so, the user is asked if he/she wishes to overwrite the output file. Once the file has been given, a drop list of the potential forms is displayed. The currently selected item is highlighted. After selecting the form, the user must select the orientation from a drop list with choices of Portrait or Landscape.

Once all the selections are made, the user can select OK or Cancel to confirm the input.

## Capturing Output to *WINPRT* as PDF Output

Output to *WINPRT* can be automatically intercepted for PDF using the 'AP' system parameter. When 'AP' is set, if the user selects Output To File and includes a filename ending in .pdf, the system looks at the options selected during the *WINPRT* Printer Selection dialogue and processes the output through *PDF* instead of *WINPRT*.

'AP' may be set On in one of three ways:

> • Via SET_PARAM 'AP'

> • In an INI file [Config] section as AutoEnablePDF=1

> • From the System Menu on a dialogue (drop-down menu from clicking the icon in a window title bar) as Use Internal PDF Driver

By setting the AutoEnablePDF=-1 in the [Config] section of your INI file, you can remove the entry from the dialogue system drop-down menu. However, you are still be able to turn the 'AP' parameter on and off programmatically.

## Changing 'CP' and 'EP' Settings on *PDF* Output

The default behavior in the system when issuing the 'CP' mnemonic is to take the current font (which normally is a 12-point font) and multiply by 5/8 rounding up. This results in an 8-point font; therefore, you get:

> ->open (1) "*pdf*;file=c:\junk.pdf"
> ->print mxc(1)
> 79
> ->print (1) 'cp',
> ->print mxc(1)
> 119
> ->end

If you want, you can override the 'CP' font (and the 'EP' font) using the MNEMONIC directive:

> ->open (1) "*pdf*;file=c:\junk.pdf"
> ->print mxc(1)
> 79
> ->mnemonic (1) 'cp'="Courier,-7":132,60
> ->print (1) 'cp',
> ->print mxc(1)
> 136

Using a point size of -7 will give you 136 columns.

## Default PDF Settings

The global variable %PDF_DEFAULT$ can be set to contain any default PDF options such as default paper size, margins, etc. As in the *PDF* pathname, options should be separated by semi-colons.

In addition, %PDF_DEFAULT$ can contain the option VIEWER, which will make the PDF driver the default report viewer in the system and will be used whenever the application opens *VIEWER*.

## See Also

'AP' Auto-Enable PDF Output
'HP' Use Haru PDF Library
'U8' Control UTF-8 Processing Defaults
'FONT' Define/List Fonts
'TEXT' Draw Text
'PICTURE' Define/Draw Picture
'RECTANGLE' Draw a Rectangle
*WINPRT* Windows Printing