Copyright: Copyright © 1992 - 1996, Attachmate Corporation. All Rights Reserved.


Overview of Using Macros

A macro contains a series of instructions that can include choosing menu commands, setting dialog box options, and calling functions and other macros. Macros can include programming elements such as structure, control statements, and variables. You can assign macros to individual keys, or user-defined buttons. You can automatically record or write macros to perform a variety of functions including signing-on to a host computer, or interacting with a user, and you can encode your macros so that they cannot be altered.

Many functions are directly equivalent to menu commands. For example, the arguments to the Communications.Setup function are equivalent to the options in the Communications Setup dialog box (Communications command, Options menu).


Macro Record feature

You can use the macro Record feature to write a macro by automatically recording your interactions with a host, either during terminal emulation mode or file transfer using file Send and Receive. For example, you might want to write a macro procedure to log-in, perform file transfers, or repeat actions with a host-resident editor. Record (also known as Learn Mode) records both your keystrokes, and the host responses to your keystrokes.

When you choose Record, the Record dialog box is displayed. Use this box to select the name of the file in which to save your macro. The default file type is .KTM.

You can edit your recorded macro to customize it or add features with KEA! Edit.

When it is enabled, the Record feature records only the following events and commands:

•	All received data, which are coded into a Match function.

•	All keystrokes, which are put into a Send or SendKey function.

•	The Insert Wait and Insert Prompt commands on the Macro menu, which are put into a Wait or Input function.

•	Any use of the Send command on the Transfer menu. Although you can issue the Send command, the Transfer.Transmit function is recorded. In the Send dialog box, the options File Name, File Type, Path, and Host Name are captured. They are applied only to that transfer.

•	Any use of the Receive command on the Transfer menu. Although you can issue the Receive command, the Transfer.Receive function is recorded. In the Receive dialog box, the options File Name, File Type, Crash Recovery, and Local Path or File Name are captured. They are applied only to that transfer.

•	Any use of the Commands command on the Transfer menu.

The Record feature does not notice changes you make in any other dialog box.

Note  When the recorded macro runs, the command strings Start Host Receiving and Start Host Sending (in the Kermit or X/Y/Zmodem Options dialog boxes) are not sent to the host. If you need these host commands, you must insert equivalent commands into the recorded macro.

  Recording a Macro


Recording a Macro

To record an exchange with the host, so you can later repeat it

1	From the Macro menu, choose Record.

2	In the Record dialog box, type a name for the macro file you want to create, and choose OK.

3	Log in to your host in the usual way, or transfer files, or perform whatever exchange with the host that you want to save. Most (but not all) actions are recorded.

4	If you want to insert a pause in the recorded macro, choose Insert Wait from the Macro menu.

5	If you want the macro to ask for user input, choose Insert Prompt from the Macro menu. After you define the prompt you want, it immediately appears so that you can continue recording the actual exchange with the host.

6	If you want to temporarily stop recording, choose Pause Recording from the Macro menu. Then you can issue commands and type commands and data to the host that are not recorded in the macro file you are creating. When you want to resume the recording, choose Continue Recording.

7	When you are finished the exchange, choose End Recording from the Macro menu.

You can now run this macro file, assign it to a key or button, or have it run whenever KEA! starts.

This is a regular macro file which you can add to or modify using KEA! Edit. Because the Record feature is generally looking for prompts, it saves the ending of received character strings, and attempts to match on the observed end of the string, immediately followed by an idle period. If you edit the recorded macro file, be careful you don't accidentally delete the end of the string. If you want to, you can remove the Idle period from the Match function argument list.


Creating Macros with KEA! Edit

KEA! Edit is a separate application, included with KEA!, for editing and testing macro programs. Editing is similar to using Windows Notepad. You can edit a file up to a maximum size of 30,000 bytes. KEA! Edit also communicates with KEA! to implement a powerful interactive debug tool.

To invoke KEA! Edit, choose Edit from the KEA! Macro menu.

  Writing a Macro

  Editing Features

  Testing/Debug Features


Writing a Macro

Writing and Saving a Macro

You use KEA! Edit, the macro editor and debug program, to write your own macros.

To write and save a macro

1	From the Macro menu, choose Edit to display KEA! Edit, the editor and debug program.

2	In the Open File dialog box, type a filename for the macro you want to create.

3	Choose OK to create a new file.

4	Type the instructions you want the macro to perform.

5	Perform any testing and debugging you want to do at this time.

6	When you finish the macro, choose Save from the KEA! Edit File menu.

To create an encoded macro

1	After you have written and tested the macro, choose Save As from the KEA! Edit File menu.

2	In the Save File dialog box, select Encoded Macros (*.KTE) from the Save File as Type drop-down list.

3	Type the filename of the macro you want to encode, then choose OK.

4	You should also save the macro in regular plain text form (with a .KTM extension), because encoded macros cannot be edited. If you don't, you are prompted to save the file before closing KEA! Edit.

Testing a Macro

If  you have saved them in plain text form, you can edit (change) existing macros and test them using KEA! Edit's debugging features.

To change and debug a macro

1	From the Macro menu, choose Edit to display KEA! Edit, the editor and debug program.

2	In the Open File dialog box, select the macro file you want to edit and/or debug.

3	From the Debug menu, choose Debug Mode.

4	From the Debug menu, choose other Debug options you want to use, such as Variables to display the Variable window. The Variables window displays the values for your macro's variables when you Step, Step Into, or Trace a macro.

5	Use the Step and Trace options to debug the macro.

6	When you finish working with the macro, choose Save, Save As, or Close from the File menu.


KEA! Edit: Editing Features

Creating a New Macro

Choose New from KEA! Edit's File menu. A new window is opened using the name Untitled.

You can also create a new macro from the Open File dialog box, which appears when you first start KEA! Edit. To create a new macro, under File Name, type the name of the file you want to create.

Opening an Existing Macro File

Choose Open from KEA! Edit's File menu. This displays the Open File dialog box. You choose the file to open from the list under File Name. You can change the drive and directory from which to choose a file. You also can change the extension to display different files in the File Name list.

Viewing More than One Open File

Choose Tile or Cascade from the Window menu to view more than one file at a time.

You can have several files open at the same time. Choose the current window from the list of open windows on the Window menu. You can view only one file at a time if you use Debug Mode.

Entering and Editing Text

Enter and edit text just as you do with most text editors.

You can use the DEL or BACKSPACE keys to delete text. You can move the insertion point with the ARROW keys or the mouse. Choose Undo from the Edit menu, or press CTRL+Z, to undo the last change you made.

You can change the number of spaces between tab stops, and the current language with commands from the Options menu.

Selecting Text

Select lines of text in the usual click-and-drag way.

Double-click to select a word. Hold down the SHIFT key and click to extend the selection. Choose All from the Edit menu to select the entire document.

Cut/Copy/Paste

To copy selected text to the clipboard, choose Copy from KEA! Edit's Edit menu, or press CTRL+C.

To remove selected text from the current window, and put it on the clipboard, choose Cut from the Edit menu, or press CTRL+X.

To paste text from the clipboard into the current window starting at the current cursor location, choose Paste from the Edit menu, or press CTRL+V.

To delete selected text without placing it on the clipboard, choose Delete from the Edit menu, or press DEL.

Searching for a Character String

Choose Find from KEA! Edit's Edit menu.

This command displays a dialog box that lets you enter the string for which to search, and specify whether to make the search case sensitive. You choose Next to search to the end of the macro, or Previous to search to the beginning. Choose Next or Previous from the Edit menu to repeat the search.

Saving your Macro Program

Choose Save or Save As from KEA! Edit's File menu when you finish editing your macro.

If you choose Save As, you can save your macro in encoded form, by selecting Encoded Macros (*.KTE) from the Save File as Type drop-down list. If you do, you should also save it with a .KTM extension, because encoded macros cannot be edited.

If you choose Close instead, you are asked if you want to save the changed file. Choose Save backup file from the Options menu to create a copy (using .BAK as the extension) when you save an edited file.


KEA! Edit: Testing/Debug Features

KEA! Edit provides a powerful macro testing tool. To use these debug features, you must invoke it from KEA!'s Macro menu. You can display only one window at a time, although you can have several open.

Debug Mode and the Variables Window

Choose Debug Mode from KEA! Edit's Debug menu.

A window is displayed in which you can see the values of your macro's variables. You can see the variables change during stepping or tracing a macro, and see the final global variable values when the macro finishes. To display the Variables window, choose Variables from the Debug menu.

Putting Breakpoints in a Macro

Type a Brk( ) function in your program.

You can put any number of breakpoints in your program. If you run the macro from KEA! Edit, the macro pauses at the breakpoint. You can inspect and change values in the Variables window. If you try to edit the macro statements, the macro quits. If you run the macro from other than KEA! Edit, the macro ignores the breakpoints.

Example

Begin

   When Match( "OK" )

      Send( "atdt 5249999" + CR )

      Continue

   When Match( "CONNECT" )

      Send( CR )

Brk( )     // break point

      Continue

   When Match( "Username :" )

Brk( )    // break point

  .

  .

End

Debug Functions

You can access the debugging commands from the ToolBar, the Debug menu, or by using Function keys.

Command	Toolbar	Key	Action

Pause		F4	Pause the macro execution.
Go		F5	Start the macro from the beginning, or from where it paused.
Quit		F6	Terminate the macro.
Trace		F7	Highlight each statement when the macro executes it, and update the Variables window. Similar to Go, but runs slowly.
Step Into		F8	Single-step the execution of the current macro and any called macros.
Step		SHIFT+F8 or F10	Single-step the execution of the current macro only. If it calls another macro, treat the called macro as a single step, and execute it to completion. The key you use depends on the Debug Keys selection from the Options menu.
Changing Variables

You can examine the current variables in the Variables window when you debug the macro with the Step or Step Into command. When the macro pauses, double-click the variable in the Variables window to modify its value. The "Enter new value for" dialog box appears, containing the name of the selected variable and a box in which you can change the current value.

KEA! Edit represents an array variable using a single line. Double-click the array line to expand it, and show all its values. Double-click an array element to modify its value. Double-click the array line again to collapse it.


Invoking a Macro

KEA! provides several ways for you to invoke (or execute, or run) a macro. Most ways allow you to pass arguments to the macro and obtain a return value.

You can run a macro by choosing Run from the KEA! Macro menu, and specifying the filename of the macro. You can assign a macro to a keyboard key, a user-defined button, or a mouse button. Then you can press the key or button to run the macro. You also can run a macro from KEA! Edit, the macro editor and debug program.

To invoke a macro, use any of the following methods:

1	From the Macro menu, choose Run.

2	In the Run dialog box, specify the filename of the macro you want to run, or select a name from the displayed list.

-or-

Assign the macro to a keyboard key, mouse button, user-defined button, or user-defined menu item.

-or-

Invoke the macro by calling it from another macro. You can simply use the name of the macro in an expression, in the same way that you call a function. Include up to six arguments as the macro expects. Because you cannot name the arguments, they are identified by their place in the argument list. Or you can put the name of the macro in a variable and use it in a Run statement.

-or-

Use the Go command from KEA! Edit.

-or-

Set the macro to run whenever you start KEA!. To run a macro automatically on startup, choose Options from the Macro menu, type the name of the macro under Startup, and save the session.

-or-

Let the host invoke a macro by sending a control sequence.

Search Path

When attempting to run a macro, KEA! searches directories in the following order:

1.	If the macro is being invoked by another macro, KEA! looks in the directory where the calling macro is located.
Or, if KEA! has a configuration file (it usually does) it looks in the directory where the configuration file is located.

2.	The path specified in the Search Path option in the Macro Options dialog box. The search path is entered using the DOS path statement format, a list of paths separated by semicolons.

3.	The user directory on your own machine, which the macro language refers to as Directory_Home. This directory is by default named USER, under Directory_Base on your own machine.

4.	The directory containing the executable KEA! (.EXE) file, which the macro language refers to as Directory_Base.

5.	The standard Windows directories, in the following order:

•	The current directory

•	Windows

•	Windows system

•	The list defined by your DOS Path command


Letting the Host Invoke a Macro

A host computer can send control sequences that tell KEA! to execute macro commands. These special control sequences can name a particular macro file that exists on your computer, or they can contain the actual commands to be executed.

Invoking REMOTEnn.KTM

The following sequence invokes the macro file REMOTEnn.KTM, where <Pn> is a pair of digits 00 to 99. You must define the named file on your computer.

CSI4;<Pn>.z

Example

CSI4;88.z

When this control sequence is received, the macro file REMOTE88.KTM is executed.

Invoking Any Macro File, or Executing Statements

The following sequences allow the host to invoke any macro file, or execute individual statements contained in the sequence. Datastring can be one or more macro statements separated by spaces (a semicolon aids readability). In the simplest case, the statement can be the name of the macro file to be invoked. The maximum size of a datastring is 8K.

DCS4.z<datastring>ST

A variation on this sequence allows you to include a checksum with the datastring. The macro statements are executed as the preceding command, only if the two-character checksum is correct.

DCS4;1.z<datastring><checksum>ST

If the checksum is incorrect, KEA! responds with

DCS4;1.y<checksum>ST

where this checksum is the correct one for the previously sent {datastring}.

If you do not want KEA! to obey such requests, select Lock Remote Macros in the Options dialog box (Macro menu).

Tip  There is an easy way to determine the correct checksum to send. The host needs only to send the preceding sequence including an arbitrary checksum, say "XX." KEA! rejects the command and responds with the correct checksum. Then the host can send the sequence a second time, including the correct checksum.

Examples

    DCS4.zEXAM1(10,"abc")ST

The host invokes the macro file EXAM1.KTM in the current directory. As in any macro statement, a macro file can be invoked as if it were a function.

    DCS4.zRun("c:\keavt\exam2",22,"abc")ST

The host uses the Run function to invoke the macro file EXAM2.KTM in the directory C:\KEAVT.

    DCS4;1.zFonts = "8wide"DEST

The host sets KEA!'s fonts to 8 wide. A checksum, calculated as the character pair "DE" is sent at the end of the datastring.

    DCS4.zCommunications(Port = "LAT");

    Communications.Setup(ServiceName = "Freddy")ST

The host instructs KEA! to prepare a LAT session with the host Freddy. Because line endings are not allowed, the two statements in this datastring are separated with a semicolon. While not absolutely necessary, the semicolon makes the datastring more readable.

The following example function shows how a checksum can be calculated. It sends the datastring, as supplied in the argument SendData, to be executed as KEA! macro commands. Notice that the example function is written in the KEA! macro language, which implies that the "host" is also running KEA!.

Function SendCSum( SendData )

  Var CSum, Sum = 0, i = 1, l = Len( SendData )

  While i <= l

    Sum = Sum - Asc( SubStr( SendData, i, 1 ) )

    i = i + 1

  End

  CSum = Chr( (Sum & 15) + 64 ) + Chr( ((Sum & 240) / 16) + 64 )

  Send( "^1444;1.z" + SendData + CSum + "^156" )

End


Macro Language Syntax

Macros, like programs, consist of instructions. Each instruction contains a number of different elements. This section gives brief definitions of these elements. For more information on each, see the section on that element.

Statement

A command that tells the macro what action to perform.

Expression

A combination of variables, operators, functions, and so on, that can be evaluated to a single result. The result can be used in an assignment statement, or as a condition in the control statements Begin..When..End, If..Else..End, and While..End.

Variable

A combination of letters and numbers used to hold a value. Variables can be numeric, string, or array. Many are predefined.

Constant

A value that does not change. Constants can be numeric or string. Many are predefined.

Operator

A symbol, such as the plus sign ( + ), used to perform mathematical computations, compare values, or concatenate strings. KEA! uses five types of operators: string, arithmetic, comparison, logical, and bit.

Function

A command that performs an action and/or returns a value; always followed by parentheses.

Argument

The element of the macro instruction that contains information that tells a function what to do.

Event

Some functions generate asynchronous events which you can use in the When clause of a Begin..When..End control statement.

Menu Equivalent Command

A macro instruction that performs the same action as its equivalent menu command. It is followed by parentheses, which can be empty, and has no return value.

Menu Equivalent Option

The element of a macro instruction that performs the same function as a dialog box option. It can assign a value, but does not perform an action.


Macro Statements

A statement tells the macro what action to perform. You must separate identifiers, such as keywords and variables, with at least one space. However, do not use spaces, tabs, or line endings within keywords or variable names.

A simple statement is the assignment statement, which has the form:

variable = expression

The following are control statements:

Begin Dialog...End

Begin...When...End

Break

Continue

For...In...End

Function

Global

If...Elseif...Else...End

Return

Var

While...End

You do not need line endings to separate statements; you can separate statements with just one space, or a semicolon. However, using line endings makes it easier to read the macro. A semicolon is useful if you map macro strings to keys, mouse buttons, or the user-defined SmartPad.

You can include comments in your macros. You start a comment with a pair of slashes (//). The comment ends at the end of the line. A semicolon does not terminate a comment.


Macro Functions

A function consists of a macro language-defined keyword followed by parentheses. These keywords perform actions, return values, or a combination of these. Most functions return a value.

You can invoke a function by using it in an expression, or by itself. You include the function's arguments in the parentheses. If the function takes no arguments, you must include empty parentheses. Functions take the form:

function_name(argument1=value1, argument2=value2,...)

or

function_name( )

You can include the argument values without the argument names. If you omit the argument names, you must place the values in a certain order or KEA! cannot evaluate them properly. However, including the argument names makes it easier to read the macro, and make changes to the function, if necessary. A function without argument names takes the form:

function_name(value1, value2,...)

Many arguments are optional. If you omit arguments, and do not use the argument names, you must retain the commas separating the arguments. This takes the form:

function_name( , value2,...)

If the function returns a value, and you do not use it in an expression, KEA! puts the return value into the predefined variable Result.

User-Defined Functions

You can write your own functions using the Function statement. However, you must define your function in the same macro that calls it. You can use up to six arguments in your function, passing these arguments by value or reference.


Passing Arguments to a Macro

Any macro you write can access arguments and return values. Some methods of invoking a macro allow you to pass arguments; others do not.

From within a macro, you can call any other macro as if it were a function. You can nest function calls to many levels. You also can invoke a macro as part of an expression, just like any function.

A macro can access up to six arguments from the calling macro using the predefined array Arg. The size of this array is given by Argcount, a predefined variable having a value of any number from 0 to 6, inclusive (0 for no arguments).

A called macro can return a value using the Return statement. When a macro invokes another macro as part of an expression, the value is returned in the expression, in the same way as a function. When a macro invokes another macro on a line by itself, any returned value is put in the predefined variable Result.

Another way to pass data between macros is by using Global variables.

Example

The following macro ADD.KTM adds two integers that are passed to it, returning the sum to the calling macro.

// ADD.KTM  function to add two integers

A = Arg[1]

B = Arg[2]

Z = A + B

Return( Z )  // value of Z is returned to caller

The following macro calls ADD.KTM. It shows one method of obtaining the returned value as the value of an expression.

A = 4

B = 2

X = Add( A, B )

Message( "The sum of A and B is " + X )

The following macro calls ADD.KTM. It shows an alternate method of obtaining the returned value, from the predefined variable Result.

A = 4

B = 2

Add( A, B )

X = Result

Message( "The sum of A and B is " + X )

In the following two macros, the called macro accepts a variable number of arguments:

// TestRun.ktm

MacroToRun = Input( "Name of macro to run", "TestRun2" )

ArgToPass = Input( "Argument to pass" )

Run( MacroToRun, ArgToPass )

// TestRun2.ktm: Display a variable number

// of arguments on the screen

List = "Arguments passed"

If Arg

  For ttt In Arg

    List = List + ";" + Arg[ttt]

  End

End

MsgBox( List )


Macro Variables

Variables hold values. You define a variable by assigning a value to it. You must define a variable before you can use it. You can declare local or global variables. The macro language contains many predefined variables.

You can assign a variable a name of any length. Variable names must start with an alphabetic character, and can contain alphanumeric characters and underscores. Variable names beginning with an underscore are reserved for internal use. Variables are case-insensitive.

Variables can hold three kinds of values: integer, string, or array. The last assignment of the variable determines the kind of value the variable holds. The content of a variable is converted as needed. Variables can hold one of the following kinds of values:

Integer

A 32-bit signed number.

String

A series of alphanumeric characters of any length.

Array

A group of items accessed by a string or integer subscript, and sharing the same variable name. You do not have to declare the array or its size; it is automatically declared when you first use it. You define the array items by assigning values to them. You can delete an array by assigning an integer to the variable.

To access any array item, enclose the subscript in brackets. For subscripts, you can use any expression. All subscript expressions are converted to strings. Subscripts are case-sensitive, and affected by leading or trailing spaces in the subscript value. For example:

          food["FRUIT"]["RED"] = "apple"

If you are using known identifiers (not expressions) for subscripts, you can access array items by simply separating the array variable and its subscript(s) with a period. Identifiers are converted to uppercase before they are used as subscripts:

          food.fruit.red = "apple"

To read the subscripts and values of an (unknown) array, you can use the For..In..End statement.

Scope of Variables

By default, a variable exists only in the macro in which you define it, and only while the macro is running. You can pass variables to called macros through an argument list. Variables of the same name can exist in called macros with no conflict; they are treated as different variables.

You can declare global and local variables. Use the Global statement to create variables that exist until you exit KEA!. You do not have to pass a global variable as an argument; global variables are available to all macros.

Local variables exist only in the section in which you define them. You use the Var statement to declare a local variable. If you declare a local variable inside an event, it does not exist in the rest of the macro. You can declare a local variable inside a user-defined function.


Predefined Macro Variables

The language contains many predefined variables. You use these predefined variables to convey function return values, function arguments, and error conditions. Among them are:

Adjustment   Used to alter the Col variable when a macro obtains the position of a mouse click.

Arg   A predefined variable that contains an array of arguments passed to a called macro.

Argcount   A predefined variable that contains the number of arguments passed to a called macro. If you call the macro with no arguments, Argcount equals 0. The maximum number of arguments is 6.

Col   Screen address used by several positioning commands.

_ddeAErr and _ddeAMsg   Global variables that contain the error code and message from the last-used high level DDE function.

FileType  When used with a file transfer command, contains one of the following values specifying the mode in which to transfer files: Xfer_Binary, Xfer_Automatic, or Xfer_Text.

HostFileName   When used with a file transfer command, contains the name of the file to transmit to the host.

HotlinkStart	Available in a macro automatically run at startup. The variable is true if KEA! was started by a hotlink from another application.

LinkHostname	Available in a macro automatically run at startup. Valid only if HotlinkStart is True. It is the name of the host KEA! should connect to. This information comes from the other application.

LocalFileList   When used with a file transfer command, contains the specified local filename.

NewSession	Available in a macro automatically run at startup. The variable is true if KEA! was started with the  /n option on the command line. When this option is specified, KEA! does not look for existing configuration files but always displays the New Session dialog box.

Page   Page number used by several positioning commands.

Result   A predefined variable used to hold a returned value. When you use an expression that returns a value in a context that does not use the value (for example, a statement without an assignment), Result is set to the returned value.

Row   Screen address used by several positioning commands.

Server   When used with a file transfer command, is True if remote Kermit is a server.


Macro Constants

A constant is a value that does not change. There are two types of constants: numeric and string.

Numeric constants can contain a leading minus (-) sign. Generally, you use numeric constants as part of an expression.

String constants can contain up to 160 alphanumeric characters. You must enclose string constants in double quotation marks ("), for example, "constant". You can represent a character by using its decimal value. For example, to assign a carriage return to a variable, you can use "^13" as the value for carriage return. You also can represent control characters with a caret ^ and the appropriate letter. For example, you also can represent a carriage return with "^M". If you want to use the double quotation (") or caret (^) literally in a string, you must use a backslash (\) in front of the character.

The macro language contains many predefined constants.


Predefined Macro Constants

The language includes many predefined constants. Typically, these are passed in as function arguments or used to test return values and error conditions. If you define a variable in a macro whose name conflicts with one of these constants, an error is reported.

The most frequently used constants are True and False. True is defined as the integer 1, and False as the integer 0. It is important to note that the expression "If A" is not equivalent to the expression "If A = True". The former will be true whenever A is a non-zero value, whereas the latter will only be true when A has the value 1. As a general rule, the constants True and False should only be used when assigning a boolean value to a variable.

The following are additional predefined constants:

Abort_All	DDErc_Ack	Icon_Info	Xfer_DetailedEnd
Abort_File	DDErc_Busy	Icon_Stop	Xfer_Discard
Abort_Immediate	DDErc_Error	Icon_What	Xfer_End
Attr_Archive	DDErc_Fatal	Info_Configname	Xfer_EndCancel
Attr_Directory	DDErc_Nack	Info_Enterprise	Xfer_Endfail
Attr_Hidden	Directory_Base	Info_PortOK	Xfer_EndOK
Attr_NoArchive	Directory_Current	Info_PortSetup	Xfer_EndRename
Attr_NoDirectory	Directory_Home	Input_DropDown	Xfer_EndSkip
Attr_NoHidden	Directory_Keaterm	Input_Hide	Xfer_Fullpath
Attr_Normal	Directory_Macro	Input_List	Xfer_Kermit
Attr_NoSystem	Directory_System	Input_Values	Xfer_MapNl
Attr_NoVolume	Directory_Windows	Numeric_Value	Xfer_NoCrashrecover
Attr_ReadOnly	File_Append	Pat_NoCase	Xfer_NoCreatePath
Attr_System	File_Attr	Pat_RegExp	Xfer_NoCtrlZ
Attr_Volume	File_Create	Pat_Strip	Xfer_NoFullPath
Attr_Write	File_Date	Select_Block	Xfer_NoMapNl
Box_Indent	File_Drive	Select_None	Xfer_NoStatus
Box_Outdent	File_Extension	Select_StatusLine	Xfer_NoSubdirectory
Button_Abort	File_Name	Select_Stream	Xfer_NoUsePath
Button_Cancel	File_Path	Sound_Always	Xfer_Overwrite
Button_Ignore	File_Prompt	Sound_Async	Xfer_Rename
Button_No	File_Read	Sound_Loop	Xfer_RenameOld
Button_Ok	File_ReadWrite	Sound_NoStop	Xfer_SendCrLf
Button_Retry	File_Size	Sound_Sync	Xfer_SendLf
Button_Yes	File_Time	String_Value	Xfer_Start
Control_Default	File_Truncate	Xfer_Append	Xfer_Subdirectories
Control_Disable	File_Write	Xfer_Ascii	Xfer_Text
Control_Enable	Filedlg_Dir	Xfer_Automatic	Xfer_UsePath
Control_Focus	Filedlg_Exist	Xfer_Between	Xfer_Xmodem
Control_GrayText	Filedlg_NoCd	Xfer_Binary	Xfer_Ymodem
Control_Init	Filedlg_NoReadOnly	Xfer_Continue	Xfer_Zmodem
Control_Label	Filedlg_Prompt	Xfer_CrashRecover
Control_Password	Filedlg_Save	Xfer_CreatePath
Control_Value	Icon_Error	Xfer_CtrlZ


Macro Operators

You use operators to form expressions by combining variables and constants. You can perform mathematical computations, concatenate strings, and compare values, just like any programming language. The macro language uses five types of operators: string, arithmetic, comparison, logical, and bit.

String Operators

You use the plus sign ( + ) as a string operator to join strings. For example, "John" + " Smith" becomes "John Smith".

Arithmetic Operators

You use arithmetic operators to define the mathematical operation to perform on the variable values. For example, A - B subtracts the value in the variable B from the value in the variable A. Arithmetic operators include:

Operator	Meaning	Example

+	Addition	A + B
-	Subtraction	A - B
*	Multiplication	A * B
/	Division without a remainder	A / B
Mod	Special division returning only the remainder	A Mod B
- A	Unary minus	- A
Comparison Operators

You use comparison operators to define the comparison between variable values. You can use these operators with integer or string values. If you use string values, they are compared in the normal ASCII order. String values are case-sensitive. If only one of the variables contains an integer value, it is converted to a string before being compared. Comparison operators include:

Operator	Meaning	Example

=	Equals	A = B
<	Less than	A < B
< =	Less than or equal to	A < = B
>	Greater than	A > B
> =	Greater than or equal to	A > = B
<>	Not equal to	A <> B
In	If left-hand item exists in right-hand item, result is True, else result is False.	A In B
Logical operators

You use logical operators to define the comparison between variable values as either True or False. The values zero (0), zero string ("0"), and null string ("") are False, and other values (numbers or strings) are True. Logical operators include:

Operator	Meaning	Example

And	True if both are true	A And B
Or	True if only one is true	A Or B
Not	True if value is false	Not A
Bit operators

You use bit operators to define the manipulation of bit patterns. Bit operators are used, for example, in testing the file attributes returned by a FileExists function call. The valid bit operators are:

Operator	Meaning

BitAnd	True if all bits true
BitOr	True if one bit true
BitXor	True if only one bit true
BitNot	True if no bits true


Macro Events

The Begin..When..End control statement allows execution of concurrent statements while waiting for one or more events. Events are generated by some functions when the function completes or other specified conditions are met.

The following functions generate events:

Control (when used with Begin Dialog..End)

CursorAt

CursorMove

DDE_Accept

DDE_Advise

DDE_Ended

DDE_Execute

Disconnected

KeyStroke

Match

ScreenChanged

ScreenMatch

Timeout

TransferCommand

TransferProgress

TransferReceive

TransferTransmit

Wait


Menu-Equivalent Commands

The macro language uses functions that perform the same actions as menu commands. These are known as Menu Equivalent Commands. They have no return value and are always followed by parentheses (which can be empty). They include commands, such as CopySpecial() and Print(), that can take arguments just like functions.

The macro language uses the English name of the older, pre-Version 4 menu command as the function name. As a matter of interest, you can see this older style of menus and commands by selecting the Old KEAterm Menus option in the General Settings dialog box (KEA! Options menu).

The macro language also contains internal functions equivalent to nested dialog boxes. It uses the English name of the dialog box, without spaces, as the internal function name. The macro language uses a dot (.) to connect the function name and internal function name.

Examples

Capture( )         // choose Capture on the File menu

Clear( )        // choose Clear on the Connection menu

Display.Tabs.Default( )   // choose Default button

                          // in the Tabs dialog box


Menu-Equivalent Options

The macro language uses internal functions that have the same effect as a command's dialog box options. These are called Menu Equivalent Options. They do not perform an action. The macro language uses the English name of the option setting, without spaces, as the macro option name. The macro language uses a dot (.) to connect the option name to the function name and internal function name. For example, the macro option Communications.Setup.BaudRate is equivalent to the Baud Rate option in the Setup dialog box that you access from the Communications dialog box (Options menu).

The macro language contains the following three classes of Menu Equivalent Options:

•	Check items

•	Items with string values

•	Dialog box items (with optional user input)

Check Items

Check items are equivalent to menu items that display a check mark when enabled. You can set and read their values. The following shows examples of check items:

StatusBar = True

StatusBar = 1

current = AutoConnect

Items with String Values

Items with string values are equivalent to menu items that display a cascading menu when you choose them. You can set and read their values. For example, to select 8 wide for Fonts, you would include the following in your macro:

Fonts = "8 wide"

Dialog Box Items

Dialog box items are equivalent to options in dialog boxes. You can set many options in one statement using a function-like syntax with parentheses. You also can set or read a single option using a dot to separate the box, secondary box, and option names. The following shows examples of dialog box items:

Communications( Port = "Serial" )

Communications.Setup.BaudRate = "19200"

Display.Colors( MapBoldToColor = FALSE,

    MapUnderlineToColor = FALSE,

    MapInverseToColor = FALSE,

    MapBlinkToColor = FALSE )

ButtonPad( ButtonsOnStatusLine = TRUE,

    Rows = "5", ButtonWidth = "10" )

If Terminal.LocalEcho

  Message( "Echo is on" )

End

Dialog Box Items, with user input

If you include a question mark before the parentheses, the dialog box is displayed to the user. The user can change any options in the box. The macro continues when the user chooses OK. You can provide default values for the dialog box items. The following shows how to provide a default value for Baud Rate, and display the Setup dialog box:

Communications.Setup?( BaudRate = "9600" )

 // box shows 9600 as default


Using Dialog Boxes in a Macro

KEA!'s macro language includes a set of functions that let you generate dialog boxes. This section provides an overview of this feature and lists the functions that implement it. To define a dialog box in a macro, you include a structure similar to the following:

Begin Dialog( [[Text=]String] )

Controls
. . .
[Do
Concurrent statements]

[When Condition
 	Statements]
[When Condition
 	Statements]
. . .
End

Begin Dialog signals the start of a dialog box definition. Its optional text argument allows you to specify a title that appears in the title bar of the dialog box.

The Controls section contains functions that define the buttons and boxes inside your dialog box. These functions are generally of the form:

Controlname( [[Text=]string], [[Width=]integer], [[Height=]integer], [[Offset=]integer] )

where

Controlname   	is one of the functions: Button, DefaultButton, OKButton, CancelButton, CheckBox, ComboBox, DropDownBox, EditBox, ListBox, LogBox, MeterBox, RadioBox, TextBox.

text   	is a literal string, or string variable that appears as a label on the button or box.

width   	is a literal integer or integer variable that defines the horizontal space (in average character width) taken up by the complete button or box. It includes any label, user entry space, and separating white space.

height   	is a literal integer or integer variable that defines the vertical space (in character height) taken up by the button or box. It includes the borders and separating white space. If you do not supply this parameter, the default is the appropriate height.

offset   	is a literal integer or integer variable that defines how far from the right edge of the space the left part of the button or box starts. You should specify an offset that is less than the width. If you specify a value for the width, but do not specify a value for the offset, the button or box will occupy all of the space given by the width value.

Dialog boxes always appear in the center of the emulation window. They are automatically sized to accommodate the buttons or boxes you define within them. You can arrange controls in a dialog box with the GroupBox function.

The optional Do section contains the concurrent code, which begins executing as soon as the dialog box is defined. The code continues to execute until a When event occurs, at which point the event takes over. When the event has finished processing, the concurrent code resumes execution at the point where it stopped. As with events, the dialog box exits when the concurrent code finishes execution, unless it encounters a Continue statement or a Suspend. If there is no Do section, the dialog box exits under control of the Controls section. There can be at most one Do section.

The optional When section contains the event handlers for the dialog box. The events may occur because a user accesses a button or box, or events normally handled by the Begin..When..End structure. Whenever you activate a button or box in the dialog box, its When Control section begins executing. If you activate a button or box for which there is no When statement, the dialog box finishes execution. In the case of a button, clicking the button or pressing ENTER triggers an event. List boxes, drop-down boxes, combo boxes, check boxes and radio boxes receive events every time you select an entry from their list of choices. Edit boxes only receive events when you finish typing in them and press ENTER. The following functions generate events:

Control	Disconnected	TransferCommand
DDE_Accept	Match	TransferProgress
DDE_Advise	ScreenChanged	TransferReceive
DDE_Ended	ScreenMatch	TransferTransmit
DDE_Execute	Timeout	Wait
The variables associated with each button or box are automatically updated before an event is processed. You can modify a button or box attribute at any time using the ControlSet function.

Example

Var Password

Begin Dialog( )

GroupBox( , True )

EditBox( "Password", Password, Width = 28 )

DefaultButton( "Encode", Width = 12 )

GroupEnd( )

GroupBreak( )

OkButton( Width = 15 )

CancelButton( Width = 15, Offset = 10 )

Button( "Help", Width = 15, Offset = 10 )

Do

ControlSet( "edit1", Control_Password, Value = 1 )

Continue

End


Handling Files in a Macro

The Macro Language provides several functions for handling files on your personal computer. The basic functions, FileOpen, FileClose, FileRead, and FileWrite, allow you to implement simple input and output routines in your macros. The function FileEnd provides a method of testing the end-of-file condition. The function FileExists allows you to determine whether or not a file exists before attempting to open it. You can also directly control the position of the file pointer by calling the function FileSetPos, and query its position with FileGetPos.

The functions FileDelete, FileRename, FileDir, and FileCopy allow you to perform the DOS-equivalent commands del, rename, dir, and copy. The function SetDirectory is used to change the current directory to a specified directory. Likewise, the function GetDirectory returns the full path name of any one of the predefined paths used by KEA!. To generate a list of all currently mapped drives, you use the function FileGetDrives.

The macro language also includes functions for manipulating file path names. The function FileGetElidedName allows you to truncate a long file path to a given length, using a method that removes directory names from the middle of the path first and replaces them with an ellipsis. The function FileGetFromPath is used to extract elements of a full path name, such as the drive or the file extension.

KEA! provides the ability to log session information using the LogOpen function. A log file can later be removed by calling the LogDelete function.


Transferring Files in a Macro

The KEA! Macro Language provides several functions for transferring files to and from the host. The basic functions, TransferTransmit and TransferReceive, are equivalent to the Transfer menu commands. A macro can prompt the user to fill in or modify transfer parameters in the appropriate dialog boxes by calling the Transmit, Receive, or FileTransfer functions followed by a question mark.

File transfer functions can appear in a Begin..When..End construct of a macro. This leaves the macro free to perform other activities during the transfer. The TransferProgress function is used as a When event to return progress information on a transfer periodically. A file transfer can be interrupted at any time by calling TransferAbort. Also, the TransferProd function allows a macro to simulate a timeout during a transfer.

When the host is in Kermit server mode, a macro can send server commands to the host using the TransferCommand function.

Specific options for each protocol can be configured using extensions of the FileTransfer command. The following set of commands can be followed by a question mark, in which case the user is prompted to fill in or modify transfer parameters in the appropriate dialog box. Alternatively, each command can be extended by a further set of options from its dialog box so that the values can be assigned directly.

FileTransfer.AsciiOptions

FileTransfer.KermitOptions

FileTransfer.KermitOptions.Advanced

FileTransfer.TextFileOptions

FileTransfer.TextFileOptions.Translation

FileTransfer.XmodemOptions

FileTransfer.YmodemOptions

FileTransfer.ZmodemOptions

FileTransfer.FTPOptions


User Interaction in a Macro

The macro language provides several ways for macros to communicate with a user. Macros can display a message, or ask a user to enter information or select an item.

You can create your own elaborate Dialog boxes to interact with a user. For an overview and list of the functions that you use, see Using Dialog Boxes.

The Echo function displays text in the emulation window.

The Message function displays the text on the status bar.

MsgBox displays text in a dialog box, and waits for the user to choose OK before continuing.

You can map a macro to a mouse button so that the macro is invoked when the user clicks the button. This macro can determine the screen position of the user's click.

The Input function displays a dialog box containing text and a default response. The list can be a regular, drop-down, or combination box.

If you include the optional question mark (?) when you use a Menu Equivalent Command, a regular dialog box is displayed, and the macro pauses so the user can select options before continuing. The following displays the Communications Serial Port Setup dialog box with some defaults set. The user can change any of the settings in the dialog box before choosing OK.

Communications.Setup?( Port = "COM2", BaudRate = "19200",

    ModemDisconnect = "2 sec" )


Searching for String Patterns

A string can include special pattern-matching characters such as the wildcards ? and *. This type of string is known as a regular expression, a term derived from the UNIX world.

Regular expressions describe single characters or groups of characters. For more information on using regular expressions, see the Instr and Match functions.

Special Character...	matches...	Example

?	any single character.	d?g matches dag, dog, and so on.
*	any number of characters.	d*g matches dg, dabcdefg, and so on.
-	the preceding character 0 or 1 times.	do-g matches dog and dg.
+	the preceding character 1 or more times.	do+g matches dog, dooooog, and so on.
{...}	the substring. This makes a group of characters equivalent to a single character when the group precedes a - or +.	{do}-g matches g and dog; {do}+g matches dog, dodog, dododododog, and so on.
|	either string (an OR operation).	dog|cat matches dog or cat.
[char1char2charN]	any of the characters.	do[abc]g matches doag, dobg, or docg.
[~char1char2charN]	any character but these.	do[~bc]g matches doag, dodg, and so on, but not dobg or docg.
[char1-char2]	characters in the specified range; shorthand for the sequence of characters from char1...char2. You can use this wherever you can use substring.	do[a-c]g matches doag, dobg, docg; [a-z0-9$] matches any lowercase character, digit, or the $ character.
\	the following character as a literal, not as a special character.	To match a question mark (?) use \?, to match a slash (\) use \\.


Addressing the Screen

Several macro features use addresses to describe areas on the VT page and history buffer area.

These include the macro commands SetSelection, GetSelection, ScreenChanged, ScreenMatch, GetCursor, Screen, and ScreenRead, and any macros invoked by a mouse action (Mouse dialog box).

The following illustrates how Row and Page are used by these commands.

------------------------------------------------------------

Row -n

History Area
The rows are numbered as an extension of page 1

Row 0

------------------------------------------------------------

Row 1

Page 1

Row 24 (or page length)

------------------------------------------------------------

Row 1

Page 2

Row 24 (or page length)

------------------------------------------------------------

. . .

. . .

------------------------------------------------------------


DDE (Dynamic Data Exchange)
DDE (Dynamic Data Exchange) Overview

KEA! supports Dynamic Data Exchange (DDE), a Windows-defined protocol for transferring data between Windows applications. To use DDE, both applications must support it. What you can do using DDE depends on the capabilities of the applications, and how they support DDE.

Terminology

DDE Conversation between Client and Server

DDE defines a data exchange in terms of a conversation. An application initiates the conversation, exchanges data with another application, and ends the conversation. The initiating application is the DDE client; the responding application is the DDE server.

Application Name

The client must use the server's application name in the request for a conversation. DDE generally uses the standard application name as the DDE name. For example, DDE uses Excel for Excel, WinWord for Word for Windows, and KEAVT for KEA!. Because you can run several copies of KEA! concurrently, there is a DDE function to change the application name to differentiate the copies. There is also a DDE function to get a list of the other currently active DDE server applications.

Topic and Item

Topic and Item further define the DDE conversation. Topic groups types of requests, and Item defines the specific request. Most DDE servers implement a topic named System. Other topics are application specific. For example, KEA! implements System and Macro topics.

KEA! Capabilities

KEA! can act as a DDE client or server.

As a client, a KEA! macro can start and control other applications. It can make them supply data, and accept data and commands, according to the other application's abilities.

As a server, a KEA! macro can supply data automatically to other applications. It also can accept data and macro commands to execute from other applications. You can use a KEA! macro as a specialized server.

Microsoft's DDE text format standard specifies that applications cannot send strings containing binary null across DDE. Therefore, when KEA! encounters a null in a string sent or received using DDE, it truncates the string at the null.

Some DDE functions are for use as a client, some as a server, and a few for use in both circumstances. Most are internal functions. However, a few external functions are included as macro files.

  DDE Client Interface

  DDE Server Interface

  DDE Return Codes


DDE Client Interface

KEA! can act as a DDE client only when executing a macro. DDE provides low and high level commands to the macro.

The low level commands give the macro more control over the conversation. They are more efficient when many transactions will occur on a link because the client needs to initiate the conversation only once. The low-level functions are built into the macro language.

Low Level Functions

DDE_Advise( Channel, item, results )

DDE_Ended( Channel )

DDE_Error( Channel )

DDE_Execute( Channel, commands, timeout, results )

DDE_Initiate( app, topic, appfile )

DDE_Message( Channel )

DDE_Poke( Channel, item, value )

DDE_Query( app, topic )

DDE_Request( Channel, item )

DDE_Terminate( Channel )

DDE_Timeout( Channel, value )

The high-level functions are macros that use the low-level built-in DDE functions. They make it easy to send and receive single values without setting up and taking down a conversation.

The high-level functions are copied into your KEA! directory during installation. If you keep your macros in this directory, you can use these high-level functions directly. Otherwise, you should copy these macros to your own macro directory.

When you use the high level functions, DDE puts the last DDE error code and message into the global variables _ddeAErr and _ddeAMsg, respectively, for access by the calling functions.

High Level Functions

DDE_Get( app!topic, item, timeout )

DDE_Run( app!topic, commands, timeout )

DDE_Send( app!topic, item, value, timeout )


DDE Server Interface

The DDE server interface uses an application's standard name as the DDE name. DDE uses KEAVT for KEA!. You can change the application name by calling DDE_Setapp.

A server macro establishes its own topic. The usual KEA! topic is Macro. However, the standard DDE System topic is also supported.

System Topic

All DDE servers should support the System topic to provide a way for a DDE client to learn the server's current state and what it can do. The KEA! System topic supports the following items:

Sysltems

Returns a list of the item names you can use with the System topic. The item names supported are SysItems, Topics, Formats, Status, and ReturnMessage.

Topics

Returns a list of the supported topic names. KEA! supports System and Macro.

Formats

Returns a list of the supported formats. KEA! supports only Text.

Status

Returns the status of the server as a string containing one of the following values:

0	Server ready, no problems.

1	Server disabled (very hard to get considering disabled does not allow server conversations).

ReturnMessage

Returns the outcome of the last DDE transaction as a string.

Macro Topic

The items KEA! supports are strings that form simple macro expressions. A variable name by itself is an expression, so you can use this interface for querying and setting variables. Expressions add the power to call any macro function, such as Screen( page, row, col, len ) which extracts data from the server's emulation screen.

The client application can change the value of a variable at the server using DDE_Poke. It can ask the server to send it a value whenever a variable changes using DDE_Advise. In both cases, you must use a simple variable name as the expression. The variable name can include an array member reference, but not a whole array.

The client application can ask for the current value of an expression using DDE_Request, as long as the expression does not involve a wait (as in a macro When statement). For example, a client application could issue a DDE_Request( ..., "Screen(page, row, col, len)" ). This returns the corresponding data from the server's emulation screen.

The client application can also use the DDE_Execute or DDE_Run functions to execute commands at the server. The format of these commands differs slightly from the standard macro format. Each statement must be enclosed in square brackets [ ]. If you need to execute a large macro, you should save the macro in a file and use "[macro_name( )]" as the argument to the function.

If the client application uses the DDE Execute function to execute a macro that contains the Continue control statement outside of a Begin..When..End, For..In..End, or While..End construct, when the macro has executed to the point of the Continue, KEA! will send the DDE Ack message that the macro has completed successfully.

Server Functions

You can write a macro that establishes itself as a specialized DDE server.

Because KEA!'s purpose is communication with a host, a DDE client application talking to KEA! typically wants access to host data. In many cases, this is more complex than the simple preceding examples, because it is necessary to control the host more closely. The appropriate way to do this is to run a macro that controls the host, and accepts data or commands from the DDE client and sends data results to it. You use the following functions to have such a macro communicate with a DDE client:

DDE_Accept( topic, results )

DDE_Data( Channel, item, data )

DDE_Enable( value )

DDE_Error( Channel )

DDE_Message( Channel )

DDE_Reply( Channel, rc, data )

DDE_Setapp( name )

DDE_Terminate( Channel )

DDE_Timeout( Channel, value )


DDE Return Codes

Most DDE functions return True or False to indicate success and failure respectively. You can access a detailed application return code by calling the DDE_Error function. DDE defines some useful constants for parsing the returned value from a DDE_Error function. These include:

0	DDErc_ack

256	DDErc_nak

512	DDErc_busy

1024	DDErc_error

2048	DDErc_fatal

The possible values and their interpretations are:

0 to 255	Positive ack with internal return code of 0 to 255 used as desired by the application.

256 to 511	Negative ack with internal return code of 0 to 255.

768 to 1023	Negative ack + busy with internal return code of 0 to 255.

1024	Failed to send message.

1025	Timed out.

1026	Outstanding transaction terminated because conversation terminated.

1027	Attempted to send data with no corresponding active advise. This error can occur when DDE queues an unadvise for a macro event to finish.

1028	Invalid handle. This error can occur when DDE queues a terminate for a macro event to finish.

3072+	Errors which will abort a running macro.

3077	Not enough memory.

3078	DDE_Ended already issued for this conversation.

3079	Invalid response to advise; the options do not match the advise. This usually means the advise and the DDE_Data do not agree on the DEFER option.

3080	DDE_Accept topic already in use by another accept.

3081	DDE_Query does not support both application and topic unspecified or both specified. You must specify one, and leave the other null.

3082	Protocol error. Reply out of sequence, using a server-only function on a client conversation, or client-only on a server; garbled arguments.

3090	Missing or too many arguments to DDE_xxx macro function.

3091	Application!topic argument to DDE_xxx macro function malformed.

You can access the descriptive message associated with each return code by calling DDE_Message.


KEA! Edit File Menu
KEA! Edit Command Reference - File menu

New

Opens a new window for programming of a macro. The new window contains the KEA! name and version number as a comment on the first line. The window is named Untitled until you save it with a filename. You can have several files open at the same time. You use the Window menu commands to switch between them.

Open...

Displays the Open File dialog box. You select a file from the list under File Name, or enter a new filename to create a new macro file. You can select the filename extension to change the list of displayed files under File Name. By default, files with the .KTM extension are displayed. You can change the drive and directory in which to look for files with the specified extension. You can edit any text file.

Close

Closes the currently active window. If you made changes to the file, you are asked if you want to save the changed file before closing. If you choose Yes, the file is saved with the changes you made, and the window is closed.

Save

Saves the current file, including any changes you made.

Save As...

Displays the Save File dialog box. You can specify a filename, extension, and the drive and directory in which to save the file. When you choose OK, the currently open file is saved using the information you supplied.

Print

Displays the Print dialog box. You can specify how much of the file to print, the print quality, how many copies to print, whether to collate the copies, and whether to print to a file. When you choose OK, the currently open file is printed.

Printer Setup...

Displays the Printer Setup dialog box. You can choose the printer, orientation, and paper size and source.

Exit

Closes the currently open file and window, and exits KEA! Edit. If you made changes to any of the open files, you are asked if you want to save the changes before closing the file. Choose Yes to save the file with the changes you made, close the window, and exit.


KEA! Edit Edit Menu
KEA! Edit Command Reference - Edit menu

Undo (CTRL+Z)

Undoes the last change you made.

Cut (CTRL+X)

Removes the selected text from the current window, and puts it on the Clipboard.

Copy (CTRL+C)

Puts a copy of the selected text onto the Clipboard.

Paste (CTRL+V)

Pastes the Clipboard text into the current window starting at the current cursor position.

Delete (DEL)

Removes the selected text from the current window, but does not put it on the Clipboard.

Select All

Selects the entire document.

Find...

Displays the Find dialog box. You enter the character string you want to locate. You can select whether to make the search case sensitive. You also can specify the direction in which you want to search for the character string; Next searches to the end of the document, Previous to the beginning. When the character string is located, KEA! Edit returns to the document and highlights the located string.

Next

Searches for next occurrence of the character string you specified in the Find dialog box.

Previous

Searches for previous occurrence of the string you specified in the Find dialog box.


KEA! Edit Options Menu
KEA! Edit Command Reference - Options menu

Tabs

Displays a cascading menu from which you select the number of spaces between tab stops.

Save backup file

Select this option to create a copy (using the .BAK extension) when you save an edited file.

Debug Keys

Displays a cascading menu from which you select the keyboard mapping for the debug functions. Choose from:

Standard	Follow the Code View convention for all keys except use SHIFT+F8 for the Step Function key. KEA! Edit uses this key combination because Windows uses F10, as well as ALT, as the standard key to access the menu bar.

Code View	Use the Code View key conventions including using F10 for the Step Function key, overriding normal Windows use.

Show ToolBar

Displays a bar containing buttons for frequently used editor and debug functions.

Languages

(Available only in KEA! International versions.) Display a cascading menu from which you specify the language for menus, commands, dialog boxes, and system messages. Although you specify the language to use during installation, you can use the Languages option to change it at any time. Choose from:

English

Français (French)

Deutsch (German)

Español (Spanish)

Italiano (Italian)

Português (Portuguese)


KEA! Edit Debug Menu
KEA! Edit Command Reference - Debug menu

Debug Mode

Puts KEA! Edit into debug mode. If you selected Variables from the Debug menu, the Variables window is displayed above the window containing your macro text.

Variables

Displays the Variables window, containing the macro variables and their values while you debug the macro. You can watch the values change while stepping or tracing the macro. KEA! Edit displays the final values of global variables when the macro finishes.

Macro Stack...

Displays called functions.

Pause (F4)

Stops macro execution until you start it again.

Go (F5)

Starts macro execution from the beginning, or from where it paused.

Quit (F6)

Stops macro execution.

Trace (F7)

Starts macro execution highlighting each statement as it executes. It also updates the values in the Variables window. Trace runs more slowly than Go.

Step Into (F8)

Single-steps the execution of the current macro, and any called macros. Step Into highlights the currently executing statement, and pauses until you press Step Into again.

Step (SHIFT+F8 or F10)

Single-steps the execution of the current macro only. If the current macro calls another macro, Step treats the called macro as a single step, and executes it to completion. Step highlights the currently executing statement, and pauses until you press Step again. Whether you use SHIFT+F8 or F10 depends on whether you selected Standard or Code View from the Debug Keys cascading menu. You access that menu by choosing Debug Keys from the Options menu.


KEA! Edit Window Menu
KEA! Edit Command Reference - Window menu

Tile

Arranges the open windows side-by-side. You cannot use this option in debug mode.

Cascade

Arranges the open windows in an overlapping fashion. You cannot use this option in debug mode.

If you have multiple windows open, you can choose which window to make current from a list of the open windows.


KEA! Edit Help Menu
KEA! Edit Command Reference - Help menu

Contents

Displays the list of topics for the KEA! macro language.

How to Use Help

Displays a list of topics for help on using the Windows Help facility.

About KEA! Edit

Displays an information box containing the KEA! Edit version number and copyright statement.


Example: Sign-on

This example illustrates a simple sign-on to a host computer.

CR = "^M"

Send( CR )

Match( "Username:" )

Wait( 2 )

Send( "jsmith" + CR )

The following example shows a more complex sign-on procedure.

CR = "^M"

Send( CR )	// solicit host prompt

Begin

  When Match( "Username:" )

    Wait( 2 )

    Send( "jsmith" + CR )	// send your username

    Continue

  When Match( "Password:" ) // exit when password prompt received

    Break

  When Wait( 100 )

    MsgBox( "Login timeout, check your connection and try again",

        BUTTON_OK )

End


Example: BBS Dial-in

This example shows a macro that dials into a remote service such as a bulletin board.

CR = "^M"

Connect( )

cont = Button_Yes

While cont = Button_Yes

  Send( "ATH" + CR )

    Begin

      When Match( "OK" )

        Wait( 2 )

        // if you want the phone number as part of the macro, then

        // uncomment the next line and remove the input line

        //     phone = "5551212"

        phone = Input( "enter the phone number to dial" )

        Send( "ATDT " + phone + CR )

        Continue

      When Match( "CONNECT" )

        Wait( 5 )

        Send( CR )	// prompt for host after connection is made

      When Wait( 300 ) // 30 sec timeout

        cont = MsgBox( "Timeout during dialing, try again?",

            Button_Yes + Button_No, Button_Yes )

    End // begin

End // while


Example: Word DDE

The following simple example, written in Microsoft WordBasic, shows how you can use Microsoft Word as a client, and KEA! as a server.

Sub Main

quote$ = Chr$(34)                    ' quote character

Chdir("D:\KEAVT")                    ' Change to the KEA! directory

Shell "KEAVT.EXE KEAVT.KTC"         ' Run KEA! externally

ChanNum = DDEInitiate("KEAVT","MACRO")  ' Initiate conversation

DDEPoke ChanNum, "Fonts", "10Wide"  ' Send a new value for "Fonts"

A$ = DDERequest$(ChanNum,"Fonts")  ' Request current value of Fonts

Print "Font Size : ",A$

CapFile$ = "CAPTURE.TXT"

Cmd$ = "[PlayBack("+quote$+CapFile$+quote$+")]"

                                ' note use of quotes

DDEExecute ChanNum, Cmd$        ' Execute a KEA! macro function

DDEExecute ChanNum, "MyFunc()"

             ' Run a KEA! external macro function

DDETerminate ChanNum            ' Terminate conversation

DocClose

FileExit

End Sub


Example: Excel DDE

The following example, written in KEA!'s macro language, shows how you can use KEA! as the client, and Excel as the server.

// Macro : DDETTL.KTM

//

// 1. Get a previous quarter's sales total from Excel

// 2. Send a this quarter's new sales total to Excel.

// 3. Display current, previous, and year to date totals in KEA!

CR = "^M^J"

TAB = "^I"

Clear( )

// Initiate conversation with Excel

Channel = DDE_Initiate( "EXCEL", "SYSTEM", "D:\EXCEL\EXCEL.EXE" )

DDE_Execute( Channel, "[OPEN(\"REVENUES.XLS\")]", 30 )

// Initiate conversation with the specific spreadsheet

// include the path of the spreadsheet if the file resides

// in a directory other that the KEA! directory

DDE_Terminate( Channel )

Channel = DDE_Initiate( "EXCEL", "REVENUES.XLS" )

// Define Excel spreadsheet cells

TotalCell1 = "R5C2"  // sales total for quarter 1

TotalCell2 = "R5C3"  // sales total for quarter 2

DDE_Request( Channel, TotalCell1 ) // get 1st quarter sales totals

Total1 = Int( SubStr(Result, 2) )

// New total for this quarter (could be captured from the host)

AddSales = 3587

Total2 = AddSales

// Calculate Year to date total

TotalYTD = AddSales + Int( SubStr(Total1, 2) ) // strip "$",

                                             // convert to numeric

// Display old and new values

Echo( "Sales This Period    Sales Last period    Year to Date" + CR + CR )

Echo( "-----------------    -----------------    ---------------" + CR )

Echo( "$" + Total2 + TAB + TAB + TAB + Total1 + TAB + TAB + TAB + "$" + TotalYTD )

// Update the spreadsheet with new 2nd quarter figure

DDE_Poke( Channel, TotalCell2, ("$" + STR(Total2)) )

DDE_Terminate( Channel )

// Cleanup and exit Excel

Channel = DDE_Initiate( "EXCEL", "SYSTEM", "D:\EXCEL\EXCEL.EXE" )

DDE_Execute( Channel, "[CLOSE(0)][APP.MINIMIZE()]", 45 )

                                         // close file


Example: DDE Server

// Version KEA! 4.00

// Sample DDE server script

// This script sets up KEA! as a DDE server, allowing

// multiple links to a single DDE conversation. The macro

// uses two arrays: AdvItem[] and AdvOptn[] which contain

// the items and options for each separate advise.  Data

// is sent to the client every time a timeout event is

// triggered.  In this case, each link is sent either the

// time or the date depending on the Item specified in the

// advise.

Var Request           // array filled in by DDE_Accept

Var AdvItem = False   // array of advise items

Var AdvOptn = False   // array of advise options

Var Conversation = 0

Var nl = "^M^J"

Var i

DDE_Enable( True )

Clear( ) // clear so that we can see the echoes

Begin

  Do

    Suspend( ) // return control to KEA!

  When Timeout( 50 ) // update every 5 seconds

    If AdvItem

      For i In AdvItem

        If AdvOptn[i] = "DEFER"

          // notify client of change

          DDE_Data( Conversation, AdvItem[i] )

        ElseIf AdvItem[i] = "Time"

          // send time(HH:MM) to client

          DDE_Data( Conversation, AdvItem[i],

              SubStr( Time(), 1, 5 ) )

        ElseIf AdvItem[i] = "Date"

          // send date to client

          DDE_Data( Conversation, AdvItem[i], Date() )

        End

      End

    End

    Continue

  // Wait for a command connection from client

  When DDE_Accept( "MacroServer", Request )

    If Request.Type = "CONNECT"

      Echo( "Client initiated conversation on channel " +

          Request.Channel + nl )

      DDE_Enable( False )  // Prevent other conversations

      Conversation = Request.Channel

    ElseIf Request.Type = "ADVISE"

      Echo( "Client advised for " + Request.Item +

          " with options \"" + Request.Options + "\"" + nl )

      If Request.Item = "Time" or Request.Item = "Date"

        // allow multiple advises per client

        AdvItem[Request.Item] = Request.Item

        AdvOptn[Request.Item] = Request.Options

        DDE_Reply( Request.Channel, 0 )    // Accept

        Echo( "..accepted" + nl )

      Else

        DDE_Reply( Request.Channel, 256 )  // Reject

        Echo( "..rejected" + nl )

      End

    ElseIf Request.Type = "UNADVISE"

      Echo( "Client unadvised for " + Request.Item + nl )

      If Request.Item = 0               // cancel all advises

        AdvItem = False

        AdvOptn = False

        DDE_Reply( Request.Channel, 0 )    // Accept

        Echo( "..accepted" + nl )

      ElseIf AdvItem[Request.Item]

        AdvItem[Request.Item] = False

        AdvOptn[Request.Item] = False

        DDE_Reply( Request.Channel, 0 )    // Accept

        Echo( "..accepted" + nl )

      Else

        DDE_Reply( Request.Channel, 256 )  // Reject

        Echo( "..rejected" + nl )

      End

    ElseIf Request.Type = "EXECUTE"

      Echo( "Client executed \"" + Request.Value + "\"" + nl )

      DDE_Reply( Request.Channel, 256 )    // Reject

    ElseIf Request.Type = "POKE"

      Echo( "Client poked " + Request.Item + " with value \"" +

        Request.Value + "\"" + nl )

      DDE_Reply( Request.Channel, 0 )      // Accept

    ElseIf Request.Type = "REQUEST"

      Echo( "Client requested " + Request.Item + nl )

      If Request.Item = "Time"

        // send time(HH:MM) to client

        DDE_Reply( Request.Channel, 0, SubStr(Time(), 1, 5) )

      ElseIf Request.Item = "Date"

        // send date to client

        DDE_Reply( Request.Channel, 0, Date() )

      Else

        DDE_Reply( Request.Channel, 256 )  // Reject

        Echo( "..rejected" + nl )

      End

    ElseIf Request.Type = "TERMINATE"

      Echo( "Client terminated" + nl )

      DDE_Terminate( Request.Channel )

      DDE_Enable( True )

      Break

    End

    Continue  // Stay until client terminates

End


Example: Kermit File Transfer

// Server mode upload

Var Info

CR = "^M"

CRLF = "^M^J"

server = False   // local flag used for testing state of Kermit

                 // server mode

// Get file name

PC_File = Input( "Enter the name of a file to send to the host" )

// Start Kermit on Host

Send( CR )                  // try to solicit a host response

Begin

  When Match( "$" )         // matches on $ if VAX in DCL mode

    Send( "kermit" + CR )

    Continue

  When Match( "C-Kermit>" ) // matches when Kermit is running

    Send( "Server" + CR )

    Continue

  When Match( "server", 1 ) // Kermit sends when server starts

    Wait( 2 )

    server = true           // set flag that server started

  When Wait( 300 )          // 30 second timeout

End

If server      // test if Kermit started

  // configure KEA! for remote server Kermit

  FileTransfer.KermitOptions( RemoteKermit = "Server" )

  Begin

    // concurrent statements

    Echo( "Bytes left to transfer" + CRLF )

    TransferTransmit( PC_File )   // send file to the VAX

    When TransferProgress( Info )

      Echo( Info.Size - Info.Bytes + CRLF ) // remaining bytes

      Continue

    When Wait( 300 )      // 30 second timeout

      MsgBox( "Kermit transmission timeout." )

  End

  TransferCommand( "Finish" )         // tell server to finish

  Match( "C-Kermit>", Timeout = 100 ) // wait for Kermit to finish

  If Result = ""          // if server doesn't respond

    Kermit.Quit( )        // force KEA! to exit its Kermit

    MsgBox( "Kermit server didn't respond to FINISH request" )

  Else

    Send( "exit" + CR )   // terminate VAX Kermit

  End

// now should be back at VMS $ prompt.

Else

  MsgBox( "Kermit failed to start." )

End


Example: Read/Write in a PC File

Consider a DOS text file ABC.TXT containing a list of names separated by newline characters:

  JACK<CRLF>

  MARY<CRLF>

  ...

  LISA<CRLF><^Z>

The following example first checks whether the file ABC.TXT exists and whether its write attribute is set, then opens the file for reading and writing. The macro then reads each line of the file and outputs the corresponding name until it reaches the end of the file. At this point the macro writes a new entry and closes the file.

CRLF = "^M^J"

FileType = FileExists( "C:\ABC.TXT" )

If FileType                         //  if file exists...

  If( FileType BitAnd Attr_Write )  //  ...and has write attribute

    FileHandle = FileOpen( "C:\ABC.TXT", File_ReadWrite )

  Else

    MsgBox( "File is write protected" )

    Return  // exit macro

  End

Else

  MsgBox( "File does not exist" )

  Return    // exit macro

End

Echo( "Names on file:" + CRLF )

While Not FileEnd( FileHandle )

  Names = FileRead( FileHandle ) // read the existing records

  Echo( Names + CRLF )

end

NewName = "JANE"

FileWrite( FileHandle, NewName ) // append new record

                                 // to end of file

FileClose( FileHandle )          // close file

Note  Changes to the file will not take effect until the macro issues a FileClose.


Definition of PRODNAME bookmark:KEA!

Definition of SHORTNAME bookmark:KEA!

Definition of EDITNAME bookmark:KEA! Edit


List of Macro Functions - Alphabetic
Macro Functions and Statements

A - B

Abort

Abs

ActivateApp

ArraySize

Asc

AutoConnect

Begin Dialog...End

Begin...When...End

Break

Brk

Button

ButtonPad

ButtonPad.DeleteAll

Buttons

C

Cancel

CancelButton

CancelEnable

Capture

CaptureSetup

CheckBox

Chr

Clear

ClearComm

ClearHistory

Close

ClosePrintJob

ComboBox

Commands?

Communications

Communications.Proxies

Communications.Setup

KEAlink MSU

LAT

Modem

NetWare for LAT

Serial

Telnet

Telnet  Advanced

Telnet  Advanced.Special

Connect

Continue

Control

ControlSet

Copy

CopySpecial

CursorAt

CursorMove

D

Date

DDE_Accept

DDE_Advise

DDE_Data

DDE_Enable

DDE_Ended

DDE_Error

DDE_Execute

DDE_Get

DDE_Initiate

DDE_Message

DDE_Poke

DDE_Query

DDE_Reply

DDE_Request

DDE_Run

DDE_Send

DDE_SetApp

DDE_Terminate

DDE_Timeout

Decode

DefaultButton

Dialog

Disconnect

Disconnected

Display

Display.Attributes

Display.Attributes.Default

Display.Colors

Display.Colors.CurrentIndexToFactory

Display.Colors.CurrentIndexToSaved

Display.Colors.ToFactoryColors

Display.Colors.ToSavedColors

Display.Tabs

Display.Tabs.Default

DisplaySize

DropDownBox

E

Echo

Edit

EditBox

EnableHistory

Encode

EnlargeFont

ErrorLevel

Exit

ExitAll

F

FileClose

FileCopy

FileCreateDir

FileDelete

FileDir

FileEnd

FileExists

FileGetDrives

FileGetElidedName

FileGetFromPath

FileGetPos

FileMove

FileOpen

FileRead

FileRemoveDir

FileRename

FileSetPos

FileTransfer

FileTransfer.AsciiOptions

FileTransfer.FTPOptions

FileTransfer.KermitOptions

FileTransfer.KermitOptions.Advanced

FileTransfer.TextFileOptions

FileTransfer.TextFileOptions.Translation

FileTransfer.XmodemOptions

FileTransfer.YmodemOptions

FileTransfer.ZmodemOptions

FileValidateName

FileWrite

Fonts

For...In...End

Format

Function

G - H

General

GetCursor

GetDirectory

GetEnv

GetIni

GetSelection

GetVersion

Global

Graphics

GroupBox

HelpKeyword

History

HoldScreen

HorizontalScrollBar

HostName

I - K

If...Elseif...Else...End

Input

InStr

Int

IsConnected

Keyboard

Keyboard.Mapping

Keyboard.Mapping.DeleteAll

Keyboard.UDKs

Keyboard.UDKs.Clear

KeyStroke

L - O

Languages

Len

Links

ListBox

Local

LocalEdit

LogBox

LogDelete

LogOpen

Lowercase

MacroOptions

Match

Maximize

Menu

Menus

Menus.Delete

Message

MeterBox

Minimize

Mouse

Mouse.DeleteAll

MRUList

MsgBox

NextSession

OkButton

OpenLayout

P - R

Paste

PlayBack

PlaySound

PreviousSession

Print

Printer

PrintSetup

RadioBox

Read

Receive?

ReduceFont

Reset

Restore

RestoreSessions

Return

Run

S

Save

SaveAs

SaveLayout

Screen

ScreenChanged

ScreenMatch

ScreenRead

Send

SendKey

SetDirectory

SetIni

SetSelection

Snapshot

StatusBar

Str

SubStr

Suspend

SystemTime

T - W

Terminal

TextBox

Time

Timeout

Title

Toolbar

TransferAbort

TransferCommand

TransferProd

TransferProgress

TransferReceive

TransferTransmit

Transmit?

Uppercase

Var

VerticalScrollBar

VTKeyboard

VTStatusLine

Wait

While...End

WindowList


List of Macro Functions - by Category
Macro Functions and Statements

 Appearance of the KEA! Window

 Capture, Selection, Playback, History

 Communication

 Conversions and Strings

 Dialog Box

 Dynamic Data Exchange

 Emulation Functions

 File Management

 File Transfer

 Host Interaction

 Keyboard, Mouse, SmartPad, Menus

 Macro Statements

 Printing

 Save/Restore Configuration


Functions in the category "Window Appearance"
Macro Functions and Statements

 Appearance of the KEA! Window

ActivateApp

Clear

Display

Display.Attributes

Display.Attributes.Default

Display.Colors

Display.Colors.CurrentIndexToFactory

Display.Colors.CurrentIndexToSaved

Display.Colors.ToFactoryColors

Display.Colors.ToSavedColors

Display.Tabs

Display.Tabs.Default

DisplaySize

EnlargeFont

Fonts

HoldScreen

HorizontalScrollBar

Languages

Maximize

Menu

Menus

Menus.Delete

Message

Minimize

ReduceFont

Restore

StatusBar

Title

Toolbar

VerticalScrollBar

VTStatusLine

 Capture, Selection, Playback, History

 Communication

 Conversions and Strings

 Dialog Box

 Dynamic Data Exchange

 Emulation Functions

 File Management

 File Transfer

 Host Interaction

 Keyboard, Mouse, SmartPad, Menus

 Macro Statements

 Printing

 Save/Restore Configuration


Functions in the category "Capture, Selection, Playback, History"
Macro Functions and Statements

 Appearance of the KEA! Window

 Capture, Selection, Playback, History

Capture

CaptureSetup

ClearHistory

Copy

CopySpecial

Links

EnableHistory

GetSelection

History

Paste

PlayBack

Read

ScreenChanged

ScreenMatch

ScreenRead

SetSelection

Snapshot

 Communication

 Conversions and Strings

 Dialog Box

 Dynamic Data Exchange

 Emulation Functions

 File Management

 File Transfer

 Host Interaction

 Keyboard, Mouse, SmartPad, Menus

 Macro Statements

 Printing

 Save/Restore Configuration


Functions in the category "Communication"
Macro Functions and Statements

 Appearance of the KEA! Window

 Capture, Selection, Playback, History

 Communication

AutoConnect

ClearComm

Communications.Proxies

Communications

Communications.Setup

KEAlink MSU

LAT

Modem

NetWare for LAT

Serial

Telnet

Telnet  Advanced

Telnet  Advanced.Special

Connect

Disconnect

Disconnected

HostName

IsConnected

Local

MRUList

NextSession

PreviousSession

RestoreSessions

Terminal

WindowList

 Conversions and Strings

 Dialog Box

 Dynamic Data Exchange

 Emulation Functions

 File Management

 File Transfer

 Host Interaction

 Keyboard, Mouse, SmartPad, Menus

 Macro Statements

 Printing

 Save/Restore Configuration


Functions in the category "Conversions and Strings"
Macro Functions and Statements

 Appearance of the KEA! Window

 Capture, Selection, Playback, History

 Communication

 Conversions and Strings

Abs

ArraySize

Asc

Chr

Date

Decode

Encode

Format

GetVersion

InStr

Int

Len

Lowercase

Str

SubStr

SystemTime

Time

Uppercase

 Dialog Box

 Dynamic Data Exchange

 Emulation Functions

 File Management

 File Transfer

 Host Interaction

 Keyboard, Mouse, SmartPad, Menus

 Macro Statements

 Printing

 Save/Restore Configuration


Functions in the category "Dialog Box"
Macro Functions and Statements

 Appearance of the KEA! Window

 Capture, Selection, Playback, History

 Communication

 Conversions and Strings

 Dialog Box

Layout

Begin Dialog...End

Button

CancelButton

CheckBox

ComboBox

DefaultButton

DropDownBox

EditBox

GroupBox

ListBox

LogBox

MeterBox

OkButton

RadioBox

TextBox

Processing

Control

ControlSet

Fixed Boxes

Input

MsgBox

 Dynamic Data Exchange

 Emulation Functions

 File Management

 File Transfer

 Host Interaction

 Keyboard, Mouse, SmartPad, Menus

 Macro Statements

 Printing

 Save/Restore Configuration


Functions in the category "Dynamic Data Exchange"
Macro Functions and Statements

 Appearance of the KEA! Window

 Capture, Selection, Playback, History

 Communication

 Conversions and Strings

 Dialog Box

 Dynamic Data Exchange

DDE_Accept

DDE_Advise

DDE_Data

DDE_Enable

DDE_Ended

DDE_Error

DDE_Execute

DDE_Get

DDE_Initiate

DDE_Message

DDE_Poke

DDE_Query

DDE_Reply

DDE_Request

DDE_Run

DDE_Send

DDE_SetApp

DDE_Terminate

DDE_Timeout

Links

 Emulation Functions

 File Management

 File Transfer

 Host Interaction

 Keyboard, Mouse, SmartPad, Menus

 Macro Statements

 Printing

 Save/Restore Configuration


Functions in the category "Emulation Functions"
Macro Functions and Statements

 Appearance of the KEA! Window

 Capture, Selection, Playback, History

 Communication

 Conversions and Strings

 Dialog Box

 Dynamic Data Exchange

 Emulation Functions

Clear

Display

Display.Tabs

Display.Tabs.Default

Graphics

Keyboard

Keyboard.UDKs

Keyboard.UDKs.Clear

LocalEdit

Reset

Terminal

 File Management

 File Transfer

 Host Interaction

 Keyboard, Mouse, SmartPad, Menus

 Macro Statements

 Printing

 Save/Restore Configuration


Functions in the category "File Management"
Macro Functions and Statements

 Appearance of the KEA! Window

 Capture, Selection, Playback, History

 Communication

 Conversions and Strings

 Dialog Box

 Dynamic Data Exchange

 Emulation Functions

 File Management

FileClose

FileCopy

FileCreateDir

FileDelete

FileDir

FileEnd

FileExists

FileGetDrives

FileGetElidedName

FileGetFromPath

FileGetPos

FileMove

FileOpen

FileRead

FileRemoveDir

FileRename

FileSetPos

FileValidateName

FileWrite

GetDirectory

GetEnv

GetIni

LogDelete

LogOpen

SetDirectory

SetIni

 File Transfer

 Host Interaction

 Keyboard, Mouse, SmartPad, Menus

 Macro Statements

 Printing

 Save/Restore Configuration


Functions in the category "File Transfer"
Macro Functions and Statements

 Appearance of the KEA! Window

 Capture, Selection, Playback, History

 Communication

 Conversions and Strings

 Dialog Box

 Dynamic Data Exchange

 Emulation Functions

 File Management

 File Transfer

Commands?

FileTransfer

FileTransfer.AsciiOptions

FileTransfer.FTPOptions

FileTransfer.KermitOptions

FileTransfer.KermitOptions.Advanced

FileTransfer.TextFileOptions

FileTransfer.TextFileOptions.Translation

FileTransfer.XmodemOptions

FileTransfer.YmodemOptions

FileTransfer.ZmodemOptions

Receive?

TransferAbort

TransferCommand

TransferProd

TransferProgress

TransferReceive

TransferTransmit

Transmit?

 Host Interaction

 Keyboard, Mouse, SmartPad, Menus

 Macro Statements

 Printing

 Save/Restore Configuration


Functions in the category "Host Interaction"
Macro Functions and Statements

 Appearance of the KEA! Window

 Capture, Selection, Playback, History

 Communication

 Conversions and Strings

 Dialog Box

 Dynamic Data Exchange

 Emulation Functions

 File Management

 File Transfer

 Host Interaction

CursorAt

CursorMove

Echo

GetCursor

Match

Screen

ScreenChanged

ScreenMatch

ScreenRead

Send

SendKey

 Keyboard, Mouse, SmartPad, Menus

 Macro Statements

 Printing

 Save/Restore Configuration


Functions in the category "Keyboard, Mouse, SmartPad, Menus"
Macro Functions and Statements

 Appearance of the KEA! Window

 Capture, Selection, Playback, History

 Communication

 Conversions and Strings

 Dialog Box

 Dynamic Data Exchange

 Emulation Functions

 File Management

 File Transfer

 Host Interaction

 Keyboard, Mouse, SmartPad, Menus

ButtonPad

ButtonPad.DeleteAll

Buttons

Keyboard

Keyboard.Mapping

Keyboard.Mapping.DeleteAll

Keyboard.UDKs

Keyboard.UDKs.Clear

KeyStroke

Menu

Menus

Menus.Delete

Mouse

Mouse.DeleteAll

VTKeyboard

 Macro Statements

 Printing

 Save/Restore Configuration


Functions in the category "Macro Statements"
Macro Functions and Statements

 Appearance of the KEA! Window

 Capture, Selection, Playback, History

 Communication

 Conversions and Strings

 Dialog Box

 Dynamic Data Exchange

 Emulation Functions

 File Management

 File Transfer

 Host Interaction

 Keyboard, Mouse, SmartPad, Menus

 Macro Statements

Control Statements

Begin...When...End

Break

Continue

For...In...End

Function

Global

If...Elseif...Else...End

Return

Var

While...End

Controlling Execution

Abort

Brk

Cancel

CancelEnable

Close

ErrorLevel

Exit

ExitAll

Suspend

Timeout

Wait

Invoking

Edit

HelpKeyword

MacroOptions

PlaySound

Run

 Printing

 Save/Restore Configuration


Functions in the category "Printing"
Macro Functions and Statements

 Appearance of the KEA! Window

 Capture, Selection, Playback, History

 Communication

 Conversions and Strings

 Dialog Box

 Dynamic Data Exchange

 Emulation Functions

 File Management

 File Transfer

 Host Interaction

 Keyboard, Mouse, SmartPad, Menus

 Macro Statements

 Printing

ClosePrintJob

Print

Printer

PrintSetup

 Save/Restore Configuration


Functions in the category "Save/Restore Configuration"
Macro Functions and Statements

 Appearance of the KEA! Window

 Capture, Selection, Playback, History

 Communication

 Conversions and Strings

 Dialog Box

 Dynamic Data Exchange

 Emulation Functions

 File Management

 File Transfer

 Host Interaction

 Keyboard, Mouse, SmartPad, Menus

 Macro Statements

 Printing

 Save/Restore Configuration

General

OpenLayout

Save

SaveAs

SaveLayout


Abort (macro function)
Abort

Abort( [Message=]string )

The Abort function stops the current macro, and displays a message box containing the text "Macro error: string". When you write a macro to be called from another macro, you may find this useful to generate a fatal error in the calling macro.

Message   	The text you want to appear in the message box.

Example

If ArgCount > 0

  If Arg[1] = 0 Or Arg[1] > 10

    Abort( "Invalid Argument Received" )

  End

End

The preceding example warns the user of invalid arguments being passed to a macro.


Abs (macro function)
Abs

Abs( [Value=]integer )

The Abs function returns the absolute value of an integer.

Examples

AbsValue1 = Abs( -234 )

AbsValue2 = Abs( 234 )

Both functions return the value 234.


ActivateApp (macro function)
ActivateApp

ActivateApp( )

The ActivateApp function brings the KEA! application window to the foreground.

Example

ActivateApp( )


ArraySize (macro function)
ArraySize

ArraySize( [List=]array )

The ArraySize function returns the number of elements in the given array.

List   	an array

Example

g[1][1] = "one one"

g[1][2] = "one two"

g[1][3] = "one three"

g[2][1] = "two one"

g[2][2] = "two two"

g[3] = "three"

SizeOfG = ArraySize( g )

SizeOfGOne = ArraySize( g[1] )

In the preceding example, both SizeOfG and SizeOfGOne would be 3.


Asc (macro function)
Asc

Asc( [String=]string )

The Asc function returns the decimal character code equivalent of the first character in the string.

This function is complementary to Chr( ).

Examples

DecimalValue = Asc( "A" )

DecimalValue = Asc( "ABC" )

Both functions return the value 65.


AutoConnect (macro variable)
AutoConnect

AutoConnect = boolean

The AutoConnect variable specifies whether to automatically connect a port when you start KEA! or change a port configuration. Values are:

0	Do not connect automatically.

1	Make the connection automatically.

Changing this variable is equivalent to selecting the Auto Connect command under the Connection menu.

Examples

AutoConnect = True

Causes an automatic connect when KEA! starts or a port is configured.

B = Autoconnect

Records the current setting of the AutoConnect variable.


Begin Dialog..End (macro statement)
Begin Dialog...End

Begin Dialog( [[Text =]String], [[NoWait=]Boolean] )

Controls
. . .
[Do
Concurrent statements]

[When Condition
 	Statements]
[When Condition
 	Statements]
. . .
End

Begin Dialog signals the start of a dialog box definition.

Text   	A string to appear in the title bar of the dialog box.

NoWait	Whether the dialog box requires user response. If the dialog box needs user response, set this to False; if the dialog box is presented when KEA! is minimized or in the background, the icon or title bar flashes and beeps. This is the default. Alternatively, if the dialog box never requires user response (for example, a box that merely informs the user "Now printing..."), set this to True; the dialog box never demands attention.

The Controls section defines the controls (buttons and boxes) that appear in your dialog box.

The optional Do section contains the concurrent code, which begins executing as soon as the dialog box is defined. The code continues to execute until a When event occurs, at which point the event takes over.

The optional When section contains the event handlers for the dialog box. The events can be produced by changes to the defined buttons and boxes, or events normally handled by the Begin..When..End structure.


Begin...When (macro statement)
Begin...When...End

Begin
[Concurrent statements]
When Condition
Statements
[When Condition
Statements]
. . .
End

The Begin..When..End control statement allows execution of concurrent statements while waiting for one or more events. Events are generated by some functions when the function completes or other specified conditions are met. If you put such an event-generating function in a When Condition, the accompanying Statements are executed when the event occurs. The following functions generate events:

Control	DDE_Execute	Timeout
CursorAt	Disconnected	TransferCommand
CursorMove	KeyStroke	TransferProgress
DDE_Accept	Match	TransferReceive
DDE_Advise	ScreenChanged	TransferTransmit
DDE_Ended	ScreenMatch	Wait

The macro first evaluates all the event (When) conditions once, in the order in which they occur. Then, it begins execution of the Concurrent statements, if any. If there are no concurrent statements, the macro simply waits until one of the event conditions occurs. If there are concurrent statements, after the concurrent statements complete execution, the macro simply waits until one of the event conditions occurs.

When an event occurs, the macro executes the event statements associated with that When condition. If the macro encounters a Continue in one of the event statements, it continues execution back in the concurrent statements as if the event never happened. If execution hits the end of the event statements or a Break statement, the macro clears all the event conditions, and continues execution after the End statement.

Tip  When you use multiple When Match( ) statements in a Begin..When..End construct, use a When Timeout( ) statement to avoid a deadlock situation if neither the host nor modem respond.

Examples

CR = "^M"

MyName = "MyUserName"

Password = Input( "What is the password?",, Input_Hide )

Send( "ATZ" + CR )               // reset the modem

Begin

  When Match( "OK" )

    Send( "ATDT 5559999" + CR )  // dial phone number

    Continue

  When Match( "CONNECT" )        // watch for connection

    Send( CR )

    Continue

  When Match( "Username :" )     // send username

    Send( MyName + CR )

    Continue

  When Match( "Password :" )     // send password

    Send( Password + CR )

    Continue

  When Match( "$" )   // watch for host prompt

    Break             // break out of loop

  When Wait( 300 )    // if we are still in the loop after 30 sec

    MsgBox( "Timeout occurred.." )

    Break

End

Send( CR )

The preceding macro dials and logs in to a host. It matches on modem and host response. When it matches the host $ prompt or the 30 second Timeout occurs, it continues execution after the End statement.

Begin

  Message( Text = "Looking for disconnect" )

  Wait( 10 )

  Suspend( )

  When Disconnected( )

    MsgBox( Text = "Session disconnected" )

    Continue

End

The preceding example monitors the host connection and reports when the connection breaks. The concurrent statements give control back to the user while KEA! waits for the disconnect condition.


Break (macro statement)
Break

Break

The Break control statement breaks out of a Begin..When..End, For..In..End, or While..End construct. It continues execution after the End statement.

Note  The Break statement is different from the Brk( ) function.

Example

CR = "^M"

Begin

  When Match( "login:" )

    Send( "MYUSERNAME" + CR )

    Continue

  When Match( "password:" )

    Send( "TEXAS" + CR )

    Continue

  When Match( "$" )

    Break        // break out of the loop

End

Send( "KERMIT" + CR )

The preceding example logs a user into his account then breaks out of the Begin..When..End loop when KEA! matches on the host $ prompt. Execution continues after the End statement.


Brk (macro function)
Brk

Brk( )

The Brk function causes the KEA! Edit debug utility to pause a macro at the point where the Brk occurs. Execution pauses only if KEA! Edit is running.

Example

Begin

  When Match( "OK" )

    Send( "atdt 5249999" + CR )

    Continue

  When Match( "CONNECT" )

    Send( CR )

Brk( )    // debugging break point

          // return to the editor

    Continue

  When Match( "Username :" )

Brk( )    // debugging break point

          // return to the editor

End

The preceding macro returns the control to KEA! Edit at two points during the macro execution, once after the Send(CR), and once after the When Match statement.


Button (macro function)
Button

Button( [[Text=]String], [[Width=]Int], [[Height=]Int], [[Offset=]Int] )

The Button function displays a button labeled with the specified string.

KEA! allows you to create buttons to be used in dialog boxes. Their definitions must appear within the Controls section of a Begin Dialog..End construct. Choosing a button causes a button's When event to be triggered.

Example

Var Password

Begin Dialog( )

GroupBox( , True )

EditBox( "Password", Password, Width = 28 )

DefaultButton( "Encode", Width = 12 )

GroupEnd( )

GroupBreak( )

OkButton( Width = 15 )

CancelButton( Width = 15, Offset = 10 )

Button( "Help", Width = 15, Offset = 10 )

Do

ControlSet( "edit1", Control_Password, Value = 1 )

Continue

End


ButtonPad (macro function)
ButtonPad

ButtonPad[?]( [[Reset=]boolean], [[Caption=]string], [[MapTo=]string], [[Value=]string], [[ViewButtons=]boolean], [[ButtonsOnStatusBar=]boolean], [[OrderByRow=]boolean], [[Rows=]string], [[Columns=]string], [[ButtonWidth=]string] )

The ButtonPad function defines buttons and configures a SmartPad. You can display the SmartPad in a separate window, or on the status bar. You can include multiple sets of the Caption, MapTo, and Value arguments.

The arguments are equivalent to the options of the SmartPad command on the Options menu.

Reset   	Erase the current mapping.

Caption   	String to place on the button face.

MapTo   	Type of action to perform.

Nothing	Do nothing.

Sequence	Send string to the host.

Macro	Execute macro statements.

Label of Group	Create label for group of buttons.

Next Group	Display buttons defined in the next group.

Prev Group	Display buttons defined in the previous group.

Goto Group	Display buttons defined in the specified group.

Value   	Action to perform based on MapTo value.

ViewButtons   	Display or hide SmartPad.

ButtonsOnStatusBar   Display buttons on status bar or in separate window. Values are:

True	Display on status bar.

False	Display in separate window.

OrderByRow   	Whether to fill SmartPad by rows or columns.

True	Fill SmartPad by rows from left to right.

False	Fill SmartPad by columns from top to bottom.

Rows   	Number of rows to display on SmartPad.

Columns   	Number of columns to display on SmartPad.

ButtonWidth   	Width of each button in characters.

A button can call a macro, send a string to the host, or display a SmartPad. Buttons are displayed in the same order as they appear in the macro. You can implement button control and logic by assigning related buttons to groups, and labeling each group. You can implement logical movement between groups using a menu/submenu structure.

For the macro language equivalent to the Delete All button in the SmartPad dialog box, see the ButtonPad.DeleteAll function.

Examples

The following macro implements a modem dial-up menu. Each button calls a macro; KEA! displays five buttons on the status bar; each button is 35 characters wide.

Buttons = True

ButtonPad( Reset = True,

 Caption = "DIAL", MapTo = "Macro", Value = "DIAL( )",

 Caption = "HANGUP", MapTo = "Macro", Value = "HANGUP( )",

 Caption = "TEST MODEM", MapTo = "Macro", Value = "TESTMOD( )",

 Caption = "PHONE DIR", MapTo = "Macro", Value = "PHONE( )",

 Caption = "EXIT KEA!", MapTo = "Macro", Value = "KEAEXIT( )",

 ViewButtons = True, ButtonsonStatusBar = True, Columns = "5",

 ButtonWidth = "35" )

These buttons use groups to implement a set of Kermit Commands.

Buttons = True

ButtonPad( Reset = True, Caption = "Main", MapTo = "LabelofGroup",

 Caption = "1. CONFIGURE", MapTo = "Macro", Value = "CONFIG( )",

 Caption = "2. COMMANDS", MapTo = "GotoGroup", Value = "Commands",

 Caption = "3. SEND", MapTo = "Macro", Value = "SENDIT( )",

 Caption = "4. RECEIVE", MapTo = "Macro", Value = "RCVIT( )",

 Caption = "5. GET", MapTo = "Macro", Value = "GETIT( )",

 Caption = "6. EXIT", MapTo = "Macro", Value = "KEXIT( )",

 Caption = "Commands", MapTo = "LabelofGroup", // Commands Group

 Caption = "1. DIR ", MapTo = "Macro", Value = "KDIR( )",

 Caption = "2. COPY", MapTo = "Macro", Value = "KCOPY( )",

 Caption = "3. DEL", MapTo = "Macro", Value = "KDEL( )",

 Caption = "4. LOGIN", MapTo = "Macro", Value = "KLOGIN( )",

 Caption = "5. QUERY", MapTo = "Macro", Value = "KQUERY( )",

 Caption = "Previous", MapTo = "GotoGroup", Value = "Main",

 ViewButtons = True, ButtonsOnStatusBar = False, Rows = "1",

 Columns = "6", ButtonWidth = "10" )

Note  If you try to use this example macro, the buttons are displayed, but they perform no action because they have no definitions.


ButtonPad.DeleteAll (macro function)
ButtonPad.DeleteAll

ButtonPad.DeleteAll( )

The ButtonPad.DeleteAll function deletes all current button assignments.

This function performs the same action as the Delete All button in the SmartPad dialog box (Options menu).


Buttons (macro variable)
Buttons

Buttons = boolean

The Buttons variable specifies whether KEA! displays your custom SmartPad. It is equivalent to the Show SmartPad command on the Options menu.

Values are:

0	Hide the buttons.

1	Display the buttons.

Examples

Buttons = True

Display the SmartPad.

B = Buttons

Records whether buttons are visible.


Cancel (macro function)
Cancel

Cancel( )

The Cancel function terminates all running and suspended macros. It is equivalent to the Stop command under the Macro menu. The function has no return value.


CancelEnable (macro variable)
CancelEnable

CancelEnable([Value =] boolean)

The CancelEnable function specifies whether a user can stop the running macro using the ESC key, the Cancel button on the Toolbar, or the Stop command on the Macro menu. The function returns the previous state of CancelEnable. Values are:

0	The user cannot stop the macro.

1	The user can stop the macro.

After the macro is stopped or completes, the previous cancel state is restored.

Examples

CancelEnable(False)

After the preceding statement, the user cannot stop the running macro.

prev = CancelEnable(False)

.

.

CancelEnable(prev)

In the first line, CancelEnable ensures the user cannot stop the running macro, and saves the previous cancel state in the variable Prev. After the second line, the previous cancel state is restored.


CancelButton (macro function)
CancelButton

CancelButton( [[Width=]Int], [[Height=]Int], [[Offset=]Int] )

The CancelButton function displays a button labeled Cancel. KEA! executes the Cancel button when the user chooses it or presses ESC. When the user chooses Cancel, KEA! exits the dialog box immediately, but does not update the values for the controls.

You can create buttons to be used in dialog boxes. Their definitions must appear within the Controls section of a Begin Dialog..End construct. Choosing a button causes its When event to be triggered.

Example

Var Password

Begin Dialog( )

GroupBox( , True )

EditBox( "Password", Password, Width = 28 )

DefaultButton( "Encode", Width = 12 )

GroupEnd( )

GroupBreak( )

OkButton( Width = 15 )

CancelButton( Width = 15, Offset = 10 )

Button( "Help", Width = 15, Offset = 10 )

Do

ControlSet( "edit1", Control_Password, Value = 1 )

Continue

End


Capture (macro variable)
Capture

Capture = boolean

The Capture variable specifies whether or not incoming data is written to a file. Values are:

0	Do not write data to a file.

1	Write data to a file.

Examples

Capture = True

Sets capture on.

B = Capture

Records whether the capture feature is active.


CaptureSetup (macro function)
CaptureSetup

CaptureSetup[?]( [[FileName=]string], [[Append=]boolean], [[EnableCapture=]boolean] )

The CaptureSetup function specifies the options for saving received data in a file.

The arguments are equivalent to the options in the Capture Setup dialog box (File menu).

FileName   	Specify the name of file in which to record the incoming data.

Append   	Whether to write new information to the end of an existing file, or overwrite the existing file data with the new data.

True	Append to existing file.

False	Overwrite existing file.

EnableCapture   	Whether to store incoming data in the file. Values are:

True	Capture data.

False	Do not capture data.

Examples

CaptureSetup( FileName = "SESSION1.TXT" )

Tells KEA! to write incoming data to the file SESSION1.TXT.

CaptureSetup?( )

Displays the Capture Setup dialog box for you to specify the Capture Setup options.

B = CaptureSetup.Append

Stores status of the Append option.


CheckBox (macro function)
CheckBox

CheckBox( [[Text=]String], [[Value=]Var], [[Width=]Int], [[Height=]Int], [[Offset=]Int] )

The CheckBox function is used to provide entry for a two-valued option. It must appear within the Controls section of a Begin Dialog..End construct. The check box is displayed labeled with the Text string.

Text   	The label that appears to the right of the check box. If you want to underline a character in the string (for selection with the keyboard), place an ampersand (&) before that character.

Value   	KEA! evaluates Value as Boolean, and checks the box if Value is True. On return from the dialog box, Value is set to 1 if the user selected the check box; otherwise, it is left in its current state.

Width   	A literal integer or integer variable that defines the horizontal space (in average character width) taken up by the complete control. It includes any label, user entry space, and separating white space.

Height   	A literal integer or integer variable that defines the vertical space (in character height) taken up by the control. It includes the borders and separating white space. The box defaults to an appropriate height if you do not supply this parameter.

Offset   	A literal integer or integer variable that defines how far from the right edge of the space the left part of the control starts. You should specify an offset that is less than the width.

Example

Begin Dialog( "Sample Check Box" )

  check_item = 0

  CheckBox( "&Check Item", check_item, 40,,15 )

  OKButton( 40,,15 )

End

Echo( "Value of item is " + check_item )

The preceding example displays a dialog box with a single check box and an OK button. The value returned from the check box is displayed on the screen.


Chr (macro function)
Chr

Chr( [Value=]integer )

The Chr function returns the ASCII equivalent of an integer. You can specify any integer in the range 0 through 255.

Value   	Character returned.

The following table shows some of the special characters that Chr can return:

Chr( 8 )	Backspace

Chr( 9 )	Tab

Chr( 10 )	Newline

Chr( 12 )	Formfeed

This function is complementary to Asc( ).

Examples

Char1 = Chr( 65 )

Returns the character 'A'.

Char2 = Chr( 13 )

Returns a carriage return.


Clear (macro function)
Clear

Clear( )

The Clear function removes all displayed information from the current emulation screen. It also sets all line attributes to normal. It is equivalent to the Clear command under the Connection menu. The function returns no value.


ClearComm (macro function)
ClearComm

ClearComm( )

The ClearComm function clears the communications port and ANSI interpreter. It is equivalent to the Clear Comm command under the Connection menu. The function returns no value.


ClearHistory (macro function)
ClearHistory

ClearHistory( )

The ClearHistory function removes all information from the History buffer. The function is equivalent to the Clear History command under the Connection menu. It has no return value.


Close (macro function)
Close

Close([[Options=]integer] )

The Close function quits this session. It is equivalent to the Close Session command under the File menu. The function returns no value.

Options	Values that determine when a user prompt appears, and whether a changed session configuration and layout are saved. If you specify no value in a category, the settings provided in the General function are used. You can combine one value from each of the following groups by adding them together.

Connected session

EXIT_DISCONNECT	Disconnect with no prompt.

Changed session configuration

EXIT_SAVECONFIG	Save.

EXIT_NOSAVECONFIG	Do not save.

EXIT_PROMPTCONFIG	Prompt for save.

Changed layout

EXIT_SAVELAYOUT	Save.

EXIT_NOSAVELAYOUT	Do not save.

EXIT_PROMPTLAYOUT	Prompt for save.

Example

Begin

   .

   .

   When Disconnected( )

      Close(EXIT_NOSAVECONFIG + EXIT_NOSAVELAYOUT)

      //exit KEA! without saving and return to Windows

End


ClosePrintJob (macro function)
ClosePrintJob

ClosePrintJob( )

The ClosePrintJob function indicates the end of a print job. It also sends a form feed to the print job, ejecting the current page. The function is equivalent to the Close Print Job command under the File menu. It has no return value.


ComboBox (macro function)
ComboBox

ComboBox( [[Text=]String], [[Value=]Var], [List=]Var, [[Width=]Int], [[Height=]Int], [[Offset=]Int] )

The ComboBox function displays a box that is a combination of a drop-down list box and an edit box. The function must appear within the Controls section of a Begin Dialog..End construct. The drop-down list box is filled with the values from the List array. When the number of items is greater than seven, a scroll bar is added. The user can select an item from the drop-down list, or enter a value from the keyboard.

Text   	The Combo box is labeled with the Text string; this string appears to the left of the box.

Value    	If Value evaluates to a subscript in the List array, the corresponding entry is highlighted when the dialog box is displayed. On return from the dialog box, Value contains either the value entered by the user, or the value of the selected array item.

List   	The array to display. The user can select from this list, or enter a value from the keyboard.

Width   	A literal integer or integer variable that defines the horizontal space (in average character width) taken up by the complete control. It includes any label, user entry space, and separating white space.

Height   	A literal integer or integer variable that defines the vertical space (in character height) taken up by the control. It includes the borders and separating white space. Default is 1 line.

Offset   	A literal integer or integer variable that defines how far from the right edge of the space the left part of the control starts. You should specify an offset that is less than the width.

Note  The ComboBox function returns the list values, not the subscripts as ListBox and DropDownBox do.


Commands (macro function)
Commands?

Commands?( )

When you use the Commands function in a macro (equivalent to the Commands command on the Transfer menu) you must use it with a question mark: Commands?( ). This displays the Commands dialog box associated with the file transfer protocol selected, which the user can complete before choosing OK. Note that you cannot use Commands without the question mark.

If you want to issue Kermit or FTP commands without user interaction, use the TransferCommand function instead.


Communications (macro function)
Communications

Communications[?]( [[Port=]string], [[LimitTransmitRate=]boolean], [[Rate=]string] )

The Communications function configures the communications port, limit transmit rate, and transmission rate. The arguments are equivalent to the options in the Communications dialog box on the Options menu.

Port   	Set the communication method to use. Values are:

None	No communication method.

Serial	Serial communication using standard COM port.

Modem	Modem communication using Windows 95 built-in modem management facility.

LAT	DIGITAL's Local Area Transport.

Telnet	TCP/IP Telnet.

KEAlink MSU	Multiple sessions on a COM port.

NetWare for LAT   Novell gateway to LAT.

LimitTransmitRate   	Control the transmit speed to the host.

Rate   	Set how many characters per second to send to the host when using Limit Transmit Rate.

10	Minimum transmit rate.

2000	Maximum transmit rate.

For macro language equivalents to the Setup button in the Communications dialog box, see the Communications.Setup function for Serial port, Modem, LAT, Telnet, KEAlink MSU, or NetWare for LAT.

Examples

Communications( "Serial" )

Tells KEA! to use a serial communications port.

X = Communications.Rate

Records the limited transmit speed.

Communications.LimitTransmitRate = False

Tells KEA! not to limit the transmission rate to the host.


Communications.Proxies (macro function)
Communications.Proxies

Communications.Proxies[?]( [[UseFTPProxy]boolean], [[FTPProxy]string], [[FTPPort]string], [[UseTelnetProxy]boolean], [[TelnetProxy]string], [[TelnetPort]string], [[UseSOCKSProxy]boolean], [[SOCKSProxy]string], [[SOCKSPort]string] )

The Communications.Proxies function determines the settings for FTP, Telnet, and SOCKS proxy servers.

The arguments perform the same functions as the Proxies dialog box.

UseFTPProxy   	Values are:

True	Use an FTP proxy.

False	Do not use an FTP proxy.

FTPProxy   	Name of the FTP proxy server.

FTPPort   	Specify a port number.

UseTelnetProxy   Values are:

True	Use a Telnet proxy.

False	Do not use a Telnet proxy.

TelnetProxy   	Name of the Telnet proxy server.

TelnetPort   	Specify a port number.

UseSOCKSProxy   Values are:

True	Use a SOCKS proxy.

False	Do not use a SOCKS proxy.

SOCKSProxy   	Name of the SOCKS proxy server.

SOCKSPort   	Specify a port number.


Communications.Setup LAT (macro function)
Communications.Setup         LAT

Communications.Setup[?]( [[ServiceName=]string], [[DisplayNodesInServiceNameList=]boolean], [[PromptForServiceDuringConnect=]boolean], [[PromptOnDisconnect=]boolean] )

The Communications.Setup function allows you to specify communication settings for LAT.

The arguments perform the same functions as the LAT Setup dialog box (Options menu) options.

ServiceName   	Name of service to connect.

DisplayNodesInServiceNameList   Select to list LAT Node names and the LAT service names in the service name drop-down list.

PromptForServiceDuringConnect   Prompt for the host name when attempting connection. Values are:

True	Prompt for host name.

False	Do not prompt for host name.

PromptOnDisconnect   Ask for reconnect when connection lost. Values are:

True	Inform of lost connection.

False	Do not inform of lost connection.

Examples

Communications( Port = "LAT", LimitTransmitRate = True, Rate = 250 )

Communications.Setup( ServiceName = "Freddy",

    PromptForServiceDuringConnect = False )

The preceding macro prepares a LAT session with the host "Freddy". The transmit rate is limited to 250 characters per second and KEA! is asked not to prompt the user for a host name when it attempts a connection.

Communications.Setup?( )

Allows the user to configure the communications settings in the LAT Setup dialog box.

X = Communications.Setup.ServiceName

Records the name of the service.


Communications.Setup Modem (macro function)
Communications.Setup         Modem

Communications.Setup[?]( [[Modem=]string], [[CountryCode=]string], [[AreaCode=]string], [[PhoneNumber=]string], [[UseCountryCodeAndAreaCode=]boolean], [[MaxumumRedialsOnBusyOrNoAnswer=]string], [[TimeBetweenRedials=]string], [[ReceiveXoffPoint=]string], [[BaudRate=]string], [[FlowControl=]string], [[DataBits=]string], [[StopBits=]string], [[Parity=]string], [[CheckParity=]boolean] )

The Communications.Setup function determines the communications settings for a Modem connection.

The arguments are equivalent to the options in the Modem Setup dialog box (Options Menu).

Modem   	Your modem type.

CountryCode   	If included before the macro sets the PhoneNumber, returns the default (local) Country code in the form "Country name (Country code)". For example, Canada (1). The returned value might contain more than one set of parentheses. Parse backwards from the end of the string to obtain the CountryCode.

AreaCode   	If included before the macro sets the PhoneNumber, returns the default (local) Area code.

PhoneNumber   	The number you want to dial in the form "+CountryCode (AreaCode) PhoneNumber". For example, +1 (604) 473-3992.

UseCountryCodeAndAreaCode   Whether to use the specified Country and Area codes.

MaximumRedialsOnBusyOrNoAnswer   The maximum number of times to automatically redial the number.

TimeBetweenRedials   The time interval between dialing attempts. Values are:

10 sec   30 sec   1 min   2 min

ReceiveXoffPoint   How much data can accumulate in the receive buffer before sending an Xoff requesting the host to stop sending data. The default is 1024 (the maximum). Values are:

64   256   512   1024

BaudRate   	Set the rate at which to send data to the host.  Values are:

300  1200  2400  4800  9600  19200  38400  57600  115200

FlowControl   	Specify action to take if buffer becomes too full to receive more data. Values are:

None   Xon/Xoff   Hardware

DataBits   	Specify the number of bits for each character. Values are:

7   8

StopBits   	Specify the time interval between transmitted characters. Values are:

1   1.5   2

Parity   	Specify the type of error checking. Values are:

None   Even   Odd   Mark   Space

CheckParity   	Check incoming parity.


Communications.Setup NetWare for LAT (macro function)
Communications.Setup         NetWare for LAT

Communications.Setup[?]( [[UseNetWareLoginNameOnPrimaryServer=]boolean], [[Userid=]string], [[Password=]string], [[NetWareServer=]string], [[PortPool=]string], [[ServiceName=]string], [[DisplayNodesInServiceNameList=]boolean], [[PromptForServiceDuringConnect=]boolean], [[PromptOnDisconnect=]boolean] )

The Communications.Setup function allows you to specify communication settings for NetWare for DEC Access.

The arguments perform the same functions as the NetWare for LAT Setup dialog box (Options menu) options.

UseNetWareLoginNameOnPrimaryServer   Select to have a user ID automatically selected to login to the server.

Userid   	The User ID to connect to the NetWare for DEC Access server.

Password   	The Password used to login to the NetWare for DEC Access server.

NetWareServer   	The server you want to use as your LAT gateway.

PortPool   	If the LAT Server has been configured to use port pools, enter the appropriate port pool name.

ServiceName   	Select the service to which you want to connect.

DisplayNodesInServiceNameList   Select to list LAT Node names and the LAT service names in the service name drop-down list.

PromptForServiceDuringConnect   Request a host name when attempting a connection.

PromptOnDisconnect   Prompt when the connection is lost.


Communications.Setup Serial (macro function)
Communications.Setup           Serial

Communications.Setup[?]( [[Port=]string], [[BaudRate=]string], [[DataBits=]string], [[StopBits=]string], [[Parity=]string], [[CheckParity=]boolean], [[FlowControl=]string], [[ReceiveXoffPoint=]string], [[ModemDisconnect=]string], [[DisconnectOnExit=]boolean] )

The Communications.Setup function determines the communications settings for the Serial port.

The arguments are equivalent to the options in the Serial Port Setup dialog box (Options Menu).

Port   	Specify which serial port to use.

BaudRate   	Set the rate at which to send data to the host.  Values are:

300  1200  2400  4800  9600  19200  38400  57600  115200

DataBits   	Specify the number of bits for each character. Values are:

7   8

StopBits   	Specify the time interval between transmitted characters. Values are:

1   1.5   2

Parity   	Specify the type of error checking. Values are:

None   Even   Odd   Mark   Space

CheckParity   	Check incoming parity.

FlowControl   	Specify action to take if buffer becomes too full to receive more data. Values are:

None   Xon/Xoff   Hardware

ReceiveXoffPoint   Specify how much data can accumulate in the receive buffer before sending an Xoff requesting the host to stop sending data. The default is 1024 (the maximum). Values are:

64   256   512   1024

ModemDisconnect   Disconnect the session by lowering the DTR signal for about two seconds if no DSR or DCD activity occurs for the specified period. Values are:

60 ms   2 sec   Never

DisconnectOnExit   Drop the modem DTR signal when you exit (the default). Normally, the modem disconnects.

Examples

Communications( Port = "Serial", LimitTransmitRate = True,

    Rate = "25" )

Communications.Setup( Port = "COM1", BaudRate = "9600",

    DataBits = "8", StopBits = "1", Parity = "None",

    CheckParity = False, FlowControl = "XonXoff",

    ReceiveXoffPoint = "1024", ModemDisconnect = "Never" )

Sets the communication port to serial with a transmit rate of 25 characters per second. The macro then sets the serial port to COM1 with a transmission rate of 9600 baud using 8 data bits, 1 stop bit, no parity or parity checking, and Xon/Xoff flow control with an Xoff rate of 1024.

Communications.Setup.ReceiveXoffPoint = "512"

Sets the buffer full indicator to 512 bytes.

A = Communications.Setup.Port

Records the selected communications port.


Communications.Setup MSU (macro function)
Communications.Setup           KEAlink MSU

Communications.Setup[?]( [[Port=]string], [[BaudRate=]string], [[DataBits=]string], [[StopBits=]string], [[Parity=]string], [[CheckParity=]boolean], [[FlowControl=]string], [[ReceiveXoffPoint=]string], [[ModemDisconnect=]string], [[StartMultipleSessions=]string] )

The Communications.Setup function determines the communications settings for the Serial port.

The arguments are equivalent to the options in the MSU Serial Port Setup dialog box (Options Menu).

Port   	Specify which serial port to use. Select from:

COM1   COM2   COM3   COM4

BaudRate   	Set the rate at which to send data to the host.  Values are:

300  1200  2400  4800  9600  19200  38400  57600  115200

DataBits   	Specify the number of bits for each character. Values are:

7   8

StopBits   	Specify the time interval between transmitted characters. Values are:

1   1.5   2

Parity   	Specify the type of error checking. Values are:

None   Even   Odd   Mark   Space

CheckParity   	Check incoming parity.

FlowControl   	Specify action to take if buffer becomes too full to receive more data. Values are:

None   Xon/Xoff   Hardware

ReceiveXoffPoint   Specify how much data can accumulate in the receive buffer before sending an Xoff requesting the host to stop sending data. The default is 1024 (the maximum). Values are:

64   256   512   1024

ModemDisconnect   Disconnect the session by lowering the DTR signal for about two seconds if no DSR or DCD activity occurs for the specified period. Values are:

60 ms   2 sec   Never

StartMultipleSessions   A macro command that instructs the host to enable multiple sessions.


Communications.Setup Telnet (macro function)
Communications.Setup           Telnet

Communications.Setup[?]( [[Host=]string], [[PromptForHostDuringConnect=]boolean], [[PromptOnDisconnect=]boolean], [[TCPType=]string], [[HostsFile=]string], [[TerminalType=]string], [[Custom=]string], [[ShowHexNetworkData=]boolean], [[ShowNegotiations=]boolean] )

The Communications.Setup function determines the communications settings for Telnet.

The arguments perform the same functions as the Telnet Setup dialog box (Options menu) options.

Host   	Name of host system.

PromptForHostDuringConnect   Prompt for the host name when attempting connection. Values are:

True	Prompt for host name.

False	Do not prompt for host name.

PromptOnDisconnect   Ask for reconnect when connection lost. Values are:

True	Inform of lost connection.

False	Do not inform of lost connection.

TCPType   	Specify Windows Sockets.

HostsFile   	Specify the location of your HOSTS file to use in the drop-down list of hosts.

TerminalType   	Specify type of terminal to use.

All	Offer all the terminal types emulated, and negotiate with the host for the most suitable type.

Current	Restrict KEA! to negotiating only the terminal type selected in the Terminal General dialog box.

Custom	Let KEA! negotiate a terminal type response applicable to your host, if your Telnet server does not support RFC1091. This option satisfies the host software, but does not affect the emulation.

Custom   	Name of customer terminal type to use during negotiation.

ShowHexNetworkData   Display Telnet communications information in hexadecimal.

ShowNegotiations   Display all Telnet option negotiations for debugging purposes.

For macro language equivalents to other options in the Telnet Setup dialog box, see the Communications.Setup.Advanced and Communications.Setup.Advanced.Special functions.

Examples

Communications( Port = "Telnet", LimitTransmitRate = True, Rate = 25 )

Communications.Setup( Host = "Freddy",

    PromptForHostDuringConnect = False,

    TCPType = "3ComTCP", TerminalType = "All", Custom = "",

    ShowHexNetworkData = False, ShowNegotiations = False )

The preceding macro prepares a Telnet session with the host "Freddy". The transmit rate is limited to 25 characters per second and KEA! is asked not to prompt the user for a host name when it attempts a connection.

A = Communications.Setup.Host

Records the name of the connected host.

Communications.Setup?( )

Allows the user to configure the communications settings in the Telnet Setup dialog box.


Communications...Advanced Telnet (macro function)
Communications.Setup.Advanced          Telnet

Communications.Setup.Advanced[?]( [[TelnetPort=]integer], [[PairCRWith=]string], [[LineOutputMode=]boolean], [[TieOutputModeTo=]string], [[SendSyncWithIP=]boolean], [[InitiateOptionNegotiation=]boolean], [[TieBinaryTo8bit=]boolean], [[LocalSpecialCharProcessing=]boolean] )

The Communications.Setup.Advanced function determines the advanced communications settings for Telnet.

The arguments perform the same functions as the options in the Telnet Advanced dialog box (Options menu).

TelnetPort   	Specify the number of your host's Telnet port. The standard port is 23.

PairCRWith   	Specify how to send a new line signal. Values are:

LF      null

LineOutputMode   Send data a line at a time after receiving a line ending character.

TieOutputModeTo   Specify how to control output mode switching. Values are:

None    Echo    SGA    Echo/SGA

SendSynchWithIP   Use Telnet synch sequence to send signals that interrupt the host.

InitiateOptionNegotiation   Configure negotiation of 7 or 8 bit communication.

TieBinaryTo8Bit   Negotiate binary interpretation with host, if data bits set to 8; otherwise, set data bits to 7.

LocalSpecialCharProcessing   Interpret special characters locally, and send them to the Telnet server as Telnet sequences.

For macro language equivalents to other options in the Telnet Advanced dialog box, see the Communications.Setup.Advanced.Special function.

Example

Communications.Setup.Advanced( TelnetPort = "23", PairCRwith = "LF",

    LineOutputMode = False, TieLineOutputModeTo = "Echo",

    SendSynchWithIP = True, InitiateOptionNegotiation = True,

    TieBinaryTo8bit = False, LocalSpecialCharProcessing = False )

The preceding example specifies the following: use the standard Telnet port 23, send newline signals as CR/LF, use character output mode, run in character output mode when the host is echoing and line mode when KEA! Telnet is echoing, use Telnet synch sequence to send signals that interrupt the host, try to get the host to match the KEA! Telnet setup, do not negotiate binary interpretation with the host, and do not process special characters locally.


Communications...Special Telnet(macro function)
Communications.Setup.Advanced.Special        Telnet

Communications.Setup.Advanced.Special[?]( [[NewLine=]char], [[Literal=]char], [[Erase=]char], [[EraseWord=]char], [[EraseLine=]char], [[Reprint=]char], [[Synch=]char], [[Interrupt=]char], [[BreakExtra=]char], [[AbortOutput=]char], [[AYT=]char] )

The Communications.Setup.Advanced.Special function determines some special-character settings for Telnet communications.

The arguments perform the same functions as the Special Characters dialog box (Options menu) options.

NewLine   	Send Telnet new line sequence. Default is CR.

Literal   	Treat next character as normal. Default is ^V.

Erase   	Delete previous character. Default is DEL.

EraseWord   	Delete last word on line. Default is ^J (LF).

EraseLine   	Delete entire input line. Default is ^U.

Reprint   	Reprint entire input line. Default is ^R.

Synch   	Send Telnet synch sequence. Default is ^A.

Interrupt   	Send Telnet interrupt process sequence. Default is ^C.

BreakExtra   	Send Telnet break sequence. Default is ^Y.

AbortOutput   	Send Telnet abort output sequence. Default is ^O.

AYT   	Send Telnet Are-You-There sequence. Default is ^T.

Examples

Communications.Setup.Advanced.SpecialCharacters( NewLine = " CR",

    Literal = " ^V", Erase = "DEL", EraseWord = " LF",

    EraseLine = " ^U", Reprint = " ^R", Synch = " ^A",

    Interrupt = " ^C", BreakExtra = " ^Y", AbortOutput = " ^O",

    AYT = " ^T" )


Connect (macro function)
Connect

Connect[?]( [[Host=]string | [ServiceName=]string] )

The Connect function tells KEA! to connect to the currently configured port. An optional parameter allows you to specify the name of the host or service to connect to.

The arguments are equivalent to the options in the Connect dialog box (Connection menu).

Host   	Specify the name of the host computer to which to connect. Valid only if you specified Telnet for under Port in the Communications dialog box.

ServiceName   	Specify the name of the service to which to connect. Valid only if you specified LAT under Port in the Communications dialog box.

This function returns no value.

Examples

Connect( ServiceName = "FINANCE" )

Connects to the service "Finance" using a LAT connection.

Connect?( )

Displays the Connect dialog box.

Connect( )

Initiates a connection to the communications port.


Continue (macro statement)
Continue

Continue

The Continue control statement tells Begin..When..End, For..In..End, and While..End control statements how to proceed.

In a Begin..When..End construct, Continue tells When to continue executing instead of falling through to the End. The macro continues executing as if the When event condition never occurred.

In a While..End or For..In..End construct, Continue tells the macro to proceed with another iteration from the top.

The Continue control statement can also be used outside the above constructs in a KEA! macro which is to be run by DDE Execute. When the macro has executed to the point of the Continue, KEA! sends the DDE Ack message that the macro has completed successfully.

Example

Begin

  When Match( "OK" )

    Wait( 2 )

    Send( "ATDT555-1212^M" )

    Continue	// Keep waiting for another OK or CONNECT match

  When Match( "CONNECT" )

    Wait( 5 )

    Send( "^M" )

      // With no Continue here, execution now

      // jumps to the End statement

  When Timeout( 300 )

    MsgBox( "Timeout..." )

    Break

End

The preceding macro dials a number and continues running until it receives a Connect, or a 30 second timeout occurs.


Control (macro function)
Control

Control( [Index=]String )

The Control function traps all changes to a button or box. You use this function as the event in a When statement. The user triggers the event by selecting or changing the button or box identified by Index.

Index   	The label, given by the Text= argument in the definition of each button or box.

-or-

One of the following strings, in which N is replaced by the number of that button or box in the Controls section defining this dialog box. For example "edit1" refers to the edit box defined by the first occurring EditBox function.
buttonN   any Button, DefaultButton, OkButton or CancelButton function.
textN   TextBox
editN   EditBox
checkN   CheckBox
radioN   RadioBox
listN   both ListBox and DropDownBox functions.
comboN   ComboBox
meterN   MeterBox

The Value variables associated with each button or box are updated before processing the event. Note that OkButton and CancelButton functions do not have a label; you can only refer to them by the second method.

Example

Var ButtonStr = "Off"

Begin Dialog( "Sample edit box" )

    OkButton( )

    Button( ButtonStr )

  Do

    ControlSet( "button1", Control_Disable )

    Continue

  When Control( "button2" )

    If ButtonStr = "Off"

      ButtonStr = "On"

      ControlSet( "button1", Control_Enable )

    Else

      ButtonStr = "Off"

      ControlSet( "button1", Control_Disable )

    End

    ControlSet( "button2", Control_Label, ButtonStr )

    Continue

End

The preceding example displays a dialog box with an OK button and a toggled On/Off button. The macro starts by dimming the OK button. The user can then enable or disable the OK button by successively clicking the On/Off button.


ControlSet (macro function)
ControlSet

ControlSet( [Index=]String, [[Key=]Int], [[Value=]String] )

The ControlSet function sets some attribute of a button or box.

Index   	The label, given by the Text= argument in the definition of each button or box.

-or-

One of the following strings, in which N is replaced by the number of that control (button or box) in the Controls section defining this dialog box. For example "edit1" refers to the edit box defined by the first occurring EditBox function.
buttonN   any Button, DefaultButton, OkButton or CancelButton function.
textN   TextBox
editN   EditBox
checkN   CheckBox
radioN   RadioBox
listN   both ListBox and DropDownBox functions.
comboN   ComboBox
meterN   MeterBox

Note that OkButton and CancelButton functions do not have a label; you can only refer to them by the second method.

Key   	Specify how to change the button or box. Keys are:

Control_Init	(Default) Reinitialize the specified control from the variables connected with it. Use this key when the variables associated with the control have changed, usually to update the list in a list control. Value is ignored.

Control_Label	Set the specified control label to the string given in Value. The control's label used to resolve the Index parameter remains the text passed when the control was created. This does not affect the control size. If the new label is longer than the original label, it might not display completely.

Control_Value	Set the specified control value to the string or index given in Value. KEA! interprets the value in the same way as the original Value parameter passed when the control was created.

Control_Focus	Set the control that receives keyboard input (the focus) to the specified control. Value is ignored.

Control_Default	Make the specified control the default control. This action applies only to buttons. Value is ignored.

Control_Disable	Make the specified control unavailable; the control is dimmed. Value is ignored.

Control_Enable	Make the specified control available. Value is ignored.

Control_Password	Enable or disable password mode in a specified edit control. In password mode, characters typed in the edit box appear as '*'. Use 1 for Value to enable password mode, and 0 to disable password mode.


Copy (macro function)
Copy

Copy( )

The Copy function copies the current selection to the Clipboard. It might require some interaction from you or the host application. The function is equivalent to the Copy command under the Edit menu. It has no return value.

Examples

// COPY1.KTM

Message( "Use your mouse to select an area to copy to Clipboard" )

ButtonPad( Caption = "COPY", MapTo = "MACRO", Value = "COPY2( )" )

// COPY2.KTM

Copy( )

Message( "Check your Clipboard" )

Running the COPY1 macro displays instructions, and sets up the SmartPad containing a COPY2 button. Clicking the COPY2 button runs the COPY2 macro that copies the selected text to the Clipboard and displays a message.


CopySpecial (macro function)
CopySpecial

CopySpecial[?]( [[CopyType=]string] )

The CopySpecial function lets you specify the line terminator (CopyType) to use when copying the selected area to the Clipboard. It is equivalent to the Copy Special command under the Edit menu.

CopyType   	Specify the line terminator to use. Select from:

Data	Include no line terminators or formatting.

Lines	Insert a carriage return and linefeed at the end of each line. This is equivalent to choosing Copy from the Edit menu.

Paragraph	Add a space at the end of a line to prevent words from running together. The selected text is treated as one or more paragraphs. A carriage return and a linefeed are inserted only before a blank line.

Table	If there is more than one space between words, the space is changed to a single tab character. Most spreadsheets and word processor tables interpret tab characters as cell separators. Single spaces are not changed.


CursorAt (macro function)
CursorAt

CursorAt( [Type=]integer, [Row=]integer, [Col=]integer, [EndRow=]integer, [EndCol=]integer, [Page=]integer )

The CursorAt function waits for the cursor to enter the specified area. If the cursor is already in the specified area, the function generates an immediate event. The function is typically used as a When event in a Begin..When..End construct.

Type   	Can be either one of:

Select_Stream (like left mouse-button selection) Default.

Select_Block (like right mouse-button selection)

Row   	Starting row of the selection. Default is 1, the top row.

Col   	Starting column of the selection. 1 to 80 (or 132). Default is 1, the leftmost column.

EndRow   	Ending row of the selection. Default is the last row.

EndCol   	Ending column+1 of the selection. Default is the last column+1.

Page   	The page on which the selection occurs. Page can be from 1 to the maximum number of pages, or -1 to indicate the VT status bar. Default is page 1.

This function requires the value of EndCol to be one greater than the last character included in the selection. For a description of Row and Col as used in this function, see GetSelection.

Example

Begin

  Suspend( )

  When CursorAt( Row=4, Col=1, EndRow=4, Page=1 )

    MsgBox( Text = "Cursor within row 4" )

    Break

End


CursorMove (macro function)
CursorMove

CursorMove([[Idle=]integer] )

The CursorMove function waits for a change in the cursor position. This includes a change in page or a change between the main window and status line. The function is typically used as a When event in a Begin..When..End construct.

Idle   	A time interval in tenths of a second. If this optional parameter is set, the function does not return changes in cursor position until the given idle period has elapsed during which there was no change.

It returns the new cursor position in a structure (that is, an array) which contains the following elements:

PAGE   	The page where the cursor lies. Page can be from 1 to the maximum number of pages, or -1 to indicate the VT status bar.

ROW   	Row where cursor lies. 1, 2, ...

COL   	Column where cursor lies. 1 to 80 (or 132).

When the status line is in the host-writable mode and the host moves the cursor, the host can also update text shown in the status line. Because CursorMove reacts to a change between the main window and the status line, a single cursor movement can generate several events: when the cursor moves to the new position, then to the status line to update the position shown there, then back to the new position. You could ignore events where the reported PAGE is -1.

Example

Begin

  Suspend()

  When CursorMove( )

    cursor = Result

    page    = cursor["PAGE"]

    row     = cursor["ROW"]

    column  = cursor["COL"]

    MsgBox( "Cursor changed" )

    Continue

  When Wait( 300 ) // if we are still in the loop after 30 secs

    MsgBox( "Timeout occurred.." )

    Break

End


Date (macro function)
Date

Date( )

The Date function returns the date as a character string. It uses your Windows short date format. You can set date formats using the International dialog box in the Windows Control Panel.

Example

DateString = Date( )

Message( "Today is : " + DateString )

The preceding example displays a message containing the current date on the status line.


DDE_Accept (macro function)
DDE_Accept

DDE_Accept( [Topic=]string, [[Results=]var] )

The DDE_Accept function is used by a DDE server to trap messages sent from its clients. It must be used as a When event. The first time the function is encountered, the topic for the server to support is created. Subsequently, only messages with the given topic are processed by the DDE_Accept event. The client can signal the server by using DDE_Initiate, DDE_Poke, DDE_Request, DDE_Advise or DDE_Terminate messages. All the relevant message information is stored in the variable Results.

Topic   	Name of the topic the server is to accept from clients.

Results   	Name of the array containing the message information. The subscripts are:

Type	Connect, Advise, Unadvise, Execute, Poke, Request, Terminate.

Channel	Message path to respond to the client.

Item	Contains the incoming arguments. (Advise, Unadvise, Poke, and Request)

Value	Contains data string. (Poke and Execute)

Options	Contains DEFER when the client wants to be notified of changes.

When the server accepts a Connect message, it must store the value of the Channel element if multiple channels are to be supported. Terminate indicates that the client has terminated the conversation. The server should respond to a terminate message with a DDE_Terminate. All other message types require that the server respond with a DDE_Reply.

If the Item element is null on an Unadvise, the server should cancel all Advises on that Channel. This is a standard DDE convention.

When the Options element contains the value DEFER on a received Advise, the client should only be notified of changes. Otherwise, the server should send the value of Item to the client every time its value changes (see DDE_Data).

Note  If Results is not specified (backward compatibility) then the Result variable contains the type of incoming DDE message. The Channel, Item, Value, and Options variables contain the message information.

Example

Var Request // array filled in by DDE_Accept

Var Conversation = 0

   .

   .

Begin

  Do

    Suspend()

  // Wait for a command connection from client

  When DDE_Accept( "MacroServer", Request )

    If Not Conversation      // only allow one client

      Conversation = Request.Channel

    End

    If Request.Type = "CONNECT"

      .

      .

The preceding script is taken from the DDE Server example. It illustrates how DDE_Accept is used as a When event to trap DDE messages sent from the client.


DDE_Advise (macro function)
DDE_Advise

DDE_Advise( [Channel=]channel, [Item=]string, [[Results=]var] )

The DDE_Advise function requests the server to return the value of Item whenever it changes. It must be used as a When event because the server can update Item many times.

When the server accepts the Advise, it returns True and makes data available on the given channel for the given item. If the server does not accept the Advise, it returns False and does not make the data available.

Channel   	Message path.

Item   	Name of the variable for which updates are required.

Results   	Updated value of Item.

If Results is null, use DDE_Request to get the actual value.

When the When clause exits, it automatically cancels the Advise.

Note  If Results is not specified then the variable Result contains the item value received.

Example

Var MyVar

Begin

  // when salary changes at the server

  When DDE_Advise( Channel, "Salary", Results = MyVar )

    If MyVar = ""

      MyVar = DDE_Request( Channel, "Salary" )

    End

    If MyVar = ""

       Continue

    Else

       Echo( "Updated Salary is: " + MyVar )

    End

End


DDE_Data (macro function)
DDE_Data

DDE_Data( [Channel=]channel, [Item=]string, [[Data=]string] )

The DDE_Data function sends Data to the client application in response to an earlier Advise. When the server is only signaling the availability of data (when Options = "DEFER" in DDE_Accept), the Data argument should be omitted. This macro returns True on success, and False on failure.

Channel   	Message path.

Item   	Label of information.

Data   	Updated information.

You can find out more about the operation, including any internal return codes from the server, by calling the DDE_Error or DDE_Message functions.

Example

    .

    .

When Timeout( 50 ) // update every 5 seconds

  If AdvItem

    For i In AdvItem

      If AdvOptn[i] = "DEFER"

        // notify client of change

        DDE_Data( Conversation, AdvItem[i] )

      ElseIf AdvItem[i] = "Time"

        // send time(HH:MM) to client

        DDE_Data( Conversation, AdvItem[i],

            SubStr(Time(), 1, 5) )

      ElseIf AdvItem[i] = "Date"

        // send date to client

        DDE_Data( Conversation, AdvItem[i], Date() )

      End

    End

  End

  Continue

    .

    .

The preceding script is taken from the DDE Server example. It illustrates how DDE_Data can be used to send updates to the client within a When event such as a repeated timeout.


DDE_Enable (macro function)
DDE_Enable

DDE_Enable( [Value=]boolean )

The DDE_Enable function enables or disables KEA! as a DDE server. Value is either True (enable) or False (disable). The default is True.

Example

DDE_Enable( True )

 ...

When DDE_Accept( "MacroServer", Request )

  If Request.Type = "CONNECT"

    Echo( "Client initiated conversation on channel " +

        Request.Channel + nl )

    DDE_Enable( False )  // Prevent other conversations

    Conversation = Request.Channel

 ...

The preceding script is taken from the DDE Server example. The macro sets up KEA! as a DDE server, but for the first conversation only.


DDE_Ended (macro function)
DDE_Ended

DDE_Ended( [Channel=]channel )

The DDE_Ended function picks up a termination initiated by the DDE server. You use this function as a When event. Normally, you initiate the conversation and immediately execute a When DDE_Ended.

This function indicates ended, rather than an error, if it receives an invalid channel. This is necessary because the server can terminate the conversation between the DDE_Initiate and the DDE_Ended calls.

Example

Channel = DDE_Initiate( "EXCEL", "EXCEL", "D:\EXCEL\EXCEL.EXE" )

Begin

  When DDE_Ended( Channel )

    Echo( "Conversation Terminated" )

    Break

  .

  .

  .

End


DDE_Error (macro function)
DDE_Error

DDE_Error( [Channel=]channel )

The DDE_Error function returns the application return code from the most recent DDE transaction on the specified channel. The following constants are defined for parsing the returned value from a DDE_Error function:

DDErc_ack	0

DDErc_nak	256

DDErc_busy	512

DDErc_error	1024

DDErc_fatal	2048

Example

DDE_Execute( Channel, "Update", Timeout = 100 )

ErrCode = DDE_Error( Channel )

If ErrCode = 1025

  Message( "Application timed out" )

  Return

ElseIf ErrCode = DDErc_busy

  Message( "Application busy" )

  Return

End


DDE_Execute (macro function)
DDE_Execute

DDE_Execute( [Channel=]channel, [Commands=]string, [[Timeout=]integer], [[Results=]var] )

The DDE_Execute function requests the server to execute the specified commands.

Channel   	Message path.

Commands   	One or more macro statements. Each statement must be enclosed in square brackets [ ].

Timeout   	Length of time in tenths of seconds to wait for a response. Default is 50 (five seconds).

Results   	The return code from the server.

If you want to execute a number of statements, save these in a macro file and insert the name of this macro (enclosed in square brackets) in the Commands string.

Because execution in the other application could take a long time (or forever, if the application does not acknowledge the request), you should check for a possible timeout and process it as required. You can use DDE_Execute as a When event in a Begin...When block. This lets the macro continue processing while waiting for the commands to finish executing. If you exit the When block before the DDE_Execute finishes, you lose the completion indication. This does not affect the other application. You can also use DDE_Execute stand-alone. If you use it outside a Begin...When block, KEA! waits for either the transaction to finish or the timeout to occur.

Note  If Results is not specified (backward compatibility) the Result variable contains the return code from the server.

Examples

DDE_Execute used in a Begin...When block.

Begin

  // user processing while waiting for execute to complete

  When DDE_Execute( Channel, "[OPEN(\"REVENUES.XLS\"]", Timeout = 30 )

    If Result = 1025    // check for timeout

      Message( "DDE Execute timeout" )

      Return

    End

     .

     .

End

DDE_Execute used standalone. This executes the Excel macro function Open( ). The \" lets you use quotes within quotes.

DDE_Execute( Channel, "[OPEN(\"REVENUES.XLS\")]", Timeout = 30 )

If Result = 1025    // check for timeout

  Message( "DDE Execute timeout" )

  Return

End


DDE_Get (macro function)
DDE_Get

DDE_Get( App!Topic, Item, [Timeout] )

The DDE_Get function requests the value of an item (for example, a variable, spreadsheet cell, group of cells) from the specified application and topic. Note that DDE_Get is actually a macro called DDE_GET.KTM which resides in your KEA! directory. This macro automatically initiates and terminates KEA!'s conversation with the application. Therefore, you don't need to call DDE_Initiate or DDE_Terminate to perform the DDE_Get function. The arguments are:

App!Topic   	A string containing the application name and topic separated by an exclamation point (!) character.

Item   	A string containing the item name.

Timeout   	An integer specifying the timeout interval in seconds (default is 5 sec.).

This function returns the value of Item. It returns null if the data is not available, or if Timeout is exceeded.

The _ddeAErr variable contains the internal return code from the server, if the operation got that far. The _ddeAMsg variable contains a descriptive message.

Example

MyVar = DDE_Get( "KEAVT!MACRO", "Fonts", 10 )

If MyVar = ""

  Echo( "Request failed" )

Else

  Echo( "Font size is " + MyVar )

End

The preceding example requests the value of Fonts from the KEA! server.


DDE_Initiate (macro function)
DDE_Initiate

DDE_Initiate( [App=]string, [Topic=]string, [[Appfile=]string] )

The DDE_Initiate function sets up a conversation with the given application (App) using the given topic (Topic).

App   	Application name.

Topic   	Topic name.

Appfile   	Path and filename of App if KEA! needs to start the application. Not needed if the executable name is the same as the application name and the application is on the DOS search path.

This function returns a channel. You must keep the channel value as you need it to identify the conversation in subsequent calls. If the function returns a value of zero, the conversation could not be initiated.

Examples

Establish a conversation with Excel.

ExcelChannel = DDE_Initiate( "Excel", "System", "D:\EXCEL\EXCEL.EXE" )

If ExcelChannel = 0

  Message( "DDE initiate to Excel failed" )

  Return    // Quit macro

End

Establish a conversation with Word for Windows.

WordChannel = DDE_Initiate( "WINWORD", "WINWORD",

    "D:\WINWORD\WINWORD.EXE" )

If WordChannel = 0

  Message( "DDE initiate to Word failed" )

  Return    // Quit macro

End


DDE_Message (macro function)
DDE_Message

DDE_Message( [Channel=]channel )

The DDE_Message function returns a descriptive message about the state of the last DDE transaction on the specified Channel.

Channel   	Conversation path.

Examples

DDE_Poke( Channel, "total1", "$2345" )

Echo( DDE_Message(Channel) )


DDE_Poke (macro function)
DDE_Poke

DDE_Poke( [Channel=]channel, [Item=]string, [Value=]value )

The DDE_Poke function sends the server a new value for the variable Item. It returns True if the server successfully updated the value, and False otherwise. You can find out more about the operation, including any internal return codes from the server, by calling the DDE_Error or DDE_Message functions.

Channel   	Conversation path.

Item   	Name of the item whose value is to be set.

Value   	New value for the item.

Examples

If Not DDE_Poke( Channel, "salary", 59678 )

  Message( "DDE Poke failed: " + DDE_Message() )

  Return

End


DDE_Query (macro function)
DDE_Query

DDE_Query( [[App=]string], [[Topic=]string] )

The DDE_Query function returns a list of available DDE servers. If you do not specify anything for App, it finds all servers that accept the specified topic. If you do not specify a topic, it finds all topics for the specified application. You must specify either the application or the topic.

App   	Application name.

Topic   	Topic name.

This function returns a string containing a list of items, separated by tab characters.

Examples

List = DDE_Query( "", "System" )

This lists all applications with DDE servers currently available to provide a System topic. This is a good way to find all currently available DDE servers.

List = DDE_Query( "Excel", "" )

This lists all topics from Excel's DDE server.

List = DDE_Query( "KEAVT", "" )

This lists all topics from currently running KEAVT sessions. The list does not include the server topics belonging to the session that issued the request.


DDE_Reply (macro function)
DDE_Reply

DDE_Reply( [Channel=]channel, [[Rc=]integer], [[Data=]string] )

The DDE_Reply function is used by a DDE server to respond to a message accepted by a DDE_Accept.

Channel   	Communication path.

Rc   	Return code to send:

0-255	accept

256-1023	reject

Data   	Data to be included with the reply.

The function returns True if successful, and False if unsuccessful. If replying to and accepting a DDE_Request, the reply must include the requested Data; otherwise, you can omit it.

You can find out more about the operation, including any internal return codes from the server, by calling the DDE_Error or DDE_Message functions. For a detailed description of return codes, see DDE Return Codes.

Example

  .

  .

Begin

  Do

    Suspend()  // return control to KEA!

  When DDE_Accept( "MacroServer", Request )

    If not Conversation      // only allow one client

      Conversation = Request.Channel

    End

    If Request.Type = "REQUEST"

      Echo( "Client requested " + Request.Item + nl )

      If Request.Item = "Time"

        // send time(HH:MM) to client

        DDE_Reply( Request.Channel, 0, SubStr(Time(), 1, 5) )

      ElseIf Request.Item = "Date"

        // send date to client

        DDE_Reply( Request.Channel, 0, Date() )

      Else

        DDE_Reply( Request.Channel, 256 )  // Reject

        Echo( "..rejected" + nl )

      End

        .

        .

The preceding script is taken from the DDE Server example. It illustrates how DDE_Reply is used to respond to DDE_Request messages from the client.


DDE_Request (macro function)
DDE_Request

DDE_Request( [Channel=]channel, [Item=]string )

The DDE_Request function requests the server to return the current value of Item. Normally you use this function after a DDE_Advise indicates the availability of the item by returning a null result. The arguments are:

Channel   	Communications path.

Item   	Name of the item to update.

This function has a built-in timeout. If a timeout occurs, the function returns False. You can find out more about the operation, including any internal return codes from the server, by calling the DDE_Error or DDE_Message functions.

Examples

DDE_Request( Channel, "salary" )

If Result <> ""

  Send( "Salary is: " + Result )

End


DDE_Run (macro function)
DDE_Run

DDE_Run( app!topic, commands, [timeout] )

The DDE_Run function requests the specified application and topic (app!topic) to execute the supplied commands. The optional timeout specifies the timeout interval in seconds; the default is 5 seconds. Note that DDE_Run is actually a macro called DDE_RUN.KTM which resides in your KEA! directory. This macro automatically initiates and terminates KEA!'s conversation with the application. Therefore, you don't need to call DDE_Initiate or DDE_Terminate to perform the DDE_Run function. The arguments are:

App!Topic   	String containing the application name and topic separated by an exclamation point (!) character.

Commands   	Sequence of commands the server is requested to run.

Timeout   	Integer specifying the timeout interval in seconds (default is 5 sec.).

This function returns True if it worked, and False if it did not. The _ddeAErr variable contains the internal return code from the server, if the operation got that far. The _ddeAMsg variable contains a descriptive message.

Examples

DDE_SetApp( "NEW_CLIENT" )

DDE_Run( "KEAVT!MACRO", "[PlayBack(\"CAPTURE.TXT\")]" )

In this example, both the client and the server are KEA! sessions. The client tells the server to run the macro function PlayBack which reads and displays the file CAPTURE.TXT on the server's emulation screen. Note that using \" in the command lets you use quotes within quotes.


DDE_Send (macro function)
DDE_Send

DDE_Send( app!topic, item, value, [timeout] )

The DDE_Send function sets a new value for the item (for example, a variable spreadsheet cell) in the specified application's topic (app!topic). The optional timeout specifies the timeout interval in seconds; the default is 5 seconds. Note that DDE_Send is actually a macro called DDE_SEND.KTM which resides in your KEA! directory. This macro automatically initiates and terminates KEA!'s conversation with the application. Therefore, you don't need to call DDE_Initiate or DDE_Terminate to perform the DDE_Send function. The arguments are:

App!Topic   	A string containing the application name and topic separated by an exclamation point (!) character.

Item   	A string containing the item name.

Value   	The new value for Item.

Timeout   	An integer specifying the timeout interval in seconds (default is 5 sec.).

This function returns False if the link cannot be established, or if the timeout occurs. The _ddeAErr variable contains the internal return code from the server, if the operation got that far. The _ddeAMsg variable contains a descriptive message.

Examples

DDE_Send( "KEAVT!MACRO", "Fonts", "8 Wide", 30 )

In this example, KEA! is both the client and the server. The client sets a new value for Fonts in the server application.


DDE_SetApp (macro function)
DDE_SetApp

DDE_SetApp( [Name=]string )

The DDE_SetApp function changes KEA!'s application name from KEAVT to the specified name. If the Name argument contains null, it restores the default name. The name can not exceed 19 characters. If the name is too long, KEA! truncates it and returns False. If successful, the function returns True.

Note  When you call this function, any active hotlinks to other applications are terminated and any saved ones no longer work because they contain the old application name.

Examples

DDE_SetApp( "NEW_CLIENT" )

This example changes KEA!'s application name from KEAVT to NEW_CLIENT. This is useful when both the client and the server are KEA! sessions, and both require unique application names.

DDE_SetApp( "KEATERM" )

This example sets the application name to comply with versions of KEAterm prior to 3.0.


DDE_Terminate (macro function)
DDE_Terminate

DDE_Terminate( [Channel=]channel )

The DDE_Terminate function ends the conversation indicated by Channel. It returns True if successful, and False if unsuccessful.

Examples

Channel = DDE_Initiate( "Excel", "System" )

If Channel <> 0

    ...

  If Not DDE_Terminate( Channel )

    Message( "DDE failed to terminate" )

    Return

  End

End


DDE_Timeout (macro function)
DDE_Timeout

DDE_Timeout( [Channel=]channel, [Value=]integer )

The DDE_Timeout function overrides the default timeout of 5 seconds for acknowledgments on the given channel. If Value is 0, it restores the default value. This functions returns True if successful, and False if unsuccessful.


Decode (macro function)
Decode

Decode( [String=]string [, [Key=]string]] )

The Decode function takes a string that was produced by the Encode function and restores the original string.

String   	The string to be restored.

Key   	If the string was encrypted, supply the same key that was passed into Encode. The key is case insensitive.

This function returns a string which is the restored version of the one passed.


DefaultButton (macro function)
DefaultButton

DefaultButton( [[Text=]String], [[Width=]Int], [[Height=]Int], [[Offset=]Int] )

The DefaultButton function displays a button labeled with the specified string. The default button is surrounded by a thick border.

You can create buttons to be used in dialog boxes. Their definitions must appear within the Controls section of a Begin Dialog..End construct. Choosing a button causes a button's When event to be triggered.

Example

Var Password

Begin Dialog( )

GroupBox( , True )

EditBox( "Password", Password, Width = 28 )

DefaultButton( "Encode", Width = 12 )

GroupEnd( )

GroupBreak( )

OkButton( Width = 15 )

CancelButton( Width = 15, Offset = 10 )

Button( "Help", Width = 15, Offset = 10 )

Do

ControlSet( "edit1", Control_Password, Value = 1 )

Continue

End


Disconnect (macro function)
Disconnect

Disconnect( )

The Disconnect function tells KEA! to disconnect from the current communications port. It is equivalent to the Disconnect command under the Connection menu. The function has no return value.

Example

Send( "ATH" + CR )

Begin

   When Match( "OK" )

      Disconnect( )      // disconnect from com port

   .

   .

   .

End


Disconnected (macro function)
Disconnected

Disconnected( )

The Disconnected function returns True if the current host connection has been broken.

When used in a Begin..When..End construct, this function detects a line drop.

Example

Begin

  Suspend( )                   // return control to user

  When Disconnected( )         // wait for disconnect

    Title( "Disconnected" )

    Break

End

The preceding example frees KEA! for processing but continually monitors the host connection in the background. When the host connection is broken, the macro changes the title of the dialog box to "Disconnected".


Display (macro function)
Display

Display[?]( [[Columns=]string], [[Lines=]string], [[Scroll=]string], [[StatusDisplay=]string], [[Show=]boolean], [[Block=]boolean], [[Blink=]boolean], [[Horizontal=]boolean], [[Vertical=]boolean], [[Page=]boolean], [[NewLine=]boolean], [[AutoWrap=]boolean], [[Transparent=]boolean], [[InverseScreen=]boolean] )

The Display function sets the options that affect the appearance of your display.

The arguments are equivalent to the options in the Display dialog box (Options Terminal menu).

Columns   	Number of columns for terminal display. Values are:

80   132

Lines   	Number of lines on a page, and, indirectly, the number of pages. Value can be any number between 24 and 144.

Scroll   	How much of screen to scroll. Values are:

Disabled   Jump1   Jump2   Jump4   Paged

StatusDisplay   	Use of VT status line. Values are:

None  Indicator  Host

Show   	Whether to display cursor.

Block   	Whether to display block or underline cursor.

Blink   	Whether to display blinking or steady cursor.

Horizontal   	Whether to couple cursor to left and right scrolling.

Vertical   	Whether to couple cursor to up and down scrolling.

Page   	Whether to display page from page memory when cursor moves to that page.

NewLine   	Which new line control sequence to send. Values are:

True	Send CR and LF

False	Send CR only

AutoWrap   	Automatically wrap text when last column used.

Transparent   	Whether to display control characters, or just process them.

InverseScreen   Reverse current foreground and background colors.

For macro language equivalents to other options in the Display dialog box, see the Display.Attributes, Display.Colors, and Display.Tabs functions.

Examples

Display( Columns = "132", Lines = "25", Scroll = "Jump4",

    StatusDisplay = "Indicator", Show = True, Block = True,

    Blink = True, Horizontal = False, Vertical = True, Page = True,

    NewLine = False, AutoWrap = False, Transparent = False,

    InverseScreen = False )

Sets the display to 132 columns and 25 lines with a blinking, block cursor. Scrolling is set to jump one-quarter screen at a time, and the cursor is coupled to vertical and page scrolling.

B = Display.Transparent

Records the current setting of the transparent mode option.


Display.Attributes (macro function)
Display.Attributes

Display.Attributes[?]( [[Reset=]boolean], [[Bold=]boolean], [[Underline=]boolean], [[Inverse=]boolean], [[Blink=]boolean], [[ISOColor=]boolean], [[Attribute=]string], [[Foreground=]string], [[Background=]string] )

The Display.Attributes function determines how attributes and attribute combinations are displayed. You can include multiple sets of the Attribute, Foreground, and Background arguments. These arguments are equivalent to the Attribute Colors dialog box options (Options menu).

Reset   	Set the attribute mappings to the default settings.

Bold   	Map or unmap the Bold attribute to color.

Underline   	Map or unmap the Underline attribute to color.

Inverse   	Map or unmap the Inverse attribute to color.

Blink   	Map or unmap the Blink attribute to color.

ISOColor   	Whether received ISO color sequences have any effect.

Attribute   	Attribute, attribute combination, or history. Select from the following list.

Normal	Blink Bold

Bold	Blink Underline

Underline	Blink Underline Bold

Underline Bold	Blink Inverse

Inverse	Blink Inverse Bold

Inverse Bold	Blink Inverse Underline

Inverse Underline 	Blink Inverse Underline Bold

Inverse Underline Bold	History (Background Only)

Blink

Foreground   	Color index as shown in Colors dialog box. Enter as a string or an integer.

Background   	Color index as shown in Colors dialog box. Enter as a string or an integer.

For macro language equivalents to other options in the Attributes dialog box, see the Display.Attributes.Default function.

Examples

Display.Attributes( Reset = True, Bold = False, Underline = False,

    Inverse = False, Blink = False )

The preceding example resets the attribute mappings to the default values. It also turns off color mapping for each attribute.

Display.Attributes( Attribute = "Blink" )

x = Display.Attributes.Foreground

y = Display.Attributes.Background

The preceding example reads the foreground and background colors for the blink attribute. The function remembers the last attribute referenced.


Display.Attributes.Default (macro function)
Display.Attributes.Default

Display.Attributes.Default( )

The Display.Attributes.Default function resets the attribute mappings to the default values. It is equivalent to the Default option in the Attribute Colors dialog box (Options menu).


Display.Colors (macro function)
Display.Colors

Display.Colors[?]( [[Reset=]boolean], [[UseExactColors=]boolean], [[LockUserColors=]boolean], [[VTColorIndex=]string], [Red=]string, [Green=]string, [Blue=]string )

The Display.Colors function determines the colors of the KEA! color indexes. You can include multiple sets of the VTColorIndex, Red, Green, and Blue arguments. These arguments are equivalent to the options in the Colors dialog box (Options menu).

Reset   	Reset colors to the factory colors.

UseExactColors   Give KEA! exact control over the colors it displays

LockUserColors   Prevent the host from changing colors.

VTColorIndex   	String integer between 0 and 15.

Red   	String integer between 0 and 255.

Green   	String integer between 0 and 255.

Blue   	String integer between 0 and 255.

For macro language equivalents to other options in the Colors dialog box, see the Display.Colors.CurrentIndexToFactory, Display.Colors.CurrentIndexToSaved, Display.Colors.ToFactoryColors, and Display.Colors.ToSavedColors functions.

Examples

Display.Colors( Reset = True,

    VTColorIndex = "1", Red = "255", Green = "0", Blue = "255",

    VTColorIndex = "2", Red = "0", Green = "255", Blue = "255",

    VTColorIndex = "3", Red = "255", Green = "255", Blue = "0",

    UseExactColors = False )

The preceding example sets the colors for VT color indexes 1, 2, and 3.

Display.Colors?( )

The preceding example prompts the user to select colors from the Colors dialog box.


Display.Colors.IndexToFactory (macro function)
Display.Colors.CurrentIndexToFactory

Display.Colors.CurrentIndexToFactory( )

The Display.Colors.CurrentIndexToFactory function sets the current color index to the default setting. It is equivalent to the Current Index To Factory option in the Colors dialog box (Options menu).


Display.Colors.IndexToSaved (macro function)
Display.Colors.CurrentIndexToSaved

Display.Colors.CurrentIndexToSaved( )

The Display.Colors.CurrentIndexToSaved function sets the current color index to the saved value. It is equivalent to the Current Index To Saved option in the Colors dialog box (Options menu).


Display.Colors.ToFactory (macro function)
Display.Colors.ToFactoryColors

Display.Colors.ToFactoryColors( )

The Display.Colors.ToFactoryColors function resets all color indexes to the default settings. It is equivalent to the To Factory Colors option in the Colors dialog box (Options menu).


Display.Colors.ToSaved (macro function)
Display.Colors.ToSavedColors

Display.Colors.ToSavedColors( )

The Display.Colors.ToSavedColors function resets all color indexes to your saved settings. It is equivalent to the To Saved Colors option in the Colors dialog box (Options menu).


DisplaySize (macro function)
DisplaySize

DisplaySize( )

The DisplaySize function returns the resolution of your screen in pixels. It returns the resolution as an array of two string values with X and Y subscripts.

Examples

Res = DisplaySize( )

Message( "Screen Size: " + Res.X + " by " + Res.Y )

The following example uses an alternate form of accessing elements in an array.

Res = DisplaySize( )

Message( "Screen Size: " + Res["X"] + " by " + Res["Y"] )


Display.Tabs (macro function)
Display.Tabs

Display.Tabs[?]( [Columns=]string )

The Display.Tabs function specifies where to set tab stops. It is equivalent to the Tabs dialog box under the Options menu.

Columns   	Specify the location at which you want tab stops. To use the default setting of 8 column intervals, enter +8 as the string.

For macro language equivalents to other options in the Tabs dialog box, see the Display.Tabs.Default function.

Examples

Display.Tabs( Columns = "+8" )

Changes tab stops to the default setting of 8 column intervals.

A = Display.Tabs.Columns

Records the current tab stop settings.


Display.Tabs.Default (macro function)
Display.Tabs.Default

Display.Tabs.Default( )

The Display.Tabs.Default function changes tab stop settings to the default of 8 column intervals.

This function is equivalent to the Default button in the Tabs dialog box (Options menu).


DropDownBox (macro function)
DropDownBox

DropDownBox( [[Text=]String], [[Value=]Var], [List=]Var, [[Width=]Int], [[Height=]Int], [[Offset=]Int] )

The DropDownBox function allows the user to select an item from a standard Windows drop-down list. The function must appear within the Controls section of a Begin Dialog..End construct. The drop-down list box is filled with the values from the List array. When the number of items is greater than seven, a scroll bar is added. When the user selects one of the items in the list, the list collapses again, and the selected value is displayed in the box.

Text   	The drop-down box is labeled with the Text string; this string appears to the left of the box.

Value    	If Value evaluates to a subscript in the List array, the corresponding entry is highlighted when the dialog box is displayed. On return from the dialog box, KEA! fills in Value with the subscript of the currently selected entry in the list box.

List   	The array to display. The user can select from this list.

Width   	A literal integer or integer variable that defines the horizontal space (in average character width) taken up by the complete control. It includes any label, user entry space, and separating white space.

Height   	A literal integer or integer variable that defines the vertical space (in character height) taken up by the control. It includes the borders and separating white space. Default is 1 line.

Offset   	A literal integer or integer variable that defines how far from the right edge of the space the left part of the control starts. You should specify an offset that is less than the width.

Example

Begin Dialog( "Sample Drop-down Box" )

  modelist[1] = "VT400-7bit"

  modelist[2] = "VT400-8bit"

  mode = 1	//set the default to 7 bit

  DropDownBox( "&Mode", mode, modelist, 40,,15 )

  OKButton( 40,,15 )

End

The preceding macro displays a drop-down list that contains two options.


Echo (macro function)
Echo

Echo( [Text=]string )

The Echo function displays text on the screen.

Example

CRLF = "^M^J"

Echo( CRLF + "This data appears on the next line of screen." )

Sends a carriage return and linefeed to the terminal display followed by a line of text.


Edit (macro function)
Edit

Edit( )

The Edit function invokes KEA! Edit, the macro editor and debug program. You can create a new macro, or edit an existing one. The function is equivalent to the Edit command under the Macro menu.


EditBox (macro function)
EditBox

EditBox( [[Text=]String], [[Value=]Var], [[Width=]Int], [[Height=]Int], [[Offset=]Int] )

The EditBox function displays an edit box with the Text string label to the left of it. The function must appear within the Controls section of a Begin Dialog..End construct. The Value string is used to fill in the edit box initially. On return from the dialog box, KEA! fills in Value with the string entered in the edit box.

Text   	The Edit box is labeled with the Text string; this string appears to the left of the box.

Value    	A string variable whose value is used initially in the edit box. On return from the dialog box, KEA! fills in the variable with the current string entry.

Width   	A literal integer or integer variable that defines the horizontal space (in average character width) taken up by the complete control. It includes any label, user entry space, and separating white space.

Height   	A literal integer or integer variable that defines the vertical space (in character height) taken up by the control. It includes the borders and separating white space. The box defaults to an appropriate height if you do not supply this parameter.

Offset   	A literal integer or integer variable that defines how far from the right edge of the space the left part of the control starts. You should specify an offset that is less than the width.

Example

password = ""	// Set up a variable.

Begin Dialog( "Sample Edit Box" )

  EditBox( "Enter password:", password, Width = 30 )

  OKButton( 30,,10 )

  Do

    // use Value = 1 to enable password mode

    ControlSet( "edit1", Control_Password, Value = 1 )

    Continue

  When Control( "button1" )

    Break

End

The preceding example creates a dialog box with an edit box and an OK button. In the concurrent statements, the edit box is initialized to password mode with the ControlSet so that any characters typed by the user appear as '*'.


EnableHistory (macro variable)
EnableHistory

EnableHistory = boolean

The EnableHistory variable specifies whether to store screen information in the History buffer when the information is cleared or scrolls out of view. Values are:

0	Do not keep screen data.

1	Keep screen data in the history buffer.

Changing this variable is equivalent to selecting the Enable History command under the Connection menu. It has no return value.

Examples

EnableHistory = True

Keeps scrolled and cleared screen data in the history buffer.

B = EnableHistory

Records the current setting of the EnableHistory variable.


Encode (macro function)
Encode

Encode( [String=]string [, [Key=]string]] )

The Encode function converts all the non-alphanumeric or space characters in a string into a form that contains no special characters. In this form, any string can be saved in an .INI file. It can also encrypt a string so that it cannot be read. To restore the string, use the Decode function.

String   	The string to be converted and optionally encrypted.

Key   	If supplied, this string is used to encrypt the string. The key is case insensitive.

This function returns a string which is the processed version of the one passed.


EnlargeFont (macro function)
EnlargeFont

EnlargeFont( )

The EnlargeFont function increases the font size by one increment. This function has no return value.


ErrorLevel (macro function)
ErrorLevel

ErrorLevel( [Level=]integer )

The ErrorLevel function controls which messages and requests to pass to the user for confirmation during macro execution. For those not passed, the macro takes the default action for that message. Messages are grouped, with a different icon for each group: Information 'I', Warning '!', Question '?', and Error (red octagon).

The default error level is 2.

This function returns the previous error level so you can restore it later.

Level   	Determines the level of user interaction. Values are:

0	Pass all messages to user; take no default action.

1	Pass Warning, Question, and Error messages to user; take default action on Information messages.

2	Pass Question and Error messages to user; take default action on Information and Warning messages.

3	Pass Error messages to user; take default action on Information, Warning, and Question messages.

4	Pass no messages to user; take default action on all.

Example

OldLevel = ErrorLevel( Level = 4 )

. . .

MsgBox( "Relative information message" )

. . .

ErrorLevel( OldLevel )

The preceding example sets the error level to 4 and stores the previous level in OldLevel.


Exit (macro function)
Exit

Exit([[Options=]integer] )

The Exit function quits this session. It is equivalent to the Close function and to the Close Session command under the File menu. The function returns no value.

Options	Values that determine when a user prompt appears, and whether a changed session configuration and layout are saved. If you specify no value in a category, the settings provided in the General function are used. You can combine one value from each of the following groups by adding them together.

Connected session

EXIT_DISCONNECT	Disconnect with no prompt.

Changed session configuration

EXIT_SAVECONFIG	Save.

EXIT_NOSAVECONFIG	Do not save.

EXIT_PROMPTCONFIG	Prompt for save.

Changed layout

EXIT_SAVELAYOUT	Save.

EXIT_NOSAVELAYOUT	Do not save.

EXIT_PROMPTLAYOUT	Prompt for save.

Example

Begin

   .

   .

   When Disconnected( )

      Exit(EXIT_NOSAVECONFIG + EXIT_NOSAVELAYOUT)

      //exit KEA! without saving and return to Windows

End


ExitAll (macro function)
ExitAll

ExitAll([[Options=]integer] )

The ExitAll function quits all KEA! sessions. It is equivalent to the Exit All command under the File menu. The function returns no value.

Options	Values that determine when a user prompt appears, and whether a changed session configuration and layout are saved. If you specify no value in a category, the settings provided in the General function are used. You can combine one value from each of the following groups by adding them together.

Connected sessions

EXIT_DISCONNECT	Disconnect with no prompt.

Changed session configurations

EXIT_SAVECONFIG	Save.

EXIT_NOSAVECONFIG	Do not save.

EXIT_PROMPTCONFIG	Prompt for save.

Changed layouts

EXIT_SAVELAYOUT	Save.

EXIT_NOSAVELAYOUT	Do not save.

EXIT_PROMPTLAYOUT	Prompt for save.


FileClose (macro function)
FileClose

FileClose( [File=]handle )

The FileClose function closes a file previously opened by a FileOpen function. It takes only one argument:

File    	The file handle obtained from a FileOpen function.


FileCopy (macro function)
FileCopy

FileCopy( [Name=]string, [Newname=]string )

The FileCopy function copies the contents of one file to another. Note that existing files are overwritten. The function takes the following arguments:

Name   	Source filename which can include a path, but no wildcards.

Newname   	Destination filename which can include a path, but no wildcards.

FileCopy returns the following values:

0	Success

1	Failure

Example

FileCopy( "C:\CONFIG.SYS", "C:\CONFIG.OLD" )

Copies the file CONFIG.SYS to CONFIG.OLD.


FileCreateDir (macro function)
FileCreateDir

FileCreateDir( [Name=]string )

The FileCreateDir function creates a directory. The parent directory must exist.

Name   	Name of the directory to create.

FileCreateDir returns the following values:

0	Success

1	Failure

Example

Creates a directory named UPLOAD in the KEA! home directory.

Destination = GetDirectory( Directory_Home )

FileCreateDir( Destination + "upload" )


FileDelete (macro function)
FileDelete

FileDelete( [Name=]string )

The FileDelete function deletes a file.

The function takes only one argument:

Name   	Name of the file to delete. The filename can include a path, but wildcards are not supported.

FileDelete returns the following values:

0	Success

1	Failure

Example

FileDelete( "C:\SAMPLE\TEST.TXT" )


FileDir (macro function)
FileDir

FileDir( [Name=]string, [[Options=]integer] )

The FileDir function returns a list of a directory's files matching a given pattern. The format of the return value is an array whose subscripts are the filenames and whose values contain additional information about each file. The format and content of the additional information is given by the Options argument.

This function takes the following arguments:

Name   	File specification string that can include a path and wild cards. To obtain a complete directory, use *.* as the file specification. Omitting *.* does not imply all files as it does with the DOS dir command.

Options   	Combinations of the following options allow the user to specify filtering by file attributes, as well as specify the format and content of the returned file information. Options can be combined using the addition operator ( + ). The following options specify the file types to include in the result.

Attr_Directory

Attr_NoDirectory

Attr_Volume

Attr_NoVolume

Attr_System

Attr_NoSystem

Attr_Hidden

Attr_NoHidden

Attr_Archive

Attr_NoArchive

Attr_Write

Attr_ReadOnly

Attr_Normal (default) (same as Attr_NoDirectory + Attr_NoSystem + Attr_NoVolume + Attr_NoHidden).

The following options specify whether to include file attributes, size, date, or time in the returned file information. The default for numeric values is File_Attr. For string values, an empty string is returned if no options are specified.

File_Attr	Integer or string (depending on format option) expressing the file attributes.

File_Size	Size of the file in bytes.

File_Date

File_Time	With numeric values, File_Time and File_Date have the same effect.
With string values, File_Time turns on File_Date (because time without date generally is not useful).

The following options specify the format of the returned file information. The default is numeric.

String_Value	In the returned array, values are a single string containing the information requested on each file. Individual fields are separated by spaces and appear in the following order:
• Attribute string with one or more of the following characters: R (read only), A (archive), H (hidden), S (system), D (directory), and V (volume).
• File size in bytes.
• Date and Time in the format specified by the Control Panel International settings.

Numeric_Value	In the returned array, each value is an array with subscripts ATTR, SIZE, TIME. Only the elements whose values were requested appear in each array.
Individual attributes can be filtered from ATTR by applying the BitAnd operator with the Attr_ constants.
SIZE is given in bytes.
TIME is the number of seconds since January 1st, 1970.
Note that subscript names are case sensitive, so that uppercase must be used.

Examples

MyDir = FileDir( "*.dat", File_Attr + File_Time + File_Size )

For MyFileName in MyDir

  MyAttr = MyDir[MyFileName]["ATTR"]

  MySize = MyDir[MyFileName]["SIZE"]

  MyTime = MyDir[MyFileName]["TIME"]

  // user processing of the numeric file information

End

MyDir = FileDir( "*.dat", File_Attr + File_Time + File_Size +

    String_Value )

For fname In MyDir

  Echo( fname + " " + MyDir[fname] + "^M^J" )

End

The preceding example first obtains the array MyDir using the default numeric format so that each array value is also an array containing the three subscripts ATTR, SIZE, and TIME. The second FileDir call obtains the array MyDir using the option String_Value. Its values are strings containing the file attributes, size, date, and time.

CR = "^M^J"

DirList = FileDir( "*.*", Attr_Write )

For FileName In DirList

  Echo( FileName + CR )  // display each file in list

End

The preceding example displays the list of files from the current directory whose write attributes are set.


FileEnd (macro function)
FileEnd

FileEnd( [File=]handle )

The FileEnd function tests for the end-of-file position. It takes only one argument:

File   	File handle obtained from a FileOpen function.

FileEnd returns the following values:

1	Pointer at end of file

0	Pointer not at end of file

Example

FileHandle = FileOpen( "NAMES.TXT" ) // open the file

LineCount = 1

While Not FileEnd( FileHandle )      // for each line in the file

  NextLine = FileRead( FileHandle )  // read the next line

  Echo( LineCount + ": " + NextLine + "^M^J" ) // display the line

  LineCount = LineCount + 1          // increment the line counter

End

FileClose( FileHandle )


FileExists (macro function)
FileExists

FileExists( [Name=]string, [[Options=]integer] )

The FileExists function tests whether a file exists, and if so, returns its attributes.

Name   	Filename including a full path name if required.

Options   	Determine the file attributes. Attr_Normal is the default option. If you specify neither or both the positive and negative attributes, the attribute is a do-not-care attribute. The values are:

Attr_Directory

Attr_NoDirectory

Attr_Volume

Attr_NoVolume

Attr_System

Attr_NoSystem

Attr_Hidden

Attr_NoHidden

Attr_Archive

Attr_NoArchive

Attr_Write

Attr_ReadOnly

Attr_Normal (same as Attr_NoDirectory + Attr_NoSystem + Attr_NoVolume + Attr_NoHidden)

FileExists returns the following values:

0	Specified file does not exist, or is invalid.

non-zero	File attributes are the same as specified in the Options argument.

Examples

The following two examples both open the file NAMES.TXT if it exists and is read-only.

CheckFile = FileExists( "C:\NAMES.TXT", Attr_ReadOnly )

If CheckFile  // if file exists

  FileOpen( "C:\NAMES.TXT" )

End

CheckFile = FileExists( "C:\NAMES.TXT" )

If( CheckFile BitAnd Attr_ReadOnly ) // if file exists and is read-only

  FileOpen( "C:\NAMES.TXT" )

End


FileGetDrives (macro function)
FileGetDrives

FileGetDrives( )

The FileGetDrives function returns an array containing a list of all currently mapped drives. For convenience, the drives are listed in the array subscripts as well as in the corresponding array values. Each drive is a string consisting of a letter followed by a colon.

Example

ListOfDrives = FileGetDrives( )

Input( "Select a drive:", "C:", Input_Dropdown, ListOfDrives )

If Result

  SetDirectory( Result )

End

In the preceding example, the user is prompted to select a drive from a drop-down input box. The list of possible inputs is generated using the FileGetDrives function.


FileGetElidedName (macro function)
FileGetElidedName

FileGetElidedName( [Name=]string, [Len=]integer )

The FileGetElidedName function is used when a filename needs to be limited to a certain reasonable length (for example, limited for printing or displaying). It truncates the filename to the given length, filling in the part it replaces with an ellipsis ("..."). The elided portion is in the middle of the directory path, where the last directory is kept first, the first one kept next, the second to last one kept next, and so forth. If the length of the full path is less than the given length, the full path is returned.

Example

FullName = "C:\KEATERM\MYDIR\MYFILE.KTM"

ShortName = FileGetElidedName( FullName, 23 )

In the preceding example, ShortName has the value "C:\...\MYDIR\MYFILE.KTM".


FileGetFromPath (macro function)
FileGetFromPath

FileGetFromPath( [Name=]string, [Options=]integer )

FileGetFromPath extracts the components specified by the Options argument from the given pathname.

Name   	Full pathname (delimited with '\' or '/')

Options   	One or more of the following constants:

File_Drive	Drive letter and ':'

File_Path	Path followed by a '\' (or '/')

File_Name	Filename (not including '.')

File_Extension	File extension, preceded by '.'

Returns the pathname with the requested components.

Example

myFile = "C:\KEATERM\MYFILE.TXT"

Drive = FileGetFromPath( myFile, File_Drive )

FileName = FileGetFromPath( myFile, File_Name + File_Extension )

In this example, Drive is "C:", and FileName is "MYFILE.TXT"


FileGetPos (macro function)
FileGetPos

FileGetPos( [File=]handle )

The FileGetPos function obtains the current read/write position in a file. The function takes only one argument:

File   	File handle obtained from a FileOpen function.

FileGetPos returns the position from the beginning of the file as an integer.


FileMove (macro function)
FileMove

FileMove( [Name=]string, [NewName=]string )

The FileMove function copies the contents of a file to a new location. If the copy is successful, the original file is deleted. The function takes the following arguments:

Name   	Original filename which can include a path.

NewName   	Destination path. If this path includes a filename, the file is also renamed.

FileMove returns the following values:

0	Success

1	Failure

Example

The following moves a copy of the named file into the directory DOCMT.

Dest = "e:\\docmt\\"

FileToUpload = Input( "Which file do you want to move?" )

If FileExists( FileToUpload )

  FileMove( FileToUpload, Dest+FileToUpload )

End


FileOpen (macro function)
FileOpen

FileOpen( [Name=]string, [[Options=]integer] )

The FileOpen function opens the named file. This function takes the following arguments:

Name   	Complete name (and path) of file to open.

Options   	One or more of the following integer constants:

File_Read (Default)	Open for reading only.

File_Write	Open for writing only.

File_ReadWrite	Open for reading and writing.

File_Create	Create if non-existent.

File_Append	Append to end of file (moves read/write pointer to end of file).

File_Prompt	Prompt on error or overwrite.

File_Truncate	Delete existing data.

FileOpen returns the following values:

non-zero	Integer file handle. Use this file handle as the File parameter in subsequent file I/O functions.

0	Open failed.

Example

FileHandle = FileOpen( "NAMES.TXT", File_ReadWrite + File_Append )

Opens NAMES.TXT for reading and writing and moves the file pointer to the end of the file.


FileRead (macro function)
FileRead

FileRead( [File=]handle, [[Len=]integer] )

The FileRead function reads data from a file. This function takes the following arguments:

File   	File handle obtained from a FileOpen function.

Len   	Number of bytes to read from the file. If not specified or 0, it reads the next line up to the line terminator. Maximum length is 256 characters. The returned string does not include the terminator.

FileRead returns a string containing the characters read. If you specified a number in Len, and there were fewer bytes available, it returns the string up until the number of bytes it read.

Examples

FileHandle = FileOpen( "RGNSALES.TXT", File_Read ) // Open file

Header = FileRead( FileHandle, 20 )                // Read 20 chars

While Not FileEnd( FileHandle )

  ReadData = FileRead( FileHandle )                // Read until CRLF

End

FileClose( FileHandle )


FileRemoveDir (macro function)
FileRemoveDir

FileRemoveDir( [Name=]string )

The FileRemoveDir function deletes a directory. The directory must be empty.

Name   	Name of the directory to delete.

FileRemoveDir returns the following values:

0	Success

1	Failure

Example

Removes the directory named UPLOAD in the KEA! home directory.

Destination = GetDirectory( Directory_Home )

FileRemoveDir( Destination + "upload" )


FileRename (macro function)
FileRename

FileRename( [Name=]string, [Newname=]string )

The FileRename function changes the name of a file. This function takes the arguments:

Name   	Name (and path) of the file you want to rename.

Newname   	New name for the file. (You cannot specify a new drive or path.)

FileRename returns the following values:

0	Success

1	Failure

Example

FileRename( "OLDFILE.TXT", "NEWFILE.TXT" )


FileSetPos (macro function)
FileSetPos

FileSetPos( [File=]handle, [Len=]integer, [[Options=]integer] )

The FileSetPos function moves the position of the read/write pointer in a file. This function takes the following arguments:

File   	File handle obtained from a FileOpen function.

Len   	Number of bytes to move the read/write pointer. A positive value moves the pointer toward the end of the file, wrapping at the end if necessary. A negative value moves it toward the beginning.

Options   	Determines the starting location:

0 (Default)	Beginning of file

1	Current location

2	End of file

FileSetPos returns the new position as an integer.

Example

FileHandle = FileOpen( "NAMES.TXT" )   // open file

  .

  .

FileSetPos( FileHandle, 20, 0 ) // advance pointer 20 characters

                                // from start of file


FileTransfer (macro function)
FileTransfer

FileTransfer[?]( [[Protocol=]String], [[DuplicateName=]String], [[CrashRecovery=]boolean], [[SendFullPath=]boolean], [[UsePath=]boolean], [[CreatePath=]boolean], [[RecurseSubDirectories=]boolean], [[ReceiveTo=]string], [[FileType=]string], [[ScanUnknownFileForType=]boolean], [[TextFiles=]string] )

The FileTransfer function specifies the file transfer protocol, and options common to all transfer methods.

The arguments are equivalent to the options in the File Transfer dialog box (Options on the Transfer menu).

Protocol   	Type of protocol to use for file transfers. Values are:

ASCII   Kermit   Xmodem   Ymodem   Zmodem   FTP

DuplicateName   How to handle an incoming file with the same name as an existing file in the target directory. Values are:

Rename   Overwrite   Discard   RenameOld   Append

CrashRecovery	Provides default for the Crash Recovery option in the Zmodem Receive dialog box. Zmodem only.

SendFullPath   	Whether to send the path information when transferring the file.

UsePath   	Whether to store the file based on the path supplied by the host, appended to the directory in ReceiveTo.

CreatePath   	Whether to create the path to store the file if the directories do not exist.

RecurseSubDirectories   Whether to transfer files in directories under the current directory.

ReceiveTo   	Directory into which to place the incoming file.

FileType   	Mode to use to transfer the file. Values are:

Automatic   Binary   Text

ScanUnknownFileForType   Whether to scan the file to determine if it contains 8-bit or control codes.

TextFiles   	Extensions you want to identify as text files.

For macro language equivalents to other options in the File Transfer dialog box, see the FileTransfer.AsciiOptions, FileTransfer.KermitOptions, FileTransfer.TextFileOptions, FileTransfer.XmodemOptions, FileTransfer.YmodemOptions, FileTransfer.ZmodemOptions, and FileTransfer.FTPOptions functions.

Examples

FileTransfer( Protocol = "ASCII" )

Transfers files using the ASCII method.

FileTransfer?( )

Displays the File Transfer dialog box for you to verify the file transfer configuration.

B = FileTransfer.Protocol

Stores the name of the current file transfer method.


FileTransfer.AsciiOptions (macro function)
FileTransfer.AsciiOptions

FileTransfer.ASCIIOptions[?]( [[StartHostReceiving=]string], [[EndHostReceiving=]string], [[NewlineAs=]string], [[NullLinePadding=]boolean], [[Character=]string], [[LimitTransmitRate=]boolean], [[Rate=]string] )

The FileTransfer.ASCIIOptions function specifies the various settings for ASCII Transmit and Copy/Paste transfers.

The arguments perform the same actions as the ASCII Options dialog box (Transfer menu Options) options.

StartHostReceiving   A macro that contains the commands to tell the host to start its side of the transfer. However, if the file transfer is effected in a macro, this argument is not used.

EndHostReceiving   A macro that contains the commands to tell the host to end its side of the transfer. However, if the file transfer is effected in a macro, this argument is not used.

NewlineAs   	Specify what to send to the host to indicate the end of a line. Values are:

CR	Carriage return only.

CRLF	Carriage return and line feed.

LF	Line feed only.

NullLinePadding   Whether to pad null lines with a character.

Character   	Specify character to use to pad null lines.

LimitTransmitRate   Whether to limit how fast to send characters to the host.

Rate   	Specify the number of characters per second to use for the Limit Transmit Rate.

Examples

FileTransfer.ASCIIOptions( NullLinePadding = True, Character = " " )

Pads null lines with blank characters.

B = FileTransfer.ASCIIOptions.Character

Records the value of the padding character.

FileTransfer.ASCIIOptions?( )

Displays the ASCII Options dialog box that lets you set parameters for transferring text files.

FileTransfer.ASCIIOptions.StartHostReceiving = "Send( \"cat >\" +

    HostFileName + \"^m\" ) Wait( 2 )"

FileTransfer.ASCIIOptions.EndHostReceiving = Send( "^d" )

Configures ASCII Transmit to send commands to open a file on a Unix host before transmitting a file. HostFileName is a predefined variable containing the name of the file to transmit to the host.


FileTransfer.FTPOptions (macro function)
FileTransfer.FTPOptions

FileTransfer.FTPOptions[?]([[Host=]string], [[Userid=]string], [[Account=]string], [[FTPPort=]string], [[E-MailAddress=]string], [TCPType=]string, [[HostsFile=]string] )

The FileTransfer.FTPOptions function specifies the settings for your local FTP.

The arguments perform the same actions as the FTP Options dialog box.

Host   	Name of the host to which you want to connect.

Userid   	Your user name.

Account   	Your account name if required by your host.

FTPPort   	Specify a port number if other than the default 21.

InternetMailAddress   If you supply your E-mail address, it is used as the default password when you log into a host anonymously.

TCPType   	Specify Windows Sockets.

HostsFile   	The host names file. If your TCP/IP stack is set up to use a hosts file, specify the same one.

PassiveModeTransfers    FTP data connection is established by the client rather than by the server. This is sometimes necessary if the client is behind a firewall. Values are:

True	Data connection established by client.

False	Data connection established by server.

Example

FileTransfer.FTPOptions.InternetMailAddress = "yourname@company.com"

Configures FTP to use your Internet Email address as default when logging in as user Anonymous.


FileTransfer.KermitOptions (macro function)
FileTransfer.KermitOptions

FileTransfer.KermitOptions[?]( [[StartHostReceiving=]string], [[StartHostSending=]string], [[QuitHostServer=]string], [[RemoteKermit=]string], [[BlockCheck=]string], [[RxPacketLength=]string], [[TxPacketMaxLength=]string], [[WindowRequest=]string] )

The FileTransfer.KermitOptions function specifies the settings for your local Kermit.

The arguments perform the same actions as the Kermit Options dialog box options.

StartHostReceiving   A macro that contains the commands to tell the host to start receiving files. However, if the file transfer is effected in a macro, this argument is not used.

StartHostSending   A macro that contains the commands to tell the host to start sending files. However, if the file transfer is effected in a macro, this argument is not used.

QuitHostServer   	A macro that contains the commands to tell the host what to do when transmission completes, or after a Finish command is sent. However, if the file transfer is effected in a macro, this argument is not used.

RemoteKermit   	Specify the type of remote Kermit to which you will connect. Values are:

Interactive   Server

BlockCheck   	Specify the type of error detection to use on a transmit. Values are:

Sum-1   Sum-2   CRC

RxPacketLength   Specify the maximum size for received packets.

TxPacketMaxLength   Specify the maximum size for transmitted packets.

WindowRequest   Specify the maximum number of unacknowledged packets.

For macro language equivalents to other options in the Kermit Options dialog box, see the FileTransfer.KermitOptions.Advanced function.

Example

FileTransfer.KermitOptions?( WindowRequest = "6" )

Display the Kermit Options dialog box, and set the Window Request field to 6.


FileTransfer.KermitOptions.Advanced (macro function)
FileTransfer.KermitOptions.Advanced

FileTransfer.KermitOptions.Advanced[?]( [[RxPacketStartChar=]string], [[TxPacketStartChar=]string], [[EnableTxPacketEndChar=]boolean], [[TxPacketEndChar=]string], [[RxTimeoutInSeconds=]string], [[TxTimeoutInSeconds=]string], [[ErrorRetryLimit=]string], [[ControlQuoteCharacter=]string], [[Enable8thBitQuoting=]boolean], [[EightBitQuoteCharacter=]string], [[EnableCompression=]boolean], [[CompressionCharacter=]string], [[PadCharacter=]string], [[No=]string], [[AttributePackets=]boolean] )

The FileTransfer.KermitOptions.Advanced function specifies more advanced settings for your local Kermit.

The arguments perform the same actions as the options in the Advanced dialog box that you access from the Kermit Options dialog box.

RxPacketStartChar   Character to use as received packet start character.

TxPacketStartChar   Character to use as packet start character.

EnableTxPacketEndChar   Whether to use a packet end character.

TxPacketEndChar   Character to use as packet end character.

RxTimeoutinseconds   How long to wait to receive a packet before issuing a time out. Values are any number from 0 through 94.

TxTimeoutinseconds   How long to wait for host to transmit a packet before issuing a time out. Values are any number from 0 through 94.

ErrorRetryLimit   How many consecutive errors to allow on the same packet before aborting the transfer.

ControlQuoteCharacter   Printable character to use as the prefix for printable control character sequences.

Enable8thBitQuoting   Whether to use a special character to let 8-bit data pass through a 7-bit communications channel.

EightBitQuoteCharacter   Character to use as 8 bit quote character.

EnableCompression   Whether to use a special compression character before long strings of repeated characters to speed up transmission.

CompressionCharacter   Character to use as special compression character.

PadCharacter   	Character to send before sending first character of packet.

No   	Number of pad characters to send.

AttributePackets   Whether to use attribute packets.


FileTransfer.TextFileOptions (macro function)
FileTransfer.TextFileOptions

FileTransfer.TextFileOptions[?]( [[SendNewlinesAs=]string], [[CtrlZIsEndOfFile=]boolean], [[MapNewlinesToCRLF=]boolean], [[AddCtrlZAtEndOfFile=]boolean] )

The FileTransfer.TextFileOptions function specifies how to translate text files during transfer.

The arguments perform the same actions as the Text File Options dialog box (Options from Transfer menu) options.

SendNewlinesAs   Specify what to use to indicate the end of a line in a text file.

CtrlZIsEndOfFile   Whether to stop transfer when KEA! encounters a CTRL+Z.

MapNewlinesToCRLF   Whether to translate a received LF to CRLF.

AddCtrlZAtEndOfFile   Whether to write a CTRL+Z at the end of a text file.

For macro language equivalents to other options in the Text File Options dialog box, see the FileTransfer.TextFileOptions.Translation function.


FileTransfer.TextFileOptions.Translation (macro function)
FileTransfer.TextFileOptions.Translation

FileTransfer.TextFileOptions.Translation[?]( [[Enable=]boolean], [[Method=]string], [[LocalCharacterSet=]string], [[HostCharacterSet=]string] )

The FileTransfer.TextFileOptions.Translation function specifies how to use character translation when transferring text files.

The arguments perform the same actions as the Translation dialog box (Transfer menu Options, Text File Options) options.

Enable   	Whether to turn on translation for text file transfer.

Method   	Which translation method to use. Values are:

ExactOnly   Readability

LocalCharacterSet   Which character set to use on the personal computer. Values are:

ISOLatin1   USEnglish(437)   Multilingual(850)   Portugal(860)   Canadian-French(863)   Nordic(865)

HostCharacterSet   Which character set to use on the host. Values are:

Automatic   ASCII   ISOLatin1   DEC-Multinational   National

Example

FileTransfer.TextFileOptions.Translation( Enable = False,

    Method = "Readability", LocalCharacterSet = "ISOLatin1",

    HostCharacterSet = "Automatic" )


FileTransfer.XmodemOptions (macro function)
FileTransfer.XmodemOptions

FileTransfer.XmodemOptions[?]( [[StartHostReceiving=]string], [[StartHostSending=]string], [[BlockSize1K=]boolean], [[AckTimeout=]string], [[CRC16Bit=]boolean] )

The FileTransfer.XmodemOptions function specifies the Xmodem setup options.

The arguments perform the same actions as the Xmodem Options dialog box.

StartHostReceiving   Specify a macro that contains the commands to tell the host to start receiving files. However, if the file transfer is effected in a macro, this argument is not used.

StartHostSending   Specify a macro that contains the commands to tell the host to start sending files. However, if the file transfer is effected in a macro, this argument is not used.

BlockSize1K   	Whether to use 1K size packets to send files.

AckTimeout   	How many seconds to wait for an acknowledgment of a sent packet.

CRC16Bit   	Whether to use a 16 bit check sum to verify the integrity of packets.

Example

FileTransfer.XmodemOptions?( )

Displays the Xmodem Options dialog box and lets you make changes.

FileTransfer.XmodemOptions.StartHostReceiving =

    "Send( \"rz -x \" + HostFileName + \"^m\" )"

Configures Xmodem to send a command to the host to start receiving files. HostFileName is a predefined variable containing the name of the file to be transmitted to the host.


FileTransfer.YmodemOptions (macro function)
FileTransfer.YmodemOptions

FileTransfer.YmodemOptions[?]( [[StartHostReceiving=]string], [[StartHostSending=]string], [[AckTimeout=]string], [[GOption=]boolean] )

The FileTransfer.YmodemOptions function specifies the Ymodem setup options.

The arguments perform the same actions as the Ymodem Options dialog box.

StartHostReceiving   Specify a macro that contains the commands to tell the host to start receiving files. However, if the file transfer is effected in a macro, this argument is not used.

StartHostSending   Specify a macro that contains the commands to tell the host to start sending files. However, if the file transfer is effected in a macro, this argument is not used.

AckTimeout   	Specify how many seconds to wait for an acknowledgment of a sent packet.

GOption   	Select to use the Ymodem-G protocol.

Example

FileTransfer.YmodemOptions?( )

Displays the Ymodem Options dialog box and lets you make changes.

FileTransfer.YmodemOptions.StartHostReceiving =

    "Send( \"rz -y \" + HostFileName + \"^m\" )"

Configures Ymodem to send a command to the host to start receiving files. HostFileName is a predefined variable containing the name of the file to be transmitted to the host.


FileTransfer.ZmodemOptions (macro function)
FileTransfer.ZmodemOptions

FileTransfer.ZmodemOptions[?]( [[StartHostReceiving=]string], [[StartHostSending=]string], [[AutomaticallyStartReceive=]boolean], [[AllowUncheckedCrashRecovery=]boolean], [[EscapeCRandDLE=]boolean], [[TransmitWindowRequest=]integer] )

The FileTransfer.ZmodemOptions function specifies the Zmodem setup options.

The arguments perform the same actions as the Zmodem Options dialog box.

StartHostReceiving   Specify a macro that contains the commands to tell the host to start receiving files. However, if the file transfer is effected in a macro, this argument is not used.

StartHostSending   Specify a macro that contains the commands to tell the host to start sending files. However, if the file transfer is effected in a macro, this argument is not used.

AutomaticallyStartReceive   Whether to start receiving files after receiving a special Zmodem code.

AllowUncheckedCrashRecovery   Allow crash recovery to occur even when the remote Zmodem does not support CRC checking and so cannot tell whether the local file resembles the remote file in anything more than its name. Use caution when enabling this option—the resulting "transferred" file could be a combination of unrelated data.This option has no effect unless Crash Recovery has been enabled in the Receive dialog box.

EscapeCRandDLE   Select to send an Escape character before sending any CR or DLE character.

TransmitWindowRequest   The number of 1K blocks that can be transmitted before Zmodem waits for an acknowledge. If this is set to 0, Zmodem does not wait for acknowledges.

Example

FileTransfer.ZmodemOptions?( )

Displays the Zmodem Options dialog box and lets you make changes.

FileTransfer.ZmodemOptions.StartHostReceiving =

    "Send( \"rz \" + HostFileName + \"^m\" )"

Configures Zmodem to send a command to the host to start receiving files. HostFileName is a predefined variable containing the name of the file to be transmitted to the host.

FileTransfer.ZmodemOptions.AutomaticallyStartReceive = True

Tells KEA! to start receiving files when it receives a special Zmodem code from the host.


FileValidateName (macro function)
FileValidateName

FileValidateName( [Name=]string, [[Unique=]integer] )

The function FileValidateName converts the given filename to a valid filename for the local file system—DOS or an NTFS file partition. In a DOS system, spaces are replaced with underscore characters and all other invalid characters are replaced with # characters. Filenames are generated from the first eight characters up to the first dot. The three characters following the first dot are assumed to be the file extension. Any further characters are ignored.

If you want to validate a filename for a FAT partition in Windows NT, be sure to include the drive letter before the filename so that KEA! doesn't assume the file is an NTFS file.

With the parameter Unique set to True (1), you can ensure that the returned filename does not conflict with any files in the current directory. If the name already exists, the function derives a filename that is guaranteed not to exist in the current directory. It does this by adding an integer 1, 2, 3 etc. to the filename at the left of the dot until it no longer conflicts. If the filename is already at the maximum length, the last character is changed to a number. Or, if the last character in the filename is already a number, even though the filename is not at the maximum length, that number is incremented by one until it no longer conflicts.

Name	Filename including a full path name if required.

Unique	Whether to return a unique filename if the given file already exists in the current directory.

0 (Default)	Do not attempt to generate a unique filename.

1	Generate a unique filename if the file already exists.

Returns a filename as described above.

Example

FileValidateName( "e:\temp\a long filename.and extension" )

Returns "e:\temp\a_long_f.and".

FileValidateName( "shuttle.ktm", Unique = True )

Returns "shuttle1.ktm".


FileWrite (macro function)
FileWrite

FileWrite( [File=]handle, [Data=]string, [[Len=]integer] )

The FileWrite function writes a string to a file. This function takes the following arguments:

File   	File handle obtained from a FileOpen function.

Data   	String to write starting at the current pointer position.

Len   	Number of bytes to write to the file, with null padding if necessary. If you do not specify a value, or specify 0, FileWrite writes the entire string to the file, and appends the CRLF line terminator.

FileWrite returns the number of characters written to the file.

Example

Consider a file NAMES.TXT, which contains one name followed by a CRLF:

    JANE<CRLF>

The following macro opens the file for writing and positions the file pointer at the end of the file. It then appends a new name and closes the file.

FileHandle = FileOpen( "C:\NAMES.TXT", File_Write + File_Append )

FileWrite( FileHandle, "MARY", 4 )

FileClose( FileHandle)  // close file so that the change takes effect

After executing the macro, the data in the file appears as:

    JANE<CRLF>

    MARY


Fonts (macro variable)
Fonts

Fonts = string

The Fonts variable specifies which font size is used in the emulation window. Changing its value is equivalent to selecting the Font Width option in the View dialog box (Options menu). Values are:

Auto	3 Wide	4 Wide	5 Wide	6 Wide
7 Wide	8 Wide	9 Wide	10 Wide	12 Wide
14 Wide	16 Wide	18 Wide	20 Wide	24 Wide
If you specify Auto, KEA! selects a font based on the horizontal size of the window.

The variable returns a value containing an ampersand (&) in the string.

Examples

CurrentFont = Fonts

Stores the current font setting.

Fonts = "3Wide"

Changes the font size to 3 Wide.


For..In..End (macro statement)
For...In...End

For Variable In ArrayName
     Statement(s)
End

The For..In..End control statement loops over all defined elements in an array. The loop order is numbers followed by alphabetic characters in lexical order. Variable holds, in turn, the subscript value for each item in the array. The order is: 0123456789aAbBcC...zZ.

Examples

DaysOfWeek[1] = "Monday"

DaysOfWeek[2] = "Tuesday"

  .

  .

  .

For index In DaysOfWeek

  Echo( "Day " + index + " is " + DaysOfWeek[index] )

End

The preceding macro displays a list of days of the week from an array.

CR = "^M^J"

DirList = FileDir( "*.*", Attr_Write )

For FileName In DirList

  Echo( FileName + CR )  // display each file

End

The preceding macro displays a list of files on the screen.

Phone_List["home"] = "555-1212"

Phone_List["work"] = "556-4321"

For Index In Phone_List

  Echo( Index + "  " + Phone_List[Index] + "^M^J" )

End


Format (macro function)
Format

Format( [Item=]value, [Format=]string )

The Format function converts a long integer expression to an ASCII string (time, date, or general number). It formats the string according to the supplied format (and WIN.INI's [intl] section information) or to the format specified in the Format argument.

Item   	The expression can be a variable or a number.

Format   	Defines the format of the converted date string or number. If omitted, the string is formatted according to the supplied format in the WIN.INI [intl] section. If the macro is formatting a number (not a date or time), and the format argument string does not contain enough 0s (digit placeholders) and #s, the macro considers the format to have enough extra digit placeholders on the left to display the number correctly. For numbers you can have up to three sections in the Format string; each section is separated by a semicolon (;). The first section represents the format for displaying a positive number, the second section represents the format for a negative number, and the third section represents the format for displaying a zero.

   	The following lists the accepted picture formats:

d	day in month, no leading 0

dd	day in month, always 2 digits

ddd	day of week as 3 letter abbreviation

dddd	day of week spelled out

ddddd	date in Windows short format

dddddd	date in Windows long format

w	day of week as a number (Sun=1 ... Sat=7)

ww	week of year as a number (1 ... 53)

m	month number, no leading 0 (if follows h, then minute)

mm	month number, always 2 digits (if follows h, then minute)

mmm	month as 3 letter abbreviation

mmmm	month spelled out

y	day of year as a number

yy	year, 2 digits

yyyy	year, 4 digits

h	hours, no leading 0

hh	hours, always 2 digits

n	minutes, no leading 0

nn	minutes, always 2 digits

s	seconds, no leading 0

ss	seconds, always 2 digits

ttttt	time in Windows format

a/p A/P	a or p in given case (12:00p is noon)

am/pm AM/PM	am/pm in given case

ampm	am/pm indicator from WIN.INI

:	Windows time separator string (not actual :)

/	Windows date separator string (not actual /)

0	digit placeholder, becomes digit or 0 (can have leading 0s)

.	decimal placeholder - use Windows string - treat as fixed point

%	percentage placeholder - divide number by 100 and display with %

,	thousand separator - use Windows string

#	pad field with leading blanks when number is small

>	force uppercase from now on

<	force lowercase from now on

   	The following shows the acceptable syntax for number formats:

#,##;(#,##):#	Positive number displayed #,## and a negative number displayed in parentheses

#,##;-#,##:#	Positive number displayed #,## and a negative number displayed with preceding minus sign (-)

"'True';;'False'"	Non-zero numbers are represented as True, and zero is represented as False

The Format function simply copies all unrecognized and escaped (\) characters, and all quoted strings (single or escaped double quotes) specified for the format argument.

Examples

Today = SystemTime( )

NameOfDay = Format( Today, "dddd" )

MsgBox( "Today is " + NameOfDay )

The preceding macro displays current day of the week in a message box.

clock = SystemTime( )

Numeric = Format( clock, "h:nn:ss am/pm" )

MsgBox( "The time is " + Numeric )

The preceding macro displays current time in a message box.

CR = "^M^J"

Numeric1 = 1234

Numeric2 = -4321

Numeric3 = 0

Alpha = Format( Numeric1, "#,###;( #,### )" )

Beta = Format( Numeric2, "#,###;( #,### )" )

Gamma = Format( Numeric2, "#,###" )

Delta = Format( Numeric3, "'True';;'False'" )

Pi = Format( Numeric1, "'True';;'False'" )

MsgBox( "First Number: " + Alpha )

MsgBox( "Negative Numbers: " + CR + Beta + CR + Gamma )

MsgBox( "Delta = " + Delta + CR + "Pi = " + Pi )

The preceding macro displays three message boxes with various number formats.


Function (macro statement)
Function

Function Name( [[Var ]arg1]] [,[Var ]arg2] ... )
  statements
  [Return [expression]]
End

The Function control statement defines a user-defined function. The following rules apply when defining functions:

•	You must define a user-defined function before calling it. You must define it in the same macro file as its caller. However, you can define functions that call each other in any order.

•	You can include up to six arguments.

•	The caller can identify the arguments with the function's internal variable names. The usual rules about positional and named arguments apply. If the caller omits the variable names, you must preserve the order of the arguments, using commas to maintain the place of omitted arguments.

•	Arguments not specified in a call receive the value null.

•	A function argument is passed by reference if the Var keyword precedes the argument in the function's definition; otherwise it is passed by value. When the value of an argument passed by reference changes, the argument's value also changes at the scope of the caller.

•	A function can use the Var statement to declare local variables that do not exist outside the function.

•	You can call functions recursively.

Examples

Function DoubleVal( n )

  Return n + n

End

Function DoubleRef( Var n )

  n = n + n

End

a = 5

b = 5

MsgBox( "a=" + a + ", b=" + b ) // prints 5, 5

c = DoubleVal( a )

DoubleRef( b )

MsgBox( "a=" + a + ", b=" + b + ", c=" + c ) // prints 5, 10, 10

The preceding example illustrates the difference between passing an argument by value and by reference. The variable a is passed to the function DoubleVal by value so a's value only changes locally as n within the function. The variable b, on the other hand, is passed to the function DoubleRef by reference. Therefore the change to its value in DoubleRef also holds at the level of the calling function.

Function Sum( a, b )

  Var c

  c = a + b

  Return c

End

The preceding macro shows the use of local variables inside functions. The function declares c as a local variable; the variable does not exist outside the function.


General (macro function)
General

General[?]( [SaveChangesOnExit=]string, [SaveLayoutOnExitAll=]boolean, [PromptOnExitAll=]string, [OldKeatermMenus=]boolean )

The General function lets you set other configuration options. The arguments are equivalent to the options in the General Settings dialog box (Options menu).

SaveChangesOnExit   Choose whether configuration changes are saved on exit.

Yes	Changes are always saved.

No	Changes are not saved.

Prompt	If the configuration has changed, the Exit dialog box appears on exit, asking the user whether or not to save the changes.

SaveLayoutOnExitAll   Save the current layout whenever the user exits using the Exit All command on the File menu, and there are changes to the layout.

PromptOnExitAll   Controls whether the Exit dialog box is displayed whenever the user exits using the Exit All command on the File menu.

Yes	Always show it.

No	Do not show the Exit dialog box (unless the option Save Changes on Exit is set to Prompt).

If Connected	Show the Exit dialog box if one or more sessions are still connected.

OldKeatermMenus   Change the organization of KEA! menus and commands to the older, pre-Version 4 style.


GetCursor (macro function)
GetCursor

GetCursor( )

The GetCursor function returns the current text cursor position.

The function returns the position as an array of three integer values with subscripts of PAGE, ROW, and COL (1 to 80). For a description of Row and Col as used in this function, see GetSelection.

Example

X = 0

Clear( )

Echo( "Watch the cursor > " )

While X < 20

  X = X + 1

  Echo( "*" )             // move cursor right one position

  Cursor = GetCursor( )   // get cursor coordinates

  // Extract page, row, and column :

  Page    = Cursor["PAGE"]

  Row     = Cursor["ROW"]

  Column  = Cursor["COL"]

  Wait( 2 )

  Message( " **  PAGE: " + Page + " ROW: " + Row +

      "  COLUMN: " + Column )

End

The preceding macro displays the cursor position on the status line while the position is changing.


Definition of PRODNAME bookmark:KEA!

Definition of SHORTNAME bookmark:KEA!

Definition of EDITNAME bookmark:KEA! Edit


GetDirectory (macro function)
GetDirectory

GetDirectory( [Options=]integer )

The GetDirectory function returns a string containing the requested directory path.

Options   	The directory name returned depends on which of the three possible values you use. Values are:

Directory_Base	Location of the KEA! executable (.EXE) file.

Directory_Current   Current directory at the time of the call; usually the directory where KEA! starts, or the Working Directory specified in the Windows Properties dialog box if different from KEA!'s location.

Directory_Home	A private user directory on your own machine. Unless you are using a shared network copy of KEA!, this directory is by default called USER, under Directory_Base.

Directory_Macro	Directory from which the current macro loaded.

Directory_System   Location of the Windows System directory.

Directory_Windows   Location of the Windows directory.

Examples

If KEA! was run from the directory C:\KEAVT, either of the following GetDirectory functions returns "C:\KEAVT\". This assumes the macro containing the functions is run from this directory.

CurDir = GetDirectory( Directory_Current )

KEADir = GetDirectory( Directory_Home )

If the macro containing the GetDirectory functions is run from the directory C:\MACROS, the following functions return strings as shown.

MacroDir = GetDirectory( Directory_Macro )   // returns "C:\MACROS\"

CurDir   = GetDirectory( Directory_Current ) // returns "C:\KEAVT\"

KEADir   = GetDirectory( Directory_Home ) // returns "C:\KEAVT\"

Note  The value of Directory_Current defaults to the KEA! startup directory unless you use the SetDirectory( ) function. You must use this function if the macro needs to read or write a file in a directory other than the current directory.


GetEnv (macro function)
GetEnv

GetEnv( [Var=]string )

The GetEnv function returns the value of the specified DOS environment variable Var. It returns null if it cannot find the variable. You set environment variables in DOS, often by running a batch (.BAT) file at startup.

Examples

If you set environment variables in your AUTOEXEC.BAT as follows:

  REM AUTOEXEC.BAT

  PATH = C:\;C:\KEAVT;C:\KEALINK

  SET WINDIR = D:\WINDOWS

You can trap them from within KEA! as follows:

PathEnv = GetEnv( "PATH" )

WinEnv  = GetEnv( "WINDDIR" )

You can then manipulate and display these variables, send them to the host, or use them in some other operation.


GetIni (macro function)
GetIni

GetIni( [File=]string, [Section=]string, [Key=]string [,[String=]string] )

The GetIni function returns the specified value in the registry database, or named .INI file.

The meaning of key in this description may be confusing. In the registry database, key refers to a group of values. In addition this function has a parameter Key which identifies one of a number of values grouped in a registry key.

The File parameter determines whether the function searches in the registry database or an .INI file as follows:

Filename in File parameter with path removed	Section parameter identifying a registry key or .INI file section.	Action
WIN.INI		Returns a value from the registry database. The Section parameter determines the registry key; Key is the value name.
KEA.INI	KEAVT  *	Returns the value named by Key in the current user's registry key: HKEY_CURRENT_USER\Software\Attachmate\KEA!\n.nn\KEAVT
KEA.INI	Compatibility  *	Returns the value named by Key in the machine-specific registry key: HKEY_LOCAL_MACHINE\Software\Attachmate\KEA!\n.nn\Compatibility
KEA.INI	other SectionName	The Section parameter identifies a key below the current user's own registry key:  HKEY_CURRENT_USER\Software\Attachmate\KEA!\SectionName Returns the value named by Key in this key.
other .INI filename	Name of section in the .INI file.	Returns the value of the line beginning Key= under the heading [Section] in an .INI file.
In File and Section, case is ignored.
The optional String parameter is a default value that is returned if Section and Key are not found.

*  If the string "Vn.nn" is included in the Section parameter, it is ignored. A Section parameter that includes an older version label is processed as section names in the other category. For example, GetIni with a parameter Section="KEAVT V4.10" searches the key HKEY_CURRENT_USER\Software\Attachmate\KEA!\KEAVT V4.10.

Examples

S = GetIni("c:\transfer\kea.ini", "KEAVT", "AlternateFont", "")

Returns the value of AlternateFont in the Registry key
HKEY_CURRENT_USER\Software\Attachmate\KEA!\4.12\KEAVT

S = GetIni("c:\transfer\kea.ini", "compatibility", "AsyncConnect", "")

Returns the value of AsyncConnect in the Registry key
HKEY_LOCAL_MACHINE\Software\Attachmate\KEA!\n.nn\Compatibility

S = GetIni("c:\transfer\kea.ini", "mine", "Test", "")

Returns the value of Test in the Registry key
HKEY_CURRENT_USER\Software\Attachmate\KEA!\mine

S = GetIni("c:\transfer\mine.ini", "compatibility", "Test", "")

Returns the value of the line "Test=" as it appears in the [Compatibility] section of the file C:\TRANSFER\MINE.INI


GetSelection (macro function)
GetSelection

GetSelection( )

The GetSelection function returns the coordinates of the current selection. It returns a structure (that is, an array) that contains the following elements:

TYPE   	One of:

Select_Stream (left mouse-button selection)

Select_Block (right mouse-button selection)

Select_None (no selection)

ROW   	Starting row of the selection.

COL   	Starting column of the selection. 1 to 80 (or 132)

ENDROW   	Ending row of the selection.

ENDCOL   	Ending column+1 of the selection.

PAGE   	The page on which the selection occurs. Page can be from 1 to the maximum number of pages, or -1 to indicate the VT status bar.

The value of ENDCOL is one greater than the last character included in the selection.

If there is no selection, the function returns a structure which contains only one element, TYPE, having a value of Select_None.

The following illustrates the meaning of ROW and PAGE.

------------------------------------------------------------

ROW -n

History Area
The rows are numbered as an extension of page 1

ROW 0

------------------------------------------------------------

ROW 1

PAGE 1

ROW 24 (or page length)

------------------------------------------------------------

ROW 1

PAGE 2

ROW 24 (or page length)

------------------------------------------------------------

. . .

. . .

------------------------------------------------------------

Example

CurrentSelect = GetSelection( )

If CurrentSelect.Type = Select_None

  MsgBox( "No selection" )

ElseIf CurrentSelect.Type = Select_Block

  MsgBox( "Block" )

ElseIf CurrentSelect.Type = Select_Stream

  MsgBox( "Stream" )

End


GetVersion (macro function)
GetVersion

GetVersion( )

The GetVersion function returns an array with information about the current KEA! application. The array subscripts are:

ENVIRONMENT   "Windows NT" or "Windows" or "Windows 95"

KTVERSION   	current KEA! version (for example, "4.22.0")

MODEL   	KEA! model (usually "KEAVT")

PROCESSOR   	personal computer microprocessor type (for example, "Alpha", "486")

PRODUCT   	name of the application (usually "KEA!")

WINVERSION   current Windows version (for example, "3.10")

Note that the array subscripts are case-sensitive, so the subscript names should always be typed in upper case.


Global (macro statement)
Global

Global Var1 [,VarN] ...

The Global macro statement declares a global variable. A global variable is available to all macros without having to pass it as an argument. It continues to exist until KEA! exits.

Examples

// --- MainMacro( )

  Global Username

  Global Userpath

  Global Userfile

  Username = GetEnv( "NAME" )

  Userpath = "F:\USERS\" + Username + "\"

  Userfile = "USERFILE.TXT"

 MyMacro( )    // call another macro

The preceding macro defines Username, Userpath, and Userfile as global variables. After running this macro once, the variables are defined globally and can be referenced from any other macro as long as KEA! remains open.

//  --- MyMacro( )

  KermitFileName = Userpath + Userfile

  Return // to MainMacro( )

The preceding macro uses the global variables Userpath and Userfile defined in the previous example.


Graphics (macro function)
Graphics

Graphics[[?]( [[DisplayList=]boolean], [[Bitmap=]boolean], [[GraphicsCursor=]boolean], [[MacrographReport=]boolean], [[SixelScrolling=]boolean], [[StyledLines=]boolean], [[IgnoreRequest=]boolean], [[BackgroundPrinting=]boolean], [[ColorPrinting=]boolean], [[SixelGraphicsLevel=]string], [[SixelPrintOption=]string], [[ColorSpecification=]string], [[CREffect=]string], [[LFEffect=]string], [[BSEffect=]string], [[DELEffect=]string], [[GINTerminator=]string], [[VT640Compatible=]boolean], [[Characters=]string], [[FontType=]string], [[CharacterSet=]string], [[LineStyleMap=]string], [[MarginControl=]string], [[AutoPrint=]string], [[Display=]string] )

Specifies the settings that affect graphics presentation. These options are equivalent to the Graphics dialog box (Options Terminal menu).

DisplayList   	Store the image in a Display List.

Bitmap   	Store the image in a bitmap.

GraphicsCursor   	Display graphics cursor.

MacrographReport   Send macrograph contents.

SixelScrolling   	Let sixel scroll the screen.

StyledLines   	Use solid background to ensure proper display of styled lines.

IgnoreRequest   	Ignore host request to print graphics.

Background Printing   Send background color.

Color Printing   	Send color sixels.

Sixel Graphics Level   Set aspect ratio. Values are:

LA210  Level1  Level2

Sixel Print Option   Set size of sixel image. Values are:

Compressed  Rotated  Expanded

Color Specification   Set color encoding method. Values are:

HLS  RGB

CREffect   	Set action to take after receiving CR. Values are:

CR   CR LF

LFEffect   	Set action to take after receiving LF. Values are:

LF   LF CR

BSEffect   	Set action to take after receiving BS. Values are:

BS   Delete

DELEffect   	Set action to take after receiving DEL. Values are:

Low   Ignored

GINTerminator   	Set GIN position report terminator. Values are:

None   CR   CR EOT

VT640Compatible   Interpret VT640 sequences.

Characters   	Set character size. Values are:

Aligned   Enlarged

FontType   	Set type of font to use. Values are:

Bitmap    Vector

CharacterSet   	Set character set to use. Values are:

ASCII   APL   Prog

LineStyleMap   	Map 4014 line styles to Windows colors. Values are:

Style   Color   Both

MarginControl   	Specify setting of Page Full Condition.

None   1   2

AutoPrint   	Specify whether to produce hardcopy when Page Full Condition reached. Values are:

Disabled   Enabled

Display   	Set size of emulation window. Values are:

80x24   64x24   80x30

Examples

Graphics(DisplayList=True, Bitmap=False)

The preceding example tells KEA! to use only the Display List to store the image.

B = Graphics.AutoPrint

The preceding example records whether the Auto Print option is enabled.


GroupBox..GroupEnd (macro function)
GroupBox..GroupEnd

KEA! provides three functions that let you position buttons and boxes within the dialog box. They are:

GroupBox( [[Text=]String], [[Row=]Int], [[Level=]Int] )
. . .
Controls
. . .
GroupBreak( )
. . .
Controls
. . .
GroupEnd( )

Typically, the buttons and boxes inside a dialog box are placed in a vertical column with each element immediately below the previous one. You can modify this layout by using the group functions. A group contains all the elements between a GroupBox and GroupEnd statement. By default, the elements within a group are in a vertical column.

Text   	If the GroupBox statement specifies a value for Text, KEA! draws a box around the group with the label Text in the upper left corner. If you do not specify the text argument, the box is not drawn, nor the title displayed.

Row   	If you set Row to True (non-zero), KEA! places the elements within the group in a row with each element placed immediately to the right of the preceding element. If you omit Row, or set it to False (zero), the default column placement of the elements is used.

Level   	If you set Level to Box_Indent or Box_Outdent, an outline is drawn around the group, shaded so that it appears indented or raised from the surrounding dialog box. If you use this feature, omit the preceding Text argument. If you omit Level, or set it to zero, the group appears at the same level as the surrounding dialog box.

You can use the optional GroupBreak function to start a new row or column within the current group. A new row is placed below the previous one, and aligned with the left edge of the previous row. A new column is placed to the right of the previous one, and aligned with the top of the previous column. The group is placed as a single control in the enclosing group or dialog box.

You also can use the GroupBreak function within the dialog box to start a new column. You do not need to use it inside a GroupBox()..GroupEnd() structure.

Example

Begin Dialog( "Sample GroupBox" )

  GroupBox( "Buttons", 1 )

    Button( "Button1", 20,,10 )

    Button( "Button2", 20,,10 )

  GroupBreak( )

    Button( "Button3", 20,,10 )

  GroupEnd( )

End

The preceding example displays Button1 and Button2 side-by-side. Button3 starts below Button1 because of the GroupBreak() function.


HelpKeyword (macro function)
HelpKeyword

HelpKeyword( [Key=]string[, [File=]string] )

The HelpKeyword function accesses a help file via a keyword.

Key   	Any of the search keywords provided in the help file.

File   	.HLP file. Defaults to the current help file.

Example

HelpKeyword( Key="Shuttle command" )


History (macro function)
History

History[?]( [[EnableHistory=]boolean], [[MaximumSize=]string], [[IncludeScrollingRegionData=]boolean], [[RetainHistory=]boolean], [[FileName=]string] )

The History function sets the values to use for the History buffer.

The arguments are equivalent to the options in the History dialog box (Options menu).

EnableHistory   	Store information no longer displayed on the screen in the History buffer.

MaximumSize   	Maximum size of history buffer.

Unlimited   16K   32K   64K   128K   256K   512K   1024K

IncludeScrollingRegionData

True	Information for history does not need to scroll off the top line.

False	Information for history must scroll off the top line.

RetainHistory   	Store history information in specified file.

FileName   	Name of file in which to store history information.

Examples

History( EnableHistory = True, MaximumSize = "64K",

    RetainHistory = True, FileName = "HISTORY.TXT" )

Tells KEA! to save history information in a file named HISTORY.TXT.

B = History.EnableHistory

Records whether history information is being stored.

History.EnableHistory = True

Activates History and stores history information in the History buffer.


HoldScreen (macro variable)
HoldScreen

HoldScreen = boolean

The HoldScreen variable sets the Hold Screen state. Values are:

0	Resumes output to the screen.

1	Stops output to the screen.

Changing this variable is equivalent to selecting the Hold Screen button on the Toolbar.

Examples

B = HoldScreen

Returns the current state of Hold Screen and assigns the value to B.

HoldScreen = False

Resumes output to the screen.


HorizontalScrollBar (macro variable)
HorizontalScrollBar

HorizontalScrollBar = boolean

The HorizontalScrollBar variable specifies whether to display or hide the horizontal scroll bar. Values are:

0	Hide the scroll bar.

1	Display the scroll bar.

Changing this variable is equivalent to selecting the Horizontal Scroll Bar option in the View dialog box (Options menu).


HostName (macro function)
HostName

HostName( )

The HostName function returns a string containing the name of the connected (or last connected) host. This function returns null if the current port does not have a host name. For example, a serial port never has a host name.

Examples

MyHost = HostName( )

In the preceding macro the variable MyHost contains the name of the connected host.


If..Elseif..Else..End (macro statement)
If...Elseif...Else...End

If Condition1
  Statement(s)1
[ElseIf Condition2
  Statement(s)2]
.
.
[Else
  Statement(s)N]
End

The If..ElseIf..Else..End control statement conditionally executes one group of statements from two or more groups.

Example

a = Input( "Enter a number" )

If a < 2

  Echo( "a < 2" )

ElseIf a < 4

  Echo( "a > = 2, a < 4" )

Else

  Echo( "a > = 4 )

End


Input (macro function)
Input

Input( [Text=]string, [Default=]string, [Options=]integer [,[List=]array] )

The Input function displays a dialog box. The dialog box contains prompt text and a user entry box (which can be a field, combination box, drop-down list box, or normal list box). It waits for the user to enter or select a response, then choose OK or Cancel.

The Input function is described separately for each type of dialog box:

Input - Simple Entry Field

Input - Combination Box

Input - List or Drop-down List

If you don't need the user to input text, but only to choose a button, you can use the MsgBox function instead.


Input (macro function): field
Input:   Simple Entry Field style

Input( [Text=]string, [Default=]string, [Options=]integer )

The preceding Input function displays an input dialog box in which the user can type information.

Text   	String to display as a prompt for the user.

Default   	Value that appears in the field.

Options   	How to present the typed data. Values are:

Input_Hide	Do not display what the user types.

This function returns the string that the user typed (or accepted). It returns a null string if the user chooses Cancel, or does not type anything.

Examples

CR = "^M"

Question = Input( "Connect to default servers?", "Yes" )

If Question = "Yes"

  DefaultHost = "SERVER1"

  Host = Input( "Enter Service Name", DefaultHost )

  Password = Input( "Enter Password",, Input_Hide )

End

The preceding macro first displays an Input box with the default string "Yes" displayed in the text entry box. If you click the OK button, a second Input box appears with the value of DefaultHost displayed in the text entry box. Clicking OK again causes a third Input box to appear in which the text you type is masked with '*' characters.


Input (macro function): combination
Input:   Combination Box style

Input( [Text=]string, [Default=]string, [Options=]integer, [List=]array )

The preceding Input function displays a combination dialog box. The user can enter a string, or select from a list.

Text   	String to display as a prompt for the user.

Default   	Value that appears in the field. Supply a subscript or a value, depending on the Input_Values option.

Options   	How to present the typed data. Values are:

Input_Hide	Do not display what the user types.

Input_Values	Display the value of the array item, not the subscript, in the list.

List   	Array defining the list to display. Users can type their own entries, or select from this list.

This function returns a string containing whatever the user enters in the box, or selects from the list. It returns a null string if the user enters nothing, or chooses Cancel.

Examples

Color["apple"] = "Red"

Color["banana"] = "Yellow"

Color["lime"] = "Green"

X = Input( "Select a subscript", "lime", 0, Color )

The preceding macro displays a list of the subscripts with "lime" highlighted.

Color["apple"] = "Red"

Color["banana"] = "Yellow"

Color["lime"] = "Green"

// default is a value

Y = Input( "Select a value", "Green", Input_Values, Color )

The preceding macro displays a list of the array values with "Green" highlighted.


Input (macro function): list
Input:   List or Drop-down List styles

Input( [Text=]string, [Default=]string, [Options=]integer, [List=]array )

The preceding Input function displays a list in a dialog box.

Text   	String to display as a prompt for the user.

Default   	Indicates which index is highlighted in the list when the dialog box first appears.

Options   	How to present the typed data. You must include either Input_List or Input_Dropdown. Values are:

Input_List	Produce a list box.

Input_Dropdown	Produce a drop-down list box.

Input_Values	Display the array values, not the subscripts.

List   	Array to display. The user can select from this list.

This function returns the subscript regardless of the Input_Values option. If you require the value of an array item, you can find it from the subscript as follows:

  value = array[subscript]

This function returns a null string if the user enters nothing, or chooses Cancel.

Examples

Color["apple"] = "Red"

Color["banana"] = "Yellow"

Color["lime"] = "Green"

Input( "Select subscript:", "lime", Input_List, Color )

The preceding macro displays a list of the subscripts with "lime" highlighted.

Color["apple"] = "Red"

Color["banana"] = "Yellow"

Color["lime"] = "Green"

// list of values

Input( "Select value:", "lime", Input_List + Input_Values, Color )

The preceding macro displays a list of the array values with "Green" highlighted.

Color["apple"] = "Red"

Color["banana"] = "Yellow"

Color["lime"] = "Green"

// drop-down list of subscripts

Input( "Select a subscript:", "lime", Input_Dropdown, Color )

The preceding macro displays a drop-down list of the subscripts with "lime" as the default selection.

Color["apple"] = "Red"

Color["banana"] = "Yellow"

Color["lime"] = "Green"

// drop-down list of values

Input( "Select a value", "lime", Input_Dropdown + Input_Values, Color )

The preceding macro displays a drop-down list of the array values with "Green" as the default selection.


InStr (macro function)
InStr

InStr( [String=]string, [Pat=]string, [[Options=]integer], [[Start=]integer] )

The InStr function searches a string for another string or pattern. It returns the position where it found the beginning of the string or pattern. If it does not find a match, it returns zero.

String   	String to be searched.

Pat   	A string or pattern to search for.

Options   	Whether Pat contains special pattern-matching characters, and whether to ignore upper case and lower case when matching. You can combine these values. The default is a simple string, case-exact. Values are:

Pat_RegExp	Pat contains special pattern-matching characters.

Pat_NoCase	Pat is case-insensitive.

Start   	Position at which to start searching.

Examples

My_String = "abcdefgfhijklmnop"

Alpha = InStr( My_String, "bc" )

In the preceding macro Alpha contains the value 2.


Int (macro function)
Int

Int( [Value=]string )

The Int function returns the integer equivalent of a string. It stops converting the string at the first non-numeric character it finds. If the string contains no leading numbers, the function returns zero.

Examples

Beta = Int( "123a" )

In the preceding macro Beta contains the value 123.


IsConnected (macro function)
IsConnected

IsConnected( )

The IsConnected function returns True if a connection to the host exists. Because this function tests for a state rather than an event, you use it in an If..ElseIf..Else..End statement, not a Begin..When..End.

Examples

If IsConnected( )

  Echo( "We are connected to the host right now" )

Else

  Echo( "We are not connected" )

End


Keyboard (macro function)
Keyboard

Keyboard[?]( [[Layout=]string], [[EditpadArrangement=]string], [[KeypadMode=]string], [[CursorKeyMode=]string], [[BackspaceKey=]string], [[F1Key=]string], [[F2Key=]string], [[F3Key=]string], [[F4Key=]string], [[F5Key=]string], [[Margin=]boolean], [[Warning=]boolean] )

The Keyboard function allows you to configure the various keyboard settings.

The arguments perform the same actions as the Keyboard dialog box (Options Terminal menu) options.

Layout   	Specify the type of keyboard you use. Values are:

PowerStation   Enhanced   LK250   LK450   LK411/412

EditpadArrangement   Specify whether to let the keyboard driver set the keypad layout. Values are:

Set By Driver   VT-Like

KeypadMode   	Specify whether the keypad keys send numbers or control sequences when pressed. Values are:

Numeric   Application

CursorKeyMode   Specify whether the cursor (ARROW) keys send ANSI cursor control sequences or control functions when pressed. Values are:

Normal   Application

BackspaceKey   Specify whether the BACKSPACE key sends the DEL or BS character when pressed. Values are:

Delete   Backspace

F1Key   	Specify whether the F1 key stops text scrolling, sends the VT F1 function key sequence, or does nothing. Values are:

Hold   FKey   Ignore

F2Key   	Specify whether the F2 key performs VT print functions, sends the VT F2 function key sequence, or does nothing. Values are:

Print   FKey   Ignore

F3Key   	Specify whether the F3 key acts as an ALT key (similar to VT setup function), sends the VT F3 function key sequence, or does nothing. Values are:

Setup   FKey   Ignore

F4Key   	Specify whether the F4 key sends the Escape code or the VT F4 function key sequence, or does nothing. Values are:

Esc   FKey   Ignore

F5Key   	Specify whether the F5 key sends a break signal or the VT F5 function key sequence, or does nothing. Values are:

Break   FKey   Ignore

Margin   	Specify whether the bell sounds when the text cursor reaches the right margin.

Warning   	Specify whether the bell sounds when an operating error occurs or the terminal receives the ASCII BEL character.

For macro language equivalents to other options in the Keyboard dialog box, see the Keyboard.Mapping and Keyboard.UDKs functions.

Example

Keyboard( EditPadArrangement = "VT", KeyPadMode = "Numeric",

  CursorKeyMode = "Normal", BackspaceKey = "Delete",

  F1Key = "Hold", F2Key = "Print", F3Key = "Setup", F4Key = "Esc",

  F5Key = "Break", Margin = False, Warning = True )

Sets the keyboard to a VT-like edit keypad in numeric mode, and defines the cursor (ARROW), BACKSPACE, F1, F2, F3, F4, and F5 keys. It also sets the bell to sound only as a warning of an error, or when the terminal receives an ASCII BEL.


Keyboard.Mapping (macro function)
Keyboard.Mapping

Keyboard.Mapping[?]( [[Reset=]boolean], [[PCKey=]string], [[MapTo=]string], [[Value=]string] )

The Keyboard.Mapping function specifies the settings for selected keyboard keys. You can include multiple sets of the PCKey, MapTo, and Value arguments.

These arguments are equivalent to the options in the Mapping dialog box (Keyboard dialog box, Options Terminal menu).

Reset   	Erase all keyboard mappings.

PCKey   	Name of key to map.

MapTo   	Type of action to perform when you press the key. Values are:

Nothing   Sequence   Macro

Value   	The action to perform.

For the macro language equivalent to the Delete All button in the Mapping dialog box, see the Keyboard.Mapping.DeleteAll function.

Examples

Keyboard.Mapping( Reset = True,

  PCKey = "F1 [70]", MapTo = "VTFunction", Value = "PF1",

  PCKey = "F2 [71]", MapTo = "VTFunction", Value = "PF2",

  PCKey = "F3 [72]", MapTo = "VTFunction", Value = "PF3",

  PCKey = "F4 [73]", MapTo = "VTFunction", Value = "PF4",

  PCKey = "Num - [6D]", MapTo = "VTFunction", Value = "Keypad -" )

Defines the keyboard mapping for the DIGITAL 320p notebook computer: F1 = PF1, F2 = PF2, F3 = PF3, F4 = PF4, NumPad(-)  = KeyPad(-).


Keyboard.Mapping.DeleteAll (macro function)
Keyboard.Mapping.DeleteAll

Keyboard.Mapping.DeleteAll( )

The Keyboard.Mapping.DeleteAll function resets all keyboard assignments to their default values. This function is equivalent to the DeleteAll button in the Mapping dialog box (Keyboard dialog box, Options Terminal menu).


Keyboard.UDKs (macro function)
Keyboard.UDKs

Keyboard.UDKs[?]( [[ShiftF6=]string], [[ShiftF7=]string], [[ShiftF8=]string], [[ShiftF9=]string], [[ShiftF10=]string], [[ShiftF11=]string], [[ShiftF12=]string], [[ShiftF13=]string], [[ShiftF14=]string], [[ShiftF15=]string], [[ShiftF16=]string], [[ShiftF17=]string], [[ShiftF18=]string], [[ShiftF19=]string], [[ShiftF20=]string] )

The Keyboard.UDKs function specifies assignments for the user-defined keys. Normally, the host controls this feature.

The arguments are equivalent to the options in the UDKs dialog box (Keyboard dialog box, Options Terminal menu) options.

For the macro language equivalent to the Clear button in the UDKs dialog box, see the Keyboard.UDKs.Clear function.

Examples

Keyboard.UDKs( ShiftF6 = "", ShiftF7 = "", ShiftF8 = "", ShiftF9 = "",

  ShiftF10 = "", ShiftF11 = "", ShiftF12 = "", ShiftF13 = "",

  ShiftF14 = "", ShiftF15 = "", ShiftF16 = "", ShiftF17 = "",

  ShiftF18 = "", ShiftF19 = "", ShiftF20 = "" )

Resets all UDKs to blank.


Keyboard.UDKs.Clear (macro function)
Keyboard.UDKs.Clear

Keyboard.UDKs.Clear( )

The Keyboard.UDKs.Clear function deletes all UDK assignments. It is equivalent to the Clear button in the UDKs dialog box (Keyboard dialog box, Options Terminal menu).


KeyStroke (macro function)
KeyStroke

KeyStroke( )

The KeyStroke function waits for the user to press a key. It returns the key's value as a one-character string. If the key is one of the function keys, editing keypad, or numeric keypad, KeyStroke returns the name of the associated VT function. The function is typically used as a When event in a Begin..When..End construct. You can use this string with the SendKey function.

Tip  To see the exact VT function name of a particular key, open the Keyboard Mapping dialog box (from the Options menu, Keyboard command). Press the desired key. Any key that is not in the main keypad displays its VT function name in the Value box, enclosed in "angle brackets".

Examples

  a = KeyStroke( )

  If a = "g"

    MsgBox( "Key pressed was g" )

  Else

    SendKey( a )

  End

The preceding macro waits until the user presses a key. If the key was G, it is reported. Other keys are passed to the host.

In the following example, KeyStroke generates an event.

Begin

  Suspend()

  When KeyStroke( )

    a = Result

    MsgBox( "Key pressed was " + a )

    Continue

  When Wait( 300 ) // if we are still in the loop after 30 secs

    MsgBox( "Timeout occurred.." )

    Break

End


Languages (macro variable)
Languages

Languages = string

English   	for English

Français   	for French

Deutsch   	for German

Español   	for Spanish

Italiano   	for Italian

Português   	for Portuguese

The Languages variable controls the language used to display menus, commands, dialog boxes, and system messages.

Changing this variable is equivalent to changing the Language option in the View dialog box (Options menu).

Returned values contain an ampersand (&) in the string.

Examples

Set English as the language for KEA! to use.

Languages = "English"

Records the current language KEA! uses.

A = Languages


Len (macro function)
Len

Len( [String=]string )

The Len function returns the length of a string.

Example

My_String = "abcdefg"

Beta = Len( My_String )

In the preceding macro Beta contains the value 7.


Links (macro function)
Links

Links[?]( [[EnableRemoteUpdates=]boolean], [[NoChangeFor=]string], [[MaxDelay=string] )

The Links function is used to enable or disable the updating of established hotlinks, as well as to specify options that control when updates are sent. It is equivalent to the Links command under the Edit menu.

EnableRemoteUpdates   When KEA! is started by another application this option is False so the user can ensure that both the screen and the host application are ready to interact before restarting the links.

True	Turn on the updating of hotlinks

False	Turn off the updating of hotlinks

NoChangeFor   	Specify the time to wait for data to be idle. Range is 100 to 2000 msec. Default is 1000 msec.

MaxDelay   	Specify the maximum time to wait for idle, then send anyway. Range is 0 to 600 seconds. Default is 60 seconds. 0 means don't send until idle.

Examples

Links?( )

Displays the Links dialog box.

Links.EnableRemoteUpdates = True

Turns on the updating of hotlinks. This is useful when automating the establishment of hotlinks because KEA! starts with this feature disabled if started by another application.


ListBox (macro function)
ListBox

ListBox( [[Text=]String], [[Value=]Var], [List=]Var, [[Width=]Int], [[Height=]Int], [[Offset=]Int] )

The ListBox function displays a list of items from an array. It must appear within the Controls section of a Begin Dialog..End construct. A scroll bar is added when the number of items exceeds the number of lines in the list box. The user can select one of the items.

Text   	The list box is labeled with the Text string.

Value    	If Value evaluates to a subscript in the List array, the corresponding entry is highlighted when the dialog box is displayed. On return from the dialog box, KEA! fills in Value with the subscript of the currently selected entry in the list box.

List   	The array to display. The user can select from this list.

Width   	A literal integer or integer variable that defines the horizontal space (in average character width) taken up by the complete control. It includes any label, user entry space, and separating white space.

Height   	A literal integer or integer variable that defines the vertical space (in character height) taken up by the control. It includes the borders and separating white space. The box defaults to an appropriate height if you do not supply this parameter.

Offset   	A literal integer or integer variable that defines how far from the right edge of the space the left part of the control starts. You should specify an offset that is less than the width.

Example

Begin Dialog( "Sample List Box" )

  modelist[1] = "VT400-7bit"

  modelist[2] = "VT400-8bit"

  mode = 1	// set initial value

  ListBox( "&Mode", mode, modelist, 40,,15 )

  OKButton( 40,,15 )

End

The preceding macro displays a list box containing two options.


Local (macro variable)
Local

Local = boolean

The Local variable specifies whether KEA! sends keystrokes to the communications port or directly to the screen. Changing this variable is equivalent to selecting the Local command under the Connection menu. Values are:

False	Send keystrokes to the port.

True	Do not send keystrokes to the port. Send them directly to the screen.


LocalEdit (macro function)
LocalEdit

LocalEdit[?]( [[EditMode=]string], [[FunctionKeys=]string], [[EOLChars=]character], [[EOBChars=]character], [[TransferTermination=]boolean], [[SpaceCompression=]boolean], [[LineTransmit=]boolean], [[NewLineScrolling=]boolean], [[ErasureMode=]string], [[EditKey=]string], [[Transmit=]string], [[VT131Transfer=]string], [[GuardedArea=]string], [[SelectedArea=]string], [[MultipleArea=]string] )

The LocalEdit function specifies the various settings for the local editing feature.

The arguments are equivalent to the options in the Local Edit dialog box (Options Terminal menu).

EditMode   	Whether to use local edit mode. Values are:

Interactive   Enabled   Unavailable

FunctionKeys   	How the F6 through F20 function keys work in local edit mode. Values are:

Disabled   Immediate   Prefix   Suffix

EOLChars   	Characters to use to signal the end of a line in a block of data.

EOBChars   	Characters to use to signal the end of a block of data.

TransferTermination   Whether to send scrolling region or block, based on VT131Transfer value.

SpaceCompression   Whether to send a record separator in place of unused character fields and spaces in a data block, or space character in place of unused characters.

LineTransmit   	Whether to send a line of eligible characters, or a full or partial page.

NewLineScrolling   Whether to scroll at the end of the screen in line transmit mode.

ErasureMode   	Which type of character to erase. Values are:

Unprotected   All

EditKey   	How to switch modes. Values are:

Deferred   Immediate

Transmit   	How to send data to the host. Values are:

Deferred   Immediate

VT131Transfer   	What terminal type to use to send data. Values are:

ANSI   VT131

GuardedArea   	Which type of character to send. Values are:

Unprotected   All

SelectedArea   	Which characters to send. Values are:

Selected   All

MultipleArea   	Which selected areas to send. Values are:

Single   Multiple


LogBox (macro function)
LogBox

LogBox( [[Text=]string], [[File=]handle], [[Width=]Int], [[Height=]Int], [[Offset=]Int] )

The LogBox function is used in a Begin Dialog..End to display the contents of a log.

Text   	The log box is labeled with the text string.

File   	File handle of the log "file" in memory.

Width   	A literal integer or integer variable that defines the horizontal space (in character width) taken up by the complete control. It includes any label, user entry space, and separating white space.

Height   	A literal integer or integer variable that defines the vertical space (in character height) taken up by the control. It includes the borders and separating white space. The box defaults to an appropriate height if you do not supply this parameter.

Offset   	A literal integer or integer variable that defines how far from the right edge of the space the left part of the control starts. You should specify an offset that is less than the width.

Example

Display the contents of the KEA! Transfer Log

Test = LogOpen( Name="Transfer Log", Size=2048 )

Begin

  Dialog( Text="Display Transfer Log" )

    LogBox( Text="Test Transfer Log", File=Test,

                   Width=50, Height=10, Offset=5 )

    OKButton( )

  When Control( "Button1" )

    Break

End


LogDelete (macro function)
LogDelete

LogDelete( [Name=]string )

The LogDelete function deletes the named log "file" from memory.

Name   	Specify a name of the log to delete.


LogOpen (macro function)
LogOpen

LogOpen( [[Name=]string], [[Options=]integer], [[Size=]integer] )

The LogOpen function opens or creates a log "file" in memory which is used to record information. This function returns a file handle.

Name   	Specify the name of a log. If the named log does not exist, it is created. KEA! keeps its transfer information in the log named "Transfer Log."

Options   	Specify the type of access permitted; currently, only Attr_Write.

Size   	Specify the minimum amount of memory allocated, in bytes. This size is rounded up to a power of two.

Examples

Create a log, read AUTOEXEC.BAT into it, and display the log in a window.

Test = LogOpen( Name="Test Log", Options=Attr_Write, Size=2048 )

FileToRead = FileOpen( Name="c:\autoexec.bat", Options=File_Read )

While Not FileEnd( File=FileToRead )

  FileWrite( File=Test, Data=FileRead( File=FileToRead) )

End

FileClose( File=FileToRead )

Begin

  Dialog( Text="Display Test Log File" )

    LogBox( Text="Test Log Box", File=Test,

              Width=50, Height=10, Offset=5 )

    OKButton( )

  When Control( "Button1" )

    Break

End

LogDelete( Name="Test Log" )

Display the contents of the KEA! Transfer Log

Test = LogOpen( Name="Transfer Log", Size=2048 )

Begin

  Dialog( Text="Display Transfer Log" )

    LogBox( Text="Test Transfer Log", File=Test,

              Width=50, Height=10, Offset=5 )

    OKButton( )

  When Control( "Button1" )

    Break

End


Lowercase (macro function)
Lowercase

Lowercase( [String=]string )

The Lowercase function returns a string that is the lower case equivalent of the specified string.

Example

HostString = Lowercase( "abcD" )

In the preceding macro HostString contains "abcd".


MacroOptions (macro function)
MacroOptions

MacroOptions[?]( [[LockRemoteMacros=]boolean], [[SearchPath=]string], [[Startup=]string] )

The MacroOptions function determines the settings that affect macros.

The arguments are equivalent to the options in the Macro Options dialog box (Macro menu).

LockRemoteMacros    Do not let the host run KEA! macros. Values are:

False	Execute macro statements sent by the host with the DCS 4.z <statements> ST control sequence.

True	Do not execute macro statements sent by the host.

SearchPath   	Additional places to look for macros.

Startup   	The macro  to run when KEA! starts.

Examples

MacroOptions?( )

Displays the Macro Options dialog box for you to fill in.

MacroOptions( LockRemoteMacros = False,

    Startup = "c:\macros\startup.ktm" )

Runs the macro STARTUP.KTM when you start KEA!, and allows the host to execute macro statements.


Match (macro function)
Match

Match( [Pat=]string, [[Options=]integer], [[Strip=]integer], [[Timeout=]integer], [[Idle=]integer] )

The Match function searches for a pattern match in data coming from the host. It optionally strips the matching data from the input stream.

Pat   	A string or pattern to search for.

Options   	Whether Pat contains special pattern-matching characters, and whether to ignore upper case and lower case when matching. You can combine these values. The default is a simple string, case-exact. Values are:

Pat_RegExp	Pat contains special pattern-matching characters.

Pat_NoCase	Pat is case-insensitive.

Strip   	Whether to remove the matching data from the input stream, or pass it on to be displayed. Values are:

0 (Default)	Do not strip data from input stream.

1	Strip data from input stream.

Timeout   	Timeout interval in 1/10 second units. The default is no timeout.

Idle   	An idle time in 1/10 second units. If this argument is included, a match is successful only if the characters received from the host match the given Pat and an idle time immediately follows (no characters received from the host) for the duration given in Idle. If no Pat is supplied, a successful match is reported (returns "1") after any idle period of the given duration. Idle must be less than Timeout, if a timeout is supplied.

This function returns the matching data in Result. Null indicates failure.

You can specify a timeout for the match in two different ways. If there are multiple matches, and you want to process the timeout for each match separately, use the timeout parameter to the Match function. A timeout executes the event statements for that particular match with Result set to null. If there are multiple matches, and you want common timeout processing, use the Timeout function.

Examples

Match( "CONNECT" )

The preceding macro matches the string "CONNECT".

Match( "d[iu]g", Pat_RegExp )

The preceding macro matches on the words "dig" or "dug".

CR = "^M"

Begin

  ModemConnectString = "CONNECT"

  When Match( Pat = ModemConnectString, Strip = 1, Timeout = 200 )

    Wait( 5 )

    Send( CR )

End

The preceding macro matces the string "CONNECT", strips it so it does not display on the screen, waits half a second, then sends a CR. Match will timeout after 20 seconds.


Maximize (macro function)
Maximize

Maximize( )

The Maximize function enlarges the application window to its maximum size. The maximum size depends on the current font size. Maximize is equivalent to the Maximize command under the Control menu. The function has no return value.


Menu (macro variable)
Menu

Menu = boolean

Hides the menu bar if Menu is set to False, and displays the menu bar otherwise.

Changing this variable is equivalent to choosing the Show Menu Bar command on the Control menu.


Menus (macro function)
Menus

Menus[?]( [Reset=]boolean, [Position=]string, [Add=]string, [Caption=]string, [Value=]string, [Check=]boolean, [Dim=]boolean, [Hide=]boolean )

The Menus function changes the contents of KEA! menus.

The arguments perform the same actions as the Menus dialog box (Options menu) options.

Reset   	Whether to remove any previous menu changes. Values are:

True	Erase previous menu changes.

False	Do not erase previous menu changes.

Position   	Where to set the current menu or command pointer. Values are:

Menu Name	Name of menu or command at which to position pointer.

Menu.*	Set pointer to end of current menu.

Menu.Name+n	Set pointer n down from specified name.

Add   	Type of item to add. Values are:

Menu

Macro

Sequence

Separator

Caption   	Name of the menu or command.

Value   	Name of the macro to execute, or sequence to send, when you choose the command. Menu and separator do not have values.

Check   	Whether to place a checkmark beside the command. Menu bar commands and KEA! defined commands cannot have checkmarks beside them. Values are:

True	Place checkmark beside command.

False	Remove checkmark from beside command.

Dim   	Dim the menu item. You can dim only commands that you define. Values are:

True	Dim command.

False	Undim command (make it available for use).

Hide   	Hide the command, but keep it in the internal menu structure. If you hide a menu, the menu contents are also hidden. Values are:

True	Hide command.

False	Show command.

For the macro language equivalent to the Delete button in the Menus dialog box, see the Menus.Delete function.

Examples

Menus( Position = "Connection.Escape", Add = "Macro",

    Caption = "&Login", Value = "login( )" )

Adds a new command to the Connection menu to appear after Escape. It is given the name Login and assigned to run the macro LOGIN.KTM.

Menus( Position = "Connection.Reset + 1", Hide = True,

    Position = "Connection.Enable History", Hide = True,

    Position = "Connection.Clear History", Hide = True )

Hides the History commands and the separator after the Reset command on the Connection menu.


Menus.Delete (macro function)
Menus.Delete

Menus.Delete( )

The Menus.Delete function deletes a menu or command the user defined, or hides a KEA!-defined menu or command.

Example

Menus.Position = "Connection.Login"

Menus.Delete( )

Deletes the Login command from the Connection menu.


Message (macro function)
Message

Message( [Text=]string )

The Message function displays the specified string on the status bar. The message remains until a new message is written on the status bar, or until the macro finishes. If you want to get the user's attention, use the MsgBox function instead.

Example

Message( "This displays on the status bar." )

Wait( 20 )

The preceding macro displays the text on the status bar for 2 seconds.


MeterBox (macro function)
MeterBox

MeterBox( [[Text=]String], [[Width=]Int], [[Height=] Int], [[Offset=]Int] )

The MeterBox function displays a horizontal gas gauge or thermometer that you can use to show progress or graphically display a value. The function must appear within the Controls section of a Begin Dialog..End construct. You use the ControlSet (...,Control_Value,...) function to update the position of the indicator. The values should vary between 0 and 100.

Text   	The Meter box is labeled with the Text string; this string appears to the left of the box.

Width   	A literal integer or integer variable that defines the horizontal space (in average character width) taken up by the complete control. It includes any label, user entry space, and separating white space.

Height   	A literal integer or integer variable that defines the vertical space (in character height) taken up by the control. It includes the borders and separating white space. The box defaults to an appropriate height if you do not supply this parameter.

Offset   	A literal integer or integer variable that defines how far from the right edge of the space the left part of the control starts. You should specify an offset that is less than the width.

Example

Begin Dialog( "Sample Meter Box" )

OKButton( )

Button( "Start meter" )

MeterBox( "Time left", 40,,30 )

When Control( "Start meter" )

  mtime = 0

  While mtime < 100

    mtime = mtime + 5 //increments of 5 will reach 100 in 20 steps

    // note that the meter is identified by its label here

    ControlSet( "Time left", Control_Value, mtime )

    Wait( 1 )      // 1/10 second between updates

  End

  // zero the meter box after the display

  // note that the meter is identified by its generic type

  // and number here

  ControlSet( "meter1", Control_Value, 0 )

  Continue

End

The preceding macro displays a meter box, which is incremented 20 times at 1/10 of a second intervals.


Minimize (macro function)
Minimize

Minimize( )

The Minimize function reduces the application window to an icon. It is equivalent to the Minimize command under the Control menu. The function has no return value.


Mouse (macro function)
Mouse

Mouse[?]( [[Reset=]boolean], [[Action=]string], [[MapTo=]string], [[Value=]string] )

The Mouse function changes the mapping of specified mouse actions. You can include multiple sets of the Action, MapTo, and Value arguments. These mappings are equivalent to the Mouse dialog box options (Options menu).

Reset   	Erase current map settings.

Action   	Assign one of the following positions:

Left Button Up	Middle Double-Click

Left Button Down	Right Button Up

Left Double-Click	Right Button Down

Middle Button Up	Right Double-Click

Middle Button Down

MapTo   	Map one of the following actions to the indicated mouse button:

Default Action

Sequence

Nothing

Macro

Value   	The value you want to map to this action (256 characters maximum). Depending on the Map To option, this is:

- a sequence to be sent, or

- the macro statements to execute. You can put several macro statements on the same line.The pre-defined local variables Page, Row, Col, and Adjustment are provided, which you can use in the macro statements. The variable Col tells the position between which characters the user clicked. In most cases, this is what you need. But if you want to know exactly on which character the user clicked, add the variable Adjustment to Col. Note that the selection cursor, always located between characters, might not be visible on the screen. The variables Page and Row contain the vertical position where the user clicked. If you want to use these variables in a macro file which you name in the Value box, include them as arguments.

For the macro language equivalent to the Delete All button in the Mouse dialog box, see the Mouse.DeleteAll function.

Example

Mouse( Action = "LeftButtonDown", MapTo = "Macro",

    Value = "Send( Str(ROW) )" )

The ASCII row number where the left button was clicked is sent to the host. Other left button actions are mapped to Nothing.

Mouse( Action = "LeftButtonUp", MapTo = "Macro",

    Value = "MyMacro( PAGE, ROW, COL, ADJUSTMENT )" )

The function MyMacro in invoked when the left button is clicked. It can access Page as Arg[1], Row as Arg[2], and so forth.

Assume the following line appears on the screen, with "A" in the leftmost column of the screen.

ABCDEF...

If the user clicks the right part of the letter "B" or the left part of the letter "C", the cursor moves between B and C, and Col has the value 3. Alternatively, the sum of Col plus Adjustment is 2 if the user clicks anywhere on B (the second character), and 3 if the user clicks anywhere on C.


Mouse.DeleteAll (macro function)
Mouse.DeleteAll

Mouse.DeleteAll( )

The Mouse.DeleteAll function deletes all mouse button assignments. It is equivalent to the Delete All button in the Mouse dialog box (Options menu).


MRUList (macro variable)
MRUList

MRUList

The MruList variable contains the name of the last used configuration file. It is equivalent to the first item on the list at the bottom of the File menu .


MsgBox (macro function)
MsgBox

MsgBox( [Text=]string, [[Buttons=]integer], [[Default=]Integer] )

The MsgBox function displays the specified text and buttons in a dialog box.

Text   	String to display.

Buttons   	The buttons to display. Values are:

Button_Yes + Button_No

Button_Yes + Button_No + Button_Cancel

Button_Ok (Default)

Button_Ok + Button_Cancel

Button_Retry + Button_Cancel

Button_Abort + Button_Retry + Button_Ignore

You also can display an icon with the message. Add one of the following names in the Buttons argument:

Icon_What	Question mark (?).

Icon_Info	Information sign (I).

Icon_Error	Exclamation mark (!).

Icon_Stop	Red octagon.

Default   	The default button. Values are:

Button_Ok

Button_Yes

Button_No

Button_Abort

Button_Retry

Button_Ignore

Button_Cancel

This function returns the value of the button the user chose. The return values are the same as the Default values.

You use the MsgBox function to ask a user to make a choice. To ask a user for a text string, use the Input function.

Examples

press = MsgBox( "Errors in transmission.",

    Button_Retry + Button_Cancel + Icon_Error, Button_Cancel )

If press = Button_Retry

  Send( "ATDT555-5555^M" )

End

The preceding macro displays a message box with Retry and Cancel buttons and an error icon. When you choose Retry, it sends the string.

...

When Timeout( 100 )

  MsgBox( "Login timeout, check port and try again.", Button_OK )

  Break

The preceding macro displays a message box with an OK button after the Timeout value has been reached.


NextSession (macro function)
NextSession

NextSession( )

The NextSession function switches to the next running KEA! session.

It is equivalent to the Next Session command under the Window menu. The function has no return value.


OkButton (macro function)
OkButton

OkButton( [[Width=]Int], [[Height=]Int], [[Offset=]Int] )

The OkButton function displays a button labeled OK. OK is the default button for the dialog box unless you define a different one. When the user chooses OK, KEA! exits the dialog box, and updates the values for the controls.

You can create buttons to be used in dialog boxes. Their definitions must appear within the Controls section of a Begin Dialog..End construct. Clicking a button causes a button's When event to be triggered.

Example

Var Password

Begin Dialog( )

GroupBox( , True )

EditBox( "Password", Password, Width = 28 )

DefaultButton( "Encode", Width = 12 )

GroupEnd( )

GroupBreak( )

OkButton( Width = 15 )

CancelButton( Width = 15, Offset = 10 )

Button( "Help", Width = 15, Offset = 10 )

Do

ControlSet( "edit1", Control_Password, Value = 1 )

Continue

End


OpenLayout (macro function)
OpenLayout

OpenLayout( string )

The OpenLayout function starts all application windows in the specified layout file, and connects to individual hosts. In the argument, you must include the .KTL filename extension.

The function is equivalent to the Open Layout dialog box (Window menu).


Paste (macro function)
Paste

Paste( )

The Paste function sends the currently selected area on the emulation screen to the host. You can also use this function to send the Clipboard contents to the host if no area is selected. The function might require some interaction from you or the host application. The function is equivalent to the Paste command under the Edit menu. It returns no value.

Examples

The following example prompts the user to use the mouse to select an area to send to the host. The macro then defines a button that pastes the selected area when clicked on. The second macro (PASTE2.KTM) performs the actual paste.

// PASTE1.KTM

Message( "Use your mouse to select area to paste" )

ButtonPad( Caption = "PASTE", MapTo = "MACRO", Value = "PASTE2()", .. )

// PASTE2.KTM

Paste( )

Message( "Check your application" )

Running the PASTE1 macro displays instructions, and sets up a SmartPad containing the PASTE2 button. Clicking the PASTE2 button runs the PASTE2 macro that pastes the selected text to the host, and displays a message.


PlayBack (macro function)
PlayBack

PlayBack[?]( [FileName=]string )

The PlayBack function specifies the file to display in the emulation window. You use this function primarily as a diagnostic utility.

Example

PlayBack( FileName = "ACTIVITY.LOG" )

Echo( "Above is a list of the activity log." )

Displays a file called ACTIVITY.LOG.


PlaySound (macro function)
PlaySound

PlaySound( [Name=]string[, [Options=]integer] )

The PlaySound function plays the specified sound now.

Name   	Filename of sound file, or label indicating an event from the [Sounds] section of WIN.INI (for example KEAStart)

Options   	How to play or repeat the sound. Include one or more of the following predefined constants:

Sound_Async	Play asynchronously. Default.

Sound_Sync	Play sound synchronously. That is, don't return until the sound is finished.

Sound_Always	Always make some sound. If the sound file is null, then beep.

Sound_Loop	Play continuously until PlaySound is called again with a null sound file.

Sound_NoStop	If there is an ongoing sound, wait until it is finished before starting this sound.

Examples

PlaySound( Name="chimes.wav", Options=Sound_Sync + Sound_NoStop )

PlaySound("KEAExit")

Setup inserts the following lines into your WIN.INI under the [Sounds] heading, but does not attach any sound files.

KEAStart=,KEA! Startup

KEAExit=,KEA! Exit

KEAConnect=,KEA! Connect

KEADisconnect=,KEA! Disconnect

KEATransferSend=,KEA! Transfer Send

KEATransferReceive=,KEA! Transfer Receive

KEAAttention=,KEA! Attention

To associate sounds with events, use Control Panel, then choose Sound. In the Sound dialog box, associate Events (as identified by the string at the end of each preceding line) with sound files.


PreviousSession (macro function)
PreviousSession

PreviousSession( )

The PreviousSession function switches to the previous application window from the list at the bottom of the Window menu.

The function has no return value.


Print (macro function)
Print

Print[?]( [[Extent=]string], [[Format=]string] )

The Print function prints all or some of page memory. It returns no value.

The arguments are equivalent to the options in the Print dialog box under the File menu.

Extent   	How much of page memory to print. Values are:

Selection     Window     Page All     Pages

Format   	Whether to print text and graphics, or just text (KEA! 340 only). Values are:

Text     Graphics

Examples

Print( Extent = "Page", Format = "Text" )

Prints a page of text from VT memory (KEA! 340 only).

Print( Extent = "Region", Format = "Graphics" )

Prints a graphics region (KEA! 340 only).


Printer (macro function)
Printer

Printer[?]( [[Mode=]string], [[ClosePrintJobIdleTimer=]string], [[Extent=]string], [[Terminator=]string], [[EmulateANSIPrinter=]boolean], [[PrintBackground=]boolean], [[PrintColors=]boolean], [[ReverseBlackAndWhiteColors=]boolean], [[UseBitmap=]boolean], [[Automatic=]boolean], [[Font=]string], [[FontStyle=]string], [[FontSize=]string] )

The Printer function determines the print settings to use.

In the Printer dialog box, you select font options (Font, FontStyle, and FontSize) by choosing the Fonts button to display the Fonts dialog box. The Printer function groups the font options with the other printer options.

The arguments are equivalent to the options in the Printer dialog box (Options Terminal menu).

Mode   	How the printing occurs. Values are:

Normal	No continuous printing.

Auto Print	Print one line at a time, and display data.

Controller	Host sends all information to the printer.

ClosePrintJobIdleTimer   Time to wait after receiving last piece of data before flushing buffered data, and printing the page. Values are:

2 secs   10 secs   30 secs   1 min   2 min   5 min   Manual

Extent   	How much of page memory to print. Values are:

Page   Region

Terminator   	Whether to send a form feed at end of print job. Values are:

None   Form Feed

EmulateANSIPrinter   Translate LA210 printer codes from the host to the printer type connected to the personal computer.

PrintBackground   Print the current screen background. (KEA! 340 only.)

PrintColors   	Print color on a color printer, and use dithering on a monochrome printer. (KEA! 340 only.)

ReverseBlackAndWhiteColors   Swap the darkest and brightest palette colors for printing. (KEA! 340 only.)

UseBitmap   	Use bitmap printing method. (KEA! 340 only.)

Automatic   	Use fixed-pitch font.

Font   	Which font to use. Not valid if you use Automatic.

FontStyle   	What style font to use. Values are:

Regular     Italic     Bold     Bold Italic

FontSize   	What size font to use. Not valid if you use Automatic.

Example

Printer( Automatic = True, Font = "", FontStyle = "", FontSize = "" )

Uses the fixed-pitch font that best fits 80 columns on the printed page. The font is selected from those supplied by the printer driver.


PrintSetup (macro function)
PrintSetup

PrintSetup( )

The PrintSetup function displays the Print Setup dialog box. This lets you change the printer definition.

Note  Do not use a question mark before the parentheses.

This function is equivalent to the Print Setup command on the File menu.


RadioBox (macro function)
RadioBox

RadioBox( [[Text=]String], [[Value=]Var], [List=]Var, [[Width=]Int], [[Height=]Int], [[Offset=]Int] )

The RadioBox function displays a box containing a group of radio buttons. The function must appear within the Controls section of a Begin Dialog..End construct. The box is labelled with the Text string, and the values from the List array are used to create the radio buttons. The radio buttons are arranged in rows from left to right within the box, with a new row starting whenever the next radio button would exceed the width of the box.

Unlike list boxes, KEA! does not reflect any change to the contents of the List array in the radio box on a Control_Init.

Text   	String used to label the radio box; appears above and to the left in the box outline.

Value    	If Value evaluates to a subscript in the List array, the corresponding radio button is initially pressed when the dialog box is displayed. On return from the dialog box, Value contains the subscript of the currently selected radio button.

List   	The array used to create the radio buttons.

Width   	A literal integer or integer variable that defines the horizontal space (in average character width) taken up by the complete control. It includes any label, user entry space, and separating white space.

Height   	A literal integer or integer variable that defines the vertical space (in character height) taken up by the control. It includes the borders and separating white space. The box defaults to an appropriate height if you do not supply this parameter.

Offset   	A literal integer or integer variable that defines how far from the right edge of the space the left part of the control starts. You should specify an offset that is less than the width.

Example

Begin Dialog( "Sample Radio Button Box" )

  OkButton( 30,,15 )

  Selected_Color = 1	// set the default color to red

  MyColor[1] = "Red"	// initialize the array

  MyColor[2] = "Green"

  MyColor[3] = "Blue"

  RadioBox( "&Color", Selected_Color, MyColor, 30,,15 )

End

The preceding macro displays a radio button box with three items. Notice that the control width (30 characters) is not enough to display the buttons side-by-side, so KEA! automatically wraps to another line. Try setting the control width to 40 and then 20 to see how your dialog box fits into the space defined.


Read (macro function)
Read

Read( [FileName=]string )

The Read function sends the contents of the specified file to the host, while displaying the text in the emulation window.


Receive (macro function)
Receive?

Receive?( [[HostFile=]string], [Local path or file name], [[FileType=]boolean], [[QuitServerAtEnd=]boolean], [[CrashRecovery=]boolean] )

When you use the Receive function in a macro (equivalent to the Receive command on the Transfer menu) you must use it with a question mark: Receive?( ). This displays the Receive dialog box which the user can complete before choosing OK. Any function arguments you include appear as default option values in the usual way. Note the second argument does not have a name; if you include a default for the local filename, it must be second in the argument list. Also, you cannot use Receive without the question mark.

The following arguments appear as defaults in the dialog box.

HostFile   	The filename(s) you want to get from the host (Kermit server only).

(second argument)   The location and name you want to use to store the received file.

File Type   	Mode in which to transfer the file. This option is not available for ASCII file transfers.

Automatic	Enables the automatic file type processing based on the file extension and file scan options in the File Transfer dialog box.

Binary	Send file in binary mode. KEA! sends all 8 data bits, and does not perform character translation. Typically, binary files are object code or executable programs.

Text	Send file in text mode. KEA! translates characters to suit a dissimilar remote system. You might lose data if the file contains any binary data.

QuitServerAtEnd   If True, send the Finish command to the host to indicate the end of the transfer (Kermit server only).

CrashRecovery   If True, restart a transfer from the point at which it failed. (Zmodem only).

If you want to transfer files without user interaction, use the TransferReceive function instead.


ReduceFont (macro function)
ReduceFont

ReduceFont( )

The ReduceFont function reduces the font size by one increment. The function has no return value.


Reset (macro function)
Reset

Reset( )

The Reset function returns the display to its power-up operating state. It is equivalent to the Reset command on the Connection menu. The function has no return value.


Restore (macro function)
Restore

Restore( )

The Restore function restores the application window to its former size after you have enlarged it (using the Maximize command) or reduced it to an icon (using the Minimize command). Restore is equivalent to the Restore command under the Control menu. It has no return value.


RestoreSessions (macro function)
RestoreSessions

RestoreSessions( )

The RestoreSessions function restores KEAlink MSU sessions that were accidentally interrupted. It is equivalent to the Restore Sessions command under the Connection menu. The function has no return value.


Return (macro statement)
Return

Return [expression]

The Return macro statement stops the current macro or user-defined function, and returns control to the caller. It returns the optional value to the caller either as the value of the expression, or in the predefined variable Result.

Examples

This macro uses a function that adds two integers, and obtains the result as the value of an expression.

Function Add( A, B )

  Return A + B  // returns sum to caller

End

A = 4

B = 2

X = Add( A, B )

Message( "The sum of A and B is " + X )

The following macro makes use of an alternate method of obtaining the return value. It obtains the value from the predefined variable Result.

Function Add( A, B )

  Return A + B  // returns sum to caller

End

A = 4

B = 2

Add( A, B )

X = Result

Message( "The sum of A and B is " + X )


Run (macro function)
Run

Run[?]( Macroname [, arguments] )

The Run function invokes the named macro file. You can include arguments if the file takes arguments.

Macroname   	The filename of the macro. It can be a complete path.

Arguments   	If the macro takes arguments, include them separated by commas.

This function is equivalent to the Run command (Macro menu), although the Run command does not pass arguments.

Example

The following line invokes the macro MYFUNC.KTM and passes two arguments:

Run( "Myfunc", 99, "abc" )

The following macro shows a variable used as the name of the macro to be run:

Function GetInput( )

  MacroToRun = Input( "Name of macro to run" )

  ArgToPass = Input( "Argument to pass" )

End

GetInput( )

While MacroToRun // determine if macro should be run.

  Run( MacroToRun, ArgToPass )

  GetInput( )

End


Save (macro function)
Save

Save( )

The Save function stores the configuration in the current configuration file. The function has no return value.

It is equivalent to the Save command under the File menu.


SaveAs (macro function)
SaveAs

SaveAs[?]( [FileName=]string, [[Configuration=]boolean], [[User-mappedKeys=]boolean], [[User-mappedButtons=]boolean], [[User-mappedMouseEvents=]boolean], [[User-mappedColors=]boolean], [[CreateIcon=]boolean], [[ProgramGroup=]string] )

The SaveAs function lets you save all or part of the current configuration in a file with the name you specify.

The arguments are equivalent to the options in the Save As dialog box (File menu).

Examples

SaveAs( "GRAPHICS" )

Saves the current configuration in the file GRAPHICS.KTC.

SaveAs?( )

Displays the Save As dialog box that lets you specify a filename, extension, and drive and directory in which to save the configuration. You can also select the parts of the configuration you want to save, create an icon, and specify the program group in which to put the icon.


SaveLayout (macro function)
SaveLayout

SaveLayout[?]( [Name=]string, [[CreateIcon=]boolean], [[ProgramGroup=]string] )

The SaveLayout function lets you specify a name for the layout file. You can also create an icon and program group for the layout file. Choosing the icon starts all the application windows saved in the layout and connects to the respective hosts.

The arguments are equivalent to the options in the Save Layout dialog box (Window menu).

Name   	Specify the name of the layout to create. Do not include a file extension.

CreateIcon   	Whether to create an icon in a Windows Program group that starts this layout.

ProgramGroup   If CreateIcon is selected, names the program group in where the icon appears.


Screen (macro function)
Screen

Screen( [Page=]integer, [Row=]integer, [Col=]integer, [[Len=]integer] )

The Screen function returns text extracted from the emulation screen.

Page   	The Page on which to look.

Row   	Screen row at which to start.

Col   	Screen column at which to start. 1 to 80 (or 132)

Len    	Number of characters to extract. Extraction stops at the end of the line if it occurs first. The default is to extract to the end of line.

For a description of Row and Col as used in this function, see GetSelection.

Examples

CRLF = "^M^J"

Clear( )

Echo( "Lines of Text : " + CRLF ) // line 1

Echo( "ABCD" + CRLF )             // line 2

Extract1 = Screen( 1, 1, 1, 4 )   // copy first four cols from line 1

Extract2 = Screen( 1, 2, 1, 4 )   // copy first four cols from line 2

MsgBox( "Extract1 = " + Extract1 + CRLF + "Extract2 = " + Extract2 )

The preceding macro extracts text from two lines on the screen and displays the text in a message box. Extract1 contains "Line"; Extract2 contains "ABCD".


ScreenChanged (macro function)
ScreenChanged

ScreenChanged( [Type=]integer, [Row=]integer, [Col=]integer, [EndRow=]integer, [EndCol=]integer, [Page=]integer )

The ScreenChanged function allows a macro to take action whenever the text in a specified area of the emulation screen changes. The function is typically used as a When event in a Begin..When..End construct. The ScreenChanged event is triggered when the text within the area changes.

Type   	Can be either one of:

Select_Stream (like left mouse-button selection) Default.

Select_Block (like right mouse-button selection)

Row   	Starting row of the selection. Default is 1, the top row.

Col   	Starting column of the selection. 1 to 80 (or 132). Default is 1, the leftmost column.

EndRow   	Ending row of the selection. Default is the last row.

EndCol   	Ending column+1 of the selection. Default is the last column+1.

Page   	The page on which the selection occurs. Page can be from 1 to the maximum number of pages, or -1 to indicate the VT status bar. Default is page 1.

This function requires the value of EndCol to be one greater than the last character included in the selection. For a description of Row and Col as used in this function, see GetSelection.

You can use several When ScreenChanged statements to specify as many areas as you need.

Events work similarly to DDE link updates. An event is posted after a maximum delay time if the changes happen too rapidly for the minimum idle time to be met. This time is the same value set in the Links function.

Note that the rectangle specified in the parameter list has nothing to do with current highlighted selections.

Example

Begin

  Suspend()

  When ScreenChanged( Select_Block, 1, 1, 4, 8, Page = 1 )

    MsgBox( "Screen changed in top-left quadrant" )

    Continue

  When ScreenChanged( Select_Block, 5, 8, 8, 15, Page = 1 )

    MsgBox( "Screen changed in bottom-right quadrant" )

    Continue

  When Wait( 300 ) // if we are still in the loop after 30 secs

    MsgBox( "Timeout occurred.." )

    Break

End

The preceding example sets up two screen regions defined by rectangles. When the text in either one of these regions changes, the macro receives an update event and notifies the user that a change has occurred. After thirty seconds the macro times out.


ScreenMatch (macro function)
ScreenMatch

ScreenMatch( [Pat=]string, [[Options=]integer], [[Idle=]integer], [[Timeout=]integer], [Type=]integer, [[Row=]integer], [[Col=]integer], [[EndRow=]integer], [[EndCol=]integer], [[Page=]integer] )

The ScreenMatch function allows a macro to take action when it finds a pattern match on the screen. The function is typically used as a When event in a Begin..When..End construct. The ScreenMatch event is triggered when the target characters appear on the screen.

Pat   	A string or pattern to search for. You can use "^J" to match on the left column.

Options   	Whether Pat contains special pattern-matching characters, and whether to ignore upper case and lower case when matching. You can combine these values. The default is a simple string, case-exact. Values are:

Pat_RegExp	Pat contains special pattern-matching characters.

Pat_NoCase	Pat is case-insensitive.

Idle   	An idle time in 1/10 second units. If this argument is included, a match occurs only if the characters received from the host match the given Pat and then no further characters are written over the matching string for the Idle time. Characters written outside the matched area do not affect the idle time. Idle must be less than Timeout, if a timeout is supplied.

Timeout   	Timeout interval in 1/10 second units. The default is no timeout.

Type   	Can be either one of:

Select_Stream (like left mouse-button selection)

Select_Block (like right mouse-button selection)

Row   	Starting row of the selection. Default is top row.

Col   	Starting column of the selection. 1 to 80 (or 132). Default is leftmost column.

EndRow   	Ending row of the selection. Default is bottom row.

EndCol   	One greater than the last character included the selection. Default is rightmost column.

Page   	The page on which the selection occurs. Page can be from 1 to the maximum number of pages, or -1 to indicate the VT status bar. Default is first page.

This function returns the matching string and its position as an array in Result. Null indicates failure.

Result.Value   	Matching string found on the screen.

Result.Row, Result.Col, Result.Page       Position on the screen where the found string begins.

You can use several When ScreenMatch statements to specify as many areas as you need.

You can specify a timeout for the match in two different ways. If there are multiple matches, and you want to process the timeout for each match separately, use the timeout parameter to the ScreenMatch function. A timeout executes the event statements for that particular match with Result set to null. If there are multiple matches, and you want common timeout processing, use the Timeout function.

Example

The following displays a message whenever "Username" appears on the screen at the left column anywhere in the top half of page 1 and no characters are written over this spot for an interval of 5 seconds. The matching continues until the user presses a key.

Begin

  When ScreenMatch( Pat="^JUsername", Idle=50, Type=Select_Block,

                    Row=1, Col=1, EndRow=12, EndCol=81, Page=1 )

    MsgBox( "matched string \"" + Result.value + "\" at " +

        Result.Page + " (" + Result.Row + "," + Result.Col + ")"  )

    Continue

 When Keystroke( )

   Break

End


ScreenRead (macro function)
ScreenRead

ScreenRead( [Type=]integer, [Row=]integer, [Col=]integer, [EndRow=]integer, [EndCol=]integer, [Page=]integer )

The ScreenRead function returns the text in the specified area of the emulation screen. Trailing blanks are included, but line terminators are not.

Type   	Can be either one of:

Select_Stream (like left mouse-button selection) Default.

Select_Block (like right mouse-button selection)

Row   	Starting row of the selection. Default is 1, the top row.

Col   	Starting column of the selection. 1 to 80 (or 132). Default is 1, the leftmost column.

EndRow   	Ending row of the selection. Default is the last row.

EndCol   	Ending column+1 of the selection. Default is the last column+1.

Page   	The page on which the selection occurs. Page can be from 1 to the maximum number of pages, or -1 to indicate the VT status bar. Default is page 1.

This function requires the value of EndCol to be one greater than the last character included in the selection. For a description of Row and Col as used in this function, see GetSelection.

Example

CRLF = "^M^J"

Clear( )

Echo( "Lines of text " + CRLF ) // line 1

Echo( "ABCDEFGH" + CRLF )             // line 2

// copy line 1 and 2 complete

Extract1 = ScreenRead( Type=Select_Block, Row=1, Col=1, EndRow=2, EndCol=10 )

MsgBox( "Extract1 = " + Extract1 )

The preceding macro extracts text from columns 1 through 9 on two lines on the screen and displays the text in a message box. Extract1 contains "Lines of ABCDEFGH ".


Send (macro function)
Send

Send( [Text=]string )

The Send function sends the specified string to the host.

Examples

CR = "^M"

Send( "ATH" + CR )

Phone = Input( "Enter the number to dial:" )

Send( "ATDT " + Phone + CR )

The preceding macro first issues an ATH to the host, then displays an input box. It then sends the sequence ATDT followed by the number the user entered in the input box.


SendKey (macro function)
SendKey

SendKey( [Name=]string )

The SendKey function sends a VT function to the host. You must specify a VT function that is valid for the type of terminal KEA! is emulating.

Name   	The VT function name to be sent. This must be the exact name as it appears in the Value field in the Keyboard Mapping, Mouse, or SmartPad dialog boxes. To see the exact VT function name of a particular key, open the Keyboard Mapping dialog box (from the Options menu, Keyboard command). Press the desired key. Any key that is not in the main keypad displays its VT function name in the Value box, enclosed in "angle brackets".

Example

SendKey( "Down" )

SendKey( "Down" )

SendKey( "Right" )

SendKey( "PF1" )

The preceding macro moves the cursor 2 character positions down, 1 character position right, and sends a PF1 to the host.


SetDirectory (macro function)
SetDirectory

SetDirectory( [Name=]string )

The SetDirectory function changes the current directory to the given path name. It returns the full path if you specified a valid directory.

KEA! looks for files in the current directory when executing the following functions: Capture, FileCopy, FileDelete, FileDir, FileOpen, and FileRename.

Examples

NewDir = SetDirectory( GetDirectory( Directory_Macro ) )

The preceding line changes the current directory to the directory from which the currently executing macro was loaded. The full path is assigned to NewDir.

SetDirectory( ".." )

The preceding line changes the current directory to its parent (one level closer to the root). For example, if the current directory was \KEAVT\MACROS, the preceding line would change it to \KEAVT.


SetIni (macro function)
SetIni

SetIni( [File=]string, [Section=]string, [Key=]string, [String=]string )

The SetIni function creates the specified value in the registry database, or named .INI file.

The meaning of key in this description might be confusing. In the registry database, key refers to a group of values. In addition this function has a parameter Key which identifies one of a number of values grouped in a registry key.

The File parameter determines whether String is placed in the registry database or an .INI file as follows:

Filename in File parameter with path removed	Section parameter identifying a registry key or .INI file section.	Action
WIN.INI		A value is added to the registry database following the pattern of other WIN.INI settings. The Section parameter determines the registry key; Key and String are used to create a name and value.
KEA.INI	KEAVT  *	Key and String are used to create a name and value which are added to the current user's registry key: HKEY_CURRENT_USER\Software\Attachmate\KEA!\n.nn\KEAVT
KEA.INI	Compatibility  *	Key and String are used to create a name and value which are added to the machine-specific registry key: HKEY_LOCAL_MACHINE\Software\Attachmate\KEA!\n.nn\Compatibility
KEA.INI	other SectionName	The Section parameter identifies a key below the current user's own registry key:  HKEY_CURRENT_USER\Software\Attachmate\KEA!\SectionName If the key does not exist, it is created. Key and String are used to create a name and value which are added to this key.
other INI file name	Name of section in the .INI file.	Inserts the line Key=String in a DOS-like .INI file, under the heading [Section].  If needed, the file, the section, and the key are created.
In File and Section, case is ignored.

*  If the string "V4.22" is included in the Section parameter, it is ignored. A Section parameter that includes an older version label is processed as section names in the other category. For example, SetIni with a parameter Section="KEAVT V4.10" creates the key HKEY_CURRENT_USER\Software\Attachmate\KEA!\KEAVT V4.10.

Examples

SetIni("c:\transfer\kea.ini", "KEAVT", "AlternateFont", "Yes")

After the above macro runs, Registry Editor shows the value
AlternateFont:REG_SZ:Yes
in the key
HKEY_CURRENT_USER\Software\Attachmate\KEA!\4.12\KEAVT

SetIni("c:\transfer\kea.ini", "compatibility", "AsyncConnect", "No")

After the above macro runs, Registry Editor shows the value
AsyncConnect:REG_SZ:No
in the key
HKEY_LOCAL_MACHINE\Software\Attachmate\KEA!\4.12\Compatibility

SetIni("c:\transfer\kea.ini", "mine", "Test", "Message2")

After the above macro runs, Registry Editor shows the value
Test:REG_SZ:Message2
in the key
HKEY_CURRENT_USER\Software\Attachmate\KEA!\mine

SetIni("c:\transfer\mine.ini", "compatibility", "Test", "Message3")

After the above macro runs, the line
Test=Message3
is written in the [Compatibility] section of the file C:\TRANSFER\MINE.INI


SetSelection (macro function)
SetSelection

SetSelection( [Type=]integer, [Row=]integer, [Col=]integer, [EndRow=]integer, [EndCol=]integer, [Page=]integer )

The SetSelection function selects a streamed or block area of page memory.

Type   	Can be either one of:

Select_Stream (like left mouse-button selection)

Select_Block (like right mouse-button selection)

Row   	Starting row of the selection.

Col   	Starting column of the selection. 1 to 80 (or 132)

EndRow   	Ending row of the selection.

EndCol   	Ending column+1 of the selection.

Page   	The page on which the selection occurs. Page can be from 1 to the maximum number of pages, or -1 to indicate the VT status bar.

This function requires the value of EndCol to be one greater than the last character included in the selection. For a description of Row and Col as used in this function, see GetSelection.

Examples

// This example selects the first 7 characters on row 1

SetSelection( Select_Block, 1, 1, 1, 8, 1 )

// This example selects characters starting at row 2, character 5

// up to and including row 23, character 50

SetSelection( Select_Stream, 2, 5, 23, 51, 1 )


Snapshot (macro function)
Snapshot

Snapshot( )

The Snapshot function copies the currently viewed page into the History buffer. It has no return value.

Snapshot only works if history has been enabled. To activate the history buffer use the Enable History function.


StatusBar (macro variable)
StatusBar

StatusBar = boolean

The StatusBar variable specifies whether to display the status bar. Values are:

0	Hide the status bar.

1	Display the status bar.

Changing this variable is equivalent to selecting the Status Bar option in the View dialog box (Options menu).


Str (macro function)
Str

Str( [Value=]integer )

The Str function returns the string equivalent of the specified integer.

Example

Count = 123

Alpha = Str( Count )

In the preceding macro Alpha contains the string value "123".


SubStr (macro function)
SubStr

SubStr( [String=]string, [Start=]integer [,[Len=]integer] )

The SubStr function returns a portion of the specified string.

String   	Source text string.

Start   	Begin this number of characters from the left end of the string; a negative number begins that many characters from the right end of the string.

Len   	Number of characters to extract. If omitted or larger than the remainder of the string, return all characters to the end of string.

Example

Alpha = "abcdefghijklmnop"

Beta = SubStr( Alpha, 3, 2 )

In the preceding macro Beta contains the string value "cd".


Suspend (macro function)
Suspend

Suspend( )

The Suspend function suspends operation of the macro and returns control to the user. When used in a Begin..When..End construct, Suspend leaves the macro waiting for the When event(s) to occur and returns to the user.

You can use the Stop command on the Macro menu to terminate all suspended macros.

Example

Begin

  Suspend( )  // allow concurrent user activity while

              // waiting for When events to occur

  When Wait( 500 )

    MsgBox( "Timeout occurred" )

  When Disconnected( )

    MsgBox( "Disconnected from host" )

End

In the preceding macro the Suspend allows the user to continue working in KEA! until either a Wait or Disconnected occurs.


SystemTime (macro function)
SystemTime

SystemTime( )

The SystemTime function returns the time as an integer representing the number of seconds since 1 January 1970. If your processor knows about time zones (you defined TZ= ), the time is GMT.

Example

StartTime = SystemTime( )

Wait( 20 )

EndTime = SystemTime( )

ElapsedTime = EndTime - StartTime  // in seconds

Echo( "Elapsed time is: " + ElapsedTime + " seconds" )

In the preceding macro, the SystemTime sets the StartTime; two seconds elapse and SystemTime sets the EndTime. The difference between the StartTime and EndTime is set to ElapsedTime, and is echoed to the screen.


Terminal (macro function)
Terminal

Terminal[?]( [Mode=string], [DAResponse=string], [CustomPrimaryDA=string], [CustomSecondaryDA=string], [Answerback=string], [CharacterSetMode=string], [UserPreferredCharacterSet=string], [NationalCharacterSet=string], [LocalEcho=boolean], [LockUserKeys=boolean], [LockUserFeatures=boolean] )

The Terminal function specifies the settings related to terminal type, DA response, and character set.

The arguments are equivalent to the options in the Terminal General dialog box (Options Terminal menu).

Mode   	The terminal mode for KEA! to emulate. Values are:

VT400-7bit   VT400-8bit   VT100   VT52   ANSI-BBS   401X

DAResponse   	How KEA! identifies itself to the host. Values are:

KEA! VT420   VT340   VT320   VT240   VT220   VT131   VT125   VT102   VT101   VT100   Custom   KEAterm

CustomPrimaryDA   Your custom primary device attribute response.

CustomSecondaryDA   Your custom secondary device attribute response

Answerback   	String to send in response to a ^E from the host.

CharacterSetMode   Whether to use 7-bit and 8-bit characters, or just 7-bit. Values are:

Multinational	Use 7-bit and 8-bit characters.

National	Use only 7-bit characters, and some special character to replace unused characters for a specific language.

UserPreferredCharacterSet   Which 8-bit supplemental character set to use. Values are:

DEC-MCS   ISOLatin-1   IBM-PC

NationalCharacterSet   Which National Character Replacement set to use. Values are:

N.American   British   Flemish   Fr.Canadian   Danish   Finnish   German   Dutch   Italian   SwissFrench   SwissGerman   Swedish   Norwegian   French/Belgian   Spanish   Portuguese

LocalEcho   	Whether the emulation window displays the characters sent to the host, or lets the host handle echo.

LockUserKeys   	Whether the host system can change user-defined key (UDK) definitions.

LockUserFeatures   Whether the host system can change the settings of the user preference features columns, scroll, and inverse screen.

Examples

Terminal( Mode = "VT400-8bit", DAResponse = "VT420" )

Sets the terminal type to VT420.

X = Terminal.Mode

Records the current terminal mode.


TextBox (macro function)
TextBox

TextBox( [[Text=]String], [[Width=]Int], [[Height=]Int], [[Offset=]Int] )

The TextBox control displays the string specified in Text. The function must appear within the Controls section of a Begin Dialog..End construct. The string can extend over multiple lines either because it is longer than the specified width (so it wraps), or because there are ^M^J sequences in the string.

Text   	The Text string to display.

Width   	A literal integer or integer variable that defines the horizontal space (in average character width) taken up by the complete control. It includes the text and the separating white space.

Height   	A literal integer or integer variable that defines the vertical space (in character height) taken up by the control. It includes the borders and separating white space. The box defaults to an appropriate height if you do not supply this parameter.

Offset   	A literal integer or integer variable that defines how far from the right edge of the space the left part of the control starts. You should specify an offset that is less than the width.

Example

Begin Dialog( "Sample Text Box" )

  TextBox( "This is a long string in a small width, so KEA! wraps over several lines.", 30 )

  OkButton( )

End


Time (macro function)
Time

Time( [[Format=]integer] )

The Time function returns the current time as a character string. The format is your Windows time format. (You can set the time format in the Windows Control Panel International dialog box.)

Format   	12 or 24. If omitted, your Windows time format provides the default.

Examples

Time12 = Time( Format = 12 )  //  for example:  1:29:45

Time24 = Time( Format = 24 )  //  for example: 13:29:45

Echo( "Time : " + Time12 + " or " + Time24 )

The preceding macro illustrates the use of the Format option in retrieving the time from a 12-hour clock or a 24-hour clock.


Timeout (macro function)
Timeout

Timeout( [Time=]integer [,[Options=]integer] )

The Timeout function pauses for the specified amount of time. Timeout can be used in a Begin..When loop with Continue to generate events periodically. The timeout events repeat until the Begin..When loop finishes executing with a Break or Return.

Used outside of a Begin..When loop, Timeout behaves exactly the same as Wait.

Time   	The time interval in tenths of a second. Make sure the timeout value is high enough for your application and specific hardware. Some modems and terminal servers might require a value of 300 or more.

Options   	Whether data from the host is processed during the pause; by default, it is not. If you want to process host data, specify the value Wait_ProcHostInput.

Tip  A better method to process host data while waiting is with the Match function. Even if you are not looking for a particular pattern, you can still Match on a null string.

Examples

CR = "^M"

Match( "CONNECT" )

Timeout( 5 )  // wait half a second

Send( CR )    // prompt for host

The preceding macro matches on CONNECT, times out after one half second and sends a CR.

CRLF = "^M^J"

Begin

  When Match( "*" + CRLF, Pat_RegExp )

    Message( Result )

    Continue

  When Timeout( 10 ) // every second

    Send( "DIR" + CRLF )

    Continue

  When Timeout( 300 ) // if we are still in the loop after 30 secs

    MsgBox( "Timeout occurred.." )

    Break

End

The preceding macro sends the command "DIR" to the host every second and matches on all text output from the host. This continues until the 30 second Timeout expires, at which point the macro leaves the Begin..When..End loop.


Title (macro function)
Title

Title( [String=]string )

The Title function displays the specified string on the title bar. By default, the configuration filename is displayed. The product identification, such as KEA!, always precedes the string you supply.

Examples

Title( "PURCHASING" )

The preceding macro displays a string on the title bar.

Title( Date( ) )

The preceding macro displays the current date on the title bar.

Title( HostName( ) )

The preceding macro displays the host name on the title bar.


Toolbar (macro function)
Toolbar

Toolbar = boolean

The Toolbar variable specifies whether to display the Toolbar. Values are:

0	Hide the Toolbar.

1	Display the Toolbar.

Changing this variable is equivalent to selecting the Show Toolbar command on the Options menu.


TransferAbort (macro function)
TransferAbort

TransferAbort( [[Type=]integer] )

The TransferAbort function stops the current transfer.

Type   	Specify when to stop the transfer. Values are:

Abort_Immediate	Stop transfer now; do not wait for the other end to acknowledge.

Abort_All	Stop transfer of all files with the other end's concurrence.

Abort_File	Stop transfer of the current file with the other end's concurrence and continue.


TransferCommand (macro function)
TransferCommand

TransferCommand( [[Command=]string], [[Options=]integer] )

The TransferCommand function specifies the commands to be used with a Kermit or FTP server. This function results in a file handle to a memory file containing any response from the host. If a command fails, for example, because the protocol does not support this capability, KEA! returns the string "TransferCommand failed".

Command   	Specify the command to send to the host.

Options   	Specify whether to display status, and which protocol to use.

Xfer_NoStatus	Do not display status.

Xfer_Kermit	Use Kermit.

Xfer_FTP	Use FTP.


TransferProd (macro function)
TransferProd

TransferProd( )

The TransferProd function simulates a timeout during a transfer. This function is provided so you can bind macros to a simulated timeout button.


TransferProgress (macro function)
TransferProgress

TransferProgress( [[Info=]var] [,[Options=]integer] )

The TransferProgress function records the progress information of a transfer. The function returns an array of information in the variable specified by Info, or in Result if you do not specify Info.

This function returns new values periodically.

Info   	Contains information placed in the variable in an array. Includes:

Type	Xfer_Start, Xfer_Continue, Xfer_End, or Xfer_Between according to whether between files or a new file is starting, continuing, or ending — provided to make it easy to pick up specific events without having to compare filenames or check other data elements.

FileName	Full path name on the local disk of the currently transferring file.

ReqName	Rename as requested by the user. If rename was not requested, this is null.

RemoteName	Name on the remote disk, as KEA! determines it. On a transmit, this is only correct when the host notifies KEA! of the actual name. On a receive, this is the name obtained from the protocol before any changes were made.

Message	Current information message about the transfer.

Size	Total file size (-1 if not known).

Bytes	Number of bytes transferred so far.

Packets	Number of packets transferred so far.

Time	Time, in milliseconds, spent so far on this file.

Errors	Errors encountered so far in transferring this file.

Timeouts	Number of timeouts that occurred so far in transferring this file.

FileType	Type of file transfer — Xfer_Binary or Xfer_Text.

Sending	True if sending, False if receiving.

EndState	One of the following pre-defined constants: (Xfer_EndFail has the lowest numerical value; Xfer_EndOk has the highest so that you can compare the returned value with these constants)

Xfer_EndOk

Xfer_EndRename   KEA! performed a needed rename (not user-specified) or the host renamed a received file and informed KEA! of the rename.

Xfer_EndSkip   File already existed.

Xfer_EndCancel   User cancelled.

Xfer_EndFail   All other failures.

Options   	Specify when to return updated information. If you specify no values, information is returned once a second, and at the start of a file, between files, and at the end. Values are:

Progress_NoStart	Do not report start events.

Progress_NoContinue	Do not report at one second intervals.

Progress_NoEnd	Do not report at the end of individual files.

Progress_NoBetween	Do not report between files.

Examples

Var Info

CRLF = "^M^J"

Begin

  // concurrent statements

  Echo( "Bytes left to transfer" + CRLF )

  TransferTransmit( "C:\TEST.TXT" )

  When TransferProgress( Info )

    Echo( Info.Size - Info.Bytes + CRLF ) // remaining bytes

    Continue

  When Wait( 300 )      // 30 second timeout

    MsgBox( "Transmission timeout." )

End

The preceding example periodically displays the number of bytes left to send during the transfer.


TransferReceive (macro function)
TransferReceive

TransferReceive( [[Files=]string | [Files=]array], [[Options=]integer], [[Path=]string] )

The TransferReceive function specifies the information for receiving or getting a file or files from a host. You use the TransferProgress function to get information about specific files.

Files   	Specify the file or files to receive or get from the host. Values are:

String	Single filename, or a list of names separated by spaces.

Array	List of files.

Options   	Specify how to receive the file(s). This overrides the default transfer options. Values are:

Xfer_Binary	Transmit files as binary.

Xfer_Text	Transmit files as text.

Xfer_Automatic	Determine file type automatically.

Xfer_UsePath	Use incoming path information.

Xfer_NoUsePath	Do not use incoming path information.

Xfer_CreatePath	Create missing path.

Xfer_NoCreatePath	Do not create missing path.

Xfer_CrashRecovery   Resume interrupted Zmodem transfer at point of interruption.

Xfer_NoCrashRecovery   Do not resume interrupted Zmodem transfer.

Xfer_OverWrite	Overwrite existing file with file from host.

Xfer_Rename	Rename received file.

Xfer_RenameOld	Rename existing file.

Xfer_Discard	Abort the transfer.

Xfer_Append	Write new information to end of existing file.

Xfer_NoStatus	Do not display or log transfer progress status.

Xfer_CtrlZ	Use CTRL-Z as the end of file indicator.

Xfer_NoCtrlZ	Do not add CTRL-Z to indicate end of file.

Xfer_MapNL	Change received LF or CRLF to CRLF for text file transfer.

Xfer_NoMapNL	Do not change received LF or CRLF.

Xfer_Xmodem	Use Xmodem to receive files.

Xfer_Ymodem	Use Ymodem to receive files.

Xfer_Zmodem	Use Zmodem to receive files.

Xfer_ASCII	Use ASCII to receive files.

Xfer_Kermit	Use Kermit to receive files.

Xfer_FTP	Use FTP to receive files.

Xfer_DetailedEnd	The return code becomes an array subscripted by local path names and the value of each element is the ending state for that file.

Path   	Specify the path to use for received files; this overrides the default transfer path.

This function returns an integer whose value is one of the following pre-defined constants. Xfer_EndFail has the lowest numerical value; Xfer_EndOk has the highest so that you can compare the returned value with these constants. The returned value is the lowest for any file in the group.

Xfer_EndOk

Xfer_EndRename	KEA! performed a needed rename (not user-specified) or the host renamed a received file and informed KEA! of the rename.

Xfer_EndSkip	File already existed.

Xfer_EndCancel	User canceled.

Xfer_EndFail	All other failures.

If you include Xfer_DetailedEnd among the Options, an array is returned. The array is subscripted by the local path names; the value of each element is one of the preceding constants.

Examples

Success = TranferReceive( Files = "MYFILE.DAT",

    Options = Xfer_Kermit + Xfer_NoStatus )

Success is Xfer_EndOk if the file MYFILE.DAT transferred properly from the host using the Kermit protocol.

Begin

  TransferReceive( "junk.txt", Options = Xfer_NoStatus )

  When TransferProgress( info )

    // do anything wanted with the info

    Continue

  When Timeout( 100 )

End

Sends a file with a 10 second timeout, and does not display or log status. When the timeout occurs, the macro exits the Begin..When..End. This automatically cancels the transfer.

RcName[Xfer_EndFail] = "failed"

RcName[Xfer_EndCancel] = "cancelled"

RcName[Xfer_EndSkip] = "skipped"

RcName[Xfer_EndRename] = "renamed"

RcName[Xfer_EndOk ] = "ok"

rc = TransferReceive( "FILE1.C FILE2.H FILE3.C", Xfer_DetailedEnd )

For i In rc

  Echo( "File" + i + " = " + RcName[rc[i]] + "^M^J" )

End

Receives three files, requesting an array of returned status values. It displays a list of the filenames and individual transfer results.


TransferTransmit (macro function)
TransferTransmit

TransferTransmit( [[Files=]string | [Files=]array], [[Options=]integer], [[Path=]string], [[HostName=]string] )

The TransferTransmit function specifies the information for transferring a file or files to a host. You use the TransferProgress function to get information about specific files.

Files   	Specify the file or files to send to the host. Values are:

String	Single filename, or a list of names separated by spaces.

Array	List of files.

Options   	Specify how to send the file(s). This overrides the default transfer options. Values are:

Xfer_Binary	Transmit files as binary.

Xfer_Text	Transmit files as text.

Xfer_Automatic	Determine file type automatically.

Xfer_FullPath	Send full path.

Xfer_NoFullPath	Send only filename.

Xfer_SubDirectories   Send files in subdirectories under the directory from which you are transferring files.

Xfer_NoSubDirectory   Do not send files in subdirectories.

Xfer_NoStatus	Do not display or log transfer progress status.

Xfer_SendCRLF	Send CRLF at the end of line when transmitting text files.

Xfer_SendLF	Send only LF at the end of line when transmitting text files.

Xfer_CtrlZ	Use CTRL-Z as the end of file indicator.

Xfer_NoCtrlZ	Treat CTRL-Z as part of the file.

Xfer_Xmodem	Use Xmodem to transmit files.

Xfer_Ymodem	Use Ymodem to transmit files.

Xfer_Zmodem	Use Zmodem to transmit files.

Xfer_ASCII	Use ASCII to transmit files.

Xfer_Kermit	Use Kermit to transmit files.

Xfer_FTP	Use FTP to transmit files.

Xfer_DetailedEnd	The return code becomes an array subscripted by local path names and the value of each element is the ending state for that file.

Path   	Specify the path from which to send files; this overrides the default transfer path.

HostName   	Specify the name for the first file sent to the host.

This function returns an integer whose value is one of the following pre-defined constants. Xfer_EndFail has the lowest numerical value; Xfer_EndOk has the highest so that you can compare the returned value with these constants. The returned value is the lowest for any file in the group.

Xfer_EndOk

Xfer_EndRename	KEA! performed a needed rename (not user-specified) or the host renamed a received file and informed KEA! of the rename.

Xfer_EndSkip	File already existed.

Xfer_EndCancel	User canceled.

Xfer_EndFail	All other failures.

If you include Xfer_DetailedEnd among the Options, an array is returned. The array is subscripted by the local path names; the value of each element is one of the preceding constants.

Examples

Success = TranferTransmit( Files = "myfile.dat",

    Options = Xfer_Kermit + Xfer_NoStatus )

Success is Xfer_EndOk if the file MYFILE.DAT transferred properly to the host using the Kermit protocol.

Begin

  TransferTransmit( "junk.txt", Options = Xfer_NoStatus )

  When TransferProgress( info )

    // do anything wanted with the info

    Continue

  When Timeout( 100 )

End

Sends a file with a 10 second timeout, and does not display or log status. When the timeout occurs, the macro exits the Begin..When..End. This automatically cancels the transfer.

RcName[Xfer_EndFail] = "failed"

RcName[Xfer_EndCancel] = "canceled"

RcName[Xfer_EndSkip] = "skipped"

RcName[Xfer_EndRename] = "renamed"

RcName[Xfer_EndOk ] = "ok"

rc = TransferTransmit( "FILE1.C FILE2.H FILE3.C", Xfer_DetailedEnd )

For i In rc

  Echo( "File" + i + " = " + RcName[rc[i]] + "^M^J" )

End

Transmits three files, requesting an array of returned status values. It displays a list of the filenames and individual transfer results.


Transmit (macro function)
Transmit?

Transmit?( [[FileName=]string], [[ListFilesOfType=]string], [[HostFile=]string], [[FileType=]integer], [[QuitServerAtEnd=]boolean] )

When you use the Transmit function in a macro (equivalent to the Send command on the Transfer menu) you must use it with a question mark: Transmit?( ). This displays the Transmit dialog box, which the user can complete before choosing OK. Any function arguments you include appear as default option values in the usual way. Note that you cannot use Transmit without the question mark.

The following arguments appear as defaults in the dialog box.

FileName   	The file you want to send.

ListFilesOfType   The extension for the files you want listed in the File Name field.

HostFile   	Filename which the host uses to store the file (Not available with Xmodem).

File Type   	Mode in which to transfer the file. This option is not available for ASCII file transfers.

Automatic	Enables the automatic file type processing based on the file extension and file scan options in the File Transfer dialog box.

Binary	Send file in binary mode. KEA! sends all 8 data bits, and does not perform character translation. Typically, binary files are object code or executable programs.

Text	Send file in text mode. KEA! translates characters to suit a dissimilar remote system. You might lose data if the file contains any binary data.

QuitServerAtEnd   Send the Finish command to the host at the end of the transfer (Kermit server only).

If you want to transfer files without user interaction, use the TransferTransmit function instead.


Uppercase (macro function)
Uppercase

Uppercase( [String=]string )

The Uppercase function returns a string that is the upper case equivalent of the specified string.

Examples

HostString = UpperCase( "abcD" )

In the preceding macro the variable HostString contains "ABCD".

// Return a mixed case version of the word supplied

Function MixCase( Name )

  FirstLetter = UpperCase( SubStr( Name, 1, 1 ) )

  RestName = LowerCase( SubStr( Name, 2 ) )

  NewName = FirstLetter + RestName

  Return( NewName )

End // Function MixCase

// Get a name and call the MixCase function

NameToChange = Input( "Name to change to mixed case" )

Converted = Mixcase( NameToChange )

MsgBox( "Modified Name: " + Converted )

The preceding macro creates a function called MixCase using the Lowercase and Uppercase functions. This function creates a mixed case name in the variable NewName. It displays a dialog box to enter the name to change; the entered name is then changed, and displayed in the MsgBox.


Var (macro statement)
Var

Var variable1[=expression] [, variable2[=expression]] ... [, variableN[=expression]]

The Var control statement declares local variables, initialized to zero. They are local to the section in which you define them.

You can use Var

•	at the outermost level of a macro to prevent accidental changes to a predefined or global variable;

•	inside a user-defined function;

•	in a event, so that the variables do not exist in the rest of the macro.

When used in a Begin..When..End control statement, Var appears as:

Begin
  [Concurrent statement(s)]
When Condition
   Var variable1 [, variable2] ... [, variableN]
     Statement(s)
When Condition
     Statement(s)
End


VerticalScrollBar (macro variable)
VerticalScrollBar

VerticalScrollBar = boolean

The VerticalScrollBar variable specifies whether to display or hide the vertical scroll bar. Values are:

0	Hide the scroll bar.

1	Display the scroll bar.

Changing this variable is equivalent to selecting the Vertical Scroll Bar option in the View dialog box (Options menu).


VTKeyboard (macro variable)
VTKeyboard

VTKeyboard = boolean

The VTKeyboard variable specifies whether to display the on-screen VT keyboard.

Values are:

False (0)	Do not display keyboard.

True (1)	Display keyboard.

Changing this variable is equivalent to selecting the Show Keyboard command (Options menu).


VTStatusLine (macro variable)
VTStatusLine

VTStatusLine = string

The VTStatusLine variable specifies whether to display the VT status line, and where to display it. Values are:

Hidden	Do not display the VT status line.

Above Scroll Bar	Display it above the horizontal scroll bar.

Below Scroll Bar	Display it below the horizontal scroll bar.

Changing this variable is equivalent to selecting the VT Status Line option in the View dialog box (Options menu).

The variable returns values containing an ampersand (&) in the string.


Wait (macro function)
Wait

Wait( [Time=]integer [,[Options=]integer] )

The Wait function pauses the current macro for the specified time. Used in a Begin..When loop, it generates only a single event. (In contrast, the Timeout function can be used in a Begin..When loop to generate periodic events.)

Time   	The time interval in tenths of a second. Make sure the wait value is high enough for your application and specific hardware. Some modems and terminal servers might require a value of 300 or more.

Options   	Whether data from the host is processed during the pause; by default, it is not. If you want to process host data, specify the value Wait_ProcHostInput.

Tip  A better method to process host data while waiting is with the Match function. Even if you are not looking for a particular pattern, you can still Match on a null string.

Examples

CR = "^M"

Match( "CONNECT" )

Wait( 5 )   //wait half a second

Send( CR )  //prompt for host

The preceding macro matches on "CONNECT", waits one half second and sends a CR.

CR = "^M"

MyName = "MyUserName"

Password = Input( "What is the password?",, Input_Hide )

Send( "ATZ" + CR )               // reset the modem

Begin

  When Match( "OK" )

    Send( "ATDT 5559999" + CR )  // dial phone number

    Continue

  When Match( "CONNECT" )        // watch for connection

    Send( CR )

    Continue

  When Match( "Username:" )      // send username

    Send( MyName + CR )

    Continue

  When Match( "Password:" )       // send password

    Send( Password + CR )

    Continue

  When Match( "$" )            // watch for host prompt

    Break                      // break out of loop

  When Wait( 300 )   // if we are still in the loop after 30 sec

    MsgBox( "Timeout occurred.." )

    Break

End

Send( CR )

The preceding macro dials and logs into a host. It matches on modem and host response. When it matches the host prompt or the 30 second Wait timeout occurs, it continues execution after the End statement.


While..End (macro statement)
While...End

While Condition
     Statement(s)
End

The While..End control statement repeatedly executes a group of statements until the specified condition evaluates as zero. If the condition is zero the first time the macro evaluates it, the macro never executes the statements.

Example

FileHandle = FileOpen( "D:\NAMES.TXT", File_Read )

While Not FileEnd( FileHandle )           // while not end of file

  DataString = FileRead( FileHandle, 10 ) // read in next 10 chars

  Echo( DataString )                      // display characters

End

The preceding macro reads ten characters at a time, and echoes them to the screen.

cr = "^M"

Connect( ) // make sure KEA! is connected to a port

CONT = Button_Yes

While CONT = Button_Yes

  Send( "ATH" + cr )

  Match( "OK", Timeout = 20 )

  If Result = "OK"

    If ArgCount > 0

      phone = Arg[1]

    Else

      phone = Input( "Enter the phone number to dial" )

    End

    Send( "ATDT " + phone + cr )

    Match( "CONNECT", timeout = 300 )

    If Result = ""      // test for timeout

      CONT = MsgBox( "Timeout. Try again?", Button_Yes + Button_No )

    Else

      CONT = Button_No

      Wait( 5 )

      Send( cr )   // prompt for host after connection is made

    End // if Result = ""

  Else

    CONT = MsgBox( "No response. Try again?",

        Button_Yes + Button_Cancel )

  End // if OK

End // while

The preceding macro continues to execute while the variable CONT is set to Button_Yes.


WindowList (macro variable)
WindowList

WindowList

The WindowList variable contains the name of the current session. Assigning the name of an open session to the variable makes that session active. It is equivalent to the checked item on the session list at the bottom of the Window menu.

Example

mysession = WindowList

Records the name of the current session.


Definition of PRODNAME bookmark:KEA!

Definition of SHORTNAME bookmark:KEA!

Definition of EDITNAME bookmark:KEA! Edit


ANSI Sequences

KEA! supports most of the functions of the VT terminal.

The following ANSI functions are available when the option Mode in the Terminal dialog box (Options menu) is set to VT400/7-bit, VT400/8-bit, or VT100. Some of the controls are not standard ANSI, but are extended ANSI. These include DEC private and KEA! private ANSI-compatible extensions.

Non-ANSI (VT52) functions are listed at the end of this section. These are available when Mode in the Terminal dialog box is set to VT52.

If you use features such as keyboard mapping, user-defined buttons, macros, DA responses, and so on, you may want to store a control code or string of characters and other codes. In some cases, such as macro strings, you must enclose the text in quotes. If you want to use a literal quote character within a quoted string, put a slash before the quote ( \" ).

To enter	Do

Visible characters	Press the corresponding key.

Any code	Type a circumflex (^) followed by up to three decimal digits. For example, type ^27 for ESC, or ^155 for CSI. You can use this method to store any code from the 7-bit or 8-bit character table.

Control codes 0 to 31	Type a circumflex (^) followed by an uppercase character. For example, for a carriage return you can type ^M or ^13

A literal ^	Type  \^


C0 and C1 Control Codes

C0 Code	Decimal	Action taken when code received:

NUL	0	Ignored.

SOH	1	Ignored.

STX	2	Ignored.

ETX	3	Ignored.

EOT	4	Ignored.

ENQ	5	Send ANSWERBACK message.

ACK	6	Ignored.

BEL	7	Generate bell tone, if bell enabled.

BS	8	Move cursor left.

HT	9	Move cursor to next horizontal tab stop.

LF	10	Line feed, or new line operation.

VT	11	Line feed, or new line operation.

FF	12	Line feed, or new line operation.

CR	13	Move cursor to left margin.

SO	14	Invoke G1 character set into GL position (LS1).

SI	15	Invoke G0 character set into GL position (LS0).

DLE	16	Ignored.

DC1 (XON)	17	If XON/XOFF support enabled, clear the XOFF state and start sending characters.

DC2	18	Ignored.

DC3 (XOFF)	19	If XON/XOFF support enabled, stop sending characters.

DC4	20	Ignored.

NAK	21	Ignored.

SYN	22	Ignored.

ETB	23	Ignored.

CAN	24	Terminate and cancel escape sequence, control sequence, or device control string.

EM	25

SUB	26	Terminate and cancel escape sequence, control sequence, or device control string and display error character (reverse question mark).

ESC	27	Introduce an escape sequence. Terminate any in-progress escape, control, or device control sequence.

FS	28	Ignored.

GS	29	Ignored.

RS	30	Ignored.

US	31	Ignored.

SP	32	Space.

DEL	127	Ignored.

C1 control codes (128 to 159) can only be used directly in an 8-bit environment. However, any C1 control code can be replaced by two 7-bit codes. The first code is ESC and the value of the second code is 64 less than the value of the C1 code.

C1 Code	Decimal	7-bit equiv	Action taken when code received:

IND	132	ESC D	Index: move cursor down, scroll if at bottom.

NEL	133	ESC E	Next line: move to first position on next line, scroll at bottom.

SSA	134	ESC F	Ignored.

ESA	135	ESC G	Ignored.

HTS	136	ESC H	Horizontal Tab Set.

HTJ	137	ESC I	Ignored.

VTS	138	ESC J	Ignored.

PLD	139	ESC K	Ignored.

PLU	140	ESC L	Ignored.

RI	141	ESC M	Reverse Index: move cursor up, scroll if at top.

SS2	142	ESC N	Invoke G2 set into GL position for next graphic character only.

SS3	143	ESC O	Invoke G3 set into GL position for next graphic character only.

DCS	144	ESC P	Open a device control string.

PU1	145	ESC Q	Ignored.

PU2	146	ESC R	Ignored.

STS	147	ESC S	Ignored.

CCH	148	ESC T	Ignored.

MW	149	ESC U	Ignored.

SPA	150	ESC V	Ignored.

EPA	151	ESC W	Ignored.

CSI	155	ESC [	Introduce a control sequence.

ST	156	ESC \	Terminate a device control string.

OSC	157	ESC ]	Ignored.

PM	158	ESC ^	Ignored.

APC	159	ESC _	Ignored.


Control Sequences for ANSI and DEC Modes
ANSI and DEC Modes

ANSI Modes

CSI  <Pa>  h  	These control functions set ANSI modes.

CSI  <Pa>  l  	These control functions reset ANSI modes.

Pa	ANSI Modes	CSI <Pa> h	CSI <Pa> l

2	Keyboard Action	locked	unlocked

3	Control Representation	transparent	interpret

4	Insert Replace	insert	replace

12	Send/Receive	no local echo	local echo

20	LineFeed/NewLine	Received LF FF VT   Received LF FF VT

causes newline;	causes linefeed;

Return key sends.	Return key sends

CR LF	CR.

DEC Modes

CSI  ?  <Pd>  h  	These control functions set DEC private modes.

CSI  ?  <Pd>  l  	These control functions reset DEC private modes.

Pd	DEC Modes	CSI ? <Pd> h	CSI ? <Pd> l

1	Cursor Keys	application	ANSI

2	ANSI Off	Not Applicable	VT52 mode

3	Columns	132	80

4	Scrolling	(smooth scroll not implemented)

5	Screen	reverse	normal

6	Origin Mode	Cursor addressing	Cursor addressing

relative to region.	relative to screen.

7	Autowrap	Characters wrap 	no wrap

to next line

8	Autorepeat	(autorepeat not implemented)

18	Print Form Feed	FF after print	no FF

screen

19	Printer Extent	page	region

25	Text Cursor Enable	show	hide

42	NRCS	National	Multinational

60	Horz Cursor Coupling	on	off

61	Vert Cursor Coupling	on	off

64	Page Cursor Coupling	on	off

66	Numeric KeyPad	application	numeric

67	Backarrow Key	backspace	delete

68	Keyboard Usage	(data processing keys

 not implemented)

69	Vertical Split Screen	double-wide lines 	left/right margins

disabled	disabled

81	Key Position Mode	(Key position reports not implemented)


Control Sequences for ANSI Locator Mode
ANSI Locator Mode Sequences

DEC Enable Locator Reports

CSI  <Ps> ; <Pu>  '  z	Set individual locator events to send locator reports to the host.

Ps = 0, disabled. Ps = 1, enabled. Ps = 2, One shot (allow one report, then disable)

Pu = 0 or 2 (or omitted), report location using character cells. Pu = 1, report location using device physical pixels.

Locator Position Report

CSI  <Pe> ; <Pb> ; <Pr> ; <Pc> ; <Pp>  &  w     This report is sent to the host when a selected event occurs.

Pe	Event code. Pe = 0, request received, locator unavailable. Pe = 1, request received. Pe = 2 left button down. Pe = 3, left button up. Pe = 4, middle button down. Pe = 5, middle button up. Pe = 6, right button down. Pe = 7, right button up. Pe = 8, fourth button down. Pe = 9, fourth button up. Pe = 10, locator outside filter rectangle.

Pb	Button code, ASCII decimal value 0-15. The 4 bits of the binary equivalent indicate which buttons are down.

Pr	Row coordinate of locator position, ASCII decimal value

Pc	Column coordinate of locator position, ASCII decimal value

Pp	Page number of locator position, ASCII decimal value.

DEC Enable Filter Rectangle

CSI  <Pt> ; <Pl> ; <pb> ; <Pr>  '  w     Define coordinates of and activate Filter Rectangle (one-shot event). Filter includes boundaries. When locator detected outside rectangle, or rectangle specified without a locater, an outside rectangle event is generated and rectangle disabled. Omitted parameters default to the current locator position. Sending without parameters causes application to be notified for any locator movement (unfiltered movement event).

Pt	Top boundary

Pl	Left boundary

Pb	Bottom boundary

Pr	Right boundary

Select Locator Events

CSI  <P>.;..<P>  '  {	Select which events can generate unsolicited reports. Can report both up and down transitions where exact button activation sequence significant.

<P>...<P>	One or more selective parameters. P = 0, respond only to Request Locator Position received from the host (default, also cancels pending filter rectangle). P = 1, report button down transitions. P = 2, do not report button down transitions. P = 3, report button up transitions. P = 4, do not report button up transitions.

Request Locator Position

CSI  <Ps>  '  |	Explicitly request a locator position report. If session receiving request not currently active, uses last known locator position and state. If locator disabled or unavailable, reports event code 0.

Device Status Report (DSR) request

CSI  ?  55  n	Request a locator Device Status Report. The PC can send the following responses:

CSI  ?  58  n    Locator ready and has transmitted a successful self-test message.


Control Sequences for Page Memory and Cursor
ANSI Sequences for Page Memory and Cursor

Page Position Absolute

CSI  <Ps>  sp   P	Moves the cursor to the corresponding row and column on page Ps.

Page Position Forward

CSI  <Ps>  sp  Q	Moves the cursor forward to the corresponding row and column Ps pages forward.

Page Position Backward

CSI  <Ps>  sp  R	Moves the cursor backward to the corresponding row and column Ps pages backward.

Set Columns Per Page

CSI  <Ps>  $  |	Selects the page width of all pages to be Ps columns per page, any value between 80 and 132 columns.

Cursor Up

CSI  <Pn>  A	Moves the cursor up Pn lines.

Cursor Down

CSI  <Pn>  B	Moves the cursor down Pn lines.

Cursor Right

CSI  <Pn>  C	Moves the cursor right Pn columns.

Cursor Left

CSI  <Pn>  D	Moves the cursor left Pn columns.

Cursor Position

CSI  <Pr>  ;  <Pc>  H	Move the cursor to an absolute row and column.

CSI  <Pr>  ;  <Pc>  f	Move the cursor to an absolute row and column.

Pan Right

CSI  <Ps>  sp  @	Moves the user window right Ps columns. VT340 function.

Pan Left

CSI  <Ps>  sp  A	Moves the user window left Ps columns. VT340 function.

Pan Down

CSI  <Pn>  S	Moves the user window down Pn lines.

Pan Up

CSI  <Pn>  T	Moves the user window up Pn lines.

Next Page

CSI  <Pn>  U	Moves the cursor to home, Pn pages forward.

Previous Page

CSI  <Pn>  V	Moves the cursor to home, Pn pages backward.

Clear Tab Stops

CSI  <Ps>  g	Ps =0, clear only the tab stop at cursor. =3, clear all tabs.

Set Top and Bottom Margins

CSI  <Pt>  ;  <Pb>  r	Sets the top and bottom scrolling margins for the current page. If both values are 0, the region is reset to full page.

Set Left and Right Margins

CSI  <Pl>  ;  <Pr>  s	Sets the left and right scrolling margins for the current page. If both values are 0, the vertical region is reset to full page width. Vertical Split Screen mode must be set.

Set Number Lines Per Page

CSI  <Pn>  t	Sets each page in page memory to have Pn lines. KEA! allows any value from 24 to 144 lines.

Index Left

ESC  6	Moves the cursor backward one column.

Save Cursor

ESC  7	Stores away many of the cursor settings. There can be two separate saved states at once: the main window and the status line.

Restore Cursor

ESC  8	Restores the settings saved by the preceding function.

Index Right

ESC  9	Moves the cursor forward one column.

Index Down

ESC  D	Moves the cursor down one column.

Next Line

ESC  E	Moves the cursor to the beginning of the next line.

Horizontal Tab Set

ESC  H	Sets a tab stop at the current cursor position.

Index Up

ESC  M	Moves the cursor up one column.


Control Sequences for Editing and Visual Attributes
ANSI Sequences for Editing and Visual Attributes

Selective Erase In Display

CSI  ?  <Ps>  J	Erases the erasable characters in the current page. Ps =0: cursor to end of page; =1: beginning of page to cursor; =2: complete page. The cursor remains where it was.

Selective Erase In Line

CSI  ?  <Ps>  K	Erases the erasable characters in the current line. Ps =0: cursor to end of line; =1: beginning of line to cursor; =2: complete line. The cursor remains where it was.

Set Char Protect Attribute

CSI  <Ps>  "  q	Defines successive characters written to the page memory as protected (Ps=0 or 2) or unprotected (Ps=1).

Change Attributes In Rectangular Area

CSI  <Pt>;<Pl>;<Pb>;<Pr>;  <Ps1>;...;<Psn>  $  r      Changes the visual character attributes of a specified rectangular area in page memory.

    Pt,Pl	Top-left coordinate.

    Pb,Pr	Bottom-right coordinate.

    Ps1...	Attributes to change to (same format as SET VISUAL ATTRIBUTES).

Reverse Attributes In Rectangular Area

CSI  <Pt>;<Pl>;<Pb>;<Pr>;  <Ps1>;...;<Psn>  $  t        Reverses the visual character attributes of a specified rectangular area in page memory.

    Pt,Pl	Top-left coordinate.

    Pb,Pr	Bottom-right coordinate.

    Ps1...	Attributes to reverse to (same format as SET VISUAL ATTRIBUTES).

Copy Rectangular Area

CSI  <Pts>;<Pls>;<Pbs>;<Prs>;<Pps>;  <Ptd>;<Pld>;<Ppd>  $  v      Copies a rectangular area of characters from one section to another in page memory. The copied text retains its character values and attributes.

    Pts,Pls	Source top-left coordinate.

    Pbs,Prs	Source bottom-right coordinate.

    Pps	Source page.

    Ptd,Pld	Destination top-left coordinate.

    Ppd	Destination page.

Fill Rectangular Area

CSI  <Pch>;<Pt>;<Pl>;<Pb>;<Pr>  $  x       Fills a rectangular area in page memory with a specified character. Line attributes are not affected, but all character attributes use the current writing attribute.

    Pch	character to fill area with.

    Pt,Pl	Top-left coordinate.

    Pb,Pr	Bottom-right coordinate.

Erase Rectangular Area

CSI  <Pt>;<Pl>;<Pb>;<Pr>  $  z       Erases characters and their attributes from the specified rectangular area in page memory.

    Pt,Pl	Top-left coordinate.

    Pb,Pr	Bottom-right coordinate.

Selective Erase Rectangular Area

CSI  <Pt>;<Pl>;<Pb>;<Pr>  $  {       Erases all unprotected characters from a specified rectangular area in page memory.

    Pt,Pl	Top-left coordinate.

    Pb,Pr	Bottom-right coordinate.

Select Attribute Change Extent

CSI  <Ps>  *  x	Selects which type of area (rectangle or streamed) can have their attributes changed or reversed. This affects two control functions: Change Attributes In Rectangular Area, and Reverse Attributes In Rectangular Area. Ps =0,1: use streamed areas; =2 use rectangular areas.

Insert Column

CSI  <Pn>  '  }	Inserts Pn columns into the scrolling region, underneath the cursor.

Delete Column

CSI  <Pn>  '  ~	Deletes Pn columns in the scrolling region, deleting the column under the cursor.

Insert Character

CSI  <Pn>  @	Inserts Pn blank characters at the current cursor position.

Erase In Display

CSI  <Ps>  J	Erases characters from the page. The cursor remains where it was. Ps =0: erase from cursor to end of page; =1: beginning of page to cursor; =2: complete page.

Erase In Line

CSI  <Ps>  K	Erases characters from the line. The cursor remains where it was. Ps =0: erase from cursor to end of line; =1: beginning of line to cursor; =2: complete line.

Insert Line

CSI  <Pn>  L	Inserts Pn blank single-height, single-width lines.

Delete Line

CSI  <Pn>  M	Deletes Pn lines starting at the current cursor position. If the cursor is within a region, only the region is affected.

Delete Character

CSI  <Pn>  P	Deletes Pn characters at the current cursor position. All characters following are shifted.

Erase Character

CSI  <Pn>  X	Erases Pn characters from the current cursor position to the right. No characters are shifted.

Set Visual Attributes

CSI  <Ps1>;...<Psn>  m        Selects character attributes and ISO colors.

    0	reset all attributes (to white on black)

    1	bold

    4	underline

    5	blink

    7	inverse

    8	invisible

    22	bold off

    24	underline off

    25	blink off

    27	inverse off

    28	revealed

    30	FG black

    31	FG red

    32	FG green

    33	FG yellow

    34	FG blue

    35	FG magenta

    36	FG cyan

    37	FG white

    39	default FG

    40	BG black

    41	BG red

    42	BG green

    43	BG yellow

    44	BG blue

    45	BG magenta

    46	BG cyan

    47	BG white

    49	default BG

Select Line Attributes

ESC  #  3	Double-High Double-Wide top

ESC  #  4	Double-High Double-Wide bottom

ESC  #  5	Single-High Single-Wide

ESC  #  6	Single-High Double-Wide


KEA! Private Functions

In addition to the standard ANSI control sequences, KEA! supports the following ANSI-compatible extensions.

DCS 4.z <datastring> ST

Execute the macro instructions <datastring>, maximum 8K. This function and the following one can be turned off with the Options command (Macro menu).

DCS 4;1.z <datastring><checksum> ST

Execute the macro instructions <datastring> as in the preceding command, only if the two-character <checksum> is correct. If the checksum is incorrect, KEA! responds with

DCS 4;1.y <checksum> ST

where this checksum is the correct one for the previously sent <datastring>. For more information, see Invoking a Macro.

CSI 4; <Pn> .z	Execute macro filename REMOTE<Pn>.KTM, where Pn is the character pair 00 to 99.

CSI  1;  <Pr>;  <Pc> .z       Define a rectangle and draw a border around it. The upper left corner is at the cursor, the size is Pr rows by Pc columns.

CSI  E	Newline inside the rectangle.

CSI  4  J	Clear inside the rectangle.

CSI  1 .z	Undefine the rectangle, but leave its border and contents on the screen.

CSI  3;  <Pn> .z	Stop processing for Pn/10 seconds.

CSI 5; <Pn>.z	Request a KEA! Device Attribute report. The parameters <Pn> are optional. If all are omitted, the response will include parameters 1, 2, 3, and 4.  The response is

DCS 5.y <values> ST

Values are separated by semicolons, in the same order as requested.

    Pn	value

    1	Product	KEA!

    2	Model	420

    3	Version	n.n.nn

    4	Beta	Rn.nnn or Rnn.nnn

    10	Environment	DOS/Windows

    12	Remote Macros	0=false, 1=true


Control Sequences for Local Editing
ANSI Sequences for Local Editing

Transmit Line Terminator Character

CSI  ?  <Pn1>;... <Pn6>  '  s	Defines character(s) the terminal sends to the host at the end of each line of transmitted data.

    Pn1...	EOL characters as decimal codes, 0 to 254.

Transmit Termination Character

CSI  <Ps> |   	Defines the character the terminal sends to the host at the end of each block transmission.

Ps=0	no character

Ps=1 	FF

Ps=2	ETX

Ps=3 	EOT

Ps=4 	CR

Ps=5	DC3

CSI  ? <Pn1>;    <Pn6> |      	This extended sequence defines up to 6 characters the terminal sends to the host at the end of each block transmission.

Pn1	EOB characters in the range 0 to 254

Edit Mode

CSI  ?  10  h	Puts the terminal in local edit mode.

CSI  ?  10  l	Puts the terminal in interactive mode.

Line Transmit Mode

CSI  ?  11  h	Determines the size of a line of characters

CSI  ?  11  l	Determines the size of a full or partial page

Space Compression Mode

CSI  ?  13  h 	The terminal sends no space characters at the end of character fields.

CSI  ?  13  l   	The terminal sends space characters at the end of character fields.

Transmit Execution Mode

CSI  ?  14  h   	The terminal sends data immediately after you press the Enter key,

CSI  ?  14  l   	The terminal waits for host's permission to send data.

Edit Key Execution Mode

CSI  ?  16  h   	The terminal switches between edit mode and interactive mode immediately after you press Shift+Edit.

CSI  ?  16  l    	The terminal waits for host's command to switch between edit mode and interactive mode

VT131 Transmit Mode

CSI  ?  53  h   	The terminal works like a VT131 during data transmission.

CSI  ?  53  l  	The terminal does not work like a VT131 during data transmission.

Guarded Area Transfer Mode

CSI  1  h    	The terminal can send all characters to the host.

CSI  1  l  	The terminal can send only unprotected characters to the host.

Erasure Mode

CSI  6  h  	erasure functions can edit all characters.

CSI  6  l   	erasure functions can edit unprotected characters only.

Multiple Area Transfer Mode

CSI  15  h 	The terminal can send all selected areas to the host.

CSI  15  l 	The terminal can send one selected area to the host.

Transmit Termination Mode

CSI  16  h	 Determines whether the terminal includes the cursor position as part of the criteria that end a block transmission. (scrolling region)

CSI  16  l	(partial page)

Selected Area Transfer Mode

CSI  17  h	The terminal can send all characters to the host.

CSI  17  l	The terminal can send only selected characters to the host

Visual Attribute Protection

CSI  <Ps1>;... <Psn>  }  Determines character protection based on visual attributes.

Psn=0	no characters are protected

Psn=1	bold characters

Psn=4	underline characters

Psn=5	blink characters

Psn=7	inverse characters

Psn=8 	invisible characters

Psn=21	not bold characters

Psn=24	not underline characters

Psn=25	not blink characters

Psn=27	not inverse characters

Psn=28	not invisible characters

Psn=254	normal characters are protected

Transmit Block

ESC  5	Tells the terminal to send a block of characters.

Selected Area Operations

ESC  F	start of a selected area

ESC  G	end of a selected area

Protected Area Operations

ESC  V	start protected area

ESC  W	end protected area


Control Sequences for Status Line
ANSI Sequences for Status Line

Status Line Type

CSI  <Ps>  $  ~	Selects the type of status line.

Ps =0	no status line

Ps =1	indicator line

Ps =2	host-writable status line

Select Status/Main

CSI  <Ps>  $  }	Selects whether the terminal sends data to the main display (Ps=0) or the host writable status line (Ps=1).


Control Sequences for Keyboard and Display Commands
ANSI Sequences for Keyboard and Display Commands

Define Macro

DCS  <Pid>;  <Pdt>;  <Pen>  !  z  <Data>  ST

Pid	{0,1,2,..63}  Macro ID.

Pdt	=0 replace this one; =1 delete all.

Pen	=0 ASCII data encoding; =1 hex pairs.

This device control string defines a macro consisting of a string of ANSI text and control functions.

Program User-Defined Keys (UDK)

DCS  <Pc>;<Pl>  |  <Ky1/St1>;..<Kyn/Stn>  ST

Pc	=0 (default) clears all keys before loading new values.

=1 clears one key at a time before loading a new value.

Pl	=0 locks the keys. To load in new values must be =1).

Ky1...	Key to define.

17,18,19,20,21	F6,F7,F8,F9,F10

23,24,25,26	F11,F12,F13,F14

28,29         	HELP,DO

31,32,33,34	F17,F18,F19,F20

St1...	Key definition string. The string is defined by hex pairs.

Downloads definitions for User-Defined Keys.

Numeric Keypad Mode

ESC  =	(application seqs)

ESC  >	(keypad chars)

These control functions select whether the numeric keypad sends numeric characters or application sequences to the host. Same as CSI ? 66 h

Local Function Key Control

CSI  <Pk1;Pf1>;...<Pkn;Pfn>  *  }

Pkn	0	all four keys (F1..F4).

1..4	F1,..F4.

Selects the action of the local-function keys on the top row of the keyboard.

Select Number Of Lines Per Screen

CSI  <Pn>  *  |

Selects the maximum number of lines that the screen can display. KEA! does not perform this function (permitting the user to maintain the chosen window size), but it uses it to determine which down-loadable soft character rendition to use.

Invoke VT Macro

CSI  <Pid>  *  z	Executes a stored macro with id number 0..64.

Screen Alignment Display

ESC  #  8	Fills the complete screen area with a test pattern.


Control Sequences for Terminal Reports
ANSI Sequences for Terminal Reports

Restore Terminal State

DCS  1  $  p  <Data>  ST	Restores the terminal to a previous state requested with CSI $ u . Every terminal has its own version of the Data string.

Request Control Function

DCS  $  q  <Data>  ST	Requests the settings of another control functions. Data contains the intermediate and/or final characters of the control function requested.

Restore Presentation

DCS  {1,2}  $  t  <Data>  ST	Restores one of two presentation reports specified by Ps. If P1 is 1, then cursor information is restored, otherwise 2 means that tab stops are restored.

Secondary Device Attribute

CSI  >  c	Provides the terminal's identification code, firmware version level, and hardware options.

Request Mode Settings

CSI  <Pa>  $  p	Set ANSI mode

CSI  ?  <Pd>  $  p	Set DEC mode

Request Cursor Position

CSI  6  n

CSI  ?  6  n	(extended)

These control functions request the position of the current cursor. The extended request returns the page number as well as row and column.

Request Printer Status

CSI  ?  15  n	Requests the printer status.

Request User-Define Keys Locked

CSI  ?  25  n	Reports if the user-defined keys (UDKs) are locked or unlocked.

Request Keyboard Status

CSI  ?  26  n	Reports the current keyboard dialect, operating status, and type.

Request Macro Space

CSI  ?  62  n	Reports the available macro space.

Request Memory Checksum

CSI  ?  63  n	Returns a memory checksum report of all current text macro definitions.

Request Data Integrity

CSI  ?  75  n	Reports the status of the data integrity flag. The data integrity flag indicates the integrity of the data flow between the terminal and host. This flag is reset each time the terminal sends a data integrity report.

Request Session Configuration

CSI  ?  85  n	KEA! always responds "configured as one session."

Request Window Report

CSI  "  v	Reports how much of the current page is displayed on the screen at any time.

Request Terminal State

CSI  Ps  $  u	Requests a terminal state report (Ps=1) or a color table report (Ps=2).

Request Presentation

CSI  {1,2}  $  w	Requests a cursor information report (P1=1), or tab stop report (P1=2).

Request User-Preferred Supplemental Set

CSI  &  u	Requests the current user-preferred supplemental character set.

Request Checksum of Rectangular Area

CSI  <Pid>;<Pp>;<Pt>;<Pl>;<Pb>;<Pr>  *  y
Requests a checksum of the specified rectangular area in the specified page.

Pid	the checksum report returns as an ID number.

Pp	page number.

Pt,Pl,Pb,Pr	rectangular coordinates.

Primary Device Attribute

CSI  c

ESC  Z   	Request the terminal's architectural class and basic attributes. Both report the same thing.

Request Operation Status

CSI  5  n	Requests the terminal's operating status.


Control Sequences for Character Sets
ANSI Sequences for Character Sets

Assign User Preferred Supplemental

DCS   u  {%5,A,I}  ST    Assigns the user-preferred supplemental character set. KEA! includes the IBM extended character set.

Down-Loadable Soft Character Sets

DCS  Pfn;Pcn;Pe;Pcmw;Pss;Pt;Pcmh;Pcss { Dscs Sixels;...;Sixels  ST

Pfn	DRCS font buffer. Both values {0,1} refer to the same font buffer.

Pcn	Starting character {0,1,2,..,95}; selects where to load the first character in the font buffer. A value of 0 means that the first soft character is loaded into position 2/0 (space character) of the set.

Pe	Erase control; selects which characters to erase form the DRCS buffer before loading the new fonts. A value of 0 means erase all characters in this rendition. A value of 1 means erase only characters in locations being loaded. A value of 2 means erase all renditions of the soft character set.

Pcmw	Character matrix width. If the value is either one of {2,3,4}, the height is also defined. In that case, Pcmh has no effect.

0	default (usually max width).

1	illegal.

2	(5x10)  vt220 compatibility.

3	(6x10)  vt220 compatibility.

4	(7x10)  vt220 compatibility.

5	width of 5.

6	width of 6.

7	width of 7.

8	width of 8.

9	width of 9.

10	width of 10.

11	width of 11.      11 .. 15 are VT320

12	width of 12.

13	width of 13.

14	width of 14.

15	width of 15.

Pss	Screen rendition; defines screen width and height for this font.

0,1	24 lines x 80 columns.

2	24 x 132.

11	36 x 80.

12	36 x 132.

21	48 x 80.

22	48 x 132.

Pt	Text or full cell font. 2 means use full cell, otherwise characters are automatically centered like text.

Pcmh	Character matrix height {0,1,..,20}. 0 means default, all other values are measurements in pixels high. (However the terminal will show more than this height restriction if the sixel data provides more.)

Pcss	=0: 94 character set size; =1: 96 character set size.

Dscs	Font name designated to this character set.

Examples:{ SP @, A, &%C }.

Sixels	Sixel data defining the soft character set. Each character is separated by a semi-colon, and each sixel row in a character is separated by forward-slash (/).

KEA! emulates all terminals, therefore the soft set will be accepted according to the terminal chosen in the DA Response option.

Set ANSI Conformance Levels

ESC  sp  L	(level 1)

ESC  sp  M	(level 2)

ESC  sp  N	(level 3)
Lets an application map certain character sets into the terminal's in-use table as default sets. The character sets are based on ANSI conformance levels. Levels 1 and 2: - ASCII designated as G0 mapped into GL, ISO Latin-1 supplemental designated as G1 mapped into GR. Level 3: ASCII designated as G0 mapped into GL.

Designating Character Sets

ESC  (  <Name>	(94 set -> G0)

ESC  )  <Name>	(94 set -> G1)

ESC  *  <Name>	(94 set -> G2)

ESC  +  <Name>	(94 set -> G3)

ESC  -  <Name>	(96 set -> G1)

ESC  .  <Name>	(96 set -> G2)

ESC  /  <Name>	(96 set -> G3)
These control functions designate a character set (hard or soft) as G0 through G3. Later these can be mapped into GL and GR. Possible Names follow:

ASCII	B

User-preferred supplemental	<

DEC Supplemental Graphic	%5

DEC Special Graphics	0

DEC Technical	>

ISO Latin-1 Supplemental	A	(96 characters)

IBM Extended	I	(96 characters)

(NRC sets)

ISO United Kingdom	A

DEC Finnish	5 or C

ISO French	R

DEC French Canadian	9 or Q

ISO German	K

ISO Italian	Y

ISO Norwegian/Danish	`

DEC Norwegian/Danish	6 or E

DEC Portuguese	%6

ISO Spanish	Z

DEC Swedish	7 or H

DEC Swiss	=

Dutch	4

Mapping Character Sets

SI	(G0 -> GL)

SO	(G1 -> GL)

ESC  n	(G2 -> GL)

ESC  o	(G3 -> GL)

ESC  |	(G3 -> GR)

ESC  }	(G2 -> GR)

ESC  ~	(G1 -> GR)
These control functions map a character set in {G0,G1,G2,G3} into the in-use table as GL or GR. Single shift controls are provided by C1 codes.


Control Sequences for Session Control
ANSI Sequences for Session Control

Secure Reset

CSI  <Pr>  +  p	Sets the terminal to its power-up state. Pr is an optional random number from 0 to 16383. If Pr is included, the terminal sends a confirmation with this number.

Soft Terminal Reset

CSI  !  p	Changes some of the terminal's current settings to the factory default settings.

Set Operating Level

CSI  {61,62,63,64}  ;  {0,1,2}  "  p
Selects the terminal's operating level. Performs a soft reset. This effect will also happen if the terminal mode in the menu is changed (soft reset occurs when leaving the setup menu). The first parameter is the operating level (where 61=vt100, ... 64=vt400). Selecting 62 in a vt300 series terminal will result in selecting level 3 (vt300). Selecting 62 or 63 in a vt400 series terminal will result in selecting level 4 (vt400). The second parameter is the bit control (8 bits=0,2; 7 bits=1).

Set 7-Bit Controls

ESC  sp  F	Causes the terminal to send C1 codes in their 7-bit format: ESC followed by the value of the C1 code minus 64.

Set 8-Bit Controls

ESC  sp  G	Causes the terminal to send C1 codes in their 8-bit format.

Hard Reset

ESC  c	Causes the terminal to restart with power-up default settings. Everything including the line memory is reset.


Control Sequences for Printing
ANSI Sequences for Printing

Print Cursor Line

CSI  ?  1  i	Prints the line that has the cursor. The cursor does not move.

Auto Print Mode

CSI  ?  5  i    (on)

CSI  ?  4  i    (off)	In this mode, the printer prints a line from the screen when you move the cursor off that line with an LF, FF, or VT character, or an autowrap occurs. The printed line ends with a CR and the character (LF, FF, or VT) that moved the cursor off the previous.

Print Composed Main Display

CSI  ?  10  i	Prints the data on the screen. This data may include the status line.

Print All Pages

CSI  ?  11  i	Prints all pages in page memory for the current session.

Request Printer Status

CSI  ?  15  n	Requests the printer status.

Print Page

CSI  i	Prints the page that has the cursor.

Printer Controller Mode

CSI  5  i    (on)

CSI  4  i    (off)	This mode lets the host control the operation of the printer. The terminal sends characters and control sequences directly to the printer, without displaying them on the screen. The terminal sends all characters and control sequences except NUL, XON, XOFF, and the printer controller mode sequences.


VT Functions Not Supported by KEA!

Enable Local Functions

CSI  <Pf1;Pc1>;...<Pfn;Pcn>  +  q
On a real VT terminal, this enables the keys used to perform local terminal functions (F1, Select, Remove, InsertHere, panning keys, resizing keys).

Select Mod Key Reporting

CSI  <Pm1;Pf1>;...<Pmn;Pfn>  +  r
On a real VT terminal, this enables the modifier keys (Shift, Lock, Ctrl, Alt, Compose) to send extended keyboard reports.

Make Session Active

CSI  &  x          	A real VT terminal can have two simultaneous sessions. You can have multiple simultaneous sessions by running multiple copies of KEA!.

Printer-To-Host Session

CSI  ?  9  i        CSI  ?  8  i

Assign/Release Printer To/From Active Session

CSI  ?  18  i      CSI  ?  19  i


ASCII Codes Generated by Keyboard in VT400-7bit and VT100 Modes

Key that has	Transmitted ASCII code sequence

this VT function

keypad mode	keypad mode

set to numeric	set to application

0	0	ESC O p
1	1	ESC O q
2	2	ESC O r
3	3	ESC O s
4	4	ESC O t
5	5	ESC O u
6	6	ESC O v
7	7	ESC O w
8	8	ESC O x
9	9	ESC O y
-	-	ESC O m
,	,	ESC O l
.	.	ESC O n
Enter	CR	ESC O M
PF1	ESC O P	ESC O P
PF2	ESC O Q	ESC O Q
PF3	ESC O R	ESC O R
PF4	ESC O S	ESC O S
cursor key mode	cursor key mode

set to normal	set to application

up arrow	ESC [ A	ESC O A
down arrow	ESC [ B	ESC O B
right arrow	ESC [ C	ESC O C
left arrow	ESC [ D	ESC O D
Key that has	Transmitted ASCII code sequence

this VT function

Terminal Mode	Terminal Mode

set to VT400-7bit	set to VT100

Find	ESC [ 1 ~	ESC [ H
Insert Here	ESC [ 2 ~	ESC O p
Remove	ESC [ 3 ~	ESC O n
Select	ESC [ 4 ~	ESC O q
Prev Screen	ESC [ 5 ~	ESC O y
Next Screen	ESC [ 6 ~	ESC O s
Shift +Tab	ESC [ Z	ESC [ Z
F6	ESC [ 1 7 ~	. . . . .
F7	ESC [ 1 8 ~	. . . . .
F8	ESC [ 1 9 ~	. . . . .
F9	ESC [ 2 0 ~	. . . . .
F10	ESC [ 2 1 ~	. . . . .
F11	ESC [ 2 3 ~	. . . . .
F12	ESC [ 2 4 ~	. . . . .
F13	ESC [ 2 5 ~	. . . . .
F14	ESC [ 2 6 ~	. . . . .
Help	ESC [ 2 8 ~	. . . . .
Do	ESC [ 2 9 ~	. . . . .
F17	ESC [ 3 1 ~	. . . . .
F18	ESC [ 3 2 ~	. . . . .
F19	ESC [ 3 3 ~	. . . . .
F20	ESC [ 3 4 ~	. . . . .
In VT400-8bit terminal mode, SS3 is sent in place of ESC O; CSI is sent in place of ESC [.


Received VT52 Codes

The following VT52 functions are available when the Mode option in the Terminal dialog box (Options menu) is set to VT52.

Cursor Functions

ESC A	Cursor up

ESC B	Cursor down

ESC C	Cursor right

ESC D	Cursor left

ESC H	Cursor home

ESC  I	Reverse line feed

ESC Y  row  col	Direct cursor addressing

(row and col are single characters equal to the desired setting plus 37 octal)

Erasing and Editing

ESC J	Erase to end of screen

ESC K	Erase to end of line

Modes of Operation

ESC F	Enter graphics mode

ESC G	Exit graphics mode

ESC =	Enter alternate keypad mode

ESC >	Exit alternate keypad mode

Configuration

ESC <	Enter VT100 mode

ESC Z	Identify as VT52 (transmits ESC /Z)

Printer Functions

ESC ^	Enter auto print mode

ESC _	Exit auto print mode

ESC W	Enter printer controller mode

ESC X	Exit printer controller mode

ESC ]	Print screen

ESC V	Print cursor line


Transmitted VT52 Codes
ASCII Codes Generated by Keyboard in VT52 Mode

Press the key that

has this VT function...	Transmitted ASCII code sequence

...to emulate	Keypad Mode	Keypad Mode

this VT52 key	set to numeric	set to application

0	0	0	ESC ? p
1	1	1	ESC ? q
2	2	2	ESC ? r
3	3	3	ESC ? s
4	4	4	ESC ? t
5	5	5	ESC ? u
6	6	6	ESC ? v
7	7	7	ESC ? w
8	8	8	ESC ? x
9	9	9	ESC ? y
-	. . . .	-	ESC ? m
,	. . . .	,	ESC ? l
..	. . . .	.	ESC ? n
Enter	Enter	CR	ESC ? M
PF1	_blue	ESC P	ESC P
PF2	_ red	ESC Q	ESC Q
PF3	_gray	ESC R	ESC R
PF4	. . . .	ESC S	ESC S
up arrow	_	ESC A	ESC A
down arrow	_	ESC B	ESC B
left arrow	_	ESC C	ESC C
right arrow	_	ESC D	ESC D
Find	. . . .	ESC H	ESC H
Insert Here	. . . .	ESC ? p	ESC ? p
Remove	. . . .	ESC ? n	ESC ? n
Select	. . . .	ESC ? q	ESC ? q
Prev Screen	. . . .	ESC ? y	ESC ? y
Next Screen	. . . .	ESC ? s	ESC ? s
Shift + Tab	. . . .	ESC -	ESC -


Definition of PRODNAME bookmark:KEA! for Windows 95

Definition of SHORTNAME bookmark:KEA!

Definition of EDITNAME bookmark:KEA! Edit


ReGIS and Sixel Controls

ReGIS is DIGITAL's Remote Graphics Instruction Set. This set of commands can describe the parts of an image using geometric shapes: lines, curves, circles. KEA! 340 provides all ReGIS features, including:

•	Graphics Input Modes

•	Rubberband Cursors

•	16 Colors

•	Rotated and Italic Characters

•	Patterns

•	Polygon Fill

•	Macrographs

•	Sixel Graphics

The expression [X,Y] indicates that you can use an absolute or relative X,Y screen position. The brackets are required. The default coordinate system is [0,0] at the top left, [799,479] at the bottom right. Parentheses ( ) enclose options and suboptions of commands. The parentheses are required.

Several commands can use the pixel vector PV system in which numbers 0-7 are used to indicate one of eight directions.


ReGIS Screen Control Command - S

Provides screen controls, such as erasing the screen.

(A[X1,Y1][X2,Y2])	Display addressing
Lets you define screen addressing that uses a different size or orientation than the default VT300 screen. Power-up default is S(A[0,0][799,479]) so that upper-left corner is [0,0]. Lower-right corner is [799,479].

[X,Y]	Scrolling with relative X and Y values
Uses an [X,Y] value to scroll screen data in the bitmap. Does not change the coordinate system. Power-up default is S[0,0] for no scrolling.

PV number	Scrolling with PV offset
Uses a PV number to scroll screen data in the bitmap. Does not change the coordinate system.

(H)	Print complete screen

(H[X,Y][X,Y])	Print defined area (two positions)
Uses two [X,Y] screen coordinates to define opposite corners of the area to print.

(H[X,Y])	Print defined area (one position)
Uses an [X,Y] screen coordinate and the current cursor position to define opposite corners of the area to print.

(H(P[X,Y]))	Print offset suboption
Defines where the upper-left corner of an image will print, using a relative offset from the current printhead location.
The default at power-up is S(H(P[50,0])), until you define a new value. Any printing from the screen is offset 50 coordinates at the printer, to approximate centering on 8-1/2 inch wide paper. Any new value remains in effect until redefined.


VT340 Default Color Map

Location	Color	H	L	S	R	G	B

0	Black	0	0	0	0	0	0

1	Blue	0	50	60	20	20	80

2	Red	120	46	72	80	13	13

3	Green	240	50	60	20	80	20

4	Magenta	60	50	60	80	20	80

5	Cyan	300	50	60	20	80	80

6	Yellow	180	50	60	80	80	20

7	Gray 50%	0	53	0	53	53	53

8	Gray 25%	0	26	0	26	26	26

9	Blue*	0	46	29	33	33	60

10	Red*	120	43	39	60	26	26

11	Green*	240	46	29	33	60	33

12	Magenta*	60	46	29	60	33	60

13	Cyan*	300	46	29	33	60	60

14	Yellow*	180	46	29	60	60	33

15	Gray 75%	0	80	0	80	80	80

*  These colors are less saturated than colors 1 through 6.

(In)	Background intensity (monochrome)
Selects output map location n for the background.

(I(RGB))	Background intensity (RGB color)
Selects the output map location containing the closest color to the RGB value you specified.

(I(HLS))	Background intensity (HLS color)
Selects the output map location containing the closest color to the HLS value you specified. Power-up default is S(I0) so that output map location M0 is used for background. The default value for M0 is black for color and monochrome.

(T0 to 32767)	Time delay
Selects the number of ticks of the real time clock to count for a delay.

(P0 or 1)	Display graphics page
Selects which graphics page is displayed when running a single session. Power-up default is S(P0) displaying the first graphics page.

(E)	Screen erase (current background)
Erases the screen and sets the screen to the current background intensity.

(W(Mn))	Pixel vector multiplier
Selects a multiplication factor of n for each PV value in a scroll command. n defines the number of coordinates affected by each PV value. This is a temporary write command, in effect until the next command key letter.

(C0 or 1)	Graphics cursor on/off
Turns the graphics output cursor off (C0) or on (C1). Default is on.

(C1(Hn))	Select graphics output cursor style
n=0 or 1 is diamond (default)
n=2 is crosshair.

(C1(In))	Select graphics input cursor style
n=0 or 2 is crosshair (default)
n=1 is diamond
n=3 is line
n=4 is box.

(C1(I[x,y]"ForegroundChar BackgroundChar"))
Select downloaded graphics input cursor.


ReGIS Write Control Command - W

Provides writing controls, such as writing shades.

Standard Patterns

Pattern Number	Binary Pattern	Description

0	00000000	All-off write pattern

1	11111111	All-on write pattern

2	11110000	Dash pattern

3	11100100	Dash-dot pattern

4	10101010	Dot pattern

5	11101010	Dash-dot-dot pattern

6	10001000	Sparse dot pattern

7	10000100	Asymmetrical sparse dot pattern

8	11001000	Sparse dash-dot pattern

9	10000110	Sparse dot-dash pattern

Selecting VT340 Planes for Writing

Command	Code	Planes You Can Write To

W(F0)	0000	None

W(F1)	0001	Plane 0

W(F2)	0010	Plane 1

W(F3)	0011	Planes 0 and 1

W(F4)	0100	Plane 2

W(F5)	0101	Planes 0 and 2

W(F6)	0110	Planes 1 and 2

W(F7)	0111	Planes 0, 1, and 2

W(F8)	1000	Plane 3

W(F9)	1001	Planes 0 and 3

W(F10)	1010	Planes 1 and 3

W(F11)	1011	Planes 0, 1, and 3

W(F12)	1100	Planes 2 and 3

W(F13)	1101	Planes 0, 2, and 3

W(F14)	1110	Planes 1, 2, and 3

W(F15)	1111	All planes

Note  Remember to restore writing to all planes after using 1-plane or no-plane writing.

Commands

(Mn)	PV multiplication
Defines a multiplication factor of n for all pixel vector (PV) values used in later commands. Can serve as a temporary write control for other types of commands. Power-up default is W(M1) giving a PV multiplication factor of 1.

(P0 to 9)	Select standard pattern
Selects 1 of 10 stored writing patterns. Power-up default is W(P1) giving a solid line.

(Pbinary)	Specify binary pattern
Lets you create your own writing pattern, up to 8 bits in length.

(P(M1 to 16))	Pattern multiplication
Selects how many consecutive pixels 1 to 16 to write each bit of pattern memory to. Power-up default is W(P(M2)) giving a pattern multiplication factor of 2. You can use this option:
- with the select standard pattern option,
- with the specify binary pattern option, or
- by itself, to define a multiplication factor for the last specified pattern.

VT340:   (I0 to 15)	Select foreground intensity (monochrome)
Selects the output map address (0 to 15) to use for writing. The Power-up default is VT340: W(I7)

(I(RGB)	Select foreground intensity (RGB color)
Selects the output map address to use for color writing with RGB values. Selects the color closest to the RGB value specified.

(I(HLS)	Select foreground intensity (HLS color)
Selects the output map address to use for color writing with HLS values. Selects the color closest to the HLS value specified.

VT340:  (F0 to 15)	Plane select
Selects which of the terminal's bitmap planes ReGIS can write to. Power-up default for VT340 is W(F15), writing enabled to all bitmap planes.

(V,R,C,orE)	Writing style
(V) for overlay writing (power-up default)
(R) for replace writing
(C) for complement writing
(E) for erase writing

(N0 or 1)	Negative pattern control
When set to (N1), reverses the effect of currently selected write pattern. Power-up default is W(N0), disabled.

(S0 or 1)	Shading on/off control
When set to (S1), turns on shading with currently selected pattern. The shading reference line is defined by the Y-coordinate of the active position when (S1) is selected. Power-up default is W(S0), off.

(S[,Y])	Select horizontal shading reference line
Selects a line defined by [,Y], which an be either an absolute or relative value.

(S(suboption)[X])	Select vertical shading reference line
Selects a line defined by [X], which can be either an absolute or relative value.

(S'character')	Select shading character
Selects a character to use for shading, instead of writing pattern.


ReGIS Position Command - P

Moves the graphics cursor without performing any writing.

[X,Y]	Cursor positioning with [X,Y] values
The [X,Y] values can be absolute, relative, or absolute/relative screen coordinates. If one of the values is omitted, it remains at its current value.

PV	Cursor positioning with PV values
The pixel vector values select a direction and distance to move, relative to the current cursor position.

(W(Mn))	PV multiplier
This temporary write control option selects a multiplication factor for PV values. This factor defines the number of coordinates to move for each PV value.

(B)	Begin a bounded position stack
Pushes the current active position onto the stack. This position becomes the active position again after a corresponding (E) option in the stack.

(S)	Start an unbounded position stack
Pushes a dummy position onto the stack. When ReGIS reaches an (E) option in the stack, the active position stays at its current location.

(E)	End of bounded or unbounded position stack
Selects the active position at the end of a position stack. The active position is based on the corresponding (B) option in a bounded stack or (S) option in an unbounded stack.

(Ppn)	Select graphics page option
Moves the cursor from one page to another in graphics page memory.


ReGIS Vector Command - V

Draws vectors (straight lines) between the screen locations you specify in the command.

[]	Draw dot
Draws one dot (a single pixel) at the current active position. Does not move the cursor.

[X,Y]	Draw line (with coordinate)
Draws a line from the current active position to the [X,Y] position. You can use absolute, relative, or absolute/relative values for [X,Y].

PV	Draw line (with PV value)
Draws a line from the current active position to a relative position defined by PV. The PV value defines a direction.

(B)	Begin a bounded position stack
Saves the current active position by pushing it on the stack. This is the starting point for a line.

(S)	Start an unbounded position stack
Saves a dummy position, by pushing it onto the stack.

(E)	End of bounded position stack
Draws a line to the position saved by the previous (B) option from the position specified before the (E) option. Then pops the saved position off the stack.

End of unbounded position stack
Ends a position stack started by an (S) option. No line is drawn, and the active position does not move.

(W(suboptions)	Temporary write control
Lets you use temporary write control values with one vector command. Temporary values only remain in effect for the selected command.


ReGIS Curve Command - C

Draws circles and arcs, using the screen locations you specify in the command.

All [X,Y] coordinates can be absolute, relative, or absolute/relative values.

[X,Y]	Circle with center at current position.
[X,Y] defines a point on the circumference of the circle.

(C)[X,Y]	Circle with center at specified position
[X,Y] defines the center of the circle. The current active position defines a point on the circumference.

(Adegrees)[X,Y]	Arc with center at current position
[X,Y] defines the starting point for an arc. degrees is a signed value that determines the size and direction of arc.
+ = counterclockwise
- = clockwise
Power-up default is 360 degrees counterclockwise

(AdegreesC)[X,Y]	Arc with center at specified position
[X,Y] defines the arc's center. The starting point for the arc is the current active position. degrees is a signed value that determines the size and direction of arc.
+ = counterclockwise
- = clockwise

(B)positions(E)	Closed curve sequence
Defines a closed curve based on [X,Y] positions specified in the sequence.

(S)positions(E)	Open curve sequence
Defines an open curve based on [X,Y] positions specified in the sequence.

(W(suboptions))	Temporary write control
Lets you use temporary write control values with one curve command. Temporary values only remain in effect for the selected command, but that command can include several curves.


ReGIS Text Command - T

Controls the display of text strings in graphics, and lets you display characters.

You can use characters from the terminal's built-in character sets, or you can design and load a set. All the built-in sets have 94 characters, except the ISO set. The ISO set has 96 characters. The following are Built-in character sets:

ASCII

ISO Latin Nr 1 supplemental graphic

DEC Supplemental Graphic

DEC Special Graphic

DEC Technical

National replacement character (NRC) sets (14 sets)

Control Characters in Text Strings

Carriage return	CR	Returns the cursor to the horizontal position where the current text writing command started.

Line feed	LF	Moves the cursor down one line in the same column.

Backspace	BS	Moves the cursor back one character position. You can use BS to overstrike a character.

Horizontal tab	HT	Moves the cursor forward one character position, using the current text spacing value.

Selecting a 7-Bit Character Set With the L or R Suboption

ASCII	(B

DEC Special Graphic	(0

DEC Technical	(

National Replacement Character Sets

British	(A

Dutch	(4

Finnish	(5

French	(R

French Canadian	(9

German	(K

Italian	(Y

Norwegian/Danish	('

Portuguese	(%6

Spanish	(Z

Swedish	(7

Swiss	(-

For example, the following command selects the DEC Technical set for use with ReGIS.

T(A0(L"("))

Selecting an 8-Bit Set with the R Suboption

DEC Supplemental Graphic	)%5

ISO Latin-1 Supplemental	-A

For example, the following command selects the DEC Supplemental Graphic set for use with ReGIS.

T(A0(R")%5"))

Standard Character Cell Sizes

Set Number	Display Cell Size	Unit Cell Size	Character Positioning

S0	[9,10]	[8,10]	[9,]

S1	[9,20]	[8,20]	[9,]

S2	[18,30]	[16,30]	[18,]

S3	[27,45]	[24,45]	[27,]

S4	[36,60]	[32,60]	[36,]

S5	[45,75]	[40,75]	[45,]

S6	[54,90]	[48,90]	[54,]

S7	[63,105]	[56,105]	[63,]

S8	[72,120]	[64,120]	[72,]

S9	[81,135]	[72,135]	[81,]

S10	[90,150]	[80,150]	[90,]

S11	[99,165]	[88,165]	[99,]

S12	[108,180]	[96,180]	[108,]

S13	[117,195]	[104,195]	[117,]

S14	[126,210]	[112,210]	[126,]

S15	[135,225]	[120,225]	[135,]

S16	[144,240]	[128,240]	[144,]

Note  The sizes in this table are expressed in screen coordinate values. These values are based on the default screen addressing for the VT300.

Commands

(A0 to 3)	Select character set
Selects one of four possible character sets (0 to 3) to use for text string characters.
(A0)  built-in set.
(A1to3) one of three loadable sets. Power-up default is T(A0) for ISO Latin Alphabet Nr 1 character set.

(A0(L"designator"))	Select character set (left)
Used with the (A0) option to select a built-in 7-bit set for the left side (GL) of the code table.
Default: "(B"  ASCII set.

(A0(R"designator"))	Select character set (right)
Used with the (A0) option to select a built-in 7-bit or 8-bit set for the right side (GR) of the code table.
Default: "-A"  ISO Latin-1 supplemental graphic set.

(S0 to 16)	Standard character cell size
Selects 1 of 17 standard sets. The set defines the display cell, unit cell, and character positioning values for text characters. Power-up default is T(S1) for Standard character cell size 1.

(S[width,height])	Display cell size
Lets you change the size of the screen area used for each character. Power-up default is T(S[9,20]) for Display cell size associated with standard character cell size 1.

[X,Y]	Character positioning
Lets you vary spacing between text characters. [X,Y] values are relative. Power-up default is T[+9,+0] for Character positioning associated with standard character cell size 1.

(U[width,height])	Unit cell size
Lets you change scale of characters. Power-up default is T(U[8,20]) for Unit cell size associated with standard character cell size 1.

(Hheight)	Height multiplier
Changes the height of the display cell and unit cell, without affecting the width or positioning values. New height is equal to 10 times the specified multiplier (1-25). Power-up default is T(H2) for Multiplication factor of 2.

(DaS0 to 16)	String tilt
Selects a tilt angle for text strings, relative to the current baseline.
a  Selects the degrees of the tilt. (45 degree increments)
0 to 16  Selects a standard size to use for positioning tilted characters. Power-up default is T(D0 S1 D0) for String and character tilt off.

(Ia)	Italics
Selects a tilt angle a for italic characters without changing their orientation to the current baseline. Angle is ± 22 or 45 degrees. Power-up default is T(I0) for Off.

(B)options(E)	Temporary text control
Selects temporary option values for one text command. Temporary values remain in effect until you use (E).

PV	PV spacing
Selects PV value to use for superscripts, subscripts, and overstriking.

(W(options))	Temporary write control
Selects temporary write control values for one text command.

(M[width,height])	Size multiplication
Selects a new unit cell size. Multiplies the height and width of the standard S1 unit cell by the factors you select. The maximum width factor is 16. Power-up default is T (M[1,2]) for Multiplication factor of 1 for width and 2 for height.


ReGIS Load Command - L

Defines and loads alternate characters you can display with the text command.

(A1 to 3)	Select character set
Selects one of three loadable character sets to use for any load commands that follow. Power-up default is L(A1), selecting character set 1.

(A"name")	Specify name
Selects a name of up to 10 characters for the currently selected loadable character set. You can use this option with the select character set option: (A1 to 3"name").

"ASCII"hex pairs	Load character cell
Loads a character into the currently selected loadable set.
ASCII is an ASCII character you use to select the loadable character in other commands.
hex pairs define the bit pattern for each line of the character.


Macrographs - @

Defines a command string as a macrograph. You use macrographs to store and recall other ReGIS command strings.

@call letter	Invoke macrograph
Inserts the contents of the macrograph specified by call letter into the ReGIS command string. The call letter is not case sensitive.

@:call letter  definition@;	Define macrograph
Defines a macrograph and selects call letter to identify the macrograph. The call letter is not case sensitive.

@.	Clear all macrographs
Deletes all macrograph definitions.

@:call letter@;	Clear defined macrograph
Deletes the macrograph identified by call letter.


ReGIS Report Command - R

Reports information such as the active position and error codes.

You can use report commands to perform two basic functions.
-  Request the current status of ReGIS operations.
-  Enter graphics input mode (to use a mouse or graphics tablet).

(P)	Cursor position
Reports the current active output position.

(M(call letter))	Macrograph contents
Reports the contents of the macrograph identified by call letter.

(M(=))	Macrograph storage status
Reports how much space the terminal has assigned to macrograph storage, and how much of that space is currently free.

(L)	Character set
Reports which character set (1 to 3) is selected for loading.

(E)	Error
Reports the last error found by the parser since resynchronization.

(In)	Graphics input modes
Selects one-shot mode (0) or multiple mode (1). Power-up default is 0.

(P(I))	Report position interactive
Requests an input cursor position report.


ReGIS Polygon Fill Command - F

Fills in a single closed figure, such as a circle or square.

F(Vpositions)	Vector option positions are the positions of the polygon's vertices.

F(Cpositions)	Curve option positions are coordinate values for a curve or circle.

F(C(A+ degrees)position1Pposition2...)
Position option (with curve option) C identifies a curve option.
A identifies an arc suboption.
degrees are the number of degrees and the direction to draw the arc in.
position1 is the arc's starting point.
P identifies a position option.
position2 is the new active position.

F(W(suboptions)options)	Temporary Write Control as an Option of the F Command
suboptions are the temporary write control values to use.
options are polygon fill command options that will use the temporary write control values.

F(C(W(sub-suboptions)suboptions)options)
Temporary Write Control as a Suboption of the C or V Options
C identifies a curve option. You could also use a vector (V) option.
W identifies a temporary write control suboption.
sub-suboptions are the temporary write control values to use.
suboptions are the curve options and values that will use the temporary write control values.
options are any other polygon fill command options.


ReGIS Resynchronization Command -  ;

Resynchronizes the flow of ReGIS command strings to the beginning of a new command.

ReGIS recognizes a semicolon (;) as a command to resynchronize. If you think errors are occurring in your program, you can use the semicolon between command strings to return to the command level.


ReGIS Command Summary

Letter	ReGIS Command	Description

S	Screen	Provides screen controls such as erasing the screen.

W	Write	Provides writing controls such as writing shades.

P	Position	Moves the graphics cursor without performing any writing.

V	Vector	Draws vectors (straight lines) between the screen locations you specify in the command.

C	Curve	Draws circles and arcs using the screen locations you specify in the command.

T	Text	Controls the display of text strings in graphics and lets you specify characters to display.

L	Load	Defines and loads alternate characters you can display with the text command.

@	Macrograph	Defines a command string as a macrograph. You use macrographs to store and recall other ReGIS command strings.

R	Report	Reports information such as the active position and error codes.

F	Polygon Fill	Fills in a single closed figure, such as a circle or square.

;	Resynchronization	Resynchronizes the flow of ReGIS command strings to the beginning of a new command.


Entering and Exiting ReGIS

You use device control strings to enter and exit ReGIS.

Note  You can enter ReGIS from VT100 or VT300 mode.

8-Bit DCS String	7-Bit Equivalent 	Meaning

DCS p or DCS 0p	ESC Pp or ESC P0p	Enters ReGIS at the point where ReGIS was last exited. Does not display commands.

DCS 1p	ESC P1p	Enters ReGIS at the command level. ReGIS begins at a new command. Does not display commands.

DCS 2P	ESC P2p	Enters ReGIS at the point where ReGIS was last exited. Displays commands on the screen's bottom line (command display mode).

DCS 3p	ESC P3p	Enters ReGIS at the command level. ReGIS begins at a new command. Displays commands on the screen's bottom line (command display mode).

ST	ESC\	Exits ReGIS mode.


Sixel Data Format
Sixel Graphics

Sixel Data Format

Use the following device control string to send sixel data.

DCS P1; P2; P3; q s...s ST

where

DCS is a C1 control character that introduces the sixel data sequence. You can also express DCS as the 7-bit escape sequence ESC P for a 7-bit environment.

P1 is the macro parameter. This parameter indicates the pixel aspect ratio used by the application or terminal. The pixel aspect ratio defines the shape of the pixel dots the terminal uses to draw images. For example, a pixel that is twice as high as it is wide has an aspect ratio of 2:1.

Note  The macro parameter is provided for compatibility with existing Digital software. New applications should use the set raster attributes control.

P1	Pixel Aspect Ratio (Vertical:Horizontal)

Omitted	2:1 (default)

0 or 1	2:1

2	5:1

3 or 4	3:1

5 or 6	2:1

7, 8, or 9	1:1

You can override the setting of the macro parameter by using the set raster attributes character (",2/2) in a sixel data string. See below.

;	is a semicolon (3/11). This character separates numeric parameters in a DCS string.

P2	selects how the terminal draws the background color. You can use one of three values.

P2	Meaning

0 or 2 (default)	Pixel positions specified as 0 are set to the current background color.

1	Pixel positions specified as 0 remain at their current color.

P3	is the horizontal grid size parameter. The horizontal grid size is the horizontal distance between two pixel dots. The VT300 ignores this parameter because the horizontal grid size is fixed at 0.0195 cm (0.0075 in).

q  	indicates that this device control string is a sixel command.

s...s	is the sixel encoded data string. The sixel data characters are characters in the range of ? (hex 3F) to ~ (hex 7E). Each sixel data character represents six vertical pixels of data. Each sixel data character represents a binary value equal to the character code value minus hex 3F.

Examples:

?	(hex 3F) represents the binary value 000000.

t 	(hex 74) represents binary value 110101.

~ 	(hex 7E) represents binary value 111111.

The terminal translates the six bits to a sixel (six pixels in a vertical column). The least significant bit is at the top.

You can also use sixel control functions in the data string. The next section describes these characters and their functions.

ST is the string terminator. ST is a C1 control character. You can also express ST as the 7-bit escape sequence ESC \ for a 7-bit environment.

Sixel Control Functions

Graphics Repeat Introducer (!)

The ! (2/1) character lets you repeat a graphic character.

! Pn character

where

Pn is the repeat count (any decimal value).

character is the character to repeat. You can use any character in the range of ? (hex 3F) to ~ (hex 7E).

Raster Attributes (")

This command selects the raster attributes for the following sixel data string. This command must precede any sixel data, and overrides any raster attributes set by the macro parameter described above.

" Pan; Pad; Ph; Pv

where

Pan and Pad are the pixel aspect ratio. Pan defines the vertical shape of the pixel. Pad defines the horizontal shape of the pixel. If you use the set raster attributes command (") in a sixel data string, you must specify a pixel aspect ratio. You can only use integer values for Pan and Pad. The VT300 rounds the pixel aspect ratio to nearest integer.

Ph and Pv define the horizontal and vertical size of the image (in pixels), respectively.

Note  The VT300 uses Ph and Pv to erase the background when P2 = 0 or 2. See the "Sixel Data Format" section.

Ph and Pv do not limit the size of the image defined by the sixel data. However, Ph and Pv let you omit background sixel data from the image definition and still have a color background. They also provide a concise way for the application or terminal to encode the size of an image.

Color Introducer (#)

This command lets you select colors in two ways.,

Select a color map entry by number.

# Pc

where

Pc is the color number 0 to 255.

Select HLS or RGB colors

# Pc; Pu; Px; Py; Pz

where

Pc is the color number to define, 0 to 255.

Pu is the color coordinate system (1=HLS or2=RGB).

Px, Py, and Pz are the color coordinates in the specified system.

If HLS,

Px	0 to 360 degrees	Hue angle

Py	0 to 100 percent	Lightness

Pz	0 to 100 percent	Saturation

If RGB,

Px	0 to 100 percent	Red intensity

Py	0 to 100 percent	Green intensity

Pz	0 to 100 percent	Blue intensity

Graphics Carriage Return ($)

The $ (2/4) character indicates the end of the sixel line. The active position returns to the left margin of the same sixel line. You can use this character to overprint lines.

Graphics New Line (-)

The - (2/13) character indicates the end of a sixel line. The active position moves to the left margin of the next sixel line.

Parameter Separator (;)

The ; (3/11) character separates numeric parameters in a device control string. If there is no number before the separator, the terminal assumes that parameter is 0. If there is a number after the separator, the terminal assumes that parameter is 0.

Sixel Display Mode

Set: CSI ? 8 0 h

Enables the Sixel Scrolling feature in the Graphics dialog box. Sixel drawing begins at the text active position and can scroll.

Reset: CSI ? 8 0 l

Disables the Sixel Scrolling feature in the Graphics dialog box. Sixel drawing begins at the home position and does not scroll. The text active position is not affected.


Definition of PRODNAME bookmark:KEA! for Windows 95

Definition of SHORTNAME bookmark:KEA!

Definition of EDITNAME bookmark:KEA! Edit


Control Characters in 401x Mode

BEL	Alpha: Ring the bell.

Graphics: If dark vector condition is in effect, it is cleared; else ring the bell.

GIN mode: Ring the bell.

BS	Alpha: Move the cursor one space to the left; if this moves the cursor past the left margin, the cursor is moved to the right margin on the same line. If the option BS Effect in the Graphics dialog box is set to BS-Delete, receiving a BS code also erases the character in the final cursor position.

Graphics: Move the drawing position to the left 56 tekpoints; wrap to the right edge if this moves it off the left edge.

HT	Alpha: Move the cursor one space to the right; if this would move the cursor past the right margin, do CR and LF.

Graphics: Move the drawing position to the right 56 tekpoints; wrap to the left edge if it would move off the right edge.

VT	Alpha: Move the cursor up one line; the cursor is not moved if at the top margin.

Graphics: Move the drawing position up 88 tekpoints; wrap to the bottom edge if this puts it off the top.

FS	Enter Point Plot Mode.

GS	Enter Graph Mode, set the dark vector condition. (If already in graph mode, set the dark vector condition.)

RS	Enter Incremental Plot Mode.

US	Enter Alpha Mode. The Alpha Mode cursor is positioned at the last beam drawing position.

For many control characters, ESC plus that character has the same function as that character alone.


Escape Sequences in 401x Mode

ESC ENQ	Alpha: Set bypass condition; return terminal status and address of the lower left hand corner of the cursor.

Graphics and GIN: Set bypass condition; return terminal status and address of the beam position.

The first byte transmitted to the host in response to an ESC ENQ terminal status request is a status byte with the following format:

Bit 8	= 0
Bit 7	= 0
Bit 6	= 1
Bit 5	= 0 Hardcopy Device has been selected.
= 1 No Hardcopy Device selected.
Bit 4	= 0 Alpha Mode or GIN Mode.
= 1 Graphics Mode.
Bit 3	= 0 Graphics Mode.
= 1 in Alpha Mode or GIN Mode.
Bit 2	= 0 Margin 1 is active.
= 1 Margin 2 is active.
Bit 1	= 1
The address is sent in the same format as GIN.

ESC BEL	Same as BEL.

ESC BS	Same as BS.

ESC HT	Same as HT.

ESC LF	Set LCE flag, ignore further LFs until a no-op control code is received (e.g. BEL).

ESC VT	Same as VT.

ESC FF	Enter Alpha Mode, erase the screen, position the cursor at the upper left hand corner, clear the bypass 	condition, set Margin 1.

ESC CR	Set LCE flag, ignore further CRs until a no-op control code is received (e.g. BEL).

ESC ETB	Make a hardcopy, clear bypass.

ESC CAN	Set the bypass condition.

ESC SUB	Enter GIN Mode, and set the bypass condition.

ESC FS	Enter Point Plot Mode.

ESC GS	Same as GS.

ESC RS	Same as RS.

ESC US	Same as US.

ESC / 0 d	Raster writing feature: set dots on (normal). (VT340 extension)

ESC / 1 d	Raster writing feature: set dots off (erase). This feature can be used in alpha and graph modes to replace the unsupported Tektronix write-through feature. (VT340 extension)

ESC / 2 d	Raster writing feature: complement dots. (VT340 extension)

ESC ?	Interpreted as if DEL was received. This is useful if the option DEL Effect in the Graphics dialog box is set to Ignored.


Tektronix Vector Character Size

ESC 8	Select character size: 56 (x) by 88 (y) tekpoints.

ESC 9	Select character size: 51 (x) by 82 (y) tekpoints.

ESC : 	Select character size: 34 (x) by 53 (y) tekpoints.

ESC ; 	Select character size: 31 (x) by 48 (y) tekpoints.

ESC <	Select character size: 51 (x) by 127 (y) tekpoints. (KEA! extension.)

ESC =	Select character size: 25 (x) by 53 (y) tekpoints. (KEA! extension.)

ESC 0	Select character size: 51 (x) by 90 (y) tekpoints. (KEA! extension.)

ESC 1	Select character size: 103 (x) by 180 (y) tekpoints. (KEA! extension.)

ESC 2	Select character size: 158 (x) by 270 (y) tekpoints. (KEA! extension.)

ESC 3	Select character size: 205 (x) by 360 (y) tekpoints. (KEA! extension.)

Bitmapped characters have only two sizes: large (60 by 133) and small (33 by 60).


Tektronix ASCII or APL

ESC SO	Select APL character set. The value of Character Set in the Graphics dialog box must be Prog. (Not supported by a real VT340.)

ESC SI	Select ASCII character set. The value of Character Set in the Graphics dialog box must be Prog.


Tektronix Color Index Escape Sequences

KEA! supports the 4105 color index control sequences.

ESC M L n  (or ESC M T n )

n	Color

00	black

01	bold white

02	bold red

03	bold green

04	bold blue

05	bold cyan

06	bold magenta

07	bold yellow

08	yellow

09	green

10	cyan

11	blue

12	magenta

13	red

14	gray

15	white


Tektronix Line Style

KEA! maps these line styles to the closest available Windows styles. Short dash and Long dash are mapped to dash, Long/short dash is mapped to Dash-dot.

ESC M V 0	Solid line style. (4105)

ESC M V 1	Dotted line style.(4105)

ESC M V 2	Dot-dash line style.(4105)

ESC M V 3	Short dash line style. (4105)

ESC M V 4	Long dash line style. (4105)

ESC M V 5	Dot-dot-dash line style. (4105)

ESC M V 6	Long/short dash line style. (4105)

ESC M V 7	Medium dash line style. (4105)

ESC ` 	Solid line style. (4014)

ESC a 	Dotted line style.(4014)

ESC b 	Dot-dash line style.(4014)

ESC c 	Short dash line style. (4014)

ESC d 	Long dash line style. (4014)

ESC e 	Dot-dot-dash line style. (4014) (VT340 does solid)

ESC f 	Long/short dash line style. (4014) (VT340 does solid)

ESC g 	Medium dash line style. (4014) (VT340 does solid)

ESC h 	Bold Solid line style.

ESC i 	Bold Dotted line style.

ESC j 	Bold Dot-dash line style.

ESC k 	Bold Short dash line style.

ESC l 	Bold Long dash line style.

ESC m 	Bold Dot-dot-dash line style.

ESC n 	Bold Long/short dash line style.

ESC o 	Bold Medium dash line style.

You can additionally map the line styles to Windows colors.


Tektronix Mode and ANSI Mode

CSI ? 38 h	Enter Tektronix mode (VT340)

CSI ? 38 l	Exit Tektronix mode (VT340)

In Tektronix mode, there are several display modes:

Alpha Mode

Graph Mode

Point Plot Mode

Incremental Plot Mode

GIN Mode


Tektronix Alpha Mode

In Alpha Mode, characters are displayed. Alpha Mode is used when communicating with the host, and for labeling graphics images. Alpha mode is entered when the code US, ESC US, or CR is received.

There are several character sizes. Because of limited display resolution, the smaller character sizes may be unreadable. However, even the smallest characters are readable when you zoom, or when the image is plotted on a high-resolution hardcopy device and the Display List option has been selected. Two different character sets are available: ASCII and APL.

There are two Alpha Mode margins, Margin 1 and Margin 2. Margin 1 is at the left edge of the screen, Margin 2 is in the middle of the screen. The cursor returns to the current margin when a CR is performed, or if the cursor moves off the right margin. After a Page Clear or Reset function, Margin 1 becomes the current margin. Linefeeds past the last line while Margin 1 is the current margin will make Margin 2 the current margin. Similarly, Linefeeds past the last line while Margin 2 is the current margin will make Margin 1 the current margin. This allows twice as many lines of information to be displayed before the screen is filled. In addition to the above, Margin 1 is made active by:

pressing the Page key NEXT SCRN or the Reset key SHIFT + NEXT SCRN;

receiving ESC FF;

executing a Graph Mode vector;

sending the GIN Mode cursor position to the host.

The 4014, unlike most text terminals, does not scroll the screen when the cursor is moved off the bottom line. When the page is full and Margin Control is set to 1 or 2, you must press the Page key NEXT SCRN to clear the screen and return the cursor to the upper left corner.

LF	Move the cursor down one line. If this would move the cursor past the bottom margin, the current margin is adjusted and the cursor is moved to the top of the new current margin. The cursor maintains the same horizontal position with respect to the new margin as it had with respect to the old. If the option LF Effect in the Graphics dialog box is set to LF/CR, a carriage return is also executed.
CR	Move the cursor to the current margin: the left edge of the display if Margin 1, the center of the display if Margin 2. If the option CR Effect in the Graphics dialog box is set to CR/LF, a linefeed is also executed.
SP	Move the cursor one space to the right. If this would move the cursor past the right margin, a carriage return and a linefeed are executed.
! to ~	Display the printing character then move one space right. If this would move the cursor past the right margin, a carriage return and a linefeed are executed.


Tektronix Graph Mode

Graph Mode is used to draw vectors by giving the absolute coordinates of their endpoints. Graph Mode is entered when the code GS or ESC GS is received in Alpha mode. The first vector after entering Graph Mode is unwritten; it is stored as a dark vector. If you want the first vector to appear, send a BEL character before any coordinates.

Vectors can be drawn in eight different styles. KEA! supports both the 4014 and 4105 escape sequences.

The defocused and write-through attributes are simulated with bold.

KEA! creates images on a 4160 x 3200 plane. The addressable range of this displayed plane is 0 - 4095 x and 0 - 4095 y. Each point on the plane is called a tekpoint. Some extra space is allowed for characters which overhang the edge.

Several of the graphics modes must manipulate coordinates describing the position of points or endpoints. Each coordinate consists of a 12bit x value and a 12bit y value used to represent a number in the range of 0 - 4095. The tekpoint in the lower left hand corner has the address 0,0.

Each xy coordinate pair is encoded as five ASCII characters. These five characters, in the order they are transmitted, are called: High-Y, Extra, Low-Y, High-X and Low-X. If the coordinates in binary are xxxxx xxxxx xx and yyyyy yyyyy yy where 'x' and 'y' represent single bits of the 12bit addresses, then:

High-Y	Contains the five most significant bits of y coordinate. The high order two bits of the High-Y byte are set to 01. The complete byte has the format 01yyyyy.

Extra	Contains the two low order bits of the x and the y coordinates. The high order three bits are set to 110; the next two bits contain the low order two bits of the y coordinate; the final two bits contain the low order two bits of the x coordinate. The complete byte has the format 110yyxx.

Low-Y	Contains the five intermediate bits of the y coordinate. The high order two bits of Low-Y are set to 11. The complete byte has the format 11yyyyy.

On some computer systems, the ASCII DEL character (7F hex) is used for padding. Since the Low-Y byte may take on the 7F value as part of a coordinate specification, a conflict can arise; DELs intended as padding may be interpreted as coordinates. You can set the option DEL Effect in the Graphics dialog box to either Ignored or Low-Y. If Ignored is selected, all received DEL characters are treated as pads and ignored. (If the coordinate value 7F hex is required, the special sequence ESC ? must be sent instead.) Low-Y is the default; received DEL characters are interpreted as the Low-Y address 7F.

High-X	Contains the five most significant bits of the x coordinate. The high order two bits of the High-X byte are set to 01. The complete byte has the format 01xxxxx.

Low-X	Contains the five intermediate bits of the x coordinate. The high order two bits of Low-X are set to 10. The complete byte has the format 10xxxxx.

The extra byte may be omitted if only 10 bits of precision are required. Programs intended for an unenhanced 4010 terminal will therefore still work with KEA!.

The terminal always remembers the last coordinate sent. Subsequent coordinate transmissions may omit sending bytes whose values have not changed, subject to the following rules:

The Low-X byte must always be sent.

If the Extra byte is sent, then the Low-Y byte must also be sent.

If the High-X byte is sent, then the Low-Y byte must also be sent.

The last coordinate is remembered even if the terminal is switched into a different mode.

LF	The beam drawing position is moved down by one character space. The distance depends on characters size. The position will wrap to the top edge of the screen if LF would move it off the bottom edge. A carriage return is also done if that option is selected.
CR	Enter Alpha Mode. The lower left edge of the cursor is positioned at the y beam coordinate and current margin.
SPACE to !	All codes in this range correspond to a HighX or a HighY address.
@ to _	All codes in this range correspond to a LowX address.
` to ~	All codes in this range correspond to a LowY or Extra byte address.
DEL	The DEL code is interpreted as LowY if option DEL Effect in the Graphics dialog box is set to Low-Y. DEL is ignored if the option is set to Ignored.


Tektronix Point Plot Mode

Point Plot Mode is identical to Graph Mode except that lines are not drawn. Instead, only the end points are displayed. Dark vector is set upon entry to Point Plot Mode. Point Plot mode is entered when the code FS is received.


Tektronix Incremental Plot Mode

Incremental Plot Mode emulates a plotter by responding to pen up, pen down, and direction motion commands. Each motion command moves one tekpoint in the given direction. Incremental Plot mode is entered when the code RS or ESC RS is received.

CR	Alpha Mode is entered, the lower left hand coordinate of the cursor is positioned at the y beam coordinate and current margin.
SPACE	Turn the beam off. The current position can be moved but the motion is not displayed on the screen until a beam on is received.
P	Turn the beam on. Once the beam is on, subsequent moves cause visible vectors.
D	Move one tekpoint up.
E	Move one tekpoint up and right.
A	Move one tekpoint right.
I	Move one tekpoint down and right.
H	Move one tekpoint down.
J	Move one tekpoint down and left.
B	Move one tekpoint left.
F	Move one tekpoint up and left.


Tektronix GIN Mode

In GIN (Graphics INput) Mode you can interactively use the keyboard or mouse to move the crosshair cursor and send position information to the host. GIN Mode is entered when the code ESC SUB is received in any mode. Move the cursor to the desired location. To exit GIN mode, press a mouse button or press a key that transmits a character. This sends the optional character, a cursor position report, and optional terminator. Alpha Mode is entered, and the bypass condition remains in effect.

A cursor position report is four bytes long and does not include the extra byte which is usually part of an address. The position report consists of a HighX byte , a LowX byte , a HighY byte and a LowY byte . Each byte contains five bits. The position report is always in the range of 0 - 1023. The option GIN Terminator in the Graphics dialog box controls the characters sent to terminate the position report. If GIN Terminator is set to CREOT, the codes CR and EOT are sent following a position report. If set to CR, only a CR is sent. If set to None, no terminating characters are sent.


Definition of PRODNAME bookmark:KEA! for Windows 95

Definition of SHORTNAME bookmark:KEA!

Definition of EDITNAME bookmark:KEA! Edit