DLI Implementation and Reference Guide - Datalogics

Implementation and 

Reference Guide 

Datalogics Interface 

Datalogics ®

Datalogics 

DATALOGICS INTERFACE 

Implementation and Reference Guide

This guide is part of the Adobe® PDF Library v6.1.1Plus suite; 02/15/05. 

Copyright 1999-2005 Datalogics Incorporated. All Rights Reserved. 

Use of Datalogics software is subject to the applicable license agreement. 

DL Interface is a trademark of Datalogics Incorporated. Other products mentioned herein as Datalogics products 

are also trademarks or registered trademarks of Datalogics, Incorporated. 

Adobe, Adobe PDF Library, Portable Document Format (PDF), PostScript, Acrobat, Distiller, Exchange and 

Reader are trademarks of Adobe Systems Incorporated. 

HP and HP-UX are registered trademarks of Hewlett Packard Corporation. 

IBM, AIX, AS/400, OS/400, MVS, and OS/390 are registered trademarks of International Business Machines. 

Java, J2EE, J2SE, J2ME, all Java-based marks, Sun and Solaris are trademarks or registered trademarks of Sun 

Microsystems, Inc. in the United States and other countries. 

Linux is a registered trademark of Linus Torvalds. 

Microsoft, Windows and Windows NT are trademarks or registered trademarks of Microsoft Corporation. 

SAS/C is a registered trademark of SAS Institute Inc. 

UNIX is a registered trademark of The Open Group. 

VeriSign® is a registered trademark of VeriSign, Inc. in the United States and/or other countries. 

All other trademarks and registered trademarks are the property of their respective owners. 

For additional information, contact: 

Datalogics, Incorporated 

101 North Wacker Drive, Suite 1800 

Chicago, Illinois 60606-7301 

Phone: 312-853-8200 

Fax: 312-853-8282 

www.datalogics.com 

dlcomments@datalogics.com

Table of Contents 

i 


1 Getting Started 1.1 

An Introduction to DLI 1.2 

How to Create a PDF Document with DLI 1.2 

How to Use this Book 1.5 

What’s New in This Release 1.11 

Enhancements in Prior Releases 1.20 

2 Initializing and Terminating the Library 2.1 

Overview 2.2 

Adobe PDF Library Data Structure 2.2 

Adobe PDF Library Version Control 2.6 

Files In Memory Activation 2.8 

Initializing and Terminating via DLI 2.8 

Writing PDF Output to Memory 2.15 

API Comparison 2.17 

3 Beginning and Ending a Document 3.1 

Overview 3.2 

4 Fonts 4.1 

PDF Font Overview 4.2 

Structure of a DLI Font 4.4 

Font Creation Calls 4.6 

Predefined Font Encodings 4.11 

Unicode Text Support 4.13 

Code Page Support 4.13 

Performance Considerations 4.13

ii 

DLI Implementation and Reference Guide 

Accessing Fonts 4.15 

5 Multibyte Text Work 5.1 

Concepts and Facilities: Guide to the DL Pager Composition System 

Introduction 5.2 

Loading and Creating Fonts 5.3 

Creating DLPDFTEXT Areas 5.5 

Working With DLPDFTEXT Areas 5.7 

Performance Considerations 5.10 

6 Working with Pages 6.1 

Introduction to Page Interface 6.2 

Page Interface Calls 6.2 

7 Containers within Pages 7.1 

What are Containers? 7.2 

8 Working 

with Content 8.1 

Overview of Content Interface 8.2 

Content Interface Calls 8.3 

9 Working 

with Forms 9.1 

Overview of Forms 9.2 

Form Calls 9.3 

10 Displaying Line Drawings 10.1 

Overview 10.2 

Approaches to Line Drawing 10.3 

Graphic State and Line Drawing 10.17


iii 

11 Image 

Display 11.1 

Overview 11.2 

Graphic Image Structures 11.2 

Graphic Image Forms 11.3 

Image Creation Methods 11.5 

Creating Transparent Graphics 11.12 

12 Color 

and its Use 12.1 

Library Color Descriptions 12.2 

Colors in Images 12.3 

Creating and Destroying Color Spaces 12.3 

Values for Color Channels 12.6 

Basic Color Spaces 12.7 

Advanced Color Spaces 12.11 

Building Patterned Color Spaces 12.13 

Conversion between Models 12.16 

13 Annotations and Links 13.1 

Overview 13.2 

Annotation Components 13.2 

Modifying the Link Cos Object 13.9 

14 Bookmark Creation 14.1 

Overview 14.2 

15 Digital Signatures 15.1 

Overview 15.2 

Public and Private Keys 15.2

iv 


Digital Signature Calls 15.4 

16 Error 


Testing and Recovery 16.1 

Overview 16.2 

OS/390 Platform Concerns 16.4 

17 Samples 

and Links 17.1 

Running DLI Sample Applications 17.2 

A DLI Reference Guide A.1

1 

Getting Started 

This chapter introduces the Datalogics Interface. 

Experienced users may want to skip directly to the 

section “What’s New in This Release” on page 1.11 for 

information on the latest enhancements and additions. 

1.1

1.2 DLI Implementation and Reference Guide 

An Introduction to DLI 

The Datalogics Interface (DLI) facilitates the rapid creation of PDF documents and 

improves performance, throughput and graphics handling. It does this by bypassing 

many of the functions of the PDF Edit layer and eliminating redundant calls to the 

COS layer used in the Adobe® PDF Library. For information on the various layers of 

Adobe PDF Library please see the Acrobat Core API Overview. 

How to Create a PDF Document with 

DLI 

The DLI package exists at the output end of the page creation process. As such, most 

of the intricacies of line breaking, page breaking and general composition are outside 

of its scope. 

The process of writing pages is where this package fits into an application. An 

overview of this process follows: 

1 Initialize DLI. (start of all processing) 

2 Define the document. 

3 Define fonts: i.e. Identify and describe each font to be used in the job to DLI. 

These can be done as encountered, if so desired. 

4 Define forms: i.e. Identify and describe each form to be used in the job to DLI. 

These can be done as encountered, if so desired. 

5 Define graphics: i.e. Identify and define each graphic to be used multiple times to 

DLI. These can be done as encountered, if so desired. 

6 For each page: 

• Create a dlpdfpage object. 

• Create a dlpdfcontent object. 

7 Generate the content of a single page: 

• For each graphic reference on the page, create the graphic in content. 

• For each text line on the page, create the text in content. 

8 End the content and inform DLI that the content is complete. 

9 End the page and inform DLI that the page is complete.

Getting Started 1.3 

10 End the document. 

11 End the job. 

Error handling during application execution is handled through the raising and 

handling of exceptions, as defined by the Adobe PDF Library. These are similar to 

operation exceptions in C++. For details on handling exceptions, please see the 

chapter “Error Testing and Recovery” on page 16.1. 

What You Should Know 

This document is intended for programmers who are familiar with text composition 

and the creation of output drivers, or by application designers who are constructing 

an application based on the DLI package. 

You should have access to the Adobe PDF Library Applications Programming 

Interface (API) manual and the Adobe PDF Specifications manual for your system. 

For Adobe PDF Library v5.x releases, Adobe PDF Specification 1.4 is appropriate.For 

Adobe PDF Library v6.x releases, Adobe PDF Specification 1.5 is appropriate. 

NOTE: Some structures permitted in Adobe PDF Specification 1.5 may not be 

permitted in Adobe PDF Specification 1.4, and some structures defined in Adobe 

PDF Specification 1.4 are not available in Adobe PDF Specification 1.3. 

The explanations, assumptions and samples provided in this guide refer to Adobe 

PDF Library v6.1.0Plus and DLI v3.0 or higher. 

DLI Initialization Required 

Starting with DLI v2.1, the initialization process has been simplified such that you 

must initialize DLI to automatically initialize the Adobe PDF Library. Though it may 

be functionally possible to bypass the initialization of DLI for versions 2.1 and higher, 

an application should not do so. Using the DLI initialization and termination routines 

not only simplifies application programming but also allows the use of the Datalogics


Files In Memory (FIM) System, and the enabling of certain optimizations in jobs 

which span multiple documents. 

NOTE: The Adobe PDF Library and DLI are not intended to be initialized more than 

once within a single instance of an application. Doing so can produce undesirable 

results. Versions of Adobe PDF Library prior to v6.1 are not thread-safe. 

gcc Compilation Version 

Adobe compiles their PDF Library components with gcc 2.95.2 on the Solaris®, 

AIX® and Linux® operating systems. Datalogics does not recompile Adobe 

components on any other compiler on these operating systems. Datalogics only 

distributes the Adobe PDF Library and the DLI components compiled using gcc on 

these operating systems. For the latest information on supported operating-system 

compilers and versions, please see the readme.txt file of last-minute updates 

accompanying your software release files. 

Unix Compiler Run-Time Libraries 

For clients who are using native (i.e. platform-resident) UNIX® compilers, the runtime 

libraries for each of these operating systems are available from the Free Software 

Foundation. Any clients wishing to integrate the Adobe PDF Library and DLI 

components with their natively-compiled applications can retrieve these run-time 

libraries free of charge from the Free Software Foundation at http:// 

www.gnu.org/software/gcc/.


How to Use this Book 

This book has been created to guide you through the process of creating PDF 

documents with DLI. It consists of two main sections: 

• An Implementation section 

• A Reference Guide appendix 

The Implementation section begins with Chapter 1: Getting Started. It follows the 

steps needed to create PDF and introduces DLI in relation to the Adobe PDF Library, 

explains the methods used in DLI, how they fit together, and provides various 

samples. 

The Reference Guide appendix lists all DLI methods alphabetically. 

Each function or method listed in the first section of this manual, wherever it occurs, 

is linked to the same function or method in the second section. In some cases you may 

find references to a particular function appearing in several chapters of this document, 

depending on the context, and the function may be used for (and explained for) 

different purposes within each chapter. Click the function name to go to the more 

detailed reference information, which will provide full explanation of each, a full 

listing of calling parameters and return values, and any Technical Notes which may 

apply. 

You may also find a separate, standalone /Codesamples folder in your 

documentation files which contains additional ASCII-text coding samples. 

NOTE: The files in the /Codesamples folder, if present, are not intended to be 

buildable source as-is, only to be demonstrations of correct command syntax for 

different purposes. 

Finally, the DLI release also includes a collection of complete, buildable sample 

applications, explained in the "Samples and Links" chapter following. 

The following list provides an outline of the chapters as well as a brief description of 

their contents. Click on the Chapter title below to jump to its first page.


Chapter 1: "Getting Started" (This chapter) This chapter introduces the Adobe 

PDF Library and DLI, including an overview of page creation, and describes the 

contents of this book, including enhancements in new releases of DLI. 

Chapter 2: "Initializing and Terminating the Library" describes 

initialization and termination of the Adobe PDF Library. 

Chapter 3: "Beginning and Ending a Document" describes all of the 

methods used to begin and end a document. 

Chapter 4: "Fonts" discusses creation and arrangement of fonts. 

Chapter 5: "Multibyte Text Work" discusses the DLI methods available for 

creating and manipulating multibyte text. 

Chapter 6: "Working with Pages" DLI assumes that pages will be added to the 

end of the document only. A page is represented by a data structure named 

DLPDFPAGE. This chapter explains the Page Interface and defines the calls available at 

this level. 

Chapter 7: "Containers within Pages" describes containers within pages, and 

provides examples of various applications. 

Chapter 8: "Working with Content" The Content Interface contains the bulk of 

the interface. At this level, you make marks on paper. Those marks may be on a Page 

or on a Forms XObject. They may be text, line drawings or images. A content element 

is represented by the structure DLPDFCONTENT. This chapter explains the Content 

Interface and defines the calls available at this level. 

Chapter 9: "Working with Forms" Forms XObjects are represented via the 

structure DLPDFFORM. This chapter explains forms, and defines the calls available. 

Chapter 10: "Displaying Line Drawings" describes line drawings and the 

different approaches, including directly-drawn and path-drawn methods. 

Chapter 11: "Image Display" describes images as a predefined collection of 

shapes and colors.


Chapter 12: "Color and its Use" discusses Adobe PDF Library color 

descriptions, colors in images, creating and destroying color spaces, patterned color 

spaces and more. 

Chapter 13: "Annotations and Links" describes creating annotations and how 

to modify the Link COS Structure. 

Chapter 14: "Bookmark Creation" describes bookmark creation and the steps 

involved. 

Chapter 15: "Digital Signatures" explains the process of adding a digital 

signature to a document, and outlines the methods for use. 

Chapter 16: "Error Testing and Recovery" discusses possible errors you may 

encounter and how to resolve them. 

Chapter 17: "Samples and Links" provides full program samples which have 

been compiled and tested to illustrate various aspects of the Adobe PDF Library and 

DLI. 

Appendix A: "DLI Reference Guide" provides an alphabetical listing of all 

methods used in DLI. 

Document Conventions 

The terms note, link and bookmark are used in this book the same way they are in the 

user interface of Adobe PDF Library v6.1.0Plus®, Acrobat®, Acrobat Exchange® 

and Adobe Reader®. These correspond to the text annotation, link annotation and 

routine entry structures (respectively) that appear in a PDF file. See the Portable 

Document Format Reference Manual for a description of the PDF file format.


The following documentation conventions appear throughout the manual to help you 

differentiate regular text from product and program names, and to distinguish 

command syntax. 

• Product and program names are set in italic type. 

• Multi-line examples are separated from the text and set in 

Courier monospace 

• Directory names and filenames are contained within the text and set in Courier 

monospace. 

• Commands are contained within the text and set in blue Courier monospace. In 

most cases, if you are reading this document in PDF form via Adobe Acrobat or 

Adobe Reader, clicking on a DLI command will jump you to the Reference Guide 

appendix for full information on that command. 

• New terms are italicized. 

• Page numbers in this book do not correspond to page numbers in the PDF file. The 

numbering scheme (e.g. 4.1 or A.10) indicates the chapter number (4) or appendix 

letter (A) first, followed by the page number (1 or 10), separated by a period.


Related Documentation 

The following documents will be useful in developing applications using DLI. 

Datalogics Resources 

Adobe PDF Library and DLI Installation Guide This document describes the 

installation requirements for using the Adobe PDF Library and DLI on the various 

platforms to which Datalogics has ported these products. 

Adobe PDF Library Developer Overview This document is designed to aid 

developers with incorporating the API calls for the Adobe PDF Library into their 

composition application. 

DLI Implementation and Reference Guide (This book) This document details 

the Datalogics Interface, a simplified interface to the COS Layer of the Adobe PDF 

Library. 

Java Interface User Guide This document details the Datalogics Java Interface, 

a Java-language wrapper interface to the Adobe PDF Library and DLI. 

Adobe Resources 

The following documents are distributed by Adobe as part of the original Adobe PDF 

Library release, and are redistributed by Datalogics without alteration. These and 

other documents may also be found on the Adobe website at http://


partners.adobe.com/asn/acrobat/technotes.jsp. (Descriptions below 

are provided by Adobe as part of their original accompanying readme.txt file.) 

NOTE: Adobe Solutions Network (ASN) membership may be required in order to 

access some material on the Adobe website. See http:// 

partners.adobe.com/asn/programs/developer/index.jsp for 

more details. 

Portable Document Format Reference Manual This document describes 

PDF Standard 1.5 specifications. The latest version may be found at http:// 

partners.adobe.com/asn/tech/pdf/specifications.jsp. 

NOTE: Adobe also provides an accompanying errata file for this manual, with lastminute 

updates and corrections. One copy is provided with this documentation 

(see your documentation file folder), and you can check for newer copies at 

http://partners.adobe.com/asn/acrobat/sdk/public/docs/ 

errata.txt 

Adobe PDF Library Overview Technical Note #5189 provides background 

information and development information for the Adobe PDF Library. Read this 

document before beginning development for information such as supported 

platforms, known issues and development requirements. 

Acrobat Core API Overview Technical Note #5190 provides an overview of the 

Acrobat API in general. It covers information applicable to both Plug-in development 

and Library development. Read this document to obtain an understanding of how the 

Acrobat API is organized. 

AcroColor API Reference Technical Note #5425 explains the Host Function 

Table (HFT) that allows you to access the AcroColor Engine (ACE), which controls 

color profile. 

Acrobat Core API Reference Technical Note #5191 is the reference manual for 

all of the Acrobat API methods made available by the Acrobat Viewer. It documents 

the parameters, return values and availability of each method, as well as specific


implementation notes. This document is useful while developing with the Adobe PDF 

Library or planning development to determine method availability and capabilities. 

PDF Library Supplement to the Acrobat Core API Technical Note #5414 

complements the Acrobat Core API Reference and is specific to the Adobe PDF 

Library API methods. This is an important and useful document for all Adobe PDF 

Library developers. 

What’s New in This Release 

This section contains highlights of new additions and enhancements to DLI v3.0. You 

should also check the accompanying Release Notes file (typically 

ReleaseNotes.pdf) and readme.txt files (one each accompanies the software 

release files and the documentation files in their respective folders or directories). 

Release Notes contain fixes and enhancements usually resulting from past problem 

reports; the readme.txt files typically contain last-minute information on the 

current release of the software or the documentation files. 

Minor version upgrades may be made as running changes rather than full releases, so 

the version or sub-version number of your release may be newer than those listed 

here. See the accompanying readme.txt file for the very latest changes and 

enhancements. 

DLI v3.0 for Adobe PDF Library v6.x will feature a number of changes, briefly 

outlined here. 

Adobe PDF Library Now Thread-Safe 

As of Adobe PDF Library v6.1.0Plus and DLI v3.0.11, the Library is now re-entrant, 

and therefore safe for multithreaded applications. See the following chapter and 

“Multi-Thread Initializations” on page 2.13 for more information on thread-safety 

issues.


Adobe PDF Library Version Control 

The Adobe PDF Library is a set of routines associated with other Adobe products 

such as Adobe Acrobat, Adobe Acrobat Distiller and Adobe Reader. The original 

Adobe PDF Library was labeled as version 1.2 in order to maintain consistency with 

the PDF standard of 1.2. The next version of the Library was labeled version 4.0 (and 

subsequently 4.05) due to the tie-in with Acrobat v4.0. Versions 4.0/4.05 of the 

Library complied with the PDF standard of 1.3. Adobe PDF Library v5.0.2Plus 

complies with PDF Standard 1.4, and the latest Adobe PDF Library v6.x complies 

with PDF Standard 1.5. 

PDF Level Declarations in Output 

By default, the Adobe PDF Library declares the current PDF level compliance in 

output PDF files; e.g. Adobe PDF Library v6.x applications building pages without 

Datalogics Interface methods will generate PDF v1.5. Applications generating output 

via DLI may generate different PDF declarations depending on file contents and 

application coding; see below and “Adobe PDF Library Version Control” on page 2.6 

for more details. 

NOTE: Viewing a latest-generation PDF in a prior-version Adobe Acrobat or Adobe 

Reader (e.g. viewing PDF v1.5 in Acrobat or Reader v5.0 or earlier) can produce a 

popup warning of a PDF level mismatch, to warn the user that certain PDF features 

new to that version may not be supported by the viewing program. While this is 

only a warning, it may concern some users who have not upgraded to the latest 

viewer. You should ensure that your document features are backwards-compatible 

to older viewer versions where possible, or warn your users that a viewer upgrade 

will be required in order to take full advantage of features in your document, as 

appropriate. 

PDF Level Declarations via DLI 

Applications built with Adobe PDF Library and Datalogics Interface (e.g. Adobe PDF 

Library v6.1.1Plus and DLI v3.0.19) and using DLI methods for output will have 

their output PDF compliance set appropriately by DLI. By default, files will identify 

themselves as PDF v1.3 compliant, or higher values if appropriate, based on the


functionality embedded in the document. Some further explanation can be found 

under “Selecting PDF Level Declarations via DLI” on page 2.7. 

Digital Signature Support 

New methods are now available for adding Digital Signatures to your documents, and 

a new chapter on the subject has been added to this manual. See the new chapter 

“Digital Signatures” on page 15.1 for more details. 

Enhanced Unicode Support 

Unicode support included in DLI has undergone significant revision for the new v3.x 

series. Datalogics now ships with International Components for Unicode (ICU) 

modules, which provide a number of benefits for users, including: 

• Complete TrueType, OpenType and TrueType/OpenType Collection font file 

support 

• Support for all major Unicode encoding schemes, as well as hundreds of Chinese/ 

Japanese/Korean/Vietnamese and vendor-standard input formats 

• Support for right-to-left text ordering and automatic character combining using the 

Unicode BiDirectional algorithm 

• Faster and less-memory-intensive creation of Unicode fonts 

• Text output in PDF content areas as Unicode 

NOTE: Since Unicode font creation does not use the Adobe PDF Library to locate 

fonts, customers must now explicitly load fonts intended for Unicode into a 

DLPDFINSTANCE before use. Additionally, users must be able to specify the 

system location where these fonts reside. See the DLI sample application 

WideText for a demonstration of loading and using Unicode fonts. 

Addition of DLPDFTEXT Structure 

In support of the revised Unicode architecture, the object DLPDFTEXT has been 

created. This is a reusable container for text: an input string is supplied to 

DLPDFTEXT creation calls in an input encoding. The DLPDFTEXT object stores this


text in Unicode UTF-16 format, with Big-endian or Little-endian orientation 

depending on the host platform. 

DLI Initialization now Required 

Initialization of DLI is now required; support for using DLI without initialization has 

been removed. If you intend to use DLI methods in your application, you must 

intialize DLI via dlpdfinit. DLI users should initialize the Adobe PDF Library 

through the DLI initialization call; PDFLInit and PDFLTerm should never be 

directly called from a DLI application. 

All DLI documents require an instance for creation. The 

dlpdfdoccreatewithinstance call has been removed from the API, and the 

dlpdfinit and dlpdfdoccreate call have been modified significantly (see 

“Functions Updated” on page 1.18). DLI should only be initialized once per process. 

Streaming PostScript Removed 

All PostScript output is produced using the Adobe PDF Library. Support for 

streaming PostScript created by DLI has been removed. This facility was previously 

deprecated in the DLI v2.2 series. 

PDF Image Import Improvements 

PDF image import has been enhanced as of DLI v3.0.13. The value of the imported 

PDF file's Rotate key, if present, is now honored. Images are imported by DLI and 

placed in the rotated orientation displayed by Adobe Reader and Acrobat. 

For the dlpdfimagecreatefrompdf call, a value of 0 is now accepted for the 

Width and Depth parameters. If either are 0, then the PDF page's crop box is used to 

form the DLPDFIMAGE's visible region. This will be shifted using the XDisp and 

YDisp values to generate the imported image.


Functions Added 

dlpdfmemfiledeleteonclose 

This method marks a Files In Memory (FIM) file to be removed from the filesystem 

once the last open filehandle for the file has been closed. 

NOTE: No file is automatically removed from memory, unless 

dlpdfmemfiledeleteonclose has been called for a specific MDFile. 

dlpdfmemfilesetbuffer 

This method configures Files In Memory to directly use the buffer passed in as the file 

contents. 

dlpdfmemfilesyssetmemlimit 

This method establishes an upper bound, in bytes, of the memory usage allowed for 

file contents by DLI. 

dlpdfmemfilesysgetmemusage 

This returns an ASSize_t with the current usage, in bytes, of memory for file 

contents. 

dlpdfdoccreatesignature 

dlpdfdocsetsignatureappearance 

dlpdfpageplacesignature 

dlpdfsignaturesetdatacallback 

dlpdfsignaturesetpkcs7cert 

dlpdfsignaturesetx509cert 

These new methods support Digital Signatures in documents. See the new chapter on 

“Digital Signatures” on page 15.1 for more details.


dlpdfdocasciips 

This method was added to support creation of PostScript output suitable for 

transmission through channels and to devices which do not accept binary data. Most 

PostScript printers cannot properly process binary PostScript input; Distiller and most 

print spoolers will accept binary PostScript data. 

dlpdfinstancesetgrcachelimits 

This method was added to support customers who would like to limit the amount of 

filesystem storage used for the DLI graphics cache. This accepts a low-water and a 

high-water mark, in bytes. If the graphics cache reaches the high-water mark, graphics 

will be removed from the cache in least recently used (LRU) order. Graphics will be 

removed until the cache falls to or below the low-water mark. 

dlpdftext 

This creates a DLPDFTEXT area from a string of a given length (in bytes) and an 

encoding. 

dlpdftextshowencodingnames 

This method can be used to obtain a list of valid Encoding names provided via the 

International Components for Unicode (ICU) module, for use when calling 

dlpdftext. 

dlpdftextfromutf8 

dlpdftextfromutf16le 

dlpdftextfromutf16be 

dlpdftextfromutf16he 


dlpdftextfromutf32be 

dlpdftextfromutf32he 

These are convenience functions for common Unicode encodings.


dlpdftextadvance 

This supplies the x and y advance for a string in a DLPDFTEXT area. 

dlpdftextstring 

dlpdftextlength 

dlpdftextstring returns the byte buffer for the stored string. 

dlpdftextlength returns the length, in bytes, of this buffer. 

dlpdftexttocontent 

This pastes the DLPDFTEXT string into a DLPDFCONTENT area. 

dlpdftextdestroy 

This method destroys a DLPDFTEXT area. 

dlpdfttload 

This method loads the font from a TrueType or OpenType font file, or the fonts from 

a TrueType/OpenType Collection font file. These fonts are loaded into the supplied 

DLPDFINSTANCE. Fonts loaded in this manner are used before searching the system 

directories for fonts. 

NOTE: This method does not fully support Adobe CFF-format OpenType font files. 

CMaps as defined in the PDF Reference Manual should be used for these fonts. 

Datalogics recommends creating them as CIDType0 fonts, using 

dlpdfcontentwidetext for setting text.


Functions Updated 

dlpdfinit 

This has been revised significantly, and now requires three parameters: 

• the PDFLData pointer containing Adobe PDF Library initialization data 

• the default file system to use, or NULL for the Adobe PDF Library default filesystem 

• NULL; reserved for future use as an optional argument 

The DLI graphics cache has been enhanced to use the default ASFileSys 

implementation provided to dlpdfinit for caching graphics. By default, the 

graphics cache file size is limited to 1.5GB. Customers who wish to use larger graphics 

cache files are advised to supply a filesystem to dlpdfinit which is capable of 

reliably handling files of the larger size. 

dlpdfdoccreate 

This call no longer accepts a PostScript filename. (Use dlpdfdocsetpsname, or 

supply one to dlpdfdocwritePS.) The PDFNeeded flag has been removed; PDF 

processing is always performed. It accepts one parameter, the DLPDFINSTANCE to use 

for the document. 

dlpdfterm 

This call now removes memory files used for the dlpdfttload call if the Files In 

Memory system is used, and if these files are no longer in use. 

Functions Removed 

dlpdfdocsevenbitsafe 

This method was not able to guarantee a PDF output stream safe for a seven-bit 

channel. The PDF specification refers to PDF as a binary format, and expects that 

consumers are able to accept a binary input stream.


dlpdfdocHexGraphics 

was an API for debugging graphic output. In the DLI v2.2.x series, this was disabled. 

dlpdfdocsetformsascontent 

...and... 

dlpdfimageplaceascontent 

...were not able to generate correct PDF output for some imported PDF files. This 

functionality was not widely used, and these methods have been removed. 

dlpdfdocsetembedappwidth 

This method has been removed as fonts will, with the exception of the "standard" 14 

fonts, always have their widths included in the PDF font if the font is present on the 

system on which a job is run, or if these widths are supplied to DLI. 

dlpdfdocseterrorfile 

...and... 

dlpdfdocsetwarningfile 

...are no longer supported. Functions which need to communicate errors will raise an 

ASException as required. 

dlpdfdoccreatewithinstance 

This has been replaced by a revised dlpdfdoccreate call. Since DLI initialization 

is required for v3.x releases, the dlpdfdoccreate call accepts a DLPDFINSTANCE. 

See “Functions Updated” on page 1.18 for details.


dlpdffontverifytext 

Given a font and a string of text, this method would ensure that every Unicode 

character had a valid glyph ID associated with it. Because Unicode is now handled in 

the DLPDFTEXT structure and not the font, this method was no longer needed. 

dlpdfsetlevel 

This method is now reserved for internal use. Although its function has not changed 

from prior releases, it is no longer supported for applications built with DLI. 

Enhancements in Prior Releases 

A summary of enhancements in prior releases follows below. See the relevant chapters 

or the Reference Guide appendix for full details on methods listed below. 

DLI v2.2.13 

Default Search Path Suppression Expanded to All Platforms 

The enhancement first provided with the Adobe PDF Library v5.0.2Plus and DLI 

v2.2.12 release for a method of suppressing the default search path for 

AdobeFnt.lst on Unix platforms (see “Default Search Path Suppression” on page 

1.21 below) is now expanded to all platforms. 

Image Search using Files In Memory 

DLI now searches the default ASFileSys (whichever filesystem was selected by the 

application) for graphic files, instead of automatically searching only the disk. 

(Graphic conversions are still cached to a temporary file on a physical file system.) 

1 Set the default file system to dlpdfmemfilesys. 

2 Create a file in the Files In Memory filesystem, and use dlpdfmemfilesetdata


to make a region of memory into the file-in-memory. 

3 Call dlpdfimagecreatefromfile with the name of the file-in-memory. 

4 Set the default file system back to the original default, if files-in-memory is not 

being used for anything else. 

NOTE: Users currently using Files-In-Memory in their application but assuming 

that images are always retrieved from disk may need to modify their applications. 

They should either 

• bring the images from disk into memory, or 

• deliberately switch the default filesystem to disk temporarily 

in order to pull in the graphic(s) before continuing with further processing. 

DLI v2.2.12 

Default Search Path Suppression 

An enhancement has been added to enable the Adobe PDF Library to ignore its 

default search path (which varies somewhat from one platform to another) when 

compiling its list of resources at initialization time on Unix platforms. This is done by 

adding a PDFLDataRec.flags member to PDFLInit/dlpdfinit, which can be 

filled with a kPDFLInitIgnoreDefaultDirectories value. This will stop the 

Library from searching the current working directory on startup, or writing 

AdobeFnt.lst entries on shutdown.

1.22 DLI Implementation and Reference Guide

2 

Initializing 

and Terminating the 

Library 

The procedure for initializing DLI and the Adobe PDF 

Library defines font locations, memory management 

routines and resource allocation in preparation for 

document processing. 

2.1


Overview 


The DLI initialization process has been simplified such that when DLI is initialized, it 

automatically initializes the Adobe PDF Library as well. Initialization via DLI also 

provides the option of enabling the Datalogics Files In Memory (FIM) system, by 

specifying a file system to be used for temporary files and for file input/output 

operations. 

DLI must be initialized before creating any documents with DLI or making any calls 

to the Adobe PDF Library, should be initialized only once per composition program 

run, and should be terminated prior to the application shutdown. 

Adobe PDF Library Data Structure 

Initialization of DLI and the Adobe PDF Library requires a specific collection of 

information, maintained in the data structure PDFLDataRec. One such structure 

should be created and cleared to zeros before starting the Adobe PDF Library. The 

next few sections deal with settings of parts of this structure to prepare for initializing 

DLI and the Adobe PDF Library.

Initializing and Terminating the Library 2.3 

Setting Resource Directories 

The PDFLDataRec record contains two fields (dirList and listLen) which are 

used to establish a list of paths to be searched for font resources, its AdobeFnt.lst 

file. (See “The AdobeFnt.lst File” below.) 

NOTE: DLI does not search directory paths or environmental variable entries for 

fonts loaded via dlpdfttload. 

The resource directory listing (the PDFLDataRec record ) should not be used in OS/ 

390, but may be used in all other platforms. This list is constructed by allocating an 

array of pointers to strings, and filling each pointer with a pointer to a path. 

The field dirList should be set to point to this array. The field listLen should be 

set to the number of entries in the above array. Examples of this usage can be found in 

the accompanying DLI sample applications. 

The AdobeFnt.lst File 

The process (your Adobe PDF Library application, and also Adobe Acrobat or Adobe 

Reader) compiles an AdobeFnt.lst file for its own use when either constructing a 

PDF document or rendering/displaying it later, for Adobe PDF Library and Adobe 

Acrobat applications respectively. It consists primarily of font information within files 

found on your machine. (Its actual name varies by product, platform or release level 

as AdobeFnt.lst, AdobeFnt06.lst or AdobeFnt07.lst, and possibly others.) 

You should find that the AdobeFnt.lst file is only compiled if one is not already 

present, or if any file in the directory is timestamped more recently than the 

AdobeFnt.lst file itself. The creation time does of course go up if many files are 

present. The file is not recompiled every time the application is run, only when certain 

conditions are met as described above. 

For efficiency, try to minimize the number of files that must be searched. You can do 

this by running the application from another location, so that the current working 

directory is one with very few files in it, or alternatively make use of the 

kPDFLInitIgnoreDefaultDirectories flag (see “Default Search Path 

Suppression Expanded to All Platforms” on page 1.20 for further details). You must


still ensure that the application gets a list of directories where its resources will be 

found. 


Since the AdobeFnt.lst file is a plaintext file, compiled on an as-needed basis by 

the application, you can review its contents in a text editor at any time to verify that it 

is finding the resources needed. Since it is possible to have many copies of 

AdobeFnt.lst scattered about (one may be created whenever an application is run 

in a new working directory for the first time), if there is any doubt as to which 

AdobeFnt.lst is in use by the application, you are free to delete the existing copies 

(or temporarily rename them in order to hide them), run the application again, and 

then look to see where a new copy has appeared. Reviewing that file will show you 

the resources found by that instance of the application. 

More information on this can be found in the Adobe PDF Library Overview, pp. 23- 

24 (April, 2004 edition), under the subheadings "Initialization Details" for each 

platform.


Setting Memory Allocation Routines 

You may wish to use this portion of the PDFLDataRec record when your application 

contains a memory allocation/deallocation schema that you want the Adobe PDF 

Library to share. In particular, if your application does not use the system malloc/ 

calloc/free routines, which the Adobe PDF Library will use by default, you may 

want to use this section. 

Control of memory allocation is accomplished by the creation of a new record 

(TKAllocatorProcs). You must allocate space for this record and fill in all of the 

fields in this record if you wish to establish your own memory manager. 

There are several procedures pointed to by this record: 

• allocProc — a routine to allocate memory 

• reallocProc — a routine to increase the size of an allocated block of memory 

• freeProc — a routine to free memory 

• memAvailProc — a routine that returns the amount of memory which may be 

requested without an error occurring 

The definitions of the interfaces for these procedures are contained in PDFInit.h. 

Basically, they are the interfaces for malloc (or calloc), realloc and free for 

standard UNIX. However, each contains as its first parameter a pointer to user data. 

This pointer is the fifth field of the TKAllocatorProcs record. See "Displaying a 

Square" in the Programs Links chapter for an example of setting these values. 

Setting Resource Allocation Routines 

The Adobe PDF Library contains a robust set of routines for locating resources. 

However, if your application wishes to control access to resources, this section is 

where such control is established. 

The TKResourceProcs record is similar to the TKAllocatorProcs record. It 

contains a pair of pointers to procedures for allocating and deallocating resources. 

The procedure interfaces are defined in PDFInit.h.


Adobe PDF Library Version Control 


There are two version issues that you may need to consider when building and 

running your application: the version of Adobe PDF Library and DLI in use, and the 

declared PDF version (or Compliance Level) being declared within the PDF output 

being generated. 

Obtaining Adobe PDF Library Version Number 

The version number of the Adobe PDF Library which was initialized may be obtained 

at any time after initialization as the return value of the method PDFLGetVersion: 

• The high-order 16 bits of the value are the Major Version Number 

• bits 8 through 15 are the Minor Version Number 

• bits 0 through 7 are the Sub-minor Version Number 

You may wish to have your application obtain and compare the returned Version 

Number to the constant kPDFLVersion to see if the version of the Adobe PDF 

Library being used at runtime is the same, greater, or less than the Version Number of 

with which it was compiled. 

PDF Level Declarations in Output 

PDF output files declare their compliance level with a particular version of the PDF 

Standard; e.g. documents created with Adobe PDF Library v6.x can declare PDF 

v1.5. Applications reading, processing or displaying PDF output may inspect the 

declaration within the file to determine how to process it. In particular, Adobe 

Acrobat and Reader v5.x applications may produce a popup warning of possible 

unsupported PDF features if they detect that the declared PDF level of the document is 

higher than v1.4, even if the document does not in fact contain any functionality 

unique to v1.5 or above. 

The Adobe PDF Library is a set of routines associated with other Adobe products 

such as Adobe Acrobat, Adobe Acrobat Distiller and Adobe Reader. The original 

Adobe PDF Library was labeled as version 1.2 in order to maintain consistency with


the PDF standard of 1.2. The next version of the Library was labeled version 4.0 (and 

subsequently 4.05) due to the tie-in with Acrobat v4.0. Versions 4.0/4.05 of the 

Library complied with the PDF standard of 1.3. Adobe PDF Library v5.0.2Plus 

complied with PDF Standard 1.4, and the latest Adobe PDF Library v6.x complies 

with PDF Standard 1.5. 

By default, the Adobe PDF Library declares the current PDF level compliance in 

output PDF files; e.g. Adobe PDF Library v6.x applications building pages without 

Datalogics Interface methods will generate PDF v1.5. Further description below 

applies only to PDF output generated via DLI methods. 

NOTE: Viewing a latest-generation PDF in a prior-version Adobe Acrobat or Adobe 

Reader (e.g. viewing PDF v1.5 in Acrobat or Reader v5.0 or earlier) can produce a 

popup warning of a PDF level mismatch, to warn the user that certain PDF features 

new to that version may not be supported by the viewing program. While this is 

only a warning, it may concern some users who have not upgraded to the latest 

viewer. You should ensure that your document features are backwards-compatible 

to older viewer versions where possible, or warn your users that a viewer upgrade 

will be required in order to take full advantage of features in your document, as 

appropriate. 

Selecting PDF Level Declarations via DLI 

Applications built with Adobe PDF Library and Datalogics Interface (e.g. Adobe PDF 

Library v6.1.1Plus and DLI v3.0.19) and using DLI methods for output will have 

their output PDF compliance set appropriately by DLI. Unlike output generated solely 

by Adobe PDF Library v6.x methods, DLI-generated files will by default identify 

themselves as PDF v1.3 compliant in their simplest form, or higher values if 

appropriate, based on the functionality embedded in the document. 

Overriding PDF Level Declarations via DLI 

When generating PDF output, the internal PDF Compliance Level declaration to be 

issued is made up of two internal component values, pdfMajorVer and 

pdfMinorVer, which are members of the DLPDFDOC structure. pdfMajorVer 

defaults to 1, and when using DLI methods for PDF output, pdfMinorVer initially


defaults to 3 (PDF v1.3, for Adobe Acrobat v4 compatibility). If higher-level functions 

are used within the output PDF document, the pdfMinorVer will be incremented as 

appropriate to 4 or 5 (PDF v1.4 or PDF v1.5 respectively). You can force the declared 


Compliance Level by assigning the value you desire to pdfMinorVer within your 

application. 

Files In Memory Activation 

To increase the throughput of PDF generation, memory-mapped files may be used for 

temporary storage and for final output of the PDF content. Output of a PDF file to 

both memory and disk is also supported for environments where this feature is 

desired. 

In order to utilize Files In Memory (FIM), DLI must be initialized through the 

dlpdfinit function call, and the Datalogics memory file system must be passed to 

this function call. The memory file system may be obtained by calling the 

dlpdfmemfilesys function, detailed below (see “dlpdfmemfilesys” on page 

2.11). This may be called before DLI (and, hence, the Adobe PDF Library) is 

initialized. Once set, storage of temporary files in memory is automatic. 

The DLI sample applications accompanying this release demonstrate the coding and 

use of Files In Memory. It can be invoked by adding the command-line argument 

MEMORY when calling the sample applications. 

Initializing and Terminating via DLI 

The following commands should be used to initialize and terminate the Adobe PDF 

Library and DLI. In a single-threaded application, the initialization and termination 

processes must be called only once during the life of the application. Attempting to 

initialize the Adobe PDF Library and DLI more than once in the application may 

cause errors or unpredictable behavior, and is not supported. (You are free to create 

multiple documents and/or multiple files within the run, but the initialization and


termination of the Adobe PDF Library and DLI is limited to one iteration of each. In 

a multi-threaded application, each thread must perform its own initialization.) 

dlpdfinit 

This method initializes DLI, and prepares it to use the ASFileSys passed in as the 

second parameter; this may be NULL if the caller does not have an ASFileSys to 

pass to dlpdfinit, or does not have a filesystem preference. 

The first parameter is a PDFLInit structure used to initialize the Adobe PDF 

Library. It is the same structure that would be passed to the PDFLInit function call 

in legacy programs which use that function. 

The second parameter of dlpdfinit is an ASFileSys record specifying what file 

system should be used by DLI and the Adobe PDF Library. If NULL, the default file 

system operations will be used. 

The third parameter is NULL, reserved for future use. 

CAUTION: Versions of Adobe PDF Library prior to v6.1 are not thread-safe, and 

should not be initialized more than once in a single job, either directly or via DLI. 

Doing so can produce undesirable results. Your application is free to create 

multiple output files or perform multiple tasks without exiting using the 

appropriate methods (see the DLI MultiDoc sample application, for example), 

but you must not terminate the Library until you are ready to stop the application, 

and once you have terminated the Library, you cannot initialize it again. You can 

accidentally call dlpdfinit (the DLI command) multiple times without problems, 

as it contains internal code that prevents actual initialization from occurring more 

than once, but you cannot call PDFLInit (the Adobe PDF Library command) more 

than once as a fatal error will occur. See further discussion on thread safety in 

“Thread-Safe Issues” on page 2.14. 

The DLI initialization call dlpdfinit must occur before any other call which makes 

reference to any DLPDFDOC structure (with the exception of dlpdfmemfilesys, 

which may be called for setup purposes). It returns a DLPDFINSTANCE pointer which 

may then be used to create documents. The dlpdfinit function call may also return 

a NULL pointer, indicating that DLI or the Adobe PDF Library could not initialize. If


this occurs, neither DLI nor the Adobe PDF Library should be used, and if possible, 

the calling program should cease execution as soon as is feasible. 


Specifying an Alternate File System 

The ASFileSys passed to dlpdfinit as its second argument will typically be either 

NULL (specifying that the user has no preference for how DLI manages file input and 

output) or the dlpdfmemfilesys call. Calling dlpdfmemfilesys will return the 

ASFileSys record to the Datalogics memory file system for the Adobe PDF Library. 

This file system keeps temporary files in memory, instead of on disk, resulting in 

significantly improved processing speeds on some systems. You can create your own 

ASFileSys and pass it in, if you wish more control over how files are manipulated. 

NOTE: The included fonts must still be read from disk, and the PDF document 

which is created will be written to a disk file, unless the steps described in 

"Writing PDF Output to Memory" are taken. If the user has the means to specify 

an alternative file system, that too may be passed into dlpdfinit. 

Using a Graphics Cache 

As of DLI v3.0.11, the DLI graphics cache has been enhanced to use the default 

ASFileSys implementation provided to dlpdfinit for caching graphics. By 

default, the graphics cache file size is limited to 1.5GB. Customers who wish to use 

larger graphics cache files are advised to supply a filesystem to dlpdfinit which is 

capable of reliably handling files of the larger size. 

NOTE: The cache size limit is checked every time a document is destroyed; the 

cache may therefore temporarily exceed the cache size limit. When setting the 

cache size limit, please note that to resize the graphics cache, free space equal to 

the sum of the cache limit and the "low water" mark is required. Files In Memory 

users with large graphics workloads are advised to lower the cache size limit to a 

number appropriate for their target environment.


dlpdfmemfilesys 

This procedure returns the ASFileSys structure which represents Datalogics’ Files In 

Memory file system. This file system will only be used if PDF output is requested. 

This structure is suitable as the second parameter to the dlpdfinit function. 

Image Search using Files In Memory 

With the release of DLI v2.2.13, an enhancement was added for a method of holding 

graphics in memory and searching for them there, as opposed to storing and searching 

for graphics on disk only. This was not in the form of a separate API; instead, DLI 

was altered to search the default ASFileSys (whichever filesystem was selected by 

the application) for graphic files, instead of automatically searching only the disk. 

(Graphic conversions are still cached to a temporary file on a physical file system.) 

To take advantage of this, you would 

1 Set the default file system to dlpdfmemfilesys. 

2 Create a file in the Files In Memory filesystem, and use dlpdfmemfilesetdata 

to make a region of memory into the file-in-memory. 

3 Call dlpdfimagecreatefromfile with the name of the file-in-memory. 

4 Set the default file system back to the original default, if files-in-memory is not 

being used for anything else. 

NOTE: Users currently using Files-In-Memory in their application but assuming 

that images are always retrieved from disk may need to modify their applications. 

They should either 

• bring the images from disk into memory, or 

• deliberately switch the default filesystem to disk temporarily 

in order to pull in the graphic(s) before continuing with further processing. 

Terminating DLI and the Adobe PDF Library 

Termination of DLI is accomplished by calling dlpdfterm with the 

DLPDFINSTANCE pointer returned from the dlpdfinit function call. This call


should not be made until all DLI structures, with the exception of the 

DLPDFINSTANCE pointer, and all PDE and PD library structures are freed. The 

dlpdfterm call will free the DLPDFINSTANCE pointer and the pointers set in the 


PDFLDataRec structure. Terminating DLI will also terminate the Adobe PDF 

Library. 

dlpdfterm 

This method will terminate DLI and the Adobe PDF Library. Call this function after 

all DLPDFDOC structures have been disposed of. In the case of multi-thread 

applications, each thread that initialized the Library must also terminate it when 

finished. 

This will typically be one of the last calls of a program using DLI. The call takes a 

DLPDFINSTANCE pointer, which is the DLPDFINSTANCE pointer returned by the 

dlpdfinit function call. Any composition program using DLI and the Adobe PDF 

Library should call dlpdfterm to terminate DLI and the Adobe PDF Library before 

terminating itself. The dlpdfterm function takes the DLPDFINSTANCE returned 

from dlpdfinit as its sole parameter.


Typical Order of Calls 

In summary, the overall calling sequence would be similar to the following example: 

. 

PDFLDataRec InitStruct; 

DLPDFINSTANCE *pdfInstance = NULL; 

. 

. 

. 

/* to use Files In Memory */ 

pdfInstance = dlpdfinit(&InitStruct, dlpdfmemfilesys(), NULL); 

/* to use standard files */ 

pdfInstance = dlpdfinit(&InitStruct, NULL, NULL); 

. 

. 

. 

if (!pdfInstance) /* if not 0 then error */ 

{ 

printf("Error initializing DLI -- aborting\n"); 

exit(1); 

} 

. 

. 

. 

/* to close library */ 

dlpdfterm(pdfInstance); 

Multi-Thread Initializations 

Adobe PDF Library v6.1.0Plus and DLI v3.0.11 (or higher) are re-entrant, and 

therefore safe for multithreaded applications. However, the Adobe PDF Library will 

perform cleanup work during termination if no other instances are active, which will 

cause the Library to not initialize correctly for any follow-on processes afterwards. 

Therefore, though each thread must call PDFLInit/PDFLTerm or dlpdfinit/ 

dlpdfterm (for DLI applications), take care that Adobe PDF Library and DLI are 

not re-initialized after the last outstanding initialization has been terminated. For


example, the following sequence will cause errors when attempting to initialize 

Thread 2: 

Concepts and dlpdfinit() Facilities: Guide to the DL Pager Composition System 

[Thread 1 processing] 

dlpdfterm() 

dlpdfinit() 

[Thread 2 processing] 

dlpdfterm() 

The problem above is that when Thread 1 terminates, no other processes are seen, and 

so shutdown cleanup work begins, leading to errors when the initialization of Thread 

2 comes along. 

This sequence is recommended instead: 

dlpdfinit() 

dlpdfinit() 

[thread 1 processing] 

[thread 2 processing] 

dlpdfterm() 

dlpdfterm() 

Thread-Safe Issues 

Releases of the Adobe PDF Library prior to v6.1 are not thread-safe, and so by 

extension neither is DLI. Adobe PDF Library v6.1 and its accompanying DLI is the 

first thread-safe release in distribution. Notes on use of prior versions within multithreaded 

applications are given below. It is possible to use pre-v6.1, non-thread-safe 

Library applications in a threaded environment under the proper configuration in 

certain circumstances (although you should plan to upgrade your application to a 

thread-safe Adobe PDF Library v6.1.x version at your next opportunity). 

The general idea is that your application will queue the threads' interaction with the 

Library functions so that they are executed one at a time. This is not too difficult to do 

if your pre-v6.1.x application uses a mutex (Mutual Exclusion) algorithm to ensure 

that only one thread has access to the Library at any given point in time. Testing has 

shown that execution time does not appear negatively impacted if the Library 

segments are efficiently grouped, so that any given thread's Library activity is over 

and done with before the next process calls. When properly implemented, there


should be no noticeable deterioration in performance due to the mutex gatekeeper 

logic, and a multi-threaded application can thus use an older, pre-v6.1.x version of the 

Adobe PDF Library. 

NOTE: While these instructions should enable you to implement a multi-threaded 

application with an older, non-threadsafe version of the Library, you should 

upgrade your application to make use of the latest thread-safe release as soon as 

possible. Newer releases contain numerous other improvements in addition to 

multithread capability. 

The problem revolves around the event handler stack. Since the Adobe PDF Library 

prior to v6.1.x has only one handler stack, multiple, concurrent processes have no 

means of determining whose Library activity is occurring at any given point in time, 

so it is possible for the Library to return a bad event for one process that could be 

caught by another process by mistake. With mutex coding, you can ensure that only 

one process has access to the Library at any given time, and the next process is 

granted access only after the first one is concluded. 

As stated, this works reasonably well as long as the Library access is efficiently 

arranged within the application code. That is, you should not simply put one big 

DURING/HANDLER/END_HANDLER around the entire algorithm, as the process will 

then commandeer the Library for its entire job, to the exclusion of all others. Instead, 

divide the application algorithm into logical blocks of Library activity, so that Library 

access is more likely to be evenly divided among concurrent processes. Also try to 

ensure that, if possible, a given process waiting for an external event to finish will not 

be tying up Library access in the meantime. 

Writing PDF Output to Memory 

Output of PDF files to memory ("transient files") requires slight changes to your 

application, summarized below. 

When calling dlpdfdocsetpdfname or dlpdfdocwritepdf functions, these 

functions must be given a filename which marks the file as a transient file. This is done 

by prefacing the document's filename with the transient prefix, obtained by calling the


dlpdfmemfiletransientprefix function. This returns a character string with 

the necessary prefix, which marks the file such that it is not written to disk. 


Call dlpdfdocwritepdf when the document is complete, and obtain the 

ASPathName for the string passed to dlpdfdocwritepdf. Obtain the MDFile 

representing the Files In Memory entry for the document via the 

dlpdfmemfileacquire (ASPathName) function. This returns the MDFile for 

the document. Then, the size of the memory buffer needed to contain the file can be 

obtained with the dlpdfmemfilesize(MDFile) call, and the information itself is 

returned (as a const unsigned char buffer of the size returned by the call above) 

by the dlpdfmemfiledata (MDFile) function. 

Copy the contents of the returned pointer as soon as possible. This pointer should not 

be changed or modified, and should not be freed. Call dlpdfmemfilerelease 

MDFile) to release the file, its memory and other resources once this file is finished 

being used. The function will return the remaining number of acquisitions for the Files 

In Memory file. 

The functions to support this are: 

dlpdfmemfileacquire 

This function acquires the file given by the pathname passed in, and returns it as an 

MDFile. A memory file is eligible to be removed when no acquisitions are 

outstanding upon it. 

dlpdfmemfilesize 

This function returns an ASSize_t value containing the smallest size of a block of 

memory (in bytes) which could contain the data of the given MDFile. 

dlpdfmemfiledata 

This function returns a pointer to a memory representation of this file. The contents 

should be copied as soon as possible, and must be neither altered nor freed.


dlpdfmemfilesetdata 

This function sets the file passed in to contain the data passed to the function. This 

completely overwrites the file’s previous contents. Returns TRUE if successful, or 

FALSE if the file's contents could not be set. 

dlpdfmemfilerelease 

Decrements the file's acquisition counter and signals to DLI that the application no 

longer requires the use of this file. A file should be released for each acquisition made 

to the file; if it is not released, then release of the file's memory and other resources 

will be delayed until the end of program execution. 

dlpdfmemfiletransientprefix 

Returns a string representing the transient prefix. Memory files whose names start 

with the transient prefix will not be written to disk. Otherwise, the files will be written 

to disk upon file closure or program termination. 

API Comparison 

The Hellodli program sample was created to provide a clear comparison between a 

sample program using the DLI API in conjunction with the Adobe PDF Library API, 

and one using the Adobe PDF Library API exclusively. The similarities and differences 

between the two types of applications can be seen by comparing the hellodli.c file 

to the helowrld.c file provided by Adobe. 

The two programs perform largely the same task: Produce a simple, one-page 

document with a line of text on it. You can compare the source code for each file to 

see which Adobe PDF Library methods are replaced by DLI methods. In most cases, 

you should find that the DLI methods are simpler and easier to implement. On a 

larger scale, DLI methods also enable Files In Memory processing, which in turn 

allows faster processing times and reduced I/O activity for intermediate work file 

actions.


Concepts and Facilities: Guide to the DL Pager Composition System

3 

Beginning and 

Ending a Document 

This chapter describes the methods provided in DLI to 

create and write a document. 

3.1


Overview 


DLI provides a simple interface to create and write documents. It uses a document 

structure (DLPDFDOC) to differentiate between documents, allowing for the 

simultaneous creation of a number of documents. DLPDFDOC reflects the current 

status of the document at all times and is required input to most other DLI calls. As 

the document is created with Adobe PDF Library support, a CosDoc and a PDDoc 

are created within the Library, and these may be obtained from this structure for use 

in calls outside of DLI. 

The Adobe PDF Library establishes the name and many of the attributes of a 

document when it is completed, rather than when it is begun. Many existing 

composition engines do not do this. For this reason, the document structure has a 

convenient set of handles to permit the specification of such attributes at document 

creation time, rather than at document write time. 

There are a number of calls available at the Document Interface. Multiple documents 

may be created and maintained at one time. 

Required Use of Exception Handlers 

Except for dlpdfinit and dlpdfterm, all calls to the Document Interface must be 

within an exception handler (i.e. DURING/HANDLER/END_HANDLER statements) and 

all DLI documents should be destroyed prior to closing the Adobe PDF Library. This 

can be done all at once or one step at a time. Both DLI and the Adobe PDF Library 

may raise exceptions in the form of escapes. 

dlpdfinit and dlpdfterm must not be enclosed in these handlers because they 

are not set up before initialization, and are freed during termination. 

dlpdfdoccreate 

This method will create and return a pointer to a new document, as a DLPDFDOC 

pointer. There are two parameters to this method, an ASBool and a pointer to a 

string, which are generally TRUE and NULL respectively. The first parameter, if

Beginning and Ending a Document 3.3 

FALSE, will bypass creation of the Adobe PDF Library data structures. If PDF is the 

desired output, this must be TRUE. The second parameter, if not NULL, should be the 

name for a PostScript output file to be created via a later call to dlpdfdocwritePS. 

dlpdfdoccompress 

This method should be called before any content is placed onto a page. Content 

placed prior to this call will not be compressed. The compression algorithm used is 

Flate. 

dlpdfdocembedfonts 

When this method is called, all fonts seen will be embedded in the document if 

possible, including Base 14 fonts. The flag set by this method is in 

DLPDFDOC->EmbedFonts, and may be safely manipulated by the client program. It 

is also possible to specify embedding and subsetting on the font create call. 

NOTE: If a font is available but not licensed for embedding, it will be created as a 

referenced font rather than an embedded font. An exception is not returned for 

this condition, but the NotEmbedded flag of the DLPDFFONT structure can be 

inspected after the dlpdfdocembedfonts call, if desired. 

dlpdfdocsetencoding 

The encoding of created fonts will default to WinAnsiEncoding on Windows 

machines and Standard encoding on all other platforms. You may set it to any valid 

encoding through this method. 

This encoding is used when the font create call does not include an encoding. 

dlpdfdocsetpdfname 

When the desired name of the PDF file resulting from this document is known at 

document creation time, it may be stored using this method and will be retrieved 

when the document is written.


dlpdfdoclinearize 

When it is known at document creation time that this file should be written in a 


linearized form, this knowledge may be stored via this method and will be retrieved 

when the document is written. 

dlpdfdocsetdocinfo 

This method accepts couplets of information, each a string, and saves them in the 

document information structure of the document. This may be done at any time. 

dlpdfdocmakethumbnails 

For Adobe PDF Library v4.x and higher, this method will create a thumbnail image 

for each page in the document. This call may be made at any time prior to writing the 

document. Thumbnails will be created automatically at document write time. 

dlpdfdocwritepdf 

This call causes the document to be written to a PDF file. It accepts as parameters a 

document handle, an optional string giving the name of the file to be written, and a 

flag indicating whether linearization is desired. 

If a name has been saved via dlpdfdocpdfname, that name will be used in the write, 

regardless of the specification of a name in the name parameter. If neither a name 

parameter nor a saved name is present, an exception (genErrBadParm) will be 

raised. 

If the linearize parameter is TRUE, or the method dlpdfdoclinearize has 

been used, the document will be linearized; otherwise, it will be nonlinearized. 

dlpdfdocencrypt 

This call causes the document contents to be encrypted using the Adobe PDF Library 

standard encryption mechanism. It accepts a DLPDFDOC pointer, a character pointer

Beginning and Ending a Document 3.5 

to the user password, a character pointer to the owner password, and a PDPerms 

data type. The latter must contain the security permissions as outlined in the Acrobat 

Core API Reference Manual in the PDPerms definition. This call may be made at any 

time prior to dlpdfdocwritepdf. 

dlpdfdocsetencryptkeylen 

This enables variable length encryption keys as supported by the Adobe PDF Library. 

It accepts a DLPDFDOC pointer, a parameter specifying the number of bytes between 5 

and 16 inclusive used to determine key length used during encryption. 

This function can be called to set the length of the encryption key before a call to 

dlpdfdocencrypt if the application is to use an encryption key length other than 

the original 40-bit length provided in previous versions. 

The use of this function is optional if the original 40-bit key length is to be used. 

Subsequent calls to dlpdfdocencrypt will use the number of bytes specified in the 

call to dlpdfdocsetencryptkeylen. If the key length has not been set previously, 

the standard 5-byte value is used as the default. 

For more information on Encryption, refer to the beginning of section 3.5, 

"Encryption," in the Adobe PDF Reference (Fourth edition). For information on 

PDDocSetNewSecurityData and StdSecurityDataRec, see the Adobe Core 

API Reference Guide (March, 2004 edition), pages 1352 and 2988 respectively. 

NOTE: For applications generating multiple documents, 

dlpdfdocsetencryptkeylen must be called for each document for which 

an encryption key length other than the standard 5-byte value is desired.



4 

Fonts 

For most users of DLI, font creation is both one of the 

most important and one of the most difficult aspects of 

an application. Though DLI has been designed to hide 

most of the complexity of font creation, there is still a lot 

to understand regarding font creation and usage. With 

the ability to use most Windows and Macintosh native 

code pages, as well as Unicode (using Adobe PDF 

Library v5.0.2Plus or higher), the DLI font mechanism is 

flexible enough to handle nearly any user request. 

4.1


PDF Font Overview 


It is important to start by understanding the difference between the terms character 

and glyph. A character is an abstract, named entity, such as "hyphen." A glyph is the 

representation of a character contained within a font: the mark in the PDF file which 

visually represents the character, what you see on-screen or on paper. This is an 

important distinction, since some font types use character identifiers to typeset text; 

others use glyph identifiers to typeset text. For this chapter, the terms character and 

glyph will be used interchangeably unless the technical distinction is important, in 

which case this will be noted. 

Characters and glyphs in a PDF font can be addressed using either one-byte encodings 

(such as WinAnsiEncoding), multibyte encodings (such as Shift-JIS), or 2-byte 

glyph identifier (GID) encodings for some TrueType fonts. Some fonts support more 

than one method of accessing characters. 

There are two categories of fonts in the PDF file format: 

• Simple fonts 

• Composite fonts 

Simple Fonts 

Simple fonts are those fonts which are addressed using one byte per glyph or 

character. PostScript Type1 fonts and most TrueType fonts fall into this category. With 

these fonts, no more than 255 characters are addressable. DLI offers the flexibility to 

easily encode which characters are accessible by accepting an encoding array. The 

widths of these characters can also be controlled by providing an array of character 

widths. 

PDF TrueType fonts which have a post table can use encoding vectors to access fonts 

outside the Adobe standard one-byte encodings.

Fonts 4.3 

Composite Fonts 

Composite fonts are fonts which use multibyte encodings or GID values. These are 

known as CID fonts (for "Character ID") or Type0 fonts, even though many are not 

accessed using a CID value. 

There are two varieties of Type0 fonts: 

• CIDType0 

• CIDType2 

CIDType0 Fonts 

CIDType0 fonts use the CMap file format as specified by Adobe, and will accept a 

number of different encodings, though these CMap files are typically somewhat 

narrow in their range of addressable characters. A CIDType0 font is usable with a set 

of CMap files; this is the only way to access characters. 

CIDType2 Fonts 

CIDType2 fonts are also TrueType font streams, but are addressed using 2-byte glyph 

identifiers (glyph IDs). These should not be created using CMaps, since the fonts are 

not keyed by character but by glyph. Instead, a CIDToGID map is used to convert the 

2-byte character in the PDF text strings to glyph IDs for the font. 

For font files loaded into a DLPDFINSTANCE, DLI uses the International 

Components for Unicode (ICU) to translate Unicode inputs and a large array of 

vendor-defined multibyte encodings to output text. The DLPDFTEXT structure is used 

to properly combine characters and support right-to-left reading order. For CIDType2 

fonts, a mapping from the DLPDFTEXT input to glyph IDs for output is generated. 

Whenever possible, the output text in the PDF file is in UTF16 big-endian format. 

The Adobe PDF Library and DLI also allow CIDType2 fonts to be used for a number 

of single-byte vendor encodings. Output is in two-byte glyph IDs which correspond to


glyph identifiers in the embedded font stream. Text is input using the DLPDFCONTENT 

text calls as if using a single-byte font. 


Most TrueType and OpenType font files can be used to create either TrueType (singlebyte) 

or CIDType2 PDF fonts. In all cases, TrueType and CIDType2 fonts should be 

both embedded and subset to ensure reliable results when viewing and printing. In this 

chapter, the term "TrueType font" means a PDF TrueType font using a one-byte 

encoding, and the term "CIDType2 font" means a TrueType or OpenType font using 

GID values to access characters in the PDF file. 

Structure of a DLI Font 

A font is reflected in the structure DLPDFFONT. These structures are created by the 

font creation calls on a per-document basis. They may be used only within the 

document they were created with. Fonts are tracked within the document, and 

destroyed when the document is destroyed. Pointers to fonts are invalid after the 

destruction of their document. All DLPDFFONT structures for a given document will 

be released when that document is destroyed. Therefore, methods that use 

DLPDFFONT as a parameter (i.e. dlpdfcontenttext, dlpdfcontentwidetext, 

dlpdfcontenttextwidth, dlpdfcontentwidetextwidth) must be called 

before the document is destroyed 

Font Embedding Status 

The field DLPDFFONT->NotEmbedded will be TRUE only if a request was made to 

subset the font but the request procedure failed. If the font could not embed due to 

license restrictions (i.e. the request procedure functioned correctly, but the font itself is 

not licensed for embedding), an exception will be raised instead. 

Font Subsetting Status 

The field DLPDFFONT->SubSetMap will be NULL if a font is not subset. The field 

will be not NULL if a font is (or will be) subset.

Fonts 4.5 

Font Attributes 

The field DLPDFFONT->RequestedFontAttr is a PDEFontAttrs structure. It is 

populated with the font attributes of the system font actually used to create the font, 

with the alterations requested by the calling application. 

Document EmbedFonts Flag 

If the document that contains the font carries the flag EmbedFonts (normally set by 

dlpdfdocembedfonts), then all fonts for that document will be embedded, 

regardless of the call used to create those fonts. 

All fonts will be subset unless either 

• they were created with a call to explicitly not embed the fonts, or 

• license restrictions prevent the font from being embedded. 

NOTE: If a font is available but not licensed for embedding, it will be created as a 



inspected after the dlpdfdocembedfonts call, if desired. 

Entries in the DLPDFFONT structure should not be altered after a font is created. 

Except for certain specific exceptions to be noted here, changes made to this structure 

will not be subsequently reflected in the font that is created and placed in the PDF 

document.


Font Creation Calls 


There are several procedures available for creating a DLPDFFONT structure: 

• dlpdffontcreate 

• dlpdffontcreateembedded 

• dlpdffontcreatewithmetrics 

• dlpdffontcreatewithmetricsembedded 

All of these calls create the DLPDFFONT structure described above. They are listed in 

increasing order of control given over font characteristics, and according to the 

amount of information a user is required to have about a given font. Those near the 

top of the list above require less initial information from the user than those further 

down. 

The dlpdffontcreatewithmetrics and 

dlpdffontcreatewithmetricsembedded calls can be used to modify the 

character width table and the character encoding vector array, as well as all the font 

attributes which are reflected in the PDEFontAttrs structure these calls require. 

Repetitive Font Creation Calls 

A DLPDFDOC maintains a list of defined fonts by the name and font attributes 

requested. Second and subsequent calls to create a font structure of a given name and 

attributes will return the same font structure as the first call. For example, if you ask 

for the Type1 font Baskerville 20 times, with the same attributes every time, only a 

single PDF font structure for Baskerville will be created, and only a single 

DLPDFFONT structure will be created for Baskerville. If these requests supply differing 

font attributes, more than one copy of Baskerville is created. 

NOTE: The dlpdffontcreate family of calls will always allow the creation of 

the Adobe standard type 1 fonts. The names of these 14 fonts (sometimes referred 

to as the Base 14 fonts) can be found in the PDF Reference.

Fonts 4.7 

dlpdffontcreate 

This is the basic font access method. It accepts a font name and optionally a font type, 

both as strings. When the font type is present, the method will attempt to find a font 

which matches both that type and name. If none is found, it will attempt to match the 

specified name in any type of font. 

Font Searching Sequence 

The specific dlpdffontcreate search procedure follows this sequence, in order, 

until a font fitting the search parameters is identified. For each test below, the order of 

preference when searching for a match is for Type 1 fonts first, then TrueType fonts, 

and finally CID fonts. If no match occurs, the next test in the sequence below is 

attempted. 

1 The current DLPDFDOC is searched for fonts with the same name and type as 

requested. If one was already created, it is returned. 

2 If a Base 14 font is requested and is not to be embedded, it is created and returned. 

3 If the name is matched in the DLPDFINSTANCE font cache, the font is copied to 

the current DLPDFDOC and returned. (This is where fonts loaded via 

dlpdfttload are processed.) 

4 The system is searched for a font of explicit name and type requested by the user. If 

found, it is created and returned. 

5 The system is searched for a font of explicit name (without regard to type) 

requested by the user. If found, it is created and returned. 

6 If any font of the same family and typeface style is found, it is created and 

returned. 

If a font using a one-byte encoding is found for this name, its width table in the 

document’s encoding will be loaded into the DLPDFFONT->WidthTable. If the 

document indicates that all fonts are to be embedded, this font will be embedded and 

subset if possible. The font structure created will carry all of the metrics of this font, 

so that if it is not embedded and is not present on the imaging platform, a Multiple 

Master (or "multi-master") font can be used to provide imaging of the document. 

The encoding used in this font will be the encoding specified in 

dlpdfdocsetencoding, if that call has been used; otherwise it will default 

depending on the system in use: WinAnsiEncoding will be used on Windows


systems and Adobe standard encoding will be used on UNIX, OS/390 and AS/400 

systems. 


If dlpdffontcreate is called without a font name, it will raise a genErrBadParm 

exception ("Bad Parameters") and exit. 

dlpdffontcreateembedded 

This method behaves like dlpdffontcreate, except that: 

• The font will be embedded (if possible) regardless of the overall document settings. 

• If the subset flag is TRUE, the embedded font will be subset. 

• If the subset flag is FALSE, the embedded font will not be subset. 

NOTE: Type0 fonts must be subset if they are embedded. 

dlpdffontcreatewithmetrics 

This method allows the user greater control over the font selection process, and 

permits alteration of the width table, encoding vector and font attributes of the font 

returned. This call should be used when the characteristics of a font need to be altered. 

The application using this function should initialize the PDEFontAttrs structure 

with NULL values before calling. It should then fill out the name of the font to be 

located. Supplied parameters, with the exception of the psName and cidFontType

Fonts 4.9 

fields (and the font name given, if the font returned has a different name), will be used 

to change the characteristics of the font if these are set. 

CAUTION: It is not difficult to create an invalid font by setting these values 

incorrectly. Therefore, the application should set only the fields that it is 

concerned with affecting in the returned font, and leave the rest as NULL values. 

The dlpdffontcreatewithmetrics function will match system fonts based on 

the parameters in the PDEFontAttrs structure: 

• If a system font is found, it will be altered to reflect the values in the 

PDEFontAttrs structure (with the exceptions noted above). 

• If no system font is found, a font will be created if a valid width table and set of 

PDEFontAttrs are passed into this function. 

• If no system font is found and an invalid width table or set of font attributes is 

passed to this function, an exception will be raised. 

The encoding field in the PDEFontAttrs font attributes structure is an ASAtom 

containing one of the significant strings listed in "Predefined Font Encodings," or the 

name of a predefined encoding or CMap file (as given in the PDF Reference manual). 

This should correspond to the encoding format in which the font’s text is to be 

typeset. 

NOTE: Not all the predefined encodings may be used with all fonts. Details on 

which types will accept which values are given in the section on predefined font 

encodings later in this chapter. 

The type field in the PDEFontAttrs font attributes structure should be filled in by 

the user. If it is not (i.e. currently ASAtomNull), then any type of font (Type1, 

TrueType, etc.) may be used. Otherwise, a font of the matching type will be selected if 

present. If no font of the matching type is found, any suitably-named font will be 

returned. 

The charSet field in the PDEFontAttrs font attributes structure may be set to 

"Roman" or ASAtomNull. With an ASAtom value of "Roman," only a font


containing the Adobe standard character set will be used; with ASAtomNull, any 

character set will be acceptable. 


The wMode field in the PDEFontAttrs font attributes structure may be set to 0 

(horizontal) or 1 (vertical) to select a font of the appropriate writing mode. 

The other fields in the font attributes structure are explained in Adobe PDF Library 

documentation. 

Width Table 

A width table may be included with this method for use with TrueType or Type1 

fonts. Generally, you should include such a table specifically in cases where you expect 

that the font is not known either to the Adobe PDF Library or to Adobe Reader, or 

when character widths have to be altered — for example, in the case where an 

encoding vector (described below) is used. This table is arranged from the first 

character to the 256th character for the encoding or encoding vector used to create 

the font. 

A font not present on the system must be represented by a width table. 

Encoding Vector 

You may wish to modify the encoding vector for a Type1 or TrueType font. There are 

many reasons for doing this. It is required if you must access characters within the 

font not normally encoded. It may be done as a convenience when your data is 

encoded differently from the default encoding of the font. Encodings which are not 

based on any of the predefined font encodings may also be created and used in this 

manner. 

The encoding vector is an array of 256 pointers to strings. The values of the strings 

are the glyph names of the encoded characters, as these are defined in the font. 

Positions which are not encoded should contain the string .notdef. 

Type0 fonts may not be encoded. Further, some TrueType fonts may behave 

unpredictably if an encoding vector is supplied. The PDF Reference Manual

Fonts 4.11 

recommends that encoding vectors not be supplied for TrueType fonts. Please see the 

PDF Reference Manual for further details. 

dlpdffontcreatewithmetricsembedded 

This method behaves the same as dlpdffontcreatewithmetrics, but with the 

following exception: all fonts created with this method will be embedded (if possible), 

regardless of the setting of the document's embed fonts flag; if subset is TRUE the 

embedded font will be subset, if it is FALSE, the font will be fully embedded, 

regardless of the document's font embedding settings. If the requested font is not 

found by DLI, or the font is not embeddable due to license restrictions, an exception 

will be raised. 

By manipulating the font calls within the hellodli.c sample program, you can 

compare results of using font references, embedded fonts and multi-master fonts. 

Predefined Font Encodings 

Use of an ASAtomNull for a font encoding will yield a font which uses its "Built-In" 

encoding; this is recommended for symbol (e.g. Pi) fonts where a named encoding is 

not desired. DLI recognizes a number of strings that, when used to create ASAtoms 

and passed into DLI functions requiring a font encoding, serve to denote certain 

predefined encodings for a font. 

Setting the document encoding via dlpdfdocsetencoding does not affect the 

encoding used for symbol fonts, to prevent these from becoming inadvertently 

invalidated. Named encodings passed into the font creation calls above, however, will 

be reflected in symbol fonts. 

The strings, and the font types they are valid for, are enumerated below:


Table 4-1: Encoding Font Types 

Encoding String Value Valid Font Types 


AdobeStandardEncoding Type1,TrueType 

WinAnsiEncoding 

MacRomanEncoding 

Type1,TrueType 

Type1,TrueType 

MacExpertEncoding Type1,TrueType 

Identity-H 

Identity-V 

Other Predefined CMaps 

CIDType0,CIDType2 

CIDType0,CIDType2 

CIDType0 

Adobe PDF Library v5.x and 

higher only: 

WinCP1250 

WinCP1251 

WinCP1253 

WinCP1254 

WinCP1255 

WinCP1256 

WinCP1257 

WinCP1258 

MacCentralEuropean 


MacCroatian 

MacRomanian 

MacCyrillic 

MacUkranian 

MacGreek 


CIDType2 

CIDType2 

CIDType2 

CIDType2 

CIDType2 

CIDType2 

CIDType2 

CIDType2 

CIDType2 

CIDType2 

CIDType2 

CIDType2 

CIDType2 

CIDType2 

CIDType2 

CIDType2

Fonts 4.13 

Encoding String Value 

MacTurkish 

MacArabic 

MacHebrew 

Valid Font Types 

CIDType2 

CIDType2 

CIDType2 

Unicode Text Support 

Unicode text support is available for customers using Adobe PDF Library v5.x or 

higher. It is highly recommended that customers use CIDType2 fonts whenever 

possible when setting Unicode text. CIDType2 fonts may be created from most system 

TrueType and OpenType fonts. 

Code Page Support 

Users of Adobe PDF Library v5.x (or higher) and CIDType2 fonts are also able to 

access automatic translations for many Windows and Macintosh platform encodings. 

Text to be set in these fonts should be in a NULL-terminated string in the one-byte 

platform encoding the font was created with. DLI and the Adobe PDF Library will 

automatically translate this into a string of 2-byte GID values. 

Performance Considerations 

Creation of fonts can be resource-intensive. For users creating multiple documents, 

the DLPDFINSTANCE structure for a document caches most information for fonts


which have been created for other documents. This adds a significant speedup for 

creators of multiple documents over previous versions of DLI. 


However, to obtain the best performance from DLI, users should remember the 

following: 

• Fonts created for a document have most of their characteristics, including their 

system fonts and translation tables, cached in the DLPDFINSTANCE used to create 

the document. 

• TrueType and Type1 fonts allow for faster processing than CIDType0 and 

CIDType2 fonts. They should therefore be used whenever possible.

Fonts 4.15 

Accessing Fonts 

Font access for the Library is dependent on both the Adobe PDF Library version and 

the operating system. It is explained in the Adobe PDF Library Overview manual for 

all systems other than OS/390. 

OS/390 Font Access 

For OS/390, the font access method is based on the UNIX method for v1 of the 

Library. It will attempt to locate resources via several methods, in this sequence: 

1 It will first look for a DD statement named ADOBERES 

2 If that is not found, it will look for the PDS member 

SYS1.PARMLIB(ADOBERES) 

3 If that is not found, it will look for 

ADOBE.PDFLIB.RESOURCE.INDEX(ADOBERES). 

4 CMAPS are found by looking for 

ADOBE.PDFLIB.RESOURCE.INDEX(ADOBECMP). 

The ADOBERES listing found at one of those locations is assumed to be a pointer to a 

listing of 1 entry: ADOBE.PDFLIB.RESOURCE.INDEX(FONTS). The content of 

these files is expected to be encoded using EBCDIC. 

The ADOBECMP listing has 1 entry: ADOBE.PDFLIB.RESOURCE.INDEX(CMAPS) 

This member contains a lookup table for the CMAP files.



5 

Multibyte 

Text Work 

DLI v3.0 has undergone significant enhancements for 

support of Unicode and of multibyte character set 

encodings. This chapter discusses those enhancements, 

and the methods available for multibyte text work. 

5.1


Introduction 


DLI v3.0 has undergone significant enhancements for support of Unicode and of 

multibyte character set encodings. With the inclusion of the International 

Components for Unicode (ICU), DLI is now able to properly set text in hundreds of 

multibyte encodings and all the common Unicode encodings. DLI is now also able to 

set text in scripts which flow from right to left (e.g. Arabic), supports the Unicode 

BiDirectional algorithm, and features character shaping and glyph combining. 

Unicode text composition is also significantly faster and less memory-intensive than 

previous DLI Unicode implementations. 

NOTE: The previous support for Unicode, as introduced in DLI v2.2, has been 

phased out and is no longer available. 

There are two components to this support: 

• Enhancements to the DLPDFFONT functionality 

• A new DLPDFTEXT structure 

To use these enhancements, fonts must be explicitly loaded into the DLPDFINSTANCE 

for a job; once loaded, they are available to all documents created with the 

DLPDFINSTANCE. The fonts are used to set text (in Unicode or multibyte encodings) 

into a DLPDFTEXT area. The text in the DLPDFTEXT area is stored in Unicode UCS-2 

format (in host-order endianness), and may be manipulated or extracted. The 

DLPDFTEXT is placed into a DLPDFCONTENT area, to place the text into the PDF 

content area. Text is written to the PDF file in UCS-2 big-endian format whenever 

possible. All fonts loaded are automatically subset to ensure proper output in 

generated PDF documents. 

Please see information on the DLI sample “WideText” on page 17.21 for a 

demonstration of how to use the new DLI font and text functions to typeset Unicode 

and multibyte text.

Multibyte Text Work 5.3 

Loading and Creating Fonts 

To use the enhanced DLI text functionality, fonts must first be loaded into a 

DLPDFINSTANCE, then created using the dlpdffontcreate calls. 

dlpdfttload 

Loading the font is done using the dlpdfttload function. This call accepts 

TrueType, OpenType and TrueType collection files. 

NOTE: Adobe CFF OpenType font files are not properly subset at this time. The 

sample “WideText” on page 17.21 shows the recommended usage for these fonts, 

using the DLPDFCONTENT multibyte text handling. 

int dlpdfttload (DLPDFINSTANCE, ASFile, ASAtom[], int) 

• The first argument provides a DLPDFINSTANCE into which the font is loaded; once 

that is done, any document using the instance may create the font. 

• The second argument is a font file, supplied as an ASFile for the second 

parameter; please see the sample “WideText” on page 17.21 for an example of 

creating an ASFile from a file on disk. 

• The third argument is an array of ASAtoms. Because a font file may contain more 

than one font, the caller must supply an array of ASAtoms as the third parameter. 

• The fourth argument is the number of array entries. The dlpdfttload function 

will fill the array with ASAtoms of the fonts loaded, up to the size of the ASAtom 

array. If the array is too small to hold all the font names, the additional fonts will 

still be loaded, but the names will not be returned. Datalogics recommends that this


array be allocated to hold a sufficient number of entries to prevent this. In practice, 

a dozen ASAtom entries should be sufficient. 


The dlpdfttload function returns the number of fonts loaded from the font file. 

An exception may be raised for invalid parameters, if the font file could not be 

opened, or if there was a problem invoking the font loader. 

NOTE: If a given font file has already been loaded, dlpdfttload returns a -1, 

and does not re-parse the font file (for performance reasons). 

Once loaded, the font may then be created using the dlpdffontcreate calls (see 

“Font Creation Calls” on page 4.6). The easiest means of creating the DLPDFFONT 

structure is to call dlpdffontcreateembedded, supplying the DLPDFDOC in which 

to use the font, the name of the font loaded (use the ASAtomGetString call to 

obtain a C-string representation of the font name), and a NULL or "Type0" for the 

third parameter. The fourth parameter must be True, since it is illegal to embed 

Type0 fonts without subsetting. 

Because the DLPDFINSTANCE font cache is searched for fonts before the system is 

searched, a font loaded with dlpdfttload will be found before the system is 

examined, unless a more specific font creation call is used. If both single-byte and 

multibyte versions of a font are required for a DLI document, use the 

dlpdffontcreatewithmetrics calls, specifying Type0 as the font type for 

multibyte fonts, and either Type1 or TrueType as appropriate for the single-byte 

font. 

An easier alternative is to create the single-byte versions of the required fonts before 

loading the fonts into the DLPDFINSTANCE. However, it is recommended that you 

use the multibyte font for all text output if possible, to ensure optimal PDF file 

viewing performance and file size.


Creating DLPDFTEXT Areas 

A DLPDFTEXT area is a container for multibyte and Unicode text. Text is placed into 

the container using the dlpdftext function (or one of the shortcut functions) 

described below. This text is converted into Unicode, in UTF-16 format, stored in 

host-endian byte order (little-endian for the Win32 and Intel/Linux platforms, bigendian 

elsewhere), and automatically shaped and processed through the Unicode 

BiDirectional (BiDi) algorithm. This text may then be placed into a DLPDFCONTENT 

area for output. 

dlpdftext 

The dlpdftext method is used to create a DLPDFTEXT area from a buffer of text in a 

given encoding. 

DLPDFTEXT *dlpdftext(void *, ASUns32, ASAtom) 

• The first parameter is passed in as a pointer to a data buffer. 

• The second parameter is the number of bytes in this buffer. 

• The third parameter is the encoding of the supplied text. An exception will be 

raised for invalid parameters, or if the text could not be properly converted from 

the input encoding to the platform-endian Unicode representation. 


There are over 1200 encodings and encoding aliases that may be used as input 

encodings, corresponding to the format of the input text for a DLPDFTEXT area. To


obtain a list of these encodings, use the dlpdftextshowencodingnames function 

call: 

void dlpdftextshowencodingnames(char Concepts and Facilities: Guide to *) the DL Pager Composition System 

This function call will write out a file containing a list of valid encoding names and 

aliases to the pathname supplied as the input parameter. It will raise an exception if 

unable to write this file. 

dlpdftext Shortcut Functions 

For NULL-terminated Unicode text (the NULL terminator will vary from encoding to 

encoding), the following shortcut functions are provided, each using the encoding 

listed in parentheses: 

• DLPDFTEXT *dlpdftextfromutf8(void *) (utf-8) 

• DLPDFTEXT *dlpdftextfromutf16be(void *) (utf-16be) 

• DLPDFTEXT *dlpdftextfromutf16he(void *) (utf-16be or utf-16le, by 

platform) 

• DLPDFTEXT *dlpdftextfromutf16le(void *) (utf-16le) 

• DLPDFTEXT *dlpdftextfromutf32be(void *) (utf-32be) 

• DLPDFTEXT *dlpdftextfromutf32he(void *) (utf-32be or utf-32le, by 

platform) 

• DLPDFTEXT *dlpdftextfromutf32le(void *) (utf-32le) 

These shortcut functions require the input text to be NULL-terminated, but do not 

require a Unicode byte-order marker. An exception will be raised for invalid input, or 

if the input text could not be properly converted to the platform-endian Unicode 

representation.


Working With DLPDFTEXT Areas 

Once created, a DLPDFTEXT area may not be altered. Users may wish to create a new 

DLPDFTEXT area containing a portion of the text in a previously created DLPDFTEXT 

area to fit text lines to document boundaries, or to accomplish other tasks. Users may 

obtain the text from a DLPDFTEXT area and use this as the basis for a new 

DLPDFTEXT area, using the dlpdftextstring and dlpdftextlength calls: 


void *dlpdftextstring(DLPDFTEXT *) 

This call returns the text contained in a DLPDFTEXT area, in UTF-16 format. This 

text is in host-endian format (little-endian for Win32 and Intel/Linux platforms, bigendian 

elsewhere) and does not include a Unicode byte-order marker. An exception 

will be raised if an invalid DLPDFTEXT area is supplied. 


ASUns32 dlpdftextlength(DLPDFTEXT *) 

This call returns the length of the text in a DLPDFTEXT area, in bytes. The buffer 

returned by the dlpdftextstring call will be this length. With the buffer and the 

length returned by these two calls, a user may make a new DLPDFTEXT area with a 

subset of the returned text, using the dlpdftext call and the appropriate Unicode 

encoding ASAtom.


dlpdftextadvance 

The most common use for making new text areas from portions of a DLPDFTEXT area 


is to copyfit text to composed lines. The dlpdftextadvance function call is used to 

supply the width and height change for a string of text, and accounts for character 

shaping and combining, as well as horizontal reading direction. The 

dlpdfcontentwidetextwidth function call may be used to get a rough estimate 

of the width or height change for a string. The dlpdfcontentwidetextwidth call 

does not take character shaping or combining into account, and assumes a left-toright 

line data orientation. The dlpdftextadvance call looks much like the 

dlpdfcontentwidetextwidth calls, but with some enhancements. 

void dlpdftextadvance (DLPDFTEXT *, DLPDFFONT *, 

PDEGraphicState *, 

PDETextState *, 

ASFixed, ASFixed, 

dlpdftext_X, 

ASFixed, ASFixedPoint *) 

• The first argument is a DLPDFTEXT area that contains text to be set... 

• ...in the indicated DLPDFFONT... 

• ...using the supplied graphics of PDEGraphicState... 

• ...and text states of PDETextState. 

• The fifth argument describes the point size of the font; 

• the sixth argument describes the set width of the font; 

• the seventh argument, the dlpdftext_X parameter, is one of 

DLPDFTEXT_X_LEFT or DLPDFTEXT_X_RIGHT, used to indicate whether the 

starting location is the left or right end (respectively) of the text, distinguishing a 

left-to-right line order (e.g. English) from a right-to-left line order (e.g. Arabic); 

• the eighth argument indicates the angle of text (in counterclockwise degrees), 

supplied as an ASFixed value; 

• the ninth argument is a pointer to an ASFixedPoint; the X and Y position change 

resulting from this call is returned in ASFixed units in this ASFixedPoint. 

An exception will be raised for invalid parameters, or if the text advance could not be 

calculated.


dlpdftexttocontent 

Once a line of text to be set is generated, it can be placed into a content area using the 

dlpdftexttocontent function call. It is similar in declaration to the 

dlpdftextadvance call, but note the addition of the DLPDFCONTENT area pointer 

as the second parameter. Also note the additional ASFixed parameters: 

void dlpdftexttocontent (DLPDFTEXT *, DLPDFCONTENT *, 

DLPDFFONT *, 

PDEGraphicState *, 

PDETextState *, 

ASFixed, ASFixed, ASFixed, ASFixed, 

dlpdftext_X, ASFixed) 

• The first argument is a DLPDFTEXT area that contains text to be set... 

• ...to be placed in the indicated DLPDFCONTENT... 

• ...in the indicated DLPDFFONT... 

• ...using the supplied graphics of PDEGraphicState... 

• ...and text states of PDETextState. 

• The sixth parameter, the first of four ASFixed parameters, denotes font point size; 

• the seventh parameter is set width; 

• the eighth parameter is the X-axis value of the starting baseline position; 

• the ninth parameter is the Y-axis value of the baseline position; 

• the tenth parameter, dlpdftext_X, is one of DLPDFTEXT_X_LEFT or 

DLPDFTEXT_X_RIGHT, used to indicate whether the starting location is the left or 

right end (respectively) of the text, distinguishing a left-to-right line order (e.g. 

English) from a right-to-left line order (e.g. Arabic); 

• the eleventh parameter indicates the angle of text (in counterclockwise degrees), 

supplied as an ASFixed value.


dlpdftextdestroy 

After placing the DLPDFTEXT area, or after finishing with any DLPDFTEXT area, 


destroy the text area with the dlpdftextdestroy function call: 

void dlpdftextdestroy (DLPDFTEXT *) 

After destroying a DLPDFTEXT area, the memory for the text and other information is 

released, and the text area may no longer be used by an application. 


The Unicode and multibyte functions in DLI described above represent an order of 

magnitude of performance improvements and run-time memory usage. In addition, 

Datalogics can offer some notes and tips on performance and other considerations: 

• Do not create separate DLPDFCONTENT areas for each DLPDFTEXT string. In 

general, each DLPDFCONTENT area created represents additional overhead during 

both creation and processing of a PDF file, increased file size, and slower rendering 

of a PDF page. Best performance is usually obtained by using one DLPDFCONTENT 

area per page, and pasting all content into this content area. 

• Avoid using both single-byte and multibyte versions of fonts. This results in 

increased creation time to subset two different fonts, as well as slower rendering 

and processing of PDF files. 

• If you are typesetting in Chinese, Japanese or Korean, and are certain that readers 

of a PDF file will have the appropriate Acrobat language pack installed for their 

reader, consider using the Adobe OpenType fonts (subtype 0 CID fonts), and not 

embedding or subsetting. Though you will not be able to use the functionality 

described in this chapter, this could prove to generate faster and smaller PDF files. 

See the WideText sample application included beginning with the DLI v3.0.4 

release for a demonstration of how to set Unicode text using these fonts.

6 

Working with 

Pages 

This chapter explains pages and defines the calls 

available at this level. 

6.1


Introduction to Page Interface 


DLI presumes that pages will be added to the end of the document only. This is 

required for optimal generation of the PDF Page Tree Structures, and matches the 

most common modes for creating documents. If output to PDF is desired and local 

PostScript is not, you may use DLI to create most pages, and then add pages out of 

order to the document via the COS Layer interface. If local PostScript is enabled, these 

added pages will be placed as if they were following the last page. 

Page Structure 

A page is represented in DLI by the data structure DLPDFPAGE. These data 

structures, one per page, are tracked within the package and destroyed when the 

document is destroyed. Pointers to these structures remain valid until the document is 

destroyed. 

Page Interface Calls 

Calls available to the Page Interface in DLI are: 

dlpdfpagefindfromnumber 

This procedure will return the DLPDFPAGE construct for the specified page. This is 

provided to allow pages to be modified after creation without having to keep pointers 

to all of the pages in the application. If the page number specified has not yet been 

created, a NULL pointer will be returned. The first page is considered to be page 

number one. 

dlpdfpagecreate 

This procedure will create a new page in the current document. It will be positioned 

following all other pages in the current document. If the specified document does not

Working with Pages 6.3 

exist, an exception genErrBadParm will be raised. Width and Height must be 

specified as greater than zero, and are assumed to be in points. 

dlpdfpagerotate 

This function will cause the page to be rotated clockwise to the specified angle. 

Permissible rotation angles are increments of 90 degrees only. Angle values greater 

than 360 will be reduced by 360 degrees, then rounded to the nearest 90-degree 

increment. 

This call may be issued at any time after a page is created and will be effective in PDF 

and Adobe PostScript. 

dlpdfpagecosobj 

This function will return a COS object that represents the page in the Adobe PDF 

Library. It may be used to apply COS Layer operations to the page beyond those 

functions defined in the package. 

dlpdfpagenumber 

This function will return the sequence number of the specified page. This number may 

be used in conjunction with the PDDoc returned by dlpdfdocpddoc to acquire a 

PDPage for the specified page. This PDPage will permit Edit Layer functions to be 

applied to the page beyond those defined in this package. 

dlpdfpagesetid 

This function will add an ID Entry to the page dictionary. This is generally a page’s 

FOLIO.



7 

Containers 

within Pages 

This chapter describes containers within pages and 

provides examples of various applications. 

7.1


What are Containers? 


Container may be a misleading name. These structures “contain” text and drawing 

commands in the meaning of structure or hierarchy, but they do not have a limited 

geometry in the sense of edges or boundaries. They “contain” text in data processing 

terms, but are not visual constructs like lines and columns, and hence are not 

containers in the typographic sense. 

The best way to think of these structures is as a boundless plane. This plane may be 

positioned, rotated, or scaled relative to the media on which the text will eventually be 

imaged. There is no restriction on the order or placement of things within a container. 

That is, within the container you are not constrained to move from left to right, or top 

to bottom. Nor are you limited to the quadrant that is the range of positive values. 

Negative positions within the plane may be used as well as positive positions. 

You may use as many containers within a page as you wish, and they may be 

positioned in any way. There is an overhead for the use of a container, however, and 

keeping the number small is desirable. 

The simplest use of containers is to create one for each page, and leave it positioned at 

its default location and rotation. In this case, drawing on the plane and drawing on 

the page are identical operations. The default configuration of a plane is 

• positioned with its origin at the lower left hand corner of the media 

• scaled 1.0 in both horizontal and vertical directions 

• oriented with positive values of X proceeding to the right 

• oriented with positive values of Y proceeding upward 

Often, an existing composition engine will use other positioning. For instance, if your 

engine assumes that (0, 0) is the upper left hand corner of the page and positive values 

of leading proceed down the page, then repositioning the container will allow you to 

use the X/Y values you have already calculated without changing them. 

DLI contains three calls that will permit you to modify the location, scaling or 

rotation of a container (and its content) relative to a page. These may be used at any 

time before a container is committed to a page. Other transformations (mirroring, 

shearing, etc.) may be accomplished by directly modifying the field AreaXform

Containers within Pages 7.3 

within the content structure and calling dlpdfcontentrotate to make that new 

transformation effective. 

CAUTION: The transform applied here will also apply to all contents, and many of 

the possible transformations may not be desirable. 

Simplest Container Case 

In the simplest case, all of the composed data contains X/Y coordinates in (points 

* 100), calculated from the lower left hand corner of the page: 

"C" Example: Simplest Container Case 

void WritePage (DLPDFDOC *Doc, ASFixed Width, ASFixed Depth, 

userdata *UserData) 

{ 

DLPDFPAGE *Page = dlpdfdoccreatepage (Doc, Width, Depth); 

DLPDFCONTENT *Content = dlpdfcontentcreate (Doc); 

USERDATA *UserWork = UserData; 

while (UserWork) 

{ 

WriteLine (UserWork, Content); 

UserWork = UserWork->next; 

} 

} 

dlpdfcontenttopage (Content, Page); 

Scaling 

This case assumes all of the above, but distances are in (points * 10) vertically 

and (points * 1000) horizontally. Note that all of your distances, including point 

sizes and font widths, must conform to this for this single simple solution:


"C" Example: Container with Scale 



{ 




} 

dlpdfcontentscale (Content, 

FloatToFixed (1/ 1000), 

FloatToFixed (1/10)); 

USERDATA *UserWork = UserData; 


{ 



} 


Inversion 

This case assumes that the data in your text is based on the upper right hand corner of 

the page. Scale factors remain as for the previous example. Note that in the data 

writing routine, all vertical positions must be inverted: e.g. something placed at 4 

points below the top of the page would be specified to DLI as -4. 

"C" Example: Container Moved to Top of Page 



{ 



} 

dlpdfcontenttranslate (Content, 0, Depth); 

dlpdfcontentscale (Content, 

FloatToFixed (1/ 1000), 

FloatToFixed (1/10)); 

userdata *UserWork = UserData; 


{ 



} 

dlpdfcontenttopage (Content, Page);


Areas 

If your composition engine describes lines as being members of an area and positions 

within that area, then you may want to create a container for each area, and distort it 

to match your definition of an area: 

"C" Example: Container within an Area 


areadata *AreaData) 

{ 


areadata *CurrentArea = AreaData; 

ASFixedMatrix Matrix; 

while (AreaData) 

{ 


/* Calculate rotated lower left corner */ 

Matrix.a = Matrix.d = fixedOne;/* Unity Matrix */ 

Matrix.b = Matrix.c = 0; 

/* Translate the matrix to the lower left corner of the 

* area to be rotated */ 

Matrix.h = AreaData->X; 

Matrix.v = Depth - AreaData->Y - AreaData->Depth; 

/* Rotate the matrix to the desired angle */ 

dlpdfmatrixrotate (&Matrix, AreaData->Rotation); 

/* Translate the width and depth of the area to the 

* desired angle */ 

Point.h = AreaData->Width; 

Point.v = AreaData->Depth; 

FixedMatrixTransform (&Point, &Matrix, &Point); 

/* Translate to the upper left corner of the rotated area */ 

dlpdcontenttranslate (Content, 

Point.h - AreaData->Width, 

Point.v - AreaData->Depth); 

dlpdfcontentrotate (Content, AreaData->Rotation); 

WriteLines (AreaData->UserData, Content); 


} 

AreaData = AreaData->Next;


Collection of Areas 

In this example, the page content is divided into areas. Each area has a location 


relative to the top left of the page, a width, a depth and a rotation. Each area’s 

contents are specified as an X/Y coordinate relative to the top left of the area. For 

simplicity, assume that all data is in points and is in ASFixed format: 

"C" Example: Multiple Containers per Page with Rotation 


areadata *AreaData) 

{ 


areadata *CurrentArea = AreaData; 

while (AreaData) 

{ 


dlpdcontenttranslate (Content, AreaData->X, 

Depth - AreaData->Y); 

dlpdfcontentrotate (Content, AreaData->Rotation); 

WriteLines (AreaData->UserData, Content); 


AreaData = AreaData->Next; 

}


For the rotation to work correctly in the preceding example, the composition engine 

must supply the X/Y coordinates of the area as the upper left corner viewed from the 

text, regardless of rotation. That is: 

u.l 

no 

rotation 

u.l 

90 

rotation 

u.l 

180 

rotation 

u.l 

270 

rotation 

When the area is always viewed as upright, i.e. the position of the area is always given 

as the highest, leftmost point on the page where that is area to be placed with no 

rotation, the previous example should be used instead.



8 

Working 

with Content 

This chapter explains content and defines the calls 

available at this level. 

8.1


Overview of Content Interface 


The Content Interface contains the bulk of the interface. At this level, you make 

marks on paper. Those marks may be on a Page or on a Forms XObject. They may be 

text, line drawings, or images. The marks made in a content area may also be used in 

a patterned color. 

Control Structures 

Control of style is maintained in the Adobe PDF Library structures 

PDEGraphicState and PDETextState. These structures are created and 

modified exactly as if the Adobe PDF Library were used without DLI. 

When created, content structures are always associated with a given document. They 

may be filled with arbitrarily complex text. After filling, they are associated with a 

Page or with a Forms XObject. Association destroys the structure. A single content 

element may be associated with a Forms XObject. Any number of elements may be 

associated with a Page. 

A set of transforms may be associated with a content element to position it within the 

Forms XObject or Page. This permits simple definition of text in columns or areas. 

Layering of text is straightforward: 

• The first mark made is considered to be on the bottom; all following marks are 

above it. 

• When an Image or a Form is included in a page, it is above all preceding text and 

below all following text. 

• When multiple content elements are contained in a page, they are layered in the 

order they are added to the page. 

A content element is represented by the structure DLPDFCONTENT. These structures 

are destroyed when associated with a page or form, and pointers to them should not 

be used after that time.

Working with Content 8.3 

Content Interface Calls 

The following sections contain information about the calls available for content 

elements. 

Creation and Positioning 

These calls are used to create and position a text container. 

Background colors, textures, and graphics may also be created for a container by the 

use of image and drawing commands, although special functions have not been 

supplied to accomplish these. 

dlpdfcontentcreate 

This function will create a new content element. It will be created with a rotation of 

zero degrees, a position of (0,0), and scaling of (1,1). 

dlpdfcontentrotate 

This procedure will rotate all of the contents of a given content structure by the 

specified amount. The given value may be any amount, but will be reduced to between 

0 and 360 degrees. It is expressed in degrees of counter-clockwise rotation about the 

content structure’s lower-left corner. 

dlpdfcontentscale 

This procedure will scale all of the content of a given content structure by the specified 

amount, which must be a positive number greater than 0.0001.


dlpdfcontenttranslate 

This procedure will move all of the contents of a content structure by the specified 


amounts, which are assumed to be in points. Positive values move up or right, 

depending on the axis; negative values move down and left. 

Text Placement 

These calls are used to position text within a container. 

dlpdfcontenttext 

This procedure adds a NULL-terminated string of text to the content. It will be placed 

such that the baseline of the left edge of the first character aligns with the given 

position (XPos,YPos) in points. The baseline should also proceed at the angle 

specified in Rotate, where zero is to the right and positive numbers produce 

counter-clockwise rotation in degrees. It will be set in the specified font at the 

specified PointSize and SetWidth. The parameters of PDEGraphicState and 

PDETextState will be observed. 

dlpdfcontentwidetext 

Same as dlpdfcontenttext, but permits Unicode and MultiByte text. 

Text Width Evaluation 

On occasion, it is necessary to know the width of text. The following calls will 

accomplish that.


dlpdfcontenttextwidth 

This procedure is included as an aid to composition, and to transforming widths, 

particularly word space widths, into PDF units. The procedure will return the width 

(in points) of the specified text. 

Its calling parameters include: 

• the specified Font 

• the text to be measured 

• its current SetWidth (horizontal point size) 

• Current Text State, a pointer to a PDETextState structure, which may be 

NULL. It can also be declared memset() to all 0 values, and used right away; no 

further initialization is required, nor is it provided for. 

dlpdfcontentwidetextwidth 

Same as dlpdfcontenttextwidth, but permits multi-byte (Unicode) text. 

Line Drawing 

These calls are used to draw lines within an area, and to fill or stroke those lines. 

Common to all of these calls is the PDEGraphicState, which defines line drawing 

parameters (Line Width, Join, Miter, etc.) and the Paint Operator, which


defines how the path defined should be treated (kPDEStroke, kPDEFill, 

kPDEEoFill, or a combination of these). 


There are two color definitions within the PDEGraphicState: 

• Fill Color will be used with the operators kPDEFill or kPDEEoFill. 

• Stroke Color will be used with the operator kPDEStroke. 

All of the fields within PDEGraphicState will be honored. 

NOTE: Stroking will colorize to a given width, while filling will colorize within the 

borders. To draw lines, use stroking to give the line a width. 

Functions are provided here to produce commonly-used shapes. The general path 

operator dlpdfcontentpath can image arbitrarily complex shapes. 

All of the coordinate values and sizes specified below are considered to be in points. 

The content element in which these are placed may translate, scale or rotate the 

image. 

dlpdfcontentclip 

This call is used to establish a clipping path. Note that clipping paths are not 

established automatically for images, forms, or line drawings. Generally, PDF images 

page more efficiently if there is no clipping involved. 

A clipping region is considered a part of the content structure, and will be ended at the 

end of a content structure. Clipping regions may be nested, but each nested region 

must fit within the previous region. A clipping region can, and should, be ended as 

soon as possible, using the dlpdfcontentclipend call. 

The Path and Pathlen operands of this call are identical to the 

dlpdfcontentpath operands. The EOClip operand should be FALSE for a normal 

clip and TRUE for an Even/Odd clip.


dlpdfcontentclipend 

This call is used to manually end a clipping region prior to the end of the content 

structure. It should be called as soon as possible after a clipping region is established. 

dlpdfcontentpath 

This procedure will mark a path within the content. The path is specified as an array 

of ASFixed values, pointed to by Path, with PathLen entries in the array. This is in 

all ways the same path as would be used by the Adobe PDF Library path operators. 

Such a path may be created manually or by use of the Edit Layer of the Adobe PDF 

Library. If created with the Adobe PDF Library, the pointer returned by 

PDEPathGetData is sufficient for this call. 

NOTE: The length returned by that call is the number of entries in the list, not the 

size in bytes of the list. 

dlpdfcontentrect 

This procedure marks a rectangle in the content. It will be located such that its lower 

left hand corner is at (X,Y); it will be Width wide, and Height high. Width and 

Height may not be specified as zero but may be specified as negative numbers, which 

results in flopping the rectangle. 

dlpdfcontentline 

This procedure will mark a line in the content. The line will extend from (X1,Y1) to 

(X2,Y2). 

dlpdfcontentarc 

This procedure is included as an aid in transitioning from PostScript to PDF. It will 

draw an arc centered at (X1, Y1), at a radius of Radius, from Angle1 to Angle2, 

counter-clockwise, where the angles are considered to be in degrees.


dlpdfcontentarcn 



draw an arc centered at (X1, Y1), at a radius of Radius, from Angle1 to Angle2, 

clockwise, where the angles are considered to be in degrees. 

dlpdfcontentarcto 

This is a convenience method to mimic the PostScript ArcTo operator. It will locate 

the intersections of the line (X1,Y1)->(Xint, Yint), and (X2,Y2)->(Xint, Yint), 

and draw an arc of the specified radius tangent to those two lines. The line segment 

from (X1,Y1) to the arc will be drawn. Unlike the PostScript ArcTo operator, the 

segment from the tangent to (X2,Y2) will also be drawn. 

dlpdfcontentpieslice 

This procedure is included as an aid in graph construction. It will draw a pie slice, 

centered at (X1,Y1), at a radius of Radius, from Angle1 to Angle2, counterclockwise, 

where the angles are specified in degrees. 

dlpdfcontentpieslicen 

This procedure is included as an aid in graph construction. It will draw a pie slice, 

centered at (X1,Y1), at a radius of Radius, from Angle1 to Angle2, clockwise, 

where the angle is specified in degrees. 

dlpdfcontentcircle 


draw a circle centered at (X1,Y1), at a radius of Radius. 

dlpdfcontentellipse 


draw an ellipse centered at (X1,Y1), at a vertical radius of RadiusV and a horizontal 

radius of RadiusH.


Paths 

Paths are created in the context of a document and represented as a structure, 

DLPDFPATH. 

dlpdfpathcreate 

Used to construct a path, this method accepts no parameters. It will return a pointer 

to DLPDFPATH or raise an exception indicating that no memory is available. 

dlpdfpathdestroy 

Used to destroy, this method accepts a pointer to a DLPDFPATH structure and will 

return nothing. It will raise the exception Bad Parameter if the pointer is not valid. 

dlpdfpathclear 

Used to reset a path, this method sets the current position to UNSET, the matrix to 

UNITY, and removes any path segment present. It will not deallocate the array used to 

hold the path, however, since its primary purpose is to lower the overhead associated 

with allocation and deallocation. It will raise the exception Bad Parameter if it is 

called with a NULL pointer. 

dlpdfpathcurrentx 

This method will return the current X position as an ASFixed integer. 

dlpdfpathcurrenty 

This method will return the current Y position as an ASFixed integer. 

dlpdfpathsize 

This method will return the current size of the path array (as a count of ASFixed 

integers) as an integer.


dlpdfpatharray 

This method will return a pointer to the first member of the array of ASFixed integers, 


which is the path. 

Appending Line Segments to an Existing Path 

The following methods append line segments to an existing path. Each of these 

accepts a pointer to a path as the first parameter, and may or may not have additional 

parameters describing the line segment to be built. These methods will return nothing, 

but may raise an exception if the parameters are not properly formed. 

dlpdfpathaddline 

This method accepts three parameters: 

• The first is a pointer to the path. 

• The second is the absolute Xposition. 

• The third is the absolute Yposition. 

A line will be drawn from the current position to the specified new position. If the 

current position is the same as the new position, no line segment will be added to the 

path, and no notice will be given (Optimizing). The current position following this 

command will be the specified position. 

dlpdfpathaddliner 

This methods accepts two parameters, the coordinates of the destination to draw to: 

• The first is the distance from the current Xposition to the specified Xposition. 

• The second is the distance from the current Yposition to the specified 

Yposition. 

A line will be drawn from the current position to the specified new position. If the 

distances specified are both zero, no line segment will be added to the path and no


notice will be given (Optimizing). The position following this command will be the 

position derived by applying the X and Y offsets to the prior position. 

dlpdfpathaddmove 

This method accepts two parameters, the coordinates of the destination to move to: 

• The first is an Xposition relative to the current context. 

• The second is a Yposition relative to the current context. 

The current position will be moved to the specified position without adding a stroked 

line. If the current position is the same as the specified new position, no line segment 

will be added to the path, and no notice will be given (Optimization). The position 

following this command will be the specified position. 

dlpdfpathaddmover 

This method accepts two parameters: 

• The first is an Xposition relative to the current context. 

• The second is a Yposition relative to the current context. 

The current position will be moved to the specified position without adding a stroked 

line. If the current position is the same as the specified new position, no line segment


will be added to the path, and no notice will be given (Optimization). The position 

following this command will be the specified position. 

dlpdfpathaddarc Concepts and Facilities: Guide to the DL Pager Composition System 

This method accepts six parameters: 


• The second is an Xposition of the arc center point. 

• The third is the Yposition of the arc center point. 

• The fourth is the radius of the arc. 

• The fifth is the start angle (where zero is directly to the right of center) where 

the arc is to begin. 

• The sixth is the end angle where the arc is to end. 

If the current position does not coincide with the position defined by X1, Y1, Radius 

and Start Angle, then a straight line segment will be added from the current 

position to this point. A smooth curve of the specified radius will be drawn from 

that specified point counter-clockwise to the point specified by X1, Y1, Radius, End 

Angle. The current position will be set to that ending point. If the starting and ending 

points specify the same angle, a full circle will be drawn. The position following this 


dlpdfpathaddarcn 





• The fourth is the radius of the arc. 

• The fifth is the start angle (where zero is directly to the right of center) where 


• The sixth is the end angle where the arc is to end. 

If the current position does not coincide with the position defined by X1, Y1, Radius 

and Start Angle, then a straight line segment will be added from the current 

position to this point. A smooth curve of the specified radius will be drawn from 

that specified point clockwise to the point specified by X1, Y1, Radius, End Angle.


The current position will be set to that ending point. If the starting and ending points 

specify the same angle, a full circle will be drawn. The position following this 


dlpdfpathaddarcto 



• The second is an Xposition of the intersection of tangents. 

• The third is the Yposition of the intersection of tangents. 

• The fourth is the Xposition of a point defining the second tangent. 

• The fifth is the Yposition of a point defining the second tangent. 

• The sixth is the radius of the arc. 

The two lines (CurrX, CurrY)->(X1,Y1) and (X2,Y2)->(X1,Y1) are joined by an arc 

of radius (R). The line segment from the current position to the start of the arc is 

drawn, followed by the arc itself. The line segment from the end of the arc to the point 

X2,Y2 is not drawn. The position following this command will be the intersection of 

the arc with the line (X2,Y2)->(X1,Y1). If the two lines are colinear, a straight line 

segment is drawn from current position to (X1,Y1), which then becomes the current 

point. 

dlpdfpathaddelliparc 

This method accepts seven parameters: 




• The fourth is the horizontal radius (HRad) of the ellipse defining an arc segment. 

• The fifth is the vertical radius (VRad) of the same ellipse. The HRad and VRad 

functions support creating arc segments from an elliptical shape, instead of a 

circular shape as described in dlpdfpathaddarc. If the same horizontal and


vertical radii are passed to this function, it behaves identically to 

dlpdfpathaddarc. 

• The sixth is the start angle (where zero is directly to the right of center) where 



• The seventh is the end angle where the arc is to end. If the current position does 

not coincide with the position defined by X1, Y1, Radius and Start Angle, then 

a straight line segment will be added from the current position to this point. A 

smooth curve of the specified radius will be drawn from that specified point 

counter-clockwise to the point specified by X1, Y1, Radius and End Angle. The 

current position will be set to that ending point. 

If the starting and ending points specify the same angle, a full circle will be drawn. 

The position following this command will be the specified position. 

dlpdfpathaddelliparcn 





• The fourth is the horizontal radius (HRad) of the arc. 

• The fifth is the vertical radius (VRad) of the arc. The HRad and VRad support 

drawing elliptical arc segments. 

• The sixth is the start angle (where zero is directly to the right of center) where 


• The seventh is the end angle where the arc is to end. If the current position does 

not coincide with the position defined by X1, Y1, Radius and Start Angle, then 

a straight line segment will be added from the current position to this point. 

A smooth curve of the specified radius will be drawn from that specified point 

clockwise to the point specified by X1, Y1, Radius and End Angle. The current 

position will be set to that ending point. If the starting and ending points specify the


same angle, a full circle will be drawn. The position following this command will be 

the specified position. 

dlpdfpathaddelliparcto 



• The second is the Xposition of the intersection of tangents. 

• The third is the Yposition of the intersection of tangents. 

• The fourth is the Xposition of a point defining the second tangent. 

• The fifth is the Yposition of a point defining the second tangent. 

• The sixth is the horizontal radius (HRad) of the arc. 

• The seventh is the vertical radius (VRad) of the arc. 

The HRad and VRad support drawing elliptical arc segments. The two lines 

(CurrX,CurrY)->(X1,Y1) and (X2,Y2)->(X1,Y1) are joined by an arc of radius (R). 

The line segment from the current position to the start of the arc is drawn, followed 

by the arc itself. The line segment from the end of the arc to the point X2,Y2 is not 

drawn. 

The position following this command will be the intersection of the arc with the line 

(X2,Y2)->(X1,Y1). If the two lines are colinear, a straight line segment is drawn from 

the current position to (X1,Y1), which then becomes the current point. 

dlpdfpathaddcurve 


• The first is a pointer to a path. 

• The second and third are the X and Y positions of a point which will be Control 

Point 1. 

• The fourth and fifth are the X and Y positions of a point which will be Control 

Point 2. 

• The sixth and seventh are the X and Y positions of a point which will be the end 

point of the curve. 

A smooth curve (a cubic Bézier) will be drawn from the current position to the end 

position, under direction of the two control points. The current position will be the


end position of the line at completion of this operation. If the end position specified is 

identical to the current position, no segment will be appended, and no notice will be 

given (Optimization). 


dlpdfpathaddcurver 



• The second and third are the distance from current point to the X and Y positions of 

a point which will be used for Control Point 1. 

• The fourth and fifth are the distance from current point to the X and Y positions of 

a point which will be Control Point 2. 

• The sixth and seventh are the distance from the control point to the X and Y 

positions of a point which will be the end point of the curve. 

A smooth curve (A cubic Bézier) will be drawn from the current position to the end 

position, under direction of the two control points. The current position will be the 

end position of the line at completion of this operation. If the end position specified is 

identical to the current position, no segment will be appended, and no notice will be 

given (Optimization). 

dlpdfpathaddcurvev 

This method accepts five parameters: 


• The second and third are the X and Y positions of a point which will be used for 

Control Point 2. 

• The fourth and fifth are the X and Y positions of the end point of the curve. 


position, under direction of the two control points. Control Point 1 is the current 

position. The current position will be the end position of the line at completion of this


operation. If the end position specified is identical the current position, no segment 

will be appended, and no notice will be given (Optimization). 

dlpdfpathaddcurvey 



• The second and third are the X and Y positions of a point which will be used for 

Control Point 1. 

• The fourth and fifth are the X and Y positions of the end point of the curve. 


position, under direction of the two control points. Control Point 2 is the end 

position. The current position will be the end position of the line at completion of this 

operation. If the end position specified is identical to the current position, no segment 

will be appended, and no notice will be given (Optimization). 

dlpdfpathaddrect 



• The second and third are the X and Y positions of a point which will be one corner 

of the box. 

• The fourth will be the width of the box. 

• The fifth will be the depth of the box. 

If the specified position is not the current position, a MoveTo to the specified position 

will be made. A rectangle will be added to the path, starting at the specified position


and proceeding upward (unless the depth is negative) and to the right (unless the 

width is negative). The end position after this operation will be the specified position. 


If the width and depth are both zero, no segment will be appended, but the current 

position will still be updated. 

dlpdfpathaddclose 

This method accepts no operands. It will append to the path a close path operator 

and leave the current position as the first specified position in the path. 

dlpdfpathsetmatrix 

This method accepts a pointer to a path and a pointer to a matrix. The specified 

matrix will be concatenated (i.e. applied) to the matrix of each container in which this 

path is drawn, affecting all on the current path. This allows the user complete and 

flexible control of the shape drawn by the path. If the pointer to the path or the 

matrix is NULL, a genErrBadParm exception will be raised. 

dlpdfmatrixrotate 

This function will modify the specified matrix so as to effect counter-clockwise 

rotation of any marks drawn via this matrix. Angle is an angle in degrees and 

fractions of degrees. 

Patterns 

Patterns are created in the context of a document, and represented by the structure 

DLPDFPATTERN. They contain a content block, whose contents become one tile of the


pattern. The size, shape, and location of a given tile can be modified by the specified 

matrix. 

The size of the tile is set by the BBox (Bounding Box) parameter. 

Spacing between adjacent tiles is set by the Xstep and Ystep parameters. Tiles may 

overlap, be placed adjacent, or be placed with space between them. 

The TileType parameter may be 1, 2 or 3, corresponding to the Adobe TileType 

parameter (see the Portable Document Format Reference Manual). 

The Colored parameter, if true, indicates that the pattern contains its own color 

specifications which should be used in place of any fill/stroke color specification. 

If the Colored parameter is FALSE, it indicates that the fill/stroke specification 

should be used for color. 

dlpdfpatterncreate 

This creates a patterned color space, and returns a pointer to that space. The pointer 

may be used in dlpdfcontentusefillpattern or 

dlpdfcontentusestrokepattern to apply this colored pattern to all following 

material. All patterns will be destroyed and their handles invalidated in the 

destruction of the document that contains them. 

dlpdfcontentusefillpattern 

See dlpdfpatterncreate above. Note that this call with a NULL pointer to a 

pattern will turn off patterned color space. 

dlpdfcontentusestrokepattern 

Similar to dlpdfcontentusefillpattern above.


Referencing Predefined Structures 

These calls permit the inclusion in content of complex pre-built structures. These 


structures may be arbitrarily positioned, scaled and rotated when placed into the 

content. 

dlpdfcontentreferenceform 

This procedure places a copy of a Form into the current content. All of the markings 

in the Form will appear. The lower left hand corner of the Form will be positioned at 

(X, Y). The Form will be rotated counter-clockwise as per rotate and scaled as per 

ScaleX and ScaleY. 

dlpdfcontentreferenceimage 

This procedure places a copy of the referenced image into the current content. It will 

be placed so as to align its lower left hand corner with (X, Y), will be scaled as per 

ScaleX and ScaleY, and rotated as per Rotate. 

The Scale Factors will determine the resulting size of the image. You need to know the 

original image resolution and its intended size in order to determine whether a Scale 

Factor on either axis is required. In DLI v2.2.5 and higher, the 

dlpdfimagegetsize method can retrieve image sizing data for you, and dividing 

the intended print size by the file size for each dimension (delivered by 

dlpdfimagegetsize) will yield a Scale Factor ratio which 

dlpdfcontentreferenceimage will use to calculate the final output image size.


The typical scaling calculation using values returned by dlpdfimagegetsize 

would be to divide the intended print size by the image size on each axis; e.g. 

dlpdfcontentreferenceimage(Content, Image, 

Int32ToFixed(72), Int32ToFixed(92), 0, 

ASFixedDiv(xPoints, Int32ToFixed(xRasters)), 

ASFixedDiv(yPoints, Int32ToFixed(yRasters))); 

An image in which each pixel of each raster line represents one PDF unit of output 

will return the same values for both image dimension (xRasters and yRasters) 

and print size (xPoints and yPoints), and thus a Scale Factor of 1 on both axes. 

dlpdfimagegetsize 

The Scale Factors specified in dlpdfcontentreferenceimage will determine the 

resulting size of the image. This method gives you the image information necessary to 

calculate those values, dividing the intended print size by the file size for each 

dimension. This yields a Scale Factor ratio which dlpdfcontentreferenceimage 

uses to calculate the final output image size. 

Associating Content to Page 

The dlpdfcontenttopage call places the content onto a page. Once made, the 

content is no longer accessible via the DLI Package, and the pointer to the content 

structure is no longer valid. 

dlpdfcontenttopage 

This procedure will make the markings placed into content a part of the specified 

page. Following this call, the content structure no longer exists: pointers to it are then 

invalid and should no longer be used.


Adding Comments to Content Elements 

dlpdfcontentcomment 


This method will insert the specified text string, in the order provided, into the 

content elements. This string will always be placed on a separate line, preceded by 

"%" to mark it as a comment. The comment text must not contain a newline 

character, unless the character following that newline is a percent sign ("%"). The 

content element must be valid; the comment pointer must point at a valid non-NULL, 

non-zero-length string.

9 

Working 

with Forms 

This chapter explains Forms XObjects and defines the 

calls available. 

9.1


Overview of Forms 


Forms, in this sense, are predefined content that may be placed into a document many 

times. A form’s content will be included in the PDF or PostScript document only once, 

but it may be imaged in the document any number of times. Defining forms is a 

powerful means of reducing the size of a document. It also considerably reduces the 

time needed to create a document. 

Forms Structure 

A form is represented in DLI as a structure, DLPDFFORM. Any number of forms may 

be defined, on a per-document basis: if the same form is needed in multiple 

documents, multiple copies of it must be created. 

Forms are tracked within the document structure, and all forms for a document are 

destroyed when the document is destroyed. Pointers to forms become invalid when 

the document is destroyed and must not be used after that time. 

The content of a form may be arbitrarily complex. Forms may contain images as well 

as other forms.

Working with Forms 9.3 

Form Calls 

There are only a few calls which involve forms. 

dlpdfformcreate 

This function will create a new form in the document specified as Doc, with the 

content previously placed into the container Content. 

The form will be considered to be of the size specified in BBox. This is an Adobe PDF 

Library ASFixed Rectangle, whose contents are assumed to be in points. The 

Bounding Box need not be located at (0,0); however, it must have a positive Width 

and Depth. The content block used to create a form is destroyed in the form’s 

creation, and any handles to it become invalid after that point. 

dlpdfcontentreferenceform 

Reference to a form in content is made via dlpdfcontentreferenceform. 

dlpdfformdestroy 

This destroys the named form, releasing its resources. It invalidates the form handle.



10 

Displaying 

Line Drawings 

Line drawings are pictures made up of lines connecting 

specified points. These lines may be stroked (covered in a 

fixed width and colored marking) or filled (the space 

defined by the inside of the lines is painted with a defined 

color or pattern). The areas defined by such a set of lines 

need not be contiguous. 

10.1.

10.2. DLI Implementation and Reference Guide 

Overview 


This chapter contains calls used to draw lines within an area, and fill or stroke those 

lines while producing commonly-used shapes. Common to all of these calls is the 

PDEGraphicState, which defines line drawing parameters (Line Width, Join, 

Miter, etc.) and the Paint operator, which defines how the path defined should be 

treated (kPDEStroke, kPDEFill, kPDEEoFill, or a combination of these). 

There are two color definitions within the PDEGraphicState: 

• Fill Color will be used with the operators kPDEFill or kPDEEoFill 

• Stroke Color will be used with the operator kPDEStroke. 

All of the fields within PDEGraphicState will be honored. 

NOTE: Stroking will colorize to a given width, while filling will colorize within the 

borders. To draw lines, use stroking to give the line a width. 

Functions are provided in this chapter to produce commonly-used shapes. The general 

path operator dlpdfcontentpath can image arbitrarily complex shapes. 

All of the coordinates and sizes specified below are considered to be in points. The 

content element in which these are placed may translate, scale, or rotate the image.

Displaying Line Drawings 10.3. 

Approaches to Line Drawing 

There are two approaches to line drawing supported by DLI. The first uses a simple 

interface to construct or fill and stroke a structure. The second permits the user to 

construct an arbitrarily complex collection of markings, and then place that collection 

within any number of content structures. 

Directly-Drawn Methods 

In general, the directly-drawn methods are the simplest to use, and the best choice for 

operations like underlining, page rules and area borders. This collection of directlydrawn 

structures is derived from the operators for PostScript graphics, and common 

usage of those operators. 

All of these operators have their first three parameters in common. These are: 

• The container in which the structure will be drawn 

• The current state in which all parameters are used 

• The Painting operator, which defines how the path defined should be treated. It 

must be one of the following, or a combination of these: 

• kPDEStroke — stroke the lines of the structures 

• kPDEFill — fill the areas defined by the lines 

• kPDEEOFill — stroke the area contained an odd number of times by the 

area. 

In the case of these structures, there can be no multiple containment, and hence 

EOFill and Fill will have the same results. 

All of the methods have additional parameters, specifying the location and size of the 

structure drawn. These will be different for each structure, but will always be 

ASFixed values. 

If the content area in which these structures are drawn is itself distorted (i.e. its 

AreaMatrix is not the unity matrix; see the discussion of containers and matrix 

manipulation beginning with “What are Containers?” on page 7.2), then the 

structures drawn will be positioned and shaped to reflect that distortion.


dlpdfcontentrect 

This will draw a rectangle. The four parameters are ASFixed values reflecting X 


position, Y position, Width and Depth. If Width and Depth are positive 

numbers, the rectangle will be positioned with its lower left hand corner at the 

position (X,Y). 

dlpdfcontentline 

This will draw a line. There are four parameters, reflecting ASFixed values for (X,Y) 

start and (X,Y) end. 

NOTE: The Fill operator is meaningless with this structure. 

dlpdfcontentarc 

This will draw a curved line. 

• The first two parameters are ASFixed values reflecting the (X,Y) position of the 

center of the circle of which this arc is a portion. 

• The third parameter is the ASFixed value of the Radius of that circle. 

• The fourth and fifth parameters are the Start Angle and End Angle at which 

the arc starts and ends respectively. 

The arc is drawn counter-clockwise from Start Angle to End Angle. The angles 

are specified in degrees, with Zero degrees pointing to the right. If the start and end 

angles are coincident, a full circle will be drawn. 


This is identical to the previous, except that the arc is drawn clockwise.



This is an implementation of the PostScript arcto command, included as a 

convenience to output drivers which currently support PostScript. 

• The first two parameters are the ASFixed values of the (X,Y) position of the Line 

Start. 

• The third is the ASFixed value of the Radius of the Arc Segment. 

• The fourth and fifth are the ASFixed values of the (X,Y) position of the 

Intersection. 

• The sixth and seventh are the ASFixed value of the (X,Y) position of the Line 

End. 

NOTE: This implementation will draw the line segment from the end of the arc to 

the end position, which would not be drawn in PostScript. 

dlpdfcontentpieslice 

This method was included as a convenience operator for the construction of pie 

charts. 

• The first two parameters are the ASFixed values for (X,Y) of the center of the pie 

the slice is taken from. 

• The third is the ASFixed value for the Diameter of the pie slice. 

• The fourth and fifth are the Start Angle and End Angle, in degrees, of the pie 

slice. 

The angles are counter-clockwise from right. The arc of the pie will be drawn counterclockwise. 

If the angles are coincident, a full circle will be drawn. 


This is identical to dlpdfcontentpieslice above, except that the arc will be 

drawn clockwise from the Start Angle to the End Angle.



This method will draw a circle whose center is the first two parameters and whose 


radius is the third parameter. 


This method will draw an ellipse whose center is the first two parameters, the 

ASFixed value of the X Radius is the third parameter, and the ASFixed value of 

the Y Radius is the fourth parameter. 


This method will draw an arbitrary path. The path is an array of ASFixed values, 

constructed according to the PDF rules for path construction. These can be found in 

the Adobe PDF Library API Reference Manual under PDEPathAddSegment. 

The path may have been constructed via PDEPath operators, or constructed 

manually. 

NOTE: If constructed via PDEPath, then PDEPathGetData must be used to 

obtain the array and array size used in this call. 

The first parameter is a pointer to an array of ASFixed; the second is a count of the 

number of entries in that array. 

Path Drawing Sample 

In an accompanying codesamples folder you should find a sample file entitled 

line drawing using draw fixed structure.txt. This sample source file 

will create a document with one page, containing a square whose lower left corner is 

one inch above the bottom and one inch right of the left edge of the page. The square 

will be red, edged in black. From outer edge to outer edge, the square will be 74 points 

wide and tall.


Path Drawing Methods 

The directly-drawn shapes are useful for a great number of graphics, but they do not 

permit filling of complex arbitrary shapes without the construction of a path. For that 

reason, a second set of drawing operators was added. These operators simply 

construct and draw a path, which may be arbitrarily complex. It may also be 

disjointed. 

The DLPDFPATH structure will contain a path of any size, allocating additional 

memory as needed. Path construction is via methods which add segments to the 

existing path. These methods seek to include both the PDF and PostScript graphics 

operators. When completed, the path may be added to a content area. The path is not 

destroyed when imaged and may be reused any number of times. The DLPDFPATH 

structure also includes a provision for a CTM Matrix, which may be used to 

transform the position and appearance of the path. 

Within the path, a current point is maintained. This will be undefined initially, or after 

a dlpdfpathaddclose, and will be the end point of the segment added at all other 

times. Some operators require that the current point be established prior to adding a 

segment of that type. Others will add a straight line segment drawn from the current 

position to the start of the defined segment prior to a segment. This behavior mimics 

the drawing mechanism in PostScript. 

The first parameter of all of these methods, except dlpdfpathcreate and 

dlpdfcontentdrawpath, is a pointer to a valid DLPDFPATH structure. 


This method will return a pointer to a new DLPDFPATH structure. The path’s contents 

will be empty, its current position will be undefined, and its matrix will be set to the 

unity matrix. This structure will persist until specifically deleted by the 

dlpdfpathdestroy method. 

The DLPDFPATH is not specific to a document or content structure. It may be shared 

across many documents and placed within any number of content structures.


dlpdfpathclear 

This method will remove all content from an existing DLPDFPATH structure and 


restore it to the state it was in following the call to dlpdfpathcreate. It is included 

to lower the overhead of creating many paths. 


This method will destroy a DLPDFPATH structure and free all resources that it used. 


This method will change the current position of a DLPDFPATH structure without 

drawing a line. It may be used to establish the starting point of a path or to add a 

disjunction to an existing path. It accepts two operators, an X and a Y position, as 

ASFixed values. The current position following this method will be the specified 

(X,Y) position. 


This method also sets the current position, but sets it relative to the existing current 

position. If there is no current position, this method will raise an exception 

(genErrBadParm). This method accepts two parameters, an X and a Y displacement, 

as ASFixed values. The current position following this method will reflect the 

application of the X and Y displacements. 


This method draws a line from the current position to the position specified by its two 

parameters, X and Y position as ASFixed values. If there is no current position 

established, this method will raise an exception (genErrBadParm). The current 

position following this method is the specified (X,Y) position.



This method also draws a line segment, drawn from the current position to a new 

position, specified by X and Y displacement as ASFixed values. If there is no current 

position established, this method will raise an exception (genErrBadParm). The 

current position following this method will reflect the application of the X and Y 

displacements. 

dlpdfpathaddarc 

This method will append an arc segment to the current path. The parameters specify 

an (X,Y) position, in ASFixed values, of the center of the arc, a Radius as an 

ASFixed value, and two angles in degrees as ASFixed angles. 

If there is a current position, a line segment will be added from the current position to 

the start angle of the arc. If there is no current position, a move to the start angle of 

the arc will be appended to the path. The arc will be drawn counter-clockwise from 

the start angle to the end angle. If the angles are coincident, a full circle will be drawn. 

The angles will be interpreted such that zero degrees is pointing right. 

After completion, the position of the end of the arc will be the current position. 

dlpdfpathaddarcn 

This method is identical to dlpdfpathaddarc, except that the arc will be drawn 

clockwise. 

dlpdfpathaddarcto 

This method will draw a straight line segment from the current position toward the X 

and Y coordinates specified by the first two parameters. This line will terminate at the 

intersection of an arc connecting this line to a second line, drawn from the first


specified (X,Y) to the second (X,Y) specified by the third and fourth parameters, at a 

Radius specified by the fifth parameter. 


Xint1/ 

Yint1 

X1/Y1 

Xint2/ 

Yint2 

Current Position 

X2/Y2 

NOTE: The straight segment from Xint2/Yint2 -> X2/Y2 is not drawn. The 

current position is set to Xint2/Yint2. 

If there is no current position when this method is called, an exception 

(genErrBadParm) will be raised. 


This method will append an arc segment to the current path. The parameters specify 

an (X,Y) position, as ASFixed values, of the center of the arc, a Horizontal 

Radius and Vertical Radius as ASFixed values, and two angles in degrees as 

ASFixed angles. 

The Horizontal Radius and Vertical Radius values create arc segments from 

an elliptical shape, instead of the circular arc segments of dlpdfpathaddarc. If the 

same horizontal and vertical radii are passed to this function, it behaves identically to 

dlpdfpathaddarc. 

If there is a current position, a line segment will be added from the current position to 

the start angle of the arc. If there is no current position, a move to the start 

angle of the arc will be appended to the path. The arc will be drawn counterclockwise 

from the start angle to the end angle. If the angles are coincident, a


full circle will be drawn. The angles will be interpreted such that zero degrees is 

pointing right. 

After completion, the position of the end of the arc will be the current position. 

dlpdfpathaddelliparcn 

This method is identical to dlpdfpathaddelliparc, except that the arc will be 

drawn clockwise. 


This method will draw a straight line segment from the current position toward the X 

and Y coordinates specified. This line will terminate at the intersection of an arc 

connecting this line to a second line, drawn from the first specified (X,Y) to the second 

(X,Y) specified, at a specified Horizontal Radius and Vertical Radius.


dlpdfpathaddcurve 

This is the first of the four methods which add a spline, or cubic Bézier curve, to the 


path. 

All Bézier curves consist of four points: 

Xctrl1/ 

Yctrl1 

Xend/ 

Yend 

Xstart/ 

Ystart 

Xctrl2/ 

Yctrl2 

This method (as well as the following three) uses current position as the starting point 

of the curve. If no starting point is specified, the method will raise an exception 

(genErrBadParm). 

The first two parameters of this method are the position of Control Point 1, the 

second two parameters are the position of Control Point 2, and the last two 

parameters are the position of the end point of the curve. 

Following this method, the current position will be the end point of the curve. 

dlpdfpathaddcurver 

This method is identical to dlpdfpathaddcurve, except that the positions are 

expressed as relative distances from the current point, not absolute distances from the 

origin.



This method is identical to dlpdfpathaddcurve, except that both the start and first 

control point are assumed to be the current position. 

Xend/ 

Yend 

Xstart/ 

Ystart 

Xctrl1/ 

Yctrl1 

Xctrl2/ 

Yctrl2 


This method is identical to dlpdfpathaddcurve, except that the second control 

point is assumed to be the ending position. 

Xctrl1/ 

Yctrl1 

Xstart/ 

Ystart 

Xend/ 

Yend 

Xctrl2/ 

Yctrl2


dlpdfpathaddrect 

This method will draw a rectangle. The first two parameters specify the (X,Y) position 


of a corner, and the next two specify the width and depth of the rectangle. A 

positive width will draw to the right, and a positive depth will draw upward. 

Current position need not be set before this method is called, and current position will 

be set to the specified (X,Y) position after it is used. 


This method will append a straight line segment from the current position to the start 

of the first element in the path. If a current position is not set, it will have no effect. 

Following this method, the current position will be unset. 

NOTE: This does not need to be the last segment of a path. Additional, disjoint 

segments may be set. 

dlpdfcontentdrawpath 

This method is used to add a drawn path to content. 

• Its first element is the DLPDFCONTENT onto which this path is to be drawn. 

• Its second parameter is the DLPDFPATH structure to be drawn. 

• Its third parameter is a pointer to a PDEGraphicState structure. This structure 

contains definitions of colors to be applied, and line sizes and parameters to be used 

when drawing a path.


• The fourth and last parameter is the Path Painting operator. This must be one 

of 

— kPDEStroke 

— kPDEFill 

— kPDEEoFill 

— kPDEStroke | kPDEFill 

— kPDEStroke | kPDEEoFill 

Path Drawing Sample 

In an accompanying codesamples folder you should find a sample file entitled 

drawing a rectangle and ellipse in path operators.txt. This 

program sample shows the use of an arbitrarily complex path while creating a 

rectangle with an ellipse embedded within it. 

Transformation Matrices 

A Transformation Matrix can be applied to the path as a whole when it is drawn in 

order to resize or reposition it. This matrix will be concatenated with the matrix of the 

container in which the path is drawn. 

Matrix Arguments 

The matrix consists of six ASFixed values (a, b, c, d, h and v): 

• Values a and b control the movement in X and Y coordinates produced by a 

movement in X. 

• Values c and d control the movement in X and Y coordinates of a movement in Y. 

• Values h and v are horizontal and vertical offsets to the position of the drawing 

(positive values are up and right). 

dlpdfpathsetmatrix 

This method will set a matrix which will be applied to the path as a whole when it is 

drawn. This matrix will be concatenated with the matrix of the container in which the 

path is drawn. The method accepts a single parameter, a pointer to an 

ASFixedMatrix.


Matrix Translations 

The unity matrix ([1, 0, 0, 1, 0, 0]) causes a 1 unit movement in X to be a 1 


unit movement in X and a zero unit movement in Y; a 1 unit movement in Y becomes 

a 0 unit movement in X and a 1 unit movement in Y. 

More precisely: 

RealX = X * a + Y * c + h 

RealY = X * b + Y * d + v 

Hence: 

• the matrix [1 0 0 -1 0 0] will invert the figure drawn 

• the matrix [-1 0 0 1 0 0] will mirror-image the figure 

• the matrix [.707 .707 -.707 .707 0 0] will rotate it 45 degrees 

Image Translation 

Translation is the simple movement of the image, and is accomplished by modifying h 

and/or v. These values are interpreted in the un-transformed space. For more details, 

please see section 4.2.2, "Common Transformations," in the Portable Document 

Format Reference Manual. 

Image Rotation 

A matrix may be rotated by using the method dlpdfmatrixrotate. This method 

accepts a pointer to a matrix, and transforms it to accomplish a rotation of the 

specified angle (in degrees, as an ASFixed value, counter-clockwise). 

Image Shearing and Scaling 

Shearing of an image may be accomplished by modifying b or c only. Scaling may be 

accomplished by modifying a and/or d only. 

CAUTION: Be sure to scale before rotating, if you are doing both.


Graphic State and Line Drawing 

This is a brief discussion of the graphic state parameters. For a fuller explanation, 

please see section 4.3, "Graphics State," in the Portable Document Format Reference 

Manual. The fields listed are components of the PDEGraphicState structure as 

defined by the Adobe PDF Library SDK. 

fillColorSpec 

This is the specification of color to be used when kPDEFill or kPDEEoFill is 

specified as a path, or when a structure is drawn. Refer to “Library Color 

Descriptions” on page 12.2 for a full discussion of setting this value. 

NOTE: If a pattern has been set for the container in which this figure is drawn, 

that pattern may be used in place of, or in addition to, this color specification. 

strokeColorSpec 

This is the specification of color to be used when kPDEStroke is specified as a path, 

or when a structure is drawn. Refer to “Library Color Descriptions” on page 12.2 for 

a full discussion of setting this value. 

NOTE: If a pattern has been set for the container in which this figure is drawn, 

that pattern may be used in place of, or in addition to, this color specification. 

lineWidth 

This is an ASFixed value in scaled units. Note that a DLPDFPATH matrix, which 

specifies scaling, will affect this value. This value must be set specifically when the 

graphic state structure is created.


lineJoin 

• A value of zero for this parameter continues the joined lines to a point. 

• A value of 1 rounds Concepts over and the join Facilities: at lineWidth Guide to Radius. the DL Pager Composition System 

• A value of 3 butts the line ends and fills the notch with stroke color, causing it to be 

beveled. 

If the value is 0, and the extension of the line to a point exceeds the miterLimit, 

then the line will be beveled as with a value of 3. 

lineCap 

• A value of zero produces butt-ended lines, ending at the end point of the segment. 

• A value of 1 produces round-ended lines, with a diameter equal to lineWidth. 

• A value of 2 produces square-ended lines, extending 1/2 line width beyond their end 

point. 

miterLimit 

Miter is the shape of the intersection of two lines. This parameter limits the length of a 

miter as a function of the line thickness. It is specified as an ASFixed value and must 

be greater than 1. For more information, see "Miter Limit" in section 4.3.2 of the 

Adobe PDF Reference Manual v1.5. 

flatness 

Controls the amount of error permitted between a path’s ideal position and the actual 

position in which it is placed. This is an ASFixed value, between 0 and 100. A value 

of zero permits the device to use its own flatness value, and is usually the best choice. 

dash 

A means of producing dashed, dotted or otherwise broken lines in stroking a path. 

Note that a patterned color space should not be used in stroking a path (although it


can be), because the result will be the intersection of the pattern and the path, rather 

than the pattern following the path. 

The dash parameter is a pointer to a PDEDash structure. In essence, this structure 

allows you to define a pattern of off/on changes to be used in stroking a line to achieve 

a wide variety of dashed and dotted lines. For more information, see "PDEDash" 

within the Declarations section of the Adobe Acrobat Core API Reference Manual, 

and "Line Dash Pattern" in section 4.3.2 of the Adobe PDF Reference Manual v1.5.



11 

Image 

Display 

Images are predefined collections of shapes and colors 

which are included into the document as a picture. They 

may be as simple as a single bitmap or as complex as a 

complete PDF page. 

11.1


Overview 


Inclusion of graphics is accomplished in two ways. The first is an image, in the sense 

of a PDF or PostScript Image Operator. The second is a Encapsulated PostScript (EPS) 

file. Note that images included as EPS will not appear in PDF pages on-screen (e.g. 

when displayed by Adobe Reader or Adobe Acrobat), but will appear in both 

PostScript pages and Adobe PDF PostScript pages. Adobe Normalizer, also available 

from Datalogics, can be used to distill EPS images to PDF format in order to make 

EPS sources visible in PDF output. 

The interfaces provided in DLI for images are intentionally very low-level. They 

presume that any graphics conversions have already been completed. Public-domain 

packages for the conversion of graphics from common formats (PNG, GIF, TIFF, etc.) 

are readily available and can create data in the form these interfaces expect. 

Graphic Image Structures 

DLI manages graphics via the structure DLPDFIMAGE. This structure is used for both 

image and EPS data. 

There are four functions to create images depending on the format (Bitmap, EPS, PDF, 

and a convenience function for several other graphic formats), and one function to use 

an image (dlpdfcontentreferenceimage). 

NOTE: Encapsulated PostScript (EPS) is not a valid graphic format for PDF. The EPS 

function available through DLI will enable you to embed the EPS image in the PDF 

document, but it will not be visible until the document is printed. (Adobe 

Normalizer, also available from Datalogics, can be used to distill EPS images to PDF 

format in order to make EPS sources visible in PDF output.) 

Image structures are created on a per-document basis. If the same image is used in 

multiple documents, multiple copies of that image must be created. Images are tracked 

within the document and all images are destroyed when the document is destroyed.

Image Display 11.3 

Pointers to images become invalid on document destruction and must not be used 

after that time. 

A document may contain any number of images. Each image will be included in the 

document only once, but may be referenced within that document many times. 

The image is considered to be a part of the document, and may not be used in any 

document other than the one in which it was created. Images need not be directly 

destroyed, since they will be destroyed automatically when the document that 

contains them is destroyed. 

Images are tracked and reused via the ImageName value. The same image data with a 

different Image Name is considered a different image. Image data is passed into the 

creation routines via strings in memory. These strings may be freed after the call to 

create the image. 

Implementations of DLI on UNIX and Windows include public-domain libraries to 

convert a number of common graphic forms into bitmaps usable by PDF. 

NOTE: The public-domain graphic-conversion libraries used on Unix and Windows 

are not available on OS/390 and OS/400 platforms. Consequently some image 

creation procedures are not available under OS/390 and OS/400. 

Graphic Image Forms 

Predefined images typically fall into one of two major varieties: 

• Bitmap Graphic Forms 

• Graphical Language Forms 

Bitmap Graphic Forms 

This is the most basic form of image. It consists of a stream of bits; indications of the 

number of samples per line, and the number of lines; a description of the samples 

(color model, sample size); and a description of ordering. It may also contain a


description of resolution (samples per inch horizontal and/or vertical). The stream 

may be compressed, in which case the compression algorithm and parameters must 

also be given. 


These images may be expressed at various levels, from something as simple as “Here 

is a bitmap of n lines by n samples in 1-bit gray scale,” to more-complex references to 

standards for graphics encoding and compression (e.g. JPEG/JPG, TIFF, GIF, PNG, 

etc.). However, the Adobe PDF Library package contains no logic to transform 

bitmaps, so they must all be presented to the Adobe PDF Library in a common 

manner. 

This excerpt from the graphical image example shows the logic for inserting a raw 

bitmapped graphic into a document. 

"C" Example: Bitmapped Graphic via dlpdfimagecreatefrombmp 

/* Allocate memory to hold the image bitmap */ 

ImageString = malloc (ImageWidth * ImageDepth); 

/* Open read the bitmap, and close the bitmap file */ 

ImageFile = fopen (ImageName, "rb"); 

fread (ImageString, 1, ImageWidth * ImageDepth, ImageFile); 

fclose (ImageFile); 

/* Get the color space DeviceGray as a COS object */ 

GraySpace = PDEColorSpaceCreateFromName (ASAtomFromString 

("DeviceGray")); 

PDEColorSpaceGetCosObj (GraySpace, &Color); 

/* Create a DLPDFIMAGE object from the bitmap */ 

Image = dlpdfimagecreatefrombmp (Doc, "Bear", ImageString, 

ImageDepth * ImageWidth, 

ImageWidth, ImageDepth, 

8, Color, FALSE); 

/* Free the image string from memory */ 

free (ImageString); 

/* "Paste" the image into the container, centered over the 

* red box */ 

dlpdfcontentreferenceimage (Content, Image, 

(fixedFour * 72) - ((Image->BBox.left + Image->BBox.right)/2), 

(fixedFour * 72) - ((Image->BBox.top + Image->BBox.bottom)/2), 

0, fixedOne, fixedOne);


Graphical Language Forms 

These forms of graphics are described via line drawing operators, fill and stroke 

parameters, and text. They may also include bitmapped graphics. These forms exist 

solely in the context of a standard language definition (e.g. PDF: Portable Document 

Format; CGM: Computer Graphics Metafile; WMF: Windows Metafile Format; 

QuickDraw drawing commands; etc.). 

Image Creation Methods 

With the exception of PDF, for which this package is eminently suitable, all of the 

graphic forms must be converted into a stream of line drawing, imaging and text 

drawing commands before being used as an image. 

DLI supports creating graphical images from a range of sources via the following 

methods:


dlpdfimagecreatefrombmp 

This method creates a DLPDFIMAGE from a bitmap and user-supplied information. 


• Its first parameter is the document of which the image is to be a part. 

• Its second parameter is a name to be used to identify this image. 

• Its third and fourth parameters are pointers to an array of bytes containing the 

bitmap and the length of that bitmap. 

• Its fifth parameter is the length of a line in samples. 

• Its sixth parameter is the number of lines. 

• Its seventh parameter is the size of a sample. 

• The eighth parameter is a COS Object which describes the color model used for the 

image. 

• The last parameter is a flag. When TRUE, this object will be embedded in the 

document each time it is used. When FALSE, it will be embedded only once. 

NOTE: DLI will merge inline all bitmapped images under 500 bytes. However, if 

the image is equal to one bitmap, then DLI will automatically set the image as an 

imagemask. Please see “Creating Transparent Graphics” on page 11.12 

This method assumes that the bitmap is ordered into samples within lines, that the 

first line presented is the top of the image, and that the first sample presented is the 

left edge of the image. 

Order of Values within Color Models 

The type of color model will determine whether the image contains one value per 

sample (/DeviceGray or /Indexed color models), three values per sample 

(/DeviceRGB), or four values per sample (/DeviceCMYK). 

Each value is assumed to have the number of bits specified in the sample size. For 

/DeviceRGB they are assumed to be ordered Red/Green/Blue; for /DeviceCMYK 

they are assumed to be ordered Cyan/Magenta/Yellow/Black.


Image Compression and Filtering 

If the document specifies compression, the bitmap will be compressed with Flate 

compression. If the document specifies Seven-Bit Safe mode, the bitmap will be 

filtered via ASCII85 to force it into a seven bit safe data format. 

dlpdfimagecreatefromps 

This method will create a EPS pass-through object in the PDF document. The EPS 

graphic is carried in the document, but not imaged by the document reader. Extracting 

the document to PostScript will include the object, and it will display in PostScript. 

This option is not generally used, but may be needed on occasion. 

This method assumes that the text of the EPS object is present as a string in memory. 

• The first parameter is a pointer to a document in which this object is to be created. 

• The second is a name to be given to this graphic. 

• The third and fourth are pointers to a string containing the EPS text and the length 

of that string. 

• The last parameter is a flag. If it is FALSE, this object will be inserted into the 

document only once. If it is TRUE, it will be inserted once for each usage. 

This segment of the complete graphics example inserts an EPS pass-through object, 

which will display a graphic in the PostScript produced from PDF, but not in the PDF 

document itself:


Inserting a EPS Image with dlpdfimagecreatefromps 

/* Open read the bitmap, and close the PostScript file */ 

ImageFile = fopen ("Image.eps", "rb"); 

fseek (ImageFile, Concepts 0, and SEEK_END); Facilities: Guide to the DL Pager Composition System 

ImageSize = ftell (ImageFile); 

fseek (ImageFile, 0, SEEK_SET); 

/* Allocate memory to hold the image */ 

ImageString = malloc (ImageSize); 

fread (ImageString, 1, ImageSize, ImageFile); 

fclose (ImageFile); 

Image = dlpdfimagecreatefromps (Doc, "Grid", ImageString, 

ImageSize, FALSE); 


* red box */ 




0, fixedOne, fixedOne); 

dlpdfimagecreatefrompdf 

This method will create an image from a PDF file. The image will be of a single 

specified page of the image document. 

• The first parameter is a handle for the document in which this image is to be placed. 

• The second is the name of the file containing the PDF image page. 

• The third and fourth are ASFixed values giving the desired width and depth of the 

image. If either is 0, the PDF page's crop box is used to form the DLPDFIMAGE's 

visible region. 

• The fifth and sixth are ASFixed values giving the offset within the image 

document at which the image should be displayed, relative to the position at which 

the image page is set. 

• The last parameter is an integer which is used as a page number (starting from 1) to 

access the image document and to select the image page displayed. 

This segment of the complete DLI Graphics example inserts a PDF image into the 

document:


Inserting a PDF Image with dlpdfimagecreatefrompdf 

/* Open the file and obtain the bounding box of page 0 */ 

{ 

PDDoc 

pdDoc; 

PDPage 

pdPage; 

ASFixedRect 

BB; 

/* Open the document */ 

pdDoc = PDDocOpen ("Image.pdf", NULL, NULL, TRUE); 

pdPage = PDDocAcquirePage (pdDoc, 0); 

PDPageGetBBox (pdPage, &BB); 

PDPageRelease (pdPage); 

PDDocClose (pdDoc); 

Image = dlpdfimagecreatefrompdf (Doc, "Image.pdf", 

BB.right - BB.left, 

BB.top - BB.bottom,BB.left,BB.bottom,1); 


* red box */ 





}


dlpdfimagecreatefromfile 

This method invokes various conversion routines to allow a user to simply specify the 


file name and obtain a valid DLPDFIMAGE object. All conversions are done internally 

to DLI. 

NOTE: The public-domain graphic-conversion libraries used on Unix and Windows 

are not available on OS/390 and OS/400 platforms. Consequently some image 

creation procedures are not available under OS/390 and OS/400. 

This method accepts only 2 parameters: 

• a handle to a document in which the image is to be placed 

• a file name which should contain the image 

Currently, this method will support JPEG/JPG, GIF, TIFF, PNG and PDF files on the 

NT and UNIX platforms, and PDF only on OS/390. 

From the complete DLI sample of inserting graphic images, this segment inserts a PDF 

image via dlpdfimagecreatefromfile: 

"C" Example: Inserting a PDF image with dlpdfimagecreatefromfile 

Image = dlpdfimagecreatefromfile (Doc, "math.pdf"); 


* red box */ 





The DLPDFIMAGE objects contains an ASFixedRect object called BBox (Bounding 

Box), which is set to the actual size and displacement of the image, as defined by its 

originator. This may be used in decisions about positioning and scaling the image.



Some applications have difficulty parsing PDF Form XObjects within pages as well as 

marked content blocks. Additionally, some applications are known to misinterpret 

marked content blocks between different versions of the application. The default 

action of DLI is to create a Form XObject for each imported PDF graphic, so that it 

may be referenced repeatedly without inflating the size of the resulting output file. 

This call will flag an imported PDF graphic file to have any marked content tags 

removed, and to be set into the current page's content stream instead of as a form 

reference. 

NOTE: This call may increase the size of PDF files where a graphical object is 

referenced repeatedly, as the PDF graphic is appended to the content stream at the 

point of insertion. 

LoadGraphicList 

This method is available on OS/390 only. It reads a cross-reference file which maps 

graphics keys to their physical location. The cross-reference table is accessed by the 

GetGraphicFromList method and, once read, is stored in memory for the duration 

of the job. The cross-reference file must be created without line numbers. The OS/390 

distribution includes a sample cross-reference in 

ADOBE.PDFLIB.RESOURCE.GRPHLIST(GRPIDX): 

Pic1 ADOBE.PDFLIB.RESOURCE.IMAGE.PDF 

Pic2 ADOBE.PDFLIB.RESOURCE.DLLOGO.PDF


The parameter containing the graphic list file name is the DDName of the crossreference 

file, as in: 


LoadGraphicList(“graphics”); 

with the associated JCL line: 

//GRAPHICS DD 

DSN=ADOBE.PDFLIB.RESOURCE.GRPHLIST(GRPIDX),DISP=SHR 

GetGraphicFromList 

This method is available on OS/390 only. It accepts a DLPDFDOC pointer and graphic 

key string, and returns the appropriate DLPDFIMAGE pointer. Multiple usage of the 

same graphic key within a document is tracked by DLI, resulting in only one instance 

of the graphic being placed in the document. 

NOTE: The graphic key must be passed as an ASCII string. 

Creating Transparent Graphics 

A PDF file may contain imagemasks. These are images which are used to mask, or 

block, the painting of areas beneath the mask, in the manner of a stencil. Imagemasks 

are one-bit graphics, where a value of 0 means that the pixel beneath the image is not 

to show through, and a value of 1 means that the pixel beneath is visible. 

DLI will automatically set any bitmap image created with the 

dlpdfimagecreatefrombmp function, having one bit per pixel and no color space 

(a CosNull object for the ColorSpace parameter), to be an imagemask. The mask 

will paint marked regions with the current fill color, and will leave unmarked regions 

untouched; page marks below these regions will be visible and not painted over. 

To change an image into a mask, simply insert the Imagemask key, with the value of 

TRUE as a Boolean, into the image’s dictionary. Then, remove the ColorSpace key


from the image's dictionary. (This can be accomplished through the cosImage 

member of the DLPDFIMAGE structure.) If the imagemask is to be placed over an 

image, it need not be the same size or resolution as any of the images it masks; in fact, 

the use of an imagemask of significantly higher resolution than the image to be 

masked is a useful way to simulate gradations of transparency. 

Transparent Graphics via Imagemasks Sample 

In an accompanying /codesamples folder you should find a sample file entitled 

creating transparent graphics using imagemasks.txt. This 

demonstrates how to create a mask from a suitable graphic which is approximately 11 

times as wide and high as the image to be masked. 

NOTE: The files in the /Codesamples folder are not intended to be buildable 

source as-is, only to be demonstrations of correct command syntax for different 

purposes. 

dlpdfcontentgstate 

This method enables a user to set a graphics state in a PDF file, for graphics 

operations which normally have no such state associated with them. 

For example, when creating an imagemask to create a green mask, an appropriate 

color and colorspace must be specified. Thus dlpdfcontentgstate is called to set 

the graphics state of the specified DLPDFCONTENT to that of the PDEGraphicState. 

This may be done at any point during content placement operations.



12 

Color 

and its Use 

This chapter discusses Adobe PDF Library color 

descriptions, colors in images, patterned color spaces, 

creating and destroying color spaces, and more. 

12.1


Library Color Descriptions 


Color can be added to pages produced via DLI only with the color fields of the 

PDEGraphicState. There are two fields which establish color: 

• strokeColorSpec 

• fillColorSpec 

strokeColorSpec defines the color that applied to lines which are stroked and 

fillColorSpec defines the color applied to areas which are filled. 

NOTE: Type is generally filled rather than stroked. 

Color Description Components 

The color description consists of two components: 

• The first is a pointer to a PDEColorSpace structure, which describes a color 

space. This identifies the type of color: Black and White, RGB, CMYK, etc. 

• The second component is an array of from one to seven ASFixed values, which 

describe the amount of color in each of the components of the given color model. 

These components are frequently called color channels. For example, the color 

Black can be described variously as (RGB, 0.0, 0.0, 0.0), (grayScale, 

0.0) or (CMYK 0.0, 0.0, 0.0, 1.0); all are different ways of saying 

“Black.” 

Patterned Colors 

Patterned colors, which may be used in addition to (or instead of) a solid color, are 

carried in a separate field within the DLPDFCONTENT structure, and are set with a 

specific set of calls to DLPDFCONTENT.

Color and its Use 12.3 

Colors in Images 

Color spaces may also be used separately with images if those images are bitmaps. A 

color model must be specified as a CosStructure when using 

dlpdfimagecreatefrombmp. The CosObj form of a color is obtained from the 

PDE form by the call PDEColorSpaceGetCosObj. Creating the PDE form is 

explained below. 

When images are created with any of the other dlpdfimagecreate-type calls, color 

spaces will be constructed as needed. 

Creating and Destroying Color Spaces 

For the basic colors, the color spaces used in your document will be in the form of a 

PDEColorSpace. This is not a document object, and therefore can be shared 

between documents. A COS form of that space will be created and inserted into each 

document where that color space is used. These color models can be created when the 

Adobe PDF Library is initialized, and should be destroyed before it is closed. 

CAUTION: If color models are not freed, a close error will result.


Color spaces for the basic colors (DeviceRGB, DeviceCMYK and DeviceGray) are 

created by a call to the Adobe PDF Library in this form: 


"C " Example: Creating a Gray Color Space 

PDEColorSpace GrayModel: 

AsAtom GrayAtom; 

GrayAtom = ASAtomFromName (“DeviceGray”); 

GrayModel = PDEColorSpaceCreateFromName (GrayAtom); 

"BAL" Example: Creating A Gray Color Space 

In Assembler for OS/390: 

GrCol @DLPDFS 

DSECT=NO, * 

STRUCT=__T_PDECOLORVALUE 

GrName ds A“GrayScale” 

GrAtom dc h’0’ 

@DLPDFC 

DLFUNC=AsAtomFromEBCDICName, 

DLPARAM=(GrName), 

DLRETURN=GrAtom 

DLPDFC 

DLFUNC=pdecolorspacecreatefromname, 

dlparam1=(GrAtom), 

DLRETURN=GrCol


Color Space Creation 

For Adobe PDF Library v4.0 and higher, all of the color spaces may be created by the 

procedure PDEColorSpaceCreate. 

NOTE: A COS object is a document object, and cannot be shared between 

documents. However, the PDEColorSpace created from a document-specific 

COS Object is not a document object, and may be shared. 

For example, to create a Calibrated Gray Scale color space, you would need the 

following code fragment: 

Creating Calgray Color Space for Adobe PDF Library v4.0 and later 

PDEColorSpace CIEGrey; 

PDEGrayCalFlt CIEGreyDesc; 

CIEGreyDesc.gamma = 0; 

CIEGreyDesc.whitePoint.x = 0.9506; 

CIEGreyDesc.whitePoint.y = 1.0; 

CIEGreyDesc.whitePoint.z = 1.0890; 

CIEGreyDEsc.blackPoint.x = 0.0; 

CIEGreyDEsc.blackPoint.y = 0.0; 

CIEGreyDesc.blakcPoint.z = 0.0; 

CIEGrey = CreateColorSpace (AsAtomFromName (“CalGray”), 

(PDEColorSpaceStruct *)&CIEGreyDesc);


Values for Color Channels 


The values specified for the color channels vary from space to space, but the most 

common values range between zero and 1. Since these values are specified to the 

Adobe PDF Library as ASFixed values, this allows 16 bits of precision. 

Value Conversion and Inversion 

Your own system may specify color internally with a greater or lesser precision, or in 

inverted values. These must be converted to the Adobe PDF Library’s view of color to 

function correctly. 

Generally, you should first correct the precision, matching it to the Adobe PDF 

Library’s 16 bit precision, then correct the inversion (if there is one) by subtracting the 

number from an ASFixed one. 

When the precision difference is a matter of powers of two (as it often is), precision is 

corrected by shifting the value to match the Adobe PDF Library’s ASFixed format; 

e.g. if you are carrying color as a value of 0-255, shifting left 8 bits will correct 

precision. 

When the color specification is not in binary, e.g. zero to 100 or zero to 1000, try 

converting via floating point numbers. You may also create a subroutine to convert 

color values in precision and direction from the source system to the Adobe PDF 

Library’s system.


Basic Color Spaces 

The Device color spaces below presume to render color as an absolute value. These 

are the basic color spaces, and are fully supported throughout PDF and PostScript. 

CIE Calibrated Color Spaces 

Calibrated color spaces are colors with perception qualifiers. These are defined by CIE 

and are intended to permit a more faithful rendition of color, given a knowledge of the 

display device characteristics. 

A full discussion of the CIE models is beyond the scope of this document, but you can 

find a great deal of information on them in the Adobe PDF Specifications document 

or the PostScript Language Reference. 

Device Gray 

This space allows you to use black and white or levels of gray. It has a single channel 

of color data, which is viewed by the imaging engine as a value between 1 (White) and 

zero (Black). 

Since the value is specified to the system as an ASFixed value, 16 bits of precision are 

possible. Generally, this will be rounded down to 4 decimal positions of precision 

when written to the PDF file. 

The atom used to create this color model is DeviceGray. It is assumed to be present 

in all levels of PDF, and does not need to be added to the resource directory as a color 

space name.


Device RGB 

This space allows you to use full color by encoding the color as three channels, one for 


each of the Radiant primary colors Red, Green and Blue. Each channel has a value 

between zero (none of this color) and 1 (highest level of this color). 

The color channels are always 

• color[0] = RED 

• color[1] = GREEN 

• color[2] = BLUE 

If your internal model uses a different sequence, you must reorder the colors when 

setting color values. 

The atom used to create an RGB color space is DeviceRGB. 

Device CMYK 

This space allows you to use full color by encoding the color as 4 channels, one for 

each of the absorbent colors Cyan, Magenta and Yellow, and a fourth channel for 

Black. Each channel has a value between zero (No Absorption) and 1 (Full 

Absorption). 

The channels are arranged as 

• color[0] = CYAN 

• color[1] = MAGENTA 

• color[2] = YELLOW 

• color[3] = BLACK 

The atom used to create a CMYK color space is DeviceCMYK. 

Calibrated Gray 

This is a calibrated color space, intended to make use of the knowledge of the display 

device’s characteristics to more accurately depict levels of gray. The values for this


color space are identical to those of device gray (i.e. zero to 1, where zero is darkest 

and 1 is lightest), but for Calibrated Gray, you must also add to the color space 

definition the conditions under which the original colors were viewed. 

This color space may not be created from PDEColorSpaceCreateFromName. 

When created via PDEColorSpaceCreate, its atom is CalGray and the color 

structure must be a PDEGrayCalFlt. 

Calibrated RGB 

This is a calibrated color space, intended to make use of the knowledge of the display 

device’s characteristics to more accurately depict colors. The values are identical to the 

DeviceRGB color channels in value and sequence. 

This color space may not be created with PDEColorSpaceCreateFromName. 

When created with PDEColorSpaceCreate, its atom is CalRGB, and the color 

structure must be a PDERGBCalFlt. 

CIE Lab 

This is a calibrated color space intended to display color. It uses three channels (L, A, 

and B) in that order: 

• The range of the L channel is always zero to 100. 

• The range of the A and B channels are specified within the color space model, but 

must always be in the range of -128 to +127. 

This color space cannot be created with PDEColorSpaceCreateFromName. When 

created with PDEColorSpaceCreate, the atom used to specify this color space is 

Lab, and the color structure must be a PDELabCalFlt.


ICC Based 

This is a color model promoted by the International Color Consortium (ICC). Its 


purpose is to encode color intent, so that this intent may be correctly realized in any 

medium. 

This color model includes a Color Profile, which specifies the number of channels in 

use, and the range and limits of those values. In essence, this is a calibrated color space 

schema, which permits grayScale, RGB, CMYK and Lab specifications within itself. 

This color model may not be created by PDEColorSpaceCreateFromName. When 

it is created by PDEColorSpaceCreate, its atom is ICCBased, and the color 

structure must be PDEICCBasedColorData.


Advanced Color Spaces 

The preceding color spaces all represent colors as a spectrum, from lighter to darker. 

The following color spaces do not do so: instead, each color is viewed as an 

individual. 

Separation 

This color space names a color, where the color value is a number between zero (none 

of this tint applied) to 1 (full tint applied). 

If the name specified in this space is known to the display device, then that tint will be 

used. If it is not known, a fallback color model will be used, and a transformation 

function from the tint amount to that fallback model’s color channel is provided in the 

model. 

This color space may not be created from PDEColorSpaceCreateFromName. 

When created by PDEColorSpaceCreate, its atom is Separation and the color 

structure used must be a PDESeparationColorData. 

DeviceN 

This color space is a generalization of the separation model. In it, an array of names is 

specified, rather than a single name. The number of color channels used by a DeviceN 

color is the number of names specified in the DeviceN name array. The value of each 

channel is from zero to 1. 

NOTE: The structure PDColorValue, used to set values for colors, permits only 

4 channels. 

This color space may not be created by PDEColorSpaceCreateFromName. When 

created by PDEColorSpaceCreate, its atom name is DeviceN, and it must use a 

color structure of PDEDeviceNColorData.


Indexed 

Indexed color spaces are most often used in images, but are by no means limited to 


images. 

An indexed color space first selects a device color space in which it will be rendered. 

This must be DeviceRGB, DeviceGray, DeviceCMYK, DeviceN or ICCBased. 

It then supplies an array of from 1 to n entries, each entry having the value of a color 

in the selected model. (For DeviceGray, there would be one entry per color; for 

DeviceRGB, three; and so on). 

Color is specified as a single channel, which must be an integer between zero and n-1. 

This value is used as an index to the array of colors, and the selected entry is imaged 

in the underlying color space. 

This color space cannot be created with PDEColorSpaceCreateFromName. When 

created with PDEColorSpaceCreate, its atom is Indexed and the color structure 

must be a PDEIndexedColorData. 

Patterned 

A patterned color space is not really a color space at all. Rather, it is an image which 

will fill or stroke an area or line. It may contain colors of its own, or it may be a 

black-and-white image which is colored per the underlying color space. 

Any valid PDF marking commands may be used to construct the pattern image. The 

image itself is constructed as a rectangular space, which is overlaid on the area being 

filled or stroked. Specification of how far apart each tile is to be placed (horizontally 

and vertically) permits the appearance of non-rectangular areas. 

DLI contains an interface (dlpdfpatterncreate) which will accept a container 

and convert it into a patterned color space. This space may then be used within a 

container via the interface’s dlpdfcontentusefillpattern or 

dlpdfcontentusestrokepattern methods.


Building Patterned Color Spaces 

DLI permits patterned color spaces to be easily defined and used. 

A patterned color space is created by marking a container, exactly as if writing text, 

then converting that container into a patterned color space. It is used by instructing 

the container in which marks are made to use a particular patterned color space for 

filling or stroking. 

For example, to make a patterned color space like this: 

1 Define one tile of the angled line, by creating a content area and drawing that line 

in that area. 

2 Create a pattern of that tile with dlpdfpatterncreate. 

3 Set the current container fill pattern to that pattern via 

dlpdfcontentusefillpattern. 

For example, the following code fragment can be used to build patterned color spaces:


"C" Example: Filling An Area With A Pattern 

DLPDFPATTERN 

*Pattern; 

DLPDFCONTENT 

*PatContent, *PageCont; 

PDGraphicState Concepts and State; Facilities: Guide to the DL Pager Composition System 

ASFixedMatrix Matrix; 

ASFixedRect BBox; 

/* Initialize the graphics state */ 

State.strokeColorSpec.space = State.fillColorSpec.space = 

PDEColorSpaceCreateFromName(ASAtomFromString("DeviceGray")); 

State.strokeColorSpec.value.color[0] = 

State.strokeColorSpec.value.color[0] = 0; 

State->GState.miterLimit = fixedTen; 

State->GState.flatness = fixedOne; 

State->GState.lineWidth = fixedTwo; 

/* Draw the pattern “tile” */ 

PatContent = dlpdfcontentcreate (Doc); 

dlpdfcontentline (PatContent, &State, kPDEStroke, 

0, 0, fixedTen + fixedTwo, fixedTen + fixedTwo); 

BBox.left = BBox.bottom = 0; 

BBox.right = BBox.top = fixedTen + fixedTwo; 

Matrix.a = Matrix.d = fixedTwo / 3; 

Matrix.b = Matrix.c = Matrix.h = Matrix.v = 0; 

Pattern = dlpdfpatterncreate (Doc, PatContent, &BBox, &Matrix, 

FALSE, 1, BBox.right - fixedTwo, BBox.top - fixedTwo); 

/* Set this pattern as the fill pattern */ 

dlpdfcontentusefillpattern (PageCont, Pattern); 

/* Draw and fill the structure */ 

... 

/* Cancel the fill pattern */ 

dlpdfcontentusefillpattern (PageCont, NULL); 

NOTE: A fill pattern is never destroyed. It becomes a part of the document, and 

the space used to define the pattern will be freed automatically when the 

document is freed. 

Repeating Pattern References 

Most often, you will want to create a repertoire of fill patterns that matches the 

capabilities of your existing composition engine or of the display devices you have


been using prior to PDF. If you do this, and save the pointers to the patterns in a 

findable manner, then the patterns can be used repeatedly throughout a document. 

Note that they are specific to a document, however, so you may not share them 

between documents.


Conversion between Models 


On some occasions, it is useful to be able to convert color values between color 

spaces. This does not occur often, as most composition engines permit only a single 

definition of color, but you may occasionally, for example, need to collapse colors to 

fewer models, such as when using grayscale in place of RGB when the color selected is 

a gray. 

The folowing examples assume a gray image encoded as RGB or CMYK. 

Collapsing RGB to Gray 

If all three channels of the RGB color are the same value, then the color specified is a 

gray. It may be simulated in gray by using that value as the gray color value. 

"C" Example: Collapsing RGB to Gray 

if (State->fillColorSpec.space) == GlobalRGBSpace) 

{ 

if ((State->fillColorSpec.value.color[1] == 

State->fillColorSpec.value.color[2]) && 

(State->fillColorSpec.value.color[2] == 

State->fillColorSpec.value.color[3])) 

{ 

State->fillColorSpec.Space = GlobalGraySpace; 

} 

} 

Collapsing CMYK To Gray 

If the first three channels of the CMYK color are the same, then the color is gray. The 

amount is 1 minus the sum of one of the first three channels, plus the fourth channel. 

If this is less than zero, then the amount is zero.


"C" Example: Collapsing CMYK to Gray 

if (State->fillColorSpec.space) == GlobalCMYKSpace) 

{ 

if ((State->fillColorSpec.value.color[1] == 

State->fillColorSpec.value.color[2]) && 

(State->fillColorSpec.value.color[2] == 

State->fillColorSpec.value.color[3])) 

{ 

State->fillColorSpec.Space = GlobalGraySpace; 

State->fillColorSpec.value.color[0] = 

(fixedOne - (State->fillColorSpec.value.color[0] + 

State->fillColorSpec.value.color[3])); 

if (State->fillColorSpec.value[0] < 0) 

State->fillColorSpec.Value[0] = 0; 

} 

} 

Converting RGB to CMYK 

RGB and CMY are complements, so we can turn one to the other by subtracting the 

value from 1. However, the “K” component of CMYK (Black) is present to enhance 

the distribution of ink on a printer, and should be maintained correctly across such 

conversions. 

In converting RGB to CMYK, we complement each of the channels, then identify the 

smallest of the three values, subtract it from each channel, and use it as the value for 

channel 4.


"C" Example: Converting RGB to CMYK 

if (State->fillColorSpec.space) == GlobalRGBSpace) 

{ 

State->fillColorSpec.space Concepts and Facilities: = Guide GlobalCMYKSpace; 

to the DL Pager Composition System 

State->fillColorSpec.value.color[3] = fixedOne; 

for (i = 0; i < 3; i++) 

{ 

State=>fillColorSpec.value.color[i] = 

fixedOne - State->fillColorSpec.value.color[i]; 

if (State->fillColorSpec.value.color[i] < 

State->fillColorSpec.value.color[3]) 

{ 

State->fillColorSpec.value.color[3] = 

State->fillColorSpec.value.color[i]; 

} 

} 

for (i = 0; i < 3; i++) 

State->fillColorSpec.value.color[i] -= 

State->fillColorSpec.value.color[3]; 

} 

Converting CMYK to RGB 

Very similar to conversion of RGB to CMYK, of course. 

"C" Example: Converting CMYK to RGB 

if (State->fillColorSpec.space) == GlobalCMYKSpace) 

{ 

State->fillColorSpec.space = GlobalRGBSpace; 

for (i = 0; i < 3; i++) 

State->fillColorSpec.value.color[i] += 

State->fillColorSpec.value.color[3]; 

for (i = 0; i < 3; i++) 

{ 

State=>fillColorSpec.value.color[i] = 

fixedOne - State->fillColorSpec.value.color[i]; 

if (State->fillColorSpec.value.color[i] < 0) 

State->fillColorSpec.value.color[i] = 0; 

} 

}

13 

Annotations 

and Links 

Annotations are structures within the PDF document, as 

children or subordinate structures to a page, which 

permit special actions to be initiated by the user. DLI 

supports the creation of text annotations and link 

annotations within the document. 

13.1


Overview 


Pages may contain text annotations, which are notes appended to the document, and 

link annotations, which indicate that an area of the page (always a rectangular area) 

connects to another area of this or another document. Links to external documents 

must be supported externally to this package. 

The methods used for creation of annotations return the CosObj which is the 

annotation. This object need not be picked up by the application, and does not need 

to be deallocated by the application. 

Modifying for Other Actions 

The objects may be modified, either immediately after creation or at any time prior to 

writing the document, to permit access to functionalities beyond those described in 

these method interfaces. There are fourteen or more different annotation types, and 

not all are represented by DLI methods, so in some circumstances you will need to 

create an object as one type, but then modify it to be another. 

Therefore, if you plan to change the annotations to perform other actions, you must 

make your changes before the document is released from the resources. See following 

sections of this chapter for further details. 

Annotation Components 

All annotations consist of two parts: a hot spot, which is defined as a rectangular area 

of the page, and an action. 

Hot Spots 

The hot spot can be defined as an ASFixedRectangle, or as a reference to a name 

contained in a special Name Tree within the document.

Annotations and Links 13.3 

Actions 

Actions can be specified in a number of ways, depending on the complexity of the 

action. 

DLI directly supports the most basic forms of annotations, and returns the created 

CosObj for all annotations, so that your application can easily construct more 

complex forms by modifying the basic forms provided here. 

Borders 

Borders may be placed around an annotation hot spot to highlight it to the user. Prior 

to version v4.0, the Adobe PDF Library allowed a definition of a border as an array 

of three ASFixed values: 

• Horizontal Corner Radius 

• Overcall Corner Radius 

• Border Width 

When Border Width is zero, the border is not drawn. 

DLI directly supports this definition only. In the following methods, a reference to 

borders is presumably to a NULL pointer, in which case the border is omitted, or a 

pointer to an array of three ASFixed values, interpreted as above. 

Annotation and Link Colors 

Color has a different meaning for each type of annotation: 

• For text annotations, it is the color to be used for the background of the closed 

annotation. 

• For links, it is the border color. 

Prior to v4.0 of the Adobe PDF Library, colors could be specified only as an array of 

three ASFixed values, representing an RGB color. When used below, color means a 

pointer to such an array, or NULL. If NULL, then the viewer will select a color.


dlpdfpageaddtextannotation 

The simplest annotation in PDF is a text annotation. This appears as a “sticky note” 


in Adobe Acrobat or Adobe Reader and can be opened to display a text message. 

• The first parameter is a pointer to the page which will contain this annotation. 

• The second parameter is a pointer to an ASFixedRectangle whose upper left 

corner will be the upper left corner of the closed annotation. 

• The third is a pointer to a border specification. 

• The fourth is a pointer to a color specification. 

• The fifth is a pointer to a string, which will be used as a title of the opened 

annotation. This may be a NULL pointer. 

• The sixth parameter is a pointer to a string which is the content of this annotation. 

If this is a NULL pointer, the method will raise an exception (genErrBadParm). 

• Finally, the seventh parameter is a flag. If TRUE, then this annotation will be open 

when first displayed. If FALSE, it will be closed. 

From the full example of creating annotations: 

"C" Example: Creating Text Annotations 

DLPDFDOC *Doc; 

DLPDFPAGE *Page1, *Page2; 

ASFixedRect NoteRect; 

ASFixed Border[3], Color[3]; 

dlpdfpageaddtextannotation (Page1, &NoteRect, Border, 

Color, "Page 1 Note", 

"This is a closed note placed on page one", FALSE); 

dlpdfpageaddtextannotation (Page2, &NoteRect, Border, 

Color, "Page 2 Note", 

"This is an open note placed on page Two", TRUE); 

dlpdfpageaddlinkannotation 

This is the most frequently used annotation. It links an area of the page which 

contains this annotation to a separate area on that or another page. The viewer uses


these links, when selected, to modify the view of the document to display the 

destination area. 

This method assumes that the destination will be specified as a page number, an 

ASFixedRectangle describing a portion of that destination page, and a 

FitDescription, saying how the portion of the page should be displayed. 

• The first 4 parameters of this method are identical to the text annotation above, 

except that the ASFixedRectangle is used for both location and size, and defines 

the hot spot where the user might select this link. 

• The fifth parameter is the page number of the destination page. The first page is 

considered to be page 0. The page referenced need not have been created yet. 

• The sixth parameter is the FitType. This is a text string which is one of the set of 

“XYZ”, “Fit”, “FitH’, “FitV”, “FitR”, “FitB”, “FitBH”, or “FitBV”. The 

meanings of these various types can be seen in the Adobe PDF Library Reference 

Guide, or the PDF Specification, section 7.3.1. 

• The seventh parameter defines a rectangle which will be fitted according to the 

sixth parameter. In general, this should describe the extent of the text that you want 

the user to see when selecting this link. The values actually used will vary with the 

FitType specified. 

• The eighth parameter is a zoom amount, used only with fit type “XYZ”. It is an 

ASFixed value, where 1.0 is no zoom, 2.0 is double size, and 0.5 is 1/2 size. If 

you want the view to remain unchanged, set this value to PDViewDestNull.


From the full example of creating annotations: 

"C" Example: Creating Concepts A Link and Annotation Facilities: Guide to the DL Pager Composition System 

DLPDFPAGE *Page1 

ASFixedRect BBLink1, PageRect; 


/* Set up the border and color arrays */ 

Border[0] = Border[1] = 0; /* This is a square box */ 

Border[2] = fixedTwo; /* Two points in thickness */ 

Color[0] = Color[2] = 0; /* Its color will be blue */ 

Color[1] = fixedOne; 

dlpdfpageaddlinkannotation (Page1, &BBLink1, Border, 

Color, 1, "Fit", &PageRect, PDViewDestNULL); 

dlpdfpageaddlinkannotationfromname 

An optional structure within the PDF document is a name tree. This consists of an 

ordered collection of strings (names) and a value for each name, which is an array in 

the form defined in the PDF Specification, section 7.3.1. The named destination itself 

is described in sections 7.3.2 and 6.9. 

In the Adobe PDF Library, only the DEST name tree may be defined, and within DLI, 

there is direct support only for the name tree. Names may be added to the name tree 

via dlpdfdocnameadd. 

Names vs. Destinations 

A link may be accomplished using a name, rather than a specific destination. When 

cross-document links are to be used, referring to a name permits a more flexible 

linkage: if the document referred to is modified, you need not recompose the referring 

documents. 

In practice, this means that you would need to create a name tree which names all of 

the possible interesting sites for a link, and publish the names of those sites to 

potential linking documents. These names should be derived directly from the text, to


identify them by their relevance to the context, rather than their position within the 

document. 

For example, you might create a name of "Maintaining Backup Files," rather than 

"Chapter 2," using the text of the title rather than its sequential position, so you can 

preserve the link even if the document chapters are later reorganized. 

This method is intended to permit linkages by names within a document. Making a 

link between documents is fairly straightforward: 

• The first 4 parameters are the same as the previous two methods. 

• The fifth parameter is a string giving the name of the destination. 

From the full example of adding annotations: 

"C" Example: Creating A Link To A Named Destination 

DLPDFPAGE *Page2 

ASFixedRect BBLink2; 


Border[0] = fixedFive; /* A box with elliptical corners */ 

Border[1] = fixedTen; /* longer horizontal than vert. */ 

Border[2] = fixedTwo; /* Two points in thickness */ 

Color[0] = Color[2] = 0; /* Its color will be black */ 

Color[1] = 0; 

dlpdfpageaddlinkannotationfromname (Page2, &BBLink2, 

Border, Color, "Link1"); 

dlpdfpageaddwebannotation 

This procedure supports adding a link structure which is identical in appearance to a 

link annotation, but which references a URI (Uniform Resource Indicator, equivalent 

to a URL) passed as the last character string. This method is used to place hyperlinks 

to external documents, on the World Wide Web for example, within a PDF document. 

NOTE: You should have your internet browser running before calling this 

procedure or you may receive a “browser is busy” error. Your browser can be 

specified in Acrobat via File->Preferences->Weblink.


dlpdfdocnameadd 

This method allows the user to add one destination to the name tree structure, the 


optional ordered list of names and destinations. 

The method accepts four parameters: 

• The first is a handle for the document in which the name is to reside. 

• The second is a string representing the tree name (can be NULL). 

• The third is a string containing the destination name. 

• The fourth is a COS structure, which must be an array with contents as described in 

the PDF Specification, section 7.3.1. 

"C" Example: Creating A Named Destination 

/* Create a Destination structure to fit a given rectangle to 

* the viewer window */ 

Dest = CosNewarray (Doc, TRUE, 6); 

CosArrayPut (Dest, 0, Page); /* The current page */ 

CosArrayPut (Dest, 1, CosNewName (Doc, FALSE, 

ASAtomFromString (“FitR”))); 

CosArrayPut (Dest, 2, CosNewFixed (Doc, FALSE, Left)); 

CosArrayPut (Dest, 3, CosNewFixed (Doc, FALSE, Bottom)); 

CosArrayPut (Dest, 4, CosNewFixed (Doc, FALSE, Right)); 

CosArrayPut (Dest, 5, CosNewFixed (Doc, FALSE, Top)); 

dlpdfdocnameadd (Doc, "Name Tree", "Destination Name", 

Dest); 

dlpdfdocnamefind 

This method will return the Cos structure associated with a destination name. If that 

name does not exist, a CosNull structure will be returned. 

The method accepts two parameters: 

• a document handle 

• a string containing the desired name


Modifying the Link Cos Object 

Each of the three methods which create an annotation return a CosObj. This 

structure is the annotation dictionary, and may be modified freely. In practice, it is the 

link annotation that will most often be modified. 

As created by DLI, the link annotation dictionary will contain the following key/value 

pairs: 

• Type Annot 

• SubType Link 

• Rect [x, y, x+wide, y+depth] 

• Border [v1, v2, v3] (if Border is not NULL) 

• Color [r, g, b] (if Color is not NULL) 

• Dest [...], where the destination is described in the array 

This will create a link whose action is defaulted to “GoTo.” 

Although "GoTo" is the normal state for a link within a document, there are 13 

possible actions for selecting a link permitted in PDF Specification 1.2, and a 

fourteenth added in PDF Specification 1.3. More may be added in the future. 

In order to modify this link to use one of the other actions, you must replace the Dest 

couplet with an A key and an action dictionary: 

1 The Dest couplet is removed, using 

CosDictRemove(Dict, ASAtomFromString (“Dest”));. 

2 The action dictionary is created, always as a new, indirect, dictionary structure. It 

has a Type of Action, a SubType of the action desired (See PDF Specification, 

section 6.8), and additional parameters depending on the action selected. 

The following is extracted from the full example of creating annotations:


"C" Example: Modifying a Goto Link into a GotoR Link 

/* Create a link to another document */ 

local_inserttext (Doc, Content1, &gState, 

"Link Concepts to Line and Drawing Facilities: Sample", Guide to fixedFour the DL Pager * 72, Composition System 

fixedEight * 72, &BBLink3); 

CosLink3 = dlpdfpageaddlinkannotation (Page1, &BBLink3, 

Border, Color, 0, "XYZ", &BBLink3, PDViewDestNULL); 

CosDictRemove (CosLink3, ASAtomFromString ("Dest")); 

Action = CosNewDict (Doc->cosDoc, TRUE, 3); 

CosDictPut (CosLink3, ASAtomFromString ("A"), Action); 

CosDictPut (Action, ASAtomFromString ("Type"), 

CosNewName (Doc->cosDoc, FALSE, 

ASAtomFromString ("Action"))); 

CosDictPut (Action, ASAtomFromString ("S"), 

CosNewName (Doc->cosDoc, FALSE, 

ASAtomFromString ("GoToR"))); 

Dest = CosNewArray (Doc->cosDoc, FALSE, 2); 

CosArrayPut (Dest, 0, CosNewInteger (Doc->cosDoc, 

FALSE, 0)); 

CosArrayPut (Dest, 1, CosNewName (Doc->cosDoc, FALSE, 

ASAtomFromString ("Fit"))); 

CosDictPut (Action, ASAtomFromString ("D"),Dest); 

CosDictPut (Action, ASAtomFromString ("F"), 

CosNewString (Doc->cosDoc, FALSE, 

"ExampleDraw1.pdf", 16));

14 

Bookmark 

Creation 

Bookmarks, or an outline tree, are used to help the 

reader navigate a document. In essence, they form a 

Table of Contents for a document. They are displayed on 

a collapsible navigation pane adjacent to the window in 

which the document body is displayed when using Adobe 

Acrobat or Adobe Reader. 

14.1


Overview 


You are not limited to a single tree of contents which matches your document. You 

may build multiple trees within the outline tree, and you may order material 

differently than the way it is ordered in the document. You may use bookmarks to 

point out and highlight material in any way that you believe to be useful to a reader of 

your document. 

The outline tree itself must be a single tree, with a single root node. DLI will handle 

the mechanics of constructing the actual tree, allowing you to be concerned only with 

its content. 

DLI represents the outline tree as a collection of DLPDFOUTLINE structures. These 

have a number of properties, in addition to a pointer to the COS structure which this 

structure represents. The collection of such structures is the property of a single given 

document, and will be destroyed when that document is destroyed.

Bookmark Creation 14.3 

dlpdfdocoutlineadd 

This method adds a new outline entry to the document: 

• The first parameter specifies the document in which it is to reside. 

• The second, if not NULL, is the handle of a parent structure. 

• The third, if not NULL, is the desired younger sibling (if NULL, it will be added as 

the last child of that parent). 

• The fourth parameter is required and is the text that will be displayed for this 

outline entry. 

• The fifth is a flag. If TRUE, the entry will be displayed initially as open (its children 

will be displayed). If FALSE, it will be displayed initially as closed. 

The following parameters describe a location which is to be displayed if this entry is 

selected. 

• First is a page number (the first page is zero) 

• Second is a FitType, a text string, as defined in the PDF Specification, section 

6.8.1. 

• Third is an ASFixed Rectangle, describing a location of the page to be 

displayed 

• Last is a zoom factor, indicating how much the size of the display should increase or 

decrease. (PDViewDestNull indicates “Do not change.”) 

These last 4 parameters are identical to the destination specifications for links, in the 

previous section.


From the full example on creating annotations, this segment shows the creation of an 

outline entry: 


"C" Example: Adding Outline Entries 

RootBookMark = dlpdfdocoutlineadd (Doc, NULL, NULL, 

"All Pages", TRUE, 0, "Fit", &PageRect, PDViewDestNULL); 

/* An annotation for each page, linking to display 

* entire page */ 

Page1BookMark = dlpdfdocoutlineadd (Doc, RootBookMark, NULL, 

"Page 1", FALSE, 0, "Fit", &PageRect, PDViewDestNULL); 

dlpdfdocoutlineaddfromname 

This method is the same as the previous in its action and in its first 4 parameters. It 

differs in that the destination is specified as a text string, a name in the destination 

dictionary of the document. (See the previous section for adding names and 

description of the use of name.) 

The following is an extract from the full example on annotations: 

"C" Example: Adding an Outline with a Named Destination 

dlpdfdocoutlineaddfromname (Doc, Page1BookMark, NULL, 

"Link to 2", FALSE, "Link1"); 

Each time you create a DLPDFOUTLINE, a pointer to that structure is returned. You 

may keep these pointers in your own data structures as an aid in building the 

document tree, or you may navigate the existing structure using the following 

methods. 

dlpdfdocoutline 

This method accepts a document handle, and returns the handle of the root outline 

node. If there are no outlines, it will return a NULL pointer.

Bookmark Creation 14.5 

dlpdfdocoutlinefirst 

This method accepts an outline handle, and returns the handle of the first child of this 

outline. If there are no outlines, it will return a NULL pointer. 

dlpdfdocoutlinelast 

This method accepts an outline handle, and returns the last child of that outline. If 

there are no children in the outline, it returns a NULL pointer. 

dlpdfdocoutlineprev 

This method accepts an outline pointer, and returns the handle of the previous child of 

this outline entry’s parent. If there is no previous child, it returns a NULL pointer. 

dlpdfdocoutlinenext 

This method accepts an outline pointer, and returns the pointer of the next child of 

this outline entry’s parent. If there is no next child, it returns a NULL pointer. 

dlpdfdocoutlineparent 

This method accepts a pointer to an outline entry, and returns a pointer to that entry’s 

parent. If the entry is the root entry, it returns a NULL pointer. 

The DLPDFOUTLINE structure contains three fields which may be accessed, but not 

changed, by an application: 

• DLPDFOUTLINE->Open is a flag which will be TRUE if the outline entry was 

created open, FALSE if it was not. 

• DLPDFOUTLINE->Count is a count of the children of this entry. 

• DLPDFOUTLINE->Obj is a Cos Obj which is the actual entry in the outline. This 

entry is a dictionary, as described in the PDF Specification, section 6.7. It will 

always have a Dest key, never an A key. You may replace this key to obtain actions 

other than “GoTo”.


Opening the Document with Annotations Showing 

The default action on opening a document is to show only the document window and 


hide the navigation pane. To define a document that should be opened with the 

navigation pane showing, you need to add the key PageMode with the value 

UseOutlines to the document catalog structure. This is done at the Cos level as: 

"C" Example: Setting the Page Mode to Display Navigation Pane 

CosDoc cosDoc; 

CosObj Catalog; 

cosDoc = dlpdfdoccosdoc (Doc); 

Catalog = CosDocGetRoot (cosDoc); 

CosDictPut (Catalog, ASAtomFromString ("PageMode"), 

CosNewName (cosDoc, FALSE, 

ASAtomFromString ("UseOutlines")));

15 

Digital 

Signatures 

Digital Signatures are used to validate the document’s 

content and protect it against unauthorized tampering, 

viewing or modification. 

15.1


Overview 


PDF files created with DLI may include digital signatures for use in validating a 

document's contents. With a digital signature, a certificate is added to a PDF file 

containing information about the signer. An encrypted message, and the key to 

decrypt this message, are included in the certificate or the signature PDF fields. The 

message is generated by a non-reversible mathematical transform of the PDF file's 

bytes known as a hash function. A recipient of the PDF file can then decrypt this 

message. If the message matches what the recipient calculates using the hash function 

for the PDF file, the PDF file has not been altered since it was signed. If it does not 

match, the document has been changed. 

Public and Private Keys 

Digital signatures are based on public-key cryptography. In public-key cryptography, 

there are two keys, public and private: 

• A private key is used to encrypt data that only the public key can decrypt. 

• A public key may encrypt data that only the private key can decrypt. 

This allows you, the document creator, to distribute a public key freely, and to encrypt 

a message with your private key (which must be kept secret). The reader can decrypt a 

message, but cannot re-encrypt the message in the same way that you encrypted it 

when you signed it. This prevents the reader from pretending to be the document 

author. 

Digital signatures also serve the purpose of non-repudiation. Since only the author can 

sign a document, a valid signature means that only the author of the document could

Digital Signatures 15.3 

have signed the PDF file. This makes digital signatures useful for contracts or other 

archival legal documents. 

A digital signature in a PDF file has two important parts: 

• the certificate 

• a series of DLPDFFORM objects which form a visible indicator that a document is 

signed 

The certificate is supplied to DLI and contains information such as the signer's name, 

their location, and a signature to validate the certificate. 

Certificates are accepted in PKCS #7 format and in x.509 format. For PKCS #7 

format, the calling application must be able to supply a fully-formed certificate, 

complete with the signed PDF document hash (supplied by DLI); for an x.509 

certificate, the hash value is calculated by DLI and supplied to the application 

through a callback routine for signing. This is for security purposes; calling 

applications should use secure memory routines when signing the PDF document. 

The appearance of the signature is optional; if it is not set, an invisible digital 

signature will be added to the PDF file created by DLI. It consists of several layers: 

• a background layer 

• a layer displayed before the signature is validated 

• a layer for the graphical signature representation (such as a scan of a handwritten 

signature or signature stamp) 

• a layer containing information about the signature 

Any of these layers may be omitted; if so, an empty layer is created by DLI for the 

signature.


Digital Signature Calls 


dlpdfdoccreatesignature 

This call creates a digital signature object for the DLI document being created. The 

sigType value is one of: 

dlpdfsigacrox509 (Adobe self-sign plug-in compatible with an x.509 v3 

certificate) 

dlpdfsigacropkcs7 (Adobe self-sign plug-in compatible with a PKCS #7 

certificate) 

dlpdfsigverisign (VeriSign signature plug-in compatible with a PKCS #7 

certificate) 

The nameStr, reasonStr and locationStr arguments are ASCII strings 

representing the signatory's name, the reason for signing (such as an initial release or a 

document revision), and the location of the signatory respectively. This information is 

stored outside of the certificate and is optional. 


This call sets the appearance layers for the digital signature to the supplied 

DLPDFFORM values: 

• The background layer is the bottommost layer of the digital signature 

appearance. 

• The unverified layer is displayed when the signature has not been verified. 

• The signature layer is a graphical representation of the signature itself (such as a 

scanned handwritten signature). 

• The textSigInfo layer is used to display information about the signature and the 

signatory. 

This call is optional. For an invisible digital signature, do not call this function. All the 

signature layers are also optional. Blank layers will be used for any omitted signature 

appearance layers. These forms are placed at the origin of the DLI page.

Digital Signatures 15.5 


This call associates an x.509 v3 certificate with a DLPDFSIGNATURE object created as 

a dlpdfsigacrox509-certificate digital signature. Do not call this with a 

DLPDFSIGNATURE object created as a different certificate type. 

The certificate is passed as a binary buffer in the certificate parameter; DLI will read 

certLen bytes from this buffer and make a copy for the PDF file's digital signature. 

The last parameter is a required callback function, to be called during the 

dlpdfdocwritepdf function call. It will be passed a character string containing the 

SHA-1 hash for the PDF file being written, as a NULL-terminated string of 

hexadecimal digits using PKCS #1 padding, containing a BER OID (object identifier) 

for the SHA-1 algorithm. The buffer is 256 bytes long (not including the NULL 

terminator), and formatted as 

0001FFFF .. FF003021300906052B0E03021A05000414 

[ 40 hex digits for SHA-1 hash ] 

The callback function must encrypt this hash value with the private key corresponding 

to the public key in the signature's x.509 certificate, and fill the buffer passed in with 

256 hexadecimal digits representing the encrypted value for the supplied BER 

formatted hash. A 1024-bit key is used for encryption operations. 

NOTE: The signed hash will not have padding, and must be exactly 256 

hexadecimal digits. If necessary, use zeros to pad it to the required length. 


This function sets the certificate generation callback for DLPDFSIGNATUREs of type 

dlpdfsigacropkcs7 and dlpdfsigverisign. For these signature types, the 

application using DLI is required to generated a fully-formed PKCS #7 certificate 

with an MD5 checksum of the PDF document, encrypted with the private key


corresponding to the public key in the certificate. The RSA public-key algorithm with 

a 1024-bit key length is used. 


The genPKCS7Cert callback is called by DLI during the dlpdfdocwritepdf 

function call. The callback is supplied a binary data buffer of length maxLen. The 

first 16 bytes of this buffer contain the MD5 checksum (in binary) for the PDF 

document to sign. The callback must generate a PKCS #7 certificate as described 

above, and fill the data buffer with the certificate, in binary. The callback function 

must return the length to read from the data buffer, in bytes. 

NOTE: maxLen bytes are set aside in the output PDF file for the PKCS #7 

certificate, and will be written to the PDF file regardless of the actual certificate 

length. Callers should pass length values which are close to the certificate length 

if possible. 


This call is optional for clients using PKCS #7 certificates. A callback function is 

supplied for the signature. The callback is called during the dlpdfdocwritepdf 

function with binary information from the PDF file. This information will be in 

sequential pieces, and may be used to generate the PDF document hash value. The 

information is supplied as binary values in the character buffer; the length to read is 

supplied as the second parameter. A length of 0 indicates that no further data is to be 

read, and the hash may be finalized. 


This call associates a digital signature to a page in the PDF file generated by DLI. The 

signature appearance must fit in the bounds supplied in imageBBox. This call is 

required for all digital signatures, even invisible signatures. For invisible digital 

signatures, the imageBBox is ignored and may be NULL.

16 

Error 

Testing and Recovery 

This chapter discusses possible errors you may encounter 

and how to resolve them. 

16.1


Overview 


The Adobe PDF Library and DLI will communicate errors back to your application 

program by raising an exception. For this reason, it is important that you have 

exception handlers placed to catch such errors as close as possible to their source, to 

detect the error as soon as possible and to limit the damage an error can cause. It is 

also important that an outer error catcher be in place, as having no exception handler 

when an exception is raised will cause a fatal error. 

NOTE: Follow the development guidelines for error handling that are included in 

the Adobe Acrobat Core API Overview. See chapter 12, “Handling Errors” for more 

information. 

The Adobe PDF Library provides a mechanism in “C” to define exception handlers. 

This mechanism consists of bracketing the code which may cause an exception to be 

raised with DURING and HANDLER, followed by a block of code to be executed only if 

an exception is raised, terminated by END_HANDLER. 

CAUTION: Your application must not exit from within the exception handler. 

Doing so will leave the exception handler frame on the stack, eventually leading to 

a stack overflow and crash. Your application should exit beyond the 

END_HANDLER statement, not within the HANDLER/END_HANDLER block. See 

“Risks of Function Returns within Exception Handlers” on page 16.3 following 

below.

Error Testing and Recovery 16.3 

Always use the macros defined by Adobe for returning from functions under various 

conditions. For example: 

"C" Example: Error Handler 

DURING 

Image = dlpdfimagecreatefromfile (Doc, FileName); 

HANDLER 

char Buffer[1024]; 

ASGetErrorString(ASGetExceptionErrorCode(), Buffer, 1024); 

printf (“Unable to process image ‘%s’ for reason ‘%s’, 

FileName, Buffer); 

Image = NULL; 

END_HANDLER 

To support you in handling an error, both the Adobe PDF Library and DLI report 

errors via exception names. These names are available via the method 

ASGetExceptionErrorCode. It will be translated into a meaningful text string via 

the call ASGetErrorString. 

Each method documents the exceptions that may be raised by that method. You may 

design error routines which examine the exception code and act differently based on 

its value. 

Be careful in placing DURING/HANDLER/END_HANDLER constructs. Try to get them as 

close to a definable piece of your data constructs as possible. Depending on the 

function of your application, this may allow a single construct to fail without 

removing all of a line, area, page, or the document as a whole. 

The more handler constructs you build, the smaller the effect of an error may be, and 

the greater your chances that your application may be able to recover from that error 

and continue (depending on the nature of the problem, of course). 

Risks of Function Returns within Exception Handlers 

Do not return from a function while inside an exception handler, since doing so can 

cause unexpected and hard-to-trace program crashes. If an application must exit while 

inside a DURING/HANDLER/END_HANDLER construct, use the E_RETURN(X) macro


to return the value X, or the E_RTRN_VOID macro to exit a function with no return 

value. 


OS/390 Platform Concerns 

The preceding error recovery mechanism applies on the OS/390 platform if the SAS/C 

compiler is used. In cases where the OS/390 application is not compiled via SAS/C, it 

must use a different mechanism to obtain the error status. This consists of three 

primary function calls: 

DLExceptionFlag 

Returns: ASInt32 

DLExceptionFlag returns 0 if no exception was raised by the exception handler in 

the most-recently-called Adobe PDF Library or DLI function. A non-zero return 

value indicates that an error was detected while processing the last function call. 

This error mechanism is destructive, in that the flag value is reset by accessing it with 

the DLExceptionFlag function call. 

NOTE: If DLExceptionFlag returns a non-zero return code, the return value 

of the function in which the error occurred is undefined. 

DLExceptionCode 

Returns: ASInt32 

DLExceptionCode returns the last exception code set by an exception raised by an 

Adobe PDF Library or DLI function. The code value returned by the 

DLExceptionCode function may be used to retrieve an error message via a call to 

ASGetErrorString, as documented in the Adobe PDF Library Developer Guide.

Error Testing and Recovery 16.5 

DLExceptionMessage 

Returns: char* 

DLExceptionMessage returns a non-NULL pointer if an additional message string 

was generated by Adobe PDF Library or DLI when an exception was raised. This 

pointer may be NULL when an error is raised if the Adobe PDF Library or DLI 

function does not supply the optional message string. 

The application should call DLExceptionFlag after each Adobe PDF Library and 

DLI function call to determine if an exception was raised. If the flag is non-zero, the 

application should use DLExceptionCode and/or DLExceptionMessage to 

obtain additional information, then handle the exception as appropriate. 

These are the basic steps that should be followed: 

1 Call the desired Adobe PDF Library/DLI function 

2 Get the Exception Status by calling DLExceptionFlag 

3 If DLExceptionFlag returns a non-zero value: 

• Get additional error information (DLExceptionCode, ASGetErrorString, 

DLExceptionFlag) 

• Handle exception as appropriate to the application (e.g. switch to a default font, 

flush the current statement, etc.).



17 

Samples 

and Links 

The following pages explain the full DLI sample 

programs that have been compiled and tested, and which 

accompany this release. They illustrate various aspects of 

the usage of Adobe PDF Library and DLI. 

17.1


Running DLI Sample Applications 


Notes on each specific DLI sample follow below. You are not required to test any or 

all of them, but if you do, we suggest running them in the order given below. 

Some samples require one or more command-line arguments, and will prompt for 

them if not given. 

You should find the following DLI samples in individual subfolders under 

C:\Datalogics\APDFL6.1.1\DLI\Samples (or similar). On Windows 

platforms, a Visual Studio C++ v6.0 Workspace file, including all DLI samples as 

Projects within, can be found in 

C:\Datalogics\APDFL6.1.0\DLI\Samples\All (see dli_samples.dsw). 

NOTE: Sample applications included in each release are subject to change. Some 

samples may not appear in releases on certain platforms. 

Activating Files-in-Memory within Samples 

For most samples, adding the command-line keyword "MEMORY" will run the 

application using Files-in-Memory methods. This will make use of memory work files 

instead of I/O processing to disk, and as a result should show improved processing 

times. 

Review the source code of any sample to see whether the MEMORY keyword is 

supported in that application. (Most DLI samples include it.) Typically this is 

recognized as an indicator which then determines the calling arguments for 

dlpdfinit, as shown in the following excerpt from the Paths sample application,

Samples and Links 17.3 

where FileSystemType is defined as eMemFileSys if MEMORY was found in the 

calling arguments for the application: 

switch (FileSystemType) 

{ 

case eStdFileSys: 

pdfInstance=dlpdfinit(&DataRec, NULL, NULL); 

break; 

case eMemFileSys: 

pdfInstance=dlpdfinit(&DataRec, dlpdfmemfilesys(), NULL); 

break; 

default: 

printf("Unknown File System requested."); 

return 8;


HelloDLI 


This application is similar to the Adobe PDF Library sample HeloWrld, generating a 

single page reading "Hello DLI!" via DLI methods. Comparing HelloDLI.c to 

HeloWrld.c can show the simplified coding available via DLI for performing 

common Adobe PDF Library tasks.


Paths 

This sample shows how to draw various simple shapes using DLI, and how to draw 

PDF paths with DLI. A path in PDF, like in PostScript, consists of a series of 

movements from a starting point. A path is filled with the fill color in the 

graphics state, and the lines connecting the movements of the path are drawn with 

the stroke color in the graphics state. This sample also demonstrates some 

common matrix operations, such as rotations and translations of paths. 

For common shapes, DLI has shortcut operations to create paths, such as for 

rectangles and arcs. 

This sample also demonstrates the use of CMYK color spaces. For an example of 

using RGB color spaces, please see “Annotations” on page 17.15.


Graphics 


This sample demonstrates how to imports graphics from DLI-supported graphic file 

formats ( RAW, EPS, PNG, JPEG/JPG, GIF, TIFF and PDF ) into a PDF document, 

how to scale these to the individual graphic's design width and height, and how to 

place these on the page. Details on some graphic formats follow below. 

NOTE: An Encapsulated PostScript (EPS) image written to an output PDF file will 

be present in the file, but will not display when viewed in PDF output. It will 

appear when produced as PostScript (e.g. to a PostScript printer). You may need to 

define EPSF_ENABLED in this example in order to process the EPS sample image.


EPS 

EPS graphics will not show when viewing the output PDF graphic; EPS graphics will 

only print, and only when printing to a PostScript device. These graphics are stored in 

PDF as comments. 

If you need to convert EPS files to PDF, please contact Datalogics for information on 

licensing Adobe Normalizer, or use Adobe Distiller. 

PDF 

PDF pages are imported as graphical elements, and some items such as annotations 

and bookmarks are not imported with the PDF file. Additionally, Acrobat Forms are 

not imported at this time. PDF images created with the 

dlpdfimagecreatefromfile call are created from the first page; to import other 

pages, use the dlpdfimagecreatefrompdf function. 

PNG 

Alpha channels are currently flattened into a 1-bit plane (visible/invisible) to facilitate 

placement using a threshhold algorithm. This threshhold cannot be changed at this 

time. 

TIFF 

Only the first page of a multipage TIFF image will be processed at this time. 

Alpha channels are currently flattened into a 1-bit plane (visible/invisible) to facilitate 

placement using a threshhold algorithm. This threshhold cannot be changed at this 

time.


BMP 

NOTE: Some BMP images with LZW skip markers may not embed properly. If 

possible, avoid images with LZW skip markers. 


For all raster images, DLI attempts to do as little image alteration as possible, though 

usually some image processing is required to create stream information suitable for 

inclusion in PDF files. 

NOTE: All images are cached by DLI by filename. Applications should not attempt 

to change image file data during a job, as unpredictable or unexpected results 

could occur.


Encrypt 

This produces a simple PDF document (a blank page with a red square), applying 

encryption to the output PDF file, requiring one of two passwords for viewing: 

When prompted by Adobe Acrobat or Adobe Reader, entering the user password 

"ValidUser" (case-sensitive, must be entered as shown) will open the document for


viewing and printing. 

Entering the owner password "DocOwner" will open the document for viewing and 


printing as before, but will also allow current protection to be modified or removed. 

Compare the action under either password when following the "File- 

>SaveAs..." menu and attempting to change the Security settings on the new file to 

be created. The owner password must be given before Security settings can be viewed 

or modified:


FontFaux 

This sample demonstrates how to create a font for use in a PDF file when the font is 

not present on the system on which an application is running, and illustrates the 

meanings of the various font attributes available to the user in the PDEFontAttrs 

structure. It demonstrates font fauxing techniques for simulating the appearance of 

various referenced fonts which are neither embedded in the document nor available 

on the viewing user machine. 

The sample creates a number of simulated ("faux") fonts, each with different 

attributes. When the created PDF document is opened, Adobe Acrobat or Adobe 

Reader will substitute a font for that used by the PDF file. The document contains


enough information for each font that a viewer can create a lookalike font. That 

lookalike will not be suitable for precise typography, but should be acceptable for 

web-delivery documents. 


NOTE: Only fonts using characters in the Adobe standard encodings (Standard, 

WinAnsi and MacRoman) can be fauxed correctly. Attempting to do this with 

fonts containing characters outside the range of standard encodings will result in 

a bad display. Set the PD_STD_ENCODING font flag in the PDEFontAttrs 

structure to indicate that the font uses only "standard" characters.


FontVerification 

This application is useful for creating a quick-reference table of fonts available to your 

application. It compiles a directory of all fonts found in the current resource listing, 

including a hyperlinked Table of Contents and a sample listing, font dump and 

encoding grid page for every font found. It demonstrates basic font creation using


DLI, and displays the fonts which the Adobe PDF Library was able to locate on the 

host system. 


NOTE: On machines with lengthy resource listings (i.e. numerous fonts available), 

this application may take a minute or two to complete. Some time may elapse 

before any completion messages appear onscreen. 

For each single-byte Type 1 or TrueType font found, a font will be created in DLI 

with the same name and type. Each character of a target encoding will then be 

displayed in a grid formation, to verify proper font creation. Fonts of other types (e.g. 

MultiMaster fonts, Type 0 fonts) will be noted in the Table of Contents, but not used 

for font creation. 

See the source code comments in Fontverification.c for more information on 

how the resource lists are compiled, and what options are available for maintaining 

them and controlling how they are compiled.


Annotations 

This sample demonstrates types of PDF annotations for which DLI provides output 

support. (Other annotation types can be done at the COS layer; see the sample 

“AcroForm” on page 17.18 for more details.) This sample also shows how to 

manipulate RGB color spaces to produce colored text and path elements. 

Annotations include features such as "sticky notes" (open or closed), bookmarks and 

hyperlinks (enabling the user to jump to other places in the current document, to 

other PDF documents or other files, or to Internet addresses elsewhere). 

The first two pages of output demonstrate links to other documents and to other 

pages within the same document. (e.g. a link on Page 1 will take you to Page 2, and a 

link on Page 2 will take you to Page 1.) 

Notice that the link can specify not only the destination being pointed to but also the 

type of screen display to use when you arrive. For example, Page 1’s "Link to page 2,"


if selected, will take you to a full-page view of Page 2. However, Page 2’s "Link to 

page 1," if selected, will zoom in on its Page 1 target note to fill the entire screen. 


Finally, the third page demonstrates two methods of visually cueing the reader to 

embedded hyperlinks: boxing the hyperlink area with an outline rule, or generating 

text of a different color. In either case, clicking on the links should trigger a jump to 

the Datalogics website at http://www.datalogics.com. 

memFiles 

This sample demonstrates use of the Datalogics Files-in-Memory file system. Using 

this filesystem, a DLI user can create ASFile objects from a memory buffer , 

enabling creation of images from memory such as database blobs (Binary Large 

OBjects). The filesystem also allows the user to write PDF files to memory buffers, 

which can then be retrieved, written to other files or manipulated in various ways. 

Temporary files are also written to the Files-in-Memory filesystem, if it is active at the 

time the temporary file is opened. This usually occurs when a document is created. 

MultiDoc 

This sample controls the generation of multiple documents from a single run of the 

application. It has two required arguments: 

• Argument 1 must be the number of documents to produce. 

• Argument 2 must be the number of pages per document to produce. 

Several additional, optional arguments may also be used to vary the output as desired, 

such as PSTOUT or PDFOUT keywords to generate PostScript or PDF output 

respectively. (This sample is mainly intended to demonstrate program operation, not 

text output.) Other command-line arguments can also be given in order to test output 

variations or application performance. Run the sample with no command-line 

arguments for a short usage message; see the source code file MultiDoc.c for more 

details.


NestedPDF 

This sample generates a set of output documents, in which a pair of PDF graphic files 

are in turn included within a larger PDF file, repeating the process several times. It 

demonstrates the ability of the interface to embed PDF files as graphics, in the 

presence of conflicting names, to show PDF Form XObject name scoping rules. 

This sample also demonstrates how to create patterns in DLI for painting content 

areas with a background.


AcroForm 


This sample demonstrates how to create an Acrobat Form using the Adobe PDF 

Library and DLI, creating a number of different field types using COS-layer object 

manipulation.


SignDoc 

This sample demonstrates how to place a digital signature into a PDF file generated by 

DLI. This signature will be compatible with the Adobe self-sign plugin, and will 

contain an x.509 certificate. 

NOTE: Included in this project is a file "rsasign.cpp", containing a very slow 

implementation of the RSA encryption algorithm. Datalogics does not recommend 

using this implementation as a basis for Production code. 

DLI can also produce signatures with PCKS #7-format certificates, for the Adobe selfsign 

plugin and the VeriSign signature plugin. Customers wishing to do this will 

follow a slightly different path, and must be able to generate these certificates. 

This sample uses a dummy x.509 certificate; the key pair used to generate this 

certificate is stored in the sample.key.info file in the @Data directory. 

As of Adobe PDF Library v6.1.1 and DLI v3.0.23, this sample application produces 

digital signatures compatible with the Adobe Acrobat v5 validation plug-in. In a 

future release, DLI will be upgraded to generate digital signatures compatible with


Adobe Acrobat v6 or higher. You should also be aware that this sample takes a long 

time to run. 


psOutput 

This sample demonstrates generation of PostScript from the Adobe PDF Library and 

DLI. The sample will create a new DLI document, add the pages (in reverse order) of


a sample PDF file to the document, and write a PostScript Level 2 output file. 

Additionally, an output PDF file will be written. 

The application does all processing of the material in PDF form; the PostScript is 

generated by exporting the PDF file created by the Adobe PDF Library and DLI to 

PostScript output. This sample shows how one might write an application to convert 

PDF files to PostScript for printing or other processing. 

WideText 

This sample demonstrates the DLI interface to the ICU functionality, used to typeset 

lines of text in Unicode or other wide-text encodings. This functionality supercedes 

the Unicode functionality present in the DLI v2.2.x series. This functionality is 

available for TrueType, TrueType Collection and OpenType font files. This sample 

also demonstrates the use of DLPDFTEXT areas for placement of text. 

NOTE: This sample uses ArialUnicodeMS and BitstreamCyberbit, fonts which are 

not distributed with Adobe PDF Library or DLI. You must ensure that these fonts are 

accessible (or that the sample is modified to use others instead) when running this 

program, or problems may occur, as either a raised exception or an output 

document containing blank glyphs.



A 

DLI Reference Guide 

This appendix defines methods available with DLI. 

A.1

A.2 DLI Reference Guide 

dlpdfcontentarc (DLPDFCONTENT *Content, 

PDEGraphicState *gState, int PaintOp, ASFixed X1, ASFixed 

Y1, ASFixed Radius, ASFixed Angle1, ASFixed Angle2) 

Return Value: void 


Description 

Parameters 

Return Value 

Included as an aid in transitioning from Post- 

Script to PDF. It will draw an arc centered at 

(X1,Y1), at a radius of Radius, from Angle1 

to Angle2, counter-clockwise, where the angles 

are considered to be in degrees. 

• DLPDFCONTENT *Content: Element 

structures, destroyed when associated with a 

page or form; pointers to them should not be 

used after that time. 

• PDEGraphicState *gState: Color 

definitions; path-drawing line sizes and 

parameters. 

• int PaintOp: A composite of text-display 

flags, set by performing a bitwise OR with the 

desired combination of flag values 

kPDEFill, kPDEStroke, kPDEEoFill 

and kPDEInvisible. 

• ASFixed X1 

• ASFixed Y1 

• ASFixed Radius 

• ASFixed Angle1 


void 

Exceptions 

Header 

Related Methods 

Availability 

dli.h 

dlpdfcontentarcn, 


All DLI supported platforms.

DLI Reference Guide A.3 

dlpdfcontentarcn (DLPDFCONTENT *Content, 




Description 

Parameters 

Return Value 

This procedure is included as an aid in transitioning 

from PostScript to PDF. It will draw an 

arc centered at (X1,Y1), at a radius of Radius, 

from Angle1 to Angle2, clockwise, where the 

angles are considered to be in degrees. 

• DLPDFCONTENT *Content: Represents the 

content element. These structures are 

destroyed when associated with a page or 

form, and pointers to them should not be 


• PDEGraphicState *gState: Contains 

definitions of colors to be applied, and line 

sizes and parameters to be used when 

drawing a path. 

• int PaintOp: A composite of flags which 

define how the text will be displayed. It is set 

by performing a bitwise OR with the desired 

combination of the Adobe PDF Library flag 

values kPDEFill, kPDEStroke, 

kPDEEoFill and kPDEInvisible. 






void 

Exceptions 

Header 


Availability 

dli.h 

dlpdfcontentarc, 


All DLI-supported platforms.


dlpdfcontentarcto (DLPDFCONTENT *Content, 


Y1, ASFixed Radius, ASFixed X2, ASFixed Y2, ASFixed Xint, 

ASFixed Yint) 



Description 

Parameters 

Return Value 

This is a convenience method to mimic the Post- 

Script ArcTo operator. It will locate the intersections 

of the line (X1,Y1)->(Xint,Yint), and 

(X2,Y2)->(Xint,Yint), and draw an arc of the 

specified radius tangent to those two lines. The 

line segment from (X1,Y1) to the arc will be 

drawn. Unlike the PostScript ArcTo operator, 

the segment from the tangent to (X2,Y2) will 

also be drawn. 





















• ASFixed Xint 

• ASFixed Yint 

void


Exceptions 

Header 


Availability 

dli.h 

dlpdfcontentarc, 




dlpdfcontentcircle (DLPDFCONTENT *Content, 

PDEGraphicState *gState, int PaintOp, ASFixed X, ASFixed 

Y, ASFixed Radius) 



Description 

Parameters 

Return Value 


from PostScript to PDF. It will draw a 

circle centered at (X,Y) at a radius of Radius. 
















• ASFixed X 

• ASFixed Y 


void 

Exceptions 

Header 


Availability 

dli.h 




dlpdfcontentclip (DLPDFCONTENT *Content, 

ASFixed *Path, int PathLen, int EOClip) 


Description 

Parameters 

Return Value 

Establish a clipping path. Note that clipping 

paths are not established automatically for 

images, forms, or line drawings. Generally, PDF 

images page more efficiently if there is no clipping 

involved. 






• ASFixed *Path: Specifies path; identical 

to dlpdfcontentpath operand. 

• int PathLen: Specifies path length; 

identical to dlpdfcontentpath operand 

• int EOClip: Should be FALSE (0) for a 

normal clip and TRUE (1) for an even/odd 

clip. 

void 

Exceptions 

Header 


Availability 

dli.h 

dlpdfcontentclipend, 




Technical Notes 

1 Clipping paths are not established automatically for images, forms, or line 

drawings. Generally, Concepts PDF and images Facilities: page more Guide efficiently to the if DL there Pager is no Composition clipping System 

involved. 

2 A clipping region is considered a part of the content structure, and will be ended at 

the end of a content structure. Clipping regions may be nested, but each nested 

region must fit within the previous region. A clipping region can and should be 

ended as soon as possible, using the dlpdfcontentclipend call.


dlpdfcontentclipend (DLPDFCONTENT *Content) 


Description 

Parameters 

Return Value 

This call is used to manually end a clipping 

region prior to the end of the content structure. 

It should be called as soon as possible after a 

clipping region is established. 

DLPDFCONTENT *Content: Represents the 

content element. These structures are destroyed 

when associated with a page or form, and 

pointers to them should not be used after that 

time. 

void 

Exceptions 

Header 


Availability 

dli.h 

dlpdfcontentclip 



dlpdfcontentcomment (DLPDFCONTENT 

*Content, char *Comment) 



Description 

Parameters 

Return Value 

This method will insert the specified text string 

as a comment, in the order provided, into the 

content elements. 






• char *Comment: A text string 

void 

Exceptions 

Header 

dli.h 


Availability 

All DLI-supported platforms. 


1 The comment string will always be placed on a separate line, beginning with a 

percent sign (“%”) provided by DLI to mark it as a comment. 

2 The comment text must not contain a new line character, unless you provide a 

percent sign immediately following it. (DLI provides only the initial percent sign 

for each comment. Follow-on new lines within the comment text must contain 

their own starting percent sign for each comment line of output.) 

3 The content element must be valid: the comment pointer must point at a valid non- 

NULL, non-zero length string.


dlpdfcontentcreate (DLPDFDOC *Doc) 

Return Value: DLPDFCONTENT* 

Description 

Parameters 

Return Value 

Creates a new content element with a rotation 

of zero degrees, a position of (0,0) and scaling 

of (1,1). 

DLPDFDOC *Doc: represents the document 

structure and the current status of the document 

at all times. 

DLPDFCONTENT* 

Exceptions 

Header 

dli.h 


Availability 



dlpdfcontentellipse (DLPDFCONTENT *Content, 


Y, ASFixed RadiusH, ASFixed RadiusV) 



Description 

Parameters 

Return Value 


from PostScript to PDF. It will draw an 

ellipse centered at (X,Y), at a vertical radius of 

RadiusV, and a horizontal radius of RadiusH. 
















• ASFixed X 

• ASFixed Y 

• ASFixed RadiusH 

• ASFixed RadiusV 

void 

Exceptions 

Header 


Availability 

dli.h 




dlpdfcontentfontskew (DLPDFCONTENT 

*Content, ASFixedMatrix *Matrix) 


Description 

Parameters 

Return Value 

Causes the font currently in effect for this content 

structure to appear "twisted" according to 

the matrix supplied. 






• ASFixedMatrix *Matrix 

void 

Exceptions 

Header 

dli.h 


Availability 



1 This may be used to simulate an italic or reverse-italic font using a Roman font.


dlpdfcontentgstate (DLPDFCONTENT *Content, 

const PDEGraphicState *newGState) 



Description 

Parameters 

Return Value 

Sets the graphics state of the specified 

DLPDFCONTENT to that of the 

PDEGraphicState. This may be done at any 

point during content placement operations. 

• DLPDFCONTENT* Content: Represents the 

document structure and the current status of 

the document at all times. 

• const PDEGraphicState *newGState 

void 

Exceptions 

Header 

dli.h 


Availability 



dlpdfcontentline (DLPDFCONTENT *Content, 


Y1, ASFixed X2, ASFixed Y2) 


Description 

Parameters 

Return Value 

This procedure will mark a line in the content, 

extending from (X1,Y1) to (X2,Y2). 
















• ASFixed X1: Start X-axis coordinate 

• ASFixed Y1: Start Y-axis coordinate 

• ASFixed X2: End X-axis coordinate 

• ASFixed Y2: End Y-axis coordinate 

void 

Exceptions 

Header 

dli.h 


Availability 



dlpdfcontentpath (DLPDFCONTENT *Content, 

PDEGraphicState *gState, int PaintOp, ASFixed *Path, int 

PathLen) 



Description 

Parameters 

Return Value 

This procedure will mark a path within the content. 






• PDEGraphicState *gState 







• ASFixed *Path: Specifies path 

• int PathLen: Specifies path length 

void 

Exceptions 

Header 

dli.h 


Availability 




1 This is in all ways the same path as would be used by the Adobe PDF Library path 

operators. Such a path may be created manually or by use of the Edit Layer of the 

Adobe PDF Library. 

2 If created with the Adobe PDF Library, the pointer returned by 

PDEPathGetData is sufficient for this call. The length returned by that call must 

be the number of entries in the list, not the size in bytes of the list.


dlpdfcontentpieslice (DLPDFCONTENT *Content, 





Description 

Parameters 

Return Value 

This procedure is included as an aid in graph 

construction. It will draw a pie slice, centered at 


to Angle2, counter-clockwise, where the angles 

are specified in degrees. 





















void 

Exceptions 

Header 


Availability 

dli.h 




dlpdfcontentpieslicen (DLPDFCONTENT 

*Content, PDEGraphicState *gState, int PaintOp, ASFixed 

X1, ASFixed Y1, ASFixed Radius, ASFixed Angle1, ASFixed 

Angle2) 


Description 

Parameters 

Return Value 

This procedure is included as an aid in graph 

construction. It will draw a pie slice, centered at 


to Angle2, clockwise, where the angle is specified 

in degrees. 





















void 

Exceptions 

Header 


dli.h 

dlpdfcontentpieslice


Availability 




dlpdfcontentrect (DLPDFCONTENT *Content, 


Y, ASFixed Width, ASFixed Height) 


Description 

Parameters 

Return Value 

This procedure marks a rectangle in the content. 

It will be located such that its lower left hand 

corner is at (X,Y). 
















• ASFixed X: The X location of the rectangle. 

• ASFixed Y: The Y location of the rectangle. 

• ASFixed Width: The width of the 

rectangle. This may not be specified as zero, 

but may be specified as a negative value, 

which results in flopping the rectangle (i.e. 

right instead of left). 

• ASFixed Height: The height of the 

rectangle. This may not be specified as zero, 

but may be specified as a negative value, 

which results in flopping the rectangle (i.e. 

down instead of up). 

void 

Exceptions


Header 

Availability 

dli.h 




dlpdfcontentreferenceform (DLPDFCONTENT 

*Content, DLPDFFORM *Form, ASFixed X, ASFixed Y, 

ASFixed Rotate, ASFixed ScaleX, ASFixed ScaleY) 


Description 

Parameters 

Return Value 

Places a reference to the specified DLPDFFORM 

into the specified content structure, with the 

lower left corner of the form positioned at 

(X,Y), and with the specified rotation and scaling 

factors. 






• DLPDFFORM *Form 

• ASFixed X: X coordinate for Form 

placement 

• ASFixed Y: Y coordinate for Form 

placement. 

• ASFixed Rotate: Degrees to rotate the 

form counterclockwise 

• ASFixed ScaleX: X-axis Scale Factor. “No 

scaling” is represented by the value 1. 

• ASFixed ScaleY: Y-axis Scale Factor. “No 

scaling” is represented by the value 1. 

void 

Exceptions 

Header 

dli.h 


Availability 




(DLPDFCONTENT *Content, DLPDFIMAGE *Image, ASFixed 

X, ASFixed Y, ASFixed Rotate, ASFixed ScaleX, ASFixed 

ScaleY) 



Description 

Parameters 

Return Value 

This procedure places a copy of the referenced 

image into the current content. 






• DLPDFIMAGE *Image 

• ASFixed X: The X-axis location of the 

rotation point 

• ASFixed Y: The Y-axis location of the 

rotation point 

• ASFixed Rotate: Amount of 

counterclockwise rotation in degrees 

• ASFixed ScaleX: X-axis Scale Factor 

• ASFixed ScaleY: Y-axis Scale Factor 

void 

Exceptions 

Header 


Availability 

dli.h 

dlpdfimagegetsize (New in DLI v2.2.5) 




1 The image will be placed so as to align its lower left hand corner with the given 

(X,Y) location, scaled as per ScaleX and ScaleY, and rotated as per Rotate. 

2 Image rotation, if any, always occurs about its origin, typically the lower-left 

corner of the image, and the point of rotation is located by the given (X,Y) 

location. 

3 The Scale Factors will determine the resulting size of the image. You need to know 

the original image resolution and its intended size in order to determine whether a 

Scale Factor on either axis is required. In DLI v2.2.5 or higher, the 

dlpdfimagegetsize method can retrieve image sizing data for you, and 

dividing the intended print size by the file size for each dimension (delivered by 

dlpdfimagegetsize) will yield a Scale Factor ratio which 

dlpdfcontentreferenceimage uses to calculate the final output image size. 

4 The typical scaling calculation using values returned by dlpdfimagegetsize 

would be to divide the intended print size by the image size on each axis (e.g. 

"dlpdfcontentreferenceimage(Content, Image, 


ASFixedDiv(xPoints,Int32ToFixed(xRasters)), 

ASFixedDiv(yPoints,Int32ToFixed(yRasters)));"). 

5 An image in which each pixel of each raster line represents one PDF unit of output 


and print size (xPoints and yPoints), and thus a Scale Factor of 1 on both 

axes.


dlpdfcontentrotate (DLPDFCONTENT *Content, 

ASFixed Rotate) 



Description 

Parameters 

Return Value 

Rotates all of the contents of a given content 

structure by the specified amount. 






• ASFixed Rotate: May be any amount, but 

will be reduced to between 0 and 360 

degrees. Considered to be in degrees of 

counterclockwise rotation about the content 

structure’s lower left corner. 

void 

Exceptions 

Header 

dli.h 


Availability


dlpdfcontentscale (DLPDFCONTENT *Content, 

ASFixed XScale, ASFixed YScale) 


Description 

Parameters 

Return Value 

Scales all of the content of a given content structure 

by the specified amount. 






• ASFixed XScale: X-axis scale factor, a 

positive number greater than 0.0001. 

• ASFixed YScale: Y-axis scale factor, a 

positive number greater than 0.0001. 

void 

Exceptions 

Header 

dli.h 


Availability 



dlpdfcontenttext (DLPDFCONTENT *Content, 

DLPDFFONT *Font, char *str, PDEGraphicState *gState, 

PDETextState *tState, ASFixed pointSize, ASFixed setWidth, 

ASFixed XPos, ASFixed YPos, ASFixed Rotate) 



Description 

Parameters 

Adds a NULL-terminated string of text to the 

content. It will be placed such that the baseline 

of the left edge of the first character aligns to 

the position (XPos,YPos) in points. 






• DLPDFFON *Font: Reflects the font. It is 

created by dlpdffontcreate on a perdocument 

basis, and may only be used within 

the document it was created in. Fonts are 

tracked within the document and destroyed 

when the document is destroyed. Pointers to 

fonts are invalid after the destruction of their 

document. 

• char *str: Text string 





• PDETextState *tState: The current text 

state. This should not be NULL. A zero-filled 

PDETextState parameter is permitted.


Parameters (Continued) 

Return Value 

• ASFixed pointSize: Point size 

• ASFixed setWidth: Set width 

• ASFixed XPos: Position along the X axis 

where the baseline of the left edge of the first 

character will be aligned. 

• ASFixed YPos: Position along the Y axis 

where the baseline of the left edge of the first 

character will be aligned. 

• ASFixed Rotate: Angle at which the 

baseline should proceed, where zero is to the 

right and positive numbers express 

counterclockwise rotation in degrees. 

void 

Exceptions 

Header 


Availability 

dli.h 

dlpdfcontenttextwidth, 

dlpdfcontentwidetext, 




dlpdfcontenttextwidth (DLPDFFONT *Font, char 

*Text, ASFixed SetWidth, PDETextState *TState) 

Return Value: ASFixed 


Description 

Parameters 

Return Value 

Returns the width (in points) of the specified 

Text set in the specified Font with the specified 

SetWidth. The fourth parameter is an optional 

Current Text State, which may be NULL. 

• DLPDFFONT *Font: The specified font 

• char *Text: The specified text 

• ASFixed SetWidth: The specified width 

• PDETextState *TState: The current text 

state. This may be NULL. A zero-filled 

PDETextState parameter is also permitted. 

ASFixed 

Exceptions 

Header 


Availability 

dli.h 

dlpdfcontenttext, 

dlpdfcontentwidetext, 




dlpdfcontenttopage (DLPDFCONTENT *Content, 

DLPDFPAGE *Page) 


Description 

Parameters 

Return Value 

This procedure will make the markings placed 

into content a part of the specified page. Following 

this call, the content structure no longer 

exists; pointers to it are invalid and should not 

be used. 


content element. This structure is destroyed 

when associated with a page or form, and 

pointers to them should not be used after that 

time. 

• DLPDFPAGE *Page: Represents a page. This 

structure is tracked within the package and 

destroyed when the document is destroyed. 

Pointers to this structure remain valid until 

the document is destroyed. 

void 

Exceptions 

Header 

dli.h 


Availability 



dlpdfcontenttranslate (DLPDFCONTENT 

*Content, ASFixed X, ASFixed Y) 



Description 

Parameters 

Return Value 

Moves all the contents of a content structure by 

the specified amounts. 






• ASFixed X: The X-axis amount by which 

content structure will be moved, in points. 

Positive X values move right; negative X 

values move left. 

• ASFixed Y: The Y-axis amount by which 

content structure will be moved, in points. 

Positive Y values move up; negative Y values 

move down. 

void 

Exceptions 

Header 

dli.h 


Availability 



dlpdfcontentusefillpattern (DLPDFCONTENT 

*Content, DLPDFPATTERN *Pattern) 


Description 

Parameters 

Return Value 

Applies the fill pattern. 






• DLPDFPATTERN *Pattern: If this is NULL, 

the patterned color space will be turned Off. 

void 

Exceptions 

Header 


Availability 

dli.h 

dlpdfpatterncreate, 





(DLPDFCONTENT *Content, DLPDFPATTERN *Pattern) 



Description 

Parameters 

Similar to dlpdfcontentusefillpattern, 

but strokes instead of filling. 






• DLPDFPATTERN *Pattern 

Return Value 

Exceptions 

Header 


Availability 

dli.h 

dlpdfcontentusefillpattern 



dlpdfcontentwidetext (DLPDFCONTENT 

*Content, DLPDFFONT *Font, char *str, int Length, 

PDEGraphicState *gState, PDETextState *tState, ASFixed PS, 

ASFixed SW, ASFixed X, ASFixed Y, ASFixed Rotate) 


Description 

Parameters 

Return Value 

Same as dlpdfcontenttext, but permits 

Unicode and MultiByte text. 






• DLPDFFON *Font 

• char *str: A text string 

• int Length 





• PDETextState *tState: The current text 

state. This may be NULL. A zero-filled 

PDETextState parameter is also permitted. 

• ASFixed PS: Point Size scale factor along 

the Y axis (vertical). 1 = no scaling (2 = 

double the original size, 0.5 = ½ the original 

size, etc...) 

• ASFixed SW: Set Width scale factor along 

the X axis (horizontal). 1 = no scaling. 

• ASFixed X: X coordinate of the lower left 

corner of the bounding box for the text 

• ASFixed Y: Y coordinate of the lower left 

corner of the bounding box for the text 

• ASFixed Rotate: Angle of rotation. 0 = no 

rotation. 

void 

Exceptions


Header 

dli.h 






Availability 




1 Double-byte NULL values acting as Unicode string terminators are not required, 

and, if present, are not included in any Unicode string length calculations.


dlpdfcontentwidetextwidth (DLPDFFONT 

*Font, char *string, int Length, ASFixed SetWidth, 

PDETextState *TState, PDEGraphicState *GState) 



Description 

Parameters 

Return Value 

Same as dlpdfcontenttextwidth, but 

permits multi-byte (Unicode) text. 

• DLPDFFONT *Font 

• char *string 

• int Length 

• ASFixed SetWidth 



PDETextState parameter is permitted. 

• PDEGraphicState *GState: Contains 




ASFixed 

Exceptions 

Header 


Availability 

dli.h 



dlpdfcontentwidetext 



1 Double-byte NULL values acting as Unicode string terminators are not required, 

and, if present, are not included in any Unicode string length calculations.


dlpdfdocasciips (DLPDFDOC *Doc) 


Description 

Parameters 

Return Value 

This method supports creation of PostScript 

output suitable for transmission through channels 

and to devices which do not accept binary 

data. Most PostScript printers cannot properly 

process binary PostScript input, although Distiller 

and most print spoolers will accept binary 

PostScript data. 

DLPDFDOC *Doc: Represents the document 


at all times. 

void 

Exceptions 

Header 

dli.h 


Availability 



dlpdfdoccomplete (DLPDFDOC *Doc) 



Description 

Parameters 

Return Value 

Completes the page tree for a document and 

creates specified thumbnails. It is called internally 

by dlpdfdocwritepdf and dlpdfdocwritePS, 

and may be manually called to 

write the document using other interface elements 

(e.g. writing to a custom file system), or 

as a method of imaging pages prior to writing 

the document. 



at all times. 

void 

Exceptions 

Header 


Availability 

dli.h 

dlpdfdocwritepdf, 

dlpdfdocwritePS 



dlpdfdoccompress (DLPDFDOC *Doc) 


Description 

Parameters 

Return Value 

Turns compression On (by default, it is Off) for 

text streams used within the PDF document. 

When on, Flate compression will be used on all 

textual content, images and forms. This method 

should be called before any content is placed 

onto a page. Content placed prior to this call 

will not be compressed. 



at all times. 

void 

Exceptions 

Header 

dli.h 


Availability 



dlpdfdoccosdoc (DLPDFDOC *Doc) 

Return Value: CosDoc 


Description 

Parameters 

Return Value 

Used with the COS layer of the Adobe PDF 

Library to accomplish functions outside DLI. 



at all times. 

CosDoc: Reflects the constructed document 

Exceptions 

Header 


Availability 

dli.h 

dlpdfdocpddoc, 

dlpdfdoccomplete 



1 The COS form of the document must not be used in any way that accesses pages 

prior to writing the document or calling dlpdfdoccomplete. Prior to those 

calls, the page tree is not complete.


dlpdfdoccreate (DLPDFINSTANCE *instance) 

Return Value: DLPDFDOC * 

Description 

Parameters 

Creates a new, empty document. 

DLPDFINSTANCE *instance: The DLPD- 

FINSTANCE to use for the document 

Return Value DLPDFDOC * 

Exceptions 

Header 


Availability 

genErrBadParam 

dli.h 

dlpdfdocdestroy, 

dlpdfdocsetpsname, 

dlpdfdocwritePS (See Technical Notes 

below) 



1 Processing is much faster if the Adobe PDF Library is not invoked; however, the 

Library must be invoked if PDF and PostScript are to be created. 

2 See the Adobe API Reference Guide for information on Adobe PostScript support. 

3 As of DLI v3.0, this call no longer accepts a PostScript filename. (Use 

dlpdfdocsetpsname, or supply one to dlpdfdocwritePS.) The PDFNeeded 

flag has been removed; PDF processing is always performed.


dlpdfdoccreatesignature (DLPDFDOC *Doc, 

dlpdfsighandler sigType, char *nameStr, char *reasonStr, 

char *locationStr) 


Return Value: DLPDFSIGNATURE * 

Description 

Parameters 

This call creates a digital signature object for 

the DLI document being created. 

• DLPDFDOC *Doc: The document for which 

the signature object will be created 

• dlpdfsighandler sigType: The 

signature type, one of dlpdfsigacrox509, 

dlpdfsigacropkcs7 or 

dlpdfsigverisign; see Technical Notes 

below. 

• char *nameStr: (Optional) Signatory 

Name 

• char *reasonStr: (Optional) Reason for 

signing (e.g. Initial Release; Document 

Revision) 

• char *locationStr: (Optional) Location 

of the signatory 

Return Value DLPDFSIGNATURE * 

Exceptions 

Header 


Availability 

dli.h 






1 The sigType is one of: 

• dlpdfsigacrox509 (Adobe self-sign plug-in compatible with an x.509 v3 

certificate) 

• dlpdfsigacropkcs7 (Adobe self-sign plug-in compatible with a PKCS #7 

certificate) 

• dlpdfsigverisign (VeriSign signature plug-in compatible with a PKCS #7 

certificate)


dlpdfdocdestroy (DLPDFDOC *Doc) 



Description 

Parameters 

Return Value 

Destroys the specified document, releasing all 

resources used in the document. 

DLPDFDOC *Doc: represents the document 


at all times. 

void 

Exceptions 

Header 


Availability 

dli.h 

dlpdfdoccreate, 




1 All documents should be destroyed before terminating DLI. 

2 A pointer to a DLPDFDOC structure is invalid and should not be used after calling 

dlpdfdocdestroy for that structure. 

3 The collection of information regarding where elements lie within a document is 

the responsibility of the composition engine. DLI cannot provide assistance with 

this. 

4 If dlpdfinstancesetgrcachelimits had been set previously, the graphics 

cache size is evaluated at this time, and graphics are purged if the cache size 

exceeds its preset high-water mark limit. 

5 If applicable, dlpdfdocdestroy removes the Files In Memory file representing 

the DLI document if no handle has been acquired to the file in memory.


dlpdfdocembedfonts (DLPDFDOC *Doc) 


Description 

Parameters 

Return Value 

This call will set the input document to embed 

and subset all fonts which are present on the 

system when created, regardless of the font call 

used to create them. Fonts created with dlpdffontcreateembedded 

or dlpdffontcreatewithmetricsembedded 

with the 

Subset parameter set to FALSE will be fully 

embedded after calling this function (license 

permitting; see Technical Notes below). 

DLPDFDOC *Doc: The document for which to 

embed all fonts 

void 

Exceptions 

Header 


Availability 

dli.h 

dlpdffontcreateembedded, 




1 If a font is available but not licensed for embedding, it will be created as a 



inspected after the dlpdfdocembedfonts call, if desired.


dlpdfdocencrypt (DLPDFDOC *Doc, char *UserPW, 

char *OwnerPW, PDPerms Permissions) 



Description 

Parameters 

Return Value 

Applies the Adobe PDF Library standard security 

mechanism to the document, using the permissions 

specified in the Permissions 

parameter as outlined in the Acrobat Core API 

Reference Manual in the PDPerms definition 

on page 2101. 

• DLPDFDOC *Doc: Represents the document 

structure and the current status of the 

document at all times. 

• char *UserPW: (Case sensitive) string for 

User Password 

• char *OwnerPW: (Case sensitive) string for 

Owner Password 

• PDPerm Permissions 

void 

Exceptions 

Header 


Availability 

dli.h 

dlpdfdocsetencryptkeylen 

Adobe PDF Library v4.05 and higher; all DLIsupported 

platforms. 


1 Both Owner Password and User Password are case-sensitive. Either password will 

allow viewing of the document, but only the Owner can modify its Security 

settings. 

2 This call may be made at any time prior to dlpdfdocwritepdf.


dlpdfdoclinearize (DLPDFDOC *Doc) 


Description 

Parameters 

Return Value 

Instructs DLI to linearize any PDF output created 

from this document, regardless of the setting 

of the linearization flag used at document 

output time. 



at all times. 

void 

Exceptions 

Header 

dli.h 


Availability 



1 This is included in support of document processing systems which know the 

desired result of document creation at the start of document processing, but which 

may not retain that knowledge until the end of processing.


dlpdfdocmakethumbnails (DLPDFDOC *Doc) 



Description 

Parameters 

Return Value 

Instructs the application to create thumbnail 

page images. These will be added to all pages 

when the file is written to PDF. 



at all times. 

void 

Exceptions 

Header 

dli.h 


Availability 

Adobe PDF Library v4.05 and later; all DLIsupported 

platforms.


dlpdfdocnameadd (DLPDFDOC *Doc, char 

*TreeName, char *Name, CosObj Dest) 


Description 

Parameters 

Return Value 

Adds a new name and an associated destination 

(as a COS structure) to the name tree, which 

will be named as defined in TreeName. 

“Dests” is the default TreeName value, which 

is assumed if NULL is used. 




• char *TreeName: TreeName string, or 

NULL for default TreeName. 

• char *Name: Name string 

• CosObj Dest 

void 

Exceptions 

Header 


Availability 

dli.h 

dlpdfdocnamefind 



dlpdfdocnamefind (DLPDFDOC *Doc, char 

*TreeName, char *Name,) 

Return Value: CosObj 


Description 

Parameters 

Return Value 

Locates a name in the tree, and returns its associated 

COS structure. 




• char *TreeName: TreeName string, or 

NULL for default TreeName 


CosObj 

Exceptions 

Header 


Availability 

dli.h 

dlpdfdocnameadd 



dlpdfdocoutline (DLPDFDOC *Doc) 

Return Value: DLPDFOUTLINE* 

Description 

Parameters 

Return Value 

Returns a pointer to the root outline node. This 

node contains no text; it is used simply as a container 

for nodes at the root layer. If there are no 

outlines, this pointer will be NULL. 



at all times. 

DLPDFOUTLINE* 

Exceptions 

Header 

dli.h 


Availability 



dlpdfdocoutlineadd (DLPDFDOC *Doc, 

DLPDFOUTLINE *Parent, DLPDFOUTLINE *Before, char 

*Text, int Open, long PageNumber, char *Fit, ASFixedRect 

*Where, ASFixed Zoom) 



Description 

Parameters 

Creates an outline structure within the document 

specified. 

• DLPDFDOC *Doc: Specifies the document in 

which the new outline will reside 

• DLPDFOUTLINE *Parent: If specified, the 

new outline structure will be contained 

within the parent. If not specified, the new 

outline structure will be placed within the 

root node. 

• DLPDFOUTLINE *Before: If specified, the 

new outline entry will be positioned directly 

after the previous outline entry given. If not 

specified, the new entry will be created as the 

last within the parent or root. 

• char *Text: Text that will appear in the 

displayed outline and which must be 

specified 

• int Open: A Boolean operator: if TRUE, the 

entry will be open and its children will be 

displayed; if FALSE, it will be closed. 

• long PageNumber: The zero-relative 

number of the page to which this link 

connects 

• char *Fit: valid PDF fit type expressed as 

a string. 

• ASFixedRect *Where: location of the 

rectangle to be displayed. Only portions are 

used, based on the Fit Type specified in 

Fit. 

• ASFixed Zoom: factor by which the size of 

the display should be increased or decreased.


Return Value 

DLPDFOUTLINE*: Internal structure that 

reflects the outline entry 

Exceptions 

Header 


Availability 

dli.h 

dlpdfdocoutlineaddfromname, 

dlpdfdocoutlinecosobj, 

dlpdfdocoutlinefirst, 

dlpdfdocoutlinelast, 

dlpdfdocoutlinenext, 

dlpdfdocoutlineparent, 




1 Only internal destinations (within the same document) are supported by this 

method. 

2 Valid Fit Type values are “Fit”, “FitH”, “FitV”, “FitBH”, “FitBV”, 

“FitR”, “FitB”, and “XYZ”. See the Adobe PDF Library Reference Guide for 

explanations of the meaning of each fit type and which values of rectangle and 

zoom are used for each. 

3 If nested outlines are desired, these structures should be saved by the application. 

They will be destroyed automatically when the document is destroyed and may 

not be accessed after that time. Their contents must not be modified, as they are 

maintained within the package. 

4 Zero values in the rectangle will behave as PDViewNull values, as will a zero 

value for Zoom. 

5 The most common values used are XYZ as the fit type, Zero for Zoom, and the 

(X,Y) coordinates of the upper left hand edge of the desired target text in 

Where.top and Where.left. This will change to the target page and position 

the specified text so it is within the display window, leaving the Magnification 

factor where the user last set it.


dlpdfdocoutlineaddfromname (DLPDFDOC 

*Doc, DLPDFOUTLINE *Parent, DLPDFOUTLINE *Before, char 

*Text, int Open, char *DestName) 



Description 

Parameters 

Return Value 

Exceptions 

Header 


Availability 

Adds a new outline entry using the named destination, 

rather than a specified document. 




• DLPDFOUTLINE *Parent 

• DLPDFOUTLINE *Before 

• char *Text: Text string 

• int Open 

• char *DestName: String for destination 

name 

DLPDFOUTLINE* 

dlpdfdocoutlineadd, 

dlpdfdocoutlinecosobj, 






dli.h 

dlpdfdocoutlineadd 



dlpdfdocoutlinecosobj (DLPDFOUTLINE *Outline) 


Description 

Parameters 

Return Value 

Returns the COS structure that is the outline 

entry. It may be modified by the user to accomplish 

actions other than those specified by this 

package. 

DLPDFOUTLINE *Outline 

CosObj 

Exceptions 

Header 


Availability 

dli.h 

dlpdfdocoutline 



1 Only the Title, Dest, A (Action), or AA (Additional Action) keys should be 

modified. Modification of other keys may result in invalid documents.


dlpdfdocoutlinefirst (DLPDFOUTLINE *Outline) 



Description 

Parameters 

Return Value 

Returns a pointer to the first child outline of the 

specified outline 


DLPDFOUTLINE* 

Exceptions 

Header 


Availability 

dli.h 







1 If the specified outline contains no children, this method will return a NULL.


dlpdfdocoutlinelast (DLPDFOUTLINE *Outline) 


Description 

Parameters 

Return Value 

Returns a pointer to the last child outline of a 

specified outline node. If the node contains no 

children, this method will return a NULL. 


DLPDFOUTLINE* 

Exceptions 

Header 


Availability 

dli.h 







dlpdfdocoutlinenext (DLPDFOUTLINE *Outline) 



Description 

Parameters 

Return Value 

Returns a pointer to the outline node that follows 

the specified node 


DLPDFOUTLINE* 

Exceptions 

Header 


Availability 

dli.h 







1 If the specified node is the last within its parent, this method will return a NULL.


dlpdfdocoutlineparent (DLPDFOUTLINE 

*Outline) 


Description 

Parameters 

Return Value 

Returns a pointer to the parent of the specified 

node 


DLPDFOUTLINE* 

Exceptions 

Header 


Availability 

dli.h 







1 If this node is the root node, this method will return a NULL.


dlpdfdocoutlineprev (DLPDFOUTLINE *Outline) 



Description 

Parameters 

Return Value 

Returns a pointer to the outline node that precedes 

this node within its container. 


DLPDFOUTLINE* 

Exceptions 

Header 


Availability 

dli.h 




dlpdfdocoutlineparent 



1 If this is the first node in the container, this node will return a NULL.


dlpdfdocpddoc (DLPDFDOC *Doc) 

Return Value: PDDoc 

Description 

Parameters 

Return Value 

Used with the PD Layer of the Adobe PDF 

Library to accomplish functions outside of DLI. 

DLPDFDOC *Doc represents the document 


at all times. 

PDDoc reflects the constructed document. 

Exceptions 

Header 


Availability 

dli.h 

dlpdfdoccosdoc 



1 The PDDoc must not be used in any way prior to calling dlpdfdocwritepdf, 

dlpdfdocwritePS or dlpdfdoccomplete. Prior to those calls, the page tree is 

not complete.


dlpdfdocsetdocinfo (DLPDFDOC *Doc, ASAtom 

Field, char *Value) 



Description 

Parameters 

Return Value 

Creates or replaces an entry in the document’s 

DocInfo directory 




• ASAtom Field: Any name is valid, 

although only certain names have meaning to 

PDF readers 

• char *Value: A string pair 

void 

Exceptions 

Header 

dli.h 


Availability 



1 This method may be called at any time.


dlpdfdocsetencoding (DLPDFDOC *Doc, ASAtom 

Encoding) 


Description 

Parameters 

Return Value 

Exceptions 

Header 

Sets the default encoding for fonts used within 

the document. 




• ASAtom Encoding: Valid values are 

ASAtoms containing 

“MacRomanEncoding”, 

“MacExpertEncoding” or 

“WinAnsiEncoding”. A NULL ASAtom, as 

returned by the ASAtomNull function, is 

also allowed, meaning “Standard” 

encoding 

void 

genErrBadParam: Raised if any encoding 

value other than the values specified above (or a 

NULL document pointer) is passed to this function. 

dli.h 


Availability 



dlpdfdocsetencryptkeylen (DLPDFDOC *Doc, 

unsigned int KeyLenBytes) 



Description 

Parameters 

Return Value 

Exceptions 

Header 


Availability 

Enables variable-length encryption keys as supported 

by the Adobe PDF Library. 




• unsigned int KeyLenBytes: The 

desired encryption key length in bytes, from 

5 to 15 inclusive 

void 

This function itself throws no specific exceptions, 

but the underlying functions within the 

Adobe PDF Library may throw exceptions. 

dli.h 

dlpdfdocencrypt 




1 For more information on Encryption, please refer to the beginning of section 3.5 

in the Adobe PDF Specification Guide. For information on 

PDDocSetNewSecurityData and StdSecurityDataRec, see the Adobe 

Core API Reference Guide. 

2 This function can be called to set the length of the encryption key before a call to 

dlpdfdocencrypt, if the application requires an encryption key length other 

than the original 40-bit length of previous versions. 

3 This function is optional if the original 40-bit key length will be used. Subsequent 

calls to dlpdfdocencrypt will use the number of bytes specified in the call to 

dlpdfdocsetencryptkeylen. If the key length has not been set previously, the 

standard 5-byte value is used as the default. 

4 For applications generating multiple documents, dlpdfdocsetencryptkeylen 

must be called for each document for which an encryption key length other than 

the standard 5-byte value is desired.


dlpdfdocsetpdfname (DLPDFDOC *Doc, char 

*Name) 



Description 

Parameters 

Return Value 

Saves the desired location of a PDF file which 

results from this document. 




• char *Name: This name will be used in 

place of any name specified in a 

dlpdfdocwritepdf procedure call. 

void 

Exceptions 

Header 


Availability 

dli.h 

dlpdfdocsetpsname 







dlpdfdocsetpsname (DLPDFDOC *Doc, char 

*Name) 


Description 

Parameters 

Return Value 

Saves the desired location of a PostScript file 

which results from this document. 




• char *Name: This name will be used in 

place of any name specified in a 

dlpdfdocwritePS procedure call. 

void 

Exceptions 

Header 


Availability 

dli.h 

dlpdfdocsetpdfname 








(DLPDFDOC *Doc, DLPDFSIGNATURE *Sig, DLPDFFORM 

*background, DLPDFFORM *unverified, DLPDFFORM 

*signature, DLPDFFORM *textSigInfo) 



Description 

Parameters 

Return Value 

This call sets the appearance layers for the digital 

signature to the supplied DLPDFFORM values. 

This call is optional. For an invisible digital 

signature, do not call this function. All the signature 

layers are also optional. Blank layers will 

be used for any omitted signature appearance 

layers. 

• DLPDFDOC *Doc: document for which the 

signature object will be created 

• DLPDFSIGNATURE *Sig: signature to 

which appearance settings will be assigned 

• DLPDFFORM *background: bottom-most 

layer of the digital signature appearance 

• DLPDFFORM *unverified: layer displayed 

when the signature has not been verified 

• DLPDFFORM *signature: graphical 

representation of the signature itself (such as 

a scanned handwritten signature) 

• DLPDFFORM *textSigInfo: layer 

displaying information about the signature 

and the signatory 

void 

Exceptions 

Header 


Availability 

dli.h 

dlpdfdoccreatesignature, 




dlpdfdocwritepdf (DLPDFDOC *Doc, char 

*FileName, int Linearize) 


Description 

Parameters 

Return Value 

Exceptions 

Header 


Availability 

Writes the document to PDF. 




• char *FileName: May be NULL if it was 

set by a previous call to 

dlpdfdocsetpdfname, otherwise, if the 

filename is not specified, a 

genErrBadParam exception will be raised. 

If the filename was set, 

dlpdfdocsetpdfname has been called. 

• int Linearize: If true, linear optimized 

output will be created. If the procedure 

dlpdfdoclinearize has been called 

prior to a call to write the document, the 

document will be linearized regardless of the 

setting of the linearization flag. 

void 

genErrBadParam: Raised if the filename is 

not specified. 

dli.h 

dlpdfdocwritePS 



dlpdfdocwritePS (DLPDFDOC *Doc, char 

*FileName) 



Description 

Parameters 

Return Value 

Exceptions 

Header 


Availability 

Writes the document to PostScript. 




• char *FileName: May be NULL if it was 

set by a previous call to 

dlpdfdocsetpsname, otherwise, if the 

filename is not specified, a 

genErrBadParam exception will be raised. 

If the filename was set, 

dlpdfdocsetpsname has been called. 

void 

genErrBadParam: Raised if the filename is 

not specified. 

dli.h 




dlpdffontcreate (DLPDFDOC *Doc, char *fontName, 

char *fontType) 

Return Value: DLPDFFONT* 

Description 

Parameters 

Return Value 

This function call will cause the Adobe PDF 

Library to search the system default font locations 

and the locations supplied at initialization 

time for a font of the specified name (and of the 

specified type, if supplied). If a font cannot be 

located, this call will raise an exception. The 

font returned will be created in the document's 

default encoding if that encoding is compatible 

with the font; otherwise, a platform-dependent 

default will be used. 


to embed all fonts 

• char *fontName: The font name to search 

for 

• char *fontType: The type of font (e.g. 

"Type1," "TrueType," "Type3") to 

search for. This may be NULL. 

The DLPDFFONT * which has been created 

Exceptions 

Header 


Availability 

dli.h 

dlpdfdocembedfonts, 


dlpdffontcreatewithmetrics, 





1 When a font type is specified, a font of that type and name is sought. If no such 

font is found, Concepts any type of and font Facilities: with the same Guide name to the is sought. DL Pager Please Composition see “Font System 

Searching Sequence” on page 4.7 for the specific order of search tests followed 

when the font creation process attempts to locate a font in resources.


dlpdffontcreateembedded (DLPDFDOC *Doc, 

char *fontName, char *fontType, ASBool Subset) 


Description 

Parameters 

Return Value 




time for a font of the specified name (and of the 

specified type, if supplied). If a font cannot be 

located, this call will raise an exception. The 

font returned will be embedded and created in 

the document's default encoding if that encoding 

is compatible with the font; otherwise, a 

platform-dependent default will be used. If the 

Subset parameter is set to TRUE, the font will 

be embedded and subset. 



• char *fontName: Font name to search for 

• char *fontType: The type of font (e.g. 

"Type1," "TrueType," "Type3") to 

search for. This may be NULL. 

• ASBool Subset: If TRUE, then the font is 

both embedded and subset. If FALSE, the 

entire font file is embedded in the PDF 

document. For Type0 fonts, this must be 

TRUE. 

The DLPDFFONT which has been created 

Exceptions 

Header 


Availability 

dli.h 


dlpdffontcreate, 

dlpdffontcreatewithmetrics, 




dlpdffontcreatewithmetrics (DLPDFDOC 

*Doc, char *fontName, PDEFontAttrs *fontAttrs, unsigned 

short *Widths, char *Encoding []) 



Description 

Parameters 

Return Value 




time for a font of the specified name and 

attributes. If the font cannot be found, one will 

be created if a width table and valid font 

attributes have been supplied. If no encoding is 

specified in the font attributes, the font will be 

created with the document's default font encoding. 



• char *fontName: Font name to search for 

• PDEFontAttrs *fontAttrs: A 

PDEFontAttrs structure which has been 

zero-filled and set with parameters which the 

caller wants to see reflected in the returned 

font. See the Adobe Acrobat Core API 

Reference for details on this structure. 

• unsigned short Widths: If non-NULL, 

an array of 256 values; see Technical Note 1 

below. 

• char *Encoding: If non-NULL, an array of 

256 values; see Technical Note 2 below. 

The DLPDFFONT which has been created 

Exceptions 

Header 

dli.h



Availability 







1 Each of these is the width of the character in that position, in EMs. If this is NULL, 

the default character widths in the requested encoding of the FontAttrs 

structure are used. This must be NULL for Type0 fonts. 

2 Each of these is the PostScript name of the character to use for the specified code 

point. If this is NULL, the encoding specified in the PDEFontAttrs structure is 

used. This must be NULL for Type0 fonts. It is highly recommended that you 

supply a width table when specifying an encoding vector.



(DLPDFDOC *Doc, char *fontName, PDEFontAttrs 

*fontAttrs, unsigned short *Widths, char *Encoding [], 

ASBool Subset) 



Description 

Parameters 

Return Value 




time for a font of the specified name and 

attributes. If the font cannot be found, an 

exception will be raised. If no encoding is specified 

in the font attributes, the font will be created 

with the document's default font encoding. 

The created font will be embedded; if Subset 

is set to TRUE, then the font will be subset as 

well. 



• char *fontName: The font name to search 

for 

• PDEFontAttrs *fontAttrs: A 

PDEFontAttrs structure which has been 

zero-filled and set with parameters which the 

caller wants to see reflected in the returned 

font. See the Adobe Acrobat Core API 

Reference for details on this structure. 

• unsigned short *Widths: If non-NULL, 

an array of 256 values; see Technical Note 1 

below. 

• char *Encoding: If non-NULL, an array of 

256 values; see Technical Note 2 below. 

• ASBool Subset: If TRUE, then the font is 

both embedded and subset. If FALSE, the 

entire font file is embedded in the PDF 

document. For Type0 fonts, this must be 

TRUE. 

The DLPDFFONT which has been created


Exceptions 

Header 


Availability 

dli.h 







1 Each of these is the width of the character in that position, in EMs. If NULL, the 

default character widths in the requested encoding of the PDEFontAttrs 

structure are used. This must be NULL for Type0 fonts. 

2 Each of these is the PostScript name of the character to use for the specified code 

point. If NULL, the encoding specified in the PDEFontAttrs structure is used. 

This must be NULL for Type0 fonts. When specifying an encoding vector, a width 

table is highly recommended.


dlpdfformcreate (DLPDFDOC *Doc, DLPDFCONTENT 

*Content, ASFixedRect *BBox) 


Return Value: DLPDFFORM* 

Description 

Parameters 

Return Value 

Creates a new form in the document specified as 

Doc., with the content previously placed into 

the container Content. The form will be considered 

to be of the size specified in BBox. The 

Bounding Box need not be located at (0,0); 

however, it must have a positive Width and 

Depth. 

• DLPDFDOC *Doc: Name of new form 

created with this call 


content element. The content block used to 

create a form is destroyed in the form’s 

creation, and any handles to it become 

invalid. 

• ASFixedRect *BBox: Represents the 

bounding box of the form, in points. 

DLPDFFORM* 

Exceptions 

Header 


Availability 

dli.h 

dlpdfformdestroy 



dlpdfformdestroy (DLPDFFORM *Form) 


Description 

Parameters 

Return Value 

Destroys the named form, releasing its resources 

and invalidating the form handle. 

DLPDFFORM *Form 

void 

Exceptions 

Header 


Availability 

dli.h 




dlpdfimagecreatefrombmp (DLPDFDOC *Doc, 

char *ImageName, char *Image, long ImageSize, long 

Width, Long Depth, int bpc, CosObj ColorSpace, int InLine) 


Return Value: DLPDFIMAGE* 

Description 

Parameters 

Return Value 

Creates an image from a bitmap. The map is 

considered to be scanned left to right and top to 

bottom. 

• DLPDFDOC *Doc represents the document 



• char *ImageName: Image name string 

• char *Image: Pointer to the image raster 

data 

• long ImageSize in bytes. Should be equal 

to ((Width*Depth*BitsPerComponent)/ 

8)*CompPerPixel. Components per pixel 

is derived from ColorSpace. 

• long Width in pixels 

• Long Depth in pixels 

• int bpc 

• CosObj ColorSpace: this should be the 

color space name as a COS structure 

(/DeviceGray, /DeviceRGB or 

/DeviceCMYK, which have 1, 3, and 4 

components per pixel respectively), a 

CosNull structure (if this is a 1BPP, onechannel 

bitmap to be placed as an 

imagemask), or an indexed color space 

structure which has one component per pixel. 

• int InLine: A flag which when TRUE will 

embed this structure in the document each 

time it is used. When FALSE, it will be 

embedded only once. 

DLPDFIMAGE* 

Exceptions 

Header 

dli.h



Availability 

dlpdfimagecreatefromfile, 

dlpdfimagecreatefrompdf, 




1 For efficiency purposes, DLI inlines images when the ImageLength parameter is 

less than 500 bytes. 

2 The bitmap processed by this function is a “raw” bitmap with no header 

information or wrapper. Unprocessed BMP files are not supported by this 

function.


dlpdfimagecreatefromfile (DLPDFDOC *Doc, 

char *Name) 



Description 

Parameters 

Return Value 

Invokes the graphics library conversion facility, 

which will convert an arbitrary file containing 

an image (JPG/JPEG, PNG, TIFF, GIF or PDF) 

into a returned DLPDFIMAGE* structure for 

further processing. 





DLPDFIMAGE* 

Exceptions 

Header 


Availability 

dli.h 

dlpdfimagecreatefrombmp, 

dlpdfimagecreatefrompdf, 


Not available on OS/390


dlpdfimagecreatefrompdf (DLPDFDOC *Doc, 

char *ImageName, ASFixed Width, ASFixed Depth, ASFixed 

XDisp, ASFixed YDisp, long Page) 


Description 

Parameters 

Return Value 

This convenience operator will create an image 

from a file containing a PDF document. If 

importing an image containing a Rotate key, 

that value will be honored. Images will be 

placed in the same orientation displayed by 

Adobe Reader and Acrobat. The specified page 

of the PDF document will be used as a graphic 

image. 




• char *ImageName: Image name string 

• ASFixed Width 

• ASFixed Depth 

• ASFixed XDisp 

• ASFixed YDisp 

• long Page 

DLPDFIMAGE* 

Exceptions 

Header 


Availability 

dli.h 







1 As of DLI v3.0.11, a value of 0 is now accepted for the Width and Depth 

parameters. If Concepts either is 0, and the Facilities: PDF page's Guide crop box to the is used DL to Pager form Composition the System 

DLPDFIMAGE's visible region. This will be shifted using the XDisp and YDisp 

values to generate the imported image. 

2 Datalogics recommends supplying a value of 0 for the width, depth, and x- and y- 

displacements, unless it is otherwise known that the imported graphic should be 

placed with a visible region other than that visible in Adobe Acrobat or Reader. 

3 The BoundingBox in the returned DLPDFIMAGE is not rotated by the value of the 

Rotate key for the imported page, and thus can be used to determine the "real" 

width and depth of the imported PDF image.


dlpdfimagecreatefromps (DLPDFDOC *Doc, 

char *ImageName, char *Image, long ImageSize, int InLine) 


Description 

Parameters 

Return Value 

Creates an image from an EPS graphic. It must 

contain a “%%BoundingBox” statement. 




• char *ImageName: Name of Image 

• char *Image: The graphic is contained in 

this array. 

• long ImageSize: Size of image 

• int Inline: A flag, which when TRUE 

embeds this structure in the graphic each time 

it is used. When FALSE, it will be embedded 

only once. 

DLPDFIMAGE* 

Exceptions 

Header 


Availability 

dli.h 



dlpdfimagecreatefrompdf 



1 DLI does not convert PostScript fragments to PDF. Any PostScript images will not 

be viewable in most PDF viewers. This method is included for PDF files which will 

go to printers or print processors which can appropriately handle these fragments.


dlpdfimagegetsize (DLPDFIMAGE *Image, 

ASUns32 *xRasters, ASUns32 *yRasters, ASFixed *xPoints, 

ASFixed *yPoints) 



Description 

Parameters 

Return Value 

This procedure retrieves image size information 

from a graphic file. 

• DLPDFIMAGE *Image: Represents a pointer 

to the image file. This method will examine 

the image file and return values in the four 

arguments following. 

• ASUns32 *xRasters: Width of image in 

rasters or image units (depending on format) 

• ASUns32 *yRasters: Height of image in 

rasters or image units (depending on format) 

• ASFixed *xPoints: Intended print width 

in PDF units 

• ASFixed *yPoints: Intended print height 

in PDF units 

void 

Exceptions 

Header 


Availability 

dli.h 





1 The Scale Factors specified in dlpdfcontentreferenceimage will determine 

the resulting size of the image. This method gives you the image information 

necessary to calculate those values, dividing the intended print size by the file size 

for each dimension. This yields a Scale Factor ratio which 

dlpdfcontentreferenceimage uses to calculate the final output image size. 

2 The typical scaling calculation using values returned by this method would occur 

during the call to dlpdfcontentreferenceimage; e.g. 

"dlpdfcontentreferenceimage(Content, Image, 


ASFixedDiv(xPoints,Int32ToFixed(xRasters)), 

ASFixedDiv(yPoints,Int32ToFixed(yRasters)));". 

3 An image in which each pixel of each raster line represents one PDF unit of output 


and print size (xPoints and yPoints), and thus a Scale Factor of 1 on both 

axes.


dlpdfinit (PDFLData pdflLibData, ASFileSys defaultFS, void 

*unused) 


Return Value: DLPDFINSTANCE * 

Description 

Parameters 

Initializes the Adobe PDF Library and DLI, 

and should be called prior to creating the first 

document. 

• PDFLData pdflLibData: contains the 

initialization information for the Adobe PDF 

Library. 

• ASFileSys defaultFS: the default file 

system for file input/output and creation of 

temporary files. If this parameter is NULL, the 

default file system for the current platform 

will be used. 

• void *unused: NULL; reserved for future 

use 

Return Value DLPDFINSTANCE * 

Exceptions 

Header 


Availability 

dli.h 

dlpdfmemfilesys, 

dlpdfterm 




1 Initialization of DLI is now required; support for using DLI without initialization 

has been removed. If you intend to use DLI methods in your application, you must 

intialize DLI via dlpdfinit. DLI users should initialize the Adobe PDF Library 

through the DLI initialization call; PDFLInit and PDFLTerm should never be 

directly called from a DLI application. 

2 In a multi-threaded application, each thread must do its own initialization and 

termination of the Library. 

3 This procedure, along with dlpdfterm, replaces the need for calls to PDFLInit 

and PDFLTerm. DLI should be initialized, or the Adobe PDF Library, but not 

both. 

4 You can accidentally call dlpdfinit (the DLI command) multiple times without 

problems, as it contains internal code that prevents actual initialization from 

occurring more than once, but you cannot call PDFLInit (the Adobe PDF 

Library command) more than once as a fatal error will occur. 

5 dlpdfinit and dlpdfterm are the only methods which must not be enclosed in 

exception handlers (i.e. DURING/HANDLER/END_HANDLER statements), because 

they are not set up before initialization, and are freed during termination. 

6 As of DLI v3.0.11, the DLI graphics cache has been enhanced to use the default 



larger graphics cache files are advised to supply a filesystem to dlpdfinit which 

is capable of reliably handling files of the larger size. 








dlpdfinstancesetcancelproc (DLPDFINSTANCE 

*dliInst, CancelProc cProc, void *cData) 



Description 

Parameters 

Return Value 

This call sets the cancel procedure used when 

writing a document using the dlpdfdocwritepdf 

call, along with other calls 

which may take a large quantity of time. This 

progress monitor will be used for all documents 

created with the specified instance. 

• DLPDFInstance *dliInst: The 

DLPDFINSTANCE for which to set the cancel 

procedure 

• CancelProc cProc: The cancel procedure 

to use. See the Adobe Acrobat Core API 

Reference for details on creating a cancel 

procedure. 

• void *cData: A pointer to client data 

which is passed to the cancel procedure 

callback. See the Adobe Acrobat Core API 

Reference for details. 

void 

Exceptions 

Header 

dli.h 


Availability 




(DLPDFINSTANCE *dliInst, ASUns32 highLimit, ASUns32 

deleteLimit) 


Description 

Parameters 

Return Value 

This call supports a control on the amount of 

filesystem storage used for the DLI graphics 

cache. It accepts a low-water and a high-water 

mark, in bytes. At document-destroy time (i.e. 

when a call to dlpdfdocdestroy is made), 

the graphics cache size is evaluated, and if it 

exceeds the high-water mark in size, graphics 

will be removed from the cache in least recently 

used (LRU) order until the cache falls to or 

below the low-water mark. 

• DLPDFINSTANCE *dliInst: The 

DLPDFINSTANCE for which the cache will be 

reviewed 

• ASUns32 highLimit: The high-water 

mark level, in bytes. Exceeding this level will 

trigger a purge of graphics in LRU order at 

document-destroy time. 

• ASUns32 deleteLimit: The low-water 

mark level, in bytes, above which graphics 

will be purged at document-destroy-time. 

Graphics will be removed in LRU order until 

the total storage is at or below this figure. 

void 

Exceptions 

Header 


Availability 

dli.h 

dlpdfdocdestroy 




1 The highLimit value is a trigger-point setting only, not a storage limit; the cache 

is allowed to Concepts grow beyond and that Facilities: point. The Guide highLimit to the DL value Pager is inspected Composition only at System 

document-destroy time when dlpdfdocdestroy is called, not before. The 

graphics cache may grow larger than the highLimit value during document 

creation, but will be reduced to the deleteLimit point before the next 

document is begun. 

2 As of DLI v3.0.11, the DLI graphics cache has been enhanced to use the default 



larger graphics cache files are advised to supply a filesystem to dlpdfinit which 

is capable of reliably handling files of the larger size. 








dlpdfinstancesetprogressmonitor 

(DLPDFINSTANCE *dliInst, ProgressMonitor pRec, void 

*progData) 


Description 

Parameters 

Return Value 

This call sets the progress monitor used when 

writing a document using the dlpdfdocwritepdf 

call, along with other calls 

which may take a large quantity of time. This 

progress monitor will be used for all documents 

created with the specified instance. 

• DLPDFINSTANCE *dliInst: The 

DLPDFINSTANCE for which to set the 

progress monitor 

• ProgressMonitor pRec: The progress 

monitor to use. See the Adobe Acrobat Core 

API Reference for details on creating and 

obtaining progress monitors. 

• void *progData: A pointer to client data 

which is passed to the progress monitor 

callbacks. See the Adobe Acrobat Core API 

Reference for details. 

void 

Exceptions 

Header 

dli.h 


Availability 



dlpdfmatrixrotate (ASFixedMatrix *Matrix, ASFixed 

Angle) 



Description 

Parameters 

Return Value 

Rotates a matrix counterclockwise by the specified 

angle after accepting a pointer to the 

matrix. 

• ASFixedMatrix *Matrix: Matrix to be 

rotated 

• ASFixed Angle: In degrees, as an 

ASFixed counterclockwise value 

void 

Exceptions 

Header 

dli.h 


Availability 



dlpdfmemfileacquire (ASPathName Name) 

Return Value: MDFile 

Description 

Parameters 

Return Value 

Acquires a Files In Memory representation for 

the file named FileName, previously created 

with an ASFileOpen call. It returns this file as 

an MDFile, which may then be used to obtain a 

representation of the file's contents. 

ASPathName Name 

MDFile 

Exceptions 

Header 


Availability 

dli.h 




dlpdfmemfiledata (MDFile File) 

Return Value: unsigned const char * 


Description 

Parameters 

Returns a pointer (of the size returned by the 

dlpdfmemfilesize function call) containing 

a memory representation of the file passed 

into the function. This should be neither altered 

nor freed, and should be copied by the application 

into the application’s memory area. 

MDFile File 

Return Value unsigned const char * 

Exceptions 

Header 


Availability 

dli.h 

dlpdfmemfileacquire, 

dlpdfmemfilerelease, 

dlpdfmemfilesize 



dlpdfmemfiledeleteonclose (MDFile File) 


Description 

Parameters 

Return Value 

This method marks a Files In Memory file to be 

removed from the filesystem once the last open 

filehandle for this file has been closed. No file is 

automatically removed from memory, unless 

this call has been made on a specific MDFile. 

MDFile File 

void 

Exceptions 

Header 


Availability 

dli.h 





dlpdfmemfilerelease (MDFile File) 

Return Value: int 


Description 

Parameters 

Return Value 

Relinquishes one acquisition as made by the 

dlpdfmemfileacquire call, and returns 

the number of acquisitions left on the file. 

MDFile 

Int 

Exceptions 

Header 


Availability 

dli.h 

dlpdfmemfileacquire 



1 An application should make one release call for each acquire call: the 

release call signals that the acquiring program no longer needs the file, and its 

resources may be safely freed.


dlpdfmemfilesetbuffer (MDFile File, unsigned 

char * Data, ASSize_t Size) 

Return Value: ASBool 

Description 

Parameters 

Return Value 

This method configures Files In Memory to 

directly use the buffer passed in as the file contents. 

Unlike dlpdfmemfilesetdata, this 

method does not copy the buffer; the file 

instance and buffer instance are one and the 

same. 

• MDFile File: File to be overwritten 

• unsigned char * Data: Memory to 

replace the File’s previous content. 

• ASSize_t Size 

ASBool: TRUE is returned if the file’s data 

buffer could be set to this memory, FALSE if it 

could not. 

Exceptions 

Header 


Availability 

dli.h 



dlpdfmemfilesetdata 



1 As of DLI v3.0.11, the dlpdfmemfilesetbuffer and 

dlpdfmemfilesetdata calls no longer rewind the memory files to position 0.


dlpdfmemfilesetdata (MDFile File, unsigned 

const char * Data, ASSize_t Size) 

Return Value: ASBool 


Description 

Parameters 

Return Value 

Sets the file passed in to contain the data passed 

to the function. This completely overwrites the 

file’s previous contents. 

• MDFile File: File to be overwritten 

• unsigned const char * Data: Data 

that replaces File content. 

• ASSize_t Size 

ASBool: TRUE is returned if the file could be 

set to this data, FALSE if it could not. 

Exceptions 

Header 


Availability 

dli.h 



dlpdfmemfilesetbuffer 



1 As of DLI v3.0.11, the dlpdfmemfilesetbuffer and 

dlpdfmemfilesetdata calls no longer rewind the memory files to position 0.


dlpdfmemfilesize (MDFile File) 

Return Value: ASSize_t 

Description 

Parameters 

Return Value 

Returns the size of the memory buffer which the 

dlpdfmemfiledata call will return if called. 

This is the smallest size of buffer that can 

accommodate the memory representation of 

Files In Memory passed in as a file. 

MDFile File 

ASSize_t 

Exceptions 

Header 


Availability 

dli.h 





dlpdfmemfilesys (void) 

Return Value: ASFileSys 


Description 

Parameters 

Return Value 

Returns the ASFileSys structure which represents 

the Datalogics Files In Memory file system.This 

file system will only be used if PDF 

output is requested. 

None 

ASFileSys 

Exceptions 

Header 


Availability 

dli.h 

dlpdfinit, 





1 This method is suitable as the second parameter for the dlpdfinit function, or 

for any other Adobe PDF Library function call requiring an ASFileSys record.


dlpdfmemfilesysgetmemusage (void) 

Return Value: ASSize_t 

Description 

Parameters 

Return Value 

This returns an ASSize_t with the current 

usage, in bytes, of memory for Files In Memory 

file contents by DLI. 

None 

ASSize_t 

Exceptions 

Header 


Availability 

dli.h 



dlpdfmemfilesyssetmemlimit 



dlpdfmemfilesyssetmemlimit (ASSize_t 

memLimit) 



Description 

Parameters 

Return Value 

This establishes an upper bound, in bytes, of the 

memory usage allowed for Files In Memory file 

contents by DLI. 

ASSize_t memLimit 

void 

Exceptions 

Header 


Availability 

dli.h 



dlpdfmemfilesysgetmemusage 



dlpdfmemfiletransientprefix (void) 

Return Value: const char * 

Description 

Parameters 

Returns a NULL-terminated string representing 

the prefix for the transient files 

None 

Return Value const char * 

Exceptions 

Header 


Availability 

dli.h 





1 Transient files are files which are to reside entirely within the bounds of Files In 

Memory, and are not to be written to disk upon file closure. All temporary files 

created by the Adobe PDF Library and DLI are automatically transient files when 

Files In Memory is activated. 

2 Applications which wish to write PDF files to memory areas should append this 

prefix to the beginning of all their file names. Files which do not start with this 

prefix will be written to disk upon file closure or upon program termination.


dlpdfpageaddlinkannotation (DLPDFPAGE 

*Page, ASFixedRect *Location, ASFixed *Border, ASFixed 

*Color, long PageNumber, Char *Fit, ASFixedRect *Where, 

ASFixed *Zoom) 



Description 

Parameters 

Creates a link annotation in the specified page. 

• DLPDFPAGE *Page: Represents a page. This 

structure is tracked within the package and 

destroyed when the document is destroyed. 

Pointers to this structure remain valid until 

the document is destroyed. 

• ASFixedRect *Location: The hot spot 

for the link will be located at the rectangle 

specified here. 

• ASFixed *Border: (Optional) An array of 

three ASFixed values in the order 

Horizontal Corner Radius, 

Vertical Corner Radius and Line 

Width, drawing a visible border around the 

hot spot. 

• ASFixed *Color: Optional pointer by 

which border color may be set. When used, 

this is assumed to point to an array of three 

ASFixed values, giving the color as Red, 

Green and Blue values.


Parameters (Continued) 

Return Value 

• long PageNumber: The zero-relative number 

of the page to which this link connects. The 

page referenced does not need to have been 

created yet. 

• Char *Fit: Must be a valid PDF fit type 

expressed as a string. The list of valid types 

are “Fit”, “FitH”, “FitV”, “FitBH”, 

“FitBV”, “FitR”, “FitB” and “XYZ”. 

See the Adobe PDF Library Reference Guide 

for explanations of the meaning of each fit 

type, and which values of the rectangle and 

zoom are used for each. 

• ASFixedRect *Where: The rectangle to be 

displayed. This is used to distinguish an 

annotation. Only portions of this rectangle 

are used, based on the Fit Type selected in 

Fit. 

• ASFixed *Zoom: Adjustment to size of link 

target display. 

CosObj: The actual link structure which may 

be modified by the user to access capabilities 

beyond this interface. 

Exceptions 

Header 


Availability 

dli.h 

dlpdfpageaddlinkannotationfromname, 

dlpdfpageaddtextannotation, 





1 Only internal destinations (within the same document) are supported in this 

method. Concepts and Facilities: Guide to the DL Pager Composition System 

2 Zero values in the rectangle will behave as PDViewNull values, as will a zero 

value for Zoom. 

3 The most common values used are XYZ as the fit type, Zero for Zoom, and the 

(X,Y) coordinates of the upper left hand edge of the desired target text in 

Where.top and Where.left. This will change to the target page and position 

the specified text so it is within the display window, leaving the Magnification 

factor where the user last set it.



(DLPDFPAGE *Page, ASFixedRect *Location, ASFixed 

*Border, ASFixed *Color, char *Target) 


Description 

Parameters 

Return Value 

Adds a new link to a page using the named destination 

rather than a specified destination. 

• DLPDFPAGE *Page 

• ASFixedRect *Location: Location of 

rectangle 

• ASFixed *Border 

• ASFixed *Color: Link color 

• char *Target 

CosObj 

Exceptions 

Header 


Availability 

dli.h 

dlpdfpageaddlinkannotation, 

dlpdfpageaddtextannotation, 




dlpdfpageaddtextannotation (DLPDFPAGE 


*Color, char *Title, char *Contents, int Open) 



Description 

Parameters 

Return Value 

Creates a text annotation within the specified 

page. 

• DLPDFPAGE *Page: Represents a page. 

This structure is tracked within the package 

and destroyed when the document is 

destroyed. Pointers to this structure remain 

valid until the document is destroyed. 

• ASFixedRect *Location: The lower-left 

corner of where the text annotation is to be 

displayed. 

• ASFixed *Border: (Optional) an array of 

three ASFixed values: Horizontal 

Corner Radius, Vertical Corner 

Radius and Line Width. 

• ASFixed *Color: (Optional) an array of 

three ASFixed values giving the color as 

Red, Green and Blue values. 

• char *Title: (Optional) displayed in the 

title bar of an open text annotation. 

• char *Contents: (Required) the displayed 

contents of the annotation. 

• int Open: A Boolean where TRUE will 

cause the annotation to be opened by default, 

while FALSE will cause it to be closed by 

default. 

CosObj 

Exceptions 

Header 

dli.h



Availability 






1 A page may contain any number of annotations. There are capabilities of 

annotations beyond those described here. To access those capabilities, modify the 

COS structure returned by this call.


dlpdfpageaddwebannotation (DLPDFPAGE 


*Color, char *URIDestination) 

Return value: CosObj 


Description 

Parameters 

Return Value 

Adds a new link to a page, using a URI (equivalent 

to URL) destination given by the URIDestination 

parameter. This URI is assumed to 

be in UTF-8 text format; support for URIs in 

other character sets is unavailable at this time. 


• ASFixedRect *Location 

• ASFixed *Border 

• ASFixed *Color 

• char *URIDestination: URI destination 

in UTF-8 text format. 

CosObj 

Exceptions 

Header 


Availability 

dli.h 



dlpdfpageaddtextannotation 



1 You should have your internet browser running before calling this procedure or 

you may receive a “browser is busy” error. Your browser can be specified in Adobe 

Acrobat or Adobe Reader via File->Preferences->Weblink.


dlpdfpagecosobj (DLPDFPAGE *Page) 


Description 

Parameters 

Return Value 

This function will return a COS structure that 

represents the page in the Adobe PDF Library. 

It may be used to apply COS Layer operations 

to the page beyond those functions defined in 

the package. 

DLPDFPAGE *Page 

CosObj 

Exceptions 

Header 

dli.h 


Availability 



dlpdfpagecreate (DLPDFDOC *Doc, ASFixed Width, 

ASFixed Height) 


Return Value: DLPDFPAGE* 

Description 

Parameters 

Return Value 

Exceptions 

Header 

Creates a new page in the current document, 

positioned to follow all other pages in the current 

document. 




• ASFixed Width: Must be specified as 

greater than zero; assumed to be in points. 

• ASFixed Height: Must be specified as 

greater than zero; assumed to be in points. 

DLPDFPAGE* 

genErrBadParam: Raised if the specified document 

does not exist. 

dli.h 


Availability 



dlpdfpagefindfromnumber (DLPDFDOC *Doc, 

long PageNumber) 

Return Value: DLPDFPAGE* 

Description 

Parameters 

Return Value 

Allows pages to be modified after creation without 

requiring pointers to all pages in the application. 

If the page number specified has not yet 

been created, a NULL pointer will be returned. 

The first page is considered to be page one. 




• long PageNumber 

DLPDFPAGE* 

Exceptions 

Header 

dli.h 


Availability 



dlpdfpagenumber (DLPDFPAGE *Page) 

Return Value: long 


Description 

Parameters 

Return Value 

Returns the sequence number of the specified 

page. This number may be used in conjunction 

with the PDDoc returned by dlpdfdocpddoc 

to acquire a PDPage for the specified page. This 

PDPage will permit Edit Layer functions to be 

applied to the page beyond those defined in this 

package. 

DLPDFPAGE *Page 

long 

Exceptions 

Header 

dli.h 


Availability 



dlpdfpagerotate (DLPDFPAGE *Page, PDRotate 

Angle) 


Description 

Parameters 

Return Value 

Rotates page clockwise in 90-degree increments. 

Angles specified will be reduced if necessary by 

360 degrees, then rounded to the nearest 90- 

degree increment. 


• PDRotate Angle 

void 

Exceptions 

Header 

dli.h 


Availability 



1 This call may be issued at any time after a page is created, and will be effective in 

PDF and Adobe PostScript.


dlpdfpagesetart (DLPDFPAGE *Page, ASFixedRect 

*Rect) 



Description 

Parameters 

Return Value 

Sets the Art box for the DLPDFPAGE provided 

as input to the function. Please see the "Page 

Boundaries" section of Prepress Support in the 

Adobe PDF Reference Manual for more details. 


• ASFixedRect *Rect 

void 

Exceptions 

Header 


Availability 

dli.h 

dlpdfpagesetbleed, 

dlpdfpagesetcrop, 

dlpdfpagesetmediabox, 

dlpdfpagesettrim 



dlpdfpagesetbleed (DLPDFPAGE *Page, 

ASFixedRect *Rect) 


Description 

Parameters 

Return Value 

Sets the Bleed box for the DLPDFPAGE provided 






void 

Exceptions 

Header 


Availability 

dli.h 

dlpdfpagesetart, 






dlpdfpagesetcrop (DLPDFPAGE *Page, ASFixedRect 

*Rect) 



Description 

Parameters 

Return Value 

Sets the Crop box for the DLPDFPAGE provided 






void 

Exceptions 

Header 


Availability 

dli.h 







dlpdfpagesetid (DLPDFPAGE *Page, char *Id) 


Description 

Parameters 

Return Value 

Adds an ID Entry to the page dictionary. This is 

generally a page’s FOLIO. 


• char *Id: ID entry. 

void 

Exceptions 

Header 

dli.h 


Availability 



dlpdfpagesetmediabox (DLPDFPAGE *Page, 

ASFixedRect *Rect) 



Description 

Parameters 

Return Value 

Sets the Media box for the DLPDFPAGE provided 

as input to the function. Please see the 

"Page Boundaries" section of Prepress Support 

in the Adobe PDF Reference Manual for more 

details. 



void 

Exceptions 

Header 


Availability 

dli.h 







dlpdfpagesettrim (DLPDFPAGE *Page, ASFixedRect 

*Rect) 


Description 

Parameters 

Return Value 

Sets the Trim box for the DLPDFPAGE provided 






void 

Exceptions 

Header 


Availability 

dli.h 




dlpdfpagesetmediabox 



dlpdfpathaddarc (DLPDFPATH *Path, ASFixed X, 

ASFixed Y, ASFixed Rad, ASFixed T1, ASFixed T2) 



Description 

Parameters 

Return Value 

Appends an arc segment to the current path. 

The current position will be set to the ending 

point. 

• DLPDFPATH *Path: Pointer to the path. 

• ASFixed X: Starting X position of the arc 

• ASFixed Y: Starting Y position of the arc 

• ASFixed Rad: Radius of the arc 

• ASFixed T1: Start angle for the arc 

• ASFixed T2: End angle for the arc 

void 

Exceptions 

Header 


Availability 

dli.h 

dlpdfpathaddarcn, 

dlpdfpatthaddarcto, 

dlpdfpathaddelliparc, 

dlpdfpathadddelliparcn, 




1 If the current position is not the starting position defined by 

(X,Y,Radius,StartAngle), then a straight line segment will be added from the 

current position to get there. A smooth curve of the specified radius will be drawn 

from that specified point counter-clockwise to the angle specified by EndAngle. 

2 If the starting and ending degree values specify the same angle, a full circle will be 

drawn, and the position following this command will be the specified position.


dlpdfpathaddarcn (DLPDFPATH *Path, ASFixed X, 

ASFixed Y, ASFixed Rad, ASFixed T1, ASFixed T2) 


Description 

Parameters 

Return Value 

Identical to dlpdfpathaddarc, except the 

arc will be drawn clockwise. 

• DLPDFPATH *Path is the pointer to the 

path. 

• ASFixed X 

• ASFixed Y 

• ASFixed Rad 

• ASFixed T1 

• ASFixed T2 

void 

Exceptions 

Header 


Availability 

dli.h 

dlpdfpathaddarc, 







dlpdfpathaddarcto (DLPDFPATH *Path, ASFixed 

X1, ASFixed Y1, ASFixed X2, ASFixed Y2, ASFixed Rad) 



Description 

Parameters 

Return Value 

Appends a straight line segment from the current 

position towards the first pair of X and Y 

coordinates specified, terminating when it intersects 

an arc connecting this line to a second line 

drawn between the first and second pairs of 

(X,Y) coordinates. The arc is circular, drawn at 

the specified radius. 


path. 

• ASFixed X1 is the X-axis position of the 

intersection of tangents. 

• ASFixed Y1 is the Y-axis position of the 

intersection of tangents. 

• ASFixed X2 is the X-axis position of a 

point defining the second tangent. 

• ASFixed Y2 is the Y-axis position of a point 

defining the second tangent. 

• ASFixed Rad is the radius of the arc. 

void 

Exceptions 

Header 


Availability 

dli.h 


dlpdfpatthaddarc, 






Xint1/ 

Yint1 

X1/Y1 

Xint2/ 

Yint2 

Current Position 

X2/Y2 


1 The two lines (CurrX,CurrY)->(X1,Y1) and (X2,Y2)->(X1,Y1) are joined by an 

arc of radius (Rad). The line segment from the current position to the start of the 

arc is drawn, followed by the arc itself, finishing at (Xint2,Yint2). The line 

segment from the end of the arc to the point (X2,Y2) is not drawn. 

2 The position following this command will be the intersection of the arc with the 

line (X2,Y2)->(X1,Y1), shown above as (Xint2,Yint2). If the two lines are 

colinear, a straight line segment is drawn from the current position to (X1,Y1), 

which then becomes the current point.


dlpdfpathaddclose (DLPDFPATH *Path) 



Description 

Parameters 

Return Value 

Appends a “close path” operator to the 

path. The current position after the path is 

closed is (1,-1). 

DLPDFPATH *Path is the pointer to the path 

void 

Exceptions 

Header 

dli.h 


Availability 



dlpdfpathaddcurve (DLPDFPATH *Path, ASFixed 

Ctrl1X, ASFixed Ctrl1Y, ASFixed Ctrl2X, ASFixed Ctrl2Y, 

ASFixed EndX, ASFixed EndY) 


Description 

Parameters 

Return Value 

Exceptions 

Header 


Availability 

Adds a spline or cubic Bézier curve to the path. 


path. 

• ASFixed Ctrl1X is the X position of a 

point which will be Control Point 1. 

• ASFixed Ctrl1Y is the Y position of a 






• ASFixed EndX is the X position which will 

be the end point of the curve. 

• ASFixed EndY is the Y position which will 


void 

genErrBadParam is returned if no starting 

point is specified. 

dli.h 

dlpdfpathaddcurver, 

dlpdfpathaddcurvev, 




Ctrl1X/ 

Ctrl1Y 


EndX/ 

EndY 

StartX/ 

StartY 

Ctrl2X/ 

Ctrl2Y 


1 A smooth curve (a cubic Bézier) will be drawn from the current position to the end 

position, under direction of the two control points. At completion of this 

operation, the current position will be the end position of the line. If the end 

position specified is identical to the current position, no segment will be appended 

and no notice will be given (optimization). 

2 All Bézier curves consist of four points. This method (as well as 

dlpdfpathaddcurver, dlpdfpathaddcurvev and dlpdfpathaddcurvey) 

uses current position as the starting point of the curve. The first two parameters of 

this method are the position of Control Point1, the second two parameters are the 

position of Control Point 2, and the last two parameters are the position of the 

end point of the curve. 

3 If no starting point is specified, the method will raise an exception 

(genErrBadParm).


dlpdfpathaddcurver (DLPDFPATH *Path, ASFixed 

Ctrl1X, ASFixed Ctrl1Y, ASFixed Ctrl2X, ASFixed Ctrl2Y, 

ASFixed EndX, ASFixed EndY) 


Description 

Parameters 

Return Value 

Identical to dlpdfpathaddcurve, except 

that the positions are expressed as relative distances 

from the current point, not absolute distances 

from the origin. 


path 









• ASFixed EndX is the X position which will 


• ASFixed EndY is the Y position which will 


void 

Exceptions 

Header 


Availability 

dli.h 

dlpdfpathaddcurve, 

dlpdfpathaddcurvev, 




dlpdfpathaddcurvev (DLPDFPATH *Path, ASFixed 

Ctrl2X, ASFixed Ctrl2Y, ASFixed EndX, ASFixed EndY) 



Description 

Parameters 

Return Value 


that both the start and first control point are 

assumed to be the current position. 

• DLPDFPATH *Path: The pointer to the 

path. 

• ASFixed Ctrl2X: The X position of a 


• ASFixed Ctrl2Y: The Y position of a 


• ASFixed EndX: The X position which will 


• ASFixed EndY: The Y position which will 


void 

Exceptions 

Header 


Availability 

dli.h 






EndX/ 

EndY 

StartX/ 

StartY 

Ctrl1X/ 

Ctrl1Y 

Ctrl2X/ 

Ctrl2Y 


1 This method is identical to dlpdfpathaddcurve, except that both the start and 

first control point are assumed to be the current position.


dlpdfpathaddcurvey (DLPDFPATH *Path, ASFixed 

Ctrl1X, ASFixed Ctrl1Y, ASFixed EndX, ASFixed EndY) 



Description 

Parameters 

Return Value 


that the second control point is assumed to be 

the ending position. 


path 

• ASFixed Ctrl1X 

• ASFixed Ctrl1Y 

• ASFixed EndX 

• ASFixed EndY 

void 

Exceptions 

Header 


Availability 

dli.h 






Ctrl1X/ 

Ctrl1Y 

StartX/ 

StartY 

EndX/ 

EndY 

Ctrl2X/ 

Ctrl2Y 


1 This method is identical to dlpdfpathaddcurve, except that the second control 

point is assumed to be the ending position.


dlpdfpathaddelliparc (DLPDFPATH *Path, 

ASFixed CentX, ASFixed CentY, ASFixed HRad, ASFixed 

VRad, ASFixed T1, ASFixed T2) 



Description 

Parameters 

Return Value 

Appends an arc segment to the current path. 

This method accepts seven parameters. 


path. 

• ASFixed CentX is the X-axis position of 

the arc center point. 

• ASFixed CentY is the Y-axis position of 


• ASFixed HRad is the horizontal radius of 

the ellipse defining an arc segment. 

• ASFixed VRad is the vertical radius of the 

same ellipse. The HRad and VRad functions 

support creating arc segments from an 

elliptical shape, as opposed to the circular 

shape described in dlpdfpathaddarc, 

although if the same value is used for both 

horizontal and vertical radii, it behaves 

identically to dlpdfpathaddarc. 

• ASFixed T1 is the beginning arc angle 

(where zero is directly to the right of center). 

• ASFixed T2 is the ending arc angle. 

void 

Exceptions 

Header 


dli.h 






Availability



1 If the current position does not coincide with the position defined by 

(CentX,CentY,HRad,VRad,StartAngle), then a straight line segment will be 

added from the current position to get there. A smooth curve of the specified 

radius will be drawn from that specified point counter-clockwise to the point 

specified by (CentX,CentY,HRad,VRad,EndAngle). The current position will be 

set to that ending point. If the starting and ending points specify the same angle, a 

full circle will be drawn. 

2 The position following this command will be the specified position.


dlpdfpathaddelliparcn (DLPDFPATH *Path, 

ASFixed CentX, ASFixed CentY, ASFixed HRad, ASFixed 

VRad, ASFixed T1, ASFixed T2) 



Description 

Parameters 

Return Value 

This method is identical to dlpdfpathaddelliparc, 

except that the arc will be drawn 

clockwise. 


path. 

• ASFixed CentX is the X-axis position of 


• ASFixed CentY is the Y-axis position of 


• ASFixed HRad is the horizontal radius of 

the ellipse defining an arc segment. 

• ASFixed VRad is the vertical radius of the 

same ellipse. The HRad and VRad functions 

support creating arc segments from an 

elliptical shape, as opposed to the circular 

shape described in dlpdfpathaddarc, 

although if the same value is used for both 

horizontal and vertical radii, it behaves 

identically to dlpdfpathaddarc. 

• ASFixed T1 is the beginning arc angle 

(where zero is directly to the right of center). 

• ASFixed T2 is the ending arc angle. 

void 

Exceptions 

Header 


Availability 

dli.h 








dlpdfpathaddelliparcto (DLPDFPATH *Path, 

ASFixed X1, ASFixed Y1, ASFixed X2, ASFixed Y2, ASFixed 

HRad, ASFixed VRad) 


Description 

Parameters 

Return Value 

Appends a straight line segment from the current 

position towards the first pair of X and Y 

coordinates specified, terminating when it intersects 

an arc connecting this line to a second line 

drawn between the first and second pairs of 

(X,Y) coordinates. The arc is elliptical, drawn at 

the specified horizontal and vertical radius. 

• DLPDFPATH *Path: The pointer to the 

path 

• ASFixed X1: The Xposition of the 

intersection of tangents 

• ASFixed Y1: The Yposition of the 

intersection of tangents 

• ASFixed X2: The Xposition of the endpoint 

of the second tangent 

• ASFixed Y2: The Yposition of the endpoint 

of the second tangent 

• ASFixed HRad: The horizontal radius of 

the arc 

• ASFixed VRad: The vertical radius of the 

arc 

void 

Exceptions 

Header 


Availability 

dli.h 



dlpdfpathaddarcto, 




dlpdfpathaddline (DLPDFPATH *Path, ASFixed X, 

ASFixed Y) 



Description 

Parameters 

Return Value 

Draws a line from the current position to the 

specified new position. If the current position is 

the same as the new position, no line segment 

will be added to the path and no notice will be 

given. The current position following this command 

will be the specified position. 


path. 

• ASFixed X is the absolute X-axis position. 

• ASFixed Y is the absolute Y-axis position. 

void 

Exceptions 

Header 


Availability 

dli.h 




dlpdfpathaddliner (DLPDFPATH *Path, ASFixed X, 

ASFixed Y) 


Description 

Parameters 

Return Value 

Draws a line from the current position for the 

given X and Y offset distances (i.e. this is a 

movement relative to the current position). If 

the distances specified are both zero, no line 

segment will be added to the path and no notice 

will be given. The position following this command 

will be the position derived by applying 

the X and Y offsets to the prior position. 


path. 

• ASFixed X is the X-axis distance to draw 

from the current X position to the new X 

position. 

• ASFixed Y is the Y-axis distance to draw 

from the current Y position to the specified Y 

position. 

void 

Exceptions 

Header 


Availability 

dli.h 




dlpdfpathaddmove (DLPDFPATH *Path, ASFixed 

X, ASFixed Y) 



Description 

Parameters 

Return Value 

Moves the current position to the specified new 

position without adding a stroked line. If the 

current position is the same as the specified new 

position, no adjustment of the current position 

will be added to the path and no notice will be 

given. The position following this command 

will be the specified position. 


path. 

• ASFixed X is the specified X-axis position. 

• ASFixed Y is the specified Y-axis position. 

void 

Exceptions 

Header 


Availability 

dli.h 




dlpdfpathaddmover (DLPDFPATH *Path, ASFixed 

X, ASFixed Y) 


Description 

Parameters 

Return Value 

Moves the current position for the given X and 

Y offset distances (i.e. this is a movement relative 

to the current position). If the distances 

specified are both zero, no movement will be 

added to the path and no notice will be given. 

The position following this command will be 

derived by applying the X and Y offsets to the 

prior position. 


path. 

• ASFixed X is the X-axis distance to move 

from the current X position to the new X 

position. 

• ASFixed Y is the Y-axis distance to move 

from the current Y position to the new Y 

position. 

void 

Exceptions 

Header 


Availability 

dli.h 




dlpdfpathaddrect (DLPDFPATH *Path, ASFixed X, 

ASFixed Y, ASFixed Width, ASFixed Depth) 



Description 

Parameters 

Return Value 

Draws a rectangle. 


path 

• ASFixed X is the X position of a point 

which will be one corner of the box 

• ASFixed Y is the Y position of a point 

which will be one corner of the box 

• ASFixed Width will be the width of the 

box 

• ASFixed Depth will be the depth of the 

box 

void 

Exceptions 

Header 

dli.h 


Availability 



1 If the specified position is not the current position, a MoveTo to the specified 

position will be made. A rectangle will be added to the path, starting at the 

specified position and proceeding upward (unless Depth is negative) and to the 

right (unless Width is negative). The end position after this operation will be the 

specified position. If Width and Depth are both zero, no segment will be 

appended, but the current position will still be updated.


dlpdfpatharray (DLPDFPATH *Path) 

Return Value: ASFixed* 

Description 

Parameters 

Return Value 

This method will return a pointer to the first 

member of the array of ASFixed integers, 

which is the path. 

DLPDFPATH *Path is the pointer to the path. 

ASFixed* 

Exceptions 

Header 

dli.h 


Availability 



dlpdfpathclear (DLPDFPATH *Path) 



Description 

Parameters 

Return Value 

Exceptions 

Header 

Used to reset a path, this method will set the 

current position to UNSET, set the matrix to 

UNITY, and remove any path segment present. 

It will not deallocate the array used to hold the 

path, however, since its primary purpose is to 

lower the overhead associated with allocation 

and deallocation. 


void 

genErrBadParam is raised if the method is 

called with a NULL pointer. 

dli.h 


Availability 



dlpdfpathcreate (void) 

Return Value: DLPDFPATH* 

Description 

Parameters 

Return Value 

Exceptions 

Header 


Availability 

Creates a new, empty DLPDFPATH structure. 

None 

DLPDFPATH* 

genErrNoMemory 

dli.h 




dlpdfpathcurrentx (DLPDFPATH *Path) 



Description 

Parameters 

Return Value 

This method will return the current X position 

as an ASFixed value. 

DLPDFPATH *Path is the pointer to the path 

ASFixed 

Exceptions 

Header 


Availability 

dli.h 

dlpdfpathcurrenty 



dlpdfpathcurrenty (DLPDFPATH *Path) 


Description 

Parameters 

Return Value 

This method will return the current Y position 

as an ASFixed value. 


ASFixed 

Exceptions 

Header 


Availability 

dli.h 

dlpdfpathcurrentx 



dlpdfpathdestroy (DLPDFPATH *Path) 



Description 

Parameters 

Return Value 

Exceptions 

Header 


Availability 

Destroys a DLPDFPATH structure and frees its 

resources. 

DLPDFPATH *Path: The pointer to the path 

void 

genErrBadParam: Raised if the pointer is not 

valid 

dli.h 




dlpdfpathsetmatrix (DLPDFPATH *Path, 

ASFixedMatrix *Matrix) 


Description 

Parameters 

Return Value 

Exceptions 

Header 

This method will accept a pointer to a path and 

a pointer to a matrix. The specified matrix will 

be concatenated to the matrix of the container 

in each container in which this path is drawn. 

This allows the user complete and flexible control 

of the shape drawn by the path. 


path 


void 

genErrBadParam exception is raised if the 

pointer to the path or the matrix is NULL 

dli.h 


Availability 



dlpdfpathsize (DLPDFPATH *Path) 

Return Value: ASInt32 


Description 

Parameters 

Return Value 

This method will return the current size of the 

path array as an integer. 


ASInt32 

Exceptions 

Header 

dli.h 


Availability 



dlpdfpatterncreate (DLPDFDOC *Doc, 

DLPDFCONTENT *Content, ASFixedRect *BBox, 

ASFixedMatrix *Matrix, int Colored, int TileType, ASFixed 

XStep, ASFixed YStep) 

Return Value: DLPDFPATTERN* 

Description 

Parameters 

Return Value 

This creates a patterned color space and returns 

a pointer to that space. The pointer may be used 

in dlpdfcontentusefillpattern or 

dlpdfcontentusestrokepattern to 

apply this colored pattern to all following material. 

All patterns will be destroyed and their 

handles invalidated at the destruction of the 

document that contains them. 

• DLPDFDOC *Doc: represents the document 








• ASFixedRect *BBox 


• int Colored 

• int TileType 

• ASFixed XStep 

• ASFixed YStep 

DLPDFPATTERN* 

Exceptions 

Header 


Availability 

dli.h 

dlpdfcontentusefillpattern, 




dlpdfpatternrotate (ASFixedMatrix *Matrix, 

ASFixed Angle) 



Description 

Parameters 

Return Value 

This function will modify the specified matrix 

so as to effect counter-clockwise rotation of any 

marks drawn via this matrix. Angle is an angle 

in degrees and fractions of degrees. 


• ASFixed Angle 

void 

Exceptions 

Header 

dli.h 


Availability 



dlpdfpageplacesignature (DLPDFPAGE *Page, 

DLPDFSIGNATURE *Sig, ASFixedRect *imageBBox) 


Description 

Parameters 

Return Value 

This call associates a digital signature to a page 

in the PDF file generated by DLI. This call is 

required for all digital signatures including 

invisible ones, although for invisible digital signatures, 

the imageBBox is ignored and may be 

NULL. 

• DLPDFPAGE *Page: page to receive the 

signature 

• DLPDFSIGNATURE *Sig: signature to be 

associated with the page 

• ASFixedRect *imageBBox: bounding 

box in which signature must fit. 

void 

Exceptions 

Header 


Availability 

dli.h 

dlpdfdoccreatesignature, 





dlpdfseterrorfile (FILE *errorFilePtr) 



Description 

Parameters 

Return Value 

Sets file to which error messages will be logged. 

File *errorFilePtr: By default error messages 

are logged to stderr 

void 

Exceptions 

Header 


Availability 

dli.h 

dlpdfsetwarningfile 



dlpdfsetwarningfile (FILE * warningFilePtr) 


Description 

Parameters 

Return Value 

Sets file to which warning messages will be 

logged. 

File *warningFilePtr: By default warning 

messages are not logged. 

void 

Exceptions 

Header 


Availability 

dli.h 

dlpdfseterrorfile 




(DLPDFSIGNATURE *signature, void (*dataCallback)(char *, 

int)) 



Description 

Parameters 

Return Value 

This is an optional call for clients using PKCS 

#7 certificates. A callback function is supplied 

for the signature. 

• DLPDFSIGNATURE *signature: signature 

with which PKCS #7 certificate will be 

associated 

• void (*dataCallback)(char *, 

int): callback function, called during the 

dlpdfdocwritepdf function call; see 

Technical Notes below. 

void 

Exceptions 

Header 


Availability 

dli.h 





1 The callback is called during the dlpdfdocwritepdf function with binary 

information from the PDF file. This information will be in sequential pieces, and 

may be used to generate the PDF document hash value. The information is 

supplied as binary values in the character buffer; the length to read is supplied as 

the second parameter. 

• A length of 0 (zero) passed in the callback function indicates that no further data is 

to be read, and the hash may be finalized.


dlpdfsignaturesetpkcs7cert (DLPDFSIGNATURE 

*signature, int maxLen, int (*genPKCS7Cert)(char *)) 


Description 

Parameters 

Return Value 

This function sets the certificate generation callback 

for DLPDFSIGNATUREs of type 

dlpdfsigacropkcs7 and dlpdfsigverisign. 


with which certificate will be associated 

• int maxlen: number of bytes provided to 

the genPKCS7Cert callback 

• int (*genPKCS7Cert)(char *): callback 

function, called during the 



void 

Exceptions 

Header 


Availability 

dli.h 






1 For these signature types, dlpdfsigacropkcs7 and dlpdfsigverisign, the 

application using DLI is required to generated a fully-formed PKCS #7 certificate 

with an MD5 checksum of the PDF document, encrypted with the private key 

corresponding to the public key in the certificate. The RSA public-key algorithm 

with a 1024-bit key length is used. 

• The genPKCS7Cert callback is called by DLI during the dlpdfdocwritepdf 

function call. The callback is supplied a binary data buffer of length maxLen. The


first 16 bytes of this buffer contain the MD5 checksum (in binary) for the PDF 

document to sign. The callback must generate a PKCS #7 certificate as described 

above, and fill the data buffer with the certificate, in binary. The callback function 

must return the Concepts length to and read Facilities: from the data Guide buffer, to the in bytes. DL Pager Composition System 

NOTE: maxLen bytes are set aside in the output PDF file for the PKCS #7 

certificate, and will be written to the PDF file regardless of the actual certificate 

length. Callers should pass length values which are close to the certificate length, 

if possible.


dlpdfsignaturesetx509cert (DLPDFSIGNATURE 

*signature, char *certificate, int certLen, void 

(*encryptSHA1Hash)(char *)) 


Description 

Parameters 

Return Value 

This call associates an x.509 v3 certificate with 

a DLPDFSIGNATURE object created as a 

dlpdfsigacrox509 certificate digital signature. 


with which x.509 v3 certificate will be 

associated 

• char *certificate: a binary buffer in 

the certificate parameter; DLI will read 

certLen bytes from this buffer and make a 

copy for the PDF file's digital signature 

• int certLen: number of bytes to be read 

from certificate buffer 

• void (*encryptSHA1Hash)(char *): 

callback function, called during the 



void 

Exceptions 

Header 


Availability 

dli.h 





1 It is an error to call this with a DLPDFSIGNATURE object created as a different


certificate type. 

2 The last parameter is a required callback function. This function will be called 

during the dlpdfdocwritepdf function call. It will be passed a character string 


containing the SHA-1 hash for the PDF file being written, as a NULL-terminated 

string of hexadecimal digits using PKCS #1 padding, containing a BER OID 

(object identifier) for the SHA-1 algorithm. The buffer is 256 bytes long (not 

including the NULL terminator), and formatted as 

0001FFFF .. FF003021300906052B0E03021A05000414 

[ 40 hex digits for SHA-1 hash ] 

The callback function must encrypt this hash value with the private key 

corresponding to the public key in the signature's x.509 certificate, and fill the 

buffer passed in with 256 hexadecimal digits representing the encrypted value for 

the supplied BER formatted hash. A 1024-bit key is used for encryption 

operations. Note that the signed hash will not have padding, and must be exactly 

256 hexadecimal digits. Zeros must be used for padding, if required.


dlpdfterm (DLPDFINSTANCE * instance) 


Description 

Parameters 

Return Value 

Terminates the Adobe PDF Library and DLI. 

All active documents should be closed prior to 

this call. 

DLPDFINSTANCE *instance 

void 

Exceptions 

Header 


Availability 

dli.h 

dlpdfinit, 

dlpdfttload 



1 This will typically be one of the last calls of a program using DLI. 

2 In a multi-threaded application, each thread must do its own initialization and 

termination of the Library. 

3 dlpdfinit and dlpdfterm are the only methods which must not be enclosed in 

exception handlers (i.e. DURING/HANDLER/END_HANDLER statements), because 

they are not set up before initialization, and are freed during termination. 

4 As of DLI v3.0.11, the dlpdfterm call now removes memory files used for the 

dlpdfttload call if the Files In Memory filesystem is used, and if these files are 

no longer in use.


dlpdftext (void *Text, ASUns32 Length, ASAtom 

Encoding) 

Return Value: DLPDFTEXT* 


Description 

Parameters 

Return Value 

Returns a DLPDFTEXT structure for the given 

Text and Length, in the given Encoding. 

• void *Text: the text to be passed to the 

DLPDFTEXT structure 

• ASUns32 Length: Length of the Text 

string in bytes. 

• ASAtom Encoding: Encoding of the input 

Text; a valid ICU Encoding value; see 

Technical Notes below 

DLPDFTEXT* 

Exceptions 

Header 


Availability 

dli.h 

dlpdftextfromutf8, 

dlpdftextfromutf16be, 

dlpdftextfromutf16he, 

dlpdftextfromutf16le, 






1 Text passed to this method does not require a NULL terminator, since its Length is 

given as a calling argument. Conversely, the related methods listed above do not 

accept a Length argument, and assume that a NULL terminator is present. 

2 Valid ICU Encoding values for the Encoding argument of this method can be 

obtained via the dlpdftextshowencodingnames call.


dlpdftextadvance (DLPDFTEXT *Text, 

DLPDFFONT *Font, PDEGraphicState *GState, 

PDETextState *TState, ASFixed PointSize, 

ASFixed SetWidth, dlpdftext_X XMeaning, 

ASFixed Angle, ASFixedPoint *Advance) 


Description 

Parameters 

Return Value 

This method supplies the x and y advance for a 

string in a DLPDFTEXT area. 

• DLPDFTEXT *Text: the text structure to be 

acted upon 





drawing a path 

• PDETextState *TState: Current text 

state; should not be NULL. A zero-filled 


• ASFixed PointSize: Point size 

• ASFixed SetWidth: Set width 

• dlpdftext_X XMeaning: 

DLPDFTEXT_X_LEFT or 

DLPDFTEXT_X_RIGHT, used to indicate 

whether the starting location is the left or 

right end (respectively) of the text, 

distinguishing a left-to-right line order (e.g. 

English) from a right-to-left line order (e.g. 

Arabic) 

• ASFixed Angle: Angle of flow, in degrees, 

as an ASFixed counterclockwise angle 

• ASFixedPoint *Advance: The returned x 

and y position change after evaluation of the 

text 

void 

Exceptions


Header 

dli.h 



Availability 



dlpdftextdestroy (DLPDFTEXT *Text) 


Description 

Parameters 

Return Value 

This method destroys the indicated DLPDFTEXT 

instance. 

DLPDFTEXT *Text: the text structure to be 

acted upon 

void 

Exceptions 

Header 


Availability 

dli.h 

dlpdftext 



dlpdftextfromutf16be (void *Text) 



Description 

Parameters 

Return Value 


UTF16 big-endian Unicode Text string. 

void *Text: the text to be passed to the DLP- 

DFTEXT structure 

DLPDFTEXT* 

Exceptions 

Header 


Availability 

dli.h 

dlpdftext, 









1 Text passed to this method requires a NULL terminator. Only the related method 

dlpdftext will accept unterminated text strings, since that method includes 

Length as an additional calling argument.


dlpdftextfromutf16he (void *Text) 


Description 

Parameters 

Return Value 


UTF16 host-endian Unicode Text string. 



DLPDFTEXT* 

Exceptions 

Header 


Availability 

dli.h 

dlpdftext, 













dlpdftextfromutf16le (void *Text) 



Description 

Parameters 

Return Value 


UTF16 little-endian Unicode Text string. 



DLPDFTEXT* 

Exceptions 

Header 


Availability 

dli.h 

dlpdftext, 













dlpdftextfromutf32be (void *Text) 


Description 

Parameters 

Return Value 


UTF32 big-endian Unicode Text string. 



DLPDFTEXT* 

Exceptions 

Header 


Availability 

dli.h 

dlpdftext, 













dlpdftextfromutf32he (void *Text) 



Description 

Parameters 

Return Value 


UTF32 host-endian Unicode Text string. 



DLPDFTEXT* 

Exceptions 

Header 


Availability 

dli.h 

dlpdftext, 













dlpdftextfromutf32le (void *Text) 


Description 

Parameters 

Return Value 


UTF32 little-endian Unicode Text string. 



DLPDFTEXT* 

Exceptions 

Header 


Availability 

dli.h 

dlpdftext, 













dlpdftextfromutf8 (void *Text) 



Description 

Parameters 

Return Value 


UTF8 Unicode Text string. 



DLPDFTEXT* 

Exceptions 

Header 


Availability 

dli.h 

dlpdftext, 













dlpdftextlength (DLPDFTEXT *Text) 

Return Value: ASUns32 

Description 

Parameters 

Return Value 

This method returns the length, in bytes, of the 

buffer for the stored string. NULL string terminators 

are not stored, and thus are not counted 

as part of the length. 


acted upon 

ASUns32 

Exceptions 

Header 


Availability 

dli.h 

dlpdftext, 




dlpdftextshowencodingnames (char 

*FileName) 



Description 

Parameters 

Return Value 

Returns an output file of the given FileName, 

listing all valid Encoding names provided via 

the International Components for Unicode 

(ICU) module for use when calling dlpdftext 

to construct the DLPDFTEXT object. 

char *FileName: Name for the output file to 

be created 

void 

Exceptions 

Header 


Availability 

dli.h 

dlpdftext 



dlpdftextstring (DLPDFTEXT *Text) 

Return Value: char * 

Description 

Parameters 

This method returns the byte buffer for the 

stored string. 


acted upon 

Return Value char * 

Exceptions 

Header 


Availability 

dli.h 

dlpdftext, 




dlpdftexttocontent (DLPDFTEXT *Text, 

DLPDFCONTENT *Content, DLPDFFONT *Font, 

PDEGraphicState *GState, PDETextState *TState, 

ASFixed PointSize, ASFixed SetWidth, ASFixed 

XPos, ASFixed YPos, dlpdftext_X XMeaning, 

ASFixed Angle) 



Description 

Parameters 

This method pastes the DLPDFTEXT string into 

a DLPDFCONTENT area. 

• DLPDFTEXT *Text: the text structure to be 

acted upon 

• DLPDFCONTENT *Content: the target 

structure in which the text will be pasted 





drawing a path 




• ASFixed PointSize: Point size 

• ASFixed SetWidth: Set width 

• ASFixed Xpos: X position of starting point 

within DLPDFCONTENT 

• ASFixed Ypos: Y position of starting point 

within DLPDFCONTENT


Parameters (continued) 

Return Value 

• dlpdftext_X XMeaning: 

DLPDFTEXT_X_LEFT or 

DLPDFTEXT_X_RIGHT, used to indicate 

whether the starting location is the left or 

right end (respectively) of the text, 

distinguishing a left-to-right line order (e.g. 

English) from a right-to-left line order (e.g. 

Arabic) 

• ASFixed Angle: Angle of flow, in degrees, 

as an ASFixed counterclockwise angle 

void 

Exceptions 

Header 

dli.h 


Availability 



dlpdfttload (DLPDFINSTANCE *Instance, ASFile 

TTFont, ASAtom *Names, int NameLen) 

Return Value: int 


Description 

Parameters 

Return Value 

This method loads the given font from an 

ASFile TrueType or OpenType font file, or the 

fonts from a TrueType/OpenType Collection 

font file. These fonts are loaded into the supplied 

DLPDFINSTANCE. Fonts loaded in this 

manner are used before searching the system 

directories for fonts. 

• DLPDFINSTANCE *Instance: the 

DLPDFINSTANCE for which the font(s) will 

be loaded 

• ASFile TTFont: fonts from file or 

collection to be loaded 

• ASAtom *Names: pointer to font 

ASAtom(s) to be loaded (one or more) 

• int NameLen: number of ASAtom *Names 

to be completed 

int: Number of fonts loaded 

Exceptions 

Header 

dli.h 


Availability 




1 This method does not fully support Adobe CFF-format OpenType font files. 

CMaps as defined in the PDF Reference Manual should be used for these fonts. 

Datalogics recommends creating them as CIDType0 fonts, using 

dlpdfcontentwidetext for setting text. 

2 DLI does not search directory paths or environmental variable entries for fonts 

loaded via dlpdfttload. 

3 If a given font file has already been loaded, dlpdfttload returns a -1, and does 

not re-parse the font file (for performance reasons). 

4 As of DLI v3.0.11, the dlpdfterm call now removes memory files used for the 

dlpdfttload call if the Files In Memory filesystem is used, and if these files are 

no longer in use.


GetGraphicFromList (DLPDFDOC *Doc, char 

*Name) 



Description 

Parameters 

Return Value 

Obtains a DLPDFIMAGE* by specifying the target 

document and the key for the graphic file. 

• DLPDFINSTANCE *Instance: Represents 

the document structure and the current status 

of the document at all times. 


DLPDFIMAGE*: NULL is returned if the graphic 

is not found. 

Exceptions 

Header 


Availability 

dli.h 

LoadGraphicList 

Available on OS/390 only


LoadGraphicList (char *ListFileName) 


Description 

Parameters 

Return Value 

Reads a cross-reference file which maps graphics 

keys to their physical location. The cross-reference 

table is accessed by the 

GetGraphicFromList method, and, once 

read, is stored in memory for the duration of 

the job. 

char *ListFileName: File name 

void 

Exceptions 

Header 


Availability 

dli.h 

GetGraphicFromList 

Available on OS/390 only



Index 

I.i 

Index 

A 

A key 

Use in Links 13.9 

AcroForm (Sample DLI Application) 17.18 

action (parameter) 

Use in Annotations and Links 13.2 

Action Dictionary 

Use in Links 

Creating Replacement 13.9 

Modifying 13.9 

Actions 

in Annotations and Links 13.3 

Adobe Acrobat 1.8 

Adobe Acrobat Distiller 1.12, 2.6 

Adobe Distiller 17.7 

Adobe Normalizer 11.2, 17.7 

Adobe Reader 1.7, 1.8, 1.12, 2.3, 2.6, 

4.10, 13.4, 14.1, 17.9, A.114 

Adobe Technical Notes 

#5189 (Adobe PDF Library Overview) 

1.10 

#5190 (Acrobat Core API Overview) 

1.10 

#5191 (Acrobat Core API Reference) 

1.10 

#5414 (PDF Library Supplement to the 

Acrobat Core API) 1.11 

#5425 (AcroColor API Reference) 1.10 

ADOBECMP 

OS/390 Location Search 4.15 

AdobeFnt.lst 2.3 

Efficient use of 2.3 

Naming variations 2.3 

Search path definition via PDFLDataRec 

2.3 

Use in Default Search Path Suppression 

1.20, 1.21 

ADOBERES 

OS/390 Location Search 4.15 

allocProc 

Use in Setting Memory Allocation 

Routines 2.5 

Annotation Dictionary 


Annotations 

action (parameter) 13.2 

Border Specification 13.4 

Color Specification 13.4 

Components 13.2 

Content 13.4 

hot spot (parameter) 13.2 


Link 

Overview 13.2 

Modifying for Other Actions 13.2 

Open/Close Flag 13.4 

Opening the Document with 

Annotations Showing 14.6 

Text 

Overview 13.2 

Title 13.4 

Annotations (Sample DLI Application) 17.15 

Annotations and Links 

Borders 

Color 13.3 

Definition 13.3 

Calls 13.4, 13.6, 13.7, 13.8 

Colors 

Links 13.3 

Text Annotations (when closed) 13.3 

ArcTo (PostScript operator) 8.8, A.4 

ASBool 

Use in Documents, Beginning and 

Ending 3.2 

ASCII 

Use in Displaying Images 11.12 

ASCII85 


ASFile 17.16 

ASFileSys 

Specifying an Alternate File System via 

dlpdfinit 2.9 

Use in Image Search using Files in

I.ii 


Memory 1.20, 2.11 

Use in Initializing and Terminating via 

DLI 2.9, 2.11 

Use in Specifying an Alternate File 

System 2.10 

ASFixed 

Use in Basic Color Spaces 

Device Gray 12.7 

Use in Color Channels 

Definitions 12.6 

Inversion Correction 12.6 

Precision Correction 12.6 

Use in Color Description 12.2 

ASFixedMatrix 

Use in Line Drawing 10.15 

ASFixedRect 


ASFixedRectangle 

Use in Annotations and Links 13.4, 

13.5 

hot spot Definition 13.2 

ASGetErrorString 

Use in Error Handling 16.3, 16.4, 16.5 

ASGetExceptionErrorCode 

Use in Error Handling 16.3 

ASPathName 

Use in Writing PDF Output to Memory 

2.16 

ASSize_t 


2.16 


B 

Background patterns, creating 17.17 

Backwards Compatibility, Ensuring 1.12, 2.7 

BBox (parameter) 

Use in Content Interface Calls 8.19 


Use in Forms 9.3 

Bezier Curve 

Use in Line Drawing 

Basic points 10.12, A.132 

Calls 10.12, 10.13 

Parameters 10.12, A.132 

Bézier curve 8.15, 8.16, 8.17 

Bitmaps 

Image Conversion from 11.2 

Use in Image Color Spaces 12.3 

blobs (Binary Large OBjects) 17.16 

Bookmarks 

Accessing DLPDFOUTLINE fields 14.5 

Building Multiple Trees 14.2 

Calls 14.3, 14.4, 14.5 

DLPDFOUTLINE 14.2, 14.4 

DLPDFOUTLINE->Count 14.5 

DLPDFOUTLINE->Obj 14.5 

DLPDFOUTLINE->Open 14.5 


Opening Document with Annotations 

Showing 14.6 

Outline Tree 14.2 

Overview 14.2 

PageMode 14.6 

PDViewDestNull 14.3 

Border 


Border (parameter) 

Use in Annotation Dictionary 13.9 

BoundingBox (PostScript statement) A.87 

Browser 

Specifying via Acrobat 13.7 

C 

CalGray 

Use in Color Spaces 

Basic 12.9 

Calibrated Gray Scale 12.5 

calloc 

Alternate Routines for 2.5 

PDFInit.h Interface to 2.5 

CalRGB 


Basic 12.9 

Cautions 

Color Models must be Freed before 

Closing 12.3 

Do not Exit from within Error Handler 

16.2 

Initialize pre-v6.1 Library and DLI only 

once 2.9 

Invalid Font Creation 4.9 

Scale Before Rotating Image 10.16 

Transformation, Undesirable Side- 

Effects via dlpdfcontentrotate 7.3 

CGM (Computer Graphics Metafile) 

Use in Graphical Language Forms 11.5 

CIDToGID Conversion Map 4.3 

CIDType2 font

Index 

I.iii 

Terminology usage 4.4 

Clipping Path A.7 


CMYK Color 

Collapsing to Gray 12.16 

Converting to RGB 12.18 


Use in ICC Based Color Profile 12.10 

Color 

Color Description Components 12.2 

Converting Values to Binary 12.6 

of Annotations and Links 13.3 


Use in Images 12.3 

Use with PDFGraphicState 12.2 

Color (parameter) 


Color Channels 

Inversion Correction 12.6 

Precision Correction 12.6 

Value Conversion and Inversion 12.6 

Values for 12.6 

Color Models 

/DeviceCMYK 

Order of Values Assumed 11.6 


/DeviceGray 


/DeviceRGB 

Order of Values Assumed 11.6 


/Indexed 


Order of Values 11.6 

Color Profile 


Basic 12.10 

Color Spaces 

Advanced 

DeviceN 12.11 

Indexed 12.12 

Overview 12.11 

Patterned 12.12 

Separation 12.11 

Basic 

Calibrated Gray 12.8 

Calibrated RGB 12.9 

CIE Calibrated Color 12.7 

CIE Lab 12.9 

Device CMYK 12.8 

Device Gray 12.7 

Device RGB 12.8 

ICC Based 12.10 

Conversion of Values between Models 

CMYK To Gray 12.16 

CMYK to RGB 12.18 


RGB to CMYK 12.17 

RGB to Gray 12.16 

Creating and Destroying 12.3 

Patterned 

Building 12.13 

Repeating References 12.14 

ColorSpace 


Comments 

Use in Adding to Content Elements 8.22 

Compression 

Activating 3.3, A.41 

Calls 3.3 

Flate 



Ending 3.3, A.41 


Inversion 7.4 

Overview 7.2 

Scaling 7.3 

Content Elements 

representation by DLPDFCONTENT 8.2 

Content Interface Calls 8.3 

Adding Comments to Content Elements 

8.22 

Calls 8.22 

Associating Content to Page 8.21 

Calls 8.21 

Control Structures 8.2 

Creation and Positioning 8.3 

Calls 8.3, 8.4 

Line Drawing 8.5 

Calls 8.6, 8.7, 8.8 

Fill Color 8.6 

kPDEEoFill 8.6 

kPDEFill 8.6 

kPDEStroke 8.6 

Paint Operator 8.5 

PDEGraphicState 8.5 

Overview 8.2 

Paths 8.9 

Appending Line Segments 8.10

I.iv 


Calls 8.10, 8.11, 8.12, 8.13, 

8.14, 8.15, 8.16, 

8.17, 8.18 

Calls 8.9, 8.10 

Patterns 8.18 

Calls 8.19 

Referencing Predefined Structures 8.20 

Calls 8.20, 8.21 

Text Placement 8.4 

Calls 8.4 

Text Width Evaluation 8.4 

Calls 8.5 

Conventions, Document 1.7 

CosDictRemove 

Use in Links 

Replacing 13.9 

CosDoc 

Use in Document Creation 3.2 

cosImage 


CosNull 


CosObj 


13.9 


CosStructure 


Cross-Reference File, OS/390 


CTM Matrix 


Current Point 



D 

dash 


Dashed and Dotted Lines 10.18 

Data Structure, Library 2.2 

DDName 


Dest (parameter) 


Use in Bookmarks 14.5 

Use in Links 

Replacing 13.9 

Destination 

Adding to Name Tree 13.8 

Obtaining Name 13.8 

Use in Links 13.7, 13.8 

Use of, vs. Name 13.6 

Destination Dictionary 


DeviceCMYK 

Creating Color Space for 12.4 


Advanced 12.12 

Basic 12.8 

DeviceGray 




Basic 12.7 

DeviceN 


Advanced 12.11, 12.12 

DeviceRGB 




Basic 12.8 

Digital Signatures 

Appearance layers 15.3, 15.4 

Calls 

dlpdfdoccreatesignature 15.4 


15.4 

dlpdfpageplacesignature 15.6 

dlpdfsignaturesetdatacallback 15.6 

dlpdfsignaturesetpkcs7cert 15.5 

dlpdfsignaturesetx509cert 15.5 

Components of 15.3 

imageBBox (signature bounding box) 

15.6 


Overview 15.2 

Public and Private Keys 15.2 

sigType (plug-in compatibility) 15.4 

dirList 

Use in Setting Resource Directories 2.3 

DLExceptionCode 

Use in Error Handling 16.4, 16.5 

DLExceptionFlag 

Use in Error Handling 16.4, 16.5 

DLExceptionMessage 


DLI 

DLI-selected PDF Level Declarations 2.7

Index 

I.v 

How to Create a PDF Document 1.2 

Initialization in DLI v3.0 1.14 


Overriding DLI-selected PDF Level 

Declarations 2.7 

Required Initialization 1.3 

DLPDFCONTENT 8.2 

Use by dlpdftexttocontent 1.17 



Use in Patterned Colors 12.2 

Use with CIDType2 fonts 4.4 

dlpdfcontent objects 1.2 

dlpdfcontentarc A.2 



dlpdfcontentarcn A.3 



dlpdfcontentarcto A.4 



dlpdfcontentcircle A.6 



dlpdfcontentclip A.7 


dlpdfcontentclipend A.8, A.9 

Use in Content Interface Calls 8.6, 8.7 


dlpdfcontentcomment A.10 


dlpdfcontentcreate A.11 


dlpdfcontentdrawpath 

Use in Line Drawing 10.7, 10.14 

dlpdfcontentellipse A.12 



dlpdfcontentfontskew A.13 

dlpdfcontentgstate A.14 


dlpdfcontentline A.15 



dlpdfcontentpath A.16 

Use in Content Interface Calls 8.6, 8.7 

Use in Line Drawing 8.6, 10.2, 10.6 

dlpdfcontentpieslice A.12, A.18 



dlpdfcontentpieslicen A.19 



dlpdfcontentrect A.21 



dlpdfcontentreferenceform A.23 



dlpdfcontentreferenceimage A.24 

Usage example 8.21 



dlpdfcontentrotate A.26 


dlpdfcontentscale A.27 


dlpdfcontenttext A.28, A.35 


dlpdfcontenttextwidth A.30, A.38 


dlpdfcontenttopage A.31 


dlpdfcontenttranslate A.32 


dlpdfcontentusefillpattern A.33, A.34, 

A.155 





dlpdfcontentusestrokepattern A.34, A.155 




dlpdfcontentwidetext A.35 

Updates in DLI v3.0 1.17 


dlpdfcontentwidetextwidth A.38 


DLPDFDOC 2.7, A.46 

EmbedFonts 


Ending 3.3 

Use in Creation Calls in DLI 

Font Searching Sequence 4.7 

Repetitive Calling 4.6 


Use in Document Status 3.2

I.vi 



Ending 3.2 

Encryption 3.4, 3.5 



Use in Multiple Document Creation 3.2 

dlpdfdocasciips A.39 

What’s New in DLI v3.0 1.16 

dlpdfdoccomplete A.40 

dlpdfdoccompress A.41 


Ending 3.3 

dlpdfdoccosdoc A.42 

dlpdfdoccreate A.43 

Modifications in DLI v3.0 1.19 

Updates in DLI v3.0 1.14, 1.18 


Ending 3.2 

dlpdfdoccreatesignature A.44 

Use in digital signatures 15.4 


dlpdfdoccreatewithinstance 

Removal from DLI v3.0 1.14, 1.19 

dlpdfdocdestroy A.46 

dlpdfdocembedfonts A.47, A.73, A.75, 

A.77, A.79 


Ending 3.3 

Use of Document EmbedFonts Flag 4.5 

dlpdfdocencrypt A.48 


Ending 3.4, 3.5 

dlpdfdocHexGraphics A.50 

Removal from DLI v3.0 1.19 

dlpdfdoclinearize A.49 


Ending 3.4 

dlpdfdocmakethumbnails A.50 


Ending 3.4 

dlpdfdocnameadd A.51 



dlpdfdocnamefind A.52 


dlpdfdocoutline A.53 


dlpdfdocoutlineadd A.54 


dlpdfdocoutlineaddfromname A.56 


dlpdfdocoutlinecosobj A.57 

dlpdfdocoutlinefirst A.58 


dlpdfdocoutlinelast A.59 


dlpdfdocoutlinenext A.60 


dlpdfdocoutlineparent A.61 


dlpdfdocoutlineprev A.62 


dlpdfdocpddoc A.63, A.118 

Use in Page Interface 6.3 

dlpdfdocsetdocinfo A.64 


Ending 3.4 

dlpdfdocsetencoding A.65 


Ending 3.3 

dlpdfdocsetencryptkeylen A.66 


Ending 3.5 

dlpdfdocseterrorfile 


dlpdfdocsetformsascontent 


dlpdfdocsetpdfname A.68 


Ending 3.3 


2.15 

dlpdfdocsetpsname A.69 

Use required for dlpdfdoccreate 1.18, 

A.43 

dlpdfdocsetsignatureappearance A.70 



dlpdfdocsetwarningfile 


dlpdfdocsevenbitsafe 


dlpdfdocwritepdf A.68, A.71 

Use in digital signatures 15.5, 15.6 


Ending 3.4 

with dlpdfdocencrypt 3.5 


2.15, 2.16 

dlpdfdocwritePS A.69, A.72 


Index 

I.vii 


Ending 3.3 

Use required for dlpdfdoccreate 1.18, 

A.43 

DLPDFFONT 3.3, 4.4, 4.5, A.47 

Font Attributes 4.5 

Font Embedding Status 4.4 

Font Subsetting Status 4.4 

Use in Creation Calls in DLI 4.6 


WidthTable 4.7 

dlpdffontcreate A.73, A.75, A.77, A.79 

Use in Font Creation 4.6, 4.7 

Use in Font Searching Sequence 4.7 

Use in Loading and Creating Fonts 5.3, 

5.4 

Use in Multibyte Text Work 5.3 

dlpdffontcreateembedded 4.6, A.73, A.75, 

A.77, A.79 


Use in Loading and Creating Fonts 5.4 

dlpdffontcreatewithmetrics A.73, A.75, 

A.76, A.79 


Use in Loading and Creating Fonts 5.4 

Use in Matching System Fonts 4.9 

dlpdffontcreatewithmetricsembedded A.73, 

A.75, A.77, A.78 


dlpdffontverifytext 


DLPDFFORM 9.2 

Use in Digital Signatures 15.3, 15.4 

dlpdfformcreate A.80 


dlpdfformdestroy A.81 


DLPDFIMAGE 

Use in Displaying Images 11.2, 11.6, 

11.10, 11.12, 11.13 

dlpdfimagecreatefrombmp A.82 



dlpdfimagecreatefromfile A.84 


Use in Image Search using Files in 

Memory 1.21, 2.11 

dlpdfimagecreatefrompdf A.85 


dlpdfimagecreatefromps A.87 

dlpdfimagegetsize A.88 




dlpdfinit A.90 

Use in Multi-Thread Initializations 

2.13 

Caution on Multiple Initializations of 

Library 2.9 

Error Handler not required 3.2, A.91, 

A.165 

Invoking Files in Memory 17.2 

Note on Writing PDF Output to Memory 

2.10 

Specifying an Alternate File System 2.10 

Updates in DLI v3.0 1.14, 1.18 


1.21 

Use in Files in Memory 2.8 

Use in Initializing and Terminating the 

Library 2.12 

Failure to Initialize 2.9 


DLI 2.9, 2.11, 2.12 


System 2.10 

Use in Terminating Library 2.11 

Using a Graphics Cache 2.10 

DLPDFINSTANCE 

Addition in DLI v3.0 1.13 

Unicode font translation via ICU 4.3 

Use by dlpdfttload 1.17 

Use in Creation Calls in DLI 


Use in dlpdfdoccreate 1.18, 1.19 


Library 2.12 



Use in Terminating Library 2.11, 2.12 

dlpdfinstancesetcancelproc A.92 

dlpdfinstancesetgrcachelimits A.93 


dlpdfinstancesetprogressmonitor A.95 

dlpdfmatrixrotate A.96 


dlpdfmemfileacquire A.96, A.97 


2.16

I.viii 


dlpdfmemfiledata A.98, A.99 


2.16 

dlpdfmemfiledeleteonclose A.99 

Note on usage for file deletion 1.15 


dlpdfmemfilerelease A.100 


2.16, 2.17 

dlpdfmemfilesetbuffer A.101 


dlpdfmemfilesetdata A.102 

Differences from dlpdfmemfilesetbuffer 

A.101 


Memory 1.20, 2.11 


2.17 

dlpdfmemfilesize 2.16, A.103 


2.16 

dlpdfmemfilesys A.104 

Use in Files in Memory 2.8 


Memory 1.20, 2.11 


Library 2.9 


DLI 2.11 


System 2.10 

dlpdfmemfilesysgetmemusage A.105 


dlpdfmemfilesyssetmemlimit A.106 


dlpdfmemfiletransientprefix A.107 


2.16, 2.17 

DLPDFOUTLINE 

Use in Bookmarks 14.2, 14.4, 14.5 

DLPDFPAGE 6.2 

dlpdfpage objects 1.2 

dlpdfpageaddlinkannotation A.108 



A.111 


dlpdfpageaddtextannotation A.112 


dlpdfpageaddwebannotation A.114 


dlpdfpagecosobj A.115 


dlpdfpagecreate A.116 


dlpdfpagefindfromnumber A.117 


dlpdfpagenumber A.118 


dlpdfpageplacesignature A.157 



dlpdfpagerotate A.119 


dlpdfpagesetart A.120 

dlpdfpagesetbleed A.121 

dlpdfpagesetcrop A.122 

dlpdfpagesetid A.123 


dlpdfpagesetmediabox A.124 

dlpdfpagesettrim A.125 

DLPDFPATH 

Effect of DLPDFPath.scaling on 

PDEGraphicState.lineWidth 10.17 

Use in Line Drawing 10.7, 10.8, 10.14, 

10.17 

Use in Paths 8.9 

dlpdfpathaddarc A.126 



dlpdfpathaddarcn A.127 



dlpdfpathaddarcto A.128 





dlpdfpathaddcurve A.131 



dlpdfpathaddcurver A.133 



dlpdfpathaddcurvev A.134 



dlpdfpathaddcurvey A.136 




Index 

I.ix 



dlpdfpathaddelliparcn A.140 


dlpdfpathaddelliparcto A.141 


dlpdfpathaddline A.142 



dlpdfpathaddliner A.143 



dlpdfpathaddmove A.144 



dlpdfpathaddmover A.145 



dlpdfpathaddrect A.146 



dlpdfpathadelliparc A.138 

dlpdfpatharray A.147 


dlpdfpathclear A.148 



dlpdfpathclosepath A.130 

dlpdfpathcreate A.149 



dlpdfpathcurrentx A.150 


dlpdfpathcurrenty A.151 


dlpdfpathdestroy A.152 



dlpdfpathsetmatrix A.153 



dlpdfpathsize A.154 


DLPDFPATTERN 8.18 

Parameters 

BBox 8.19 

Colored 8.19 

TileType 8.19 

Xstep 8.19 

Ystep 8.19 

dlpdfpatterncreate A.33, A.155 





dlpdfpatternrotate A.156 

dlpdfseterrorfile A.158 

dlpdfsetlevel 


dlpdfsetwarningfile A.159 

DLPDFSIGNATURE 

Use in Digital Signatures 15.5 

dlpdfsignaturesetdatacallback A.160 



dlpdfsignaturesetpkcs7cert A.161 



dlpdfsignaturesetx509cert A.163 



dlpdfterm A.165 

Use in Multi-Thread Initializations 

2.13 

Error Handler not required 3.2, A.91, 

A.165 

Updates in DLI v3.0 1.18 


Library 2.12 



Use in Terminating Library 2.11, 2.12 

DLPDFTEXT 17.21 


dlpdftext A.166 

Obtaining Encoding names via 


1.16, A.178 


Associated shortcut functions 5.6 


DLPDFTEXT (structure) 1.20, 5.2 

Addition in DLI v3.0 1.13 

Creating 5.5 


Shortcut Functions 5.6 


Use by dlpdftextdestroy 1.17 

Use by dlpdftexttocontent 1.17

I.x 


Use in dlpdftext (method) A.166 

Use in dlpdftextadvance A.167 

Use in dlpdftextdestroy A.169 

Use in dlpdftextlength A.177 

Use in dlpdftextstring A.179 

Use in dlpdftexttocontent A.180 

What’s New in DLI v3.0 1.16, 1.17 

Working with 5.7, 5.8, 5.9, 5.10 

dlpdftextadvance A.167 



dlpdftextdestroy A.169 



dlpdftextfromutf16be A.170 



dlpdftextfromutf16he A.171 



dlpdftextfromutf16le A.172 



dlpdftextfromutf32be A.173 



dlpdftextfromutf32he A.174 



dlpdftextfromutf32le A.175 



dlpdftextfromutf8 A.176 



dlpdftextlength A.177 



dlpdftextshowencodingnames A.178 



dlpdftextstring A.179 



dlpdftexttocontent A.180 



dlpdfttload A.182 

Clearance of memory files by dlpdfterm 

1.18 

Note on no default font searching 2.3 

Use in Font Searching Sequence 4.7 



Document Conventions 1.7 

Document Handle 


Document Information 

Calls 3.4 

Document Interface 

Use with Error Handler 3.2 

Document Opening 

with Annotations Showing 14.6 

Documents, Beginning and Ending 

Calls 3.2, 3.3, 3.4, 3.5 

Overview 3.2 


E 

E_RETURN(X) 


E_RTRN_VOID 


eMemFileSys 

Use in Files in Memory in DLI Samples 

17.3 

Encoding 

Generation of Grid via FontVerification 

(Sample DLI Application) 17.13 

Encoding Vector 4.10 

Encrypt (Sample DLI Application) 17.9 

Changing Security Settings 17.10 

DocOwner Password 17.10 

ValidUser Password 17.9 

Encryption 

Calls 3.5 

Setting Encryption Key Length 3.5 


Ending 3.4 

EPS 


EPS (Encapsulated PostScript) 


Use in Graphics (Sample DLI Application) 

17.6 

Error Handling 

ASGetErrorString 16.3 

ASGetExceptionErrorCode 16.3 

DURING 16.2, 16.3 

E_RETURN(X) 16.3

Index 

I.xi 

E_RTRN_VOID 16.4 

END_HANDLER 16.2, 16.3 

Exception Codes from Methods 16.3 

Exception Names 16.3 

HANDLER 16.2, 16.3 

Handler Constructs 

Multiple 16.3 

Risks of Returning from within 16.3 

Handler Mechanism 16.2 

OS/390 Platform Concerns 16.4 

Overview 16.2 

Errors 

Communication back to Application 

16.2 

Link 

"Browser is Busy" 13.7 

OS/390 

Not Using SAS/C 

ASGetErrorString 16.4, 16.5 

DLExceptionCode 16.4, 16.5 

DLExceptionFlag 16.4, 16.5 

DLExceptionMessage 16.5 

Using SAS/C 16.4 

Outer Error Catcher 16.2 

Examples 

Adding Outline Entries 14.4 

with a Named Destination 14.4 

Bitmapped Graphic via 

dlpdfimagecreatefrombmp 11.4 

Collapsing 

CMYK to Gray 12.17 

RGB to Gray 12.16 

Converting 

CMYK to RGB 12.18 

RGB to CMYK 12.18 

Creating 

Calgray Color Space 12.5 

Gray Color Space 

Assembler 12.4 

C coding 12.4 

Link Annotation 13.6 

Link To A Named Destination 13.7 

Named Destination 13.8 

Text Annotations 13.4 

Drawing a Rectangle and Ellipse in Path 

Operators 10.15 

Filling an Area with a Pattern 12.14 

Inserting 

EPSF Image with 


11.8 

PDF Image 

via dlpdfimagecreatefromfile 

11.10 

via dlpdfimagecreatefrompdf 

11.9 

Line Drawing Using Fixed Structure 10.6 

Modifying a Goto Link into a GotoR Link 

13.10 

Multiple Containers per Page with 

Rotation 7.6 

Setting the Page Mode to Display 

Navigation Pane 14.6 

Transparent Graphics via Imagemasks 

11.13 

Exception Handlers, Required Use 3.2 

Exceptions 


F 

Filename, Setting Output PDF 

Calls 3.3 

Files in Memory 

Activating within DLI Samples 17.2 

Activation 2.8 

MEMORY Command Line Argument, 

Use of 17.2, 17.3 

Use of dlpdfinit 17.2 

Use of eMemFileSys in DLI Samples 17.3 

Use of FileSystemType in DLI Samples 

17.3 

Files, Transient 2.15 

FileSystemType 

Use in Files in Memory in DLI Samples 

17.3 

fill (parameter) 


Fill Color 

Use in PDEGraphicState 10.2 

fillColorSpec 



Fit Type 


FitDescription 


FitType 


Use in Links 13.5

I.xii 


Values 

Fit 13.5 

FitB 13.5 

FitBH 13.5 

FitBV 13.5 

FitH 13.5 

FitR 13.5 

FitV 13.5 

XYZ 13.5 

Fixed Rectangle 


Flate Compression 


flatness 


FOLIO 6.3, A.123 

Font Dump 

Via FontVerification (Sample DLI 

Application) 17.13 


FontFaux (Sample DLI Application) 17.11 

Fonts 

Accessing 4.15 

OS/390-specific 4.15 

Calls 3.3 

Code Page Support 4.13 

Composite Fonts 

CIDType0 4.3 

CIDType2 4.3 

Overview 4.3 

Creation Calls in DLI 

Calls 4.7, 4.8, 4.11 


Width Table 4.10 


Matching Calls to System Fonts 4.9 

Overview 4.6 



Default Encoding Selection 3.3 

differences between characters and 

glyphs 4.2 

Embedding 

Document EmbedFonts flag 4.5 

Subsetting Limitations 4.5 

Font Dump via FontVerification (Sample 

DLI Application) 17.13 


Overview 4.2 

PDFLDataRec 

Use in Setting Resource Directories 

2.3 

Predefined Font Encodings 4.11 

Encoding Font Types Table 4.12 

Resources, Identifying Non-Standard 

Locations of 2.3 

Search Paths 2.3 

Simple Fonts 4.2 

Standard Encoding 

Default Setting 3.3 

Structure of a DLI Font 4.4 

Terminology usage 

CIDType2 font 4.4 

TrueType font 4.4 

Unicode 4.13 



Default Setting 3.3 

FontVerification (Sample DLI Application) 

17.13 

Encoding Grid 17.13 

Slow Feedback from 17.14 

Table of Contents 17.13 

Form XObjects 


Forms 9.2 

Calls 9.3 


Use of Bounding Box 9.3 

Content Complexity 9.2 

Destruction 9.2 

Overview 9.2 

Structure 9.2 

Use in Referencing Predefined 

Structures 8.20 

Forms XObjects 

Association with Content Structures 8.2 

Use in Content Interface 8.2 

free 



Free Software Foundation 1.4 

freeProc 


Routines 2.5 

Functions added in DLI v3.0 1.15 

Functions removed from DLI v3.0 1.18 

Functions updated in DLI v3.0 1.18 


Index 

I.xiii 

G 

gcc Compilation Version 1.4 

genErrBadParm 4.8, 6.3 


GetGraphicFromList A.184 


GetGraphicFromList, OS/390 


GIF (Graphics Interchange Format) 

Encoding and Compression References 

11.4 




17.6 

Glyph IDs 4.3 

GoTo 


Graphics (Sample DLI Application) 17.6 

Graphics cache 


Graphics, One-Bit 


grayScale 



H 

HelloDLI (Sample DLI Application) 17.4 

Comparison with helowrld.c 2.17 

HeloWrld (Sample Adobe PDF Library 


Comparison with hellodli.c 2.17 

hot spot (parameter) 

Definition of 13.2 


13.5 

Hyperlinks 


I 

ICC (International Color Consortium) 12.10 

ICCBased 




ICU (International Components for Unicode) 

Obtaining Encoding names via 


1.16, A.178 



What’s New 1.13 

Image Import Improvents in DLI v3.0 1.14 

Imagemask 

ImageMask key 11.12 

Note on Use of Bitmaps 11.6 


ImageName 


Images, Displaying 

EPS Pass-Through Objects 11.7 

Example 11.8 

Graphic Image Forms 

Bitmaps 11.3 

Example 11.4 

Graphical Language 11.5 

Graphic Image Structures 

Destroying 11.3 

Formats Supported 11.2 

ImageName Use 11.3 

Multiple Document Use 11.2 

Image Creation Methods 

Assorted Formats 

dlpdfimagecreatefromfile 

11.10 

Example 11.10 

Supported Formats 11.10 

Bitmaps 

Compression and Filtering 11.7 

dlpdfimagecreatefrombmp 

11.6 

Values within Color Models 

11.6 

EPS 

dlpdfimagecreatefromps 11.7 

Example 11.8 

Form XObject 


11.11 

GetGraphicFromList 11.12 

LoadGraphicList 11.11 

PDF 

dlpdfimagecreatefrompdf 11.8 

Example 11.9 

Transparent Graphics 

dlpdfcontentgstate 11.13

I.xiv 


Imagemasks 11.12 

Sample 11.13 

Included EPS Images Not Appearing in 

PDF Pages 11.2, 11.7 

Overview 11.2 

Indexed (atom) 



Initializing and Terminating the Library 

Comparison of Applications with and 

without DLI 2.17 

Files In Memory 

Activation 2.8 

Image Search using Files in Memory 

2.11 

Output to Memory, Writing PDF 2.15 

Calls 2.16, 2.17 

Transient Files 2.15 

Overview 2.2 

PDFLDataRec Initialization 2.2 

Memory Allocation Routines, Setting 

2.5 

Resource Allocation Routines, 

Setting 2.5 

Resource Directories, Setting 2.3 

Terminating 2.11 

Thread-Safe Issues 

Initialization of non-thread-safe 

Library releases 2.14 

Multi-Thread Initializations 2.13 

mutex (Mutual Exclusion algorithm) 

2.14 

Version Number, Obtaining 2.6 

With DLI 

Calls 2.9, 2.11, 2.12 

Overview 2.8 

Specifying an Alternate File System 

2.10 

Typical Order of Calls 2.13 

Using a Graphics Cache 2.10 

Intended Audience 1.3 


J 

JPEG/JPG (Joint Photographic Experts Group) 


11.4 



17.6 

K 

Keys, Public and Private 15.2 

kPDEEoFill 



10.17 


kPDEFill 



10.17 


kPDEStroke 



10.17 


kPDEStroke | kPDEEoFill 


kPDEStroke | kPDEFill 


kPDFLInitIgnoreDefaultDirectories 


1.21, 2.3 

kPDFLVersion 

Use in Obtaining Version Number 2.6 

L 

Lab 


Basic 12.9 


Library Data Structure 2.2 

Line Drawing 10.1 

Directly-Drawn Methods 10.3 

Calls 10.4, 10.5, 10.6 

Common Parameters 10.3 


Example 10.6 

Graphic State 10.17 

Overview 10.2 

Path Drawing Methods 10.7 

Calls 10.7, 10.8, 10.9, 10.10, 

10.11, 10.12, 10.13, 

10.14, 10.15 

Common Parameters 10.7 

Example 10.15 

Transformation Matrix 10.15

Index 

I.xv 

Arguments 10.15 

dlpdfmatrixrotate 10.16 

Inversion Matrix 10.16 

Mirror-image matrix 10.16 

Rotation Matrix 10.16 

Scale/Rotation Caution 10.16 

Scaling 10.16 

Shearing 10.16 

Translations 10.16 

Unity Matrix 10.16 

Linearization 

Calls 3.4 


Ending 3.4 

lineCap 


lineJoin 


lineWidth 


Link Annotation 


Link Cos Object 


Links 

action (parameter) 13.2 

Calls 13.4, 13.6, 13.7, 13.8 

Components 13.2 

Cross-document 13.6 

Destination Page Number 13.5 

FitType 13.5 

hot spot (parameter) 

Definition of 13.2, 13.5 


List of Possible Actions 13.9 


Overview 13.2 

URI 13.7 

URL 13.7 

Zoom 13.5 

listLen 

Use in Setting Resource Directories 2.3 

LoadGraphicList A.185 

M 

Major Version Number 2.6 

malloc 



Matrix operations 

Rotations 17.5 

Translation of Paths 17.5 

MDFile 


2.16 

memAvailProc 


Routines 2.5 

memFiles (Sample DLI Application) 17.16 

MEMORY 

Use in Files in Memory Activation 17.2, 

17.3 

Memory Allocation Routines, Setting 2.5 

allocProc 2.5 

freeProc 2.5 

memAvailProc 2.5 

reallocProc 2.5 

Minor Version Number 2.6 

Miter 


miterLimit 


Multibyte Text 

Commands 5.3, 5.5, 5.6, 5.7, 5.8, 

5.9, 5.10 

Creating DLPDFTEXT Areas 5.5 


Loading and Creating Fonts 5.3 


Working With DLPDFTEXT Areas 5.7 

MultiDoc (Sample DLI Application) 17.16 

Required Arguments 17.16 

mutex (Mutual Exclusion algorithm) 2.14 

N 

name 

Use in Links 

instead of Destination 13.6 

name (parameter) 


Name Tree A.51 

Adding Destination 13.8 


hot spot Definition 13.2 


Named Destination 


Names

I.xvi 



vs. Destinations 13.6 

NestedPDF (Sample DLI Application) 17.17 

NotEmbedded (flag) 3.3, 4.5, A.47 

Notes 

"Browser is Busy" Error during Link 13.7 

Adobe CFF OpenType font files not 

properly subset 5.3 

ASN membership may be required for 

Adobe website access 1.10 

Base 14 Fonts 

Creation Allowed by dlpdffontcreate 

4.6 

Bitmapped Images under 500 Bytes 

Always Merged Inline 11.6 

BMP images with LZW skip markers may 

not embed properly 17.8 

Cache size limit is checked every time a 

document is destroyed 2.10, 

A.91, A.94 

Colorizing via Stroke and Fill 8.6, 10.2 

Default-filesystem settings may need 

updating for images in memory 

1.21, 2.11 

Digital Signature signed hash values 

must be exactly 256 hex digits 

15.5 

Disk resources used by default if Output 

to Memory is not set 2.10 

DLI v2.2 Unicode support now 

superceded by new Multibyte text 

methods 5.2 

dlpdfcontentarcto Discrepancies with 

PostScript Output 10.5 

DLPDFINSTANCE required for Unicode 

font creation 1.13 

dlpdfmemfiledeleteonclose required for 

memory file deletion 1.15 

dlpdfpathaddarcto Line Drawing Details 

10.10 

dlpdfpathaddclose, Adding Disjoint Path 

Segments After 10.14 

dlpdfttload does not re-parse previouslyloaded 

font file 5.4 

Document Sharing of COS Objects and 

PDEColorSpaces 12.5 

Encryption Key Length, Setting in 

Multiple Documents 3.5 

Error Handling should conform to 

Adobe guidelines 16.2 

File Sizes, Effect on, by 

Repeated Graphical Object 

References 11.11 

Files in /Codesamples folder not 

buildable source as-is 1.5, 11.13 

Fill Operator Not Valid via 

dlpdfcontentline 10.4 

Fill Patterns are Never Destroyed 12.14 

Font Encoding, Limitations on 

Predefined 4.9 

Font not licensed for embedding will be 

created as Referenced instead 3.3, 

4.5 

Function Return Value is Undefined if 

Error Occurs 16.4 

Graphic Conversions,Some Unavailable 

on OS/390 and OS/400 11.3, 

11.10 

Graphic Key on OS/390 Must be ASCII 

String 11.12 

Images cached by filename 17.8 

Included EPS Images Not Appearing in 

PDF Pages 11.2, 17.6 

Library is not thread-safe 1.4 

No default font searching for 

dlpdfttload 2.3 

Only fonts using standard encodings 

may be fauxed 17.12 

Pass accurate length values for PKCS #7 

certificate output space reservation 

15.6, A.162 

Pattern Interaction with Color when 

Drawing Figures 10.17 

PDColorValue Permits Only 4 Channels 

12.11 

PDEPathGetData Requirement for Path 

Data Retrieval 10.6 

PDEPathGetData Return Value 8.7 

PDF Reference Manual errata file 

available for download 1.10 

Popup warning may occur for new PDF 

in old viewers 1.12, 2.7 

RSA encryption algorithm within 

SignDoc sample not recommended 

for Production code 17.19 

Sample applications are subject to 

change 17.2 

Slow Feedback from FontVerification 

(Sample DLI Application) 17.14 

Structure Variations may exist between 


Index 

I.xvii 

O 

PDF 1.5 and earlier 1.3 

Type is Filled, Not Stroked 12.2 

Type0 Fonts must be Subset if 

Embedded 4.8 

Unicode NULL string terminators not 

required or included in calculations 

A.37, A.38 

Upgrade applications to thread-safe 

capability as soon as possible 2.15 

WideText sample application uses fonts 

not distributed with DLI 17.21 

Outline Tree 

Adding New Entry 14.3 

Use in Bookmarks 

Building Multiple Trees 14.2 

Output File, Writing 

Calls 3.4 

Document Information 3.4 

Encryption 3.4 

Linearization 3.4 

Security Permissions 3.5 

P 

Page 


Page Interface Calls 6.2, 6.3 

Page Structure 6.2 

PageMode 


Paint Operator 



Pass-Through Objects 

Use in Displaying EPS Images 11.7 

Passwords 

Setting in Encrypt (Sample DLI 


Paths (Sample DLI Application) 17.5 

Patterned Colors 12.2 

Patterns, creating background 17.17 

PCKS #7-format certificates 17.19 

PD_STD_ENCODING (flag) 17.12 

PDColorValue 



PDDoc 3.2 

PDDocSetNewSecurityData 


Ending 3.5 

PDEColorSpace 


Document Sharing 12.5 


PDEColorSpaceCreate 



Advanced 12.11, 12.12 

Basic 12.9 


PDEColorSpaceCreateFromName 


Advanced 12.11, 12.12 

Basic 12.9, 12.10 

PDEColorSpaceGetCosObj 


PDEDash 


PDEDeviceNColorData 



PDEFontAttrs 4.5, 4.8, 17.11, 17.12 

charset field 4.9 

encoding field 4.9 

type field 4.9 

Use in Creation Calls in DLI 4.6 

wMode field 4.10 

PDEGraphicState 8.4, 8.5 

Color Definitions 10.2 




Use in Line Drawing 10.2, 10.14, 

10.17 

dash 10.18 

fillColorSpec 10.17 

flatness 10.18 

lineCap 10.18 

lineJoin 10.18 

lineWidth 10.17 

miterLimit 10.18 

effect on lineJoin 10.18 

strokeColorSpec 10.17 

PDEGrayCalFlt 


Basic 12.9 

PDEICCBasedColorData

I.xviii DLI Implementation and Reference Guide 


PDEIndexedColorData 



PDELabCalFlt 


Basic 12.9 

PDEPath 


PDEPathAddSegment 

Cited in PDF Rules for Path Construction 

10.6 

PDEPathGetData A.17 



PDERGBCalFlt 


Basic 12.9 

PDESeparationColorData 

Color Spaces 


PDETextState 8.4 


PDF 


Level Declarations in Output 1.12, 2.6 

Declarations via DLI 1.12 

DLI-selected Declarations 2.7 

Overriding DLI-selected Declarations 

2.7 

Use in Displaying Images 11.8, 11.10, 

11.11 



17.6 

PDF Library 

Use in Multithreaded Applications 1.11 

Version Control 1.12, 2.6 

PDF Page Tree Structures 6.2 

PDFInit.h 


Routines 2.5 

Use in Setting Resource Allocation 

Routines 2.5 

PDFLDataRec 


1.21 


Library 2.2, 2.3 


Routines 2.5 

Use in Terminating Library 2.12 

PDFLGetVersion 

Use in Obtaining Version Number 2.6 

PDFLInit 


pre-v6.1 Library 2.9, A.91 

Prohibition on calling from DLI v3.0 

1.14, A.91 


1.21 



Use in Multi-Thread Initializations 2.13 

PDFLTerm 

Prohibition on calling from DLI v3.0 

1.14, A.91 

Use in Multi-Thread Initializations 2.13 

pdfMajorVer 2.7 

pdfMinorVer 2.7, 2.8 

PDFNeeded (flag) 

Removal from dlpdfdoccreate 1.18, 

A.43 

PDPerms 


Ending 


PDViewDestNull 


Use in Links 

with Zoom 13.5 


Font Creation Calls in DLI 4.13 

Plugins 

Self-Sign 17.19 

VeriSign Signature 17.19 

PNG (Portable Network Graphics) 


11.4 




17.6 

Private keys 15.2 

psOutput (Sample DLI Application) 17.20 

Public keys 15.2 


Q 

QuickDraw

Index 

I.xix 

R 


RAW (Unformatted Unannotated Bitmap) 


17.6 

readme.txt 1.11 

realloc 


reallocProc 


Routines 2.5 

Rect (parameter) 


Rectangles 


Release Notes 1.11 

Resource Allocation Routines, Setting 2.5 

Resource Directories, Setting 


Library 2.3 

Resources 

Adobe 

AcroColor API Reference 1.10 

Adobe Acrobat Core API Overview 

1.10 

Adobe Acrobat Core API Reference 

1.10 

Adobe PDF Library Overview 1.10 

Adobe PDF Library Supplement to 

the Acrobat Core API 

1.11 

Portable Document Format 

Reference Manual 1.10 

Errata file 1.10 

Datalogics 

Adobe PDF Library and DLI 

Installation Guide 1.9 

Adobe PDF Library Developer 

Overview 1.9 

DLI Implementation and Reference 

Guide 1.9 

Java Interface User Guide 1.9 

RGB Color 

Collapsing to Gray 12.16 

Converting to CMYK 12.17 




Rotate (flag), in imported image files 1.14 

RSA encryption algorithm 17.19 

S 

Sample DLI Applications 

AcroForm 17.18 

Activating Files in Memory 17.2 

Annotations 17.15 

Encrypt 17.9 

FontFaux 17.11 

FontVerification 17.13 

Graphics 17.6 

HelloDLI 17.4 

memFiles 17.16 

MultiDoc 17.16 

NestedPDF 17.17 

Overview 17.2 

Paths 17.5 

psOutput 17.20 

SignDoc 17.19 

WideText 17.21 

Security Permissions 


Ending 


Use in Encrypt (Sample DLI Application) 

17.10 

Self-Sign Plugin 17.19 

Separation 

Color Spaces 


Seven-Bit Safe 


Signatures 

as images in Digital Signatures 15.3 

SignDoc (Sample DLI Application) 17.19 

Standard Encoding 


Ending 3.3 

StdSecurityDataRec 


Ending 3.5 

sticky note 


Streaming PostScript 


stroke (parameter) 


Stroke Color 8.6

I.xx 



strokeColorSpec 



Sub-minor Version Number 2.6 

SubType (parameter) 




T 


Generation via FontVerification (Sample 

DLI Application) 17.13 

Text Container 

Creation and Positioning 8.3 

Text Placement Calls 8.4 

Text Layering 8.2 

Text Width 8.4 

Thread Safety 


pre-v6.1 Library 2.9 

Initialization of non-thread-safe Library 

releases 2.14 

Multi-Thread Initializations 2.13 

Thumbnails 

Calls 3.4 


Ending 3.4 

TIFF (Tagged Image File Format) 


11.4 




17.6 

TKAllocatorProcs 


Routines 2.5 

TKResourceProcs 

Use in Setting Resource Allocation 

Routines 2.5 

Transformation Matrix 

Arguments 10.15 


Translations 

Inversion 10.16 

Mirror-image 10.16 

Rotation 10.16 

Scale/Rotation Caution 10.16 

Scaling 10.16 

Shearing 10.16 

Translation 10.16 

Transforms 

Association with Content Elements 8.2 

Tree Name 


TrueType font 

Terminology usage 4.4 

Type 

Filled vs. Stroked 12.2 

Type (parameter) 



U 

Unicode 

as CIDType2 Fonts 4.3 

Text Support 

Font Type Recommendations 4.13 

NULL string terminators A.37, A.38 

Unix Compiler Run-Time Libraries 1.4 

URI 


URL 


UseOutlines 


V 

VeriSign signature plugin 17.19 

Version Number, Obtaining 2.6 

W 

What’s New 

DLI v2.2.12 1.21 


1.21 

DLI v2.2.13 1.20 


Expanded to All Platforms 

1.20 

Image Search using Files in Memory 

1.20 

DLI v3.0 1.11 

Overview 1.11 

WideText (Sample DLI Application) 1.13,

DLI Implementation and Reference 

17.21 


Use in Documents, Beginning and Ending 3.3 

WMF (Windows Metafile Format) 


Writing Pages 

Procedure for 1.2 

X 

x.509 certificate 17.19 

XYZ 

Use in Links 

with Zoom 13.5 

Z 

zoom 


Use in Links 13.5

DLI Implementation and Reference Guide - Datalogics

You also want an ePaper? Increase the reach of your titles

Delete template?

Save as template?