Creating and using macros

You can use macro-commands in your methods. Using macro-commands saves a lot of time during method entry.

A macro-command is a section of 4D code that is permanently accessible and that can be inserted anywhere in your methods, whatever the type of database open. Macros can contain all types of 4D text, commands and constants, as well as special tags which are replaced at the time of macro insertion by values derived from the method context. For instance, a macro may contain the tag <method_name/>; at the time of macro insertion, this tag will be replaced by the name of the current project method. 

Macros are stored in one or more XML format (text) file(s). They can be placed in a Method editor list; they can also be called using the context menu of the editor or using the autocomplete function.

4D macros are written in XML format. You can use the 4D default macro file “as is” or modify it.

4D loads the macros from a folder named “Macros v2.” Macros must be in the form of one or more XML files that are placed in this folder. 

The “Macros v2” folder can be located:

• In the active 4D folder of the machine. Macros are then shared for all the databases.
  Note: The location of the active 4D folder varies according to the operating system used. For more information, refer to the description of the Get 4D folder command in the 4D Language Reference manual.
• Next to the database structure file. Macros are only loaded for this structure.
• For components: in the Components folder of the database. Macros are then only loaded if the component is installed.

These three locations can be used simultaneously: it is possible to install a “Macros v2” folder in each location. The macros will be loaded in the following order: 4D folder, structure file, component 1... component X.

4D offers a set of default macros corresponding, in particular, to the list of keywords in previous versions of 4D. These macros are included in the default “Macros.xml” file, placed in the “Macros v2” folder that is created in the active 4D folder of the machine during the initial startup of 4D. 

You can modify this file or the contents of the folder subsequently as desired (see the following paragraph). In the event of problems with this folder, it can be deleted and 4D will re-create it on the next startup.

You can add customized macros in the “Macros.xml” file using a standard text editor or by programming. You can also add XML files of customized macros in this folder. 

In local mode, the macros file can be open while using 4D. The list of available macros is updated on each event activating 4D. For instance, it is possible to bring the text editor to the foreground, modify the macro file, then return to the method: the new macro is then available in the Method editor. 

Empty or erroneous macros are not displayed.

The macro-command files of 4D must be in conformity with the XML standard. This means more particularly that XML declaration <?xml version="1.0" ...?> and document declaration <!DOCTYPE macros SYSTEM "http://www.4d.com/dtd/2007/macros.dtd"> statements are mandatory at the beginning of a macro file in order for it to be loaded. The different types of XML encoding are supported. However, it is recommended to use encoding that is Mac/PC (UTF-8) compatible. 4D provides a DTD that can be used to validate the macro files. This file is found in the following location:

• Windows: \Resources\DTD\macros.dtd
• Mac OS: :Contents:Resources:DTD:macros.dtd

If a macros file does not contain the declaration statements or cannot be validated, it is not loaded.

4D macros are built using customized XML tags called “elements.”

Some tags indicate the start and end of the definition (double tags of the type <tag> </tag>), others are replaced by insertion context values (<tag/>).

In conformity with XML specifications, some element tags can include attributes. Unless otherwise indicated, these attributes are optional and a default value is used when they are omitted. The syntax of elements with attributes is as follows:

• Double tags: <tag attribute="value"> </macro>
• Single tags: <tag attribute="value"/>

If the element accepts several attributes, you can group them in the same line of command, separated by a space:
<tag attribute1="value" attribute2="value" attribute3="value"... >

Here is the list of tags and their mode of use:

* Macros can be called using the context menu of the Method editor or using the type-ahead function (see the following section).
** If you want to conform to XML language specifications, you must not use extended characters (accented characters, quotation marks, etc.).

Here is an example of a macro definition:

The <method> tag allows you to generate and use macro-commands that execute 4D project methods. This allows developers to create sophisticated functions that can be distributed via macro-commands which are associated with components. For example, the following macro will cause the MyMethod method to be executed with the name of the current method as parameter:

