PDFinclude PRO

Version 1
Documentation

Prepared by:
PRO-SYS Consultants Ltd.
Gordon Campbell
July 6, 2005

01/09/2006

PDFinclude PRO v1 Documentation

PRO-SYS Document PDFinclude PRO Documentation

Any questions regarding this document should be forwarded to:
PRO-SYS Consultants Ltd.
7220 Montana Road
Richmond, BC, CANADA
V7C 4K3
Phone:

1-604-377-5050 or 1-403-606-0799

E-mail: [email protected] or [email protected]

Progress and OpenEdge are registered trademarks of Progress

Software Corporation.
Adobe PDF is a registered trademark of Adobe Solutions Incorporated.

ii

PDFinclude PRO v1 Documentation

01/09/2006

Document Change Log

As documents are revised, important information is added or removed. Enter
changes in this table so readers know what has changed.
Refer to this table to make sure you havent missed the latest information.

Date
yy/mm/dd

Changed By

Description of Change

Reason for Change

05/07/06

G Campbell

Initial Release

Initial Release

This is the document change log for Project: PDFinclude PRO Documentation.

01/09/2006

PDFinclude PRO v1 Documentation

iii

Table of Contents
1. Introduction...................................................................................7
2. PDFinclude PRO............................................................................8
2.1 Overview..................................................................................................................................8

3. Procedure List.............................................................................10
pdf_bookmark.............................................................................................................................10
pdf_circle....................................................................................................................................10
pdf_close....................................................................................................................................10
pdf_close_path...........................................................................................................................11
pdf_curve....................................................................................................................................11
pdf_Encrypt................................................................................................................................11
pdf_fill_text..................................................................................................................................14
pdf_Font_Diff..............................................................................................................................14
pdf_GetBestFont........................................................................................................................15
pdf_insert_page..........................................................................................................................15
pdf_line.......................................................................................................................................15
pdf_line_dec...............................................................................................................................16
pdf_link.......................................................................................................................................16
pdf_load_font..............................................................................................................................17
pdf_load_image..........................................................................................................................18
pdf_load_xml..............................................................................................................................18
pdf_markup.................................................................................................................................19
pdf_merge_stream.....................................................................................................................19
pdf_move_to...............................................................................................................................20
pdf_new......................................................................................................................................20
pdf_new_page............................................................................................................................21
pdf_new_page2..........................................................................................................................21
pdf_note......................................................................................................................................22
pdf_open_pdf..............................................................................................................................22
pdf_place_image........................................................................................................................23
pdf_place_image2......................................................................................................................23
pdf_rect.......................................................................................................................................24
pdf_rect2.....................................................................................................................................24
pdf_ReplaceTxt..........................................................................................................................25
pdf_reset_all...............................................................................................................................25
pdf_reset_stream........................................................................................................................25
pdf_rgb........................................................................................................................................26
pdf_set_BottomMargin...............................................................................................................26
pdf_set_dash..............................................................................................................................26
pdf_set_FillBlue..........................................................................................................................27
pdf_set_FillGreen.......................................................................................................................27
pdf_set_FillRed...........................................................................................................................27
pdf_set_font................................................................................................................................28
pdf_set_GraphicX.......................................................................................................................28
pdf_set_GraphicY.......................................................................................................................29
pdf_set_info................................................................................................................................29
pdf_set_LeftMargin.....................................................................................................................30
pdf_set_Orientation....................................................................................................................30
pdf_set_PageHeight...................................................................................................................30
pdf_set_PageRotate...................................................................................................................31
pdf_set_PageWidth....................................................................................................................31
pdf_set_PaperType....................................................................................................................31

PDFinclude PRO v1 Documentation

01/09/2006

pdf_set_parameter.....................................................................................................................32
pdf_set_TextBlue........................................................................................................................34
pdf_set_TextGreen.....................................................................................................................34
pdf_set_TextRed........................................................................................................................34
pdf_set_TextX............................................................................................................................35
pdf_set_TextY............................................................................................................................35
pdf_set_tool_parameter.............................................................................................................35
pdf_set_TopMargin....................................................................................................................36
pdf_set_VerticalSpace...............................................................................................................36
pdf_skip......................................................................................................................................36
pdf_skipn....................................................................................................................................37
pdf_stamp...................................................................................................................................37
pdf_stroke_color.........................................................................................................................38
pdf_stroke_fill.............................................................................................................................38
pdf_text.......................................................................................................................................39
pdf_text_align.............................................................................................................................39
pdf_text_at..................................................................................................................................39
pdf_text_boxed_xy.....................................................................................................................40
pdf_text_center...........................................................................................................................40
pdf_text_char..............................................................................................................................41
pdf_text_charxy..........................................................................................................................41
pdf_text_color.............................................................................................................................41
pdf_text_render..........................................................................................................................42
pdf_text_rotate............................................................................................................................42
pdf_text_to..................................................................................................................................42
pdf_text_xy.................................................................................................................................43
pdf_text_xy_dec.........................................................................................................................43
pdf_tool_add...............................................................................................................................43
pdf_use_pdf_page......................................................................................................................44
pdf_Watermark...........................................................................................................................44
pdf_Wrap_Text...........................................................................................................................45

4. Function List................................................................................46
GetXMLNodeValue.....................................................................................................................46
pdf_Angle...................................................................................................................................46
pdf_BottomMargin......................................................................................................................46
pdf_FillBlue.................................................................................................................................46
pdf_FillGreen..............................................................................................................................47
pdf_FillRed.................................................................................................................................47
pdf_Font......................................................................................................................................47
pdf_Font_Loaded.......................................................................................................................47
pdf_FontType.............................................................................................................................48
pdf_get_info................................................................................................................................48
pdf_GetNumFittingChars............................................................................................................48
pdf_get_parameter.....................................................................................................................49
pdf_get_tool_parameter.............................................................................................................49
pdf_get_wrap_length..................................................................................................................49
pdf_GraphicX..............................................................................................................................50
pdf_GraphicY..............................................................................................................................50
pdf_ImageDim............................................................................................................................50
pdf_LeftMargin............................................................................................................................50
pdf_Orientation...........................................................................................................................51
pdf_Page....................................................................................................................................51
pdf_PageFooter..........................................................................................................................51
pdf_PageHeader........................................................................................................................51
pdf_PageHeight..........................................................................................................................52

01/09/2006

PDFinclude PRO v1 Documentation

pdf_PageRotate..........................................................................................................................52
pdf_PageWidth...........................................................................................................................52
pdf_PaperType...........................................................................................................................53
pdf_PointSize.............................................................................................................................53
pdf_Render.................................................................................................................................54
pdf_text_fontwidth......................................................................................................................54
pdf_text_width............................................................................................................................54
pdf_text_widthdec.......................................................................................................................55
pdf_text_widthdec2.....................................................................................................................55
pdf_TextBlue..............................................................................................................................55
pdf_TextGreen............................................................................................................................56
pdf_TextRed...............................................................................................................................56
pdf_TextX...................................................................................................................................56
pdf_TextY...................................................................................................................................56
pdf_TotalPages..........................................................................................................................56
pdf_TopMargin...........................................................................................................................57
pdf_VerticalSpace......................................................................................................................57

5. Internal Procedures and Functions...........................................58

6. Component List...........................................................................60
7. How to Implement Page Headers and Footers.........................61
8. How to Implement Compression...............................................63
9. How to Implement Encryption....................................................64
10. Implementing Tools..................................................................65
10.1 TABLE Tool.........................................................................................................................65
10.2 CALENDAR Tool.................................................................................................................67
10.3 MATRIX Tool.......................................................................................................................71

11. Introducing Complex Forms....................................................75

11.1 Publishing Data to a PDF Template....................................................................................77
11.1.1 Overview.......................................................................................................................77
11.1.2 Modify Your Process(es)..............................................................................................78
11.1.3 Create A Template........................................................................................................81

12. Sports2000 Samples.................................................................86

12.1 Hello World..........................................................................................................................86
12.2 Hello World Compressed and Encrypted.........................................................................86
12.3 Text Positioning...................................................................................................................86
12.4 Customer Listing.................................................................................................................87
12.5 Formatted Item Listing.........................................................................................................90

Appendix A Embedding Fonts...................................................93

Appendix B Creating AFM File...................................................94

PDFinclude PRO v1 Documentation

01/09/2006

1.Introduction
PDFinclude PRO is a Progress include file developed by PRO-SYS Consultants Ltd (PROSYS) to allow Progress developers to output reports in Adobe PDF file format without having to
use third-party tools or utilities.
PDFinclude PRO is a stand-alone component that defines a toolset of Progress functions and
procedures that aid in the output of a PDF file directly from within the Progress 4GL.
PDF files can be read by PDF viewers such as Adobe Reader and PDFView.
The PDF file format is fast becoming an industry-standard for electronic document viewing. The
PDF format allows for documents that can be accessed by a broad range of hardware and
software devices (including PDAs and Internet browsers).
PDFinclude PRO utilizes Progress code that is compliant with versions 9 and 10 of the Progress
4GL.
Some of the benefits of using PDFinclude PRO are:
Consistency

By using the PDF file format, you can present a representation of the
output file in a consistent manner. Use the same PDF file across
multiple devices, platforms and/or software packages.

Easy Implementation

Since PDFinclude PRO is written in Progress 4GL the ability to

implement into your existing (or new) code is easy and seamless.
No external calls are required to third-party products (such as a Perl
script).
PDFinclude PRO can also be used with Progress versions 9 and 10
on UNIX and/or Windows platforms.

Secure Report Output

The PDF file format is a secure format that cannot be easily

changed therefore sensitive reports can be distributed to users
without the worry of them changing reported material.

Configurable

By offering a multitude of different Progress-written PDF related

functions, you can easily configure and determine the outputs
content, object placement and look-and-feel.

Report Viewer Supplied

Since PDF is becoming an industry-standard file format, many

document viewers already exist (such as Adobes Acrobat Reader).
This reduces your development effort by not having to create a
separate Report Viewer.

01/09/2006

PDFinclude PRO v1 Documentation

2.PDFinclude PRO
2.1Overview
As previously mentioned, PDFinclude PRO is written in Progress and consists of a set of
functions. These functions are used in combination to create an output file in PDF format. The
list of procedures and functions and their uses can be viewed in Section 3 and Section 4.
Due to the complexity of the PDF specification and our requirement of having PDF easy to
implement, building a PDF document with PDFinclude PRO involves two different planes or
Spaces as they are called within the PDF specification. The two spaces are the Text Space and
the Graphic Space. Each of the spaces are defined further in preceding sections but the
following items outline the basic space functions.
Text Space:

The Text Space allows you to manipulate and control the where and how text
will appear on the document. The Text Space starts on the top-left hand
corner of the page and moves across and downward.
In fact, this space doesnt actually exist in the PDF specification. It was
created by PRO-SYS to mimic how reports are currently developed using the
Progress 4GL.
Procedures such as pdf_text_to, pdf_text_at use the Text Space. These
procedures use a mimicked Row and Column coordinate system. And these
are really only useful if you use a Fixed width font (such as Courier).

Graphic Space:

The Graphic Space allows you to manipulate and control the drawing of nontextual object such as JPEG Images, Rectangles, Lines, etc. The Graphic
Space start at the bottom-left corner of the page and move up and across.
Text placement can also be used performed on the Graphic Space by using
procedures such as pdf_text_xy, pdf_text_align. These procedures allow you
to specifically use X and Y coordinates and are very useful when dealing with
proportional fonts (such as Arial).

By manipulating and controlling the Spaces, you can create elegant documents that are directly
derived from within your Progress application.
Before using of the following procedures or functions, you must add { pdf_inc.i } to your
Progress program.
The pdf_inc.i include file also accepts an argument. The argument allows you to specify whether
you want to add the pdf_inc.p as a SUPER procedure or not. The following table outlines the
possible options.
Argument

Sample

Description

blank

{ pdf_inc.i }

This will run pdf_inc.p as a SUPER

procedure and associate the
procedure handle with the SESSION
handle.

PDFinclude PRO v1 Documentation

01/09/2006

This is the default action.

THIS-PROCEDURE

{ pdf_inc.i THIS-PROCEDURE }

This will run pdf_inc.p as a SUPER

procedure and associate the
procedure handle with the THISPROCEDURE handle.

Anything Else

{ pdf_inc.i NOT SUPER }

This will run pdf_inc.p as a

PERSISTENT procedure and will not
create the procedure as SUPER.
If this option is used then the
procedure calls must have the
following added to each call IN
h_PDFinc.
For example, you originally had:
RUN pdf_new (Spdf).
now with this option you must
change your call to:
RUN pdf_new IN h_PDFinc (Spdf).

01/09/2006

PDFinclude PRO v1 Documentation

3.Procedure List
This section defines the procedures available within PDFinclude PRO. For each procedure you
are given the required parameters, expected values, sample calls, and a detailed description of
how (and when) the procedure should be used.

pdf_bookmark
Parameters:

Stream as Character
Title as Character
Parent as Integer
Expand as Logical

- Stream name as identified in pdf_new

- Bookmark Description
- 0 or valid Bookmark number
- Expand this bookmark (if parent) Yes/No

OUTPUT:
Bookmark as Integer
Sample Call:

- How thick to draw the circle border (stroke)

RUN pdf_bookmark (Spdf,Customer 0001,0,No,OUPUT vBookmark)

Description:
This procedure allows you to add a bookmark to the PDF document. This will in turn add a
marker that will appear in the Bookmarks section when viewing the PDF document (via Reader).
This allows for easier navigation of the document when viewing.

pdf_circle
Parameters:

Stream as Character
X Coord as Integer
Y Coord as Integer
Radius as Integer
Weight as Decimal

- Stream name as identified in pdf_new

- Graphic X Coordinate
- Graphic Y Coordinate
- Radius of Circle
- How thick to draw the circle border (stroke)

Sample Call:

RUN pdf_circle (Spdf,10,10,100,0.5)

Description:
This procedure will draw a circle at the specific X/Y coordinate. The X/Y coordinate represent the
center point of the circle and also become the new Graphic X/Y points after drawing the circle.
This procedure uses the colours set by the pdf_stroke_color and pdf_stroke_fill.

pdf_close
Parameters:

Stream Name as Character

Sample Call:

RUN pdf_close (Spdf)

- Stream name as identified in pdf_new

Description:

10

PDFinclude PRO v1 Documentation

01/09/2006

This procedure closes the identified PDF stream and generates the PDF document that was
identified in the pdf_new procedure.

pdf_close_path
Parameters:

Stream Name as Character

Sample Call:

RUN pdf_close_path (Spdf)

- Stream name as identified in pdf_new

Description:
This procedure output a B element. This will basically stroke and fill anything that has been
drawn on the graphic plane. Not usually required but in certain circumstances may be needed.

pdf_curve
Parameters:

Stream as Character
X1 Coord as Integer
Y1 Coord as Integer
X2 Coord as Integer
Y2 Coord as Integer
X3 Coord as Integer
Y3 Coord as Integer
Weight as Decimal

- Stream name as identified in pdf_new

- Graphic X1 Coordinate
- Graphic Y1 Coordinate
- Graphic X2 Coordinate
- Graphic Y2 Coordinate
- Graphic X3 Coordinate
- Graphic Y3 Coordinate
- How thick to draw the circle border (stroke)

Sample Call:

RUN pdf_curve (Spdf,10,10,100,200,200,100,0.5)

Description:
This procedure add a Bzier curve is added from the current Graphic X/Y Location to X3/Y3
using X1/Y1 and X2/Y2 as the control points. The X3/Y3 of the curve becomes the new Graphic
X/Y Location.
This procedure uses the colours set by the pdf_stroke_color and pdf_stroke_fill.

pdf_Encrypt
Parameters:

Stream Name as Character

Master Password as Character
User Password as Character
Access List as Character
Encryption Key as Integer
Encryption Mode as Character
Silent Encryption as Logical

Sample Call:

RUN pdf_Encrypt (Spdf,gord1,gord,,128,COM,TRUE)

01/09/2006

- Stream name as identified in pdf_new

- The PDF documents Master Password
- The PDF documents User Password
- List identifying Access Rights
- 40 or 128 Bit Encryption Key Length
- COM, SHARED or OS
- TRUE OR FALSE

PDFinclude PRO v1 Documentation

11

Description:
This procedure allows you to encrypt a generated PDF document. The call to this procedure can
occur anywhere between the appropriate pdf_new and pdf_close procedures.
This procedure call integrates with PDFpsp.w (another external procedure). PDFpsp.w uses a
commercial product called Pretty Safe PDF (PSP) from PDFlib GmbH. The PSP product can be
downloaded from www.pdflib.com. PRO-SYS has is a reseller of all PDFlib GmbH products and
we offer PEG members a discount. For more information go to www.epro-sys.com. The discounts
will only be applied by PRO-SYS. PDFlib GmbH will not honour the discounts, so orders must be
directed to PRO-SYS Consultants Ltd.
The following table outlines the parameters in further detail:

12

PDFinclude PRO v1 Documentation

01/09/2006

Parameter

Description

Stream Name

Must be a valid Stream Name as created in the procedure see calls to

pdf_new to identify valid stream names.

Master Password

The Master Password must be a maximum of 32 characters. A blank

password is valid.
The Master Password allows you to associate a password to protect the
documents security settings. This password must be entered to access
the Document Security. This password also allows entry to the documents
contents.

User Password

The User Password must be a maximum of 32 characters. A blank

password is valid.
The User Password allows you to associate a password to protect the
documents contents. This password must be entered to access the
Document.

Access List

The Access list can be blank or a comma-delimited list of access

