home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Shareware 1 2 the Maxx
/
sw_1.zip
/
sw_1
/
COMM
/
TE2120.ZIP
/
SCRIPT.DOC
< prev
next >
Wrap
Text File
|
1992-06-15
|
105KB
|
2,371 lines
TE/2 Script Language Reference
Oberon Software
518 Blue Earth Street
Mankato, MN 56001-2142
Last Revision: June 15, 1992
-------------------------------------------------------------
Copyright 1990-92, Oberon Software, Mankato, MN - All Rights Reserved
-------------------------------------------------------------
----------------------------------------------------
Notice: Information in this document is subject to change without
notice and does not constitute a commitment on the part of Oberon
Software.
----------------------------------------------------
General:
========
A TE/2 script file is a flat ASCII file containing TE/2 script
commands. Each line in the file must be terminated with either a
carriage return-line feed pair or with a single line feed. No line
may be longer than 256 characters in length, a line longer than 256
characters will generate an error message and terminate execution of
the script.
The TE/2 script language is not case sensitive, identifiers,
keywords, functions, et al may be entered in either upper or lower
case in any mixture. Identifier names (variables, subroutine names)
have no formal length restriction except as relates to the line
length restriction given above.
Blank lines within the script file are ignored as are any leading
or trailing space or tab characters on a line. You may indent and
space the file any way you please for readability purposes. The
semicolon is the comment mark character. Any and all text on a line
including and following a semicolon (;) is ignored. The obvious
exception to this is when the semicolon appears within a quoted
string.
REXX/2 Language Scripts
=======================
In addition to the script language syntax described in this document,
you may also create your scripts using the REXX Procedure Language.
You must be operating under a version of OS/2 which supports REXX to
use this feature. Because TE/2 sets itself up as the default addresssing
environment when it executes a REXX procedure, all of the functions
described later in this document are available also to the REXX
script as are most of the TE/2 built-in and system variables. You are
referred to the section of this document titled "Notes on REXX Scripts"
for further information.
Executing a script:
===================
A script file may be executed in one of four ways:
1) Type Alt-/ (Alt-Slash) in terminal mode, at the "Command:"
prompt type "call filename" where filename is the full file name
(including path and extension) of the script to execute.
2) Associate a script file name (once again, full path and
extension) with a dialing directory entry and make connection with
that number.
3) Assign the "call" command to a TE/2 function key. Set the
macro associated with the function to to "!call filename". Note
that ANY script command may be associated with a function key using
the exclamation point as the leading character.
4) Run a script automatically when TE/2 starts using the
"-mfilename" command line parameter. Note that there is one "magic"
script file name "TE2START.SCR" which TE/2 will always execute
automatically at startup if it finds it on the script path.
Program structure:
==================
The general structure of a TE/2 script file is thus:
variable declarations/definitions
subroutine definitions
program body
Constants:
==========
Numeric Constants
-----------------
Numeric constants are 32 bit, signed quantities. A numeric constant
may be expressed in standard decimal, hexadecimal, or octal notation
and may range from -2147483647 to 2147483647. Some examples of numeric
constants are:
32, -768, 0x1b, 0333, 0x12345678
There are several built in numeric constants. The most important of
these are TRUE (1) and FALSE (0). There are others that are designed
for special purposes, these will be covered in the appropriate
sections. Table 1 contains a list of these constants.
Table 1. -- Built in numeric constants
---------------------------------------
ansi_bbs
ansi_te2
ascii
false
ifcarrier
query
toggle
true
tty
vt100
xmodem
xmodem1k
ymodem
ymodemg
zmodem
Character Constants
-------------------
Character constants are really just a special method of specifying
an numeric constant. A character constant is any single character
between a pair of single quote marks (') or any two character Control
Character sequence (See Table 2. below) between a pair of single
quotes. The result is the ASCII value of the specified character and
it may be used anywhere a numeric constant or variable is allowed.
To specify the ASCII value of the single quote character (39), simply
use a sequence of three single quotes.
Note that the character constant 'A' is exactly equal to ASCIIVAL("A")
(See function ASCIIVAL below).
String Constants
----------------
String constants are any string of ASCII characters delimited
before and after with double quote marks ("). To embed a quote mark
in a string use a sequence of two double quotes. For example:
"This string has ""quotes"" embedded into it."
String constants should not exceed 256 characters in length. This
is not a hard and fast rule though exception handling for long
strings may be less than robust at this point.
The carat (^) character is treated specially, use it to embed
control characters into a string. Table 2 lists all of the valid
conversions. If a carat character appears in any other situation in
a quoted string it is ignored. Note that ^! yields character 94
which is itself the carat character, thus "^!" is the method of
embedding the carat character itself into a string. "^`" is a space
character, this is interesting but not very useful.
Table 2. -- Control character conversions
--------------------------------------------------------------
^@ 0 ^L or ^l 12 ^X or ^x 24
^A or ^a 1 ^M or ^m 13 ^Y or ^y 25
^B or ^b 2 ^N or ^n 14 ^Z or ^z 26
^C or ^c 3 ^O or ^o 15 ^[ 27
^D or ^d 4 ^P or ^p 16 ^\ 28
^E or ^e 5 ^Q or ^q 17 ^] 29
^F or ^f 6 ^R or ^r 18 ^^ 30
^G or ^g 7 ^S or ^s 19 ^_ 31
^H or ^h 8 ^T or ^t 20 ^` 32
^I or ^i 9 ^U or ^u 21 ^! 94
^J or ^j 10 ^V or ^v 22
^K or ^k 11 ^W or ^w 23
There is one built in string constant, "null" which specifies the
absence of a string. Note that "null" is not the same as the string
constant "". The later is a representation of the empty string
whereas "null" is no string at all; several functions in the TE/2
script language will make a distinction.
Variables:
==========
Variable types and scope:
-------------------------
User defined variables may be either string or integer variables.
An integer variable is capable of holding a signed, 32 bit quantity -
the same as the numeric constants mentioned above while a string
variable may refer to anything expressible with a string constant.
Variables may be local or global in scope. If a variable is local,
it is in effect for the current script file only; it is released when
the script file ends execution and it is not available in any nested
script file execution. If a variable is global, it is in effect from
the instant it is declared until TE/2 ends execution and exits back
to the OS/2 prompt and it is available to any script file that
executes thereafter and may even be used at the "Command:" prompt.
Declaring variables:
--------------------
Variables are declared in the first section of the script file,
anywhere before the "PROGRAM" statement except in a "SUBROUTINE"
.. "ENDSUB" block. A variable declaration has the following form:
[GLOBAL] type name [ = expression ]
If the "GLOBAL" scoping modifier is omitted, the variable is local
in scope. "type" is either "INTEGER" or "STRING". A variable name
must begin with an alphabetic character ("A" through "Z"), be
comprised entirely of alphanumeric characters ("A" through "Z" plus
"0" through "9"), and must not conflict with a TE/2 keyword or
predefined variable. If a GLOBAL variable name coincides with
another GLOBAL variable already defined in another script file, it
will refer to the same entity. If a LOCAL variable has the same name
as an already defined GLOBAL variable, it takes precedence over the
GLOBAL variable for the duration of the current script file after
which the GLOBAL variable will be reinstated.
The optional initializing expression follows all of the rules given
below for expressions. Remember that it can't refer to any variables
which are not yet declared.
Subroutines:
============
All subroutines must be defined before the "PROGRAM" statement in
the script file. The general form of a subroutine is:
SUBROUTINE name
statements
ENDSUB
A subroutine name must begin with an alphabetic character and be
composed entirely of alphanumeric characters. Unlike variables, the
name may conflict with a TE/2 script language keyword or a variable
name but not with any other subroutine name in that script file.
Rules for the statements in a subroutine are the same as the
general rules given below except that the "RETURN" statement is only
valid within a subroutine. The "RETURN" statement is not strictly
needed, the subroutine will exit back to the main line of code when
it reaches the "ENDSUB" statement but the "RETURN" statement may be
used to exit the subroutine early.
A subroutine has access to all of the local variables defined in
the script file even though they may have been declared later in the
file.
Program body:
=============
After all variable declarations and subroutine definitions, the
keyword "PROGRAM" is used to indicate the beginning of the main
program body of the script file. Execution of the script begins at
the very next statement after the "PROGRAM" directive. The program
is composed of one or more statements.
Statements:
===========
A statement may be one of the following:
an assignment statement
a TE/2 function call
a control statement
Assignment statements:
----------------------
An assignment statement has the following form:
variablename = expression
"variablename" must be the name of any LOCAL variable declared within
that script file, any GLOBAL variable declared within some script
file that has executed during this TE/2 session, or any TE/2
system-global variable that is not specifically read-only (see list of
keywords and system variables below).
Depending on the type (INTEGER or STRING) of the variable on the
left hand side, the expression may take either of the following
forms:
String expressions
------------------
Either a string variable, string literal, or string valued
function or the addition (concatenation) of two or more such
variables, literals or functions.
Examples:
stringvar = "fred flinstone"
HelloMsg = "Hello " + strleft("Worldwide", 5) + "^M^J"
Integer expressions
-------------------
Either an integer variable, numeric constant, or integer
valued function or the algebraic combination of two or more
such variables, constants, or functions.
Examples:
intvar = 12345
area = width * length
loword = longval & 0x0000ffff
The following operators are available for use in integer
expressions, given in the order of precedence. Parenthesis
may be freely used to ensure the correct order of evaluation
and/or for clarity and readability.
Table 3. -- Integer arithmetic operators
----------------------------------------
- Unary minus
~ Unary bitwise negation
! Unary logical negation
& Bitwise AND operator
| Bitwise OR operator
^ Bitwise EXCLUSIVE-OR operator
>> Bitwise shift-right
<< Bitwise shift-left
* Multiplication
/ Division
% Modulus
+ Addition
- Subtraction
AND Logical AND
OR Logical OR
> Relational Greater-Than
< Relational Less-Than
>= Relational Greater-Than-Or-Equal
<= Relational Less-Than-Or-Equal
!= Relational Not-Equal
== Relational Equality
TE/2 Function calls:
--------------------
The TE/2 script file language has a rich set of built in functions
which are listed alphabetically below in the Function Directory. In
general, each function has a return value, either INTEGER or STRING
and may appear in the right hand side of an expression as discussed
above but a function (indeed an entire expression, see below) may also
appear on a line of its own in the script file. In this case the
function is evaluated (usually for its actions or side effects) and
the return value is discarded. Clearly, this is not advantageous for
some functions such as GETENV or STRLEN whose entire purpose in life
is to return some information however it may be just the ticket for
action functions like CHAT, SCROLLBACK, or even WAITFOR if you aren't
interested in the return value.
It was mentioned that an entire expression could appear on a line
in the script file. The following is a perfectly valid statement:
waitfor("Select:", 60) + 5 + atoi("1234")
however the result (1239 or 1240 if WAITFOR was successful) will be
discarded. You might be tempted to write:
waitfor("Select:", 60) + transmit("m^M")
instead of:
waitfor("Select:", 60)
transmit("m^M")
however you should NOT depend on left-to-right evaluation of this
or any expression as it may not be the case in future versions of
TE/2 or in the compiled language when it become available.
Likewise, Boolean statements (those which use AND, OR, the logical
negation (!), and/or the relational operators are NOT short circuited
once their results are clear (as they are in "C", for instance);
expect all terms of a Boolean expression to be evaluated.
Control statements:
-------------------
The following is a brief summary of the program control structures
available in the TE/2 script language.
Subroutines:
------------
GOSUB subname { subname must be defined in file }
RETURN { valid within a subroutine only }
Notes: The subroutine has access to all variables
that are available at the main line level. The
program location after the GOSUB statement is saved
and restored when the RETURN statement is encountered
or when an ENDSUB statement is reached. Subroutines
may call other subroutines in the same file. The END
statement may be used within the subroutine with the
same results as using it in the main program body.
IF-ELSEIF-ELSE structure:
-------------------------
IF num-expression
statements
[ELSEIF num-expression { any number of ELSEIF clauses are }
statements { allowed }
ELSEIF num-expression
.
.]
[ELSE { ELSE statement is optional }
statements]
ENDIF
Loop structures:
----------------
DO { loop forever }
statements
LOOP
DO WHILE num-expression
statements
LOOP
DO UNTIL num-expression
statements
LOOP
DO
statements
LOOP WHILE num-expression
DO
statements
LOOP UNTIL num-expression
BREAK { exit current loop structure }
CONTINUE { branch to top of current loop structure }
Notes: In the DO WHILE..LOOP and DO UNTIL..LOOP
structures, the control expression is evaluated at
the beginning of the loop, execution may never enter
the loop if the expression does not evaluate
correctly for that style of loop. In the DO..LOOP
WHILE and DO..LOOP UNTIL forms, the expression is
evaluated at the end of the loop, the loop will
always be executed at least once.
The BREAK statement will exit the current loop
structure. If execution is within nested loops, only
the innermost loop will be exited. The BREAK
statement is the only way to exit the first form of
the DO..LOOP structure.
The CONTINUE statement transfers control back to the
top of the loop structure. If it is of the form
DO WHILE..LOOP or DO UNTIL..LOOP, the expression is
immediately reevaluated.
Other controls:
---------------
END { terminate current script file even
if currently in subroutine }
STOP { terminate current script file and
all calling script files }
RUN(str-expression) { execute script file - control
returns to current file when called
file ends }
PROCESS { recursively execute a TE/2 terminal
session, script file is suspended
until an EXIT() is performed. Note
that Alt-X generates an EXIT() by
default }
EXIT(num-expression) { terminate current PROCESS level or
terminate TE/2 if not in a PROCESS
shell }
Note that the END statement is not strictly necessary, the script
file will terminate when it reaches the end of the file.
Please note that loop structures, IF blocks and subroutines must be
properly nested. The TE/2 script language interpreter may detect a
faulty nesting and terminate with an error but the problem may not be
detected in some pathological cases until execution has already
progressed in an erroneous manner for a while. The following are
examples of incorrect block nesting.
Incorrect nesting:
------------------
counter = 0
do while counter < 50
if counter == 25
loop
endif
counter = counter + waitfor("Next", 10)
loop
Correct nesting:
----------------
counter = 0
do while counter < 50
if counter == 25
continue
endif
counter = counter + waitfor("Next", 10)
loop
Incorrect nesting:
------------------
if stricmp(strg1, strg2) == 0
message("^M^Jwaiting")
do
message(".")
else
message("!")
until waitfor(strg2, 1)
endif
Keywords:
=========
This is a list of reserved words within the TE/2 script language.
In addition to these words, no user variable may have the same name
as a system-global variable (see below).
Table 4. -- TE/2 script language reserved words
-----------------------------------------------
abs getenv setphone
and gets setscript
ansi_bbs getyesno settag
ansi_te2 hangup setxonxoff
ascii ifcarrier setvt100bksp
asciival itoa setxlattable
atoi jdate sendbreak
beep julian sendbyte
cancelwatch julian2 sendinit
chat jwday shell
chdir kbdabort sleep
chdisk keypressed snapshot
closedialog lastdownload sprintf
cls lastupload status
connected lfaftercr strcmp
curdir localecho strdate
cursorcol logclose streval
cursorrow logfile strget
date logopen stricmp
dial logpause strleft
directory mainmenu strlen
direntry message strput
dirname muxwait strright
dirphone null strstr
dirscript opendialog strtime
dirtag or strtrim
download parmsmnu substr
dumpinit password termecho
emulate pgmmenu time
erase porthandle timedout
errormsg query toggle
execpgm queuedial tolower
exit redial toupper
false rename trace
fnkey restorescr transmit
fclose rgetc true
feof rgets tty
ferror rshell upload
fgetc savedirfile vt100
fgets savescr waitfor
fopen scrollback watchfor
fputc setctsrts weekday
fputs setcursor xmodem
fseek setname xmodem1k
ftell setparms ymodem
getc setpassword ymodemg
zmodem
TE/2 System-Global Variables:
=============================
The following are the system-global variables (those which are
usually set in TE2.INI) which may be referred to in script language
statements. The type (INTEGER or STRING) of each is given by its
name. In general, these variables may also appear on the left-hand
side of an assignment statement, i.e.:
modemInitStrg = "ATE0 V1 X6^M^J"
Those which cannot be assigned directly are marked with an asterisk.
The marked variables must be set/reset through other means (usually a
function is provided, in some cases only through a TE/2 dialog box or
only from TE2.INI).
Table 5. -- TE/2 system-global variables
----------------------------------------------
* indicates read-only variable w.r.t assignment statements
TermAttr - INTEGER
MenuNormAttr - INTEGER
MenuHiAttr - INTEGER
LogoAttr - INTEGER
DLogNormAttr - INTEGER
DLogHiAttr - INTEGER
DLogDaAttr - INTEGER
DLogEdAttr - INTEGER
DLogEdHiAttr - INTEGER
ShadowAttr - INTEGER
DialNormAttr - INTEGER
DialHiAttr - INTEGER
ErrorAttr - INTEGER
ScrlBackAttr - INTEGER
ScrlBackFdAttr - INTEGER
ScrlBackMkAttr - INTEGER
ScrlBackTiAttr - INTEGER
ChatAttr - INTEGER
ChatRemoteAttr - INTEGER
ChatTitleAttr - INTEGER
CmdPromptAttr - INTEGER
CmdInputAttr - INTEGER
CmdInputHiAttr - INTEGER
SnapShotAttr - INTEGER
LocalEcho - INTEGER
DtrHangUp - INTEGER
LFafterCR - INTEGER
AutoZM - INTEGER
MatchBaud - INTEGER
AutoDirSave - INTEGER
ChatBuffered - INTEGER
Te2DEBUG - INTEGER
AlarmPopUp - INTEGER
MenuActive - INTEGER *
ColorLock - INTEGER
ClsReset - INTEGER
QueryZMRecover - INTEGER
DialerDC - INTEGER
AutoNL3101 - INTEGER
AutoLF3101 - INTEGER
Scroll3101 - INTEGER
EndChar3101 - INTEGER
NoOvIO - INTEGER
ExtendedFIFO - INTEGER
SwapBS4Del - INTEGER
VT100Backspace - INTEGER *
BreakLen - INTEGER
DialerTimeOut - INTEGER
AlarmType - INTEGER
AlarmTime - INTEGER
ForceLines - INTEGER
ScrlBackLns - INTEGER *
RedialDelay - INTEGER
LogoDelay - INTEGER
QueryHangUp - INTEGER
ClobberDL - INTEGER
DialerSendInit - INTEGER
ModemInitStrg - STRING
ModemDialStrg - STRING
ModemDialSufx - STRING
ModemHangStrg - STRING
ModemAnsStrg - STRING
ModemOKStrg - STRING
ModemDelayChar - INTEGER
EnqReply - STRING
VT100Prn - STRING
CallLog - STRING *
LogPath - STRING
UploadPath - STRING
DownloadPath - STRING
ScriptPath - STRING
ShellCmd - STRING
DIRFile - STRING *
FNKFile - STRING *
XEXFile - STRING *
Device - STRING *
Port - INTEGER *
Baud - INTEGER *
Parity - INTEGER *
WordLen - INTEGER *
StopBits - INTEGER *
XonXoff - INTEGER *
CtsRts - INTEGER *
ULPrtyClass - INTEGER
DLPrtyClass - INTEGER
Other System variables:
=======================
The following are other read-only variables, maintained by the
system which may not be set in any way. Their values may only be
examined.
Connected - INTEGER, TRUE if TE/2 is online
CurDir - STRING, the current subdirectory
CursorCol - INTEGER, current horizontal postion of the
cursor, leftmost column is 0
CursorRow - INTEGER, current vertical position of the
cursor, topmost row is 0
Date - INTEGER, the current date in packed format
Time - INTEGER, the current time in packed format
TimedOut - INTEGER, TRUE if last WAITFOR, MUXWAIT, RGETS
ended because of a timeout
KbdAbort - INTEGER, TRUE if last WAITFOR, MUXWAIT, RGETS
ended because of ESCape was typed
KeyPressed - INTEGER, TRUE if a local keystroke is pending
LastUpload - STRING, the name of the most recently uploaded
file or "" if no uploads have occurred
LastDownload - STRING, the name of the most recently downloaded
file or "" if no downloads have occurred
Porthandle - INTEGER, the OS/2 file handle for the open com port
StrDate - STRING, the current date in string format
StrTime - STRING, the current time in string format
Weekday - STRING, the current day of the week, one
of: "Sun", "Mon", "Tue", "Wed", "Thu",
"Fri", or "Sat".
Note: the formats of the date and time strings are determined by
querying OS/2 for the current codepage.
Note: the formats of the date and time numeric variables are:
year = (date & 0xffff0000) >> 16
month = (date & 0x0000ff00) >> 8
day = date & 0x000000ff
hour = (time & 0xff000000) >> 24
minute = (time & 0x00ff0000) >> 16
second = (time & 0x0000ff00) >> 8
hunds = time & 0x000000ff
Function directory:
===================
All functions are invoked by giving their names plus a pair of
parentheses containing the list of arguments. In some cases, a
function may not require an argument list, in these cases the empty
parentheses are still required.
In the function directory below, the format is: the function name
is listed and, in the parentheses, the type of each required argument
is given. If no arguments are required, the word "void" appears in
the parentheses. Some functions receive "special" parameters;
usually these will be taken from a select set of predefined constants
(as mentioned in the section on constants above). In these cases,
the word "special" will appear in that argument position and an
explanation will be given in the text. If a function takes a
variable number of arguments, this is indicated by ending the
argument list with three dots ("...").
ABS(integer)
Returns: INTEGER, the absolute value of its argument
ASCIIVAL(string)
Returns: INTEGER, the ASCII value of the first character of
its argument
ATOI(string)
Returns: INTEGER, the numeric value of the argument
Notes: this function understands hex and octal notation,
thus ATOI("27") and ATOI("0x1b") and ATOI("033")
all return the same value, 27.
BEEP(integer, integer)
Returns: INTEGER, always TRUE
Notes: this function will sound the console beeper, the
first parameter specifies the frequency (pitch) of
the sound, the second the duration.
CANCELWATCH(integer)
Returns: INTEGER, TRUE or FALSE
Notes: The argument must be a 'watch handle' created via a
previous call to WATCHFOR. This function releases
the watch. It returns FALSE if the watch did not
exist, TRUE otherwise.
See also WATCHFOR.
CHAT(void)
Returns: INTEGER, always TRUE
Notes: Activates chat mode, same as Alt-G from terminal mode
CHDIR(string)
Returns: INTEGER, TRUE or FALSE
Notes: the argument specifies a subdirectory, this function
will attempt to change the current working directory
on the current or specified disk, it will NOT change
the currently logged disk however. CHDIR returns
TRUE if it was successful. (See CHDISK)
Examples:
CHDIR("D:\")
CHDIR("\comm\log")
CHDISK(string)
Returns: INTEGER, TRUE or FALSE
Notes: the first character of the argument should specify a
disk letter. This function will attempt to make that
the current drive. It returns TRUE if it was
successful. (See CHDIR)
CLOSEDIALOG(integer)
Returns: INTEGER, always TRUE
Notes: The argument MUST be a handle to a dialog that has
been created by an earlier call to OPENDIALOG.
Restores the area of the screen which was saved during
the OPENDIALOG call and frees up all memory associated
with this dialog.
CLS(void)
Returns: INTEGER, always TRUE
Notes: Clears the terminal screen to the current attribute.
DIAL(string OR integer)
Returns: INTEGER, TRUE or FALSE
Notes: If the argument is an integer or if it is a string
with the format "#nnn" where the n's are digits, DIAL
will attempt to dial the indicated entry in the
current dialing directory. If it is a string and
not "#nnn" format, then if the first character is a
digit it will manually dial the string, else if the
string is not empty it will search for a TAG in the
current dialing directory that matches and dial that
entry. If the string is empty, the user is prompted
for a number (this is equivalent to typing Alt-M from
terminal mode). DIAL returns TRUE if a connection
was made.
DIRECTORY(void)
Returns: INTEGER, TRUE or FALSE
Notes: This is equivalent to typing Alt-D from terminal
mode. DIRECTORY returns TRUE if a connection was
made.
DIRNAME(string)
Returns: STRING
Notes: The parameter is either a "tag" to search for in
the currently loaded dialing directory or it may be
"" in which case it refers to the most recently dialed
entry. Returns the value of the "Name" field in the
specified entry or "" if it could not be located.
DIRPHONE(string)
Returns: STRING
Notes: The parameter is either a "tag" to search for in
the currently loaded dialing directory or it may be
"" in which case it refers to the most recently dialed
entry. Returns the value of the "Number" field in the
specified entry or "" if it could not be located.
DIRSCRIPT(string)
Returns: STRING
Notes: The parameter is either a "tag" to search for in
the currently loaded dialing directory or it may be
"" in which case it refers to the most recently dialed
entry. Returns the value of the "Script" field in the
specified entry or "" if it could not be located.
DIRTAG(string)
Returns: STRING
Notes: The parameter is either a "tag" to search for in
the currently loaded dialing directory or it may be
"" in which case it refers to the most recently dialed
entry. Returns the value of the "Tag" field in the
specified entry or "" if it could not be located.
DOWNLOAD(special, string)
Returns: INTEGER, TRUE or FALSE
Notes: The "special" parameter must be one of the following
pre-defined constants: XMODEM, XMODEM1K, YMODEM,
YMODEMG, ZMODEM, or QUERY. If this parameter is
QUERY, the user is prompted for the protocol. The
second parameter is the file name, if it is the empty
string, XMODEM and XMODEM1K will prompt the user for
the filename, this parameter is ignored by YMODEM,
YMODEMG, and ZMODEM.
The function returns TRUE if the file transfer ended
with no fatal errors. (See UPLOAD)
DUMPINIT(void)
Returns: INTEGER, always TRUE
Notes: Prints the current value of all the system-global
values settable via TE2.INI to the terminal screen.
EMULATE(special)
Returns: INTEGER, the new emulation.
Notes: The "special" parameter must be one of the following
pre-defined constants: TTY, ANSI_BBS, ANSI_TE2,
VT100, or QUERY. If it is QUERY, the user is
prompted for the emulation.
ERASE(string)
Returns: INTEGER, 0 on success, -1 on error
Notes: This function will delete the indicated file from
the disk. Clearly, you should use this function
with care.
ERRORMSG(string, string)
Returns: INTEGER, always TRUE
Notes: Displays the error message dialog (TE/2 uses this
dialog for most all, non-script related errors).
String1 is left justified on the first line of the
dialog, string2 centered on the second and "Strike
any key to continue" is placed at the bottom of the
dialog. ErrorAttr from the initialization file is
used for the dialog color. The portion of the screen
overlaid by the dialog is saved and restored when the
dialog is exited.
EXECPGM(string, string, string, integer, integer)
Returns: INTEGER
Notes: The arguments are, in order, session_title, program_name,
program_args, exec_type, and exec_flags. These parameters
map directly to the information contained in the external
program file that TE/2 uses to build the "User Programs"
menu (Alt-J), you should refer to the TE/2 Manual for
more information on these settings. All of the functionality
for user input and global value passing that is referred
to there is present here. The exec_flags parameter is NOT
optional for this call like it is in the external programs
file however.
The return value of EXECPGM() depends on the mode in which
the child process was executed. A return value of -1 will
usually indicate an invalid parameter list. If the child
was executed in the background or in a new session, the
return value is zero for success or the error code which
was returned by OS/2. If the child was executed as a
foreground process, the return value is the exit code of
the child program (i.e., the value which it passed to
DosExit()).
EXIT(special)
Returns: INTEGER, TRUE or FALSE
Notes: The "special" parameter must be one of the following
pre-defined constants: TRUE, FALSE, IFCARRIER. If it
is FALSE, the user will be asked for confirmation
before exiting, if TRUE TE/2 will unconditionally
exit, if QUERY the user will be queried only if the
carrier is high (TE/2 is online).
The function returns TRUE if TE/2 is exiting
(although you won't be able to test this, if the
function returns to the script at all it should do so
with FALSE).
FNKEY(integer)
Returns: INTEGER, TRUE or FALSE
Notes: If the argument is zero or greater than 48, the
function key menu is activated, this is equivalent
to typing Alt-K from terminal mode. If it is a
number from 1 to 48, the corresponding function key
macro is transmitted.
1 - 12 -> unshifed function keys 1-12
13 - 24 -> shifted function keys 1-12
25 - 36 -> control-function keys 1-12
37 - 48 -> alt-function keys 1-12
The function returns TRUE if a macro was transmitted.
FCLOSE(integer)
Returns: INTEGER, TRUE or FALSE
Notes: The argument should be the value returned from an
earlier call to FOPEN (see notes on file handling).
This function returns TRUE if the file was
successfully closed.
FEOF(integer)
Returns: INTEGER, TRUE or FALSE
Notes: The argument should be the value returned from an
earlier call to FOPEN (see notes on file handling).
This function returns TRUE if the current file
pointer position is at the end of file.
FERROR(integer)
Returns: INTEGER, error code
Notes: The argument should be the value returned from an
earlier call to FOPEN (see notes on file handling).
This function returns FALSE if no error has occurred
accessing the indicated file, else it is an error
code.
FGETC(integer)
Returns: INTEGER, character code or -1
Notes: The argument should be the value returned from an
earlier call to FOPEN (see notes on file handling).
This function returns the next character in a file
which has been opened for input. A -1 result is
used to indicate end-of-file or error (See FEOF and
FERROR).
FGETS(integer)
Returns: STRING, input from file
Notes: The argument should be the value returned from an
earlier call to FOPEN (see notes on file handling).
This function reads a line of text from a file opened
for input. It reads all characters up to and
including a newline character ("^J", see notes on
file handling for information about newline
translation) or 1024 characters, whichever occurs
first. It returns and empty string to indicate
end-of-file or error (See FEOF and FERROR).
FOPEN(string, string)
Returns: INTEGER, file handle
Notes: This function MAY NOT be called outside the context
of and assignment statement. It opens a file and
its return value is a "handle" for all the other
file oriented functions (FGETC, FEOF, FCLOSE, etc).
Care should be taken with this value so that it not
altered in any way until FCLOSE has safely been
called.
The first argument is a file name, the second is the
open "mode" and should be one of "r", "w", "a", "rt",
"rb", "wt", "wb", "at", "ab", "r+t", "w+t", "a+t",
"r+b", "w+b", or "a+b" (see notes on file handling
for an explanation).
If the function returns 0, the file was not opened.
FPUTC(integer, integer)
Returns: INTEGER, the output character or -1
Notes: The second argument should be the value returned from
an earlier call to FOPEN (see notes on file handling).
The first argument is the ascii value of the
character to be output to the file, the file must
have been opened in a mode which allows writing of
data ("w", "a", etc). A return value of -1 indicates
an error situation (see FEOF and FERROR).
FPUTS(string, integer)
Returns: INTEGER, the last output character or -1
Notes: The second argument should be the value returned from
an earlier call to FOPEN (see notes on file handling).
The first argument is the string to write to the file.
The file must have been opened in a mode which allows
writing of data ("w", "a", etc). A return value of
-1 indicates an error (see FEOF and FERROR).
FSEEK(integer, integer, special)
Returns: INTEGER, TRUE or FALSE
Notes: The first argument should be the value returned from
an earlier call to FOPEN (see notes on file handling).
The second integer specifies an offset into the file
which may be positive, negative, or zero depending
upon the mode specified in the third argument.
This function will attempt to move the current file
location pointer in the indicated file to a number
of bytes (specified in the second argument) from the
origin (specified in the third argument). The third
argument MUST be one of:
0 -- beginning of file
1 -- current position in file
2 -- end of file
If this function returns false, an error has occurred.
(see FEOF and FERROR)
FTELL(integer)
Returns: INTEGER,
Notes: The argument should be the value returned from an
earlier call to FOPEN (see notes on file handling).
This function retrieves the current location pointer
in the indicated file. A return value of -1
indicates an error (see FOEF and FERROR).
GETC(void)
Returns: INTEGER, keystroke value or zero
Notes: Waits for the user to type a key and returns the value
of the keystroke. If an error occurred, the return
is zero, if it was a 'standard' key, the return is
the ASCII value of the keystroke, if it was an
'extended' key (i.e., Alt key or function key) it
returns the scan code of the key times 256. The
keystroke is NOT echoed to the terminal screen.
(See GETS)
GETENV(string)
Returns: STRING
Notes: This function will scan the OS/2 environment table
for the current process (TE/2) and retrieve the value
associated with the string specified in its argument
or the empty string if the argument was not found in
the environment.
Examples:
CmdExe = GETENV("COMSPEC")
MESSAGE("%s", GETENV("PROMPT"))
GETYESNO(string, string, integer)
Returns: INTEGER, User selection result
Notes: Displays the Yes/No dialog (TE/2 uses this dialog
for querying the user for hangup and exit). Both
strings are centered in the dialog, string2 may be
NULL. The integer determines the default answer
(TRUE for Yes, FALSE for No). DLogNormAttr and
DLogHiAttr from the initialization file are used for
the dialog colors. The portion of the screen overlaid
by the dialog are saved and restored when the dialog
is exited.
Returns TRUE if "Yes" was selected, FALSE if "No" was
selected.
GETS(integer)
Returns: STRING
Notes: Gets a string from the console at the current cursor
location. The argument specifies the maximum length
of the string, it may be a number from 1 to 255. If
it is less than one, an empty string is immediately
returned, if it is greater than 255, it is treated as
if it were 255. GETS retrieves a string from the
user up to, but not including the first carriage
return character or the maximum length whichever
occurs first. Backspace will erase the previous
character typed (if any) and the ESCape key will
immediately terminate the input and GETS will return
an empty string. If terminal display is turned on
(see TERMECHO) the input is echoed to the terminal
screen in the current attribute and at the current
cursor location. (See GETC)
HANGUP(special)
Returns: INTEGER, TRUE or FALSE
Notes: The "special" argument must be one of TRUE, FALSE, or
IFCARRIER. If FALSE, the hangup sequence will be
unconditionally performed, if TRUE the user will be
queried for permission, if IFCARRIER, the user will
be queried only if the carrier is high (TE/2 is
online). The function returns TRUE if the hangup
sequence was successfully transmitted and TE/2 is
no longer on line.
NOTE: The parameter for the HANGUP() statement will
override the current setting of the TE/2 QueryHangUp
initialization variable.
ITOA(integer, special)
Returns: STRING, ASCII representation of the argument
Notes: The "special" argument must be in the range 2-36,
it specifies the radix for the conversion (number
system base. If the radix is 10 and the value of
the first argument is negative, a leading '-' sign
is the first character of the result.
Examples:
ITOA(1234, 10) returns "1234"
ITOA(8, 2) returns "1000"
JDATE(integer, integer)
Returns: INTEGER, A packed date (in the same format as the
'date' read-only variable) based on the given Julian
day number in the first parameter. Returns 0 on error.
Notes: The first parameter is the Julian Day Number to
translate, the second is a Boolean switch. If the
second parameter is TRUE, the returned date will be
relative to the Gregorian Calendar otherwise it will
be relative to the Julian Calendar. If the Julian
Day Number is invalid or the results would be out of
bounds for the requested calendar, the return value
will be 0. (See discussion on Julian date conversions
elsewhere in this document.)
JULIAN(integer, integer)
Returns: INTEGER, Julian Day Number or -1 on error.
Notes: The first parameter must be a packed date in the same
format as the 'date' read-only variable. The second
parameter indicates which calendar to use when
translating the date: TRUE means that this is a
Gregorian date, FALSE implies a Julian date. The
return value is the Julian Day Number for the given
date. If the date is invalid for the indicated
calendar, this function returns -1. (See discussion
on Julian date conversions elsewhere in this
document.)
JULIAN2(integer, integer, integer, integer)
Returns: INTEGER, Julian Day Number or -1 on error.
Notes: The parameters are, in order: month number (1 to 12),
day number (1 to 31), year number, and a Boolean to
indicate which calendar to use when translating this
date: TRUE means that this is a Gregorian date, FALSE
inplies a Julian Date. The return value is the Julian
Day Number for the given date. If the date is invalid
for the indicated calendar, this function returns -1.
(See discussion on Julian date conversions elsewhere in
this document.)
JWDAY(integer)
Returns: INTEGER, weekday index (0 to 6) or -1 on error.
Notes: The single parameter is a Julian Day Number, the
function will return the weekday index for that
Julian Day (0 is Sunday). If the Julian Day number
is invalid, the function returns -1.
LFAFTERCR(special)
Returns: INTEGER, TRUE or FALSE, the new value of LFafterCR
Notes: The "special" parameter must be one of TRUE, FALSE,
or TOGGLE. If TRUE or FALSE, the value of the
LF-After-CR flag is set to that value, if it is
TOGGLE the flag becomes TRUE if it was FALSE and
vice-versa.
LOCALECHO(special)
Returns: INTEGER, TRUE or FALSE, the new value of LocalEcho
Notes: The "special" parameter must be one of TRUE, FALSE,
or TOGGLE. If TRUE or FALSE, the value of the
Local-Echo flag is set to that value, if it is
TOGGLE the flag becomes TRUE if it was FALSE and
vice-versa.
LOGCLOSE(void)
Returns: INTEGER, TRUE or FALSE
Notes: Closes the currently open log file and returns TRUE,
if there is no currently open log file no action is
performed and the function returns FALSE.
LOGFILE(void)
Returns: INTEGER, TRUE or FALSE
Notes: This is equivalent to typing Alt-L in terminal mode.
If a log file is currently open this function will
close it and return TRUE, else the user will be
prompted for a log file name to open. In this case
it returns TRUE if a log file was opened or FALSE if
the user typed ESCape at the prompt of if there was
an error opening the file.
LOGOPEN(string, integer)
Returns: INTEGER, TRUE or FALSE
Notes: The first argument specifies the log file to open.
This must contain the entire path/name of the file,
default logpath handling is NOT performed on this
string. The second argument should be TRUE if the
the log file should overwrite any existing file of
the same name, if FALSE, new data will be appended
to the file.
If the first argument is NULL, the user will be
prompted for the file name and overwrite/append mode,
the second parameter is ignored.
The function returns TRUE is a log file was
successfully opened, FALSE if the file was not opened
due to error or user intervention.
LOGPAUSE(special)
Returns: INTEGER, TRUE or FALSE
Notes: The "special" argument must be one of TRUE, FALSE, or
TOGGLE. If TRUE, the log file will be placed in the
paused state, if FALSE it will be made active, if
TOGGLE it will alternate states. The function
returns TRUE if an action was performed, if there is
no currently open log file, it will return FALSE.
MAINMENU(special)
Returns: INTEGER, TRUE or FALSE
Notes: The "special" argument must be one of TRUE, FALSE, or
TOGGLE. If TRUE, the TE/2 main menu will be
displayed, if FALSE it will be hidden, if TOGGLE it
will alternate states. The function returns TRUE if
the menu state was changed. Note that the
system-global variable "MenuActive" may be examined
to determine the current state of the menu.
MESSAGE(string, ... )
Returns: INTEGER, the length of the message string
Notes: MESSAGE takes a parameter list identical to the
SPRINTF function, refer to SPRINTF for a more
complete discussion of the format string and its
arguments. This function will build a string
according to the rules for SPRINTF and display it
on the terminal screen at the current cursor
location.
MUXWAIT(string, integer)
Returns: INTEGER
Notes: Very much like the related WAITFOR function, MUXWAIT
allows you to specify, in the its first argument, as
many as 10 strings to wait for. The first character
of the string argument defines the delimiter that
will be in effect for parsing the seperate wait
strings. This may be any character you choose bit it
should be a character that does not otherwise appear
in any of the substrings (see the examples). MUXWAIT
does not return until one of the specified strings
has been encountered at the comm port, the duration
in seconds specified in the second argument has
elapsed, or the user types ESCape, whichever occurs
first. Returns the index of the string which was
found or FALSE if a timeout occured or the wait was
aborted by typing ESCape.
Incoming characters are echoed to the terminal screen
unless terminal display is turned off, the log file
is maintained. (See WAITFOR, WATCHFOR)
If the second parameter is less than zero, normal
timeout processing is disabled and MUXWAIT will not
return until a string has been matched or an ESCape
is typed at the keyboard.
Examples:
MUXWAIT("/ENTER to continue/Select:/", 60)
The above example will wait up to 60 seconds
for either the string "ENTER to continue" or
"Select:" to appear at the comm port. If,
for instance, "Select:" was encountered, the
function returns 2.
MUXWAIT("!Enter name/userid:!What system?!", 30)
Note the use of "!" as the delimiter in this
example rather than the "/" used in the
first. This example needs to use the slash
as a valid character in one of its searches
thus the different delimiter is mandated.
OPENDIALOG(integer, integer, integer, integer, integer)
Returns: INTEGER, handle to created dialog
Notes: Creates a dialog box on screen complete with frame
and shadow. The arguments are, in order, top row,
left column, bottom row, right column, and color
attribute. The contents of the portion of the screen
overlaid by the dialog box are saved and will be
restored with a subsequent call to CLOSEDIALOG.
The return value is a 'handle' to the dialog.
PARMSMNU(void)
Returns: INTEGER, always FALSE
Notes: This is equivalent to typing Alt-P from terminal
mode. The system-global variables "Device", "Port",
"Baud", "WordLen", and "StopBits" may be examined
to determine the current line settings at any time.
PASSWORD(string)
Returns: STRING
Notes: The parameter is either a "tag" to search for in
the currently loaded dialing directory or it may be
"" in which case it refers to the most recently dialed
entry. Returns the value of the "Password" field in the
specified entry or "" if it could not be located.
PGMMENU(void)
Returns: INTEGER, always TRUE
Notes: This is equivalent to typing Alt-J in terminal mode.
QUEUEDIAL(void)
Returns: INTEGER, TRUE or FALSE
Notes: This is equivalent to typing Alt-Q in terminal mode
or "Q" in the dialing directory in that it activates
the Queue Dialer. The function returns TRUE if a
connection resulted.
REDIAL(void)
Returns: INTEGER, TRUE or FALSE
Notes: This is equivalent to typing Alt-R in terminal mode in
that the Redialer is activated. The function returns
TRUE is a connection resulted.
RENAME(string, string)
Returns: INTEGER, TRUE or FALSE
Notes: This function will attempt to rename the file
specified in the first argument to the new name given
in the second argument. The function returns TRUE if
it was successful, otherwise an error has occurred.
Further note, this function may be used to move a
file from one subdirectory to another on the same
disk but not across disks.
Examples:
RENAME("logfile.log", "logfile.bak")
RENAME("somefile.dat", "\safe\place\somefile.dat")
RESTORESCR(integer)
Returns: INTEGER, always TRUE
Notes: The argument MUST be a handle to a saved screen that
has been created via an earlier call to SAVESCR or
disaster is sure to follow. This function will restore
a previously saved screen setup, restoring the video
mode (if neccessary), cursor position, size, and
attribute, and the entire contents of the screen and
frees up all memory used by SAVESCR.
RGETC(integer, special)
Returns: INTEGER, received character or 0
Notes: This function retrieves one byte of incoming data.
The integer parameter specifies the timeout value in
seconds. If the timeout period elapses or the user
types an ESCape at the console before a byte of
information is received, RGETC returns 0.
The second, special parameter determines how TE/2 will
echo the character back to the sender. It may be an
integer or a string. If it is an integer and is non-zero
then the character will be echoed back to the sender,
if it is zero, or if it is an empty or NULL string,
no character is echoed. Otherwise, the first character
of the string is echoed back to the sender (use this
for remote entry of passwords, for instance).
Note that by specifying a number less than zero as the
timeout parameter, timeout processing is disabled.
Incoming characters are echoed to the terminal screen
unless terminal display is turned off, the log file
is maintained.
Backspaces are processed and filtered by RGETS before
returning, if echoing is enabled, backspaces,
carriage returns, and line feeds are echoed as
themselves regardless of any translation specified
in parameter 2. (See RGETS)
RGETS(integer, integer, special)
Returns: STRING, the received data
Notes: This function retrieves incoming data into a string
variable up to the first carriage return or the
string length specified in the first argument or
until the number of seconds specified in the second
argument has elapsed, or until the user types an
ESCape character at the console, whichever occurs first.
The third, special parameter determines how TE/2 will
echo the characters back to the sender. It may be an
integer or a string. If it is an integer and is non-zero
then the characters will be echoed back to the sender,
if it is zero, or if it is an empty or NULL string,
no characters are echoed. Otherwise, the first character
of the string is echoed back to the sender for each
received character. (use this for remote entry of
passwords, for instance).
Note that by specifying a number less than zero as the
timeout parameter, timeout processing is disabled.
Incoming characters are echoed to the terminal screen
unless terminal display is turned off, the log file
is maintained.
Backspaces are processed and filtered by RGETS before
returning, if echoing is enabled, backspaces,
carriage returns, and line feeds are echoed as
themselves regardless of any translation specified
in parameter 3.
If the length parameter evaluates to 1, backspaces
are NOT filtered or translated.
(See RGETC)
RSHELL(string, string, integer)
Returns: INTEGER
Notes: Similar in many ways to the SHELL function but subtly
different in several important aspects. The first string
specifies a program to be executed, the second its arguments.
The program argument MUST be specified, there is no default
value. When the program is executed, the standard input,
standard output, and standard error system handles are all
redirected to the comm port. Thus, any program which takes
its input from stdin and writes to stdout and/or stderr,
will receive its input now from the comm port and send its
output back out the comm port.
If the third, integer parameter is non-zero TE/2 will
continue to monitor the status of the connection while the
child process is running. If a loss of carrier is detected,
the child program will be aborted and control will return
to your script file.
TE/2's screen wil be saved and cleared before executing the
RSHELL program and restored upon return.
The return value is -1 if there was an error otherwise it is
the return code of the program.
RSHELL processes incoming backspace characters
in the expected fashion.
The meaning of the third parameter has been
expanded. The parameter may take any of the
following values either singly or ORed together:
1 --> watch carrier
2 --> echo incoming characters
4 --> translate cr == cr-lf
8 --> buffer remote input & translate backspaces
Any other bits set in the parameter are ignored.
While in the RSHELL, the remote user has several
special key sequences available that will modify the
behavior. Each begins with a Control-Backslash
(^\, ascii code 28):
^\e --> toggles echoing of characters
^\x --> toggles cr-crlf translation
^\b --> toggles buffering
Anything else following a ^\ is simply passed
through unchanged (thus ^\^\ == ^\). Note that the
character codes ARE case sensitive, that is, ^\B is
not the same thing as ^\b. More special codes may
be added in the future.
SAVEDIRFILE(string)
Returns: INTEGER, 0 on success or an eror code
Notes: Saves the current dialing directory to disk using
the filename specified in the parameter. If the
parameter is "" then the file will be saved using
its current name.
SAVESCR(void)
Returns: INTEGER, handle to saved screen information
Notes: Saves the current contents of the entire screen and
returns a 'handle' to the saved information. This
information includes the current video mode, the
cursor position, the cursor size and attribute as
well as the actual contents of the screen. If SAVESCR
returns zero then there was not sufficient memory
to perform the operation.
SCROLLBACK(void)
Returns: INTEGER, TRUE or FALSE
Notes: This is equivalent to typing Alt-W from terminal
mode. The function returns TRUE unless the Scroll
Back feature is disabled in which case it returns
FALSE.
SETCTSRTS(integer)
Returns: INTEGER, TRUE or FALSE
Notes: Sets the Cts/Rts handling according to the argument:
0 - CTS/RTS both off
1 - CTS on, RTS off
2 - RTS on, CTS off
3 - CTS/RTS both on
The function returns TRUE if it was successful.
SETCURSOR(integer, integer)
Returns: INTEGER, TRUE on success, FALSE on error
Notes: Places the cursor at (row, column) on the terminal
screen. This is direct placement independent of the
current terminal emulation. The origin is (usually)
the upper lefthand corner and is (0,0). If the current
terminal emulation is VT100 AND the virtual terminal is
in relative cursor addressing mode AND a scroll region
is set, this function will obey the VT100 emulation's
rules for cursor placement relative to scrolling region.
If the requested location is invalid, this function
will return FALSE.
SETNAME(string, string)
Returns: INTEGET, TRUE or FALSE
Notes: The first paramter is a "tag" to search the currently
loaded dialing directory for; if it is "" then it is
taken to mean the most recently dialed entry. The
"Name" field in that entry will be set to the value
of the second parameter. Return TRUE on success or
FALSE on error.
SETPARMS(integer, integer, integer, integer, integer)
Returns: INTEGER, TRUE or FALSE
Notes: The arguments are Portnumber, baudrate, parity,
wordlength, and stopbits respectively. SETPARMS
returns TRUE if it was able to set the specified
parameter configuration. If it was unsuccessful
NONE of the parameters were changed. If the port
number changes, the original comm port will be
closed and any active connection severed. If any
of the parameters are to stay the same either the
appropriate system-global variable should be used
or, alternately a -1 in that position.
Examples:
SETPARMS(Port, 2400, 0, 8, 0) sets the current
comm port to 2400 baud, no parity, 8 bit word
length and 1 stop bit.
SETPARMS(-1, 2400, 0, 8, 0) is equivalent to the
previous example.
SETPARMS(-1, 9600, -1, -1, -1) sets the current
comm port to 9600 baud and leaves all other
settings alone.
SETPARMS(Port, 9600, Parity, WordLen, StopBits)
is equivalent to the previous example.
Further Notes:
The following is a list of the numbers to use for
setting parity, word length, and stop bits:
Parity:
0 - no parity
1 - odd parity
2 - even parity
3 - mark parity
4 - space parity
Word Length:
7 - 7 bit words
8 - 8 bit words
Stop Bits:
0 - 1 stop bit
1 - 1.5 stop bits
2 - 2 stop bits
SETPASSWORD(string, string)
Returns: INTEGET, TRUE or FALSE
Notes: The first paramter is a "tag" to search the currently
loaded dialing directory for; if it is "" then it is
taken to mean the most recently dialed entry. The
"Password" field in that entry will be set to the value
of the second parameter. Return TRUE on success or
FALSE on error.
SETPHONE(string, string)
Returns: INTEGET, TRUE or FALSE
Notes: The first paramter is a "tag" to search the currently
loaded dialing directory for; if it is "" then it is
taken to mean the most recently dialed entry. The
"Number" field in that entry will be set to the value
of the second parameter. Return TRUE on success or
FALSE on error.
SETSCRIPT(string, string)
Returns: INTEGET, TRUE or FALSE
Notes: The first paramter is a "tag" to search the currently
loaded dialing directory for; if it is "" then it is
taken to mean the most recently dialed entry. The
"Script" field in that entry will be set to the value
of the second parameter. Return TRUE on success or
FALSE on error.
SETTAG(string, string)
Returns: INTEGET, TRUE or FALSE
Notes: The first paramter is a "tag" to search the currently
loaded dialing directory for; if it is "" then it is
taken to mean the most recently dialed entry. The
"Tag" field in that entry will be set to the value
of the second parameter. Return TRUE on success or
FALSE on error.
SETXONXOFF(integer)
Returns: INTEGER, TRUE or FALSE
Notes: If the argument is zero, XonXoff processing will be
turned off, if the argument is "1" transmit XonXoff
processing will be enabled, if it is "2" receive
XonXoff processing will be enabled, if it is "3" both
transmit and receive XonXoff processing are enabled.
The system-global variable "XonXoff" may be examined
at any time to determine the current state of XonXoff
processing. The function returns TRUE if it was
successful.
SETVT100BKSP(integer)
Returns: INTEGER
Notes: Sets the VT100 emulation backspace translation mode.
If the parameter is TRUE then the VT100 eumlation
will treat incoming Backspace characters (ASCII 8)
as destructive backspaces, if FALSE the VT100 backspace
will be non-destructive. Returns the previous setting
for the VT100 Backspace handling.
SETXLATTABLE(string, integer)
Returns: INTEGER
Notes: Reads a new character translation table from the
file specified in the first parameter. If the second
parameter is zero, the new table will replace the
input character translation table, if it is non-zero,
it will replace the output character translation table.
Returns 0 on success or an error code on failure.
SENDBREAK(integer)
Returns: INTEGER, the value of its argument
Notes: Will transmit a break signal to the port for the
specified duration in milliseconds. If a zero value
is specified, the current value of the system-global
variable "BreakLen" is used for the duration.
SENDBYTE(integer OR string)
Returns: INTEGER, TRUE or FALSE
Notes: Sends the byte specified by either the integer
expression or the first character of the string
expression to the port. If the character is either
Ctrl-S or Ctrl-Q, the byte is transmitted
immediately. The function returns TRUE if it was
successful.
SENDINIT(void)
Returns: INTEGER, TRUE or FALSE
Notes: Transmits the string in the system-global variable
"modemInitStrg" to the comm port. Returns TRUE if
it was successful.
SHELL(string, string)
Returns: INTEGER
Notes: Executes the program specified in the first argument
sending it the parameters specified in the second.
If the first argument is NULL, the current value of
the system-global variable "ShellCmd" is used unless
it is also NULL in which case CMD.EXE is executed
with no parameters. If the first argument is NULL,
the second argument is ignored. The program is
executed synchronously in the foreground, TE/2 is
suspended while in the shell. TE/2's screen is saved
before and restored after execution. The return
value of the function is the return code of the
executed program or -1 if an error occurred.
SHELL(NULL, NULL) is equivalent to typing Alt-O from
terminal mode.
SLEEP(integer)
Returns: INTEGER, the value of its argument
Notes: Suspends execution of TE/2 for the duration in
milliseconds specified in its argument.
SNAPSHOT(string)
Returns: INTEGER
Notes: Performs the TE/2 SnapShot function saving its results
to the filename indicated in the parameter. If the
parameter is "" the the screen capture is saved to the
default file name. Snapshot always appends data to the
output file. Returns zero on success or an error code
on failure.
SPRINTF(string, ... )
Returns: STRING
Notes: SPRINTF receives a format string in its first
argument followed by up to 10 additional arguments
that may be either integers or strings. The arguments
are formatted into a string according to rules
specified by embedded commands in the format string.
With the exception of floating point handling and
pointer notation, all of the functionality of the "C"
functions "printf" and "sprintf" are supported by
TE/2's implementation of SPRINTF, the reader is
referred to the C Language library reference manual of
his or her choice for complete definition of all of
the rules regarding format strings. Here we will note
the following:
All characters from the format string are copied
to the output string with the following exceptions:
If "%s" is encountered in the format string, the
next unexamined parameter is interpreted as a
string an embedded at that point in the output
string. The notation "%10s" will right justify the
string in a field of 10 spaces at that point in the
output string. "10" is used by way of example, it
may be any decimal number. The notation "%-10s"
will likewise left justify the string in a field
of 10 spaces.
If "%d" is encountered in the format string, the
next unexamined parameter is interpreted as a
16 bit signed integer and the ascii representation
of it is embedded into the output string at that
point. "%ld" interprets the numeric parameter as
a 32-bit signed integer (the native form of all
integers in the TE/2 script language). "%10d" or
"%10ld" right justifies the number in a field of
10 spaces in the output string, "%010d" or "%010ld"
right justify the number in a field of ten zeros
in the output string.
If "%*s", "%-*s", "%*d", et cetera are encountered
in the format string, these will behave exactly the
same as the examples above with numeric values
except that TWO parameters are expected in the
argument list, the first an integer which will
specify the field width, the second the string or
integer to place in the output string.
If "%%" is encountered in the format string, a
single "%" is placed in the output string.
The arguments to SPRINTF may be literal strings,
string variables, string expressions, numeric
literals, constants, variables, or expressions
in any form or order. The only restriction is that
the first argument, the format string, must evaluate
to a string.
WARNING
It is not possible to type check all of the
parameters in an SPRINTF (or MESSAGE or TRANSMIT)
argument list. The script file writer is expected
to take precautions to avoid type mismatches so that
integers are not interpreted as strings and vice
versa. In general, if a string is interpreted as an
integer there should be no ill effects other than
erroneous output. If an integer is interpreted as
a string however, a protection violation may well
occur.
Examples:
SPRINTF("Hello %s", "World")
returns "Hello World"
SPRINTF("Hello %8s", "world")
returns "Hello world"
SPRINTF("Hello %-8s", "World")
returns "Hello World "
SPRINTF("This is the %dth example", 4)
returns "This is the 4th example"
SPRINTF("Action is %03d%% %s", 35, "complete")
returns "Action is 035% complete"
STATUS(void)
Returns: INTEGER, always FALSE
Notes: This is equivalent to typing Alt-I from terminal mode.
STREVAL(string)
Returns: STRING, the value of its argument
Notes: This function is included as a convenience for the
REXX language script writer, it simply returns the
value of its argument allowing a REXX script to query
any TE/2 internal or global variable.
STRCMP(string, string)
Returns: INTEGER
Notes: Lexigraphically compares two strings, returns zero if
the strings are identical, less than zero if the
first string is "less than" the second, greater than
zero otherwise.
STRGET(string, integer, integer, integer, integer, integer, integer)
Returns: STRING, user response
Notes: String input routine. The string parameter is the
default value, and the integer parameters are, in
order, row for the input, column for the input, width
of the input area, maximum input length (may be larger,
smaller or equal to the previous parameter), attribute
for 'first display' of the default, and attribute for
display while the user is editing/inputting. Returns
the edited string, returns the empty string if the user
pressed ESCape.
Note that input area is NOT saved and restored, it will
remain on screen after the input.
STRICMP(string, string)
Returns: INTEGER
Notes: Case-insensitive version of STRCMP. See STRCMP.
STRLEFT(string, integer)
Returns: STRING
Notes: Returns the leftmost N characters in the string where
N is the number specified in the second argument. If
N is greater than the length of the string, the
entire string is returned. (see STRRIGHT, SUBSTR)
STRLEN(string)
Returns: INTEGER, the length of the string
STRPUT(integer, integer, integer, string, ... )
Returns: INTEGER, length of displayed string
Notes: The integer parameters are, in order, screen row,
screen column, and attribute for display. The
string is a format string (see SPRINTF) which may
be followed by up to ten additional arguments.
The resulting string is placed at the indicated
position on screen using the indicated attribute.
Return value is the length of the displayed string.
STRRIGHT(string, integer)
Returns: STRING
Notes: Returns the rightmost N characters in the string where
N is the number specified in the second argument. If
N is greater than the length of the string, the
entire string is returned. (see STRLEFT, SUBSTR)
STRSTR(string, string)
Returns: INTEGER
Notes: Scans the string in the first argument for an
occurrence of the string in the second. Returns zero
if the string was not found else it returns the
position of the second string in the first.
STRTRIM(string)
Returns: STRING
Notes: Returns a string which is a copy of the string in
its argument with all leading space, tab, carriage
return, and newline characters removed from the
beginning and end. Embedded spaces, etc., are not
removed.
SUBSTR(string, integer, integer)
Returns: STRING
Notes: Returns a substring of the string in its argument.
If N is the value of the second argument and M the
value of the third, SUBSTR returns the string which
begins N characters into the first argument and
continues for M characters. If N is greater than the
length of the string, the empty string is returned,
if N+M is greater than the length of the string, only
the characters in the string from position N to the
end of the string are returned. (see STRLEFT and
STRRIGHT)
TERMECHO(special)
Returns: INTEGER, TRUE or FALSE
Notes: The special argument must be one of TRUE, FALSE, or
TOGGLE. TERMECHO will enable or disable the echoing
of characters to the terminal screen. This effects
both incoming characters from the comm port received
during a WAITFOR, MUXWAIT, RGETS, or RGETC and
characters typed at the keyboard during a GETS call.
It does NOT have any effect on characters received
during a main or higher level PROCESS.
Example:
message("Enter string to wait for:")
termecho(FALSE)
waitSrch = gets(255) ; no screen echo here
waitfor(waitSrch, 60) ; or here
process ; screen will update during this
; but will still be off when we
; get back
TOLOWER(string)
Returns: STRING
Notes: Returns a string which is a copy of its argument
with all upper case letters translated to lower case.
(see TOUPPER)
TOUPPER(string)
Returns: STRING
Notes: Returns a string which is a copy of its argument
with all lower case letters translated to upper case.
(see TOLOWER)
TRACE(integer)
Returns: INTEGER, the value of its argument
Notes: Enables and disables trace mode during script file
execution. When in trace mode each line of the
script file is printed on the terminal display (and
will appear in the scroll back buffer and log file
if one is open) as it is encountered. This is a
global toggle, once turned on it is on for all
subsequent script file processing until it is turned
off again or until TE/2 ends.
TRANSMIT(string, ... )
Returns: INTEGER, the length of the message string
Notes: TRANSMIT takes a parameter list identical to the
SPRINTF function, refer to SPRINTF for a more
complete discussion of the format string and its
arguments. This function will build a string
according to the rules for SPRINTF and transmit
it to the comm port.
UPLOAD(special, string)
Returns: INTEGER, TRUE or FALSE
Notes: The "special" parameter must be one of the following
pre-defined constants: ASCII, XMODEM, XMODEM1K,
YMODEM, YMODEMG, ZMODEM, or QUERY. If this parameter
is QUERY, the user is prompted for the protocol. The
second parameter is the file name, if it is the empty
string, the user is prompted for the file name.
The function returns TRUE if the file transfer ended
with no fatal errors. (See DOWNLOAD)
WAITFOR(string, integer)
Returns: INTEGER, TRUE or FALSE
Notes: Does not return until either the string specified in
the first parameter is encountered at the comm port,
the duration in seconds specified in the second
parameter has elapsed, or the user types ESCape,
whichever occurs first. Returns TRUE if the string
was encountered, FALSE if a timeout occurred or the
wait was aborted by typing ESCape.
Note that specifying a number less than zero as the
timeout parameter, timeout processing is disabled.
Incoming characters are echoed to the terminal screen
unless terminal display is turned off, the log file
is maintained. (See MUXWAIT, WATCHFOR)
WATCHFOR(string, string)
Returns: INTEGER, 'handle' for installed watch
Notes: Unlike WAITFOR, which does not return until the
indicated string has been encountered or a set period
of time has elapsed, WATCHFOR installs an asynchronous
'watch' and returns immediately. The return value is
zero if TE/2 could not install this watch, only 10
watches may be active at any time. If successful,
the return value is a 'handle' which you will
need to pass to CANCELWATCH when you want to end
the watch. This handle is therefore every bit as
precious as the handle returned from FOPEN and the
warnings given below in the notes about file handles
apply equally well to watch handles.
The first parameter is the string to 'watch' for.
The second parameter may be nearly any valid TE/2
Script Language assignment statement or function
call. The statement is not checked for proper syntax
or variable usage until the watch string has been
matched and TE/2 attempts to execute the statement so
you must take care that the syntax is correct and
that any variables referred to in the statement will
be accessible when the statement is to be executed.
Global and system-global variables are always safe
but local variables will cause problems if the watch
is left to continue after the current script has
finished execution or during the execution of any
nested script files or recursive PROCESSes.
Every incoming character from the com port is checked
against the currently active watches, if a watch
string is matched it is tagged for execution. If
TE/2 is in a process loop at the time, it will be
immediately executed. However, if a script file
is running at the time, it will not execute until
the current line has finished execution - this means
that a WAITFOR, MUXWAIT, RGETS, RGETC, etc., will not
be interrupted to execute a watch command.
Use the function CANCELWATCH to release a watch that
is no longer needed. (See CANCELWATCH)
Example:
integer whand1
integer whand2
integer gotMail = FALSE
program
whand1 = watchfor("ENTER to continue", "sendbyte(13)")
whand2 = watchfor("mail waiting", "gotMail = TRUE")
waitfor("Enter your choice:", 120)
cancelwatch(whand1)
cancelwatch(whand2)
if gotMail
; et cetera
Special Notes on the File Handling Functions:
=============================================
The integer value returned from FOPEN is a very important one. It
is a file "handle" that is used for all actions performed on that
file via the other file oriented functions. This value should NOT be
modified by your program until the file is safely closed (via a call
to FCLOSE) and is no longer needed. Though all the other file
oriented functions other than FOPEN will accept any integer valued
expression in the field used for the file handle, it is VERY
dangerous to use anything but the variable containing the value
returned from FOPEN. Any number of problems, up to and including
general protection violations, may occur is this procedure is not
followed.
The valid open modes for a file that may be used as the second
argument to FOPEN are given in Table 6 below. Certain of the file
oriented functions will operate only on a file which has been opened
in a mode which permits reading from the file. FGETS, FGETC, are
examples of these functions. Others, like FPUTS and FPUTC, will
operate only on a file which has been opened on a file which has been
opened in a mod which allows writing to the file. Others, like
FCLOSE and FTELL will work on any open file.
Table 6. -- Valid "mode" parameters for FOPEN
---------------------------------------------
"r" open for reading. If the file does not exist,
the FOPEN call will fail.
"w" open an empty file for writing. If the given
file exists it will be truncated.
"a" open for writing at the end of file (appending)
create the file if it does not exist.
"r+" open for both reading and writing. If the file
does not exist, the FOPEN call will fail.
"w+" open for both reading and writing. If the given
file exists it will be truncated.
"a+" open for both reading and appending. If the file
does not exist it will be created.
Translation mode specifiers:
---------------------------
One of the following characters may be optionally appended
to the mode string, they control the translation mode of
the file. The default mode is "t" (translated) mode so
that the use of "t" is unnecessary.
"b" open in binary (untranslated) mode. Absolutely
no translation is performed on data read from or
written to the file.
"t" open in text (translated) mode. Carriage return-
line feed combinations are translated to a single
line feed on input, line feed characters are
translated to carriage return-line feed pairs on
output. Control-Z characters are considered to
be the end of file regardless of their position
in the physical file. A file opened for writing
or read/writing will have a Control-Z found at the
end of the file removed if possible because the
presence of this character at the end of the file
may cause FSEEK to behave improperly.
Note that the return value of FTELL and the actions
of FSEEK may not be consistent with the actual
physical locations in a file opened in translated
mode. However, they will behave compatibly, that
is, FSEEKing to a location previously determined
by a call to FTELL will return the location pointer
to the same spot in the file.
Note: because "t" is the default action for FOPEN,
its use is discouraged.
Special Notes on Julian Date Conversion Functions:
==================================================
General notes on the calendars:
-------------------------------
Julian proleptic dates earlier than January 1, 4713 B.C. are
invalid, as are Julian dates in the year 0. Gregorian dates prior to
October 15, 1582 are also invalid, as are dates with month numbers
not in the range 1 to 12, or with day numbers less than 1 or greater
than the number of days in that month. Invalid dates will cause an
error return.
Julian Date Conversion Functions:
---------------------------------
JULIAN(integer packed_date, integer Gregorian)
JULIAN2(integer mon, integer day, integer year, integer Gregorian)
These two functions return the Julian Day Number corresponding to
the input calendar date or -1 if given an invalid input date. If
parameter 'Gregorian' is non-zero, this denotes input as a Gregorian
calendar date, otherwise it is a Julian calendar date. Note that, in
JULIAN, the date is given in the same packed format as the TE/2
Script Language read-only variable 'date', in JULIAN2 the date is
broken out into its componants. Month ranges from 1 to 12, day from
1 to 31 (or less depending on the month). For Julian B.C. dates,
express the year as a negative number (remembering, there is no
Julian Year 0). These function are, except as noted above,
identical.
JDATE(integer JulianDay, integer Gregorian)
Returns date, in packed format, if it can calculate it from the
Julian Day Number argument (JulianDay), or 0 if it cannot. If valid,
the calculated month, day, and year are stored in the return value in
the same packed format as the TE/2 Script Language read-only variable
'date'. If parameter 'Gregorian' is non-zero, a Gregorian calendar
date will be calculated, otherwise a Julian calendar date is
calculated.
JWDAY(integer JulianDay)
Returns a day-of-week code (0 => Sunday, 1 => Monday, etc.) if
given a valid Julian Day Number, or -1 if the Julian Day Number is
invalid.
Notes on REXX Scripts
=====================
You can call a REXX script from TE/2 anyplace you can call a TE/2
Script Language script! TE/2 determines whether or not it's a REXX
script by examining the first two bytes of the file for "/*" (as all
good REXX files should begin) so you can name the file with a .SCR
if you want. If it's not .SCR, you'll have to specify the full file
name. REXX scripts also go into a directory referred to in the
ScriptPath .INI variable (see note below).
A REXX script is executed directly (not via a shell to the command
processor) and the default addressing environment is set to 'TE2'.
As a subcommand handler, TE2 will accept any command that can be
typed at the Alt-/ Command Prompt (i.e, any TE/2 Script Language
assignment or function but not "if", "do .. loop" or any such control
construct).
TE2 also registers itself to handle screen and keyboard i/o. All
PULLs come from TE/2's keyboard handler and all, non debug, SAYs go
to TE/2 terminal screen. Debug mode SAYs go to stderr as always.
Calling a TE/2 Script language function from REXX:
--------------------------------------------------
Just put the call into quotes like you would if you were addressing
CMD.EXE, the return value will be in RC. E.g.,
'upload(ZMODEM, "myfile.zip")'
if rc = 1 ...
Note the use of single and double quotes. REXX will accept either but
the TE/2 Script Language requires double quotes to delimit it's strings
so you will have to watch for this.
If you wanted to make the above UPLOAD call but had the file name in
a REXX variable, call it as such:
'upload(ZMODEM, "' rexxvar '")'
If the TE/2 Script function returns a string instead of a numeric
value, this also will be in rc. E.g.,
'rgets(250, 60, TRUE)'
if rc = 'exit' ...
Errors when calling TE/2:
-------------------------
After returning from calling a TE/2 Script Language function, the
REXX special variable RC is always set to the return value of the
function unless a syntax error of some sort occured. TE/2 will print
an error message on the terminal screen in this event and raise a REXX
error condition (the value of RC is indetermanent in this case). You
may want to use the REXX "SIGNAL ON ERROR ..." feature while debugging
scripts.
Querying TE/2 Internal 'System' Variables:
------------------------------------------
Clearly, because you aren't executing a TE/2 script language script,
you won't have any TE/2 local, user variables to deal with at all but
you may want to query a TE/2 system variable or perhaps a global variable
from a previously executed TE/2 Script Language script.
If the variable is a string: use the StrEval() function.
'streval(downloadpath)'
rxdlpath = rc
If the variable is an integer: use the itoa() function.
'itoa(kbdabort, 10)'
if rc = 1 ...
Setting a TE/2 Variable from REXX:
----------------------------------
Some TE/2 System variables may be set by a script, all global user
variables may also be set.
Set a string from a literal:
'downloadpath = "D:\Junk"'
-- or --
'downloadpath = "' "D:\Junk" '"'
Set a string from a variable:
'downloadpath = "' rxvar '"'
Set an integer from a literal:
'localecho = 1'
-- or --
'localecho = ' 1
Set an integer from a variable:
'localecho = ' rxnumvar