Reporting Progress and Errors

In this chapter….

you will learn how to…..

By default, APGetInfo writes any error messages to the screen (STDOUT) and to the default log file, apgetinfo.log. With APGetInfo’s reporting options, you can display progress messages, as well, and direct your messages to a file other than the default log file.

These reporting options are useful for debugging and for understanding how APGetInfo works. In addition, if you ever contact Appligent Customer Support with a problem, we will want to see all messages generated by the command you were running when the problem occurred.

Note: For purposes of illustration, the examples in this chapter focus on reporting messages generated by commands used to obtain document description information. (Document description information is discussed in Getting Document Information) However, the reporting functions described here apply to logging the results of all APGetInfo information retrieval commands, not just to those involving the retrieval of document description information.

Displaying Progress Messages

To reduce clutter, APGetInfo does not show you any messages unless they represent errors that require your attention. These messages are directed to the screen (STDOUT) and to the default log file, apgetinfo.log. If you also want to see standard progress messages, use the -p option to instruct APGetInfo to write them to the screen and to apgetinfo.log.

Command

$apgetinfo -p [other options] inPDFFile

Windows Example

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

UNIX/Macintosh Example

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

Result

The -p option instructs APGetInfo to write progress messages to the screen and to the default log file, apgetinfo.log. If apgetinfo.log does not already exist, it is created in the directory where APGetInfo is installed. An entry like the one shown in the figure below is then created in apgetinfo.log.

Progress messages written to logfile

The same progress messages are displayed on the screen, but without the date, as shown in the figure below.

Progress messages to STDOUT

Directing Error Messages to a User-Specified File

By default, APGetInfo writes any error messages to the screen (STDOUT) and to the default log file, apgetinfo.log. You can direct error messages to a different log file by specifying the -l option, followed by the name of the file. The file must be in  text format (.txt).

Note: The log file must be write-enabled. If it is a read-only file, the following warning is displayed and nothing is written to the file:
Warning: error opening log file filename.txt

Command

$apgetinfo -l logFile.txt [other options] inPDFFile

Windows Example

$apgetinfo -l C:\Appligent\APGetInfo\mylogfile.txt -info C:\Appligent\APGetInfo\samples\ApUtilsSampleEnc.pdf

UNIX/Macintosh Example

$./apgetinfo -l /Appligent/APGetInfo/mylogfile.txt -info /Appligent/APGetInfo/samples/ApUtilsSampleEnc.pdf

Result

The example commands shown above generate an error, because the ApUtilsSampleEnc.pdf file requires a User password to open it, but the -d option and User password are not included. The -l option directs the associated error message to mylogfile.txt, instead of the default apgetinfo.log file. The error message created in mylogfile.txt looks like the one shown below. The same error message is displayed on the screen.

Error messages written to logfile

Writing All Messages to a User-Specified File

You can have APGetInfo write both error messages and progress messages to a log file of your choice by specifying the -p option and the -l option, followed by the name of the log file. The file must be in text format (.txt).  All messages written to the file are also written to the screen (STDOUT).

Note: The log file must be write-enabled. If it is a read-only file, the following warning is displayed and nothing is written to the file:
Warning: error opening log file filename.txt

Command

$apgetinfo -p -l logFile.txt [other options] inPDFFile

Windows Example

$apgetinfo -p -l C:\Appligent\APGetInfo\mylogfile.txt -info -d userpass C:\Appligent\APGetInfo\samples\ApUtilsSampleEnc.pdf C:\Appligent\APGetInfo\samples\ApUtilsSample.pdf

UNIX/Macintosh Example

$./apgetinfo -p -l /Appligent/APGetInfo/mylogfile.txt -info -d userpass /Appligent/APGetInfo/samples/ApUtilsSampleEnc.pdf /Appligent/APGetInfo/samples/ApUtilsSample.pdf

Result

The example commands shown above generate an error, because the ApUtilsSample.pdx file does not exist. (The file name was typed incorrectly; the extension should be pdf, not pdx.). The second input file, ApUtilsSampleEnc.pdf file, is successfully processed. Progress and error messages like those shown in the figure below are written to mylogfile.txt. The same messages are displayed on the screen.

Progress with errors