DIRECTIVES AND VARIABLES

Contents Summary

Detailed Contents
1. Introduction
2. Starting DigImage
3. Basic Operation
4. Sample Session
5. Command Files
6. Movies
7. Coordinate Systems
8. Warnings, Errors and Crashes
9. Utilities
10. Macros
11. Other Considerations
12. Updates
Appendix A: Menus
Index

5 .3 DIRECTIVES AND VARIABLES

In DigImage the ! character has a special meaning as it provides access to many of the more powerful structures available within command files. Below we list the features accessible through the ! character. With the exception of the jump directives, all of these commands, variables etc. may be accessed interactively using !. Blank lines are completely ignored. If you wish to include pass DigImage an empty line, then utilise the !B directive. In addition the following commands are

Command Description

# comment Comment - ignore.

!^ comment Comment - print on screen. Useful for generating prompts.

!% comment Comment - print on screen, beeping. Useful for generating prompts and warning messages.

!$ comment Comment - print on screen then Press any key to continue.

!" Print quoted text - prints out (without any further processing) all the text following this command up until the next occurrence of !".

!{command parameter_list} Ex ecute complex command, replacing !{...} expression with the resulting value. Any variables within the braces ({}) are substituted before interpreting the command. Note that these !{...} commands can not be nested. Valid commands are:

!{CHARACTER iChar char_list} returns the character in the iChar-th position in char_list. Thus !{CHARACTER 3 ABCD} will return "D". If no char_list is specified, then the ASCII character corresponding to iChar will be returned (e.g. !{CHARACTER 66} will return "B").

!{COMPARE string1 string2} Returns 1 if string1>string2, 0 if string1=string2, or -1 if string1<string2.

!{ENVIRONMENT aspect} Returns some detail about a particular aspect of the environment in which DigImage is running. The string aspect can be one of BUFFERS Returns the total number of buffers
(same as !!N)
DIGIMAGEPATH Directory where DigImage is installed
ONBOARD Returns the number of onboard buffers
THISPATH Current working directory

!{EVAL val0 val1 ... key expr}evaluates the expression expr, written in terms of the variables indicated by key (typically letters). Each of the characters in key must have a corresponding value val0, val1, ...

!{EXIST file} Returns 1 (true) if the specified file exists, and 0 (false) if it does not.

!{FILEPATH iComponent filename} Returns specific parts of the complete file name specified. The integer iComponent specifies which bit of the file or path name is to be returned:
iComponent Effect
iComponent<=7:
bit0 Base file name
bit1 Extension
bit2 Complete path
iComponent>7:
8 Top directory, excluding tree.

!{FORMAT value format} converts the numerical value into the specified format. This command understands the common Fortran number formats, e.g. F10.3, G12.2, E10.4, I3, Z2. Note that only one value per !{FORMAT ...} statement may be specified.

!{INDEX substring string} returns the position of the substring within the string. Note that the substring starts at the first non space character after the INDEX and is terminated by the first space character after that point.

!{LEFTSTR nChars string} returns first nChars characters of the specified string.

!{LENGTH string} returns the length of the specified string in characters.

!{MAPIJTOX i j} Returns the x pixel coordinate corresponding to i j.

!{MAPIJTOY i j} Returns the y pixel coordinate corresponding to i j.

!{MAPXYTOJ x y} Returns the j pixel coordinate corresponding to x y.

!{MAPXYTOI x y} Returns the i pixel coordinate corresponding to x y.

!{NUMSTRING iColumn string} returns the numerical value in the iColumnth position in the specified string. Each number in string is assumed to be separated by one or more spaces or comma characters. Note that this command is identical to !{TIMESTRING ...} as they both understand both number and time formats.

!{PRESSCHAR key_list} returns the character pressed, provided it is in key_list. All alphabetic characters are converted to upper case. Special keys return their lower case codes (see !{PRESSKEY key_list} for details). If no key_list is specified, then !{PRESSCHAR} simply returns the character pressed.

