DCSConvertFolder

DCSConvertFolder

A command line utility to walk a folder and convert all files, or all files matching a search filter, using Document Conversion Service. The utility can optionally also process all subfolders under the starting folder as well. The Document Conversion Service must be running, either locally or on a remote computer for the files to be converted.  If it is not running the command will return immediately with an error.

Any sorting options applied only control the order in which the files are picked up from the directory. Sorting does not guarantee the order the files are processed in, only that files sorted to the top of the list are submitted for conversion first. A smaller file further down the list might finish before a larger file that was first in the list.

 

DCSConvertFolder /P=profile [/R] [/F=filter] [/X=exclude filter] [/S=save location]

                 [/O] [/NE] [/L] [/D="name:value"] [/E=extension map]

                 [/FAIL=failed results log file location] [/SIL=conversion log file path] 

                 [/W=wait time] [/C=remote computer name;remote scratch folder] 

                 [/T=alternate temp folder]

                 [/NAME=sort files by name] [/CREATED=sort files by creation date]

                 [/MODIFIED=sort files by name] [/DESC=sort files in descending order (Z-A, 9-0)]

                 folder

 

Sample Command Lines

Convert all files in a folder to TIFF images:

DCSConvertFolder /P="TIFF 200dpi Monochrome" "C:\Test\Input"

Sends all files in the folder C:\Test\Input to Document Conversion Service to be converted using the settings contained in the conversion profile TIFF 200dpi Monochrome.xml. Any folders under C:\Test\Input are not processed.

Upon successful conversion each output file is placed in a folder named .converted created under the C:\Test\Input folder. Each output file is named using the base name and file extension of the original file, plus the extension of the file type you are creating.

If a file of that name already exists in the .converted folder the conversion will fail and a .failed folder will be created under the C:\Test\Input folder. A results log file, ending with .failed.dcsresults, is created for each failed file and saved to a new subfolder under the .failed folder. The subfolder is named using the date and time of the conversion to keep subsequent runs separate.

 

Convert all files in a folder to TIFF images, wait up to 5 minutes for the conversion service to start:

DCSConvertFolder /P="TIFF 200dpi Monochrome" /W=300 "C:\Test\Input"

Sends all files in the folder C:\Test\Input to Document Conversion Service to be converted using the settings contained in the conversion profile TIFF 200dpi Monochrome.xml. Any folders under C:\Test\Input are not processed.

If Document Conversion Service is not running, wait up to 5 minutes (300 seconds) for the conversion service to be available.

 

Convert all files in a folder, including subfolders, to TIFF images in a specific location:

DCSConvertFolder /R /P="TIFF 300dpi OptimizedColor" /S="C:\Test\Output"

                 "C:\Test\Input"

Walks the folder C:\Test\Input and any folders underneath and sends all the files found to Document Conversion Service to be converted using the settings contained in the conversion profile TIFF 300dpi OptimizedColor.xml.

Upon successful conversion each output file is placed in the C:\Test\Output folder in a directory structure that mirrors the source folder directory structure.

If a file does not convert, a subfolder named .failed is created in the same location as the input file. A results log named by appending .failed.dcsresults to the input file name is created and saved to a new subfolder under the .failed folder. The new subfolder is named using the date and time of the conversion to keep subsequent runs separate.

To store all of the failed file information in a separate location, see the /FAIL option.

 

Convert all Word and Excel files in the folder, including subfolders, to vector PDF documents in a specific location:

DCSConvertFolder /R /F="*.doc|*.docx|*.xls|*.xlsx" /X="12-01*" /S="C:\Test\Output\"

                 /P="C:\Test\Adobe PDF Multipage.xml" "C:\Test\Input"

Walks the folder C:\Test\Input and any folders underneath and sends all Word files ending in .doc and .docx and all Excel files ending in .xls and .xlsx to Document Conversion Service to be converted to vector PDF using the settings contained in the conversion profile Adobe PDF Multipage.xml. Any files or folders that begin with "12-01" are excluded.

Upon successful conversion each output file is placed under the C:\Test\Output folder in a directory structure that mirrors the source folder directory structure.

Failed conversion results logs are is saved in a .failed folder created in the same location as the source file. A results log named by appending .failed.dcsresults to the input file name is created and saved to a new subfolder under the .failed folder. The new subfolder is named using the date and time of the conversion to keep subsequent runs separate.

 

Convert a folder of documents to vector PDF, overwrite any existing files, and save the results log:

DCSConvertFolder /P="Adobe PDF Multipage" /O /L "C:\Test\Input"

Sends all files in the folder C:\Test\Input to Document Conversion Service to be converted to vector PDF using the settings contained in the conversion profile Adobe PDF Multipage.xml. Any folders under C:\Test\Input are not processed.

