pdfHarmony Users Guide

Usage: pdfHarmony [options] inPDFFile1 [inPDFFile2 ...]

-verifyonly          : Verify Only, search for corrupt files without creating any new files
-o <string>          : Output directory name or PDF filename

-verifypage          : Verify page drawing
-rewritepage         : Rewrite page contents to cleanup at the page content level
-removerotation      : Remove rotation from all pages
-retaincreator       : Retain original document creator

Document Save, Optimize & Compression Options

-pdfa                : Support PDF/A documents
-flate               : Encode any non-encoded streams using Flate compression
-rascii              : Remove ASCII85 filters from all streams
-nolzw               : Replace LZW encoded streams with Flate encoding

-optxobj             : Merge identical XObjects and Images
-optcontent          : Optimize common sequences in page content
-optfonts            : Merge identical font descriptors and encodings

-optimize            : Combine -flate, -rascii, -nolzw, -optxobj, -optcontent and -optfonts

-nocomp              : Do not compress using Object Streams; compatible with all versions of Acrobat
-comp                : Compress using Object Streams; Acrobat 6 and later
-cstruct             : Compress logical structure

                       Note: -nocomp, -comp and -cstruct are mutually exclusive; these 
                       options can all be off, but only one can be used at a time.

-xreadonly           : Suppresses the generation of padding in the XMP Metadata
-xpadding <int>      : XMP Metadata padding bytes. Default is 2048

-iso32000            : Set file for ISO 32000 compliance (PDF 1.7)

-w                   : Save the output as a linearized file
-wauto               : Auto-detect linearized and save linearized; otherwise save normal
-wforms              : Extends "-w" and "-wauto" to linearize Acrobat Forms; 
                       default is not to linearize forms; requires "-w" or "-wauto"

-nomod               : Retain current file modification date
-nosign              : Ignore Digital Signatures; default is to incrementally save files with 
                       digital signatures.

Document Metadata

-title <string>      : Document title
-author <string>     : Author of the document
-subject <string>    : Subject of the document
-keyword <string>    : Keywords associated with the document ( separated by commas )
-addinfo             : Add the new information to any existing in the file.
-custom <string>     : Custom document information ( -custom "name,value"; name and value are separated 
                       by a comma; this option may be repeated. )

Document Open & Layout Options

-pageMode <string>   : Set the document's Page Mode 
                       ( DontCare | UseNone | UseThumbs | UseBookmarks | Fullscreen | UseOC | UseAttachments )

-layout <string>     : Set the document's layout  
                       ( single | oneColumn | twoColLeft | twoColRight | twoPageLeft | twoPageRight )

-openAction <string> : Set the document's Open Action 
                       ( FitPage | FitWidth | FitHeight | FitBoundingBox ) 

-openToPage <int>    : Open the document to the given page number.

-hideToolbar         : Hide the toolbar upon opening the document.
-hideMenubar         : Hide the menubar upon opening the document.
-hideWinUI           : Hide scrollbars and other controls upon opening the document.
-fitWin              : Resize the window to the initial page.
-centerWin           : Center the window on the screen.
-showTitle           : Display document title in windows title bar.

-LeftToRight         : Left to Right reading order used to determine relative position of pages for 
                       side by side display.
-RightToLeft         : Right to Left reading order; includes vertical writing systems like Chinese, 
                       Japanese, and Korean.

Bookmarks

-openBookmarks       : Open all bookmarks.
-closeBookmarks      : Close all bookmarks.
-openLevel <int>     : Open all bookmarks up to and including this level.
-removeBookmarks     : Remove all bookmarks.

Annotations & Form Fields

-removeAnnots        : Remove all Annotations including notes, highlights, form fields, etc.
-removeFields        : Remove all form fields.

Watched Folders

-watch <string>      : Path to watched folder base directory
-watchin <string>    : Path to input watched folder; optional
-watchout <string>   : Path to output of watched folder; optional

-d <string>          : Owner password to open this document
-l <string>          : Write progress to the given log file name
-p                   : Write progress information to diagnostics
-html <string>       : Output results to HTML file.
-htmlurl <string>    : Specify path to server hosting HTML support files.
-v                   : Print version information
-r <string>          : pdfHarmony serial number
-h                   : Show help
-help                : Show help

Introduction

pdfHarmony is a key resource for performing process quality control in mission-critical applications. The software analyzes PDF files, identifies and repairs corrupt/malformed PDF files

Leveraging Adobe Systems’s own PDF Library, pdfHarmony offers positive identification in high-volume settings of any PDF page that stops Adobe Reader®, as well as recovery and repair of many otherwise broken PDF files.

