Introduction

BLAST Data Pump supports BLASTscript, a programming language for automating communications tasks. This chapter defines and illustrates BLASTscript's programming commands. BLASTscript Reserved Variables describes another important aspect of BLASTscript, the role played by reserved variables.

Quick Reference

The following list offers a quick reference to the BLASTscript commands supported by Data Pump. If you are not familiar with BLASTscript commands, be sure to read the sections following this list. These sections explain the data types used with BLASTscript commands and the BLASTscript command syntax.

ASCII ASK CALL CALLSUB CHAR CHECKSUM CLEAR CLEOL CONNECT CURSOR DATAPUMP DISCONNECT DISPLAY DROP ECHO ERRSTR ESC FCLOSE FILETRANSFER FLUSH

FOPENA FOPENAB FOPENR FOPENRB FOPENW FOPENWB FREAD FREADB FREADINISTRING FSEEK FWRITE FWRITEB FWRITEINISTRING GET GETENV GOSUB GOTO IF LCHDIR LDELETE

LET LISTCAT LISTDIRS LISTFILES LISTINX LISTITEM LISTLEN LISTTRIM LLIST LOAD LOG LOWER LPRINT LRENAME LRUN LSYSTEM LTYPE MENU OFFLINE ONLINE

PUT PWD QUIT RAISE RCHDIR RDELETE REPS RETURN RETURNSUB RLIST RPASSWORD RPRINT RRENAME RTYPE SEND SET SETPRINTER SETTRAP STRCAT #STRICT

STRINX STRLEN STRRINX STRTRIM TCAPTURE TRACE TSEND TTRAP TUPLOAD UPPER WAIT WAIT CARRIER WAIT IDLE WAIT UNTIL WERROR WHILE WRITE

For a list of the commands that set @STATUS, see The Status of @STATUS.

In a BLAST script, all data is stored as strings of text. Conversions to binary and numerical representations occur as needed during program execution.

Variables

Variables have global or file-local scope. Global variables start with @ and are followed by characters that identify the variable uniquely. There is no limit to the length of a variable name. For example, here are some legal variables:

@X @Fred @123_456 @A_very_long_variable_name

Some characters cannot be used in variable names. These characters are [ - : / + = * @ # ( ) , " ], and space. Variable names are not case sensitive. Thus, @Fred, @fred, and @FRED all refer to the same variable.

File-local variables start with @@. A file-local variable has meaning only within the script file where it is defined. These are some legal file-local variable names:

@@X @@Fred @@123_456

Scripts may contain global variables and file-local variables with the same name without conflict.

Numeric Constants

Except where specifically noted, numeric constants are unsigned integers. They may not be enclosed in quotation marks. For example:

4 268901

Time Constants

Time constants are clock times or durations. Clock times are written in HH:MM form (24-hour format). Durations are written in MM:SS form. The maximum duration is 60:59. For example:

2:31 16:00

String Constants

String constants are sequences of characters, preferably enclosed in quotation marks. Unquoted strings are limited to printable characters and may not contain the space (" "), pound sign ("#"), or comma (",") characters. When quoted, string constants may include these characters and any others defined by an escape sequence.

Escape sequences are initiated by \ or ^. Common control characters can be coded with simple escape sequences:

Additionally, any character value can be coded in a string constant using one of the following forms:

The ^ notation follows a usage common on UNIX platforms for denoting control characters (ASCII characters "0" to decimal "31"). Note that ^^ codes for a single ^ and that ^_ is not allowed. The notation ^@ codes for an ASCII NUL, \000. For a list of ASCII characters, see ASCII Character Set.

Escape sequences are not supported in unquoted strings.

These are examples of legal string constants:

C:\Tmp\Samplefile.txt "C:\\Tmp\\Samplefile.txt" "Four carriage returns: ^M \r \x0D \015"

Numeric Values

Numeric values may be numeric constants or variables.

String Values

String values may be string constants or variables.

BLASTscript Statements

Syntax

BLASTscript statements are executable commands or comments. Executable commands begin with a keyword, such as DISPLAY, and may be followed by one or more parameters (numeric values, string values, or constants). Parameters must be separated by a comma or whitespace (one or more space or tab characters). Comments begin with # and may be written on the same line as an executable command after all command parameters have been specified, or on a separate line.

Blank lines are ignored by the interpreter, and they may be used freely to improve readability. Indentation is also permitted for easier reading; the interpreter strips leading whitespace from statements before parsing.

In the reference section below, the following notation is used for describing the syntax of command parameters:

Remote commands (RCHDIR, RDELETE, RLIST, RPASSWORD, RPRINT, RRENAME, RTYPE) are executed within a FILETRANSFER-ESC block as shown in the example below:

CONNECT FILETRANSFER RLIST "*.txt" ESC

ASCII

ASCII value of a character in a string

FORMAT: ASCII sval [ , nval ]

ASCII sets @STATUS to the ASCII value of the character at position nval within sval. The first character position is 1. If nval is omitted, the value of the first character will be returned.

EXAMPLE:

set @filename = "\\path\\filename" ASCII @filename, 6 if @STATUS = 92 display @filename, " contains a backslash"

ASK	prompt for a string from the user

FORMAT: ASK [ NOECHO ] sval, @var

ASK prompts the user with sval at the top of the Script View. NOECHO suppresses the display of text that the user enters in response to the prompt. When the user presses ENTER, the user's input is stored into @var and @STATUS is set to "0." If the user presses ESC instead of ENTER, @STATUS is set to "-1."

EXAMPLE:

ASK "Enter month", @month

CALL	call another script

FORMAT: CALL sval

CALL loads and executes another BLAST script, after which the calling script resumes execution. sval is the pathname to the called program. If CALL is successful, @STATUS is set to "0." On return, @STATUS is set to the value of the return code given by the RETURN statement of the called script.

If a filename extension is not specified, the interpreter searches first for the given name and then for the filename formed by appending ".scr" if the search fails. The interpreter checks the current working directory, then Userscripts\, and finally the directory specified by the reserved variable @SCRIPTDIR. For example, if the script file is "Myscript," and the Blast directory is C:\DP\, and @SCRIPTDIR is C:\DP\Blast\Scripts\, the search path would be:

.\Myscript .\Myscript.scr C:\DP\UserScripts\Myscript C:\DP\UserScripts\Myscript.scr C:\DP\Blast\Scripts\Myscript C:\DP\Blast\Scripts\Myscript.scr

IMPORTANT: When writing a script that will be CALLed, you may not want assign a RETURN value of "1" if the calling script checks @STATUS to determine the success of CALL. Since @STATUS is set to "1" when a CALLed script cannot be found, assigning a value of "1" in the RETURN statement would invalidate the check of CALL.

EXAMPLE:

CALL "Myscript"

CALLSUB

call another script with preloading

FORMAT: CALLSUB sconst1 [ , sconst2 [ , sconst3 ] ]

CALLSUB transfers control to the script named by sconst1. On return, @STATUS is set to the value of the return code given by the RETURN statement of the called script. Execution of the calling script continues when sconst1 ends. The optional hint (sconst2) and mark (sconst3) primarily support Modems.scr, Systems.scr, and files of like structure. The hint is a BLASTscript command that the interpreter will execute before the first line of sconst1; typically the command is a GOTO statement. The mark is a label formatted in the manner of a BLAST Modem Type or System Type. For more information on CALLSUB, see GOSUB Statement.

EXAMPLE:

CALLSUB "modems.scr", "goto .DIAL", ":USROBOT"

CHAR	convert decimal into ASCII

FORMAT: CHAR nval

CHAR takes a variable or decimal integer and sets @STATUS to the corresponding ASCII character. This command is the logical inverse of the ASCII command.

EXAMPLE:

CHAR 87 display "87th ASCII character is = ", @STATUS        # displays a 'W'

CHECKSUM

calculate an error check for a string

FORMAT: CHECKSUM nval1, nval2, @var1, @var2 [, @var3] ...

CHECKSUM generates a checksum, CRC, or one's complement from a string (@var2 and additional variables) and stores the result in @var1. nval1 specifies the type of checksum to create (checksum, CRC, or none); nval2 specifies whether or not to apply the one's complement. When nval2 is set to "1," the one's complement for the particular CRC or checksum will be generated. If you wish to generate only a one's complement, set nval1 to "0." When nval1 is "0," a one's complement for only the first byte of data will be generated.

TYPE nval1)                            ONE'S COMPLEMENT (nval2) 0 = None                                 1 = one's complement 2 = 16-bit CRC 3 = 32-bit CRC 4 = 8-bit checksum 5 = 16-bit checksum 6 = 32-bit checksum 7 = Motorola pager 3-byte ASCII checksum

