Você está na página 1de 78

Installation Guide

Adobe PDF Library v7

Datalogics

Datalogics
ADOBE PDF LIBRARY

Installation Guide

This guide is part of the Adobe PDF Library v7.0.1Plus suite; 08/30/06. Copyright 1999-2006 Datalogics Incorporated. All Rights Reserved. Use of Datalogics software is subject to the applicable license agreement. Datalogics Interface and Datalogics Java Interface are trademarks of Datalogics Incorporated. Other products mentioned herein as Datalogics products are also trademarks or registered trademarks of Datalogics, Incorporated. Adobe, Adobe PDF Library, Portable Document Format (PDF), PostScript, Acrobat, Distiller, Exchange and Reader are trademarks of Adobe Systems Incorporated. HP and HP-UX are registered trademarks of Hewlett Packard Corporation. IBM, AIX, AS/400, OS/400, MVS, and OS/390 are registered trademarks of International Business Machines. Java, J2EE, J2SE, J2ME, all Java-based marks, Sun and Solaris are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. Linux is a registered trademark of Linus Torvalds. Microsoft, Windows and Windows NT are trademarks or registered trademarks of Microsoft Corporation. SAS/C is a registered trademark of SAS Institute Inc. UNIX is a registered trademark of The Open Group. VeriSign is a registered trademark of VeriSign, Inc. in the United States and/or other countries. All other trademarks and registered trademarks are the property of their respective owners. For additional information, contact: Datalogics, Incorporated 101 North Wacker Drive, Suite 1800 Chicago, Illinois 60606-7301 Phone: 312-853-8200 Fax: 312-853-8282 www.datalogics.com dlcomments@datalogics.com

Table of Contents
1 About This Guide
Introduction The Purpose of This Book What You Should Know How This Book is Organized Document Conventions Related Documentation Whats New in This Release Whats New in Previous Releases 1.2 1.2 1.3 1.3 1.4 1.4 1.6 1.7

1.1

2 Installing the PDF Library and DLI


Adobe PDF Library Installation Procedure Windows Installation UNIX Installation AS/400 OS/390 DLI Installation Procedure Documentation Unpacking 2.2 2.3 2.11 2.17 2.21 2.34 2.35

2.1

3 Configure Your Environment


Building with the Adobe PDF Library and DLI Setting Environment Variables Building and Running Sample Jobs Unresolved Symbol References on UNIX Accessing Font Information Using z/OS Fonts in Zip Files 3.2 3.4 3.9 3.16 3.17 3.19

3.1

TOC.2 Adobe PDF Library

1 About This
Guide
This guide describes the system components and installation requirements for the Adobe PDF Library (APDFL) and the Datalogics Interface (DLI). This guide also includes information on how to configure the development environment, and discusses application considerations.

Experienced users may want to skip directly to the section Whats New in This Release on page 1.6 for information on the latest enhancements and additions.

1.1

1.2

Ado be P DF L ibr a ry Ins ta ll a ti on Gui de

Introduction
This chapter explains the scope and contents of this guide, provides highlights of each chapter, describes the organization of the information, and explains the conventions used throughout.

The Purpose of This Book


This guide is intended to provide information necessary to install and set up the Adobe PDF Library (APDFL) and Datalogics Interface (DLI). However, it is not a replacement of Adobes own Adobe PDF Library Overview document, but should be used as a supplement.
NOTE: Datalogics ports the Adobe PDF Library and DLI to other platforms beyond those chosen by Adobe, such as HP-UX, OS/390, OS/400 and SGI IRIX, but also supports the products on the original Adobe-selected platforms. Except where noted, information in this Datalogics manual applies to all platforms, not just those to which Datalogics has ported the software.

About This Guide

1.3

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: Product development knowledge in addition to programming, such as database and macro development Familiarity with the process of writing applications Understanding of high-level language Application Programming Interfaces (APIs) Knowledge of programming on the specific platform of interest, including use of the corresponding development tools A general understanding of the structure and contents of PDF files and the PostScript language Experience in managing fonts (the complete set of characters of a particular design), including the style, arrangement and appearance of typeset matter for print or electronic display from composition Knowledge of the operating-system environment of the platform 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). The explanations and assumptions in this guide refer to Adobe PDF Library v7.0.1Plus and DLI v7.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: "Installing

the PDF Library and DLI" provides installation procedures for Adobe

PDF Library and DLI by platform. Chapter 3: "Configure

Your Environment" describes how to configure your development

environment after installation and before incorporating the Library into your applications.

1.4

Ado be P DF L ibr a ry Ins ta ll a ti on Gui de

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 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. New terms are italicized. Page numbers in this book do not correspond to page numbers in the PDF file. The numbering scheme (e.g. 4.1 or A.10) indicates the chapter number (4) or appendix letter (A) first, followed by the page number (1 or 10), separated by a period.

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

Datalogics Resources
Adobe PDF Library and DLI Installation Guide (This book) 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 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.

About This Guide

1.5

Adobe Resources
The following documents are distributed by Adobe as part of the original Adobe PDF Library release, and are redistributed by Datalogics without alteration. These and other documents may also be found on the Adobe website at http://partners.adobe.com/asn/acrobat/technotes.jsp. (Descriptions below are provided by Adobe as part of their original accompanying readme.txt file.)
NOTE: Adobe Solutions Network (ASN) membership may be required in order to access some material on the Adobe website. See http://

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

Portable Document Format Reference Manual This document describes PDF Standard 1.6 specifications. The latest version may be found at http://partners.adobe.com/public/ developer/pdf/index_reference.html.
NOTE: Adobe also provides an accompanying errata file for this manual, with lastminute updates and corrections. One copy is provided with this documentation (see your documentation file folder), and you can check for newer copies at

http://partners.adobe.com/public/developer/en/pdf/ PDF16Errata.pdf Adobe PDF Library Overview This guide provides background 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 and PDF Library API Overview This guide provides an overview of the Acrobat API in

general. It covers information applicable to both Plug-in development and PDF Library development. Read this document to obtain an understanding of how the Acrobat API is organized. Acrobat and PDF Library API Reference This is the reference manual for all of the Acrobat API methods made available to the Acrobat Viewer and Adobe PDF Library. It documents the parameters, return values and availability of each method, as well as specific implementation notes. This document is

1.6

Ado be P DF L ibr a ry Ins ta ll a ti on Gui de

useful while developing with the Adobe PDF Library or planning development to determine method availability and capabilities.
NOTE: As of the v7.x release series, the former "PDF Library Supplement to the Acrobat Core API" (Technical Note #5414) is now combined with this manual, as a separate section near the back of the main book.

3D Annotations Tutorial As its Introduction explains, "This tutorial describes how to programmatically create 3D annotations in PDF files. The code [...] can be used as part of an application developed using the Adobe PDF Library." 3D JavaScript Reference This guide provides a listing of the JavaScript APIs specific to adding interactivity to 3D annotations within PDF documents. SnippetRunner Cookbook This documents the useful SnippetRunner sample application development tool, provided by Adobe as a means of rapidly developing new functions using Library methods, and testing them within the context of a working Library application.

Whats New in This Release


This section contains highlights of new additions and enhancements to Adobe PDF Library v7.0.1Plus and DLI v7.0.1. 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) if present. Release Notes contain fixes and enhancements usually resulting from past problem reports; the readme.txt files typically contain lastminute information on the current release of the software or the documentation files. Enhancements listed in this document generally pertain to those added by Datalogics when building the release of the Library accompanied by the Datalogics Interface (DLI). (The "Plus" suffix on the version number of a Library release denotes a Datalogics build, usually with accompanying DLI. An original Adobe-built Library release obtained directly from Adobe does not carry the "Plus" designation, and does not function with DLI methods.) Updates and enhancements added by Adobe in their original release may be found in Adobes own release notes and Adobe documentation and user guides. Minor version upgrades may be made as running changes rather than full releases, so the version or subversion number of your release may be newer than those listed here. See the accompanying readme.txt file for the very latest changes and enhancements.

About This Guide

1.7

New IBM AS/400 Release


