General Developper Notes

Development tool – Code::Blocks:

The lion share of development work has been carried out on a PC with Code::Blocks IDE tool as a C compiler.  Once programs have been found to work correctly on suc a PC platform, they were transferred to either MVS or Linux together with whatever resources they may use, say Forms, Images, Configuration files, Data files, etc.  For the record, after recompilation and link edition, they ran almost immediately as expected on target servers.  The most frequent issues popping up being related to:

• either {ASCII –> EBCDIC} mistranscoding for MVS platforms
• or uppercase-lowercase recurent problems in Linux vs Windows file naming as well as slash / antislash separation characters.

Coding considerations:

Recalling the starting point which was a PHP class, moving to ‘C’ language involved a significant number of changes: for example, a case in point has been variable declaration and memory allocation which PHP layers handle automatically underneath and ‘C’ doesn’t.  Consequently, constructor mechanism found in original PHP class has been replaced by NewPdfy() initialisation function which takes into account a configuration file.

Strings:

Core FPDF4ZOS engine is coded in C and therefore, in the interface proposed and described in reference manual, all strings are always assumed to be null terminated.  This statements also holds also for both Cobol and PL/I interface.

Trigraph usage:

For those curious enough to have a glance at the source code which comes with the library, they may be surprised as most braces as well as bracket characters have systematically been replaced by strange combinations such as ??(, ??), ??<, ??>.  These characters set are known as trigraph sequences and are used for ‘C’ coding in mainframe environments for which so called 3270 terminals have been the only data entry and display device for decades.  On such a classical 3270 keyboard, there were neither brackets nor braces keys.  For further information on trigraph sequences, see wikipedia.

FPDF4ZOS is multiplatform:

This library has been developed so that it can execute on several machines.  Therefore, it is also available in Windows as a DLL as well as in Linux-Unix as a library (libfpdf.so).  Since it is relatively easy to install and run PHP programs in these two environments, the benefits of using this new component might not be as high as it is for MVS [2].

Nevertheless, the code is here and has been successfully tested and qualified under both Windows and Unix-Linux environments.  Besides, if significant efforts are invested in developing forms and programs in MVS, the fact that the work thus done may be transported on a “lighter” platform and run “as is” in case of a downsizing move is an important consideration in picking up a solution for building documents.

As a matter of fact, investments done in AFP overlays and pagedef development are not easily migrated to Linux-Unix – an understatement – when a company does decide to downsize.

MVS specific:

PDF files to be built may be either PS (sequential files) or PDS members (PDS=Partionned Data Set) or even files in Unix system environment available from z/OS.  Besides, they can be specified as DDNAME provided their 8 character names are prefixed by “DD:”.  For example, a DDNAME specified in a JCL file by the following line:

//FOUT     DD DSN=S01.DEMOFPDF.PDF,DISP=SHR

should be referred by DD:FOUT in calling program.

When PDF files to be created are members of a PDS or a PDSE, this PDS or PDSE must already be existing.  FPZF4ZOS will never allocate by itself a PDS or a PDSE.  However,  when PDF files to be created are sequential (say PS), they are dynamically allocated by the engine according to information retrieved from configuration file.  In that file, there is a specific parameter section dedicated to MVS which defines file features to be taken into account when creating PDF sequential files: RECFM for RECord ForMat (NB: ‘VB’ is strongly recommended), LRECL for Logical RECord Length, BLKSIZE for BLocK SIZE and UNIT for storage disk Unit.

For international usage, a customized EBCDIC to ASCII transcoding file may also be specified.  Refer to configuration file page for more information.