AttachFile: Import an external file   [ 59 ]

This function enables a program to import an external file as PDF embedded data.  In target position, a kind of link will appear in the document on which readers will be able to double-click in order to view data which have been imported. For services provider, this function enables companies to offer the best of two worlds when official reports are generated: on the one hand, an unmodifiable PDF document which will display data as required and onthe other hand an additional embedded document with which customers will be able to extract data to further process information relevant to its many needs.  For example, an Excel file for this secondary document while there is no risk of user modifying the Excel file since its reference will remain the one embedded in the PDF which has been delivered.

This function takes 9 parameters:

1. Pointer to a string character which is the name of a file containing data to be imported.  For z/OS environment, this may be a PS, a member of a PDS, a file located in Unix space (absolute name) or even a DDNAME if it starts with "DD:".  For Windows-Linux environments, it is recommanded to enforce absolute names as current directory may eventually not be known in advance.
2. Pointer to a string character which is the name of embedded data as it will appear within PDF.  It is important to specify here an extension which is usually associated with data type; say ".txt" for text files, ".xlsx" for Excel files, ".html" for HTML files, even ".pdf" for secondary PDF files etc.  Otherwise, the double click action may not work properly.
3. Integer number which specifies the page number in which the link to embedded data will appear.
4. Float number which specifies the X position where the link will be located
5. Float number which specifies the Y position where the link will be located
6. Pointer to a string character (= either "Y" or "N") which indicates whether or not data is to be transcoded from EBCDIC to ASCII - z/OS only.
7. Pointer to a string character (= either "Y" or "N") which indicates whether or not each line of data should be appended with a LineFeed (LF) when data embedding takes place - z/OS only.
8. Pointer to a string character (= either "Y" or "N") which indicates whether or not each line of data should be stripped of its rightmost space characters when data embedding takes place - z/OS only.
9. Last parameter is deprecated.

Developper Notes:

1. Parameters #6, #7 & #8 are significant for MVS platforms only in order to deal with the specifities of that platform: EBCDIC coding, no line separator so common in ASCII machines, and very frequent File format featuring Fixed lenght records (RECFM=F), with countless unused white spaces in rightmost characters.
2. By default, the maximum number of PDF attachments is 4.  This default value can be modified in configuration file by mean ot key MX_MBATT .
3. Data found in attachments followed the same rules as regular streams.  If streas are compressed and / or protected, embedded data will likewise be compressed and / or protected.

#include   "fpdf.h"

static char   f_ini ??(??) = ??< "ini??/??/demofpdf.ini" ??>;
static char   f_out ??(??) = ??< "pdf??/??/demo_g.pdf" ??>;
static char   bufr ??(128??);
static char   file_txt ??(??) = ??< "data/embeddedData.txt" ??>;
static char   file_htm ??(??) = ??< "data/embeddedData.htm" ??>;
static char   filexlsx ??(??) = ??< "data/embeddedData.xlsx" ??>;

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

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

??<

NewPdfy (f_ini, 1);
AddPage ("P");
SetFont ("Arial", "BI", 20);
strcpy (bufr, "Illustration of Annotations and Embedded data");
Text (20, 25, bufr);

SetFont ("Arial", "N", 16);
strcpy (bufr, "Text Type Annotation example - Note Icon");
Text (20, 50, bufr);
AddAnnot (20 + GetStringWidth (bufr) + 10, 40, 10, 6, "Annotation #1 content from demo_g",
          "Text", "Note", "Annotation #1 title", "0 0 1", "");

SetFont ("Arial", "I", 16);
strcpy (bufr, "Link Type Annotation example - Key Icon");
Text (20, 70, bufr);
AddAnnot (20 + GetStringWidth (bufr) + 10, 65, 10, 6, "Annotation #2 content from demo_g",
          "Link", "Key", "Annotation #2 title", "0 1 0", "");

SetFont ("Courier", "N", 16);
strcpy (bufr, "Circle Type Annotation example - Help Icon");
Text (20, 90, bufr);
AddAnnot (20 + GetStringWidth (bufr) + 10, 95, 10, 6, "Annotation #3 content from demo_g",
          "Circle", "Help", "Annotation #3 title", "1 1 0", "");

SetFont ("Courier", "N", 16);
strcpy (bufr, "Square Type Annotation example - Help Icon");
Text (20, 110, bufr);
AddAnnot (20 + GetStringWidth (bufr) + 10, 105, 10, 6, "Annotation #4 content from demo_g",
          "Square", "Help", "Annotation #4 title", "1 0 0", "");

SetFont ("Courier", "A", 16);
Text (20, 155, "Embedded Text Data :");
AttachFile (file_txt, "EmbeddedData.txt", 1, 100, 150, "Y", "Y", "Y", "F");
Text (20, 175, "Embedded HTML Data :");
AttachFile (file_htm, "EmbeddedData.html", 1, 100, 170, "Y", "Y", "Y", "F");
Text (20, 195, "Embedded XLSX Data :");
AttachFile (filexlsx, "EmbeddedData.xlsx", 1, 100, 190, "N", "N", "N", "F");

FlushPdf (f_out, 2, "CUSTZZ", "demo_g");
??>

This programs illustrates annotation as well as embedded data features found in FPDF4ZOS.  It opens a PDF context, insert a page and:
- Put three different annotations
- Attaches three files of different types: Text, HTML, Excel.

The following functions are used in this piece:
- NewPdfy()      -->  Initialisation of a pdf context
- AddPage()      -->  As it says
- SetFont()      -->  Set current font
- Text()         -->  Insert Text at a specific location
- SetMargins()   -->  Specify page margins (left, top, right)
- AddAnnot()     -->  Addan annotation
- AttachFile()   -->  Embed a file within target PDF
- FlushPdf()     -->  Output PDF file taking into account all the instructions invoked since context initialization