Chapter 5

MAKING MORE OF MACROS

The WordPerfect macro language is abundant with features and capabilities that go beyond a first cursory look. Included in the macro language is a set of codes that let you control the look and placement of on-screen messages. WordPerfect provides a number of internal control codes that represent menus, font attributes, special WordPerfect characters, and much more.

In this chapter you'll learn many of the finer points of WordPerfect macro codes. You'll learn how to:

 

MACRO LEVELS

Macros have many levels of execution. Levels are an important consideration when using the {NEST}, {CALL}, and {CASE CALL} commands introduced in Chapter 4. With each of these commands, the macro temporarily suspends normal operation and executes either another macro (as in the case of the {NEST} command), or executes a special subroutine within the same macro (these functions are performed by the {CALL} or {CASE CALL} commands). When the nested macro or subroutine finishes, macro execution continues where it branched off.

You can think of the levels of execution as the levels in an underground parking garage. The top level marks the main macro. When the macro branches off to a subroutine (using the {CALL} and {CASE CALL} instructions), WordPerfect steps down a level. After the subroutine is over, WordPerfect drives back up to the top, main level.

The same thing happens when you branch to a nested macro using the {NEST} command. While executing the main macro, WordPerfect is at the top level. When the program branches off to the nested macro, it goes down one level. Conversely, when WordPerfect returns from the nested macro, it goes back up to the top level.

WordPerfect supports up to 30 levels of macro execution. That is, you can go down 30 levels before bottoming out. This allows you to use {CASE}, {CASE CALL}, and {NEST} commands before the macro has a chance to return to the first level. Here's an example: 

LEVEL 1    
	LEVEL 2
		LEVEL 3
	LEVEL 2
LEVEL 1

Here, LEVEL 1 is the main portion of the macro. The macro then branches from LEVEL 1 to LEVEL 2, then to LEVEL 3. When the macro has executed all the commands in LEVEL 3, the macro returns to LEVEL 2, and finally ends up in LEVEL 1. Used in this way, you can construct macros that go all the way to a level 30. You probably won't ever create a macro that operates this way, but it's good to know that it can be done, in case you ever need it.

Each {CALL} or {CASE CALL} subroutine represents one level of execution. That means you can nest subroutines up to 30 deep. Each nested macro represents two levels of execution -- one level for nest and another for a possible {CHAIN} command -- so you can nest macros only 20 deep.

Remember that you can use as many {CASE}, {CASE CALL}, and {NEST} commands in a macro as you want, as long as you don't exceed the 30 level limit. If all your subroutines return to LEVEL 1 before the macro begins another subroutine, you could have literally hundreds of {CASE} commands, and never exceed the 30 level limit.

Other macro commands also take up a level of macro execution. Nested {IF}, {FOR}, {FOR EACH}, and {WHILE} commands each take up one level. The concept of levels is an important one because some of WordPerfect's programming instructions are level sensitive. For example, if an error occurs in a lower level subroutine or nested macro, WordPerfect reports the error to the next higher subroutine or macro. There, the program hopes to find a command that tell sit what to do if an error occurs. If no command can be found, all macro execution stops.

 

CONTROL CHARACTERS

WordPerfect macros provide a number of display control characters that may be placed inside {CHAR}, {PROMPT}, {TEXT}, {INPUT}, and {STATUS PROMPT} messages. These control characters are used to:


Moving the Cursor for Message Display

Normally, text displayed with the {CHAR}, {TEXT}, {PROMPT}, {INPUT}, and {STATUS PROMPT} commands appears at the bottom left corner of the screen -- or line 25.

Several of the control codes are used to move the cursor so that text can be displayed anywhere on the screen. If the control code is placed at the beginning of the message text, then the message appears at that spot. If the code is placed at the end, then the cursor alone appears there. Of course, you can place cursor-movement control codes anywhere within the message text. The text following the code will be placed according to the code you used.