The code of a called method is executed in a new process. This process is killed once the method is executed. 

Note: The structure process remains frozen until the called method execution is completed. You must make sure that the execution is quick and that there is no risk of it blocking the application. If this occurs, use the Ctrl+F8 (Windows) or Command+F8 (Mac OS) command to “kill” the process.

By default, macros can be called using the context menu or toolbar of the Method editor, the autocomplete function, or a specific list at the bottom of the Method editor window.

Note that for each macro it is possible to restrict the possibility of calling it using the context menu and/or the autocomplete function.

By default, all macros can be called via the context menu of the Method editor (using the Insert macro hierarchical command) or the “Macros” button of the toolbar. 

The in_menu attribute of the <macro> tag is used to set whether or not the macro appears in this menu.

In the context menu, macros are displayed in the order of the “Macros.xml” file and any additional XML files. It is thus possible to change the order by modifying these files.

By default, all macros are accessible using the autocomplete (aka type-ahead) function (see Writing a method). The type_ahead attribute of the <macro> tag can be used to exclude a macro from this type of operation. 

Note: If the macro contains the <selection/> tag, it will not appear in the autocomplete pop-up window.

You can display your macros in a list of the Method editor (see Writing a method). Simply double-click on the name of a macro in the list in order to call it. It is not possible to exclude a specific macro from this list.

Macro support can change from one version of 4D to another. In order to keep the different versions compatible while maintaining your customizations, 4D does not remove any previous versions. If you want to use the latest features available, you must adapt your version accordingly.

In versions of 4D prior to v11, the program automatically maintained a set of process variables for manipulating text in methods when using the <method> tag: input variables (_textSel, _blobSel, _selLen, _textMethod, _blobMethod, _methodLen) to retrieve text and output variables (_textReplace, _blobReplace, _action) to insert text. For the sake of compatibility, this mechanism is still supported, but since version 11 it is obsolete for the following reasons:

• The use of BLOB variables for managing text with a size greater than 32,000 characters is no longer necessary,
• The management of variables is not compatible with the v11 architecture in which the execution spaces of variables are partitioned. A version 11 component cannot access the text of host database methods (and vice versa) using predefined variables.

Consequently, it is recommended to manage text selections using the GET MACRO PARAMETER and SET MACRO PARAMETER commands. These commands can be used to overcome the partitioning of the host database/component execution spaces and thus allow the creation of components dedicated to the management of macros. In order to activate this mode for a macro, you must declare the Version attribute with the value 2 in the Macro element. In this case, 4D no longer manages the predefined variables _textSel, _textReplace, etc. and the GET MACRO PARAMETER and SET MACRO PARAMETER are used. This attribute must be declared as follows:

If you do not pass this attribute, the previous mode is kept.

Beginning with 4D v11, strict syntax rules must be observed in order for macros files to respect the XML standard. This may lead to incompatibilities with the code of macros created with previous versions and prevent the loading of XML files. The following are the main sources of malfunctioning:

• Comments of the “// my comment” type, allowed inside <macro> elements in previous versions of 4D, are not compatible with the XML syntax. The lines of comments must respect the standard “<!-- my comment -->” form.
• The <> symbols used more particularly for interprocess object names must be encoded. For example, the <>params variable must be written &lt;>params.
• The initial <macros> declaration tag could be omitted in previous versions of 4D. It is now mandatory; otherwise, the file will not be loaded.

In version 12 of 4D, there are new macro commands available to facilitate the use of the SQL commands. Since you can customize the "Macros.xml" file, installing a new version of 4D does not automatically replace the existing version of the file. To use the new SQL macro commands of 4D v12, you must either:

• delete the "Macros.xml" file in the "Macros v2" folder (if you have never modified it), then launch 4D to create the new file automatically.
• add the new macros manually to the "Macros.xml" file in the "Macros v2" folder (if you have already customized the contents). The new template file for the macros is located in the 4D application folder 4D\Resources\en.lproj or 4D\Resources\fr.lproj.