Chapter 8
Macros and Function Keys


                        MACROS AND FUNCTION KEYS

Macros are commands which you can program in sequences to perform most of the
functions of this program.  You may program a macro sequence to perform anything
from a simple task like dialing a number to a complex task like conducting a
total log-on/access/log-off operation automatically.

Macro commands are in the form of simple text characters which you can enter
with the MODEM MGR editor and store as an ordinary text file.  In order to
create these macro script files, you should learn how to use the editor
furnished with this program or any editor which produces standard Apple text
files.  You may save the macro script file to disk under any file name.

You can execute the macro script file by using the @ command from the terminal
command mode.  After you enter this command, you must enter the name of the
macro script file.  Enter the name of the macro script file or enter [RETURN] if
you decide not to execute a macro file.

Here is an example of a simple macro script which can be used with a "smart"
modem:

T "555-1212
L "CONNECT
S" Will arrive at 5 PM"
H

This macro sequence consists of four commands which will execute automatically
from the beginning to the end.  Each command is shown in a separate line for
clarity.  The first command (T) will telephone dial the number 555-1212.  The
second command (L) will look for the CONNECT message  from the "smart" modem
which occurs after a connection is made.  The third command (S) will send the
text message and the last command (H) will hangup.

If you execute this macro, it will dial the number, wait for a connection, send
the message and hang up.  All of this will be performed without any action on
your part except to enter the @ command and macro script file name.

The macro example shown above consists of four text lines.  You can enter these
lines with the editor and save them to a disk file.  This macro could also be
created in the following format:

T"555-1212":L"CONNECT":S"Will Arrive at 5 PM":H

This macro sequence does exactly the same thing as the sequence shown earlier.
You may use the colon to separate different commands and you may remove
unnecessary spaces.


MACRO SCRIPT FILE LENGTH

A DOS 3.3 macro script file must not exceed 512 characters and a ProDOS macro
script file must not exceed 510 characters.  If more space is required, you can
use a macro command to execute another macro script file.  By chaining several
macro script files in series, you can handle a macro sequence limited only by
your disk capacity.

Since the CR/LF combination at the end of each line uses two characters, you can
save some file space by using a colon (which is only one character) between
macro commands instead of placing each command on a separate line.  You can also
save space by placing the delimited string immediately after the command letter.
Many of the examples shown have a space between the command letter and the
delimited string for clarity, but it is more efficient to eliminate any
unnecessary characters.

Although comments are allowed in a macro file, they should be used sparingly to
conserve space.

The null character (00) can be used in DOS 3.3 macro script files, but should
not be used in ProDOS macro script files.


MACRO LETTER COMMANDS

If you inspect the macro example presented earlier, it will show you each macro
command consists of a single letter.  (For example, T, L, S. H).  The macro
command letter must be the first character at the start of a new line or the
first character after the colon which separates commands.  If the first
character is not a macro command letter, the remaining characters will be
ignored until the next colon.


MACRO STRINGS

Most of the macro commands in the example shown earlier are followed by a
character string delimited by quotation marks.  The macro string delimiters can
be quotation marks (""), apostrophes (''), or less-than/greater-than characters
(<>).   For example, all of the following macro commands are the same:

L "CONNECT"
L 'CONNECT'
L <CONNECT>

The delimited string must not contain the delimiter.  For example do not use the
following string:

L 'CHARLEY'S AUNT'

Instead of looking for CHARLEY'S AUNT, this macro will look for CHARLEY.  Use
the following macro instead:

L "CHARLEY'S AUNT"

The <> delimiters have a special function when used with the L, R, S, or [ macro
commands.  The following comments only apply to L, R, S, or [ macro command
strings enclosed by the <> delimiter.  If an exclamation point (!) appears in
the string, it will be treated as a CR character.  If a percent (%) character
appears in the string, it will be treated as a LF character.  See examples in
the sections describing the L and S macro commands.

The <> delimiters also have the following special significance when used with
the macro S command.  If the first character in the string is a # character,
this character will not be sent, but the remaining characters in that string
will be sent at a slow transmission speed.  All subsequent strings will revert
back to the normal (fastest) transmission rate.  See examples in the section
describing the S macro command.

You may also use a colon (:) in a macro string.  The macro string can also
include control characters.  If you are using the editor furnished with this
program, use the control-P editing command to put control characters into the
string.  For example, if you want to enter a macro to send a control-G
character, use the following six keystrokes in the editor:

1) S
2) "
3) [CTRL] P
4) [CTRL] G
5) "
6) Return

This will be displayed on the screen as follows:

S"^G"

Since the editor does not allow Control-J (LF) or Control-M (CR) to be inserted
within a line, use the ! or % characters with the <> delimiters as described
earlier if you want to send a CR or LF character.

The length of the macro sting must be no longer than 32 characters with the DOS
3.3 version and no longer than 64 characters with the ProDOS version.  For the L
and R macro commands, the length must be no longer than 16 characters.  If you
want to specify a longer string, divide the string into shorter consecutive
segments.  For example, with the S macro command:

S"The quick brown fox jumped over ":S"the lazy dog's back"

Sometimes a macro string is a filename or pathname.  If you defined default
prefixes with the INSTALL program and you wish to over-ride the default use
"^Hfilename."  The ^H (left-arrow) will cancel the default prefix.  If you wish
to use the last filename or pathname, use " ". (Remember the space re-calls the
last filename or pathname entered).


LABELS

Numbers from 0 to 9 or the following characters can be used as labels at the
start of a new line or immediately after the colon which separates commands.

( ) * + , - . /

These labels are not commands and are ignored by most macro commands.  They are
used with the G (go to) macro command which allows a jump or call from one place
in the command sequence to another place marked by a label.

