Forms
FPDF4ZOS offers a powerful form feature which enables a program to import a whole layout composed of elementary FPDF instructions. Moreover, assuming target PDF contains 1000 pages with the same layout, instructions associated with that layout would appear only once, and each page would refer to an object containing that layout. This may decrease very significantly the volume of PDFs thus built.
Below is a list of rules for using this form feature:
- Each form is identified by an 8 characters string. In MVS environment, this string will refer to a PDS or PDSE member while its name ought to be specified in configuration file. In Windows-Linux environments, this string suffixed by ".frm" will refer to a file located in the directory the name of which ought to be specified in configuration file (key=FORM.DIR).
- A PDF may contain no more than a maximum number of forms also specified in configuration file (key=MX_NBFRM). Within that limit, each page may contain any number of forms, including none.
- There are several FPDF instructions which cannot be included in forms: NewPdfy () - Output() - FlushPdf() - AddPage() - SetDisplayMode() - GetX() - GetY() - SetCompression() - SetProtection() - AddLink() - SetLink() as well as all Forms or anchors related functions such as SetForm(), ApplyTextProp() or InclForm(). Besides, for various technical reasons not detailed here, link related features available in some instructions such as Write() or Cell() are not available when those appear in forms.
Anchors
Within forms, another powerful anchor mechanism is available. An anchor is defined as a character string which is supposed to point at a given set of features. There are three types of anchors proposed by FPDF4ZOS:
- Text Anchors which relate to a set of Text display properties,
- Column Anchors which relate to a set of table columns widths,
- Draw Anchors which relate to a set of graphical display properties
Text Anchors
Typically, a text anchor will provide a location as a pair of [X,Y] coordinates, an optional width and an height, a set of 3 integer numbers which specify Text color, and finally a font definition: font family, font size and font style.
Below is a list of rules for using this text anchor feature:
- An FPDF4ZOS context may contain no more than a maximum number of text anchors specified in configuration file (key=MX_NBTXP). Note that this maximum number refer to all text anchors across all forms.
- If two text anchors bear the same identifier, the first one wins, meaning the subsequent text anchors with that very name will be dropped.
In C language, the structure below defines text anchor properties.
typedef struct textprop ??< char txp_id ??(8+1??); /* Reference point ID */ float p_x; /* X position (in current unit) */ float p_y; /* Y position (in current unit) */ float i_x; /* X increment or width; -1 if unrelevant */ float i_y; /* Y increment or height; -1 if unrelevant */ int c_r; /* Text color (RGB) */ int c_g; /* with which text will written */ int c_b; char font_fam ??(12+1??); /* Font Family for text */ float font_siz; /* Font Family size */ char font_prp ??(3+1??); /* Font Family style (B &| I &| U) */ ??> textprop;
In COBOL language, the structure below defines anchor properties.
01 TEXTPROP. 02 TXTID PIC X(12). 02 TPX USAGE COMP-1. 02 TPY USAGE COMP-1. 02 TIX USAGE COMP-1. 02 TIY USAGE COMP-1. 02 TCR PIC S9(8) USAGE IS BINARY. 02 TCG PIC S9(8) USAGE IS BINARY. 02 TCB PIC S9(8) USAGE IS BINARY. 02 TFONTFAM PIC X(16). 02 TFONTSIZ USAGE COMP-1. 02 TFONTPRP PIC X(4). *
Columns Anchors
Typically, a Column anchor will provide a maximum of 20 float numbers which are supposed to specify a set column widths for building nice looking tables within PDFs. The idea is to have those features provided externally so that a slight modification on a column width for functional reasons would not require recompilation of a program. These kind of small layout details may be then driven externally.
Below is a list of rules for using this columns anchor feature:
- An FPDF4ZOS context may contain no more than a maximum number of columns anchors specified in configuration file (key=MX_NBCOL). This maximum number refer to all columns anchors across all forms.
- If two columns anchors bear the same identifier, the first one wins, meaning the subsequent columns anchors with that very name will be dropped.
In C language, the structure below defines columns anchor properties.
typedef struct columns ??< char col_id ??(8+1??); /* Reference point ID */ float colls ??(20??); /* Columns width */ ??> columns;
In COBOL language, the structure below defines anchor properties.
01 COLUMNS 02 COLID PIC X(12). 02 COLLS00 USAGE COMP-1. 02 COLLS01 USAGE COMP-1. 02 COLLS02 USAGE COMP-1. 02 COLLS03 USAGE COMP-1. 02 COLLS04 USAGE COMP-1. 02 COLLS05 USAGE COMP-1. 02 COLLS06 USAGE COMP-1. 02 COLLS07 USAGE COMP-1. 02 COLLS08 USAGE COMP-1. 02 COLLS09 USAGE COMP-1. 02 COLLS10 USAGE COMP-1. 02 COLLS11 USAGE COMP-1. 02 COLLS12 USAGE COMP-1. 02 COLLS13 USAGE COMP-1. 02 COLLS14 USAGE COMP-1. 02 COLLS15 USAGE COMP-1. 02 COLLS16 USAGE COMP-1. 02 COLLS17 USAGE COMP-1. 02 COLLS18 USAGE COMP-1. 02 COLLS19 USAGE COMP-1. *
Graphic Anchors
Typically, a graphic anchor will provide a location as a pair of [X,Y] coordinates, an optional line thickness and foreground / background colors respectively for Draw and Fill instructions.
Below is a list of rules for using this graphic anchor feature:
- An FPDF4ZOS context may contain no more than a maximum number of graphic anchors specified in configuration file (key=MX_NBDRP). This maximum number refer to all graphic anchors across all forms.
- If two graphic anchors bear the same identifier, the first one wins, meaning the subsequent graphic anchor with that very name will be dropped.
In C language, the structure below defines graphic anchor properties.
typedef struct drawprop
begin
char drp_id ??(8+1??); /* Reference point ID */
float p_x; /* X position (in current unit) */
float p_y; /* Y position (in current unit) */
float l_w; /* Line width (in current unit) */
int fc_r; /* Foreground line color (RGB) */
int fc_g; /* with which lines will drawn */
int fc_b;
int bc_r; /* Background line color (RGB) */
int bc_g; /* for filling areas */
int bc_b;
end drawprop;
In COBOL language, the structure below defines anchor properties.
01 DRAWPROP.
02 DRPID PIC X(12).
02 DPX USAGE COMP-1.
02 DPY USAGE COMP-1.
02 DLW USAGE COMP-1.
02 DFCR PIC S9(8) USAGE IS BINARY.
02 DFCG PIC S9(8) USAGE IS BINARY.
02 DFCB PIC S9(8) USAGE IS BINARY.
02 DBCR PIC S9(8) USAGE IS BINARY.
02 DBCG PIC S9(8) USAGE IS BINARY.
02 DBCB PIC S9(8) USAGE IS BINARY.
*