Image: Insert a JPEG Image `[ 7 ]`

Description

Inserts an image at a given position while specifying image width and height. There is also a possibility to make this image clickable by providing a valid URL. This function takes 7 parameters:

FNAM ⇒ character string pointer which specifies image name - see notes #1 and #2 below
X ⇒ float number which specifies abscissa of image top left corner position.
Y ⇒ float number which specifies ordinate of image top left corner position.
W ⇒ float number which specifies image width - see note #3 below.
H ⇒ float number which specifies image height - see note #3 below.
TYPE ⇒ Image type; at the moment, should be "jpg"
LINK ⇒ character string containing either an empty string for a non clickable image or a valid UR for a clickable one

Developper Notes:

Images are supposed to be located in a library the name of which is specified in FPDF4ZOS configuration file taken into account upon initialisation function NewPdfy(). The way this library is managed depends on the operational environment:
- For maintframes or z/OS platforms, this library is supposed to be either a PDS or a PDSE where each member refers at a specific image. Consequently, file name lengths are limited to 8 characters so as to comply with z/OS file naming rules. Obviously, this library should be defined as a Variable Length one (say RECFM=VB) and should contain binary data.
- Furthermore, for mainframe environment, it is not possible to give a DDNAME in the first parameter, nor a file located in native Unix space.
- For Windows and Unix-Linux platforms, this library is supposed to be a directory where each file points at a specific image. They are supposed to have a ".jpg" extension but for obvious compatibility issues with MVS environment, program ought to give only the base name of the file (which means name without extension). FPDF4ZOS engine automatically adds the ".jpg" extension to retrieve image content. Finally, developpers attention is drawn to the fact that unlike Windows, Unix-Linux are case sensitive machines for file names.
It is also possible to provide an absolute file name when it is required to insert images which, for various reasons, are NOT located within an image library. FPDF4ZOS engine considers that when file name length is greater than 8 characters, it is an absolute file name while it is assumed to be an element of the image library otherwise.
There are 4 possibilities for specifying image size, say its width and height:
1. W = 0 - H = 0 ⇒ Image size will be the native one specified within JPG file.
2. W > 0 - H = 0 ⇒ Image width will be the one specified while its height will be automatically adjusted to keep original image proportions.
3. W = 0 - H > 0 ⇒ Image height will be the one specified while its width will be automatically adjusted to keep original image proportions.
4. W > 0 - H > 0 ⇒ Image height and width will be the ones specified regardless of original image proportions. Although valid, this combination is not recommanded as it would likely lead to undesired image skewing.

C calling syntax

void Image (char *filename, float x, float y, float w, float y, char *type, char *slink)

Cobol calling syntax

Call "Image" using by value FILENAME,X,Y,W,H,TYPE,SLINK)

C sample code

#include   "fpdf.h"

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

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

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

??<
int    ii, jj;
char   *ptr;

NewPdfy (f_ini, 1);
jj = P_MODIFY + P_ANNOT_FORMS;
SetProtection (jj, "USER-PSWD", "OWNER-PSWD");
for (ii = 0; ii < 9; ii ++)
    begin
    AddPage("L");
    jj = PageNo ();
    sprintf (buf0, "numbers%d", jj);
    if ((ii & 1) == 0)
       ptr = "";
    else
       ptr = "http://www.cnn.com";
    Image (buf0, 50, 20, 200, 0, "jpg", ptr);
    sprintf (buf0, "Page %d", jj);
    Bookmark (buf0, 0, 0);
    end

Output (f_out);
??>

Description of sample code

This piece of code illustrates various functions found in FPDF4ZOS interface.  It opens a PDF context and specifies that the document ought to be protected at both levels: 
- It requires from users to key the string USER-PSWD in order to be able to read the document => encryption at user level.
- It further encodes the document at owner level, forbidding Print and copy-paste features.  In order to change these protections, a user should key password OWNER-PSWD.

Program then performs a loop on 9 pages in each of which a different image is inserted.  Note that in the even pages, the image carries a link to web site www.cnn.com.  The following functions are used in this piece:
- NewPdfy()         --> Initialisation of a pdf context
- AddPage()         --> As it says
- SetProtection()   --> Instruct that PDF is to be protected at user and owner levels
- Image()           --> Insert an image into a PDF document
- Bookmark()        --> Insert an bookmark into a PDF document
- PageNo()          --> Retrieve current page number while building 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

Image: Insert a JPEG Image [ 7 ]

Image: Insert a JPEG Image `[ 7 ]`