DLI Implementation and Reference Guide

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 [email protected] Table of Contents i

Table of Contents

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 Table of Contents 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 DLI Implementation and Reference Guide

Digital Signature Calls 15.4

16 Error Concepts and Facilities: Guide to the DL Pager Composition System 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 1.4 DLI Implementation and Reference Guide

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 run- time 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/. Getting Started 1.5

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. 1.6 DLI Implementation and Reference Guide

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. Getting Started 1.7

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. 1.8 DLI Implementation and Reference Guide

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. Getting Started 1.9

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:// 1.10 DLI Implementation and Reference Guide

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 last- minute 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 Getting Started 1.11

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. 1.12 DLI Implementation and Reference Guide

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 Getting Started 1.13

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 1.14 DLI Implementation and Reference Guide

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. Getting Started 1.15

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. 1.16 DLI Implementation and Reference Guide

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 dlpdftextfromutf32le dlpdftextfromutf32be dlpdftextfromutf32he

These are convenience functions for common Unicode encodings. Getting Started 1.17

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. 1.18 DLI Implementation and Reference Guide

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. Getting Started 1.19

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. 1.20 DLI Implementation and Reference Guide

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 Getting Started 1.21

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 2.2 DLI Implementation and Reference Guide

Overview

Concepts and Facilities: Guide to the DL Pager Composition System 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 2.4 DLI Implementation and Reference Guide

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

Concepts and Facilities: Guide to the DL Pager Composition System 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. Initializing and Terminating the Library 2.5

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. 2.6 DLI Implementation and Reference Guide

Adobe PDF Library Version Control

Concepts and Facilities: Guide to the DL Pager Composition System 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 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.

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 2.8 DLI Implementation and Reference Guide

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 Concepts and Facilities: Guide to the DL Pager Composition System 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 Initializing and Terminating the Library 2.9

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 2.10 DLI Implementation and Reference Guide

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.

Concepts and Facilities: Guide to the DL Pager Composition System 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. Initializing and Terminating the Library 2.11

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.

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 2.12 DLI Implementation and Reference Guide

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 Concepts and Facilities: Guide to the DL Pager Composition System 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. Initializing and Terminating the Library 2.13

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 2.14 DLI Implementation and Reference Guide

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

Concepts anddlpdfinit() 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 multi- threaded 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 Initializing and Terminating the Library 2.15

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 2.16 DLI Implementation and Reference Guide

dlpdfmemfiletransientprefix function. This returns a character string with the necessary prefix, which marks the file such that it is not written to disk.

Concepts and Facilities: Guide to the DL Pager Composition System 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. Initializing and Terminating the Library 2.17

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. 2.18 DLI Implementation and Reference Guide

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 3.2 DLI Implementation and Reference Guide

Overview

Concepts and Facilities: Guide to the DL Pager Composition System 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. 3.4 DLI Implementation and Reference Guide

dlpdfdoclinearize

When it is known at document creation time that this file should be written in a Concepts and Facilities: Guide to the DL Pager Composition System 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. 3.6 DLI Implementation and Reference Guide

Concepts and Facilities: Guide to the DL Pager Composition System 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 4.2 DLI Implementation and Reference Guide

PDF Font Overview

Concepts and Facilities: Guide to the DL Pager Composition System 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 4.4 DLI Implementation and Reference Guide

glyph identifiers in the embedded font stream. Text is input using the DLPDFCONTENT text calls as if using a single-byte font.

Concepts and Facilities: Guide to the DL Pager Composition System Most TrueType and OpenType font files can be used to create either TrueType (single- byte) 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.

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. 4.6 DLI Implementation and Reference Guide

Font Creation Calls

Concepts and Facilities: Guide to the DL Pager Composition System 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 4.8 DLI Implementation and Reference Guide

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

Concepts and Facilities: Guide to the DL Pager Composition System 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 4.10 DLI Implementation and Reference Guide

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

Concepts and Facilities: Guide to the DL Pager Composition System 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: 4.12 DLI Implementation and Reference Guide

Table 4-1: Encoding Font Types

Encoding String Value Valid Font Types Concepts and Facilities: Guide to the DL Pager Composition System AdobeStandardEncoding Type1,TrueType

WinAnsiEncoding Type1,TrueType

MacRomanEncoding Type1,TrueType

MacExpertEncoding Type1,TrueType

Identity-H CIDType0,CIDType2

Identity-V CIDType0,CIDType2

Other Predefined CMaps CIDType0

Adobe PDF Library v5.x and higher only:

WinCP1250 CIDType2

WinCP1251 CIDType2

WinCP1253 CIDType2

WinCP1254 CIDType2

WinCP1255 CIDType2

WinCP1256 CIDType2

WinCP1257 CIDType2

WinCP1258 CIDType2

MacCentralEuropean CIDType2

MacCroatian CIDType2

MacRomanian CIDType2

MacCyrillic CIDType2

MacUkranian CIDType2

MacGreek CIDType2

MacCentralEuropean CIDType2 Fonts 4.13

Encoding String Value Valid Font Types

MacTurkish CIDType2

MacArabic CIDType2

MacHebrew 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 4.14 DLI Implementation and Reference Guide

which have been created for other documents. This adds a significant speedup for creators of multiple documents over previous versions of DLI.

Concepts and Facilities: Guide to the DL Pager Composition System 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. 4.16 DLI Implementation and Reference Guide

Concepts and Facilities: Guide to the DL Pager Composition System 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 5.2 DLI Implementation and Reference Guide

Introduction

Concepts and Facilities: Guide to the DL Pager Composition System 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 5.4 DLI Implementation and Reference Guide

array be allocated to hold a sufficient number of entries to prevent this. In practice, a dozen ASAtom entries should be sufficient. Concepts and Facilities: Guide to the DL Pager Composition System 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. Multibyte Text Work 5.5

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, big- endian 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.

dlpdftextshowencodingnames

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 5.6 DLI Implementation and Reference Guide

obtain a list of these encodings, use the dlpdftextshowencodingnames function call:

void dlpdftextshowencodingnames(charConcepts 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. Multibyte Text Work 5.7

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:

dlpdftextstring 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, big- endian elsewhere) and does not include a Unicode byte-order marker. An exception will be raised if an invalid DLPDFTEXT area is supplied.

dlpdftextlength

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. 5.8 DLI Implementation and Reference Guide

dlpdftextadvance

The most common use for making new text areas from portions of a DLPDFTEXT area Concepts and Facilities: Guide to the DL Pager Composition System 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-to- right 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. Multibyte Text Work 5.9

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. 5.10 DLI Implementation and Reference Guide

dlpdftextdestroy

After placing the DLPDFTEXT area, or after finishing with any DLPDFTEXT area, Concepts and Facilities: Guide to the DL Pager Composition System 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.

Performance Considerations

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 6.2 DLI Implementation and Reference Guide

Introduction to Page Interface

Concepts and Facilities: Guide to the DL Pager Composition System 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. 6.4 DLI Implementation and Reference Guide

Concepts and Facilities: Guide to the DL Pager Composition System 7 Containers within Pages

This chapter describes containers within pages and provides examples of various applications.

7.1 7.2 DLI Implementation and Reference Guide

What are Containers?

Concepts and Facilities: Guide to the DL Pager Composition System 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: 7.4 DLI Implementation and Reference Guide

"C" Example: Container with Scale void WritePage (DLPDFDOC *Doc, ASFixed Width, ASFixed Depth, userdata *UserData) { Concepts and Facilities: Guide to the DL Pager Composition System DLPDFPAGE *Page = dlpdfdoccreatepage (Doc, Width, Depth); DLPDFCONTENT *Content = dlpdfcontentcreate (Doc);

dlpdfcontentscale (Content, FloatToFixed (1/ 1000), FloatToFixed (1/10)); USERDATA *UserWork = UserData; while (UserWork) { WriteLine (UserWork, Content); UserWork = UserWork->next; } dlpdfcontenttopage (Content, Page); }

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 void WritePage (DLPDFDOC *Doc, ASFixed Width, ASFixed Depth, userdata *UserData) { DLPDFPAGE *Page = dlpdfdoccreatepage (Doc, Width, Depth); DLPDFCONTENT *Content = dlpdfcontentcreate (Doc);

dlpdfcontenttranslate (Content, 0, Depth); dlpdfcontentscale (Content, FloatToFixed (1/ 1000), FloatToFixed (1/10)); userdata *UserWork = UserData; while (UserWork) { WriteLine (UserWork, Content); UserWork = UserWork->next; } dlpdfcontenttopage (Content, Page); } Containers within Pages 7.5

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 void WritePage (DLPDFDOC *Doc, ASFixed Width, ASFixed Depth, areadata *AreaData) { DLPDFPAGE *Page = dlpdfdoccreatepage (Doc, Width, Depth); areadata *CurrentArea = AreaData; ASFixedMatrix Matrix;

while (AreaData) { DLPDFCONTENT *Content = dlpdfcontentcreate (Doc);

/* 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); dlpdfcontenttopage (Content, Page);

AreaData = AreaData->Next; } 7.6 DLI Implementation and Reference Guide

Collection of Areas

In this example, the page content is divided into areas. Each area has a location Concepts and Facilities: Guide to the DL Pager Composition System 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

void WritePage (DLPDFDOC *Doc, ASFixed Width, ASFixed Depth, areadata *AreaData) { DLPDFPAGE *Page = dlpdfdoccreatepage (Doc, Width, Depth); areadata *CurrentArea = AreaData;

while (AreaData) { DLPDFCONTENT *Content = dlpdfcontentcreate (Doc); dlpdcontenttranslate (Content, AreaData->X, Depth - AreaData->Y); dlpdfcontentrotate (Content, AreaData->Rotation); WriteLines (AreaData->UserData, Content); dlpdfcontenttopage (Content, Page); AreaData = AreaData->Next; } Containers within Pages 7.7

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

rotation 180 180

u.l u.l rotation 270 90 rotation u.l

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. 7.8 DLI Implementation and Reference Guide

Concepts and Facilities: Guide to the DL Pager Composition System 8 Working with Content

This chapter explains content and defines the calls available at this level.

8.1 8.2 DLI Implementation and Reference Guide

Overview of Content Interface

Concepts and Facilities: Guide to the DL Pager Composition System 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. 8.4 DLI Implementation and Reference Guide

dlpdfcontenttranslate

This procedure will move all of the contents of a content structure by the specified Concepts and Facilities: Guide to the DL Pager Composition System 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. Working with Content 8.5

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 8.6 DLI Implementation and Reference Guide

defines how the path defined should be treated (kPDEStroke, kPDEFill, kPDEEoFill, or a combination of these).

Concepts and Facilities: Guide to the DL Pager Composition System 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. Working with Content 8.7

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. 8.8 DLI Implementation and Reference Guide

dlpdfcontentarcn

This procedure is included as an aid in transitioning from PostScript to PDF. It will Concepts and Facilities: Guide to the DL Pager Composition System 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, counter- clockwise, 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

This procedure is included as an aid in transitioning from PostScript to PDF. It will draw a circle centered at (X1,Y1), at a radius of Radius.

dlpdfcontentellipse

This procedure is included as an aid in transitioning from PostScript to PDF. It will draw an ellipse centered at (X1,Y1), at a vertical radius of RadiusV and a horizontal radius of RadiusH. Working with Content 8.9

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. 8.10 DLI Implementation and Reference Guide

dlpdfpatharray

This method will return a pointer to the first member of the array of ASFixed integers, Concepts and Facilities: Guide to the DL Pager Composition System 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 Working with Content 8.11

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 8.12 DLI Implementation and Reference Guide

will be added to the path, and no notice will be given (Optimization). The position following this command will be the specified position.

dlpdfpathaddarcConcepts and Facilities: Guide to the DL Pager Composition System

This method accepts six parameters:

• The first is a pointer to the path. • 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 command will be the specified position.

dlpdfpathaddarcn

This method accepts six parameters:

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. dlpdfpathaddarcto

This method accepts six parameters:

• The first is a pointer to the path. • 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 first is a pointer to the path. • The second is an Xposition of the arc center point. • The third is the Yposition of the arc center point. • 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 8.14 DLI Implementation and Reference Guide

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 Concepts and Facilities: Guide to the DL Pager Composition System the arc is to begin. • 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

This method accepts seven parameters:

• The first is a pointer to the path. • The second is an Xposition of the arc center point. • The third is the Yposition of the arc center point. • 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 arc is to begin. • 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 Working with Content 8.15

same angle, a full circle will be drawn. The position following this command will be the specified position. dlpdfpathaddelliparcto

This method accepts seven parameters:

• The first is a pointer to the path. • 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

This method accepts seven parameters:

• 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 8.16 DLI Implementation and Reference Guide

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). Concepts and Facilities: Guide to the DL Pager Composition System dlpdfpathaddcurver

This method accepts seven parameters:

• The first is a pointer to a path. • 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 first is a pointer to a path. • 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.

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. Control Point 1 is the current position. The current position will be the end position of the line at completion of this Working with Content 8.17

operation. If the end position specified is identical the current position, no segment will be appended, and no notice will be given (Optimization). dlpdfpathaddcurvey

This method accepts five parameters:

• The first is a pointer to a path. • 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.

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. 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

This method accepts five parameters:

• The first is a pointer to a path. • 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 8.18 DLI Implementation and Reference Guide

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.

Concepts and Facilities: Guide to the DL Pager Composition System 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 Working with Content 8.19

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. 8.20 DLI Implementation and Reference Guide

Referencing Predefined Structures

These calls permit the inclusion in content of complex pre-built structures. These Concepts and Facilities: Guide to the DL Pager Composition System 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. Working with Content 8.21

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. 8.22 DLI Implementation and Reference Guide

Adding Comments to Content Elements

dlpdfcontentcomment Concepts and Facilities: Guide to the DL Pager Composition System

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 9.2 DLI Implementation and Reference Guide

Overview of Forms

Concepts and Facilities: Guide to the DL Pager Composition System 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. 9.4 DLI Implementation and Reference Guide

Concepts and Facilities: Guide to the DL Pager Composition System 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

Concepts and Facilities: Guide to the DL Pager Composition System 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 directly- drawn 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. 10.4. DLI Implementation and Reference Guide

dlpdfcontentrect

This will draw a rectangle. The four parameters are ASFixed values reflecting X Concepts and Facilities: Guide to the DL Pager Composition System 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.

dlpdfcontentarcn

This is identical to the previous, except that the arc is drawn clockwise. Displaying Line Drawings 10.5.

dlpdfcontentarcto

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 counter- clockwise. If the angles are coincident, a full circle will be drawn. dlpdfcontentpieslicen

This is identical to dlpdfcontentpieslice above, except that the arc will be drawn clockwise from the Start Angle to the End Angle. 10.6. DLI Implementation and Reference Guide

dlpdfcontentcircle

This method will draw a circle whose center is the first two parameters and whose Concepts and Facilities: Guide to the DL Pager Composition System radius is the third parameter.

dlpdfcontentellipse

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.

dlpdfcontentpath

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. Displaying Line Drawings 10.7.

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. dlpdfpathcreate

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. 10.8. DLI Implementation and Reference Guide

dlpdfpathclear

This method will remove all content from an existing DLPDFPATH structure and Concepts and Facilities: Guide to the DL Pager Composition System restore it to the state it was in following the call to dlpdfpathcreate. It is included to lower the overhead of creating many paths.

dlpdfpathdestroy

This method will destroy a DLPDFPATH structure and free all resources that it used.

dlpdfpathaddmove

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.

dlpdfpathaddmover

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.

dlpdfpathaddline

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. Displaying Line Drawings 10.9.

dlpdfpathaddliner

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 10.10. DLI Implementation and Reference Guide

specified (X,Y) to the second (X,Y) specified by the third and fourth parameters, at a Radius specified by the fifth parameter.

Concepts and Facilities:X1/Y1 Guide to the DL Pager Composition System Xint1/ Xint2/ Yint1 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.

dlpdfpathaddelliparc

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 counter- clockwise from the start angle to the end angle. If the angles are coincident, a Displaying Line Drawings 10.11.

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. dlpdfpathaddelliparcto

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. 10.12. DLI Implementation and Reference Guide

dlpdfpathaddcurve

This is the first of the four methods which add a spline, or cubic Bézier curve, to the Concepts and Facilities: Guide to the DL Pager Composition System 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. Displaying Line Drawings 10.13.

dlpdfpathaddcurvev

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/ Xctrl2/ Yctrl1 Yctrl2

dlpdfpathaddcurvey

This method is identical to dlpdfpathaddcurve, except that the second control point is assumed to be the ending position. Xctrl1/ Yctrl1

Xend/ Yend Xctrl2/ Yctrl2 Xstart/ Ystart 10.14. DLI Implementation and Reference Guide

dlpdfpathaddrect

This method will draw a rectangle. The first two parameters specify the (X,Y) position Concepts and Facilities: Guide to the DL Pager Composition System 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.

dlpdfpathaddclose

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. Displaying Line Drawings 10.15.

• 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. 10.16. DLI Implementation and Reference Guide

Matrix Translations

The unity matrix ([1, 0, 0, 1, 0, 0]) causes a 1 unit movement in X to be a 1 Concepts and Facilities: Guide to the DL Pager Composition System 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. Displaying Line Drawings 10.17.

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. 10.18. DLI Implementation and Reference Guide

lineJoin

• A value of zero for this parameter continues the joined lines to a point. • A value of 1 roundsConcepts over andthe 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 Displaying Line Drawings 10.19.

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. 10.20. DLI Implementation and Reference Guide

Concepts and Facilities: Guide to the DL Pager Composition System 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 11.2 DLI Implementation and Reference Guide

Overview

Concepts and Facilities: Guide to the DL Pager Composition System 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 11.4 DLI Implementation and Reference Guide

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. Concepts and Facilities: Guide to the DL Pager Composition System

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); Image Display 11.5

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: 11.6 DLI Implementation and Reference Guide

dlpdfimagecreatefrombmp

This method creates a DLPDFIMAGE from a bitmap and user-supplied information. Concepts and Facilities: Guide to the DL Pager Composition System • 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 Display 11.7

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: 11.8 DLI Implementation and Reference Guide

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);

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: Image Display 11.9

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); /* "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); } 11.10 DLI Implementation and Reference Guide

dlpdfimagecreatefromfile

This method invokes various conversion routines to allow a user to simply specify the Concepts and Facilities: Guide to the DL Pager Composition System file name and obtain a valid DLPDFIMAGE object. All conversions are done internally to DLI.

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");

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. Image Display 11.11

dlpdfimageplaceascontent

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 11.12 DLI Implementation and Reference Guide

The parameter containing the graphic list file name is the DDName of the cross- reference file, as in:

Concepts and Facilities: Guide to the DL Pager Composition System 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 Image Display 11.13

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. 11.14 DLI Implementation and Reference Guide

Concepts and Facilities: Guide to the DL Pager Composition System 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 12.2 DLI Implementation and Reference Guide

Library Color Descriptions

Concepts and Facilities: Guide to the DL Pager Composition System 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. 12.4 DLI Implementation and Reference Guide

Color spaces for the basic colors (DeviceRGB, DeviceCMYK and DeviceGray) are created by a call to the Adobe PDF Library in this form:

Concepts and Facilities: Guide to the DL Pager Composition System "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 and its Use 12.5

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); 12.6 DLI Implementation and Reference Guide

Values for Color Channels

Concepts and Facilities: Guide to the DL Pager Composition System 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. Color and its Use 12.7

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. 12.8 DLI Implementation and Reference Guide

Device RGB

This space allows you to use full color by encoding the color as three channels, one for Concepts and Facilities: Guide to the DL Pager Composition System 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 and its Use 12.9

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. 12.10 DLI Implementation and Reference Guide

ICC Based

This is a color model promoted by the International Color Consortium (ICC). Its Concepts and Facilities: Guide to the DL Pager Composition System 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. Color and its Use 12.11

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. 12.12 DLI Implementation and Reference Guide

Indexed

Indexed color spaces are most often used in images, but are by no means limited to Concepts and Facilities: Guide to the DL Pager Composition System 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. Color and its Use 12.13

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: 12.14 DLI Implementation and Reference Guide

"C" Example: Filling An Area With A Pattern DLPDFPATTERN *Pattern; DLPDFCONTENT *PatContent, *PageCont; PDGraphicStateConcepts 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 Color and its Use 12.15

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. 12.16 DLI Implementation and Reference Guide

Conversion between Models

Concepts and Facilities: Guide to the DL Pager Composition System 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. Color and its Use 12.17

"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. 12.18 DLI Implementation and Reference Guide

"C" Example: Converting RGB to CMYK if (State->fillColorSpec.space) == GlobalRGBSpace) { State->fillColorSpec.spaceConcepts 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 13.2 DLI Implementation and Reference Guide

Overview

Concepts and Facilities: Guide to the DL Pager Composition System 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. 13.4 DLI Implementation and Reference Guide

dlpdfpageaddtextannotation

The simplest annotation in PDF is a text annotation. This appears as a “sticky note” Concepts and Facilities: Guide to the DL Pager Composition System 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 Annotations and Links 13.5

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. 13.6 DLI Implementation and Reference Guide

From the full example of creating annotations:

"C" Example: CreatingConcepts A Linkand AnnotationFacilities: Guide to the DL Pager Composition System DLPDFPAGE *Page1 ASFixedRect BBLink1, PageRect; ASFixed Border[3], Color[3];

/* 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 Annotations and Links 13.7

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; ASFixed Border[3], Color[3];

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. 13.8 DLI Implementation and Reference Guide

dlpdfdocnameadd

This method allows the user to add one destination to the name tree structure, the Concepts and Facilities: Guide to the DL Pager Composition System 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 Annotations and Links 13.9

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: 13.10 DLI Implementation and Reference Guide

"C" Example: Modifying a Goto Link into a GotoR Link /* Create a link to another document */ local_inserttext (Doc, Content1, &gState, "Link Conceptsto Line andDrawing Facilities: Sample", Guide tofixedFour 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 14.2 DLI Implementation and Reference Guide

Overview

Concepts and Facilities: Guide to the DL Pager Composition System 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. 14.4 DLI Implementation and Reference Guide

From the full example on creating annotations, this segment shows the creation of an outline entry:

Concepts and Facilities: Guide to the DL Pager Composition System "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”. 14.6 DLI Implementation and Reference Guide

Opening the Document with Annotations Showing

The default action on opening a document is to show only the document window and Concepts and Facilities: Guide to the DL Pager Composition System 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 15.2 DLI Implementation and Reference Guide

Overview

Concepts and Facilities: Guide to the DL Pager Composition System 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. 15.4 DLI Implementation and Reference Guide

Digital Signature Calls

Concepts and Facilities: Guide to the DL Pager Composition System 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.

dlpdfdocsetsignatureappearance

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

dlpdfsignaturesetx509cert

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 ]

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.

dlpdfsignaturesetpkcs7cert

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 15.6 DLI Implementation and Reference Guide

corresponding to the public key in the certificate. The RSA public-key algorithm with a 1024-bit key length is used.

Concepts and Facilities: Guide to the DL Pager Composition System 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.

dlpdfsignaturesetdatacallback

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.

dlpdfpageplacesignature

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 16.2 DLI Implementation and Reference Guide

Overview

Concepts and Facilities: Guide to the DL Pager Composition System 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 16.4 DLI Implementation and Reference Guide

to return the value X, or the E_RTRN_VOID macro to exit a function with no return value.

Concepts and Facilities: Guide to the DL Pager Composition System 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.). 16.6 DLI Implementation and Reference Guide

Concepts and Facilities: Guide to the DL Pager Composition System 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 17.2 DLI Implementation and Reference Guide

Running DLI Sample Applications

Concepts and Facilities: Guide to the DL Pager Composition System 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; 17.4 DLI Implementation and Reference Guide

HelloDLI

Concepts and Facilities: Guide to the DL Pager Composition System

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. Samples and Links 17.5

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. 17.6 DLI Implementation and Reference Guide

Graphics

Concepts and Facilities: Guide to the DL Pager Composition System

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. Samples and Links 17.7

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. 17.8 DLI Implementation and Reference Guide

BMP

NOTE: Some BMP images with LZW skip markers may not embed properly. If possible, avoid imagesConcepts with andLZW Facilities:skip markers. Guide to the DL Pager Composition System

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. Samples and Links 17.9

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 17.10 DLI Implementation and Reference Guide

viewing and printing.

Entering the owner password "DocOwner" will open the document for viewing and Concepts and Facilities: Guide to the DL Pager Composition System 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: Samples and Links 17.11

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 17.12 DLI Implementation and Reference Guide

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. Concepts and Facilities: Guide to the DL Pager Composition System

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. Samples and Links 17.13

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 17.14 DLI Implementation and Reference Guide

DLI, and displays the fonts which the Adobe PDF Library was able to locate on the host system.

Concepts and Facilities: Guide to the DL Pager Composition 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. Samples and Links 17.15

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," 17.16 DLI Implementation and Reference Guide

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.

Concepts and Facilities: Guide to the DL Pager Composition System 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. Samples and Links 17.17

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. 17.18 DLI Implementation and Reference Guide

AcroForm

Concepts and Facilities: Guide to the DL Pager Composition System

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. Samples and Links 17.19

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 self- sign 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 17.20 DLI Implementation and Reference Guide

Adobe Acrobat v6 or higher. You should also be aware that this sample takes a long time to run.

Concepts and Facilities: Guide to the DL Pager Composition System 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 Samples and Links 17.21

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. 17.22 DLI Implementation and Reference Guide

Concepts and Facilities: Guide to the DL Pager Composition System 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, ASFixedConcepts Radius, and ASFixed Facilities: Angle1, Guide to ASFixed the DL Pager Angle2 Composition) System Return Value: void