A new production release of Adobe PDF Library v7.0.1PlusP1h for IBM AS/400 is now available. As with a previous v5.0 release, this is a Library-only port; it does not include DLI methods.

New MIPS32 IRIX Release


A new production release of Adobe PDF Library v7.0.1PlusP1a for MIPS32 IRIX has been released. As with a previous v6.0 release for IRIX, this is a Library-only port; it does not include DLI methods.

Whats New in Previous Releases


A summary of enhancements in prior releases follows below.

v7.0.0
libstdc++ and libgcc Dependencies Removed

As of the Adobe PDF Library v7.0.1PlusP1d release, libstdc++ and libgcc dependencies were removed from IBM AIX, Linux and Solaris platforms (although the sample application builds still depend on them).
DLI Version Numbering Upgrade

DLI version numbering was brought forward from v3.x to v7.x, to better correspond with current Adobe PDF Library version numbering.
Termination of Support for ACRO_RES_DIR and PSRESOURCEPATH

As of the Adobe PDF Library v7.0 release, Adobe dropped support for ACRO_RES_DIR and PSRESOURCEPATH variables. Please modify your application and/or its environment as necessary to place all its font & CMap resource directories into the list of directories scanned by PDFLInit() or dlpdfinit() upon startup.

1.8

Ado be P DF L ibr a ry Ins ta ll a ti on Gui de

2 Installing
the PDF Library and DLI
This chapter covers installation procedures and lists supported platforms and compilers.

2.1

2.2

Ado be P DF L ibr a ry Ins ta ll a ti on Gui de

Adobe PDF Library Installation Procedure


Platform-specific installation procedure notes follow below. After the code libraries have been installed, documentation files should be unpacked in the appropriate areas. (They are not automatically installed as part of the software.) If you are reading this Installation manual prior to running the installation procedure itself (e.g. after downloading this manual from the Datalogics website), please continue with the installation of the software release itself first, after which the documentation files can be unpacked into the directories created during the software install, per the directions given in Documentation Unpacking on page 2.35.

Supported Platforms and Compilers


The following table lists the supported platforms, operating system and compiler versions for the Adobe PDF Library and DLI. Except where noted, support for a higher version above and beyond that listed below is not automatically implied. Please see notes following the table (below) for more details.
Table 2-1: Supported Platforms and Version Numbers Platform HP PA-RISC/64-bit IBM AIX Operating System Version v11.11 v5.1 Compiler and Version gcc v3.52 gcc v3.3 for AIX Compiler or XL C/C++ (VisualAge) compiler, version 6 IBM C/C++ compiler V5R3 IBM C, Assembler IBM C gcc v3.2 CodeWarrior v9.2 gcc c3.2 (SGI distribution) or gcc v3.3 (POSIX threads enabled) gcc v3.2 Sun Studio C/C++ v10 MS Visual Studio .NET

IBM AS/400 IBM OS/390

OS/400 V5R2 or higher MVS USS

Linux Macintosh MIPS32 Sun Solaris/32-bit Sun Solaris/64-bit Windows (Intel)

Red Hat 7.2 and 8.0 Mac OS X.2 IRIX v6.5 v8 and higher v8 and higher Windows NT 4.0 (Service Pack 6 and higher), 2000 or XP

Installing the PDF Library and DLI

2.3

Notes on Supported Platforms and Compilers

1 The preceding table refers to Adobe PDF Library v7.0.x and DLI v7.x releases (and higher) only. If building your application with a prior release, please consult its accompanying documentation. 2 Except where noted, the preceding table refers to 32-bit implementations only. 3 Datalogics distributes DLI with International Components for Unicode (ICU) v2.6. Depending on your application and system configuration, it may be easier for you to use your own ICU build. Any of the v2.6.x series should be compatible with DLI, if it was built in a compatible manner (i.e. corresponding tools and compiler).

Windows Installation
An installation procedure will be delivered with the product when downloaded from your secure ftp user account on the Datalogics ftp site (ftp.datalogics.com). This release contains all the files you will need to install the Adobe PDF Library and Datalogics Interface. Before beginning a new installation, you should uninstall any prior releases of Adobe PDF Library and Datalogics Interface. (InstallShield itself will check for current copies of the installation; see Repetitive Installations on page 2.9 for further details.) Next, locate and double-click on the Setup.exe program, and InstallShield will guide you through the installation.
NOTE: The following screen illustrations show an Adobe PDF Library v7.0.5PlusP1c installation. Installation screens for later release versions are similar.

1 A small popup window will appear as the InstallShield Wizard loads:

2.4

Ado be P DF L ibr a ry Ins ta ll a ti on Gui de

2 An initial setup screen will appear as the InstallShield application loads:

3 After InstallShield has initialized, a welcome screen will appear:

Click the Next button to proceed.

Installing the PDF Library and DLI

2.5

4 You must accept the License Agreement in order to continue with the installation:

Click the Yes button to proceed. 5 At the Customer Information screen, enter your User Name and Company Name where indicated::

Accept the "Anyone" radio button if any users beside yourself will be using the application, or select the "Only for me" (current user logged in) option if you should be its only user on this machine.

2.6

Ado be P DF L ibr a ry Ins ta ll a ti on Gui de

6 Select the Setup Type and the Destination Folder:

While the Custom option does allow you to choose which program features you want installed, in general practice we recommend installing all features at once. See Selecting Features on page 2.10 for further details. By default, InstallShield will place the new release under the C:\Datalogics\APDFLxxx\ directory structure, where "xxx" denotes the current Library version. (Thus a new release of Adobe PDF Library and DLI will typically reside in an adjacent folder on the same level as previous releases, and not overwrite them.) Click the Browse... button to select an alternate location.
NOTE: Versions of the Adobe PDF Library and DLI prior to APDFL v4.05 were placed in C:\Program Files\ by default. You should ensure that any old DLL files and/or PATH definitions relating to the previous installations have been removed.

Installing the PDF Library and DLI

2.7

7 Doublecheck the displayed installation location and click the Next button to proceed

8 At this point InstallShield will begin the installation, displaying a Setup Status screen as it progresses:

2.8

Ado be P DF L ibr a ry Ins ta ll a ti on Gui de

9 When the completion screen appears, click the Finish button to conclude.

10 To install the documentation files, see Documentation Unpacking on page 2.35. By default, the Adobe PDF Library and DLI will be installed under C:\Datalogics\. The Adobe PDF Library is placed in C:\Datalogics\APDFLxxx\APDFL\ (e.g. C:\Datalogics\APDFL7.0.5\APDFL\). The Datalogics Interface is placed in C:\Datalogics\APDFLxxx\DLI\ (e.g. C:\Datalogics\APDFL7.0.5\DLI\)
NOTE: Versions of the Adobe PDF Library and DLI prior to APDFL v4.05 were placed in C:\Program Files\ by default. You should ensure that any old DLL files and/or PATH definitions relating to the previous installations have been removed.

Installing the PDF Library and DLI

2.9

Repetitive Installations
In order to avoid installing multiple copies of Adobe PDF Library on your machine, InstallShield detects whether a previous copy of this Adobe PDF Library version is already installed. If so, it will need to remove it before proceeding with the new installation release, via the following popup:

Accepting the Confirm Uninstall prompt will clear the previous copy of the release from the machine, ending with this completion screen:

At this point you must re-start the installation by again locating and double-clicking on the Setup.exe program.
NOTE: InstallShield prohibits only duplicate copies of the current version from residing on the machine; it does not prohibit prior releases. However, you should ensure that any prior releases are either isolated from the current environment in some manner (e.g. if they must be retained for backwards-compatibility or regression testing) or uninstalled in order to prevent inadvertent conflicts with the new release.

2.10

Ado be P DF L ibr a ry Ins ta ll a ti on Gui de

Selecting Features
During installation, while you are on the Setup Type installation screen, InstallShield will offer the option of selectively installing only certain portions of the Adobe PDF Library and DLI. If you select the Custom radio button to choose which program features you want to install, this screen will appear:

If desired, you can check or un-check the boxes above, which correspond to subfolders under the directory trees created for APDFL and DLI during installation. Normally, a full installation is always recommended. However, this optional screen may be useful if needed to replace only certain files and folders for any reason, such as if folders were inadvertently corrupted or lost.

DLL File Placement


The Library is considered to be a toolbox rather than an application unto itself, and so the installation procedure does not automatically place DLL files in known system resource locations such as C:\Windows\System32, etc. Similarly, system registries are not modified during installation. It is assumed that when you build your own Library application, you will allocate resources in your own setup procedures, and make their location(s) known to your application. When installing an update or upgrade of Adobe PDF Library and DLI, be sure to propagate the new library and DLL files to any locations where the previous copies may reside.

Installing the PDF Library and DLI

2.11

UNIX Installation
UNIX installations will typically contain both Adobe PDF Library and DLI release files in one .tar file. After downloading via ftp or copying the release from CD-ROM (depending on how you receive your software from Datalogics), select a high-level location for unpacking the release: e.g. /var, /opt, /var/ Datalogics or /opt/Datalogics. The release will unpack itself into directory trees under the current location. The following steps demonstrate a typical installation on a Solaris v5.8 machine. Other UNIX platforms will be similar:
NOTE: The following screen illustrations show an Adobe PDF Library v7.0.1Plus installation. Installation screens for later release versions are similar.

1 Current UNIX releases are usually distributed as Gzipped .tar files. Copy the .tar.gz file to your selected location; e.g. /var/Datalogics.

2.12

Ado be P DF L ibr a ry Ins ta ll a ti on Gui de

2 Issue the Gunzip command for your release file; e.g.: gunzip APDFL7.0.1plusP1c_sparc32-sol8-gcc32.tar.gz This will unpack the release .tar.gz file into its primary .tar file.

3 Issue the unpack command for your release file; e.g.: tar xvf apdfl7.0.1plusp1c_sparc32-sol8-gcc32.tar

This will unpack the release .tar file into several subsidiary .tar files.

Installing the PDF Library and DLI

2.13

4 Unpack each of the resulting .tar files in turn:

5 Subsidiary directories will be created as the unpacking process proceeds:

2.14

Ado be P DF L ibr a ry Ins ta ll a ti on Gui de

6 After unpacking the last .tar file, the directories and subdirectories should be fully populated:

7 Under the /var/Datalogics/APDFL7.0.1 (or similar) branch that was just created, locate the *.mak file (whichever one is appropriate for your platform) within /APDFL7.0.1/Samples/ utils:

Installing the PDF Library and DLI

2.15

8 Edit the appropriate *.mak file for your platform to point to the correct gcc and g++ locations, to ensure that make procedures will build correctly:

9 Do the same local modifications within /var/Datalogics/DLI/Samples/All to update gcc and g++ references in makefile.platform, which covers all platform building for DLI samples in one file using platform-specific conditional branches:

2.16

Ado be P DF L ibr a ry Ins ta ll a ti on Gui de

10 Finally, set the environment variables appropriately (as described in the next chapter):

(See the appropriate listings for your platform in the section Setting Environment Variables on page 3.4) 11 At this point you should be able to build all samples by issuing a gmake command:

12 To install the documentation files on a Windows machine, see Documentation Unpacking on page 2.35.

Installing the PDF Library and DLI

2.17

AS/400
Follow the steps below to install the Adobe PDF Library for AS/400. These instructions and screenshots illustrate the installation of PDFL701P1H by name; your installation may have a slightly different version number. 1 Your release is delivered in the form of a SAVF file. Move this file via binary FTP to a temporary location (e.g. your personal library) on the AS400. (This would not be in ifs.) If one does not exist yet, issue a CRTLIB <your_user_name> command to create one, followed by a CRTSAVF command to provide a receiving area for the incoming SAVF file:

2 If you are not installing this for the first time and there is a previous release of the same name already there, remove or rename it. You are now ready to deliver the SAVF file via a binary ftp put command:

2.18

Ado be P DF L ibr a ry Ins ta ll a ti on Gui de

3 Next, restore the SAVF file (e.g. RSTLIB PDFL701P1H DEV(*SAVF) SAVF(KHAHN/PDFL701P1H)). This may take a few minutes, after which you should see the message "21 objects restored from PDFL701P1H to PDFL701P1H".

NOTE: The exact number of objects in a release may vary without notice.

4 Enter the command ADDLIBLE PDFL701P1H to add PDFL701P1H to your library list. 5 Go into QSH. If the /datalogics directory already exists, delete or rename it as you prefer, to ensure that an older copy of the same name is no longer there:

Installing the PDF Library and DLI

2.19

6 Next, set PDFL701P1H to your current library (e.g. CHGCURLIB PDFL701P1H). Enter STRPDM, and go into PDFL701P1H. 7 Go into your newly-created library (e.g. PDFL701P1H) and type 16 next to 'SETUP701' *CMD (not *PGM), then press F4

8 Enter 'PDFL701P1H' (or as appropriate) in the Distribution Library field, and press Enter:

This will create the /datalogics directory structure, after which you should see a Completed Setup message appear.

2.20

Ado be P DF L ibr a ry Ins ta ll a ti on Gui de

A listing should now display the unpacked files:

For details on building and running the newly-unpacked sample files, please see the AS/400 section of the next Chapter under IBM C/C++ on page 3.17.

Installing the PDF Library and DLI

2.21

OS/390
Installing the z/OS version of PDF Library on MVS
Follow the steps below to install the Adobe PDF Library for OS/390 on MVS.
If DSS is installed:

1 Allocate a dataset to receive the .xmit file:

2.22

Ado be P DF L ibr a ry Ins ta ll a ti on Gui de

It should have the following DCB characteristics: Record Format FB Record Length 80 Block Size 3120

NOTE: Space units may be defined as megabytes (Mb) according to how many megabytes the .xmit file uses. You can determine this number by checking your local drive (or other location) for the size of the .xmit file.

Installing the PDF Library and DLI

2.23

2 Binary ftp vxxx/DSS/pdfpvxxx.xmit to your OS/390.

3 Allocate a file for the Restore.JCL file:

2.24

Ado be P DF L ibr a ry Ins ta ll a ti on Gui de

It should have the following DCB characteristis: Record Format VB Record Length 80 Block Size 6233

NOTE: Space units may be defined as megabytes (Mb) according to how many megabytes the .xmit file uses. You can determine this number by checking your local drive (or other location) for the size of the .xmit file.

Installing the PDF Library and DLI

2.25

4 ASCII ftp vxxx/DSS/JCL/restore.jcl to your OS/390.

5 Allocate a new Data Set:

2.26

Ado be P DF L ibr a ry Ins ta ll a ti on Gui de

It should have the following characteristics: Record Format U Record Length 0 Block Size 19069

Installing the PDF Library and DLI

2.27

6 Now RECEIVE the .xmit file:

At the TSO command prompt, enter: RECEIVE INDATASET('PDFPvxxxXMIT') where vxxx is the version number and the letter of release.

2.28

Ado be P DF L ibr a ry Ins ta ll a ti on Gui de

7 The message Enter restore parameters or 'DELETE' or 'END' + Enter. appears, prompting you for a dataset name.

Type: DSN('datasetfilename') where datasetfilename is the name of the dataset file to use.
NOTE: You must allocate the dataset prior to restoring the dataset.

Installing the PDF Library and DLI

2.29

Installation via JCL

1 Update your RESTORE JCL. The file as delivered will contain two dummy placeholders: Replace1 and Replace2, which should be replaced by the correct values for your system: Replace1 the name of the Data Set created when your .xmit file was RECEIVEd Replace2 the name of the volume where you want to place the new output PDS files

2.30

Ado be P DF L ibr a ry Ins ta ll a ti on Gui de

(See the comments in the JCL file.)

2 Submit RESTORE JCL:

Installing the PDF Library and DLI

2.31

JCL Dataset File List

Executing the JCL will catalog and populate the following datasets on your system:

Dataset/Filenames

