Using DaVince Command Files (DCF)

Version: 3.0

Part of DaVince Tools
Web Site: www.davince.com

Last Modified: July 8, 2004

Purpose

A DaVince command file (also known as a DCF file) is a text file that allows a DaVince Tools converter to process command directives instead of using the command line. This provides additional capability to DaVince Tools that can not be found when specifying files and directories strictly on the command line. Use of a command file has the following advantages over the command line:

Specifying files and or directories via a DCF file simplifies the command line syntax and eliminates the problem of exceeding the command line buffer when specifying a large number of files and/or directories.
Multiple configuration profiles (specified in the ".ini" file) can be specified, and individual settings of each profile can be modified during processing of the command file. Conversely, only a single profile can be specified on the command line.
A DCF file can be used to watch one or more folders for conversion to PDF using the "wait" and "goto" commands.
An alternate name or alias can be given to a file for bookmark purposes, allowing bookmarks to be created using descriptive text instead of the name of the file. Specifying a blank name will prevent a bookmark from being created for a particular file.
The command file can be used as an application programming interface (API) to the DaVince Tools converters. A programmer can write code that generates a command file which can subsequently be used by a converter to convert files to PDF. The command file is the application programming interface (API) used by the Windows interface application, wdavince, to send commands to a converter.

Syntax

A DaVince command file consists of a series of lines entered in a text file. The file can be created with a standard text editor like Notepad or it can be generated by a program like wdavince. Lines beginning with the pound character ( # ) or the single quote character ( ' ) are considered comments and are ignored. Special consideration is given to the first line in the command file by the Windows program, wdavince. If the first line begins with the two characters "#!" (a comment with an exclamation point as the second character), the text in the line specifies the converter to use when running the command file. For example, if the command file started with the line:

#! txt2pdf

then wdavince will run the command file against the txt2pdf converter. This technique allows wdavince to save a command file to disk and be able to run it at a later time against the correct converter.

The following commands are valid in the command file:

cd create dir echo exit file goto info param profile wait

Refer to the Command Description section below for details on the syntax for each command.

Note: When a filename or directory name is specified as a parameter to one of the commands above, it must be enclosed in quotes if there is a space character included in the name. For example, to convert files in the "My Documents" directory, use the following command:

# this is the correct way
dir "c:\My Documents"

Instead of the following:

# this is the WRONG way
dir c:\My Documents

Release History

The following command is new in version 3.0:

exit

The following commands were new or modified in version 2.1:

create file goto wait

The following commands were new in version 2.0:

create echo info param

Command Summary

cd	changes the current directory used by the "file" and "dir" commands
create	Specify the name of the PDF file to create
dir	Convert specified directory
echo	Echo text to the screen
exit	Exit script at this point, creating the PDF file if files were previously specified for conversion.
file	Convert specified file
goto	Go to a specified label in the command file
info	Add info strings to PDF file
param	allows configuration parameters normally stored in the .ini file to be included in the command file
profile	Specify the profile to use as defined in the INI file
wait	wait a specified # of seconds

Command Description

The following section describes the commands. Command options in square brackets ("[]") are optional. The vertical pipe character ("|") specifies a choice of options. These characters are not actually used in the command.

cd directoryname

The "cd" command changes the current directory used by the "file" and "dir" commands. This command is useful when many files are contained in a single directory, which alleviates the need to prepend a path name to a file when using the "file" command.

create [ filename ] | [ dirname ] 1 [ force ] | [ dirname ] 2

The format of this command varies depending on the conversion mode used: many to one, one to one, or many to few. For many to one, only the PDF file name to create need be specified. For one to one, an optional output directory is specified along with the number "1". To force a PDF file to be created in one to one mode, even if the file has not changed, specify the keyword "force" after the "1" option. By default, the PDF file is not created if the PDF file date is newer than the original data file. If an output directory is not specified, then the PDF files are created in the same directory as the files to be converted. For many to few, an optional output directory is specified along with the number "2". If an output directory is not specified, then the PDF files are created in the same directories as the files to be converted.

This command should be specified prior to the file or dir commands.

A PDF file will not be created if the same filename with a ".LCK" extension is found. For example, if the file "d:\conversion\myfile.lck" is present, then the PDF file "d:\conversion\myfile.pdf" will not be created. This lock file feature allows a program to temporarily disable converting to PDF until all files are ready to be converted.

Examples:

To convert many files to one to a file named "conversion.pdf", use the following syntax:

create conversion.pdf To convert files one to one, forcing a new PDF if one already exists, and storing the PDF files in the same directories as the files to be converted, use the following syntax: create 1 force To convert files many to few, and storing the PDF files in the same directories as the files to be converted, use the following syntax: create 2

dir directoryname [r]

The "dir" command specifies a directory to process. If an "r" is specified for argument 2, then the directory is processed recursively (similar to the "-r" command line option), otherwise, the directory is processed without recursion. Directory names with spaces in them must be enclosed with quotes. If a directory name contains a quote character, the quote must be preceded with a backslash character.

echo "text to display"

echo text to display

The "echo" command allows text to be displayed while processing the command file. This is useful for displaying text to the user during processing of the command file.

exit

When this command is encountered, the script will exit, creating the PDF file if files were previously specified for conversion. This allows a script to exit prior to reaching the end of the file.

file filename [aliasname]

The "file" command specifies a file to convert. When an alias is specified for argument 2, this name is used when creating the bookmark instead of the filename. If the filename or the alias name contains spaces, then they must be enclosed in quotes. If either contains a quote character, the quote character must be preceded with a backslash character. If the alias name is not specified, then a default bookmark name is used based on the filename. If the bookmark name is specified as blank (two quotes only ""), then no bookmark is generated for that file. This allows bookmarks to selectively be created for certain files in the command file.

Beginning in version 2.1: The filename parameter can contain wild card characters. If wildcards are specified, then the aliasname parameter is ignored and a default bookmark name is used based on the filename.

goto label

Use this command to jump to a specific location in the command file. It is typically used in conjunction with the wait statement to monitor a folder for new files. A label defines the location where a goto statement can jump to. All labels must end in a colon (":") character. For example:

#! tiff2pdf
profile default
create 1
# labels must end in a colon (":")
watchloop:
dir "e:\watchdir"
# wait 60 seconds before trying again
wait 60
goto watchloop

info infokey infostring

This command adds strings to the PDF info dictionary. This dictionary contains information about the PDF file, including subject, author, and title. The keys are case sensitive. infostring should be enclosed in quotes. The command info keys are:

Subject - the subject of the PDF file

Author - the writer of the PDF file

Title - The title of the PDF file

param paramkey paramstring

The "param" command allows configuration parameters normally stored in the .ini file to be included in the command file. This allows one to create a profile dynamically or modify an existing profile by first using the "profile" command.

profile profilename

The "profile" command specifies the profile to use as defined in the INI file. The profile name must be a valid profile. This option is similar to the "-p" command line option, however, it allows for the profile to change during the processing of the command file.

wait seconds

Pause the execution of the command file for the specified number of seconds. See the "goto" command for an example.

Example

#! txt2pdf
# example command file for DaVince Tools txt2pdf
# all comments start with ' or #
# specify PDF filename
create systemfiles.pdf
# specify profile from txt2pdf.ini
profile fixed-80x60
# convert autoexec.bat
file c:\autoexec.bat
# convert config.sys
file c:\config.sys