# User Macros

In addition to the standard macros supplied with MOLMOL, you can write your own macros, and execute them using the `XMacUser` command. The default extension for macros is `.mac`.

## Writing Macros

You can write macros from scratch using a text editor. If the macro you plan to write is similar to one of the standard macros, you may want to start with a copy of that, or at least look at it as an example.

A more convenient way to build macros is using the macro recorder available in MOLMOL. You can start the macro recorder with the `RecordMac` command. It allows you to execute commands in the normal environment (using menus and dialog boxes), record them selectively, and then save the resulting macro.

A history of your session is kept in the file `molmol/history` of your home/profile directory. It can also serve as starting point for macros.

## Defining Commands

In addition to simple sequences of commands that are immediately executed when the macro is executed, macros can also contain command definitions. A command definition has the form:

> `define` CommandName
> `help` one-line-help
> `$`arg1 `=` default1 prompt1
> ..
> `$`argN `=` defaultN promptN
> Command1
> ..
> CommandN
> `end`

The name of the new command is specified after the <`define` keyword. This is normally followed by a short help message, introduced with the `help` keyword. An arbitrary number of arguments can be given, each followed by (optional) default values and prompt strings. The arguments are followed by a series of commands that define the functionality of the new command. Arguments are referenced in the form `$argName` or `${argName}`.

The following example defines a new command for adding a partial surface:

>     define AddPatch
>       help create partial surface for selected atoms
>       $rad = 1.4 "Solvent Radius"
>       DefPropAtom 'surf' 'selected'
>       SelectAtom 'mol.selected'
>       AddSurface (vdw) contact $rad shaded 0
>       SelectAtom 'mol.selected & ! surf'
>       TrimSurface ($rad + 0.1)
>       SelectAtom 'surf'
>     end

When such a definition is encountered, the commands used for the definition are not executed, the only effect is that the definition is added to the MOLMOL command list. It can then be used like one of the builtin commands.

If you want to extend the program with your own set of commands, it is especially useful to have the macro definining them be automatically executed each time you start up the program. See the section on Configuration for a description of how to do that.

## Executing Macros

You can execute macros anytime using the `XMacUser` command. You can also add menu entries or buttons to give you more convenient access to frequently used macros, or have them being executed automatically when you start the program, or whenever a new molecule is loaded. See the section on Configuration for a description of these possibilities.

Last modified: Mon Jan 20 19:44:59 CST 2003