Special File Handling 

Formats

Where:

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:

¹ 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:

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:

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'.

*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:

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:

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:

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.

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