PCjs Machines
Home of the original IBM PC emulator for browsers.
PC-SIG Diskette Library (Disk #3457)
[PCjs Machine "ibm5170"]
Waiting for machine "ibm5170" to load....
CDROM.TXT
T h e P C - S I G L i b r a r y o n C D - R O M
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
This may well be the greatest collection of software ever compiled.
The PC-SIG Library on CD-ROM is our premier collection of the entire
PC-SIG library. Every shareware program we have is on one disc; over
900 megabytes of software you can have immediate access to.
Easy to use, all you have to do is insert the disc and type 'INSTALL' at
the DOS prompt. We've included all the tools you need for fast easy
access to the programs and their descriptions.
The WordCruncher text retrieval software allows you to quickly access
the description for any program you want. All the programs are indexed
by title, filename, PC-SIG disk number, and every word within the
program description. There couldn't be an easier way to find just the
right program. All the programs are logically divided into thirteen
major categories with subcategories, making it easier to find just the
right software.
All of the programs have been scanned for viruses. There are also three
online virus utilities that can be run from the CD-ROM which will scan,
screen and clean viruses. Not only does this save hard disk space, but
also gives every user added security from viruses.
Whether you're interested in Accounting or Windows, there's a shareware
program for you on the PC-SIG Library on CD-ROM.
Winner of the Optical Publishing Assn's Best Consumer Product Award.
Shareware for every imaginable need: Accounting Chemistry Educational
Engineering Games Hypertext Networks Programming Spreadsheets Utilities
Word Processing
Additional BBS file descriptions are available from PC-SIG so that the
CD-ROM can be set up quickly on a bulletin board.
System Requirements:
IBM PC/XT/AT PS/2 or compatible with 530K memory DOS 3.1 or higher and
a graphics monitor (Hercules/EGA/VGA/SVGA). A mouse is optional.
T h e E s s e n t i a l H o m e & B u s i n e s s C o l l e c t i o n
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
"Never before has such a valuable collection of popular shareware been
compiled on one CD-ROM that everyone can afford." Dr. File Finder a.k.a.
Michael Callahan
Finally, 368 of the most useful, popular, important shareware programs
have been put together on one CD. No matter what your need, it's on The
Essential Home & Business Collection. Everything from Administration to
Windows software is here.
The Essential CD incorporates the WordCruncher text retrieval system.
Every program on the disc is indexed by title, filename, PC-SIG disk
number, and every word in the program description. A new utility, Narc,
is implemented so you can look at the program files and the author's
on-line documentation without having to first copy the program to your
hard disk. By using WordCruncher and Narc, you can quickly find the
program you want and review it to be sure, without ever having to run it
from your hard disk.
If you've got a CD-ROM player at home and want to get more use of it and
your computer, or if you're trying to avoid purchasing another Nintendo
cartridge, or if you just enjoy looking at new software, you need The
Essential Home & Business Collection.
System Requirements:
IBM PC/XT/AT PS/2 or compatible with 384K memory DOS 3.1 or higher and
Microsoft MS-DOS CD ROM extensions.
The PC-SIG Games CD-ROM
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Now you can play a game a day fo over a year. This CD-ROM is jammed
with over 380 shareware games of all types, designed to appeal to the
new generation of CD-ROM users out for fun. The CD incorporates a
hypermedia interface and allows 250 of the games to be played directly
from the CD-ROM.
The hottest games in shareware are on this disk, including the
action/arcade games "Jill of the Jungle" and "Wolfenstein 3D," which
rival or surpass commercial PC and Nintendo for use of animation,
SoundBlaster audio, and VGA graphics. There are also games designed to
teach children mathematics, spelling and even ecology. All these games
for less than a dime each!
Over 250 of the games can be played directly from the CD without copying
them to a floppy or a hard drive. Being able to run from the CD means
that users can explore games without using up valuable hard disk space
or spending time downloading and deleting files. The hypermedia
interface makes it easy to browse the titles, read a one line
description or full review, and copy or start a game by clicking the
mouse or using the keyboard.
To Order in the U.S.A.: Call 800-245-6717 and ask for Customer Service.
Outside the U.S.A. call (408) 730-9291 for the name of the dealer in
your country.
PCSIG.TXT
P C - S I G
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Welcome to the world of Shareware, state of the art software you can
actually try before you buy.
Shareware, a term coined in the early eighties, refers to the method of
distribution chosen by the software authors. With shareware, you can
receive a program and put it through its paces without having to pay for
it. If you find the program useful, and choose to keep the program, then
you pay a modest registration fee to the author.
For the last nine years, PC-SIG has been providing shareware and public
domain software to its customers and members. Since 1982 PC-SIG has
developed an unprecedented library of shareware programs, constantly
updated, consistently strong in every category. Our library of
shareware contains over 3500 titles divided into 120 logical categories.
Every program we add to the library is thoroughly reviewed and tested to
insure that each one meets the high standards of reliability and value we
insist upon and you expect. As a result, our library doesn't contain
every shareware program available, just those that really work.
PC-SIG has grown into the premier distributor of shareware and and
shareware information by producing shareware collections on CD-ROM,
publishing an encyclopedia of shareware, and by publishing Shareware
Magazine, a bi-monthly magazine distributed world-wide.
Quality and support - guaranteed. All of our programs are guaranteed
virus free. We've isolated our systems and check every program
submitted to insure that no viruses make their way to your computer or
ours.
Our support staff is available by phone as well as on our BBS to help
you with questions about installation and operation of PC-SIG's
products.
Through our network of international distributors, PC- SIG strives to
bring you the most current, exciting, technically advanced software
available as shareware.
If you can't find the software you need in PC-SIG's library, it may well
not exist.
To order the latest in Shareware, in the U.S.A: Call (800) 245-6717
Outside the U.S.A. call (408) 730-9291 for the name of the dealer in
your country.
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
README.TXT
Notes for TE/2 Version 1.10.B
August 15, 1990
Oberon Software
518 Blue Earth St.
Mankato, MN 56001
Voice: 507/388-2848
BBS: 507/388-1154
-------------------------------------------------------------
Copyright 1990, Oberon Software, Mankato, MN - All Rights Reserved
-------------------------------------------------------------
The files that should be in this package are:
TE2.EXE - TE/2 Version 1.110.b executable
COMMPAK2.DLL - CommPak2 Dynamic Link Library Version 0.96
TE2.INI - Sample initialization file
TE2.DIR - Sample directory file
TE2.XEX - Sample external programs files
TE2.FNK - Sample function key definitions file
TE2.XLT - Character translation table file
TE2_11.ICO - OS/2 1.1 compatible icon file
TE2_12.ICO - OS/2 1.2 compatible icon file
TE2.DOC - Detailed documentation file
SCRIPT.DOC - Discussion of TE/2's script language
WHATS.NEW - Overview of changes in this version of TE/2
READ.ME - This file
If any of the above files are missing, please notify the sysop of the
BBS where this package was found and/or contact Oberon Software at the
above address or phone number.
-------------------------------------------------------------
This is the SHAREWARE version of TE/2. Please be aware that it
does not contain several features which are present in the full,
registered version of the program. The most notable of these
features being Compuserve B+ Protocol and the TE/2 Script Language.
The script.doc file is included with this package so as to provide
you with an indication of the features and functions of the script
language and to assist you in deciding whether or not to register for
the full version of TE/2.
The following is the "Restrictions" section from TE2.DOC:
-------------------------------------------------------------
This version of TE/2 is supplied for personal, private use.
Feel free to distribute TE/2 given these restrictions:
o the program shall be supplied in its original, unmodified
form, which includes this documentation and all accompanying
support files;
o no fee is charged;
o use for profit without a license is prohibited;
o the program may not be included or bundled with other
goods or services. Exceptions may be granted upon written
request only.
If you are using TE/2 and find it of value, you are expected to
become a registered user. Registration fee is $45.00 (US). Please
make your check or postal money order payable to: Oberon Software.
For US and Canadian orders, please include $2.50 for shipping and
handling, overseas include $5.00. Minnesota residents should add
6% state sales tax. In exchange for registration you will receive
an enhanced version of TE/2 containing, among other things, TE/2's
Script Language interpreter. You will also receive printed
documentation for TE/2 and the TE/2 Script Language, one free version
upgrade when the next version becomes available, and automatic
notification of all subsequent releases.
For use by corporations and other institutions, please contact
the Oberon Software for a licensing arrangement.
-------------------------------------------------------------
For a quick start, if you have are running OS/2 version 1.1 or 1.2
(SE or EE) and you have a Hayes compatible modem attached to COM1, all
you need to do to start TE/2 is:
1. Make a directory on your hard disk and copy all the files
except COMMPAK2.DLL into that directory.
2. Copy COMMPAK2.DLL into a directory referred to in your LIBPATH
setting from CONFIG.SYS.
3. Change directory so that you are in the directory you created
above and type "TE2" at the OS/2 prompt (or click on TE2.EXE if
you've been doing all of this from the File Manager).
If your setup does not match the above requirements, or it does but
for some reason this does not start TE/2, or TE/2 starts after emitting
an error message, then you must read at least the first several sections
of TE2.DOC to get started.
Everyone should read the TE2.DOC file, however, to find out about all
the options you have available for customizing TE/2 to you individual
tastes and requirments.
-------------------------------------------------------------
Please read the "Disclaimer" section at the end of TE2.DOC also. Use
of TE/2 will imply that you agree with the terms of that liability
statement and to the restrictions given above.
-------------------------------------------------------------
Feel free to call the Oberon BBS number given above with any questions,
problems, compliments, or chit chat. The latest shareware version will
always be available there. The BBS uses a US Robotics Courier HST
14400 modem, No Parity, eight data bits, one stop bit and should be
available 24 hours daily.
SHAREMAG.TXT
S H A R E W A R E M A G A Z I N E
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Shareware Magazine has distinguished itself as the only internationally
distributed periodical devoted to the use and business of shareware.
Shareware Magazine provides detailed reviews of new products,
hard-hitting comparisons of shareware programs with regular retail
software, and timely information about changes in the industry and the
latest technology.
Intriguing columnists and regular features add to the excitement. The
beginners section sheds light on new user's concerns regarding
everything from choosing the right operating system to alleviating the
intimidation of using on-line systems.
Educational sections focus on how low cost shareware can aid in
classroom learning, curriculum development, and as a forum for
discussing the impact of computers and technology in schools.
Graphics Gallery renders expert advice and suggestions on how to better
work with graphics, desktop publishing, CAD systems, and the Windows
environment.
Programmers benefit from others experience in developing new programs or
polishing existing ones as well as choosing the right programming
language.
And columnists provide that subjective component, sometimes
controversial, that calls for a closer look at the way we compute and
how shareware effects what we do.
Published bimonthly, Shareware Magazine is available on a subscription
or at your local newsstand or computer bookstore. In conjunction with
PC-SIG, there are special benefits for subscribers as well as
opportunities for discount purchases from PC-SIG.
To Order, in the U.S.A.: Call 800-245-6717 and ask Customer Service.
Outside the U.S.A. call (408) 730-9291 for the name of the dealer in
your country.
SIGORDER.TXT
[B]
FROM: ___________________________
___________________________
___________________________
[A] [B]
___________________________
PC-SIG Inc.
[A] [B]
1030-D East Duane Avenue
Sunnyvale California
94086
Fold - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Fold
HOW TO USE THIS RETURN ENVELOPE
1. Place any other pages underneath this page.
2. Using the Fold lines (above) as a guide, fold this flap under.
3. Fold the address flap so it covers this flap.
4. Tape or staple the envelope at the two spots marked [A].
5. Slip in any other enclosures (business cards, cheques, etc.).
6. Tape or staple the envelope at the spots marked [B].
THANKS FOR TAKING THE TIME TO PRINT THIS FORM -*- MAIL YOUR ORDER TO:
PC-SIG Inc. 1030-D East Duane Avenue Sunnyvale CA 94086
---------------------------------------------------------------------
Do not mail cash. Please allow four weeks for processing.
---------------------------------------------------------------------
Check the items desired:
PC-SIG Disks - Member $2.49 for 5.25" or $2.99 for 3.5"
Non-member $3.50 for 5.25" or $4.00 for 3.5"
_____ _____ _____ _____ _____ _____ _____ _____ _____
_____ _____ _____ _____ _____ _____ _____ _____ _____
_____ _____ _____ _____ _____ _____ _____ _____ total ______
One year subscription to Shareware Magazine $14.95 ______
Super Saver Membership $34.95 ______
(includes a 1 year subscription to Shareware Magazine,
the PC-SIG Encyclopedia on Disk with WordCruncher,
and 5 free disks)
The PC-SIG Catalog on Disk $7.00 ______
The PC-SIG Encyclopedia on Disk with WordCruncher $20.00 ______
GAMES CD Amazing Disk - Amazing Price! $25.00 ______
*** PC-SIG Library on CD-ROM 12th Edition *** $99.00 ______
Upgrade to the 12th Edition from ANY previous edition
of the PC-SIG Library on CD-ROM! $59.00 ______
Upgrade from ANY other shareware CD-ROM just $59.00 ______
Subtotal ______
Shipping and Handling $4.00
California residents add 8.25% sales tax ______
TOTAL ______
If you have any comments or suggestions, please let us know!
To order by phone with VISA or MASTERCARD call (800)245-6717
Ask for operator #2351
SCRIPT.DOC
TE/2 Script Language Reference
Copyright 1990 by
Oberon Software
518 Blue Earth Street
Mankato, MN 56001
Last Revision: April 8, 1990
-------------------------------------------------------------
Copyright 1990, Oberon Software, Mankato, MN - All Rights Reserved
-------------------------------------------------------------
----------------------------------------------------
Note: For release with the shareware version of TE/2
----------------------------------------------------
The shareware version of TE/2 DOES NOT contain the TE/2 Script
Language Interpreter! The Script Languge described in this document
is only available in the REGISTERED VERSION of TE/2. This document
is included with the shareware release to give you a full indication
of the features available in the script language and to assist you in
your decision of whether to register TE/2 or not.
For information on registering TE/2, please refer to the user
documentation file TE2.DOC or contact Oberon Software at the address
given above.
----------------------------------------------------
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.
Executing a script:
===================
A script file may be executed in one of two 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.
Default script file path handling and default filename extension
handling IS NOT implemented in this release.
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 getc setxonxoff
and getenv shell
ansi_bbs gets sleep
ansi_te2 getyesno snapshot
ascii global sprintf
asciival gosub status
atoi itoa stop
beep if strcmp
break itoa strdate
cancelwatch integer strget
chat itoa stricmp
chdir lfaftercr string
chdisk localecho strleft
closedialog logclose strlen
cls logfile strput
connected logopen strright
continue logpause strstr
date loop strtime
dial mainmenu strtrim
directory message subroutine
download muxwait substr
do null termecho
download opendialog time
dumpinit or timedout
else parmsmnu toggle
elseif pgmmenu tolower
execpgm process toupper
end program trace
endif query transmit
endsub queuedial true
errormsg redial tty
execpgm rename until
exit restorescr upload
false return vt100
fclose rgetc waitfor
feof rgets watchfor
ferror rshell weekday
fgetc run while
fgets savescr xmodem
fnkey scrollback xmodem1k
fopen sendbreak ymodem
fputc sendbyte ymodemg
fputs sendinit zmodem
fseek setctsrts
ftell setparms
Table 4a. -- Additions to the reserved words list
-------------------------------------------------
kbdabort keypressed
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
chatAttr - INTEGER
cmdPromptAttr - INTEGER
cmdInputAttr - INTEGER
cmdInputHiAttr - INTEGER
LocalEcho - INTEGER
dtrHangUp - INTEGER
LFafterCR - INTEGER
AutoZM - INTEGER
MatchBaud - INTEGER
AutoDirSave - INTEGER
chatBuffered - INTEGER
te2DEBUG - INTEGER
alarmPopUp - INTEGER
MenuActive - INTEGER *
colorLock - INTEGER
BreakLen - INTEGER
dialerTimeOut - INTEGER
alarmType - INTEGER
alarmTime - INTEGER
ForceLines - INTEGER
ScrlBackLns - INTEGER *
redialDelay - INTEGER
LogoDelay - INTEGER
QueryHangUp - INTEGER
ClobberDL - INTEGER
modemInitStrg - STRING
modemDialStrg - STRING
modemDialSufx - STRING
modemHangStrg - STRING
modemAnsStrg - STRING
modemOKStrg - STRING
modemDelayChar - INTEGER
enqReply - STRING
clogFile - STRING *
logPath - STRING
dfltDLPath - STRING
dfltULPath - STRING
scriptPath - STRING
shellCmd - 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
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
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.
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.
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 TRUE, the hangup sequence will be
unconditionally performed, if FALSE 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"
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.
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. (See RGETS)
| Enhancement 6-28-90:
| 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.
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. (See RGETC)
| Enhancement 6-28-90:
| 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.
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.
| Enhancement 6-28-90:
| RSHELL now 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.
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.
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
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.
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.
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.
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 milliseconds 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.
Directory of PC-SIG Library Disk #3457
Volume in drive A has no label
Directory of A:\
TE2_110B ZIP 228148 8-19-90 6:02p
GO-STRT DAT 540 1-06-93 4:57p
README TXT 5446 8-15-90 8:40p
SIGORDER TXT 3090 3-10-93 3:22p
GO-FORM DAT 3090 3-10-93 3:22p
GO EXE 26022 1-10-92 12:14p
PKUNZIP EXE 23528 3-15-90 1:10a
PCSIG TXT 2335 2-10-93 8:50a
SHAREMAG TXT 1837 1-21-92 6:11a
CDROM TXT 4874 3-18-93 1:28p
10 file(s) 298910 bytes
18432 bytes free