Install
Install
Install
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.1
3.1
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
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.
1.3
the PDF Library and DLI" provides installation procedures for Adobe
environment after installation and before incorporating the Library into your applications.
1.4
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.
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
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.
1.7
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
2 Installing
the PDF Library and DLI
This chapter covers installation procedures and lists supported platforms and compilers.
2.1
2.2
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
2.3
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.
2.4
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
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.
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
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.
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
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.
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
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.
2.13
2.14
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:
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
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.
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
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:
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
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.
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:
2.22
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.
2.23
2.24
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.
2.25
2.26
It should have the following characteristics: Record Format U Record Length 0 Block Size 19069
2.27
At the TSO command prompt, enter: RECEIVE INDATASET('PDFPvxxxXMIT') where vxxx is the version number and the letter of release.
2.28
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.
2.29
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
2.31
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
2.32
Dataset/Filenames
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
2.33
2.34
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).
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
2.37
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
3 Configure
Your Environment
After the Adobe
development environment must be configured before you can incorporate the toolkits into your applications.
3.1
3.2
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).
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
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).
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
3.6
LIBPATH
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
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
3.8
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
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
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.
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
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
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.
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
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:
3.13
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:
3.14
6 To run Helowrld *PGM, enter 16 on HELOWRLD (not HELOWRLDB), and press Enter:
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:
3.15
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
3.17
3.18
3.19
3.20
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 *)
3.21
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:
3 Use the Add window to select files to add to the archive. 4 When finished selecting files, click the Add button.
3.22
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
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
I.4
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
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