53
PDF Compresor Enterprise – Manual
www.luratech.com
info@luratech.com
Automatic Job List Processing: 73
one or more control files *.go it starts to process the oldest of these files. This implements a first
in, first out strategy. When a file
list0001.go
[signal a job list to be processed]
is going to be processed, PDF Compressor tries to load a job list from the file
list0001.dat
[the job list to be processed]
You ǁill see the ĐorrespoŶdiŶg joďs iŶ the PD& oŵpressor͛s list ǁiŶdoǁ
12
. The format of the
*.dat files is the same as used for job list import and export (see Job List File Syntax, p. 73).
During processing, the control file *.go is renamed to *.wrk. When all the entries of a list have
been processed without any error, the control file *.wrk is renamed to *.rdy:
list0001.rdy
[processing is ready, all files succeeded]
If an error occurred with any of the processed files, the control file is renamed to *.err:
list0001.err
[processing is ready, an error or abort occurred]
If the stop button is pressed while there are still running entries in the list, all entries are
aborted immediately, and the control file signals an error (*.err). This ensures that you will only
find list0001.rdy if all files has been successfully processed.
Job List File Priorities
After a list has been loaded, all its entries are automatically started. As soon as an entry has
finished (and is shown as stopped
13
) it is removed from the list. The next job list is loaded when
at least one processor core becomes idle and there are no jobs left waiting to get processed – so
jobs of different lists can be processed in parallel. This ensures that all available processor cores
run at full capacity as far as possible.
To enforce pure sequential processing of job lists and the contained jobs, the processing order
can be set to List Processing Order mode (compare Job List Processing, p. 14). If this option is
chosen, the next job list file is not loaded until processing all jobs from the previous file has been
completed.
In job list processing mode priorities cannot be assigned to individual job entries within a job list
file, but only to the job list file as a whole using file extensions. To this end file extensions ".go1"
(highest priority) through ".go10" (lowest) can be used for the job list files. Among files of the
same priority the oldest ones are processed first. Any file with a plain ".go" extension is given a
priority between ".go5" and ".go6".
The option Complete all jobs of highest priority before starting further jobs does not affect job
list processing.
Job List File Syntax
Job list files *.dat are plain text files. You can view and edit them in a simple text editor. It is
recommended to work with automatically generated job list files as follows: Set up your job list
12
Note that it is not necessary for the automatic job list processing to run the GUI (or even to log in).
13
If an entry is configured as a hot folder, this property is temporarily turned off for automatic job list
processing. Hot folders do never stop processing, thus the corresponding list would never be finished and
unloaded.
41
PDF Compresor Enterprise – Manual
www.luratech.com
info@luratech.com
Automatic Job List Processing: 74
within PDF Compressor first. Export the job list to a file. Modify only the basic entries explained
in the list at the end of this section. A job list file has the following structure.
A line with the keyword
LURATECH_PDF_COMPRESSOR_ENTRY_START_UTF8 <num>
starts a new entry in the list. <num> is the number of the entry counting from zero. This number
is written when exporting a list, but is ignored for import. The "_UTF8" bit serves to clarify the
text encoding. We highly recommend using Unicode UTF8 encoding, since it will properly
represent all sorts of special characters – such as accented vowels, German umlauts and Slavic
or Cyrillic characters – in paths, file names and other text strings.
As a fallback, the keyword
LURATECH_PDF_COMPRESSOR_ENTRY_START_ANSI <num>
can be used in cases where use of a Unicode compliant encoding is impossible and an ANSI
encoding must be used instead.
The properties of a job list entry are given by a number of lines, each of the form
<property_name> <value>
A <property_name> is an ASCII string defined by PDF Compressor. It does not contain any white
space. PDF Compressor reads known names, and it ignores lines with unknown names.
A <value> is either a decimal integer like 300 or a string in quotation marks like "Entry 01". Note
that strings do not escape any contained quotation character ". A string begins after the first
occurrence of the character " in a line and ends just before the last occurrence of the character
". Examples:
name "Entry 01"
set the name of the entry to Entry 01
name "Entry "01""
set the name of the entry to Entry "01"
Line feeds (hex 0A), carriage returns (hex 0D) and the character # are escaped by the following
sequences: #0A, #0D, and ##. No other substitutions occur. Example:
keywords "Key ##1#0D#0AKey ##2"
sets the keyword metadata field to two lines Key #1 and Key #2 using a carriage return / line
feed for the line separator.
A joď list eŶtrLJ ǁithiŶ a joď list file doesŶ͛t haǀe to ĐoŶtaiŶ all the defiŶed фpropertLJ_Ŷaŵeх
keywords. When loading an entry, the value of a property is calculated as follows:
1. Use the default value. See Section Setting up the Default Properties, p. 62, on how to setup
the general default values. For a single job list file with several jobs/entries the general
default can be overwritten by a file specific default. Every job list entry containing the
property listdefault with a value of 1 overwrites the default with its own property values.
2. If a corresponding <property_name> is found, use the specified value instead of the default.
64
PDF Compresor Enterprise – Manual
www.luratech.com
info@luratech.com
Automatic Job List Processing: 75
The following list contains the most important keywords used to create custom job list files:
<property_name>
Type
<value>
name
string
Name of the entry
pathIn
string
Path of the input directory or file (see also isDir)
isDir
integer
0 = pathIn is a file
1 = pathIn is a directory
recurse
integer
0 = do not scan input directories recursively
1 = scan input directories recursively
pathOut
string
Path of the output directory (see also outNext)
outNext
integer
0 = place output files in the directory specified by
pathOut
1 = place output files next to input files
pathMove
string
Path where to move input files after successful processing
(see also modeIn)
modeIn
integer
0 = do not move input files
1 = delete input files
2 = move input files to the directory specified in
pathMove
pathErr
string
Path where to move input files after an error occurred
during processing (see also moveOnErr)
moveOnErr
integer
0 = do not move input files on error
1 = move input files on error to the directory specified in
pathErr
title
string
PD& ŵetadata ͞title͟
author
string
PD& ŵetadata ͞author͟
subject
string
PD& ŵetadata ͞suďjeĐt͟
keywords
string
PD& ŵetadata ͞keLJǁords͟
New property names and/or more possible values of existing names will be added in future releases
of PDF Compressor. However, LuraTech will keep existing names, values and semantics compatible as
far as possible.
28
PDF Compresor Enterprise – Manual
www.luratech.com
info@luratech.com
Submitting Jobs via the PDF Compressor API: 76
8. Submitting Jobs via the PDF Compressor API
The PDF Compressor API (for Application Programming Interface) is an additional interface to
the PDF Compressor Service introduced with version 7.2. Using this interface 3
rd
party
Windows™ applications and services can programmatically submit jobs to a PDF CE instance
running on the same computer.
To make use of the API an external program must link against a DLL distributed with the regular
PDF Compressor installation. No restrictions or extra licenses apply. The API DLL comes in three
different flavors
a native 32 bit DLL with a C programming interface,
a native 64 bit DLL with a C programming interface,
a .NET 2.0 Assembly for both 32 and 64 bit environments, which will internally load the
appropriate native version.
As all three interfaces offer equivalent functionality we refer to them collectively as API DLL
here.
An application that has incorporated the PDF Compressor API DLL becomes an API client. It can
then create job configurations and submit them to the PDF Compressor via synchronous or
asynchronous function calls. The progress of these jobs can then be monitored via callback
functions and the caller can directly receive success or error messages.
In order to accept jobs submitted via the API the PDF Compressor Service must be put in API
Processing Mode. Similar to the Job List Processing mode covered in the previous chapter it is a
separate mode in which the PDF Compressor solely accepts jobs issued through the API. The API
Processing Mode is mutually exclusive with standard processing and Job List Processing mode.
44
PDF Compresor Enterprise – Manual
www.luratech.com
info@luratech.com
Submitting Jobs via the PDF Compressor API: 77
This color serves to remind you that in API Mode most interactive operations on job lists are
disabled. You cannot add or delete entries, nor can you edit any property of an entry. It is the
PDF Compressor service that loads and processes job entries as submitted by the API clients and
unloads them, once they have been completed.
API Job Lifecycle
IŶ ĐoŶtrast to the rather persisteŶt joď eŶtries of the PD& oŵpressor͛s staŶdard ŵode iŶ API
Mode jobs have a more limited lifespan. An API client creates an instance of a job configuration,
either from default settings or by loading a configuration from a *.dat file (compare Job List File
Syntax, p. 73).
An API Client can then access and modify all individual settings in this job configuration via set
and get functions. The entire scope of options of standard and Job List Processing mode is
available in API Mode, as well.
Once properly configured, the job can be submitted to the PDF Compressor for processing. This,
of course, requires a PDF Compressor service running in API Mode on the same computer. For
now, the API does not provide for remote access.
Note also, that input and output files are referenced through file system paths. For an API job to
succeed, these paths must be accessible by the PDF Compressor service. The API does neither
provide for passing the entire content of an input file programmatically to the service, nor for
receiving the result in a similar fashion. File input and output are performed via the file system.
API jobs can be submitted either synchronously – meaning the call will only return when the job
has been completed – or asynchronously, where the function call will return immediately.
The API client can provide a callback function to receive progress and status information
regardiŶg the suďŵitted joď͘ This iŶforŵatioŶ ĐaŶ also geŶerallLJ ďe retrieǀed usiŶg the ĐlieŶt͛s
reference handle to a submitted job.
A client can also prompt the server to abort a running job. Jobs can be submitted in a
multithreaded and asynchronous fashion. If all processor cores on the server side are busy the
PDF Compressor service will queue the submitted jobs and process them according to priority
and submission time.
The C/C++ API
The two native API DLLs reside in the api suďfolder of the PD& oŵpressor͛s iŶstallatioŶ folder as
PDF_CompApi_32.dll and PDF_CompApi_64.dll. The C header and library files required to
incorporate them in an API client can be found in the api\include folder. The api folder also
contains a PDF manual for the API and sample source code in the api\samples\ApiDemo sub
folder.
The .NET API
The suďfolder of the PD& oŵpressor͛s iŶstallatioŶ also ĐoŶtaiŶs the .NET version of the API DLL
as PDF_CompApi.NET.dll. It is also accompanied by documentation and sample source code in
the api\samples\ApiDemo.NET. The API Assembly itself requires .NET 2.0, but can be used with
higher versions. The assembly is strongly named and can therefore be installed in the Global
Assembly Cache (GAC).
15
PDF Compresor Enterprise – Manual
www.luratech.com
info@luratech.com
Submitting Jobs via the PDF Compressor API: 78
Note: The .NET API Assembly comprises a wrapper around the native API DLLs, therefore all
three DLLs are required by a .NET API client at runtime.
API Demo Applications
Two sample demo applications are deployed with PDF Compressor Enterprise
PDF_CompApi_Demo.exe is a simple command-line client using the native C DLL (it uses
the DLL version matching the operating system).
PDF_CompApi_DemoGUI.exe comprises a simple WinForms™ user interface, permitting
a user to interactively configure a handful of common job settings and then to launch
the corresponding job and receive its progress messages.
These two applications correspond to the compiled versions of the sample source code projects
found under api\samples iŶ the PD& oŵpressor͛s iŶstallatioŶ folder͘
26
PDF Compresor Enterprise – Manual
www.luratech.com
info@luratech.com
Administration and Licensing: 79
9. Administration and Licensing
Administration and license management can be performed via the
File
Options
menu. The
Options dialog has several tabs which are described in the following sub sections.
General Configuration Settings
Log Files
The section Logfile of the Options dialog lets LJou ĐoŶfigure PD& oŵpressor͛s loggiŶg sLJsteŵ͘
1. You can specify path and file name of the log file. Use the browse button to select the log
file
14
.
2. The type of logged information can be selected by the corresponding drop down box:
a. Log all and extended info works like Log errors, warnings and info but also includes
extended information that is usually not needed.
b. Log errors, warnings and info is the recommended setting. It logs errors, warnings
and other basic information. With this setting will the log file will give you detailed
14
The text edit window for the log file accepts file drag & drop: Just drag Θ drop a file froŵ the WiŶdoǁs™
Explorer into this window.
36
PDF Compresor Enterprise – Manual
www.luratech.com
info@luratech.com
Administration and Licensing: 80
information on what files have been converted and how many pages from the
license have been used.
c. Log errors and warnings will not log the additional conversion information.
d. Log error messages only will log only errors.
3. The size of the log file can be limited or set to unlimited by the corresponding drop down
box:
a. Unlimited logfile size will enable the log file to grow until all your disk space is used.
This gives you the full history of all your conversions. It is the default setting. When
your server is performing high volume conversions, and when it is not frequently
monitored, it is recommended to limit the log file size by any of the other settings.
b. Limit to <num> limits the log file size to the given amount. Once a log message is
written that lets the log file size reach its limit, the file <log_file>.log is renamed to
<log_file>.log.bak within the same directory, overwriting any present file of that
name. A new, empty log file <log_file>.log is created. This ensures that at least the
given number of bytes is always present as the logging history.
4. The Show button starts the Windows™ Notepad application to show the content of the
current log file.
Log File Analysis
Each line within the log file represents one message. It consists of the following fields:
1. Date and time of message followed by a colon
2. An optional core number followed by a colon
15
3. Type of message (Error, Warning, Info, InfoEx [extended information])
4. If the message is related to a job entry: Name of the entry as shown in the job list, followed
by a colon.
5. Clear text message (error description, warning reason, information)
Often related files are given with their full path in quotation marks.
Some errors are directly shown by a popup box when the GUI is opened:
15
If such a number is present, the message was issued by the PDF Compressor Enterprise responsible to handle
processing assigned to the given core number. Otherwise the message was issued by the PDF Compressor
WiŶdoǁs™ serǀiĐe͘
Documents you may be interested
Documents you may be interested
