User-Defined Macros in AnzioWin

Introduction

It is possible through AnzioWin for the user to define macros, or small scripts, to run Anzio functions and commands. Anzio Lite does not support the capability to create and edit macros, however many user-defined macros will work with Anzio Lite by simply using the saved key file. A macro within AnzioWin is associated with a key and stored in the Keys, "kys", file where keyboard mappings are stored.

There are two basic types of macros, those associated with a special key, and those associated with a number or letter from the keyboard.

Keys representing special keyboard keys, i.e. F1, F12, End, Home, are executed by simply pressing that key. (these override the regular keyboard definition for that key, so be careful here).

Macros associated with a number or letter are defined the same, but are executed from the "Transmit Key: " line of Anzio, called up by pressing Alt-F1, Ctrl-F1 or Shift-F1. Note: Depending on terminal types, all iterations of F1 may be defined. In this case, you can still run the macro by doing a Ctrl-Shift-f and going to the Function line. At the Function line, enter invoke

Creating a macro is done through the "define" command given to Anzio on the Function line (ctrl-shift-f).

Anzio 'keys' files

The Anzio keys files have the extension ".kys" and contain all key definitions for the particular terminal type you are working with. This includes user-defined macros.

Reviewing the current 'keys' file

Depending on the setting in the default parameters file, a key file will be loaded at start up. By going under the File menu and doing a  Read Keys  command, you can load a different keys file in to memory. You can review the current defined keys file by doing:

Defining the key

To define a key do the   Ctrl-Shift-f   followed by the "define" command and it's definition. As an example, if we want to set up a macro called "L" to do a login and password, do the following:

In the above example, you would press the F6 key from the keyboard prior to giving Anzio a command. Anything else typed goes direct to the host. There are some exceptions to this which needs to be prefaced or substituted for (see notes below).Another trick to redefining a key that is already defined is to enter a question mark after the special key. This will retrieve the current key definition for you to change:

Special key handling

Within the Anzio and the Windows environment, certain keystrokes are either intercepted by Windows or by AnzioWin. These keystrokes must either be prefaced by a special character sequence or substituted for.The special character sequence Anzio uses to preface these special keys is a Ctrl-P. As an example, when you need to enter an escape, do a  Ctrl-P followed by the ESC key. Another important keystroke that must be substituted for is the carriage return. Enter a vertical bar, "|" for a "Enter" to be part of your macro.

A complete list of special characters and commands are listed below:

The pipe character, "|", represents a carriage return within the macro.

An F6 within a defined key indicates that the following strings (up to the pipe character, "|") are commands for Anzio, not for the host.

You can issue text to the screen without it going to the host. This is done by brackets around the text, i.e. "{hi there}" within a macro would display this text on the screen, but not send it through to the host.

You can enter hex characters in the macro by holding down the ALT key and using the numeric keypad, enter the 3 digit hex code, i.e. to enter hex 132, hold ALT and press 132 on the numeric keypad.

To enter special keyboard keys, such as HOME, press that key and you should see the interpretation of the key in reverse video on the Function line. If not, see the next item.

To enter other key sequences that already have meaning in the define process or to Windows, first press Ctrl-P then the key sequence. As an example, to enter an escape, press Ctrl-P followed by ESC.

Keys can be "blocked" out (their keymap cleared) by defining them as follows define CTRL-C {}

To wait for user intervention, use the # key, i.e. define S f6OPENI #|f6TRANSMIT|

Other macros can be embedded within a macro by entering CALL or INVOKE. CALL returns control to the macro once the called macro is complete, while INVOKE transfers control to the next macro and terminate the current one.

To include one of the special characters used by macros as part of your normal text, precede it by a ~. As an example to send a "{" do define a ~{a}

To edit an already defined key, on the Function: line, enter the key followed by a question mark and the current definition will be shown, i.e. define L?

To see all keys defined, go to the Function: line and enter keys

 

As with all macros in any program, a little experimentation and testing is necessary.

We strongly recommend that you know your terminal emulation type and avoid re-defining keys that are already defined by the terminal type. Also avoid defining ALT-F, ALT-M, ALT-A and ALT-X. as they are used by the Anzio program.

Available commands for macros

While the commands are getting too numerous to list here, they are listed in the AnzioWin manual. This is available in printed form from RSI, or can be downloaded from our download area.

There are some special cases that should be covered here however.

Non-ASCII characters

Defined keys can contain any Unicode character, including combining diacritics, Cyrillic, Chinese, etc.  These will be encoded properly, according to the host's Character Set, when they are transmitted to the host.  Characters can be pasted in from the clipboard, or can by entered using the numeric pad. Since the days of DOS, it has been possible to enter non-ASCII characters using the Alt key and the numeric pad (NOT the numbers at the top of the alpha keyboard). For instance, alt-144 enters an E-acute (on a US Windows system). This number is taken from the "DOS" or "OEM" character set.

For a character from the Windows ("ANSI" or "ISO") set, precede the number with a zero, such as Alt-0255 for a y-umlaut.

In Anzio, you can also enter any Unicode character by its decimal value. For instance, a Y-tilde has a Unicode value of hex 1EF8, which is decimal 7928. So you can do Alt-7928 to enter this character.

