ttpmacro.txt

This is an excillent utility to connect your serial devices and see their output. It is a better uti

	TTPMACRO for Tera Term Pro
	T. Teranishi

	Copyright (C) 1994-1997 T. Teranishi
	All Rights Reserved.

-------------------------------------------------------------------------------
INDEX

1. Introduction

2. Usage

  2.1 How to run a macro file
  2.2 Comand line
  2.3 How to associate "TTL" files with TTPMACRO.EXE

3. Macro language "Tera Term Language (TTL)"

  3.1 Types
  3.2 Formats of constants
  3.3 Identifiers and reserved words
  3.4 Variables
  3.5 Expressions and operators
  3.6 Line formats

4. TTL command reference

  4.1 Communication commands
  4.2 Control commands
  4.3 String operation commands
  4.4 File operation commands
  4.5 Password commands
  4.6 Miscellaneous commands

5. Appendixes

  Appendix A	Error messages
  Appendix B	About new-line characters

-------------------------------------------------------------------------------
1. Introduction

TTPMACRO 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.

-------------------------------------------------------------------------------
2. Usage

...............................................................................
2.1 How to run a macro file

The executable file TTPMACRO.EXE should be placed in the directory
in which TTERMPRO.EXE exists.

There are two ways to run a macro file.

1) From Tera Term.

To start TTPMACRO, select the [Control] Macro command and then the macro file
in the Open Macro dialog box.

2) From TTPMACRO.

The macro file can be specified as a parameter of the command line (shortcut
link) of TTPMACRO. For example, if you want to run the macro file
"DIALUP.TTL", specify the command line (shortcut link) like:

	TTPMACRO 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 TTPMACRO,
by using the "connect" command in the macro file. See "4.1.5 connect".

While the macro is running, you can pause it, restart it, and stop it by
pressing the appropriate buttons in the TTPMACRO dialog box.

...............................................................................
2.2 Command line

TTPMACRO.EXE [/I] [/V] [<macro file> [<second param>] [<third param>]]

where:
	/I	Start TTPMACRO in iconized state.
	/V	Start TTPMACRO in hidden (invisible) state.
		<macro file>	Macro filename.
		<second param>	Character string stored in the system
				variable "param2".
		<third param>	Character string stored in the system
				variable "param3".

See "3.4 Variables" for the system variables "param2" and "param3".

...............................................................................
2.3 How to associate "TTL" files with TTPMACRO.EXE

To associate the file extention ".TTL" with TTPMACRO.EXE, do the
following steps.

a) In Windows 95 or Windows NT 4.0
  a-1) Execute the [View] Options command of Explorer.

  a-2) Select the "File Types" tab.

  a-3) Click the "New Type" button and specify items like the following.
	Description of type:	Tera Term macro files
	Associated extention:	TTL

  a-4) Click the "New" button and specify items like the following.
	Action:	Execute
	Application used to perform action:
		"C:\Program Files\TTERMPRO\ttpmacro.exe" "%1"
		(If Tera Term Pro is installed in C:\Program Files\TTERMPRO.)

  a-5) Close all the dialog boxes by clicking "OK" buttons.

 b) In Windows NT 3.51
  b-1) Execute the [File] Associate command of File Manager.
  
  b-2) Specify items like the following and click the "OK" button.
    Files with extention:	TTL
    Associate with:	"C:\TTERMPRO\TTPMACRO.EXE" "%1"
    			(If Tera Term Pro is installed in C:\TTERMPRO.)

-------------------------------------------------------------------------------
3. 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 4.

...............................................................................
3.1 Types

TTL have two kinds of data types:

	Integer
		Signed 32 bit, from -2147483648 to 2147483647.

	Character string
		A sequence containing any character except NUL.
		The maximum length of a string is 255.

...............................................................................
3.2 Formats of constants

1) Integer-type constants

	A integer-type constant is expressed as a decimal number.

	Example:
		123
		-11

2) String-type constants

	There are two ways of expressing a string-type constant.

	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 one expression.

	Example:
		'cat readme.txt'#13#10
		'abc'#13#10'def'#13#10'ghi'

...............................................................................
3.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]
	bplusrecv, bplussend, changedir... (see the list in section 4.)

[Operator]
	and, not, or, xor

[System variables]
	inputstr, param2, param3, result, timeout

...............................................................................
3.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 the first time. Once the type of
the variable is determined, values of a different type can not be
assigned to it.

2) System variables

Each system variable has a predefined type and value. Used with particular
commands.

Variables	Type	Initial value	Related commands
------------------------------------------------------------------------
inputstr	string		""	recvln, waitln, waitrecv,
					passwordbox, inputbox
param2		string		*1	*1
param3		string		*1	*1
result		integer		0	recvln, wait, waitevent, waitln,
					waitrecv, str2int, strcompare,
					strlen, strscan, filereadln,
					filesearch, filestrseek, yesnobox
