FlushPdf: Creates a PDF `[ 67 ]`

Description

Creates a PDF file which reflects all the commands which have been issued to FPDF4ZOS core engine either since the NewPdfy() was called or since a precedent FlushPdf() function was called. This function takes 4 parameters:

filename ⇒ character string pointing at the name of the PDF file to be created. For MVS, it may be a DDNAME defined in a Job: in that case, this DDNAME must be prefixed by character string "DD:". It can also be a file within z/OS native unix space keeping in mind that only absolute names starting with "/" are supported.
flag ⇒ integer which may take 2 values:
- 2 ⇒ creates a PDF file and free all resources allocated for processing when NewPdfy() was invoked.
- 0 ⇒ creates a PDF file while retaining resources allocated when NewPdfy() was invoked. This option is handy when a program ought to create dozens or thousands of similar PDFs -- see developper notes below.
String #1 ⇒ character string which will appear in a monthly log file. Usually, this string is supposed to identify a customer on behalf of which PDF(s) is(are) created.
String #2 , same as above. Usually, this string is supposed to identify the program name which creates this (or these) PDF(s).

Developper Notes:

When a program must create thousands over thousands of similar PDF, generally to be subsequently zipped for archiving purposes, this function may save tremendous CPU power by a good usage of its flag parameter. Consider the following scenario: 20000 documents must be created on a one PDF per document basis. Let us further assume that this document involves a form as well as a logo. Running successive sequences of NewPdfy() and Output() function would require invoking 20000 times NewPdfy(), reading 20000 times the same parameter file and reading again 20000 times the same form and the same logo.
This FlushPdf() function enables the program to invoke only once the NewPdfy() routine which will read only once the parameter file; down the line, the form and the logo files will also be read once. Indeed, when this function is invoked with a flag equal to false, all resources are kept in the PDF context and in this scenario, this FlushPdf() function should be invoked 20000 thousands times with a flag equal to false.
However, at the end of the program, this FlushPdf function MUST be called a last time with flag=2 value and an empty string as a file name. This will enable first and foremost the engine to free allocated resources, especially memory. Furthermore, it will also enable logging into the monthly file.
For the record, Function Output (file_name) is strictly equivalent to FlushPdf (file_name, 2, "", "");

C calling syntax

int FlushPdf (char *filename, int flag, char *cust_id, char *prgm_name)

Cobol calling syntax

Call "FlushPdf" using filename, flag, cust_id, prgm_name.

C sample code

#include   "fpdf.h"

static char   f_ini ??(??) = ??< "ini??/??/demofpdf.ini" ??>;
static char   f_out ??(??) = ??< "pdf??/??/demo_c.pdf" ??>;

/* ----------------------------------------------------------------- */

int  main (int argc, char *argv [])

??<

NewPdfy (f_ini, 1);
SetCompression (false);
AddPage("P");
SetFont ("Times", "B", 24);
Text (20, 25, "FPDF4ZOS for mass production #1");
AddPage("P");
SetFont ("Times", "B", 24);
Text (20, 25, "FPDF4ZOS for mass production  #2");
SetAuthor ("GMK - inspired by PHP fpdf package");
SetCreator ("Creator for FPDF4ZOS basics");
SetTitle ("Title for FPDF4ZOS basics");
SetSubject ("Subject for FPDF4ZOS basics");
SetKeywords ("FPDF4ZOS,Basics,GMK,Aba,Ima");
SetDisplayMode ("fullpage", "two", "0");
FlushPdf (f_out, 2, "CUSTOMER", "demo_c");

??>

Cobol sample code

Procedure division.
           Set Pt0 to Address of T0.
           Set Pt1 to Address of T1.
           Set Pt2 to Address of T2.
      *
           String 'DD:FINI' Low-Value delimited by size into T0.
           Move 2 to I.
           Call "NewPdfy" Using by value Pt0, I returning PdfRC.
      *
           Move 0 to FLAG.
           Call "SetCompression" Using by value FLAG.
           String 'P' Low-Value delimited by size into T0.
           Call "AddPage" Using by value Pt0.
      *
           Move  20 to W.
           String 'Arial' Low-Value delimited by size into T0.
           String 'N' Low-Value delimited by size into T1.
           Call "SetFont" Using by value Pt0, Pt1, W.
      *
           String 'FPDF4ZOS for mass production' Low-Value delimited by size into T0.
           Move   20 to X.
           Move   25 to Y.
           Call "Text" Using by value X, Y, Pt0.
      *
           String 'GMK - inspired by PHP fpdf package' Low-Value delimited by size into T0.
           Call "SetAuthor" Using by value Pt0.
           String 'Creator for FPDF4ZOS basics' Low-Value delimited by size into T0.
           Call "SetCreator" Using by value Pt0.
           String 'Title for FPDF4ZOS basics' Low-Value delimited by size into T0.
           Call "SetTitle" Using by value Pt0.
           String 'Subject for FPDF4ZOS basics' Low-Value delimited by size into T0.
           Call "SetSubject" Using by value Pt0.
           String 'FPDF4ZOS,Basics,GMK,Aba,Ima' Low-Value delimited by size into T0.
           Call "SetKeywords" Using by value Pt0.
      *
           String 'fullpage' Low-Value delimited by size into T0.
           String 'two' Low-Value delimited by size into T1.
           String '0' Low-Value delimited by size into T2.
           Call "SetDisplayMode" Using by value Pt0,Pt1,Pt2.
      *
           Move 2 to Flag.
           String  'DD:FOUT' Low-Value delimited by size into T0.
           String  'CUSTOMER' Low-Value delimited by size into T1.
           String  'DEMOCBL0' Low-Value delimited by size into T2.
           Call "FlushPdf" using by value Pt0, FLAG, Pt1, Pt2
      *

Description of sample code

This piece of code illustrates the properties setting functions found in FPDF4ZOS interface.  It opens a PDF context, inserts a page, configures a  font, writes a short string, set miscellanous properties of document and flushes result on a PDF file.
- NewPdfy()        -->  Initialisation of a pdf context
- AddPage()        -->  As it says
- SetFont()        -->  set current font
- Text()           -->  Write a piece of Text at position [x,y]
- SetCompression() -->  Instructs that PDF streams will not be compressed
- SetAuthor()      -->  Set Author property within PDF document
- SetSubject()     -->  Set Subject property within PDF document
- SetCreator()     -->  Set Creator property within PDF document
- SetTitle()       -->  Set Title property within PDF document
- SetKeywords()    -->  Set Keywords property within PDF document
- SetDisplayMode() -->  Set Initial display behavior upon opening the PDF document
- FlushPdf()       -->  Output PDF file taking into account all the instructions invoked since NewPdfy or previous FlushPdf

See sample source code in 'C' as well as PDF execution result - NB: For encrypted PDFs, user password is USER-PSWD

FlushPdf: Creates a PDF [ 67 ]

FlushPdf: Creates a PDF `[ 67 ]`