%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                           %
% UniTerm Users Guide, Copyright 1986, 1987 Simon Poole     %
%                                                           %
% This file may not be changed without permission, all      %
% rights reserved.                                          %
%                                                           %
% Simon Poole                                               %
% Bahnhofstr. 51 b                                          %
% CH-5430 Wettingen                                         %
% Switzerland                                               %
%                                                           %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Simple Macro Processor}\index{Macro Processor}

  The macro commands  can be in the strings assigned to the  function 
keys  or in a file,  the command initiator is {\tt \%} for function keys
(this is not needed in a macro file). 
 
A command line is a maximum of 80 characters long. The 
macro-processor  works  in two  modi:  
\begin{description}
\explain{Function-key  mode}{all  characters 
between commands are sent to the serial port}
\explain{Macro file mode}{everything between commands except white-space
is a syntax error, additional commands are available in this mode.} 
\end{description}

\section{Control statements}

Only one construct is available in function key mode:

\statement{if}{int}{execute the rest of the line if {\em int} is not equal 0}


\section{Arguments}

Arguments are enclosed in parentheses and separated by commas, they can 
be of the following types:

\begin{description}
\explain{String constant}{character string enclosed in single quotes, max. 80 
               characters.}
\explain{String variable}{10 user setable string variables are available: \$1 to \$10,
                          additionaly 5 predifined strings can be used.}
\explain{Integer constant}{positive integer in the range 0..32767.}
\explain{Integer variable}{10 user setable integer variables are available: @1 to @10,
                           range: -32768 to +32767.}
\explain{Function}{any of the built-in functions can be used as an argument}
\end{description}


\section{Functions}

All  commands  only have to be specified to the  point  they  are 
unique (for most commands this means one character). Case is not
significant.

\mac{ADD}{int1,int2}{
Arithmetic sum.}{{\em int1} + {\em int2}}

\mac{AND}{int1,int2}{
Logical and.}{{\em int1} and {\em int2}}

\mac{ASSERT}{}{Assert DTR.}{0}

\mac{BREAK}{len,drop-dtr}{
Send  Break  for {\em len}  (integer)  mSec, drop  DTR  according  to  the  {\em drop-dtr} 
(integer) value.}{0}

\mac{CONCAT}{str1,str2}{
Concatenate  {\em str1} (string) and  {\em str2} (string)  and  put  the  
result  in  the variable {\tt \$TEMP}.}{0}

\mac{COPY}{nr,str}{
Copy {\em str} (string) to string variable number {\em nr} (integer).}{0}  

\mac{COMPARE}{str1,str2}{
Compare  {\em str1} (string) to {\em str2} (string).}
{1 if {\em str1} equals {\em str2} else 0.}

\mac{DROP}{}{Drop DTR.}{0}

\mac{DIAL}{num}{Dial number {\em num} (1 to 10).}
{1 if sucessful, 0 otherwise.}

\mac{ECHO}{message}{Echo {\em message} (string).}{0}

\mac{FILESELECTOR}{path,filename,prompt}{
Show  a  fileselector with  path  {\em path} (string),  filename {\em filename}  (string) 
and a prompt of {\em prompt}  (string).  The new values for path and filename are  in 
the variables {\tt \$PATH}\ and  {\tt \$FILENAME}.}
{1 if \button{OK}\  is selected, else 0.}

\mac{GET}{in-string,time}{
Wait for {\em in-string} (string),  with timeout {\em time}   (integer)  sec} 
{1 if sucsessful.}

\mac{HANGUP}{}{Hangup the modem.}{0}

\mac{HISTORY}{switch}{Turn history recording on if {\em switch} is 1
(does not reset the buffer).}{0}

\mac{INLINE}{mode}{
Reads a line from the keyboard (until \key{Return}\ is pressed or a maximum
of 80 characters are read, \keytwo{Control}{C}\ aborts), if {\em mode} (integer) is 
 1 (true) the characters are echoed. \key{Delete}\ and \key{Backspace}
cause a destructive backspace. The line read is copied into {\tt \$TEMP}.}{0} 