Description 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.

Parameters • 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 • ASFixed Angle2

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfcontentarcn, dlpdfcontentarcto

Availability All DLI supported platforms. DLI Reference Guide A.3

dlpdfcontentarcn (DLPDFCONTENT *Content, PDEGraphicState *gState, int PaintOp, ASFixed X1, ASFixed Y1, ASFixed Radius, ASFixed Angle1, ASFixed Angle2) Return Value: void

Description 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.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfcontentarc, dlpdfcontentarcto

Availability All DLI-supported platforms. A.4 DLI Reference Guide

dlpdfcontentarcto (DLPDFCONTENT *Content, PDEGraphicState *gState, int PaintOp, ASFixed X1, ASFixed Y1, ASFixedConcepts Radius, and ASFixed Facilities: X2, Guide ASFixed to the DLY2, Pager ASFixed Composition Xint, System ASFixed Yint) Return Value: void

Description 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.

Return Value void DLI Reference Guide A.5

Exceptions

Header dli.h

Related Methods dlpdfcontentarc, dlpdfcontentarcn

Availability All DLI-supported platforms. A.6 DLI Reference Guide

dlpdfcontentcircle (DLPDFCONTENT *Content, PDEGraphicState *gState, int PaintOp, ASFixed X, ASFixed Y, ASFixed Radius)Concepts and Facilities: Guide to the DL Pager Composition System Return Value: void

Description This procedure is included as an aid in transitioning from PostScript to PDF. It will draw a circle centered at (X,Y) at a radius of Radius.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfcontentellipse

Availability All DLI-supported platforms. DLI Reference Guide A.7

dlpdfcontentclip (DLPDFCONTENT *Content, ASFixed *Path, int PathLen, int EOClip) Return Value: void

Description 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.

Parameters • 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. • 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.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfcontentclipend, dlpdfcontentpath

Availability All DLI-supported platforms. A.8 DLI Reference Guide

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 ifDL 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. DLI Reference Guide A.9

dlpdfcontentclipend (DLPDFCONTENT *Content) Return Value: void

Description 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.

Parameters 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.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfcontentclip

Availability All DLI-supported platforms. A.10 DLI Reference Guide

dlpdfcontentcomment (DLPDFCONTENT *Content, char *Comment) Return Value:Concepts void and Facilities: Guide to the DL Pager Composition System

Description This method will insert the specified text string as a comment, in the order provided, into the content elements.

Return Value void

Exceptions

Header dli.h

Related Methods

Availability All DLI-supported platforms.

Technical Notes

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. DLI Reference Guide A.11

dlpdfcontentcreate (DLPDFDOC *Doc)

Return Value: DLPDFCONTENT*

Description Creates a new content element with a rotation of zero degrees, a position of (0,0) and scaling of (1,1).

Parameters DLPDFDOC *Doc: represents the document structure and the current status of the document at all times.

Return Value DLPDFCONTENT*

Exceptions

Header dli.h

Related Methods

Availability All DLI-supported platforms. A.12 DLI Reference Guide

dlpdfcontentellipse (DLPDFCONTENT *Content, PDEGraphicState *gState, int PaintOp, ASFixed X, ASFixed Y, ASFixed RadiusH,Concepts and ASFixed Facilities: RadiusV) Guide to the DL Pager Composition System Return Value: void

Description This procedure is included as an aid in transitioning 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.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfcontentcircle

Availability All DLI-supported platforms. DLI Reference Guide A.13

dlpdfcontentfontskew (DLPDFCONTENT *Content, ASFixedMatrix *Matrix) Return Value: void

Description Causes the font currently in effect for this content structure to appear "twisted" according to the matrix supplied.

Return Value void

Exceptions

Header dli.h

Related Methods

Availability All DLI-supported platforms.

Technical Notes

1 This may be used to simulate an italic or reverse-italic font using a Roman font. A.14 DLI Reference Guide

dlpdfcontentgstate (DLPDFCONTENT *Content, const PDEGraphicState *newGState) Return Value:Concepts void and Facilities: Guide to the DL Pager Composition System

Description Sets the graphics state of the specified DLPDFCONTENT to that of the PDEGraphicState. This may be done at any point during content placement operations.

Parameters • DLPDFCONTENT* Content: Represents the document structure and the current status of the document at all times. • const PDEGraphicState *newGState

Return Value void

Exceptions

Header dli.h

Related Methods

Availability All DLI-supported platforms. DLI Reference Guide A.15

dlpdfcontentline (DLPDFCONTENT *Content, PDEGraphicState *gState, int PaintOp, ASFixed X1, ASFixed Y1, ASFixed X2, ASFixed Y2) Return Value: void

Description This procedure will mark a line in the content, extending from (X1,Y1) to (X2,Y2).

Return Value void

Exceptions

Header dli.h

Related Methods

Availability All DLI-supported platforms. A.16 DLI Reference Guide

dlpdfcontentpath (DLPDFCONTENT *Content, PDEGraphicState *gState, int PaintOp, ASFixed *Path, int PathLen) Concepts and Facilities: Guide to the DL Pager Composition System Return Value: void

Description This procedure will mark a path within the content.

Parameters • 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. • PDEGraphicState *gState • 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. • ASFixed *Path: Specifies path • int PathLen: Specifies path length

Return Value void

Exceptions

Header dli.h

Related Methods

Availability All DLI-supported platforms. DLI Reference Guide A.17

Technical Notes

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. A.18 DLI Reference Guide

dlpdfcontentpieslice (DLPDFCONTENT *Content, PDEGraphicState *gState, int PaintOp, ASFixed X1, ASFixed Y1, ASFixedConcepts Radius, and ASFixed Facilities: Angle1, Guide to ASFixed the DL Pager Angle2) Composition System Return Value: void

Description 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, counter-clockwise, where the angles are specified in degrees.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfcontentpieslicen

Availability All DLI-supported platforms. DLI Reference Guide A.19

dlpdfcontentpieslicen (DLPDFCONTENT *Content, PDEGraphicState *gState, int PaintOp, ASFixed X1, ASFixed Y1, ASFixed Radius, ASFixed Angle1, ASFixed Angle2) Return Value: void

Description 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.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfcontentpieslice A.20 DLI Reference Guide

Availability All DLI-supported platforms. Concepts and Facilities: Guide to the DL Pager Composition System DLI Reference Guide A.21

dlpdfcontentrect (DLPDFCONTENT *Content, PDEGraphicState *gState, int PaintOp, ASFixed X, ASFixed Y, ASFixed Width, ASFixed Height) Return Value: void

Description This procedure marks a rectangle in the content. It will be located such that its lower left hand corner is at (X,Y).

Parameters • 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. • 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. • 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).

Return Value void

Exceptions A.22 DLI Reference Guide

Header dli.h Concepts and Facilities: Guide to the DL Pager Composition System Availability All DLI-supported platforms. DLI Reference Guide A.23

dlpdfcontentreferenceform (DLPDFCONTENT *Content, DLPDFFORM *Form, ASFixed X, ASFixed Y, ASFixed Rotate, ASFixed ScaleX, ASFixed ScaleY) Return Value: void

Description 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.

Parameters • 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. • 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.

Return Value void

Exceptions

Header dli.h

Related Methods

Availability All DLI-supported platforms. A.24 DLI Reference Guide

dlpdfcontentreferenceimage (DLPDFCONTENT *Content, DLPDFIMAGE *Image, ASFixed X, ASFixed Y,Concepts ASFixed and Rotate, Facilities: ASFixedGuide to the ScaleX, DL Pager ASFixed Composition System ScaleY) Return Value: void

Description This procedure places a copy of the referenced image into the current content.

Parameters • 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. • 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

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfimagegetsize (New in DLI v2.2.5)

Availability All DLI-supported platforms. DLI Reference Guide A.25

Technical Notes

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, Int32ToFixed(72), Int32ToFixed(92), 0, 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 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. A.26 DLI Reference Guide

dlpdfcontentrotate (DLPDFCONTENT *Content, ASFixed Rotate) Return Value:Concepts void and Facilities: Guide to the DL Pager Composition System

Description Rotates all of the contents of a given content structure by the specified amount.

Parameters • 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. • 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.

Return Value void

Exceptions

Header dli.h

Related Methods

Availability DLI Reference Guide A.27

dlpdfcontentscale (DLPDFCONTENT *Content, ASFixed XScale, ASFixed YScale) Return Value: void

Description Scales all of the content of a given content structure by the specified amount.

Parameters • 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. • 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.

Return Value void

Exceptions

Header dli.h

Related Methods

Availability All DLI-supported platforms. A.28 DLI Reference Guide

dlpdfcontenttext (DLPDFCONTENT *Content, DLPDFFONT *Font, char *str, PDEGraphicState *gState, PDETextStateConcepts *tState, and ASFixed Facilities: GuidepointSize, to the DLASFixed Pager Composition setWidth, System ASFixed XPos, ASFixed YPos, ASFixed Rotate) Return Value: void

Description 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.

Parameters • 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. • DLPDFFON *Font: Reflects the font. It is created by dlpdffontcreate on a per- document 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 • PDEGraphicState *gState: Contains definitions of colors to be applied, and line sizes and parameters to be used when drawing a path. • PDETextState *tState: The current text state. This should not be NULL. A zero-filled PDETextState parameter is permitted. DLI Reference Guide A.29

Parameters (Continued) • 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.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfcontenttextwidth, dlpdfcontentwidetext, dlpdfcontentwidetextwidth

Availability All DLI-supported platforms. A.30 DLI Reference Guide

dlpdfcontenttextwidth (DLPDFFONT *Font, char *Text, ASFixed SetWidth, PDETextState *TState) Return Value:Concepts ASFixed and Facilities: Guide to the DL Pager Composition System

Description 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.

Parameters • 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.

Return Value ASFixed

Exceptions

Header dli.h

Related Methods dlpdfcontenttext, dlpdfcontentwidetext, dlpdfcontentwidetextwidth

Availability All DLI-supported platforms. DLI Reference Guide A.31

dlpdfcontenttopage (DLPDFCONTENT *Content, DLPDFPAGE *Page) Return Value: void

Description This procedure will make the markings placed into content a part of the specified page. Fol- lowing this call, the content structure no longer exists; pointers to it are invalid and should not be used.

Parameters • DLPDFCONTENT *Content: Represents the 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.

Return Value void

Exceptions

Header dli.h

Related Methods

Availability All DLI-supported platforms. A.32 DLI Reference Guide

dlpdfcontenttranslate (DLPDFCONTENT *Content, ASFixed X, ASFixed Y) Return Value:Concepts void and Facilities: Guide to the DL Pager Composition System

Description Moves all the contents of a content structure by the specified amounts.

Parameters • 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. • 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.

Return Value void

Exceptions

Header dli.h

Related Methods

Availability All DLI-supported platforms. DLI Reference Guide A.33

dlpdfcontentusefillpattern (DLPDFCONTENT *Content, DLPDFPATTERN *Pattern) Return Value: void

Description Applies the fill pattern.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfpatterncreate, dlpdfcontentusestrokepattern

Availability All DLI-supported platforms. A.34 DLI Reference Guide

dlpdfcontentusestrokepattern (DLPDFCONTENT *Content, DLPDFPATTERN *Pattern) Return Value:Concepts void and Facilities: Guide to the DL Pager Composition System

Description Similar to dlpdfcontentusefillpattern, but strokes instead of filling.

Return Value

Exceptions

Header dli.h

Related Methods dlpdfcontentusefillpattern

Availability All DLI-supported platforms. DLI Reference Guide A.35

dlpdfcontentwidetext (DLPDFCONTENT *Content, DLPDFFONT *Font, char *str, int Length, PDEGraphicState *gState, PDETextState *tState, ASFixed PS, ASFixed SW, ASFixed X, ASFixed Y, ASFixed Rotate) Return Value: void

Description Same as dlpdfcontenttext, but permits Unicode and MultiByte text.

Parameters • 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. • DLPDFFON *Font • char *str: A text string • int Length • PDEGraphicState *gState: Contains definitions of colors to be applied, and line sizes and parameters to be used when drawing a path. • 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.

Return Value void

Exceptions A.36 DLI Reference Guide

Header dli.h Concepts and Facilities: Guide to the DL Pager Composition System Related Methods dlpdfcontenttext, dlpdfcontenttextwidth, dlpdfcontentwidetextwidth

Availability All DLI-supported platforms. DLI Reference Guide A.37

Technical Notes

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. A.38 DLI Reference Guide

dlpdfcontentwidetextwidth (DLPDFFONT *Font, char *string, int Length, ASFixed SetWidth, PDETextStateConcepts *TState, and PDEGraphicStateFacilities: Guide to the *GState) DL Pager Composition System Return Value: ASFixed

Description Same as dlpdfcontenttextwidth, but permits multi-byte (Unicode) text.

Parameters • DLPDFFONT *Font • char *string • int Length • ASFixed SetWidth • PDETextState *TState: The current text state. This should not be NULL. A zero-filled PDETextState parameter is permitted. • PDEGraphicState *GState: Contains definitions of colors to be applied, and line sizes and parameters to be used when drawing a path.

Return Value ASFixed

Exceptions

Header dli.h

Related Methods dlpdfcontenttext, dlpdfcontenttextwidth, dlpdfcontentwidetext

Availability All DLI-supported platforms.

Technical Notes

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. DLI Reference Guide A.39

dlpdfdocasciips (DLPDFDOC *Doc) Return Value: void

Description 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 Dis- tiller and most print spoolers will accept binary PostScript data.

Parameters DLPDFDOC *Doc: Represents the document structure and the current status of the document at all times.

Return Value void

Exceptions

Header dli.h

Related Methods

Availability All DLI-supported platforms. A.40 DLI Reference Guide

dlpdfdoccomplete (DLPDFDOC *Doc) Return Value: void Concepts and Facilities: Guide to the DL Pager Composition System

Description Completes the page tree for a document and creates specified thumbnails. It is called internally by dlpdfdocwritepdf and dlpdf- docwritePS, 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.

Parameters DLPDFDOC *Doc: Represents the document structure and the current status of the document at all times.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfdocwritepdf, dlpdfdocwritePS

Availability All DLI-supported platforms. DLI Reference Guide A.41

dlpdfdoccompress (DLPDFDOC *Doc) Return Value: void

Description 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.

Parameters DLPDFDOC *Doc: Represents the document structure and the current status of the document at all times.

Return Value void

Exceptions

Header dli.h

Related Methods

Availability All DLI-supported platforms. A.42 DLI Reference Guide

dlpdfdoccosdoc (DLPDFDOC *Doc) Return Value: CosDoc Concepts and Facilities: Guide to the DL Pager Composition System

Description Used with the COS layer of the Adobe PDF Library to accomplish functions outside DLI.

Parameters DLPDFDOC *Doc: Represents the document structure and the current status of the document at all times.

