Developer Overview Adobe PDF Library v6.1 Datalogics® Datalogics ADOBE PDF LIBRARY Developer Overview This guide is part of the Adobe® PDF Library v6.1.0Plus suite; 08/11/04. Copyright 1999-2004 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 prod- ucts 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. Microsoft, Windows and Windows NT are trademarks or registered trademarks of Microsoft Corporation. IBM, AIX, AS/400, OS/400, MVS, and OS/390 are registered trademarks of International Business Machines. HP and HP-UX are registered trademarks of Hewlett Packard Corporation. SAS/C is a registered trademark of SAS Institute Inc. 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. UNIX is a registered trademark of The Open Group. Linux is a registered trademark of Linus Torvalds. 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 1 Table of Contents 1 About This Guide 1.1 The Purpose of this Guide 1.2 Introduction 1.2 What You Should Know 1.3 How This Book is Organized 1.4 Document Conventions 1.5 Related Documentation 1.6 2 Design Overview 2.1 Introduction 2.2 Adobe PDF Library Version Control 2.3 Adobe PDF Library for OS/390, OS/400 and Selected Unix Platforms 2.4 Creating a PDF Document 2.6 How the PDF Library Operates 2.8 Enhancements for the OS/390 and OS/400 Environments 2.14 Assembler Interface 2.15 Platform-Specific Concerns 2.16 3 Structure Reference 3.1 Interface Structure Summary 3.2 Job Interface 3.2 Document Interface 3.4 Page Interface 3.9 Graphical Interface 3.12 2 Developer Overview 4 Examples 4.1 OS/390 Examples 4.2 Concepts and Facilities: Guide to the DL Pager Composition System PDF Document Options 4.6 Compatibility Between PDF Documents 4.8 Compatibility with External Applications 4.10 Optimizing Performance 4.11 5 Data Conversion 5.1 Translations 5.2 1 About This Guide This chapter explains the scope and content of this guide and provides developers with an introduction to the Adobe PDF Library. 1.1 1.2 Developer Overview The Purpose of this Guide This guide is designed to aid developers with incorporating the API calls for the Adobe PDF Library and DLI into their composition application. NOTE: Datalogics ports the Adobe PDF Library and DLI to the OS/390, OS/400 and certain additional Unix platforms, but also supports the products on the original Adobe-selected Windows, Macintosh and Unix platforms. Except where noted, information in this Datalogics manual applies to all platforms, not just those to which Datalogics has ported the software. Introduction The Adobe PDF Library is a collection of object-oriented routines offering an Application Programming Interface (API) which enables your composition application to produce PostScript (PS) or Portable Document Format (PDF) Page Description Language (PDL) files. PDF files are compact, device-independent files providing efficient electronic distribution of large documents either viewed by Adobe Reader or output to high-speed printers. As with the original Adobe release on Windows, Macintosh and certain Unix platforms, the Datalogics-supplied Adobe PDF Library and DLI allow you to control the manipulation of PDF files. The Library can link to your composition application to manipulate and produce PDF files, and can also add private data to the PDF output. NOTE: The Adobe PDF Library cannot be used to display PDF files on the OS/390 and OS/400 operating systems. From the User’s Viewpoint Adobe PDF Library for HP-UX, OS/390 and OS/400 does not require a Graphical User Interface. Applications built with it do not require Adobe Acrobat or Adobe Reader in order to generate PDF output. The interface to the Adobe PDF Library is in About This Guide 1.3 terms of calls to library-defined entries (the API). The Adobe PDF Library appears as a collection of objects, and methods which may be applied to them. The objects fall into three categories: 1 Objects that persist, either in memory or in the object store, until a document is completed and freed 2 A collection of objects used to communicate with the Adobe PDF Library which has a short life span and is terminated by a call into the Adobe PDF Library 3 A Library Control Object, which is the PDFLDataRec structure created before initializing the Adobe PDF Library, populated before and during the Adobe PDF Library initialization, and cleared and released during and after the Adobe PDF Library termination What You Should Know This book is not for developers new to application programming interfaces; therefore, it does not describe programming concepts and techniques. The following list describes the level of experience or knowledge required to understand this book: • Familiarity with high-level language Application Programming Interfaces (APIs), programming on the relevant operating system with the corresponding development tools for that platform, and the process of writing applications in general • A general understanding of the structure and contents of PDF files; the PostScript language; font management (the complete set of characters of a particular design) including the style, arrangement, and appearance of typeset matter for print or electronic display; and composition processes in the platform environment Your application should be capable of the following, where appropriate: • Applications which create PDF should be capable of providing the x and y page coordinates for each object to be placed on the page. The default basis of the coordinates are based on the "first quadrant" values, where (0,0) is the lower left 1.4 Developer Overview corner. Applications which consume or modify PDF will be supplied the x and y page coordinates for each component addressed. • Applications generating textual objects must be capable of specifying font and point size information for those objects. i.e. The Adobe PDF Library itself is not a composition engine; its purpose is to produce Adobe PDF-compliant code as directed by the application, according to the typesetting information provided by that application. You should have access to the Adobe PDF Library Applications Programming Interface (API) manual, related Datalogics Interface documentation, and the Adobe PDF Specifications manual for your system. You should find these documents provided within your release, accessible via the referencelibrary.pdf document using the copy of Adobe Reader provided (or any other PDF viewer utility). 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. How This Book is Organized The following list provides an outline of the chapters as well as a brief description of their contents. Click on each Chapter title below to jump to its first page. Chapter 1: "About This Guide" (This chapter) outlines the chapters to follow, explains the document conventions used here, and lists other related documentation which you may find useful for your work. Chapter 2: "Design Overview" introduces the design of the components of the Adobe PDF Library for HP-UX, OS/390, and OS/400, explains the function of the About This Guide 1.5 Adobe PDF Library, and summarizes concepts and the most common objects and methods used. Chapter 3: "Structure Reference" lists the functional specifications for each interface. These object and method names are described in-depth in the Acrobat Core API On-line Reference document. Chapter 4: "Examples" identifies some Adobe PDF Library functionality for HP- UX, OS/390 and OS/400, and provides sample code to illustrate usage. In addition, a discussion on optimizing performance is included. Chapter 5: "Data Conversion" explains the translation process from EBCDIC to ASCII. 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®, Adobe Acrobat® and Adobe Reader®. These correspond to the text annotation, link annotation and routine entry 1.6 Developer Overview structures (respectively) that appear in a PDF file. See the Portable Document Format Reference Manual for a description of the PDF file format. The following documentation conventions appear throughout the manual to help you differentiate regular text from product and program names, and to distinguish command syntax. • Product and program names are set in italic type. • Multi-line examples are separated from the text and set in Courier monospace • Directory names and filenames are contained within the text and set in Courier monospace. • Commands are contained within the text and set in Courier monospace. • 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.