Last week we looked at how to use PPWizard, the unusually flexible and powerful Web page design tool from Dennis Bareis to build an actual web page from this site.¹ This week we shall continue that tutorial spirit by taking a detailed look at one of PPWizard's most powerful and best-supported features: the macro.² We shall define what a macro is and examine an actual macro and each of its components in detail with a view to showing the macro's power.

Macro Described

The best way to describe a Macro is to compare it with a Function (or Procedure).

1. Similarities

   1. Functions and Macros are both ways to reduce programming labour for scripts that occur, perhaps with minor variations, over and over.

   2. Both are called by name.

   3. Both may or may not have parameters.

2. Differences

   1. Macros are typically faster for shorter lengths of code (i.e. scripts).

      1. Note, however, that macros combined with the conditionals such as #ifdef, etc., can result in entire sections of code disappearing as far as the HTML compiler (i.e. browser) is concerned resulting in good net performance even with long macros.

      2. Macros are processed at preprocessor (build) time, and are gone once the browser is loaded.

      3. Functions are built by the compiler (using java or javascript) and continue to require computer time while the browser is running.

      4. If macros become too big, they can become unwieldly, and it may be worth looking into a Javascript function.

Macro Defined

1. Define command

   1. The usual method of defining a macro is to write the command Define followed by a "\" or other line continuation character, and then write the definition of the macro below. ³

      Here is a simple example:

         #define Major                \
         #if ['{$Color=''}' = '']     \
            <H3><Font Color="Red">{$Head}</Font></H3>  -\
         #elseif                                        \
            <H3><Font Color={$Color}>{$Head}</Font></H3> -\
         #endif
      

      • Note: All PPWizard macros are conceptually one-line macros. If more than one line is necessary, then a continuation string (typically "\" or "-\") must be used. This applies both when defining and when calling.

   2. Before we begin detailed study of this macro itself, it's worth pointing out that the above macro is the actual macro that produces the major red headings on this page--it is actual source code used as an example, and yet you can read the special macro characters such as '<', '>', and "#". This is because PPWizard includes commands and macros to automate the conversion of these characters into browser-displayable sequences.

2. Components of Macro Definition

   1. The first component of a macro definition is the macro name, and is required.

   2. The next element consists of one or more strings of text. This text can be either plain ASCII or an HTML expression or string. At least one such string is required.

      1. In our example Major can best be thought of having three main elements: the first is the string from #elseif to the end of the next line; the second consists of the string from "#elseif" to "#endif"; and the third consists of the parameters.

      2. The macro is executed by testing the expression after the #if statement. If true, the value of the macro is the second line; if it is false then the value of the macro is the line following "#elseif". The value of the macro is displayed as the heading.

   3. The next element consists of zero or more parameters. They are not required.

      1. A simple example of a macro without a parameter would be:

         #define EMailGuide "walter.os2@rogers.com"
         

         Apart from being shorter, the obvious advantage to this approach is that whenever the email address is changed, as it did when the Mining Co. changed its name to About.com, the email address needs to be changed in just one place instead of hundreds or even thousands of places.

      2. A parameter is indicated by an alphameric string preceded by $ included in braces (e.g. {$Color}). Therefore in the Major macro, there are two parameters: Color and Head.

         1. Optional Parameter

            • The special notation {$Color=''} indicates that the parameter Color is optional: it may be omitted. If the parameter is omitted it will be assigned an empty or null value.

         2. Finally, as a result of the macro's execution, if the parameter is not supplied ($Color='') the Font color is changed to Red; otherwise the font color is changed to the color specified by the Color parameter.

Macro Called

One of the most important things to understand is the difference in format between a macro definition and a macro call.

1. A macro is called by prepending a $ and enclosing the result in angle brackets:

                <$Major>
                

   • Notice the angle brackets: it is sometimes easy to confuse these with macro parameters in definitions which are enclosed in braces.

2. Parameters, if any, are generally specified by typing the name of the parameter immediately after the macro name, followed by an equal sign, and then followed by the value of the parameter in quotes, or other delimiter.

   • Example:

            <$Major Head='This is a sample heading'>
            

3. Although the macros we've looked at have been relatively simple, they have demonstrated the most important points. The complexity of macros is almost unlimited, but then their length begins to increase very quickly, and space prevents us from investigating them here. ⁴ If you wish to look at two complex macros that are very useful, I suggest you begin by downloading the files Htmlpre and Footnote from the PPWizard Web site. These are two especially helpful, not overly complex headers which contain several related and well-commented macros.

—Walter Metcalf

Next week: Setting Up a SOHO Network on OS/2 Warp 4, Part 1