Return Value CosDoc: Reflects the constructed document

Exceptions

Header dli.h

Related Methods dlpdfdocpddoc, dlpdfdoccomplete

Availability All DLI-supported platforms.

Technical Notes

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. DLI Reference Guide A.43

dlpdfdoccreate (DLPDFINSTANCE *instance) Return Value: DLPDFDOC *

Description Creates a new, empty document.

Parameters DLPDFINSTANCE *instance: The DLPD- FINSTANCE to use for the document

Return Value DLPDFDOC *

Exceptions genErrBadParam

Header dli.h

Related Methods dlpdfdocdestroy, dlpdfdocsetpsname, dlpdfdocwritePS (See Technical Notes below)

Availability All DLI-supported platforms.

Technical Notes

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. A.44 DLI Reference Guide

dlpdfdoccreatesignature (DLPDFDOC *Doc, dlpdfsighandler sigType, char *nameStr, char *reasonStr, char *locationStr)Concepts and Facilities: Guide to the DL Pager Composition System Return Value: DLPDFSIGNATURE *

Description This call creates a digital signature object for the DLI document being created.

Parameters • 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 dli.h

Related Methods dlpdfdocsetsignatureappearance dlpdfpageplacesignature

Availability All DLI-supported platforms. DLI Reference Guide A.45

Technical Notes

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) A.46 DLI Reference Guide

dlpdfdocdestroy (DLPDFDOC *Doc) Return Value: void Concepts and Facilities: Guide to the DL Pager Composition System

Description Destroys the specified document, releasing all resources used in the document.

Parameters DLPDFDOC *Doc: represents the document structure and the current status of the document at all times.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfdoccreate, dlpdfinstancesetgrcachelimits

Availability All DLI-supported platforms.

Technical Notes

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. DLI Reference Guide A.47

dlpdfdocembedfonts (DLPDFDOC *Doc) Return Value: void

Description 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).

Parameters DLPDFDOC *Doc: The document for which to embed all fonts

Return Value void

Exceptions

Header dli.h

Related Methods dlpdffontcreateembedded, dlpdffontcreatewithmetricsembedded

Availability All DLI-supported platforms.

Technical Notes

1 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. A.48 DLI Reference Guide

dlpdfdocencrypt (DLPDFDOC *Doc, char *UserPW, char *OwnerPW, PDPerms Permissions) Return Value:Concepts void and Facilities: Guide to the DL Pager Composition System

Description 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.

Parameters • 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

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfdocsetencryptkeylen

Availability Adobe PDF Library v4.05 and higher; all DLI- supported platforms.

Technical Notes

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. DLI Reference Guide A.49

dlpdfdoclinearize (DLPDFDOC *Doc) Return Value: void

Description Instructs DLI to linearize any PDF output created from this document, regardless of the setting of the linearization flag used at document output time.

Parameters DLPDFDOC *Doc: Represents the document structure and the current status of the document at all times.

Return Value void

Exceptions

Header dli.h

Related Methods

Availability All DLI-supported platforms.

Technical Notes

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. A.50 DLI Reference Guide

dlpdfdocmakethumbnails (DLPDFDOC *Doc) Return Value: void Concepts and Facilities: Guide to the DL Pager Composition System

Description Instructs the application to create thumbnail page images. These will be added to all pages when the file is written to PDF.

Parameters DLPDFDOC *Doc: Represents the document structure and the current status of the document at all times.

Return Value void

Exceptions

Header dli.h

Related Methods

Availability Adobe PDF Library v4.05 and later; all DLI- supported platforms. DLI Reference Guide A.51

dlpdfdocnameadd (DLPDFDOC *Doc, char *TreeName, char *Name, CosObj Dest) Return Value: void

Description 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.

Parameters • DLPDFDOC *Doc: Represents the document structure and the current status of the document at all times. • char *TreeName: TreeName string, or NULL for default TreeName. • char *Name: Name string • CosObj Dest

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfdocnamefind

Availability All DLI-supported platforms. A.52 DLI Reference Guide

dlpdfdocnamefind (DLPDFDOC *Doc, char *TreeName, char *Name,) Return Value:Concepts CosObj and Facilities: Guide to the DL Pager Composition System

Description Locates a name in the tree, and returns its associated COS structure.

Return Value CosObj

Exceptions

Header dli.h

Related Methods dlpdfdocnameadd

Availability All DLI-supported platforms. DLI Reference Guide A.53

dlpdfdocoutline (DLPDFDOC *Doc) Return Value: DLPDFOUTLINE*

Description 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.

Parameters DLPDFDOC *Doc: Represents the document structure and the current status of the document at all times.

Return Value DLPDFOUTLINE*

Exceptions

Header dli.h

Related Methods

Availability All DLI-supported platforms. A.54 DLI Reference Guide

dlpdfdocoutlineadd (DLPDFDOC *Doc, DLPDFOUTLINE *Parent, DLPDFOUTLINE *Before, char *Text, int Open,Concepts long and PageNumbe Facilities: Guider, tochar the *Fit,DL Pager ASFixedRect Composition System *Where, ASFixed Zoom) Return Value: DLPDFOUTLINE*

Description Creates an outline structure within the document specified.

Parameters • 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. DLI Reference Guide A.55

Return Value DLPDFOUTLINE*: Internal structure that reflects the outline entry

Exceptions

Header dli.h

Related Methods dlpdfdocoutlineaddfromname, dlpdfdocoutlinecosobj, dlpdfdocoutlinefirst, dlpdfdocoutlinelast, dlpdfdocoutlinenext, dlpdfdocoutlineparent, dlpdfdocoutlineprev

Availability All DLI-supported platforms.

Technical Notes

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. A.56 DLI Reference Guide

dlpdfdocoutlineaddfromname (DLPDFDOC *Doc, DLPDFOUTLINE *Parent, DLPDFOUTLINE *Before, char *Text, int Open,Concepts char and *DestName) Facilities: Guide to the DL Pager Composition System Return Value: DLPDFOUTLINE*

Description Adds a new outline entry using the named destination, rather than a specified document.

Parameters • DLPDFDOC *Doc: Represents the document structure and the current status of the document at all times. • DLPDFOUTLINE *Parent • DLPDFOUTLINE *Before • char *Text: Text string • int Open • char *DestName: String for destination name

Return Value DLPDFOUTLINE*

Exceptions dlpdfdocoutlineadd, dlpdfdocoutlinecosobj, dlpdfdocoutlinefirst, dlpdfdocoutlinelast, dlpdfdocoutlinenext, dlpdfdocoutlineparent, dlpdfdocoutlineprev

Header dli.h

Related Methods dlpdfdocoutlineadd

Availability All DLI-supported platforms. DLI Reference Guide A.57

dlpdfdocoutlinecosobj (DLPDFOUTLINE *Outline) Return Value: CosObj

Description 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.

Parameters DLPDFOUTLINE *Outline

Return Value CosObj

Exceptions

Header dli.h

Related Methods dlpdfdocoutline

Availability All DLI-supported platforms.

Technical Notes

1 Only the Title, Dest, A (Action), or AA (Additional Action) keys should be modified. Modification of other keys may result in invalid documents. A.58 DLI Reference Guide

dlpdfdocoutlinefirst (DLPDFOUTLINE *Outline) Return Value: DLPDFOUTLINE* Concepts and Facilities: Guide to the DL Pager Composition System

Description Returns a pointer to the first child outline of the specified outline

Parameters DLPDFOUTLINE *Outline

Return Value DLPDFOUTLINE*

Exceptions

Header dli.h

Related Methods dlpdfdocoutlinelast, dlpdfdocoutlinenext, dlpdfdocoutlineparent, dlpdfdocoutlineprev

Availability All DLI-supported platforms.

Technical Notes

1 If the specified outline contains no children, this method will return a NULL. DLI Reference Guide A.59

dlpdfdocoutlinelast (DLPDFOUTLINE *Outline) Return Value: DLPDFOUTLINE*

Description 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.

Parameters DLPDFOUTLINE *Outline

Return Value DLPDFOUTLINE*

Exceptions

Header dli.h

Related Methods dlpdfdocoutlinefirst, dlpdfdocoutlinenext, dlpdfdocoutlineparent, dlpdfdocoutlineprev

Availability All DLI-supported platforms. A.60 DLI Reference Guide

dlpdfdocoutlinenext (DLPDFOUTLINE *Outline) Return Value: DLPDFOUTLINE* Concepts and Facilities: Guide to the DL Pager Composition System

Description Returns a pointer to the outline node that follows the specified node

Parameters DLPDFOUTLINE *Outline

Return Value DLPDFOUTLINE*

Exceptions

Header dli.h

Related Methods dlpdfdocoutlinefirst, dlpdfdocoutlinelast, dlpdfdocoutlineparent, dlpdfdocoutlineprev

Availability All DLI-supported platforms.

Technical Notes

1 If the specified node is the last within its parent, this method will return a NULL. DLI Reference Guide A.61

dlpdfdocoutlineparent (DLPDFOUTLINE *Outline) Return Value: DLPDFOUTLINE*

Description Returns a pointer to the parent of the specified node

Parameters DLPDFOUTLINE *Outline

Return Value DLPDFOUTLINE*

Exceptions

Header dli.h

Related Methods dlpdfdocoutlinefirst, dlpdfdocoutlinelast, dlpdfdocoutlinenext, dlpdfdocoutlineprev

Availability All DLI-supported platforms.

Technical Notes

1 If this node is the root node, this method will return a NULL. A.62 DLI Reference Guide

dlpdfdocoutlineprev (DLPDFOUTLINE *Outline) Return Value: DLPDFOUTLINE* Concepts and Facilities: Guide to the DL Pager Composition System

Description Returns a pointer to the outline node that pre- cedes this node within its container.

Parameters DLPDFOUTLINE *Outline

Return Value DLPDFOUTLINE*

Exceptions

Header dli.h

Related Methods dlpdfdocoutlinefirst, dlpdfdocoutlinelast, dlpdfdocoutlinenext, dlpdfdocoutlineparent

Availability All DLI-supported platforms.

Technical Notes

1 If this is the first node in the container, this node will return a NULL. DLI Reference Guide A.63

dlpdfdocpddoc (DLPDFDOC *Doc) Return Value: PDDoc

Description Used with the PD Layer of the Adobe PDF Library to accomplish functions outside of DLI.

Parameters DLPDFDOC *Doc represents the document structure and the current status of the document at all times.

Return Value PDDoc reflects the constructed document.

Exceptions

Header dli.h

Related Methods dlpdfdoccosdoc

Availability All DLI-supported platforms.

Technical Notes

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. A.64 DLI Reference Guide

dlpdfdocsetdocinfo (DLPDFDOC *Doc, ASAtom Field, char *Value) Return Value:Concepts void and Facilities: Guide to the DL Pager Composition System

Description Creates or replaces an entry in the document’s DocInfo directory

Parameters • DLPDFDOC *Doc: Represents the document structure and the current status of the document at all times. • ASAtom Field: Any name is valid, although only certain names have meaning to PDF readers • char *Value: A string pair

Return Value void

Exceptions

Header dli.h

Related Methods

Availability All DLI-supported platforms.

Technical Notes

1 This method may be called at any time. DLI Reference Guide A.65

dlpdfdocsetencoding (DLPDFDOC *Doc, ASAtom Encoding) Return Value: void

Description Sets the default encoding for fonts used within the document.

Parameters • DLPDFDOC *Doc: Represents the document structure and the current status of the document at all times. • 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

Return Value void

Exceptions genErrBadParam: Raised if any encoding value other than the values specified above (or a NULL document pointer) is passed to this function.

Header dli.h

Related Methods

Availability All DLI-supported platforms. A.66 DLI Reference Guide

dlpdfdocsetencryptkeylen (DLPDFDOC *Doc, unsigned int KeyLenBytes) Return Value:Concepts void and Facilities: Guide to the DL Pager Composition System

Description Enables variable-length encryption keys as supported by the Adobe PDF Library.

Parameters • DLPDFDOC *Doc: Represents the document structure and the current status of the document at all times. • unsigned int KeyLenBytes: The desired encryption key length in bytes, from 5 to 15 inclusive

Return Value void

Exceptions This function itself throws no specific exceptions, but the underlying functions within the Adobe PDF Library may throw exceptions.

Header dli.h

Related Methods dlpdfdocencrypt

Availability All DLI-supported platforms. DLI Reference Guide A.67

Technical Notes

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. A.68 DLI Reference Guide

dlpdfdocsetpdfname (DLPDFDOC *Doc, char *Name) Return Value:Concepts void and Facilities: Guide to the DL Pager Composition System

Description Saves the desired location of a PDF file which results from this document.

Parameters • DLPDFDOC *Doc: Represents the document structure and the current status of the document at all times. • char *Name: This name will be used in place of any name specified in a dlpdfdocwritepdf procedure call.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfdocsetpsname

Availability All DLI-supported platforms.

Technical Notes

dlpdfdocsetpsname (DLPDFDOC *Doc, char *Name) Return Value: void

Description Saves the desired location of a PostScript file which results from this document.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfdocsetpdfname

Availability All DLI-supported platforms.

Technical Notes

dlpdfdocsetsignatureappearance (DLPDFDOC *Doc, DLPDFSIGNATURE *Sig, DLPDFFORM *background,Concepts DLPDFFORM and Facilities: *unverified, Guide to the DLPDFFORM DL Pager Composition System *signature, DLPDFFORM *textSigInfo) Return Value: void

Description 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.

Parameters • 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

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfdoccreatesignature, dlpdfpageplacesignature

Availability All DLI-supported platforms. DLI Reference Guide A.71

dlpdfdocwritepdf (DLPDFDOC *Doc, char *FileName, int Linearize) Return Value: void

Description Writes the document to PDF.

Parameters • DLPDFDOC *Doc: Represents the document structure and the current status of the document at all times. • 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.

Return Value void

Exceptions genErrBadParam: Raised if the filename is not specified.

Header dli.h

Related Methods dlpdfdocwritePS

Availability All DLI-supported platforms. A.72 DLI Reference Guide

dlpdfdocwritePS (DLPDFDOC *Doc, char *FileName) Return Value:Concepts void and Facilities: Guide to the DL Pager Composition System

Description Writes the document to PostScript.

Return Value void

Exceptions genErrBadParam: Raised if the filename is not specified.

Header dli.h

Related Methods dlpdfdocwritepdf

Availability All DLI-supported platforms. DLI Reference Guide A.73

dlpdffontcreate (DLPDFDOC *Doc, char *fontName, char *fontType) Return Value: DLPDFFONT*

Description 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.

Parameters • DLPDFDOC *Doc: The document for which 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.

Return Value The DLPDFFONT * which has been created

Exceptions

Header dli.h

Related Methods dlpdfdocembedfonts, dlpdffontcreateembedded, dlpdffontcreatewithmetrics, dlpdffontcreatewithmetricsembedded

Availability All DLI-supported platforms. A.74 DLI Reference Guide

Technical Notes

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 sameGuide 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. DLI Reference Guide A.75

dlpdffontcreateembedded (DLPDFDOC *Doc, char *fontName, char *fontType, ASBool Subset) Return Value: DLPDFFONT*

Description 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 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.

Parameters • DLPDFDOC *Doc: The document for which to embed all fonts • 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.

Return Value The DLPDFFONT which has been created

Exceptions

Header dli.h

Related Methods dlpdfdocembedfonts, dlpdffontcreate, dlpdffontcreatewithmetrics, dlpdffontcreatewithmetricsembedded

Availability All DLI-supported platforms. A.76 DLI Reference Guide

dlpdffontcreatewithmetrics (DLPDFDOC *Doc, char *fontName, PDEFontAttrs *fontAttrs, unsigned short *Widths,Concepts char and *Encoding Facilities: Guide []) to the DL Pager Composition System Return Value: DLPDFFONT*

Description 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 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.

Parameters • DLPDFDOC *Doc: The document for which to embed all fonts • 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.

Return Value The DLPDFFONT which has been created

Exceptions

Header dli.h DLI Reference Guide A.77

Related Methods dlpdfdocembedfonts, dlpdffontcreate, dlpdffontcreateembedded, dlpdffontcreatewithmetricsembedded

Availability All DLI-supported platforms.

Technical Notes

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. A.78 DLI Reference Guide

dlpdffontcreatewithmetricsembedded (DLPDFDOC *Doc, char *fontName, PDEFontAttrs *fontAttrs, Conceptsunsigned and short Facilities: *Widths, Guide to char the DL *Encoding Pager Composition [], System ASBool Subset) Return Value: DLPDFFONT*

Description 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 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.

Parameters • DLPDFDOC *Doc: The document for which to embed all fonts • 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.

Return Value The DLPDFFONT which has been created DLI Reference Guide A.79

Exceptions

Header dli.h

Related Methods dlpdfdocembedfonts, dlpdffontcreate, dlpdffontcreateembedded, dlpdffontcreatewithmetrics

Availability All DLI-supported platforms.

Technical Notes

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. A.80 DLI Reference Guide

dlpdfformcreate (DLPDFDOC *Doc, DLPDFCONTENT *Content, ASFixedRect *BBox) Return Value:Concepts DLPDFFORM* and Facilities: Guide to the DL Pager Composition System

Description 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.

Parameters • DLPDFDOC *Doc: Name of new form created with this call • DLPDFCONTENT *Content: Represents the 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.

Return Value DLPDFFORM*

Exceptions

Header dli.h

Related Methods dlpdfformdestroy

Availability All DLI-supported platforms. DLI Reference Guide A.81

dlpdfformdestroy (DLPDFFORM *Form) Return Value: void

Description Destroys the named form, releasing its resources and invalidating the form handle.

Parameters DLPDFFORM *Form

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfformcreate

Availability All DLI-supported platforms. A.82 DLI Reference Guide

dlpdfimagecreatefrombmp (DLPDFDOC *Doc, char *ImageName, char *Image, long ImageSize, long Width, LongConcepts Depth, and int Facilities: bpc, CosObj Guide to ColorSpace, the DL Pager Compositionint InLine) System Return Value: DLPDFIMAGE*

Description Creates an image from a bitmap. The map is considered to be scanned left to right and top to bottom.

Parameters • DLPDFDOC *Doc represents the document structure and the current status of the document at all times. • 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, one- channel 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.

Return Value DLPDFIMAGE*

Exceptions

Header dli.h DLI Reference Guide A.83

Related Methods dlpdfimagecreatefromfile, dlpdfimagecreatefrompdf, dlpdfimagecreatefromps

Availability All DLI-supported platforms.

Technical Notes

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. A.84 DLI Reference Guide

dlpdfimagecreatefromfile (DLPDFDOC *Doc, char *Name) Return Value:Concepts DLPDFIMAGE* and Facilities: Guide to the DL Pager Composition System

Description 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.

Parameters • DLPDFDOC *Doc represents the document structure and the current status of the document at all times. • char *Name: Name string

Return Value DLPDFIMAGE*

Exceptions

Header dli.h

Related Methods dlpdfimagecreatefrombmp, dlpdfimagecreatefrompdf, dlpdfimagecreatefromps

Availability Not available on OS/390 DLI Reference Guide A.85

dlpdfimagecreatefrompdf (DLPDFDOC *Doc, char *ImageName, ASFixed Width, ASFixed Depth, ASFixed XDisp, ASFixed YDisp, long Page) Return Value: DLPDFIMAGE*

Description 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.

Parameters • DLPDFDOC *Doc represents the document structure and the current status of the document at all times. • char *ImageName: Image name string • ASFixed Width • ASFixed Depth • ASFixed XDisp • ASFixed YDisp • long Page

Return Value DLPDFIMAGE*

Exceptions

Header dli.h

Related Methods dlpdfimagecreatefrombmp, dlpdfimagecreatefromfile, dlpdfimagecreatefromps

Availability All DLI-supported platforms. A.86 DLI Reference Guide

Technical Notes

1 As of DLI v3.0.11, a value of 0 is now accepted for the Width and Depth parameters. IfConcepts either is 0 and, the Facilities:PDF page's Guide crop box to theis used DL toPager form Compositionthe 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. DLI Reference Guide A.87

dlpdfimagecreatefromps (DLPDFDOC *Doc, char *ImageName, char *Image, long ImageSize, int InLine) Return Value: DLPDFIMAGE*

Description Creates an image from an EPS graphic. It must contain a “%%BoundingBox” statement.