!{PRESSKEY key_list} waits for the pressing of one of the keys listed in key_list. Once a key in key_list has been pressed, this command returns the ordinal position of that key in the key_list. For example, !{PRESSKEY ABCD} would return the number 3 if <C> were pressed. Note that alphabetic keys produce upper case letters, and these must be given as upper case in key_list (i.e. !{PRESSKEY abcd} would not return if <C> were pressed). The following lower case letters are reserved for the special keys: u up arrow
d down arrow
l left arrow
r right arrow
p page up
o page down
h home
e end
i insert
x deletethus !{PRESSKEY udlr} would return 2 if the down arrow cursor key were pressed. If key_list is blank, then !{PRESSKEY} returns the ASCII value of the key pressed (e.g. if <A> were pressed, then !{PRESSKEY} would return the value 65).

!{READNUM iLine iColumn file_name} returns the numerical value in number column iColumn on line number iLine. The number columns are separated by one or more spaces or commas. Note that this command does not understand the time format. If a time in the hours:minutes:seconds format must be read from a file, then this should be done by using !{READSTR ...} to assign the line to a string variable, then !{TIMESTRING ...} to extract the time.

!{READSTR iLine iColumn nChars file_name} returns the nChars characters starting in character column iColumn of line iLine in the specified file.

!{RIGHTSTR nChars string} returns the last nChars characters of the specified string.

!{SEARCHFILE [iLine] iColumn key_value file_name} returns the line number in the file file_name where the specified numeric key_value may be found in column iColumn. The search will normally begin from the start of the file. If the optional iLine is specified, then the search will begin from line iLine. In either case the returned value is relative to the start of the file. The main purpose for this command is to facilitate the reading of experimental data databases by command files.

!{TIMESTRING iColumn string} returns the time value in the iColumnth position in the specified string. Each number or time in string is assumed to be separated by one or more spaces or comma characters. Note that this command is identical to !{NUMSTRING ...} which understands both number and time formats.

!B In dicates a blank line. The !B directive may be used instead of a blank line. The advantage is that a comment may be included after the !B on the blank line. Note that !B is not equivalent to # as !B is accepted as input, while # lines are ignored. The !B must occupy the first two non blank characters of the line. Note that empty lines in the command file will be ignored and NOT treated as blank lines by DigImage.

!C directory Ch ange directories to that specified. The !C must occupy the first two non blank characters of the line.

!D Re tu rns the name of the current working directory. This may occur anywhere on the line.

!E file_name Er ase (delete) the specified file name. The !E must occupy the first two non blank characters of the line.

!F [file_name] Op en the specified file name for macro output (using the !W directive). If no file name is given, then !F will close any file previously opened by !F. The !F must occupy the first two non blank characters of the line.

!FB [file_name] Di splay the specified file using the DigImage Help System browser.

!FR old_name new_name Re name the specified file old_name with the new name indicated. A warning will be generated if new_name already exists.

!GC Th e name of the currently executing command file. If a nested command file is executing, then the name of this file is returned. If no command file executing, then blank.

!GD Th e current date in dd/mm/yyyy format when a 50Hz field rate is used or mm/dd/yyyy when a 60Hz field rate is used.

!GP Th e name of the outer-most level of the current plot file. If no plot file is executing, then blank is returned.

!GT Th e current time in hh:mm:ss.

!I dos_command Th e specified dos_command is passed to the DOS command line interpreter for execution. Any error code produced is returned in !!R0. Note that this command may fail due to insufficient memory being available. If it fails then !!R0 will contain the value -1.

!K Ta ke alphanumeric string from keyboard (this may be used anywhere on the command file line). This directive is similar to !!K except that it accepts string as well as numeric text.

!L text Take input from the command file, even if the prompt normally forces input to be from the keyboard (e.g. the "Press any key to grab frame (C for continuous acquisition)" prompt in [;GG Grab single frame]). The !L must occupy the first two non blank characters of the line.

!M buffer Er ase the specified buffer. If no buffer number is specified, the current output buffer is erased. The !M must occupy the first two non blank characters of the line.

!N Cl ear the computer's display. The !N must occupy the first two nonblank characters of the line.

!P If given without a file name within a command file, then execution of that command file is suspended to allow interactive input. To resume the command file, type !P from the keyboard. The status file will indicate any command file which has been suspended. Note that it is important that the command file is resumed in either a known (prespecified) location or in a menu so that it may take control without any complications. In the latter case, the command file should execute <;> to return to the main menu to ensure the correct menu tree is entered.

