Invoking Command Line Apps

First of all, customers do not usually run DocOrigin Merge directly by keying a command on the command line. Truly, with some other applications, notably RunScript, that is more likely. See the Invoking RunScript section below. Merge though, is generally run, in development mode. via a preview operation from within Design, or in production mode, via FolderMonitor's detection of a data file to process and subsequent invocation of a Job Processing Script. Customers also have the option of launching Merge from their own application code. But it is possible, from time to time, that you will want to invoke a DocOrigin application directly from the command line. There is no mystery:

Programs that run from a command line have the following basic syntax:

programName –option1 value1 –option2 value2 …

.prm Files

First a reminder about .prm files. They are extremely useful. Yes, there is a bit of indirection in their use — instead of putting the parameters on the command line itself, you put them in a file and simply reference the .prm file as-is:

programName @myParms.prm

Having created that .prm file you so often want to go back and change it a little, this way and that, back and forth, test after test. That is so much easier to do than re-entering a full command line. Before/While going down the road of planning typed-in command lines, do keep considering those super flexible .prm files. They let you put in comments, you can nest them, you can escape much of the tyranny of parameter quoting, each line is not super-wide so you can grasp its meaning so much more quickly. When thinking about invoking Command-Line Apps, think prm files.

Convenience Invocation

The following is about mere convenience features that you may choose to use and which provide us a means to hide away the details of where you may have happened to install DocOrigin. This really has no place in production usage but might be useful during development.

... On Windows

DO_ROOT

When DocOrigin is installed, it does update your system and current user PATH variables with .../DO/Bin folder. Also it adds an environment variable named DO_ROOT to your system. It contains the fully qualified path to where you installed DocOrigin. Our favorite such place is: C:\DocOrigin.

DO.bat

We also deliver a convenience .bat file named DO.bat. It is deposited into the .../DO/Bin folder of your chosen installation folder. However, we urge you to copy it out to somewhere in your PATH. The end result then is that at a Windows command prompt you can code:

DO Merge merge-parms-as-needed

That's pretty easy.

There's not really much to it. In fact you could've taken advantage of the fact that the DO_ROOT environment variable was defined and instead code:

"%DO_ROOT%\DO\Bin\Merge" merge-parms-as-needed

But the needed quotes, \DO\Bin, and %s are pretty ugly and tedious.

Naturally, this applies to other apps such as RunScript, uconv, ConvertDatToXml, ... whatever it is that you wish to run in a standalone, command line, way.

DO.bat Parameter Count Limit

There is a caveat here. DO.bat is just a plain old .bat file. Have a read. It is limited by the arcane wonders of Windows command prompt processing. Normally that means that it can reference only 10 parameters, %0 through %9. (And the %0 is 'DO' itself!). As of 3.0.003.28, that limit has been brute force increased to 29 parameters. If you are in the habit of typing in command lines with that many parameters then I suggest that you explore other methodologies.

As many parameters to DocOrigin applications are of the format -name=value be aware that that equal sign, unless quoted as "-name=value", will come through as a blank, and hence the construct will count as two parameters.

Again, remember .prm files. A real treat is:

DO app @myParms.prm

there is no parameter overflow there!

Other DO.bat Features

DO.bat has in it recognition of some special options. These allow it to more easily take you to:

... On Linux

DO_ROOT, LD_LIBRARY_PATH

When DocOrigin is installed, it does not use root access. It does not set any environment variables. However, we really do like to have an environment variable named: DO_ROOT. It is to contain the fully qualified path to where you installed DocOrigin. Our favorite such place is: /var/DocOrigin3.0.

We also require that the LD_LIBRARY_PATH be augmented to include the .../DO/Bin folder of the chosen installation location.

We accomplish this by supplying a shell script named DO. That is provided in the usual .../DO/Bin folder. At install time it is dynamically constructed and contains the name of the installation folder.

We urge you to copy that DO shell script somewhere into your PATH. If you put it in your PATH then you don't have to continually give a fully qualified path name in order to invoke it. The end result then is that at a shell prompt you can code:

DO Merge merge-parms-as-needed

That's pretty easy.

That will define and export DO_ROOT every time and will adjust the LD_LIBRARY_PATH as needed before invoking the named application.

Other DO Shell Script Features

The DO shell script has in it recognition of some special options. These allow it to more easily take you to:

It may be that you will want to customize the DO shell script to better address your recurring development desires.

Invoking RunScript

Something of a personal digression...

In my experience, during development, I often want to run RunScript standalone from the command line. It's just too handy! I do this A LOT. For me, typing out:

DO RunScript "-script=abc.wjs" -form xxx.xatw -in vvv.txt ...

is just too much effort. Most of the time, during development, my script has some hard-coded test values as defaults, at least until I get by the initial prototype working. My most common invocation of RunScript is as follows:

rs foo

Where foo.wjs is the script I am developing. It may seem an absurd amount of abbreviation, but did I tell you that I run this A LOT? The rs.bat script in my path is awfully simple, but it affords me a place to do all the things that I want to do every time. I like to delete all my log files. It just makes it easier to cope. My rs.bat file allows me to specify or not specify the .wjs extension. I could worry about more parameters or other features but this is simple and I like simple.

My rs.bat

@setlocal
@echo off
if exist "%DO_ROOT%\User\Logs\*.log" del /f "%DO_ROOT%\User\Logs\*.log"
set script=%~1
set ext=%~x1
if "%ext%" == "" set script=%script%.wjs
"%DO_ROOT%/DO/Bin/RunScript" -script="%script%" %2 %3 %4 %5 %6 %7 %8 %9

On Linux, the least I can do is to define an alias of:

alias rs='/var/DocOrigin3.0/DO/Bin/RunScript -script '

I really do encourage you to take some time to set up a development environment that is nice for you. Do use GUI apps when you can but when some of the underlying tools that you use are command-line based you are going to want to be able to invoke them easily. Once you have developed your custom data filter script or your special Job Processing Script, you will deploy them in ways suitable to production, and these development-time command-line invocation tricks won't matter.

See Also

Common Command-Line Options