Parameters • DLPDFDOC *Doc represents the document structure and the current status of the document at all times. • 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.

Return Value DLPDFIMAGE*

Exceptions

Header dli.h

Related Methods dlpdfimagecreatefrombmp, dlpdfimagecreatefromfile, dlpdfimagecreatefrompdf

Availability All DLI-supported platforms.

Technical Notes

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. A.88 DLI Reference Guide

dlpdfimagegetsize (DLPDFIMAGE *Image, ASUns32 *xRasters, ASUns32 *yRasters, ASFixed *xPoints, ASFixed *yPoints)Concepts and Facilities: Guide to the DL Pager Composition System Return Value: void

Description This procedure retrieves image size information from a graphic file.

Parameters • 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

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfcontentreferenceimage

Availability All DLI-supported platforms. DLI Reference Guide A.89

Technical Notes

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, Int32ToFixed(72), Int32ToFixed(92), 0, 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 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. A.90 DLI Reference Guide

dlpdfinit (PDFLData pdflLibData, ASFileSys defaultFS, void *unused) Return Value:Concepts DLPDFINSTANCE and Facilities: * Guide to the DL Pager Composition System

Description Initializes the Adobe PDF Library and DLI, and should be called prior to creating the first document.

Parameters • 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 dli.h

Related Methods dlpdfmemfilesys, dlpdfterm

Availability All DLI-supported platforms. DLI Reference Guide A.91

Technical Notes

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 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.

dlpdfinstancesetcancelproc (DLPDFINSTANCE *dliInst, CancelProc cProc, void *cData) Return Value:Concepts void and Facilities: Guide to the DL Pager Composition System

Description 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.

Parameters • 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.

Return Value void

Exceptions

Header dli.h

Related Methods

Availability All DLI-supported platforms. DLI Reference Guide A.93

dlpdfinstancesetgrcachelimits (DLPDFINSTANCE *dliInst, ASUns32 highLimit, ASUns32 deleteLimit) Return Value: void

Description 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.

Parameters • 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.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfdocdestroy

Availability All DLI-supported platforms. A.94 DLI Reference Guide

Technical Notes

1 The highLimit value is a trigger-point setting only, not a storage limit; the cache is allowed to Conceptsgrow 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 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.

dlpdfinstancesetprogressmonitor (DLPDFINSTANCE *dliInst, ProgressMonitor pRec, void *progData) Return Value: void

Description 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.

Parameters • 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.

Return Value void

Exceptions

Header dli.h

Related Methods

Availability All DLI-supported platforms. A.96 DLI Reference Guide

dlpdfmatrixrotate (ASFixedMatrix *Matrix, ASFixed Angle) Return Value:Concepts void and Facilities: Guide to the DL Pager Composition System

Description Rotates a matrix counterclockwise by the specified angle after accepting a pointer to the matrix.

Parameters • ASFixedMatrix *Matrix: Matrix to be rotated • ASFixed Angle: In degrees, as an ASFixed counterclockwise value

Return Value void

Exceptions

Header dli.h

Related Methods

Availability All DLI-supported platforms. DLI Reference Guide A.97

dlpdfmemfileacquire (ASPathName Name) Return Value: MDFile

Description 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.

Parameters ASPathName Name

Return Value MDFile

Exceptions

Header dli.h

Related Methods dlpdfmemfilerelease

Availability All DLI-supported platforms. A.98 DLI Reference Guide

dlpdfmemfiledata (MDFile File) Return Value: unsigned const char * Concepts and Facilities: Guide to the DL Pager Composition System

Description 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.

Parameters MDFile File

Return Value unsigned const char *

Exceptions

Header dli.h

Related Methods dlpdfmemfileacquire, dlpdfmemfilerelease, dlpdfmemfilesize

Availability All DLI-supported platforms. DLI Reference Guide A.99

dlpdfmemfiledeleteonclose (MDFile File) Return Value: void

Description 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.

Parameters MDFile File

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfmemfileacquire, dlpdfmemfilerelease

Availability All DLI-supported platforms. A.100 DLI Reference Guide

dlpdfmemfilerelease (MDFile File) Return Value: int Concepts and Facilities: Guide to the DL Pager Composition System

Description Relinquishes one acquisition as made by the dlpdfmemfileacquire call, and returns the number of acquisitions left on the file.

Parameters MDFile

Return Value Int

Exceptions

Header dli.h

Related Methods dlpdfmemfileacquire

Availability All DLI-supported platforms.

Technical Notes

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. DLI Reference Guide A.101

dlpdfmemfilesetbuffer (MDFile File, unsigned char * Data, ASSize_t Size) Return Value: ASBool

Description 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.

Parameters • MDFile File: File to be overwritten • unsigned char * Data: Memory to replace the File’s previous content. • ASSize_t Size

Return Value ASBool: TRUE is returned if the file’s data buffer could be set to this memory, FALSE if it could not.

Exceptions

Header dli.h

Related Methods dlpdfmemfileacquire, dlpdfmemfilerelease, dlpdfmemfilesetdata

Availability All DLI-supported platforms.

Technical Notes

1 As of DLI v3.0.11, the dlpdfmemfilesetbuffer and dlpdfmemfilesetdata calls no longer rewind the memory files to position 0. A.102 DLI Reference Guide

dlpdfmemfilesetdata (MDFile File, unsigned const char * Data, ASSize_t Size) Return Value:Concepts ASBool and Facilities: Guide to the DL Pager Composition System

Description Sets the file passed in to contain the data passed to the function. This completely overwrites the file’s previous contents.

Parameters • MDFile File: File to be overwritten • unsigned const char * Data: Data that replaces File content. • ASSize_t Size

Return Value ASBool: TRUE is returned if the file could be set to this data, FALSE if it could not.

Exceptions

Header dli.h

Related Methods dlpdfmemfileacquire, dlpdfmemfilerelease, dlpdfmemfilesetbuffer

Availability All DLI-supported platforms.

Technical Notes

1 As of DLI v3.0.11, the dlpdfmemfilesetbuffer and dlpdfmemfilesetdata calls no longer rewind the memory files to position 0. DLI Reference Guide A.103

dlpdfmemfilesize (MDFile File) Return Value: ASSize_t

Description 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.

Parameters MDFile File

Return Value ASSize_t

Exceptions

Header dli.h

Related Methods dlpdfmemfileacquire, dlpdfmemfilerelease

Availability All DLI-supported platforms. A.104 DLI Reference Guide

dlpdfmemfilesys (void) Return Value: ASFileSys Concepts and Facilities: Guide to the DL Pager Composition System

Description 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.

Parameters None

Return Value ASFileSys

Exceptions

Header dli.h

Related Methods dlpdfinit, dlpdfmemfileacquire, dlpdfmemfilerelease

Availability All DLI-supported platforms.

Technical Notes

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. DLI Reference Guide A.105

dlpdfmemfilesysgetmemusage (void) Return Value: ASSize_t

Description This returns an ASSize_t with the current usage, in bytes, of memory for Files In Memory file contents by DLI.

Parameters None

Return Value ASSize_t

Exceptions

Header dli.h

Related Methods dlpdfmemfileacquire, dlpdfmemfilerelease dlpdfmemfilesyssetmemlimit

Availability All DLI-supported platforms. A.106 DLI Reference Guide

dlpdfmemfilesyssetmemlimit (ASSize_t memLimit) Return Value:Concepts void and Facilities: Guide to the DL Pager Composition System

Description This establishes an upper bound, in bytes, of the memory usage allowed for Files In Memory file contents by DLI.

Parameters ASSize_t memLimit

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfmemfileacquire, dlpdfmemfilerelease dlpdfmemfilesysgetmemusage

Availability All DLI-supported platforms. DLI Reference Guide A.107

dlpdfmemfiletransientprefix (void) Return Value: const char *

Description Returns a NULL-terminated string representing the prefix for the transient files

Parameters None

Return Value const char *

Exceptions

Header dli.h

Related Methods dlpdfmemfileacquire, dlpdfmemfilerelease

Availability All DLI-supported platforms.

Technical Notes

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. A.108 DLI Reference Guide

dlpdfpageaddlinkannotation (DLPDFPAGE *Page, ASFixedRect *Location, ASFixed *Border, ASFixed *Color, longConcepts PageNumber, and Facilities: Char Guide *Fit, to ASFixedRect the DL Pager Composition *Where, System ASFixed *Zoom) Return Value: CosObj

Description Creates a link annotation in the specified page.

Parameters • 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. DLI Reference Guide A.109

Parameters (Continued) • 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.

Return Value CosObj: The actual link structure which may be modified by the user to access capabilities beyond this interface.

Exceptions

Header dli.h

Related Methods dlpdfpageaddlinkannotationfromname, dlpdfpageaddtextannotation, dlpdfpageaddwebannotation

Availability All DLI-supported platforms. A.110 DLI Reference Guide

Technical Notes

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. DLI Reference Guide A.111

dlpdfpageaddlinkannotationfromname (DLPDFPAGE *Page, ASFixedRect *Location, ASFixed *Border, ASFixed *Color, char *Target) Return Value: CosObj

Description Adds a new link to a page using the named destination rather than a specified destination.

Parameters • DLPDFPAGE *Page • ASFixedRect *Location: Location of rectangle • ASFixed *Border • ASFixed *Color: Link color • char *Target

Return Value CosObj

Exceptions

Header dli.h

Related Methods dlpdfpageaddlinkannotation, dlpdfpageaddtextannotation, dlpdfpageaddwebannotation

Availability All DLI-supported platforms. A.112 DLI Reference Guide

dlpdfpageaddtextannotation (DLPDFPAGE *Page, ASFixedRect *Location, ASFixed *Border, ASFixed *Color, charConcepts *Title, andchar Facilities: *Contents, Guide toint the Open) DL Pager Composition System Return Value: CosObj

Description Creates a text annotation within the specified page.

Parameters • 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.

Return Value CosObj

Exceptions

Header dli.h DLI Reference Guide A.113

Related Methods dlpdfpageaddlinkannotation, dlpdfpageaddlinkannotationfromname, dlpdfpageaddwebannotation

Availability All DLI-supported platforms.

Technical Notes

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. A.114 DLI Reference Guide

dlpdfpageaddwebannotation (DLPDFPAGE *Page, ASFixedRect *Location, ASFixed *Border, ASFixed *Color, charConcepts *URIDestination) and Facilities: Guide to the DL Pager Composition System Return value: CosObj

Description Adds a new link to a page, using a URI (equivalent to URL) destination given by the URIDes- tination parameter. This URI is assumed to be in UTF-8 text format; support for URIs in other character sets is unavailable at this time.

Parameters • DLPDFPAGE *Page • ASFixedRect *Location • ASFixed *Border • ASFixed *Color • char *URIDestination: URI destination in UTF-8 text format.

Return Value CosObj

Exceptions

Header dli.h

Related Methods dlpdfpageaddlinkannotation, dlpdfpageaddlinkannotationfromname, dlpdfpageaddtextannotation

Availability All DLI-supported platforms.

Technical Notes

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. DLI Reference Guide A.115

dlpdfpagecosobj (DLPDFPAGE *Page) Return Value: CosObj

Description 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.

Parameters DLPDFPAGE *Page

Return Value CosObj

Exceptions

Header dli.h

Related Methods

Availability All DLI-supported platforms. A.116 DLI Reference Guide

dlpdfpagecreate (DLPDFDOC *Doc, ASFixed Width, ASFixed Height) Return Value:Concepts DLPDFPAGE* and Facilities: Guide to the DL Pager Composition System

Description Creates a new page in the current document, positioned to follow all other pages in the current document.

Parameters • DLPDFDOC *Doc: Represents the document structure and the current status of the document at all times. • 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.

Return Value DLPDFPAGE*

Exceptions genErrBadParam: Raised if the specified document does not exist.

Header dli.h

Related Methods

Availability All DLI-supported platforms. DLI Reference Guide A.117

dlpdfpagefindfromnumber (DLPDFDOC *Doc, long PageNumber) Return Value: DLPDFPAGE*

Description 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.

Parameters • DLPDFDOC *Doc represents the document structure and the current status of the document at all times. • long PageNumber

Return Value DLPDFPAGE*

Exceptions

Header dli.h

Related Methods

Availability All DLI-supported platforms. A.118 DLI Reference Guide

dlpdfpagenumber (DLPDFPAGE *Page) Return Value: long Concepts and Facilities: Guide to the DL Pager Composition System

Description 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.

Parameters DLPDFPAGE *Page

Return Value long

Exceptions

Header dli.h

Related Methods

Availability All DLI-supported platforms. DLI Reference Guide A.119

dlpdfpagerotate (DLPDFPAGE *Page, PDRotate Angle) Return Value: void

Description 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.

Parameters • DLPDFPAGE *Page • PDRotate Angle

Return Value void

Exceptions

Header dli.h

Related Methods

Availability All DLI-supported platforms.

Technical Notes

1 This call may be issued at any time after a page is created, and will be effective in PDF and Adobe PostScript. A.120 DLI Reference Guide

dlpdfpagesetart (DLPDFPAGE *Page, ASFixedRect *Rect) Return Value:Concepts void and Facilities: Guide to the DL Pager Composition System

Description 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.

Parameters • DLPDFPAGE *Page • ASFixedRect *Rect

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfpagesetbleed, dlpdfpagesetcrop, dlpdfpagesetmediabox, dlpdfpagesettrim

Availability All DLI-supported platforms. DLI Reference Guide A.121

dlpdfpagesetbleed (DLPDFPAGE *Page, ASFixedRect *Rect) Return Value: void

Description Sets the Bleed 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.

Parameters • DLPDFPAGE *Page • ASFixedRect *Rect

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfpagesetart, dlpdfpagesetcrop, dlpdfpagesetmediabox, dlpdfpagesettrim

Availability All DLI-supported platforms. A.122 DLI Reference Guide

dlpdfpagesetcrop (DLPDFPAGE *Page, ASFixedRect *Rect) Return Value:Concepts void and Facilities: Guide to the DL Pager Composition System

Description Sets the Crop 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.

Parameters • DLPDFPAGE *Page • ASFixedRect *Rect

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfpagesetart, dlpdfpagesetbleed, dlpdfpagesetmediabox, dlpdfpagesettrim

Availability All DLI-supported platforms. DLI Reference Guide A.123

dlpdfpagesetid (DLPDFPAGE *Page, char *Id) Return Value: void

Description Adds an ID Entry to the page dictionary. This is generally a page’s FOLIO.

Parameters • DLPDFPAGE *Page • char *Id: ID entry.

Return Value void

Exceptions

Header dli.h

Related Methods

Availability All DLI-supported platforms. A.124 DLI Reference Guide

dlpdfpagesetmediabox (DLPDFPAGE *Page, ASFixedRect *Rect) Return Value:Concepts void and Facilities: Guide to the DL Pager Composition System

Description 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.

Parameters • DLPDFPAGE *Page • ASFixedRect *Rect

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfpagesetart, dlpdfpagesetbleed, dlpdfpagesetcrop, dlpdfpagesettrim

Availability All DLI-supported platforms. DLI Reference Guide A.125

dlpdfpagesettrim (DLPDFPAGE *Page, ASFixedRect *Rect) Return Value: void

Description Sets the Trim 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.

Parameters • DLPDFPAGE *Page • ASFixedRect *Rect

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfpagesetart, dlpdfpagesetbleed, dlpdfpagesetcrop, dlpdfpagesetmediabox

Availability All DLI-supported platforms. A.126 DLI Reference Guide

dlpdfpathaddarc (DLPDFPATH *Path, ASFixed X, ASFixed Y, ASFixed Rad, ASFixed T1, ASFixed T2) Return Value:Concepts void and Facilities: Guide to the DL Pager Composition System

Description Appends an arc segment to the current path. The current position will be set to the ending point.

Parameters • 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

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfpathaddarcn, dlpdfpatthaddarcto, dlpdfpathaddelliparc, dlpdfpathadddelliparcn, dlpdfpathaddelliparcto

Availability All DLI-supported platforms.

Technical Notes

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. DLI Reference Guide A.127

dlpdfpathaddarcn (DLPDFPATH *Path, ASFixed X, ASFixed Y, ASFixed Rad, ASFixed T1, ASFixed T2) Return Value: void

Description Identical to dlpdfpathaddarc, except the arc will be drawn clockwise.

Parameters • DLPDFPATH *Path is the pointer to the path. • ASFixed X • ASFixed Y • ASFixed Rad • ASFixed T1 • ASFixed T2

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfpathaddarc, dlpdfpatthaddarcto, dlpdfpathaddelliparc, dlpdfpathadddelliparcn, dlpdfpathaddelliparcto

Availability All DLI-supported platforms. A.128 DLI Reference Guide

dlpdfpathaddarcto (DLPDFPATH *Path, ASFixed X1, ASFixed Y1, ASFixed X2, ASFixed Y2, ASFixed Rad) Return Value:Concepts void and Facilities: Guide to the DL Pager Composition System

Description Appends a straight line segment from the current position towards the first pair of X and Y coordinates specified, terminating when it inter- sects 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.

Parameters • DLPDFPATH *Path is the pointer to the 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.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfpathaddarcn, dlpdfpatthaddarc, dlpdfpathaddelliparc, dlpdfpathadddelliparcn, dlpdfpathaddelliparcto

Availability All DLI-supported platforms. DLI Reference Guide A.129

X1/Y1 Xint1/ Xint2/ Yint1 Yint2

Current Position X2/Y2

Technical Notes

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. A.130 DLI Reference Guide

dlpdfpathaddclose (DLPDFPATH *Path) Return Value: void Concepts and Facilities: Guide to the DL Pager Composition System

Description Appends a “close path” operator to the path. The current position after the path is closed is (1,-1).

Parameters DLPDFPATH *Path is the pointer to the path

Return Value void

Exceptions

Header dli.h

Related Methods

Availability All DLI-supported platforms. DLI Reference Guide A.131

dlpdfpathaddcurve (DLPDFPATH *Path, ASFixed Ctrl1X, ASFixed Ctrl1Y, ASFixed Ctrl2X, ASFixed Ctrl2Y, ASFixed EndX, ASFixed EndY) Return Value: void

Description Adds a spline or cubic Bézier curve to the path.

Parameters • DLPDFPATH *Path is the pointer to the path. • ASFixed Ctrl1X is the X position of a point which will be Control Point 1. • ASFixed Ctrl1Y is the Y position of a point which will be Control Point 1. • ASFixed Ctrl2X is the X position of a point which will be Control Point 2. • ASFixed Ctrl2Y is the Y position of a point which will be Control Point 2. • ASFixed EndX is the X position which will be the end point of the curve. • ASFixed EndY is the Y position which will be the end point of the curve.

Return Value void

Exceptions genErrBadParam is returned if no starting point is specified.

Header dli.h

Related Methods dlpdfpathaddcurver, dlpdfpathaddcurvev, dlpdfpathaddcurvey

Availability All DLI-supported platforms. A.132 DLI Reference Guide

Ctrl1X/ ConceptsCtrl1Y and Facilities: Guide to the DL Pager Composition System EndX/ EndY

StartX/ StartY Ctrl2X/ Ctrl2Y

Technical Notes

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). DLI Reference Guide A.133

dlpdfpathaddcurver (DLPDFPATH *Path, ASFixed Ctrl1X, ASFixed Ctrl1Y, ASFixed Ctrl2X, ASFixed Ctrl2Y, ASFixed EndX, ASFixed EndY) Return Value: void

Description Identical to dlpdfpathaddcurve, except that the positions are expressed as relative distances from the current point, not absolute distances from the origin.

Parameters • DLPDFPATH *Path is the pointer to the path • ASFixed Ctrl1X is the X position of a point which will be Control Point 1. • ASFixed Ctrl1Y is the Y position of a point which will be Control Point 1. • ASFixed Ctrl2X is the X position of a point which will be Control Point 2. • ASFixed Ctrl2Y is the Y position of a point which will be Control Point 2. • ASFixed EndX is the X position which will be the end point of the curve. • ASFixed EndY is the Y position which will be the end point of the curve.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfpathaddcurve, dlpdfpathaddcurvev, dlpdfpathaddcurvey

Availability All DLI-supported platforms. A.134 DLI Reference Guide