The numerical labels do not have to be in numerical sequence.  In fact, the
number selected for a numerical label determines the maximum number of times
that label can be accessed through the G (go to) macro command.

The "0" numerical label has a special characteristic.  It is used to mark the
macro command the program will execute whenever a timeout occurs.  it also marks
where execution will resume if the G (go to) command to a particular label has
been performed more than the allowed number of times.

The next example uses numerical labels 0 and 3

T"555-1212"
L"CONNECT":S"Send more money"
3:V:^G":Z"1":G"3"
0:H:Q

This macro is for a "smart" modem.  The first macro command line will dial the
number.  The Second line will look for the CONNECT message from the "smart"
modem.  If a connection is made, the "Send more money" message will be sent.

The label 3 on the third line will be ignored initially.  The V"^G" command will
beep the speaker and the Z"1" command will pause for one second.  The G"3"
command will cause a jump to the label 3 at the beginning of the same line.  The
speaker will be beeped again.  After three repeats, the G"3" command will no
longer go to numerical label 3, but will go to numerical label 0.  This label is
on the last line with the H and Q macro commands which will hangup and quit
(end) the macro.  Essentially, the last two macro command lines will beep the
speaker four times (once plus three repeats) at one second intervals.

What happens if no connection occurs and the "CONNECT" is never received?  The
macro will time out and jump to label 0 where it will hangup and quit.  The
speaker beeping will not occur.

More information on these labels will be provided in the description of the G
macro command


MACRO COMMENTS

You may place comments in a macro script file as reminders of what the macro
file or a particular command does.  You can read the comments when you view or
edit the file.

If the first letter in a new line or after a colon is not a macro command
letter, the remainder (until the next colon or CR/LF) will be ignored and can be
used as a comment line.  You may also place comments after the delimited string
or between the macro command letter and the delimited string.

Comments placed directly after the macro command letter must not contain any of
the delimiters listed earlier.  Comments must not use the colon (:) character.
Comments use up file space so they should be used sparingly.  Some examples of
comments are shown below.

L Passwo"rd"
T "555-1212" acme realty co
 stock market macro

The last line is a comment line because it is preceded by a non-macro command
letter (the space character).  If you wish to have comments appear on the video
screen while the macro is being executed, use the V macro command described
later.


MACRO ERROR MESSAGES

If you enter an erroneous string with a macro command, you will see the
following type of error message:

x MACRO ERR --> yyyy

The "x" represents the macro command and the "yyyy" represents the string.  For
example, if the macro command is G"9", which means go to label 9, and label 9
does not exist, the following error message will appear:

G MACRO ERR --> 9


The macro sequence will not terminate when an error occurs.  the command with
the error will be skipped and the next macro command will be executed.


MACRO COMMANDS

A description of all of the macro commands is presented below.  Some of these
commands are similar to the commands which you can enter directly in the
terminal command mode.  In these cases, the macro command letter is the same as
the letter used for the direct command.  many of these commands must be followed
by a character or string delimited by "", '', or <>.  In the description below,
the "" delimiters are used in the examples, but any of the other delimiters can
be used.

Your system might not support all of these commands.  For example, if you do not
have a clock card installed, the K macro command will not function.


A: AUTO SAVE BUFFER

     A "1"          Turn auto-save on
     A "0"          Turn auto-save off

The A macro command will turn the capture buffer auto-save feature on or off. If
you do not set auto-save on and the capture buffer becomes full, the buffer will
be set off and no further text will be captured.  If you set auto-save on, the
buffer contents will be saved to disk with the file name SAVED.x where x is
initially the letter A.  After the disk save, the buffer will be cleared to
capture additional text.  If XON/XOFF is enabled, XOFF will be sent before the
disk save.


B:BUFFER ON/OFF

     B "1"          Set capture buffer on
     B "0"          Set capture buffer off

The B macro command will set the capture buffer on or off.


C:CLEAR BUFFER

     C              Clear capture buffer

The C macro command will clear the capture buffer.  No string is required with
this command.


D:DISK SAVE

     D "filename" or
     D "pathname"

The D macro command will save the capture buffer to a disk file.  The macro
command D "filename" or D "pathname" will save the buffer to a file called
"filename" or "pathname" on the currently active disk.  the buffer will not be
automatically cleared after the file has been saved to disk.  (Use the C macro
command if you wish to clear the buffer.)  If you have enabled XON/XOFF, XOff
will be sent before the disk save and XON will be sent after the disk save.


E:EMULATION ON/OFF

     E "1"          Enable emulation
     E "0"          Disable emulation

The E macro command will enable an emulation if that emulation file is loaded.
(See the N macro command).


F:  FULL/HALF DUPLEX

     F "F"          Switch to full duplex
     F "H"          Switch to half duplex

The F macro command will switch to full or half duplex


G:GO TO LABEL OR SUBROUTINE

     G "n"           Go to label n

The G macro command will go to the label specified in the delimited string.  The
label can be any number from 0 to 9 or one of the following characters:

( ) * + , - . /

For example, the macro command G "3" will jump to the label 3 and resume macro
command execution at that point.  If the label is not found, an error message
will be displayed and the next following macro command will be executed.

If this command is  part of a loop, it may be executed several times.  However,
if a numerical label (1-9) is used, the numerical value of the label also
defines the maximum number of times this jump command can be executed.  After
the maximum is exceeded, the next macro command to be executed will be the
command after the numerical label 0 instead of the specified numerical label.

The following macro illustrates this decremented counting limit

3:S"^G"
G"3"
0:Q

