Introduction

This chapter explains the basics of managing file input and output when retrieving information from one or more PDF documents.

You will learn how to:

For purposes of illustration, the examples in this chapter focus on managing input and output for the retrieval of document description information. (Document description information is discussed in Getting Document Information.) However, the input and output functions described here apply to all APGetInfo information gathering options, not just to obtaining document description information.

Retrieving Information from an Unsecured File

No special action is required to retrieve information from a PDF document that has no security applied to it. Just enter the apgetinfo command, followed by one or more options, and then the path name of the input file.

Command

$apgetinfo [options] inPDFFile

Windows Example

$apgetinfo -info C:\Appligent\APGetInfo\samples\ApUtilsSample.pdf

UNIX/Macintosh Example

$./apgetinfo -info /Appligent/APGetInfo/samples/ApUtilsSample.pdf

Result

The figure below shows the results of running apgetinfo with the -info option on the ApUtilsSample.pdf file supplied with APGetInfo. APGetInfo retrieves document description information from the document and sends it to the standard output device (STDOUT), the screen.

Note: The same command was used in Retrieving Document Description Information

information reported by -info option

Obtaining Information from an Encrypted File

To get information about an encrypted file, you must supply its User password. (The User password, which is also called an Open password, is required to open the document.)

Note: An Owner password (also called a Permissions or Master password) will not work correctly with APGetInfo. You must supply a User password.

Command

$apgetinfo -d userpassword [other options] inPDFFile

Windows Example

$apgetinfo -d userpass -info C:\Appligent\APGetInfo\samples\ApUtilsSampleEnc.pdf

UNIX/Macintosh Example

$./apgetinfo -d userpass -info /Appligent/APGetInfo/samples/ApUtilsSampleEnc.pdf

Result

This command uses the -d option to supply the User password (userpass) required to open ApUtilsSampleEnc.pdf. It then retrieves document description information from the document and directs the output to the screen (STDOUT). The output is shown in the figure below. It is the same as the output for the unsecured ApUtilsSample.pdf file shown in the figure above, except for the encryption information, the Changing ID and file size. (The ApUtilsSampleEnc.pdf file was created by saving ApUtilsSample.pdf as ApUtilsSampleEnc.pdf, and then creating a User password and adding other security settings.)

Information reported on encrypted document

Note: If you fail to specify the -d option and a User password for an encrypted document, you will receive this error message:
Error: this document requires a password

Gathering Information from Multiple Files

You can retrieve information from more than one file at a time by specifying the path name for each input file. If you want to retrieve information from all of the PDF files in a directory, you can use the *.pdf wildcard specification as a shortcut.

If any of the input files are encrypted, you must also specify a User password. However, only one User password can be included on a command, and no information will be retrieved from encrypted files that have a different password. A separate command must be submitted for each User password.

Command

$apgetinfo [options] inPDFFile1 [inPDFFile2...]

Windows Examples

  • Using full path names:
C:\Appligent\APGetInfo\apgetinfo -info -d userpass C:\Appligent\APGetInfo\samples\ApUtilsSample.pdf  C:\Appligent\APGetInfo\samples\ApUtilsSampleEnc.pdf
  • Substituting a wildcard shortcut:
c:\Appligent\APGetInfo\apgetinfo -info -d userpass C:\Appligent\APGetInfo\samples\*.pdf

UNIX/Macintosh Examples

  • Using full path names:
$./apgetinfo -info -d userpass /Appligent/APGetInfo/samples/ApUtilsSample.pdf /Appligent/APGetInfo/samples/ApUtilsSampleEnc.pdf
  • Substituting a wildcard shortcut:
$./apgetinfo -info -d userpass /Appligent/APGetInfo/samples/*.pdf

Result

The figure below shows the results of running apgetinfo with the -info option and the -d option on the ApUtilsSample.pdf and ApUtilsSampleEnc.pdf files supplied with APGetInfo. APGetInfo retrieves document description information from both of these documents and sends the results to the standard output device (STDOUT), the screen. The -d option is required to open the encrypted ApUtilsSampleEnc.pdf file. This option is ignored by the ApUtilsSample.pdf file, which is unsecured and does not need a password.

Results from an unsecured and secured document

Including the File Name in the Results

When you run multiple commands or include multiple input files on one command, it can be helpful to include the name of each input file with its results. You can do this with the -name option.

Command

$apgetinfo -name [other options] inPDFFile

Windows Example

$apgetinfo -name -info -d userpass C:\Appligent\APGetInfo\samples\*.pdf

UNIX/Macintosh Example

$./apgetinfo -name -info -d userpass /Appligent/APGetInfo/samples/*.pdf

Result

The figure below shows the results of running apgetinfo with the -name option, -info option, and -d option on the two sample files supplied with APGetInfo: ApUtilsSample.pdf and ApUtilsSampleEnc.pdf. (The -d option is required because ApUtilsSampleEnc.pdf is an encrypted file that can only be opened with a User password.) The output is essentially the same as that shown in the figure above, except for the addition of a file name at the beginning of each set of results. The file names, included because of the addition of the -name option, clearly indicate which file each set of results belongs to.

Note: These results were obtained on a Windows platform, as indicated by the C: root directory and backward slashes in the file names.

Information reported with -name option included

 

Writing the Results to a Text File

By default, APGetInfo directs all output to the screen (STDOUT). To write your output to a file instead, specify the -o option, followed by the name of a text file. If you want your output file to go to a particular directory, be sure it exists beforehand. APGetInfo will not create a new directory.

Command

$apgetinfo -o outFile.txt [other options] inPDFFile

Windows Example

$apgetinfo -o C:\Appligent\APGetInfo\samples\myoutput.txt -name -info -d userpass C:\Appligent\APGetInfo\samples\*.pdf

UNIX/Macintosh Example

$./apgetinfo -o /Appligent/APGetInfo/samples/myoutput.txt -name -info -d userpass /Appligent/APGetInfo/samples/*.pdf

Result

The results are exactly the same as those shown in the figure above, except they are saved in myoutput.txt instead of being displayed on the screen.