Function Input PDF file for ADDELEM PDFL C/C++ Sample Input file for DLGRAPH DLI C/C++ Sample Assembler samples JCL for Assembler samples Load library for Assembler samples Macro library for Assembler samples Object library for Assembler samples Input PDF file for Assembler samples Input file for DLMULTI DLI C/C++ Sample C members of C/C++ samples JCL for C/C++ samples Load library for C/C++ samples Object library for C/C++ samples Compiler and link options for C/C++ samples Zip file to store Cmaps Copy library for Assembler samples C++ members of C/C++ samples Input PDF file for DECRYPT PDFL C/C++ Sample Input PDF file for DLANNOT DLI C/C++ Sample Input PDF file for Assembler samples Input PDF file for DRWTOMEM PDFL C/C++ Sample Export files Zip file to store Fonts Input files for DLGRAPH DLI C/C++ Sample

ADDELEM.PDF ADDIMAGE.RAW
ASM

ASM.JCL ASM.LOAD ASM.MACLIB ASM.OBJ BILL.PDF BITMAP.RAW


C

C.JCL C.LOAD C.OBJ C.OPTS CMAP.ZIP


COPY CPP

DECRYPT.PDF DLANNOT.PDF DLLOGO.PDF DRWTOMEM.PDF


EXP

FONT.ZIP IMAGE.EPS, IMAGE.GIF, IMAGE.JPG IMAGE.PDF

Input PDF file for C/C++ Samples

2.32

Ado be P DF L ibr a ry Ins ta ll a ti on Gui de

Dataset/Filenames

Function Input files for DLGRAPH DLI C/C++ Sample

IMAGE.PNG, IMAGE.RAW, IMAGE.TIFF


JCL

JCL Input PDF file for JPXENC PDFL C/C++ Sample Load libraries for PDFL Macro library Input file for PEDDLER PDFL C/C++ Sample Input files for MERGEPDF PDFL C/C++ Sample Input PDF file for Assembler samples Input file for PEDDLER PDFL C/C++ Sample Input file for PRINTPDF PDFL C/C++ Sample Input file for DLMULTI DLI C/C++ Sample Input files for DLNSTPDF DLI C/C++ Sample Input files for DLWIDE DLI C/C++ Sample

JPXENC.PDF
LOAD MACLIB

MAPFILE.TXT MERGE1.PDF, MERGE2.PDF PBEAR.PDF PEDDLER.PDF PRINTPDF.PDF SIMPLE.EPSF S1DDEB2.PDF, S1LOGO1.PDF UTF16BCS.TXT, UTF16BCT.TXT, UTF16BE.TXT, UTF16BJP.TXT, UTF16BKO.TXT, UTF16LE.TXT, UTF8.TXT

Installing the PDF Library and DLI

2.33

Installing the z/OS version of PDF Library on USS


Follow the steps below to install the Adobe PDF Library for OS/390 on USS. 1 Via binary ftp, transfer APDFL7.0.x.xxx.tar.gz to a Hierarchical File System (HFS) directory (e.g. /u/vol2/Datalogics). 2 From the directory, submit the command gzip -d APDFL7.0.x.xxx.tar.gz 3 Submit the command tar xvf APDFL7.0.x.xxx.tar 4 Submit the command gzip -d *.tar.gz 5 Submit the command tar xvf <filename>.tar for each of the tar files (e.g. apdflinclude.tar).

2.34

Ado be P DF L ibr a ry Ins ta ll a ti on Gui de

DLI Installation Procedure


NOTE: In most cases, the DLI Installation procedures are part of the Adobe PDF Library installation process. You may only need to follow these steps if you are installing a DLI update separate from a Library delivery. Please see APDFL installation instructions for more information on DLI installation on those platforms.

UNIX-Related Platforms
The following procedure describes how to install the Datalogics Interface (DLI) on UNIX-based platforms (e.g. AIX, HP-UX, Linux or Sun Solaris): 1 Binary-ftp the DLIxxx.tar files from the DLI folder on the product CD (or your secure ftp download account on the ftp.datalogics.com website) to the desired location. 2 Untar the files: tar -xvf <tar file> 3 Within your All directory, edit your makefile.platform to point to where the Adobe PDF Library and DLI files reside.
NOTE: The makefile.platform file covers several platforms; your section is under the specific area named by platform (e.g. sun4-solaris area).

Installing the PDF Library and DLI

2.35

Documentation Unpacking
The Adobe PDF Library and DLI documentation suite is delivered in .zip file form, to be unpacked on a Windows machine in a tree directory structure that will allow quick reference, reading and searching of the various documents. Documentation should be extracted to the same C:\Datalogics\APDFLxxx\ location as that of the code installation. Be sure to allow it to create folders (if necessary) and unpack into subfolders, so that the correct tree structure of the documentation path will be maintained. Index files suitable for Adobe Catalog search functions under Adobe Acrobat or Adobe Reader version 6 are also included; look for APDFLIndex6.pdx. Although the C:\Datalogics\APDFLxxx\ location is recommended, the documentation files may be unpacked anywhere. Be aware that unpacking in a location other than C:\Datalogics\APDFLxxx\ may require you to rebuild the APDFLIndex6.pdx file before the Catalog search utility can be used.
NOTE: The following screen illustrations show an Adobe PDF Library v7.0.1Plus installation. Installation screens for later release versions are similar.

1 The InstallShield installation procedure should have created \APDFL and \DLI folders under a C:\Datalogics\APDFLxxx\ directory path. Place the referencelibrary.zip file that you retrieved from the Datalogics website (or copied from your CD-ROM, if applicable) into the C:\Datalogics\APDFLxxx\ folder:

2.36

Ado be P DF L ibr a ry Ins ta ll a ti on Gui de

2 Unpack the file with WinZip or a comparable utility:

3 The folder names must be used when unpacking:

Installing the PDF Library and DLI

2.37

4 \Codesamples and \Documentation folders will be created as unpacking proceeds:

5 When complete, you can delete the referencelibrary.zip file:

6 Your starting point for all documentation is the referencelibrary.pdf file in this folder, which contains pointers and links to subsidiary documents and files. You can also explore the /documentation subfolder directly if desired.

2.38

Ado be P DF L ibr a ry Ins ta ll a ti on Gui de

3 Configure
Your Environment
After the Adobe

PDF Library and DLI have been installed, the

development environment must be configured before you can incorporate the toolkits into your applications.

3.1

3.2

Ado be P DF L ibr a ry Ins ta ll a ti on Gui de

Building with the Adobe PDF Library and DLI


There are some platform-specific considerations that should be made when building and linking to the Adobe PDF Library and DLI. For more information regarding how to compile and link to the Adobe PDF Library, please see the Adobe PDF Library Overview manual. Notes on some specific platforms follow below.

HP PA-RISC/64-bit
Adobe PDF Library v7.0.xPlus for HP PA-RISC/64-bit is distributed only in dynamic-library form. When building with the Library: In order to build and run sample applications in a 64-bit configuration, you must set BUILD_64_BIT = true. The LD_LIBRARY_PATH must be set for the resulting executables to locate all APDFL and DLI dynamic libraries (if necessary).

IBM AIX
Adobe PDF Library v7.0.xPlus for IBM AIX is distributed only in dynamic-library form.
NOTE: As of the Adobe PDF Library v7.0.1PlusP1d release, libstdc++ and libgcc dependencies were removed from IBM AIX, Linux and Solaris platforms (although the sample application builds still depend on them).

When building with the Library: Using either GCC or the XL C/C++ compiler in multithreaded mode to drive the linker is highly recommended; ld is not. The LIBPATH must be set for the resulting executables to locate all APDFL and DLI dynamic libraries (if necessary).

Configure Your Environment

3.3

Linux
Adobe PDF Library v7.0.xPlus for Linux is distributed in dynamic library form.
NOTE: As of the Adobe PDF Library v7.0.1PlusP1d release, libstdc++ and libgcc dependencies were removed from IBM AIX, Linux and Solaris platforms (although the sample application builds still depend on them).

When building with the Library: Using GCC to drive the linker is highly recommended; ld is not. The LD_LIBRARY_PATH must be set for the resulting executables to locate all APDFL and DLI dynamic libraries (if necessary).

