84
3-Heights™ Document Converter, Version 4.6
Page 42 of 90
January 25, 2016
© PDF Tools AG - Premium PDF Technology
single dedicated worker instance per
WorkerServer/WorkerUserName pair
4
TempDirectory
The absolute path to an existing directory
that is accessible for both the dispatcher
service and the worker session. A UNC path
can be specified, if these programs execute
on different computers.
If this entry is missing, the system
default temporary directory is used.
CleanupTemp
*
Periodically clean up left-over files in
the TempDirectory folder.
DisableLogonMessage *
Temporarily disable the interactive logon
message configured on the server during
starting worker sessions.
RunDisconnected
*
Automatically disconnect the worker session
once it is established. This is useful on
Server 2008 platforms, as disconnected
sessions do not count towards license based
limits.
LogFile
C:\o2psrv.log
The absolute path of the log file to be
written.
LogLevel
2
The log level controls filtering of log
messages. Debug=1, Info=2, Error=3
SvcLogLevel
3
The log level controlling service log
entries into the system event log.
WorkerLogLevel
(none)
Set the log level for PDF and raster image
processing work performed in-process by the
dispatcher service. Default: no logging
WorkerLogFile
C:\o2psrv-w.log
File containing log entries from PDF and
raster image processing work, including
OCR. These entries are more detailed than
the log entries generated in the standard
o2psrv.log
LogUTC
False
Print date/time information in UTC rather
than local time.
StartupDelay
30
Time span in seconds to wait after starting
the service before attempting to start the
worker sessions.
Use of this feature helps to avoid session
startup problems after booting due to
system overload.
Note: specifying “nodelay” as the first
parameter when starting the service will
disable the configured StartupDelay.
WorkersBusyTimeout 30
Timeout period to wait for when all worker
sessions are busy before returning an
error.
WorkerConcurrency
1
Limit for the number of concurrent
conversions dispatched to any worker
session. Note: increasing this number can
result in stability problems with Microsoft
* The default value for a missing configuration is “false”; however, the default
configuration comes with a value of “true”.
4
See http://support.microsoft.com/kb/291636; the Outlook application can be opened
only once by a specific user on a terminal server.
67
3-Heights™ Document Converter, Version 4.6
Page 43 of 90
January 25, 2016
© PDF Tools AG - Premium PDF Technology
Office applications. The recommended way to
increase concurrency for the conversion of
office documents is to increase the number
of worker sessions (see WorkerCount).
WorkerTimeLimit
600
Time limit in seconds for performing the
conversion of a document by a worker. The
service will forcibly logoff the worker’s
session when reaching this limit (and then
restart a new session).
NOTE: when setting the TempDirectory and LogFile values, consider the security
settings for the account under which the Dispatcher Service is running. Depending on
the account under which the service runs, it may not have any write privilege unless you
explicitly grant it.
Worker Instance Suffix: each of the worker session related settings can be
individually configured by adding the instance suffix to the corresponding key.
Examples: WorkerUserName1, WorkerPassWord1, RestartHours1, WorkerServer1, etc.
4.3
O2PWSC.exe.config
This section lists the configuration entries that apply to the worker session control
program O2PWSC.exe:
Name
Default Value
Description
ServiceHost
localhost
The computer name or network address
for binding to the dispatcher
service.
ServicePort
7981
The port number configured for the
dispatcher service (see 4.2)
DispatcherAliveCheck 60
Time interval in seconds for calling
the dispatchers “AreYouStillAlive”
method. Specify the value “false” to
disable this feature.
LogFile
C :\o2pwsc-%ID-
%Y%M%D.log
The absolute path of the log file to
be written.
%ID is a place holder for the
instance number of the worker
session.
%Y %M and %D are place holders for
the current date, i.e. year, month
and day.
LogLevel
2
This value controls the level of
details to be logged.
1: debug + below
2: informational + below
3: warnings + errors
4: errors only
4.4
O2PWFS.exe
O2PWFS.exe is the watched folder executable. It actually constitutes a client application
of the Document Converter. It uses the client API DLL (O2PProxyAPI.DLL) that itself
relays any documents passed for processing to the (possibly remote) service.
47
3-Heights™ Document Converter, Version 4.6
Page 44 of 90
January 25, 2016
© PDF Tools AG - Premium PDF Technology
4.4.1 O2PWFS.ini
The O2PWFS.INI file contains the entries that configure the watched folders and their
corresponding processing options.
Here is a sample INI file:
[O2PWFS]
ServiceHost = localhost
ServicePort = 7981
AutoDelete = false
JobPrefix = false
Threads=1
Thread1=-w d:\DocConverter –j PDFA –b Outline –o “C:\Temp”
:\Temp”
”
The O2PWFS section consists of some global settings affecting all watched folders, such
as
AutoDelete (delete input files of successfully converted documents)
AutoDeleteAll (delete input files of failed jobs)
JobPrefix (rename files to contain a unique job specific prefix)
PollingInterval (milliseconds between file searches)
LogLevel (1: log errors only; 0: informational log)
KeepTimeForSucceeded (hours until files are deleted; unspecified or 0=never)
KeepTimeForFailed
(hours until files in failed folder are deleted; 0=never)
LogPath (file path for log file)
WorkerThreads (maximum number of concurrent worker threads; use this to control
the maximum load on the Document Converter)
The first two entries, ServiceHost and ServicePort, refer to the Document Converter
instance that shall serve the document conversion requests. The value specified for
ServiceHost is the computer name or network address where the Document Converter is
hosted; “localhost” is a common network name alias referring to the local computer.
ServicePort is the port number configured for the Converter Service (usually 7981).
For each watched folder there is thread entry, starting with Thread1, Thread2 etc. The
total number of threads or watched folders is specified with the Threads entry.
The value after the “-w” option specifies the path to the watched folders where
documents (or conversion jobs) will be picked up.
The -j option takes optional job options as explained in section 5.4.
The -o option can be used to specify the directory location for storing result PDF files
(the default being the sub-folder “PDFs” or “TIFFs” in the watched folder specified with
the option -w). A folder relative to the pickup/drop directory is specified by prefixing the
folder name with a colon (e.g. “:PDFA”).
Other options are
-wd set drop directory
-wfs Select only files with certain extensions (Example: -wfs .pdf.tiff)
46
3-Heights™ Document Converter, Version 4.6
Page 45 of 90
January 25, 2016
© PDF Tools AG - Premium PDF Technology
-wfi Ignore files with certain extensions (Example: -wfi .tmp.temp)
-R also search in subfolders of drop directory, and store output in corresponding
subfolder of output directory.
-l
create an error log file in case of errors during the conversion process. The file will
be located in the output directory.
-b document options (see 5.4.1.4 Document Conversion)
-os set directory for succeeded jobs (default: “Succeeded” below thread folder
specified by –w). A folder relative to the pickup folder can also be specified by prefixing
the folder name with a colon.
-o0 Keep any conversion output despite errors or warnings during conversion
-o1 Store another copy of the output in a second folder specified as the argument to
this option
-o2 always move job input file to ‘Success’ folder (in addition to the copy sent to the
‘Failed’ folder)
-op remove job prefix of output file after conversion
-ow ignore PDF/A conversion warnings, accepting the PDF/A validated output despite
possible changes of page content (e. g. removal of transparency)
-owf
ignore any warnings (related to PDF/A conversion or parts that are not
convertible), but move the result to the specified folder
-ox Specify a name pattern for the index file path to be used with option -1 an -1l. A
relative path can be specified and will be based on the output folder for the conversion
job. The placeholder * will be substituted by the job’s name. Example: -ox
C:\Completed-IDX\*.txt
-1 store TIFF result in a collection of single page TIFF files. In addition, a file with
ending .idx is created that contains the names of the single page files.
-1l like -1, but store the full file path in the .idx file
-di Delete the input file(s) listed in job control files.
-u set the “ZIPPED” job setting and store each entry of the output archive in a
subfolder of the output directory.
Please refer to section 2.3.5 Post Installation for Client Components for more
information about these options.
Remarks:
The input file will be moved to the “Failed” folder in case of a failed conversion. An
output file may still be stored in case of non-fatal errors (such as PDF/A conversion
issues).
4.4.2 Implementation Limits
The Watched Folder Service has the following implementation limits:
Maximum name length for input documents: limited by Windows (260 characters)
Maximum name length of output documents: limited to 160 characters, unless option –u
is specified. With –u, there is a limit of 80 characters for the output folder, and 80
34
3-Heights™ Document Converter, Version 4.6
Page 46 of 90
January 25, 2016
© PDF Tools AG - Premium PDF Technology
characters for the names of files stored in that folder (file extensions included; the
significant part of the names will be less).
There is no hard limit for the maximum number of watched folders; however, file search
overhead will increase with the number of watched folders. The number may exceed a
few hundred for folders on a local disk, but should be significantly less for network
shares.
Processing of documents from a specific folder is performed sequentially. If you need to
increase throughput, create multiple folders and distribute documents equally.
4.5
Mail Folder Service
When so selected during MSI based installation, the “O2PMFS” service is installed,
showing as “3-Heights™ Mail Converter Service” in the services list of the system
management console. This service features the conversion of e-mail messages to PDF/A
or TIFF – directly from mail folders on a mail server.
4.5.1 O2PMFS.ini
The O2PMFS.ini file contains the configuration information for the mail folder service. Its
syntax and options are very similar to the O2PFWS.ini file.
Please use the configuration editing tool (O2Pconfigure.exe) to edit this configuration
file.
To configure non-standard ports for IMAP or SMTP connections as well as SSL/TLS,
append a colon followed by the port number to the server name. For SSL, add a small
letter s; to configure SSL with STARTTLS, add a capital letter S. To configure Microsoft’s
Live Mail server for example, specify “smtp.live.com:587S” (smtp.live.com is the
network name, 587 the port number, and S indicates that “StartTLS” shall be used).
Note: passwords for mail accounts are encrypted in the configuration file.
4.5.2 Requirements and Limitations
The only protocol to access a mail server directly is via IMAP. SSL is supported. For
authentication, only plain text is supported.
As IMAP does not support locking, make sure that folders watched by the service are
not simultaneously accessed and modified by users or another instance of the service.
71
3-Heights™ Document Converter, Version 4.6
Page 47 of 90
January 25, 2016
© PDF Tools AG - Premium PDF Technology
5
Reference Manual
5.1
Document Type Index
The Document Converter contains a number of standard modules for controlling external
document authoring applications as well as built-in support for PDF and raster images.
Application/Format
Section Name
Scope Name
Microsoft Outlook
Outlook
Outlook
Microsoft Word
MSWord
MSWord
Microsoft Excel
Excel
Excel
Microsoft PowerPoint
PowerPoint
PowerPoint
Microsoft Visio
Visio
Visio
Microsoft Project
MSProject
MSProject
OpenOffice
OO
OO
PDF
built-in
PDF
Internet Mail Messages
Eml
Eml
JPEG, TIFF, GIF, BMP, PNG images
built-in
Image
http/HTML based Web page
HTML
HTML
Text (ANSI, UTF-8, Unicode)
TXT2PDF
TXT2PDF
XML Paper Specification
XPS
XPS
Windows Enhanced Metafile
EMF
EMF
The “Section Name” column refers to the configuration section in the INI file (see 4.1).
The “Scope Name” column refers to the document level options scope according to
section 5.4.1.5.
5.2
Document Extensions Index
The application used for converting a particular document is selected according to the
document format. In a first attempt, document formats are determined based on the file
extension. In most cases, the file extension corresponds to the actual document’s
format. If the extension is unknown or incorrect, the Document Converter tries to guess
the document format from the file header, and finally tries to open the document with
each application.
The following table lists the file extensions registered for the supported applications. Any
plug-in registered with the Document Converter extends this table with their proprietary
extensions.
Application
Extension
58
3-Heights™ Document Converter, Version 4.6
Page 48 of 90
January 25, 2016
© PDF Tools AG - Premium PDF Technology
Microsoft Outlook
.msg
Microsoft Word
.doc .docx .rtf .txt .htm .html .wpd .wpc .ws
Microsoft Excel
.xls .xlt .xlsx .xlsm .xlsb
Microsoft PowerPoint
.ppt .pps .pptx .pptm .ppsx .ppsm
Microsoft Visio
.vsd .vsdx .vsdm .vdx .vssx .vssm .vss .vsx .fstx .vstm .vst
.vtx .vsw .vdw .svg .svgz
Microsoft Project
.mpp
Internet
Mail
Messages
.eml
OpenOffice.org
.odf .odg .odp .ods .odt .sxw .sxi .sxc
Raster
image
formats
.jpg .jpeg .bmp .gif .tif .tiff .jb2 .jp2 .png
http/HTML
.url .mht .htmzip
ZIP Archives
.zip
RAR Archives
.rar
Text
.txt .log .ini
XML
Paper
Specification
.xps
Enhanced Metafile
.emf
Note: if TXT2PDF is enabled, the extensions .txt, .log and .ini are no longer associated
with MS Word (unless done so explicitly in O2PWSC.ini).
5.3
Processing Paradigm
The Document Converter supports processing for single documents and also for
converting multiple documents into a single output PDF. For the latter purpose, the
Document Converter features the job paradigm.
Processing starts with the creation of a job. At this time, the name of the output PDF is
specified, and any job specific options are passed. Following that, documents are added
one by one to be converted to PDF and appended to the output PDF.
Single document and job processing modes work interleaved, because any single
document can actually be an aggregate5, containing internally multiple documents of
potentially different types, and job processing builds on top of the conversion of
individual documents.
When passing documents for processing, they can be accompanied by document related
options. For detailed information on job and document level options, see section 5.4.
5 Examples for aggregate documents are e-mails with attachments or ZIP files
52
3-Heights™ Document Converter, Version 4.6
Page 49 of 90
January 25, 2016
© PDF Tools AG - Premium PDF Technology
5.4
Conversion Jobs
Conversion jobs are the common paradigm for the Watched Folder Service
(O2PWFS.EXE), the Command Line Tool (O2PCLIENT.EXE), and also the Application
Programming Interface (O2PProxyAPI.DLL). The two executables actually build on top of
the API DLL.
5.4.1 API
O2PProxyAPI.DLL incorporates programming interfaces for COM and C.
5.4.1.1 Initialization
COM
Set oConverter = CreateObject(“O2Pconverter.Iconverter”)
.NET
using Pdftools.Converter;
IconverterService converter = ConverterFactory.GetInstance(null);
C
#include “o2pproxyapi_c.h”
O2Pconverter hConverter = O2PcreateConverter(0);
During creation of the Converter object, the API attempts to connect to the Document
Converter. The location URL can be passed to the API when using the .NET or C
interfaces. When a null pointer is specified (or during construction of the COM object),
the API tries to retrieve the URL from the application’s configuration file. If this fails, the
default URL is used (tcp://localhost:7981/O2Pservice).
De-initialization is performed implicitly with the .NET and COM interfaces when the last
reference to the object is released. When using the C interface, the
O2PdestroyConverter function is called.
5.4.1.2 Job Creation
COM
Set oJob = oConverter.CreateJob
.NET
Ijob job = Converter.CreateJob();
C
O2Pjob hJob = O2PconverterCreateJob(hConverter);
Prior to perform any job related processing, the application obtains a job object as
shown above.
5.4.1.3 Setting Job Options
COM
oJob.SetOptions(“PDFA=true;”)
.NET
job.SetOptions(“PDFA;”);
C
O2PjobSetOptions(hJob, “PDFA”);
Job options can be set any time and will replace any options that have been set
previously.
The options string is composed of a sequence of semicolon separated key-value pairs,
where key and value are separated by an equal sign. Note that in the sample code
above, the option key is “PDFA” whose value can be either true or false. For setting a
true value, it is sufficient to just list the key value. Therefore, all three option strings
have the same effect. The terminating semicolon is not necessary.
57
3-Heights™ Document Converter, Version 4.6
Page 50 of 90
January 25, 2016
© PDF Tools AG - Premium PDF Technology
The following options are supported:
Key
Description
PDFA
Values “true” or “false”. When “true” is set, the resulting PDF
will conform to the PDF/A standard.
PDFA.ERROR
Values “true” or “false”. When “true”, return detailed error
information from PDF/A conversion.
PDFA.LOGSUMMARY When “true”, include summary information in error text.
Default: PDFA.ERROR setting
PDFA.LOGDETAILS
When “true”, include detail information in error text. Default:
PDFA.ERROR setting
PDFA.XMPWARNINGS Raise a conversion error if the XMP Metadata was changed in
order to achieve PDF/A conformance
PDFA.WARNCOLL
Default “true”; warn, if an input PDF contains embedded files
that need to be removed for PDF/A-1 compliance
PDFA.WARNOCSP
Default “false”, warn on failure to embed the OCSP response or
time stamp for a signature
PDFA.SUBSET
Do subset those fonts that are being embedded during PDF/A
conversion. Default TRUE.
Setting this option to FALSE may produce potentially much
larger PDF/A output files; however, these files may be easier to
enhance or modify later on. Warning: all fonts used in
documents converted with this setting must be installed on the
server to obtain correct output!
PDF.COMPLIANCE
Required (minimum) compliance level (for PDF/A conversion).
Default: “1AB”
A compliance is defined by values: “1A”, “1B”, “2A”, “2B”, “2U”,
“3A”, “3U”, “3B”
Additionally a fall-back value can be defined. So if you prefer
“1A”, but will also accept “1B” in cases where “1A” is not
possible, you can define “1AB”.
“1A”: raise an error if tagging information is missing
“1B”: produce PDF/A-1b output, even if structure tags are
available.
“1AB”: try to create PDF/A-1a; degrade to PDF/A-1b if tagging
g
information is missing
“2A”: produce PDF/A-2a (or fail)
“2UB”: produce PDF/A-2u or – if text encoding information is
is
missing – PDF/A-2b
2b
“2AUB”: produce the ‘best possible’ PDF/A-2 output
PDF.Embed
When converting multiple documents, embed any but the first
document into the resulting PDF document as document level
Documents you may be interested
Documents you may be interested