dlpdfpathaddcurvev (DLPDFPATH *Path, ASFixed Ctrl2X, ASFixed Ctrl2Y, ASFixed EndX, ASFixed EndY) Return Value:Concepts void and Facilities: Guide to the DL Pager Composition System

Description Identical to dlpdfpathaddcurve, except that both the start and first control point are assumed to be the current position.

Parameters • DLPDFPATH *Path: The pointer to the path. • ASFixed Ctrl2X: The X position of a point which will be Control Point 2. • ASFixed Ctrl2Y: The Y position of a point which will be Control Point 2. • ASFixed EndX: The X position which will be the end point of the curve. • ASFixed EndY: The Y position which will be the end point of the curve.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfpathaddcurve, dlpdfpathaddcurver, dlpdfpathaddcurvey

Availability All DLI-supported platforms. DLI Reference Guide A.135

EndX/ EndY

StartX/ StartY Ctrl1X/ Ctrl2X/ Ctrl1Y Ctrl2Y

Technical Notes

1 This method is identical to dlpdfpathaddcurve, except that both the start and first control point are assumed to be the current position. A.136 DLI Reference Guide

dlpdfpathaddcurvey (DLPDFPATH *Path, ASFixed Ctrl1X, ASFixed Ctrl1Y, ASFixed EndX, ASFixed EndY) Return Value:Concepts void and Facilities: Guide to the DL Pager Composition System

Description Identical to dlpdfpathaddcurve, except that the second control point is assumed to be the ending position.

Parameters • DLPDFPATH *Path is the pointer to the path • ASFixed Ctrl1X • ASFixed Ctrl1Y • ASFixed EndX • ASFixed EndY

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfpathaddcurve, dlpdfpathaddcurver, dlpdfpathaddcurvev

Availability All DLI-supported platforms. DLI Reference Guide A.137

Ctrl1X/ Ctrl1Y

EndX/ EndY Ctrl2X/ Ctrl2Y StartX/ StartY

Technical Notes

1 This method is identical to dlpdfpathaddcurve, except that the second control point is assumed to be the ending position. A.138 DLI Reference Guide

dlpdfpathaddelliparc (DLPDFPATH *Path, ASFixed CentX, ASFixed CentY, ASFixed HRad, ASFixed VRad, ASFixedConcepts T1, ASFixed and Facilities: T2) Guide to the DL Pager Composition System Return Value: void

Description Appends an arc segment to the current path. This method accepts seven parameters.

Parameters • DLPDFPATH *Path is the pointer to the path. • ASFixed CentX is the X-axis position of the arc center point. • ASFixed CentY is the Y-axis position of the arc center point. • 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.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfpathaddarc, dlpdfpathaddarcn, dlpdfpatthaddarcto, dlpdfpathadddelliparcn, dlpdfpathaddelliparcto

Availability DLI Reference Guide A.139

Technical Notes

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. A.140 DLI Reference Guide

dlpdfpathaddelliparcn (DLPDFPATH *Path, ASFixed CentX, ASFixed CentY, ASFixed HRad, ASFixed VRad, ASFixedConcepts T1, ASFixed and Facilities: T2) Guide to the DL Pager Composition System Return Value: void

Description This method is identical to dlpdfpathaddelliparc, except that the arc will be drawn clockwise.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfpathaddarc, dlpdfpathaddarcn, dlpdfpatthaddarcto, dlpdfpathaddelliparc, dlpdfpathaddelliparcto

Availability All DLI-supported platforms. DLI Reference Guide A.141

dlpdfpathaddelliparcto (DLPDFPATH *Path, ASFixed X1, ASFixed Y1, ASFixed X2, ASFixed Y2, ASFixed HRad, ASFixed VRad) Return Value: void

Parameters • 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

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfpathaddarc, dlpdfpathaddarcn, dlpdfpathaddarcto, dlpdfpathaddelliparc

Availability All DLI-supported platforms. A.142 DLI Reference Guide

dlpdfpathaddline (DLPDFPATH *Path, ASFixed X, ASFixed Y) Return Value:Concepts void and Facilities: Guide to the DL Pager Composition System

Description 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.

Parameters • DLPDFPATH *Path is the pointer to the path. • ASFixed X is the absolute X-axis position. • ASFixed Y is the absolute Y-axis position.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfpathaddliner

Availability All DLI-supported platforms. DLI Reference Guide A.143

dlpdfpathaddliner (DLPDFPATH *Path, ASFixed X, ASFixed Y) Return Value: void

Description 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.

Parameters • DLPDFPATH *Path is the pointer to the 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.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfpathaddline

Availability All DLI-supported platforms. A.144 DLI Reference Guide

dlpdfpathaddmove (DLPDFPATH *Path, ASFixed X, ASFixed Y) Return Value:Concepts void and Facilities: Guide to the DL Pager Composition System

Description 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.

Parameters • DLPDFPATH *Path is the pointer to the path. • ASFixed X is the specified X-axis position. • ASFixed Y is the specified Y-axis position.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfpathaddmover

Availability All DLI-supported platforms. DLI Reference Guide A.145

dlpdfpathaddmover (DLPDFPATH *Path, ASFixed X, ASFixed Y) Return Value: void

Description 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.

Parameters • DLPDFPATH *Path is the pointer to the 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.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfpathaddmove

Availability All DLI-supported platforms. A.146 DLI Reference Guide

dlpdfpathaddrect (DLPDFPATH *Path, ASFixed X, ASFixed Y, ASFixed Width, ASFixed Depth) Return Value:Concepts void and Facilities: Guide to the DL Pager Composition System

Description Draws a rectangle.

Parameters • DLPDFPATH *Path is the pointer to the 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

Return Value void

Exceptions

Header dli.h

Related Methods

Availability All DLI-supported platforms.

Technical Notes

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. DLI Reference Guide A.147

dlpdfpatharray (DLPDFPATH *Path) Return Value: ASFixed*

Description This method will return a pointer to the first member of the array of ASFixed integers, which is the path.

Parameters DLPDFPATH *Path is the pointer to the path.

Return Value ASFixed*

Exceptions

Header dli.h

Related Methods

Availability All DLI-supported platforms. A.148 DLI Reference Guide

dlpdfpathclear (DLPDFPATH *Path) Return Value: void Concepts and Facilities: Guide to the DL Pager Composition System

Description 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.

Parameters DLPDFPATH *Path is the pointer to the path.

Return Value void

Exceptions genErrBadParam is raised if the method is called with a NULL pointer.

Header dli.h

Related Methods

Availability All DLI-supported platforms. DLI Reference Guide A.149

dlpdfpathcreate (void) Return Value: DLPDFPATH*

Description Creates a new, empty DLPDFPATH structure.

Parameters None

Return Value DLPDFPATH*

Exceptions genErrNoMemory

Header dli.h

Related Methods dlpdfpathdestroy

Availability All DLI-supported platforms. A.150 DLI Reference Guide

dlpdfpathcurrentx (DLPDFPATH *Path) Return Value: ASFixed Concepts and Facilities: Guide to the DL Pager Composition System

Description This method will return the current X position as an ASFixed value.

Parameters DLPDFPATH *Path is the pointer to the path

Return Value ASFixed

Exceptions

Header dli.h

Related Methods dlpdfpathcurrenty

Availability All DLI-supported platforms. DLI Reference Guide A.151

dlpdfpathcurrenty (DLPDFPATH *Path) Return Value: ASFixed

Description This method will return the current Y position as an ASFixed value.

Parameters DLPDFPATH *Path is the pointer to the path.

Return Value ASFixed

Exceptions

Header dli.h

Related Methods dlpdfpathcurrentx

Availability All DLI-supported platforms. A.152 DLI Reference Guide

dlpdfpathdestroy (DLPDFPATH *Path) Return Value: void Concepts and Facilities: Guide to the DL Pager Composition System

Description Destroys a DLPDFPATH structure and frees its resources.

Parameters DLPDFPATH *Path: The pointer to the path

Return Value void

Exceptions genErrBadParam: Raised if the pointer is not valid

Header dli.h

Related Methods dlpdfpathcreate

Availability All DLI-supported platforms. DLI Reference Guide A.153

dlpdfpathsetmatrix (DLPDFPATH *Path, ASFixedMatrix *Matrix) Return Value: void

Description 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.

Parameters • DLPDFPATH *Path is the pointer to the path • ASFixedMatrix *Matrix

Return Value void

Exceptions genErrBadParam exception is raised if the pointer to the path or the matrix is NULL

Header dli.h

Related Methods

Availability All DLI-supported platforms. A.154 DLI Reference Guide

dlpdfpathsize (DLPDFPATH *Path) Return Value: ASInt32 Concepts and Facilities: Guide to the DL Pager Composition System

Description This method will return the current size of the path array as an integer.

Parameters DLPDFPATH *Path is the pointer to the path.

Return Value ASInt32

Exceptions

Header dli.h

Related Methods

Availability All DLI-supported platforms. DLI Reference Guide A.155

dlpdfpatterncreate (DLPDFDOC *Doc, DLPDFCONTENT *Content, ASFixedRect *BBox, ASFixedMatrix *Matrix, int Colored, int TileType, ASFixed XStep, ASFixed YStep) Return Value: DLPDFPATTERN*

Description 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.

Parameters • DLPDFDOC *Doc: represents the document structure and the current status of the document at all times. • 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. • ASFixedRect *BBox • ASFixedMatrix *Matrix • int Colored • int TileType • ASFixed XStep • ASFixed YStep

Return Value DLPDFPATTERN*

Exceptions

Header dli.h

Related Methods dlpdfcontentusefillpattern, dlpdfcontentusestrokepattern

Availability All DLI-supported platforms. A.156 DLI Reference Guide

dlpdfpatternrotate (ASFixedMatrix *Matrix, ASFixed Angle) Return Value:Concepts void and Facilities: Guide to the DL Pager Composition System

Description 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.

Parameters • ASFixedMatrix *Matrix • ASFixed Angle

Return Value void

Exceptions

Header dli.h

Related Methods

Availability All DLI-supported platforms. DLI Reference Guide A.157

dlpdfpageplacesignature (DLPDFPAGE *Page, DLPDFSIGNATURE *Sig, ASFixedRect *imageBBox) Return Value: void

Description 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.

Parameters • 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.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfdoccreatesignature, dlpdfdocsetsignatureappearance dlpdfdocwritepdf

Availability All DLI-supported platforms. A.158 DLI Reference Guide

dlpdfseterrorfile (FILE *errorFilePtr) Return Value: void Concepts and Facilities: Guide to the DL Pager Composition System

Description Sets file to which error messages will be logged.

Parameters File *errorFilePtr: By default error messages are logged to stderr

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfsetwarningfile

Availability All DLI-supported platforms. DLI Reference Guide A.159

dlpdfsetwarningfile (FILE * warningFilePtr) Return Value: void

Description Sets file to which warning messages will be logged.

Parameters File *warningFilePtr: By default warning messages are not logged.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfseterrorfile

Availability All DLI-supported platforms. A.160 DLI Reference Guide

dlpdfsignaturesetdatacallback (DLPDFSIGNATURE *signature, void (*dataCallback)(char *, int)) Concepts and Facilities: Guide to the DL Pager Composition System Return Value: void

Description This is an optional call for clients using PKCS #7 certificates. A callback function is supplied for the signature.

Parameters • 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.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfsignaturesetpkcs7cert dlpdfdocwritepdf

Availability All DLI-supported platforms.

Technical Notes

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. DLI Reference Guide A.161

dlpdfsignaturesetpkcs7cert (DLPDFSIGNATURE *signature, int maxLen, int (*genPKCS7Cert)(char *)) Return Value: void

Description This function sets the certificate generation callback for DLPDFSIGNATUREs of type dlpdfsigacropkcs7 and dlpdfsigverisign.

Parameters • DLPDFSIGNATURE *signature: signature with which certificate will be associated • int maxlen: number of bytes provided to the genPKCS7Cert callback • int (*genPKCS7Cert)(char *): callback function, called during the dlpdfdocwritepdf function call; see Technical Notes below.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfdocwritepdf dlpdfsignaturesetdatacallback dlpdfsignaturesetx509cert

Availability All DLI-supported platforms.

Technical Notes

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 A.162 DLI Reference Guide

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 theConcepts length to andread Facilities:from the data Guide buffer, to thein bytes. DL Pager Composition System

dlpdfsignaturesetx509cert (DLPDFSIGNATURE *signature, char *certificate, int certLen, void (*encryptSHA1Hash)(char *)) Return Value: void

Description This call associates an x.509 v3 certificate with a DLPDFSIGNATURE object created as a dlpdfsigacrox509 certificate digital signature.

Parameters • DLPDFSIGNATURE *signature: 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 dlpdfdocwritepdf function call; see Technical Notes below.

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfdocwritepdf dlpdfsignaturesetpkcs7cert

Availability All DLI-supported platforms.

Technical Notes

1 It is an error to call this with a DLPDFSIGNATURE object created as a different A.164 DLI Reference Guide

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 Concepts and Facilities: Guide to the DL Pager Composition System 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. DLI Reference Guide A.165

dlpdfterm (DLPDFINSTANCE * instance) Return Value: void

Description Terminates the Adobe PDF Library and DLI. All active documents should be closed prior to this call.

Parameters DLPDFINSTANCE *instance

Return Value void

Exceptions

Header dli.h

Related Methods dlpdfinit, dlpdfttload

Availability All DLI-supported platforms.

Technical Notes

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. A.166 DLI Reference Guide

dlpdftext (void *Text, ASUns32 Length, ASAtom Encoding) Return Value:Concepts DLPDFTEXT* and Facilities: Guide to the DL Pager Composition System

Description Returns a DLPDFTEXT structure for the given Text and Length, in the given Encoding.

Parameters • 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

Return Value DLPDFTEXT*

Exceptions

Header dli.h

Related Methods dlpdftextfromutf8, dlpdftextfromutf16be, dlpdftextfromutf16he, dlpdftextfromutf16le, dlpdftextfromutf32be, dlpdftextfromutf32he, dlpdftextfromutf32le

Availability All DLI-supported platforms.

Technical Notes

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. DLI Reference Guide A.167

dlpdftextadvance (DLPDFTEXT *Text, DLPDFFONT *Font, PDEGraphicState *GState, PDETextState *TState, ASFixed PointSize, ASFixed SetWidth, dlpdftext_X XMeaning, ASFixed Angle, ASFixedPoint *Advance) Return Value: void

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

Parameters • DLPDFTEXT *Text: the text structure to be acted upon • DLPDFFONT *Font: The specified font • PDEGraphicState *GState: Contains definitions of colors to be applied, and line sizes and parameters to be used when drawing a path • PDETextState *TState: Current text state; should not be NULL. A zero-filled PDETextState parameter is permitted. • 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

Return Value void

Exceptions A.168 DLI Reference Guide

Header dli.h Concepts and Facilities: Guide to the DL Pager Composition System Related Methods

Availability All DLI-supported platforms. DLI Reference Guide A.169

dlpdftextdestroy (DLPDFTEXT *Text) Return Value: void

Description This method destroys the indicated DLPDFTEXT instance.

Parameters DLPDFTEXT *Text: the text structure to be acted upon

Return Value void

Exceptions

Header dli.h

Related Methods dlpdftext

Availability All DLI-supported platforms. A.170 DLI Reference Guide

dlpdftextfromutf16be (void *Text) Return Value: DLPDFTEXT* Concepts and Facilities: Guide to the DL Pager Composition System

Description Returns a DLPDFTEXT structure for the given UTF16 big-endian Unicode Text string.

Parameters void *Text: the text to be passed to the DLP- DFTEXT structure

Return Value DLPDFTEXT*

Exceptions

Header dli.h

Related Methods dlpdftext, dlpdftextfromutf16he, dlpdftextfromutf16le, dlpdftextfromutf32be, dlpdftextfromutf32he, dlpdftextfromutf32le, dlpdftextfromutf8

Availability All DLI-supported platforms.

Technical Notes

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. DLI Reference Guide A.171

dlpdftextfromutf16he (void *Text) Return Value: DLPDFTEXT*

Description Returns a DLPDFTEXT structure for the given UTF16 host-endian Unicode Text string.

Parameters void *Text: the text to be passed to the DLP- DFTEXT structure

Return Value DLPDFTEXT*

Exceptions

Header dli.h

Related Methods dlpdftext, dlpdftextfromutf16be, dlpdftextfromutf16le, dlpdftextfromutf32be, dlpdftextfromutf32he, dlpdftextfromutf32le, dlpdftextfromutf8

Availability All DLI-supported platforms.

Technical Notes

dlpdftextfromutf16le (void *Text) Return Value: DLPDFTEXT* Concepts and Facilities: Guide to the DL Pager Composition System

Description Returns a DLPDFTEXT structure for the given UTF16 little-endian Unicode Text string.

Parameters void *Text: the text to be passed to the DLP- DFTEXT structure

Return Value DLPDFTEXT*

Exceptions

Header dli.h

Related Methods dlpdftext, dlpdftextfromutf16be, dlpdftextfromutf16he, dlpdftextfromutf32be, dlpdftextfromutf32he, dlpdftextfromutf32le, dlpdftextfromutf8

Availability All DLI-supported platforms.

Technical Notes

dlpdftextfromutf32be (void *Text) Return Value: DLPDFTEXT*

Description Returns a DLPDFTEXT structure for the given UTF32 big-endian Unicode Text string.

Parameters void *Text: the text to be passed to the DLP- DFTEXT structure

Return Value DLPDFTEXT*

Exceptions

Header dli.h

Related Methods dlpdftext, dlpdftextfromutf16be, dlpdftextfromutf16he, dlpdftextfromutf16le, dlpdftextfromutf32he, dlpdftextfromutf32le, dlpdftextfromutf8

Availability All DLI-supported platforms.

Technical Notes

dlpdftextfromutf32he (void *Text) Return Value: DLPDFTEXT* Concepts and Facilities: Guide to the DL Pager Composition System

Description Returns a DLPDFTEXT structure for the given UTF32 host-endian Unicode Text string.

Parameters void *Text: the text to be passed to the DLP- DFTEXT structure

Return Value DLPDFTEXT*

Exceptions

Header dli.h

Related Methods dlpdftext, dlpdftextfromutf16be, dlpdftextfromutf16he, dlpdftextfromutf16le, dlpdftextfromutf32be, dlpdftextfromutf32le, dlpdftextfromutf8

Availability All DLI-supported platforms.

Technical Notes

dlpdftextfromutf32le (void *Text) Return Value: DLPDFTEXT*

Description Returns a DLPDFTEXT structure for the given UTF32 little-endian Unicode Text string.

Parameters void *Text: the text to be passed to the DLP- DFTEXT structure

Return Value DLPDFTEXT*

Exceptions

Header dli.h

Related Methods dlpdftext, dlpdftextfromutf16be, dlpdftextfromutf16he, dlpdftextfromutf16le, dlpdftextfromutf32be, dlpdftextfromutf32he, dlpdftextfromutf8

Availability All DLI-supported platforms.

Technical Notes

dlpdftextfromutf8 (void *Text) Return Value: DLPDFTEXT* Concepts and Facilities: Guide to the DL Pager Composition System

Description Returns a DLPDFTEXT structure for the given UTF8 Unicode Text string.

Parameters void *Text: the text to be passed to the DLP- DFTEXT structure

Return Value DLPDFTEXT*

Exceptions

Header dli.h

Related Methods dlpdftext, dlpdftextfromutf16be, dlpdftextfromutf16he, dlpdftextfromutf16le, dlpdftextfromutf32be, dlpdftextfromutf32he, dlpdftextfromutf32le

Availability All DLI-supported platforms.

Technical Notes

dlpdftextlength (DLPDFTEXT *Text) Return Value: ASUns32

Description 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.

Parameters DLPDFTEXT *Text: the text structure to be acted upon

Return Value ASUns32

Exceptions

Header dli.h

Related Methods dlpdftext, dlpdftextstring

Availability All DLI-supported platforms. A.178 DLI Reference Guide

dlpdftextshowencodingnames (char *FileName) Return Value:Concepts void and Facilities: Guide to the DL Pager Composition System

Description 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.

Parameters char *FileName: Name for the output file to be created

Return Value void

Exceptions

Header dli.h

Related Methods dlpdftext

Availability All DLI-supported platforms. DLI Reference Guide A.179