Upon successful conversion each output file is placed in a folder named .converted created under the C:\Test\Input folder. Any files of the same name that already exist in that folder are overwritten.

A conversion results log file for each file converted will be also be saved in the .converted folder. The name of the results log file is based on the name of the original source file appended with .succeeded.dcsresults.

Failed conversion results logs are saved in a .failed folder created in the same location as the source file. A results log named by appending .failed.dcsresults to the input file name is created and saved to a new subfolder under the .failed folder. The new subfolder is named using the date and time of the conversion to keep subsequent runs separate.

 

Convert a folder of documents to vector PDF, strip off the source extension and save the output and results log files to a specific location:

DCSConvertFolder /R /P="Adobe PDF Multipage" /NE /S="C:\Test\Output"

                 /L /FAIL="C:\Test\FailedResults\\" "C:\Test\Input"

Walks the folder C:\Test\Input and any folders underneath and creates vector PDF files from all documents found. The type of PDF created is controlled by the settings in the conversion profile Adobe PDF Multipage.xml.

Upon successful conversion each output file is placed under the C:\Test\Output folder in a directory structure that mirrors the source folder directory structure. The /NE flag causes the output file to be named using the base name of the original file, plus the extension of the file type you are creating. If a file of that name already exists in the folder the conversion will fail.

A conversion results log file for each file will be also be saved in the C:\Test\Output folder in the same mirrored directory structure.The name of the results log file is based on the original source file and appended with .succeeded.dscresults to indicate its conversion status.

If the conversion did not succeed, the results log is named by appending .failed.dcsresults to the input file name and placing this file into a subfolder named with the current date and time created under the specified folder C:\Test\FailedResults.

Note: The double ending backslash used when specifying the folder for the /FAIL switch is required for the command line path to be parsed correctly.

Use the command line argument D="UseDateTimeInFailedFolder:FALSE" to store the results log file directly in the folder C:\FailedResults.

 

Controlling the Number of Documents Processed in Parallel

When converting a folder of files, the number of documents that can be passed in parallel (at the same time) to Document Conversion Service to be converted is automatically determined based on the number of CPU's and cores on your system multiplied by 1.5. We recommend that you allow this value to be determined automatically, but if needed, you can specify exactly how many documents you want to process in parallel by adding the following line into the profile you are using.

 

Please note that this value is completely separate from the value of the same name used by the Document Conversion Service configuration. Also, keep in mind that setting this to a value that is too high for the capabilities of the computer can cause the computer to work very slowly.

 

<add Name="NumberOfDocumentsInParallel" Value="10"/>

 

You can also pass this directly on the command line using the /D option.

 

DCSConvertFolder /P="TIFF 200dpi Monochrome.xml" /D="NumberOfDocumentsInParallel:6"

                 "C:\Test\Input"

 

Command Line Arguments

Command line switches are not case-sensitive and can be entered in either upper or lower case.

/R - Include Subfolders (Recurse)

Use this switch to also search any subfolders under the source folder when building the list of files to be passed to Document Conversion Service to be converted.

 

/F - File Filter

A filter can be provided using this switch to only process certain types of files. Multiple file filters can be combined using the pipe (|) character. Hidden and system files are ignored, and the search pattern filters files based on a regular expression match of the long name of a file.

When this switch is not specified all files in the folder are (*.*) passed to Document Conversion Service to be processed.

Examples:

Convert PDF only: /F="*.pdf"

Convert Word, Excel and PDF only: /F="*.doc|*.docx|*.xls|*.xlsx|*.pdf"

Convert all Word files starting with MEMO: /F="MEMO*.doc"

 

/X - Exclude File Filter

A exclude file filter can be provided to take the returned file list gathered using the /F file filter and exclude any files that match a pattern. Multiple patterns can be combined using the pipe (|) character.By default no files are excluded.

Examples:

Exclude Word and Excel 2010 documents: /X="*.docx|*.xlsx"

Exclude all files starting with "Draft": /X="Draft*.*"

 

/S - The Save Location

Pass in the full path to the folder in which to save the new files.  If the /R switch is used the original directory structure is maintained.

If the path includes spaces it must be enclosed in quotes.

If the path is specified but doesn't exist, the conversion will fail.

If a file of the same name already exists in the save file location, the conversion will fail. The /O option can be used to enable file overwriting, which is off by default.

 

If this argument is not specified, a .converted folder is created in the same location as each source file and all output files are saved there. On subsequent processing of the same folder with the /R switch enabled, any .converted folders are ignored.

Example:

/S="C:\Converted Files\Test"

 

/O - Overwrite Always

Enables overwrite mode so that existing files of the same name are overwritten with the new file. If the overwrite switch is not specified, the conversion of that file in the list of files will fail if a file of the same name already exists in the output folder.

 