EXAMPLE:

set @etx = "\003"                     # set @etx to ASCII value for ETX character set @reply = "data, data"             # assign value to @reply CHECKSUM 2, 0, @mylrc, @reply, @etx   # 16-bit CRC, 0 complement stored in @mylrc                                       # contents of @reply and @etx                                       # used to calculate CRC

CLEAR

clear the scrolling region

FORMAT: CLEAR

CLEAR clears the Script View.

EXAMPLE:

CLEAR

CLEOL

clear to the end of the line

FORMAT: CLEOL

CLEOL clears a line of the Script View beginning at the current cursor position.

EXAMPLE:

CLEOL

CONNECT

connect to a remote

FORMAT: CONNECT

CONNECT executes modem and system scripts that control the sequence of modem initialization, connection, and remote login. The value of @STATUS can be tested to determine whether the connection succeeded or failed. If CONNECT is successful, @STATUS is set to " 0." Nonzero values indicate an error. For a list of error codes, see Error Messages.

EXAMPLE:

CONNECT if OK display "connection achieved" else display "connection error: ", @STATUS

CURSOR

position the cursor within the scrolling region

FORMAT: CURSOR nval1, nval2

CURSOR positions the cursor to a given row (nval1) and column (nval2) in the Script View. Normally, row values range from "0" to "19" and column values range from "0" to "79." If the "menu region" at the top of the Script View is disabled, however, row values can range from "0" to "24." See the description of the MENU command for a means of enabling and disabling the menu region.

Use PUT statements following cursor positioning to display text in the Script View.

EXAMPLE:

CURSOR @row, 17

DATAPUMP

communicate with BLAST Data Pump

FORMAT: DATAPUMP sval

DATAPUMP relays the message sval to Data Pump. Return messages from Data Pump are placed in the reserved variable @DATAPUMPREPLY.

DATAPUMP is intended primarily for troubleshooting. By issuing messages directly to Data Pump, the script interpreter and Data Pump may lose synchronization with unpredictable consequences.

EXAMPLE:

DATAPUMP "SELECT_PB NewYork JanetCrosby" display "DataPump answers: ", @DATAPUMPREPLY

DISCONNECT

disconnect from a remote

FORMAT: DISCONNECT

DISCONNECT executes programs in the System\ and Modem\ directories to log off and hang up the connection. The programs that are executed depend on the values of the reserved variables @MODEM and @SYSTYPE. If DISCONNECT is successful, @STATUS is set to "0." Nonzero return codes are defined by any modem and system scripts invoked by this command. See Connecting and Disconnecting for more information about the process of connecting and disconnecting.

EXAMPLE:

DISCONNECT

DISPLAY

display strings to display region

FORMAT: DISPLAY sval [ , sval ] ...

DISPLAY displays a line of text in the Script View. The text is also written to the log file.

EXAMPLE:

DISPLAY "Dialing... ", @PHONENO

DROP	DROP DTR/RTS

FORMAT: DROP {DTR | RTS }

DROP terminates signals on the RS-232 interface. If the value is DTR, the Data-Terminal-Ready signal drops, hanging up most modems (cable and modem configuration permitting). If the value is RTS, the Request-to-Send signal drops, causing some devices to stop transmitting. DROP DTR and DROP RTS commands are supported for standard internal (non-multiplexor) ports only. If DROP DTR or DROP RTS is successful, @STATUS is set to "0."

EXAMPLE:

DROP DTR DROP RTS

ECHO	enable/disable script display

FORMAT: ECHO { ON | OFF | MODE | NEST | @var }

ECHO is a diagnostic aid. ECHO ON displays the text of all BLASTscript statements as they are executed; ECHO OFF cancels the operation of ECHO ON. ECHO MODE displays the script interpreter's current operating mode. ECHO NEST displays the script interpreter's current nesting level. ECHO @var produces diagnostic output for the variable @var. Output is directed to the Script View and log file.

EXAMPLE:

ECHO ON set @myvar = "Science! True daughter of Old Time thou art!" ECHO @myvar ECHO OFF

ERRSTR

script error text

FORMAT: ERRSTR nval, @var

ERRSTR translates an error number nval to a descriptive string, which is stored in @var.

EXAMPLE:

fopenr 1, "nonexist_file" if not OK   ERRSTR @STATUS, @msg   display "File error: ", @msg end

ESC	end Filetransfer mode

FORMAT: ESC

ESC ends Filestransfer mode. This is the counterpart to the FILETRANSFER command.

EXAMPLE:

filetransfer "invtry.bin", "store003.bin", "bo" ESC

FCLOSE

close an open file

FORMAT: FCLOSE nval

FCLOSE closes the file denoted by the file handle nval. If FCLOSE is successful, @STATUS is set to "0."

EXAMPLE:

fopenw 4, "newfile" fwrite 4, "Hello" FCLOSE 4

FILETRANSFER

BLAST transfer command file

FORMAT: FILETRANSFER

FILETRANSFER initiates a filetransfer session.

For more information, see Transferring Files.

EXAMPLE:

FILETRANSFER if OK send "invtry.bin", "store003.bin", "bo" esc

FLUSH

clear the input buffer

FORMAT: FLUSH

FLUSH clears the communications port input buffer. Only characters received after the FLUSH command has been executed will be available.

EXAMPLE:

FLUSH               # empty buffer ttrap 10, "@"       # trap for "@"

FOPENA

open a file for appending in text mode

FORMAT: FOPENA nval, sval

FOPENA opens the filename sval for appending in text mode. Subsequent I/O operations on the file will reference the handle nval, not the filename. The handle can take any positive integer value 1 <= nval <= 32767, but may not be a handle that is already in use. (The conditional operator ISOPEN may be used to determine whether a given handle is in use.) If FOPENA is successful, @STATUS is set to "0" and the size of the open file is stored in @FILECNT.

EXAMPLE:

set @hndl = 6                              # pick an available handle while ISOPEN @hndl                         # in use?   let @hndl = @hndl + 1                    # go to next one end FOPENA @hndl, "C:\\Tmp\\Diary.txt"         # append in text mode if @STATUS = 0                             # successful open?   fwrite @hndl, @DATE, " -- Dear diary, it rained all day. "   fclose @hndl end