MIPS32 IRIX
Adobe PDF Library v7.0.xPlus for MIPS32 IRIX is distributed in dynamic library form. When building with the Library: Tested compilers include gcc 3.2 as distributed by SGI, and a version of gcc 3.3 with POSIX threads enabled. The LD_LIBRARYN32_PATH must be set for the resulting executables to locate all APDFL dynamic libraries. Remember to include the APDFL7.0.x/Libs directory. The libraries of this release require a dynamic version of libgcc_s.so in order to function. Datalogics includes this library in the libgcc-gcc33-dynamic.tar file within the release. This tarfile creates a libgcc directory with the required runtime library, along with a symbolic link which should be preserved. These must be copied to either your APDFL7.0.x/Libs directory or (preferably) your /opt/lib32 directory on any machines which will be using the PDF Library.
NOTE: The libgcc library is built from GNU's unmodified gcc v3.3.6 source release. Upon request, Datalogics will make available to customers the source code used to build libgcc. Contact your Datalogics Support representative for more details.

3.4

Ado be P DF L ibr a ry Ins ta ll a ti on Gui de

Sun Solaris/32-bit
Adobe PDF Library v7.0.xPlus 32-bit release for Sun Solaris is distributed in dynamic library form.
NOTE: As of the Adobe PDF Library v7.0.1PlusP1d release, libstdc++ and libgcc dependencies were removed from IBM AIX, Linux and Solaris platforms (although the sample application builds still depend on them).

When building with the Library: Using GCC to drive the linker is highly recommended; ld is not. The LD_LIBRARY_PATH must be set for the resulting executables to locate all APDFL and DLI dynamic libraries (if necessary).

Sun Solaris/64-bit
Adobe PDF Library v7.0.xPlus 64-bit release for Sun Solaris is distributed in dynamic library form.
NOTE: As of the Adobe PDF Library v7.0.1PlusP1d release, libstdc++ and libgcc dependencies were removed from IBM AIX, Linux and Solaris platforms (although the sample application builds still depend on them).

When building with the Library: Using GCC to drive the linker is highly recommended; ld is not. The LD_LIBRARY_PATH must be set for the resulting executables to locate all APDFL and DLI dynamic libraries (if necessary).

Setting Environment Variables


Resources must be specified by the methods presented in the Adobe PDF Library Overview manual. It is assumed that the resource specification will point to all necessary resources for the job.

Specifying CMaps for PDWordFinder Use


In particular, you should ensure that your application can find useful CMap files whenever using PDWordFinder to extract text from a document. Especially in the case of CIDType0 fonts, a /ToUnicode

Configure Your Environment

3.5

table is not always included, and so the Adobe PDF Library should have access to the Adobe-supplied "UCS2-..." CMaps in order to achieve a conversion from a multibyte format to a Unicode one.
NOTE: Beginning with Adobe PDF Library v6.0.0Plus and DLI v3.0, the Resource folder names \Resource\CMaps and \Resource\Fonts have been renamed to the singular forms \Resource\Cmap and \Resource\Font respectively. Applications built under Adobe PDF Library v5.x or earlier which reference these folders by name must be updated for use with newer releases.

HP PA-RISC/64-bit Platform
The following environment variables must be defined prior to building applications.
NOTE: Beginning with the Adobe PDF Libary and DLI v7.x releases, ACRO_RES_DIR and PSRESOURCEPATH environment variables are no longer used or supported.

LD_LIBRARY_PATH

A colon-separated list specifying all of your library file locations; e.g.

setenv LD_LIBRARY_PATH /APDFL7.0.1/Libs:/DLI/Libs:/usr/local/lib OS Operating System; e.g. setenv OS hppahpux


CAUTION: As of Adobe PDF Library v6.1.1 and DLI v3.0.22, proper setting of the OS (Operating System) variable is now required in order to correctly build the DLI sample applications.

3.6

Ado be P DF L ibr a ry Ins ta ll a ti on Gui de

IBM AIX Platform


The following environment variables must be defined prior to building applications.
NOTE: Beginning with the Adobe PDF Libary and DLI v7.x releases, ACRO_RES_DIR and PSRESOURCEPATH environment variables are no longer used or supported.

LIBPATH

A colon-separated list specifying all of your library file locations; e.g.

setenv LIBPATH /APDFL7.0.1/Libs:/DLI/Libs:/usr/local/lib OS Operating System; e.g. setenv OS aixgcc (for gcc v3.3 compiler) setenv OS rs6000aix (for XL C/C++ VisualAge compiler)
CAUTION: As of Adobe PDF Library v6.1.1 and DLI v3.0.22, proper setting of the OS (Operating System) variable is now required in order to correctly build the DLI sample applications.

Linux Platform
The following environment variables must be defined prior to building applications.
NOTE: Beginning with the Adobe PDF Libary and DLI v7.x releases, ACRO_RES_DIR and PSRESOURCEPATH environment variables are no longer used or supported.

LD_LIBRARY_PATH

A colon-separated list specifying all of your library file locations; e.g.

setenv LD_LIBRARY_PATH /APDFL7.0.1/Libs:/DLI/Libs:/usr/local/lib OS Operating System setenv OS i80386linux


CAUTION: As of Adobe PDF Library v6.1.1 and DLI v3.0.22, proper setting of the OS (Operating System) variable is now required in order to correctly build the DLI sample applications.

Configure Your Environment

3.7

Macintosh Platform
The following environment variables must be defined prior to building applications.
NOTE: Beginning with the Adobe PDF Libary and DLI v7.x releases, ACRO_RES_DIR and PSRESOURCEPATH environment variables are no longer used or supported.

LD_LIBRARY_PATH

A colon-separated list specifying all of your library file locations; e.g.

setenv LD_LIBRARY_PATH /APDFL7.0.1/Libs:/DLI/Libs:/usr/local/lib OS Operating System setenv OS macintosh


CAUTION: As of Adobe PDF Library v6.1.1 and DLI v3.0.22, proper setting of the OS (Operating System) variable is now required in order to correctly build the DLI sample applications.

MIPS32 IRIX Platform


The following environment variables must be defined prior to building applications. LD_LIBRARYN32_PATH A colon-separated list specifying all of your library file locations; e.g.

setenv LD_LIBRARYN32_PATH /APDFL7.0.1/Libs:/usr/local/lib OS Operating System setenv OS mips32irix

3.8

Ado be P DF L ibr a ry Ins ta ll a ti on Gui de

Solaris 32-bit
The following environment variables must be defined prior to building applications.
NOTE: Beginning with the Adobe PDF Libary and DLI v7.x releases, ACRO_RES_DIR and PSRESOURCEPATH environment variables are no longer used or supported.

LD_LIBRARY_PATH

A colon-separated list specifying all of your library file locations; e.g.

setenv LD_LIBRARY_PATH /APDFL7.0.1/Libs:/DLI/Libs:/usr/local/lib OS Operating System setenv OS sparcsolaris


CAUTION: As of Adobe PDF Library v6.1.1 and DLI v3.0.22, proper setting of the OS (Operating System) variable is now required in order to correctly build the DLI sample applications.

Solaris 64-bit
The following environment variables must be defined prior to building applications.
NOTE: Beginning with the Adobe PDF Libary and DLI v7.x releases, ACRO_RES_DIR and PSRESOURCEPATH environment variables are no longer used or supported.

LD_LIBRARY_PATH

A colon-separated list specifying all of your library file locations; e.g.

setenv LD_LIBRARY_PATH /APDFL7.0.1/Libs:/DLI/Libs:/usr/local/lib OS Operating System setenv OS sparcsolaris


CAUTION: As of Adobe PDF Library v6.1.1 and DLI v3.0.22, proper setting of the OS (Operating System) variable is now required in order to correctly build the DLI sample applications.

Configure Your Environment

3.9

Windows Platforms
There are no required environment variables that must be defined prior to building applications. However, please see important details in Specifying CMaps for PDWordFinder Use on page 3.4 (preceding).

