Special Command File Functions

 

The table below lists the special functions supported by DADiSP command files. A detailed discussion of each function follows. These functions cannot be nested as arguments to regular commands or functions. Note that the @CR is not used following any of the special command file functions.

 

Function

Description

@BEEP

Causes your computer to emit an audible beep.

@CALL

Executes the specified command file n times from within the current command file.

@HIGHLIGHT_MESSAGE

Displays a message in reverse video on the Status Line.

@LOAD

Executes the specified command file from within the current command file.

@MESSAGE

Displays a message in normal video on the Status Line.

@PAUSE

Pauses the command file for the specified number of seconds.

@POP

Displays a pop-up text box on the screen.

@PULLDOWN

Activates a pull-down menu.

@RETURN

Exits a command file.

@SUSPEND

Temporarily suspends command file execution until one of the specified terminator keystrokes is received. The terminator keystroke is passed to the command file.

@SUSPEND_NOPASS

Temporarily suspends command file execution until one of the specified terminator keystrokes is received. The terminator keystroke is not passed to the command file.

@UNPOP

Clears a specific pop-up box from the screen.

@WAIT

Stops execution of the command file for the specified number of seconds.

@WAITKEY

Stops execution of the command file until any key is pressed.

 

Detailed descriptions of the command file functions listed in the table above follow.

 

@BEEP(n)

Causes your computer to emit an audible beep. Extend the length of the beep by setting the argument n to the number of beeps in a row. For example, @BEEP(1) causes a very short beep, and @BEEP(100) causes a longer beep.

 

@CALL("command_file", n)

Executes the specified command file n times from within the current command file. After the called command file completes, the current command file resumes execution from the next statement. @CALL is useful for creating loops in a command file. Use @RETURN to return from the called command file.

 

@HIGHLIGHT_MESSAGE("text")

Displays a message in reverse video on the Status Line.

 

@LOAD("command_file")

Executes the specified command file from within the current command file. After the loaded command file completes, the current command file resumes execution from the next statement. Use @RETURN to return from the called command file.

 

@MESSAGE("text")

Displays a message in normal video on the Status Line.

 

@PAUSE(t)

Pauses the command file for the specified number of seconds. For example, @PAUSE(3) inserts a pause of 3 seconds before continuing to process the command file. This is helpful when you want the user to read a pop-up message box or a message on the status line. You can override a pause by a hitting any key, although the space bar is probably the safest key to hit.

 

@POP("name", x, y, "text")

Displays a pop-up text box on the screen. For example, @POP("p1", 4, 3, "This is my message."), displays a text box at x=4, y=3, that says: "This is my message.". The upper left hand corner of the box is located at x characters from the left and y characters from the top. The upper left hand corner of the screen is the origin (0,0). The screen has dimensions of 80 columns (x) by 24 rows (y). To center the box horizontally, set x = -1; to center the box vertically, set y = -1. To allow the user to read the text in the pop-up text box, include an @PAUSE or an @WAIT. Use @UNPOP to remove the text box from the screen. Unlike most functions typed at the command line during a DADiSP session, note that double quotes must surround the name of the pop-up text box, as well as the text within the box. If the text you wish to display in the pop-up text box includes quotes, they must be single quotes.

 

@PULLDOWN

Activates a pull-down menu. For example, @PULLDOWN F O S executes the pull-down menu choices for File, Open, Series.

 

@RETURN

Exits a command file. If the command file was launched with an @CALL or an @LOAD statement, control is returned to the calling command file.

 

@SUSPEND("terminator keystrokes")

Temporarily suspends command file execution until one of the specified terminator keystrokes is received. When the command file is suspended, the user is placed into an interactive mode, and can type commands into DADiSP normally until the specified terminator character or keystroke is pressed. Command file execution resumes after the terminator character or keystroke is pressed. The terminator keystroke (i.e., last key pressed) is passed to DADiSP.

For example:

 

 @SUSPEND("@F1 @F2 @F4")

 

suspends execution of the command file until either the F1, F2, or F4 function key is pressed. The pressed key is passed to DADiSP, and the command file resumes processing.

 

 @SUSPEND("@CR ")

 

suspends execution of the command file until a carriage return is pressed. The carriage return is passed back to the command file. This is helpful following an INPUT statement, for example:

 

! suspend.dsp

mystring=input(3) @CR

@SUSPEND("@CR")

echo(mystring) @CR

@return

 

Note: There is no error checking on the @SUSPEND function. When a terminating character is found, the command file resumes, regardless of the success or failure of the intervening operations.

 

@SUSPEND_NOPASS("terminator keystrokes")

Temporarily suspends command file execution until one of the specified terminator keystrokes is received. When the command file is suspended, the user is placed into an interactive mode, and can type commands into DADiSP normally until the specified terminator character or keystroke is typed. Command file execution resumes after the terminator character or keystroke is typed. Unlike the @SUSPEND function, the last key pressed is not passed to DADiSP.

For example:

 

 @SUSPEND_NOPASS("@F9 @SP Z Q")

 

suspends execution of the command file until any one of the F9, Spacebar, Z or Q keys is pressed. The command file resumes processing without passing the pressed key through to DADiSP. The following command file statements display a text box and wait for the @CR before unpopping the text box. If you @SUSPEND instead of @SUSPEND_NOPASS, the @CR will be passed to the command file and cause you to enter the Window.

 

! SuspNoP.dsp

moveto(w1) @CR

grandom(100,.01) @CR

@POP("pop1",-1,-1,

"

This is random data.  

Hit the [Enter] key  

to continue. 

")

@SUSPEND_NOPASS("@CR")

@UNPOP("pop1")

@RETURN

 

Note: There is no error checking on the @SUSPEND_NOPASS function. When a terminating character is found, the command file resumes, regardless of the success or failure of the intervening operations.

 

@UNPOP("name")

Clears a specific pop-up box from the screen. For example, @UNPOP("p1") clears the pop-up text box "p1" from the screen. If you have popped several boxes onto the screen, be sure to unpop them in reverse order of creation. If you neglect to unpop a pop-up text box, the bitmap beneath the box will not be updated properly. If you try to unpop a pop-up text box that does not exist, you will receive an error message.

 

@WAIT(t)

Stops execution of the command file for the specified number of seconds. For example, @WAIT(3) inserts a pause of 3 seconds before continuing to process the command file. This is helpful when you want the user to read a pop-up message box or a message on the status line. You can not override the pause; @WAIT forces a timed pause in command file execution regardless of any keystrokes.

 

@WAITKEY

Stops execution of the command file until any key is pressed. This is helpful when you want the user to read a pop-up message box or a message on the status line, and you want confirmation (via a keystroke) before resuming execution of the command file.