prevention rights. If blank, the document has full access rights (default).
If non-blank, then only specific items will be allowed when the document
is viewed. The following table outlines the valid entries for the commadelimited list:
Code

Description

noprint
nohiresprint
nomodify
nocopy
noannots

Prevent Printing of the File

Prevent High Resolution Printing
Prevent Adding Form Fields & Other Changes
Prevent Copying and Extracting Text or Graphics
Prevent Adding or Changing Comments or Form
Fields
Prevent Filling of Form Fields
Prevent Extraction of Text or Graphics
Prevent Inserting/Deleting/Rotating Page, Bookmarks

noforms
noaccessible
noassemble

Encryption Key
Length

This value can either be 40 or 128. This value represents the length of the
Encryption Key (in bits). 128 Bit encryption is currently the strongest
encryption available.

Encryption Mode

PSP can be run via a few different options. The options available vary by
Operating System. The following table outlines the values and the
Operating System that they can be used with.

01/09/2006

Mode

OS

Description

COM

Windows

SHARED

Windows, *NIX

Uses the COM version of PSP.

Accessed via a COM-Handle.
Uses the DLL (for Windows) or Shared
Library (for *NIX). Accessed via
Functions calls defined in PSP.i and
PSPbind.p.

PDFinclude PRO v1 Documentation

13

pdf_fill_text
Parameters:

Stream Name as Character

Form FieldName as Character
Field Text as Character
Field Options as Character

- Stream name as identified in pdf_new

- Name of a valid Font
- Integer value of the Character to change
- Postscript Character name

Sample Call:

RUN pdf_fill_text (Spdf, InvoiceNumber,00001,)

Description:
This procedure is used in conjunction with the pdf_open_pdf and pdf_use_pdf_page procedures.
If youve opened and existing PDF document and then used a page within your new document
then you may be able to publish data to any Adobe Form Fields that appear within that used
page. If no Form Fields are available, or you publish a field name that doesnt exist, then no data
will be added to your form.
The last parameter options, allows you to perform some additional processing if the form field is
found. The two options currently available are:
Align=LEFT|CENTER|RIGHT
Multiline
The Align option allows you to programmatically set how you want the field contents aligned
when the field value is displayed.
The MultiLine option allows you to tell the program to fit as many lines of text into the specified
region of the Form Field as possible.
For more information on this functionality, see the section called Introducing Complex Forms.

pdf_Font_Diff
Parameters:

Stream Name as Character

Font Name as Character
Character Number as Integer
Postscript Name as Integer

- Stream name as identified in pdf_new

- Name of a valid Font
- Integer value of the Character to change
- Postscript Character name

Sample Call:

RUN pdf_font_diff (Spdf, 190,/nsuperior)

Description:
This procedure allows you to dynamically change the character mapping for a given character in
a specified Font Name. This is useful when you have previously created text files that include
high ASCII character values that are used for graphic line drawing. For example, you use ASCII
character 196 to draw a horizontal line. When you look at the actual text file you wont see a
horizontal line you will see a funny looking binary character. Using this procedure, you can
redefine how PDFinclude handles that character you can have it remapped to a horizontal line
(Postscript name is SF100000).

14

PDFinclude PRO v1 Documentation

01/09/2006

pdf_GetBestFont
Parameters:

Sample Call:

Stream Name as Character

Font Name as Character
I/O Text as Character
I/O FontSize as Decimal
change
Smallest Size as Decimal
Chop Text Name as Logical
From X as Decimal
To Y as Decimal

- Stream name as identified in pdf_new

- Name of a valid Font
- Integer value of the Character to change
- Integer value of the Character to
- Postscript Character name
- Postscript Character name
- Postscript Character name
- Postscript Character name

RUN pdf_GetBestFont
(Spdf,
Arial,
INPUT-OUTPUT cText,
INPUT-OUTPUT dFontSize,
1.0,
No,
100.0,
200.0)

Description:
This procedure calculates the best font size to use to insert text into a given range along the X
axis - tests in 0.5 point size increments. You can specify whether or not you want the text
truncated or not (within the given range).

pdf_insert_page
Parameters:

Stream Name as Character

Page Number as Integer
Where as Character

- Stream name as identified in pdf_new

- Non-zero Integer value of the page to insert
- Insert the page Before or After the page #

Sample Call:

RUN pdf_insert_page (Spdf,1,AFTER)

Description:
This procedure allows you to insert a page anywhere in the stream while you are still building the
document.
This is useful if you wanted to add a table of contents to your document. You could build your
document as is but track the TOC elements then at the end of your document generation (and
before running pdf_close) insert the TOC page as Page 1.

pdf_line
Parameters:

01/09/2006

Stream Name as Character

From Column Point as Integer

- Stream name as identified in pdf_new

- A non-zero integer value representing the

PDFinclude PRO v1 Documentation

15

lines columnar starting point

- A non-zero integer value representing the
lines row starting point
To Column Point as Integer
- A non-zero integer value representing the
lines columnar ending point
To Row Point as Integer- A non-zero integer value representing the
lines row ending point
Line Weight as Decimal
- A non-zero decimal value representing the
width that the line should be drawn with (a
higher number indicates a thicker line)
From Row Point as Integer

Sample Call:

RUN pdf_line (Spdf,10,10,10,600,2,0.5)

Description:
This procedure allows you to draw a line from a given starting point to a specified end point. You
can determine the color of the line by using the pdf_stroke_color procedure. You can also
change the appearance of the line by using the pdf_set_dash procedure.

pdf_line_dec
Parameters:

Stream Name as Character

- Stream name as identified in pdf_new
From Column Point as Decimal - A non-zero decimal value representing the
lines columnar starting point
From Row Point as Decimal
- A non-zero decimal value representing the
lines row starting point
To Column Point as Decimal
- A non-zero decimal value representing the
lines columnar ending point
To Row Point as Decimal
- A non-zero decimal value representing the
lines row ending point
Line Weight as Integer
- A non-zero decimal value representing the
width that the line should be drawn with (a
higher number indicates a thicker line)

Sample Call:

RUN pdf_line_dec (Spdf,10.0,10.0,10.0,600.0,2.0,0.5)

Description:
This procedure allows you to draw a line from a given starting point to a specified end point. You
can determine the color of the line by using the pdf_stroke_color procedure. You can also
change the appearance of the line by using the pdf_set_dash procedure.
This differs from pdf_line in that it uses decimal values for the X/Y coordinates. This allows for
more exact positioning/drawing of the line.

pdf_link
Parameters:

Stream Name as Character

From X as Integer
From Y as Integer

16

- Stream name as identified in pdf_new

- A non-zero integer value representing the
X axis starting point
- A non-zero integer value representing the
Y axis starting point

PDFinclude PRO v1 Documentation

01/09/2006

Link Width as Integer

Link Height as Integer
Link Text as Character
Text Red as Integer
Text Green as Integer
Text Blue as Integer
Link Border as Integer
Link Style as Character
Sample Call:

- How wide should the link boundry be?

- How high should the link boundry be?
- Text to appear when link is hovered over
- Red value of RGB Colour
- Green value of RGB Colour
- Blue value of RGB Colour
- Non-negative integer for the border width
- Display style of link

RUN pdf_line (Spdf,10,10,10,600,2)

Description:
This procedure allows you to place a rectangular link boundry into a PDF document. This can be
useful when used with linking a Customer ID to another document that lists all Customer
Invoices.
The link boundry could also be placed around an image (such as a logo image) that once clicked,
could redirect someone to your corporate webpage.
Possible Style values are:
N No highlighting (blank)
I Invert the contents of the link
O Invert the links border
P Display a down (or Pushed) appearance

pdf_load_font
Parameters:

Stream Name as Character

Font Name as Character
Font File as Character
Font AFM File as Character
Font DIF File as Character

- Stream name as identified in pdf_new

- Unique Font Name (no spaces)
- Location of TTF Font File (uses PROPATH)
- Location of AFM file (uses PROPATH)
- Location of DIF file (uses PROPATH)

Sample Call:

RUN pdf_load_font
(Spdf,Code39,c:\windows\fonts\Code39.ttf,.\code39.afm,)

Description:

01/09/2006

PDFinclude PRO v1 Documentation

17

This procedure allows you to load and embed external fonts for later use. You can use a font by
using the pdf_set_font procedure.
The DIF file is optional and is only used if you want to remap some of the characters. The DIF file
should have a format similar to the following:
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90

/SF100000
/SF110000
/SF010000
/SF030000
/SF040000
/SF080000
/SF090000
/SF060000
/SF070000
/SF050000
/SF430000
/SF240000
/SF510000
/SF520000
/SF390000
/SF220000
/SF210000
/SF250000
/SF500000
/SF490000
/SF380000
/SF280000
/SF270000
/SF260000
/SF360000
/SF370000

The first entry represents the character to replace and the second entry represents the Postscript
name of character to replace it with. The Postscript character names can be found at:
http://partners.adobe.com/asn/tech/type/opentype/appendices/wgl4.jsp

pdf_load_image
Parameters:

Stream Name as Character

Image Name as Character

- Stream name as identified in pdf_new

- Unique Font Name (no spaces)

Sample Call:

RUN pdf_load_image (Spdf,ProSysLogo,logo.jpg)

Description:
This procedure allows you to load and embed and external JEPG image. You can use the
image by using the pdf_place_image procedure. Currently, only JPEG images can be loaded
using this procedure.

pdf_load_xml
Parameters:

18

Stream Name as Character

- Stream name as identified in pdf_new

PDFinclude PRO v1 Documentation

01/09/2006

XML Name as Character

Sample Call:

- XML File Name

RUN pdf_load_image (Spdf,c:\temp\mydata.xml)

Description:
This procedure allows you to load an XML file. The Node Data can then be accessed by
referencing the TT_pdf_xml TEMP-TABLE. Then any of the data values etc can be output to
your PDF document using the appropriate procedures (eg: pdf_text).

pdf_markup
Parameters:

Stream as Character
Text as Character
Title as Character
Style as Character
X1 as Decimal
Y1 as Decimal
X2 as Decimal
Y2 as Decimal
X3 as Decimal
Y3 as Decimal
X4 as Decimal
Y4 as Decimal
Red as Decimal
Green as Decimal
Blue as Decimal

- Stream name as identified in pdf_new

- Text to appear in markup content
- Small title for the Markup content
- Predefined Style set (CASE-SENSITIVE)
- Lower Left X Coordinate
- Lower Left Y Coordinate
- Lower Right X Coordinate
- Lower Right Y Coordinate
- Upper Left X Coordinate
- Upper Left Y Coordinate
- Upper Right X Coordinate
- Upper Right Y Coordinate
- decimal value representing Red colour value
- decimal value representing Green colour value
- decimal value representing Blue colour value

Sample Call:

RUN pdf_markup(Spdf,My Markup Text,My Markup

Title,Highlight,10.0,10.0,20,0,30.0,10.0,100.0,20.0,100.01.0,0.0,0.0)

Description:
This procedure allows you to add a Style at a specific location (actually an area determined by
the X/Y coordinates) on the current PDF page.
The Markup can contain as much as 32K of associated text.
The possible Markup Style are:
Highlight (default)
Underline
Squiggly
StrikeOut

pdf_merge_stream
Parameters:

01/09/2006

Stream From as Character

Stream To as Character
Copies as Integer

- Stream name to copy

- Stream name to copy to
- Number of times to copy

PDFinclude PRO v1 Documentation

19

Sample Call:

RUN pdf_merge_stream (Spdf,Sxxx,1)

Description:
This procedure allows you to copy one stream into another stream. But the two streams must be
generated at the same time (that is, within the same process).
This is useful if you want to create separate documents (say customer invoices) but then have a
summary document that includes all separate documents.

pdf_move_to
Parameters:

Stream Name as Character

To Column Point as Integer

- Stream name as identified in pdf_new

- A non-zero integer value representing a
columnar location that you want to move the
Graphic State cursor to
To Row Point as Integer- A non-zero integer value representing a row
location that you want to move the Graphic
State cursor to

Sample Call:

RUN pdf_line (Spdf,10,10)

Description:
This procedure allows you to dynamically change Graphic State locations within the PDF stream.

pdf_new
Parameters:

Stream Name as Character

File Name as Character

- Stream name as identified in pdf_new

- The name of the PDF file to generate (as it
will be stored on the Operating System)

Sample Call:

RUN pdf_new (Spdf,c:\sports2000\sample.pdf)

Description:

20

PDFinclude PRO v1 Documentation

01/09/2006

This procedure initiates a new PDF stream to create with PDFinclude. The stream name must be
unique and is used by most all other PDFinclude functions and procedures. By adding a stream
name to each of the functions and procedures, we allow you to create multiple (unlimited) PDF
documents from within a single Progress procedure.
When creating a new stream, this procedure loads the PDF Base 14 fonts (a defined set of fonts
including Courier, Helvetica, etc) plus it includes setup of the following default parameters:
Parameter Name

Default Value

Orientation
PaperType
PageWidth
PageHeight
Render
TextX
TextY
Font
FontSize
GraphicX
GraphicY
VerticalSpace
LeftMargin
TopMargin

Portrait
LETTER
612
792
0
0
0
Courier
10
0
0
10
10
50

pdf_new_page
Parameters:

Stream Name as Character

Sample Call:

RUN pdf_new_page (Spdf)

- Stream name as identified in pdf_new

Description:
This procedure initiates a creates a new PDF page to write output to. It also resets the current
TextX, TextY, GraphicX and GraphicY parameters.
Note: The Progress default paging is not used, as is the Header, Footer, Page-Top, PageBottom, Page-Number, and Line-Counter options. Using PDFinclude requires that you control all
output.

pdf_new_page2
Parameters:

Stream Name as Character

Orientation as Character

- Stream name as identified in pdf_new

- Landscape/Portrait

Sample Call:

RUN pdf_new_page2 (Spdf,Landscape)

Description:

01/09/2006

PDFinclude PRO v1 Documentation

21

This procedure initiates a creates a new PDF page to write output to. It also resets the current
TextX, TextY, GraphicX and GraphicY parameters. Plus you can specify what the orientation
should be for the new page.
This allows you to intermix portrait and landscape pages within the same PDF document.

pdf_note
Parameters:

Stream as Character
Text as Character
Title as Character
Icon as Character
LLX as Decimal
LLY as Decimal
URX as Decimal
URY as Decimal
Red as Decimal
Green as Decimal
Blue as Decimal

- Stream name as identified in pdf_new

- Text to appear in note
- Small title for the note header
- Predefined icon set
- Lower Left X Coordinate
- Lower Left Y Coordinate
- Upper Right X Coordinate
- Upper Right Y Coordinate
- decimal value representing Red colour value
- decimal value representing Green colour value
- decimal value representing Blue colour value

Sample Call:

RUN pdf_note(Spdf,My Note Text,My Note

Title,Note,10.0,10.0,20,0,30.0,1.0,0.0,0.0)

Description:
This procedure allows you to add an annotation (or note) at a specific location (actually an area
determined by the LL and UR X/Y coordinates) on the current PDF page.
The note can contain as much as 32K of text. This is useful if you have a large product
description that wont fit on the printed document but youd like to have inserted in the viewable
document.
The possible icon types are:
Note (default)
Comments
Insert
Key
Help
NewParagraph
Paragraph
The icons may differ based on viewer being used.

pdf_open_pdf
Parameters:

22

Stream Name as Character

PDF Name as Character
PDF ID as Character

- Stream name as identified in pdf_new

- PDF File Name and Path (must exist)
- Unique PDF Identifier (eg: Invoice)

PDFinclude PRO v1 Documentation

01/09/2006

Sample Call:

RUN pdf_open_pdf (Spdf,c:\temp\myInvoice.pdf,INV)

Description:
This procedure allows you to open a pre-existing PDF document. This procedure parses the
identified PDF file and determines information about that file.
This procedure basically makes the contents of the existing PDF document available for use
within your new document (see procedure pdf_use_pdf_page).
Very useful if you have an existing blank form (say an Invoice form) that you want to use as the
basis for your page. You can then overlay data (either dynamically or statically) onto the form.
For more information on this, see the section called Introducing Complex Forms.

pdf_place_image
Parameters:

Stream Name as Character

Image Name as Character
Graphic Column as Integer
Graphic Row as Integer
Width as Integer
Height as Integer

Sample Call:

- Stream name as identified in pdf_new

- Valid Image name as pre-loaded with
pdf_load_image function
- Non-zero integer value identifying the
columnar location to begin drawing the image
- Non-zero integer value identifying the row
location to begin drawing the image
- Non-zero integer value representing the
width to render the image at
- Non-zero integer value representing the
height to render the image at

RUN pdf_place_image (Spdf, ProSysLogo,200,16)

Description:
This procedure places a previously loaded image onto the current PDF page at the specified
location.
This differs from pdf_place_image2 in that it originally drew the image above any text elements
therefore obscuring the text.
NOTE: The functionality of PDFinclude has changed so that the placement of elements (text or
graphic) are drawn onto the document as you call them therefore the usage of pdf_place_image2
is not really required but has been maintained for backward compatibility.

pdf_place_image2
Parameters:

Stream Name as Character

Image Name as Character
Graphic Column as Integer

01/09/2006

- Stream name as identified in pdf_new

- Valid Image name as pre-loaded with
pdf_load_image function
- Non-zero integer value identifying the
columnar location to begin drawing the image

PDFinclude PRO v1 Documentation

23

Graphic Row as Integer

Width as Integer
Height as Integer

Sample Call:

- Non-zero integer value identifying the row

location to begin drawing the image
- Non-zero integer value representing the
width to render the image at
- Non-zero integer value representing the
height to render the image at

RUN pdf_place_image (Spdf, ProSysLogo,200,16)