!P [value0 value1 ...] ["string0" "string1" ...] file_name Ex ecute the command file procedure specified by file_name. Command file procedures are themselves complete command files. Execution of this command passes control to the specified command file. On completion of that command file, control is returned to the calling command file. Command file procedures may be nested and may be recursive.
If the specified file is not found in the current directory, then DigImage will first search the path specified by [P Set command file search path], and, if it is still not found, then the DigImage\Macro directory is searched.
To ensure a procedure command file operates from a known location within DigImage, you should normally start the procedure with the <;> command to return to the main menu before the body of the code is executed. The !P must be the first two non-blank characters of the line.All string variables (!0 to !9) and all numeric variables (!!0 to !!9 and !!a to !!z) are treated as local variables within the nested command file. Any changes made within the nested command file do not alter the values on return from the command file. If values are to be returned, then they may either be recovered using the !Pn and !!Pn variable return syntax (see below), or the !PA... (!!a to !!z global), !PG... (all variables global), !PO... (!!a to !!z and !0 to !9 global) or !PS... (!0 to !9 global) variants may be used (see below).Note that the outermost command file (i.e. the one started by the user, either from within DigImage or at the MS-DOS prompt) all the variables are considered global in that changes made within the command file affect the base DigImage values. If you do not wish this to occur, start the command file with !PL ... to force all variables to be local.If one or more of the optional numeric values value0, value1, ... are specified, then these will be available in the nested command file as variables !!0, !!1 etc. Up to ten such values may be specified. If fewer values are specified, then the remaining !!n variables retain the values they had in the calling command file. Thus there are two mechanisms for passing parameters: they may be assigned to the !!0, !!1 etc. variables prior to the !P directive, or they may be included in the !P directive line.Similarly, if one or more of the optional strings (delimited by double quotes) are specified, then these will be available in the nested command file as !0, !1 etc. Up to ten such strings may be specified. If fewer strings are specified, then the remaining !n strings retain the values they had in the calling command file.

!PA [value0 value1 ...] ["string0" "string1" ...] file_name Th is directive is identical to !P ... except that the numeric variables !!a to !!z are treated as global. Any changes made in the nested command file are maintained on exit from the command file.The !!0 to !!9 and !0 to !9 variables are still treated as local.

!PG [value0 value1 ...] ["string0" "string1" ...] file_name Th is directive is identical to !P ... except that all the numeric variables (!!0 to !!9, !!a to !!z and !0 to !9) are treated as global. Any changes made in the nested command file are maintained on exit from the command file.

!PL [value0 value1 ...] ["string0" "string1" ...] file_name This directive is identical to !P ... except that all the variables are treated as local even for the outermost command file level. Thus if the command file is to be executed from the command file and have no effect on the base DigImage variables, then it should be started with !PL ...

!PM As with !PQ and !P (without any parameters), !PM suspends a command file until !P is typed from the keyboard. In this case, however, the command file will also be resumed automatically if DigImage enters a menu. This command thus provides a simple mechanism for allowing interactive input up until the end of the current menu option.

!PO [value0 value1 ...] ["string0" "string1" ...] file_name Th is directive is identical to !P ... except that the numeric variables !!a to !!z and string variables !0 to !9 are treated as global. Any changes made in the nested command file are maintained on exit from the command file.The numeric variables !!0 to !!9 are still treated as local.Note that this was the effect of the !P... command prior to DigImage version 1.3.

!PQ As with !PM and !P (without any parameters), !PQ suspends a command file until !P is typed from the keyboard. In this case, however, the command file will also be resumed automatically if a menu is exited by pressing <Q>, <;> or <escape>. This command thus provides a simple mechanism for allowing interactive input up until the current menu is exited.

!PR plot_file [cmd_line_opts] In vokes DigiPlot within the context of DigImage or Trk2DVel. The specified plot_file will be rendered, by default, on the computer monitor. To render on the frame grabber buffer, use the /B [buffer_number] switch. All the standard DigiPlot command line options are supported except for /H (help). Refer to the DigiPlot Users Guide for full details on the options.Note that while the !PR directive may be issued from anywhere within a command file, it may have unexpected side effects if issued from within a menu option. Hence we recommend that its use is restricted to within menus.