timeout		integer		0	recvln, wait, waitevent, waitln,
					waitrecv

	*1 The second and third command line parameter of TTPMACRO. The first
	parameter is the macro file name. See "2.2 Command line".

...............................................................................
3.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 value of a relational expression
(formed using relational operators) is 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		=, <>, <, >, <=, >=

...............................................................................
3.6 Line formats

There are five kinds of line formats for 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 4.2.7)).

	Format:
		<command> <parameter> ...
	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:
		<Variable> = <Value (constant, variable, expression)>
	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<J
		Username='MYNAME'

5) Label lines

Lines which begin with a ':' character followed by a label identifier.

	Format:
		:<Label>
	Example:
		:dial
		:100

-------------------------------------------------------------------------------
4. TTL command reference

Command index

New commands added for the current version are labeled by "** new **".
Commands modified for the current version are labeled by "** changed **".

4.1 Communication commands

	4.1.1 bplusrecv
	4.1.2 bplussend
	4.1.3 changedir
	4.1.4 closett		** changed **
	4.1.5 connect		** changed **
	4.1.6 disconnect	** new **
	4.1.7 flushrecv		** new **
	4.1.8 gettitle		** new **
	4.1.9 kmtrecv
	4.1.10 kmtsend
	4.1.11 loadkeymap	** new **
	4.1.12 logclose
	4.1.13 logopen
	4.1.14 logpause
	4.1.15 logstart
	4.1.16 logwrite
	4.1.17 quickvanrecv
	4.1.18 quickvansend
	4.1.19 recvln		** new **
	4.1.20 restoresetup	** new **
	4.1.21 send
	4.1.22 sendbreak	** new **
	4.1.23 sendfile
	4.1.24 sendln
	4.1.25 setecho		** new **
	4.1.26 setsync		** new **
	4.1.27 settitle		** new **
	4.1.28 showtt		** changed **
	4.1.29 unlink		** new **
	4.1.30 wait
	4.1.31 waitevent	** new **
	4.1.32 waitln		** new **
	4.1.33 waitrecv
	4.1.34 xmodemrecv
	4.1.35 xmodemsend
	4.1.36 zmodemrecv
	4.1.37 zmodemsend

4.2 Control commands

	4.2.1 call
	4.2.2 end
	4.2.3 execcmnd
	4.2.4 exit
	4.2.5 for, next
	4.2.6 goto
	4.2.7 if, then, elseif, else, endif
	4.2.8 include
	4.2.9 pause
	4.2.10 return
	4.2.11 while, endwhile

4.3 String operation commands

	4.3.1 str2int
	4.3.2 strcompare
	4.3.3 strconcat
	4.3.4 strcopy
	4.3.5 strlen
	4.3.6 strscan

4.4 File operation commands

	4.4.1 fileclose
	4.4.2 fileconcat
	4.4.3 filecopy
	4.4.4 filecreate
	4.4.5 filedelete
	4.4.6 fileopen
	4.4.7 filereadln
	4.4.8 filerename
	4.4.9 filesearch
	4.4.10 fileseek
	4.4.11 filestrseek
	4.4.12 filewrite
	4.4.13 filewriteln

4.5 Password commands

	4.5.1 delpassword	** new **
	4.5.2 getpassword	** new **
	4.5.3 passwordbox

4.6 Miscellaneous commands

	4.6.1 beep
	4.6.2 closesbox		** new **
	4.6.3 exec
	4.6.4 getdate
	4.6.5 getenv		** new **
	4.6.6 gettime
	4.6.7 inputbox
	4.6.8 int2str
	4.6.9 messagebox
	4.6.10 setdate		** new **
	4.6.11 setdlgpos	** new **
	4.6.12 setenv		** new **
	4.6.13 settime		** new **
	4.6.14 show		** changed **
	4.6.15 statusbox	** new **
	4.6.16 yesnobox

...............................................................................
4.1 Communication commands

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4.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.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4.1.2 bplussend

Format:
	bplussend <filename>

Causes Tera Term to send the file <filename> to the host with the B-Plus
protocol. Pauses until the end of the file transfer.

Example:
	bplussend 'readme.txt'

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4.1.3 changedir

Format:
	changedir <path>

Changes the current directory of Tera Term.

Example:
	changedir 'c:\'

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4.1.4 closett		** changed **

Format:
	closett

Closes Tera Term and enters the unlinked state.
In the unlinked state, the "connect" command can open a new
Tera Term window and link TTPMACRO to it.

See also:
	"4.1.5 connect"
	"4.1.6 disconnect"
	"4.1.29 unlink"

Example:
	closett
	connect 'host'

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4.1.5 connect		** changed **