\mac{INPUT}{prompt}{
Prompt for a line of input, result is in {\tt \$TEMP},   
{\em prompt}  is  a   string.}
{1 if \button{OK}\  is selected.}


\longmac{KERMIT}{mode,8-bit-mode,filespec}{
Start   Kermit  filetransfer  with   the following parameters:}{
{\em mode} (string):\>{\tt SEND} : send file(s) \\
                    \>{\tt REC}  : receive file(s) \\
                    \>{\tt GET}  : receive file(s) from server \\
{\em 8-bit-mode} (integer):\>{\tt 0} : 7 bit ASCII text \\
                           \>{\tt 1}  : 8 bit binary \\
{\em filespec} (string): \>file specification  with wildcards}
{0}

\mac{LOADSETUP}{name}{   
Load  the  setup file with  name  {\em name} (string).}{0}

\mac{LOADTEL}{filename}{Load a dialer setup file.}{0}
  
\mac{MESSAGE}{msg}{
Displays {\em msg} (string) on the statusline. If {\em msg} is empty the
normal statusline is restored.}{0}

\mac{MACRO}{name}{Execute  the  macro  with  filename  {\em name} 
(string) from disk,  default path is the current directory}
{the value of the exit command, or 
\begin{quote}
   -3 : syntax error (line in \$TEMP) \\
   -2 : not enough stack (nested more than one level) \\
   -1 : macro buffer full (more than 4kB).
\end{quote}
}

\mac{OR}{int1,int2}{
Logical or.}{{\em int1} or {\em int2}}

\mac{PATH}{path}{Change default path to {\em path} (string).}{0}

\longmac{POPUP}{entry,command,name}{Redefines an entry in the popup menu:}{
{\em entry} : \>1..20 \\
{\em command} : \>see list \\
{\em name} : \> string that will be displayed}{0}