This macro will start by executing the first line which send a control-G (bell)
character.  The G"3" command in the second line will cause a jump to the first
line and the same character will be repeated.  This will be repeated two more
times for a total of three repeats.  After the third repeat, the macro will jump
to numerical label 0 and quit.  The bell character will be sent a total of four
times (once at the start plus three repeats).

After a numerical label has been jumped to the maximum number of times, it can
never be accessed again with the G macro command. The only exception is the
numerical label 0 which can be accessed an unlimited number of times.

If the numerical label 0 is not used in a macro file, its presence is implied at
the end of the file.  That is, a G "0" will terminate the macro if label 0 is
not assigned anywhere.

If a } macro command is encountered after a G command has been executed, it will
be interpreted as the end of a subroutine and the operation will resume
execution after the previous g macro command.  For example:

G"+":G"+":Q
+"S"GOODBYE"}

The last line is the subroutine which begins with the + label and ends with the
} command.  This subroutine is called twice by the G"+" macro commands.


H:HANGUP

     H               Hangup

The H macro command will hangup the phone connection


I:INSERT LF

     I "1"           Insert line feeds
     I "0"           Do not insert line feeds

The I macro command will enable or disable the automatic insertion of a line
feed character after each CR character sent.


J:PARITY/LENGTH

     J "n"           Set Comm parameters

The J macro command will select the world length, parity, and number of stop
bits.  This macro command must be followed by a delimited number which
corresponds to the number associated with the data word parameters desired.
These parameters are listed when the J command is executed in the terminal mode.
For example, in many cases the J command in the terminal mode will show a list
of parameters which may include  the following:

      6)8+1+none

In this example, you would use the J"6" macro command to select 8 data bits with
one stop bit and no parity.


K:KLOCK TIME

     K "time"        Wait for time set
     K "T"           Select time-of-day
     K "E"           Select elapsed time

The K macro command will specify the time to wait for before executing the next
macro command.  this is useful in delaying the start of a macro until a
designated time.

You must have a clock card which has been installed with the INSTALL program in
order to use this macro command.  You do not need to enable the clock or
time-of-day display.  To specify the time, you may use any one of the following
formats:

K "01:35 PM"
K "1:35 PM"
K "1:35 pm"
K "12:15 am"
K "12:15 AM"

You must specify AM, PM, am, or pm.  This may be preceded by a space.  There
must be an hour number in the range of 01 to 12 followed by a colon followed by
a minute number in the range of 00 to 59.  Remember that 11:59 is followed by
12:00 and 12:59 is followed by 1:00.  The zero hour is not recognized as a
substitute for the 12th hour.  If you make an error in defining the time, the
macro sequence will terminate.

When the macro clock command is in effect, you may quit this command and skip to
the next macro command by pressing any key except the escape key.


L:LOOK FOR STRING

     L "string"      Look for specified string
     L               Look for any character

The L macro command will look for the specified string.  It will wait until the
string has been received before continuing to the next macro command.  For
example, L "HI" will wait until the string HI has been received.  The string
must be exactly as defined.  In this example, the string hi will not be
recognized because the lower case letters do not match the specified string.
When this command is in effect, you may quit this command and skip to the next
macro command by pressing any key except the escape key.  If no string is
specified, the command will look for any received character.  If the <>
delimiters are used, the following substitutions will be made in the string:

     ! will be treated as a CR
     % will be treated as a LF

The following are some examples:

L                Look for any character
L "HI!"          Look for HI!
L <HI!>          Look for HI followed by CR
L 'HI%'          Look for HI%
L <HI%>          Look for HI followed by LF
L "HI!%"         Look for HI!%
L <HI!%>         Look for HI followed by CR and LF
L <!>            Look for CR
L <%>            Look for LF
L "!":L<!>       Look for ! then look for CR

This command is useful in situations where you must wait for a prompt or query
from the other system before responding. By specifying the required prompt with
the L macro command, your system will wait until it is received before
responding.  For example, if you must log into a system by supplying a password
after the other system sends "Enter password:", you can use the following macro:

L "Enter password:"
S <ROSEBUD!>

You may shorten the first line to any of the following forms:

L "word:"
L "d:"
L ":"

Use as long a string as necessary to avoid conflicts with other text which may
be received.  The maximum length allowed is 16 characters.

If you expect a string to be received more than once and you don't want to
proceed the first time it is received, you can use the same L macro command
several times.  For example, suppose you expect to receive the following
message:

"You need a password for this system.  Enter your password"

You want to ignore the first "password" string which is received, but you want
to respond when this string is received the second time.  Use the following
macro sequence:

L "password
L "password"
S <ROSEBUD!>

Or to reduce space, use the following:

L"rd":L"rd":S<ROSEBUD!>

The password will be sent after the second "password string is received.

The L macro command is also useful in using "smart" modem messages to determine
modem status changes.  Fort example, any one of the following macro commands can
be used to determine when a connection has been made:

L "CONNECT"
L" "ECT"
L "T"

The receiver control input on your serial card must be "high" to receive the
CONNECT message from a "smart" modem.  If you are using carrier control, the
messages sent by the modem might not be received until a remote carrier has been
detected.

In the case of non-smart internal plug-in modems, the MODEM MGR program
generates the modem messages (CONNECT, NO CARRIER, RING, etc).  Since these
messages are self-generated and are not received from an external source, the
messages cannot be used with the L macro command.  However, when a connection is
made with these modems, a LF character is inserted into the input buffer so the
following macro command can be used with non-smart internal modems to recognize
a connection has been made.

L <%>

See the U macro command for another way of detecting a connection when carrier
control is enabled.

If the string is not received within a defined time period, time-out will occur
and the next macro to be executed will be the one following the label 0.  If a
label 0 does not exist, the macro sequence will terminate.  The macro timeout
period can be set by executing the INSTALL program.


