AccuTerm Programming. AccuSoft 7

PDF

مستند

204 AccuTerm 7 Help

3 AccuTerm 7 Reference

3.1 AccuTerm Programming

AccuTerm 7 supports many "private" commands which may be sent by host application programs.

These commands allow for remote control of file transfer and data capture, executing DOS or Windows programs, enabling the mouse, displaying images, playing sounds, executing VBA scripts, and programming the function and keypad keys. These commands are valid in all terminal types.

External Program Execution

ESC STX

command

Executes the Windows command line

command

, then returns to AccuTerm emulation mode immediately. Command is executed concurrently with the terminal session.

Command

may also be the file name of a document that is registered with Windows. If command is a document file name, the program associated with the specified file is used to open the file.

For example, if the file name ends in ".doc", Microsoft Word is used to open the specified document file. You can also use this function to open a URL in the default browser (be sure to include the http:// prefix in the URL):

EQU ESC TO CHAR(27), STX TO CHAR(2), CR TO CHAR(13)

CMD = "calc.exe"

PRINT ESC:STX:'<':CMD:CR:

ESC STX

command

Executes the Windows command line

command

and suspends the terminal session until the command completes. See above for details.

Note: when using this function, you often need the host program to wait until the command terminates. If you require this functionality, then you should send the

ESC STX

command immediately following the

ESC STX

command, and then wait for input. AccuTerm will not process the

ESC STX

until the command terminates. After the command completes,

ESC

STX

transmits AccuTerm's licensing information back to the host, thus the input is satisfied and the host program can continue execution:

EQU ESC TO CHAR(27), STX TO CHAR(2), CR TO CHAR(13)

CMD = "notepad.exe"

PRINT ESC:STX:'>':CMD:CR:

PRINT ESC:STX:'I':

INPUT JUNK

Mouse Functions

ESC STX

Disable mouse input; turns off mouse cursor.

ESC STX

Enable mouse input; turns on mouse cursor. Transmits mouse location whenever a mouse button is pressed. Both single and double clicks are supported. A single-click will always precede a double-click. Note: this command is ignored unless host mouse reporting is

AccuTerm 7 Reference 205

enabled in the Mouse Settings.

The format of the mouse click report depends on whether the current terminal type uses

ASCII or ANSI-style function keys. The report is designed to look like a function key, followed by the click position. For terminal types with ASCII-style function keys, the report is:

STX b

ccc.rr

where

indicates which mouse button was pressed (

=left click,

=right click,

= center click,

=left double click,

=right double click,

=center double click),

ccc

is the three digit column of the mouse cursor and

is the two digit row of the mouse cursor (both in decimal,

000.00

is the upper left corner).

For terminal types with ANSI-style function keys, the report is:

ESC

[

n ~

ESC

[

;

c R

where

indicates which mouse button was pressed (101=left click, 102=right click, 103

=center click, 111=left double click, 112=right double click, 113=center double click),

is the row of the mouse cursor and

is the column of the mouse cursor (both in decimal, where 1;1 is the upper left corner). If the terminal is using 8-bit control codes, AccuTerm sends

CSI

instead of

ESC

[

. in this report.

Note: if the mouse is click ed on an image that is displayed on the terminal screen, the location in the above reports is replaced by the image file name.

ESC STX

SystemBuilder compatibility mode; turns on mouse cursor. Transmits mouse location whenever a mouse button is pressed. Note: this command is ignored unless host mouse

reporting is enabled in the Mouse Settings.

STX

CR b

;

c ;

r CR b

indicates which mouse button was pressed (1 = left, 2 = right, 4 = center),

is the column of the mouse cursor and

is the row of the mouse cursor (both in decimal, 0;0 is the upper left corner).

ESC STX

Resets the mouse pattern table used for mouse pattern matching.

ESC STX

button

pattern

click

dblclk

Adds an entry to the mouse pattern table used for mouse pattern matching. See Mouse

Support for more information about using mouse pattern matching.

Data Transfer

ESC STX

p o m x ;

path

Download file from host to PC. Protocol

may be

(ASCII),

(Kermit),

(Xmodem),

(

Ymodem) or

(Zmodem); overwrite

may be

(overwrite) or

(no overwrite) or, if protocol is

, overwrite may be

; transfer mode

may be

(text) or

(binary); translate mode

206 AccuTerm 7 Help

ESC STX

p m x ; path

Upload file from PC to host. Protocol

may be

(ASCII),

(Kermit),

(Xmodem),

(Ymodem) or

(Zmodem); transfer mode

may be

(text) or

(binary); translate mode

may be

to enable character set translation or

to disable translation.

Path

is the drive, directory and file name of the file to send to the host. Wildcard characters (

) are valid when using Kermit, Ymodem or Zmodem protocols.

Note: the upload command is typically used by applications which implement the host side of the file transfer protocol to automatically start the corresponding client protocol. This command only affects the client (AccuTerm) side of the process.

ESC STX

may be

to enable character set translation or

to disable translation.

Path

is the drive, directory and file name of the file being received. When using Kermit, Ymodem or Zmodem protocols, only drive and directory need be specified, as the file name is included in the transfer protocol; however if the file name is specified here, it overrides the file name included in the transfer protocol.

Note: the download command is typically used by applications which implement the host side of the file transfer protocol to automatically start the corresponding client protocol. This command only affects the client (AccuTerm) side of the process.

Returns status of last file transfer. The format of the status message is:

Status:

s files f bytes b

where

is the number of files transferred,

is the number of bytes transferred, and

is the transfer status:

= transfer successful

= unable to open file

= transfer aborted by operator

= file already exists

= terminated due to timeout

= terminated due to corrupted data

= invalid packet type

= terminated by remote program

= 8 data bits required for protocol

= software flow control not allowed for protocol

= destination file is write protected

ESC STX

p t ;

path

Begin capture. Mode

may be

(overwrite),

(append),

(new file only) or

(clipboard).

Source

may be

to capture printed data or null to capture received data.

may be

(text) to capture text only (filters out control characters) or null for no filtering.

Path

is the drive, directory and file name where the captured data is to be stored. All characters received (or printed) are stored in the file (or clipboard) until capturing is disabled (via local or remote command). Note: when capturing to the clipboard,

path

is ignored.

ESC STX

C X

End capture. The file containing the captured data is closed.

AccuTerm 7 Reference 207

ESC STX

path

Send clipboard or file to host. If

path

is null, the contents of the clipboard are sent, otherwise the specified file is sent. Each line is terminated as specified in the ASCII file transfer settings. A

SUB

(

CTRL+ Z

) is sent after the last line.

Status and Control

ESC STX

Returns AccuTerm release, serial number, type and licensee information. Message format is:

ACCUTERM/WIN

rel serial type licensee...

where

rel

is the AccuTerm release number,

serial

is the program serial number,

type

SINGLE

SITE

CORP

DEALER

DEMO

, and

licensee

is the name under which the program has been licensed.

ESC STX

Returns a string indicating the platform, product type, license type, capabilities and automation services. Message format is:

platform * product * license * capabilities * services

where

platform

(Win32);

product

= AccuTerm (standard version),

= AccuTerm

Internet Edition,

= AccuTerm Emulator ActiveX Control,

= AccuTerm Lite; release number,

serial

is the program serial number,

license

= single user,

= site,

= enterprise,

= developer,

= internet,

= component,

= evaluation;

capabilities

is a string of letters indicating the various capabilities where:

A = ASCII protocol supported

B = Border effects (visual styles) enabled

C = Capture supported

D = Download supported

E = Execute command supported

F = On-the-fly character set conversion supported during file transfers

G = GUI supported

H = Server mode supported

I = Image display supported

J = Screen save & restore supported

K = Kermit protocol supported

L = Background image supported

O = Object Bridge supported

P = Packetized messages supported

Q = Message integrity checks supported

R = Reliable connection

S = Scripting supported

T = File transfer error info supported

U = Upload supported

V = Host capabilities command supported

X = File conversion supported

Y = Printer control & status query supported

208 AccuTerm 7 Help

services

is a string of letters indicating which automation services are available (

= Object

Bridge,

= file converter,

= GUI).

ESC STX

host-capabilities

buffer-size

Informs AccuTerm of any special host program capabilities.

host-capabilities

is a string of letters indicating various host features:

D = host programs use tag notation for system delimiters

C = host supports message checksums

M = host supports message length check

buffer-size

is optional, and specifies the maximum packet size that the client can send to host.

ESC STX

% 0

Returns the program directory, followed by

CR.

This is normally the directory where

AccuTerm is installed, except in the case of AccuTerm Internet Edition, the directory returned is the one containing the Internet Explorer exe file.

ESC STX

% 1

Returns the current directory (usually from the shortcut "start in" field), followed by

CR.

ESC STX

% 2

Returns the directory containing AccuTerm's atwin71.ini file, followed by

CR.

ESC STX

% 3

Returns the directory containing AccuTerm's emulator DLL, followed by

CR.

ESC STX

Terminates the current AccuTerm session. If only one session exists, then AccuTerm is terminated also.

ESC STX

Saves the current session settings to disk. If no session file name exists, then one will be prompted for.

ESC STX

Sets the

CapsLock

key state to "On"

ESC STX

Sets the

CapsLock

key state to "Off"

Terminal Screen

ESC STX

Selects extended (132 column) screen size as defined by the extended columns and rows in the screen settings.

ESC STX

Selects normal (80 column) screen size as defined by the normal columns and rows in the screen settings.

AccuTerm 7 Reference 209

ESC STX

color

Sets the foreground (text) color to

color

. This command overrides the foreground color assigned by the last visual attribute selected.

ESC STX

color

Sets the background color to

color

. This command overrides the background color assigned by the last visual attribute selected.

Color Display

0 Black

Dark Blue

Dark Green

Turqoise

Dark Red

Purple

Olive

Light Gray

Dark Grey

Blue

Green

Cyan

Red

Magenta

Yellow

White

Note: the actual display color may vary from the color shown in the table, since it is

possible to modify the palette (see Color Settings).

ESC STX

x1 , y1 , x2 , y2 ,

fill

border

Draw rectangle.

x1, y1

is the upper-left corner and

x2, y2

is the lower-right corner.

Coordinates are in character columns and rows. The upper-left corner of the screen is (0,0).

The rectangle can be filled using either a visual attribute or a background color. To fill with a visual attribute,

fill

A63

. The attribute number is formed by adding the following values:

0 = normal

1 = invisible

2 = blinking

4 = reverse

8 = underline

16 = dim

32 = bright

To fill with a background color (as described above),

fill

...

B15

. To draw a border without filling the rectangle,

fill

. A border can be drawn around the rectangle.

Border

(no border),

(flat border),

(inset border) or

(raised border).

ESC STX

, ID , col , row , width , height , page CR

210 AccuTerm 7 Help

Saves a copy of the specified screen block (text, colors and visual effects) and terminal state in memory and associates the block with the specified identifier (

) which can be an arbitrary alpha-numeric string (may not contain commas). Any number of screen blocks can be saved.

Col

and

row

specify the upper-left corner of the block. If either is omitted or null, zero is assumed.

Width

and

height

specify the size of the block. If

width

height

is omitted or null, the screen width or height is used.

Page

optionally specifies the terminal page for the block, and if omitted or null, the current page is used.

ESC STX

, ID , col , row , page , state

Restores the screen block associated with the specified identifier (

) to the screen.

Col

and

row

specify the upper-left corner of the destination. If either is omitted or null, the original position of the saved block is assumed.

Page

optionally specifies the terminal page for the destination, and if omitted or null, the current page is used.

State

optionally specifies whether the terminal state (cursor position, visual attribute, text color, etc.) is restored To restore the terminal state, pass

for this argument.

ESC STX

, ID

Deletes the screen block associated with the specified identifier (

) from memory.

ESC STX

yj,

ID CR

Queries status of a stored screen block. Sends a 0 or 1, followed by a

, indicating if a block of the specified identifier (

) exists in AccuTerm's screen block memory.

Keyboard

ESC STX

t s d k data CR

Program function and keypad keys. Type

may be

(normal function keys),

(control function keys),

(ALT function keys) or

(keypad keys). Both

and

are permitted when programming control-keypad keys. Shift

may be

(unshifted) or

(shifted). Destination

may be null (program key) or

(program function bar button caption). Key code

may be digits

: ; < = >

according to the following table.

Data

contains the function key data (or caption text). Normally, the key data is transmitted to the host when the programmed key is pressed. However, if

data

is enclosed in brackets (

[ ]

), then when the key is pressed, the key data will be interpreted as a VBA script statement and will be executed instead of being sent to the host.

;

Key

Code

Function key

F10

F11

F12

Editing key

BKSP

TAB

INS

DEL

HOME

END

PGUP

PGDN

LEFT

RIGHT

DOWN

ESC

AccuTerm 7 Reference 211

ENTER

KPD ENTER

To enter control characters (and special prefix characters) in key data, use the notation shown in the following table:

Key sequence

CTRL

CTRL +

CTRL

CTRL +

CTRL

DELETE

ENQ

ACK

BEL

Control code

NUL

SOH

STX

ETX

EOT

DEL

AccuTerm notation

Key sequence

CTRL

CTRL +

CTRL

CTRL +

CTRL

[

CTRL

]

CTRL

NAK

SYN

ETB

CAN

SUB

ESC

Control code

DLE

DC1

DC2

DC3

DC4

AccuTerm notation

For example, to program the

END

key to send the word "END", followed by a carriage return, the following code could be used:

EQU ESC TO CHAR(27), STX TO CHAR(2), CR TO CHAR(13)

PRINT ESC:STX:'FKU5END^M':CR:

Printer

ESC STX

mode

Selects the printer mode:

mode

= 0 - turns off auto or transparent print

mode

= 1 - turns on auto (copy) print mode

mode

= 2 - turns on transparent print mode

mode

= X - turns off auto or transparent print and closes the print job immediately

Multimedia

ESC STX

, filename , col , row , width , height , aspect, border

Displays the image file

filename

at column

col

and row

row

Height

and

width

are optional; if specified (and not zero), the image is scaled to

height

rows and

width

columns. Otherwise, the original image size is used. If

aspect

is non-zero, the image aspect ratio is preserved

(the specified width or height is reduced to preserve the aspect ration).

Border

for no

212 AccuTerm 7 Help

border,

for simple border,

for raised border or

for inset border style. Image file types supported include BMP, JPEG, GIF, PCD, PCX, PICT, PNG, PSD, TARGA, TIFF, WBMP,

XBM, XPM and Windows Metafile. Images are considered "protected" data; a "clear unprotected characters" command will not clear images from the terminal screen.

The image file does not need to be a local file; if an internet connection is available the filename can specify a URL instead of a local or network file.

Note: AccuTerm 7 uses the FreeImage Open Source image library.

ESC STX

, filename

Removes the displayed image file

filename

from the screen.

ESC STX

Clears all displayed images from the screen.

ESC STX

iB,

filename,scalemode,opacity

Loads an image to use as the screen background (wallpaper).

filename

- the path or URL of the image to use as the screen background.

scalemode

= 0 - picture is stretched to fit screen size. This may alter the picture's aspect ratio.

scalemode

= 1 - picture is scaled so that its longest dimension fills the screen. The area not filled by the picture is black.

scalemode

= 2 - picture is scaled so that its shortest dimension fill the screen. The longer dimension is cropped.

opacity

- specifies the opacity of the background image, as a percentage. 100 means that the picture is opaque. 0 means that the image is invisible (transparent) and the screen background color is used as the background. Any percentage in between blends the image with the screen background color.

To clear the background image, simply use

ESC STX

filename

ESC STX

filename CR

Plays sound file

filename

. The file does not need to be a local file; if an internet connection is available the filename can specify a URL instead of a local or network file. Supported sound file formats are WAVE, MIDI and MP3.

Scripting

ESC STX

statements CR

Executes VBA script

statements

. See Scripting for details on VBA scripting. Multiple statements may be executed; separate each statement with

control characters.

You can call subroutines or functions contained within the script loaded in the Main Script tab of the Script Editor window. For example, to call subroutine

FOO

, simply send:

ESC STX

P FOO

. You can execute a script stored in a script file (.atsc file) by using the Chain statement:

EQU ESC TO CHAR(27), STX TO CHAR(2), CR TO CHAR(13)

FILENAME = 'myscriptfile.atsc'

SCRIPT = 'Chain "':FILENAME:'"'

PRINT ESC:STX:'P':SCRIPT:CR: