Description

The starting point for the development of this component has been the FPDF.PHP library the sources of which are available at www.fpdf.org .   This well known, field proven and widespread open source library is coded in PHP language and is composed of a core class to which several additional contributions have been introduced by an active community.  For the record, it has been available since 2001 and is still widely spread on the planet.  As running PHP in z/OS wouldn’t be very practical [1] in many MVS operational installations, each and every PHP line has been recoded into ‘C’ language.

Though the coding price was significant, the performance reward has been achieved as generating PDF files with FPDF4ZOS is very cost effective both in terms of size of PDF files produced and in terms of Mips executed, not a small consideration in MVS environments.

Furthermore, the operational environment which is proposed takes into account miscellaneous issues one has to deal with when working in MVS.  For instance:

• Customization of EBCDIC à ASCII transcoding table.
• File specifications and dynamic allocation  (RECFM, LRECL, UNIT, etc.)
• DDNAME and PDS support, etc.

However, these added features do NOT affect the multi platform capability of this library which is fully operational both under Linux-Unix and Windows.

Goals:

FPDF4ZOS has the capability to generate very sophisticated documents in terms of design, but its main target is obviously mass production of administraive documents, typically: bills, bank statement or similar reports, payslips, etc.  In other words, performances and file size considerations have been favoured, while some features available in the core PHP version have been intentionnaly discarded, at least in first releases.  For instance, the capability to add fonts embedded into PDF was NOT taken into account as of this version.

In fact, regarding character fonts, the basic assumption was that the kind of documents handled in mainframe services can make do with the 14 basic Type 1 fonts “natively” supported by Adobe Reader without their being embedded in PDF files.  Namely Courier, Times and Helvetica with their respective four variants: { normal, bold, italic and bold-italic }.  Two additional “fancier” fonts have also been taken into account: Symbol and ZapfDingbats.

Features implemented:

Basically, beyond the language dependant calls – FPDF constructor which is meaningless in ‘C’ language and which has been replaced by NewPdfy() call – almost all of the functional features available in FPDF4ZOS are the ones described in the original web site www.fpdf.org .  Only one functions is not supported in current release which is the capability to add fonts, say AddFont().

Moreover, some possibilities which were seen irrelevant for MVS | z/OS environment for the Output routine were also discarded for the time being.  For instance, the possibility to send PDF output to <stdout> instead of a regular file, a useful feature in web environments, was not taken into account.  In other words, only file output is available.

Besides, many features which are available only in original FPDF PHP extension scripts have been integrated into the basic FPDF4ZOS core library because their anticipated widespread use in the kind of applications running on MVS:

• Graphics:             Rounded rectangles, ellipses, polygons, sectors, rotation.
• Bookmark:           Generation of hierarchical bookmarks in output PDF
• SetProtection:      Enable PDF protection, at both user and owner levels.
• Embedded data:   The possibility to include data file within a PDF
• Etc.

Other features available which were not part of the original PHP package:

In order to make the most of the MVS environment where many unrelated applications may potentially use this library, powerful features have been added which didn’t exist in the original PHP package or their extensions:

FPDF4ZOS  initialization:

An initialisation function NewPdfy() is proposed whereas parameters will be automatically set within the library according to the content of a configuration file. Besides, it further specifies the maximum number of pages anticipated in order to significantly optimize memory usage. The format of the proposed parameter file is described in a specific page.

Form management:

Two functions SetForm() and InclForm() have been specified in order to reduce file size.  The idea is to include a set of instructions (named ‘form’ hereafter) once in the PDF and to refer to it in subsequent pages.  This feature is especially interesting for mass production where a ratio of 80% has been achieved in file size reduction for a 1000 pages PDF file which features relatively complex forms; say payslips or bills.  The format of form instructions is directly derived from FPDF primitives as shown in the samples contained in the Windows package.  More on forms features in a dedicated page.

Anchor mechanism: lay out Instructions associated with form management:

