PDM_MACRO Insert Text from a Macro File

The <PDM_MACRO> tag is used to insert a macro file into an HTMPL file. Its functionality is similar to PDM_INCLUDE, with two important differences:
casm173
The <PDM_MACRO> tag is used to insert a macro file into an HTMPL file. Its functionality is similar to PDM_INCLUDE, with two important differences:
  • A file included by PDM_MACRO has a formal argument list, with required arguments and arguments with default values.
  • A file included by PDM_MACRO always comes from the directory specified for the configuration property MacroPath, regardless of the current user's access type.
  • NAME=
    macroname
    (Required) Specifies the macro to include. The web engine affixes the suffix “.mac” and searches for the file in the path specified by configuration file property MacroPath.
Other properties may be required, depending on the macro included. A macro file has the general layout:
comments #args name1 [= value1] name2 [= value2] ... #data data to insert
The following descriptions explains the file layout, line by line:
  • comments
    -- The only valid statements in a macro prior to the #args statement are comments. Comments are indicated by either a # sign or a // as their first non-blank character or characters.
  • #args
    -- Must be coded exactly as shown, with the # sign in column one and no other information on the line. This statement begins the args section, which can contain argument definitions and comments.
  • name [= value]
    -- Defines an argument for the macro. Only arguments explicitly mentioned in the args section are valid for the macro. A value specified for an argument in the args section is that argument's default value. Arguments without a default value are required, and must be supplied by the caller on the <PDM_MACRO> statement itself.
  • #data
    -- Must be coded exactly as shown, with the # sign in column one and no other information on the line. This statement begins the data section, which is the part of the macro inserted into the file using PDM_MACRO. Everything in the data section is inserted into the calling file, including lines that would be comments prior to the data section.
  • data to insert
    -- The data to insert into the calling file. This data can contain references to arguments in the form:
  • &{arg_name}
    -- These references are replaced with the value of the argument supplied by the caller, or with the default value if the caller did not supply a value.
The web engine normally reads a macro file only once, the first time it is used, and then stores the parsed macro in its own memory. This improves performance, but can be inconvenient if you are developing a macro. Use the configuration file property SuppressMacroCache to prevent this behavior and cause the web engine to discard all macros in its memory each time it begins processing a new form.
To Comment Out PDM_MACRO Tags
To comment out <PDM_MACRO> tags, enter an exclamation point in front of the P as follows: <!PDM_MACRO>. To prevent the browser from processing the commented out portion of the form, place <PDM_IF 0> before the <!PDM_MACRO> tag, and </PDM_IF> after the line you commented out.Example:
<PDM_IF 0> <!PDM_MACRO NAME=dtlDropdown hdr="Status" attr=status lookup=no evt="onBlur=\\\"detailSyncEditForms(this)\\\""> <!PDM_MACRO NAME=dtlDropdown hdr="Priority" attr=priority lookup=no evt="onBlur=\\\"detailSyncEditForms(this)\\\""> </PDM_IF>