~~Title: MS-DOS Batch commands ~~
<pageheader/>

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).

{{:media:dos_batch_function.png?nolink|}} 

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 [[:reference:command_reference:external_control_codes|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:


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

\\
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|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 [[:reference:command_reference:command_modifier_reference|command modifier reference]] for a full description of command modifiers.