In documents, it happens frequently that either text or line drawings ought to be associated with elements to be found in forms in a sort of “anchor” mechanism.  For example, a piece of data handled by a given program must be aligned with a text appearing in a form; say  “Name:”  label to be followed by real name of the person considered.  To that end, three pairs of instructions have been implemented:  SetTextProp() & {GetTextProp() | ApplyTextProp()} :

SetTextProperties() is to be found in forms while GetTextProperties() as well as ApplyTextProperties() is to be used in programs.  The idea is that programs can position text with its associated properties (font and color) while these may be externally driven (externally meaning outside the program proper) from dedicated instructions to be retrieved from a form.  GetTextProperties() only retrieves properties in a data structure and  ApplyTextProperties() outputs target text taking into account properties retrieved.

SetDrawProperties() to be found in forms and GetDrawProperties() to be retrieved in programs so that the latter can position a line and draw it according to externally driven properties.

SetColumns() is to be found in forms and GetColumns() is to be retrieved in programs so that the latter can retrieve externally driven columns widths.

For further details on these functions, the reader is invited to check the Reference section as well as the samples provided in this package.

Embedded data:

PDF format offers the possibility to embed data within output PDF documents.  By attaching a name with an appropriate extension to this data, Windows can launch an application.  This feature may be interesting for documents in several cases, three of which are listed below:

• Supposing the PDF file is generated from CSV data, it might be interesting to embed this CSV raw data into the PDF for possible subsequent Excel manipulations by recipient users, if need be.
• Several secondary PDF files may be embedded into a “master page” in a kind of binder document.
• Supposing the PDF file should be sent to archiving facilities, it might be useful to embed XML data into the PDF to further specify document attributes.

NB:  in Rel 4.A, number of data attachments per PDF document is limited to 4.

Annotation management:

PDF format offers the possibility to add miscellaneous notes into PDF documents.  The number of possibilities in Note and Comment management is infinite and the library offers only a small subset of available features.  Only Subtype Text and Square are supported in Rel 2.4.

NB:  in Rel 4.A, total number of annotations within a PDF may be  set in configuration file, but maximum number of annotations per page is limited to 8.

Miscellaneous graphic feature:

To make the most of PDF format graphical capabilities, several routine have been added in release 2.2 and above: Ellipse, Circle, Polygon, Sector, Rotate, SetAlpha.  See:

• Ellipse(), Circle(), Polygon() to draw basic geometric figures.
• Sector() which enables the drawing of Apple pie statistical charts
• Rotate() to output text or image in slanted mode
• SetAlpha() for color transparency

InLine instructions:

When various finer grain effects are required, there is a possibility to insert raw PDF instructions by means of the InLine() function in order to adjust some elements in a page.  Here are some examples of such fine grain effects:

• BT 1 0 0 1 24 730 Tm 5.00 Tc 2 Tr 0 g 0.3 0.3 0.9 rg (Hello FPDF Characters Spacing and Rendering mode) Tj  0 Tc 0 Tr ET 0 g

Write text ‘Hello FPDF’ at current position with specific character spacing and specific rendering mode.

• q 0 g BT 0 1 -1 0 524 440 Tm (Hello FPDF Bottom to Top) Tj ET Q

Write text ‘Hello FPDF’ at the bottom right of a landscape page in current font in vertical mode (90°).

• q 0.8 g BT 1 1 -1 1 150 440 Tm (Hello FPDF Gray lanted) Tj ET Q

Write text ‘Hello FPDF’ at (x,y) in current font in slanted mode (45°) and in gray color.

Caution:

A relatively high level of expertise in PDF inner format is required to use this InLine() function: a slight error in the string parameter can result in a flawed PDF file – which means that Adobe Reader will not be able to open the file.

Besides, programmers are remembered that in raw PDF instructions, position must be expressed in dpi units – dpi stands for dots per inch.  For the record, it is recalled that:

1 cm = 28.35 dpi.

Readers who wish to use this powerful InLine() feature are invited to consult PDF reference.

The list of functions currently available as well as their respective parameters is available in the Manual section, in their ‘C’ and Cobol syntax.