M:MODEM BAUD RATE

    M "X"            Set modem baud rate

The M macro command will set the baud rate for the modem serial card (if used)
within the range of baud rate settings available.  This macro command must be
followed by a delimited letter which corresponds to the letter associated with
the baud rate desired.  These letters and their associated baud rates are listed
when the M command is executed in the terminal mode.  For example, the M command
in the terminal mode may show the following list of baud rates:

     A:High speed
     B:Low speed

In this example, you would use the M"A" macro command to select the high speed
baud rate.  In other cases, you may see the following rates listed when the M
command is executed in the terminal mode:

     A:50
     B:75
     C:110
     D:135
     E:150
     F:300
     G:600
     H:1200
     I:1800
     J:2400
     K:3600
     L:4800

     N:9600
     0:19200

If you wanted to use a macro to select the baud rate of 1200 baud, you would use
the M "H" command.


N:NEW EMULATION

     N "filename" or
     N "pathname"

The N macro command will load the emulation file specified in the string
following this command.  For example, the macro command N "D200" will load the
emulation file with the name D200.EMU.  For DOS 3.3, the emulation file must be
on the work disk used to start the program.


O:ORIGINATE TO ANSWER

     O               Switch to answer mode

The O macro command will switch the modem from the originate mode to the answer
mode.  To enter the originate mode, see the T macro command.


P:PRINTER ON/OFF

     P "1"           Enable printing
     P "0"           Disable printing

The P macro command will enable or disable printing.


Q:QUIT MACRO

     Q               Quit macro

The Q macro command will terminate the macro.  All macros will also terminate
automatically at the end of the last command in the macro file.


R:CONDITIONAL SKIP

     R "string1/string2"       Look for string1 or string2
     R                         Look for any character

The R macro command looks for a match with either one of two specified strings.
The form of this command is R "string1/string2" where string1 and string2
represent two different strings.  If the first string (string1) is received
first, the macro execution will proceed to the next macro command on the same
line.  If the second string (string2) is received first,the macro execution will
skip to the start of the next line in the macro file. The next macro instruction
executed is dependent on which string is received first.  Each string can be up
to 16 characters.

The following is an example of the use of this conditional macro.

3:T"555-1212"
R"CONNECT/BUSY":V^G:Q
H:Z"9":Z"9":Z"9":G"3"
0:H:Q

Suppose you have a "smart" modem which will issue a CONNECT or BUSY status
message if the appropriate condition exists.  The first macro command will dial
the number.  (Ignore the numerical label 3 for now).  the R "CONNECT/BUSY"
command in the second line will look for a CONNECT or a BUSY.  If the "smart"
modem send the CONNECT message, the remainder of that command line will be
executed.  (The remaining commands on that line will beep the speaker and quit
the macro).  If the "smart" modem sends the BUSY message, the next command line
will be executed. )  The beeping of the speaker and quitting will not be
executed).  The next and subsequent commands will cause hangup and a 27 second
pause before going to the beginning of the macro to repeat it all over again.

Essentially this macro will  dial a number and if a connection is made, it will
beep the speaker so the user will be aware of the successful connection.  If the
line is busy, the macro will pause for 27 seconds and try again.  After 3 tries,
it will quit.

If neither string is received within a set period, timeout will occur and the
entire macro sequence will terminate.  The macro timeout period can be set by
executing the INSTALL program.

If no strings are specified after the R macro command, the program will wait for
up to approximately one second for the next character to be received.  If a
character is not received within approximately one second, the macro execution
will skip to the start of the next line of the macro.

The following is an example of the use of this R conditional macro without a
string.

9:S<!>
R:G"9"
V"^G"

The first line will send a CR character.  In the second line, the program will
wait for a response from the other system. If nothing is received within one
second, the G"9" command will result in a jump to the first line to send a CR
character again.  This will be repeated up to 9 times before it quits.  If a
character is received , the last line will be executed (the speaker will be
beeped.)

This is an example of using a macro to log into a system which requires a CR
character to initiate the log-in process, but does not always reliable recognize
the CR character until it has been sent a few times.


S:SEND STRING

     S "string"      Send string

The S macro command will send the following delimited string.  If you use the <>
delimiters, the following substitutions will be made in the string:

     ! will send a CR character instead
     % will send a LF character instead

For example:

S "HI!"              Send HI!
S <HI!>              Send HI followed by CR
S 'HI%'              Send HI%
S <HI%>              Send HI followed by LF
S "HI!%"             Send HI!%
S <HI!%>             Send HI followed by CR and LF
S <!>                Send CR
S <%>                Send LF
S "!":S <!>          Send ! followed by CR

Also, if the <> delimiters are used and the first character is a # character,
the # character will not be transmitted, but all remaining characters in the
string will be sent at a slow rate. It is a good idea to use the <> delimiters
with the initial # character for systems which cannot receive characters at the
maximum rate.  Some examples are shown below.

S "HI"               Send HI at normal speed
S <HI>               Send HI at normal speed
S "#HI"              Send #HI at normal speed
S <#HI>              Send HI at slow speed
S <#HI!>             Send HI and CR at slow speed
S<#HI>:S"BYE"        Send HI at slow speed and send BYE at normal speed

If you use the ' ' delimiters when the block mode is enabled with the
split-screen video, the string will be placed in the block and will not be sent
until the block is transmitted.

If the string sending command is the last macro command in a script file and the
other system is echoing your characters, you may find the MACRO END message
appears before the string is completely echoed.  For example, if the last macro
command is S<OFF!>, you may see the following:

OF
MACRO END
F

If this bothers you, use the following command sequence:

S<OFF!>
L<!>