/NE - No Extension

Specify this option if you do not want the original file name extension as part of your output file name. Normally the name of the each output file is created using the base name and file extension of the original file to prevent name collision when you have two files in the folder with the same base name.

 

/L - Results Log

The results log file is an XML file containing a complete snapshot of the conversion information for each file converted. Normally only saved for failed conversions, the /L argument enables creation of the results log file when the conversion succeeds. The results log file is placed in the same location as the converted files.

The name of the results log file is based on the name of the original file and also indicates the conversion status. For example, when converting Document.doc, a successful conversion will create a log file named Document.doc.succeeded.dcsresults, while a failed conversion would be named Document.doc.failed.dcsresults.

The results log file for a successful conversion is always copied to the output location with the converted files when this flag is used.

In the case of a failed conversion, the log file is always created. See the /FAIL switch to control the location and creation of the failed results log files.

The result log files can later be passed to the DCSExtractResults command line utility to extract information such as all files created or any errors encountered during conversion. You can search a folder for the results log files using the DCSCreateFileList utility.

 

/FAIL - Failed Results Log File Location

In the case of a failed conversion, the conversion results log file is always created. The default behavior is to create a .failed folder in the same location as the source file and save the conversion results log file to a new subfolder under the .failed folder. The subfolder is named using the date and time of the conversion to keep subsequent runs separate.

This argument allows you to override the default use of the .failed folder and to provide a specific folder in which to store the failed results log files. The name of the results log file is based on the name of the original file and also indicates the conversion status. For example, when converting Document.doc, a failed conversion would be named Document.doc.failed.dcsresults.

You can suppress the use of the date and time subfolder by passing the UseDateTimeInFailedFolder setting using the /D switch.

Note: The double ending backslash used when specifying the folder for the /FAIL switch is required for the command line path to be parsed correctly.

Examples:

/FAIL="C:\ConvertedFiles\Failed\\" /D="UseDateTimeInFailedFolder:FALSE"

 

If you do not want to create the failed results log files at all, you can use the /D switch to pass the KeepFailedItemResultsFiles setting as false.

On the command line:

/D="KeepFailedItemResultsFiles:False"

 

In a conversion profile:

<add Name="KeepFailedItemResultsFiles" Value="False"/>

 

The result log files can later be passed to the DCSExtractResults command line utility to extract information such the source file used or any errors encountered during conversion. You can search a folder for the results log files using the DCSCreateFileList utility.

 

/P - Conversion Profile

This is a required argument. The type of file created is controlled by supplying a conversion profile using this switch. The profiles are referenced by passing in the name of the profile XML file, with or without the XML extension. See Creating and Customizing Profiles for more information about the contents of the profiles, a list of profiles included with Document Conversion Service, and how to create your own.

Examples:

/P="TIFF 300dpi Color Fax"

/P="TIFF 204x196dpi Monochrome Fax.xml"

 

/D - Define Setting

Individual profile settings can be supplied on the command line using this switch. This switch can be specified multiple times for separate settings and any settings passed here will override the settings in the profile.

Any name-value pair that can be written in a profile can be passed through this parameter. This includes options to control the conversion settings as well as the behavior of the individual converters as well. See Creating and Customizing Profiles for more information about the name-value pairs that can be used.

Examples:

These first two are settings that control the converter options, such as what pages to print, and the output that PowerPoint will print.

/D="PrintRange:1-5"

/D="PowerPoint.PrintOptionsOutputType:PrintOutputNotesPages"

 

These two settings control the output file creation options, and would override or add to the settings in the conversion profile passed using the /P switch.

/D="Image Options;Fax Resolution:3"

/D="TIFF File Format;BW compression:Group3-2D"

 

These two settings control where the failed results log files are created and are most often used along with the /FAIL switch to control where the results log files are saved.

/D="KeepFailedItemResultsFiles:TRUE"

/D="UseDateTimeInFailedFolder:FALSE"

 

/E - File Extension Mapping

A file extension mapping profile uses the extension of the source file to determine what converter will be used to convert the file. Like the conversion profiles, this file is also an XML file. This switch is optional and an internal default mapping is provided. You would only need to provide this file if you wanted to override the default file extension to converter mappings provided.

Examples:

/E="Custom Extension To Converter Map"

 

/W - Wait Time

Use this switch wait to the specified number of seconds for the Document Conversion Service to be running and available to convert documents. If Document Conversion Service is already running the command executes immediately. If the Document Conversion Service is not running in the timeout period specified, the command will return with an error.

If this argument is not specified the command will return immediately with an error if Document Conversion Service is not running.

Example:

/W=300

 

/C - Convert on a Remote Computer (DCOM)