Adobe Acrobat can open the vast majority of PDFs, and so can pdfHarmony. For these files, pdfHarmony optimizes the file structure, reduces the file size without affecting page content, and returns an authentic Adobe PDF file, fully compliant with ISO 32000, the international standard for PDF.

Technical Introduction

pdfHarmony leverages Adobe’s PDF library to run a series of processes that convert PDFs to Adobe PDF. These processes include:

• detecting and reporting damaged or malformed PDFs that can’t be opened with Adobe Acrobat or Reader
• detecting and reporting page rendering errors
• repairing and saving PDFs
• consolidates identical fonts, font subsets, and XObjects to reduce file size without altering objects on the page
• converting input PDFs into authentic Adobe PDFs
• ensuring PDFs are ISO 32000 compliant

pdfHarmony operates on recursive folders, watched folders, or from the command line. It sets document information fields and generates XMP metadata with or without modifying the creation date. In addition, pdfHarmony sets PDF open options that control page and layout modes, including open actions, toolbar, menu and bookmark states.

Results are captured in a log file and may be summarized in an HTML report.

User Guide Conventions

This User Guide uses certain styles of text to indicate different things throughout the documentation. The following is a description of these styles:

• Command Line user input:

pdfHarmony -p -optimize -o c:\Appligent\pdfHarmony\output.pdf c:\Appligent\pdfHarmony\input.pdf

• Cross Reference to other locations in the documentation: Command Line Option Reference

• Code snippets: begin_message

Introduction

pdfHarmony is an application that brings a new sense of security and reliability to electronic document workflows because it can identify “broken” files and pages just like Adobe® Acrobat®. If Adobe Acrobat can resolve the problem, then so can pdfHarmony.

Memory Requirements

Minimum free memory available to run the application: 512 MBytes

Windows Installation

Windows installation is handled by the installer and does not require any special handling.

Unix Installation

Setting environmental variables ( All Unix Platforms )

In this release, there are two additional environmental variables that need to be set for pdfHarmony on all UNIX platforms. If you run pdfHarmony from the pdfharmony script created during installation, these environmental variables will be set by the script. If you run pdfharmonyapp directly, you will need to set these environmental variables to run pdfHarmony. Once pdfHarmony is installed, you can view the variables needed by looking at the pdfharmony script created by the installer.

Setting the Appligent home directory ( All Unix Platforms )

The environmental variable that stores the location of the Appligent home directory is APPLIGENT_HOME. The default location for the Appligent home directory is /usr/local/appligent. The Appligent home directory contains the library files and resources needed to run pdfHarmony. It also contains license information for pdfHarmony.

Example

export APPLIGENT_HOME=/usr/local/appligent

Setting the APDFL library path ( All Unix except AIX )

The APDFL library path must be added to the LD_LIBRARY_PATH variable. The APDFL library path is located in a subdirectory of the APPLIGENT_HOME directory.
The path should be set to ${APPLIGENT_HOME}/APDFLX.X.X/Libs

Example

export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${APPLIGENT_HOME}/APDFLX.X.X/Libs

Setting the APDFL library path ( AIX Only )

The APDFL library path for AIX must be added to the LIBPATH variable. The APDFL library path is located in a subdirectory of the APPLIGENT_HOME directory.
The path should be set to ${APPLIGENT_HOME}/APDFLX.X.X/Libs.

Example

export LIBPATH=${LIBPATH}:${APPLIGENT_HOME}/APDFLX.X.X/Libs

Supported Platforms

Windows: 7 & above
AIX: 5.2 & above
Linux:  32 & 64 bit
Solaris: 10

Introduction

This chapter tells you what you need to know to get started with pdfHarmony…

you will learn:

• The basic structure of  pdfHarmony commands
• How to get product information about your installation of pdfHarmony

pdfHarmony Command Basics

All pdfHarmony commands that you run from the command line start with the pdfharmony command name. The command name is followed by one or more options, which begin with a dash. Commands that you use to obtain information about a PDF document must also include an input file specification. For example, the following command instructs pdfHarmony to optimize the PDF file:

$pdfharmony -optimize -o pathname\output.pdf  pathname\myfile.pdf

Displaying the Product Version Number

It is a good idea to test your installation of pdfHarmony by displaying the product version number. You will also need this number if you ever contact Appligent’s Customer Support with a question.

Command

$pdfharmony -v

Result

The following listing is typical of the output you would receive. In addition to the product version number, it contains the release date and registration number.  It also indicates that the registration number is valid.

Typical listing produced by -v option