This will send the OFF string and look for the echoed CR character before ending
the macro.  Another solution is to use:

S<OFF!>
Z"1"

This will send the OFF string and pause for one second before ending the macro.


T:TELEPHONE DIAL

     T "string"      Telephone dial

The T macro command is the same as the T command in the terminal command mode.
It dials the number in the delimited string which follows this command.  If no
string is supplied, the modem will be switched to the originate mode.  The
following are some example commands:

T "T555-1212"        Tone dial 5551212
T "P555-1212"        Pulse dial 555-1212
T "P9,T555-1212"     Pulse dial 9, delay 2 seconds, tone dial 555-1212
T "Z"                Redial last number dialed
T "D"                Dial default number
T                    Go to originate mode


U:USE CARRIER CONTROL

     U"1"            Use carrier control
     U"0"            Don't use carrier control

The U macro command can be used to check for the presence of a carrier before
proceeding.  It can also be used to terminate a macro sequence if a detected
carrier is lost.  Carrier detection is one way to determine if a connection has
been made.  You must have carrier control in order to use this macro.

The U "1" command will suspend further macro command execution until a carrier
is detected.  After the carrier is detected, the next macro instruction will be
executed.  If the carrier is subsequently lost, the macro sequence will
terminate.  The U "0" command will disable carrier checking under macro control.

If the U "1" command is used, the macro sequence will terminate after the
carrier is lost when a call is completed.  Be sure to complete all desired
operations before this happens.  For example, there is a bug in the following
macro sequence:

B "1"
C
T "555-1212"
U "1"
S <Send stock quotes!>
L "End of quotes"
H
D "STOCK.FILE"

After the capture buffer is enabled and cleared and the phone number is dialed,
the U "1" command will look for carrier detection which indicated a connection
has been made.  It will then ask for stock quotes and after the quotes have been
received, it will hangup the phone.  However, before the last macro command can
be executed to save the buffer to a disk file, the hangup operation will cause
loss of carrier and the macro sequence will be terminated.

There ar two ways you can avoid this problem.  One way is to use the D macro
command to save the file before using the H macro command to hangup the phone.
Another way is shown below.

B "1"
C
T "555-1212"
U "1"
U "0"
S <Send stock quotes!>
L "End of quotes"
H
D "STOCK.FILE"

Now the U "0" command is used to turn off the carrier checking after the initial
carrier presence is detected.  This will allow all of the macro commands to be
executed even if the carrier is lost after hangup.


V: VIEW MESSAGE

     V "string"      View string on video screen

The V macro command will print the delimited string on your video screen.  If
you want to put messages on the screen to indicate which macro instruction is
0urrently being executed, this is one way to provide a running status report.
Limit the string to a maximum of 32 (DOS 3.3) or 64 (ProDOS) characters.  The
following are examples:

V "Stock market macro"
V "Chaining to next macro"
V "^G"

The last example will beep your speaker.  (The delimited character is a
control-G). Since these messages can use up a lot of character space, you should
use them sparingly.  Usually there are status messages issued with each macro
command so additional comments are not necessary.


W: WAIT FOR CALL

     W               Wait for phone call

The W macro command will set your system ready to answer a phone call.  When a
call is received, your system will answer the call in the answer mode. There is
no timeout on this macro.  To terminate the macro, press the [ESC] key.  With a
"smart" modem, do not use the L"CONNECT" command after the W command because the
W command will do this.


X:XON/XOFF

     X "1"           Enable XON/XOFF handshaking
     X "0"           Disable XON/XOFF handshaking

The X macro command will enable or disable XON/XOFF.  If the other system
responds to XON and XOFF, you may wish to use this command to enable XON/XOFF
for flow control.


Y:SEND DISK FILE

     Y "filename     Send disk text file
  or Y "pathname"

The Y macro command will transmit the disk text file specified by the file name.
For example, the following macro command will send the disk file caLLED MYFILE:

Y "MYFILE"