Description:
This procedure places a previously loaded image onto the current PDF page at the specified
location.
This differs from pdf_place_image in that it originally drew the image below any text elements (so
it was useful for using an image as a watermark).
NOTE: The functionality of PDFinclude has changed so that the placement of elements (text or
graphic) are drawn onto the document as you call them therefore the usage of pdf_place_image2
is not really required but has been maintained for backward compatibility.

pdf_rect
Parameters:

Sample Call:

Stream Name as Character

From Column as Integer

- Stream name as identified in pdf_new

- Non-zero integer value identifying the
columnar location to begin drawing the
rectangle
From Row as Integer
- Non-zero integer value identifying the row
location to begin drawing the rectangle
Width as Integer
- Non-zero integer value representing the
width to render the rectangle at
Height as Integer
- Non-zero integer value representing the
height to render the rectangle at
Weight as Decimal
- Value representing how thick a line to draw
RUN pdf_rect (Spdf, 10,10,200,16,0.5)

Description:
This procedure draws a rectangle onto the current PDF page at the specified location using the
specified width and height.
This call uses both the Fill and Stroke colours when building the rectangle.

pdf_rect2
Parameters:

Stream Name as Character

From Column as Integer

From Row as Integer

24

- Stream name as identified in pdf_new

- Non-zero integer value identifying the
columnar location to begin drawing the
rectangle
- Non-zero integer value identifying the row

PDFinclude PRO v1 Documentation

01/09/2006

location to begin drawing the rectangle

- Non-zero integer value representing the
width to render the rectangle at
Height as Integer
- Non-zero integer value representing the
height to render the rectangle at
Weight as Decimal
- Value representing how thick a line to draw
RUN pdf_rect2 (Spdf, 10,10,200,16,0.5)
Width as Integer

Sample Call:
Description:

This procedure draws a rectangle onto the current PDF page at the specified location using the
specified width and height.
This call uses only the Stroke colours when building the rectangle. This is useful if you want to
draw a rectangle but want to see the information (such as an image or text) below the rectangle.

pdf_ReplaceTxt
Parameters:

Stream From as Character

MergeNbr as Character
From Text as Character
To Text as Character

- Stream name to copy

- Stream name to copy to
- Number of times to copy
- Number of times to copy

Sample Call:

RUN pdf_ReplaceTxt (Spdf,1,Invoice,Invoice Copy)

Description:
This procedure is only used in conjunction with the pdf_merge_stream procedure. It allows you
to change text within the stream content.

pdf_reset_all
Parameters:
Sample Call:

None
RUN pdf_reset_all.

Description:
This procedure clears all PDF content for all defined PDF streams.

pdf_reset_stream
Parameters:

Stream Name as Character

Sample Call:

RUN pdf_reset_all.

01/09/2006

- Stream name as identified in pdf_new

PDFinclude PRO v1 Documentation

25

Description:
This procedure clears all PDF content for the named PDF stream.

pdf_rgb
Parameters:

Stream Name as Character

Target Procedure Name
as Character
RGB Color code as Character

- Stream name as identified in pdf_new

- Must be one of: pdf_text_color,
pdf_stroke_color, pdf_stroke_fill
- Must be either a six digit Hex RGB color
code, preceded by 0x, or #, or a nine digit
decimal RGB color code, of the format
RRRGGGBBB.

Sample Call:

RUN pdf_rgb (Spdf, pdf_text_color, 0x006466) /* Hex Teal Green*/

RUN pdf_rgb (Spdf, pdf_text_color, 000100102) /* Decimal Teal Green*/

Description:
This procedure accepts a six digit Hex RGB color code (preceded by 0x, or #, format
RRGGBB), or a Nine digit decimal RGB color code (format RRRGGGBBB) and converts it into
the three PDF RGB colors. It then runs the Target Procedure, passing in these three PDF colors.

pdf_set_BottomMargin
Parameters:

Stream Name as Character

Margin as Integer

- Stream name as identified in pdf_new

- An integer value for the top of the Margin

Sample Call:

RUN pdf_set_BottomMargin (Spdf, 80)

Description:
This procedure allows you to set the height of the Bottom Margin. As soon as the Text Y location
goes greater than the Bottom Margin then a new PDF page is created. This is useful for
formatting a document as it ensures that you dont run text to the bottom of the PDF page.
This procedure is also used in conjunction with the PageFooter functionality (explained
elsewhere). That is, if a PageFooter is defined and the Text Y location is greater than the Bottom
Margin, then the PageFooter is automatically output to the PDF document.

pdf_set_dash
Parameters:

Stream Name as Character

Points On as Integer
Points Off as Integer

26

- Stream name as identified in pdf_new

- An integer value representing how many
points to display
- An integer value representing how many

PDFinclude PRO v1 Documentation

01/09/2006

points not to display

Sample Call:

RUN pdf_set_dash (Spdf, 1,0)

Description:
This procedure allows you to take a solid line (or rectangle) and adjust it to look like a dashed
line. The On/Off parameter options allows you to define the appearance of the dashed line. You
may want to have one short line appear (eg: On=1) then have a fairly large space where the line
doesnt appear at all (eg: Off=10).

pdf_set_FillBlue
Parameters:

Stream Name as Character

Value as Decimal

- Stream name as identified in pdf_new

- Value to set Blue option on RGB Colours

Sample Call:

RUN pdf_set_FillBlue (Spdf,1.0)

Description:
This procedure allows you to individually change the Fill Blue value of the current RGB colour
scheme. That is, if you had previously set the Fill to Black (eg: Red=0, Blue=0, Green=0) then
you can easily change it to use blue fill by running the sample call (as above). Then you can
easily set it back to black by using RUN pdf_set_FillBlue (Spdf,0.0).
Possible Values: Any realistic decimal value between 0.0 and 1.0.

pdf_set_FillGreen
Parameters:

Stream Name as Character

Value as Decimal

- Stream name as identified in pdf_new

- Value to set Green option on RGB Colours

Sample Call:

RUN pdf_set_FillGreen (Spdf,1.0)

Description:
This procedure allows you to individually change the Fill Green value of the current RGB colour
scheme. That is, if you had previously set the fill to Black (eg: Red=0, Blue=0, Green=0) then
you can easily change it to use green fill by running the sample call (as above). Then you can
easily set it back to black by using RUN pdf_set_FillGreen (Spdf,0.0).
Possible Values: Any realistic decimal value between 0.0 and 1.0.

pdf_set_FillRed
Parameters:

01/09/2006

Stream Name as Character

Value as Decimal

- Stream name as identified in pdf_new

- Value to set Red option on RGB Colours

PDFinclude PRO v1 Documentation

27

Sample Call:

RUN pdf_set_FillRed (Spdf,1.0)

Description:
This procedure allows you to individually change the Red Fill value of the current RGB colour
scheme. That is, if you had previously set the fill to Black (eg: Red=0, Blue=0, Green=0) then
you can easily change it to use red fill by running the sample call (as above). Then you can
easily set it back to black by using RUN pdf_set_FillRed (Spdf,0.0).
Possible Values: Any realistic decimal value between 0.0 and 1.0.

pdf_set_font
Parameters:

Stream Name as Character

Font Name as Character

Font Size as Decimal

Sample Call:

- Stream name as identified in pdf_new

- The name of a valid Font (either one of the
PDF 14 Base fonts or a font previously loaded
by the pdf_load_font function)
- The size to display the font with

RUN pdf_setfont (Spdf, Code39,10)

Description:
This procedure allows you to set how the following text will be displayed. All text following this
procedure will appear using the set font until the Font is set back to another font.
The following table defines the names of the PDF Base14 Fonts.
Note: Only 12 are defined right now. We still need to add the WingDings and Symbol Fonts.
Font Name

Description

Courier
Courier-Bold
Courier-Oblique
Courier-BoldOblique
Helvetica
Helvetica-Bold
Helvetica-Oblique
Helvetica-BoldOblique
Times
Times-Bold
Times-Italic
Times-BoldItalic

Fixed-Width Courier Font

Bolded Fixed-Width Courier Font
Italicized Fixed-Width Courier Font
Bolded and Italicized Proportional-Width Helvetica Font
Proportional-Width Helvetica Font
Bolded Proportional-Width Helvetica Font
Italicized Proportional-Width Helvetica Font
Bolded and Italicized Proportional-Width Helvetica Font
Proportional-Width Times Roman Font
Bolded Proportional-Width Times Roman Font
Italicized Proportional-Width Times Roman Font
Bolded and Italicized Proportional-Width Times Roman Font

pdf_set_GraphicX
Parameters:

Stream Name as Character

Value as Integer

Sample Call:

RUN pdf_set_GraphicX(Spdf,300)

28

- Stream name as identified in pdf_new

- Value to set the Graphic X coordinate to

PDFinclude PRO v1 Documentation

01/09/2006

Description:
This procedure allows you to programmatically change the X coordinate of the Graphic drawing
plane.
Similar to pdf_move_to but you only get to set the X coordinate in this procedure.
Possible Values: Any value greater than or equal to 1 and less than or equal to the Page
Width.

pdf_set_GraphicY
Parameters:

Stream Name as Character

Value as Integer

- Stream name as identified in pdf_new

- Value to set the Graphic Y coordinate to

Sample Call:

RUN pdf_set_GraphicY(Spdf,300)

Description:
This procedure allows you to programmatically change the Y coordinate of the Graphic drawing
plane.
Similar to pdf_move_to but you only get to set the Y coordinate in this procedure.
Possible Values: Any value greater than or equal to 1 and less than or equal to the Page
Height.

pdf_set_info
Parameters:

Stream Name as Character

Attribute Name as Character
Attribute Value as Character

- Stream name as identified in pdf_new

- The name of a valid attribute that can be set
- The value you want to assign to the specified
Attribute

Sample Call:

RUN pdf_set_info (Spdf,Author,Gordon Campbell)

Description:

01/09/2006

PDFinclude PRO v1 Documentation

29

This procedure allows you to set values that help you define attributes about the PDF document
itself. The following table outlines the settable attributes:
Attribute

Description

Author
Producer
Creator
Keywords
Subject

Who created the document

What is the primary producer of the document (eg: PDFinclude)
What created the document (eg: The name of your procedure)
Keywords that will help identify the contents of the PDF document
Any phrase that would describe the contents of the document
eg: Accounts Payable
Any phrase that would describe the contents of the document
eg: Vendor Listing

Title

pdf_set_LeftMargin
Parameters:

Stream Name as Character

Margin Value as Character

- Stream name as identified in pdf_new

- The value you want to assign to the Left
Margin

Sample Call:

RUN pdf_set_LeftMargin (Spdf,10)

Description:
This procedure allows you to set the number of points that the document will be indented from the
left-hand edge of the pages boundaries (identified by Page Height and Page Width).

pdf_set_Orientation
Parameters:

Stream Name as Character

Orientation as Character

- Stream name as identified in pdf_new

- How you would like the page oriented

Sample Call:

RUN pdf_set_Orientation (Spdf,Landscape)

Description:
This procedure allows you to define how the page should be displayed upright (Portrait) or
lengthwise (landscape). This value can be set before or after the Page Height or Page Width has
been set but must be set before the call to the pdf_new_page procedure.
Possible Values: Portrait or Landscape (Portrait is the default)

pdf_set_PageHeight
Parameters:

30

Stream Name as Character

Page Height as Integer

- Stream name as identified in pdf_new

- How tall is the page?

PDFinclude PRO v1 Documentation

01/09/2006

Sample Call:

RUN pdf_set_PageHeight (Spdf,792)

Description:
This procedure allows you to define how tall (or wide if using Landscape orientation) the page
should be. This value can be set before or after the Page Width or Orientation has been set but
must be set before the call to the pdf_new_page procedure. As soon as this procedure is used,
the Paper Type is set to CUSTOM.
Possible Values: Any realistic integer value greater than zero

pdf_set_PageRotate
Parameters:

Stream Name as Character

Rotation Angle as Integer

- Stream name as identified in pdf_new

- By what degree to rotate the contents

Sample Call:

RUN pdf_set_PageRotate(Spdf,90)

Description:
This procedure allows you to determine how the contents of the page should be output to the
page. That is, keeping the same page size (say Letter) and orientation (say Portrait), you can
change how the contents should appear on the page. If you rotate the page 180 degrees, then
the content will appear up-side-down on the Letter/Portrait page.
Possible Values: 0,90,180,270

pdf_set_PageWidth
Parameters:

Stream Name as Character

Page Width as Integer

- Stream name as identified in pdf_new

- How wide is the page?

Sample Call:

RUN pdf_set_PageHeight (Spdf,612)

Description:
This procedure allows you to define how wide (or tall if using Landscape orientation) the page
should be. This value can be set before or after the Page Height or Orientation has been set but
must be set before the call to the pdf_new_page function. As soon as this procedure is used, the
Paper Type is set to CUSTOM.
Possible Values: Any realistic integer value greater than zero

pdf_set_PaperType
Parameters:

01/09/2006

Stream Name as Character

Page Type as Character

- Stream name as identified in pdf_new

- Enter a valid Paper Type

PDFinclude PRO v1 Documentation

31

Sample Call:

RUN pdf_set_PageType (Spdf,LETTER)

Description:
This procedure allows you to select Paper Types that have predefined height and widths. The
following table outlines the valid Paper Types and their associate page dimensions.

Paper Type

Width

Height

A0
2380
3368
A1
1684
2380
A2
1190
1684
A3
842
1190
A4
595
842
A5
421
595
A6
297
421
B5
501
709
LETTER
612
792
LEGAL
612
1008
LEDGER
1224
792
The Widths and Heights identified in the preceding table are based on the Portrait orientation. If
you were to change the Orientation to Landscape then the Width and Height columns would be
reversed.

pdf_set_parameter
Parameters:

Stream Name as Character

- Stream name as identified in pdf_new
Parameter Name as Character - name of parameter to set
Parameter Value as Character - value to set parameter to

Sample Call:

RUN pdf_set_parameter (Spdf,Compress,True)

Description:
This procedure allows you to set parameters associated with the specified PDF stream. The
following table outlines the valid parameter names and potential values (please note that with
using 40-bit encryption only certain parameters are useful or work).

32

PDFinclude PRO v1 Documentation

01/09/2006

Parameter Name

Description

Compress

The parameter allows you to specify that you want to compress the data
streams. Compression occurs before encryption.

Encrypt

Possible Values: TRUE or FALSE

This parameter allows you to encrypt your data streams. Encryption
does not change the size of the data streams.

UserPassword

Possible Values: TRUE or FALSE

This parameter allows you to add a User password to the document.
This password must be entered whenever the document is opened.

MasterPassword

Possible Values: Any alpha-numeric character combination. Max 32

characters.
This parameter allows you to add a Master password to the document.
This password must be entered when trying to modify the security
settings.

EncryptKey

Possible Values: Any alpha-numeric character combination. Max 32

characters.
This parameter allows you to specify the level of encryption. Currently
only handles 40-bit Encryption and is automatically set when the
Encrypt parameter is set to TRUE.
Possible Values: 40

AllowPrint

(128 bit will be the other possible value in future versions)

This parameter allows you to specify whether the PDF document is
printable or not.

AllowCopy

Possible Values: TRUE or FALSE

This parameter allows you to specify whether elements (such as text or
Graphics) can be copied or not.

AllowModify

Possible Values: TRUE or FALSE

This parameter allows you to specify whether elements (such as Form
objects) can be modified or not.

AllowAnnots

Possible Values: TRUE or FALSE

This parameter allows you to specify whether Annotations are allowed
or not.

AllowForms

Possible Values: TRUE or FALSE

This parameter allows you to specify whether Forms processing can be
performed or not.

AllowExtract

Possible Values: TRUE or FALSE

This parameter allows you to specify whether Extraction can be
performed or not.

AllowAssembly

Possible Values: TRUE or FALSE

This parameter allows you to specify whether Assembly can be
performed or not.
Possible Values: TRUE or FALSE

01/09/2006

PDFinclude PRO v1 Documentation

33

pdf_set_TextBlue
Parameters:

Stream Name as Character

Value as Decimal

- Stream name as identified in pdf_new

- Value to set Blue option on RGB Colours

Sample Call:

RUN pdf_set_TextBlue (Spdf,1.0)

Description:
This procedure allows you to individually change the Blue value of the current RGB colour
scheme. That is, if you had previously set the font to Black (eg: Red=0, Blue=0, Green=0) then
you can easily change it to use blue text by running the sample call (as above). Then you can
easily set it back to black by using RUN pdf_set_TextBlue (Spdf,0.0).
Possible Values: Any realistic decimal value between 0.0 and 1.0.

pdf_set_TextGreen
Parameters:

Stream Name as Character

Value as Decimal

- Stream name as identified in pdf_new

- Value to set Green option on RGB Colours

Sample Call:

RUN pdf_set_TextGreen (Spdf,1.0)

Description:
This procedure allows you to individually change the Green value of the current RGB colour
scheme. That is, if you had previously set the font to Black (eg: Red=0, Blue=0, Green=0) then
you can easily change it to use green text by running the sample call (as above). Then you can
easily set it back to black by using RUN pdf_set_TextGreen (Spdf,0.0).
Possible Values: Any realistic decimal value between 0.0 and 1.0.

pdf_set_TextRed
Parameters:

Stream Name as Character

Value as Decimal

- Stream name as identified in pdf_new

- Value to set Red option on RGB Colours

Sample Call:

RUN pdf_set_TextRed (Spdf,1.0)

