Chapter 6

ENHANCING KEYBOARD-RECORDED
MACROS

At least in the beginning, the majority of the macros you'll create will be the keyboard-recorded kind. Turn on macro definition, tap a series of keys, and the macro will be prepared for you. Keyboard-recorded macros are fine for basic tasks -- those that simple reply a series of keys -- but they use less than 15 percent of WordPerfect's powerful macro features.

You can, however, enhance keyboard-recorded macros by adding a few well-placed commands using WordPerfect's built-in macro editor. You'll create the macro in the usual fashion by defining it at the keyboard, then enhance the macro by inserting your own special commands.

 

REVIEW: RECORDING AND EDITING A MACRO

Earlier chapters in this book explained the process of recording and editing a macro, but it's worth reviewing the technique here. Let's use a named macro, called TESTMAC, for the summary. In it, we'll change the line spacing to 3.

To define a named macro:

Key Sequence What it Does
1. [Ctrl]-[F10] Starts macro recording.
2. TESTMAC
[Enter]
Names macro.
3. Test macro
[Enter]
Describes macro.
4. {Format}LS3
{Exit}{Exit}
Sets line spacing to 3.
5. [Ctrl]-[F10] Stops macro recording; saves macro file on disk.

To replay the TESTMAC macro:

Key Sequence What it Does
1. [Alt]-[F10] Execute play back macro command.
2. TESTMAC Defines TESTMAC as the macro to use.
3. [Enter] Initiates macro playback.

To edit TESTMAC, you must go through the steps of defining it once more. After you press [Ctrl]-[F10] and type TESTMAC (followed by pressing the [Enter] key), WordPerfect will ask if you want to replace, edit, or describe the macro.

To edit the macro, press E or 2 for Edit. Your screen should show the macro editing window.

WordPerfect automatically places the cursor at the very beginning of the macro. You can now move around the macro, deleting, adding, or formatting text and codes.

When you're done with the macro, press the Exit key ([F7]), and you're returned to the main editing screen.

 

GENERAL HOUSEKEEPING

Longer and more complex keyboard-recorded macros may contain one or more pages of code. The jumble of text, commands, and WordPerfect feature keys can look confusing at first. But there are a number of ways you can tame the wild macro beast:

 

Formatting the Macro

The Enter and Tab keys can be used to format the macro code. Formatting helps to make the macro more readable, so you can analyze what it's doing at every step. When all the code runs together, it can be hard to decipher its function.

To separate macro code into lines, position the cursor where you want to break into a new line, and press [Enter]. Remember you can use most all of WordPerfect's standard cursor keys, including [Ctrl]-[Right] and [Ctrl]-[Left] for Word Right and Word Left, to move around in the macro editor. Add an extra blank line after major routines.

The Tab key indents the macro code in the line. DO NOT use the Spacebar to indent macro code -- the spaces will appear in your document. You can always spot the difference between tabbed indentions and spaced indentions. Spaces are represented by a small, mid-line dot (ASCII 250), whereas tabs are blank.

Although you can't see the [Enter] and [Tab] codes in the macro document, you can remove them, just as you can in WordPerfect's main editor. Use the Delete key to remove a tab or enter code under the cursor; use the Backspace key to delete to the left of the cursor.


Editing Mistakes

You'll likely make a mistake here and there while defining the macro. You might press the wrong keys and backspace over them to delete them. Or you might open the wrong menu, cancel out, and open the correct one.

With a bit of house cleaning, you can remove any typos and unnecessary commands. To edit a macro, move the cursor over the offending character or code, and press the [Delete] key. You can also use the [Backspace] key, and most every other editing key provided in WordPerfect (with the notable exception of Delete to End of Page, or [Ctrl]-[Page Down]. Be careful that you don't remove any characters or code that you really need. If you do erase code you need, you can enter it again by pressing the appropriate key on the keyboard. To re-enter an A, for example, press the A key. To re-enter a {Screen} code, press [Ctrl]-[F3].


Commenting

Comments are one or more lines of text that you can include in your macro for descriptive purposes, but will be ignored when the macro is executed. Adding comments to macros (or commenting out) helps you identify important parts of the code so that you can better trace its operation. Comments are especially helpful if anyone else attempts to customize the macro, or if you return to the macro at some later date, and need to remember how it works.

To add a comment, move the cursor to the appropriate spot in the macro. Although a comment can appear anywhere, you'll want to start it on its own line, or at least on the same line as an important piece of macro code. Press [Ctrl]-[Page Up] (the Macro Commands key). The macro commands list appears over the macro editing box. The Comment command, top-most in the list, should already be highlighted. If it's not, press [Home], [Home], [Up], or tap once on the [Spacebar] key. With the Comment command highlighted, press the [Enter] key. The Comment code, {;} should appear in the macro editing box, at the location of the cursor.

Write the comment text. The comment can be any length you want, and you are free to format it using the [Enter] and [Tab] keys, as outlined above.

At the end of the comment, add a tilde (~). This character serves as a delimiter and tells WordPerfect that the comment is ended. Characters and codes that appear after the comment are to be executed.

Comments are an advanced macro command you can also add when defining a keyboard-recorded macro. During macro definition, press [Ctrl]-[Page Up], then press C for comment. Write the comment and press [Enter] when you're through. The comment will be added on its own line in the macro, but in subsequent playback of the macro, WordPerfect will ignore the text you wrote. You won't see the comment unless you edit the macro.

Tip: Although comments are a handy thing to have around when you're examining, editing, or "debugging" a macro, too many comments can make macro execution sluggish. You may wish to place one large comment at the beginning of the macro that describes the basic function and special features. You may also wish to indicate the unique variable names you've used (if any) or any special considerations the user should know about before using the macro. If you must add many comments to the macro, make them short and concise. You may also wish to make two versions of the macro: one that is fully commented and serves to document the macro, and the other -- for actual use -- where the comments have been removed.

Adding Routine Labels

The {LABEL} command is ordinarily used to direct WordPerfect to a specific spot in the macro, as when using subroutines. But you can also use {LABEL} as an alternative means to comment a macro.

To add a label, move the cursor to the appropriate spot and press the [Enter] key a few times to move the code down one or more lines. This separates the {LABEL} from any codes above it, and helps make it easier to spot when you're reviewing the macro. Press [Ctrl]-[Page Up], and type LABEL to jump to the {LABEL} command (you actually need only type the first two characters; WordPerfect will know you want the {LABEL} command with just LA).

Press [Enter] to place a {LABEL} command code in the macro, then enter a label name. Most any name will do, and you can use any character you like, including spaces and underlines.

Tip: Label names can be any length, though when you use the {LABEL} command to actually identify routines for the macro (when using the {GO} and {CALL} commands, for example), the name should be 15 characters or less. The reason: WordPerfect looks at just the first 15 characters for uniqueness, and ignores any other characters thereafter. If two labels start with the same 15 characters, WordPerfect won't be able to distinguish between them, and the macro won't work properly.

To complete the label name, type a tilde (~). This delimits the label name, and lets WordPerfect know that any characters or codes thereafter are part of the macro, not part of the label name.

 

CHAINING AND NESTING MACROS WHILE EDITING

Recall from Chapter 2 the difference between a chained and a nested macro. In a chained macro, WordPerfect starts the first macro and executes it to completion. At the end of the macro is an instruction to chain or branch off to another macro. WordPerfect then starts the second macro. Once a macro has been chained, WordPerfect forgets about the previous one and concentrates just on the new one.

In a nested macro, WordPerfect executes the first macro, then -- when it encounters the nesting instruction -- temporarily branches off to another one. When the second macro is finished, WordPerfect returns to the first macro where it left off.

You can provide chaining and nesting instructions while defining the macro from the keyboard, or you can add them during editing.


To Chain to A Named Macro

WordPerfect offer a number of ways to add a chain command in the macro editor. This is just one way. The basic chain command is -- what else -- {CHAIN}. WordPerfect assumes you want to chain to another macro after the first macro is completely finished, so it expects the {CHAIN} command to be at the very end of the macro. At the macro editing screen, move the cursor to the end of the macro. Add one or two lines (using the [Enter] key as described in the previous section) to separate the {CHAIN} command from the rest of the macro code. Then:

Key Sequence What it Does
1. [Ctrl]-[Page Up] Accesses macro commands list.
2. CHAIN Goes to {CHAIN} command in list.
3. [Enter] Inserts the {CHAIN} command into the macro.

Now, enter the name of the macro you want to chain to. You don't need to provide the .WPM extension. Remember to provide the disk and drive if the macro file doesn't reside in the current directory. Finally, type a tilde (~) to signal the end of the {CHAIN} command.


To Chain to An Alt-Letter Macro

You can also chain to an Alt-letter macro by entering its name explicitly after the {CHAIN} command. For example, if the macro you want to chain to is recalled with the [Alt]-K keys, its name on the disk is ALTK.WPM. Provide the name ALTK after the {CHAIN} command.


To Nest to A Named Macro

As with chaining, WordPerfect offer a number of ways nest to other macro. Here's are two easy ways. {NEST} is the basic command WordPerfect uses for nesting to other macros. Unlike chaining, you can place the {NEST} command anywhere within the macro. The instant WordPerfect encounters the command, it will branch off to the named macro, complete it, and return. Execution will resume at the spot right after the {NEST} command.

At the macro editing screen, move the cursor to where you want to add the {NEST} command. Use the [Enter] key to add one or two blank lines to separate the {NEST} command from the rest of the macro code. Then:

Key Sequence What it Does
1. [Ctrl]-[Page Up] Accesses macro commands list.
2. NEST Goes to {NEST} command in list.
3. [Enter] Inserts the {NEST} command into the macro.

Provide the name of the macro you want to nest to. You don't need to provide the .WPM extension. Remember to include the disk and drive if the macro file doesn't reside in the current directory. Finally, type a tilde (~) to signal the end of the {NEST} command.


To Chain to An Alt-Letter Macro

You can nest to an Alt-letter macro in one of two ways: by using the {NEST} command, as described above), or by inserting an {ALT n} command. The {ALT n} command represents an Alt-letter macro, where "n" is a letter from A to Z. To enter an {ALT n} command,