# Copyright XXXX by Appligent, Inc.  http://www.appligent.com
# Written by Mark Gavin
# Version X.X, Build Date XXXX, Library Version X.X.X
# Serial Number XXXX-XXXX-XXXX-XXXX-XXXX-XXXX
# License is valid.

Displaying Product Usage Information

If you have a question about the command syntax or a command option, you can get help by displaying product usage information.

Command

$pdfharmony -h

Typical listing produced by -h or -help option

Usage: pdfHarmony [options] inPDFFile1 [inPDFFile2 …]

Using Command-line Options

Command-line options are used in all Appligent Document Solutions server applications. The tables below shows command-line options for pdfHarmony. The following is an example of command syntax for pdfHarmony:

pdfharmony [options] inPDFFile1 [inPDFFile2]

Document Save and Optimize Options

Document Metadata Options

Document Open and Layout Options

Bookmarks, Annotations and Form Fields Options

Watched Folders Options

General Options

Notes on options

If -hideWinUI is on the command line, then pageMode is ignored.

If you are running pdfHarmony on a file that contains form fields and you want the output to be linearized, you must have both -wforms and -w on the command line. Running with -w alone does not linearize output files that contain active form fields.

The -html reporting option cannot be used with watched folders.

A note on using -p and -l <logfile> together

As outlined in the above sections the -p option gives you progress messages on your screen and the -l <logfile> option writes error messages to a file if errors occur. The table below provides more detail on using these options alone or together.

l	p	errors	Result
			Nothing will be written to the screen or to the log file you specify
			Progress message will be written to the screen and pdfHarmony.log
			Progress messages will be written to the screen and to the log file you specify
			A pdfHarmony.log file will be created with the errors in your working directory
			Errors will be written to the log file you specify
			Errors will be written to pdfHarmony.log and your screen
			Both progress and error messages will be written to the screen and to the log file you specify

Therefore, -l <logfile> used on its own will only go into action if there are errors. With -p and -l <logfile> combined, you will get a text file with full details on pdfHarmony operations whether there are errors or not.

Sample pdfHarmony Commands

To optimize a PDF file:

pdfharmony -p -optimize -o output.pdf input.pdf

To optimize multiple files:

pdfharmony -p -optimize -o OutputDir input.pdf input2.pdf

To set document properties:

pdfharmony -p -subject pdfHarmony -author "Jane Smith" -title "Testing pdfHarmony" -o output2.pdf input.pdf

Introduction

pdfHarmony is a command-line application. If you are used to the Microsoft Windows  operating system, you may not be familiar with running command-line tools. This section shows you all you need to get started.

• Windows tells you how to use pdfHarmony on Windows.
  Note: You can refer to the Getting Started With Command Line Applications for additional information on using command-line applications.

Windows

To run pdfHarmony in Windows, you need to open a Command Prompt window.

In Windows :

• Click Start > Programs > Accessories > Command Prompt

The Command Prompt window opens.

Some basic commands

At the command prompt, you type each command, and press the Enter key to execute it. You can use the mouse to select text to copy or cut to the clipboard, but you cannot position the cursor with it. The command line is completely keyboard driven. Navigation keys are shown below:

In addition to running programs, you have many commands to navigate and maintain the system. Two important ones are cd and dir.

Changing directories

Use the cd command to change directories. For example, to change to the directory that pdfHarmony is located in, type:

C:\>cd \Appligent\pdfHarmony\

The command prompt changes to:

C:\Appligent\pdfHarmony>

to show you where you are.

To move back one level, use the shortcut of two periods (..)

C:\Appligent\pdfHarmony>cd..

Don’t forget to press the Enter key after every command. You will now be in this directory:

C:\Appligent>

Move back to pdfHarmony:

C:\Appligent>cd pdfHarmony

Listing the contents of a directory

Use the dir command to list the contents of a directory:

C:\Appligent\pdfHarmony>dir

The computer responds with a listing of all the contents of the pdfHarmony directory.

If the directory contents fly by too fast to read, do this:

C:\Appligent\pdfHarmony>dir /p

The /p switch tells DOS to display one page at a time. Press the Enter key to see the next page.

To see the contents of all the subdirectories at the same time, type:

C:\Appligent\pdfHarmony>dir /s

This displays the contents of pdfHarmony and all the subdirectories under it.

Running pdfHarmony

To run pdfHarmony, type the commands on the command line as shown in other sections of this manual and press Enter.  A simple command would be:

c:\Appligent\pdfHarmony\pdfharmony [options] -o c:\Appligent\pdfHarmony\output.pdf c:\Appligent\pdfHarmony\input.pdf