Use the following codes to control the placement of message text.

{Home}
Starts the text or positions the cursor at the upper left corner of the screen.
{Enter}
Starts the text or positions the cursor on a new line.
{Del to EOL}
Deletes previous message to the end of the current line.
{Del to EOP}
Starts the text at the upper left corner of the screen, AND temporarily hides all document text on the screen.
{^P}
Starts the text or positions the cursor at a specific row/column intersection. See "Using the {^P} Code," below, for more information.
{Up}
Starts the message or positions the cursor up one line.
{Down}
Starts the message or positions the cursor down one line.
{Right}
Starts the message or positions the cursor right one character.
{Left}
Starts the message or positions the cursor left one character.

IMPORTANT NOTES: Keep these points in mind:


Changing the Appearance of Message Text

If you're not satisfied with the normal appearance of message text, you can change its attributes with the following commands. Options include underline, bold, and blink.

{^N}
Turns on display attribute (see "Font Attribute Characters," below). Follow with a display character.
{^O}
Turns off display attribute. Follow with a display character.
{^Q}
Turn off all display attributes started with the {^N} code.
{^R}
Turns on reverse video.
{^S}
Turns off reverse video.
{^T}
Turns on underline.
{^U}
Turns off underline.
{^V}
Turns on mnemonic attribute.
{^]}
Turns on bold.
{^\}
Turns off bold.
 

Keep these points in mind:

 

USING THE {^P} CONTROL CODE

The {^P} control code allows you to position the cursor and place a message at any spot on the screen. You can use {^P} in messages displayed with the {CHAR}, {TEXT}, {PROMPT}, {INPUT}, and {STATUS PROMPT} commands. Along with the {^P} code, you enter two characters that indicate the column (character position) and row intersection where you want the cursor to be placed. The characters follow general ASCII or WordPerfect function key format: to place the cursor at column 5 and row 5, for example, you enter an {^E} code, or an <<ASCII 5 character>>. Both are equal to five.

To enter any ASCII character, press and hold the [Alt] key, then type the corresponding number on the numeric keypad (not the number keys on the top of the keyboard). Or, you can use the Compose ([Ctrl]-2 key) if your computer doesn't respond to the [Alt]-keypad method.

WordPerfect function keys, which include all control characters, function key codes, and editing key codes, can also be used. The problem with WordPerfect function keys is that they make the macro look messy when you view and edit it using the program's built-in macro editor. And several function numbers -- notable 30 and 31 -- are not directly accessible through the keyboard.

Note that to WordPerfect, the very top left corner of the screen is column 0, row 0. There's no ASCII 0, so you have to cheat a little. There are several alternatives, as discussed in Chapter 18, "Macro Strategies."

The {^P} control code is used often in the working macros presented in Part Two of this book. One of the more outstanding uses of the {^P} code is to create "pop-up" windows and macro menus. See Chapter 9 for details on creating menus using macros.

 

FONT ATTRIBUTE CHARACTERS

These special font attribute characters can be placed after the {^N} Display On code (see above). To cancel an attribute characters, enter the {^O} code, then the character you want shut off. Note that most of these font attribute characters require Hercules Graphics Card Plus with RamFont or a Hercules InColor Card with RamFont (or equivalent) to show on-screen fonts.

The appearance of font attributes depends on the current display settings, as defined under the Setup menu. The font attributes will appear on the screen only if they have been properly set under the Setup menu. If you are using a color display, the font attributes may appear as text in a different color, or with a different background.

{^A}
Very large text.
{^B}
Large text.
{^C}
Small text.
{^D}
Small print text.
{^E}
Superscript text.
{^F}
Subscript text.
{^G}
Outline text.
{Home}
Italics text.
{Tab}
Shadow text.
{Enter}
Redline text.
{Del to EOL}
Double underline text.
{Del to EOP}
Bold text.
{^M}
Strikeout text.
{^N}
Underline text.
{^O}
Small caps text.
{^P}
Blink text on and off.
{^Q}
Reverse video text.
 

