TTMACRO for Tera Term T. Teranishi Copyright (C) 1994-1996 T. Teranishi All Rights Reserved. ------------------------------------------------------------------------------- INDEX 1. Introduction 2. Installation 3. How to run a macro file 4. Macro language "Tera Term Language (TTL)" 4.1 Types 4.2 Formats of constants 4.3 Identifiers and reserved words 4.4 Variables 4.5 Expressions and operators 4.6 Line formats 5. TTL command reference 5.1 Communication commands 5.2 Control commands 5.3 String operation commands 5.4 File operation commands 5.5 Miscellaneous commands 6. Appendixes Appendix A Error messages Appendix B About new-line characters ------------------------------------------------------------------------------- 1. Introduction TTMACRO is an interpreter of the macro language 'Tera Term Language (TTL)', which controls Tera Term and provides various functions like auto dialing, auto login, and so on. Note that TTMACRO.EXE is a 16-bit executable file. Long macro filenames are not supported. ------------------------------------------------------------------------------- 2. Installation Place TTMACRO.EXE in the directory (folder), in which Tera Term is installed. ------------------------------------------------------------------------------- 3. How to run a macro file There are two ways to run a macro file. 1) From Tera Term. To start TTMACRO, select the [Control] Macro command and then the macro file in the Open Macro dialog box. 2) From TTMACRO. The macro file can be specified as a parameter in the command line (shortcut link) of TTMACRO. For example, if you want to run the macro file "DIALUP.TTL", specify the command line (shortcut link) like: TTMACRO DIALUP.TTL You can omit the file name extension ".TTL". If you omit the file name, the Open Macro dialog box appears. It's convenient to install icons (shortcuts) for the macro files you use frequently. If you choose method 2), you can run Tera Term, after starting the TTMACRO, by using the "connect" command in the macro file. See the description of the "connect" command in section 5.1.5. While the macro is running, you can pause it, restart it, and stop it by pressing the appropriate buttons in the TTMACRO dialog box. ------------------------------------------------------------------------------- 4. Macro language "Tera Term Language (TTL)" TTL is a simple interpreted language like BASIC. To learn TTL quickly, study the sample macro files in the distribution package and the command reference in section 5. ............................................................................... 4.1 Types TTL have two kinds of data types: Integer Signed 16 bit, from -32768 to 32767. Character string A sequence containing any character except NUL. The maximum length of a string is 255. ............................................................................... 4.2 Formats of constants 1) Integer-type constants Expressed as a decimal number. Example: 123 -11 2) String-type constants There are two ways of expressing string-type constants. a) A character string quoted by ' or " (both sides must be same). Example: 'Hello, world' "I can't do that" b) A single character expressed as a "#" followed by an ASCII code (decimal number). Note: Strings can not contain NUL (ASCII code 0) characters. Example: #65 the character "A" #13 the CR character Format a) and b) can be combined in an expression. Example: 'cat readme.txt'#13#10 'abc'#13#10'def'#13#10'ghi' ............................................................................... 4.3 Identifiers and reserved words 1) Variable identifiers The first character must be an alphabetic (A-Z, a-z) or an underscore character "_". Subsequent characters can be alphabetic, underscore, or numeric (0-9). Variable identifiers are not case sensitive. The maximum length is 32. Example: VARIABLE _flag 2) Label identifiers Label identifiers consist of alphabetic, underscore, or numeric characters, and are not case sensitive. The maximum length is 32. Example: label1 100 3) Reserved words The following words are reserved: [Command] beep, bplusrecv, bplussend... (see the list in section 5.) [Operator] and, not, or, xor [System variables] inputstr, param2, param3, result, timeout ............................................................................... 4.4 Variables 1) User variables Defined by user. The type of a variable is determined when a value (integer or string) is assigned to it for first time. Once the type of the variable is determined, values of a different type can not be assigned to it. 2) System variables Variables which have a predefined type and value. Used with particular commands. Variables Type Initial value Related commands ------------------------------------------------------------------------ inputstr string '' inputbox, passwordbox param2 string *1 *1 param3 string *1 *1 result integer 0 filereadln, filesearch, filestrseek, str2int, strcompare, strlen, strscan, wait, waitrecv, yesnobox timeout integer 0 wait, waitrecv *1 Second and third command line parameter of TTMACRO. The first parameter is the macro file name. ............................................................................... 4.5 Expressions and operators Expressions consist of constants, variables, operators, and parentheses. Constants and variables must be of the integer type. The value of an expression is also an integer. The values of a relational expression (formed using relational operators) are 0, if it is true, or 1 if false. The following are operators: Category Precedence Operators -------------------------------------------------------------- unary 1, high not multiplicative 2 *, / additive 3 +, -, or, xor relational 4, low =, <>, <, >, <=, >= ............................................................................... 4.6 Line formats There are five kinds of line formats in the macro files. 1) Empty lines Lines which have no character or contain only space and tab characters. They have no effect on the execution of the macro. 2) Comment lines Lines beginning with a ';' character. No effect on the execution of the macro. Example: ; Tera Term Language 3) Command lines Lines containing a single command with parameters (the one exception is the "if" command (see 5.2.7)). Format: ... Example: connect'myhost' wait 'OK' 'ERROR' if result=2 goto error sendln 'cat' pause A*10 end 4) Assignment lines Lines which contain an assignment statement. Format: = Example: A = 33 B = C C must already have a value. VAL = I*(I+1) A=B=C the value of B=C (0 for false, 1 for true) is assigned to A. Error=0 Example: :dial :100 ------------------------------------------------------------------------------- 5. TTL command reference Command index 5.1 Communication commands 5.1.1 bplusrecv 5.1.2 bplussend 5.1.3 changedir 5.1.4 closett 5.1.5 connect 5.1.6 kmtrecv 5.1.7 kmtsend 5.1.8 logclose 5.1.9 logopen 5.1.10 logpause 5.1.11 logstart 5.1.12 logwrite 5.1.13 quickvanrecv 5.1.14 quickvansend 5.1.15 send 5.1.16 sendfile 5.1.17 sendln 5.1.18 showtt 5.1.19 wait 5.1.20 waitrecv 5.1.21 xmodemrecv 5.1.22 xmodemsend 5.1.23 zmodemrecv 5.1.24 zmodemsend 5.2 Control commands 5.2.1 call 5.2.2 end 5.2.3 execcmnd 5.2.4 exit 5.2.5 for, next 5.2.6 goto 5.2.7 if, then, elseif, else, endif 5.2.8 include 5.2.9 pause 5.2.10 return 5.2.11 while, endwhile 5.3 String operation commands 5.3.1 str2int 5.3.2 strcompare 5.3.3 strconcat 5.3.4 strcopy 5.3.5 strlen 5.3.6 strscan 5.4 File operation commands 5.4.1 fileclose 5.4.2 fileconcat 5.4.3 filecopy 5.4.4 filecreate 5.4.5 filedelete 5.4.6 fileopen 5.4.7 filereadln 5.4.8 filerename 5.4.9 filesearch 5.4.10 fileseek 5.4.11 filestrseek 5.4.12 filewrite 5.4.13 filewriteln 5.5 Miscellaneous commands 5.5.1 beep 5.5.2 exec 5.5.3 getdate 5.5.4 gettime 5.5.5 inputbox 5.5.6 int2str 5.5.7 messagebox 5.5.8 passwordbox 5.5.9 show 5.5.10 yesnobox ............................................................................... 5.1 Communication commands - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5.1.1 bplusrecv Format: bplusrecv Causes Tera Term to receive a file from the host with the B-Plus protocol. Pauses until the end of the file transfer. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5.1.2 bplussend Format: bplussend Causes Tera Term to send the file to the host with the B-Plus protocol. Pauses until the end of the file transfer. Example: bplussend 'readme.txt' - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5.1.3 changedir Format: changedir Changes the current directory of Tera Term. Example: changedir 'c:\' - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5.1.4 closett Format: closett Closes Tera Term. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5.1.5 connect Format: connect Runs Tera Term with , and links it to TTMACRO. If the link has been already established by Tera Term or another "connect" command, the "connect" command is ignored. No other communication commands should be executed before the link is established. See CMNDLINE.TXT for the format of the . Example: connect '' No command line parameter connect '/C=2' Run Tera Term with parameter '/C=2'. connect 'foohost.foo.foo.jp' CommandLine = '111.111.11.11' connect CommandLine - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5.1.6 kmtrecv Format: kmtrecv Causes Tera Term to receive a file from the host with the Kermit protocol. Pauses until the end of the file transfer. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5.1.7 kmtsend Format: kmtsend Causes Tera Term to send the file to the host with the Kermit protocol. Pauses until the end of the file transfer. Example: kmtsend 'readme.txt' - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5.1.8 logclose Format: logclose Causes Tera Term to close the log file. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5.1.9 logopen Format: logopen Causes Tera Term to start logging. Received characters are written to the file . If is zero, received new-line characters are converted (CR -> CR/CRLF) and escape sequences are stripped out. If is non-zero, received characters are written without first being converted. If is non-zero and the file already exists, received characters are appended to it. If is zero and the file already exists, the file is overwritten. Example: logopen 'myhost.log' 0 0 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5.1.10 logpause Format: logpause Causes Tera Term to pause logging. Received characters are discarded while logging is paused. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5.1.11 logstart Format: logstart Causes Tera Term to restart the logging, if paused. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5.1.12 logwrite Format: logwrite Appends a to the log file of the Tera Term. This command is valid only while Tera Term is logging. The can be written even while logging is paused. Example: logwrite 'LOG FILE'#13#10 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5.1.13 quickvanrecv Format: quickvanrecv Causes Tera Term to receive a file from the host with the Quick-VAN protocol. Pauses until the end of the file transfer. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5.1.14 quickvansend Format: quickvansend Causes Tera Term to send the file to the host with the Quick-VAN protocol. Pauses until the end of the file transfer. Example: quickvansend 'readme.txt' - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5.1.15 send Format: send .... Causes Tera Term to send characters to the host. If is a string, the string is sent to the host. If is an integer, its low-order byte (0-255) is regarded as an ASCII code of the character, and the character is sent to the host. Example: send 'ABC' send 65 66 67 Send 'ABC'. (ASCII code of the character "A" is 65.) myname='Tera Term' send 'My name is ' myname '.' - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5.1.16 sendfile Format: sendfile Causes Tera Term to send the file to the host. Pauses until the end of the file transfer. If is non-zero, the file is sent without being converted. If is zero, new-line characters are converted (CR -> CR/CRLF) and control characters except TAB, LF, and CR are not sent. Example: sendfile 'data.dat' 1 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5.1.17 sendln Format: sendln .... Causes Tera Term to send characters followed by a new-line character to the host. Format of is the same as the "send" command (5.1.15). Example: sendln Only a new-line character is sent. sendln 'abc' Password='mypassword' sendln Password - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5.1.18 showtt Format: showtt Minimizes Tera Term if is zero. Restores Tera Term if is non-zero. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5.1.19 wait Format: wait ... Pauses until one of the strings is received from the host, or until the time-out occurs. Maximum number of the strings is 10. If the system variable "timeout" is greater than zero, the time-out occurs when seconds have passed. If the "timeout" is less than or equal to zero, the time-out never occurs. The "wait" command returns the following values in the system variable "result": Value Meaning ------------------------------------------------------- 0 Time-out. No string has received. 1 has received. 2 has received. . . . . . . Example: timeout = 30 The time-out limit is 30 sec. wait 'OK' 'ERROR' Wait until 'OK' or 'ERROR' has received. if result=0 goto timeout If time-out, go to ':timeout'. if result=1 goto ok If 'OK' has received, go to ':ok'. if result=2 goto error wait #10'>' 'complete.'#13 Wait a line beginning with the ">" or a line ending with the "complete.". (ASCII code of LF is 10, and CR is 13.) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5.1.20 waitrecv Format: waitrecv Pauses until a string, which satisfies a condition, is received from the host, or until the time-out occurs. The condition is: The length of the string is , and the string contains the beginning at the th character. For example, if is "def" and is 9 and is 4, the string "abcdefghi" satisfies the condition. If such string is received, it is saved in the system variable "inputstr". If the system variable "timeout" is greater than zero, the time-out occurs when seconds have passed. If the "timeout" is less than or equal to zero, the time-out never occurs. The "waitrecv" command returns the following values in the system variable "result": Value Meaning ---------------------------------------------------------------------------- -1 A string, which contains the beginning at the th character, has been received, and saved in the "inputstr", but its length is less than because of the time-out. 0 Time-out. No string, which satisfies the condition, has been received. 1 A string, which satisfies the condition, has been received, and saved in the "inputstr". - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5.1.21 xmodemrecv Format: xmodemrecv