ttpmacro.txt

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

Deletes the file specified by <filename>.

Example:
	filedelete 'temp.log'

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4.4.6 fileopen

Format:
	fileopen <file handle> <file name> <append flag>

Opens a file specified by <file name>.

If the file does not exist, it is created and then opened. If the file is
successfully opened, the file handle is returned in the integer variable
<file handle>. Otherwise, <file handle> is set to -1.

If <append flag> is zero, the file pointer is set to the beginning of the
file. If <append flag> is non-zero, the file pointer is set to the end of
the file.

Example:
	fileopen fhandle 'data.dat' 0

	fileopen fhandle 'data.dat' 1

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4.4.7 filereadln

Format:
	filereadln <file handle> <strvar>

Reads a line from the file specified by <file handle>.
The line is written into the string variable <strvar>. The file pointer
is moved to the beginning of the next line. If the file pointer reaches the
end of the file while reading the line, the system variable "result" is set
to 1. Otherwise, "result" is set to zero.

Example:
	fileopen fhandle 'test.txt' 0	Open a file.
	:loop
	filereadln fhandle line		Read a line from the file.
	if result goto fclose
	messagebox line 'test.txt'	Display the line.
	goto loop			Repeat until the end of the file.
	:fclose
	fileclose fhandle		Close the file.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4.4.8 filerename

Format:
	filerename <file1> <file2>

Renames <file1> to <file2>.
<file1> and <file2> must not be same.

Example:
	filerename 'test.dat' test2.dat'

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4.4.9 filesearch

Format:
	filesearch <filename>

Searches for the file specified by <filename>.
If it is found, the system variable "result" is set to 1. Otherwise,
"result" is set to zero.

Example:
	filesearch 'readme.txt'
	if result=0 messagebox 'File not found.' 'error'

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4.4.10 fileseek

Format:
	fileseek <file handle> <offset> <origin>

Moves the pointer for the file specified by <file handle>.
With this command, the file pointer is moved <offset> bytes from:

	the beginning of the file, if <origin> is 0.

	the current position, if <origin> is 1.

	the end of the file, if <offset> is 2.

Example:
	fileseek fhandle 0 0	Move to the beginning of the file.

	fileseek fhandle 10 1	Move 10 bytes from the current position.

	fileseek fhandle 0 2	Move to the end of the file.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4.4.11 filestrseek

Format:
	filestrseek <file handle> <string>

Searches for <string> in the file specified by <file handle>.
The search is started from the current position of the file pointer.

If <string> is found, the file pointer is moved to the next character of
the string, and the system variable "result" is set to 1. If <string> is
not found, the file pointer is not moved, and "result" is set to zero.

Example:
	fileopen fhandle 'teraterm.log' 0	Search for the string 'abc'
	filestrseek fhandle 'abc'		in the file 'teraterm.log'.
	if result=0 goto not_found
	filereadln fhandle str			Read characters from the next
						of the 'abc' to the end of the
						line.
	:not_found
	fileclose fhandle

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4.4.12 filewrite

Format:
	filewrite <file handle> <string>

Writes <string> to the file specified by <file handle>.

Example:
	filewrite fhandle '---------cut here---------'#13#10

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4.4.13 filewriteln

Format:
	filewriteln <file handle> <string>

Writes <string> and the new-line characters (CR+LF) to the file specified
by <file handle>.

Example:
	filewriteln fhandle '---------cut here---------'

...............................................................................
4.5 Password commands

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4.5.1 delpassword		** new **

Format:
	delpassword <filename> <password name>

Deletes a password specified by <password name> in the password
file <filename>. If <password name> is a blank string,
all passwords in the file are deleted.

See "4.5.2 getpassword" for the password file.

Example:
	delpassword 'password.dat' 'mypassword'

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4.5.2 getpassword		** new **

Format:
	getpassword <filename> <password name> <strvar>

Retrieves an encrypted password identified by <password name> from
the password file <filename>. Decrypts the password and stores it
into the string variable <strvar>.

If the specified file does not exist, it is newly created.
If the specified password is not stored in the file,
the password dialog box appears and the entered password
is sotred in <strvar>. At the same time, the new password
is encrypted and written in the file with the identifier
<password name>.

A password file can contain multiple passwords. Each of them
is identified by the password identifier.

Example:
	getpassword 'password.dat' 'mypassword' password
	connect 'myhost'
	wait 'login:'
	sendln 'myname'
	wait 'password:'
	sendln password

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4.5.3 passwordbox

Format:
	passwordbox <message> <title>

Displays a dialog box prompting the user to input a password.

The <message> is displayed in the dialog box. The <title> is displayed as the
dialog box title. The password typed by the user is not displayed as is.
Instead, asterisks are displayed. The password is returned in the system
variable "inputstr".

Example:
	passwordbox 'Enter password' 'Login'

...............................................................................
4.6 Miscellaneous commands

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4.6.1 beep

Format:
	beep

Makes a beep sound.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4.6.2 closesbox		** new **

Format:
	closesbox

Closes the status dialog box opend by the "statusbox" command.

Example:
	See "4.6.15 statusbox".
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4.6.3 exec

Format:
	exec <command line>

Runs an application specified by <command line>.

Format:
	exec 'notepad readme.txt'	Run "Notepad".

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4.6.4 getdate

Format:
	getdate <strvar>

Returns the current date in the string variable <strvar>, with the format
"YYYY-MM-DD".

Example:
	getdate datestr

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4.6.5 getenv		** new **

Format:
	getenv <envname> <strvar>

