Category : Communication (modem) tools and utilities
Archive   : CA29-2.ZIP
Filename : CASCRIPT.DOC

 
Output of file : CASCRIPT.DOC contained in archive : CA29-2.ZIP
COM-AND: IBM PC Communications Script Language










------------------------------------------
COM-AND: Communications Script Language
for the IBM PC
------------------------------------------




COM-AND version 2.9 is copyright 1992 by CABER Software. It is
distributed freely and may be copied by anyone for any number
of machines, for purposes of evaluation. The author offers
COM-AND and its accessory programs as a package, as "shareware".
If you USE COM-AND after evaluating it, you MUST pay for it.



The complete user license and registration information is to be
found in the file REGISTER.DOC. Limitations on redistribution
of COM-AND are set out in the file VENDOR.DOC. These two files
are included with the COM-AND program release.



CABER Software
R. (Scott) McGinnis
P.O. Box 3607 Mdse Mart
Chicago, IL 60654-0607

GEnie, Delphi: TARTAN
CIS .......... 73147,2665
Internet ..... [email protected]











Version 2.9: 921203

COM-AND: IBM PC Communications Script Language



COM-AND version 2.9 is copyright 1992 by CABER Software. All
rights are reserved world wide, excepting redistribution under the
shareware concept. COM-AND is distributed freely and may be copied
by anyone for any number of machines, for purposes of evaluation.


Restrictions on redistribution are set out in the document file
VENDOR.DOC. You may NOT distribute COM-AND or its documentation in
connection with ANY commercial venture, product, publication or
service without written approval from CABER Software.


COM-AND is distributed as shareware. You may try COM-AND without
charge, to evaluate its usefulness to you. You may evaluate COM-AND
for a period of up to 30 days. If you continue to use COM-AND after
30 days, then you must pay for it. Please read REGISTER.DOC for the
terms and conditions of the User License.


Additional benefits are available when you register COM-AND. These
values include:

. A free Compuserve intro-pack
. The Compuserve Automation script-set for COM-AND
. A tailored dialing directory for your area code
. Discounts on shareware magazines and books

These offers are discussed in detail in REGISTER.DOC. A simple
registration form is provided in the file REGISTER.FRM. Please
print this form (or use REGISTER.CMD to print it), and include the
form with your payment.


The author supports COM-AND through electronic mail on the various
on-line services. Several BBSes focused on COM-AND exist at this
time. Voice support for COM-AND is also available from Support
EtCetera in Long Beach, CA. Please read REGISTER.DOC for details
on support, and COM-AND BBSes.


CABER Software is a member of the Association of Shareware Profes-
sionals (ASP). The ASP offers an ombudsman service to help you
resolve shareware related disputes with ASP members. Please read
the file REGISTER.DOC for information on how to contact the ASP
Ombudsman.




Version 2.9: 921203

COM-AND: IBM PC Communications Script Language


Table of Contents
-----------------

I. COM-AND Introduction ...................................... page 1
II. Script Introduction ....................................... page 2
III. Definitions ............................................... page 4

A. Comments ................................................ page 4
B. Labels .................................................. page 4
C. Keywords ................................................ page 5
D. Commands ................................................ page 5
E. Strings ................................................. page 6
F. Numerics ................................................ page 7
G. States .................................................. page 8

IV. Syntax .................................................... page 9
V. Script Language Commands ................................... page 11

Commands beginning "A"...................................... page 11
Commands beginning "B"...................................... page 14
Commands beginning "C"...................................... page 15
Commands beginning "D"...................................... page 20
Commands beginning "E"...................................... page 26
Commands beginning "F"...................................... page 29
Commands beginning "G"...................................... page 39
Commands beginning "H"...................................... page 43
Commands beginning "I"...................................... page 44
Commands beginning "J"...................................... page --
Commands beginning "K"...................................... page 52
Commands beginning "L"...................................... page 52
Commands beginning "M"...................................... page 54
Commands beginning "N"...................................... page 59
Commands beginning "O"...................................... page 60
Commands beginning "P"...................................... page 62
Commands beginning "Q"...................................... page 63
Commands beginning "R"...................................... page 64
Commands beginning "S"...................................... page 67
Commands beginning "T"...................................... page 77
Commands beginning "U"...................................... page 79
Commands beginning "V"...................................... page 79
Commands beginning "W"...................................... page 80
Commands beginning "X"...................................... page --
Commands beginning "Y"...................................... page --
Commands beginning "Z"...................................... page --






