home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Windoware
/
WINDOWARE_1_6.iso
/
comm
/
softrm
/
scripts.doc
< prev
next >
Wrap
Text File
|
1992-08-18
|
152KB
|
4,022 lines
Script Files
Important
To be used, a script file must be configured in a
Script profile.
Softerm's script files act much like the operating
system's batch and command files by automating
repetitious operations. The script language is
optimized for communications tasks. Because
communications operations involve data, Softerm's
Script language includes many file and data
manipulation functions.
Script files are standard text files and can be
created using almost any editor or word processing
program which can create and save files in standard
ASCII format. A description of the command syntax is
included in this section.
Script Language Capabilities
The Script language format is constructed from the
basic capabilities typically asssociated with
programming languages. These capabilities include:
Functions
o File transfer, disk file manipulation, error
processing, operator input
Text String Manipulation
o Maximum text string length of 255 characters
o Text string catenation
Numeric Operations
o Numeric range of -2,147,483,648 to +2,147,483,647
o Operations including Not, Addition, Subtracttion,
Multiplication, Division, Arithmetic AND,
Arithmetic OR, Arithmetic XOR, Assignment
Variable Manipulation
o Assignment
Conditional Processing
o IF/ELSE, Less Than, Less Than or Equal To, Equal
To, Not Equal To, Greater Than or Equal To,
Greater Than, Logical AND, Logical OR
Script File Operation
When a script file is started, a window opens and,
depending upon the setting of script window control
functions, displays some or all of this information:
o A title that contains the Session name and file
name of the running script.
o A menu that provides control over the script file
operation:
o Cancel script operation
o Start and Cancel the Watch script function
operation
o A client area where script commands are displayed
during Watch and where the MESSAGE command
displays text.
o The current path being used by the Script.
o The full path and file name of the active script.
Operation Message File
When operation of a script file starts and ends,
appropriate information text messages are written to
the file, SOFTERM.MSG, in the user's SOFTERM write
file directory. This information typically will
contain the following:
o Session name
o Script file name
o Initiation message
o Operation error message (if applicable)
o Statement where operation error occurred
o Stop message: normally or by operator
In Case of Error
When a function produces an error other than a
simple file or data processing error, one of the
following will occur:
1. Fatal errors will cause script file operation to
be cancelled.
2. Non-fatal errors will cause script file operation
to continue at the defined error processing label
(determined by the ONERR function) or, if no
error processing label is defined, script file
operation will be cancelled. Read-only system
variables are available that will contain the
error code, error level and error text for the
implementation of suitable error recovery
procedures.
- 2 -
Script Language Syntax
This section provides a brief overview of the
Softerm script language. Each component also is
described fully in separate sections.
Syntax Rules
1. An input line consists entirely of the data
between one '>' character which is in the first
column and the next '>' character which is in the
first column. The exception is, of course, the
last command in the script file.
2. An input line may contain only a single script
language statement. However, a statement may
consist of multiple functions.
3. Text strings and variables containing text
strings are interchangeable throughout the script
language.
4. Numerics and variables containing numerics are
interchangeable throughout the script language.
Variable Classification
Softerm's script language recognizes three
classifications of variables:
o User-defined variables, such as:
> TXTVAR = 'This is a test.'
> NUMVAR = 42
o Assignable predefined system variables, such as:
> BAUD = 9600
o Read-only predefined system variables, such as:
> IF ERRORLEVEL == 6
Function Identification
Functions are identified as such by enclosing their
arguments between parentheses. This includes those
functions that require no arguments. For example:
> EXAMPLE() ;is a function
> EXAMPLE ;is a variable
Result Codes
All functions return a result so that relatively
complex and meaningful statements may be
constructed. For example, while the following
command is valid, little can be done with it:
> NEXTFILE (filedef)
- 3 -
However, by using the returned result, a useful
statement is created, such as:
> SFILE = NEXTFILE (filedef)
> IF GETLENGTH (SFILE) < 5
> GOTO NO_MORE
> ENDIF
Important: Except where noted, this result code
will be a zero value for success or an error code
value in the case of a failure.
Arguments
A function argument may be any valid expression.
For example:
> WRITELINE(HANDLE,'Error code = ' + VALTOSTR(ERRORCODE))
Function arguments must be separated with commas.
Function arguments that have predefined default
values may be specified as null. For example:
> EXAMPLE(arg1,,,arg4)
Trailing function arguments that have predefined
default values may be omitted.
Remarks
A remark is all remaining data within a statement
that follows a semi-colon.
> EXAMPLE(arg1,arg2) ;this is a remark
Labels
A label that is the target of a discontinuity is
signified by a colon following the label operand,
such as:
> ERRORLABEL:
> BEGIN:
Label names are not case sensitive, but they must
begin with a letter. Only the first 10 characters
are significant.
User Variable
User variables are not case sensitive, but they must
begin with a letter.
- 4 -
Script File Format
Script files exist on disk as text files. Within
the text file, a function is defined by a keyword
and possible arguments. The general format of a
command in a script file is:
> RESULT = KEYWORD (arg1,arg2,...,argn)
The > character is required to identify the line as
the start of a statement and must be the first non-
blank, non-tab character on the line. Any other
character occurring as the first non-blank, non-tab
character on the line indicates that the line is a
continuation of a previous command. Carriage
returns and line feeds and any blank or tab
characters following the carriage return or line
feed are considered to be white space and may be
used to separate keywords, arguments, and switches.
Inserting Special Functions
The acronyms listed in Appendix A, ASCII Character
Codes, and the tilde (~) character are used to
insert characters which normally are interpreted as
special functions into an argument. Command lines
can contain any of the 128 ASCII characters,
including control characters. For example, the
following character sequences can be used to allow
function characters to be inserted in strings:
Sequence Function
[CR] Insert a carriage return into strings
[LF] Insert a line feed into strings
[ddd] Insert a character into strings where
ddd is the decimal ASCII value of the
character from 0-255. Up to 3 decimal
digits can be used. For example, [7]
will insert a BEEP.
~any char Insert characters into strings. For
example, use ~~ to insert a tilde and ~[
to insert a bracket. Note: The tilde
prefix can be redefined by the ESCAPE
assignable predefined system variable
for use within Script functions.
Note: The conversion from internal nomenclature to
destination character is performed only when the
text is prepared for transmission, such as by the
Send, Receive and Xmit_Wait functions.
Directory Paths and File Names
File names used with these commands may include a
drive specifier and a complete directory path from
the root directory of the drive, including the
special symbols backslash (\), period (.), or double
- 5 -
period (..). If no directory path is specified, the
directory path displayed on the bottom row of the
progress frame window will be used. If the direc-
tory path specified does not begin with the root
directory, Softerm assumes the directory path
specified begins with the current default directory.
Wildcard Characters
Softerm allows global or wildcard characters to be
used in file names for most file transfer commands
performed by Softerm. The wildcard characters
asterisk (*) and question mark (?) indicate the
portion of a file name which may be ignored or which
may match any series of characters. The asterisk is
used to match any string of characters and the
question mark is used to match single characters.
An * used alone or *.* will match all file names.
An *. will match only file names with no extension.
The use of file name wildcard characters is
identical to the operation of these characters when
specified for standard DOS operations. The command
will be performed on all files whose file names meet
the subset specification.
Script File Language
Softerm's script file script language consists of
three basic groups: Variables and Parameters;
Functions; and Directives.
Variables and Parameters
The Softerm script language can use string
variables, consisting of sequences of alphanumeric
text up to 255 characters long, and numeric
variables, consisting of an integer from
-2,147,483,648 through +2,147,483,647.
Characters in a string are numbered from left to
right beginning with 1. A number of functions are
defined for the manipulation of the variables.
Important: If you set a variable equal to a numeric
value, remember that Softerm stores numeric values
in binary format; not decimal. Refer to the
description of the VALTOSTR() function which
converts binary data to decimal.
Variables are referenced by a name which consists of
an alphanumeric string between 1 and 255 characters
in length and which begins with an alpha character.
Note: The space used to store variable names and
values is limited. If many variables are used in a
- 6 -
script file, the length of variable names should be
kept to a minimum.
Script Variables
Script Variables, also called Parameters, are a
special type of string variable. These text
variables are used to import values to, and export
values from, script files.
Softerm recognizes five Script Variables, each of
which can be 64 characters long. Values for these
parameters can be assigned within script files. In
addition, these parameters can be defined when a
script file is initiated and used by the script file
as arguments to modify the operation of the script
file. For additional information, please refer to
the Script File Profile and Session Window: Options
Menu chapters.
Script Variables are referenced by the special
symbols SV1 through SV5, representing parameter 1
through parameter 5, respectively. When encountered
in a script file, the value of the specified Script
Variable is substituted in the script file for the
parameter name before the command containing the
parameter is evaluated. This allows the
modification of Script Variable values by the script
file.
When a CHAIN command is performed to stop the
current script file and start another one, the new
script receives all the defined variables. This
allows the values of variables from one script file
to be passed to another script file. All variables,
except the ERRORCODE variable and the Script
Variables, may be cleared with the VCLEAR command.
This allows unused variable storage to be reclaimed.
Expressions
An expression is a series of one or more variables,
constants or literals (operands) separated by
operators. The evaluation of an expression yields
either a string or a numeric result, depending on
the type of operators in the expression.
Constants are numeric values and may be combined
with other constants or numeric variables in an
expression.
Literals are string values and may be combined with
other literals or string variables in an expression.
- 7 -
The following command illustrates the definition of
a numeric variable:
> NUMBER = 5
The result of this command is to define NUMBER as a
numeric variable and assign it the constant value of
5. The following commands do the same thing:
> NUMBER = 2
> NUMBER = 10 / NUMBER ; / signifies
division.
The following illustrates the definition of a string
variable:
> STRING = "Hello, Mikey"
The result of this command is to define STRING as a
string variable and assign it the literal value of
"Hello, Mikey". The following command does the
same:
> STRING = 'Hello, ' + 'Mikey'
The plus sign is a catenation operator, used to
combine the two strings.
Expression Evaluation Order
Expressions are evaluated in left to right order
(there is no operator precedence), unless
parentheses are used to alter the evaluation order.
Using parentheses will force the evaluation of the
expression inside the parentheses before combining
it with the operand to the left of the parenthesized
expression.
Numeric Constants
Numeric constants may be integer decimal, binary,
octal, and hexadecimal numbers and may range in
value from -2,147,483,648 through +2,147,483,647.
The format of a numeric constant is:
Type Format Example
Decimal ±nnnn 15
Octal ±0nnnnO 017O
Hexadecimal ±0nnnnH 0FH
Binary ±0nnnnB 01111B
Important: A numeric constant not beginning with 0
is treated as a decimal.
- 8 -
Literals
Literals are strings enclosed in single (') or
double quotes ("). They may contain any
alphanumeric characters and may be up to 255
characters in length.
Operators
! Logical Not + Plus
- Minus * Multiply
/ Divide & Arithmetic AND
| Arithmetic OR ^ Arithmetic Exclusive OR
< Less Than > Greater Than
= Assignment <= Less Than or Equal To
== Identical To >= Greater Than or Equal To
&& Logical AND != Not Identical To
|| Logical OR
Unary Arithmetic Operators
The !, + and - symbols are unary arithmetic
operators. They affect the value associated with
the constant or numeric variable which follows the
symbol.
! invokes the NOT function, causing a boolean
True/False evaluation of the expression following
the not operator (!). A non-zero result is
evaluated as False; a zero result is evaluated
as True. For example, IF !EXIST (filename) will
perform a set of instructions if the file is not
found.
+ is optional on all numeric values, and implies
normal interpretation of the value.
- causes a numeric value to be negated, transform-
ing a positive value to a negative value, or a
negative value to a positive one.
Binary Arithmetic Operators
The + and - signs also may be binary operators.
+ Addition
- Subtraction
* Multiplication
/ Division
& Arithmetic AND function; the two operands are
ANDed bit by bit to produce the resultant numeric
value.
| Arithmetic OR function; performs an inclusive OR
on the operands.
^ Performs an arithmetic exclusive OR of the two
operands.
- 9 -
Binary String Operators
The + sign also is a binary string operator.
Separating two string values, either literal or
variable, causes the catenation of the two strings to
form the resultant string value.
Relational Operators
Relational operators, also called logical operators,
are used in the IF directive to test the relation
between numeric or string variables. When comparing
strings, the operation is not case sensitive; that
is, 'abc' is equivalent to 'ABC'. The result of a
relational operation is either True (any non-zero
result) or False (a zero result).
For example:
> TYPE = 'BEETLE'
> IF MAKER == 'FORD' && TYPE == 'MUSTANG'
yields a False value, while:
> IF (ROW >= 24) || (COLUMN >= 79)
> GOTO CONTINUE
> ENDIF
yields a True value when you reach row 25 or column
80 of the screen. Note: Screen coordinates are zero
relative. That is, the point 0,0 defines the top
left corner.
File Transfer Errorlevel Codes
These codes are returned to the Script file and can
be used for error processing at an ONERR label. For
additional information, refer to the ERRORLEVEL,
ERRORTEXT, GETERRORTEXT(), IF(), and ONERR system
variables, directives and functions.
Code Type Of Error
0 None
1 Timeout
2 Line failure (Retry count expired
or loss of carrier)
3 Operator cancel
4 Remote cancel
5 DOS error
6 Expression evaluation error
Variable Names
Variable names can contain only alphanumeric
characters (A-Z, 0-9) and must begin with an alpha
character (A-Z). Softerm is case insensitive when
searching for variable names; there is no
- 10 -
distinction between lower case and upper case.
Thus, number and NUMBER refer to the same variable.
Softerm decides that a string refers to a variable
name rather than a literal string by whether or not
it is enclosed in quotation marks.
System Variables and Reserved Names
Softerm includes special variables which allow you
to access system information from within script
files for use in expressions.
Important: These names are reserved for use by
Softerm and must not be used as variable names.
Very unpredictable results can occur.
Assignable Predefined System Variables
These system variables can be used on the left side
of an equality and set to a valid value. For
example:
> DATABITS = 7
BAUD Numeric variable which can be set to a
valid baud rate in the range 50 through
57600, such as: > BAUD = 9600
DATABITS Numeric variable which can be set to a
value in the range 7 through 8, such
as: > DATABITS = 7
ESCAPE Text variable which defines the lead-in
character to be used. This variable
defaults to the tilde (~) character.
Additional information is available in
the Inserting Special Functions heading
above.
PARITY Numeric variable which can be set to
one of the following values: NONE,
ODD, EVEN, MARK, SPACE, such as: >
PARITY = NONE
RXPACING Numeric variable which can be set to
one of the following values: NONE,
XON_XOFF, DTR, RTS, such as: >
RXPACING = XON_XOFF
SPEED Numeric variable which can be set to a
value in the range 0 through 255
milliseconds, such as: > SPEED = 25
The default value is 0. The SPEED
variable defines a transmit character
delay which allows a delay between
characters transmitted on the
communications line. This variable
- 11 -
could be used when the host computer is
not able to accept characters as fast
as the actual line speed allows.
STOPBITS Numeric variable which can be set to 1
or 2.
TIMEOUT Numeric variable which can be set to a
value in the range 0 through 65535
seconds. The default value is 15. The
TIMEOUT variable specifies the delay
tolerated before cancelling a DIAL or
XMIT_WAIT operation. A value of 0
indicates that there is an unlimited
timeout period.
TXPACING Numeric variable which can be set to
one of the following values: NONE,
XON_XOFF, XON_XOFF_PAIRS, CTS, DSR, DCD
Read-Only Predefined System Variables
These system variables are not user-settable.
Instead, they are updated as required and, as a
general rule, are used in conditional processing.
For example:
> IF ERRORLEVEL == 3
CONNECT Logical variable which may be tested
TRUE or FALSE indicating if a connection
currently is established.
CTS Numeric variable which may be used to
set TXPACING, such as: > TXPACING = CTS
DATE String variable that holds the current
date in MM/DD/YY format when referenced.
DAY Numeric variable that holds the current
day (1-31).
DCD Numeric variable which may be used to
set TXPACING, such as: > TXPACING = DCD
DSR Numeric variable which may be used to
set TXPACING, such as: > TXPACING = DSR
DTR Numeric variable which may be used to
set RXPACING, such as: > RXPACING = DTR
ERRORCODE Numeric variable that contains the error
value of the last function that
terminated with a serious error. This
variable will be set correctly only
during ONERR processing.
- 12 -
ERRORLEVEL Numeric variable in the range 0 through
6 which contains the Errorlevel Code
(discussed above and in the description
of the IF() function). This variable
will be set correctly only during ONERR
processing.
ERRORTEXT Text variable which contains the text
related to the ERRORCODE. ERRORTEXT may
be displayed using the MESSAGE function.
This variable will be set correctly only
during ONERR processing.
FALSE Opposite of TRUE. An expression which
evaluates to a zero result is FALSE.
HOUR Numeric variable that holds the current
hour (0-23)
MINUTE Numeric variable that holds the current
minute (0-59).
MONTH Numeric variable that holds the current
month (1-12).
NONE Numeric variable which may be used to
set TXPACING and RXPACING, such as: >
RXPACING = NONE
OFF Numeric variable with the value of zero.
(False)
ON Numeric variable with the value of one.
(True)
PATH String variable that holds the full path
of the current directory.
PORT Text variable that contains the name of
the Connection Path used by the
currently-running script file.
RTS Numeric variable which may be used to
set RXPACING, such as: > RXPACING = RTS
RXDATA Text variable containing the last 255
characters received by the most recent
XMIT_WAIT function
SECOND Numeric variable which holds the current
second (0-59)
- 13 -
SESSIONNAME Text variable which holds the name of
the current Session as displayed in the
Session Manager window.
TIME String variable that holds the current
time in HH:MM 24-hour format.
TRUE Used to test the result of a logical
expression. An expression which
evaluates to a non-zero result is TRUE.
When it is returned from a function,
TRUE will have the value of 1.
USERNAME If Host Mode optional logon processing
is in effect, this string variable holds
the current username of 32 characters,
blank filled.
WEEKDAY Numeric variable which contains the day
of the week in the form 0 (Sunday)
through 6 (Saturday).
XON_XOFF Numeric variable which may be used to
set TXPACING and RXPACING, such as: >
TXPACING = XON_XOFF
XON_XOFF_PAIRS Numeric variable which may be used
to set TXPACING, such as:
> TXPACING = XON_XOFF_PAIRS
YEAR Numeric variable that holds the current
year.
Script Functions and Directives
Softerm file transfers are controlled by the
following directives and functions which may require
additional parameters:
(semi-colon) Comment
: (colon) Label (name) a command sequence
location
AUTOANSWER() Enable and disable an auto-dial
modem's Auto-Answer mode
BREAK() Transmit a communications break
signal
CANCEL Cancel the operation of a script
file
CHAIN() Transfer script operation to a new
script file
CHDIR() or CD() Change default directory
- 14 -
CHRTOVAL() Returns the numeric value of any
ASCII character (for example, '1'
is returned as 49)
CLOSE() Close a specified open disk file
CLOSEALL() Close all open files
CONVERSE() Exit to online operation
COPY() Copy a file
DELETE() Delete a file
DIAL() Establish a communications
connection
ELSE Alternate conditional processing
END End of script file
ENDIF End conditional processing
EXIST() Check for the existence of a
particular file
EXIT Terminate the current script file
and the current runtime session.
FINDLINE() Search an open file for a
particular text string
FIRSTFILE() Return information about the first
file found in the given path/file
name template
FIXLENGTH() Sets the length of a text string
by padding with spaces or by
truncating
GETERRORTEXT() Converts any numeric value to its
related error text (if there is
any). In particular, this would
be used to create the error text
for a result code which is
returned by a function.
GETLENGTH() Returns the numeric value of the
length of a text string
GOTO or JUMP Go to a Label
HANGUP() Disconnect, lower DTR
- 15 -
HOST() Initiate a Host mode -- unattended
interaction
IF Begin conditional processing
INPUT() Accept operator text input to the
script
LOG() Begin logging
LOWER() Convert a string to all lower-case
MESSAGE() Displays a message in the progress
frame window, no wait
MKDIR() Create a disk directory
NEXTFILE() Returns an information text string
for the next file matching the
file name template specified in a
FIRSTFILE function
NOLOG() End logging
ON() Branch in a Script file based on a
received value
ONERR Use this directive to provide a
label to which Script processing
will be redirected in the event of
a serious error which otherwise
would cause Script operation to
terminate
OPENNEW() Create and open a new disk file
OPENOLD() Open an existing disk file
PAUSE() Delay n seconds
PROMPT() Displays an information message
box until cancelled by the
operator
READ() Returns a text string from an open
file
READLINE() Returns a line of text from an
open file
RECEIVE() Transfer a file from a host to
your PC
RENAME() Rename a file
- 16 -
RESUME Resume operation after error
RETRY Retry last command
RSTATTR() Reset file attributes
SEND() Transfer a file from your PC to a
host
SETATTR() Set a file's attributes
SETBOF() During file operations, sets the
position of the internal file
pointer to the beginning of the
file
SETEOF() During file operations, sets the
position of the internal file
pointer to the end of the file
SKIP() During file operations, sets the
position of the internal file
pointer relative to the current
file position
STRFIND1() Returns the numeric position of
the start of a specified text
string within a text string
STRFIND2() Returns the numeric position of
any character from a specified
text list within a text string
STRGET1() Extracts a text string from a text
string by length
STRGET2() Extracts a text string from a text
string terminated by a specific
terminator character from a text
string
STRPUT() Replaces a text substring within a
text string
STRTOVAL() Returns the numeric value
representing an ASCII numeric text
string (for example, '456' is
returned as 456)
UPPER() Convert a string to all upper-case
VALTOCHR() Returns the ASCII character
representing a numeric value (for
example, 49 is returned as '1')
- 17 -
VALTOSTR() Returns the ASCII numeric text
string representing a numeric
value
VCLEAR() Clear all variables
VDEFINED() Check if a variable has been
defined
VDELETE() Clear a particular variable
WAIT() Wait for an event and return a
code
WRITE() Writes a text string to an open
file
WRITELINE() Writes a line of text to an open
file
XMIT_WAIT() Transmit a string, wait for a
reply
Script Window Control Functions
These functions control the separate window which may
be displayed by a script file. They are explained at
the end of this chapter:
WATCH() Display script commands and current
file and directory names in the
script window
WINDOWPOS() Set the upper left corner of a
script file window
WINDOWPRMS() Set menu and display options to be
used by a script window
WINDOWSHOW() Display a user-defined script
window
WINDOWSIZE() Set the size of the client area of
a script file window
WINDOWTITLE() Provide a title for a script file
window
- 18 -
Script Functions Descriptions
AUTOANSWER (arg1)
Function: Enable or Disable an auto-dial modem's
Auto-Answer mode
Syntax:
> AUTOANSWER (on)
> AUTOANSWER (off)
If this command is processed when a connection has
already been established, an error message similar
to the following will be generated: "Can not Change
Mode while Connected".
BREAK()
Function: Send a communications break signal of 255
milliseconds duration
Syntax:
> BREAK()
BREAK (arg1)
Function: Send a communications break signal for a
specified number of seconds
Syntax:
> BREAK (seconds)
The argument may be a numeric value in the range 1 -
9 which specifies of the break signal duration in
seconds.
CANCEL
Function: Cancel further script file processing
Syntax:
> CANCEL
This directive usually is used in combination with
the ONERR directive and IF ERRORLEVEL conditional
processing when it is desired to terminate
processing of the script file due to the type of
error encountered.
The current script file and log file are closed when
a CANCEL command is processed.
- 19 -
CHAIN (arg1)
Function: Terminate the operation of the current
script file and start another
Syntax:
> CHAIN (path_scriptname)
where:
PATH_SCRIPTNAME is the text string or defined
variable providing the location and name of the
script file to run.
Example:
> CHAIN ('c:\softerm\scripts\sethost.scr')
Use when a single script file cannot contain all the
commands required, or it is desired to segment the
operation of multiple operations. All file transfer
variables including the variable heap, error
processing retry count, transmit character delay,
and timeout value are unchanged after the CHAIN.
Logging will remain enabled if active.
Wildcard characters are not allowed in the file name
entered. When a CHAIN command is used, if the
specified script file does not exist, an error
message is displayed; the command is cancelled;
and operation of the current script file is
terminated.
CHDIR (arg1) and CD (arg1)
Function: Set a new default directory path
Syntax:
> CD (pathname)
where:
PATHNAME is the text string or defined variable
providing the drive and directory to which to
change.
Example:
> CD ('s:\database')
The new default directory including a drive
specifier and directory path is entered as an
argument on the command line. File names entered
for file transfer commands may include a drive
specifier and a complete directory path from the
root directory of the drive. If no directory path
- 20 -
is specified in a file name, the current default
directory path will be used. If the directory path
specified in a file name does not begin with the
root directory, Softerm assumes the directory path
specified begins with the current default directory.
CHRTOVAL (arg1)
Function: Returns the numeric value of any ASCII
character (for example, '1' is returned as
49)
Syntax:
> CHRTOVAL (ascii)
where:
ASCII is the ASCII character.
Example:
> NUM_VAL = CHRTOVAL ('Z')
The numeric variable NUM_VAL will contain the
decimal value 90.
The CHRTOVAL function can be used to extract control
codes from text variables. For instance, a Ctrl A
would be returned as 1. CHRTOVAL also can be used
to compute checksums (the sum of the ASCII values of
each character in a string).
CLOSE (arg1)
Function: Close an open file
Syntax:
> CLOSE (file_handle)
where:
FILE_HANDLE must be the name of a variable that
contains the handle returned by a previous file open
function
CLOSEALL()
Function: Close all open files
Syntax:
> CLOSEALL()
- 21 -
CONVERSE (arg1)
Function: Return to the online terminal operation
mode; stopping the current script file
Syntax:
> CONVERSE (initial_string)
where:
INITIAL_STRING is an optional string (maximum 35
characters) which may be entered as initial keyboard
input to the online terminal mode.
Example:
> CONVERSE ([CR])
The CONVERSE command is useful when an immediate
return to the online terminal mode is required from
a script file. The CONVERSE command is not valid
when used in a script file run when terminal mode is
not available.
COPY (arg1,arg2,arg3)
Function: Copy a file
Syntax:
> COPY (source,dest,if_exist)
where:
SOURCE is the source path and file name text string.
DEST is the destination path and file name text
string.
IF_EXIST is the option to use if a file with the
DEST name already exists. The options are:
Replace Overwrite the existing file with the new
file.
Append Add the contents of the new file to the
end of the existing file. This
generally is not a appropriate option to
use with binary files.
Fail Cancel the Copy operation. This is the
default.
- 22 -
Example:
> COPY ('c:\softerm\my.mdb',
's:\softerm\public\special.mdb',replace)
or
> SV3 = 'c:\softerm\my.mdb'
> SV4 = 's:\softerm\public\special.mdb'
> COPY (SV3,SV4,)
DELETE (arg1)
Function: Delete a file from the current or
specified directory
Syntax:
> DELETE (path_filename)
where:
PATH_FILENAME is the text string or defined variable
providing the location and name of the file to
delete.
Example:
> DELETE ('c:\softerm\softemp.999')
If no drive or directory path is entered, the file
is deleted from the current directory. You can use
the wildcard characters (?) and (*) in the file name
and in the extension.
If the file does not exist, no error is reported and
command processing will continue. All other DOS
errors will cause error processing to be performed.
DIAL (arg1,arg2,arg3,arg4)
Function: Establish a communications connection
Syntax:
> DIAL (handshake_trans,phone_num1,telnet_id,phone_num2)
Note: The number of arguments and their types depend
on the current connection path type and the
applicable Admittance Data dialog.
where:
HANDSHAKE_TRANS is a string which will be
transmitted automatically when a connection is made.
If no string is entered, this argument defaults to
either:
- 23 -
o The string used by a previous DIAL command, or
o The Handshake Transmission string as defined in
the Admittance Data configuration for the current
Session if no previous DIAL command has been
issued.
PHONE_NUM is the Phone Number or equivalent, such as
a Called DTE Address or Service Name. If no string
is entered, this argument defaults to either:
o The string used by a previous DIAL command, or
o The field which precedes the Handshake
Transmission field defined in the Admittance Data
configuration for the current Session if no
previous DIAL command has been issued.
Note: If the Admittance Data configuration has only
the Handshake Transmission field, the DIAL command
will have only one argument.
TELNET_ID is the Telephone Network ID string. If no
string is entered, this argument defaults to either:
o The string used by a previous DIAL command, or
o The Telephone Network profile defined in the
Admittance Data configuration for the current
Session if no previous DIAL command has been
issued.
Note: If the current Admittance Data configuration
does not have a Telephone Network profile field,
this argument is not applicable.
PHONE_NUM2 is the second telephone number (or
equivalent). For example, the IBM ACS connection
lets you dial by specifying the CBX Datagroup and
the Account ID. The DIAL() function might resemble:
> DIAL (,CBXData_Group,,Accnt_ID)
This example does not specify a handshake
transmission or a telephone network profile name.
Important
If an argument is not specified, DIAL will attempt
to make the connection using either the value
contained in the current Admittance Data
configuration field or the last value which was
used, whichever is more current. To ensure no value
is used for an argument, place a null-length string
in the argument's position. For example, the
following command would dial the Softronics'
Customer Service BBS without transmitting an initial
string and without using a Telephone Network ID:
> DIAL ('','17195939530','')
- 24 -
The DIAL function uses the values of the current
TIMEOUT and RETRIES parameters. For example, if
TIMEOUT is set to 45 seconds and RETRIES is set to
8, the DIAL function will attempt to make the
connection 8 times and will wait 45 seconds each
time before cancelling the operation. Note: Values
for TIMEOUT less than 30 seconds are defaulted to 30
seconds for the DIAL function.
ELSE
Function: Specify alternate conditional processing
when used in conjunction with a previous
IF command
Syntax:
> ELSE
If the conditional result of an IF command is true,
all commands following the IF command are processed
until an ELSE or the corresponding ENDIF command is
encountered. Commands following an ELSE command up
to the corresponding ENDIF command are ignored.
If the conditional result of an IF command is false,
all commands following the IF are ignored until an
ELSE command or ENDIF command is encountered.
Commands following the ELSE command are processed
until the ENDIF command corresponding to the IF
command is reached.
This command is ignored if there is no previous
corresponding IF command. The following example
demonstrates how the ELSE command is used:
> IF conditional expression
>
> commands processed if condition is true
>
> ELSE
>
> commands processed if condition is false
>
> ENDIF
For example:
> IF RESPONSE == 'Y'
> GOTO DO-IT
> ELSE
> NUMVAR = 1
> CHAIN ('NORESP.SCR')
> END
> ENDIF
- 25 -
END
Function: Terminate the operation of a script file
Syntax:
> END
The current script file and any log file are closed
when an END command is processed.
ENDIF
Function: Terminate the conditional processing of a
previous corresponding IF statement and
resume normal command processing
Syntax:
> ENDIF
This command is ignored if there is no previous
corresponding IF command.
EXIST (arg1)
Function: Test for the existence of a file and
return a TRUE or FALSE result
Syntax:
> EXIST (path_filename)
where:
PATH_FILENAME is the text string or defined variable
providing the location and name of the file for
which you are checking.
If no drive or directory path is entered, the test
is performed in the current directory.
This function usually is used in an IF statement,
such as
> IF EXIST ('v:\database\test.dbf')
> ; do one thing
> ELSE
> ; do something else
> ENDIF
The following example also is valid:
> FILENAME = 'c:\softerm\manual.txt'
> VALUE = EXIST (filename)
> IF VALUE == TRUE
> ...
> ENDIF
- 26 -
EXIT
Function: Terminate the current script file and the
current runtime session.
Syntax:
> EXIT
This is similar to the END directive, except that
EXIT also terminates the current runtime session.
FINDLINE (arg1,arg2)
Function: Search an open file for a particular text
string and return a TRUE or FALSE value
result
Syntax:
> RESULT = FINDLINE (filedef,search_string)
where:
FILEDEF must be the name of a variable that contains
the handle returned by a previous file open
function.
SEARCH_STRING is the text string or the variable
containing the text string to locate.
This function will treat the open file defined by
the file definition variable, FILDEF, as a line-type
file and will search, from the current position of
the pointer in the file, each line of text for the
match string.
If the value of RESULT is TRUE, the position of the
internal file pointer will have been set to the
first character of the line containing the specified
text.
> NAME = 'JONES, JOHN'
> RESULT = FINDLINE (FILDEF,NAME)
On completion of the command, a result code is
returned to the variable RESULT. A result code of
True means the search was successful; a False value
indicates that the command was not successful. If
the returned result is True, the current file
position will be set to the first character of the
text line containing the match string.
The statement:
> IF (FINDLINE(FILDEF,VName)) == FALSE
will search from the current position in the open
file for the value contained in the variable VName.
- 27 -
(VName must have been defined by a previous
statement, such as VName = 'Chevrolet', or the value
must have been read into it by a previous READ or
READLINE function).
If the value is not found (the returned value of the
operation is FALSE), you can process an error-
handling or branching routine. For instance, it
could mean that the value assigned to the variable
VName has been entered incorrectly; or the internal
file pointer is past the point in the file where the
value assigned to VName is.
FIRSTFILE (arg1,arg2)
Function: Return information about the first file
found in the given path/file name
template
Syntax:
> FIRSTFILE (template,filedef)
where:
TEMPLATE is the file name template text string.
FILEDEF must be the name of a variable to receive a
unique identifier value that will be used as an
argument in any subsequent NEXTFILE functions.
Examples:
> INFOSTRING = FIRSTFILE('C:\*.*',FILDEF)
or
> FILENAME = 'C:\*.*'
> INFOSTRING = FIRSTFILE(FILENAME,FILDEF)
The returned text variable (INFOSTRING) will be a
null length string if no matching file name is found
or will contain a fixed-format text string as
follows:
bytes:
1-12 file name
13 blank
14-21 file size
22 blank
23-30 file date in mm-dd-yy format
31 blank
32-36 file time in hh:mm format
37 blank
38 A attribute character, archived file
39 D attribute character, file name is a
directory
- 28 -
40 V attribute character, file name is a volume
name
41 S attribute character, system file
42 H attribute character, hidden file
43 R attribute character, read-only file
The internal resources allocated for the unique
identifier are released automatically under the
following circumstances:
1. When no file is available for this FIRSTFILE
function
2. When no more files are available to a subsequent
NEXTFILE function
3. By processing a CLOSE(filedef) function
4. By processing a CLOSEALL() function
FIXLENGTH (arg1,arg2)
Function: Sets the length of a text string by
padding with spaces or by truncating
Syntax:
> FIXLENGTH (source_string,length)
where:
SOURCE_STRING is the source text string.
LENGTH is the numeric value of the length.
Examples:
> SRCSTR = 'Enter File Name"
> OUTPUTSTRING = FIXLENGTH (SRCSTR,20) + ':'
or
> LEN = 20
> OUTPUTSTRING = FIXLENGTH (SRCSTR,LEN)
GETERRORTEXT (arg1)
Function: Converts any numeric value to its related
error text (if there is any)
Syntax:
> GETERRORTEXT (numeric)
where:
NUMERIC can be any numeric value, although the
function is designed primarily to use the result
codes which are returned by a script function.
- 29 -
Examples:
> RESULT = OPENNEW ('TEST.DOC',FILEDEF)
> IF RESULT != 0 ; If file creation failed
; We'll display the reason
> MESSAGE (GETERRORTEXT (RESULT))
> ENDIF
or
> NUMERIC = 63
> MESSAGE (GETERRORTEXT (NUMERIC))
Important
1. Not all numeric values have associated error
text.
2. Unlike the ERRORLEVEL and ERRORTEXT variables,
this function may be used during local error
checking, rather than only during ONERR
processing.
3. Although the command:
> OPENNEW ('TEST.DOC',FILEDEF)
is perfectly legal, you'll notice that there is no
variable to hold a returned result code. It is
not possible to verify the success or failure of
the call.
GETLENGTH (arg1)
Function: Returns the numeric value of the length of
a text string
Syntax:
> GETLENGTH (source_string)
where:
SOURCE_STRING is the source text string.
Example:
> SRCSTR = 'Softerm Modular -- The best choice
for Windows and OS/2'
> STRLENGTH = GETLENGTH (SRCSTR)
- 30 -
GOTO label
Function: Transfer command processing to the command
immediately following a specified Label
Syntax:
> GOTO Label
Label corresponds to the name specified in a Label.
A Label name must begin with an alpha character and
only the first 10 characters are significant.
GOTOs may occur in either a forward or backward
direction, and processing will continue with the
first command following a label whose name matches
the GOTO command label. If no label is found with a
matching name, operation is cancelled.
Note: A Label is written in the form:
> Label_Name:
The GOTO command will cancel all conditional
processing when used with IF, ELSE, and ENDIF
commands.
GOTO and Processing Speed
All GOTO operations cause the script file to return
to the beginning and conduct a forward search for
the Label. This, naturally, causes a slowdown of
the processing time.
You may speed up operation significantly by
rearranging the order of the script file so that all
initial setup operations are actually placed at the
end of the file, and placing a GOTO LabelName (such
as BEGIN) at the very beginning and a GOTO
OtherLabelName at the end of the initialization
sequence returning processing to the physical
beginning of the file, such as:
> GOTO Begin
> RealOperations:
.
Sequence of operations involving numerous GOTO
commands
.
> Begin:
.
Initialization routine
.
> GOTO RealOperations
- 31 -
HANGUP()
Function: End the current communications connection
Syntax:
> HANGUP()
The DTR (data terminal ready) control signal is low-
ered and Softerm waits 3 seconds for the connection
to be broken. Then Softerm continues processing of
a script file with the next command. Note: When
used with a Communications Server, the connection to
the service is broken.
Note: After a HANGUP command has been processed,
the DTR control signal remains low until a
communications command, such as DIAL or XMIT is
processed.
HOST (arg1,arg2,arg3,arg4,arg5)
Function: Initiate operation of a host mode
environment. Note: This function is
described in the chapter, Host Mode.
Syntax:
> HOST (idletime,maxtime,term_on,force,script)
where:
IDLETIME is a numeric value in minutes that defines
the maximum time which can elapse at the READY
prompt without input from the caller. A zero value
allows unlimited idle time.
MAXTIME is a numeric value in minutes that defines
the maximum connect time allowed per connection. A
zero value allows unlimited connect time per
connection.
TERM_ON defines the condition under which the Host
mode environment will be automatically terminated.
Available options are:
NONE (default)
IDLE
MAXTIME
NOCARRIER
FORCE defines whether the Host mode security feature
will be forced if the Host mode was initiated when a
communications connection already existed.
Available options are:
NO (default)
YES
- 32 -
SCRIPT is a text string that defines a script file
to be run whenever a new communications connection
is established.
The following are valid HOST() commands:
> HOST (30,,,)
> HOST (0,,,"C:\SOFTERM\SCR\HOST.SCR")
> HOST (0,NOCARRIER,YES,)
IF (expression)
Function: Provide conditional processing within a
script file by testing for a True or False
evaluation of an expression
Syntax:
> IF expression
Variables, constants, literals and functions may be
included in the expression to be evaluated.
Softerm provides a special variable called
ERRORLEVEL that allows you to test for any error
conditions which may occur during the operation of a
script file. This is a reserved variable name that
represents the completion state of the last command
to be processed. The possible values of the
ERRORLEVEL variable are:
Errorlevel Type of Error
0 None
1 Timeout
2 Line Failure (Retry count expired or
loss of carrier)
3 Operator Cancel
4 Remote Cancel
5 DOS Error
6 Expression evaluation error
The ERRORLEVEL variable is used in conjunction with
the ONERR directive to provide an error processing
routine when an error occurs during the processing
of any command. The ERRORLEVEL variable always
contains the value of the error code from the
previous command. If the ONERR directive is not
used, script file operation will be cancelled by
default when an error occurs.
You can use the IF command to test for an error
condition as follows:
> IF ERRORLEVEL != 2
> IF ERRORLEVEL == 6
- 33 -
Softerm also provides a special function which
allows you to test for the existence or not of a
filename on disk. The following examples show how
the EXIST() function can be used with the IF command
to test for filenames:
> IF EXIST("BRUCE.TXT")
or
> FILENAME = "C:\SOFTERM\TEMP\SOFTERM.SS2"
> IF EXIST(FILENAME)
or
> IF !EXIST(FILENAME)
IF commands can be nested. Each IF command must be
matched to a corresponding ENDIF command for proper
processing. If ELSE commands are used with nested
IF commands, they will be matched with the first
previous IF command which has not been terminated by
an ENDIF command.
The following is an example of nested IF's:
> IF condition (1)
> commands processed if condition (1) true
>
> IF condition (2)
> commands processed if condition (2) true
>
> ELSE
> commands processed if condition (2) false
>
> ENDIF terminates condition (2)
>
> ELSE
> commands processed if condition (1) false
>
> ENDIF terminates condition (1)
Operators and variables can be combined to create
expressions which can be evaluated and tested for
True or False in an IF command. Following are some
examples of the use of expressions in IF commands:
> IF STRINGVAR == 'SMITH'
>
> IF NUMVAR == ((3 * 5) + VALUE1)
>
> IF (GETLENGTH(STRING)) > 7
> IF (REPLY != 'Y'( && (REPLY != 'N')
> GOTO REPLYLOOP
> ENDIF
- 34 -
The script file parameters SV1-SV5 text replacement
variables are substituted before processing of the
IF command. Care should be taken in substituting a
variable name or a string. For example:
> STRING = 'C:\SOFTERM\SOFTERM.EXE'
> SV1 = STRING
> IF EXIST(SV1)
> PROMPT (SV1' EXISTS IN THAT DIRECTORY')
> ENDIF
will substitute the value of STRING before
processing the IF EXIST statement. Including quote
marks around the SV1 would result in a check on the
existence of the file named SV1. Similarly, you
could use this method:
> SV1 = 'C:\SOFTERM\SOFTERM.EXE'
> IF EXIST(SV1)
> PROMPT (SV1' EXISTS IN THAT DIRECTORY')
> ENDIF
INPUT (arg1,arg2,arg3)
Function: Displays a dialog and allows text input to
a script
Syntax:
> INPUT (title,prompt,input_var)
where:
TITLE is the text to be displayed in the Input
window's title bar.
PROMPT is the text to be displayed. The text string
may be up to 32 characters long.
INPUT_VAR is the variable to receive the input,
which can be a maximum of 64 characters. If
INPUT_VAR is initialized to a value before the INPUT
command is processed, the value will be shown when
the dialog is presented.
The INPUT dialog includes the following information:
o The Script File name
o The text to be displayed
o A text input area
o An OK button
o A Cancel button
- 35 -
Selecting OK accepts the displayed input text and
continues. Selecting Cancel or Close continues
script processing, but ignores any changes to the
input variable.
As with other functions, INPUT returns a code which
is separate from the input variable. INPUT returns
0 for OK and a non-zero value for Cancel or Close.
An INPUT command might be included in a script file
to prompt for a filename to be transmitted, or for a
password in a logon sequence.
The following are valid INPUT commands:
> REPLYLOOP:
> SET REPLY = ''
> INPT = INPUT ('Kermit Send','Enter file name to
send',REPLY)
> IF REPLY == ''
> GOTO REPLYLOOP
> ENDIF
> IF INPT != 0
> GOTO CANCEL
> ENDIF
> SET SV1 = REPLY
> SEND (KERMIT,SV1,SV1,,ON)
or
> SET CHOICE = 'Y'
> INPUT (,'Enter more data?',CHOICE)
> IF (CHOICE == '') || (CHOICE == 'Y')
> GOTO MOREDATA
> ENDIF
JUMP label
Function: Transfer command processing to the command
immediately following a specified Label
Syntax:
> JUMP Label
JUMP functions exactly as the GOTO directive.
LOG (arg1)
Function: Create a log file of all commands run by a
script file
Syntax:
> LOG (d:\path\filename.ext)
If the specified log file already exists, it is de-
leted and a new file is opened. Wildcard characters
are not allowed in the log file name entered. The
- 36 -
log file is created and written in standard text
file format.
An initial entry is written to the log file when the
command begins and a copy of the current command
line with including arguments and switches is
written to the log file. The final Characters,
Blocks, and Errors counts displayed during SEND(),
RECEIVE(), and HOST() commands also are written to
the log file.
Once initiated by the LOG command, logging remains
active until a NOLOG, END or CONVERSE command is
performed, or the current script file is cancelled.
Once the log file is opened, any subsequent commands
will be recorded. Each command recorded in the log
file will include the current date and time in
MM/DD/YY HH:MM:SS format. An I/O error while
writing to the log file will cause it to be closed.
The log file created may be printed or viewed.
Note: Multiple LOG files cannot be open at the same
time. If a LOG command is performed while a log
file already is open, the first log file will be
closed and the new log file opened. If the command
specifies the same file name as the previous log
file, the previous log file is replaced.
LOWER (arg1)
Function: Returns a lower case text string
Syntax:
> LOWER (source_string)
where:
SOURCE_STRING is the source text string (maximum
length 255 characters).
Example:
> LOWCASE = LOWER ('THIS IS A TEST")
or
> TXT = 'THIS IS A TEST'
> LOWCASE = LOWER (TXT)
The variable LOWCASE will contain the string 'this
is a test'.
- 37 -
MESSAGE (arg1)
Function: Displays a message in the progress frame
window
Syntax:
> MESSAGE (text)
where:
TEXT is the information text to be displayed. The
string can contain a maximum of 255 characters. The
text will remain until it scrolls off the progress
frame window.
Note: If the script progress frame window is
covered by another window, the text string will not
be visible.
MKDIR (arg1)
Function: Create a directory path
Syntax:
> MKDIR (path_name)
where:
PATH_NAME is the directory path text string.
NEXTFILE (arg1)
Function: Returns an information text string for the
next file matching the file name template
specified in a FIRSTFILE function
Syntax:
> NEXTFILE (filedef)
where:
FILEDEF is the name of a variable that contains the
unique identifier value that was returned by the
previous FIRSTFILE function.
The returned information text string will be a null
if there are no files matching the specified
template; else the string will take the format
defined for the FIRSTFILE function.
NOLOG ()
Function: Cancel the logging started by the LOG()
function
Syntax:
> NOLOG()
- 38 -
ON (arg1,arg2,......,arg11)
Function: Provides conditional branching to a label
within a script file based upon a numeric
value
Syntax:
> ON (numeric_val,label_1,label_2,...,label_10)
where:
NUMERIC_VAL is a numeric value in the range 1 to 10
typically obtained from a preceding XMIT_WAIT()
function. If the value is less than 1 or greater
than 10, or if no Label is defined for the value,
processing will continue immediately with the first
statement following the ON command.
LABEL_1 to LABEL_10 are the label names that
correspond to the numeric values 1 to 10.
Important: The value for 'arg1' often will be
provided by using a preceding XMIT_WAIT() function.
For example:
> ARG1_VAL = XMIT_WAIT (xmit_str,arg2,...,arg11)
> ON (ARG1_VAL,label_1,label_2,...,label_10)
ONERR label
Function: When a serious error -- one which would
cause Script file processing to terminate
-- occurs, transfer command processing to
the specified Label
Syntax:
> ONERR Label
Note: Related directives and a reserved variable
are: IF, ERRORLEVEL, RESUME and RETRY.
If an ONERR directive is used in a script file, when
a serious error condition occurs processing will
continue with the first command following a LABEL
whose name matches the ONERR command label. If no
LABEL is found with a matching name, command
processing is cancelled.
If the ONERR directive is not used in a script file,
processing of the file is cancelled when a serious
error condition occurs.
Caution: When using the ONERR directive, it is
possible to create looping conditions. For example,
running a script file using Softrans protocol to
- 39 -
RECEIVE a file which does not exist when the ONERR
processing is set to RETRY the RECEIVE operation
will cause looping.
Error conditions recognized by this directive
include: expression evaluation errors; line
timeout errors when using the character protocol;
line failure errors which occur when the RETRIES
count expires; operator cancel errors; remote
cancel errors when using the Softrans and Kermit
protocols; disk errors; and line disconnects due
to loss of carrier.
Note: An operator cancel or a line timeout which
terminates a character mode RECEIVE operation is not
considered to be a serious error.
OPENNEW (arg1,arg2)
Function: Creates and opens a new file
Syntax:
> OPENNEW(filename.new,filedef)
where:
FILENAME.NEW is the file name text string.
FILEDEF must be the name of a variable to receive
the file open handle that will be used as an
argument in subsequent functions that access the
same file.
Examples:
> RESULT = OPENNEW('PAYROLL.DOC',FILDEF)
or
> FILENAME = 'PAYROLL.DOC'
> RESULT = OPENNEW(FILENAME,FILDEF)
On completion of the command, a result code is
returned to the variable RESULT. A result code of 0
(zero) means the command was successful; a non-zero
value indicates that the command was not successful.
OPENOLD (arg1,arg2)
Function: Opens an existing file
Syntax:
> OPENOLD(filename.old,filedef)
where:
FILENAME.OLD is the file name text string.
- 40 -
FILEDEF must be the name of a variable to receive
the file open handle that will be used as an
argument in subsequent functions that access the
same file.
Examples:
> RESULT = OPENOLD('GRADES.CL3',FILDEF)
or
> FILENAME = 'GRADES.CL3'
> RESULT = OPENOLD(FILENAME,FILDEF)
On completion of the command, a result code is
returned to the variable RESULT. A result code of 0
(zero) means the command was successful; a non-zero
value indicates that the command was not successful.
Note: On an OPENOLD command, the internal file
pointer will be set at the start of the file.
PAUSE (arg1)
Function: Delay the start of the next script file
command
Syntax:
> PAUSE (seconds)
The desired pause time in seconds is entered as the
argument. A value from 1 to 255 seconds may be
specified for the pause. The delay indicated is
processed immediately and no further script commands
are processed until the pause interval is complete.
This function may be necessary when transferring
files with some host computer systems to allow
preparation time before the next command is
processed.
PROMPT (arg1,arg2)
Function: Displays an information message dialog box
until dismissed by the operator
Syntax:
> PROMPT (title,text)
where:
TITLE is the text which will be displayed in the
prompt's title bar.
TEXT is the information text to be displayed. The
string can contain a maximum of 255 characters.
- 41 -
Note: If the window in which the Script file is
running is not the current window, the text string
will not be visible and no action can be taken.
READ (arg1,arg2)
Function: Returns a text string from an open file
Syntax:
> READ (filedef,numeric_val)
where:
FILEDEF must be the name of a variable that contains
the handle returned by a previous file open
function.
NUMERIC_VAL is the numeric value of the length of
data to be read.
Examples:
> TXT = READ (FILEDEF,20)
or
> READCOUNT = 20
> TXT = READ (FILDEF,READCOUNT)
TXT is a variable to receive the data read, and
READCOUNT is a numeric variable or constant
indicating the amount of data to be read (255
characters maximum). The returned TXT string will be
a null length string if the current file position is
at the End-of-File. If less data is available than
READCOUNT, the read still will be performed without
error and the amount of data read may be determined
using the GETLENGTH function.
READLINE (arg1)
Function: Returns a line of text from an open file
Syntax:
> READLINE (filedef)
where:
FILEDEF must be the name of a variable that contains
the handle returned by a previous file open
function.
Example:
> TXT = READLINE (FILEDEF)
TXT is a variable to receive the data read. A line
of data is a maximum of 255 characters terminated by
- 42 -
CR, LF, CR+LF or LF+CR. The terminator sequence is
not returned with the read data. The returned TXT
will have a length of 1 and will contain a control-Z
(26 decimal) character if the internal file pointer
is at End-of-File.
You can copy, profile and run the following script
to demonstrate the READLINE() function:
> windowpos (0,0)
> windowtitle ('ReadLine Test - ' + sessionname)
> windowsize (24,80)
> windowprms (off,200,201)
> watch (off,on,3)
> windowshow ()
> delete ('\openold.000')
> copy ('\config.sys','\openold.000',replace)
> openold ('\openold.000',handle)
> read:
> text = readline (handle)
> if ((getlength (text) == 1) && (chrtoval (text) == 26))
> message ('Press any key to terminate script')
> timeout = 0
> watch (on)
> wait ()
> close (handle)
> delete ('\openold.000')
> end
> endif
> message (text)
> goto read
RECEIVE (arg1,arg2,arg3,arg4,arg5,arg6,arg7)
Function: Transfer a file from a host to your PC
Syntax:
> RECEIVE (protocol,host_filename,
local_filename,if_exist,xmit,
display_stats,display_filename)
where:
PROTOCOL is a text string defining either a file
transfer protocol profile or a file transfer
protocol name. If a profile has the same name as a
protocol, this argument will use the profile.
HOST_FILENAME is the file name as it appears on the
host system.
LOCAL_FILENAME is the name to be assigned to the
file on the local PC.
- 43 -
IF_EXIST is the option to use if a file with the
LOCAL_FILENAME already exists. The options are:
Replace Overwrite the existing file with the new
file.
Append Add the contents of the new file to the
end of the existing file. This generally
is not a appropriate option to use with
binary files.
Fail Cancel the Receive operation. This is the
default.
XMIT is the initial transmit text string.
DISPLAY_STATS specifies whether the file transfer
statistics should or should not be displayed. Note:
The statistics display is described in the Session
Window: File Menu chapter. The allowable values are:
ON Display statistics
OFF Do not display statistics
DISPLAY_FILENAME specifies whether the names of the
files being transferred should or should not be
displayed in the Script window. The allowable
values are:
ON Display names (the default)
OFF Do not display names
Examples:
> RECEIVE ('character','letter.txt',
'letter.txt',append,
'type letter.txt[CR]',on,off)
or
> SV1 = 'kermit'
> SV2 = 'project.dbf'
> SV3 = 'kermit -s '+SV2+'[CR]'
> RECEIVE (SV1,,SV2,replace,SV3,off,on)
RENAME (arg1,arg2)
Function: Renames a file
Syntax:
> RENAME (old_name,new_name)
where:
OLD_NAME is the current file name text string.
NEW_NAME is the new file name text string.
- 44 -
Example:
> RENAME ('SETHRPT.TXT','SETHRPT.BK1')
RESUME
Function: Used in ONERR directive processing to
resume processing with the next command
after the command on which an error
occurred
Syntax:
> RESUME
This directive requires no additional parameters.
If it is processing as a result of ONERR processing,
the next command after the command on which the
error occurred will be processing.
This directive is ignored when an error has not
occurred.
RETRY
Function: Used with ONERR directive processing to
retry the command on which an error
occurred
Syntax:
> RETRY
If this command is processed as a result of ONERR
processing after an error has occurred, the command
on which the error occurred will be re-processed.
Example:
> ONERR Error
> DIAL ()
.
> Error:
> IF ERRORLEVEL == 1
> RETRY
> ELSE
> GOTO EXIT
> ENDIF
Important: Incorrect use of the RETRY directive can
cause looping.
This directive is ignored when an error has not
occurred.
- 45 -
RSTATTR (arg1,arg2)
Function: Resets a file attribute
Syntax:
> RSTATTR (fname,attrib)
where:
FNAME is the file name text string.
ATTRIB is a text list which can contain any
combination of the A, H, and R attribute characters,
as described in the FINDFIRST function. The volume,
sub-directory, and system attributes may not be
reset.
Examples:
> RSTATTR('C:\SOFTERM\SOFT.PWD','AH')
or
> FILENAME = 'C:\SOFTERM\SOFT.PWD'
> RSTATTR(FILENAME,'H')
or
> RESULT = RSTATTR(FILENAME,'AHR')
On completion of the last example, a result code is
returned to the variable RESULT. A result code of 0
(zero) means the command was successful; a non-zero
value indicates that the command was not successful.
SEND (arg1,arg2,arg3,arg4,arg5,arg6)
Function: Transfer a file from your PC to a host
Syntax:
> SEND (protocol,local_filename,host_filename,
xmit,display_stats,display_filename)
where:
PROTOCOL is a text string defining either a file
transfer protocol profile or a file transfer
protocol name. If a profile has the same name as a
protocol, this argument will use the protocol.
LOCAL_FILENAME is the name as it appears on the
local PC.
HOST_FILENAME is the name to be assigned to the file
on the host system.
XMIT is the initial transmit text string.
- 46 -
DISPLAY_STATS specifies whether the file transfer
statistics should or should not be displayed. Note:
The statistics display is described in the Session
Window: File Menu chapter. The allowable values
are:
ON Display statistics
OFF Do not display statistics
DISPLAY_FILENAME specifies whether the names of the
files being transferred should or should not be
displayed in the Script window. The allowable
values are:
ON Display names (the default)
OFF Do not display names
Examples:
> SEND ('character','letter.txt','letter.txt',
'accept letter.txt[CR]',on,off)
or
> SV1 = 'kermit'
> SV2 = 'project.dbf'
> SV3 = 'kermit -r '+SV2+'[CR]'
> SEND (SV1,,SV2,SV3,off,on)
SETATTR (arg1,arg2)
Function: Sets a file attribute
Syntax:
> SETATTR (fname,attrib)
where:
FNAME is the file name text string.
ATTRIB is a text list which can contain any
combination of the A, H, and R attribute characters,
as described in the FINDFIRST function. Refer to
the RSTATTR function for additional information.
SETBOF (arg1)
Function: Sets the current file position to
beginning-of-file
Syntax:
> SETBOF (filedef)
where:
FILEDEF must be the name of a variable that contains
the handle returned by a previous file open
function.
- 47 -
SETEOF (arg1)
Function: Sets the current file position to end-
of-file
Syntax:
> SETEOF (filedef)
where:
FILEDEF must be the name of a variable that contains
the handle returned by a previous file open
function.
SKIP (arg1,arg2)
Function: Sets the file position relative to the
current file position
Syntax:
> SKIP (filedef,skipcount)
where:
FILEDEF must be the name of a variable that contains
the handle returned by a previous file open
function.
SKIPCOUNT is the numeric reposition value.
This function will adjust the current position of
the pointer in the file referenced by the file
definition variable FILDEF by the number of
characters defined by the argument SKIPCOUNT.
SKIPCOUNT is a numeric string indicating forward or
backward position adjustment in the range
-2,147,483,648 to +2,147,483,647 or a numeric
variable defining the reposition count. Omission of
the leading sign in the case of a numeric string
implies a forward reposition.
> SKIP (FILDEF,-10)
or
> SKIPCOUNT = -10
> RESULT = SKIP (FILDEF,SKIPCOUNT)
On completion of the command, a result code is
returned to the variable RESULT. A result code of 0
(zero) means the command was successful; a non-zero
value indicates that the command was not successful.
- 48 -
STRFIND1 (arg1,arg2,arg3)
Function: Returns the numeric position of the start
of a specified text string within a text
string. A value of zero is returned if
the specified string is not found.
Syntax:
> STRFIND1 (var_name,text,which)
where:
VAR_NAME is the name of the variable to be searched
and may be defined as the read-only predefined
system variable, RXDATA, which contains the last 255
characters received by the most recent XMIT_WAIT
function.
TEXT is the text string to find (maximum length 255
characters).
WHICH is the occurrence to be found. A value of
zero will locate the final occurrence.
Important: STRFIND1() is not case sensitive; lower
case will match upper case when performing the
search.
Examples:
> SRCH = 'FT'
> POS = STRFIND1(SRCH,'Softerm does the job!',1)
The numeric variable POS will contain 3, which is
the value of the position of the first occurence of
the specified text string in the text string defined
by the text variable SRCH.
> TXT = 'Four score and seven years ago,...'
> POS = STRFIND1 (RXDATA,TXT,0)
This is similar to the first example, except a text
variable is used to hold the search string and the
last 255 characters received by the most recent
XMIT_WAIT function are searched for the last
occurence of the search text.
- 49 -
STRFIND2 (arg1,arg2,arg3)
Function: Returns the numeric position of any
character from a specified text list
within a text string. A value of zero is
returned if no characters from the
specified list are found in the specified
string.
Syntax:
> STRFIND2 (var_name,list,which)
where:
VAR_NAME is the name of the variable which contains
the source string. This may be defined as the read-
only predefined system variable, RXDATA, which
contains the last 255 characters received by the
most recent XMIT_WAIT function.
LIST is the text string that is the list of
characters (maximum length 255 characters).
WHICH is the occurrence to be found. A value of
zero will locate the final occurrence.
Important: STRFIND2() is not case sensitive; lower
case will match upper case when performing the
search.
Examples:
> POS = STRFIND2 (RXDATA,VALTOCHR(30),0)
The numerical variable POS will contain the position
of the last occurence of the Record Separator
character in the RXDATA string. If POS is zero, no
Record Separator character was located in the
string.
> POS = STRFIND2 (TXT_VAR,'XYZ',1)
The numerical variable POS will contain the position
of the first occurence of 'x', 'X', 'y', 'Y', 'z' or
'Z' in the TXT_VAR string. If POS is zero, none of
the specified characters was located in the string.
> POS = STRFIND2 (TXT_VAR,'\',0)
The numerical variable POS will contain the position
of the last occurence of the path separator '\' in
the TXT_VAR string. If POS is zero, the character
was not located in the string.
- 50 -
STRGET1 (arg1,arg,arg3)
Function: Extracts a text string from a text string
by length
Syntax:
> STRGET1 (var_name,start_pos,length)
where:
VAR_NAME is the name of the variable which contains
the source string. This may be defined as the read-
only predefined system variable, RXDATA, which
contains the last 255 characters received by the
most recent XMIT_WAIT function.
START_POS is the numeric value of the extraction
start position. This value generally is obtained
from one of the STRFIND functions.
LENGTH is the numeric value of the length of the
string to be extracted (maximum length 255
characters).
Example:
> POS = STRFIND1(SRCH,'soft',1)
> TXT = STRGET1 (SRCH,POS,21)
Using the results of the STRFIND1() example, the
STRGET1() command would return the text variable TXT
with 'Softerm does the job!'
STRGET2 (arg1,arg,arg3)
Function: Extracts a text string from a text string
terminated by a specific terminator
character from a text string
Syntax:
> STRGET2 (var_name,start_pos,termchar_list)
where:
VAR_NAME is the name of the variable which contains
the source string. This may be defined as the read-
only predefined system variable, RXDATA, which
contains the last 255 characters received by the
most recent XMIT_WAIT function.
START_POS is the numeric value of the extraction
start position. This value generally is obtained
from one of the STRFIND functions.
TERMCHAR_LIST is the termination character list.
- 51 -
Example:
> POS = STRFIND1(SRCH,'soft',1)
> TXT = STRGET2 (SRCH,POS,'!')
Using the results of the STRFIND1() example, the
STRGET1() command would return the text variable TXT
with 'Softerm does the job!'
STRPUT (arg1,arg2,arg3)
Function: Puts a text substring within a text
string, replacing any existing characters
Syntax:
> STRPUT (source,text,start_pos)
where:
SOURCE is the source text string (maximum length 255
characters).
TEXT is the replacement text string (maximum length
255 characters).
START_POS is the numeric value of the start
position. This value generally is obtained from one
of the STRFIND functions.
STRTOVAL (arg1)
Function: Returns the numeric value representing an
ASCII numeric text string (for example,
'123' is returned as 123)
Syntax:
> STRTOVAL ('numeric_string')
where:
'NUMERIC_STRING' is the ASCII numeric text string.
Example:
> NUM_VAL = STRTOVAL ('754')
The numeric variable NUM_VAL will contain the
decimal number 754 (seven hundred fifty-four).
STRTOVAL() is used to convert ASCII text to a binary
value. It typically is used to convert operator
input to a numeric variable that can be used for
arithmetic operations. For example, the following
commands implement a simple command loop:
- 52 -
> ;operator input is placed in the
> ; text variable TEXTCOUNT
> COUNT = STRTOVAL(TEXTCOUNT)
> LOOP:
> IF !COUNT
> GOTO LOOPEND
> ELSE
> COUNT = COUNT - 1
> GOTO LOOP
> LOOPEND:
Before operator input can be used in an arithmetic
operation, it must be converted to a numeric varia-
ble. STRTOVAL() performs this function.
UPPER (arg1)
Function: Returns an upper case text string
Syntax:
> UPPER (source_string)
where:
SOURCE_STRING is the source text string (maximum
length 255 characters).
Example:
> UPCASE = UPPER ('this is a test")
or
> TXT = 'this is a test'
> UPCASE = UPPER (TXT)
The variable UPCASE will contain the string 'THIS IS
A TEST'.
VALTOCHR (arg1)
Function: Returns the ASCII character representing a
numeric value (for example, 49 is returned
as '1')
Syntax:
> VALTOCHR (numeric)
where:
NUMERIC is a numeric value in the range 0 through
255.
- 53 -
Example:
> ASC_CHAR = VALTOCHR (65)
The ASCII text variable ASC_CHAR will contain the
ASCII character 'A'.
VALTOSTR (arg1)
Function: Returns the ASCII numeric text string
representing a numeric value
Syntax:
> VALTOSTR (numeric_val)
where:
NUMERIC_VAL is the numeric value.
Example:
> ASC_VAL = VALTOSTR (754)
The text variable ASC_VAL will contain the ASCII
string '754'.
VALTOSTR() is the inverse of STRTOVAL(); it
converts a numeric value to a string value. For
example, to report the counting process, the above
command sequence could be modified as follows:
> ;operator input is placed in the
> ; text variable TEXTCOUNT
> COUNT = STRTOVAL(TEXTCOUNT)
> LOOP:
> IF !COUNT
> GOTO LOOPEND
> ENDIF
> SV1 = VALTOSTR(COUNT)
> MESSAGE ('Current count is 'SV1)
> COUNT = COUNT - 1
> GOTO LOOP
If you set a variable equal to a numeric value,
remember that Softerm stores numeric values in
binary format, not text. Therefore, you would need
to use the function VALTOSTR() (Value-To-String) to
use the variable as an ASCII character.
The reserved variable, ERRORCODE, contains the
numeric value of the last error code generated. For
instance, if you had an error trap routine that
displayed the error value, you would need to convert
the value contained in ERRORCODE to an ASCII value:
- 54 -
> ERROR:
> SV1 = VALTOSTR(ERRORCODE)
> PROMPT (SV1)
VCLEAR()
Function: Deletes all variables and their associated
resources except the ERRORCODE variable
and the Script Variables
Syntax:
> VCLEAR()
Note: To remove only a single variable and its
resources, use the VDELETE() function.
VDEFINED (arg1)
Function: Tests for the existance of a variable and
returns a TRUE or FALSE value result
Syntax:
> VDEFINED (variable_name)
where:
VARIABLE_NAME is the name of the variable.
This function is used in an IF command to check if a
variable has been defined. If the variable exists,
True is returned, else False is returned. The
result of this function may be inverted by using the
not operator (!).
Examples:
> VAL = 6
> IF VDEFINED(VAL)
would return a True, while:
> IF !VDEFINED(VAR_NAME)
would return False if VAR_NAME had been defined
previously.
VDELETE (arg1)
Function: Deletes the specified variable and any
associated resources
Syntax:
> VDELETE (variable_name)
- 55 -
where:
VARIABLE_NAME is the variable to be deleted.
WAIT ()
Function: Wait for an event and return an event code
numeric value
Syntax:
> WAIT()
The returned event code will be:
0 to indicate a timeout.
-1 to indicate a carrier transition, either
up to down or down to up.
Any other code will be the ASCII character of a
keystroke.
Examples:
To delay until any event takes place, simply use:
> WAIT()
To test for a particular event, use:
> EVENT = WAIT()
> IF EVENT == 0
> GOTO LABEL_A
> ENDIF
> GOTO LABEL_B
WRITE (arg1,arg2)
Function: Writes a text string to an open file
Syntax:
> WRITE (filedef,text)
where:
FILEDEF must be the name of a variable that contains
the handle returned by a previous file open
function.
TEXT is the text to write.
A newline sequence (CR/LF) is not appended to the
text written to the file. The position pointer in
the file will move to the next character after the
text is written.
- 56 -
Examples:
> WRITE (FILEDEF,'Testing...')
or
> TXT = 'Total Orders Shipped This Month = '
> RESULT = WRITE (FILDEF,TXT)
On completion of the command, a result code is
returned to the variable RESULT. A result code of 0
(zero) means the command was successful; a non-zero
value indicates that the command was not successful.
WRITELINE (arg1,arg2)
Function: Writes a line of text to an open file
Syntax:
> WRITELINE (filedef,text)
where:
FILEDEF must be the name of a variable that contains
the handle returned by a previous file open
function.
TEXT is the text to write.
A newline sequence (CR/LF) will be written to the
file after the text has been written to the file,
and the position pointer in the file will move to
the next character after the newline sequence.
Examples:
> WRITELINE (FILEDEF,'Testing...')
or
> TXT = 'Total Orders Shipped This Month:'
> RESULT = WRITELINE (FILDEF,TXT)
If an error occurs, processing will continue at the
label specified by the ONERR directive, or the
script will terminate.
XMIT_WAIT (arg1,arg2,......,arg12)
Function: Send a text string, wait for 1 of 10
optional specified replies, and return the
numeric value of the response received.
Syntax:
> XMIT_WAIT (text_string,echo_option,
reply_1,...,reply_10)
- 57 -
where:
TEXT_STRING is the string to transmit. The string
can contain a maximum of 255 characters.
ECHO_OPTION can be ON or OFF (the default). If set
to ON, the caller's input in response to the
transmitted string will be echoed back. Otherwise,
the input will not be visible to the caller.
REPLY_1 through REPLY_10 are 10 optional text string
responses. These strings can contain a maximum of
32 characters.
A value of zero is returned if a timeout occurs
without receiving any of the 10 strings.
Important: This function often will be used to
provide the 'arg1' value to an ON() function.
Example:
> ARG1_VAL = XMIT_WAIT (xmit_str,,arg2,...,arg12)
> ON (ARG1_VAL,label_1,label_2,...,label_10)
Window Control Functions
WATCH (arg1,arg2,arg3)
Function: Enable or disable the display of script
file commands and error messages in the
script window
Syntax:
> WATCH (on_off,errors,errortimeout)
where:
ON_OFF specifies the default setting for displaying
script commands as they are processed. If set to
ON, the commands will be displayed. If arg1 of the
WINDOWPRMS() function is set to ON, the script
window will contain a menu which can be used to
override this argument.
ERRORS defines whether or not error and information
messages will be displayed. If set to ON, error
messages will be displayed, even if the WINDOWSHOW()
function is not used.
- 58 -
ERRORTIMEOUT is a numeric value which sets the
amount of time, in seconds, that an error message
will be displayed before it is cleared. Valid
values are:
0 Do not clear the error message.
1 - 255 Valid number of seconds
Examples:
> WATCH (ON,ON,0) ; display commands as they
; are processed,
; display error messages,
; and leave them displayed
; until cancelled
> WATCH (OFF,ON,100) ; do not display commands,
; do display error messages
; and leave them until
; cancelled by the
; operator or until 100
; seconds have elapsed.
WINDOWPOS (arg1,arg2)
Function: Set the upper left corner of a script file
window
Syntax:
> WINDOWPOS (horizontal,vertical)
where:
HORIZONTAL is the horizontal displacement, in
pixels, from the left edge of the screen.
VERTICAL is the vertical displacement, in pixels,
from the top edge of the screen.
Note1: Screen positions are zero-relative to the
top left corner. That is, the top left corner has
the coordinates (0,0).
Note2: The screen position function is based on
pixels, rather than text column and row. The base
screen size depends on the video adapter and monitor
being used. A rough conversion is 8 pixels of
horizontal movement is approximately equal to one
character column, and 14 pixels of vertical movement
is approximately equal to one character row.
Note3: If this function is not used, the script
window will use the same start coordinates as its
parent runtime, terminal emulation window.
- 59 -
Example:
> WINDOWPOS (50,32) ; the start point is
; approximately at text
; column 10 (50/5) and
; row 2 (32/16)
WINDOWPRMS (arg1,arg2,arg3)
Function: Set menu and display options to be used by
a script window
Syntax:
> WINDOWPRMS (menu,scrname_pos,pathname_pos)
where:
MENU can be ON or OFF. If set to ON, the script
window will have a menu bar and one menu, similar
to:
If arg1 of the WATCH() function is set to OFF, the
Begin display option will be active and the End
display option will be greyed. Select Begin display
to show the script commands, as they are processed,
in the client area. Conversely, if arg1 of the
WATCH() function is set to ON, the End display
option will be active and the Begin display option
will be greyed.
SCRNAME_POS is the numeric priority which determines
if and where the name of the running script file
will be displayed. Valid numeric values are:
0 Do not display the name of the running
script file
1 - 127 Display the name above the client area
129 - 255 Display the name below the client area
PATHNAME_POS is the numeric priority which
determines if and where the name of the current
directory will be displayed. Valid numeric values
are:
0 Do not display the name of the current
directory
1 - 127 Display the name above the client area
129 - 255 Display the name below the client area
Note: If both names are to be displayed either
above or below the client area, the name having the
lower value will be displayed first.
- 60 -
Examples:
> WINDOWPRMS (OFF,0,0) ; neither menu nor names
; are displayed
> WINDOWPRMS (ON,1,129) ; the script menu is
; displayed, the script
; name is displayed
; above the client area,
; and the current
; directory is displayed
; below the client area.
WINDOWSHOW ()
Function: Cause the script window to be displayed
Syntax:
> WINDOWSHOW ()
If this function is not used, no script window will
be displayed. If arg2 of the WATCH() function is
set to ON, however, error and information messages
still will be displayed.
WINDOWSIZE (arg1,arg2)
Function: Set the size of the client area of a
script file window
Syntax:
> WINDOWPOS (rows,columns)
where:
ROWS is the number of screen rows which will be used
by the script window's client area.
COLUMNS is the number of screen columns which will
be used by the script window's client area.
Note1: If this function is not used, the script
window will be the size of its parent runtime,
terminal emulation window.
Note2: If this function is used after the script
window has been displayed using the WINDOWSHOW
function, it only may be used to make the window
smaller.
Example:
> WINDOWSIZE (1,15)
- 61 -
WINDOWTITLE (arg1)
Function: Provide a title for a script file window
Syntax:
> WINDOWTITLE ('title')
where:
TITLE is the text string to place in the script
window's title bar.
Note: If this function is not used, the title will
default to:
Softerm script - session_name
Examples:
> WINDOWTITLE ('Time') ; Time is the title
> WINDOWTITLE ('') ; title bar is blank
CLOCK.SCR
This example shows how the script window control
functions work together to display the current time.
Create CLOCK.SCR using any editor which can save
files in standard ASCII form, and make a Script
profile so you can run this example from a Session
Window. You might want to play with the different
argument settings to see how they affect the
operation and appearance.
> WINDOWPOS (0,0) ;start the window in
; the upper left corner
> WINDOWTITLE ('Time') ;the title
> WINDOWSIZE (1,14) ;the window client area
; is 1 row by 14 columns
> WINDOWPRMS (OFF,0,0) ;no menu and no file or
; directory name display
> WATCH (OFF,ON,10) ;don't show commands as
; they're processed,
; error messages will be
; displayed for 10 sec.
> WINDOWSHOW () ;enable the window
> TIMEOUT = 1 ;1-second delay for the
; WAIT() function
> LOOP:
> MESSAGE (' ' + time + ' ') ;see Note
> IF (WAIT() != 0) ;if a key is pressed
> END ;end operation
> ENDIF
> GOTO LOOP ;else, continue
- 62 -
Note: The Message consists of the catenation of 3
spaces, the system time (11 characters), and 3 more
spaces. This centers the time in the 14 columns
specified for the client area.
The Message function writes the text string to the
last line of the client area. Because the specified
area is only 1 line deep, it appears as though the
time is continually updated. Actually, the messages
are scrolled up off the display.
- 63 -