dlpdftextstring (DLPDFTEXT *Text) Return Value: char *

Description This method returns the byte buffer for the stored string.

Parameters DLPDFTEXT *Text: the text structure to be acted upon

Return Value char *

Exceptions

Header dli.h

Related Methods dlpdftext, dlpdftextlength

Availability All DLI-supported platforms. A.180 DLI Reference Guide

dlpdftexttocontent (DLPDFTEXT *Text, DLPDFCONTENT *Content, DLPDFFONT *Font, PDEGraphicStateConcepts and *GState, Facilities: GuidePDETextState to the DL Pager *TState, Composition System ASFixed PointSize, ASFixed SetWidth, ASFixed XPos, ASFixed YPos, dlpdftext_X XMeaning, ASFixed Angle) Return Value: void

Description This method pastes the DLPDFTEXT string into a DLPDFCONTENT area.

Parameters • DLPDFTEXT *Text: the text structure to be acted upon • DLPDFCONTENT *Content: the target structure in which the text will be pasted • DLPDFFONT *Font: The specified font • PDEGraphicState *GState: Contains definitions of colors to be applied, and line sizes and parameters to be used when drawing a path • PDETextState *TState: The current text state. This should not be NULL. A zero-filled PDETextState parameter is permitted. • 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 DLI Reference Guide A.181

Parameters (continued) • 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

Return Value void

Exceptions

Header dli.h

Related Methods

Availability All DLI-supported platforms. A.182 DLI Reference Guide

dlpdfttload (DLPDFINSTANCE *Instance, ASFile TTFont, ASAtom *Names, int NameLen) Return Value:Concepts int and Facilities: Guide to the DL Pager Composition System

Description 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.

Parameters • 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

Return Value int: Number of fonts loaded

Exceptions

Header dli.h

Related Methods

Availability All DLI-supported platforms. DLI Reference Guide A.183

Technical Notes

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. A.184 DLI Reference Guide

GetGraphicFromList (DLPDFDOC *Doc, char *Name) Return Value:Concepts DLPDFIMAGE* and Facilities: Guide to the DL Pager Composition System

Description Obtains a DLPDFIMAGE* by specifying the target document and the key for the graphic file.

Parameters • DLPDFINSTANCE *Instance: Represents the document structure and the current status of the document at all times. • char *Name: Name string

Return Value DLPDFIMAGE*: NULL is returned if the graphic is not found.

Exceptions

Header dli.h

Related Methods LoadGraphicList

Availability Available on OS/390 only DLI Reference Guide A.185

LoadGraphicList (char *ListFileName) Return Value: void

Description 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.

Parameters char *ListFileName: File name

Return Value void

Exceptions

Header dli.h

Related Methods GetGraphicFromList

Availability Available on OS/390 only A.186 DLI Reference Guide

Concepts and Facilities: Guide to the DL Pager Composition System Index I.i

Index

A Routines 2.5 Annotation Dictionary A key Modifying 13.9 Use in Links 13.9 Annotations AcroForm (Sample DLI Application) 17.18 action (parameter) 13.2 action (parameter) Border Specification 13.4 Use in Annotations and Links 13.2 Color Specification 13.4 Action Dictionary Components 13.2 Use in Links Content 13.4 Creating Replacement 13.9 hot spot (parameter) 13.2 Modifying 13.9 Introduction 13.1 Actions Link in Annotations and Links 13.3 Overview 13.2 Adobe Acrobat 1.8 Modifying for Other Actions 13.2 Adobe Acrobat Distiller 1.12, 2.6 Open/Close Flag 13.4 Adobe Distiller 17.7 Opening the Document with Adobe Normalizer 11.2, 17.7 Annotations Showing 14.6 Adobe Reader 1.7, 1.8, 1.12, 2.3, 2.6, Text 4.10, 13.4, 14.1, 17.9, A.114 Overview 13.2 Adobe Technical Notes Title 13.4 #5189 (Adobe PDF Library Overview) Annotations (Sample DLI Application) 17.15 1.10 Annotations and Links #5190 (Acrobat Core API Overview) Borders 1.10 Color 13.3 #5191 (Acrobat Core API Reference) Definition 13.3 1.10 Calls 13.4, 13.6, 13.7, 13.8 #5414 (PDF Library Supplement to the Colors Acrobat Core API) 1.11 Links 13.3 #5425 (AcroColor API Reference) 1.10 Text Annotations (when closed) 13.3 ADOBECMP ArcTo (PostScript operator) 8.8, A.4 OS/390 Location Search 4.15 ASBool AdobeFnt.lst 2.3 Use in Documents, Beginning and Efficient use of 2.3 Ending 3.2 Naming variations 2.3 ASCII Search path definition via PDFLDataRec Use in Displaying Images 11.12 2.3 ASCII85 Use in Default Search Path Suppression Use in Displaying Images 11.7 1.20, 1.21 ASFile 17.16 ADOBERES ASFileSys OS/390 Location Search 4.15 Specifying an Alternate File System via allocProc dlpdfinit 2.9 Use in Setting Memory Allocation Use in Image Search using Files in I.ii DLI Implementation and Reference Guide

Memory 1.20, 2.11 Bookmarks Use in Initializing and Terminating via Accessing DLPDFOUTLINE fields 14.5 DLI 2.9, 2.11 Building Multiple Trees 14.2 ConceptsUse in andSpecifying Facilities: an Alternate Guide File to the DL PagerCalls Composition 14.3, 14.4, 14.5 System System 2.10 DLPDFOUTLINE 14.2, 14.4 ASFixed DLPDFOUTLINE->Count 14.5 Use in Basic Color Spaces DLPDFOUTLINE->Obj 14.5 Device Gray 12.7 DLPDFOUTLINE->Open 14.5 Use in Color Channels Introduction 14.1 Definitions 12.6 Opening Document with Annotations Inversion Correction 12.6 Showing 14.6 Precision Correction 12.6 Outline Tree 14.2 Use in Color Description 12.2 Overview 14.2 ASFixedMatrix PageMode 14.6 Use in Line Drawing 10.15 PDViewDestNull 14.3 ASFixedRect Border Use in Displaying Images 11.10 Use in Annotations and Links 13.4 ASFixedRectangle Border (parameter) Use in Annotations and Links 13.4, Use in Annotation Dictionary 13.9 13.5 BoundingBox (PostScript statement) A.87 hot spot Definition 13.2 Browser ASGetErrorString Specifying via Acrobat 13.7 Use in Error Handling 16.3, 16.4, 16.5 ASGetExceptionErrorCode C Use in Error Handling 16.3 ASPathName CalGray Use in Writing PDF Output to Memory Use in Color Spaces 2.16 Basic 12.9 ASSize_t Calibrated Gray Scale 12.5 Use in Writing PDF Output to Memory calloc 2.16 Alternate Routines for 2.5 PDFInit.h Interface to 2.5 B CalRGB Use in Color Spaces Background patterns, creating 17.17 Basic 12.9 Backwards Compatibility, Ensuring 1.12, 2.7 Cautions BBox (parameter) Color Models must be Freed before Use in Content Interface Calls 8.19 Closing 12.3 Use in Displaying Images 11.10 Do not Exit from within Error Handler Use in Forms 9.3 16.2 Bezier Curve Initialize pre-v6.1 Library and DLI only Use in Line Drawing once 2.9 Basic points 10.12, A.132 Invalid Font Creation 4.9 Calls 10.12, 10.13 Scale Before Rotating Image 10.16 Parameters 10.12, A.132 Transformation, Undesirable Side- Bézier curve 8.15, 8.16, 8.17 Effects via dlpdfcontentrotate 7.3 Bitmaps CGM (Computer Graphics Metafile) Image Conversion from 11.2 Use in Graphical Language Forms 11.5 Use in Image Color Spaces 12.3 CIDToGID Conversion Map 4.3 blobs (Binary Large OBjects) 17.16 CIDType2 font Index I.iii

Terminology usage 4.4 Device Gray 12.7 Clipping Path A.7 Device RGB 12.8 Use in Line Drawing 8.6 ICC Based 12.10 CMYK Color Conversion of Values between Models Collapsing to Gray 12.16 CMYK To Gray 12.16 Converting to RGB 12.18 CMYK to RGB 12.18 Use in Color Description 12.2 Overview 12.16 Use in ICC Based Color Profile 12.10 RGB to CMYK 12.17 Color RGB to Gray 12.16 Color Description Components 12.2 Creating and Destroying 12.3 Converting Values to Binary 12.6 Patterned of Annotations and Links 13.3 Building 12.13 Use in Annotations and Links 13.4 Repeating References 12.14 Use in Images 12.3 ColorSpace Use with PDFGraphicState 12.2 Use in Displaying Images 11.12 Color (parameter) Comments Use in Annotation Dictionary 13.9 Use in Adding to Content Elements 8.22 Color Channels Compression Inversion Correction 12.6 Activating 3.3, A.41 Precision Correction 12.6 Calls 3.3 Value Conversion and Inversion 12.6 Flate Values for 12.6 Use in Displaying Images 11.7 Color Models Use in Documents, Beginning and /DeviceCMYK Ending 3.3, A.41 Order of Values Assumed 11.6 Containers within Pages 7.1 Use in Displaying Images 11.6 Inversion 7.4 /DeviceGray Overview 7.2 Use in Displaying Images 11.6 Scaling 7.3 /DeviceRGB Content Elements Order of Values Assumed 11.6 representation by DLPDFCONTENT 8.2 Use in Displaying Images 11.6 Content Interface Calls 8.3 /Indexed Adding Comments to Content Elements Use in Displaying Images 11.6 8.22 Order of Values 11.6 Calls 8.22 Color Profile Associating Content to Page 8.21 Use in Color Spaces Calls 8.21 Basic 12.10 Control Structures 8.2 Color Spaces Creation and Positioning 8.3 Advanced Calls 8.3, 8.4 DeviceN 12.11 Line Drawing 8.5 Indexed 12.12 Calls 8.6, 8.7, 8.8 Overview 12.11 Fill Color 8.6 Patterned 12.12 kPDEEoFill 8.6 Separation 12.11 kPDEFill 8.6 Basic kPDEStroke 8.6 Calibrated Gray 12.8 Paint Operator 8.5 Calibrated RGB 12.9 PDEGraphicState 8.5 CIE Calibrated Color 12.7 Overview 8.2 CIE Lab 12.9 Paths 8.9 Device CMYK 12.8 Appending Line Segments 8.10 I.iv DLI Implementation and Reference Guide

Calls 8.10, 8.11, 8.12, 8.13, Obtaining Name 13.8 8.14, 8.15, 8.16, Use in Links 13.7, 13.8 8.17, 8.18 Use of, vs. Name 13.6 ConceptsCalls and 8.9 Facilities:, 8.10 Guide to the DLDestination Pager Composition Dictionary System Patterns 8.18 Use in Bookmarks 14.4 Calls 8.19 DeviceCMYK Referencing Predefined Structures 8.20 Creating Color Space for 12.4 Calls 8.20, 8.21 Use in Color Spaces Text Placement 8.4 Advanced 12.12 Calls 8.4 Basic 12.8 Text Width Evaluation 8.4 DeviceGray Calls 8.5 Creating Color Space for 12.4 Conventions, Document 1.7 Use in Color Spaces CosDictRemove Advanced 12.12 Use in Links Basic 12.7 Replacing 13.9 DeviceN CosDoc Use in Color Spaces Use in Document Creation 3.2 Advanced 12.11, 12.12 cosImage DeviceRGB Use in Displaying Images 11.13 Creating Color Space for 12.4 CosNull Use in Color Spaces Use in Links 13.8 Advanced 12.12 CosObj Basic 12.8 Use in Annotations and Links 13.2, Digital Signatures 13.9 Appearance layers 15.3, 15.4 Use in Image Color Spaces 12.3 Calls CosStructure dlpdfdoccreatesignature 15.4 Use in Image Color Spaces 12.3 dlpdfdocsetsignatureappearance Cross-Reference File, OS/390 15.4 Use in Displaying Images 11.11 dlpdfpageplacesignature 15.6 CTM Matrix dlpdfsignaturesetdatacallback 15.6 Use in Line Drawing 10.7 dlpdfsignaturesetpkcs7cert 15.5 Current Point dlpdfsignaturesetx509cert 15.5 Use in Line Drawing 10.7 Components of 15.3 imageBBox (signature bounding box) D 15.6 Introduction 15.1 dash Overview 15.2 Use in Line Drawing 10.18 Public and Private Keys 15.2 Dashed and Dotted Lines 10.18 sigType (plug-in compatibility) 15.4 Data Structure, Library 2.2 dirList DDName Use in Setting Resource Directories 2.3 Use in Displaying Images 11.12 DLExceptionCode Dest (parameter) Use in Error Handling 16.4, 16.5 Use in Annotation Dictionary 13.9 DLExceptionFlag Use in Bookmarks 14.5 Use in Error Handling 16.4, 16.5 Use in Links DLExceptionMessage Replacing 13.9 Use in Error Handling 16.5 Destination DLI Adding to Name Tree 13.8 DLI-selected PDF Level Declarations 2.7 Index I.v

How to Create a PDF Document 1.2 Use in Line Drawing 10.5 Initialization in DLI v3.0 1.14 dlpdfcontentpieslicen A.19 Introduction 1.2 Use in Content Interface Calls 8.8 Overriding DLI-selected PDF Level Use in Line Drawing 10.5 Declarations 2.7 dlpdfcontentrect A.21 Required Initialization 1.3 Use in Content Interface Calls 8.7 DLPDFCONTENT 8.2 Use in Line Drawing 10.4 Use by dlpdftexttocontent 1.17 dlpdfcontentreferenceform A.23 Use in Displaying Images 11.13 Use in Content Interface Calls 8.20 Use in Line Drawing 10.14 Use in Forms 9.3 Use in Patterned Colors 12.2 dlpdfcontentreferenceimage A.24 Use with CIDType2 fonts 4.4 Usage example 8.21 dlpdfcontent objects 1.2 Use in Content Interface Calls 8.20 dlpdfcontentarc A.2 Use in Displaying Images 11.2 Use in Content Interface Calls 8.7 dlpdfcontentrotate A.26 Use in Line Drawing 10.4 Use in Content Interface Calls 8.3 dlpdfcontentarcn A.3 dlpdfcontentscale A.27 Use in Content Interface Calls 8.8 Use in Content Interface Calls 8.3 Use in Line Drawing 10.4 dlpdfcontenttext A.28, A.35 dlpdfcontentarcto A.4 Use in Content Interface Calls 8.4 Use in Content Interface Calls 8.8 dlpdfcontenttextwidth A.30, A.38 Use in Line Drawing 10.5 Use in Content Interface Calls 8.5 dlpdfcontentcircle A.6 dlpdfcontenttopage A.31 Use in Content Interface Calls 8.8 Use in Content Interface Calls 8.21 Use in Line Drawing 10.6 dlpdfcontenttranslate A.32 dlpdfcontentclip A.7 Use in Content Interface Calls 8.4 Use in Content Interface Calls 8.6 dlpdfcontentusefillpattern A.33, A.34, dlpdfcontentclipend A.8, A.9 A.155 Use in Content Interface Calls 8.6, 8.7 Use in Color Spaces Use in Line Drawing 8.6 Advanced 12.12 dlpdfcontentcomment A.10 Patterned 12.13 Use in Content Interface Calls 8.22 Use in Content Interface Calls 8.19 dlpdfcontentcreate A.11 dlpdfcontentusestrokepattern A.34, A.155 Use in Content Interface Calls 8.3 Use in Color Spaces dlpdfcontentdrawpath Advanced 12.12 Use in Line Drawing 10.7, 10.14 Use in Content Interface Calls 8.19 dlpdfcontentellipse A.12 dlpdfcontentwidetext A.35 Use in Content Interface Calls 8.8 Updates in DLI v3.0 1.17 Use in Line Drawing 10.6 Use in Content Interface Calls 8.4 dlpdfcontentfontskew A.13 dlpdfcontentwidetextwidth A.38 dlpdfcontentgstate A.14 Use in Content Interface Calls 8.5 Use in Displaying Images 11.13 DLPDFDOC 2.7, A.46 dlpdfcontentline A.15 EmbedFonts Use in Content Interface Calls 8.7 Use in Documents, Beginning and Use in Line Drawing 10.4 Ending 3.3 dlpdfcontentpath A.16 Use in Creation Calls in DLI Use in Content Interface Calls 8.6, 8.7 Font Searching Sequence 4.7 Use in Line Drawing 8.6, 10.2, 10.6 Repetitive Calling 4.6 dlpdfcontentpieslice A.12, A.18 Use in Displaying Images 11.12 Use in Content Interface Calls 8.8 Use in Document Status 3.2 I.vi DLI Implementation and Reference Guide

Use in Documents, Beginning and Use in Bookmarks 14.4 Ending 3.2 dlpdfdocoutlinecosobj A.57 Encryption 3.4, 3.5 dlpdfdocoutlinefirst A.58 ConceptsUse in andInitializing Facilities: and Terminating Guide tovia the DL PagerUse inComposition Bookmarks 14.5 System DLI 2.9, 2.12 dlpdfdocoutlinelast A.59 Use in Multiple Document Creation 3.2 Use in Bookmarks 14.5 dlpdfdocasciips A.39 dlpdfdocoutlinenext A.60 What’s New in DLI v3.0 1.16 Use in Bookmarks 14.5 dlpdfdoccomplete A.40 dlpdfdocoutlineparent A.61 dlpdfdoccompress A.41 Use in Bookmarks 14.5 Use in Documents, Beginning and dlpdfdocoutlineprev A.62 Ending 3.3 Use in Bookmarks 14.5 dlpdfdoccosdoc A.42 dlpdfdocpddoc A.63, A.118 dlpdfdoccreate A.43 Use in Page Interface 6.3 Modifications in DLI v3.0 1.19 dlpdfdocsetdocinfo A.64 Updates in DLI v3.0 1.14, 1.18 Use in Documents, Beginning and Use in Documents, Beginning and Ending 3.4 Ending 3.2 dlpdfdocsetencoding A.65 dlpdfdoccreatesignature A.44 Use in Documents, Beginning and Use in digital signatures 15.4 Ending 3.3 What’s New in DLI v3.0 1.15 dlpdfdocsetencryptkeylen A.66 dlpdfdoccreatewithinstance Use in Documents, Beginning and Removal from DLI v3.0 1.14, 1.19 Ending 3.5 dlpdfdocdestroy A.46 dlpdfdocseterrorfile dlpdfdocembedfonts A.47, A.73, A.75, Removal from DLI v3.0 1.19 A.77, A.79 dlpdfdocsetformsascontent Use in Documents, Beginning and Removal from DLI v3.0 1.19 Ending 3.3 dlpdfdocsetpdfname A.68 Use of Document EmbedFonts Flag 4.5 Use in Documents, Beginning and dlpdfdocencrypt A.48 Ending 3.3 Use in Documents, Beginning and Use in Writing PDF Output to Memory Ending 3.4, 3.5 2.15 dlpdfdocHexGraphics A.50 dlpdfdocsetpsname A.69 Removal from DLI v3.0 1.19 Use required for dlpdfdoccreate 1.18, dlpdfdoclinearize A.49 A.43 Use in Documents, Beginning and dlpdfdocsetsignatureappearance A.70 Ending 3.4 Use in digital signatures 15.4 dlpdfdocmakethumbnails A.50 What’s New in DLI v3.0 1.15 Use in Documents, Beginning and dlpdfdocsetwarningfile Ending 3.4 Removal from DLI v3.0 1.19 dlpdfdocnameadd A.51 dlpdfdocsevenbitsafe Use in Annotations and Links 13.6 Removal from DLI v3.0 1.18 Use in Links 13.8 dlpdfdocwritepdf A.68, A.71 dlpdfdocnamefind A.52 Use in digital signatures 15.5, 15.6 Use in Links 13.8 Use in Documents, Beginning and dlpdfdocoutline A.53 Ending 3.4 Use in Bookmarks 14.4 with dlpdfdocencrypt 3.5 dlpdfdocoutlineadd A.54 Use in Writing PDF Output to Memory Use in Bookmarks 14.3 2.15, 2.16 dlpdfdocoutlineaddfromname A.56 dlpdfdocwritePS A.69, A.72 Index I.vii

