MS-DOS Batch commands

An Opus button or hotkey function can be set to MS-DOS Batch Function mode. A function in this mode is run as if it were a .bat batch file, and it can use MS-DOS commands, branching and logic instructions, as well as run external programs that are only designed to be run from the command line. You can also include regular Opus internal commands in the batch function (note that this can cause confusion when attempting to use external commands like Set or Copy that clash with internal commands - use the @externalonly modifier described below to fix this).

The above screenshot shows an example of a simple MS-DOS batch function. This uses the MS-DOS dir instruction to produce a directory listing of the current source folder. Using the > redirection symbol, the directory listing will be saved to a file in the destination path named after the current source folder.

Breaking down the function,

• The type is set to MS-DOS Batch Function using the Function drop-down. This is necessary to use the dir instruction - dir isn't a real program or command, it's an instruction that's only understood by the MS-DOS command interpreter.
• The first line of the command, cd {sourcepath}, sets the current directory of the batch script to the current source folder. This is the folder that dir will produce a listing of.
• The second command invokes the dir instruction (the /w flag turns on wide mode). The > character redirects the output of the command, and the combination of external control codes following the > supply the output filename.
  • {destpath} - the path of the current destination directory
  • {sourcepath|nopath|noterm} - the current source directory, without the path or trailing termination (i.e. the name of the directory)
  • .txt - the file extension for the output file.

When you run an MS-DOS batch function, Opus actually creates a temporary batch file on disk, and writes your instructions to it before invoking it. If you were to look at the batch file created by the above function, you would see something similar to the following:

@echo off
chcp 1252 > nul
C:
cd "\Users\Jon\Documents"
dir /w > "C:\Test\Documents.txt"

These instructions are written automatically to the .bat file, based on the parameters and definition of the function.

• @echo off is a standard MS-DOS instruction that prevents each command from being echoed to the prompt window as the batch file is run
• chcp 1252 > nul initialises the code page of the command prompt (1252 is the standard Windows code page).
• C: sets the current drive of the command prompt - this is generated automatically from the cd {sourcepath} instruction in the command definition.
• cd "\Users\Jon\Documents" sets the current directory on the current drive - again, this is generated automatically from the cd {sourcepath} instruction.
• dir /w > "C:\Test\Documents.txt" is responsible for producing the actual directory listing. In this instance, the source folder was called Documents, and the destination folder was C:\Test - so the name of the output file generated by {destpath}{sourcepath|nopath|noterm}.txt was C:\Test\Documents.txt.

Several of the command modifiers relate specifically to MS-DOS batch functions:

• @leavedoswindowopen can be used to force the DOS prompt window to remain open once the function has finished (letting you see any output or error messages).
• @codepage can be used to change the code page of the DOS prompt from the default of 1252.
• @externalonly tells Opus to ignore any command names that might coincide with internal commands (e.g. Set or Copy). Normally internal commands override external ones.
• @nocall is used to invoke a batch file and not return control to the parent function.
• @runbatch and @norunbatch control how external programs and internal commands interact in an MS-DOS batch function
• @runmode:hide can be used to prevent the brief flash of the DOS prompt window.

See the command modifier reference for a full description of command modifiers.