Now, refer to the rest of this User Guide for details about using pdfHarmony.

Introduction

This chapter describes what you can do if you do not get the results you expect when you run pdfHarmony. This troubleshooting checklist describes common problems. It is the first place to look for a possible solution to your problem.

Reviewing the Troubleshooting Checklist

Are you trying to retrieve information from one or more encrypted files?

You must specify the -d option, followed by a User password, as in the following example. (An Owner password will not work.)

You can only specify one User password. Therefore, all of the encrypted files you include on the command line must have the same User password. If you want to retrieve information from encrypted files that have different User passwords, run a separate command for each User password.

Are you using any options that require a file name (-o, -l)?

The file name must immediately follow the option, as in the following examples:

-o C:\Appligent\pdfHarmony\samples\myoutput.pdf

-l /Appligent/pdfHarmony/mylogfile.txt

If a text string other than a file name follows the option, pdfHarmony will recognize that text string as the file name.

Did you receive an error “this file cannot be found”?

You may not have provided the correct path for all files or you may have misspelled a file or directory name.

Is each input file a PDF document?

pdfHarmony can only open PDF files. If you are using wildcards, include the .pdf suffix (for example, *.pdf) to help prevent you from accidentally attempting to open a non-PDF file.

Are you using pdfHarmony in a script?

Use full path names for all files and applications accessed from within the script. If you cannot get your script to work, make sure that you can run pdfHarmony from a command line.

E-mail

You can contact support directly by sending an e-mail to support@appligent.com. Support e-mails are answered within one business day during the normal business hours listed below.  

Telephone & Fax

• Telephone: +1 610 284 4006
• Fax: +1 610 284 4233

To better serve you, please call us during our normal business hours, Monday - Friday, 8:00 am - 5:00 pm U.S. EST/EDT.

A member of our friendly, knowledgeable support staff will reply as soon as possible, generally within one business day.

International Support

Customers from locations outside the United States, including Germany, United Kingdom, Canada and Australia can contact us directly or connect with one of our many resellers.

When contacting support please provide the following information:

• Name of the Product
• Product Version Number
• Operating System
• Your Name
• Company Name
• Your Email Address
• Your Phone Number
• Product Registration Number
• Any files to help us reproduce your problem (if needed)

New Features – pdfHarmony 2.0

-optimize – For document optimization, use -optimize. This flag will do the following

1. Encode any non-encoded streams using Flate compression
2. Remove ASCII85 filters from all streams
3. Replace LZW encoded streams with Flate encoding
4. Merge identical XObjects and images
5. Optimize common sequences in page content
6. Merge identical font descriptors and encodings
   This option will usually result in a smaller file size

-iso32000 – To create a document that is ISO 32000 complaint.  This flag set file for ISO 32000 compliance (PDF version 1.7).

–comp – To use object level compression, use the -comp flag. This flag will apply object level compression, typically reducing the file size by 2%.

-nocomp – To not use object level compression, use the -nocomp flag.  This flag will not add object level compression and will remove object level compression, if found; resulting in a document that is compatible with all versions of Acrobat

PDF files support the use of multiple types of compression simultaneously.  Object level compression is a technique developed by Adobe to reduce the size of PDF files.  Object level compression is used in addition to the other compression mechanisms used within the PDF file. Object level compression will reduce the file size typically by 2%. NOTE: This mechanism is not always understood by older versions of Acrobat or third party PDF viewers or procession tools.

-rewritepage – Rewrite page contents to cleanup at the page content level.  This feature can be used to clean PDF files at the page level

-removerotation – Remove rotation from all pages. Landscape (11 x 8.5) pages in a PDF file are often portrait (8.5 x 11) pages rotated by 90 degrees.  This flag will remove the rotation, replacing the rotated page with a true landscape (11 x 8.5) page

-retaincreator – Retain the original document creator

-nomod – Retain the original document file modification date

Known Issues

• Running digitally-signed files through pdfHarmony will modify the digital signature
• Using -nosign on a digitally-signed file is not forcing a full save on the document
• if -hideWinUI is on the command line, then pageMode is ignored
• If you are running on a file that contains form fields and you want the output file to be linearized, you must have both -wforms -w on the command line.  Running with just -w does not linearize files with active form fields
• Comma separated keyword lists are not supported.  To enter a list of keywords, use the semicolon (;) character as a separator
• The -html reporting option cannot be used with watched folders

To Get Help

Contact technical support by:

emailing support@appligent.com, or calling 610-284-4006

Please provide the following:

Product name and version number
Operating system
Your name, company name, email address, and phone number
Description of your question or problem

Responses are typically emailed within one business day.