Other Platforms
Resources must be specified by the methods presented in the Adobe PDF Library Overview manual. It is assumed that the resource specification will point to all necessary resources for the job.

Building and Running Sample Jobs


Each product, Adobe PDF Library and DLI, contains a collection of sample jobs illustrating various tasks. Each sample job is contained within its own subdirectory under its respective product, such as (on Windows platforms) C:\Datalogics\APDFLxxx\APDFL\Samples\ or C:\Datalogics\APDFLxxx\DLI\Samples\.

UNIX and Windows Platforms


You can use the makefile.W32 included with each sample to build the job via the NMAKE command, or, on Windows, you can build applications via the supported development software for the Windows platforms, Microsoft Visual Studio .NET
Building via Visual Studio .NET

You can quickly open all sample applications at once via .NET Project Solution files under either Adobe PDF Library or DLI. Within the \Samples folder under each branch, look for a subfolder named \All. This will contain a Solution file covering all samples provided in that branch, for either Adobe PDF Library or DLI: C:\Datalogics\APDFLxxx\APDFL\Samples\All\all.sln (Adobe PDF Library) C:\Datalogics\APDFLxxx\DLI\Samples\All\dli_samples.sln (DLI)

3.10

Ado be P DF L ibr a ry Ins ta ll a ti on Gui de

Building via nmake

To compile and link a selected sample yourself, set your default to its subdirectory and issue the command: nmake /f makefile.W32 This will compile and link the sample in a new \Release subdirectory under the current sample location. In order to execute the sample program from the current directory, specify the path to the executable, or drop down into the \Release subdirectory to run it. Some samples include referenced files that are located in the @data directory. These samples need to be run from the original sample directory with the release path included with the executable: release\sample.exe For example, in order to run the APDFL addimage sample job you must type: release\addimage.exe as found in the C:\Datalogics\APDFLxxx\APDFL\Samples\addimage directory. The program expects the data files to be in a location relative to the sample source directory, not relative to the \Release directory.
NOTE: The DLI DLL file DLI_PDFL70.dll and other DLL files installed under DLI must be placed in a directory specified in your PATH definition in order for the sample executables to run correctly. They are initially installed in the

C:\Datalogics\APDFLxxx\DLI\Libs directory. Be sure to remove or


rename any previous copies which may be located elsewhere on your machine.

Configure Your Environment

3.11

IBM OS/390
IBM Assembler

1 Create PROD.PDFPV701.FONT.ZIP and PROD.PDFPV701.CMAP.ZIP to your specifications as uncompressed zip files. 2 From ISPF, open the library PROD.PDFPV701.ASM.JCL. 3 Open the selected member (e.g. CHKERR) and type sub at the command line.
IBM C via JCL

1 Create PROD.PDFPV701.FONT.ZIP and PROD.PDFPV701.CMAP.ZIP to your specifications as uncompressed zip files. 2 Make sure that the apdflinclude.tar.gz file was installed into your HFS directory as described in Installing the z/OS version of PDF Library on MVS on page 2.21. 3 From ISPF, open the library PROD.PDFPV701.C.OPTS. 4 In members PDFL and DLI, enter the location where the Include libraries were installed in Step 2. 5 6 From ISPF, open the library PROD.PDFPV701.C.JCL, or, for EBCDIC samples, PROD.PDFPV701.EBC.C.JCL. Open the selected member (e.g. HELOWRLD) and type sub at the command line.

IBM C via USS

1 Create APDFL7.0.5/Resource/Font.zip and APDFL7.0.5/Resource/CMap.zip to your specifications as uncompressed zip files. 2 Set the LIBPATH variable: export LIBPATH=/usr/local/lib:/usr/lib:/lib:/u/vol2/Datalogics/APDFL7.0.5/ Libs:/u/vol2/Datalogics/DLI/Lib 3 To build and run all the APDFL samples, issue a gmake command from the directory APDFL/Samples/All (or APDFL/EBCDICSamples/All). 4 To build and run all the DLI samples, issue a gmake command from the directory DLI/Samples/All (or /EBCDICSamples/All). 5 To build and run individual samples, go to the selected directory (e.g. helowrld) and type gmake. Then type ./helowrld 2>&1|iconv -f ISO8859-1 -t IBM-1047 to run the sample.
NOTE: When using EBCDIC samples, the redirection 2>&1|iconv -f ISO8859-1 -t IBM-1047 is not needed.

3.12

Ado be P DF L ibr a ry Ins ta ll a ti on Gui de

AS/400
IBM C/C++

1 Add the AS400 library which contains the distribution to your library list (e.g. ADDLIBLE PDFL701P1A), then change your current library to that same library (e.g. CHGCURLIB PDFL701P1A). 2 Start the Programming Development Manager via STRPDM. Select option 1, and enter 12 to work with the library you selected in the previous step. 3 Go into the PROC source physical file (via 12) and compile (via 14) the CL script CMPLALL701:

This will compile all the CL scripts for each sample.

Configure Your Environment

3.13

4 Now go back one screen, and enter 16 at CMPLALL701:

This will create all of the compiles and linkings for the individual samples. 5 To build the HeloWrld executable, enter 16 on HELOWRLDB and press Enter:

This creates HELOWRLD *PGM.

3.14

Ado be P DF L ibr a ry Ins ta ll a ti on Gui de

6 To run Helowrld *PGM, enter 16 on HELOWRLD (not HELOWRLDB), and press Enter:

Output will appear on the IFS in /datalogics/APDFLxxx/samples/helowrld.


Running Multithreaded Samples via AS/400

For running multithreaded sample applications, the OS400 JOB running the application must be initialized by the system in a mode to support threads. In the multithread-capable sample applications provided by the Library, this is done by adding an ALWMLTTHD (Allow Multithreaded) option when issuing the SBMJOB (Submit Job) command:

Configure Your Environment

3.15

A confirmation message will appear when the job is submitted:

For example, to run MTTEXTEXT (the multithreaded MTTextExtract text extraction sample application), you should issue the command as SBMJOB CMD(CALL MTTEXTEXT) ALWMLTTHD(*YES) The other multithreaded samples run similarly.
Working and Output Directories

Output for the MTSerialNums and MTInMemFS sample applications will appear in their respective directories under APDFL7.0.1/Samples. The output for MTTextExtract will be the .pdf.txt files in the @Data area. To specify the working directory where the sample is running, issue the WRKLNK command with the path to the desired location; e.g. WRKLNK ('/datalogics/APDFL7.0.1/Samples/PDFLSnippetRunner').

3.16

Ado be P DF L ibr a ry Ins ta ll a ti on Gui de

Unresolved Symbol References on UNIX


Adobe distributes the Adobe PDF Library on several UNIX platforms (AIX, Linux and Sun Solaris) built with GCC. Some developers have experienced unresolved symbol references when linking the Library into applications built with non-GCC C and C++ compilers. To resolve these references, if problems occur: 1 Obtain the GCC runtime library for the platform in question. 2 Extract the individual objects from the GCC runtime: ar -x <libgcc_runtime_library_name> 3 Build a helper library consisting of the objects which contain the symbols with unresolved references. Those which have been incorporated successfully to date include: bsearch.o ctime.o _op_delete.o _new_handler.o _op_new.o frame.o tinfo.o _eh.o _dummy.o exception.o _pure.o _op_vnew.o vdel.o _eprintf.o tinfo2.o
NOTE: This is a representative list only; the actual list of unresolved references may vary.

4 Include the helper library in the application build.

Configure Your Environment

3.17

Accessing Font Information


As of Adobe PDF Library v7.x, the following files are distributed with the release: Adobe Ming Standard Light Adobe Myungjo Standard Medium Adobe Pi Standard Adobe Song Standard Light Courier Standard Courier Standard Bold Courier Standard Bold Oblique Courier Standard Oblique Kozuka Gothic Pro Medium Kozuka Mincho Pro-VI Regular Symbol Adobe Sans MultiMaster Adobe Serif MultiMaster Additional fonts must be licensed or purchased separately. Once they are installed on your machine, the Adobe PDF Library should find them automatically, and make use of them as needed from that point on. You may need to define or update environment variables on your system to ensure that the font resources are found by your application; see Setting Environment Variables on page 3.4 for more details. Running a test composition to embed your new fonts in an output PDF document is a good way to ensure that your resources are available to your application.