!PS [value0 value1 ...] ["string0" "string1" ...] file_name Th is directive is identical to !P ... except that the string variables !0 to !9 are treated as global. Any changes made in the nested command file are maintained on exit from the command file.The numeric variables !!0 to !!9 and !!a to !!z variables are still treated as local.

!Pn Re ad-only pseudo variable (with n in the range 0 to 9) returning the value of the !n string variable immediately prior to the return from the last nested command file. This provides a mechanism for returning string variables used in nested command files started with the !P ... directive and its variants (see above).

!Rn Re ad only system string variable. This variable allows results from some DigImage facilities to be communicated to a command (or plot) file. There are 36 such string variables available, !R0 to !R9 and !Ra to !Rn. Not all DigImage menu items currently return values in these variables. Refer to the help text for specific menu items for details of what data is returned (if any) by that item. returned (if any) by that item. Note that these variables should only be accessed while a command file is the menu immediately following completion of the option (or at a suitable point during the option) which set them. If this is not done, the !!Rn values may be unpredictable.

!RD Re ad only system string variable. If DigImage is at a => type prompt, then this variable returns the current default value for the reply to the prompt. If there is no default value (or the default is blank), then !RD returns a null string (zero length). If DigImage is not at a => prompt when this variable is accessed, then !RD returns the default value for the last => prompt executed. The main purpose of this variable is to allow a command file to select the default value which would be available to the user in an interactive session.

!RU Re ad only system string variable returning the currently specified units for the world coordinate system.

!S OFF Tu rns off all screen output (except that due to !$, !^, !%, errors or warnings) while in a command file. The !S must occupy the fist two non blank characters of the line.

!S ON Turns on screen output previously suppressed by !S OFF.

!SW OFF Tu rns off WARNING messages when in a command file. Warning messages may be re-enabled by !SW ON or simply !SW. The warning messages will be automatically enabled when the command file terminates. When turned off, the command file will simply continue execution as though the warning had not been generated.

!SW ON Turns on WARNING messages previously turned off by !SW OFF.

!T seconds De lays execution for the specified time (in seconds). The !T must occupy the fist two non blank characters of the line.

!W text Wr ite the specified text to the file previously opened by !F file_name. Note that any DigImage variables or replaceable string parameters will be substituted before the write is performed. The !W must be the first two non blank characters of the line.

!WI image_file Wr ite the current output buffer to the specified file using the compressed image format.

!:Label Un co nditional jump to the specified label. The label is defined by !!:Label. The jump must be the fist non blank characters in the line.

!n Us e string variable, where n is a digit from 0 to 9 (inclusive).

!n:=string Assign a value to the specified string variable. For example !1:=!K may be used to set string parameter 1 to a value entered from the keyboard. The !n:= assignment must be the first non blank characters in the line. The remainder of the line, excluding any trailing blanks, will be assigned to !n.

!!n Us e numeric variable n, where n is a digit from 0 to 9 or a lower case letter; there are 36 possible variables. Note that all command file variables are stored and processed as real values. However, whether they appear as real or integer input to DigImage depends on the syntax through which they are accessed. This !!n form produces an integer value occupying the minimum required space. Note that if !!n is included on the right hand side of an expression, then only the integer value will be used. To utilise the real value, you must specify one of the real replacement specifiers (!!En, !!Fn or !!Gn).

!!_n In di rect access to variable. The contents of !!n is taken as an integer value (m, say) and used as an index to the variables (to give !!m). The effect of this may be expressed as !!(!!n), although this is not a valid syntax. !!0 to !!9 are accessed indirectly through values 0 to 9 while variables !!a to !!z are accessed indirectly through 10 to 35. If the index variable (!!n) contains a value outside the range 0 to 35, then an error will be generated.

!!Smn As f or !!n except that the integer value takes up m characters and uses leading blanks. This may not be used on the left hand side of an assignment.

!!Zmn As for !!n except that the integer value takes up m characters and includes leading zeros. This may not be used on the left hand side of an assignment.

!!En As for !!n except that the full real value is accessed as the Fortran E12.5. This may not be used on the left hand side of an assignment.

!!Fn As for !!n except that the full real value is accessed as the Fortran F12.5. This may not be used on the left hand side of an assignment.