Version 2.9: 921203

COM-AND: IBM PC Communications Script Language


Table of Contents
-----------------

VI. SET Commands .............................................. page 85

A. Basic set ............................................... page 85
B. SET ASCII ............................................... page 101
C. SET BPLUS ............................................... page 102
D. SET KERMIT .............................................. page 103
E. SET ZMODEM .............................................. page 104

VII. String Intrinsics ......................................... page 105
VIII. Script Errors .............................................. page 109
IX. ASPECT 1.x and PROCOMM 2.x scripts ......................... page 110
X. Program Requirements ....................................... page 112
XI. Program and Author Information ............................ page 113


Appendices
----------

A. Sample scripts ............................................ page 114
B. Host and BBS scripts ...................................... page 117
C. External Protocol Drivers ................................. page 118
D. Encoded Music ............................................. page 120
E. File transfer error numbers ............................... page 123
F. EBL ....................................................... page 125
G. Manual setting and scripts ................................. page 126

1. Alt-S (Setup window) .................................... page 126
2. Alt-O (Options window) .................................. page 127
3. Alt-P (Parameters window) ............................... page 128
4. Alt-K (KERMIT defaults window) .......................... page 129
5. Alt-J (Colors window) ................................... page 129
6. Help (General Help list) ................................ page 130

H. STACK and Macro keycodes .................................. page 131
I. Dynamic string variables ................................... page 132
J. Flow control methods ....................................... page 134
K. Machine language subroutines ............................... page 136
L. CACMP ...................................................... page 140
M. Script Language (version 1.x) .............................. page 141
N. Language Summary ........................................... page 144







Version 2.9: 921203

COM-AND: IBM PC Communications Script Language Page 1


I. COM-AND Introduction


COM-AND for the IBM PC and compatibles is a communications program
for use by itself, or for use with several integrated accessory
programs (which themselves may be used independent of COM-AND).
COM-AND provides standard comm program functions: a dialing
directory, macros, disk logging, binary and ASCII file transfers,
and most particularly: scripted execution.


COM-AND Version 2.9 executes as a CRT based comm program either in
25 line text mode on a CGA or monochrome screen, or 25/43(50) line
mode on an EGA(VGA) display. When an accessory is loaded through
COM-AND (or when COM-AND is loaded by an accessory), most of the
functions of COM-AND are available through the accessory.


COM-AND and its bundled scripts may be copied freely and distributed
to anyone for any number of machines. The author offers COM-AND as
"shareware". If the program is used after a period of 30 days, you
MUST pay for it.


COM-AND provides a script language for automation of certain tasks.
COM-AND is distributed with a KERMIT server, a HOST mode, a Bulletin
board, a file manager, and a LEARN MODE... all as scripts. Scripts
may be written for COM-AND by anyone, requiring only an editor to
produces ASCII files. COM-AND executes scripts written for the
very popular PROCOMM 2.x and Procomm Plus 1.x scripts, as well.


This document discusses scripted execution, and the COM-AND Script
Language. The script language has grown over the years to the point
where its documentation requires a separate file.


A detailed guide to installation, and an introduction to modem
communication is to be found in the document INTRO.DOC. For manual
use of COM-AND, and functional reference, the reader is referred to
the document COM-AND.DOC. The internal editor is documented in
CAEDIT.DOC, included with this release.








Version 2.9: 921203

COM-AND: IBM PC Communications Script Language Page 2


II. Script Introduction


The script processor supports automation of certain manual tasks,
and COM-AND to run unattended (if you have tested the script !!!).
Scripts are invoked in several ways:

o at load time:

.. COM-AND.CMD, if present in the current directory or the
subdirectory indicated by the 'COM-AND=' environment
variable, is executed immediately;

.. the /F switch in the run command may specify a script to
be executed immediately (after COM-AND.CMD, if present);

o interactively (through F2) as a script

o interactively (through F1) as an accessory or part of one

o a script may be attached to a dialing directory entry, to
be executed upon successful connection

