Chapter 20


Best novels are not written, they say, but rewritten. The same is true of best macros. Not only will you rewrite your macros to improve upon them, to make them even better and productive, but you'll rewrite some of your macros because you will be plagued from time to time with inexplicable problems.

When things don't work right in computer programs, its called a bug. Understandably enough, ridding your macros of bugs is called "debugging." This topic is important enough to any serious WordPerfect macro user to devote an entire chapter on it. If you're experiencing problems with your macros, read through this chapter first before pulling out your hair.



Mistakes during macro keyboard entry or editing are common, so you should always double-check your work at the first sign of a problem. Things to look for:



Barring any typographical errors in the entry of the macro, the next step in determining the cause of a problem is to isolate the routines of the macro. If the macro is any size at all (more than two or three window-fulls), you will probably have an idea of the approximate location of the difficulty. If the macro isn't copying a piece of text correctly, for instance, you know to look in the routine that finds the text, blocks it, and copies it.

Carefully review the problem area one more time and look for errors. Then insert a {QUIT} instruction after the first step. Exit the macro and run it. The macro will proceed up until it reaches the {QUIT} instruction, then stop. Has the problem shown up yet? If not, re-edit the macro, delete the first {QUIT} instruction, and add another after the next step.

Repeat this process one step at a time until you find the problem. Once the problem has been pinpointed, you can carefully study the malfunctioning step and determine what has gone wrong. Try the step yourself (without the macro) to see if it works under manual control. Usually, you will find a missing step or an incorrect code.

You can also pinpoint problems using the {SPEED} and {STEP ON} instructions. {SPEED} slows down execution of the macro so that you can watch it perform its various steps. Set the speed once at the beginning of the macro or at least at the beginning of the routine you believe is causing the problem.

Note that even with one speed used for the entire macro, some operations, like writing text, go slowly while others go much more quickly. You may need to adjust the speed of playback throughout the macro in order to see some operations.