Use in Documents, Beginning and dlpdfimagegetsize A.88 Ending 3.3 Use in Content Interface Calls 8.21 Use required for dlpdfdoccreate 1.18, dlpdfimageplaceascontent A.43 Removal from DLI v3.0 1.19 DLPDFFONT 3.3, 4.4, 4.5, A.47 dlpdfinit A.90 Font Attributes 4.5 Font Embedding Status 4.4 Use in Multi-Thread Initializations Font Subsetting Status 4.4 2.13 Use in Creation Calls in DLI 4.6 Caution on Multiple Initializations of Repetitive Calling 4.6 Library 2.9 WidthTable 4.7 Error Handler not required 3.2, A.91, dlpdffontcreate A.73, A.75, A.77, A.79 A.165 Use in Font Creation 4.6, 4.7 Invoking Files in Memory 17.2 Use in Font Searching Sequence 4.7 Note on Writing PDF Output to Memory Use in Loading and Creating Fonts 5.3, 2.10 5.4 Specifying an Alternate File System 2.10 Use in Multibyte Text Work 5.3 Updates in DLI v3.0 1.14, 1.18 dlpdffontcreateembedded 4.6, A.73, A.75, Use in Default Search Path Suppression A.77, A.79 1.21 Use in Font Creation 4.6, 4.8 Use in Files in Memory 2.8 Use in Loading and Creating Fonts 5.4 Use in Initializing and Terminating the dlpdffontcreatewithmetrics A.73, A.75, Library 2.12 A.76, A.79 Failure to Initialize 2.9 Use in Font Creation 4.6, 4.8 Use in Initializing and Terminating via Use in Loading and Creating Fonts 5.4 DLI 2.9, 2.11, 2.12 Use in Matching System Fonts 4.9 Use in Specifying an Alternate File dlpdffontcreatewithmetricsembedded A.73, System 2.10 A.75, A.77, A.78 Use in Terminating Library 2.11 Use in Font Creation 4.6, 4.11 Using a Graphics Cache 2.10 dlpdffontverifytext DLPDFINSTANCE Removal from DLI v3.0 1.20 Addition in DLI v3.0 1.13 DLPDFFORM 9.2 Unicode font translation via ICU 4.3 Use in Digital Signatures 15.3, 15.4 Use by dlpdfttload 1.17 dlpdfformcreate A.80 Use in Creation Calls in DLI Use in Forms 9.3 Font Searching Sequence 4.7 dlpdfformdestroy A.81 Use in dlpdfdoccreate 1.18, 1.19 Use in Forms 9.3 Use in Initializing and Terminating the DLPDFIMAGE Library 2.12 Use in Displaying Images 11.2, 11.6, Use in Initializing and Terminating via 11.10, 11.12, 11.13 DLI 2.9, 2.12 dlpdfimagecreatefrombmp A.82 Use in Terminating Library 2.11, 2.12 Use in Displaying Images 11.12 dlpdfinstancesetcancelproc A.92 Use in Image Color Spaces 12.3 dlpdfinstancesetgrcachelimits A.93 dlpdfimagecreatefromfile A.84 What’s New in DLI v3.0 1.16 Use in Displaying Images 11.10 dlpdfinstancesetprogressmonitor A.95 Use in Image Search using Files in dlpdfmatrixrotate A.96 Memory 1.21, 2.11 Use in Line Drawing 10.16 dlpdfimagecreatefrompdf A.85 dlpdfmemfileacquire A.96, A.97 What’s New in DLI v3.0 1.14 Use in Writing PDF Output to Memory dlpdfimagecreatefromps A.87 2.16 I.viii DLI Implementation and Reference Guide

dlpdfmemfiledata A.98, A.99 Use in Links 13.7 Use in Writing PDF Output to Memory dlpdfpagecosobj A.115 2.16 Use in Page Interface 6.3 Conceptsdlpdfmemfiledeleteonclose and Facilities: A.99 Guide to the DLdlpdfpagecreate Pager Composition A.116 System Note on usage for file deletion 1.15 Use in Page Interface 6.2 What’s New in DLI v3.0 1.15 dlpdfpagefindfromnumber A.117 dlpdfmemfilerelease A.100 Use in Page Interface 6.2 Use in Writing PDF Output to Memory dlpdfpagenumber A.118 2.16, 2.17 Use in Page Interface 6.3 dlpdfmemfilesetbuffer A.101 dlpdfpageplacesignature A.157 What’s New in DLI v3.0 1.15 Use in digital signatures 15.6 dlpdfmemfilesetdata A.102 What’s New in DLI v3.0 1.15 Differences from dlpdfmemfilesetbuffer dlpdfpagerotate A.119 A.101 Use in Page Interface 6.3 Use in Image Search using Files in dlpdfpagesetart A.120 Memory 1.20, 2.11 dlpdfpagesetbleed A.121 Use in Writing PDF Output to Memory dlpdfpagesetcrop A.122 2.17 dlpdfpagesetid A.123 dlpdfmemfilesize 2.16, A.103 Use in Page Interface 6.3 Use in Writing PDF Output to Memory dlpdfpagesetmediabox A.124 2.16 dlpdfpagesettrim A.125 dlpdfmemfilesys A.104 DLPDFPATH Use in Files in Memory 2.8 Effect of DLPDFPath.scaling on Use in Image Search using Files in PDEGraphicState.lineWidth 10.17 Memory 1.20, 2.11 Use in Line Drawing 10.7, 10.8, 10.14, Use in Initializing and Terminating the 10.17 Library 2.9 Use in Paths 8.9 Use in Initializing and Terminating via dlpdfpathaddarc A.126 DLI 2.11 Use in Content Interface Calls 8.12 Use in Specifying an Alternate File Use in Line Drawing 10.9 System 2.10 dlpdfpathaddarcn A.127 dlpdfmemfilesysgetmemusage A.105 Use in Content Interface Calls 8.12 What’s New in DLI v3.0 1.15 Use in Line Drawing 10.9 dlpdfmemfilesyssetmemlimit A.106 dlpdfpathaddarcto A.128 What’s New in DLI v3.0 1.15 Use in Content Interface Calls 8.13 dlpdfmemfiletransientprefix A.107 dlpdfpathaddclose Use in Writing PDF Output to Memory Use in Content Interface Calls 8.18 2.16, 2.17 Use in Line Drawing 10.7, 10.14 DLPDFOUTLINE dlpdfpathaddcurve A.131 Use in Bookmarks 14.2, 14.4, 14.5 Use in Content Interface Calls 8.15 DLPDFPAGE 6.2 Use in Line Drawing 10.12 dlpdfpage objects 1.2 dlpdfpathaddcurver A.133 dlpdfpageaddlinkannotation A.108 Use in Content Interface Calls 8.16 Use in Annotations and Links 13.4 Use in Line Drawing 10.12 dlpdfpageaddlinkannotationfromname dlpdfpathaddcurvev A.134 A.111 Use in Content Interface Calls 8.16 Use in Annotations and Links 13.6 Use in Line Drawing 10.13 dlpdfpageaddtextannotation A.112 dlpdfpathaddcurvey A.136 Use in Annotations and Links 13.4 Use in Content Interface Calls 8.17 dlpdfpageaddwebannotation A.114 Use in Line Drawing 10.13 Index I.ix

dlpdfpathaddelliparc dlpdfpatterncreate A.33, A.155 Use in Content Interface Calls 8.13 Use in Color Spaces dlpdfpathaddelliparcn A.140 Advanced 12.12 Use in Content Interface Calls 8.14 Patterned 12.13 dlpdfpathaddelliparcto A.141 Use in Content Interface Calls 8.19 Use in Content Interface Calls 8.15 dlpdfpatternrotate A.156 dlpdfpathaddline A.142 dlpdfseterrorfile A.158 Use in Content Interface Calls 8.10 dlpdfsetlevel Use in Line Drawing 10.8 Removal from DLI v3.0 1.20 dlpdfpathaddliner A.143 dlpdfsetwarningfile A.159 Use in Content Interface Calls 8.10 DLPDFSIGNATURE Use in Line Drawing 10.9 Use in Digital Signatures 15.5 dlpdfpathaddmove A.144 dlpdfsignaturesetdatacallback A.160 Use in Content Interface Calls 8.11 Use in digital signatures 15.6 Use in Line Drawing 10.8 What’s New in DLI v3.0 1.15 dlpdfpathaddmover A.145 dlpdfsignaturesetpkcs7cert A.161 Use in Content Interface Calls 8.11 Use in digital signatures 15.5 Use in Line Drawing 10.8 What’s New in DLI v3.0 1.15 dlpdfpathaddrect A.146 dlpdfsignaturesetx509cert A.163 Use in Content Interface Calls 8.17 Use in digital signatures 15.5 Use in Line Drawing 10.14 What’s New in DLI v3.0 1.15 dlpdfpathadelliparc A.138 dlpdfterm A.165 dlpdfpatharray A.147 Use in Content Interface Calls 8.10 Use in Multi-Thread Initializations dlpdfpathclear A.148 2.13 Use in Content Interface Calls 8.9 Error Handler not required 3.2, A.91, Use in Line Drawing 10.8 A.165 dlpdfpathclosepath A.130 Updates in DLI v3.0 1.18 dlpdfpathcreate A.149 Use in Initializing and Terminating the Use in Content Interface Calls 8.9 Library 2.12 Use in Line Drawing 10.7 Use in Initializing and Terminating via dlpdfpathcurrentx A.150 DLI 2.12 Use in Content Interface Calls 8.9 Use in Terminating Library 2.11, 2.12 dlpdfpathcurrenty A.151 DLPDFTEXT 17.21 Use in Content Interface Calls 8.9 Use in Multibyte Text Work 5.7 dlpdfpathdestroy A.152 dlpdftext A.166 Use in Content Interface Calls 8.9 Obtaining Encoding names via Use in Line Drawing 10.7, 10.8 dlpdftextshowencodingnames dlpdfpathsetmatrix A.153 1.16, A.178 Use in Content Interface Calls 8.18 Use in Multibyte Text Work 5.5 Use in Line Drawing 10.15 Associated shortcut functions 5.6 dlpdfpathsize A.154 What’s New in DLI v3.0 1.16 Use in Content Interface Calls 8.9 DLPDFTEXT (structure) 1.20, 5.2 DLPDFPATTERN 8.18 Addition in DLI v3.0 1.13 Parameters Creating 5.5 BBox 8.19 Performance Considerations 5.10 Colored 8.19 Shortcut Functions 5.6 TileType 8.19 Unicode font translation via ICU 4.3 Xstep 8.19 Use by dlpdftextdestroy 1.17 Ystep 8.19 Use by dlpdftexttocontent 1.17 I.x DLI Implementation and Reference Guide

Use in dlpdftext (method) A.166 Note on no default font searching 2.3 Use in dlpdftextadvance A.167 Use in Font Searching Sequence 4.7 Use in dlpdftextdestroy A.169 Use in Multibyte Text Work 5.3 ConceptsUse in anddlpdftextlength Facilities: A.177 Guide to the DL PagerWhat’s Composition New in DLI v3.0 System 1.17 Use in dlpdftextstring A.179 Document Conventions 1.7 Use in dlpdftexttocontent A.180 Document Handle What’s New in DLI v3.0 1.16, 1.17 Use in Links 13.8 Working with 5.7, 5.8, 5.9, 5.10 Document Information dlpdftextadvance A.167 Calls 3.4 Use in Multibyte Text Work 5.8 Document Interface What’s New in DLI v3.0 1.17 Use with Error Handler 3.2 dlpdftextdestroy A.169 Document Opening Use in Multibyte Text Work 5.10 with Annotations Showing 14.6 What’s New in DLI v3.0 1.17 Documents, Beginning and Ending dlpdftextfromutf16be A.170 Calls 3.2, 3.3, 3.4, 3.5 Use in Multibyte Text Work 5.6 Overview 3.2 What’s New in DLI v3.0 1.16 dlpdftextfromutf16he A.171 E Use in Multibyte Text Work 5.6 What’s New in DLI v3.0 1.16 E_RETURN(X) dlpdftextfromutf16le A.172 Use in Error Handling 16.3 Use in Multibyte Text Work 5.6 E_RTRN_VOID What’s New in DLI v3.0 1.16 Use in Error Handling 16.4 dlpdftextfromutf32be A.173 eMemFileSys Use in Multibyte Text Work 5.6 Use in Files in Memory in DLI Samples What’s New in DLI v3.0 1.16 17.3 dlpdftextfromutf32he A.174 Encoding Use in Multibyte Text Work 5.6 Generation of Grid via FontVerification What’s New in DLI v3.0 1.16 (Sample DLI Application) 17.13 dlpdftextfromutf32le A.175 Encoding Vector 4.10 Use in Multibyte Text Work 5.6 Encrypt (Sample DLI Application) 17.9 What’s New in DLI v3.0 1.16 Changing Security Settings 17.10 dlpdftextfromutf8 A.176 DocOwner Password 17.10 Use in Multibyte Text Work 5.6 ValidUser Password 17.9 What’s New in DLI v3.0 1.16 Encryption dlpdftextlength A.177 Calls 3.5 Use in Multibyte Text Work 5.7 Setting Encryption Key Length 3.5 What’s New in DLI v3.0 1.17 Use in Documents, Beginning and dlpdftextshowencodingnames A.178 Ending 3.4 Use in Multibyte Text Work 5.5 EPS What’s New in DLI v3.0 1.16 Image Conversion from 11.2 dlpdftextstring A.179 EPS (Encapsulated PostScript) Use in Multibyte Text Work 5.7 Image Conversion from 11.2 What’s New in DLI v3.0 1.17 Use in Graphics (Sample DLI Application) dlpdftexttocontent A.180 17.6 Use in Multibyte Text Work 5.9 Error Handling What’s New in DLI v3.0 1.17 ASGetErrorString 16.3 dlpdfttload A.182 ASGetExceptionErrorCode 16.3 Clearance of memory files by dlpdfterm DURING 16.2, 16.3 1.18 E_RETURN(X) 16.3 Index I.xi

E_RTRN_VOID 16.4 11.8 END_HANDLER 16.2, 16.3 PDF Image Exception Codes from Methods 16.3 via dlpdfimagecreatefromfile Exception Names 16.3 11.10 HANDLER 16.2, 16.3 via dlpdfimagecreatefrompdf Handler Constructs 11.9 Multiple 16.3 Line Drawing Using Fixed Structure 10.6 Risks of Returning from within 16.3 Modifying a Goto Link into a GotoR Link Handler Mechanism 16.2 13.10 OS/390 Platform Concerns 16.4 Multiple Containers per Page with Overview 16.2 Rotation 7.6 Errors Setting the Page Mode to Display Communication back to Application Navigation Pane 14.6 16.2 Transparent Graphics via Imagemasks Link 11.13 "Browser is Busy" 13.7 Exception Handlers, Required Use 3.2 OS/390 Exceptions Not Using SAS/C Use in Error Handling 16.2 ASGetErrorString 16.4, 16.5 DLExceptionCode 16.4, 16.5 F DLExceptionFlag 16.4, 16.5 DLExceptionMessage 16.5 Filename, Setting Output PDF Using SAS/C 16.4 Calls 3.3 Outer Error Catcher 16.2 Files in Memory Examples Activating within DLI Samples 17.2 Adding Outline Entries 14.4 Activation 2.8 with a Named Destination 14.4 MEMORY Command Line Argument, Bitmapped Graphic via Use of 17.2, 17.3 dlpdfimagecreatefrombmp 11.4 Use of dlpdfinit 17.2 Collapsing Use of eMemFileSys in DLI Samples 17.3 CMYK to Gray 12.17 Use of FileSystemType in DLI Samples RGB to Gray 12.16 17.3 Converting Files, Transient 2.15 CMYK to RGB 12.18 FileSystemType RGB to CMYK 12.18 Use in Files in Memory in DLI Samples Creating 17.3 Calgray Color Space 12.5 fill (parameter) Gray Color Space Use in Displaying Images 11.5 Assembler 12.4 Fill Color C coding 12.4 Use in PDEGraphicState 10.2 Link Annotation 13.6 fillColorSpec Link To A Named Destination 13.7 Use in Color Description 12.2 Named Destination 13.8 Use in Line Drawing 10.17 Text Annotations 13.4 Fit Type Drawing a Rectangle and Ellipse in Path Use in Bookmarks 14.3 Operators 10.15 FitDescription Filling an Area with a Pattern 12.14 Use in Annotations and Links 13.5 Inserting FitType EPSF Image with Use in Annotations and Links 13.5 dlpdfimagecreatefromps Use in Links 13.5 I.xii DLI Implementation and Reference Guide

Values Use in Setting Resource Directories Fit 13.5 2.3 FitB 13.5 Predefined Font Encodings 4.11 ConceptsFitBH and 13.5 Facilities: Guide to the DL PagerEncoding Composition Font Types System Table 4.12 FitBV 13.5 Resources, Identifying Non-Standard FitH 13.5 Locations of 2.3 FitR 13.5 Search Paths 2.3 FitV 13.5 Simple Fonts 4.2 XYZ 13.5 Standard Encoding Fixed Rectangle Default Setting 3.3 Use in Bookmarks 14.3 Structure of a DLI Font 4.4 Flate Compression Terminology usage Use in Displaying Images 11.7 CIDType2 font 4.4 flatness TrueType font 4.4 Use in Line Drawing 10.18 Unicode 4.13 FOLIO 6.3, A.123 Use in Multibyte Text Work 5.3 Font Dump WinAnsiEncoding Via FontVerification (Sample DLI Default Setting 3.3 Application) 17.13 FontVerification (Sample DLI Application) Font Searching Sequence 4.7 17.13 FontFaux (Sample DLI Application) 17.11 Encoding Grid 17.13 Fonts Slow Feedback from 17.14 Accessing 4.15 Table of Contents 17.13 OS/390-specific 4.15 Form XObjects Calls 3.3 Use in Displaying Images 11.11 Code Page Support 4.13 Forms 9.2 Composite Fonts Calls 9.3 CIDType0 4.3 dlpdfformcreate CIDType2 4.3 Use of Bounding Box 9.3 Overview 4.3 Content Complexity 9.2 Creation Calls in DLI Destruction 9.2 Calls 4.7, 4.8, 4.11 Overview 9.2 dlpdffontcreatewithmetrics Structure 9.2 Width Table 4.10 Use in Referencing Predefined Font Searching Sequence 4.7 Structures 8.20 Matching Calls to System Fonts 4.9 Forms XObjects Overview 4.6 Association with Content Structures 8.2 Performance Considerations 4.13 Use in Content Interface 8.2 Repetitive Calling 4.6 free Default Encoding Selection 3.3 Alternate Routines for 2.5 differences between characters and PDFInit.h Interface to 2.5 glyphs 4.2 Free Software Foundation 1.4 Embedding freeProc Document EmbedFonts flag 4.5 Use in Setting Memory Allocation Subsetting Limitations 4.5 Routines 2.5 Font Dump via FontVerification (Sample Functions added in DLI v3.0 1.15 DLI Application) 17.13 Functions removed from DLI v3.0 1.18 Font Searching Sequence 4.7 Functions updated in DLI v3.0 1.18 Overview 4.2 PDFLDataRec Index I.xiii