o through a macro and similar methods


Script commands are read by COM-AND from an ASCII file (word pro-
cessor files are not usually ASCII files!). COM-AND's internal text
editor (Alt-Q), programmer's text editors, and EDLIN (included with
DOS) may be used to create and modify a script file. If you wish to
use a word processor to update a script, first ensure the particular
word processor can write an ASCII file (often called non-document,
perhaps even called ASCII).


Once a script begins, execution of COM-AND is automatic, driven by
the script. However, the ESC key may be used to terminate the
script at most any time (depending on the script. The script author
might make ESC unusable). During dialing, two ESCs are needed...
one to terminate the dial function, and the second to end script.


Generally speaking, a script usually takes the form:



... and so on


Version 2.9: 921203

COM-AND: IBM PC Communications Script Language Page 3


II. Script Introduction (continued)


For example, a script might dial a number listed in the dialing
directory and wait for the "ID = " response from the dialed host.
The next action would be to send the logon ID, with a carriage
return and await a prompt for a password.


The scripts included with COM-AND are examples of such simple
scripts. However: the COM-AND script language is not limited to
communications related tasks... programs may be loaded and passed
parameters, screen windows may be opened and scrolled, and so on.
A nontrivial BBS has been written using COM-AND's scripting, and is
provided with the distribution for the interested (and wary)!


It is taken for granted that the script programmer is acquainted with
the computer and telecommunications environment in general, and the
COM-AND program in particular. Much of the script language facility
revolves around making the features of COM-AND available to the
programmer. The remainder of the language makes the computer (e.g.
read and write files), and the communications line (e.g. read and
write lines of text) available to the programmer.


Details of the features of COM-AND are discussed in the COM-AND.DOC
document. Most of the discussion to follow assumes familiarity with
COM-AND.DOC.


The next few pages define terms used in discussing scripts and script
language elements. Notational symbols are then defined. Then,
script language elements are presented in detail. Appendix M
summarizes the version 1.x script language (no longer supported).
Appendix N summarizes the version 2 language. Sample scripts are
presented in Appendix A.













Version 2.9: 921203

COM-AND: IBM PC Communications Script Language Page 4


III. Definitions


A. Comments:

Comments may be used (and are highly recommended!) alone on a
line, on a command line (after the command) or on a label line
(after the label). A comment begins with a semi-colon or asterisk
and extends to the end of the line.

Blank lines are also treated as comments, for phrasing. Top-of-
form, appearing in the first column, is treated as a comment.


B. Labels:

Labels are character strings terminated with a colon, not
including the characters: blank, comma(,), exclamation (!),
number sign (#), dollar sign ($), percent sign (%), ampersand (&),
apostrophe ('), double quote ("), left and right parenthesis,
asterisk (*), plus (+), hyphen (-, minus), right slash (/), and
semi-colon(;).

Only the first 8 characters of the label are significant to the
script processor; if two labels match for the first 8 characters,
the one closest to the beginning of the script is used, and the
second label ignored.

Case is not significant in labels.

Comments are allowed on a line with a label (comments begin with
semi-colon or asterisk and extending to the end of the line).

Commands are not allowed on a line with a label.
















Version 2.9: 921203

COM-AND: IBM PC Communications Script Language Page 5


III. Definitions (continued)


C. Keywords:

Keywords are alphanumeric character strings terminated by a blank,
a comma, a left parenthesis, or a semi-colon. Only the first 4
characters of the keyword are significant to the script processor
(where keywords are the same for the first 4 letters, the last
letter is used to distinguish them).


Case is not significant in keywords.


D. Commands:

Commands are structured: followed by argument(s) (if
any). Delimiters between command arguments are blank and comma.
Each command is a line by itself (with the exception of the IF
and ELSE statements which may carry a second command). Comments
are allowed after the command (comments begin with semi-colon or
asterisk and extend to the end of the line).


COM-AND implements a stack for GOSUB, IF, SWITCH, FOR, DO and
WHILE commands. This allows nesting of these commands up to 20
levels. A 'stack overflow' message is issued when nesting of
more than 20 is attempted. A 'stack underflow' message is issued
when a RETURN is encountered for which no corresponding GOSUB
preceded.



















Version 2.9: 921203

COM-AND: IBM PC Communications Script Language Page 6


III. Definitions (continued)


E. Strings:

String arguments are of two kinds: literal and variable. Literal
strings are enclosed in double quotes ("). The accent grave (`)
is used in a literal string to force the next character (e.g. the
string "`"" is a literal consisting of a double quote by itself).


String variables are referred to as S0, S1, ... S29. Each string
variable is 80 characters wide, and may be set with the Sx =,
ASSIGN, GET, RGET, and other statements. They are set to blank
when the script begins (but are not reset to blanks when EXECUTE
or FCALL moves the script processor to a new script file).


Strings are manipulated internally exactly as given. However,
when issued (to the console or out the comm port, or in some cases
to disk), or used in WHEN string, certain edits are performed:

o Trailing blanks are trimmed
o "!" by itself (except "!!") is translated into a
carriage return
o "^x" (except ^^) where 'x' is character "@" through "`"
is translated into the corresponding control character
o Certain strings are treated as "intrinsic"s. Refer
to chapter VII of this document for further discussion.

Refer below to the "Sx = " discussion on page 77 for
details on string expressions.


Another set of string variables may be dynamically allocated by a
script (or scripts). These variables are referred to as V0, V1,
... Vx, where 'x' is determined by the allocating script.
Dynamic string variables may be used anywhere static variables are
used, AFTER A SCRIPT ALLOCATES THEM. Refer to appendix 'I' for a
discussion of these variables and their use.










Version 2.9: 921203

COM-AND: IBM PC Communications Script Language Page 7


III. Definitions (continued)


F. Numerics:

Numeric arguments are of two kinds: literal and variable. The
literal numerics are values alone, within double quotes, or as
a string within a string variable. Decimal values in the range
-32,768 to 32,767 may be expressed. Hexadecimal values may be
specified using the 'C' convention (e.g. 0xffff is -1).


Numeric variables are referred to as N0, N1, ... N99. Each
numeric variable is capable of storing the value -32,768 to
32,767. All are set to zero when the script begins (but not
reset to zeroes when an EXECUTE or FCALL statement moves the
script processor to a new script file).


Refer below to the "Nx = " discussion on page 59
for details on numeric expressions. Numeric expressions are
allowed in place of single numeric values (where a value is
required) in all commands except: ADD, SUB, MUL and DIV, IF
EQ/LT/... and IF ZERO. An expression may be used in these
commands only if it is entirely contained within parentheses.

























Version 2.9: 921203

COM-AND: IBM PC Communications Script Language Page 8


III. Definitions (continued)


G. States:

o String variables are set to blank at the start of a script.

o Numeric variables are set to zero at the start of a script.

o EXECUTE does not reset string or numeric variables or clear
any conditions (SUCCESS/FAILED/WAITFOR/etc). Neither does
EXECUTE clear WHEN settings.

o EXECUTE clears any IF and SWITCH function and GOSUB stack.
o EXECUTE clears any ON ESCAPE or ON SILENCE conditions.

o FCALL does not allow 'branch-back' from a called file to a
label in the calling file. FCALL does not reset the ON
ESCAPE implicit GOSUB (which potentially is a branch-back),
so be careful!.

o GOTO must not be used to enter an IF clause or SWITCH case,
even from within an IF clause or SWITCH.

o Received text is not processed until RGET, PAUSE or WAITFOR
instructions are performed.

o Keystrokes entered during a script are transmitted out the
comm port (unless HITKEY or SET TTHRU has been invoked).





















Version 2.9: 921203

COM-AND: IBM PC Communications Script Language Page 9


IV. Syntax


The chapter defines symbols used in command syntax descriptions.
Of necessity, some may seem cryptic at first... bear with me,
please.


-> Author's note. A command highlighted with '->'
IS compatible with ASPECT 1.x and PROCOMM 2.x scripting.

* Author's note. A command highlighted with '*'
is documented for ASPECT compatiblity, but not
implemented in this version of COM-AND.

[A] optional keyword A

(A!B!C...) Required choice: A or B or C ...

Sx String variable S0, S1, S2 ...S29
Vx String variable (dynamic) V0, V1, V2 ...V99
Nx Numeric variable N0, N1, N2 ...N99

->