FOPENAB

open a file for appending in binary mode

FORMAT: FOPENAB nval, sval

FOPENAB opens the filename sval for appending in binary mode. Subsequent I/O operations on the file will reference the handle nval, not the filename. If FOPENAB is successful, @STATUS is set to "0" and the size of the open file is stored in @FILECNT. See also FOPENA.

EXAMPLE:

set @data = "\001_81:\002Temperature:\011 55\003"        # binary info FOPENAB 2, "C:\\Tmp\\temps.bin" if @STATUS = 0   fwriteb 2, @data   fclose 2 end

FOPENR

open a file for reading in text mode

FORMAT: FOPENR nval, sval

FOPENR opens the filename sval for reading in text mode. The file must already exist. Subsequent operations on the file will reference the handle nval, not the filename. The file handle, nval, may range from 1<= nval <= 32768. If FOPENR is successful, @STATUS is set to "0" and the size of the open file is stored in @FILECNT.

EXAMPLE:

FOPENR 1, "C:\\Tmp\\Diary.txt" while OK   fread 1, @item   if OK display @item end fclose 1

FOPENRB

open a file for reading in binary mode

FORMAT: FOPENRB nval, sval

FOPENRB opens the filename sval for reading in binary mode. The file must already exist. Subsequent operations on the file will reference the handle nval, not the filename. The file handle, nval, may range from 1<= nval <= 32768. If FOPENRB is successful, @STATUS is set to "0" and the size of the open file is stored in @FILECNT.

EXAMPLE:

FOPENRB 1, "C:\\Tmp\\Temps.bin" while OK   freadb 1, @data, 24               # 24-byte binary records   if OK gosub MessageData end fclose 1

FOPENW

open a file for writing in text mode

FORMAT: FOPENW nval, sval

FOPENW opens the filename sval for writing in text mode. If sval is the name of an existing file, the existing file is destroyed. The file handle, nval, may range from 1<= nval <= 32768. If FOPENW is successful, @STATUS is set to "0." After opening, I/O operations refer to the file by its file handle. A file that is open for writing is also open for reading.

EXAMPLE:

FOPENW @hndl, "C:\\Tmp\\Diary.txt" if @STATUS = 0   fwrite @hndl, @DATE, "Dear diary, this is my first message to you."   fclose @hndl end

FOPENWB

open a file for writing in binary mode

FORMAT: FOPENWB nval, sval

FOPENWB opens the filename sval for writing in binary mode. If sval is the name of an existing file, the existing file is destroyed. The file handle, nval, may range from 1<= nval <= 32768. If FOPENWB is successful, @STATUS is set to "0." After opening, I/O operations refer to the file by its file handle. A file that is open for writing is also open for reading.

EXAMPLE:

FOPENWB 2, "C:\\Tmp\\Temps.bin" if @STATUS = 0   fwriteb 2, "\001_81:\002Temperature:\011 55\003"   fclose 2 end

FREAD

read a line from a file

FORMAT: FREAD nval, @var

FREAD reads a line of text from a file into @var. The file is identified by the file handle nval used in the FOPENx statement for the file. If FREAD is successful, @STATUS is set to "0." A nonzero value indicates an error reading the file or the end of file.

EXAMPLE:

fopenr 1, "C:\\Tmp\\Diary.txt" while OK   FREAD 1, @item   if OK display @item end fclose 1

FREADB

read a block of data in binary mode

FORMAT: FREADB nval1, @var, nval2

FREADB reads a block of data from a file into @var, where the size of the block is given by nval2. The file is identified by the file handle nval1 used in the FOPENxB statement for the file. If FREADB is successful, @STATUS is set to "0." A nonzero value indicates an error reading the file or the end of file. The actual number of bytes read by the command is returned in @FILECNT.

EXAMPLE:

fopenrb 1, "C:\\Tmp\\Temps.bin" while OK   FREADB 1, @data, @blksize   if OK gosub MessageData end fclose 1

FREADINISTRING

read the value from a Windows .ini file

FORMAT: FREADINISTRING sval1, sval2, @var, sval3

FREADINISTRING returns the value of a key-value pair from a Windows initialization file (.ini file). The name of the section of the file in which the key-value pair is stored is given by sval1. The key name is given by sval2, and the .ini filename by sval3. The value of the key-value pair is returned in @var. FREADINISTRING can also return a list of section names for the .ini file or key names for a particular section. If FREADINISTRING succeeds in reading the .ini file, @STATUS is set to "0."

To retrieve the value of a key, all parameters in the command are specified:

To retrieve a list of section names, sval1 (the section name) is coded as an empty string, and the value of sval2 is ignored but required. Section names are returned in @var as a list.

FREADINISTRING "", "anykeyname", @mysections,"C:\\Tmp\\geo.ini"

To retrieve a list of key names for a particular section, sval2 is coded as an empty string. The key names are returned in @var as a list.

FREADINISTRING "CapitalCities", "", @mykeys, "C:\\Tmp\\geo.ini"

For more information about list operations, see LISTITEM and other commands in the list family.

The complete path to the .ini file is needed unless the file resides in the Windows\ directory.

FSEEK

move file pointer in an open file

FORMAT: FSEEK nval1, { BEGIN | END | nval2 }

FSEEK moves the file pointer to a new location in the file. The command takes the file handle nval1 and a second parameter describing how the pointer is to be moved. To move the pointer to the beginning of the file, use the BEGIN keyword. To move the pointer to the end of the file, use the END keyword.

In files open for binary-mode operations, the pointer can be moved a specific number of bytes from its current position by specifying nval2, the number of bytes to move. nval2 can be negative to move the pointer backwards in the file. Do not use this option with files opened for text-mode operations, since byte counts are handled differently in text mode.

If FSEEK is successful, @STATUS is set to "0."

EXAMPLE:

fopenab 1, "data.bin"          # open for writing FSEEK 1, -34                   # move back 34 bytes freadb 1, @in, 7               # can also read (7 bytes) FSEEK 1, end                   # go to the end fwriteb 1, @DATE, "\000"       # write something fclose 1                       # close

FWRITE

write a line to a file

FORMAT: FWRITE nval, sval [, sval1 ] ...

FWRITE writes one or more strings sval to a file as a single line of text. nval refers to the file handle assigned in an FOPENW or FOPENA statement. If FWRITE is successful, @STATUS is set to "0."

EXAMPLE::

fopenw 1, "WBY.txt" FWRITE 1, "Once more the storm is howling, and half hid" FWRITE 1, "Under this cradlehood and coverlid" FWRITE 1, "My child sleeps on." fclose 1

FWRITEB

write a block of data to a file in binary mode

FORMAT: FWRITEB nval, sval [ , sval1 ] ...

FWRITEB writes one or more strings sval to a file as a block of data. Unlike FWRITE, FWRITEB does not add line termination characters to the block. nval refers to the file handle assigned in an FOPENWB or FOPENAB statement. If FWRITEB is successful, @STATUS is set to "0."

EXAMPLE::

fopenwb 1, "Binary.bin" FWRITEB 1, @DATE, ":", "\x00\x01\x02\x03\x04\x05" fclose 1

FWRITEINISTRING

write a key-value pair to a Windows .ini file