Keep these points in mind:

 

UNDERSTANDING VARIABLES

As you learned in Chapter 4, "Learning the Macro Programming Language," WordPerfect variables are temporary holders of information. A variable can hold numbers, text, WordPerfect function codes, and expressions.

Placing number, text, codes, and so forth in a variable is often referred to assigning, or assigning a value to a variable. When you see a phrase such as, "Assign the value of 10 to variable number," you know that it means to store the number 10 in a variable referred to as "number."

The contents of the variables are erased when you reassign them with a new value. All variables are lost when you exit WordPerfect.


Numbers as Variables

A WordPerfect variable can store any whole number from -2,147,483,647 to 2,147,483,647. This numbering system "wraps" around, so that 2,147,483,648 (one more than the highest value allowed) is actually treated as -2,147,483,648. While this may appear a strange way of doing things, the method isn't entirely madness.

WordPerfect uses signed integers, and actually works only with positive numbers. The positive numbers it can accommodate range from 0 to 4,294,967,295. Numbers between 2,147,483,648 and 4,294,967,295 are treated as negative numbers. Therefore, when you enter 2,147,483,648, WordPerfect understands it as a negative number, and places a minus sign in front of it. As you increase the value -- up to the maximum 4,294,967,295 -- the negative number gets smaller.

Note that WordPerfect variables can contain whole numbers only, and that the numbers must not contain any non-numeric characters. The following are not considered numbers by WordPerfect macros, or will cause a different result than what you expect:

2873.009 

is treated as

2873

The numbers to the right of the decimal point, and the decimal point itself, are ignored. The one non-numeric character you can include is the minus sign (-). This tells WordPerfect that you want to treat the number as a negative.

Variables that contain numbers can be used in math computations.


Text as Variables

Text is any collection of assorted characters. WordPerfect understands the variable contains text if at least the first character is non-numeric (exception: the minus symbol). Examples of text that can be stored in a variable:

Variables that contain text cannot be used in math computations.


Function Codes as Variables

From within the WordPerfect macro editor, you can assign any function code, such as {Enter}, {Tab}, {Help}, and so forth, to a variable. Stored in a variable, these codes do the same thing they'd normally do within WordPerfect. Examples of codes used in a variable:

In the first example, retrieving the contents of the variable prints two tab spaces, the text "My name is Mudd," and enters a new line. In the second example, the variable prints the text "You asked for help, here it is...," then waits for 1.5 seconds before actuating the help command. The third example moves the cursor to the right 15 spaces. Note that, as shown in the second example, you can also store WordPerfect macro commands in variables. This provides for some extremely powerful capabilities, as you'll see throughout this book.

Used in this fashion, variables become "mini-macros" that can store any assortment of text, WordPerfect codes, and macro commands you like. However, variables can only hold a certain number of characters, as detailed below, so you are limited to creating short variable-macros only.


Expressions as Variables

An expression is a procedure, usually a mathematical formula, that the macro must complete before continuing. A good example of an expression is the simple formula:

2+2

Put this formula in a variable, and when the macro is run, WordPerfect calculates (or evaluates) it and comes with the answer, 4. While you may have entered the formula "2+2" into the variable, WordPerfect treats it simply as the number "4."

WordPerfect can use both text and numbers in expressions, as you'll see later in this chapter. Numbers can be used in numeric expressions (such as "2+2"), and text can be used in boolean, or TRUE/FALSE expressions.


Variable Types

We mentioned this in Chapter 4, but it bears repeating here. WordPerfect has three types of variables: numbered, named, and internal. You can't control the contents of internal variables, but you can access them to see what they hold. This allows you to take a peek at what WordPerfect is doing at any particular moment. You can assign numbers, text, codes, and expressions to both numbered and named variables. Although we make the distinction between numbered and named variables, you work with them both in much the same way.