If Document Conversion Service is running on a different computer, use this switch to pass the name of the remote computer and the path of a shared location that both computers have access to. Separate the name of the remote computer and the path to the shared folder location with a semi-colon.

When converting remotely, the client redistributable, PNDocConvClientSetup_3.0.exe, must be installed on the computer running this command line utility. The client setup install program is included as part of the Document Conversion Service install and can be found in the \Samples\Redist folder in your product installation folder.

Examples:

/C="DOCCONV_SERVER;\\DOCCONV_SERVER\DCSREMOTE"

 

/SIL - Smart Inspect Logging File

Smart Inspect Log files are a tracing of the entire conversion process and are not the same as the conversion results log files created when a conversion fails. These logs can be viewed using the SmartInspect Redistributable Console included with Document Conversion Service.

These log files are automatically deleted when conversion succeeds. To keep the log files on success use the custom setting AlwaysKeepProcessingLoggingFiles as shown below.

The default location for this file is the TEMP folder. Each logging file is assigned a unique date, time and thread prefix followed by "_PNConvertFolder.sil", such as 2014_09_11_2_38_00_PM_4_PNConvertFolder.sil.

Use this argument to specify a custom path and optional file name for the SmartInspect logging file (*.sil) created by this utility. The /SIL switch can take a folder, or a path to a filename. If a path without a trailing backslash is provided, the last part of the path is assumed to be a filename.

Note: The double ending backslash used when specifying a folder for the /SIL switch is required for the command line path to be parsed correctly.

/SIL=

Is interpreted as...

"C:\Test\LogFile"

Create the SmartInspect log file as C:\Test\LogFile.sil.

"C:\Test\LogFile\\"

Create the SmartInspect log file as C:\Test\LogFile\datetime_PNConvertFolder.sil

"C:\Test\LogFile\ConvertFileCustom.sil"

Create the SmartInspect log file as C:\Test\LogFile\ConvertFileCustom.sil

The following settings can be used to control the creation and naming of the logging file. These settings are all passed using the /D switch.

Custom Setting

Description

RemoveDateTimePrefixOnProcessingLoggingFiles

Pass True to disable the adding of the unique date, time and thread prefix when a custom file name has not been specified in the ConvertFileProcessLoggingPath parameter.

KeepFailedProcessingLoggingFiles

Pass as False to disable the automatic creation of SmartInspect logging files when conversion fails. This setting can be overridden by AlwaysKeepProcessingLoggingFiles.

AlwaysKeepProcessingLoggingFiles

When set to True, the SmartInspect logging files are always created in the %TEMP% or other specified folder for both successful and failed conversions. If set to False, no logging files are created. This setting will override the KeepFailedProcessingLoggingFiles setting.

Examples:

Pass a custom folder and remove the prefix, each run will overwrite the log file C:\PEERNET\Logs\PNConvertFolder.sil.

/SIL="C:\PEERNET\Logs\\" /D="RemoveDateTimePrefixOnProcessingLoggingFiles:TRUE"

 

Pass a custom folder and log file name and remove the prefix. Each run will overwrite the logging file C:\PEERNET\Logs\MyLogFile.sil.

/SIL="C:\PEERNET\Logs\MyLogFile" /D="RemoveDateTimePrefixOnProcessingLoggingFiles:TRUE"

 

Don't save any SmartInspect log files at all.

/D="AlwaysKeepProcessingLoggingFiles:FALSE"

 

/T - Alternate Temp Folder

This is an advanced setting that should not be needed in most cases. When converting files, the conversion tool copies each file and performs the conversion in temporary staging and working folders created on demand in the default Windows temp folder. When dealing with long path and file names the default folders created can occasionally cause path names that are too long to process. When this happens this switch can be used to set the temporary folder to a shorter path to allow processing.

This setting is overridden if the /C option for remote conversion is being used with its own path to a shared location for conversion.

Examples:

/T="C:\PNTemp\\"

 

/NAME - Sort Files by Name

The file list picked up from the folder is sorted by file name in ascending order (0-9, A-Z).

 

/CREATED - Sort Files by Creation Date

The file list picked up from the folder is sorted by the files creation date file name in ascending order (0-9, A-Z).

 

/MODIFIED - Sort Files by Modified Date

The file list picked up from the folder is sorted by the files last modifed date file name in ascending order (0-9, A-Z).

 

/DESC - Sort Files in Descending Order

Use with /NAME, /CREATED or /MODIFIED. Sorts the descending order (Z-A, 9-0).

 

/? - Display Help

When passed as the only argument this switch will display help for this command.

 

Folder

The folder containing the files to convert.

If the path to the folder includes spaces it must be enclosed in quotes.

If the folder doesn't exist, the conversion will fail.