G Obtaining Encoding names via dlpdftextshowencodingnames gcc Compilation Version 1.4 1.16, A.178 genErrBadParm 4.8, 6.3 Unicode font translation via ICU 4.3 Use in Annotations and Links 13.4 Use in Multibyte Text Work 5.2 GetGraphicFromList A.184 What’s New 1.13 Use in Displaying Images 11.11 Image Import Improvents in DLI v3.0 1.14 GetGraphicFromList, OS/390 Imagemask Use in Displaying Images 11.12 ImageMask key 11.12 GIF (Graphics Interchange Format) Note on Use of Bitmaps 11.6 Encoding and Compression References Use in Displaying Images 11.12 11.4 ImageName Image Conversion from 11.2 Use in Displaying Images 11.3 Use in Displaying Images 11.10 Images, Displaying Use in Graphics (Sample DLI Application) EPS Pass-Through Objects 11.7 17.6 Example 11.8 Glyph IDs 4.3 Graphic Image Forms GoTo Bitmaps 11.3 Use in Annotation Dictionary 13.9 Example 11.4 Graphics (Sample DLI Application) 17.6 Graphical Language 11.5 Graphics cache Graphic Image Structures What’s New in DLI v3.0 1.16 Destroying 11.3 Graphics, One-Bit Formats Supported 11.2 Use in Displaying Images 11.12 ImageName Use 11.3 grayScale Multiple Document Use 11.2 Use in Color Description 12.2 Image Creation Methods Use in ICC Based Color Profile 12.10 Assorted Formats dlpdfimagecreatefromfile H 11.10 Example 11.10 HelloDLI (Sample DLI Application) 17.4 Supported Formats 11.10 Comparison with helowrld.c 2.17 Bitmaps HeloWrld (Sample Adobe PDF Library Compression and Filtering 11.7 Application) 17.4 dlpdfimagecreatefrombmp Comparison with hellodli.c 2.17 11.6 hot spot (parameter) Values within Color Models Definition of 13.2 11.6 Use in Annotations and Links 13.2, EPS 13.5 dlpdfimagecreatefromps 11.7 Hyperlinks Example 11.8 Use in Links 13.7 Form XObject dlpdfimageplaceascontent I 11.11 GetGraphicFromList 11.12 ICC (International Color Consortium) 12.10 LoadGraphicList 11.11 ICCBased PDF Use in Color Spaces dlpdfimagecreatefrompdf 11.8 Advanced 12.12 Example 11.9 Use in ICC Based Color Profile 12.10 Transparent Graphics ICU (International Components for Unicode) dlpdfcontentgstate 11.13 I.xiv DLI Implementation and Reference Guide

Imagemasks 11.12 K Sample 11.13 Included EPS Images Not Appearing in Keys, Public and Private 15.2 kPDEEoFill ConceptsPDF and Pages Facilities: 11.2, 11.7 Guide to the DL Pager Composition System Overview 11.2 Use in Content Interface Calls 8.6 Indexed (atom) Use in Line Drawing 10.2, 10.3, 10.15, Use in Color Spaces 10.17 Advanced 12.12 Use in PDEGraphicState 10.2 Initializing and Terminating the Library kPDEFill Comparison of Applications with and Use in Content Interface Calls 8.6 without DLI 2.17 Use in Line Drawing 10.2, 10.3, 10.15, Files In Memory 10.17 Activation 2.8 Use in PDEGraphicState 10.2 Image Search using Files in Memory kPDEStroke 2.11 Use in Content Interface Calls 8.6 Output to Memory, Writing PDF 2.15 Use in Line Drawing 10.2, 10.3, 10.15, Calls 2.16, 2.17 10.17 Transient Files 2.15 Use in PDEGraphicState 10.2 Overview 2.2 kPDEStroke | kPDEEoFill PDFLDataRec Initialization 2.2 Use in Line Drawing 10.15 Memory Allocation Routines, Setting kPDEStroke | kPDEFill 2.5 Use in Line Drawing 10.15 Resource Allocation Routines, kPDFLInitIgnoreDefaultDirectories Setting 2.5 Use in Default Search Path Suppression Resource Directories, Setting 2.3 1.21, 2.3 Terminating 2.11 kPDFLVersion Thread-Safe Issues Use in Obtaining Version Number 2.6 Initialization of non-thread-safe Library releases 2.14 L Multi-Thread Initializations 2.13 mutex (Mutual Exclusion algorithm) Lab 2.14 Use in Color Spaces Version Number, Obtaining 2.6 Basic 12.9 With DLI Use in ICC Based Color Profile 12.10 Calls 2.9, 2.11, 2.12 Library Data Structure 2.2 Overview 2.8 Line Drawing 10.1 Specifying an Alternate File System Directly-Drawn Methods 10.3 2.10 Calls 10.4, 10.5, 10.6 Typical Order of Calls 2.13 Common Parameters 10.3 Using a Graphics Cache 2.10 dlpdfcontentpath Intended Audience 1.3 Example 10.6 Graphic State 10.17 Overview 10.2 J Path Drawing Methods 10.7 JPEG/JPG (Joint Photographic Experts Group) Calls 10.7, 10.8, 10.9, 10.10, Encoding and Compression References 10.11, 10.12, 10.13, 11.4 10.14, 10.15 Use in Displaying Images 11.10 Common Parameters 10.7 Use in Graphics (Sample DLI Application) Example 10.15 17.6 Transformation Matrix 10.15 Index I.xv

Arguments 10.15 Matrix operations dlpdfmatrixrotate 10.16 Rotations 17.5 Inversion Matrix 10.16 Translation of Paths 17.5 Mirror-image matrix 10.16 MDFile Rotation Matrix 10.16 Use in Writing PDF Output to Memory Scale/Rotation Caution 10.16 2.16 Scaling 10.16 memAvailProc Shearing 10.16 Use in Setting Memory Allocation Translations 10.16 Routines 2.5 Unity Matrix 10.16 memFiles (Sample DLI Application) 17.16 Linearization MEMORY Calls 3.4 Use in Files in Memory Activation 17.2, Use in Documents, Beginning and 17.3 Ending 3.4 Memory Allocation Routines, Setting 2.5 lineCap allocProc 2.5 Use in Line Drawing 10.18 freeProc 2.5 lineJoin memAvailProc 2.5 Use in Line Drawing 10.18 reallocProc 2.5 lineWidth Minor Version Number 2.6 Use in Line Drawing 10.17 Miter Link Annotation Use in Line Drawing 10.18 Modifying 13.9 miterLimit Link Cos Object Use in Line Drawing 10.18 Modifying 13.9 Multibyte Text Links Commands 5.3, 5.5, 5.6, 5.7, 5.8, action (parameter) 13.2 5.9, 5.10 Calls 13.4, 13.6, 13.7, 13.8 Creating DLPDFTEXT Areas 5.5 Components 13.2 Introduction 5.2 Cross-document 13.6 Loading and Creating Fonts 5.3 Destination Page Number 13.5 Performance Considerations 5.10 FitType 13.5 Working With DLPDFTEXT Areas 5.7 hot spot (parameter) MultiDoc (Sample DLI Application) 17.16 Definition of 13.2, 13.5 Required Arguments 17.16 Introduction 13.1 mutex (Mutual Exclusion algorithm) 2.14 List of Possible Actions 13.9 Modifying 13.9 N Overview 13.2 URI 13.7 name URL 13.7 Use in Links Zoom 13.5 instead of Destination 13.6 listLen name (parameter) Use in Setting Resource Directories 2.3 Use in Links 13.8 LoadGraphicList A.185 Name Tree A.51 Adding Destination 13.8 M Use in Annotations and Links 13.6 hot spot Definition 13.2 Major Version Number 2.6 Use in Links 13.6 malloc Named Destination Alternate Routines for 2.5 Use in Annotations and Links 13.6 PDFInit.h Interface to 2.5 Names I.xvi DLI Implementation and Reference Guide

Use in Annotations and Links 13.6 File Sizes, Effect on, by vs. Destinations 13.6 Repeated Graphical Object NestedPDF (Sample DLI Application) 17.17 References 11.11 ConceptsNotEmbedded and (flag) Facilities: 3.3, 4.5, GuideA.47 to the DL PagerFiles Compositionin /Codesamples folderSystem not Notes buildable source as-is 1.5, 11.13 "Browser is Busy" Error during Link 13.7 Fill Operator Not Valid via Adobe CFF OpenType font files not dlpdfcontentline 10.4 properly subset 5.3 Fill Patterns are Never Destroyed 12.14 ASN membership may be required for Font Encoding, Limitations on Adobe website access 1.10 Predefined 4.9 Base 14 Fonts Font not licensed for embedding will be Creation Allowed by dlpdffontcreate created as Referenced instead 3.3, 4.6 4.5 Bitmapped Images under 500 Bytes Function Return Value is Undefined if Always Merged Inline 11.6 Error Occurs 16.4 BMP images with LZW skip markers may Graphic Conversions,Some Unavailable not embed properly 17.8 on OS/390 and OS/400 11.3, Cache size limit is checked every time a 11.10 document is destroyed 2.10, Graphic Key on OS/390 Must be ASCII A.91, A.94 String 11.12 Colorizing via Stroke and Fill 8.6, 10.2 Images cached by filename 17.8 Default-filesystem settings may need Included EPS Images Not Appearing in updating for images in memory PDF Pages 11.2, 17.6 1.21, 2.11 Library is not thread-safe 1.4 Digital Signature signed hash values No default font searching for must be exactly 256 hex digits dlpdfttload 2.3 15.5 Only fonts using standard encodings Disk resources used by default if Output may be fauxed 17.12 to Memory is not set 2.10 Pass accurate length values for PKCS #7 DLI v2.2 Unicode support now certificate output space reservation superceded by new Multibyte text 15.6, A.162 methods 5.2 Pattern Interaction with Color when dlpdfcontentarcto Discrepancies with Drawing Figures 10.17 PostScript Output 10.5 PDColorValue Permits Only 4 Channels DLPDFINSTANCE required for Unicode 12.11 font creation 1.13 PDEPathGetData Requirement for Path dlpdfmemfiledeleteonclose required for Data Retrieval 10.6 memory file deletion 1.15 PDEPathGetData Return Value 8.7 dlpdfpathaddarcto Line Drawing Details PDF Reference Manual errata file 10.10 available for download 1.10 dlpdfpathaddclose, Adding Disjoint Path Popup warning may occur for new PDF Segments After 10.14 in old viewers 1.12, 2.7 dlpdfttload does not re-parse previously- RSA encryption algorithm within loaded font file 5.4 SignDoc sample not recommended Document Sharing of COS Objects and for Production code 17.19 PDEColorSpaces 12.5 Sample applications are subject to Encryption Key Length, Setting in change 17.2 Multiple Documents 3.5 Slow Feedback from FontVerification Error Handling should conform to (Sample DLI Application) 17.14 Adobe guidelines 16.2 Structure Variations may exist between Index I.xvii

PDF 1.5 and earlier 1.3 PDDocSetNewSecurityData Type is Filled, Not Stroked 12.2 Use in Documents, Beginning and Type0 Fonts must be Subset if Ending 3.5 Embedded 4.8 PDEColorSpace Unicode NULL string terminators not Creating and Destroying 12.3 required or included in calculations Document Sharing 12.5 A.37, A.38 Use in Color Description 12.2 Upgrade applications to thread-safe PDEColorSpaceCreate capability as soon as possible 2.15 Creating and Destroying 12.5 WideText sample application uses fonts Use in Color Spaces not distributed with DLI 17.21 Advanced 12.11, 12.12 Basic 12.9 O Use in ICC Based Color Profile 12.10 PDEColorSpaceCreateFromName Outline Tree Use in Color Spaces Adding New Entry 14.3 Advanced 12.11, 12.12 Use in Bookmarks Basic 12.9, 12.10 Building Multiple Trees 14.2 PDEColorSpaceGetCosObj Output File, Writing Use in Image Color Spaces 12.3 Calls 3.4 PDEDash Document Information 3.4 Use in Line Drawing 10.19 Encryption 3.4 PDEDeviceNColorData Linearization 3.4 Use in Color Spaces Security Permissions 3.5 Advanced 12.11 PDEFontAttrs 4.5, 4.8, 17.11, 17.12 P charset field 4.9 encoding field 4.9 Page type field 4.9 Use in Content Interface 8.2 Use in Creation Calls in DLI 4.6 Page Interface Calls 6.2, 6.3 wMode field 4.10 Page Structure 6.2 PDEGraphicState 8.4, 8.5 PageMode Color Definitions 10.2 Use in Bookmarks 14.6 Use in Color Description 12.2 Paint Operator Use in Content Interface 8.2 Use in Content Interface Calls 8.5 Use in Displaying Images 11.13 Use in Line Drawing 10.2 Use in Line Drawing 10.2, 10.14, Pass-Through Objects 10.17 Use in Displaying EPS Images 11.7 dash 10.18 Passwords fillColorSpec 10.17 Setting in Encrypt (Sample DLI flatness 10.18 Application) 17.9 lineCap 10.18 Paths (Sample DLI Application) 17.5 lineJoin 10.18 Patterned Colors 12.2 lineWidth 10.17 Patterns, creating background 17.17 miterLimit 10.18 PCKS #7-format certificates 17.19 effect on lineJoin 10.18 PD_STD_ENCODING (flag) 17.12 strokeColorSpec 10.17 PDColorValue PDEGrayCalFlt Use in Color Spaces Use in Color Spaces Advanced 12.11 Basic 12.9 PDDoc 3.2 PDEICCBasedColorData I.xviii DLI Implementation and Reference Guide

Use in ICC Based Color Profile 12.10 Routines 2.5 PDEIndexedColorData Use in Terminating Library 2.12 Use in Color Spaces PDFLGetVersion ConceptsAdvanced and Facilities: 12.12 Guide to the DL PagerUse inComposition Obtaining Version System Number 2.6 PDELabCalFlt PDFLInit Use in Color Spaces Caution on Multiple Initializations of Basic 12.9 pre-v6.1 Library 2.9, A.91 PDEPath Prohibition on calling from DLI v3.0 Use in Line Drawing 10.6 1.14, A.91 PDEPathAddSegment Use in Default Search Path Suppression Cited in PDF Rules for Path Construction 1.21 10.6 Use in Initializing and Terminating via PDEPathGetData A.17 DLI 2.9 Use in Content Interface Calls 8.7 Use in Multi-Thread Initializations 2.13 Use in Line Drawing 8.7, 10.6 PDFLTerm PDERGBCalFlt Prohibition on calling from DLI v3.0 Use in Color Spaces 1.14, A.91 Basic 12.9 Use in Multi-Thread Initializations 2.13 PDESeparationColorData pdfMajorVer 2.7 Color Spaces pdfMinorVer 2.7, 2.8 Advanced 12.11 PDFNeeded (flag) PDETextState 8.4 Removal from dlpdfdoccreate 1.18, Use in Content Interface 8.2 A.43 PDF PDPerms Image Conversion from 11.2 Use in Documents, Beginning and Level Declarations in Output 1.12, 2.6 Ending Declarations via DLI 1.12 Encryption 3.5 DLI-selected Declarations 2.7 PDViewDestNull Overriding DLI-selected Declarations Use in Bookmarks 14.3 2.7 Use in Links Use in Displaying Images 11.8, 11.10, with Zoom 13.5 11.11 Performance Considerations Use in Graphical Language Forms 11.5 Font Creation Calls in DLI 4.13 Use in Graphics (Sample DLI Application) Plugins 17.6 Self-Sign 17.19 PDF Library VeriSign Signature 17.19 Use in Multithreaded Applications 1.11 PNG (Portable Network Graphics) Version Control 1.12, 2.6 Encoding and Compression References PDF Page Tree Structures 6.2 11.4 PDFInit.h Image Conversion from 11.2 Use in Setting Memory Allocation Use in Displaying Images 11.10 Routines 2.5 Use in Graphics (Sample DLI Application) Use in Setting Resource Allocation 17.6 Routines 2.5 Private keys 15.2 PDFLDataRec psOutput (Sample DLI Application) 17.20 Use in Default Search Path Suppression Public keys 15.2 1.21 Use in Initializing and Terminating the Q Library 2.2, 2.3 Use in Setting Memory Allocation QuickDraw Index I.xix

Use in Graphical Language Forms 11.5 Rotate (flag), in imported image files 1.14 RSA encryption algorithm 17.19 R S RAW (Unformatted Unannotated Bitmap) Use in Graphics (Sample DLI Application) Sample DLI Applications 17.6 AcroForm 17.18 readme.txt 1.11 Activating Files in Memory 17.2 realloc Annotations 17.15 PDFInit.h Interface to 2.5 Encrypt 17.9 reallocProc FontFaux 17.11 Use in Setting Memory Allocation FontVerification 17.13 Routines 2.5 Graphics 17.6 Rect (parameter) HelloDLI 17.4 Use in Annotation Dictionary 13.9 memFiles 17.16 Rectangles MultiDoc 17.16 Use in Links 13.5 NestedPDF 17.17 Release Notes 1.11 Overview 17.2 Resource Allocation Routines, Setting 2.5 Paths 17.5 Resource Directories, Setting psOutput 17.20 Use in Initializing and Terminating the SignDoc 17.19 Library 2.3 WideText 17.21 Resources Security Permissions Adobe Use in Documents, Beginning and AcroColor API Reference 1.10 Ending Adobe Acrobat Core API Overview Encryption 3.5 1.10 Use in Encrypt (Sample DLI Application) Adobe Acrobat Core API Reference 17.10 1.10 Self-Sign Plugin 17.19 Adobe PDF Library Overview 1.10 Separation Adobe PDF Library Supplement to Color Spaces the Acrobat Core API Advanced 12.11 1.11 Seven-Bit Safe Portable Document Format Use in Displaying Images 11.7 Reference Manual 1.10 Signatures Errata file 1.10 as images in Digital Signatures 15.3 Datalogics SignDoc (Sample DLI Application) 17.19 Adobe PDF Library and DLI Standard Encoding Installation Guide 1.9 Use in Documents, Beginning and Adobe PDF Library Developer Ending 3.3 Overview 1.9 StdSecurityDataRec DLI Implementation and Reference Use in Documents, Beginning and Guide 1.9 Ending 3.5 Java Interface User Guide 1.9 sticky note RGB Color Use in Annotations and Links 13.4 Collapsing to Gray 12.16 Streaming PostScript Converting to CMYK 12.17 Removal from DLI v3.0 1.14 Use in Annotations and Links 13.3 stroke (parameter) Use in Color Description 12.2 Use in Displaying Images 11.5 Use in ICC Based Color Profile 12.10 Stroke Color 8.6 I.xx DLI Implementation and Reference Guide

Use in PDEGraphicState 10.2 Scaling 10.16 strokeColorSpec Shearing 10.16 Use in Color Description 12.2 Translation 10.16 ConceptsUse in andLine Drawing Facilities: 10.17 Guide to the DLTransforms Pager Composition System Sub-minor Version Number 2.6 Association with Content Elements 8.2 SubType (parameter) Tree Name Use in Annotation Dictionary 13.9 Use in Links 13.8 Use in Links 13.9 TrueType font Terminology usage 4.4 T Type Filled vs. Stroked 12.2 Table of Contents Type (parameter) Generation via FontVerification (Sample Use in Annotation Dictionary 13.9 DLI Application) 17.13 Use in Links 13.9 Text Container Creation and Positioning 8.3 U Text Placement Calls 8.4 Text Layering 8.2 Unicode Text Width 8.4 as CIDType2 Fonts 4.3 Thread Safety Text Support Caution on Multiple Initializations of Font Type Recommendations 4.13 pre-v6.1 Library 2.9 NULL string terminators A.37, A.38 Initialization of non-thread-safe Library Unix Compiler Run-Time Libraries 1.4 releases 2.14 URI Multi-Thread Initializations 2.13 Use in Links 13.7 Thumbnails URL Calls 3.4 Use in Links 13.7 Use in Documents, Beginning and UseOutlines Ending 3.4 Use in Bookmarks 14.6 TIFF (Tagged Image File Format) Encoding and Compression References V 11.4 Image Conversion from 11.2 VeriSign signature plugin 17.19 Use in Displaying Images 11.10 Version Number, Obtaining 2.6 Use in Graphics (Sample DLI Application) 17.6 W TKAllocatorProcs Use in Setting Memory Allocation What’s New Routines 2.5 DLI v2.2.12 1.21 TKResourceProcs Default Search Path Suppression Use in Setting Resource Allocation 1.21 Routines 2.5 DLI v2.2.13 1.20 Transformation Matrix Default Search Path Suppression Arguments 10.15 Expanded to All Platforms Overview 10.15 1.20 Translations Image Search using Files in Memory Inversion 10.16 1.20 Mirror-image 10.16 DLI v3.0 1.11 Rotation 10.16 Overview 1.11 Scale/Rotation Caution 10.16 WideText (Sample DLI Application) 1.13, DLI Implementation and Reference

17.21 WinAnsiEncoding Use in Documents, Beginning and Ending 3.3 WMF (Windows Metafile Format) Use in Graphical Language Forms 11.5 Writing Pages Procedure for 1.2

X x.509 certificate 17.19 XYZ Use in Links with Zoom 13.5

Z zoom Use in Bookmarks 14.3 Use in Links 13.5