## KEDIT Macros: How to Query, Define and Run Them

Built into KEDIT is a powerful macro facility that you can use to customize KEDIT's behavior and to automate repetitive editing tasks. This article focuses on the KEDIT commands you can use to control the macro facility: commands that display existing macro definitions, modify or create macro definitions, and execute macros within KEDIT.

The details of KEDIT's macro language, KEXX, are not discussed in this article. For an overview of KEXX, see KEDIT for Windows User's Guide Chapter 10, "Using Macros".

### Macros are either on-disk or in-memory

Macros referred to as in-memory macros are held in memory by KEDIT. In-memory macros are placed into memory using the DEFINE command, which is discussed in the "Defining in-memory macros" section of this article. When KEDIT needs to run a macro, KEDIT first checks to see if it is an in-memory macro. If the specified macro is not in memory, KEDIT looks for an on-disk macro according to the search process described in the "Running a macro" section of this article. An on-disk macro is a macro whose contents are stored on disk in a .KEX file.

In-memory macros execute more quickly than on-disk macros, but occupy memory for the duration of your KEDIT session. Because on-disk macros have to be reloaded into memory each time you use them, they take longer to execute, but will only occupy memory while they run.

Some in-memory macros are bound to keys. This means that the name of the macro is the same as the name of a key, and when the key is hit the macro runs. So, for example, when you press the F1 key KEDIT automatically runs the F1 macro, which in turn causes KEDIT's Help file to be displayed. When you first use KEDIT you are using these default in-memory macros. These macro assignments include default settings for the function keys, Alt, Ctrl, and Shift key combinations, and all the other keys on the keyboard.

Other special in-memory macros are invoked when you make a menu selection, or use the mouse. For example, when you select the File Open menu item, KEDIT runs the MENU_FILE_OPEN macro, which in turn issues a command that causes the File Open dialog box to be displayed. The naming conventions used for all of these special in-memory macros are discussed in KEDIT for Windows Reference Manual Chapter 7, "Built-In Macro Handling". Copies of all of KEDIT's default macro definitions included in the file BUILTIN.KML, which is installed in KEDIT's SAMPLES directory by the KEDIT Setup program.

### Querying in-memory macro definitions

There are several ways to find out the current definition of an in-memory macro within KEDIT. You can issue a QUERY from the KEDIT command line, as in the following example:

```      QUERY MACRO F1
```

which returns the current macro definition assigned to the F1 key by placing the code for the definition in the message area of your screen.

An alternative to QUERY MACRO, the following form of the DEFINE command also returns a definition in the message area:

```      DEFINE F1
```

If you want to query several macros, or if the definition displayed from a query extends beyond the viewable area on the message line, the MACROS command can be used. Issuing the MACROS command with no operands, or entering MACROS ALL, will place the definitions of most in-memory macros into a file called MACROS.KML ("uninteresting" macro assignments, such as 'text a' for the letter 'a', are not included).

If you don't want to see all the in-memory macros, you can issue the MACROS command with a list of the specific macros you want to see, for example:

```      MACROS F1 F6 F11 ALT-G CTRL-F SPLITEM
```

or just

```      MACROS F1
```

and the MACROS.KML file will contain only those macros listed.

Enter MACROS CHANGED if you just want to see the macros that you have defined during your KEDIT session and not the default definitions built into KEDIT.

The MACROS.KML file exists only in memory, but you can modify it and save it to disk using the SAVE or FILE commands. Note, however, that each time you issue the MACROS command in any form a new MACROS.KML file is created, replacing any existing in-memory MACROS.KML file.

### Defining in-memory macros

There are three ways to define in-memory macros.

You can enter a one line macro definition on the KEDIT command line using the DEFINE command:

```        DEFINE macroname macrodefinition
```

Used in this way, the DEFINE command loads the macro definition into memory. For example, you can enter

```        DEFINE ALT+Q 'FILE'
```

to redefine the ALT+Q macro (which has NOP, for "no operation", as its default definition) to issue the 'FILE' command. Note that 'FILE' is enclosed in quotes because it is a literal string within a macro definition.

Using another form of the DEFINE command, you can define a macro by specifying a disk file. For example,

```        DEFINE ABC.KEX
```

places the macro definition contained in the ABC.KEX file into memory, where you can invoke it by name.