FORMAT: FWRITEINISTRING sval1, sval2, sval3, sval4

FWRITEINISTRING writes a key-value pair into a Windows initialization file (.ini file). sval1 is the section of the file where the key-value pair will be stored, sval2 is the key name, sval3 is the value to write, and sval4 is the name of the .ini file. If necessary, new sections and keys are created by the command. The complete path to the .ini file is required unless the file resides in the Windows\ directory.

EXAMPLE:

set @section = "CapitalCities" set @key = "France" set @value = "Paris" FWRITEINISTRING @section, @key, @value, "C:\\Tmp\\geo.ini"

GET	receive a file

FORMAT: GET sval1 [ , sval2 [ , sval3 ] ]

GET instructs Data Pump to receive a file from the remote connection. sval1 is the remote filename, sval2 is the local filename, and sval3 specifies any valid transfer options. Because there is no provision in Xmodem for specifying the remote file, sval1 is ignored. It is, however, required.

When sval1 specifies a single file, sval2 optionally specifies the name to give the file on the local machine. For example:

If sval2 is omitted, the file is saved with the same name in the present working directory.

With BLAST protocol and FTP, transfers of multiple files are specified with the wildcards *, ?, and %. Substitutions of any length are specified with * and substitutions of a single character are specified with ?. When * or ? are used to form the remote filespec, % is required in sval2 to form the local filespec. % acts as a place holder for the filenames generated by the remote connection. For example, the statement

GET "/halloween/*.lis", "C:\\Tmp\\%"