Key Sequence What it Does
1. [Ctrl]-V Tells WordPerfect you want to enter a special macro code.
2. [Alt]-{letter} Specifies the Alt-key macro to nest to.

You do not need to enter any additional information when using the {ALT n} technique for nesting, nor do you need to provide a tilde character, as you do with the {CHAIN} and {NEST} commands.

IMPORTANT: Be sure to press [Ctrl]-V before you press the [Alt] and letter keys, or WordPerfect will attempt to play back the Alt-letter macro right in the macro editor! Should you forget to press [Ctrl]-V first, the macro you're editing may be garbled with wrong characters, and the display may temporarily "freeze" (a *Please Wait* indicator appears in the lower left corner of the screen).

Don't panic. To unfreeze the display and cancel any changes to the macro, press the Cancel key ([F1]), and press Y -- you want to quit the macro without saving the changes. Once you're back at the WordPerfect main editing screen, re-define the macro to continue editing it.

If you don't think the Alt-letter macro did any harm to the macro you are editing, press the [Esc]key once or twice to clear the display of the *Please Wait* message.

Note that tildes are always provided after the macro names in {CHAIN} and {NEST} commands. Without the tildes the macro won't work.

Tip: You can place an {ALT n} code anywhere within a macro, even at the very end. When you place the code at the end, WordPerfect considers it the same as a {CHAIN} command. If you still want to use the {ALT n} code to nest, but must have it at the conclusion of the macro, add a mock label at the very end of the file, something like {LABEL}end~ You don't have to include any characters or codes after the label.

 

LOOPING

Loops repeat all or part of a macro. If you know that the steps in a macro must be repeated a certain number of times each occasion you run it, you can include all the necessary looping instructions, and the macro will take care of itself. Looping is a common scheme of getting more mileage out of a small amount of macro code. Although some types of loops require complex macro programming, there are three techniques you can easily apply to most any macro:

 

Loop Back to Macro

