Reporting Progress and Errors
Introduction
By default, APSplit writes any error messages to the screen (STDOUT) and to the default log file, apsplit.log. With APSplit’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 APSplit 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.
In this chapter, you will learn how to:
- Display progress messages
- Direct error messages to a user-specified text file
- Write all messages to a user-specified text file
Note: For purposes of illustration, the examples in this chapter focus on reporting messages generated by the default APSplit command (described in, Performing a Basic Split). However, the reporting functions described here apply to logging the results of all APSplit commands.
Displaying Progress Messages
To reduce clutter, APSplit 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, apsplit.log. If you also want to see standard progress messages, use the -p option to instruct APSplit to write them to the screen and to apsplit.log.
Command
$ apsplit -p [other options] inPDFFile [inPDFFile2...]
Windows
>apsplit -p -o C:\Appligent\APSplit\output\ C:\Appligent\APSplit\samples\SplitSample.pdf
UNIX/Macintosh
$ ./apsplit -p -o /Appligent/APSplit/output/ /Appligent/APSplit/samples/SplitSample.pdf
Result
The -p option instructs APSplit to write progress messages to the screen and to the default log file, apsplit.log. If apsplit.log does not already exist, it is created in the directory where APSplit is installed. An entry like the one shown in the figure below is then created in apsplit.log. The same progress messages are displayed on the screen, but without the date.
Directing Error Messages to a User-Specified File
By default, APSplit writes any error messages to the screen (STDOUT) and to the default log file, apsplit.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 TXT format.
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
$ apsplit -l logFile.txt [other options] inPDFFile [inPDFFile2...]
Windows
> apsplit -l C:\Appligent\APSplit\mylogfile.txt -o C:\Appligent\APSplit\output\ C:\Appligent\APSplit\samples\SplitSampleSecure.pdf
UNIX/Macintosh
$ ./apsplit -l /Appligent/APSplit/mylogfile.txt -o /Appligent/APSplit/output/ /Appligent/APSplit/samples/SplitSampleSecure.pdf
Result
The example commands shown above generate an error, because the SplitSampleSecure.pdf file requires an Owner password, but the -d option and Owner password are not included. The -l option directs the associated error message to mylogfile.txt, instead of the default apsplit.log file. The error message created in mylogfile.txt looks like the one shown in the figure below. The same message is displayed on the screen.
Writing All Messages to a User-Specified File
You can have APSplit 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 TXT format. 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
$ apsplit -p -l logFile.txt [other options] inPDFFile [inPDFFile2...]
Windows
> apsplit -p -l C:\Appligent\APSplit\mylogfile.txt -d myownerpass -o C:\Appligent\APSplit\output\ C:\Appligent\APSplit\samples\SplitSample.pdf C:\Appligent\APSplit\samples\SplitSampleSecure.pdf
UNIX/Macintosh
$ ./apsplit -p -l /Appligent/APSplit/mylogfile.txt -d myownerpass -o /Appligent/ApSplit/output/ /Appligent/APSplit/samples/SplitSample.pdx /Appligent/APSplit/samples/SplitSampleSecure.pdf
Result
The example commands shown above generate an error, because the SplitSample.pdx file does not exist. (The file name was typed incorrectly; the extension should be pdf, not pdx.). The second input file, SplitSampleSecure.pdf, 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.