!!Gn As for !!n except that the full real value is accessed as G12.5. This may not be used on the left hand side of an assignment.

!!K Ps eudo variable: requests numeric keyboard input. In this form the input is taken as integer. The !!S, !!Z, !!E, !!F and !!G modifiers apply.

!!B Ps eudo variable: requests a buffer number to be input from the keyboard input. The routine is similar to !!K except that it will always return an integer and performs a range check on the buffer number.

!!T Ps eudo variable: requests keyboard time input. This variable is similar to !!K except that the minutes:seconds and ::fields formats may be used. In this form the input is taken an integer number of seconds. The !!S, !!Z, !!E, !!F and !!G modifiers apply.

!!C Re ad /write system variable returning or setting the current logical output buffer. Warning: if this variable is set while executing an option, unpredictable results may sometimes occur as the contents of buffer 0 may be different from what the option expects.

!!D Re ad only system variable returning the current onboard output buffer.

!!H Re ad/write system variable returning or setting the current video multiplexer channel for the optional DT-2859.

!!I Re ad only system variable returning the intensity of the point last accessed by the location cursor. Note that the location cursor is utilised by a large number of the DigImage facilities. To ensure the desired point is accessed, it may be advisable to access the cursor through the [;GZ Zoom & pan/locate points] option prior to using the value of !!I.

!!J Re ad only system variable returning the intensity of the cell of five points centred on the point last accessed by the location cursor (this is the Average intensity displayed by this submenu). Note that the location cursor is utilised by a large number of the DigImage facilities. To ensure the desired point is accessed, it may be advisable to access the cursor through the [;GZ Zoom & pan/locate points] option prior to using the value of !!J.

!!L Re ad only system variable returning the current nesting level for command files and plot files. The top most command file or plot file will have a level 0, and any command file or plot file called (through the !P call or R plot instruction - see DigiPlot user guide for details) from it will have a level of 1. Likewise, the next level of nesting will be 2 and so on. This variable provides a mechanism for testing to see if a command file or plot file has been nested.

!!M Re ad only system variable returning maximum buffer number.

!!N Re ad only system variable returning the number of buffers (!!M+1).

!!O Re ad/write system variable returning or setting the current logical output look up table.

!!Pn Re ad-only pseudo variable (with n in the range 0 to 9) returning the value of the !!n numeric variable immediately prior to the return from the last nested command file. This provides a mechanism for returning numeric variables used in nested command files started with the !P... directive and its variants (see above). Note that the normal format specifiers apply (e.g. !!GPn for floating point value).

!!PN In plot files, returns the number of points plotted since the last N plot instruction.

!!PW In plot files, returns a bit flag indicating where the plot is being produced. The bit assignments are:
bit 0 Frame grabber buffer
bit 1 Computer monitor
bit 2 PostScript file.If a bit is set, then the plot is being rendered on the associated device.

!!PX In plot files, returns the x coordinate of the last point plotted.

!!PY In plot files, returns the y coordinate of the last point plotted.

!!PZ In plot files, returns the z coordinate of the last 3D point plotted.

!!Rn Re ad only system variable. This variable allows results from some DigImage facilities to be communicated to a command (or plot) file. There are 36 such variables available, !!R0 to !!R9 and !!Ra to !!Rz. Not all DigImage menu items currently return values in these variables. Refer to the help text for specific menu items for details of what data is returned (if any) by that item. returned (if any) by that item. Note that these variables should only be accessed while a command file is the menu immediately following completion of the option (or at a suitable point during the option) which set them. If this is not done, the !!Rn values may be unpredictable.

!!U Re ad only system variable returning the field rate (in Hz) for the video system being used (i.e. 50 or 60).

!!V Re ad only system variable returning the current position of the VTR in seconds.

!!WT Re ad only system variable returning the current i coordinate of the top of the current default window. Note that this variable is selected by two key letters both of which must be upper case.

!!WB Read only system variable returning the current i coordinate of the bottom of the current default window.

!!WL Read only system variable returning the current j coordinate of the left hand side of the current default window.

!!WR Read only system variable returning the current j coordinate of the right hand side of the current default window.

!!WI Re ad only system variable returning the current i pixel coordinate of the last position of the cursor.