To repeat a macro, you need only add a {CHAIN} command at the end. Provide the same name as the macro, and WordPerfect will re-run it indefinitely. This type of loop is open-ended, or "infinite," and actually has little use in day-to-day work. You'll want some way to control the number of times the macro is repeated. That can be done by including a Search as one of the steps in the macro (see below) or by adding a "repeat" prompt before the macro is restarted.

The repeat prompt makes use of a helpful macro command, {CHAR}. The {CHAR} command temporarily freezes macro execution, and displays a message of your choice. It expects a single-key response. To control looping, the {CHAR} command is used to stop the macro just long enough to decide if you want to re-run the macro. If you press Cancel, the macro stops. If you press any other key, the macro continues.

Note that the {CHAR} command "captures" the key you pressed and holds it in a variable. In this application, the contents of the variable will not be used, but in later macros in this book, you'll see how the key you pressed in response to a {CHAR} command can be used to precisely control the flow and direction of a macro.

To add the {CHAR} command and associated codes to repeat the macro, move to the end of the macro and add some extra lines using the [Enter] key. Remember, these blank lines won't affect the operation of the macro; they are there just to format the macro to make it easier to edit. Then do the following:

Key Sequence What it Does
1. [Ctrl]-[Page Up] Activates macro commands list.
2. CHAR
[Enter]
Pin-points the {CHAR} command within the list, and enters it in the macro.
3. 1 ~ Enters a 1 to store the keystroke into variable 1 (don't forget the tilde).
4. Press any key to repeat the macro, or press Cancel to stop~ Enters message prompt.
4. [Ctrl]-[Page Up] Activates macro commands list.
5. CHAIN Selects {CHAIN}, selects it. [Enter]
7. {macro name}~ Specifies the name of the macro you are editing (to chain back to itself).

Tip: While the name search feature of quickly pin-pointing the command you want to use from the macro commands list is the most straightforward method, you can also use the cursor keys to highlight any of the commands in the list.

When you run the macro, it will complete one iteration, then stop and ask if you want to do another. Press Cancel if you don't; any other key if you do. How does this macro work? When you press the Cancel key, it automatically terminates the macro. When you press any other key, it ends the {CHAR} command and goes directly to the {CHAIN} command.


Loop Back to Label

Instead of repeating the entire macro, you can repeat just a portion of it. Looping back to a label requires that you identify the routine you want to repeat with a {LABEL}, and indicate to the macro that you want to go back to it with the {GO} command.

You'll find it easiest to repeat a routine if you construct the macro so that the beginning part has the codes you don't want to repeat (run once the first time the macro is executed, but not thereafter). Fill the remainder with the routine you want to replay. At the end of this routine, provide the {GO} command, such as:

...Start of macro you don't want to repeat
{LABEL}loop~
Repeat this part of the macro.
{GO}loop~

The text and codes between the {LABEL} and {GO} commands are repeated an endless number of times. As with repeating the entire macro, you'll most likely want a way to stop the loop at some point. Use a search as one of the steps in the loop (see below), or use the {CHAR} prompt, as illustrated above.

Follow the same procedures outlined previously in this chapter for adding macro commands. Press [Ctrl]-[Page Up], find the command you want to use, then press [Enter] to insert it in the macro editor. DO NOT type commands from the keyboard. WordPerfect will not know they are macro commands, and will treat them like text.

By re-arranging the repeated loop a bit, and using the {CALL} command instead, you can indicate a precise number of times to re-run the routine. Use this construction:

...Start of macro you don't want to repeat
{CALL}loop~
{CALL}loop~
{CALL}loop~
{QUIT}
{LABEL}loop~
Repeat this part
{RETURN}

Let's take a look at what's going on. The beginning of the macro contains text and codes you want to run just once (of course, this portion is completely optional; you can repeat the entire macro if you wish). Then, three {CALL} commands repeat the "loop" subroutine three times. At the end of the third iteration, the macro quits. Note the {RETURN} command at the end of the "loop" subroutine. This is absolutely required. It tells the macro that the "loop" subroutine is finished, and that control should be resumed to the point immediately after the initiating {CALL} command.


Loop Using Search

A feature of macros is that they automatically terminate if you initiate a search, and that search fails (you can prevent termination after failed searches, but that's a topic for later chapters).

By providing a search of some kind in the repeating steps of the macro, you incorporate a method to stop the macro and cease additional iterations. A macro that finds all the occurrences of one name and replaces it with another is a good example. While this macro can be more easily duplicated with the Replace feature of WordPerfect, it demonstrates the use of search in a macro loop.

The macro starts and begins a search. Assuming WordPerfect finds the name its looking for, it deletes the previous entry and replaces it with another name. The macro then loops back -- using {CHAIN} in this case, but you can also loop back to a label. At some point, WordPerfect will no longer find a matching name. When that happens, a *Not Found* message is displayed on the screen, and the macro abruptly terminates. It never has a chance to add the replacement name, or continue with another loop.

 

ADDING PROMPTS

You've already learned how to use the {CHAR} command to provide your own on-screen message during macro execution. WordPerfect provides five commands for message display: {CHAR}, {TEXT}, {PROMPT}, {INPUT}, and {STATUS PROMPT}. The first two commands display a message, AND capture the user's response in a variable. The remaining commands throw a message on the screen and don't expect user feedback. While it may seem that these prompt commands do much the same thing, they are radically different. Future chapters will show you how to use each one in specific applications. Chapter 4, "Learning the Macro Programming Language," provides an explanation of their uses and differences.

When defining a macro from the keyboard, you can add pauses to temporarily halt execution (using [Ctrl]-[Page Up], the Macro Commands key). Until the user presses the [Enter] key, the macro sits in limbo, inactive. During that time, the user can enter text, call up menus, and do any other regular WordPerfect task. The moment the [Enter] key is pressed, the macro continues.

Stopping a macro at a (PAUSE) can be confusing if the user doesn't know what do do next. He may think the macro has finished, or worse -- has failed. By adding a {PROMPT} message before the {PAUSE}, you can provide precise instructions on the next steps that are required. Your message can be any length -- you can fill the screen if you want to -- but for the time being we'll limit it to just one line at the bottom of the display.

To add a prompt message during macro editing, position the cursor immediately prior to the {PAUSE} command. Insert a {PROMPT} command (using the [Ctrl]-[Page Up] key to access the macro commands list), then write your message. Finish the message with a tilde, as in:

{PROMPT}Fill in your name, then press Enter~

When the macro is run, WordPerfect displays "Fill in your name, then press Enter" at the bottom of the screen. It then pauses, allowing for keyboard entry. You can provide a {PROMPT} for every {PAUSE} in your macro.

IMPORTANT: Do not forget to end the {PROMPT} message with a tilde, or the macro will not work properly.

The {INPUT} command takes the place of a {PROMPT} and a {PAUSE}. If you've created a macro with {PAUSE}s, you can substitute the {INPUT} command for them. For every {PAUSE} in your macro:

  1. Delete the {PAUSE} command.
  2. Enter an {INPUT} command from the macro commands list.
  3. Enter your message.
  4. Finish the message with a tilde character.

The proper syntax for the {INPUT} command is:

{INPUT}Your message goes here~

When WordPerfect encounters the {INPUT} command, it temporarily freezes macro execution and displays the message at the bottom of the screen. You can now work with WordPerfect in the normal fashion --- enter text, edit text, format a document, etc. -- and the macro will not continue until you press the [Enter] key.

While the {INPUT} command makes a great substitute for {PAUSE} and {PROMPT}, it does have its drawbacks. The most serious is that if you press the [Cancel] key, the macro will cancel and the message will remain on the screen. To clear the message, you must either exit WordPerfect, or run another macro that explicitly clears the persistent {INPUT} message with a "null" message: {INPUT}~


Substituting {PAUSE KEY} for {PAUSE}

WordPerfect 5.1 has a great new addition to its macro commands line-up: {PAUSE KEY}. It works exactly like the {PAUSE} command, except that it lets you decide which key causes the macro to continue execution. Use the {PAUSE KEY} command whenever you need to specify a key other than Enter as the {PAUSE} delimiter. The proper syntax for {PAUSE KEY} is:

{PAUSE KEY}key~ 

Here are some examples.


Note that the keys are entered as WordPerfect feature key codes. Don't type the name of the key in braces, but enter the key code from the keyboard. In each of the examples provided, you must first press [Ctrl]-V before you can press the [Cancel], [Exit], or [Help] keys. You must do the same with most other editing and cursor movement keys.

As with the {PAUSE} command, you may wish to add a {PROMPT} command to relay a message to the user. For instance,

 {PROMPT}Press Exit when done~{PAUSE KEY}{Exit}~ 

IMPORTANT: When you press the key the {PAUSE KEY} command is looking for, it is not passed on to the WordPerfect document. For example, if you want to watch for the {Help} key, pressing Help ([F3]) will terminate the {PAUSE KEY} command, but it won't pass the Help request to WordPerfect. If you need the macro to execute the key used in the {PAUSE KEY} command, add it explicitly in the macro, as in: {PAUSE KEY}{Help}~{Help}. The second {Help} command tells WordPerfect to actually access help.

 

CONTROLLING THE DISPLAY

When you define a macro from the keyboard, WordPerfect automatically inserts a {DISPLAY OFF} code at the beginning. If you then access menus, switch documents, or perform some other action where the screen display changes, it prevents these changes from showing on the display when the macro is run. Not only does the macro operate less distractingly, it runs faster.

Should you define a keyboard-recorded macro that stops while you are in a menu -- you terminate macro definition in the Setup menu, for example -- WordPerfect will remove the {DISPLAY OFF} code. Why? WordPerfect can re-write the screen when displaying text in the editing window, but it can't re-write a menu. If the macro stops at the menu with display off, nothing shows. WordPerfect also removes the {DISPLAY OFF} code is the macro includes a {PAUSE} command.

If WordPerfect were to keep the {DISPLAY OFF} code, and the macro stops at a menu or at a pause, nothing will appear on the screen except a *Please Wait* message in the lower-left corner. WORDPERFECT IS STILL RUNNING, however, and you do not need to reset your computer. You can usually extract yourself from this situation by pressing the [Cancel] or [Ctrl]-[Break]keys.

WordPerfect takes care of adding or removing the {DISPLAY OFF} code for you when you define a macro from the keyboard. But you can always delete the {DISPLAY OFF} code yourself should you want the display to show at all times. Similarly, you can replace the {DISPLAY OFF} code should you want to hide some or all of macro execution.

Complementing the {DISPLAY OFF} code is {DISPLAY ON}, available in the macro commands list. As you can surmise, {DISPLAY ON} turns the display back on.

Life would be easy if the {DISPLAY OFF} and {DISPLAY ON} commands simply shut the screen off and on, but that's not how they work. Keep these points in mind:

Tip: If your macro accesses many menus but happens to also stop in a menu, WordPerfect will omit the {DISPLAY OFF} at the beginning of the file. The end result is that all the menus accessed by your macro will flash on the screen. You can prevent the extra menus from showing on the screen by replacing the {DISPLAY OFF} code at the beginning, and adding a {DISPLAY ON} code immediately before the macro accesses the last menu. Be sure to turn the display back on before accessing the menu, not after.

 

Troubleshooting with Display On

Even if WordPerfect adds the {DISPLAY OFF} code at the beginning of the macro, you may need to temporarily delete it if you find your macro isn't working right. Even though most macros whiz by in the wink of an eye, you can often tell what's going wrong if you can see the process of macro execution. If you're having trouble getting a macro to work properly, delete the {DISPLAY OFF} code (or codes if you've added more of your own), and watch the screen as the macro runs.

 

IMPORTANT TOPICS

This chapter has covered enhancing keyboard-recorded macros. You learned:

---

 Top Contents

WordPerfect 5.1 Macros and Templates
Electronic Edition
Copyright 1990, 1997, Gordon McComb.  All Rights Reserved.
First published by Bantam Electronic Publishing, 1990.
http://www.gmccomb.com/