File and screen selection functions

Anzio provides two selection functions for use inside a defined key,

DIR/S	Displays a directory browsing dialog for the user to select a file. Normally, DIR/S sends its result to the host (indicated by "/S"), but inside a defined key, the result is passed back as user input.
MENUBAR	Sets up a selection grid on the screen, with one or more columns.  The user selects a grid location, and the characters on the screen at those positions are passed back as user input. For example, if the host has displayed a list of file names, or a table of data, MENUBAR lets the user select an entry right off the screen.

 

 

DIR/S example               

DEFINE O OPENI f6DIR/S *.DAT|#||f6TRANSMIT |

In this case, the filename OPENI is expecting comes from the DIR/S command.  DIR/S presents a directory of all files matching "*.DAT".  When you select a file, DIR/S returns the name to OPENI.  Next, TRANSMIT sends the opened file.

Note the characters after the DIR/S command:  The first vertical bar is the end of the DIR/S command, and the # tells Anzio to wait for operator input.  The second vertical bar is the end of the # command, and the last vertical bar is the end of the OPENI command.

MENUBAR example

 that the host has displayed a list of filenames on the screen, and you want to receive one of these files.  If you know that the host will display the filenames in columns 1-13, you can call MENUBAR in your key definition:

DEFINE K f6KRECEIVE f6MENUBAR 1 13 1 23 0 0 1 13|#||

The KRECEIVE command's input filename comes from the MENUBAR function.  The numbers are 1 13 for the start and end column, 1 23 for the start and end lines, 0 0 for no second column, and 1 13 for the start and end returned character offsets.

Note the characters after the MENUBAR command:  the first vertical bar is the end of the MENUBAR command, and the # tells Anzio to wait for operator input.   The second vertical bar is the end of the # command, and the last vertical bar is the end of the KRECEIVE command.

OnError macro

You may need to have some error handling in your macro processing. For instance, if Anzio is running a macro that opens an input file, but that file does not exist, you may want Anzio to handle that cleanly. For this purpose there is the ONERROR macro.

You define this macro with the DEFINE command, as with any other macro. Let's assume it's the "E" macro. Then use the ONERROR command to designate it as the ONERROR macro:

ONERROR E

Of course, this command could be part of another macro. Now start your main macro.  At any point that a command fails, ALL nested executing macros will be terminated, and the "E" macro will be invoked.  The ONERROR macro remains in effect until it is cancelled or replaced.

Some examples of commands that can trigger ONERROR:

WAITFOR (with timeout)        Times out MKDIR Illegal directory name CD Directory not found LAUNCH                          Can't start program Various OPENs   File not found, etc. COPY File not found RENAME File not found, target exist     Code activated switch macros Anzio's passthrough print can be configured so that receipt of certain control codes, in the print data stream, triggers certain actions.  More specifically, a particular control character would trigger a particular macro, which might flush a print job, switch to a different printer, and begin printing again on the new printer. A range of 6 macros is associated with 6 control characters, control-A through control-F.  The PRINTMACRO command specifies what the first of these 6 macros is; that is, which one is associated with control-A. For instance, if you did: PRINTMACRO a then receipt of a control-A would trigger the "a" macro, control-B would trigger the "b" macro, etc., up to "f". When Anzio's passthrough print routine detects a triggering control character, it quits from passthrough print and then CALLs the appropriate macro. Nesting defined keys INVOKE X starts defined key X, abandoning the original defined key.  When X is done, control returns to the keyboard. Handling the 'keys' files For each terminal type that Anzio supports, there is a pre-defined set of keyboard mappings. AnzioWin can redefine these keys and add others to them through the "define" function addressed above. However, it is important to remember that until this key file is saved, the key definitions are only stored in memory. Under the File menu are the Save Keys and Read Keys menu items which allow you to read into memory and save to disk certain keymap files. Care should be taken with the Save Keys in the file name chosen, to not write over another key file.The key file name is saved in the defaults file so that the next time you call up a particular session of Anzio, it will retrieve the same key file.All key files are usable by AnzioWin. Anzio Lite can also handle most all key files with the exception of some user-defined macros where a command may not be available to the Lite version. In AnzioWin there is also the added feature that allows a user to merge another key file on top of the current key file. If keys are defined that are being merged in, they will overwrite what was already present in memory, so again, care should be taken. Keys file memory model within Anzio There is one additional item to discuss here. Anzio temporarily stores the keys file in memory whenever a key file is read. However, there are a couple of things that can influence the keys file that you need to be aware of, such as programmable keys being loaded from the host, or user key remappings, or read/merge of keys. The example below demonstrates the sequence of events that can occur: At startup, Anzio loads its default keys file. The user gets logged into their host. The user redefines the F1 key. This overwrite the F1 definition in memory. The user does a Merge with another key file. If this file contains an F1 definition, it overwrite what is in memory again. The user runs a host application that downloads programmable keys. If an F1 is included in this download, it overwrites the F1 definition in memory yet again. And it can go on and on. It is important to know what influences what where keyboard definitions are involved in case something goes wrong along the way.