You may specify a prompt character for line pacing by using the [ macro command
before the Y macro command is used.


Z:DELAY

     Z "n"           Delay n seconds

The Z macro command will pause approximately for the number of seconds
specified.  The number of seconds can be from 0 to 9.  If n number is specified,
the delay will be 1/4 second.  Longer delay times can be achieved by using the
letters A through Z, although the delay times will be less accurate. The
following are some examples:

Z            Pause 1/4 second
Z:Z          Pause 1/2 second
Z "1"        Pause 1 second
Z "8"        Pause 8 seconds
Z "A"        Pause 17 seconds
Z "Z"        Pause 42 seconds

All times are approximate. Although the macro execution will be suspended, any
characters received during the pause will be displayed and captured (if the
capture buffer is enabled).


@:EXECUTE ANOTHER MACRO

     @ "filename"    Exec another macro script file
  or @ "pathname"

The @ macro command will load and execute another macro script file.  This
command allows macro files to be chained so a long macro sequence which exceeds
the 512 (DOS 3.3) or 510 (ProDOS) byte limit per macro script file can be
handled.  Each macro script file executed will be essentially a brand new macro
sequence and the previous macro sequence which loaded it will no longer exist.
Therefore, you cannot use a G macro command to jump back to a numerical label in
a previous macro file.

The following is an example of the @ macro command used with a "smart" modem.

3:T"555-1212"
R"CONNECT/BUSY":@"STOCKS.MACRO"
H:G"3"

After dialing the number, the macro R command looks for a CONNECT or BUSY status
message from the modem.  If the CONNECT is received, it will load and execute
the macro script file called STOCKS.MACRO.  If the BUSY is received, it will
hangup and repeat the macro sequence up to three more times before quitting.


;:RESET ELAPSED TIME

The ; macro command will reset the elapsed time to 00 minutes


[:SET PROMPT TO SEND DISK FILE

You may use the [ macro command for any subsequent Y macro command to specify a
single character prompt.  The program will wait until the prompt is received
before sending each line from the disk file.  If you do not specify a prompt,
the file will be sent without prompting.

For example, the following macro sequence will wait until a ? prompt is received
before sending each line from the disk file HISFILE then will wait until a LF is
echoed before sending each line from the disk file HERFILE then will send the
disk file MYFILE without prompting.

["?":Y"HISFILE"
[<%>:Y"HERFILE"
[:Y"MYFILE"


\:CLEAR SCREEN

The \ macro command will clear the screen and home the cursor.  The clock
display will not be cleared.


]:CAPTURE SCREEN

The ] macro command will capture the screen to the buffer.  The following
example shows how you can capture the time display to the buffer:

\:]


^:SEND BREAK

The ^ macro command will send a continuous space or break condition for a period
of approximately 230 milliseconds.


_:FLUSH BUFFER

The _ macro command will save the buffer to disk.  This is similar to the D
macro command except you do not have to specify the filename.  The buffer will
be saved with a "SAVED.x" filename where x is the next letter in the current
"SAVED.x filename sequence.


|:ENTER STRING

The | macro command will allow you to enter a string to be used wherever a null
string occurs in the macro sequence.  The string can be no longer than 16
characters.  You will not be prompted to enter the string so use the V command
to provide prompting.  This allows you to enter a string into the macro sequence
without having to load, edit, and save the macro script file.  For example:

V"Enter time to start^G"
|
K""

When you enter the string, it will be used as the string for the K command which
is shown with a null string.

You may use as many null strings as you wish.  The example below shows the
string you enter will be used in two places.

V"Enter call-sign^G"
|
S"":S" DE W6OU R UR RST 599 ":S"":S" DE W6OU K"


}:RETURN FROM SUBROUTINE

The } macro command will return to the macro instruction following the previous
G macro command.  It is used to mark the end of a subroutine which has been
called with the G command.  For example:

V"Enter name^G"
|
G"*"
G"*"
S"Happy birthday dear ":"S"":SV!>
G"*"
Q
*S<Happy birthday to you!>:}

The last line is a subroutine which start with the * label and ends with the }
return command. This subroutine is called three times with the G"*" commands.


{:SEND MESSAGE NUMBER

The { macro command will send a flagged message number followed by a CR.
(Messages can be flagged in the reverse-scroll mode.)  The earliest flagged
message number will be sent first.  The next flagged number will be sent each
time this macro command is used.  After a message number is sent, the next macro
command on the same line will be executed. If there are no more flagged
messages, the macro execution will skip to the next line.  The following is an
example to retrieve all flagged messages from a host.

S<RETRIEVE!>
*:L"Enter msg no.":{G"*"
S<QUIT!>

The first line tells the host you wish to retrieve messages.  The second line is
a loop which sends a flagged number whenever the host asks for one.  If there
are no more numbers left, the macro skips to the third line to quit.


MACRO FILENAME STRINGS

You may use the space character to recall the last filename or pathname used.
For example, if you want to save a file to disk and then transmit it:

D"MYFILE"
Y" "

In the ProDOS version, if you have used the INSTALL program to specify default
prefixes for the capture or macro files, you may cancel the default prefix by
using the backspace character (Control-H) as the first character in the macro
filename string.  For example, if you wish to use a macro command to execute
another macro script file which is not in the default prefix volume or
sub-directory:

@"^H/OTHER/MACRO.FILE"


MACRO TERMINATION

A macro command sequence will terminate if any of the following occurs:

1) There are no more macro commands in the sequence
2) A quit (Q) macro command is executed.
3) A timeout occurs and there is no label 0.
4) Carrier is lost when carrier checking is effect (U"1").
5) You have set the wrong time with the clock (K) macro command.
6) A disk error occurs.
7) You type the [ESC] key or whichever key you have defined as the command key.


FUNCTION KEYS

You can pre-program the keyboard numerical keys from 1 through 9 to provide
special functions.  The functions you assign to each key can be a simple
function like sending a special character.  It can also be a complex function
like an entire log-on/access/log-off operation.

You define the functions by assigning programmed macro sequences to the number
keys.  These macro sequences are similar to those used with macro script files.
The major differences is all of the function key macros are loaded from one disk
file and each one can be subsequently executed by suing one of the function
keys.  To program a function key, you should be familiar with the macro
commands.

A function key file is an ordinary text file which you can create with the
editor.  The macro sequence which is assigned to a function key must be entirely
on one continuous line.  If there is more than on macro command on a line, the
commands must be separated by a colon (:) character.  The first two characters
in each function key line must be the number of the function key followed by an
equal sign (=).  The remainder of the line is the macro command or sequence in
the same format as previously described.

A DOS 3.3 function key file must be no more than 512 characters in length and a
ProDOS function key file must be no more than 510 characters in length.

An example of a function key file is shown below.

1=S "{"
2=S "}"
6=T"555-1212":L"CONNECT":L"Password?":S<ROSEBUD!>

This function key file defines three function keys corresponding to the
numerical keys 1, 2, and 6.  Each key is defined by its number followed by an
equal sign (=) followed by the macro sequence to be assigned to that function
key.

Suppose you have loaded this function key file.  If you enter [ESC] 1 or oa-1,
the { character will be sent.  If you enter [ESC] 2 or oa-2, the } character
will be sent.  If you enter [ESC] 6, the function key macro sequence will dial
the number, wait for a connection, and send the password when prompted.

All of the function keys do not have to be defined.  In the example above, there
are not functions assigned to keys 3, 4, 5, 7, 8 and 9