Description:
This procedure allows you to individually change the Red value of the current RGB colour
scheme. That is, if you had previously set the font to Black (eg: Red=0, Blue=0, Green=0) then
you can easily change it to use red text by running the sample call (as above). Then you can
easily set it back to black by using RUN pdf_set_TextRed (Spdf,0.0).
Possible Values: Any realistic decimal value between 0.0 and 1.0.

34

PDFinclude PRO v1 Documentation

01/09/2006

pdf_set_TextX
Parameters:

Stream Name as Character

Value as Integer

Sample Call:

RUN pdf_set_TextX(Spdf,300)

- Stream name as identified in pdf_new

- Value to set the Text X coordinate to

Description:
This procedure allows you to programmatically change the X coordinate of the Text drawing
plane. This is useful if you want to continue using the text drawing procedures (such as pdf_text,
pdf_text_to, pdf_text_at etc) but want to change the X location within your program.
Possible Values: Any value greater than or equal to 1 and less than or equal to the Page
Width.

pdf_set_TextY
Parameters:

Stream Name as Character

Value as Integer

Sample Call:

RUN pdf_set_TextY(Spdf,300)

- Stream name as identified in pdf_new

- Value to set the Text Y coordinate to

Description:
This procedure allows you to programmatically change the Y coordinate of the Text drawing
plane. This is useful if you want to continue using the text drawing procedures (such as pdf_text,
pdf_text_to, pdf_text_at etc) but want to change the Y location within your program.
Possible Values: Any value greater than or equal to 1 and less than or equal to the Page
Height.

pdf_set_tool_parameter
Parameters:

Stream Name as Character

Tool Name as Character
Parameter as Character
Column as Integer
Value as Character

- Stream name as identified in pdf_new

- Valid Tool Name (as defined in pdf_tool_add)
- Valid Tool Parameter
- integer value (usage varies on tool)
- Parameter Value

Sample Call:

RUN pdf_set_TextY(Spdf,CustList, HeaderFont",0,"Helvetica-Bold")

Description:

01/09/2006

PDFinclude PRO v1 Documentation

35

This procedure allows you to set a parameter that is allowed for a given tool.
For more information on what parameters are available for specific tools, see the section called
Implementing Tools.

pdf_set_TopMargin
Parameters:

Stream Name as Character

Margin Value as Character

- Stream name as identified in pdf_new

- The value you want to assign to the Top
Margin

Sample Call:

RUN pdf_set_TopMargin (Spdf,50)

Description:
This procedure allows you to set the number of points that the document will be indented from the
top edge of the pages boundries (identified by Page Height and Page Width)

pdf_set_VerticalSpace
Parameters:

Stream Name as Character

Vertical Space as Integer

- Stream name as identified in pdf_new

- The value you want to assign to Vertical
Space

Sample Call:

RUN pdf_set_VerticalSpace (Spdf,10)

Description:
This procedure allows you to set the number of points that represents the vertical spacing of
lines. A value of 12 is typical for Portrait oriented documents while 10 is fairly common for
Landscape oriented documents.

pdf_skip
Parameters:

Stream Name as Character

Sample Call:

RUN pdf_skip (Spdf)

- Stream name as identified in pdf_new

Description:
This procedure will skip to the next line in the Text Space. This also updates the current TextX
and TextY attributes for the stream.

36

PDFinclude PRO v1 Documentation

01/09/2006

pdf_skipn
Parameters:

Stream Name as Character

Number of Lines as Integer

Sample Call:

RUN pdf_skipn (Spdf,2)

- Stream name as identified in pdf_new

- Number of lines to skip

Description:
This procedure will skip n number of lines in the Text Space. This also updates the current TextX
and TextY attributes for the stream. This saves you calling pdf_skip multiple times.

pdf_stamp
Parameters:

Stream as Character
Text as Character
Title as Character
Stamp as Character
LLX as Decimal
LLY as Decimal
URX as Decimal
URY as Decimal
Red as Decimal
Green as Decimal
Blue as Decimal

- Stream name as identified in pdf_new

- Text to appear in note
- Small title for the note header
- Predefined icon set
- Lower Left X Coordinate
- Lower Left Y Coordinate
- Upper Right X Coordinate
- Upper Right Y Coordinate
- decimal value representing Red colour value
- decimal value representing Green colour value
- decimal value representing Blue colour value

Sample Call:

RUN pdf_stamp(Spdf,My Stamp Text,My Stamp

Title,Approved,10.0,10.0,20,0,30.0,1.0,0.0,0.0)

Description:

01/09/2006

PDFinclude PRO v1 Documentation

37

This procedure allows you to add a Stamp at a specific location (actually an area determined by
the LL and UR X/Y coordinates) on the current PDF page.
The stamp can contain as much as 32K of associated text.
The possible Stamp types are:
Approved
Experimental
NotApproved
AsIs
Expired
NotForPublicRelease
Confidential
Final
Sold
Departmental
ForComment
TopSecret
Draft (default)
ForPublicRelease
The stamps icon may differ based on viewer being used.

pdf_stroke_color
Parameters:

Stream Name as Character

Red as Decimal

Green as Decimal

Blue as Decimal

Sample Call:

- Stream name as identified in pdf_new

- A decimal value not less than 0 and no
greater than 1. Represents the Red
component of an RGB color value
- A decimal value not less than 0 and no greater
than 1. Represents the Green component of
an RGB color value
- A decimal value not less than 0 and no greater
than 1. Represents the Blue component of an
RGB color value

RUN pdf_stroke_color (Spdf,1.0,0.0,0.0)

Description:
This procedure allows you to change the color PDF objects that are stroked. These include
stroked text (see pdf_text_render), lines, and rectangle borders.

pdf_stroke_fill
Parameters:

38

Stream Name as Character

Red as Decimal

- Stream name as identified in pdf_new

- A decimal value not less than 0 and no
greater than 1. Represents the Red

PDFinclude PRO v1 Documentation

01/09/2006

Green as Decimal

Blue as Decimal

Sample Call:

component of an RGB color value

- A decimal value not less than 0 and no greater
than 1. Represents the Green component of
an RGB color value
- A decimal value not less than 0 and no greater
than 1. Represents the Blue component of an
RGB color value

RUN pdf_stroke_fill (Spdf,1.0,0.0,0.0)

Description:
This procedure allows you to change the color PDF objects that are filled. These include filled
text (see pdf_text_render), and rectangles.

pdf_text
Parameters:

Stream Name as Character

Text as Character

- Stream name as identified in pdf_new

- Any string value

Sample Call:

RUN pdf_text (Spdf,Hello World)

Description:
This procedure allows you to place the passed text string at the current TextX and TextY Text
Space points.

pdf_text_align
Parameters:

Stream Name as Character

Text as Character
Align as Character
Column as Integer
Row as Integer

- Stream name as identified in pdf_new

- Any string value
- LEFT,CENTER,RIGHT
- Any non-zero integer value
- Any non-zero integer value

Sample Call:

RUN pdf_text_align (Spdf,Hello World,CENTER, 60, 100)

Description:
This procedure allows you to place the passed text string at a specific Row/Column (X/Y)
Coordinate. How the text is placed at the coordinate depends on the Alignment.
LEFT starts placing the text the passed Row/Column coordinate
CENTER centers the text string over the Row/Column coordinate
RIGHT places the end of the text string at the Row/Column coordinate

pdf_text_at

01/09/2006

PDFinclude PRO v1 Documentation

39

Parameters:

Stream Name as Character

Text as Character
Column as Integer

- Stream name as identified in pdf_new

- Any string value
- Any non-zero integer value

Sample Call:

RUN pdf_text_at (Spdf,Hello World,60)

Description:
This procedure allows you to place the passed text string at column 60 (determined by current
PointSize * passed Column Value) on the current Text row (TextX).
Note: The column value entered here is determined by the actual row that you would like to see
the text appear beginning at. That is, assuming a PointSize of 10, instead of entering 600 to have
the text begin at Column 60, just enter 60.

pdf_text_boxed_xy
Parameters:

Sample Call:

Stream Name as Character

Text as Character
Column as Integer
Row as Integer
Width as Integer
Height as Integer
Justify as Character
Weight as Integer

- Stream name as identified in pdf_new

- Any string value
- Any non-zero integer value
- Any non-zero value

- Currently Unused
- Weight of Boxes line

RUN pdf_text_boxed_xy (Spdf,Hello World,10,100,15,105,LEFT,1)

Description:
This procedure allows you to specifically place the passed text string at the passed Row and
Column. A box will be placed around the text.
Note: The column and row values passed to this function should represent the actual PDF points.
That is , unlike pdf_text_at, if you want to have the text appear at point 600 then enter 600 (not
60).

pdf_text_center
Parameters:

Stream Name as Character

Text as Character
Column as Integer
Rowas Integer

- Stream name as identified in pdf_new

- Any string value
- Any non-zero integer value
- Any non-zero integer value

Sample Call:

RUN pdf_text (Spdf,This is Centered Text,50,100)

Description:
This centers the passed text on the given X,Y point.

40

PDFinclude PRO v1 Documentation

01/09/2006

pdf_text_char
Parameters:

Stream Name as Character

Value as Integer

Sample Call:

RUN pdf_text_char (Spdf,63)

- Stream name as identified in pdf_new

- Any value between 0 and 377

Description:
This procedure outputs the character using the specified character code. This is useful if you
want to change your font to ZapfDingbats then output a check mark (9) into your text stream.

pdf_text_charxy
Parameters:

Stream Name as Character

Value as Character
Column as Integer
Row as Integer

- Stream name as identified in pdf_new

- Any character code
- Any value between 1 and Page Height
- Any value between 1 and Page Width

Sample Call:

RUN pdf_text_charxy (Spdf,063,100,100)

Description:
This procedure outputs the character using the specified character code at the specific location.
This is useful if you want to change your font to ZapfDingbats then output a check mark (9) onto
your graphic plane.

pdf_text_color
Parameters:

Stream Name as Character

Red as Decimal

Green as Decimal

Blue as Decimal

Sample Call:

- Stream name as identified in pdf_new

- A decimal value not less than 0 and no
greater than 1. Represents the Red
component of an RGB color value
- A decimal value not less than 0 and no
greater than 1. Represents the Green
component of an RGB color value
- A decimal value not less than 0 and no
greater than 1. Represents the Blue
component of an RGB color value

RUN pdf_textcolor (Spdf,1.0,0.0,0.0)

Description:
This procedure allows you to set the color that the following text displays should appear in.

01/09/2006

PDFinclude PRO v1 Documentation

41

pdf_text_render
Parameters:

Stream Name as Character

Render Type as Integer

- Stream name as identified in pdf_new

- An integer value representing how to render
the text

Sample Call:

RUN pdf_text_render (Spdf, 0)

Description:
This procedure allows you to define how the text will be rendered. There are four possible values
and they are outlined below.
Render Type

Description

0
1
2
3

Fill Text
Stroke Text
Fill, then Stroke Text
Neither Fill nor Stroke Text (invisible)

pdf_text_rotate
Parameters:

Stream Name as Character

Angle as Integer

Sample Call:

RUN pdf_skip (Spdf, 90)

- Stream name as identified in pdf_new

- Angle to rotate and display text in

Description:
This procedure will set the rotation angle for displaying text in. This must be run before you
display the text you want rotated.
Possible Values are:
0 0 Degrees (default)
90 90 Degrees
180 180 Degrees
270 270 Degrees

pdf_text_to
Parameters:

Stream Name as Character

Text as Character
Column as Integer

- Stream name as identified in pdf_new

- Any string value
- Any non-zero value

Sample Call:

RUN pdf_text_to (Spdf,Hello World,30)

Description:

42

PDFinclude PRO v1 Documentation

01/09/2006

This procedure allows you to place the passed text string right-aligned to the specified column
(determined by current PointSize * passed Column Value) on the current Text row (TextX).
Note: The column value entered here is determined by the actual row that you would like to see
the text appear beginning at. That is, assuming a PointSize of 10, instead of entering 600 to have
the text begin at Column 60, just enter 60.

pdf_text_xy
Parameters:

Stream Name as Character

Text as Character
Column as Integer
Row as Integer

- Stream name as identified in pdf_new

- Any string value
- Any non-zero value
- Any non-zero value

Sample Call:

RUN pdf_text_xy (Spdf,Hello World,10,100)

Description:
This procedure allows you to specifically place the passed text string at the passed Row and
Column.
Note: The column and row values passed to this procedure should represent the actual PDF
points. That is , unlike pdf_text_at, if you want to have the text appear at point 600 then enter
600 (not 60).

pdf_text_xy_dec
Parameters:

Stream Name as Character

Text as Character
Column as Decimal
Row as Decimal

- Stream name as identified in pdf_new

- Any string value
- Any non-zero value
- Any non-zero value

Sample Call:

RUN pdf_text_xy_dec (Spdf,Hello World,10.0,100.00)

Description:
This procedure allows you to specifically place the passed text string at the passed Row and
Column.
This procedure is similar in functionality to pdf_text_xy except that it accepts decimal values for
the Row/Column (or X/Y) graphic coordinates. This allows for more accurate placement of the
text element.

pdf_tool_add
Parameters:

01/09/2006

Stream Name as Character

Tool Name as Character
Tool Type as Character
Tool Data as Handle

- Stream name as identified in pdf_new

- Any string value
- valid tool type
- Handle to TEMP-TABLE

PDFinclude PRO v1 Documentation

43

Sample Call:

RUN pdf_tool_add (Spdf,CustList,TABLE,TT_Customer)

Description:
This links to the pdftool.p procedure. The pdftool.p procedure has some predefined tools that
allow for simplified documents. The tool types available are:
TABLE
CALENDAR

MATRIX

This allows you to easily create a columnar report that will span multiple
pages.
This allows you to easily create a calendar for a specific year/month. A
calendar is associated with a specific page (cant span pages) and you can
have multiple calendars on a single page. You can also specify notes for a
specific day within the calendar.
This allows you to easily create a columnar table that does not span
multiple pages. A Matrix is associated with a single page and you can have
multiple matrices on a single page. You control what data is entered in
each cell of the matrix.

pdf_use_pdf_page
Parameters:

Stream as Character
PDF ID as Character
Page as Integer

- Stream name as identified in pdf_new

- Valid PDF ID as created in pdf_open_pdf
- Number of page to use from PDF ID

Sample Call:

RUN pdf_use_pdf_page (Spdf, INV,1)

Description:
This procedure allows you to include a page from a pre-existing PDF document into your newly
generated document.
This command can be called once per page. In other words, you can only include an existing
page once per new page. But you can still use the pre-existing page as many times as you wish
(on each page of your new document or not).
By using a page from a pre-existing document, it also enables you access to any Adobe Form
Fields that have been embedded into the pre-existing document page. You can then write data
to those field placement by using the pdf_fill_text procedure.
For more information on using pre-existing PDF documents, see the section called Introducing
Complex Forms.

pdf_Watermark
Parameters:

44

Stream Name as Character

Text as Character
Font as Character
FontSize as Integer
Red as Decimal
Blue as Decimal

- Stream name as identified in pdf_new

- Text value to display
- Name of Font to display Text in
- How large the text should appear
- Value to set Red option for text Colour
- Value to set Blue option for text Colour

PDFinclude PRO v1 Documentation

01/09/2006

Green as Decimal
X as Integer
Y as Integer
Sample Call:

- Value to set Green option for text Colour

- X location to display text at
- Y location to display text at

RUN pdf_set_WaterMark
(Spdf,
Sample Report,
Courier,
16,
1.0,
0.0,
0,0,
100,
500)

Description:
This procedure allows you to place a text watermark into the PDF document. The watermark will
appear only on the Page where it is issued, so if you want to have it appear on all pages ensure
that the command is reissued whenever a new page is issued.

pdf_Wrap_Text
Parameters:

Stream Name as Character

Text as Character
From Column as Integer
To Column as Integer
Alignment as Character
Max Y as Integer

- Stream name as identified in pdf_new

- Text value to display
- Column at which to start Text output
- Column to stop Text Output
- how to align the text left or right aligned?
- OUTPUT variable

Sample Call:

RUN pdf_set_TextRed
(Spdf,
This is a lot of text that could include line breaks etc,
10,
20,
left,
OUTPUT CurrentY).

Description:
This procedure allows you to place text into the PDF document within a from/to column location.
If the text is longer than the from/to location then it will automatically wrap the text to the next line
and place the remaining text within the same from/to location as the previous line. This is useful
when printing character fields that have been input via an Editor widget.

01/09/2006

PDFinclude PRO v1 Documentation

45

4.Function List
This section defines the functions available within PDFinclude PRO. For each function you are
given the required arguments, expected or valid values, sample calls, and a detailed description
of how (and when) the function should be used.

GetXMLNodeValue
Arguments:

Parent Name as Character

Node Name as Character

- Parent Node
- Node Name

Returns:
Sample Call:

Character
GetXMLNodeValue (Invoice,InvoiceNumber)

Description:
This function returns the value of a unique Parent/Child Node combination from the TT_pdf_xml
TEMP-TABLE (which was created using the pdf_load_xml procedure).

pdf_Angle
Arguments:

Stream Name as Character

Returns:
Sample Call:

Integer
pdf_Angle (Spdf)

- Stream name as identified in pdf_new

Description:
This function returns the currently set angle that is being used for the Text Rotation.

pdf_BottomMargin
Arguments:

Stream Name as Character

Returns:
Sample Call:

Integer
pdf_BottomMargin (Spdf)

- Stream name as identified in pdf_new

Description:
This function returns the currently set value of the PDF pages Bottom Margin.

pdf_FillBlue
Arguments:

Stream Name as Character

Returns:
Sample Call:

Decimal
pdf_FillBlue (Spdf)

46

- Stream name as identified in pdf_new

PDFinclude PRO v1 Documentation

01/09/2006

Description:
This function allows you to determine what the current Blue value of the current FILL RGB setting
is.

pdf_FillGreen
Arguments:

Stream Name as Character

Returns:
Sample Call:

Decimal
pdf_FillGreen (Spdf)

- Stream name as identified in pdf_new

Description:
This function allows you to determine what the current Green value of the current FILL RGB
setting is.

pdf_FillRed
Arguments:

Stream Name as Character

Returns:
Sample Call:

Decimal
pdf_FillRed (Spdf)

- Stream name as identified in pdf_new

Description:
This function allows you to determine what the current Red value of the current FILL RGB setting
is.

pdf_Font
Arguments:

Stream Name as Character

Returns:
Sample Call:

Character
pdf_Font (Spdf)

- Stream name as identified in pdf_new

Description:
This function returns the currently selected font that is being used to display text.

pdf_Font_Loaded
Arguments:

Stream Name as Character

Font Name as Character

- Stream name as identified in pdf_new

- Font Name

Returns:
Sample Call:

Logical
pdf_Font_Loaded (Spdf,Arial)

Description:
This function lets you determine whether a font has already been loaded or not.

01/09/2006

PDFinclude PRO v1 Documentation

47

pdf_FontType
Arguments:

Stream Name as Character

Font Name as Character

- Stream name as identified in pdf_new

- Font Name

Returns:
Sample Call:

Character
pdf_Font_Loaded (Spdf,Arial)

Description:
This function returns what type of Font this is FIXED or Proportional.

pdf_get_info
Arguments:
Returns:
Sample Call:

Stream Name as Character

Attribute Name as Character
Character
pdf_get_info (Spdf)

- Stream name as identified in pdf_new

- One of the valid Attributes (see below)

Description:
This function returns the value of the specified Document Information attribute.
Possible attributes are listed in the table below:
Attribute

Description

Author
Creator

Who created the document

What created the document (eg: PDFinclude or the name of your
procedure)
Keywords that will help identify the contents of the PDF document
Any phrase that would describe the contents of the document
eg: Accounts Payable
Any phrase that would describe the contents of the document
eg: Vendor Listing

Keywords
Subject
Title

pdf_GetNumFittingChars
Arguments:

Stream Name as Character

Text as Character
From X as Integer
To X as Integer

Returns:
Sample Call:

Integer
pdf_get_NumFittingChars
(Spdf,
This is my text example,
10, 20).

- Stream name as identified in pdf_new

- Text value to check
- Starting X Coordinate
- Ending X Coordinate

Description:

48

PDFinclude PRO v1 Documentation

01/09/2006

This function returns the index of the last character that will fit into the specified width. It does this
by summing each characters AFM width (as specified in the tt_pdf_font.font_width array) and
comparing with the required width (converted into these same units).

pdf_get_parameter
Arguments:
Returns:
Sample Call:

Stream Name as Character

- Stream name as identified in pdf_new
Parameter Name as Character - One of the valid parameter names
Character
pdf_get_parameter (Spdf,Encrypt)

Description:
This function returns the value of the specified Document parameter. For a list of valid document
parameters see the pdf_set_parameter procedure.

pdf_get_tool_parameter
Arguments:

Stream Name as Character

Tool Name as Character
Parameter Name as Character
Tool Column as Integer

- Stream name as identified in pdf_new

- Tool Name
- Valid Tool Parameter Name
- Column ID

Returns:
Sample Call:

Character
pdf_get_tool_parameter (Spdf,CustList,HeaderFont,0)

Description:
This function returns the value of the specified Tool parameter. For a list of valid Tool parameters
see the section on Implementing Tools.

pdf_get_wrap_length
Arguments:

Stream Name as Character

Text as Character
Width as Integer

Returns:
Sample Call:

Integer
pdf_get_NumFittingChars
(Spdf,
This is my text example,
10).

- Stream name as identified in pdf_new

- Text value to check
- Maximum width required

Description:
You can use the function to see how long a piece of text WOULD be if you were to wrap it.

01/09/2006

PDFinclude PRO v1 Documentation

49

pdf_GraphicX
Arguments:

Stream Name as Character

Returns:
Sample Call:

Integer
pdf_GraphicX (Spdf)

- Stream name as identified in pdf_new

Description:
This function returns the value of the current X (Column) location of the Graphic State.

pdf_GraphicY
Arguments:

Stream Name as Character

Returns:
Sample Call:

Integer
pdf_GraphicY (Spdf)

- Stream name as identified in pdf_new

Description:
This function returns the value of the current Y (Column) location of the Graphic State.

pdf_ImageDim
Arguments:

Stream Name as Character

Image Name as Character

- Stream name as identified in pdf_new

- Image name as defined with a
pdf_load_image
Dimenstion Type as Character - Either HEIGHT or WIDTH

Returns:
Sample Call:

Integer
pdf_ImageDim (Spdf,Logo,HEIGHT)

Description:
This function returns the value of the Image Dimension that was requested with Dimension Type
input parameter. This is useful because when you load the image you dont know the Image
Width or Height. With this function you can determine either.

pdf_LeftMargin
Arguments:

Stream Name as Character

Returns:
Sample Call:

Integer
pdf_LeftMargin (Spdf)

- Stream name as identified in pdf_new

Description:
This function returns the value of the Left Margin.

50

PDFinclude PRO v1 Documentation

01/09/2006

pdf_Orientation
Arguments:

Stream Name as Character

Returns:
Sample Call:

Character
pdf_Orientation (Spdf)

- Stream name as identified in pdf_new

Description:
This function returns the value of the Orientation parameter. The Orientation parameter is used
to define how the page appears.
Possible Values: Portrait or Landscape

pdf_Page
Arguments:

Stream Name as Character

Returns:
Sample Call:

Integer
pdf_Page (Spdf)

- Stream name as identified in pdf_new

Description:
This function returns the value of the current Page parameter. The Page parameter is
incremented after every call to a pdf_new_page.

pdf_PageFooter
Arguments:

Stream Name as Character

- Stream name as identified in pdf_new
Proc Handle as Handle - Handle to called from procedure
Footer Name as Character - Footer procedure name from calling procedure

Returns:
Sample Call:

Logical
pdf_PageFooter (Spdf, THIS-PROCEDURE:HANDLE, PageFooter)

Description:
This function notified PDFinclude that the calling report procedure has a Page Footer procedure
associated with it. If this has been set (with a non-blank value) then whenever a text element is
to be displayed below the Bottom Margin (set by pdf_set_BottomMarging) this procedure (eg:
PageFooter) will be called.

pdf_PageHeader
Arguments:

01/09/2006

Stream Name as Character

- Stream name as identified in pdf_new

PDFinclude PRO v1 Documentation

51

Proc Handle as Handle - Handle to called from procedure

Header Name as Character - Header procedure name from calling procedure
Returns:
Sample Call:

Logical
pdf_PageHeader (Spdf, THIS-PROCEDURE:HANDLE, PageHeader)

Description:
This function notified PDFinclude that the calling report procedure has a Page Header procedure
associated with it. If this has been set (with a non-blank value) then on each call to
pdf_new_page this procedure (eg: PageHeader) will be called.

pdf_PageHeight
Arguments:

Stream Name as Character

Returns:
Sample Call:

Integer
pdf_PageHeight (Spdf)

- Stream name as identified in pdf_new

Description:
This function returns the value of the current Page Height parameter. The Page Height
parameter is used to determine the page boundaries. The Page Height parameter can either be
set directly by using pdf_set_PageHeight or indirectly by calling pdf_PaperType.

pdf_PageRotate
Arguments:

Stream Name as Character

Returns:
Sample Call:

Integer
pdf_PageRotate (Spdf)

- Stream name as identified in pdf_new

Description:
This function returns the value of the current PageRotate parameter. Can only be set to
0,90,180, or 270.

pdf_PageWidth
Arguments:

Stream Name as Character

Returns:
Sample Call:

Integer
pdf_PageWidth (Spdf)

- Stream name as identified in pdf_new

Description:

52

PDFinclude PRO v1 Documentation

01/09/2006

This function returns the value of the current Page Width parameter. The Page Width parameter
is used to determine the page boundaries. The Page Width parameter can either be set directly
by using pdf_set_PageWidth or indirectly by calling pdf_PaperType.

pdf_PaperType
Arguments:

Stream Name as Character

Returns:
Sample Call:

Character
pdf_PaperType (Spdf)

- Stream name as identified in pdf_new

Description:
This function returns the value of the current Paper Type parameter. The Paper Type parameter
is used to determine the page boundaries. The Paper Type parameter is set by calling
pdf_set_parameter and selecting a valid Paper Type or by calling pdf_set_PageHeight or
pdf_set_PageWidth. Calling either of the two latter functions will set the Paper Type to
CUSTOM.
Valid Paper Types are:

Paper Type

Width

Height

A0
2380
3368
A1
1684
2380
A2
1190
1684
A3
842
1190
A4
595
842
A5
421
595
A6
297
421
B5
501
709
LETTER
612
792
LEGAL
612
1008
LEDGER
1224
792
The Widths and Heights identified in the preceding table are based on the Portrait orientation. If
you were to change the Orientation to Landscape then the Width and Height columns would be
reversed.

pdf_PointSize
Arguments:

Stream Name as Character

Returns:
Sample Call:

Integer
pdf_PointSize (Spdf)

- Stream name as identified in pdf_new

Description:
This function returns the value of the current Point Size parameter. The Point Size parameter is
used to determine how large a text object will be drawn on the PDF page. The Point Size is set
by calling the pdf_set_Font function.

01/09/2006

PDFinclude PRO v1 Documentation

53

pdf_Render
Arguments:

Stream Name as Character

Returns:
Sample Call:

Integer
pdf_Render (Spdf)

- Stream name as identified in pdf_new

Description:
This function returns the value of the current Text Rendering parameter. The Test Rendering
parameter is used to determine how the text will be drawn on the PDF page. The Text Rendering
parameter is set by calling the pdf_Text_Render function.
The following table outline the possible values for the Text Rendering parameter:
Render Type

Description

0
1
2
3

Fill Text
Stroke Text
Fill, then Stroke Text
Neither Fill nor Stroke Text (invisible)

pdf_text_fontwidth
Arguments:

Stream Name as Character

Font Name as Character
Text Value as Character
width of

- Stream name as identified in pdf_new

- The Font Tag name
- The text you want to determine the

Returns:
Sample Call:

Decimal
pdf_text_widthdec2 (Spdf,Arial,End of Report)

Description:
This function is similar in functionality to the pdf_text_widthdec2 function except that you only
pass in the Font. The Font Size is determined by using the current Point Size (as set by
pdf_set_font).

pdf_text_width
Arguments:

Stream Name as Character

Text Value as Character
width of

- Stream name as identified in pdf_new

- The text you want to determine the

Returns:
Sample Call:

Integer
pdf_text_width (Spdf,End of Report)

Description:

54

PDFinclude PRO v1 Documentation

01/09/2006

This function allows you to determine the length (in points) of the passed text string using the
current Font and PointSize. The width is calculated as follows:
width = (LENGTH(text value) * individual character lengths / 1000) * pdf_PointSize(PDF Stream)
The individual character lengths may differ for each character within a given font. The
accumulation of the total character widths divided by 1000 then multiplied by the current font
Point Size. This function is useful when used in conjunction with the pdf_text_boxed_xy function
(allowing you to determine how wide the box around the text should be).

pdf_text_widthdec
Arguments:

Stream Name as Character

Text Value as Character
width of

- Stream name as identified in pdf_new

- The text you want to determine the

Returns:
Sample Call:

Decimal
pdf_text_widthdec (Spdf,End of Report)

Description:
This function is similar in functionality to the pdf_text_width function except that it returns the
value in decimal format. This allows for more exact determination of the text width.

pdf_text_widthdec2
Arguments:

Stream Name as Character

Font Tag as Character
Font Size as Decimal
Text Value as Character
width of

- Stream name as identified in pdf_new

- The Font Tag name
- Stream name as identified in pdf_new
- The text you want to determine the

Returns:
Sample Call:

Decimal
pdf_text_widthdec2 (Spdf,\Arial,8.0,End of Report)

Description:
This function is similar in functionality to the pdf_text_widthdec function except that you pass in
the Font and Font Size you want to use to determine the Text width.

pdf_TextBlue
Arguments:

Stream Name as Character

Returns:
Sample Call:

Decimal
pdf_TextBlue (Spdf)

- Stream name as identified in pdf_new

Description:
This function allows you to determine what the current Blue value of the current RGB setting is.

01/09/2006

PDFinclude PRO v1 Documentation

55

pdf_TextGreen
Arguments:

Stream Name as Character

Returns:
Sample Call:

Decimal
pdf_TextGreen (Spdf)

- Stream name as identified in pdf_new

Description:
This function allows you to determine what the current Green value of the current RGB setting is.

pdf_TextRed
Arguments:

Stream Name as Character

Returns:
Sample Call:

Decimal
pdf_TextRed (Spdf)

- Stream name as identified in pdf_new

Description:
This function allows you to determine what the current Red value of the current RGB setting is.

pdf_TextX
Arguments:

Stream Name as Character

Returns:
Sample Call:

Integer
pdf_TextX(Spdf)

- Stream name as identified in pdf_new

Description:
This function returns the current X (Column) location within the Text Space.

pdf_TextY
Arguments:

Stream Name as Character

Returns:
Sample Call:

Integer
pdf_TextY (Spdf)

- Stream name as identified in pdf_new

Description:
This function returns the current Y (Row) location within the Text Space.

pdf_TotalPages
Arguments:

Stream Name as Character

Returns:

Character

56

- Stream name as identified in pdf_new

PDFinclude PRO v1 Documentation

01/09/2006

Sample Call:

pdf_TotalPages (Spdf)

Description:
This function allows you to include the Total Number of Pages for the document directly into your
report. For instance, if you wanted to have 'Page n of x' as your Page footer then you can
implement this with pdf_TotalPages(streamname).

pdf_TopMargin
Arguments:

Stream Name as Character

Returns:
Sample Call:

Integer
pdf_TopMargin (Spdf)

- Stream name as identified in pdf_new

Description:
This function returns the current Top Margin point setting.

pdf_VerticalSpace
Arguments:

Stream Name as Character

Returns:
Sample Call:

Integer
pdf_VerticalSpace (Spdf)

- Stream name as identified in pdf_new

Description:
This function returns the current point size for the Vertical Space. The Vertical Space is used to
define the spacing between lines.

01/09/2006

PDFinclude PRO v1 Documentation

57

5.Internal Procedures and Functions

This section outlines the other procedures and functions that are used within PDFinclude PRO.
These procedure and functions should not be used within programs as they may cause issues
when developing a PDF document.
Name

Type

Description

Compress

Procedure

UnCompress

Procedure

First_Marker
Hex
Nextbyte
Next2Bytes
Next_Marker
ObjectSequence

Function
Function
Function
Function
Function
Function

Pdf_Catalog
Pdf_Content

Procedure
Procedure

Pdf_Definition

Procedure

pdf_error

Procedure

pdf_set_Angle

Procedure

Pdf_Encoding
Pdf_Fonts

Procedure
Procedure

Pdf_FontType

Function

Pdf_Get_Image_WH
Pdf_Header

Procedure
Procedure

Pdf_inc_ContentSequenc
e
Pdf_init_param

Function

Pdf_Length

Procedure

Pdf_ListPages
Pdf_LoadBase14

Procedure
Procedure

Defines External Compress Procedure in the Zlib

DLL or Shared Library
Defines External UnCompress Procedure in the Zlib
DLL or Shared Library
Used in determination of Image Dimensions
Used in determination of Image Dimensions
Used in determination of Image Dimensions
Used in determination of Image Dimensions
Used in determination of Image Dimensions
Used to increment the PDF Object Counter. The
objects represent different dictionaries within the
PDF document. The start and end bytes of each
Object must be stored so that the XREF dictionary
can be built correctly.
This procedure creates the PDF Catalog Object.
This procedure is the main content generator of the
PDF document.
This procedure creates the Page Dictionaries (and
Annotations) for the PDF document.
This procedure is used to track errors that have
occurred during the building of the PDF document.
Sample errors include incorrectly defined parameter
options or incorrect stream names. Any errors are
displayed to the default Progress stream and the
PDF document is not generated.
This procedure stores the value of the Angle as
defined in pdf_Text_Rotation so that it can be
retrieved via pdf_Angle.
This procedure creates the PDF Encoding Object.
This procedure creates the appropriate Font
Dictionaries for Base 14 fonts.
This function returns whether the current font is
FIXED or VARIABLE (Proportional)
Used in determination of Image Dimensions
Output the beginning of the PDF Document plus the
Document Information Object (Object #1)
This function increments the Object Sequence
(Object Number).
This procedure initializes the PDF document for a
given stream.
This procedure writes the Length Object for another
associated Object. Example, a Page object would
have an associated Length Object.
This procedure writes the Page Object Dictionary.
This procedure loads the Base 14 fonts, for a PDF

58

Procedure

PDFinclude PRO v1 Documentation

01/09/2006

Pdf_Load_Fonts

Procedure

Pdf_Load_Images

Procedure

Pdf_Load_Links

Procedure

Pdf_LoadParseAFMFile

Procedure

Pdf_Replace_Text

Procedure

Pdf_Resources

Procedure

pdf_set_GraphicX

Procedure

pdf_set_GraphicY

Procedure

pdf_set_page

Procedure

Pdf_Xref
Process_SOF
ReleasePDFencryptlib
Release Zlib
Skip_Variable

Procedure
Function
Procedure
Procedure
Function

01/09/2006

stream, so that the font can be used when generating

the PDF (eg: when using pdf_Set_font)
This procedure writes the Font Dictionaries for the
TTF Fonts that were embedded via pdf_load_font.
This procedure writes the Image Dictionaries for the
JPEG Images that were embedded via
pdf_load_image.
This procedure writes the Annotation Dictionaries for
the links that were included via pdf_link.
This procedure parses the AFM file specified in a
pdf_Load_font call.
This procedure replaces any special characters in
the content that would result in an invalid PDF being
generated.
This procedure writes the Resource Object
Dictionary.
This procedure sets the current graphic plane X axis
location whenever a graphic element is added to the
PDF document.
This procedure sets the current graphic plane Y axis
location whenever a graphic element is added to the
PDF document.
This procedure increment the PDF page number
whenever a new page is required.
This procedure writes the XREF Object Dictionary.
Used in determination of Image Dimensions
Releases the Encryption DLL or Shared Library
Releases the Zlib DLL or Shared Library
Used in determination of Image Dimensions

PDFinclude PRO v1 Documentation

59

6.Component List
This section lists and describes the components that make-up the PDFinclude PRO package.
Component

Description

pdf_inc.i

Main include file.

Creates initial GLOBAL parameters (and TEMP-TABLES used by other
PDFinclude components) via pdfglobal.i.
Calls main pdf_inc.p procedure

pdf_inc.p

FORWARD declares Function declarations (via pdf_func.i).

Main PDFinclude procedure.
Defines all functions and procedures available within PDFinclude.

pdf_func.i

FORWARD declares Function declarations

pdfglobal.i

Defines GLOBAL parameters and TEMP-TABLES

pdftool.p

Tool Library

pdfextract.p

PDF Parser component that allows for inclusion of existing PDF

documents into PDFinclude generated documents.

pdfencrypt.p

PDF Encryption component (40-Bit Encryption)

pdf_pre.i

Preprocessor definitions. The definitions maintained in this include file

are used throughout PDFinclude PRO.

60

PDFinclude PRO v1 Documentation

01/09/2006

7.How to Implement Page Headers and Footers

Page Headers and Footers allow you to define code blocks that will appear whenever a page is
generated. The code blocks allow you to include both text and graphic elements into your PDF
document.
Page Headers appear whenever a call to pdf_new_page is issued. The Page Header is
generated before anything else can be included in the PDF content of the page, ensuring that the
Page Header content actually appears at the top of the page unless youve used an element
that uses specific X/Y positioning (eg: pdf_text_xy or pdf_place_image), then that element can be
placed anywhere on the current page (useful if you wanted a watermark to appear on a page).
Page Footers appear only if you have set the Bottom Margin of the page (using
pdf_set_BottomMargin). If any text elements (except X/Y positional text elements) are going to
be displayed below the Bottom Margin setting, then the Page Footer code block is run and a call
to pdf_new_page is issued .. to automatically increment the PDF paging. Ensure that when you
call pdf_set_BottomMargin you set the value to something that will allow your Footer to appear
correctly. That is, if you set the value to low (say 10) you may not get a page footer, or if your
footer included graphic elements those elements may overlay some of the text.
To create Page Footers and Page Headers for a report, you need to create code blocks
(procedures) in your program that will generate the appropriate output. For example, the
following procedure illustrates a PageFooter:
PROCEDURE PageFooter:
/*-----------------------------------------------------------------------------Purpose: Procedure to Print Page Footer -- on all pages.
------------------------------------------------------------------------------*/
/* Display a Sample Watermark on every page */
RUN pdf_watermark ("Spdf","Customer List","Courier-Bold",34,.87,.87,.87,175,500).
RUN pdf_skip ("Spdf").
RUN pdf_set_dash ("Spdf",1,0).
RUN pdf_line ("Spdf", 0, pdf_TextY("Spdf") - 5, pdf_PageWidth("Spdf") - 20 ,
pdf_TextY("Spdf") - 5, 1).
RUN pdf_skip ("Spdf").
RUN pdf_skip ("Spdf").
RUN pdf_text_to ("Spdf", "Page: "
+ STRING(pdf_page("Spdf"))
+ " of " + pdf_TotalPages("Spdf"), 97).
vlines = 1. /* Restart our count for the linking */
END. /* PageFooter */
But this code wont be run unless we communicate this procedure to PDFinclude PRO. To do
that you need to make the appropriate call. The two calls (functions) that notify PDfinclude PRO
that you have included headers and footers in your report are:
pdf_PageFooter (<stream name>,THIS-PROCEDURE:HANDLE, <Procedure Name>).
pdf_PageHeader (<stream name>,THIS-PROCEDURE:HANDLE, <Procedure Name>).
So, for our footer example, we would need to include the following function call (after referencing
pdf_inc.i) in our program.

01/09/2006

PDFinclude PRO v1 Documentation

61

pdf_PageFooter (Spdf,THIS-PROCEDURE:HANDLE,"PageFooter").
This function call lets PDFinclude know that we have a footer procedure in our calling program.

62

PDFinclude PRO v1 Documentation

01/09/2006

8.How to Implement Compression

PDFinclude PRO uses the Zlib Compression Library (Zlib) to implement Flate compression. Zlib
is a free open-source project and the binaries (or source) for many operating systems can be
found at www.zlib.net.
Steps to implementing compression:
1. Download and install the appropriate binary from www.zlib.net
2. Open the file pdf_pre.i Progress include file in the PDFinclude PRO download. Change
the zlib pre-processor to point to the appropriate DLL or Shared Library object.
Eg: For Windows installs the zlib pre-processor would have the value of zlib1.dll defined
like:
&GLOBAL-DEFINE zlib zlib1.dll
3. Add the following command to each of the PDF documents that you wish to compress:
RUN pdf_set_parameter(<stream name>,Compress,TRUE).
This statement can be run anytime between the calls to pdf_new and pdf_close. If you
happen to run the statement multiple times before pdf_close, then the last call will be
used to determine whether compression is to be used or not.
4. Run your code and you will see a reduction in your PDF filesize.
PDFinclude PRO does compress images but since they are already compressed, you may find
that they arent further reduced by very much.

01/09/2006

PDFinclude PRO v1 Documentation

63

9.How to Implement Encryption

The Encryption of the data stream is performed after compression if compression is used that
is.
PDFinclude PRO uses external binaries (a DLL or Shared Library object) to perform the
encryption.
For Windows, a DLL (procryptlib.dll) is included in the download.
If you are on a *NIX OS then you will need to compile the rc4.c object into a Shared Library
Steps to implementing encryption:
1. Copy pdfencrypt.p to the same location as pdf_inc.p etc
2. Edit pdf_pre.i and modify the pre-processor MD5LIB to point to the appropriate md5
routine.
On Windows:
On *NIX:

use the md5.exe binary included in the download

point to the appropriate *NIX command (eg: /usr/lib/md5sum)

3. Edit pdf_pre.i and modify the pre-processor pdfencryptlib to point to the appropriate
DLL or Shared Library object (this will contain the external function endecrypt)
4. Add the following command to each of the PDF documents that you wish to encrypt:
RUN pdf_set_parameter(<stream name>,Encrypt,TRUE).
This statement can be run anytime between the calls to pdf_new and pdf_close. If you
happen to run the statement multiple times before pdf_close, then the last call will be
used to determine whether encryption is to be used or not.
You can also set the Allow*, UserPassword and/or MasterPassword document
parameters to determine the permissions (see pdf_set_parameter procedure
documentation for more info) associated with the PDF document.
5. Run your procedures and see the encrypted (or protected) PDF document.
Currently PDFinclude PRO currently only utilizes 40-Bit encryption.

64

PDFinclude PRO v1 Documentation

01/09/2006

10.Implementing Tools
Tools are pre-built components that allow you to quickly and easily create specific content types
(or tool types).
To add a tool to a PDFinclude PRO document you need call the pdf_add_tool procedure.
Syntax:

RUN pdf_add_tool(<Stream>,<ToolType>,<ToolID>).

Tool Parameters are used to control the output and look-and-feel of the Tool. To set parameters
(listed in the following sections) for a tool you need to call the pdf_set_tool_parameter
procedure.
Syntax:
RUN pdf_set_tool_parameter(<Stream>,<ToolID>,<ParamName>,<Indicator>,<ParamValue>)
This section outlines the tools that are available via the pdftool.p procedure.

10.1TABLE Tool
This Table tool allows you to generate a multi-page columnar report. For example, helps to
produce a Customer Listing (as illustrated below):

01/09/2006

PDFinclude PRO v1 Documentation

65

To use a Table you must supply a data set (TEMP-TABLE Handle) when running the
pdf_tool_add procedure.
The Table tool has a number of parameters that can be set. Those parameters are outlined
below.
Parameter Name

Description

ColumnHeader

For each column, you must specify the header (or column-label in
Progress-speak).
Use the Indicator value to specify which column should have which
label.
eg: RUN pdf_set_tool_parameter(Spdf,
TBL,ColumnHeader,1,Customer #).
In this case the 1 tells pdftool.p that the column label for the first column
should be Customer #.

ColumnPadding

This represents the space between the line and the start of the column
text. It is set for the table (not per cell or column) therefore the indicator
must be zero (0).

ColumnWidth

For each column you need to specify the width (in points).
Since this is a column specific parameter, you must use the Indicator to
specify which column you are referring to.
If no width is specified then pdftool.p uses the Fields format to
determine the width.

ColumnX

For each column you need to specify the starting point of the column.
Since this is a column specific parameter, you must use the Indicator to
specify which column you are referring to.

DetailBGColor

This represents the background colour for each of the detail lines in the
columnar output (eg: the gray background in the table sample).
Since this is a table specific parameter the Indicator must be zero (0).

DetailFont

This represents the font used for each of the detail lines in the columnar
output.
Since this is a table specific parameter the Indicator must be zero (0).

DetailFontSize

This represents the font size used for each of the detail lines in the
columnar output.
Since this is a table specific parameter the Indicator must be zero (0).

DetailTextColor

66

This represents the colour used to display the text in, for each of the
detail lines in the columnar output.

PDFinclude PRO v1 Documentation

01/09/2006

Since this is a table specific parameter the Indicator must be zero (0).
HeaderBGColor

This represents the background colour for column headers (eg: the red
background in the table sample).
Since this is a table specific parameter the Indicator must be zero (0).

HeaderFont

This represents the font used for each of the column headers.
Since this is a table specific parameter the Indicator must be zero (0).

HeaderFontSize

This represents the font size used for each of the column headers.
Since this is a table specific parameter the Indicator must be zero (0).

HeaderTextColor

This represents the colour used to display the text in, for each column
header.
Since this is a table specific parameter the Indicator must be zero (0).

MaxX

This value sets the maximum value allowed for the X coordinate of a
column. Usually, this is set by pdftool.p and is primarily used to draw
the rectangle (outline) around the column.
Since this is a column specific parameter, the indicator must represent
the column you wish to adjust.

MaxY

This value sets the maximum value allowed for the Y coordinate of the
table. Usually, this is set by pdftool.p and is primarily used to determine
the height of the outline box.
Since this is a table specific parameter the Indicator must be zero (0).

Outline

This should be a decimal value representing the width of the outline

box. If zero, then no box will appear around the table elements. If nonzero, then a box will be drawn with the specified width.
Since this is a table specific parameter the Indicator must be zero (0).

For an example of how to implement the TABLE tool, check out the samples/super/table.p
procedure.

10.2CALENDAR Tool
This Calendar tool allows you to generate a calendar for a given Year/Month combination. The
Calendar ID is associated with a specific page but you can create a calendar on any page and
you can create as many calendars as you like on a specific page.
The following illustrates multiple calendars on a single page.

01/09/2006

PDFinclude PRO v1 Documentation

67

The Calendar tool has a number of parameters that can be set. Those parameters are outlined
below.
Parameter Name

Description

DayBGColor

This parameter allows you to specify what the background colour will be
for all the days within the calendar.
Since this is a calendar specific parameter the Indicator must be zero
(0).

DayFont

This parameter allows you to control the font to be used to display all
days in, or you can specify the font for a particular day.
If the Indicator is zero, then the font specified becomes the default for
all days.
If the Indicator is non-zero, and it is the same value as a day in the
calendar, then the default font is overridden and the specified font is
used instead.

DayFontColor

This parameter allows you to control the font colour to be used to

display all days in, or you can specify the font colour for a particular
day.
If the Indicator is zero, then the font colour specified becomes the
default for all days.

68

PDFinclude PRO v1 Documentation

01/09/2006

If the Indicator is non-zero, and it is the same value as a day in the

calendar, then the default font colour is overridden and the specified
font colour is used instead.
DayFontSize

This parameter allows you to control the font size to be used to display
all days in, or you can specify the font size for a particular day.
If the Indicator is zero, then the font size specified becomes the default
for all days.
If the Indicator is non-zero, and it is the same value as a day in the
calendar, then the default font size is overridden and the specified font
size is used instead.

DayHighlight

This parameter allows you to highlight a given day within the calendar.
The Indicator must represent a day within the calendars month. The
parameter value is a textual value representing why you want the
highlight.

DayLabelBGColor

This parameter allows you to specify the background colour where the
Day Labels (eg: Mon. Tues. Wed etc) are displayed.
Since this is a calendar specific parameter the Indicator must be zero
(0).

DayLabelFont

This parameter allows you to specify the Font where the Day Labels
(eg: Mon. Tues. Wed etc) are displayed.
Since this is a calendar specific parameter the Indicator must be zero
(0).

DayLabelFontColor

This parameter allows you to specify the Font colour where the Day
Labels (eg: Mon. Tues. Wed etc) are displayed.
Since this is a calendar specific parameter the Indicator must be zero
(0).

DayLabelFontSize

This parameter allows you to specify the Font size where the Day
Labels (eg: Mon. Tues. Wed etc) are displayed.
Since this is a calendar specific parameter the Indicator must be zero
(0).

DayLabelHeight

This parameter allows you to specify the height of the box surrounding
where the Day Labels (eg: Mon. Tues. Wed etc) are displayed.
Since this is a calendar specific parameter the Indicator must be zero
(0).

DayLabelY

Usually not specified.

But if required, allows you to specifically set the Y coordinate where
each day label will appear.

01/09/2006

PDFinclude PRO v1 Documentation

69

If used, then the Instance should be 1 through 7.

HeaderBGColor

This parameter allows you to specify the background colour where the
Header Label (usually month name) is displayed.
Since this is a calendar specific parameter the Indicator must be zero
(0).

HeaderHeight

This parameter allows you to specify the height of the box where the
Header Label (usually month name) is displayed.
Since this is a calendar specific parameter the Indicator must be zero
(0).

HeaderFont

This parameter allows you to specify the Font of the Header Label
(usually month name).
Since this is a calendar specific parameter the Indicator must be zero
(0).

HeaderFontColor

This parameter allows you to specify the Font colour of the Header
Label (usually month name).
Since this is a calendar specific parameter the Indicator must be zero
(0).

HeaderFontSize

This parameter allows you to specify the Font Size of the Header Label
(usually month name).
Since this is a calendar specific parameter the Indicator must be zero
(0).

Height

This parameter allows you to specify the total height of the Calendar
tool.
Since this is a calendar specific parameter the Indicator must be zero
(0).

HighlightColor

If a day is to be highlighted (see DayHighlight), then this lets you

determine what colour it should be highlighted in.
Since this is a calendar specific parameter the Indicator must be zero
(0).

Month

This parameter lets you set which month of a year (see Year) you want
to produce the calendar for.
Since this is a calendar specific parameter the Indicator must be zero
(0).

Title

This parameter allows you to set the text that will appear in the Header
section of the calendar (typically the month name and year).
Since this is a calendar specific parameter the Indicator must be zero

70

PDFinclude PRO v1 Documentation

01/09/2006

(0).
Weekdays

This parameter allows you to set the Day Labels (eg: Sun. Mon. Tue
etc) of the calendar tool. If not specified then it is defaulted to
Sun,Mon,Tue,Wed. This must be a comma-delimited list.
Since this is a calendar specific parameter the Indicator must be zero
(0).

WeekdayStart

This parameter allows you to specify which day to start the week on.
Valid values are 1 (Sunday) through 7 (Saturday).
If this value isnt set then the WeekDayStart default to 1 (Sunday).
Since this is a calendar specific parameter the Indicator must be zero
(0). Use the Parameter value to set which day to start on.

Width

Note: If you start your day on a different day that Sunday (day you want
it started on Monday) then you must also change the WeekDays
parameter to correctly reflect the day labels.
This parameter allows you to specify the total Width of the Calendar
tool.
Since this is a calendar specific parameter the Indicator must be zero
(0).

This parameter allows you to specify the X Coordinate of the Calendar

tool.
Since this is a calendar specific parameter the Indicator must be zero
(0).

This parameter allows you to specify the Y Coordinate of the Calendar

tool.
Since this is a calendar specific parameter the Indicator must be zero
(0).

Year

This parameter lets you set which year you want to produce the
calendar for (used in conjunction with the Month parameter).
Since this is a calendar specific parameter the Indicator must be zero
(0).

For an example of how to implement the CALENDAR tool, check out the
samples/super/calendar-euro.p procedure.

10.3MATRIX Tool
The Matrix tool allows you to generate a matrix (or table) on a specific page. You can have as
many matrices on one page as you like but the matrix definition/usage cannot span a page.

01/09/2006

PDFinclude PRO v1 Documentation

71

The following illustrates multiple matrices on a single page.

The Matrix tool has a number of parameters that can be set. Those parameters are outlined
below.
Parameter Name

Description

BGColor

This parameter allows you to define the background colour for each row
of the matrix.
The Indicator is used to specify which row you want to apply the
background colour to. If the Indicator is zero (0) then the colour is
applied as a default to each row of the matrix.

CellValue

This parameter lets you specify the value that will appear in each cell of
the matrix.
The Indicator represents the cell number where the Cell Value will
appear.
The cell number is determined by starting at the first possible cell of the
matrix (cell number = one) and incrementing by one for each column
and row.
eg: The following matrix has 3 rows and 5 columns. The cell number is
shown in the cell.

72

PDFinclude PRO v1 Documentation

01/09/2006

ColumnAlign

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
This parameter lets you specify the cell value alignment for a column
that will appear in the Matrix.
The Indicator must represent the column to which you are referring to.
If this value isnt set for a particular column the LEFT alignment is
assumed.
Possible values are: LEFT, RIGHT, CENTER

Columns

This parameter lets you specify the maximum number of columns that
should appear in the Matrix.
Since this is a matrix specific parameter the Indicator must be zero (0).

ColumnWidth

This parameter lets you specify the width of each column that will
appear in the Matrix.
The Indicator must represent the column to which you are referring to.

FGColor

The Indicator is used to specify which row you want to apply the text
colour to. If the Indicator is zero (0) then the colour is applied as a
default to each row of the matrix.

Font

This parameter allows you to define the font for each row of the matrix.
If not set for a row, then the current Font (see pdf_Font) for the PDF
stream is used.
The Indicator is used to specify which row you want to apply the font to.

FontSize

This parameter allows you to define the size of the font for each row of
the matrix. If not set for a row, then the current PointSize (see
pdf_PointSize) for the PDF stream is used.
The Indicator is used to specify which row you want to apply the font
sizing to.

GridColor

The parameter allows you to specify the colour of the grid line.
Since this is a matrix specific parameter the Indicator must be zero (0).

GridWeight

This parameter allows you to specify the weight of the line to be drawn
around each matrix cell.
Since this is a matrix specific parameter the Indicator must be zero (0).

Rows

This parameter lets you specify the maximum number of rows that
should appear in the Matrix.
Since this is a matrix specific parameter the Indicator must be zero (0).

01/09/2006

This parameter lets you set the starting X coordinate of the Matrix.

PDFinclude PRO v1 Documentation

73

Since this is a matrix specific parameter the Indicator must be zero (0).
Y

This parameter lets you set the starting Y coordinate of the Matrix.
Since this is a matrix specific parameter the Indicator must be zero (0).

For an example of how to implement the MATRIX tool, check out the samples/super/xml.p
procedure.

74

PDFinclude PRO v1 Documentation

01/09/2006

11.Introducing Complex Forms

Typically the phrases Progress and Complex Forms are not used within the same sentence but
with the advent of PDFinclude PRO the terms can now be used without laughter (or, at least,
without emptying your pocket book).
So, all kidding aside, how does PDFinclude PRO allow me to create Complex Forms from my
Progress application?
First off, you need to get the content that will appear on the form and there are three different
options that are available for obtaining form content. These are:

Use existing text files as content

Create content using PDFinclude PRO
o Either by static placement of data, Or
o By publishing data
Read an XML document

Secondly, you need the ability to define the graphical template that the content will be placed
onto. There are two options available for doing this and those are:

Programmatically (or statically) place your graphical elements

Build your template using MS Word and then print it through Adobe Distiller to generate a
blank PDF template. Then you can use that template from within PDFinclude PRO.

Each combination of content/template is useful depending on your circumstances. The following

table outlines the combinations and defines when they would be useful.
Content Type

Graphic Form Type

Practical Use

Existing Text File

Programmatically Generated
PDF Template

For either combination, this would

typically be used when you dont have
the ability (or need) to modify the
source output but you do want to add
graphical elements to your output.
This would be a post-generation
process.

01/09/2006

PDFinclude PRO v1 Documentation

75

PDFinclude PRO
Generated Content
Static Placement
Note: Both
combinations produce
a document during the
actual process. That
is, no post-processing
is required on the
document.
These combinations
also require program
changes.

PDFinclude PRO
Generated Content
Published Data
Note: Both
combinations produce
a document during the
actual process. That
is, no post-processing
is required on the
document.
These combinations
also require program
changes.

Read XML Document

Note: When reading
from an XML
Document you can
either perform static
placement or publish
data elements.

Programmatically Generated

This combination would be used if you

want to create a static document that
you dont want the user to modify. It
also disallows them from modifying the
placement of the content ... although
you could allow for dynamic
placement/usage of elements if you
accommodated this in your application
(eg: you let them define what their logo
will be).

PDF Template

This combination is useful if you want

the end user to control the look-andfeel of the document but they cant
control the placement of the data. This
could be used to allow the end user to
change the look-and-feel of the
graphical elements (like changing the
logo) without changing the actual data
content placement.

Programmatically Generated

This combination actually wont

produce any data content. It will use
whatever form you have generated but
no data will appear since the published
data method uses the pdf_fill_text
procedure which performs no data
placement at all.
Consider this a useless combination.

PDF Template

This combination offers the most

flexibility when producing complex
forms. It gives the end user the ability
to create their own forms, define where
data will be placed and how it will
appear.
From the application perspective, you
dont have to place data, instead you
publish an element name (eg:
InvoiceNumber) which the end user
can then use in their form definition.

Programmatically Generated
PDF Template

These combination are similar to the

PDFinclude PRO Generated Content
methods, its just that the data
elements are coming from an XML file
as opposed to the database. The data
elements can either be statically placed
or published.

Each method has its pluses and minuses and each method allows for differing control and
definition of the forms complexity.

76

PDFinclude PRO v1 Documentation

01/09/2006

In this section we are going to discuss the PDFinclude PRO Generated Content Published
Data to a PDF Template. This option offers the most functionality when creating dynamic
complex forms.

11.1Publishing Data to a PDF Template

Typically, the people who design forms arent necessarily the people who fill the forms with data.
Or they dont associate the data with the form since the data comes from an application they use.
As application developers (or users) it would be nice to give the business user the ability to define
their own form, use the data from our DB, and not have to bother us to do so.
Sounds nice. But how would you implement this into your application?
There are many tools available for doing this.
Some costs lots of money. Some dont.
Some offer lots of functionality (PDFinclude PRO has lots of functionality including
scripting, templating, compression and encryption). Others dont.
Some are easily integrated (PDFinclude PRO is written in the Progress 4GL. How easy
is that?). Others are a pain.
Anyway, were not here to discuss them. Were here to discuss PDFinclude PRO and how it can
work for you. The following subsections will hopefully illustrate the publishing/template
functionality enough that you will run to your boss and say we gotta do this its easy for us, it
will get the end users off our backs, and it will create awesome forms.

11.1.1Overview
In your typical Progress program you will not only design the form (using FORM statement,
Control Characters etc) but you will also statically place the data elements to specific coordinates
(using DISPLAY, PUT etc). So not only have you pigeon-holed yourself into static data
placement but you need to use pre-printed forms to get a visually appealing form (with your logo,
shading, different fonts, colours etc). And, of course, the placement of information may change
with each end user and/or form redesign.
To overcome these limitations (static placement and pre-printed forms) you can use PDFinclude
PRO to publish your data elements then you can also use a pre-designed form to place those
data elements onto.
Publishing data elements allows you to separate the data from the form and from the placement.
And by being able to use a pre-designed form (with colouring, images etc) you remove the need
for pre-printed forms (say cost savings).
So how do we tie the published data to the pre-defined form? Basically, the pre-defined form will
have placeholders (Adobe Form Fields) that the data will be plugged into. With these
placeholders you have the ability to dynamically position them plus you can modify the font it
uses (so you could display the Invoice Number as a BarCode), the Font Size and the Font
Colour. With this you can give the entire form design and data placement process back to the
end user. And you dont have to change any of your code even if you have multiple clients
with multiple languages (of course, you need to be able to link the process to the document it is
to produce. This will be application specific and you may need to add some additional DB fields
to handle this portion).

01/09/2006

PDFinclude PRO v1 Documentation

77

Now, that Ive confused you let me try and make it a little clearer. The following subsections
outline what has to get done to accommodate this functionality.

11.1.2Modify Your Process(es)

Since your current process is probably generating the form, you need to modify your process not
to perform any output. Instead you need to:

Tell the process which form to use

Publish the data
Produce the merged document (merging the template and the data).

A simple example of an Invoice generation routine is show below (assume that all the detail lines
will fit on one page):

{ pdf_inc.i}
DEFINE VARIABLE i_LineCounter AS INTEGER NO-UNDO.
DEFINE VARIABLE dec_Shipping
DEFINE VARIABLE dec_SubTotal

AS DECIMAL NO-UNDO.
AS DECIMAL NO-UNDO.

RUN pdf_new ("Spdf","\InvoiceDoc-Fill.pdf").

/* Set the PageFooter Routine - this is used to load subtotal/total
figures */
pdf_PageFooter ("Spdf",
THIS-PROCEDURE:HANDLE,
"PageFooter").
RUN pdf_open_PDF("Spdf","InvoiceDoc.pdf","Inv"). /* Open Template PDF
*/
/* Here is my Invoice logic */
FOR EACH Invoice WHERE Invoice.CustNum = 81 NO-LOCK,
FIRST Order WHERE Order.OrderNum = Invoice.OrderNum
NO-LOCK:
RUN DoNewPage.
ASSIGN i_LineCounter = 0
dec_SubTotal = 0
dec_Shipping = Invoice.ShipCharge.
FOR EACH OrderLine OF Order.
I_LineCounter = i_LineCounter + 1.
RUN DoOrderLine.
END.
END.
RUN pdf_close("Spdf").
/* ------------------ INTERNAL PROCEDURES ------------------ */

78

PDFinclude PRO v1 Documentation

01/09/2006

PROCEDURE DoNewPage:
RUN pdf_new_page("Spdf").
RUN pdf_use_PDF_page("Spdf","Inv",1).

/* Use Page 1 from Template */

RUN pdf_fill_text("Spdf",
"InvoiceNumber",
STRING(Invoice.InvoiceNum,"99999"),
"").
/* Set TODAYS date */
RUN pdf_fill_text("Spdf", "Today", STRING(TODAY,"99/99/99"), "").
/* Set Company Info */
RUN pdf_fill_text("Spdf",
RUN pdf_fill_text("Spdf",
RUN pdf_fill_text("Spdf",
RUN pdf_fill_text("Spdf",
RUN pdf_fill_text("Spdf",

"CompanyName","Acme", "").
"CompanyPhone","(123) 555-1234", "").
"CompanyFax","(123) 555-4321", "").
"CompanyEmail","[email protected]", "").
"CompanyWeb","www.acme.com", "").

/* Get Customer Info */

FIND Customer WHERE Customer.CustNum = Invoice.CustNum
NO-LOCK NO-ERROR.
RUN pdf_fill_text("Spdf",
"CustomerID",
STRING(Customer.CustNum,"99999"),
"").
/* Display 'To' information */
RUN pdf_fill_text("Spdf","BillTo_Name",Customer.Name,"").
RUN pdf_fill_text("Spdf","BillTo_Address1",Customer.Address,"").
RUN pdf_fill_text("Spdf","BillTo_Address2",Customer.Address2,"").
/* Display 'Ship To' Information - same as Customer for now */
RUN pdf_fill_text("Spdf","ShipTo_Name",Customer.Name,"").
RUN pdf_fill_text("Spdf","ShipTo_Address1",Customer.Address,"").
RUN pdf_fill_text("Spdf","ShipTo_Address2",Customer.Address2,"").
RUN pdf_fill_text("Spdf",
"InvoiceDate",
STRING(Invoice.InvoiceDate,"99/99/99"),
"").
RUN pdf_fill_text("Spdf",
"Shipping",
STRING(Invoice.ShipCharge,">,>>>,>>9.99"),
"").
RUN pdf_fill_text("Spdf","Terms",Order.Terms,"").
RUN pdf_fill_text("Spdf",
"OrderNumber",
STRING(Order.OrderNum,"999999"),
"").
RUN pdf_fill_text("Spdf","SalesRep",Order.SalesRep,"").
RUN pdf_fill_text("Spdf","FOB",Order.WarehouseNum,"").
END.
PROCEDURE PageFooter:
RUN pdf_fill_text("Spdf",
"SubTotal",

01/09/2006

PDFinclude PRO v1 Documentation

79

STRING(dec_SubTotal,">,>>>,>>9.99"),
"align=right").
RUN pdf_fill_text("Spdf",
"Total",
STRING(dec_SubTotal,">,>>>,>>9.99"),
"align=right").
RUN pdf_fill_text("Spdf",
"Balance",
STRING(dec_SubTotal + dec_Shipping,">,>>>,>>9.99"),
"align=center").
END.
PROCEDURE DoOrderLine:
RUN pdf_fill_text("Spdf",
"Quantity_" + STRING(i_LineCounter),
STRING(OrderLine.Qty,">,>>>,>>9.99"),
"align=right").
RUN pdf_fill_text("Spdf",
"Item_" + STRING(i_LineCounter),
OrderLine.ItemNum,
"").
RUN pdf_fill_text("Spdf",
"Units_" + STRING(i_LineCounter),
"EACH",
"").
FIND Item WHERE Item.ItemNum = OrderLine.ItemNum NO-LOCK NO-ERROR.
RUN pdf_fill_text("Spdf",
"Description_" + STRING(i_LineCounter),
Item.ItemName,
"").
RUN pdf_fill_text("Spdf",
"Discount_" + STRING(i_LineCounter),
STRING(OrderLine.Discount,">,>>>,>>9.99"),
"align=right ").
RUN pdf_fill_text("Spdf",
"UnitPrice_" + STRING(i_LineCounter),
STRING(Item.Price,">,>>>,>>9.99"),
"align=right ").
RUN pdf_fill_text("Spdf",
"Total_" + STRING(i_LineCounter),
STRING((Item.Price * OrderLine.Qty)
- OrderLine.Discount,">,>>>,>>9.99"),
"align=right").
ASSIGN dec_SubTotal = dec_SubTotal
+ (Item.Price * OrderLine.Qty)
- OrderLine.Discount.
END.

80

PDFinclude PRO v1 Documentation

01/09/2006

In the preceding example, you will see that nowhere does it say where to place data. Using the
pdf_fill_text procedure we are telling the procedure to publish the data to PDFinclude PRO which
will merge the data with the template (InvoiceDoc.pdf) to produce InvoiceDoc-Fill.pdf.
Now how do you create a template? The next section outlines this process.

11.1.3Create A Template
You, or your end user, can create the template in whichever language(s) they require. The
process is fairly simple and is outlined below.
Step 0:
Purchase Adobe Professional (www.Adobe.com) or utilize OpenOffice (www.OpenOffice.org).
The following steps outline the process when utilizing Adobe Professional.
Step 1:
Using your favourite productivity tool (eg: MS Word) create your blank template. See example
below:

Step 2:
Once your document is complete, print it through Adobe Distiller to create a blank PDF
document. See example below.

01/09/2006

PDFinclude PRO v1 Documentation

81

This has created a blank PDF document with no Form Fields.

Step 3:
Using Adobe Acrobat Professional you need to add your Form Fields.

82

PDFinclude PRO v1 Documentation

01/09/2006

The above example illustrates field placement using Adobe Form Fields. You can have as many
fields as you like and you can control the placement of the fields. For each Form Field defined
you can specify some properties.

The only properties that are utilized by PDFinclude PRO are:

01/09/2006

PDFinclude PRO v1 Documentation

83

Name
Type (must be Text)
Text Color
Font
Size

All other properties are ignored. NOTE: Do not use periods in the FieldName.
If you wanted a field printed with a BarCode font, then this is where youd set it up to do so. For
example:

The Form Field called InvoiceNumber is to be printed as Size 18 with the Code 39 font that I have
installed on my local machine (but it can be used anywhere as the fonts are embedded into the
PDF document). You can use the same Form Field name as many times as you want on the
same page, controlling how the appearance/placement will be for each of them (so have one
instance of InvoiceNumber as a BarCode while another instance would just show the numeric
value).
Once youve completed your form and field placement (which may take multiple interations), its
best to use the Save As option when creating the working template. This is due to the fact that
for each time you use the Save option Adobe saves the previous object version within itself.
This greatly increases the number of objects that PDFinclude PRO has to parse plus it also
increases the template file size. Using Save As creates a fresh copy of the file.
Thats it. With the combination of the programming required (as illustrated in the previous
section) and the template generated you can produce complex, and visually appealing forms,
from within your Progress application.
The following image illustrates the resulting merge document.

84

PDFinclude PRO v1 Documentation

01/09/2006

01/09/2006

PDFinclude PRO v1 Documentation

85

12.Sports2000 Samples
This sections gives a couple of sample procedures to run against the Sports2000 database that
is typically supplied with the Progress Installation.
The Samples assume that:
1. You are connected to the Sports2000 database
2. You have pdf_inc.i in your PROPATH
3. You have Acrobat Reader (or some other PDF viewer) installed on you machine
4. You have the free Code39 BarCode downloaded from www.barcodetrader.com.
5. You have created the code39.afm file using ttf2pt1 (See Appendix B)
6. You will need to change the directories used for file storage and retrieval (eg: the
samples use c:\sports2000 you may use another directory for testing).

12.1Hello World
The following sample produces a minimal PDF document. The output file is included in the
Zipped download and is called hello.pdf.
{ ./pdf_inc.i }
RUN pdf_new ("Spdf","c:\sports2000\PDFinc\hello.pdf").
RUN pdf_new_page("Spdf").
RUN pdf_text

("Spdf", "Hello World").

RUN pdf_close("Spdf").

12.2Hello World Compressed and Encrypted

The following sample produces a minimal PDF document that is both compressed and encrypted.
{ ./pdf_inc.i }
RUN pdf_new ("Spdf","c:\sports2000\PDFinc\hello-encrypt.pdf").
RUN pdf_new_page("Spdf").
RUN pdf_set_parameter("Spdf",Encrypt,TRUE).
RUN pdf_set_parameter("Spdf",Compress,TRUE).
RUN pdf_text

("Spdf", "Hello World").

RUN pdf_close("Spdf").

12.3Text Positioning
The following sample produces a PDF document displaying the different type of Text options
available. The output file is included in the Zipped download and is called text.pdf.
{ ./pdf_inc.i }

RUN pdf_new ("Spdf","c:\sports2000\PDFinc\text.pdf").

86

PDFinclude PRO v1 Documentation

01/09/2006

RUN pdf_new_page("Spdf").

/* Place some text */

RUN pdf_text

("Spdf", FILL("123456789 ",8)).

RUN pdf_skip

("Spdf").

RUN pdf_text_at ("Spdf", "Position AT Column 10",10).

RUN pdf_text_to ("Spdf", "Position TO Column 70",70).
RUN pdf_text

("Spdf", "Text placed at last X/Y Coordinate").

RUN pdf_skip

("Spdf").

/* Change the text color to red */

RUN pdf_text_color("Spdf",1.0,.0,.0).

RUN pdf_set_font("Spdf","Courier",14.0).
RUN pdf_text_xy ("Spdf","This is text placed using XY coordinates",100,500).
RUN pdf_set_font("Spdf","Courier",10.0).

/* Change the text color back to black */

RUN pdf_text_color("Spdf",.0,.0,.0).

/* Change the Rectangle border to red and the fill to white */

RUN pdf_stroke_color("Spdf",1.0,.0,.0).
RUN pdf_stroke_fill("Spdf",1.0,1.0,1.0).

/* Display a boxed text string */

RUN pdf_text_boxed_xy ("Spdf",
"This is BOXED text placed using XY coordinates",
100,
450,
pdf_text_width("Spdf", "This is BOXED text placed using XY coordinates"),
10,"Left",1).

RUN pdf_close("Spdf").

12.4Customer Listing
This sample produces a Customer Listing that illustrates how to create a basic PDF report. The
output file is included in the Zipped download and is called custlist.pdf.
Copy the following code into your Editor and run.

01/09/2006

PDFinclude PRO v1 Documentation

87

/* custlist.p - sample PDF generation */

{ ./pdf_inc.i }
DEFINE VARIABLE Vlines
DEFINE VARIABLE Vpage
DEFINE VARIABLE Vold_Y

AS INTEGER NO-UNDO.
AS INTEGER NO-UNDO.
AS INTEGER NO-UNDO.

/* Create stream for new PDF file */

RUN pdf_new
("Spdf","c:\sports2000\PDFinc\custlist.pdf").
/* Load Bar Code Font */
RUN pdf_load_font ("Spdf","Code39","c:\windows\fonts\code39.ttf","c:\sports2000\code39.afm").
/* Load PRO-SYS Logo File */
RUN pdf_load_image ("Spdf","ProSysLogo","c:\sports2000\pdfinc\prosyslogo.jpg",1354,166).
/* Set Document Information */
RUN pdf_set_info("Spdf","Author","Gordon Campbell").
RUN pdf_set_info("Spdf","Subject","Accounts Receivable").
RUN pdf_set_info("Spdf","Title","Customer List").
RUN pdf_set_info("Spdf","Keywords","Customer List Accounts Receivable").
RUN pdf_set_info("Spdf","Creator","PDFinclude").
RUN pdf_set_info("Spdf","Producer","custlist.p").
/* Instantiate a New Page */
RUN new_page.
/* Loop through appropriate record set */
FOR EACH customer WHERE NAME BEGINS "AB" NO-LOCK
BREAK BY State
BY CustNum:
/* Output the appropriate Record information */
RUN pdf_set_font ("Spdf","Courier-Oblique",10.0).
RUN pdf_text_at ("Spdf", customer.state,1).
RUN pdf_set_font ("Spdf","Courier",10.0).
RUN pdf_text_at ("Spdf", STRING(customer.CustNum,">>>9"),6).
RUN pdf_text_at ("Spdf", customer.NAME,12).
RUN pdf_text_at ("Spdf", customer.phone,44).
RUN pdf_text_to ("Spdf", STRING(customer.balance),80).
/* Display a BarCode for each Customer Number */
RUN pdf_set_font ("Spdf","Code39",10.0).
Vold_Y = pdf_TextY("Spdf"). /* Store Original Text Path */
RUN pdf_text_xy ("Spdf", STRING(customer.CustNum,"999999"),500, pdf_textY("Spdf")).
RUN pdf_set_TextY("Spdf",Vold_y). /* Reset Original Text Path */
RUN pdf_set_font ("Spdf","Courier",10.0).
/* Skip to Next Line */
RUN pdf_skip ("Spdf").
/* Process Line Counter */
Vlines = Vlines + 1.
IF Vlines = 60 THEN
RUN new_page.
IF LAST-OF(State) THEN DO:
IF Vlines + 2 > 60 THEN
RUN new_page.

88

PDFinclude PRO v1 Documentation

01/09/2006

/* Put a red line between each of the states */

RUN pdf_skip ("Spdf").
RUN pdf_stroke_color ("Spdf",1.0,.0,.0).
RUN pdf_set_dash ("Spdf",2,2).
RUN pdf_line ("Spdf", pdf_LeftMargin("Spdf") , pdf_TextY("Spdf") + 5, pdf_PageWidth("Spdf") - 20 ,
pdf_TextY("Spdf") + 5, 1).
pdf_stroke_color ("Spdf",.0,.0,.0).
pdf_skip ("Spdf").
Vlines = Vlines + 2.
END. /* Last-of State */
END.
RUN end_of_report.
RUN pdf_close("Spdf").
/* -------------------- INTERNAL PROCEDURES -------------------------- */
PROCEDURE new_page:
/* Display Footer UnderLine */
IF Vpage > 0 THEN
RUN page_footer.
RUN pdf_new_page("Spdf").
Vpage = Vpage + 1.
/* Place Logo but only on first page of Report */
IF Vpage = 1 THEN DO:
RUN pdf_place_image ("Spdf","ProSysLogo",pdf_LeftMargin("Spdf"), pdf_TopMargin("Spdf") - 20
,179,20).
END.
/* Set Header Font Size and Colour */
RUN pdf_set_font ("Spdf","Courier-Bold",10.0).
RUN pdf_text_color ("Spdf",1.0,.0,.0).
/* Put a Rectangle around the Header */
RUN pdf_stroke_color ("Spdf", .0,.0,.0).
RUN pdf_stroke_fill ("Spdf", .9,.9,.9).
RUN pdf_rect ("Spdf", pdf_LeftMargin("Spdf"), pdf_TextY("Spdf") - 3, pdf_PageWidth("Spdf") - 30 ,
pdf_TextX("Spdf") + 12).
/* Output Report Header */
RUN pdf_text_at ("Spdf","St",1).
RUN pdf_text_at ("Spdf","Nbr",6).
RUN pdf_text_at ("Spdf","Customer Name",12).
RUN pdf_text_at ("Spdf","Phone Number",44).
RUN pdf_text_to ("Spdf","Balance",80).
/* Display Header UnderLine */
RUN pdf_skip ("Spdf").
RUN pdf_set_dash ("Spdf",1,0).
RUN pdf_line ("Spdf", pdf_LeftMargin("Spdf"), pdf_TextY("Spdf") + 5, pdf_PageWidth("Spdf") - 20 ,
pdf_TextY("Spdf") + 5, 2).
RUN pdf_skip ("Spdf").
/* Set Detail Font Colour */
RUN pdf_text_color ("Spdf",.0,.0,.0).

01/09/2006

PDFinclude PRO v1 Documentation

89

Vlines = 3.
END. /* new_page */
PROCEDURE page_footer:
RUN pdf_skip ("Spdf").
RUN pdf_set_dash ("Spdf",1,0).
RUN pdf_line ("Spdf", 0, pdf_TextY("Spdf") - 5, pdf_PageWidth("Spdf") - 20 , pdf_TextY("Spdf") - 5, 2).
RUN pdf_skip ("Spdf").
RUN pdf_skip ("Spdf").
RUN pdf_text_to ("Spdf","Page: " + STRING(Vpage), 97).
END. /* page_footer */
PROCEDURE end_of_report:
RUN page_footer.
/* Display Footer UnderLine and End of Report Tag (Centered) */
RUN pdf_skip ("Spdf").
RUN pdf_stroke_fill ("Spdf",1.0,1.0,1.0).
RUN pdf_text_boxed_xy ("Spdf", "End of Report", 250, pdf_TextY("Spdf") - 20,
pdf_Text_Width("Spdf","End Of Report"), 12, "Left",1).
END. /* end_of_report */
/* end of custlist.p */

12.5Formatted Item Listing

This sample produces a Item Listing that illustrates how you can control the output of a fairly
custom PDF report. The output file is included in the Zipped download and is called itemlist.pdf.
Copy the following code into your Editor and run.
/* itemlist.p - sample PDF generation */
{ ./pdf_inc.i }
DEFINE VARIABLE Vitems
AS INTEGER NO-UNDO.
DEFINE VARIABLE Vrow
AS INTEGER NO-UNDO.
DEFINE VARIABLE Vcat-desc AS CHARACTER EXTENT 4 FORMAT "X(40)" NO-UNDO.
/* Create stream for new PDF file */
RUN pdf_new
("Spdf","c:\sports2000\PDFinc\itemlist.pdf").
/* Load Bar Code Font */
RUN pdf_load_font ("Spdf","Code39","c:\windows\fonts\code39.ttf","c:\sports2000\code39.afm").
/* Set Document Information */
RUN pdf_set_info("Spdf","Author","Gordon Campbell").
RUN pdf_set_info("Spdf","Subject","Inventory").
RUN pdf_set_info("Spdf","Title","Item Catalog").
RUN pdf_set_info("Spdf","Keywords","Item Catalog Inventory").
RUN pdf_set_info("Spdf","Creator","PDFinclude").
RUN pdf_set_info("Spdf","Producer","itemlist.p").
/* Instantiate a New Page */
RUN new_page.
/* Loop through appropriate record set */
FOR EACH ITEM NO-LOCK
BREAK BY ItemNum:

90

PDFinclude PRO v1 Documentation

01/09/2006

RUN display_item_info.
/* Process Record Counter */
Vitems = Vitems + 1.
IF Vitems = 6 THEN
RUN new_page.
END.
RUN pdf_close("Spdf").
/* -------------------- INTERNAL PROCEDURES -------------------------- */
PROCEDURE display_item_info:
/* Draw main item Box */
RUN pdf_stroke_fill("Spdf",.8784,.8588,.7098).
RUN pdf_rect ("Spdf", pdf_LeftMargin("Spdf"), Vrow, pdf_PageWidth("Spdf") - 20 , 110).
/* Draw Smaller box (beige filled) to contain Category Description */
RUN pdf_rect ("Spdf", 350, Vrow + 10, 240, 45).
/* Draw Smaller box (white filled) to contain Item Picture (when avail) */
RUN pdf_stroke_fill("Spdf",1.0,1.0,1.0).
RUN pdf_rect ("Spdf", pdf_LeftMargin("Spdf") + 10, Vrow + 10, pdf_LeftMargin("Spdf") + 100 , 90).

/* Display Labels with Bolded Font */

RUN pdf_set_font("Spdf","Courier-Bold",10.0).
RUN pdf_text_xy ("Spdf","Part Number:", 140, Vrow + 90).
RUN pdf_text_xy ("Spdf","Part Name:", 140, Vrow + 80).
RUN pdf_text_xy ("Spdf","Category 1:", 140, Vrow + 40).
RUN pdf_text_xy ("Spdf","Category 2:", 140, Vrow + 30).
RUN pdf_text_xy ("Spdf","Qty On-Hand:", 350, Vrow + 90).
RUN pdf_text_xy ("Spdf","Price:", 350, Vrow + 80).
RUN pdf_text_xy ("Spdf","Category Description:", 350, Vrow + 60).
/* Display Fields with regular Font */
RUN pdf_set_font("Spdf","Courier",10.0).
RUN pdf_text_xy ("Spdf",STRING(item.ItemNuM), 230, Vrow + 90).
RUN pdf_text_xy ("Spdf",item.ItemName, 230, Vrow + 80).
RUN pdf_text_xy ("Spdf",item.Category1, 230, Vrow + 40).
RUN pdf_text_xy ("Spdf",item.Category2, 230, Vrow + 30).
RUN pdf_text_xy ("Spdf",STRING(item.OnHand), 440, Vrow + 90).
RUN pdf_text_xy ("Spdf",TRIM(STRING(item.Price,"$>>,>>9.99-")), 440, Vrow + 80).
/* Now Load and Display the Category Description */
RUN load_cat_desc.
RUN pdf_text_xy ("Spdf",Vcat-desc[1], 352, Vrow + 46).
RUN pdf_text_xy ("Spdf",Vcat-desc[2], 352, Vrow + 36).
RUN pdf_text_xy ("Spdf",Vcat-desc[3], 352, Vrow + 26).
RUN pdf_text_xy ("Spdf",Vcat-desc[4], 352, Vrow + 16).
/* Display text in Image Box */
RUN pdf_text_color("Spdf",1.0,.0,.0).
RUN pdf_text_xy ("Spdf","NO", 40, Vrow + 66).
RUN pdf_text_xy ("Spdf","IMAGE", 40, Vrow + 56).
RUN pdf_text_xy ("Spdf","AVAILABLE", 40, Vrow + 46).
RUN pdf_text_color("Spdf",.0,.0,.0).

01/09/2006

PDFinclude PRO v1 Documentation

91

/* Display the Product Number as a Bar Code */

RUN pdf_set_font("Spdf","Code39",14.0).
RUN pdf_text_xy ("Spdf",STRING(item.ItemNuM,"999999999"), 140, Vrow + 60).
Vrow = Vrow - 120.
END. /* display_item_info */
PROCEDURE new_page:
RUN pdf_new_page("Spdf").
/* Reset Page Positioning etc */
ASSIGN Vrow = pdf_PageHeight("Spdf") - pdf_TopMargin("Spdf") - 110
Vitems = 0.
END. /* new_page */
PROCEDURE load_cat_desc:
DEFINE VARIABLE L_cat AS CHARACTER NO-UNDO.
DEFINE VARIABLE L_loop AS INTEGER NO-UNDO.
DEFINE VARIABLE L_extent AS INTEGER NO-UNDO.
ASSIGN Vcat-desc = ""
L_cat
= item.catdescr.
REPLACE(L_cat,CHR(13),"").
REPLACE(L_cat,CHR(10),"").
L_extent = 1.
DO L_Loop = 1 TO NUM-ENTRIES(L_cat," "):
IF (LENGTH(Vcat-desc[L_extent]) + LENGTH(ENTRY(L_loop,L_cat," ")) + 1) > 40
THEN DO:
IF L_extent = 4 THEN LEAVE.
L_extent = L_extent + 1.
END.
Vcat-desc[L_extent] = Vcat-desc[L_extent] + ENTRY(L_loop,L_cat," ") + " ".
END.
END. /* load_cat_desc */
/* end of itemlist.p */

92

PDFinclude PRO v1 Documentation

01/09/2006

Appendix A Embedding Fonts

As previously mentioned, you need to be legally responsible when embedding True Type Font
files into any documents. Most fonts are embeddable but not distributable. In order to ascertain
whether you can legally embed the TTF file you should download the Extended Font Viewer from
Microsoft.
The Extended Font Viewer can be obtained via the following link:
http://www.microsoft.com/typography/property/property.htm?fname=%20&fsize=

Once installed you can right-click on a TTF file, select the Properties option and the following
screen (or very similar dependant on Windows version) will appear.

Click on the Embedding tab. Here you will see the license options available for the Font file.
Basically, if it says that you have Restricted License Embedding then you cannot legally embed
the font file.
PRO-SYS is not legally responsible for any actions you take with embedding font files into your
PDF file.

01/09/2006

PDFinclude PRO v1 Documentation

93

Appendix B Creating AFM File

The Adobe Font Metrics (AFM) file is used by PDFinclude PRO to determine how the glyphs (or
characters) should appear when displayed by a PDF viewer (such as Adobe Acrobat).
The AFM file stores information such as glyph widths, is the font italicized, glyphs defined etc.
PDFinclude PRO does not generate the AFM file for you. Instead you must resort to using a free
utility called ttf2pt1. This utility will read a TTF file and generate the AFM file.
To download ttf2pt1 go to the following link:
http://ttf2pt1.sourceforge.net/
Or you can download the binary executable for Windows from:

http://www.epro-sys.com/downloads/ttf2pt1.zip
The utility is written in C and must be compiled into binary executable format on whichever
platform you are running.
Note: PRO-SYS was unable to compile the 3.4.0 version but we were able to compile the 3.3.5
version.

Once installed and compiled, the process to create the AFM file is very simple. The following
command can be used as an example.
ttf2pt1 A \windows\fonts\arial.ttf arial

The A is important. This option actually indicates to ttfpt1 that it must output an AFM file.
You may wish to read the documentation that comes with the download for a further
understanding of what ttf2pt1 is capable of.

PRO-SYS does not resell ttf2pt1 as a component of the PDFinclude PRO package. If you have
another tool that generates AFM files then by all means use it.
PRO-SYS does not support ttf2pt1 and is not legally responsible for anything related to the utility.

94

PDFinclude PRO v1 Documentation

01/09/2006