Summary

This document describes the little pitfalls to watch out for when using the Commandline Processor post processing filter in upCast. It especially focusses on correct quoting both in the GUI version, as well as in BCF files.

This note was revised on 29-Jul-2004 to account for fundamental changes in quoting behaviour within upCast 5.2's variable resolution system. The only two characters you may quote as of upCast 5.2 is the $ (dollar) sign, and you need to quote it by doubling: $$, and the double quote character ", quoted by writing \". This means that single backslashes can and must be used as of upCast 5.2 .
( The former version of the TN (valid up to and including upCast 5.1) is archived here.)

Commandline Processor's guts

Runtime.exec()

The Commandline post processing filter relies on a generic Java method, Runtime.exec(). This method is implemented differently for each platform the Java VM runs on. Since we cannot rely on this call being based on some parsing shell, upCast resolves the commandline string itself using a very basic parser whose sole purpose is to detect argument boundaries in the commandline string and split it at these points.

Quoting

For upCast's parser being able to extract the single arguments in a command line, you need to aid it a little by quoting arguments that include spaces using double quotes ("..."). To be able to include the double quotes as part of an argument itself, upCast uses the backslash character \ for quoting.

Pitfalls

Relative paths

Using relative paths or no path specification at all is dangerous, since there is no standard base path within upCast. This may lead to the underlying interpreter not being able to find a certain file or command. Use absolute paths wherever possible.

upCast aids in doing this by offering the built-in, dynamic variables ${il:destfolder}, ${il:srcbasename}, ${il:imgdestfolder} etc. (see 5.3.5, Commandline Processor). Use these, they're your friend!

Quoting

As outlined above, you need to quote special characters. These special characters are:

" and the space character: quote using the backslash character '\'

$: quote by doubling, i.e. write $$

For example, to specify a file

C:\Documents and settings\chris\20$ rise report.doc

as a parameter, you'd need to write this either as

C:\Documents\ and\ settings\chris\20$$\ rise\ report.doc

"C:\Documents and settings\chris\20$$ rise report.doc"

whereby the latter form is preferred. You should quote the dollar sign by doubling it so that it may not mistakenly understood as as the variable substituton sequence start character in case it is followed by an opening brace '{'.

Length restrictions

Windows seems to impose a length restriction on command lines of about 248 characters. If you need longer commands, we recommend writing them into a batch file and calling only the batch file from upCast.

Batch Configuration Files (BCFs)

Doing it by hand

Nothing special here: The same rules as for writing in the GUI apply here.

Note that BCF parameter names are case-sensitive and the correct parameter name for the commandline parameter is Commandline (capital C).

Doing it the easy way

As of upCast 4.0.2, we offer a new command under the File menu called Save Configuration As BCF... . This command saves the current configuration you have set-up in the GUI in form of a BCF file. This means you only need to observe the Commandline Processor quoting rules outlined above and can forget about any peculiarities when generating the appropriate BCF.

Examples

Running a .bat file on Windows

To run the batch file C:\batchfiles\mybatch.bat using the Commandline Processor on Windows NT, WIndows 2000 or Windows XP, use this as the actual commandline parameter:

"C:\batchfiles\mybatch.bat"

To pass the output file of an earlier run of the XML (upCast DTD) export filter to the batch file, use:

"C:\batchfiles\mybatch.bat" "${il:destbasename}.xml"

Running an AppleScript script on Mac OS X

To run the AppleScript script "upcast.scpt" that's residing in your home folder on Mac OS X, set the commandline parameter to:

/usr/bin/osascript /Users/login/upcast.scpt

back to upCast Support Page

Author: Christian Roth
Last revised: 2004-07-29 0:46