News Products Support Download Licenses Company

Home > Products > upCast > Support > TechNote 1

TechNote 1

Commandline, be at my command!

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.

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

Windows paths

Windows paths generally take the following form:

C:\path\to\file.txt

However, since the backslash character is used for quoting, we need to quote it itself so that the result is the above. In the commandline parameter, you therefore need to write the above path as follows:

C:\\path\\to\\file.txt

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 macros (or shortcuts or variables) %O, %F, %I 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 using the percentage character '%'

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

or as

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

whereby the latter form is preferred. You need to quote the percent sign using the percentage symbol as the variable substitutor, which runs after the commandline parsing into pieces, would otherwise try to find a macro '%<space>' which of course does not exist, and it would report an error.

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

The BCF (Batch Conversion File) language itself has the concept of variables. Every attribute of an element in the BCF language is run through a variable expander. Since BCF also requires and uses the backslash character, things start to get a little more complicated, since the commandline parameter as we mean it is expanded twice: The first time by the BCF processor, and the second time by the Commandline Processor parser (as described above).

When you're going about to write BCFs manually from scratch, you need to take this into account and perform some double quoting.

As an example, we use the same path as above. To have:

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

as the Commandline parameter in a BCF, you'd need to write it as follows:

This means you essentially need to quote the backslashes from the basic commandline, and (single-) quote additionally any of the following characters:

$ { }

which are part of the variable specification syntax used in BCFs.

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

Since 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 the double quoting requirement for BCFs completely as this function will take care of it all.

In the generated BCF, you probably only need to adjust the <file> element(s) for source file selection, but the complete filter setup is provided similar to a template. Or, set up only the Commandline Processor filter, save as BCF and copy the relevant portion over to your actual 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" "%O%F.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:35