Retrieves the value of an environment variable specified丂by <envname> and
stores it in the string variable <strvar>.

Example:
	getenv 'TEMP' env

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4.6.6 gettime

Format:
	gettime <strvar>

Returns the current time in the string variable <strvar>, with the format
"HH:MM:SS".

Example:
	gettime timestr

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4.6.7 inputbox

Format:
	inputbox <message> <title>

Displays a dialog box prompting user to input a string.

The <message> is displayed in the dialog box. The <title> is displayed as the
dialog box title. The string entered by the user is returned in the system
variable "inputstr".

Example:
	inputbox 'Password:' 'Login'
	sendln inputstr

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4.6.8 int2str

Format:
	int2str <strvar> <integer value>

Converts <integer value> to its string expression, and returns it in the
string variable <strvar>.

Example:
	int2str valstr 123		The string "123" is assigned to
					the variable "valstr".

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4.6.9 messagebox

Format:
	messagebox <message> <title>

Displays a dialog box with <message> and <title>.

Example:
	messagebox ErrorMessage 'Error'

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4.6.10 setdate		** new **

Format:
	setdate <date>

Sets the system date to <date>. The format of <date> should be "YYYY-MM-DD".

Example:
	setdate '1997-06-30'

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4.6.11 setdlgpos		** new **

Format:
	setdlgpos <x> <y>

Changes the initial position for dialog boxes opend by the "inputbox",
"messagebox", "passwordbox" and "statusbox" commands. If the status dialog
box is displayed, the "setdlgpos" command also moves the dialog box.

<x> and <y> specify the position (x,y) in the screen coordinate.
The origin (0,0) is upper left corner of the screen.

Example:
	setdlgpos 0 0
	messagebox 'Message' 'Title'	message box at the upper left corner

	setdlgpos 0 200			open the status box
	statusbox 'Message' 'Title'
	for i 0 200
	  setdlgpos i 200		moves the status box
	next

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4.6.12 setenv		** new **

Format:
	setenv <env name> <env value>

Sets the environment variable specified by <env name> to the character
string <env value>.

Example:
	setenv 'WORK' 'c:\work'

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4.6.13 settime		** new **

Format:
	settime <time>

Sets the system time to <time>. The format of <time> should be "HH:MM:SS".

Example:
	settime '01:05:00'

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4.6.14 show		** changed **

Format:
	show <show flag>

Minimizes TTPMACRO, if <show flag> is zero.
Restores TTPMACRO, if <show flag> is greater than zero.
Hides TTPMACRO, if <show flag> is less than zero.

Example:
	show 0		Minimize TTPMACRO.
	show 1		Restore TTPMACRO.
	show -1		Hide TTPMACRO.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4.6.15 statusbox		** new **

Format:
	statusbox <message> <title>

Displays the status dialog box if it has not been displayed yet.
Changes the message to <message> and title to <title>.

The "setdlgpos" command (see 4.6.11) changes the position of status
dialog box.
The "closesbox" (see 4.6.2) command closes the status dialog box.

Example:
	setdlgpos 200 200			set the initial position
	statusbox 'Message' 'Title'		display the status dialog box
	pause 3	
	setdlgpos 0 0				move the dialog box
	pause 3
	closesbox				close the dialog box

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4.6.16 yesnobox

Format:
	yesnobox <message> <title>

Displays a dialog box with the <message>, <title>, "Yes" button and
"No" button.

If the user clicks on the "Yes" button, the system variable "result" is set
to 1.  If the user clicks on the "No" button, "result" is set to zero.

Example:
	yesnobox 'Try agian?' 'Tera Term'
	if result goto retry
	end

-------------------------------------------------------------------------------
 6. Appendixes

...............................................................................
Appendix A	Error messages

 Error message				Meaning
 ----------------------------------------------------------------------------
 Can't call sub.		Cannot call the subroutine, the subroutine
				is located in a different file.

 Can't link macro.		Failure to establish the link between
				TTPMACRO and Tera Term.

 Can't open file.		The include file does not exist, or there are
				too many nested include files.

 ")" expected.			A closing parenthesis does not exist where
				it should.

 Link macro first.		The command cannot be executed before the
				link between TTPMACRO and Tera Term is
				established.

 Divide by zero.		The expression attempts to divide by zero.

 Invalid control.		Invalid use of "else", "elseif" or "endif".

 Label already defined.		Duplicate use of the label.

 Label required.		The label is not defined.

 Stack overflow.		There are too many nested subroutines,
				"for-next" loops or "while-endwhile" loops.

 Syntax error.			The format of the statement is invalid.

 Too many labels.		TTPMACRO can not handle more than 256 labels.

 Too many variables.		TTPMACRO cannot handle more than 128 integer
				variables and 128 string variables.

 Type mismatch.			The type of the constant or variable is
				invalid.

 Variable not initialized.	The variable must be initialized before it is
				referenced.

...............................................................................
Appendix B	About new-line characters

New-line characters (CR or CR+LF) received from the host are converted to
CR+LF pairs by Tera Term, and then Tera Term sends them to TTPMACRO.

You should use the pair (CR+LF) as a new-line character to send to Tera Term.

ASCII code 13 (decimal) is for CR, and 10 is for LF.

Example:
  send 'abc'#13#10		Same as the statement "sendln 'abc'". The
				actual new-line character to be sent to the
				host is determined by Tera Term.

  wait #10'abc' 'def'#13	Waits for a line beginning with "abc",
				or a line ending with 'def'.

  logwrite 'abc'#13#10		Writes line "abc" to the log file.