WordPerfect allows you to store up to 10 numbered variables. At WordPerfect's main editing screen, you can access ("play back") the contents of the variables by pressing the [Alt] key and a number key. For example, to retrieve the contents of variable 4, press [Alt]-4.

WordPerfect allows you to store an almost unlimited number of named variables. The maximum number of variables you can store depends on their contents and available memory. WordPerfect doesn't offer a direct means to access named variables from the keyboard as you can with numbered variables. The main use of named variables is to hold scraps of information needed for the operation of a macro. For example, you may need to keep track of the number of times the user presses the Enter key. That number is hardly useful to the user, but you track it because the macro depends on it for some special function.

 

ASSIGNING VARIABLES

You can assign a value to one of WordPerfect's variables in either of four ways:

From the Keyboard

While you're writing and editing within WordPerfect, press [Ctrl]-[Page Up] (the Macro Commands key) and you are prompted for the variable number or name. To enter a number, press one of the number keys, then press [Enter]. To enter a name, type the name, and press [Enter]. You are then prompted for a value. The value can be letters, numbers, or both. Press [Enter] when you are done. If you're created a numbered variable, you can play back the contents of the variable by pressing [Alt] and the variable number.


Within the Macro Editor

Use the {ASSIGN} programming statement as detailed in Chapter 4. For example, to assign the number "1000" to variable 1, you'd enter

{ASSIGN}1~1000~

Or to assign the text "WordPerfect" to variable name, you'd enter

{ASSIGN}name~WordPerfect~ 


Defining a Macro From the Keyboard

If you're currently defining a macro from the keyboard (as opposed to writing it within the macro editor), press [Ctrl]-[Page Up]. WordPerfect displays the message:

1 Pause; 2 Display; 3 Assign; 4 Comment 

Press 3 or A to select Assign, then enter a variable number or name. Press [Enter] when you're done. Enter a value, then press [Enter] one more time. If you later examine the macro you made, you will see that WordPerfect automatically added the {Macro Commands}Avalue statement.


Transferring Blocked Text

If you'd like to assign text already written in a WordPerfect document, block the characters you want to include in the variable. Now press [Ctrl]-[Page Up] and enter a variable number or name. Finish by pressing the [Enter] key. The contents of the block is automatically transferred to the variable.

NOTE: Most codes in a block are ignored and not passed to the variable. The exceptions are Right Indent, Hard Return, Hard Page, and Hard Hyphen. Soft Returns are converted to spaces and Soft Pages are converted to either Hard Returns or spaces.


And Yet Another Way...

In addition to the four techniques outlined above to enter a value into a variable, WordPerfect also allows you to assign a value to a variable in response to a {TEXT} or {CHAR} message. The {TEXT} and {CHAR} commands display a message on the screen, and enters the user's reply in a designated macro. For instance,

{TEXT}text~Type your name here~ 

displays the message "Type your name here" and stores the reply in variable text. The {TEXT} command is designed to allow multiple keystroke replies. It terminates when the user presses the [Enter] key. The {CHAR} command is designed to allow just one keystroke for the reply. There's no need to press [Enter] after answering the message.


A Simple Experiment

To experiment with variables, try the following:

Key Sequence What it does
1. [Ctrl]-[Page Up] Invokes variable assign function.
2. 1 [Enter] Selects variable 1.
3. Macros are neat!! Enters the phrase "Macros are [Enter]neat!! into the variable.

To play back the variable, press, [Alt]-1. WordPerfect will spill out:

Macros are neat!!

on the screen.


Length Constraints

One limitation of WordPerfect macro variables is that let you store a maximum of 129 characters. The actual maximum number of characters depends on how you've assigned the variable:

Procedure Max Characters
From the keyboard (using [Ctrl]-[Page Up]) 79
While defining a macro ([Ctrl]-[Page Up]) 79
Transferring blocked text ([Ctrl]-[Page Up]) 128
Within the macro editor (using {ASSIGN}) 128
Answering a {TEXT} message 129
Answering a {CHAR} message 1

