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 (described below). To obtain the current OPT= value, use the OPT( ) Function.
option Supported parameters for defining PDF output. (See Output Parameters described below.)
*PDF* Keyword, not case-sensitive. Special device filename, enclosed in quotation marks within OPEN directive. (Include asterisks in syntax.)
[WDX] File tag for directing output to a PDF on a WindX client machine instead of the server.
   
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’ 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.
DISPLAY Brings up an input window for the user to enter information regardless if it is needed.
OVERWRITE Indicates that overwriting the output file is OK, no need to verify with the user.
FILE=FileName Allows specification of output file pathname.
FORM=FormName Allows specification of forms names (see Forms Handling).
PAPERSIZE=FormNumber Allows specification of form given internal form number (see Forms Handling).
ORIENTATION=LANDSCAPE | PORTRAIT Defines how the report is intended to print.
MARGINS=top:left:right:bottom Defines margins (See Margin Settings).
TITLE=string Adds a Title tag to the PDF Document.
SUBJECT=string Adds a Subject tag to the PDF Document.
AUTHOR=string Adds an Author tag to the PDF Document.t.
PRODUCER=string Adds a Producer tag to the PDF Document.
CREATOR=string Adds a Keywords tag to the PDF Document
The following PDF options are +PxPlus Exclusive
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, (build 9190)
ENCRYPT ¹ Encrypts document. By default a password is required so if no owner password is provided the system will default to 'password'. (build 9190)
METRIC Indicates that the PDF is to default to Metric paper size (A4) instead of 8.5x11 (Letter) sized paper.
OWNERPSWD=password ¹ Sets the password to be used to identify the user as the document owner. (build 9190)
OPENPSWD= password ¹ Sets password required to open/view the document (build 9190)
NOEDIT ¹ Disable document editing (build 9190)
NOCOPY ¹ Disable document copy (build 9190)
NOPRINT ¹ Disable document printing (build 9190)
NOENTRY ¹ Disable form entry and annotation (build 9190)
VIEW 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. (This option only available on Windows or when using a WindX based Client Server interface)

¹ These options require the use of the HARU PDF library thus requires the 'HP' system parameter be set

PDF-A Compliant output

In order 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, then it is considered not as 1/1000 but as either inches or millimetres.

Examples:

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" x 11") size is assumed. If both FORM= and PAPERSIZE= are given, the FORM= option has priority.

For further details, see Forms Handling.

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 ProvideX 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 they should issue the open as follows:

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

In order 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 ProvideX-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"

The 'FONT' mnemonic only supports the following basic 14 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",
"ZapfDingbats"

Font Mapping

In order 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
  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 colour mnemonics,
'WHITE' '_WHITE' and other named colours, 'COLOUR' and
'COLOR', 'LF', 'CR', and 'FF'

*PDF* also supports language functions such as:

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

Text Mode Printing

*PDF* accepts character mode text:

PRINT (chan) "This is a sentence to output."

Some Limitations

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

  • Invalid mnemonics are ignored.
  • 'BO' & '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' is supported on the Windows platforms only (not on UNIX or Linux); however, any image format supported by the 'PICTURE' mnemonic may be used
    (bmp, jpg etc).
  • '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.
   
Forms Handling The ProvideX-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 include 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 ProvideX 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 for 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–ust below the standard form sizes.

   
Utility for Processing PDF Options ProvideX includes PDF utility programs for processing options on an OPEN:
*ext/system/pdf ProvideX-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 ProvideX, which saves it as the default setting. In order to allow for application designers to access this default setting, the OPEN logic for *PDF* files allows the programmer 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–f so, the user is asked if they wish to overwrite the output file. The Form drop box contains the list of all the known form size 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.

Pressing 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–if so, the user is asked if they wish 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 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, ProvideX 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 3 ways:

  1. Via SET_PARAM 'AP'.
  2. In an INI file [Config] section as AutoEnablePDF=1.
  3. 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 parameter 'AP' 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 hsould be seperated 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*.

The %PDF_DEFAULT$ variable is a +PxPlus Exclusive
   
See Also 'AP' System Parameter
'FONT' Mnemonic
*WINPRT* Windows Printing