You set the speed by entering a number from 1 to 100 (you can actually go higher, but there's not much application for such a slow-running macro). Each digit represents 1/100ths of a second, and denotes the extra time the macro waits before executing each step or printing each character. Therefore, entering {SPEED}100~ is equivalent to waiting an extra second between steps. For most debugging purposes, a speed of 10 to 75 is acceptable. The {SPEED} instruction is ignored when you turn the display off using the {DISPLAY OFF} command.

The {STEP ON} command lets you step through macro execution one operation at a time. You control the progress by striking any key on the keyboard. While the {STEP ON} command is useful for diagnosing weird, off-the-wall problems, it has limited use in normal debugging. Not only does the macro execute the steps encoded in the macro, it displays in the status line the function keys and statements you have entered.

Rather than indicating the exact function keys or statements you have entered, the macro indicates their number. The numbers for macro statements and function keys appear in Tables 20-1 and 20-2.

Table 20-1

2    BELL
3    BREAK
4    CALL
7    CASE
9    CHAIN
10   CHAR
11   COMMENT {;}
14   ELSE
15   END FOR
16   END IF
18   FOR
20   GO
21   IF
22   LABEL
23   LOOK 24   NEST
25   NEXT
30   PAUSE
32   QUIT
38   SPEED
39   STEP ON
40   TEXT
41   STATE
42   WAIT
43   WHILE
44   Macro Commands
51   INPUT
54   MID
55   NTOK
56   KTON
57   LEN

Table 20-2

These key command numbers appear during STEP ON operation and indicate a function or cursor key.

Number    Code           Press these keys to make the code:
1         ^A             [Ctrl]-A
2         ^B             [Ctrl]-B
3         ^C             [Ctrl]-C
4         ^D             [Ctrl]-D
5         ^E             [Ctrl]-E    
6         ^F             [Ctrl]-F
7         ^G             [Ctrl]-G
8         Home           [Home] or [Ctrl]-H
9         Tab            [Tab] or [Ctrl]-I
10        Enter          [Enter] or [Ctrl]-J
11        Del to EOL     [Ctrl]-[End] or [Ctrl]-K
12        Del to EOP     [Ctrl]-[Page Down] or [Ctrl]-L
13        ^M             [Ctrl]-M
14        ^N             [Ctrl]-N
15        ^O             [Ctrl]-O
16        ^P             [Ctrl]-P
17        ^Q             [Ctrl]-Q
18        ^R             [Ctrl]-R
19        ^S             [Ctrl]-S
20        ^T             [Ctrl]-T
21        ^U             [Ctrl]-U
22        ^V             [Ctrl]-V
23        Up             [Up] or [Ctrl]-W
24        Right          [Right] or [Ctrl]-X 
25        Left           [Left] or [Ctrl]-Y
26        Down           [Down] or [Ctrl]-Z
27        ^[ (Escape)    [Esc] or [Ctrl]-[
28        ^\             [Ctrl]-\
29        ^]             [Ctrl]-]
30        ^^ (Keyboard)  Not accessible through keyboard
31        ^_             Not accessible through keyboard
32        Cancel         [F1]  
33        Search         [F2]
34        Help           [F3]
35        R Indent       [F4]
36        List           [F5]
37        Bold           [F6]
38        Exit           [F7]
39        Underline      [F8]
40        End Field      [F9]
41        Save           [F10]
42        Reserved       [F11]            
43        Reserved       [F12]
44        Setup          [Shift]-[F1]
45        Left Search    [Shift]-[F2]
46        Switch         [Shift]-[F3]
47        L/R Indent     [Shift]-[F4]
48        Date/Outline   [Shift]-[F5]
49        Center         [Shift]-[F6]
50        Print          [Shift]-[F7]
51        Format         [Shift]-[F8]
52        Merge Codes    [Shift]-[F9]
53        Retrieve Text  [Shift]-[F10]
54        Reserved       [Shift]-[F11]
55        Reserved       [Shift]-[F12]
56        Thesaurus      [Alt]-[F1]
57        Replace        [Alt]-[F2]
58        Reveal Codes   [Alt]-[F3]
59        Block          [Alt]-[F4]
60        Mark Text      [Alt]-[F5]
61        Flush Right    [Alt]-[F6]
62        Footnote       [Alt]-[F7]      
63        Style          [Alt]-[F8]
64        Graphics       [Alt]-[F9]
65        Macro          [Alt]-[F10]
66        Reserved       [Alt]-[F11]
67        Reserved       [Alt]-[F12]
68        Shell          [Ctrl]-[F1]
69        Spell          [Ctrl]-[F2]
70        Screen         [Ctrl]-[F3]
71        Move           [Ctrl]-[F4]
72        Text In/Out    [Ctrl]-[F5]
73        Tab Align      [Ctrl]-[F6]
74        Tables/Columns [Ctrl]-[F7]
75        Font           [Ctrl]-[F8]
76        Merge/Sort     [Ctrl]-[F9]
77        Macro Define   [Ctrl]-[F10]
78        Reserved       [Ctrl]-[F11]
79        Reserved       [Ctrl]-[F12]
80        Backspace      [Backspace]
81        Del            [Delete]
82        Delete Word    [Ctrl]-[Backspace]
83        Word Right     [Ctrl]-[Right]
84        Word Left      [Ctrl]-[Left]
85        End            [End]
86        Home-Home-Left Not accessible through keyboard
87        Invalid        Not accessible through keyboard
88        Goto           [Ctrl]-[Home]
89        Page Up        [Page Up] 
90        Page Down      [Page Down]
91        Screen Down    + (on keypad)
92        Screen Up      - (on keypad)
93        Typeover       [Insert]
94        Left Mar Rel   [Shift]-[Tab]      
95        Hard Page      [Ctrl]-[Enter]
96        Soft Hyphen    [Ctrl]- -  
97        {-}            [Alt]--
98        { }            Not accessible through keyboard
99        Para Up        Enhanced keyboard
100       Para Down      Enhanced keyboard
101       Item Left      Enhanced keyboard
102       Item Right     Enhanced keyboard
103       Item Up        Enhanced keyboard
104       Item Down      Enhanced keyboard
105       Alt-Home       Enhanced keyboard
106       Del Word (Row) Not accessible through keyboard
107       Menu Bar       [Alt]-=
108       Block Append   Enhanced keyboard
109       Block Move     Enhanced keyboard     
110       Block Copy     Enhanced keyboard


ALTA - ALTZ for nested/chained macros {ALTA} through {ALTZ}

VAR0 - VAR 9 for variables {VAR 0} through {VAR 9}



Normally, WordPerfect abruptly terminates macro execution when it encounters an error. These messages always appear on the screen, but you may miss them if you're not being attentive (note: "not found" messages are not shown if the display has been turned off).

WordPerfect reports a File Not Found error when it cannot find a file for retrieval. If this error occurs during macro playback, WordPerfect will execute as much of the macro as it can -- up to the point of the error -- and stop. WordPerfect also reports a File Not Found error when it cannot locate the printer driver file originally used to format the document. The document will still open (using the default printer driver), but the error will still occur, causing the macro to stop.

The Access Denied error message occurs, among other instances, when you attempt to save a document into a directory that doesn't exist, or a directory that WordPerfect can't find (did you enter the proper path?).

You can limit WordPerfect's sensitivity to errors by including the {ON ERROR} exception handler command in the macro. By itself, {ON ERROR} will trap errors, but it won't tell WordPerfect what to do when an error occurs. You can indicate a specific course of action by including an action statement following {ON ERROR}, such as


Not all macro statements can be used with {ON ERROR} and special syntax is required when using the {GO} and {CALL} commands. See Chapter 4, "Learning the Macro Programming Language," for more details on using the {ON ERROR} statement.

Note that WordPerfect will always display the error message on the screen, pause for a few seconds, then execute your {ON ERROR} exception routine. There's no way to prevent WordPerfect from displaying this message.

If WordPerfect can't find a document or macro file, you may need to enter a {Cancel} code as one of the first actions in your {ON ERROR} routine. This cancels the filename prompt, and prevents the macro and WordPerfect from chasing each other in an endless loop. Should this happen, try to release yourself from the loop with the Cancel or [Ctrl]-[Break]. If these don't work, you may need to restart your computer.



You may want to know the contents of variable during macro execution. When necessary, you can create "watchpoints" to keep tabs on variable values.

At the end of the macro, enter a prompt routine that lists the variables you've used, such as:

Variable abc: {VARIABLE}abc~  
Variable def: {VARIABLE}def~~

At critical points in the macro, add {CALL}watchpoint~ instructions to temporarily branch off to the prompt. Each time you {CALL} the "watchpoint" the contents of the variables are flashed on the screen (you may want to add a delay so that you can view the variable contents, in case they don't remain on the screen for long).

Remove the watchpoints {CALL}s and routine when the macro has been debugged.



It's often helpful to review a macro in paper form rather than within the meager confines of the macro editing window. At present, WordPerfect 5.1 lacks a means to print the contents of macros (although this capability is provided in the stand-alone ED macro/program editor, available from WordPerfect Corp.).

To make it easier for you to review your macros, the Applications Disk contains a DOS program MACREAD.EXE. This program reads the contents of your macros and creates WordPerfect-format document files. The text appears exactly as it does in the macro. Once converted, you can print the document using your regular printer.


  1. Place a copy of the program it in your macros directory.
  2. Start the program by typing MACREAD at the DOS prompt, and press [Enter].
  3. Enter the name of the macro file without the .WPM extension. You can use upper and/or lower case. If the macro file is located in a directory or disk, include a full path.
  4. MACREAD will read the macro file and copy the code into a WordPerfect document (of course, your original macro file is left untouched). The program indicates the progress and tells you when it's done.

MACREAD names the converted macro file macro.DOC, where "macro" is the name of the macro file you converted. MACREAD doesn't check to see if a file with the same name already exists, so check first before running the program or a file you may want to keep could be over-written.

NOTE: MACREAD reads and converts macro files at the rate of about 1K per second. Longer macro files (say, 8K to 12K in length), may take some time to finish. Be patient, and wait at least 45 to 60 seconds before thinking about pulling the plug.



An adjunct to the MACREAD.EXE macro file reader is MACPROF.EXE (for "Macro Professor"). This program searches through macro files and notes the name used for {LABEL}s, {VARIABLE}s, {GO} and {CALL} statements, {ASSIGN} instructions, and more. The resulting checkpoint file provides a list of this data in document form. The list includes line numbers that correspond with the position of the data within the macro file.

Use MACPROF.EXE in the same manner as MACREAD: Start the program and enter a macro file (no .WPM extension). MACPROF will create an analysis file name named macro.PRO, where "macro" is the name of the macro file you analyzed.

To use the line numbers in your analysis, use MACREAD to produce a documented version of the macro file. Before printing, turn line numbering on, and set the Restart Number on Each Page option to No. Note that you can't see the line numbers until the document is printed, and that the Print View will show the line numbers restarting for every page. However, the document will be properly numbered when it is printed.



The cause of some problems is more obvious than others. Following are possible causes for a variety of obstacles you may encounter as you are creating your own macros.

Beeping Computer

If your computer beeps when its not supposed to during macro execution, the problem may be caused by the block command. WordPerfect does not let you enter text while block is on; the computer beeps as you attempt to enter text. If you've written a macro that turns the block on, you must either complete an action that automatically shuts block off or you must turn it off manually by issuing another {Block} code. You can readily see if block is still on by stopping the macro just after the block code.

You can also test for an active block condition by using the {STATE} instruction. Force the macro to turn off the block by adding this routine:

{GO}rest of macro~
{GO}rest of macro~

Also note that you cannot switch from document screen to document screen when block is on. If you do, WordPerfect will assume you want to change the capitalization of the blocked text.

Quotation Marks and Variable Statements

Quotation marks must be used around {VAR #} and {VARIABLE} statements in {IF} instructions when testing for non-numeric strings. The same rule applies to text strings placed in the {IF} instruction. You must also bracket function and editing key codes with quotation marks. Be sure that you use the quotes in pairs or the macro won't work. Use a separate set of quotes if testing for a text string that already contains quotes.

{IF}{VAR 1}={Enter}~		Won't work 
{IF}"{VAR 1}={Enter}~    	Won't work
{IF}"{VAR 1}"="{Enter}"~ 	Will work 
{IF}"{VARIABLE}text~"="HELLO"~  Will work 

If you forget to add quotation marks to both sides of the variable and text string, WordPerfect will still try to compare the values on both sides of the equals operator, but the result will always be FALSE because a match will never be found.

The same rules apply to expressions used with the {WHILE} command.

Missing {ELSE} and {END IF}

Each {IF} statement must be accompanied by a matching {END IF} statement. The {ELSE} statement, which is optional, indicates what should happen if the {IF} instruction proves FALSE, and the {END IF} instruction marks the end of the {IF} structure. Unless you add the {END IF}, the macro will assume everything after the {ELSE} statement is to be executed when the IF condition proves FALSE.

The instructions to execute when the {IF} condition is TRUE can be placed immediately after the tilde following the {IF} statement, or they can be placed after the {END IF} statement.

Run-On Routines

Special routines and subroutines are normally placed at the end of the macro. That way, they don't get in the way of normal macro execution. If you do not tell the macro to stop, it will execute all the instructions sequentially, and may inadvertently repeat some of the routines. Make it a point to include a {QUIT} instruction immediately before any special routines or subroutines. That prevents the macro from accidentally running them.

Blank Screen

Should a macro seem to come to a lurching stop and display nothing but a blank screen (the *waiting* indicator may remain in the status line as well), it's a good indication that the macro has stopped at a menu with the display off. Unlike the regular document window, WordPerfect doesn't automatically turn the display back on when you finish up at a menu. Rewrite the macro so that you include a {DISPLAY ON} immediately before the menu is accessed.

Halted Execution

If your macro suddenly stops working, but the display is still on, it could be an indication that it is caught in an endless loop. An endless loop is when the macro repeats the same operation over and over again, with no means to stop other than pressing the Cancel key. It is most often caused by a macro looping back on itself at the wrong point. Look for an errant {GO} instruction or a misplaced label.

Missing {RETURN}

The {RETURN} instruction at the end of a subroutine tells WordPerfect to go back to the {CALL} or {CASE CALL} statement. If the {RETURN} is missing, the {CALL} or {CASE CALL} statement may not work at all or the macro may end prematurely.

The {RETURN} instruction is also used as a signal in a nested macro to go back to the main macro. If a {RETURN} is not present, the nested macro will continue execution until it finishes. If you don't want the entire nested macro to run, be sure so include the {RETURN} statement at the appropriate spot.

Search Not Found

Even if the text you want to find is in the document, certain circumstances may cause a search instruction to end with a *not found* message. Unless you trap the *not found* condition with an {ON NOT FOUND} instruction, the macro will stop prematurely, making it even more difficult for you to locate the problem. Keep these pointers in mind when searching through a document with macros.

	Searches for the text "Total"
{Left Search}macro{Search}
	Searches backward through the text for "macro" 


Wrong Variable Numbers/Names

WordPerfect variables may act strangely at times, but if you understand their operation, their behavior is logical. WordPerfect's variables can accept any alphanumeric entry. When you enter a whole number into the variable, you can then perform some basic arithmetic with it. For example, if variable 1 contains the number 10, and variable 2 contains the number 15, you can add them together in a macro, such as:

{ASSIGN}3~{VAR 1}+{VAR 2}~

The total of {VAR 1} and {VAR 2} (25) is entered into variable 3. Pressing [Alt]-3 after running the macro prints the number 25.

However, if you enter a fractional number into a variable, WordPerfect no longer treats it as a number, but as text. If you enter 13.5 into variable 1 and 17.8 into variable 2, the result is not 31.3 but "13.5+17.8." WordPerfect converts the decimal numbers into text, and since it cannot add two pieces of text together, it also displays the plus sign as part of the string.

Variables have certain limitations, the most important of which is that they cannot accept more than 128 characters each (the actual character limit depends on how the variable was assigned, as detailed in Chapter 5, "Making More of Macros." Chapter 5 also provides other insights on the use and application of variables, including the maximum values that can stored.

Macro Not Found

Nested and chained macros can show up missing is they have been sequestered onto another diskette or tucked within some far-away subdirectory. You have three choices to remedy the situation:

  1. Move the macro so that its on the current drive and directory.
  2. Rewrite the macro so that it can find the file it needs to complete its task.
  3. Put the macro in a MACROS directory, and update the Location of Files option (under the Setup key) so that WordPerfect will know where to find macro files.

Nested and chained macros may also not be executed if you misspelled their name. Double check the spelling of the macro name. WordPerfect assumes the .WPM file extension in {NEST}, {CHAIN}, and {Macro} instructions, so you don't need to add it yourself.

There are actually several ways to chain and nest macros, and if you are the forgetful type, you may use the wrong procedure.


Garbled Screen

If the screen is garbled during macro execution, or even after the macro finishes, you need to do a little housekeeping to get everything back into order. The usual cause is a {TEXT}, {CHAR}, {PROMPT}, {INPUT}, or {STATUS PROMPT} message drifting off with the rest of the document (the message is not a permanent intruder, but it looks terrible and cause unwary users some unneeded heartache).

To keep the screen clear, temporarily turn the display off, then turn it back on again using {DISPLAY OFF}{DISPLAY ON} or {Screen}{Screen}. The screen will flash very quickly.

Macros that change the margins or push the cursor beyond the normal boundaries may slide some text off the screen. This is natural, but it can be disconcerting if you're not expecting it. There isn't much you can do because it is a normal operation of WordPerfect and has nothing to do with macros. You can alleviate the problem of cropped text by using an EGA or Hercules mono-graphics boards that displays more than 80 characters across the screen. Be sure to use the proper display drivers with these boards or WordPerfect will continue to display the standard 80 character screen.

Some Keys Don't Always Work Right

WordPerfect's key remapping feature is a great boon to power users, but can cause problems to the uninitiated. Because you can change the definition of any key, you run the risk of altering the definition of some keys critical to the operation of macros. For example, let's say you've switched the definition of Reveal Codes and Help. [F3] becomes [Alt]-[F3] and vice-versa. You faithfully accommodate the change in the macros you write.

Now suppose you share your macros with someone else who has WordPerfect, but this person hasn't changed the definition of the Reveal Codes and Help keys. The result? The macro doesn't work or it behaves erratically. The moral: If you plan on sharing macros, avoid using redefined keys whenever possible. If it can't be avoided, include the key layout file with your macros and have the layout file automatically load when the macro is executed.

Of course, you are not immune from the effects of your own key reassignments. If you've reassigned some the the control keys to operate as WordStar cursor keys, then you won't be able to access the control key characters when editing macros and in some other applications. WordPerfect uses [Ctrl]-E to move the cursor up, so you redefine it as {Up}. If you try to use [Ctrl]-E to insert a WordPerfect 5.0 ^E merge code, for instance, the ^E character doesn't appear; it moves the cursor up a line.

In short, if you want to use reassigned keys for their intended purpose, turn any key reassignments off (select "Original" in the Keyboard Layout menu, or press [Ctrl]-6 anywhere within WordPerfect).

Macros and Merges

WordPerfect 4.2 had an annoying habit of stopping macro execution when you started a merge. Happily, that limitation is fixed in WordPerfect 5.1 (as it was in 5.0, as well). But be forewarned that although you can execute a macro and a merge simultaneously, you cannot define a macro and a merge at the same time. Starting a merge operation while defining a new macro from the keyboard immediately stops macro execution. If you want to include the instructions for a merge, you must do so within the macro editor.

Missing or Bad WP.MRS File

WordPerfect uses the WP.MRS file to help decode macros for editing. If the WP.MRS file is missing, or you're using a file that went with an earlier release of WordPerfect, the program will report a File Not Found error, or indicate that the macro file you're trying to edit uses an incompatible format. Be sure the correct WP.MRS file on the current drive and directory with the WP.EXE program file, and try again. A similar file, KEYS,MRS, serves as a resource file for the keyboard layout editor.

Sluggish Performance

Because WordPerfect has so many features, some of its operations tend to be slower than they ought to be. This is especially true of search and sort operations, and is apparent in a number of macros. And, some macro commands -- especially {MID} and {FOR} -- require extra computing power to operate swiftly. For best results, WordPerfect should be used on a "turbocharged" AT running at a speed of no less than 8 MHz; 10 to 12 MHz is even better. Performance increases when the program is used on faster computers using the 80386 and 80486 microprocessor.

Macro Quits When it Encounters {ON xxxxx} Trap

Your macro will quit unexpectedly if it encounters an {ON NOT FOUND}, {ON CANCEL}, or {ON ERROR} exception handler that:

Remember to use two tildes if you are {GO}ing or {CALL}ing a special routine for your exception handler, as in

{ON NOT FOUND}{GO}not_found~~

When WordPerfect encounters an exception handling instruction that branches off to another label, it always checks to see if the label exists before proceeding with the rest of the macro. The exception handler doesn't have to be invoked before the macro breaks down. If you have included an exception handler at the beginning of the macro, and the macro quits at the onset, check that the label names match.

Macro in Cache

WordPerfect always tries to keeps at least the last macro it has run in cache memory, so that if you use the macro again, it can be retrieved from RAM, and not from the disk. This is normally a good feature, except under certain circumstances.


Out of Memory

WordPerfect will warn you if a macro you're trying to edit is too big to fit in the macro editing window. But the program offers no such out of memory warning when running the macro. If your macros are behaving unusually -- stopping when they shouldn't -- keep an eye out for shortage of memory. A macro that uses many variables is quick to consume lots of memory.

Take one or more of these steps to free up memory for your macros:

  1. Clear one of both document windows.
  2. Turn off the current keyboard layout, if any.
  3. Restart WordPerfect with the /R switch, if your computer has enough expanded memory for it.
  4. If you are using Shell, start WordPerfect without it.
  5. Temporarily quit WordPerfect and restart; this clears named variables that were created when executing previous macros, but are no longer needed.



This chapter discussed debugging WordPerfect macros. You learned:

	{IF}"{VARIABLE}text~"="hello there"~ 


 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.