!!WJ Read only system variable returning the current j pixel coordinate of the last position of the cursor.

!!WX Read only system variable returning the current x world coordinate of the last position of the cursor.

!!WY Read only system variable returning the current y world coordinate of the last position of the cursor.

!!n:= expression Set the variable to the result of the specified expression. The expression may include constants, variables and/or replaceable string parameters. Expressions are evaluated from left to right without the normal operator precedence. For example
!!1:= (!!0+2)^(2+!!G2/3)is equivalent to the Fortran
v1 = (INT(v0)+2.0)**((2.0+v2)/3.0)The allowable arithmetic operators are:
+ Addition
- Subtraction
* Multiplication
/ Division
^ Exponentation
MOD Modulo arithmeticThe bit-wise operators are:
% Bit-wise OR (Fortran IOR(,))
& Bit-wise AND (Fortran IAND(,))
$ Bit-wise Exclusive Or (Fortran
(IEOR(,)).The allowable logical operators: OR Logical OR
AND Logical AND
EOR Logical Exclusive OR
NOT(..) Logical NOT of integer part.The comparative operators are (true = 1, false = 0):
< Less than
<= Less than or equal to
> Greater than
>= Greater than or equal to
= Equal to
<> Not equal toOther operators: MIN The smaller of the two arguements
( MIN equivalent to Fortran
MIN(,))
MAX The larger of the two arguements
( MAX equivalent to Fortran
MAX(,))

!!n:= expression (continued) Brackets nested up to 10 levels. The following functions of one argument are also supported (not case sensitive):
LOG(..) Logarithm, base 10
LN(..) Natural logarithm
EXP(..) Exponential
SQRT(..) Square root
SIN(..) Sine (angle in radians)
COS(..) Cosine (angle in radians)
TAN(..) Tangent (angle in radians)
SINH(..) Hyperbolic sine
ASIN(..) Arc-sine (angle in radians)
ACOS(..) Arc-cosine (angle in radians)
ATAN(..) Arc-tangent (angle in radians)
COSH(..) Hyperbolic cosine
TANH(..) Hyperbolic tangent
ABS(..) Absolute value
SGN(..) Sign (-1 for negative, 1 for positive and 0 for zero).Comments may be appended to the end of an assignment using the # comment indicator.

!!n+=expression Increment the variable by the result of the specified expression. For more details on expressions consult the entry for !!n:= expression above.

!!n-= expression Decrement the variable by the result of the specified expression. For more details on expressions consult the entry for !!n:= expression above.

!!n*= expression Multiply the variable by the result of the specified expression. For more details on expressions consult the entry for !!n:= expression above.

!!n/= expression Divide the variable by the result of the specified expression. For more details on expressions consult the entry for !!n:= expression above.

!!n= expression Te st for equality - see below.

!!n< expression Test for variable less than value - see below. !!n> expression Test for variable greater than value - see below.

!!n<= expression Test for less than or equal - see below.

!!n>= expression Test for greater than or equal - see below.

!!n<> expression Test for inequality - see below.

!!nc expression STOP Te st the internal variable !!n against the value of the specified expression, where c is one of =, <, >, <=, >= or <>. If satisfied, then terminate the command file. For more details on expressions, consult the entry for !!n:= expression above.

!!nc expression :Label Te st the variable !!n against the value of the specified expression, where c is one of =, <, >, <=, >= or <>. If satisfied, then jump to the label !!:Label. For more details on expressions, consult the entry for !!n:= expression above.

!!:Label Ta rg et label for conditional (!!n?!!m :Label) or unconditional (!:Label) jumps.

Goto next document (Intrlace) If it is necessary for a line to start with a # or ! then the character should be escaped by an @ symbol. Similarly, @@ will yield a single @. Note that it is not necessary to escape !, # or @ within a !" block. It is also not possible to include the !" sequence at the start of a line within the !" block as this would finish the block.

DIRECTIVES AND VARIABLES

Contents Summary

5 .3 DIRECTIVES AND VARIABLES

Links

SYSTEM OVERVIEW

OTHER

DIRECTIVES AND VARIABLES

Contents Summary

5.3 DIRECTIVES AND VARIABLES

Links

SYSTEM OVERVIEW

OTHER

5 .3 DIRECTIVES AND VARIABLES