will get all files matching the filespec /halloween/*.lis on the remote machine and save them in the C:\Tmp\ directory of the local machine. Thus, the files

/halloween/guests.lis /halloween/costumes.lis /halloween/tricks.lis

will be transferred to the "C:\Tmp\" directory as

C:\Tmp\guests.lis C:\Tmp\costumes.lis C:\Tmp\tricks.lis

There is no provision within the Xmodem protocol for doing wildcard transfers. Thus, file transfer templates are unsupported.

The transfer options, given in sval3, are:

Transfer options can be grouped. For example, to receive a text file and overwrite an existing file of the same name:

GET @file_remote, @file_local, "to"

However, you cannot combine a, o, and r in the same group of options. Similarly, t and b cannot be combined together. For more information about transfer options, see Transferring Files.

EXAMPLE:

set @PROTOCOL = "BLAST" FILETRANSFER GET @file_remote, "C:\\Tmp\\local.txt", "t" GET "/u/file???.txt", "%", "to" ESC

GETENV

retrieve the value of an environment variable

FORMAT: GETENV sval, @var

GETENV retrieves the value of a DOS environment variable (not a value from the system registry).

EXAMPLE:

GETENV "COMSPEC", @mycomspec

GOSUB

invoke a subroutine

FORMAT: GOSUB sconst

GOSUB invokes a subroutine defined within the current script file. A subroutine is a section of code prefixed by a subroutine declaration and terminated with a RETURNSUB statement. A subroutine declaration consists of the SUB keyword followed by the subroutine name. The subroutine must be unique for that script file. For more on GOSUB, see GOSUB Statement.

EXAMPLE:

GOSUB MySubroutine display "All done!" return # SUB MySubroutine display "This is my subroutine" returnsub

GOTO	branch to another point in program

FORMAT: GOTO sconst

GOTO branches in a script to another location in marked by the label sconst. Labels begin with a period (dot) and obey the same naming convention as variables.

EXAMPLE:

.PWD ask noecho "Enter the secret password", @secret if @secret = "rosebud" GOTO .CONTINUE werror "Invalid" GOTO .PWD .CONTINUE display "Good morning, Mr. Phelps"

IF, IF-ELSE

perform action for true or false conditions

FORMAT:

IF test expression [ { AND | OR } test expression ] ... statement

IF test expression [ { AND | OR } test expression ] ... statement
ELSE statement

IF test-expression [ { AND | OR } test expression ] ...
statement block
END

IF test expression [ { AND | OR } test expression ] ...
statement block
END
ELSE
statement block
END

IF executes a statement (or statement block) based on a test expression. The optional ELSE clause executes if the test fails. With some exceptions, statement can be any executable BLASTscript command.

A statement block contains one or more executable commands or comments, including other IF and IF-ELSE statements up to a nesting of 32 levels. The keyword END terminates the block.

Test expressions take several forms. The first form is valid for string comparisons, the second is for numeric comparisons, and the third form comprises special operations. For a discussion of script statements, see Making Decisions.

String comparisons:

sval1 [ NOT ] { > | >= | < | <= | = | != } sval2

where

> Greater than >= Greater than or equal to < Less than <= Less than or equal to = Equal to != Not equal to

The comparison is based on ASCII values and the length of sval1 and sval2. The sense of the comparison is reversed if NOT is used in the expression.

Numeric comparisons:

nval1 [ NOT ] { GT | GE | LT | LE | EQ | NE } nval2

where

GT--Greater than GE--Greater than or equal to LT--Less than LE--Less than or equal to EQ--Equal to NE--Not equal to

The sense of the comparison is reversed with NOT.

Special comparisons:

[NOT] NULL @var
True [false] when the length of @var is zero.

[NOT] @var
True [false] when the value of @var is greater than zero. The value of a null string is zero.

[NOT] nconst
True [false] when nconst equals @STATUS.

[NOT] REPS
True [false] when the REPS counter is greater than zero. The value of the REPS counter is automatically decremented by this expression if it is not already "0."

[NOT] EXIST sval
True [false] when sval refers to an existing file.

[NOT] ISDIR sval
True [False] when sval refers to an existing directory.

[NOT] OK
True [false] when @STATUS = 0.

[NOT] ISOPEN nval
True [false] when nval refers to an open file handle.

IF statements can perform more complex testing when test expressions are joined by AND or OR. Expressions are evaluated left-to-right without grouping; parentheses are permitted for readability, but they are ignored by the interpreter.

Some commands cannot be used as the statement in a single-line IF or single-line ELSE. The commands are:

other IF or ELSE statements
END
WHILE
the REPS command
#STRICT
FILETRANSFER

This restriction does not apply to block IF or block ELSE statements.

EXAMPLE:

IF EXIST "file.one" ldelete "file.one" IF NOT NULL @PHONENO display "@PHONENO is not empty" ELSE ask "What phone number", @PHONENO IF @USERID = "fred" AND NOT NULL @PASSWORD   gosub Conn   IF OK     gosub Xfer     gosub Disc   END   ELSE display "Could not connect! " END

LCHDIR

change working directory

FORMAT: LCHDIR sval

LCHDIR changes the current working directory on the local computer to the directory specified in sval. If LCHDIR is successful, @STATUS is set to "0."

EXAMPLE:

LCHDIR "C:\\Blast"

LDELETE

delete a file on the local system

FORMAT: LDELETE sval

LDELETE deletes the file named by sval on the local computer. If LDELETE is successful, @STATUS is set to "0."

EXAMPLE:

LDELETE "C:\\Tmp\\Jazz.lib"

LET	perform simple arithmetic

FORMAT: LET @var = nval1 [ { + | - | * | / } nval2 ] ...

LET performs integer arithmetic. The expression is evaluated left-to-right with no grouping or operator precedence.

EXAMPLE:

LET @count = @count + 1

LISTCAT

build a list

FORMAT: LISTCAT @var, sval1 [ , sval2 ] ...

LISTCAT adds one or more items sval to the end of a list @var. The list may be initially empty. The syntax of the command is similar to STRCAT.

Items are separated by the list delimiter character (@LISTDELIM). By default, the delimiter character is the ASCII NUL ("\000"). Generally this value is safe to use, but to handle lists properly in a DISPLAY statement, the delimiter must be changed to another value (commonly, a tab character, "\t"). The delimiter must be set before the list is created and any list manipulations are performed.

EXAMPLE:

set @LISTDELIM = "\t" set @list = "" LISTCAT @list, "eggs", "milk", "bread"

LISTDIRS

format a list of directories

FORMAT: LISTDIRS [ sval ], @var

LISTDIRS formats a list of directories from sval and saves it in the variable @var. If LISTDIRS is successful, @STATUS is reset.

EXAMPLE:

set @LISTDELIM = "^I"         # make horizontal tab list delimiter LISTDIRS "C:\\", @dirlist display @dirlist

LISTFILES

format a directory listing

FORMAT: LISTFILES [ LONG | SHORT ] sval, @var

LISTFILES formats a directory listing from sval and saves it in the variable @var. When LONG is specified, sizes and time stamps are included in the listing. If LISTFILES is successful, @STATUS is reset.

EXAMPLE:

LISTFILES short, "*.txt", @dirlist listlen @dirlist set @last = @STATUS set @itemnum = 1 while @itemnum LE @last   listitem @dirlist, @itemnum, @item   display "File: ", @item   let @itemnum = @itemnum + 1 end

LISTINX

find an item in a list

FORMAT: LISTINX @var, sval

LISTINX searches a list for a matching item and sets @STATUS to the list position of the match or "0" if no match was found. The syntax is similar to STRINX.

EXAMPLE:

set @LISTDELIM = "\t" set @list = "" listcat @list, "harmonica", "whistle", "kazoo" LISTINX @list, "whistle" display "'whistle' found at position ", @STATUS, " in the list"

LISTITEM

copy an item from a list

FORMAT: LISTITEM @var1, nval, @var2

LISTITEM copies the item at position nval in the list @var1 to @var2.

EXAMPLE:

set @LISTDELIM = "\t" set @list = "" listcat @list, "eggs", "milk", "bread" LISTITEM @list, 2, @item display "Don't forget to buy chocolate ", @item

LISTLEN

report number of items in a list

FORMAT: LISTLEN @var

LISTLEN sets @STATUS to the number of items in a list. The syntax is similar to STRLEN, which sets @STATUS to the number of characters in a string.

EXAMPLE:

set @LISTDELIM = "\t" set @magazines = "" listcat @magazines, "Newsweek", "People", "Granta", "Dr. Dobbs" LISTLEN @magazines display "The list has ", @STATUS, " items" strlen @magazines display "The list has ", @STATUS, " characters"

LISTTRIM

extract a list from another list

FORMAT: LISTTRIM @var, nval1 [ , nval2 ]

LISTTRIM extracts an item or a list of consecutive items from a list @var. The new list replaces the original list. Items are extracted from position nval1 to position nval2. If nval2 is omitted, all items from nval1 to the end of the list are extracted. (The syntax is similar to STRTRIM, with item positions substituting for character positions.)

EXAMPLE:

set @LISTDELIM = "\t"                  # so we can display the list set @magazines = "" listcat @magazines, "Time", "People", "Granta", "Dr. Dobbs" LISTTRIM @magazines, 3, 4              # same as: listtrim @magazines, 3 display "the only serious magazines: ", @magazines

LLIST

display a listing of files on the system

FORMAT: LLIST [ LONG ] sval

LLIST displays a list of files as specified by sval. The output is sent to the Script View and the log file. Filename templates may be used. If "LONG" is specified, the listing will contain additional information about the files listed rather than just the filenames. If LLIST is successful, @STATUS is reset.

EXAMPLE:

LLIST LONG "*.GIF"

LOAD	load a phonebook listing

FORMAT: LOAD [ sval1 , ] sval2

LOAD loads a phonebook listing sval2 from the phonebook sval1. If sval1 is omitted, the listing will be loaded from the current phonebook. If LOAD is successful, @STATUS is set to "0."

EXAMPLE:

LOAD "Midwest", "Chicago"          # opens Midwest.pbk and reads Chicago.pbl gosub PollThis LOAD "Moline"                      # assumes Midwest.pbk is open gosub PollThis

LOG	control a log file

FORMAT: LOG { sval | CLOSE | OPEN sval }

LOG controls the log file associated with the current phonebook listing. LOG CLOSE closes the file. LOG OPEN sval opens the log file sval. LOG sval writes the message sval to an open log.

Time stamps are automatically appended to each entry in the log. The format of the time stamp is controlled by the reserved variable @LOGDATEFORMAT. By default, the format for time stamps is "%m/%d/%y %M:%H:%S," but the format may be set by the script.

EXAMPLE:

set @LOGDATEFORMAT = "%d/%m/%Y %M:%H:%S"       # gives 4-digit years LOG open C:\tmp\transfer.log LOG "Hi, Mom!" LOG close

LOWER

change uppercase to lowercase

FORMAT: LOWER @var

LOWER changes the uppercase characters in @var to lowercase.

EXAMPLE:

set @quiet = "I FEEL LIKE SHOUTING" LOWER @quiet

LPRINT

print a file on the local printer

FORMAT: LPRINT sval1 [ , sval2 ]

LPRINT prints the file svar1 to the local printer identified by the reserved variable @BPRINTER (see SETPRINTER for more information). If LPRINT is successful, @STATUS is set to " 0."

If sval2 is provided, that string is printed as a header line at the top of each page of output. If sval2 is omitted, no header is printed. A null string prints the filename as the header.

EXAMPLE:

LPRINT @file               # no header LPRINT @file, ""           # header: filename & page # LPRINT @file, @DATE        # header: date & page #

LRENAME

rename a file on the local system

FORMAT: LRENAME sval1, sval2

LRENAME renames the file sval1 to the new name sval2 on the local system. If LRENAME is successful, @STATUS is set to " 0."

EXAMPLE:

LRENAME "file1.txt", "file2.txt" LRENAME @filename1, @filename2

LRUN	launch an application

FORMAT: LRUN [HIDE] sval [, nval ]

LRUN launches the application sval on the local system. HIDE causes the application named in sval to run in a "minimized" state. If nval is given, it specifies the maximum number of seconds to wait for the application to finish before executing the next script command. If the application did not successfully launch, @STATUS is set to "-1." If nval seconds elapse before the application exits, @STATUS is set to "-2." If nval is omitted or is "0," the next script command is executed immediately.

EXAMPLE:

LRUN "notepad.exe", 60           # wait up to 60 sec to type something if @STATUS = -2 display "Hurry up!"

LSYSTEM

execute a shell command

FORMAT: LSYSTEM [ svar ]

LSYSTEM executes a shell command svar. If the command could not execute, @STATUS is set to "-1." If svar is omitted, the system shell is opened for interactive use.

EXAMPLE:

set @syscmd = "dir *.txt /b > C:\\Tmp\\dir.txt" LSYSTEM @syscmd

LTYPE

type a file on the local screen

FORMAT: LTYPE svar

LTYPE displays the contents of a text file svar in the Script View. If LTYPE is successful, @STATUS is set to "0."

EXAMPLE:

LTYPE "jnk.txt"

MENU	enable/disable menu display during script execution

FORMAT: MENU { ON | OFF }

The "menu" area consists of the top four lines of the Script View and includes indicators for the current file transfer protocol, script name, and the session ID (stored in @SESSIONID) as well as lines for operator messages and interactive keyboard input. Normally the menu region is enabled (MENU ON), which leaves the lower 21 lines of the Script View available for other display purposes. The menu region can be disabled with the command MENU OFF to permit a script to display text in all 25 lines of the Script View.

EXAMPLE:

MENU ON ask "What is your name", @name MENU OFF

OFFLINE

close port

FORMAT: OFFLINE

OFFLINE releases the communications port. The port becomes available for use by another script (or another software program). When Offline, the variable @COMMOPEN is set to "0."

Communications parameters such as baud rate, port address, etc., should be set while offline because changes to these parameters are only registered at an offline-to-online transition.

EXAMPLE:

OFFLINE                        # release the port set @BAUDRATE = "9600"         # new baud rate online                         # reacquire the port at 9600 bps

ONLINE

open port

FORMAT: ONLINE

ONLINE acquires the communications port specified in the reserved variable @COMMPORT when @TRANSPORT is set to "serial," or acquires the port specified by @NETSERVICE when @TRANSPORT is "socket." It is not normally necessary to issue this command since the interpreter issues it automatically if a script statement is encountered that requires access to the port (i.e., TSEND, CONNECT, etc.). Scripts can check @COMMOPEN to determine if ONLINE (either explicit or implied) has succeeded. When online, @COMMOPEN is set to "1."

EXAMPLE:

ONLINE if not @COMMOPEN   if @TRANSPORT = "serial" werror "can't open ", @COMMPORT   else werror "can't reach ", @NETSERVICE   return end

PUT	output strings to the scrolling region

FORMAT: PUT sval1 [ , sval2 ] ...

PUT displays one or more text strings in the Script View. There is no implicit new line after the output. PUT is usually used in conjunction with CURSOR.

EXAMPLE:

PWD @whereami cursor 9, 30 PUT "The present working directory is ", @whereami

PWD	write present working directory

FORMAT: PWD @var

PWD writes the present working directory location to the variable @var.

EXAMPLE:

PWD @whereami

QUIT	quit BLAST Data Pump application

FORMAT: QUIT [ nval ]

QUIT aborts the BLAST Data Pump application and returns control to the shell with nval set to the exit code. If nval is omitted, the exit code is "0." When QUIT is executed in the debugger, the script terminates but the application does not exit.

EXAMPLE:

QUIT 14

RAISE

RAISE DTR/RTS

FORMAT: RAISE {DTR | RTS }

RAISE raises the Data-Terminal-Ready signal (DTR) or the Request-to-Send signal (RTS) on the RS-232 interface. These signals are normally used with modems. Some systems have DTR and RTS tied together so that raising either one affects both signals. RAISE DTR and RAISE RTS commands are supported for standard internal (non-multiplexor) ports only. If RAISE DTR or RAISE RTS is successful, @STATUS is set to "0."

EXAMPLE:

RAISE DTR RAISE RTS

RCHDIR

change directory on the remote

FORMAT: RCHDIR sval

RCHDIR changes the directory on the remote computer to sval. This command is valid for FTP and the BLAST protocol only.

EXAMPLE:

RCHDIR /u/dcb

RDELETE

delete a file on the remote

FORMAT: RDELETE sval

RDELETE deletes a file sval on the remote computer. This command is valid for FTP and the BLAST protocol only.

EXAMPLE:

RDELETE /u/dcb/old_342.txt

REPS	set repetition counter

FORMAT: REPS nval

REPS is used to make a loop in BLAST scripts, where nval is the number of repetitions of the loop. Loop testing is performed in an IF statement. REPS loops cannot be nested.

EXAMPLE:

REPS 3                    # three times .AGAIN display "Hello" if REPS goto .AGAIN display "Goodbye"

RETURN

return control

FORMAT: RETURN [ nval ]

RETURN returns control to the script that called the current script. @STATUS is set to nval, or "0" if nval is omitted.

EXAMPLE:

RETURN 1        # return to caller with @STATUS = 1

RETURNSUB

return to a calling program

FORMAT: RETURNSUB [ nval ]

RETURNSUB returns execution control to the line following the GOSUB call that initiated the current subroutine. @STATUS is set to nval, or "0" if nval is omitted.

EXAMPLE:

RETURNSUB 1

RLIST

list remote files

FORMAT: RLIST [ LONG ] sval

RLIST requests a list of files from the remote system. If "LONG" is specified, additional information about the files will be returned. The command is valid only for FTP and the BLAST protocol. Output is directed to the File Transfer Status dialog and the file named in @EFLOG.

EXAMPLE:

RLIST LONG "*.txt"

RPASSWORD

send a password to the remote

FORMAT: RPASSWORD sval

RPASSWORD transmits a password (sval) to the remote computer. If sval matches the Transfer Password of the remote computer, the local computer will be given permission to perform file maintenance on and file transfers to and from the remote computer. If sval does not match, the local computer will be restricted to sending and receiving messages. This command is valid only for the BLAST protocol.

NOTE:  This command is required only when the remote computer has set Transfer Password or @TRPASSWD to something other than null.

EXAMPLE:

filetransfer RPASSWORD "stor234pw" get "data.txt", "data.txt", "to" esc

RPRINT

print a remote file

FORMAT: RPRINT sval

RPRINT prints a remote file on the remote system. This command is valid only for the BLAST protocol.

EXAMPLE:

RPRINT @remfile

RRENAME

rename a remote file

FORMAT: RRENAME sval1, sval2

RRENAME renames a file on the remote system. The old name is sval1 and the new name will be sval2. This command is valid only for FTP and the BLAST protocol.

EXAMPLE:

RRENAME "/u/dcb/sales.dat", "/u/dcb/sales_01.dat"

RTYPE

type a remote file

FORMAT: RTYPE sval

RTYPE opens a text file sval on the remote system and writes its contents to the File Transfer Status dialog and the file specified by @EFLOG on the local system. This command is valid only for the BLAST protocol.

EXAMPLE:

RTYPE "/u/dcb/sales_01.dat"

SEND	send a file

FORMAT: SEND sval1 [ , sval2 [ , sval3 ] ]

SEND instructs Data Pump to send a file. sval1 is the local filename, sval2 is the remote filename, and sval3 specifies any valid transfer options. Because there is no provision in Xmodem for specifying the remote file, sval2 is ignored. It is, however, required.

For FTP and the BLAST protocol, sval1 defines a file specification that may including wildcards for sending multiple files. If sval1 specifies a single file, sval2 optionally specifies the name to give the file on the remote machine.

For example:

SEND "C:\\Tmp\\halloween.txt", "/halloween/party_ideas"

If sval2 is omitted, the file is saved with the same name in the present working directory on the remote system.

Transfers of multiple files are specified through the wildcards *, ?, and %. Substitutions of any length are specified with *, and substitutions of a single character are specified with ?. When * or ? are used to form the local filespec, % is required in sval2 to form the remote filespec. The % character is a place holder for the filenames generated by the local connection.

For example:

SEND "C:\\Tmp\\*.lis", "/halloween/%"

will send all files matching the filespec C:\Tmp\*.lis on the local machine and save them in the /halloween/ directory of the remote machine. Thus, the files

C:\Tmp\guest.lis C:\Tmp\music.lis C:\Tmp\treats.lis

will be transferred to the /halloween/ directory as

/halloween/guest.lis /halloween/music.lis /halloween/treats.lis

There is no provision within the Xmodem protocol for doing wildcard transfers. Thus, file transfer templates are not supported.

The transfer options, given in sval3, are:

Transfer Option	BLAST		FTP		Xmodem
	GET	SEND	GET	SEND	GET	SEND
T (Text)	X	X	X	X
O (Overwrite)	X	X	X		X
A (Append)	X	X	X		X
S (Store)	X	X
F (Forward)	X	X
CN (Compression, level)	X	X
N (No Overwrite)	X	X	X		X
B (Binary)	X	X	X	X

Transfer options can be grouped. For example, to send a text file and overwrite an existing file of the same name:

SEND @file_local, @file_remote, "to"

However, you cannot combine a, o, and r in the same group of options. Similarly, t and b cannot be combined together. For more information about transfer options, see Transferring Files.

EXAMPLE:

set @PROTOCOL = "BLAST" FILETRANSFER SEND @file_local, "/u/tmp/remote_file", "t" SEND "C:\\Tmp\\file???.txt", "%", "to" ESC

SET	set script variables to a string

FORMAT: SET @var = sval

SET assigns a string value to a variable.

EXAMPLE:

SET @PHONENO = "555-1212"

SETPRINTER

specify printer

FORMAT: SETPRINTER { DEFAULT | FIRST | NEXT }

SETPRINTER allows a script to select the printer used by LPRINT. The normal operating mode is SETPRINTER DEFAULT. In this mode, changes to the default printer made in the Windows Control Panel are reflected in the printer used by LPRINT. The options FIRST and NEXT are used to iterate through the available printers. @STATUS is set to a nonzero value when the last available printer has been selected. The name of the currently selected printer and the port to which it is attached is held in @BPRINTER.

When SETPRINTER FIRST or SETPRINTER NEXT is used, the last printer selected will be used by LPRINT regardless of the setting in the Windows Control Panel. SETPRINTER FIRST must be issued to initialize the list pointer before SETPRINTER NEXT is called.

EXAMPLE:

let @num = 0 SETPRINTER FIRST while OK   let @num = @num + 1   display "Printer: ", @BPRINTER   SETPRINTER NEXT end display "There are ", @num, " printers installed. " return

SETTRAP

capture commport data to a script variable

FORMAT: SETTRAP @gvar, nval1 [ , nval2 ]

SETTRAP prepares a TTRAP statement to capture incoming data into a user-defined variable. Note that it does not perform the capture itself--one or more TTRAPs must follow it. Once a SETTRAP is executed, it remains in effect until another SETTRAP is issued.

@gvar specifies the variable to hold the data. Because SETTRAP can affect the operation of TTRAP statements in other scripts that are called, the variable must be global in scope.

nval1 defines the maximum number of characters to save in @gvar. An overflow will save only the last nval1 characters in the variable. Setting nval1 to "0" cancels the operation of SETTRAP.

nval2 specifies the maximum number of characters that each TTRAP will scan. If this value is reached before a trigger string matches, TTRAP will set @STATUS to "-5." This feature is disabled by setting nval2 to "0" or omitting it.

EXAMPLE:

SETTRAP @cap, 10, 85        # capture data into @cap: 10 chars max,                             # ttrap exits if 85 chars received before matching ttrap 6, "\015"             # trap next carriage return SETTRAP @cap, 20            # no char-count; ttrap will either timeout or match ttrap 45, "logout"          # wait for "logout" SETTRAP @cap, 0             # turn off SETTRAP

STRCAT

combine strings

FORMAT: STRCAT @var, sval1 [ , sval2 ] ...

STRCAT appends sval1 to the end of @var.

EXAMPLE:

set @s1 = "def" set @alpha = "abc" STRCAT @alpha, @s1, "ghi" display "@alpha = ", @alpha       # displays "abcdefghi"

#STRICT

force BLAST Professional for DOS compatibility

FORMAT: #STRICT

#STRICT forces the script interpreter to check the syntax of script statements for compatibility with BLAST for MS-DOS. If an incompatible statement is found, the error is flagged but script execution continues. This feature is intended for assisting customers who maintain scripts for older platforms. #STRICT does not monitor variable usage. As a result, it does not guarantee compatibility (i.e., reserved variables that can be modified under DOS BLAST but are fixed under Data Pump remain fixed even under #STRICT interpretation).

The "#" character is part of the command name. This syntax allows DOS BLAST to execute a script containing #STRICT without error, because the command will appear to be a comment to the DOS BLASTscript interpreter. Consequently, #STRICT cannot be executed in a one-line IF or ELSE statement, i.e.:

IF OK #STRICT           # won't work

There is no mechanism for disabling #STRICT interpretation once it has been specified.

EXAMPLE:

# Daily_s.txt # daily upload script # #STRICT # connect if OK   filetransfer          # multi-line syntax required by DOS BLAST end                     # for filetransfer; still works in version 11.0, daily.txt               # though not recommended new/daily.txt t esc end disconnect quit                    # End of script.

STRINX

find the first occurrence of one string in another

FORMAT: STRINX @var, sval1

STRINX finds the first occurrence of sval1 in @var. @STATUS is set to the starting character position of sval1 in @var, or "0" if there is no match.

EXAMPLE:

set @string = "anemometer" STRINX @string, "mom" display "found 'mom' at position = ", @STATUS       # = 4

STRLEN

determine the length of a string

FORMAT: STRLEN @var

STRLEN sets @STATUS to the length of @var.

EXAMPLE:

STRLEN @string display "The length of @string is ", @STATUS

STRRINX

find the last occurrence of one string in another

FORMAT: STRRINX @var, sval1

STRRINX finds the last occurrence of sval1 in @var. @STATUS is set to the starting character position of the last occurrence of sval1 in @var, or "0" if there is no match.

EXAMPLE:

set @string1 = "0123456789123456" STRRINX @string1, "3" display "The number 3 occurs last at position ", @STATUS

STRTRIM

extract a string from another string

FORMAT: STRTRIM @var, nval1 [ , nval2 ]

STRTRIM extracts a substring from @var. @var is set to the substring that begins at position nval1 and ends at position nval2.

EXAMPLE:

set @name = "A:\\file.dat" set @drive = @name STRTRIM @drive, 1, 3              # "A:\" set @filename = @name strlen @name                      # get length of string STRTRIM @filename 4, @STATUS

TCAPTURE

enable text file capture

FORMAT: TCAPTURE { ON [ APPEND | OVERWRITE ] sval | OFF }

TCAPTURE enables or disables data capture to the file sval while in terminal mode (i.e., when a file transfer is not in progress). Append and Overwrite are used only with ON to indicate whether an existing file should be appended or overwritten. If neither is specified, Append is assumed.

@STATUS is set to "0" if sval was successfully opened for writing.

After capturing data, it is best to perform a WAIT IDLE or TTRAP to be sure that a stopping point has been reached in the data stream before closing the capture file.

EXAMPLE:

TCAPTURE ON APPEND "C:\\Tmp\\capfile.txt" tsend "ls -l", lf wait 2 idle                # wait for 2 seconds of idle on the commport TCAPTURE OFF

TRACE

control trace of script execution

FORMAT: TRACE { ON | OFF }

TRACE traces the operation of the script interpreter. Tracing is enabled with TRACE ON and disabled with TRACE OFF. Output is sent to the file Tsessionid.txt in the BLAST Logs\ directory, where sessionid is an identification number for the BLAST session. The session ID is held by the reserved variable @SESSIONID.

TRACE produces more information than ECHO, but in a form that can be harder to interpret. In addition, trace files can become very large because of the amount of information generated by the command. Experiment with both commands to determine the appropriate level of debugging information needed in a particular case.

EXAMPLE:

TRACE ON        # show me what you're doing connect TRACE OFF       # ok, that's enough

TSEND

send strings to the remote computer

FORMAT: TSEND { sval | CR | LF } [ , { sval | CR | LF } ] ...

TSEND transmits carriage returns (CR), linefeeds (LF), and strings (sval) to the remote connection. If TSEND is successful, @STATUS is set to "0."

NOTE: An @STATUS setting of "0" indicates only that the characters were successfully transmitted, not that they were successfully received by the remote computer.

EXAMPLE:

TSEND "ATDT", @PHONENO, CR

TTRAP

trap for output from the remote computer

FORMAT: TTRAP [ tconst | nconst ] sval1 [ , sval2 ] ...

TTRAP pauses script execution until a timeout occurs, specified by tconst (MM:SS) or nconst (a duration in seconds), or until one of the specified strings sval is encountered in the incoming terminal data stream. The timeout defaults to "0" (indefinite wait, no timeout) if none is specified. When TTRAP exits, it sets @STATUS to the position of the matching string in the list, or "0" if a timeout has occurred.

The timeout cannot be specified with a variable.

EXAMPLE:

TTRAP 5:30 "DONE", "done"                     # 5 min, 30 sec TTRAP 45 "CONNECT", "NO CARRIER", "VOICE"     # 45 seconds TTRAP @exitstring

TUPLOAD

upload a text file to the remote system

FORMAT: TUPLOAD sval

TUPLOAD opens the file specified by sval and sends its contents to the remote computer. The transmission is paced by any flow control specified in the phonebook listing. TUPLOAD sets @STATUS to "0" on completion of the text upload. If an error occurs, @STATUS is set to an error code. For a list of error codes, see Error Messages.

The reserved variable @UPLOADEOL holds the end-of-line terminator string that will be transmitted at the end of each line of text. @UPLOADEOL defaults to ^M (a carriage return).

Some device drivers buffer the flow of data extensively. This means that TUPLOAD may finish well before all the characters in the file clear the local driver buffer. After performing a TUPLOAD, you should TTRAP for a prompt signaling the end of the upload or perform a WAIT IDLE.

EXAMPLE:

set @UPLOADEOL = "^J"        # use line feed to terminate lines TUPLOAD "file.txt" ttrap 4, "$"                 # wait for remote prompt to come back

UPPER

convert lowercase to uppercase

FORMAT: UPPER sval

UPPER changes all lowercase characters in svar to uppercase.

EXAMPLE:

UPPER @salesdata

WAIT	wait for time to pass

FORMAT: WAIT { tconst | nval }

WAIT pauses a script for a duration of tconst or nval seconds.

EXAMPLE:

WAIT 2:02     # wait 2 minutes, 2 seconds WAIT 45       # wait 45 seconds

WAIT CARRIER

wait for phone call

FORMAT: WAIT { tconst | nval } CARRIER

WAIT CARRIER pauses a script for a duration of tconst (MM:SS) or nval seconds, or until a Data Carrier Detect signal is asserted at the serial port. If the modem raises carrier detect, @STATUS is set to "0." If the statement times out, @STATUS is set to a nonzero value. This command is not compatible with network connections.

EXAMPLE:

WAIT 2:02 CARRIER         # wait 2 min, 2 sec, or until DCD is asserted WAIT 45 CARRIER           # wait 45 sec, or until DCD is asserted

WAIT IDLE

wait for communications port activity to finish

FORMAT: WAIT { tconst | nval } IDLE

WAIT pauses a script until no characters are received at the communications port for a duration of tconst (MM:SS) or nval seconds. If WAIT IDLE is successful, @STATUS is set to "0."

EXAMPLE:

WAIT 2:02 IDLE     # wait for 2 minutes, 2 seconds of quiet WAIT 45 IDLE       # wait for 45 seconds of quiet

WAIT UNTIL

wait until a clock time

FORMAT: WAIT UNTIL { tconst | sval }

WAIT UNTIL pauses a script until the specified clock time.

EXAMPLE:

WAIT UNTIL 14:20     # wait until 2:20 pm WAIT UNTIL 2:02      # wait until 2:02 am

WERROR

write an error message to the screen

FORMAT: WERROR sval1 [ , sval2 ] ...

WERROR displays a message string to the operator and also writes it in the log file. WERROR pauses the script until the operator presses the ENTER key if the reserved variable @ONERROR is set to the value "STOP." The script will not pause if @ONERROR is set to "CONTINUE."

EXAMPLE:

WERROR "No response from ", @COMMPORT

WHILE

execute until a condition is false

FORMAT:

WHILE test-expression
statement-block
END

WHILE executes a statement block until its test expression is false.

The test expression is evaluated in the same manner as an IF statement. In particular, constant values are compared to the value of @STATUS. For example, the following code fragment opens a text file for reading and displays each line:

fopenr 1, "filenames.txt" WHILE (0)                         # true if @STATUS=0, ie, no error   fread 1, @input   if (0) display @input           # ditto end fclose 1

Note that the expression WHILE ("0") will be true as long as @STATUS = 0. This mode of evaluation differs from many programming languages such as C, which treats the constant "0" as false.

Care should be exercised when combining WHILE and GOTO commands. In particular, it is possible to jump into or out of a WHILE-END block with a GOTO statement. In such cases, the following behavior is expected:

Goto Into a While Block

In this case, the conditional expression at the top of the WHILE block is not executed. The test is performed at the bottom of the block as usual. Example:

goto .INSIDE WHILE @firstclasspostage LT 40          # skipped by GOTO   display "skipped first"               # skipped   .INSIDE   display "displayed first" end                                     # still loops!

Goto Out Of a While Block

It is sometimes convenient to use a GOTO statement to exit a WHILE block prematurely, simulating the break keyword of other programming languages. This technique is legal in BLAST scripts, as shown:

set @true = 1 WHILE (@true)                            # forever   ask "Connect now (Y/N)", @yn   upper @yn   if @yn not = "Y" goto .OUTSIDE         # break   call "goconnect.scr" end .OUTSIDE

However, careful use of IF logic can usually avoid the necessity of GOTO.

EXAMPLE:

WHILE @count LE 4   let @count = @count + 1 END

WHILE not exist "C:\\tmp\\semaphore.txt"   display "just waiting around for the semaphore"   wait 10 END

WRITE

write a message to the second menu line

FORMAT: WRITE sval1 [ , sval2 ] ...

WRITE displays a message to the operator and writes it to the log file without pausing the script as in WERROR.

EXAMPLE:

WRITE "dialing Chicago at: ", @TIME

Command Comparison Chart

The following chart compares support of commands by different versions of BLAST.

x = supported command
o = optional
+ = command recognized for backward compatibility only; not recommended for use in new scripts