Acrobat, Distiller, InDesign, Illustrator, Photoshop, FrameMaker, PDFWriter, PageMaker, the Adobe
logo, the Acrobat logo and PostScript are trademarks of Adobe Systems Incorporated.
Macintosh, Mac, Mac OS and ColorSync are trademarks of Apple Computer, Inc., registered in the
U.S. and other countries.
Windows, Windows 2000, Windows XP, Windows Vista and windows 7 are registered trademarks
of Microsoft Corporation.
PANTONE®Colors displayed here may not match PANTONE-identified standards. Consult current
PANTONE Color Publications for accurate color.
Quark, QuarkXPress, QuarkXTensions, XTensions and the XTensions logo among others, are
trademarks of Quark, Inc. and all applicable affiliated companies, Reg. U.S. Pat. & Tm. Off. and
in many other countries.
This product and use of this product is under license from Markzware under U.S.Patent No.
5,963,641.
Other brand and product names may be trademarks or registered trademarks of their respective
holders. All specifications, terms and descriptions of products and services are subject to change
without notice or recourse.
4
2. Introduction
2.1 Short summary
This document specifies a command line interface for PitStop Server, shipped as part of the
standard product in the 10 release.
2.2 Objectives
PitStop Server
Terminology
Target group
Ease of use
Distribution
DefinitionShorthand
Command line interfaceCLI
Command line applicationCLA
System integrators (including sophisticated end-users) form the main target group for the PitStop
Server Command line interface (CLI).
Integrators often want to use PitStop technology in a convenient way without using the C
programming language. They may lack the C programming skills or they may need to invoke
PitStop from a scripted environment.
The CLI is identical on all supported platforms. Options are specified as command-line arguments
and in a configuration file passed to the command line. Advanced options can be omitted. Simple
processing can even be achieved without a configuration file.
The CLI is implemented as an independent executable, called the command line application
(CLA), which is part of PitStop Server. On Mac OS X the CLA is installed inside the PitStop Server
package, on Windows next to all other executables.
The CLA finds its resources without relying on the PATH environment variable or regardless of the
working folder from which the CLI is called.
The CLA is only supported in combination with “its” PitStop Server installation. If PitStop Library
is replaced or resources are added or removed, there are no guarantees on its behavior. Like in
the regular PitStop Server product we do not verify that the installation is unmodified and we
5
PitStop Server
try to give reasonable error messages if something goes wrong, but most error messages will be
cryptic and sometimes we could even crash.
The CLA knows were to find PitStop Library and its resources. The Integrator only needs to find
the CLA to use the CLI.
Multiple invocations
Multiple invocations of the CLA can execute concurrently. Each invocation creates a unique
temporary location for PitStop Library and removes the temporary data on exit.
6
3. Command line application
The PitStop Server CLI is implemented by a command line application (CLA) with the same interface
on all platforms.
3.1 Command line options
Syntax
The arguments on the command line are of the form:
–key [value]
with following restrictions:
• Keys are case-insensitive.
• Values that contain spaces are enclosed in double quotes (“) on Windows. On Mac OS X there
are 3 conventions: enclose in double quotes or single quotes (‘), or precede the space with a
backslash (\<space>). All three conventions are supported.
• Paths are in platform syntax (Posix notation on Mac OS X) and either absolute or relative to
the current working directory.
PitStop Server
Overview
Configuration
PitStopServerCLI
[–config <file path to a configuration file>]
[-input <file path to an input file>]
[-mutator <file path to a preflight profile or an action list>]
[–reportPDFTmpl <file path to a report template>]
[-output <file path to an output location (incl. filename)>]
[-reportPDF <file path to a report location (incl. filename)>]
[-reportXML <file path to a report location (incl. filename)>]
[-taskReport <file path to a task report file (incl. filename)>]
[-version]
[-libraryVersion]
[-help]
None of these options is required (but at least one option has to be provided). The order in which
options are specified is irrelevant (with a minor exception for admin options).
DescriptionValue typeKey name
7
PitStop Server
Process
Path (in)config
The configuration file is an XML file describing the task(s) to be executed with detailed settings.
If no configuration file is specified, defaults are used for all settings. In that case, at least the
input option should be specified along with the mutator, output and/or report options (or nothing
meaningful will happen).
Path (in)mutator
Location and name of a configuration XML file with settings
to configure PitStop Server CLI tasks
The format of the configuration file is described in a separate
chapter
DescriptionValue typeKey name
Location and name of the input PDF filePath (in)input
Location and name of a file containing a preflight profile or
an action list
Location and name for the output PDF filePath (out)output
It is acceptable for this to be the same path as the input path
(i.e. a file can be processed “in place”)
Task report
Path (out)reportPDF
Path (in)reportPDFTmpl
These options specify the input and output paths used by the CLA for processing a PDF file. Any
pre-existing file at an output location is overwritten.
If a configuration file is specified that contains one or more Process elements, a value on the
command line (for one of the above options) overrides the corresponding value in the first Process
element. In other words the value in the configuration file is ignored.
This rule applies to each value individually. For example, specifying an input file on the command
line does not affect the mutator(s) specified in the Process element. However, a mutator specified
on the command line does override all mutators specified in the Process element.
Any subsequent Process elements (other than the first one) in the configuration file are not
affected by the command line options.
Location and name for the PDF report file (regular or
annotated report)
Location and name of the report template for creating the
report
This value is ignored if no reportPDF path is specified
Location and name for the XML report filePath (out)reportXML
DescriptionValue typeKey name
8
PitStop Server
Admin
Path (out)taskReport
If a configuration file is specified that contains a TaskReport element, the value for the taskReport
option on the command line overrides the TaskReportPath value in the TaskReport element. In
other words the value in the configuration file is ignored.
nonehelp
These options cause low-ASCII text to be written to stdout. The version and libaryVersion options
produce a single line that can be easily interpreted by another application (in addition to being
readable for humans).
Location and name of a task report XML file, with information
on the tasks executed by the CLA
Any pre-existing file at the location is overwritten
The format of the task report file is described in a separate
chapter
DescriptionValueKey name
Write the CLA version to stdoutnoneversion
Write the PitStop Library version to stdoutnonelibraryVersion
Write an English summary of the command line options to stdout
(see overview section earlier in this chapter)
Use cases
If an admin option is specified, all non-admin options are ignored. If multiple admin options
are specified, they are processed in order of occurrence on the command line.
Options may be meaningfully combined as follows.
Use caseDescriptionOptions specified
Verify version numberProduce output on stdoutA single admin option
Get help on options
Just input/output options
(no config file)
Just the config option
The config option plus
input/output options
Use default settings for simple
processing
All settings are specified in the
configuration file, including
input and output paths
Most settings are in the
configuration file, and some
input/output paths are overruled
on the command line
Produce a preflight report for a PDF
file
Run an action list on a PDF file
An automated system generates a
configuration file with specific
settings for every job
The configuration file is created
once (perhaps by hand); it serves
as a fixed template for all jobs
9
PitStop Server
3.2 Exit behavior
Exit code
The exit code of the CLA is zero when the task is successful and non-zero when there is a fatal
problem (see table in a later section).
Note that preflight errors or warnings do not cause the CLA to return a non-zero exit code; these
issues are listed in the preflight report or in the CLA’s task report.
Error message
If the CLA exits with a nonzero exit code, it writes an appropriate error message to stderr with
the following characteristics:
• It starts with a decimal representation of an error code (see next section), followed by a colon,
and followed by a human-readable message describing the problem in as much detail as
possible.
• It is in English (enUS) and uses UTF-8 encoding (so that filenames can always be interpreted
correctly).
• It is on a single line and it is the last nonempty line written to stderr.
Error codes
-1
-2
3.3 Default values
The default value for each setting is discussed in the chapter on the configuration file.
General rule
As a general rule, the default value for PitStop Server CLI settings is the default value used by
PitStop Server after a clean installation. The CLI does not rely on the PitStop Server preferences.
arguments or configuration file
settings detected by the CLA
PitStop Library
Error code written to stdoutDescriptionExit code
Not applicableSuccessful operation0
Error code specific to the CLAProblem with command line
These error codes are chosen so that they
don’t clash with those of PitStop Library
PitStop Library error codeUnexpected error returned by
10
System fonts
PitStop Server
For example the default temporary location is the operating system default (temp folder for the
current user) even if the PitStop Server preferences are set to use a specific folder.
By default PitStop Server CLI loads all system fonts before processing a PDF file. Depending on
the number of available fonts, this may consume substantial processing time and resources.
In situations where the system fonts aren’t used, one should use the appropriate setting in the
configuration file to avoid loading them.
11
PitStop Server
4. Configuration XML file
4.1 Introduction
The configuration file provides detailed instructions and settings for the command line tool. It
is constructed as a tree of XML elements. The remaining sections in this chapter describe each
element that may appear in the file and its immediate child elements.
Ordering of XML elements
The elements in the configuration file must be ordered to allow single-pass parsing. In other
words, all information necessary to execute a certain task must be presented before the command
requesting the task.
The description for each element specifies the ordering requirements for its immediate children,
if there are any such requirements. The tables always list elements in a “safe” order; in other
words ordering elements as presented in the tables never violates the ordering requirements.
Unicode support
The configuration file is a well-formed XML document, which means that it fully supports Unicode
for text values such as file names. If the text encoding specified in the XML header is not
understood, the job fails.
This is a string type representing a file or folder path. Both absolute and relative paths are
supported.
An absolute path must be specified in the native platform format, for example:
• On Windows: C:\Preflight\Input\input.pdf
• On Mac OS: /Volumes/Preflight/Input/input.pdf
A relative path is interpreted relative to the CLA’s current working directory and can be specified
with forward or backward slashes on all platforms. This allows a configuration file with only
relative paths to be platform-independent. For example the following two paths have the same
meaning on all platforms:
• Windows style: ..\Input\input.pdf
• Mac OS style: ../Input/input.pdf
4.3 Configuration
This is the root element of the configuration file. This element’s children, if present, must be
ordered exactly as presented in the table.
PitStop Server
DescriptionMultiplicityTypeElement name
requiredVersioningVersioning
ProcessProcess
zero or
more
The version of this configuration file and the
strategy to follow when PitStop Server CLI encounters
settings it does not understand
Settings for producing a task reportoptionalTaskReportTaskReport
If no task report element is provided, and there is
no task report option on the command line, no task
report is generated
Requests for processing PDF files (e.g. performing
preflight and/or running action lists)
Certain command line options override settings in
the first Process element (or in a virtual default
Process element if none is provided).
If no Process elements are provided, and there are
no process options on the command line, no
processing occurs
4.4 Versioning
This element specifies the version of the XML config file, and how to react to unknown settings.
DescriptionMultiplicityTypeElement name
requiredintegerVersion
optionalenumerationVersioningStrategy
The version of this XML configuration file;
currently this must be “2”
The strategy to follow when an unsupported
setting is encountered:
13
PitStop Server
4.5 Initialize
This element specifies a temp folder (in case temporary files should be stored in a place other
than the system default for the current user).
BestEffort (the default): ignore setting or
substitute a reasonable value
MustHonor: exit with an error code
DescriptionMultiplicityTypeElement name
Other information
The CLA passes the appropriate information to PitStop Library for:
• Product info used in PDF reports
• System info for Certified PDF
• Registration info for Certified PDF
This information can’t be changed by the user.
4.6 TaskReport
optionalPathTypeTempPath
Path to the folder in which all temporary files
should be stored
The default temporary location is the
operating system default (temp folder for the
current user)
It is acceptable to specify the same path for
multiple concurrent invocations of the CLA
14
This element specifies a request to generate a task report, including the settings to define the
report’s contents. The TaskReportPath element must be placed first; the order of the other children
may vary and determines the order in which the responses occur in the task report.
DescriptionMultiplicityTypeElement name
requiredPathTypeTaskReportPath
optionalbooleanLogVersionInfo
The location and filename where the
requested task report should be placed
If present and true, the task report
contains version information on the
PitStop Server CLA and its PitStop Library
PitStop Server
optionalbooleanLogSupportInfo
optionalbooleanLogCommandLine
optionalbooleanLogProcessResults
optionalbooleanLogErrors
optionalbooleanQueryLanguages
If present and true, the task report
contains information useful for support
and debugging purposes
Use this option only when requested by
Enfocus technical support
If present and true, the task report
contains a list of the options received
(and recognized) on the command line
If present and true, the task report
contains the number of errors, warnings,
fixes, signoffs, failures and critical
failures for each Process task
If present and true, the task report
contains a list of warning and error
messages encountered during execution
If present and true, the task report
contains a list of the languages
supported by PitStop Server CLI
optionalbooleanQueryCMMs
optionalQueryMutatorDBQueryDefaultProfileDB
optionalQueryMutatorDBQueryLocalProfileDB
optionalQueryMutatorDBQueryDefaultActionDB
optionalQueryMutatorDBQueryLocalActionDB
QueryMutatorInfoQueryMutatorInfo
zero or
more
If present and true, the task report
contains a list of CMMs supported by
PitStop Server CLI
Requests a list of the preflight profiles
in the default database to be included
in the task report
Requests a list of the preflight profiles
in the local database to be included in
the task report
Requests a list of the action lists in the
default database to be included in the
task report
Requests a list of the action lists in the
local database to be included in the task
report
Requests information on a mutator, i.e.
a preflight profile or an action list, to be
included in the task report
15
PitStop Server
4.7 QueryMutatorDB
These elements specify a request for getting a list of mutators in one of the databases managed
by PitStop Server (the default and local preflight profile and action lists databases).
The path of each mutator is always listed. Additional information can be requested by specifying
one or more child elements.
DescriptionMultiplicityTypeElement name
The type of information requested; one of:zero or moreenumerationMutatorInfoOptions
• Name: the name of the mutator
• Company: the company of the author of the mutator
• Author: the author of the mutator
• Description: the description of the mutator
• MutatorType: the type of mutator (preflight profile or action list)
• DateTime: the most recent modification date and time of the mutator
• Version: the version of the mutator
• IsFullyUnderstood: check if PitStop Server CLI fully supports all settings
and instructions in this mutator
• IsVersionCorrect: check if the version of the mutator is correct
• IsConfigurationCorrect: check if the configuration of the mutator is
correct
4.8 QueryMutatorInfo
This element specifies a request for getting information on a mutator, i.e. a preflight profile or
an action list.
DescriptionMultiplicityTypeElement name
requiredPathTypeMutatorPath
• Name: the name of the mutator
• Company: the company of the author of the mutator
• Author: the author of the mutator
• Description: the description of the mutator
• MutatorType: the type of mutator (preflight profile or action list)
• DateTime: the most recent modification date and time of the mutator
• Version: the version of the mutator
The path to the mutator (preflight profile or
action list) for which information is being
requested
The type of information requested; one of:zero or moreenumerationMutatorInfoOptions
16
4.9 Process
PitStop Server
• IsFullyUnderstood: check if PitStop Server CLI fully supports all settings
and instructions in this mutator
• IsVersionCorrect: check if the version of the mutator is correct
• IsConfigurationCorrect: check if the configuration of the mutator is
correct
This element specifies a request for processing a PDF file (e.g. performing preflight or running
action lists). There can be multiple Process elements.
DescriptionMultiplicityTypeElement name
Location of the input PDF fileoptional (*)InputPDFInputPDF
(*) is in fact required, but for the first
Process element may be specified as a
command-line option
(*) is in fact required, but for the first
Process element may be specified as a
command-line option
Type and location of reports to be
created
If no reports are specified here or (for
the first Process element) on the
command-line, none are generated
Settings for the transparency flattening.
If this setting is not defined, no
transparency flattening will be
performed.
Location of preflight profile or action list
to be used
If no mutators are specified here or (for
the first Process element) on the
command-line, none are used
Settings for Certified PDF behavioroptionalCertifiedPDFCertifiedPDF
Settings for color managementoptionalColorManagementColorManagement
Settings for font managementoptionalFontsFonts
17
PitStop Server
4.10 InputPDF
This element specifies the location of an input PDF file.
optionalenumerationLanguage
optionalenumerationMeasurementUnit
The language to be used in the preflight
report as a 4-character string in the
form 'enUS'; 'frFR', 'deDE', ...
If the requested language is not
available English (enUS) is used instead
The default language is English (enUS)
The measurement unit to be used in the
preflight report; one of:
• Point (the default)
• Pica
• Inch
• Centimeter
• Millimeter
4.11 OutputPDF
This element specifies the location and save options for the output PDF file.
DescriptionMultiplicityTypeElement name
Path to the input PDF fileoptional (*)PathTypeInputPath
(*) is in fact required, but for the first Process
element may be specified as a command-line
option
DescriptionMultiplicityTypeElement name
Path for the output PDF fileoptional (*)PathTypeOutputPath
(*) is in fact required, but for the first Process
element may be specified as a command-line
option
Save options for the output PDF fileoptionalSaveOptionsSaveOptions
18
4.12 SaveOptions
This element specifies save options for the output PDF file.
PitStop Server
DescriptionMultiplicityTypeElement name
4.13 Reports
This element specifies which reports should be created when processing a PDF file.
optionalbooleanPerformFullSave
If true (the default), a full save is performed which
means it is no longer possible to roll back Certified PDF
sessions
If false, an incremental save is performed
Set the optimization option as one of:optionalenumerationOptimization
• Disabled: no optimization is
performed
• FileSize: the internal structure is
optimized to create the smallest
possible PDF file
• WebDownload: the file will be
optimized for usage on the web
The default value is “FileSize”
4.14 ReportPDF
This element specifies settings for creating a PDF report.
DescriptionMultiplicityTypeElement name
ReportPDFReportPDF
more
requiredPathTypeReportPath
Settings for creating a PDF reportzero or
Settings for creating an XML reportoptionalReportXMLReportXML
DescriptionMultiplicityTypeElement name
Location and name for the generated report
file
19
PitStop Server
4.15 ReportXML
This element specifies settings for creating an XML report.
4.16 TransparencyFlattening
This element specifies which settings are to be used when transparency is flattenend. If
preflighting is enabled by defining at least one Preflight Profile or Action List, Transparency
Flattening is performed before preflighting the PDF. It is possible to do Transparency Flattening
without preflighting. Transparency Flattening requires that Color Management is enabled.
optionalPathTypeReportTemplatePath
requiredPathTypeReportPath
Path to a PitStop report template; if no
template is specified the regular Enfocus
report template is used
DescriptionMultiplicityTypeElement name
Location and name for the generated report
file
4.17 Mutators
This element specifies the mutators that should be used for processing the PDF file. Any number
of action lists and at most one preflight profile can be specified. The actions lists are executed
in the same order as the XML elements; the preflight profile is always executed last.
If a mutator is specified on the command line, any and all mutators listed in the first Process
element are ignored.
DescriptionMultiplicityTypeElement name
optionalintegerResolution
optionalbooleanResolveOverprint
The resolution used for transparency
flattening. All the objects in the PDF that need
transparency flattening will be resampled to
this resolution.
If present and true, the resulting PDF file will
not have any objects in overprint. This setting
has no effect on the visual appearance of the
PDF.
20
PitStop Server
DescriptionMultiplicityTypeElement name
4.18 CertifiedPDF
This element specifies settings related to Certified PDF processing.
PathTypeActionList
more
Path to an action list filezero or
Path to a preflight profile fileoptionalPathTypePreflightProfile
DescriptionMultiplicityTypeElement name
The Certified PDF action; one of:optionalenumerationCertifiedPDFAction
• MakeCertified: always output a Certified PDF
file (even if the input is not)
• MakeUncertified: remove any Certified PDF
information when saving the output file
• KeepStatusUnchanged: incoming Certified
PDF documents remain certified; incoming
non-Certified PDF documents remain
uncertified
If a preflight profile is specified for this process,
the default is “MakeCertified"; otherwise the
default is “KeepStatusUnchanged”
optionalbooleanKeepOriginalProfile
optionalUserInfoUserInfo
requiredstringSessionComment
The value of this setting is used only if a
preflight profile is specified for this process
If true, and the incoming Certified PDF file has
an embedded preflight profile, that profile is
used for performing the preflight step instead
of the preflight profile specified for this process
If false (the default), any embedded preflight
profile is removed and replaced by the
preflight profile specified for this process
Information on the user performing this
operation; stored in the Certified PDF data
Description of the operation being performed;
stored in the Certified PDF data
21
PitStop Server
4.19 UserInfo
This element specifies information on the user performing this operation. This information is
stored in the PDF file as part of the Certified PDF data.
DescriptionMultiplicityTypeElement name
User name and contact informationoptionalstringName
optionalstringCompany
optionalstringStreet
optionalstringCity
optionalstringState
optionalstringCountry
optionalstringPostalCode
optionalstringPhone
optionalstringFax
optionalstringEmail
optionalstringMessage
Default value is the empty string for all fields
Comments that may help identify the user or
otherwise assist in the Certified PDF workflow
Default value is the empty string
4.20 ColorManagement
This element specifies settings related to color management.
Color management can be configured separately for images and all other objects (text, line art),
or for all objects (including images) at the same time.
If color management not turned on for a particular object type, the corresponding source and
target ICC profiles are ignored.
22
Multiplicity & DescriptionTypeElement name
Only the following combinations are allowed:ColorManagementSettingsAllObjects
ColorManagementSettingsImages
• Just “AllObjects”: specify the same color
management options for all objects in the file
PitStop Server
ColorManagementSettingsOtherObjects
booleanUseBlackPointCompensation
• Both “Images” and “OtherObjects”: specify
separate color management options for images
and for non-images (text & line-art)
• None of these elements: use the default settings
for all objects in the file
The color management engine to be used; one of:enumerationCMMEngine
• SystemCMM: the platform-specific engine (ICM
on Win32, ColorSync on Mac OS X)
• AdobeCMM: the Adobe CMM engine, if it is
available on the system; if it is not available,
PitStop will return an error if the color
management engine is required during
processing
• LittleCMS: the LittleCMS engine built into PitStop
The default value is SystemCMM
If present and true, Black Point Compensation will
be used. Note that this option is only available for
the Adobe CMM and the Little CMS engine.
4.21 ColorManagementSettings
This element specifies color management settings for a particular category of objects.
DescriptionMultiplicityTypeElement name
optionalbooleanEnabled
If true (the default), color management is
enabled
If false, the remaining settings in this list are
ignored
The output rendering intent; one of:optionalenumerationRenderingIntent
• ObjectDefined (the default): the rendering
intent of the object itself, as shown on the
prepress tab of PitStop Inspector
• Relative: in-gamut colors are reproduced
exactly; out-of-gamut colors are mapped
to the nearest value within the
reproducible gamut; corrections are made
for the output medium's white point
• Absolute: in-gamut colors are reproduced
exactly; out-of-gamut colors are mapped
to the nearest value within the
reproducible gamut; no correction is made
for the output medium's white point.
23
PitStop Server
• Saturation: colors are represented in a
manner that preserves or emphasizes
saturation
• Perceptual: colors are represented in a
manner that provides a pleasing
perceptual appearance
The source ICC profilesoptional (*)ICCProfilesSourceICCProfiles
(*) Required if color management is enabled
ridesICCProfiles
ridesICCProfiles
4.22 ICCProfiles
This element specifies the source or target ICC profiles for a particular category of objects.
Each child element specifies the file path to the default ICC profile for a particular color space.
This ICC profile is used for color converting an object in this color space unless the PDF file explicitly
associates an ICC Profile with the object.
optionalbooleanSourceOutputIntentOver-
optionalbooleanTargetOutputIntentOver-
If true, the rendering intent overrides the
selected ICC profile rendering intent for the
source ICC profiles
The default value is false
The target ICC profilesoptionalICCProfilesTargetICCProfiles
If not provided, the source ICC profiles are
used as target ICC profiles as well
If true, the rendering intent overrides the
selected ICC profile rendering intent for the
target ICC profiles
The default value is false
24
If the ICC Profile for a color space is not provided, the corresponding default Enfocus ICC Profile
is used instead.
DescriptionMultiplicityTypeElement name
Path to ICC Profile for Gray color spaceoptionalPathTypeGray
Path to ICC Profile for RGB color spaceoptionalPathTypeRGB
Path to ICC Profile for CMYK color spaceoptionalPathTypeCMYK
Path to ICC Profile for Lab color spaceoptionalPathTypeLab
4.23 Fonts
PitStop Server
This element specifies settings for loading fonts.
Loading fonts can be quite time-consuming. To optimize performance, turn off system fonts if
they are not needed, and limit additional fonts to those actually used in the job being processed.
DescriptionMultiplicityTypeElement name
optionalbooleanUseSystemFonts
PathTypeAdditionalFolder
zero or
more
If true (the default), the fonts in the system folder
are available for handling fonts during processing
If false; the fonts in the system folder are not
available
Path to a folder containing additional fonts that
should be available for handling fonts during
processing of this task
25
PitStop Server
5. Task Report XML file
5.1 Introduction
When a task report path is specified on the command line or in the configuration file, PitStop
Server CLI creates a task report. By default the task report contains only minimal status
information. However the configuration file can request additional information to be included
in the task report (see chapter on configuration file). Examples include:
• The errors and warnings produced by a preflight operation.
• A list of available preflight profiles.
• Debugging information on the CLA’s execution.
The task report is constructed as a tree of XML elements. The remaining sections in this chapter
describe each element that may appear in the file and its immediate child elements.
Unicode support
The task report is a well-formed XML document using UTF-8 encoding, which means that it fully
supports Unicode for text values such as file names.
XML namespace and schema
The task report generated by PitStopServerCLI uses the default namespace but it also defines the
“tr” prefix to facilitate querying the report with xslt in Switch.
This is a string type representing an absolute file or folder path in the native platform format,
for example:
• On Windows: C:\Preflight\Input\input.pdf
• On Mac OS: /Volumes/Preflight/Input/input.pdf
5.3 TaskReport
This is the root element of the task report file. Its child elements are generated in a logical
execution order, not necessarily in the order presented in the following table.
PitStop Server
DescriptionMultiplicityTypeElement name
The format version of this task reportrequiredintegerFormatVersion
Currently this is always “1”
The exit code returned by the CLArequiredintegerExitCode
This is always present, assuming that
the task report could be created
optionalintegerErrorCode
optionalstringErrorMessage
VersionInfoVersionInfo
VersionInfoLibraryVersionInfo
SupportInfoSupportInfo
CommandLineCommandLine
optional
(if requested)
optional
(if requested)
optional
(if requested)
optional
(if requested)
If the exit code is nonzero, the error
code as written to stdout (assuming that
the task report could be created)
If the exit code is nonzero, the error
message as written to stdout, without
the leading error code and colon
(assuming that the task report could be
created)
Version information on the PitStop
Server CLA generating this task report
Version information on the PitStop
Library used by the PitStop Server CLA
generating this task report
Information useful for support and
debugging purposes
A list of the options received (and
recognized) on the command line
ProcessResultsProcessResults
LanguagesLanguages
zero or more
(if requested)
optionalErrorsErrors
optional
(if requested)
The number of errors, warnings, fixes,
signoffs, failures and critical failures for
each Process task
A list of error and warning messages
encountered during execution
A list of the languages supported by
PitStop Server CLI
27
PitStop Server
CMMsCMMs
MutatorDBDefaultProfileDB
MutatorDBLocalProfileDB
MutatorDBDefaultActionDB
MutatorDBLocalActionDB
MutatorInfoMutatorInfo
optional
(if requested)
optional
(if requested)
optional
(if requested)
optional
(if requested)
optional
(if requested)
zero or more
(as requested)
A list of CMMs supported by PitStop
Server CLI
A list of the preflight profiles in the
default database
A list of the preflight profiles in the local
database
A list of the action lists in the default
database
A list of the action lists in the local
database
Information on a mutator, i.e. a
preflight profile or an action list
5.4 VersionInfo
This element offers version information on the CLA (VersionInfo) or on the associated PitStop
Library (LibraryVersionInfo).
DescriptionMultiplicityTypeElement name
requiredstringDisplayVersion
requiredenumerationBuildType
optionalintegerReleaseNumber
requiredbooleanLicensedState
The version string as it would be displayed to
a user, for example “09 update 2”
The major version number, e.g. “9”requiredintegerMajor
The minor version number, e.g. “2”requiredintegerMinor
The build type; one of: Alpha, Beta,
ReleaseCandidate or Final
The release number; this is not present for
final builds
The internal build sequence numberrequiredintegerBuildNumber
True if fully enabled (during trial period or with
a purchased license); false if expired
28
By definition this value is identical for the CLA
and for PitStop Library
5.5 SupportInfo
This element offers information that is useful for Enfocus technical support. Its content is not
documented and may be changed without notice in future versions of the task report.
5.6 CommandLine
This element lists the values of the command line options as they were recognized by PitStop
Server CLI after merging with the corresponding values in the first Process element and the
TaskReport element in the configuration file.
A child element is not listed if both the command line option and the corresponding value in
the configuration file are missing.
PitStop Server
5.7 ProcessResults
DescriptionMultiplicityTypeElement name
Absolute path to the configuration fileoptionalPathTypeConfig
Absolute path to the PDF input fileoptionalPathTypeInput
zero or morePathTypeMutator
Absolute path to the mutators used for
processing
Absolute path to the PDF output fileoptionalPathTypeOutput
Absolute path to the PDF report fileoptionalPathTypeReportPDF
Absolute path to the PDF report template fileoptionalPathTypeReportPDFTmpl
Absolute path to the XML report fileoptionalPathTypeReportXML
Absolute path to the task report filerequiredPathTypeTaskReport
This element offers information on the results of a process task. A separate ProcessResults element
is provided for each Process element in the configuration file.
DescriptionMultiplicityTypeElement name
Number of errors reported during processingrequiredintegerErrors
Number of warnings reported during processingrequiredintegerWarnings
29
PitStop Server
Number of fixes reported during processingrequiredintegerFixes
Number of sign-offs reported during processingrequiredintegerSignoffs
Number of failures reported during processingrequiredintegerFailures
5.8 Errors
5.9 Error
requiredintegerNonCriticalFailures
This element lists any error and warning messages encountered during execution. There is only
a single “Errors” element, i.e. errors are not split per process or task.
zero or moreErrorError
This element offers information about an error or warning message
Number of non-critical failures reported during
processing
DescriptionMultiplicityTypeElement name
Information about an error or warning
message
DescriptionMultiplicityTypeElement name
The date and time the error or warning occurredrequireddate-timeTimeStamp
requiredstringMessage
optionalintegerErrorCode
optionalintegerSeverity
A message describing the error or warning in
English
An error code corresponding to the error or
warning, if available
An indication of the severity of this error or
warning; higher numbers indicate more severe
errors
The default value is zero, which should be used
for warnings
30
5.10 Languages
This element lists the preflight report languages supported by PitStop Server CLI.
PitStop Server
DescriptionMultiplicityTypeElement name
5.11 CMMs
This element lists the color management engines available to PitStop Server CLI.
5.12 MutatorDB
one or moreenumerationLanguage
one or moreenumerationCMM
One of the supported languages as a
4-character string in the form 'enUS'; 'frFR',
'deDE', ...
English is always available
DescriptionMultiplicityTypeElement name
One of the available color management
engines (SystemCMM, AdobeCMM, or LittleCMS)
LittleCMS is always available
These elements (DefaultProfileDB, LocalProfileDB, DefaultActionDB, LocalActionDB) list the mutators
in one of the predefined databases plus any requested information on these mutators.
5.13 MutatorInfo
This element lists information about a mutator. It can occur in two places:
• As a child of one of the MutatorDB elements.
• As a standalone child of the TaskReport, in response to a QueryMutatorInfo request.
DescriptionMultiplicityTypeElement name
zero or moreMutatorInfoMutatorInfo
Information on one of the mutators in the
predefined database
DescriptionMultiplicityTypeElement name
31
PitStop Server
requiredPathTypeMutatorPath
optionalenumerationMutatorType
optionaldate-timeDateTime
optionalbooleanIsFullyUnderstood
The absolute file path to the mutator
(preflight profile or action list)
The name of the mutatoroptionalstringName
The company of the author of the mutatoroptionalstringCompany
The author of the mutatoroptionalstringAuthor
The description of the mutatoroptionalstringDescription
The mutator type: PreflightProfile or
ActionList
The most recent modification date and
time of the mutator
The version of the mutatoroptionalintegerVersion
True if PitStop Server CLI fully supports all
settings and instructions in this mutator
True if the version of the mutator is correctoptionalbooleanIsVersionCorrect
optionalbooleanIsConfigurationCorrect
True if the configuration of the mutator is
correct
32
6. Task identifiers
6.1 Introduction
Logical order
Information in the task report is generally listed in a logical order. For example:
• ProcessResults elements in the task report are listed in the same order as the corresponding
Process elements in the configuration file.
• MutatorInfo elements in the task report are listed in the same order as the corresponding
QueryMutatorInfo elements in the configuration file.
Still it is not trivial to locate the information associated with a particular task or query.
PitStop Server
Task identifiers
Task identifiers help locate information in the task report as follows:
• Selected elements in the configuration file allow an XML attribute called “TaskID” which can
have an arbitrary string value.
• If a TaskID attribute is specified in the configuration file, the corresponding elements in the
task report also have a TaskID attribute with the same value.
Thus one can locate information in the task report simply by locating elements with the
appropriate value for the TaskID attribute.
XML namespace
The TaskID attribute has no namespace prefix.
Empty value
Specifying an empty TaskID attribute value is equivalent to specifying no TaskID attribute, and
vice versa.
6.2 Supported elements
The following table presents the list of elements in the configuration file supporting the TaskID
attribute, and the corresponding elements in the task report that “inherit” the value of the
TaskID attribute.
Task report elements inheriting TaskIDConfiguration elements supporting TaskID
ErrorInitialize
33
PitStop Server
ProcessResults, ErrorProcess
MutatorInfo, ErrorQueryMutatorInfo
Specifying a TaskID attribute on any other element has no effect.