2. Starting DigImage
3. Basic Operation
4. Sample Session
5. Command Files
7. Coordinate Systems
8. Warnings, Errors and Crashes
11. Other Considerations
Appendix A: Menus
The ability to control DigImage from a command file is an essential feature for processing the significant quantities of data available from a time series of images. In its simplest form a command file simply lists the key sequences which would normally be typed from the keyboard. However the ability to nest command files, define variables, evaluate expressions, perform conditional jumps, create files etc. makes the command file a powerful programming tool. In fact the command files have many of the features of a conventional programming language.
A crude command file to undertake an interlace filter on buffer 2 (such as that used in the sample session above) is shown below:
; F I a 2 S O ;
This command file would be read one line after another. When a single character is required, the first character in the next line will be used. Blank lines are ignored entirely by DigImage. If you want to pass DigImage a blank line, you must use the !B directive (see section 5.3 for more details). Note that except for variables and directives (both of which are preceded by the ! character - see section 5.3 ) the characters are not case sensitive (e.g. the "a" could equally be "A"). When numeric or string input is required, the value is read from as much of the line as required. This enables us to utilise most of the line as a comment, an important feature if the command file is to be readable. Thus for the above example we could instead write
# Command sequence for averaging the odd numbered lines ; Return to main menu F: Filter I: Interlace filters A Average interlace information 2 Buffer containing foreground S Apply filter to whole screen O Use the odd numbered lines ; Return to main menu
The # character used on the first line indicates a comment line. When executing the command file, this line will be ignored. This example does not utilise the full power of the command file language. However we should consider the various methods of running a command file before introducing the more advanced features.
There are a number of methods of starting a command file. The most straight forward method is by accessing the [;ZF Take input from file] option. Suppose our above example is in a file named EXAMPLE.CMD, then we could run the command file by the following procedure:
->; >> Main Menu >> ... ->Z >> Keyboard Redirection Menu >> ... ->F >> Name of file containing command sequence ? >> => =>EXAMPLE
As is always the case, execution will continue until the end of the command file is reached, or the command file is terminated by <escape> or <ctrl><break>. Note that in starting EXAMPLE.CMD we have not given the .CMD extension for the command file. If DigImage is not able to find a file of the specified name (in this case EXAMPLE) then it appends a .CMD and tries again (this time finding the required file). If for some reason it still can not find the requested file, it searches in the directory specified by [;ZP Set command file search path], and if still not found then the path pointed to by %DIGIMAGE%\MACROS for the file. This directory may thus be used to store command files which may be of use to other users or from other directories without the need to specify the complete path.
A command file started in this manner will commence execution from the [;Z: Take input from file] menu. Typically the first command in the file would be a semicolon to take DigImage back to the main menu. A short cut to the above procedure would be to press <alt><f12> from any menu. Functionally this is identical to the above key sequence, with the user being prompted for the file name from within the [;ZF Take input from file] option.
Command files may be started from the MS-DOS command line by invoking the [/CF] command_file switch (the /CF is optional). This was noted in section 2 A command file started in this manner will always commence execution from the main menu. It is good practice to include a <;> command to ensure this, just in case the command file is started through some other mechanism. Note that with the /CF switch a .CMD extension is not supplied if the specified command_file is not found. Both the current working directory and search path specified by [;ZP Command file search path] will be searched.
The final method of starting a command file allows
the file to be invoked at any point, not just from a menu. The
sequence !P command_file
(or !PL command_file
- see next section, 5.3 ,
for the difference) may be entered in response to either the ->
prompts. If entered to the ->
prompt, then DigImage will change to the =>
prompt on detection of the !
character. This method is in fact the most powerful option for
invoking a command file as it may be used within a command file
to invoke another one (or invoke itself recursively). On completion
a nested command file will return control to its parent. In the
case of the top level file, the parent is simply interactive entry
from the keyboard. Command files may be nested up to 999 deep.
Goto next document (Directives) Command files already executing may be paused using <scroll lock> or suspended using <tab>. If a command file (or any other DigImage operation) is paused, then it can be continued by pressing any key. If a command file is suspended, then DigImage will exit and return to the DOS prompt or Windows environment (depending on how DigImage was started). In this case the command file will be resumed by simply restarting DigImage in the same directory.
If a command file has been suspended, you may start
and use DigImage in a different directory without affecting the
suspended command file. Note that the suspend can only take place
from a menu (and even then some menus can not be suspended). Thus
the command file will continue execution until a suitable menu
DigImage documentation page
DigImage home page
Stuart Dalziel's home page