Embedding and Subsetting Fonts


Embedding fonts in your output PDF documents will ensure that the document can be viewed and printed in its original form by any recipient later on, since its required resources will be included in the file. PDF files that do not have embedded fonts will have smaller file sizes, but those fonts will be needed again later for viewing or printing the document. At that point, they must then be either supplied from an external source, or simulated via MultiMaster fonts if the specified font is not available. Adobe and Datalogics recommend that applications embed and subset all fonts wherever possible. Subsetting those fonts will minimize the space required, and thus the resulting file size, by including only those glyphs (characters) which are actually used in the document. Subsetting is not recommended if the file may be need to be edited later by Adobe Acrobat or a similar utility, since any new text introduced in revisions may need other glyphs for that font, beyond those that were provided in the subset. See the accompanying Adobe PDF Reference Manual for more information.

3.18

Ado be P DF L ibr a ry Ins ta ll a ti on Gui de

Font Embedding Restrictions


Licensed fonts may carry restrictions preventing them from being embedded in a new document. The Adobe PDF Library will return an exception if you attempt to embed a font whose license does not permit this operation. Contact your font provider for assistance if this occurs. This does not mean that you cannot use this font for creating a PDF document, but the resulting file can only reference the font, not embed it within the document. Viewing the document on another machine will require that font to be available on that machine for proper viewing and printing, or else Adobe Acrobat or Adobe Reader will attempt to simulate its appearance with a MultiMaster font. For elaborate, stylized typefaces, this substitution may not work very well; for Symbolic fonts, it can be impossible. On Windows platforms, a free Font Properties Extension utility is available from Microsoft at http:// www.microsoft.com/typography/FreeToolsOverview.mspx which enables you to inspect your fonts for restrictions such as those before you attempt to create documents. In the screenshots below, we can see by using the Microsoft Font Properties Extension that the Marlett font (left) can be embedded in an output PDF document; the Mistral font (right) cannot: Font Property Embedding Capabilities

Configure Your Environment

3.19

Using z/OS Fonts in Zip Files


One feature now available in Adobe PDF Library v7.0 releases (or higher) on the z/OS platform is the ability to keep font resources in Zip files. This includes both font files and CMap files. Placing the fonts into a zip file has several advantages, mostly related to running in z/OS: The fonts do not have to be placed into the HFS file system. There is improved ease of management over previous solutions for font files on z/OS. Simply create Zip files with the appropriate resources in them, and upload them to the mainframe. Commonly-available tools are used to create the files. The Zip file is opened once when first used, and held open until the end of the job, avoiding expensive file-open operations on z/OS. A special feature permits the AdobeFnt09.lst file to be added to the file, provided it is writable. One disadvantage to this approach is that access to the Zip file is achieved using normal file input/output operations. Access to font files in normal directories (including HFS on z/OS) is done using mmap, which is much more efficient.

Specifying a Zip file to PDFLInit


Simply specify the name of the Zip file instead of a directory name. Access to the files within the Zip file is handled automatically. On z/OS, in batch, use a DDname of the form *DD:FILE or DD:FILE, or a dataset name in the form // PATH.TO.FILE.ZIP. A Zip file works like a directory would, with the following consequences: It is better to put CMap files in a separate Zip file, listing it after the fonts, as is often done with resource directories. Fonts are drawn from the first Zip file in which they are found. In other words, the searching order for Zip files is the same for directories. Directories and Zip files may be intermixed freely on the PDFLInit() call. AdobeFnt.lst files are stored individually in each Zip file, just as they are in directories.

3.20

Ado be P DF L ibr a ry Ins ta ll a ti on Gui de

File allocation in a dataset