Tip: WordPerfect considers each function key code and macro command as a single character. You can blend any combination of text, codes, and commands in a variable, as long as the total length doesn't exceed the maximum allowed by WordPerfect.

WordPerfect ignores any extra characters beyond the bounds stipulated in the previous table, with one exception. If you attempt to assign a variable with more than 128 characters using the {ASSIGN} command, WordPerfect ignores all the characters.

 

CREATING EXPRESSIONS

Operators form the basis of WordPerfect macro expressions. An operator tells WordPerfect what you want to do with the numbers or text or text you've provided. In WordPerfect macros, expressions can be used within variables, or they can be part of a more elaborate scheme using other macro commands. These commands are:

Most of the operators work with numbers only, but some can also be used with text. WordPerfect supports the following operators. In all cases, you may substitute the values (identified as v1 and v2) as variables, as described below. Remember that WordPerfect cannot store numbers in variables larger than 2,147,483,647 or smaller than -2,147,483,648.

!value
Evaluates the logical NOT of value. The logical NOT is the binary equivalent of the numerical value inverted -- 0's become 1's and vice versa.
-value
Treats the value as a negative number.
v1+v2
Adds values v1 and v2 together.
v1-v2
Subtracts value v1 from v2.
v1*v2
Multiplies values v1 and v2.
v1/v2
Divides values v1 and v2. The result is a whole (integer) number.
v1%v2
Divides values v1 and v2. The result is the remainder.
v1&v2
Evaluates the logical AND of v1 and v2.
v1|v2
Evaluates the logical OR of v1 and v2.
v1=v2
Test that v1 and v2 are equal.
v1!=v2
Test that v1 and v2 are not equal.
v1>v2
Test that v1 is greater than v2.
v1<v2
Test that v1 is less than v2
 
 

True/False Operators

The =, !=, >, and < symbols are known as TRUE/FALSE operators. They test that the values on either side of the operator is equal, not equal, greater than, or less than one another. As with many computer languages, WordPerfect uses numbers to denote the TRUE and FALSE conditions. When a macro evaluates an expression such as:

1000<1001 

it uses numbers to indicate whether the result is TRUE or FALSE. If the result is TRUE (which in this case, it is), WordPerfect returns a value of -1. If the result is FALSE, WordPerfect returns a value of 0.

The values of -1 and 0 are of little concern to you, because you aren't likely to see them. Rather, WordPerfect uses the numbers returned by TRUE/FALSE expressions in conditional statements and branching. If the values are TRUE, one thing happens. If they are FALSE, another thing happens.

You can test the way WordPerfect handles TRUE/FALSE comparisons by entering some values and an operator in a variable. You can do it directly from the keyboard:

Key Sequence What it Does
1. [Ctrl]-[Page Up] Activates keyboard variable assign.
2. 1 [Enter] Indicates you want the expression stored in variable 1.
3. 1000<1001 Enters the expression 1000 is less than 1001.
4. [Enter] The variable is assigned.

When you press the [Alt]-1 keys to retrieve the value of variable 1, you get -1 instead of 1000<1001. WordPerfect evaluated the expression, and returned a result of -1, or TRUE. Repeat the process, this time entering 1000>1001. The result is FALSE, so WordPerfect returns a 0.

Remember this when assigning values to variables. You may think you're entering a character string, such as 1000<1001, but WordPerfect will think you want to evaluate the numbers.


How to Use AND and OR Operators

Most people freak when they encounter the logical AND and OR operators. You may have used similar operators with WordPerfect's sort feature. Well, the variable AND and OR operators are not the same, so don't try to figure out their use based on your experience with sorting.

