Developer Overview Adobe PDF Library v7.0 Datalogics® Datalogics ADOBE PDF LIBRARY Developer Overview This guide is part of the Adobe PDF Library v7.0.5 suite; 08/17/06. Copyright 1999-2006 Datalogics Incorporated. All Rights Reserved. Use of Datalogics software is subject to the applicable license agreement. Datalogics Interface (DLI) 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, PostScript, Acrobat, Distiller, Exchange and Reader are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States or other countries. 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. 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 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.4 Related Documentation 1.5 What’s New in This Release 1.7 What’s New in Previous Releases 1.9 2 Design Overview 2.1 Introduction 2.2 Adobe PDF Library Version Control 2.2 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.7 Enhancements for the OS/390 and OS/400 Environments 2.11 Assembler Interface 2.11 Platform-Specific Concerns 2.13 3 Structure Reference 3.1 Interface Structure Summary 3.2 Job Interface 3.2 Document Interface 3.3 Page Interface 3.7 Graphical Interface 3.9 4 PDF Functionality 4.1 OS/390 Examples 4.2 PDF Document Options 4.4 Compatibility Between PDF Documents 4.7 Compatibility with External Applications 4.8 Optimizing Performance 4.9 Print Issues 4.10 5 Data Conversion 5.1 Translations 5.2 TOC.2 Adobe PDF Library Developer Overview 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. Experienced users may want to skip directly to the section “What’s New in This Release” on page 1.7 for information on the latest enhancements and additions. 1.1 1.2 Adobe PDF Library 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 here applies to all platforms, not just Datalogics ports. 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 for either viewing with Adobe Acrobat, Adobe Reader and similar PDF viewers, 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 does not require a Graphical User Interface, and applications built with it do not require Adobe Acrobat or Adobe Reader viewers for operation. (You can also create a Windows viewing application using the Adobe PDF Library. Ask your Sales or Support representative for a copy of the DLViewer sample application.) The interface to the Adobe PDF Library is in terms of calls to library-defined entries (the API). The Adobe PDF Library appears as a collection of objects and their applicabls methods, in 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 About This Guide 1.3 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 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 1.4 Adobe PDF Library Developer Overview referencelibrary.pdf document using the copy of Adobe Reader provided (or any other PDF viewer utility). For Adobe PDF Library v6.x releases, Adobe PDF Specification 1.5 is appropriate. For Adobe PDF Library v7.x releases, Adobe PDF Specification 1.6 is appropriate. NOTE: Some structures permitted in Adobe PDF Specification 1.6 may not be permitted in Adobe PDF Specification 1.5, and some structures defined in Adobe PDF Specification 1.5 are not available in Adobe PDF Specification 1.4. The explanations, assumptions and samples provided in this guide refer to Adobe PDF Library v7.0.5 and DLI v7.0.5 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 various platforms, explains the function of the 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: "PDF Functionality" identifies some Adobe PDF Library functionality, and provides sample code to illustrate usage. In addition, discussions on optimizing performance and print issues are 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 v7.0®, Adobe Acrobat® and Adobe Reader®. These correspond to the text About This Guide 1.5 annotation, link annotation and routine entry structures (respectively) that appear in a PDF file. See the Portable Document Format Reference Manual for a description of the PDF file format. The following documentation conventions appear throughout the manual to help you differentiate regular text from product and program names, and to distinguish command syntax. • Product and program names are set in italic type. • Multi-line examples are separated from the text and set in Courier monospace • Directory names and filenames are contained within the text and set in Courier monospace. • Commands are contained within the text and set in Courier monospace.