Fonts in an OS dataset must have a record format of FB to work correctly. Record formats VB and U may only be used if the environment variable _EDC_BYTE_SEEK is set to Y. (
NOTE: The effect of this option on performance or other functions of the library has not been fully tested.

In USS, an environment variable is set with the setenv (csh) or export (bash) commands. Alternatively, the ENVAR run-time option may be used. The USS cp command creates VB record format datasets by default when copying to a dataset. A dataset may be preallocated with the desired attributes. The FTP server creates FB record format datasets by default.

Transferring files
Be sure to use ftp for transfers, specifying BINary mode before issuing the put command. You cannot use scp for file transfers, as it appears to convert files from ASCII to EBCDIC by default; resulting in corrupted ZIP files.

Performance
For best performance, the contents of the Zip file should be uncompressed. This has several advantages: The host computer does not have to use CPU cycles to decompress the font. The Adobe PDF Library does not have to read the entire font into memory to access it randomly. This reduces time and memory costs, especially when gathering information from a Zip file with many and/ or large fonts. For example, using the Info-ZIP zip program commonly found on UNIX installations, specify the -0 (zero) flag to avoid compression. A sample command to create a Zip file from a Font subdirectory would look like this: $ (cd Font && zip -r -0 ../Font.zip *)

Configure Your Environment

3.21

Creating uncompressed Zip files in WinZip

To create a Zip file with uncompressed members in WinZip: 1 Click the Add button to add members to the Zip file portion of the WinZip Add window:

2 Change the Compression option in the Add window to None.

3 Use the Add window to select files to add to the archive. 4 When finished selecting files, click the Add button.

Cache File Usage


The AdobeFnt.lst cache file (its specific name ends in a number which varies from one Library release to the next, such as AdobeFnt09.lst) is the Librarys own compilation of available font resources, appended to the Zip file the first time it is read, provided that the Zip file is writable. This cache file prevents having to read every font to find out its name and other basic information every time the application is invoked. The AdobeFnt.lst file is only recompiled if the application finds that it is not the most recent file in the local directory. To create this cache file, run a dummy job (simply calling PDFLInit() and PDFLTerm() will suffice) with DISP=MOD. At the end of the process, a new cache file should be created. Subsequent jobs may be run with DISP=SHR.

3.22

Ado be P DF L ibr a ry Ins ta ll a ti on Gui de

Limitations
When creating encodings for multibyte fonts, the Adobe PDF Library reads CMap files directly; it does not currently access CMaps in Zip files. Concatenations should not be used on DD cards used for Zip files.
CAUTION: There is currently no locking mechanism for Zip files other than that offered by the DISP parameter of the DD card in batch. Care should be taken to ensure that only one job has write access to a Zip file at a time. In batch, this is supported by using DDnames and DISP=SHR or DISP=MOD.

Index
A Accessing Font Information 3.17 ACRO_RES_DIR No longer supported 1.7, 3.5, 3.6, 3.7, 3.8 Adobe Acrobat 1.4 Adobe PDF Library Applications Programming Interface (API) manual 1.3 Document Conventions 1.4 Adobe Reader 1.3, 1.4 AdobeFnt.lst file on z/OS systems 3.21 ALWMLTTHD (Allow Multithreaded) 3.14 APDFLIndex6.pdx 2.35 Manual 1.5 Errata file 1.5 SnippetRunner Cookbook 1.6 Datalogics Adobe PDF Library and DLI Installation Guide 1.4 Adobe PDF Library Developer Overview 1.4 DLI Implementation and Reference Guide 1.4 Java Interface User Guide 1.4 Index files 2.35 Unpacking 2.35 dummy.o 3.16

E EDC_BYTE_SEEK Use on z/OS 3.20 eh.o 3.16 Embedding and Subsetting Fonts 3.17 ENVAR Use on z/OS 3.20 Environment Configuration 3.1 Environment Variables, Setting LD_LIBRARY_PATH on HP PA-RISC/64-bit 3.5 on Linux 3.6 on Macintosh 3.7 on Solaris 32-bit 3.8 64-bit 3.8 LD_LIBRARYN32_PATH on MIPS32 IRIX 3.7 LIBPATH on IBM AIX 3.6 OS Caution on required definition 3.5, 3.6, 3.7, 3.8 on HP PA-RISC/64-bit 3.5 on IBM AIX 3.6 on Linux 3.6 on Macintosh 3.7 on MIPS32 IRIX 3.7 on Solaris 32-bit 3.8 64-bit 3.8 Platforms HP PA-RISC/64-bit 3.5

B bsearch.o 3.16

C Cautions CMaps and Fonts folders now renamed to singular form 3.5 No locking mechanism for Zip files on z/OS 3.22 Proper OS definition now required for DLI sample builds 3.5, 3.6, 3.7, 3.8 CIDType0 Fonts Reliance on ACRO_RES_DIR definition with PDWordFinder 3.4 CMap Files Reliance on ACRO_RES_DIR definition with PDWordFinder 3.4 Compilers, Supported 2.2 Conventions, Document 1.4 ctime.o 3.16

D Datalogics ftp site 2.3, 2.34 Document Conventions 1.4 Documentation Adobe 3D Annotations Tutorial 1.6 Acrobat and PDF Library API Overview 1.5 Acrobat and PDF Library API Reference 1.5 Adobe PDF Library Overview 1.5 Portable Document Format Reference

I.2

Adobe PDF Library Installation Guide

IBM AIX 3.6 Linux 3.6 Macintosh 3.7 MIPS32 IRIX 3.7 Other Platforms 3.9 Solaris 32-bit 3.8 64-bit 3.8 Windows 3.9 eprintf.o 3.16 exception.o 3.16

F Font Embedding Restrictions 3.18 Font Information, Accessing 3.17 Standard fonts 3.17 Fonts Embedding Restrictions 3.18 Microsoft Font Properties Extension 3.18 Subsetting and Embedding 3.17 frame.o 3.16 ftp Datalogics download site 2.3, 2.34

AIX 2.2 AS/400 2.2 OS/390 MVS 2.2 USS 2.2 ICU (International Components for Unicode) Compatibility with DLI 2.3 Index files (for documentation) 2.35 Info-ZIP 3.20 Installation Procedures Documentation 2.2 IBM AS/400 2.17 OS/390 2.21 MVS 2.17, 2.21 For DSS 2.21 JCL Dataset File List 2.31 Via JCL 2.29 USS 2.33 UNIX 2.11 DLI for UNIX 2.34 Windows 2.3 DLL File Placement 2.10 Documentation 2.35 Repetitive Installations 2.9 Selecting Features 2.10 Supported Platforms and Compilers 2.2

G GCC Use for unresolved references 3.16 Use in Dynamic Building 3.2, 3.3, 3.4 Use on UNIX Platforms 3.16 L ld Use in Dynamic Building 3.2, 3.3, 3.4 LD_LIBRARY_PATH 3.2, 3.3, 3.4 on HP PA-RISC/64-bit 3.5 on Linux 3.6 on Macintosh 3.7 on Solaris 32-bit 3.8 64-bit 3.8 LD_LIBRARYN32_PATH 3.3 on MIPS32 IRIX 3.7 libgcc Dependency removed 1.7, 3.2, 3.3, 3.4 libgcc_s.so In MIPS32 IRIX release 3.3 LIBPATH 3.2 on IBM AIX 3.6 libstdc++ Dependency removed 1.7, 3.2, 3.3, 3.4 Linking on HP PA-RISC/64-bit 3.2 on IBM

H Helper Library 3.16 How This Book is Organized 1.3 HP Linking on PA-RISC/64-bit 3.2 Setting Environment Variables PA-RISC/64-bit 3.5 Supported Versions PA-RISC/64-bit 2.2

I IBM Linking on AIX 3.2 Setting Environment Variables AIX 3.6 Supported Versions

Index

I.3

AIX 3.2 on Linux 3.3 on MIPS32 IRIX 3.3 on Sun Solaris 32-bit 3.4 64-bit 3.4 Linux Linking on 3.3 Setting Environment Variables 3.6 Supported Versions 2.2

M Macintosh Setting Environment Variables 3.7 Supported Versions 2.2 Microsoft Font Properties Extension 3.18 MIPS32 IRIX Linking on 3.3 Setting Environment Variables 3.7 Supported Versions 2.2 mmap Role in font file access on z/OS 3.19 Multibyte text Converting PDWordFinder output to Unicode 3.5

Number of release objects may change without notice 2.18 PDF Library Supplement now combined into Acrobat and PDF Library API Reference 1.6 PDF Reference Manual errata file available for download 1.5 Performance impact of _EDC_BYTE_SEEK not fully tested 3.20 Redirection command not needed for EBCDIC samples 3.11 Unresolved references in a given release may vary 3.16 Verify location of Dli_dll.dll and related files within PATH 3.10

O op_delete.o 3.16 op_new.o 3.16 op_vnew.o 3.16 OS Caution on required definition 3.5, 3.6, 3.7, 3.8 on HP PA-RISC/64-bit 3.5 on IBM AIX 3.6 on Linux 3.6 on Macintosh 3.7 on MIPS32 IRIX 3.7 on Solaris 32-bit 3.8 64-bit 3.8

N new_handler.o 3.16 Notes ACRO_RES_DIR and PSRESOURCEPATH no longer supported 3.5, 3.6, 3.7, 3.8 ASN membership may be required for Adobe website access 1.5 Check size of .xmit file on OS/390 2.22, 2.24 Datalogics manuals apply to all platforms 1.2 Dataset must be allocated prior to restoring on OS/390 2.28 DLI installation usually combined with Library 2.34 Ensure removal of old DLL files 2.6, 2.8 Installation screen illustrations show v7.0.1Plus 2.11, 2.35 Installation screen illustrations show v7.0.5PlusP1c 2.3 InstallShield prohibits duplicate current releases 2.9 libstdc++ and libgcc Dependencies Removed 3.2, 3.3, 3.4 makefile.platform file covers multiple platform installations 2.34 MIPS32 IRIX libgcc source code available on request 3.3

P PDF File format 1.4 PDWordFinder Reliance on ACRO_RES_DIR definition 3.4 Platforms, Supported 2.2 Plus suffix, meaning of 1.6 Portable Document Format Reference Manual 1.4 PSRESOURCEPATH No longer supported 1.7, 3.5, 3.6, 3.7, 3.8 pure.o 3.16

R readme.txt 1.6 Related Documentation 1.4 Release Notes 1.6

I.4

Adobe PDF Library Installation Guide

Resources Microsoft Microsoft Font Properties Extension 3.18

W What You Should Know 1.3 Whats New in Previous Releases 7.0.0Plus DLI Version Numbering Upgrade 1.7 Termination of Support for ACRO_RES_DIR and PSRESOURCEPATH 1.7 Whats New in This Release libstdc++ and libgcc Dependencies Removed 1.7 New IBM AS/400 Release 1.7 New MIPS32 IRIX Release 1.7 Overview 1.6 Windows (Intel) Setting Environment Variables 3.9 Supported Versions 2.2 WinZip Creating uncompressed font file with 3.21 Cache File Creation on z/OS 3.21 Cache File Usage on z/OS 3.21 Limitations 3.22

S Samples Compiling and Linking IBM Assembler 3.11 C via JCL 3.11 via USS 3.11 C/C++ via AS/400 3.12 Multithreaded Samples 3.14 Working and Output Directories 3.15 UNIX and Windows via Makefiles 3.9 via nmake 3.10 via VS .NET 3.9 Location 3.9 Project Solution files 3.9 SBMJOB (Submit Job) 3.14 Subsetting Fonts, Embedding and 3.17 Sun Solaris Linking on 32-bit 3.4 64-bit 3.4 Setting Environment Variables 32-bit 3.8 64-bit 3.8 Supported Versions 32-bit 2.2 64-bit 2.2 Symbols, Unresolved 3.16

X XL C/C++ Use in Dynamic Building 3.2

T tinfo.o 3.16 tinfo2.o 3.16 ToUnicode Table Use in CIDType0 Fonts 3.4

U Unicode Converting PDWordFinder output from multibyte 3.5 Unresolved Symbols 3.16

V vdel.o 3.16