You can also define several in-memory macros at once using a .KML (KEDIT Macro Library) disk file:

```        DEFINE GHI.KML
```

The set of macro definitions in the GHI.KML file are then loaded into memory where each can be invoked individually. The format for .KML files is described in KEDIT for Windows Users Guide Chapter 10, "Using Macros".

These DEFINE commands themselves can also be issued from within a macro (your WINPROF.KEX macro, for example, might contain several DEFINE commands). To execute a DEFINE command from within a .KEX file you would simply enclose it in quotes as a literal string. If the definition itself contains quotes, as in our ALT+Q example, use double quotes to enclose the entire DEFINE command:

```      "DEFINE ALT+Q 'FILE'"
```

Where KEDIT Looks for .KEX and .KML Files

If you don't specify an explicit directory path when you use the DEFINE command to load a .KEX or .KML file, KEDIT looks in the following places for the file: in the current directory, in a list of directories controlled via the SET MACROPATH command, in the directory from which the KEDIT module was loaded, and in the USER and SAMPLES subdirectories of that directory.

Unless you are using a shared copy of KEDIT installed on a network server, we suggest that you keep any macros that you create in the USER subdirectory of the main KEDIT for Windows directory (which is usually either C:\KEDITW or C:\Program Files\KEDITW). The USER subdirectory is created by KEDIT's SETUP program and is a convenient place to store macros because KEDIT automatically looks in this directory when searching for macros. KEDIT also looks in the main KEDITW directory and in its SAMPLES subdirectory, but we recommend that you not put your own files into these directories, reserving these directories for files installed by KEDIT's SETUP program.

If you are using a copy of KEDIT stored on a network server and want to maintain your own macros, independent of other users accessing the same copy of the KEDIT module, you will need to keep your KEDIT macros in one of the directories specified via SET MACROPATH.

### Modifying in-memory macros

You can modify the definition of a one line in-memory macro on the KEDIT command line using a form of the MODIFY command:

```      MODIFY MACRO macroname
```

For example, entering

```      MODIFY MACRO ALT+S
```

will place the definition for the F6 macro on the command line,

```      define alt+s if \command() then 'split aligned'
```

where it can then be modified and entered.

To modify the definitions of several in-memory macros you can issue the MACROS command with a list of the macros you want to change, again in the form:

```      MACROS macroname1 macroname2 ...
```

then alter the definitions listed for the specified macros inside the MACROS.KML file and FILE it. The MACROS.KML file must then be defined via the DEFINE command to place those altered macros into memory.

### Macros are either on-disk or in-memory

#### Running a macro

To execute an in-memory macro that is bound to a key you can simply press the appropriate key. Or, because the MACRO command causes KEDIT to run a specified macro, you could enter

```      MACRO F1
```

which is equivalent to hitting the F1 key. If the macro specified is not in memory then the MACRO command can execute it from disk via the KEDIT macro search process. You can also explicitly specify the drive or directory in which to look, and give a file extension (if it is something other than the default of .KEX). The syntax of the MACRO command is:

```      MACRO macroname [text]
```

where text is passed to the macro as an argument which the macro can then access using the ARG() function. For example:

```      MACRO C:\MANUALS\DOCSTYLE brochure
```

instructs KEDIT to pass the argument 'brochure' to DOCSTYLE (which must be a .KEX file, since no extension is specified) in the MANUALS directory of the C: drive, and execute the DOCSTYLE macro.

If the directory path for a macro is not explicitly specified, KEDIT initially looks for the specified macro in memory and, if found, executes it. If the macro is not in memory KEDIT will next look on disk for a .KEX file whose name matches the name that you specify. The search order that KEDIT uses when searching for .KEX files is described above [add link]. If the macro is found, it is then loaded from disk and executed. If the specified macro cannot be found in memory or on disk KEDIT will issue the following error message:

```      Error 71: Macro not found:macroname
```

You can also execute macros whose names consist entirely of alphabetic characters without the MACRO command if, as is normally the case, IMPMACRO ON is in effect. With IMPMACRO ("implied macro") ON, when KEDIT receives a command that it does not recognize it will engage in a macro search process and execute the macro if it is found. Macros whose names are entirely alphabetic can therefore be run by simply entering the macro name on the KEDIT command line, just as though it were a built-in KEDIT command.