You can load a function key file by using the [ESC] 0 or oa-0 command in the
terminal command mode.  If no function key file is loaded, a NO FUNCTION KEY
FILE message will be displayed.  If a function key file is already loaded, its
contents will be displayed.  The following prompts will then appear:

     NEW FUNCTION KEY FILE
     Filename? -->

If you don't want to load a new function key file, enter [RETURN].  If you want
to load a file, enter the name of the function key file.  If the file is longer
than 512 characters (DOS 3.3) or 510 characters (ProDOS), a FILE TOO LONG
message will be displayed and the file will be partially loaded.  If you load a
new file, any existing function key definitions will be lost.

You may also use the function keys to manage your macro script files.  Suppose
you have macro script files named COMPUSERVE, SOURCE, and DELPHI which provide
automatic log-on.  You can create the following function key file which will log
you on to any of these systems with just a few keystrokes.

1=@"SOURCE"
2=@"COMPUSERVE"
3=@"DELPHI"

In the split-screen video mode with the block enabled, you may use the function
keys to send text to the block instead of sending it directly to the output.  If
you use the ' ' delimiters, the text will be sent to the block.  If you use the
" " or < > delimiters, the text will be sent direct.  For example, the following
function key file will send the text associated with function keys 1 and 2
direct, but will send the text associated with function key 3 to the block where
it will be transmitted after a [RETURN] is typed.

1="S"RYRYRYRYRYRYRYRYRYRYRY"
2=S<THE QUICK BROWN FOX JUMPED OVER>:S<THE LAZY DOG'S BACK!>
3=S' de w6ou placentia california'

The ' ' delimiters will not have this special feature if you have disabled the
block mode or if you are using the full-screen video.

You may also run a function key command sequence with a control key.  Use the
INSTALL program to re-define the control key to the desired function key.
Instead of typing [ESC] followed by the function key number, you can execute the
same function key command by just typing the control key.  Since the keyboard
arrow keys are control keys, you may defined the arrow keys to execute functions
defined by a function key file.  For example, suppose you want to use the
left-arrow (hex $08), the right-arrow (hex $15), the down-arrow (hex $0A) and
the up-arrow (hex $0B) to generate the cursor commands for a DEC VT-52 .  The
function key file would be:

1=S"^[A"
2=S"^[B"
3=S"^[C"
4=S'^[D"

The ^[ is the escape character.  the control keys would be redefined as:

$08 --> $34
$0A --> $32
$0B --> $31
$15 --> $33

Since the function key file is an ordinary text file which you can display by
suing the [ESC] 0 command in the terminal command mode, this feature can be used
for other purposes.  You may create a reminder or help file and load it as a
function key file.  Whenever you want to refer to this file, enter [ESC] 0 and
the contents of this file will be displayed on your video screen.  Since this
file is not being used to define function keys, avoid the use of an equal sign
(=) in the file.


AUTO-LOAD MACRO OR FUNCTION KEY FILE

You can have a macro script file or a function key file automatically loaded
whenever you start the MODEM MGR program.  If you name the macro script file
BTMAC.FILE and place it on the work disk, it will be automatically loaded and
executed when the program is started.  If you name the function key file FK.FILE
and place it on the work disk, it will also be automatically loaded when the
program is started.


MACRO PROBLEMS

What can go wrong with macros?  Everything!!  Macros are programmed to follow
expected prompts and status messages in a specific order.  These must be defined
exactly as they are expected to be received.  You should always test a macro
file under the actual operating conditions before using it regularly. Preparing
a macro file is like writing a computer program.  A miner typographical error or
mis-spelling can cause a fatal malfunction of the program.

Here is a list of potential causes of problems when you use macros it connect to
another host system:

1) The modem is set to the wrong baud rate.
2) The modem mis-identifies a valid connection as a BUSY or NO CARRIER.
3) The modem mis-identifies a BUSY or NO CONNECT as a valid connection.
4) Someone answers the phone instead of the modem.
5) Noise on the phone lines causes a prompt or reply to be garbled.
6) Although a valid connection occurs, the host is busy.
7) The host sends you a special message instead of the usual expected
   message.
8) Your transmissions are sent too soon or too fast.
9) When a macro accesses a disk drive, it accesses the wrong drive, slot, or
   prefix.
10) Your modem refuses to hang up.


MACRO EXAMPLES

Some useful macro sequences will not be described for use with currently popular
information systems.  Since these are based on present system prompts and menus,
future system changes may render these non-operational.  However, they are
useful as examples which you can modify to fit your needs.


LOGGING ON SOURCE VIA TELENET NETWORK

Suppose your SOURCE account number is ABC123, your password is BOO, your local
Telenet phone number is 558-7078, and the Source Telenet code is C 30124.  After
the connection is made, you have to send the CR character twice.  you will then
receive a "Terminal=" message.  You must send a "D1" followed by a CR. After the
">" prompt is received, you must send "ID" followed by your account number and
password.  The following example shows a macro which accomplishes this with a
"smart" modem.  The comments in the right column should not be included in the
macro file.

B"1":C                   Turn capture buffer on and clear it
T"T558-7078"             Tone dial the number
L"ECT"                   Look for CONNECT"
Z"5"                     Pause 5 seconds
S<!>                     Send CR
Z"1"                     Pause 1 second
S<!>                     Send CR again
L"="                     Look for "Terminal="
S<#D1!>                  Send "d1" and CR (slow)
L"@"                     Look for "@"
S<#C 30124!>             Send code and CR (slow)
L">"                     Look for ">"
S<#ID ABC123 BOO!>       Send your ID and CR (slow)

