How it Works
Enfocus software
Loading...
PITSTOP SERVER 10
COMMAND LINE INTERFACE
40 pgs712.88 Kb0
Table of contents
Loading...

Enfocus software PITSTOP SERVER 10 COMMAND LINE INTERFACE

Command Line
Interface

Contents

1. Copyrights.........................................................................4
2. Introduction......................................................................5
PitStop Server
2.1 Short summary..................................................................................5
2.2 Objectives........................................................................................5
Terminology.................................................................................5
Target group................................................................................5
Ease of use..................................................................................5
Distribution.................................................................................5
Multiple invocations......................................................................6
3.1 Command line options........................................................................7
Syntax.........................................................................................7
Overview.....................................................................................7
Configuration...............................................................................7
Process.......................................................................................8
Task report..................................................................................8
Admin........................................................................................9
Use cases....................................................................................9
3.2 Exit behavior...................................................................................10
Exit code....................................................................................10
Error message.............................................................................10
Error codes.................................................................................10
3.3 Default values.................................................................................10
General rule...............................................................................10
System fonts................................................................................11
4.1 Introduction....................................................................................12
Ordering of XML elements...............................................................12
Unicode support..........................................................................12
XML namespace and schema...........................................................12
4.2 PathType........................................................................................12
4.3 Configuration..................................................................................13
4.4 Versioning......................................................................................13
4.5 Initialize........................................................................................14
Other information........................................................................14
4.6 TaskReport.....................................................................................14
4.7 QueryMutatorDB...............................................................................16
4.8 QueryMutatorInfo............................................................................16
2
Contents
4.9 Process..........................................................................................17
4.10 InputPDF......................................................................................18
4.11 OutputPDF.....................................................................................18
4.12 SaveOptions...................................................................................19
4.13 Reports.........................................................................................19
4.14 ReportPDF.....................................................................................19
4.15 ReportXML.....................................................................................20
4.16 TransparencyFlattening....................................................................20
4.17 Mutators.......................................................................................20
4.18 CertifiedPDF...................................................................................21
4.19 UserInfo........................................................................................22
4.20 ColorManagement..........................................................................22
4.21 ColorManagementSettings.................................................................23
4.22 ICCProfiles.....................................................................................24
4.23 Fonts...........................................................................................25
5. Task Report XML file...........................................................26
5.1 Introduction...................................................................................26
Unicode support..........................................................................26
XML namespace and schema..........................................................26
5.2 PathType........................................................................................26
5.3 TaskReport......................................................................................27
5.4 VersionInfo....................................................................................28
5.5 SupportInfo....................................................................................29
5.6 CommandLine................................................................................29
5.7 ProcessResults.................................................................................29
5.8 Errors...........................................................................................30
5.9 Error.............................................................................................30
5.10 Languages.....................................................................................31
5.11 CMMs............................................................................................31
5.12 MutatorDB.....................................................................................31
5.13 MutatorInfo....................................................................................31
6. Task identifiers.................................................................33
6.1 Introduction...................................................................................33
Logical order...............................................................................33
Task identifiers............................................................................33
XML namespace...........................................................................33
Empty value...............................................................................33
6.2 Supported elements.........................................................................33
7. Appendix.........................................................................35
7.1 Example Configurations......................................................................35
Windows...................................................................................35
OS X..........................................................................................38
3
PitStop Server

1. Copyrights

©
2010 Enfocus NV all rights reserved. Enfocus is an EskoArtwork company.
Certified PDF is a registered trademark of Enfocus NV; patent pending.
Enfocus PitStop Pro, Enfocus Workgroup Manager, Enfocus PitStop Server, Enfocus PitStop Connect, Enfocus Instant PDF, Enfocus StatusCheck, Enfocus CertifiedPDF.net, Enfocus Instant Barcode, Enfocus PitStop Extreme, Enfocus PDF Workflow Suite, Enfocus LightSwitch, Enfocus FullSwitch, Enfocus PowerSwitch, Enfocus SwitchClient and Enfocus SwitchScripter are product names of Enfocus NV.
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.
PANTONE®and other Pantone, Inc. trademarks are the property of Pantone, Inc.©Pantone, Inc.,
2006.
OPI is a trademark of Aldus Corporation.
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.

XML namespace and schema

4.2 PathType

http://www.enfocus.com/2010/PitStopServerCLI_ConfigurationXML namespace
cf (or use default namespace)Preferred prefix
PitStopServerCLI_Configuration.xsdSchema definition
12
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
Loading...
+ 28 hidden pages
Buy Points How it Works FAQ Contact Us Questions and Suggestions Privacy Policy Cookie Policy Terms of Use