The variable AND and OR operators work with numbers only, but they can also be used in more complex TRUE/FALSE expressions, as detailed in Chapter 18, "Macro Strategies." Normally, when you include the AND and OR operators with text, WordPerfect just treats the whole expression as text. Here's an example:

{ASSIGN}1~This~
{ASSIGN}2~That~
{ASSIGN}3~{VAR 1}&{VAR 2}~

Run the macro and display the contents of variable 3 (press [Alt]-3. The result is This&That. But put "9" in variable 1 and "14" in variable 2, and you get 8. How? Good question. The answer isn't probably anything you'd use in day-to-day macros, but it can helpful -- if you plan on being a macro wizard -- to understand how ANDing and ORing work.

Consult the following table for truth tables. Notice what happens when you AND two binary digits together. Only when both digits are a "1" does the result equal 1. All other instances the result is 0. With the logical OR expression, the output is 0 when both input digits are "0." In all other instances, the output is 1.


AND Truth Table

Input A Input B Output
0 0 0
0 1 0
1 0 0
1 1 1


OR Truth Table

Input A Input B Output
0 0 0
0 1 1
1 0 1
1 1 1

To visualize how WordPerfect come up with a result of 8 when it ANDed the numbers "9" and "14" together, you have to reduce those numbers to their binary equivalent.

Decimal Number Binary Equivalent
9 1001
14 1110

Using the truth table in Figure 5-9, above, as a guide, manually compute what happens when you AND these two numbers together.

	1001  =  9 
	1110  =  14
	____   
    AND 1000  =  8 

Not surprisingly, binary 1000 is equivalent to decimal 8. Using the same numbers, perform an OR computation.

	1001  =  9
	1110  = 14
	____
    OR  1111  = 15 

For your reference, here are the binary equivalents of the first 16 numbers (counting zero as the first digit, and ending with 15). You can count higher by adding an extra 1 or 0 digit on the left. The extra digit increases the count by a power of two -- 31, 63, 127, 255, 511, 1023, etc.

Decimal Number Binary Equivalent
0 0000
1 0001
2 0010
3 0011
4 0100
5 0101
6 0110
7 0111
8 1000
9 1001
10 1010
11 1011
12 1100
13 1101
14 1110
15 1111

How can this stuff possibly come in handy? The first and foremost application of the AND and OR logical operators is to test for a specific condition of operation using the {STATE} command (see {STATE} Chapter 4, "Learning the Macro Programming Language"). The syntax to use is:

{STATE}&value to check

Some examples to prove it:

	{STATE} = 4 (0100)   
	Check Value = 4  (0100)    
	0100  {STATE}
	0100  Check Value 
	____ 
	0100  = 4

	{STATE} = 4 (0100)   
	Check Value = 8  (1000)    
	0100  {STATE}
	1000  Check Value 
	____
	0000  = 0

You can also use ANDing and ORing to perform scientific or numerical analysis. If you don't mind sitting down and doing some thinking, you can even have WordPerfect perform complex comparisons of numbers that represent either numerical or textual data. Even circuit board analysis is not far off. These advanced applications are not the main thrust of this book, so we'll leave the topic as it stands.


The NOT Operator

The NOT operator has limited use in WordPerfect macro expressions, but it's included in case you ever need it. The NOT operator inverts the binary form of a number. If the number is 15, the binary form is

1111 

When inverted with NOT, the result is

0000

You can use the NOT operator by itself to invert numbers.

Expression  Meaning
1000!=1001  1000 is not equal to 1001
1000!<1001  1000 is not less than 1001
1000!>1001  1000 is not greater than 1001

Used in this fashion, the NOT operator acts as a negative logic symbol. While every expression can be written so that you test for some positive logic (such as "value 1 is equal to value 2"), but some operations are best performed by using negative logic. One of the most powerful uses of the NOT operator is in IF and WHILE loops to test that a particular key has been pressed. For example,

{WHILE}"{ORIGINAL KEY}"!="{Enter}"~
	Perform some action
{END WHILE}

This this example, the macro repeats the routine "Perform some action" until you press the [Enter] key. Without the NOT operator, you'd have to test for all the other keys that could be pressed. As WordPerfect recognizes several hundred unique keys, testing for each one would lead to cumbersome and unworkable macros.


Working With Text

In many programming languages, a value is a number, and a string is some sort of text. In WordPerfect macro parlance, the terms value and string are used more loosely. A string can actually be any assortment of characters, function codes, or macro commands, but it is most often text. When you see the term "string" used in this book, you can assume it means text, unless you're told otherwise.

When you are comparing non-numeric strings, including but not limited to text, enclose the values in quotation marks. This rule applies to all macro commands except {CASE} and {CASE CAll}. For example: "text1"="text2" checks to see if the text of text1 is equal to the text of text2. Remember that WordPerfect treats all keys on the keyboard (except numbers) as text. This includes the Tab and Enter keys. So if you're checking to see if the user has press the Tab key, the tab code, {Tab}, must also be enclosed in quotes.

WordPerfect variables are case sensitive, so the strings must match exactly.

Examples:

String 1	String 2	Result
hello   	hello		Match
Hello		hello		No Match  
HELLO		hello		No Match


Multiple Operators

WordPerfect can handle many operators in each expression. Unlike version 5.0 of WordPerfect, 5.1 does let you add three or more variables together or string them along in a complex math statement, such as v1+v2/v3*v4. If you're doing math computations, only one number in the expression can be equal to or larger than 65535.

You also must be careful of "order of precedence," the order in which WordPerfect evaluates a formula. Like many programming languages (and electronic spreadsheets), WordPerfect doesn't merely start at the left side of the formula and calculate to the other side. Rather, it calculates multiplication and division first, then addition and subtraction, and so forth. Here's the order in which WordPerfect evaluates an expression: 

Order 	Operator	Meaning
1	-		Unary minus; a negative number
	+     		Unary plus; a positive number
	!     		NOT
2	*		Multiply
	/     		Divide
	%     		Modulus
3	+		Addition
	-		Subtraction
4	<		Less than
	>		Greater than
	=		Equal to
	!=		Not equal to
5	&		AND
	|		OR

Here are some examples:

Expression   Result
15+98-34     79
76*12-65/2   880
15-15%15     15
2*4*6-2      46

WordPerfect doesn't distinguish between operators on the same level or precedence. If it encounters a + for addition and a - for subtraction, it will evaluate the expression by the first operator it encounters, going from left to right.

You can specify another calculation order by using parenthesis. Values and operators inside the parentheses are evaluated first. You can write complex expressions using parentheses inside other parentheses. WordPerfect always starts at the inside-most parentheses, and works outward, such as

2*((41+2)/21) 

This expression is evaluated as follows:

  1. Add 41 plus 2
  2. Divide the result obtained in step 1 by 21.
  3. Multiply 2 by the result obtained in step 2.

The answer is 4.

 

USING INTERNAL SYSTEM VARIABLES

WordPerfect sports its own internal variables. These variables communicate some facet of WordPerfect's operating condition. System variables are read-only; you can access them, but you can't change them (unless, of course, you change the actual operating condition of WordPerfect). WordPerfect controls the contents of its system variables, depending on what it's doing.

There are two categories of internal system variables: those accessed with the {STATE} command those accessed with the {SYSTEM} command.

The {STATE} command returns a single number. {STATE} is not used with an argument, because when you use it, WordPerfect adds up all the operating conditions currently active or turned on, and provides a total result. As mentioned in Chapter 4 and earlier in this chapter, you can use the & operator to isolate, or mask, the specific operating condition you're looking for. For instance, to test if WordPerfect is presenting a Yes/No prompt, you'd enter

{STATE}&1024 

To be useful, you'd use the {STATE} command in a variable, IF construction, or WHILE loop. As used in an IF construction,

{IF}{STATE}&1024~
	Yes
{ELSE}
	No
{END IF}

If a Yes/No prompt is presented, the expression {STATE}&1024 yields 1024, and the result is TRUE (any number other than 0 is considered TRUE by WordPerfect). The macro prints the word "Yes." If a Yes/No prompt is not presented, the expression yields 0, and the result is FALSE. The macro prints the word "No."

The {SYSTEM} commands needs an argument to work. At present, there are 25 unique variables you can access with the {SYSTEM} command. You can use the name of the system variable, such as "Attrib," or its corresponding number, in a macro. Here's a summary list of the {SYSTEM} variables that are available, and what they do.

Number  Name	   Notes 
1	Attrib	   Displays document codes of item to right of cursor.
2	Cell	   Current cell, in tables  
3	Column     Column number in column or table 
4	Document   Document status.
5	Endnote    Endnote number 
6	Equation   Equation number
7	Figure     Figure number
8	Footnote   Footnote number 
9	Left       Character or code to the left of the cursor 
10	Line       Current line position, in 1/1200" 
11	List       Number of items in a list.
12	Name       Document name (when document is saved only) 
13	Menu       Current menu number 
14	Page       Current page number 
15	Path       Current path (when document is saved only) 
16	Pos        Current cursor position 
17	Print      Print status
18	Right      Character or code under the cursor 
19	Tablebox   Table box number.
20	Textbox    Text box number.
21	Userbox    User box number.
22	Row        Row number, in tables.
23	CellAttr   Attributes of the current cell.
24	CellState  State of the current cell.
25	ShellVer   Detects version number of Shell, if present. 

The values returned by many of the {SYSTEM} variables are raw numbers, and may not mean too much to you if you were to just display them. In a macro, however, you use these numbers to test for a certain condition. For example, the Document variable returns the current status of the document. If the document is empty and has never contained text, the value returned is 256. If the document has been saved and not altered, the value returned is 4. Other values are returned, depending on additional document status parameters, as detailed in Appendix C, "WordPerfect Codes."

In a macro, you can test for a certain condition using a value returned by the {SYSTEM} command. If you need to check if a document screen (Doc 1 or Doc 2) is empty, you'd write something like:

{IF}{SYSTEM}document~=256~
	...do this if true...
{ELSE}
	...do this if false...
{END IF}

If the document screen is empty, the macro performs the "do this if true" routine. Otherwise, the macro performs the "do this if false" routine.

 

SYSTEM FUNCTION VALUES

WordPerfect is number oriented. It assigns numbers to keys, characters, and codes so that it can better track what's going on. By using numbers (or values), it's easier to adapt WordPerfect to other languages, and to update the program from time to time.

Many of the {SYSTEM} variables, discussed above, return a unique number that represents a character, code, or operating status of WordPerfect. For instance, the Menu variable returns a unique number, depending on the menu currently displayed on the screen (see Appendix C for a full list of all menu numbers used in WordPerfect). WordPerfect doesn't know the menu by name or function, but by number.

Likewise, embedded format codes, like [BOLD], [Style On], and [Header] carry with them unique function numbers. The Right and Left variables (see above) display the character or code to under or to the left of the cursor, respectively. If the cursor is resting on a formatting code, for example, the Right system variable will return a unique number that represents the code, not the actual code itself.

System function values are an advanced topic, and are more fully discussed in Chapter 19, "For Pros Only: Advanced Techniques," but you should know of their existence now. If you use the Right or Left system variables, for example, and you encounter some unusual numbers, you know it's not WordPerfect going on the fritz. There is a legitimate purpose of the numbers, and although you may never have a use for them in the average macro you create, it's good to know what they mean.

 

IMPORTANT TOPICS

This chapter discussed some advanced topics of macro programming. You learned about macro execution levels, special codes you can insert in display messages, and the nitty-gritty of WordPerfect variables. To recap:

---

 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/