\mac{RUN}{name,commandline}{
Execute program {\em name} (string) with {\em commandline} commandline (string). 
If  its a {\tt .TTP} program you'll be  asked for parameters.}
{Return code of program.}

\mac{REASSIGN}{alt-key,command}{
Assigns  integer  value {\em command}  to  the alternate key value {\em alt-key}.}
{0}

\mac{RS232CONF}{conf-str}{
Sets the serial port to the values specified in the string {\em conf-str},
consult the section on the dialer setup for information on the format
of the string}{0}

\mac{SEND}{out-string}{Send {\em out-string} (string).}{0}

\mac{SET}{nr,int}{
Set integer variable number {\em nr} (integer) to {\em int} (integer)}{0}  

\mac{SUSPEND}{}{
Displays  ``Press any key...'' on the statusline and waits for a keypress.}
{0}

\mac{WAIT}{time}{Wait for {\em time} (integer) mSec$\times$100.}{0}

\mac{UNICOMMAND}{command}{
Execute   one  of   UniTerm's   internal commands, see list.}{0}

\longmac{XMODEM}{mode,file}{
Start XModem with:}{
{\em mode} (string):\>{\tt SEND} : send file \\
                    \>{\tt REC}  : receive file \\ 
{\em file} (string): \>file to send/receive}
{0}

\longmac{YMODEM}{mode,filespec}{
Start YModem with:}{
{\em mode} (string):\>{\tt SEND} : send file(s) \\
                    \>{\tt REC}  : receive file(s) \\
{\em filespec} (string): \>file specification  with wildcards}
{0}

                                              
\section{Prefix Operators}
\begin{tabbing}
MMMMMMM\=MMMM\=\kill
  \>{\tt - } \>negate integer value \\
  \>{\tt ! } \>logical not \\
  \>{\tt " } \>return integer as string \\
  \>{\tt . } \>return string as integer \\
\end{tabbing}

Bug: {\tt .} and {\tt "} don't know about negative integers!


\section{String Constants}

 String constants are a maximum of 80 characters long and are enclosed in 
single quotes. Special ASCII values can be entered with the escape character
\Bslash ; every character after  \Bslash\ equals itself, except:
\begin{tabbing}
MMMMMMM\=MMMM\=\kill
     \> r    \>: is \ASCII{CR} \\
     \> n    \>: is \ASCII{LF} \\
     \> 0xx  \>: \Bslash 0xx is the octal ASCII value 0xx \\
\end{tabbing}

\section{Predefined String Variables}

\begin{description}
\explainnoi{{\tt \$PATH}}{\index{Variable PATH}  contains the  last  file
                             selector  path,  is initialized  to 
                             the home directory of UniTerm.}
\explainnoi{{\tt \$FILENAME}}{\index{Variable FILENAME}  contains the  last  file
                             selector filename,  is  initialized 
                             to '\,'.}
\explainnoi{{\tt \$CURRENT}}{\index{Variable CURRENT} contains the current  GEM
                             DOS path.}
\explainnoi{{\tt \$TEMP}}{\index{Variable TEMP} tempory string for use  in 
                             the macro processor.}  
\explainnoi{{\tt \$VAR}}{\index{Variable VAR} holds the address of 
                             \UniTerm's parameter block\footnotemark\ for passing to 
                             other programs.} 
\end{description}
\footnotetext{Please consult the separate documentation on this subject.}

\section{Additional Features in Macro File Mode}

\subsection{Labels}

Twenty local labels (per macro file) can be used:   {\tt :1} to {\tt :20}. 
A label must be the first and only word on a line!

\subsection{Comments}

A line starting with \#\ is ignored on input.

\subsection{Additional Statements}

These statements can only be used in macro file mode, and will cause
an error if used from a function key.


\statement{jump}{nr}{goto label number {\em nr}}

\statement{exit}{int}{stop processing and return with value {\em int}}

\statement{call}{nr}{execute subroutine at label {\em nr} (subroutines can't be 
                  nested!)}

\statement{return}{}{return from subroutine}


\section{Example}

\begin{verbatim}
#####################################
# Test Macro for UniTerm V2.0c 002  #
# Copyright 1988 Simon Poole        #
#                                   #
#####################################
# turn history recording on
history(1)
call(20)
echo('\007\r\nSample UniTerm macro file')
echo('\r\n-------------------------\007') 
#
# Reset the modem
#
copy(1,'ATZ')
copy(2,'OK')
set(2,5)
call(4)
#
if(@1) echo('\r\nReset\r\n') jump(2)
#
echo('\r\nToo many retries\r\n') exit(-1)
#
# Dial the number and wait for CONNECT
# (in real life you would use the dial() function)
#
:2
# Get number from user
if(!input('Enter number (2512002)')) exit(0)
# if the string is empty use the default
if(compare($T,'')) concat('2512002','')
# Hayes want a ATD 
concat('ATD',$T)
# dial............
copy(1,$T)
copy(2,'CONNECT')
set(2,30)
call(4)
if(!@1) echo('\r\nFailed\r\n')exit(1)
#
# Login
#
# this is for our LocalNet 20 system
:6
send('\r')
if(!get('#',2)) break(100,FALSE) if(!get('#',2)) send('\001\001')
send('echo off\r')
if(!get('#',2)) echo('\r\nSomething is wrong!') hangup() exit(-1)
# call the system
send('call e780\r')
# should have a counter here, but you can always stop with ^C
if(!get('COMPLETED',3)) send('done\r') jump(6)
if(!get('ogin',3)) send('done\r') jump(6)
send('poole\r')
#
# should send my password here
#
# Finished!
exit(0)
#########################################################
#                                                       #
#  Send a string to a Hayes compatible modem            #
#                                                       #
#########################################################
#
# @1 number of retries
# @2 timeout
# $1 string to send (telephone number...)
# $2 string to wait for (CONNECT)
#
:4
set(1,3)
:5
   echo('\r\nTry: ')
   echo("add(4,-@1))
   set(1,add(@1,-1))
   wait(10)
# send attn string
   echo('\r\nSending +++')
   send('+++')
# we might get a OK here...
   get('OK',2)
   echo('\r\nSending ')
   echo($1) 
   send($1)
   send('\r')
if(and(!get($2,@2),@1)) jump(5)
return()
########################################################
#                                                      #
# Home cursor and clear screen                         #
#                                                      #
########################################################
:20
echo('\033[f\033[2J')
return()
########################################################
\end{verbatim}



A  very  useful  aspect  of  the macro processor, is that you can 
assign a string like {\tt {\%}R('TEMPUS.PRG','\,')}\ to a function key and run 
your favourite editor just by pressing one key\footnote{Remember that 
enough system memory has to be reserved for programs to run in.}.


\section{\UniTerm\ Internal Function Numbers}

\begin{tabbing}
12341\=23456789011111111111 \= \kill
\>  ResetTek = \>1 \\
\>  VDIOutput = \>2 \\
\>  PrintTextScreen = \>3 \\
\>  TekMode = \>4 \\
\>  TextMode = \>5 \\
\>  Reset = \>6 \\
\>  AutoPrint = \>7 \\
\>  Zoom = \>8 \\
\>  132ColumnToggle = \>9 \\
\>  ScrollLock = \>10 \\
\>  49LineToggle = \>11 \\
\>  SendAnswerBack = \>12 \\
\>  ShortBreak = \>13 \\
\>  DropDTR = \>14 \\
\>  LongBreak = \>15 \\
\>  SaveHistory = \>16 \\
\>  ControlHistory = \>17 \\
\>  Switch = \>18 \\
\>  ControlCapture = \>19 \\
\>  PlayBack = \>20 \\
\>  SendFile = \>21 \\
\>  DegasSave = \>22 \\
\>  ViewHistory = \>23 \\
\>  Hangup = \>24 \\
\>  Dial1 = \>25 \\
\>  Dial2 = \>26 \\
\>  Dial3 = \>27 \\
\>  Dial4 = \>28 \\
\>  Dial5 = \>29 \\
\>  Dial6 = \>30 \\
\>  Dial7 = \>31 \\
\>  Dial8 = \>32 \\
\>  Dial9 = \>33 \\
\>  Dial10 = \>34 \\
\>  SetPath = \>35 \\
\>  DelFile = \>36 \\
\>  DiskSpace = \>37 \\
\>  F1 = \>38 \\
\>  F2 = \>39 \\
\>  F3 = \>40 \\
\>  F4 = \>41 \\
\>  F5 = \>42 \\
\>  F6 = \>43 \\
\>  F7 = \>44 \\
\>  F8 = \>45 \\
\>  F9 = \>46 \\
\>  F10 = \>47 \\
\>  SF1 = \>48 \\
\>  SF2 = \>49 \\
\>  SF3 = \>50 \\
\>  SF4 = \>51 \\
\>  SF5 = \>52 \\
\>  SF6 = \>53 \\
\>  SF7 = \>54 \\
\>  SF8 = \>55 \\
\>  SF9 = \>56 \\
\>  SF10 = \>57 \\
\>  Utilities = \>58 \\
\>  ToggleMeta = \>59 \\
\>  Help = \>60 \\
\>  InsertClip = \>61 \\
\>  SaveClip = \>62 \\
\>  ViewHistEOL = \>63 \\
\>  ClearTextScreen = \> 64 \\
\>  Exit =            \> 65 \\
\>  ExitImmediatly = \> 66 \\
\>  StartSLE = \>67 \\
\>  CF1 = \>68 \\
\>  CF2 = \>69 \\
\>  CF3 = \>70 \\
\>  CF4 = \>71 \\
\>  CF5 = \>72 \\
\>  CF6 = \>73 \\
\>  CF7 = \>74 \\
\>  CF8 = \>75 \\
\>  CF9 = \>76 \\
\>  CF10 = \>77 \\
\end{tabbing}



