Reporting Progress and Errors
In this chapter….
you will learn how to…..
- Display progress messages (-p option) — Display progress to screen (STDOUT)
- Direct error messages to a user-specified text file (-l option) — Write progress and/or error messages to a file you specify
- Write all messages to a user-specified text file (-p and -l options together) — Direct all progress and errors to file
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.
The same progress messages are displayed on the screen, but without the date, as shown in the figure below.
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.
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.