If your modem does not support tone dialing, remove the T from the phone number
string.  If you have a non-smart external modem with carrier control enabled,
use the U"1" command instead of the L"ECT" command.  If you have a non-smart
internal plug-in modem, use the L<%> command if carrier control is disabled, or
use the U"1" command if carrier control is enabled instead of the L"ECT"
command.

The timing used in sending the initial two CR characters is sometimes critical.
A five second pause is used in this example before sending the first CR.  If the
CR is sent immediately after the connection is made, it may be missed.  In some
cases, you may have to use a longer delay.  In other cases, you may have to
remove the one-second pause between the transmission of the two CR characters.
Experiment with the timing to find the most reliable log-in sequence.


LOGGING ON COMPUSERVE VIA COMPUSERVE NETWORK

Suppose your Compuserve USER ID is 76003,5, your password is BOO, and your local
Compuserve phone number is 520-9733.  After the connection is made, you must
send a control-C character. The reply will be a "User ID:" message.  You must
then send your suer ID followed by a CR/  This completes the log-in operation.
The following example shows a macro which accomplishes this with a "smart" modem

B"1":C                        Turn capture buffer on and clear it
T"T520-9733"                  Tone dial the number
L"ECT"                        Look for "CONNECT"
Z"5"                          Pause for 5 seconds
S"^C"                         Send control-C
L"ID:"                        Look for User ID:"
S<#76003,5!>                  Send ID and CR (slow)
L"rd:"                        Look for "Password"
S<#BOO!>                      Send password and CR (slow)

In the S"^C" macro command above, the delimited string is not a "^" character
followed by a "C" character, but is a single control-C character. Refer to the
discussion in Chapter 7 on entering control characters into text with the
editor.

The timing used in sending the initial control-C character is sometimes
critical. A five second pause is used in this example before sending it. If the
control-C is sent immediately after the connection is made, it may be missed and
the remainder of the macro will not be executed. You may have to use a longer
delay.


LOGGING ON COMPUSERVE VIA TYMNET NETWORK

Suppose your Compuserve User ID is 76003,5, your password is BOO, your local
Tymnet phone number is 756-8341, and the Compuserve Tymnet code is CIS02. After
the connection is made, the network will send you a "please type your terminal
identifier" message at 300 baud. This message will be displayed normally if you
are operating at 300 bps. If you are operating at 1200 or 2400 bps you may see
nothing at all, or you may see a string of garbled characters. After receiving
the message (garbled or otherwise), you must send the "A" character alone with
no CR. You will receive a "please log in:" message. You must send the Compuserve
Tymnet code followed by CR. After the "User ID:" message appears, you must send
your user ID followed by a CR. After the "Password:" message appears, you must
send your password followed by a CR. This completes the log-in operation. The
following example shows a macro which accomplishes this with a "smart" modem at
1200 or 2400 bps.

B"1":C                   Enable buffer and clear it
T"T756-8341"             Tone dial the number
L"ECT"                   Look for "CONNECT"
Z"5"                     Pause 5 seconds
S"A"                     Send A
L"in:"                   Look for "please log in:"
S<#CIS02!>               Send code and CR (slow)
L"ID:"                   Look for "User ID:"
S<#76003,5!>             Send ID and CR (slow)
L"rd:"                   Look for "Password:"
S<#BOO!>                 Send password and CR (slow)

The 5 second pause allows the "please type your terminal identifier"
transmission before sending the "A" character. You will not see this message if
you are not operating at 300 bps. If you are logging in at 300 bps, use the
L"ier" macro command to key off the last portion of the message instead of using
the Z"5" macro command.


DIFFICULT LOG-IN

The most critical macro command is often the one which signals the host you are
trying to get online. In the previous examples, this usually involved the
sending of a control-C or two CR characters. If the result of this macro command
is not recognized, your log-in attempt will not be successful and the remainder
of the macro will be useless. If you are experiencing problems, you might try
the method illustrated in the following example:


T"558-7078"
L"CONNECT"
Z"5"
R:G"9"
L"="

This example is for logging on the SOURCE via the Telenet network. After the
connection is made, the fourth command line will send two CR characters 1/4
second apart. The R command will look for a response within one second. If
nothing is received, the G"9" command will go back to the fourth line and the
two CR characters will be sent again. This will be repeated up to 9 more times
before quitting. If a response is received, the remainder of the log-in process
(L"=") will be executed.

Additional delays before, between, and after the two CR characters should not be
used because if the response from the host occurs during these delays the R
command will not see it.


SAMPLE MACROS

The following examples are provided to show other tasks which can be done with
macros. Study each example to obtain some ideas to help you create your own
macro files.

Set Promodem Clock - This macro prompts you to enter the date and time to set
the clock in the Prometheus ProModem 1200 and 1200A. Enter the information after
the "MACRO END" message appears. The last Z"l" command allows the modem command
echo to be displayed before the "ENTER..." message.

Z"1"
S"+++"
Z"1"
S"AT@T="
Z"l"
V"ENTER MM/DD/hh/mmX"

Read Promodem Clock - The following macro retrieves the date and time from the
Prometheus ProModem 1200 or 1200A clock. The Z"3" command at the end allows the
date and time to be displayed completely before the "MACRO END" message.

Z"1"
S"+++"
Z"1"
S<AT@T!>
Z"3"

Log Into Call-Back System - For security, you must furnish some systems with
your phone number when you sign up for system privileges. Whenever you log in,
the system will direct you to hang up so it can call you back. The following
macro will handle this log-in sequence. After the initial log-in, the H and W
commands will hangup and wait for the call.

T"555-1212"
L"CONNECT"
Z"3"
S<!>
L"Enter password"
S<W6OU!>
L"Please hang up"
H
W
Z"3"
S<!>