ÛADVANCED MACROS With the Macros feature, you can create and edit macros using a programming language. Macro programming is done in the Macro Editor. You can also do limited programming from the editing screen. The programming commands are accessible through the Macro Commands feature. MACRO EDITOR The Macro Editor allows you to view the individual commands (keystrokes) of your macro. You can edit existing macros, create new ones, and insert programming commands to create complex macros. Each command is displayed in braces { }. Characters and numbers appear as they normally do. The Macro Editor requires that you enter the name of a macro that already exists. If you want to create a new macro, you must first create it with Macro Define (Ctrl-F10). Simply press Ctrl-F10, enter the macro name and, optionally, a description, then press Ctrl-F10. You are now ready to enter the Macro Editor 1 Press Macro Define (Ctrl-F10) and enter the name of a macro that already exists. 2 Select Edit (2) to enter the Macro Editor. The Macro Editor screen displays the name of the macro, its description (your explanation of its function), and the keystrokes (Action). 3 If you want to type a description for the macro, select Description (1) and enter the description. 4 Select Action (2) to enter the Action Editing Window. 5 Edit the macro (see Macro Editing below). 6 Press Exit twice to return to the Document Editing Screen. MACRO EDITING While your cursor is inside the Action Editing Window, you can delete commands, insert new ones, and format your macro. Spaces you enter appear as small dots. Use Tab and Enter to make your macro more readable. INSERTING COMMANDS To insert a WordPerfect command (e.g., {Spell}) into your macro, press the feature's key. To insert text, simply type the text. You will probably want to use the editing keys (e.g., Enter, Arrows, Home, Backspace, Pg Up) in two ways: 1) to edit your macro, and 2) to insert the command into your macro. For example, pressing Enter either inserts a line into your macro or includes an {Enter} command. When you want the editing command to be a part of the macro, press Ctrl-v before pressing the key. This tells WordPerfect to insert the command itself into the macro. For example, to insert the {Enter} command into your macro, press Ctrl-v, then press Enter. If you will be inserting many of these commands, you can enter the Command Insert Mode by pressing Macro Define (Ctrl-F10). While in this mode, all keys you press will insert the key command. When you want to use the editing keys to edit, press Macro Define again. You must either press Ctrl-v or enter the Command Insert mode before pressing the key to insert the following commands: Exit, Cancel, Tab, Insert, Macro Commands, Variables, certain Control Characters, and Keyboard Macro Contents. To insert programming commands (commands not assigned to any key), press Macro Commands (see Macro Commands below). CANCELING CHANGES If, after editing your macro, you would like to restore it to it's previous state, press Cancel. WordPerfect will prompt "Cancel Changes? (Y/N) No." Type y to have WordPerfect cancel the changes you made and exit the Action Editing Window. Type n to return to the edited macro. VARIABLES There are ten variables available in WordPerfect. A variable is similar to a file macro in that it can store keystrokes. A variable differs from a file macro in the following ways: ùVariables are named {VAR 0} through {VAR 9} and are executed by pressing Alt-variable number (0-9). A variable can be executed from anywhere in WordPerfect operation. ùYou can perform operations such as adding numbers, and comparing the contents of one variable to another. ùYou can block text and assign it to a variable. ùThe method you use to assign variable contents determines what kind (if any) codes you can assign. ùA variable can only hold 120 characters. ùVariables are temporary--their contents will be erased when you exit WordPerfect. USES FOR VARIABLES A variable is useful as a temporary "macro" or as part of a complex macro. You can also do simple calculations or assign existing text to a variable. ùAs a temporary "macro" Use a variable to hold text you would otherwise need to type several times. The contents of a variable are executed one key at a time, which means that it can act as a macro. For example, you can record the keystrokes which would take you to the Tab Set menu with {ASSIGN}1~{Format}lt~. ùTo assign existing text You can assign on-screen text to a variable without retyping it. ùTo calculate You can define a variable to do simple calculations. For example, to calculate 245 times 11, press Macro Commands (Ctrl-Pg Up) while at the main editing screen, enter the variable number (0-9), then enter 245*11. Press Alt-number to insert the result (2695) into your document. A variable can compute only one operation at a time. If you enter an expression such as "2+3+4", the expression will be treated as a string. ùAs part of a complex macro You might want to create a macro which will calculate and/or keep track of values and text which will change during macro execution. Variables are an important part of these procedures. ASSIGNING VARIABLE CONTENTS You can assign contents to a variable from any text-editing screen, or with a macro command inside a macro. OUTSIDE OF MACRO DEFINITION From any text-editing screen, you can choose either to enter the contents of a variable, or to assign existing text. To enter the variable contents: 1 Press Macro Commands (Ctrl-Pg Up) from any text-editing screen. 2 Type the variable number (0-9). 3 Enter the variable contents. You can enter only characters and numbers when you assign a variable in this way. You can enter up to 79 characters. To assign existing text: 1 Block the text. 2 Press Macro Commands (Ctrl-Pg Up). 3 Type the variable number (0-9). The first 120 characters of the block will be assigned to the variable. When codes are encountered in the block, they are converted (if possible) to the keystroke command that would normally insert that code. For example, if the block includes a [Tab] code, it will be converted to the command {Tab}. All of the codes of the blocked text are ignored except the following: ùTab, Indent, Hard Return, Hard Page, and Required Hyphen. ùSoft Return is kept as a space. ùSoft Page is kept either as the Enter key or a space. DURING MACRO DEFINITION During macro definition, the macro commands key allows more options. After you press Macro Commands (Ctrl-Pg Up), a menu of four options will appear. Select Assign (3) and continue the steps as outlined above. MACRO EDITOR You can place commands in your macro which will assign contents to a variable when the macro is executed (see Assign, Char, Look and Text below). These commands will allow you to assign any command to the variable. EXECUTING A VARIABLE To insert the contents of a variable, press Alt-variable number. If the variable contains arithmetic or logical expressions, the result of the expression will be inserted. Variables may be executed at any point in WordPerfect operation. INSERTING A VARIABLE COMMAND In the Macro Editor, you can insert a variable command (e.g., {Var 1}) into your macro. The variable is executed during macro execution. 1 Position the cursor where you want {Var n} to appear in your macro. 2 Press Ctrl-v. 3 Press Alt-variable number. If you want a macro to use the contents of a variable during macro execution, simply place the {VAR n} command in the macro. If you want to insert the variable contents into your macro when it is displayed in the Action Editing Window, press Alt-variable number. KEYBOARD MACROS Keyboard macros act much like variables when they are executed in the Macro Editor. When you want the key to act as it would in the main editing screen, simply press the key. When you want to insert the commands assigned to the key (the command(s) that are executed during macro execution), press Macro Define (Ctrl-F10) or Ctrl-v before pressing the key. You can insert the contents of a macro into other macros by assigning it to a key (see Keyboard Layout in Reference). The commands of the macro will be inserted into the Action Editing Window when you press Ctrl-v, key. MACRO COMMANDS The Macro Commands Key (Ctrl-Pg Up) is one of WordPerfect's most versatile keys. It allows you to manipulate variables and place programming commands in macros. The function of the Macro Commands key differs depending upon where you are in the program. For information on what options are available, see Figure 1. Pause Display Assign Comment Normal Execution ù Block On ù Macro Define ù ù ù ù (edit screen) Macro Define ù ù (no edit screen) Macro Editor All Programming Commands Macro Editor Inserts {Macro Commands} (with Ctrl-v) NORMAL EXECUTION In normal execution (no Block, no Macro Define, no menus, etc.) Macro Commands (Ctrl-Pg Up) is used to assign a value to a variable. BLOCK ON When Block is on, the highlighted text is assigned to a variable. MACRO DEFINITION/EXECUTION Pressing Macro Commands (Ctrl-Pg Up) while defining or executing a macro brings up either two or four options. Four options are available if you are in an editing screen and two options are available otherwise. Pause stops the macro to allow for text from the keyboard. When Enter is pressed, the macro continues. Display determines whether the execution of the macro is visible. Assign functions as in normal execution (see Normal Execution above). Comment allows the user to make comments about the macro during definition. The comments are displayed the Macro Editor along with the macro commands. When the macro is executed, the comments are ignored. MACRO EDITOR Pressing Macro Commands (Ctrl-Pg Up) in the Macro Editor displays a list of keyboard commands (those that cannot be entered by normal keys and are used strictly inside macros). To insert a command, move the cursor to where you want to insert the command. Press Macro Commands (Ctrl-Pg Up), highlight the command, and press Enter. You can use a Name Search function to highlight a command. after pressing Macro Commands, start typing the name of the command you want to insert. To insert the command {Macro Commands} into your macro, press Ctrl-v followed by Macro Commands (Ctrl-Pg Up). When the macro is executed, you will be given access to the functions listed under Macro Definition/Execution above. PROGRAMMING COMMANDS The programming commands can be categorized by the functions they perform. The categories are: User Interface, Flow Control, Decision Making, Terminate Macro or Subroutine, External Condition Handling, Macro Execution, Variables, System Variables, Macro Execution Control, and Programming Aids. See the alphabetical listing of commands below for a description of each command. USER INTERFACE. These commands communicate with the user. They display a prompt, allow input from the keyboard, or both. {BELL} {CHAR} {LOOK} {ORIGINAL KEY} {PAUSE} {PROMPT} {TEXT} FLOW CONTROL. These commands can change the flow of macro execution. {BREAK} {CALL} {CASE} {CASE CALL} {CHAIN} {ELSE} {END IF} {GO} {IF} {IF EXISTS} {LABEL} {NEST} {ON CANCEL} {ON ERROR} {ON NOT FOUND} {QUIT} {RESTART} {RETURN} {RETURN CANCEL} {RETURN ERROR} {RETURN NOT FOUND} DECISION MAKING. These commands evaluate a condition and perform different operations depending on the outcome. {CASE} {CASE CALL} {IF} {IF EXISTS} TERMINATE MACRO OR SUBROUTINE. These commands will terminate either a macro or a subroutine. {QUIT} {RESTART} {RETURN} {RETURN CANCEL} {RETURN ERROR} {RETURN NOT FOUND} EXTERNAL CONDITION HANDLING. These commands either determine how a condition outside of macro execution (i.e., Cancel is pressed) is dealt with, or create the condition. {CANCEL OFF} {CANCEL ON} {ON CANCEL} {ON ERROR} {ON NOT FOUND} {RETURN CANCEL} {RETURN ERROR} {RETURN NOT FOUND} MACRO EXECUTION. These commands start macro execution. {ALT letter} {CHAIN} {KEY MACRO n} {NEST} {VAR n} VARIABLES. These commands either assign a value to a variable or determine the state of the variable. {ASSIGN} {CHAR} {IF EXISTS} {LOOK} {TEXT} SYSTEM VARIABLES. These commands are used by the macro as variables. {STATE} {ORIGINAL KEY} MACRO EXECUTION CONTROL. These commands affect the speed or visibility of macro execution. {DISPLAY OFF} {DISPLAY ON} {SPEED} {WAIT} PROGRAMMING AIDS. These commands can be used as programming aids. {:} {DISPLAY OFF} {DISPLAY ON} {SPEED} {STEP OFF} {STEP ON} Many of the commands use parameters or arguments (values) which require that a tilde (~) be placed at the end. If a macro is not working properly, check to make sure all the comments and commands have their tilde marks correctly placed. The Macros Keyboard Definition (see Keyboard Layout in Reference) contains several advanced macros. Studying these examples will help you see how the commands interrelate. The examples have numerous comments included. The comments help you follow the commands of the macro. In the examples, "var" represents a variable. "Value" represents a number, string (text), variable, command or expression (or a combination). {;}Comment~ The text you type between the comment command {;} and the tilde (~) is ignored during macro execution. Comments are useful in helping you (or someone else who might use your macro) to quickly recognize what each part of your macro does. You can also use comments to convert ("comment out") a section of your macro so it won't execute with the macro. If you want a column of comments to run side-by-side with the related commands, keep in mind that a separate comment must be entered on each line. For example, {ASSIGN}1~One~ {;}Assign "One" to var 1~ {ASSIGN}2~Two~ {;}Assign "Two" to var 2~ {ASSIGN}3~{VAR 1}ù{VAR 2}~ {;}Assign to var 3 the contents of var 1 concatenated (combined) with var 2~ {VAR 3} {;}Execute var 3 (Type the string"One Two")~ Note the centered dot (ù) between {VAR 1} and {VAR 2}. Spaces are represented this way in the Macro Editor. If the space were not there, variable 3 would hold "OneTwo". {ASSIGN}variable~value~ The {ASSIGN} command assigns a value to a variable. A number (0-9) indicates to which variable the value should be assigned. See {;} above for examples of {ASSIGN}. Do not enclose the value in quotes. If the value is an expression, the expression is evaluated (see Expressions below) and the result is assigned to the variable. Otherwise, it is treated as a string. For example, {ASSIGN}5~3~ {;}Assign 3 to var 5~ {ASSIGN}5~{VAR 5}*2~ {;}Multiply old value of var 5 by 2, assign the result as the new value of var 5~ {ASSIGN}5~WordPerfect~ {;}Assign string to var 5~ If you want to empty the variable of its contents, leave the value section empty (e.g., {ASSIGN}0~~). It is a good idea to empty variables at the beginning of a macro in which they are used (unless the macro will assign new contents to them). The {IF EXISTS} command checks for the existence of variable contents. You can assign up to 120 characters to a variable. {BELL} The {BELL} command sounds a beep. You might use {BELL} to signal the end of a lengthy process. It is also useful to prompt the user for input (in connection with {CHAR}, {PROMPT}, {PAUSE}, and {TEXT}). For example, {BELL} {;}Sound a bell~ {TEXT}1~Please enter your name~ {;}Prompt for a name and place it in var 1~ Hello {VAR 1}. {;}Type "Hello name"~ Note: the text "Hello name ." will be typed at the cursor position. The {BELL} command can be placed inside the prompts for {CHAR}, {TEXT} and {PROMPT} commands (i.e., {TEXT}1~{BELL}Please enter your name~. {BREAK} When {BREAK} is encountered inside an {IF} structure, macro execution is moved to the end of the {IF} structure (see {IF} below). If {BREAK} is not inside an {IF} structure, macro execution is moved to the end of the macro. {BREAK} is useful when you want the macro to skip some commands when an Error, Cancel or Not Found condition occurs. For example, a macro might perform a search inside an {IF} structure. If the search fails, the macro will end unless you include an {ON NOT FOUND} command. If you use the command {ON NOT FOUND}{BREAK}~, the macro will not end when the search fails. Instead, macro execution will continue directly below the {IF} structure. For example, {ON NOT FOUND}{BREAK}~ {;}If search fails, break to end the {IF} structure~ {IF}{VAR 1}=1~ {;}If var 1 contains 1, continue~ {HOME}{HOME}{UP} {;}Move to top of document~ {SEARCH}test{SEARCH} {;}Search for "test"~ {BLOCK}{Word Left} {;}Block the word "test"~ {Backspace}y {;}Delete the word~ {END IF} {;}End of {IF} structure~ If the search fails, the commands directly after the search will be skipped and macro execution will continue after the {END IF} command. {CALL}label~ The {CALL} command branches macro execution to a different part of the macro. When that section of the macro is completed, execution returns to the command following {CALL}. It is as if another section of the macro is placed where {CALL} is located. The "other section" of the macro is often called a subroutine. A subroutine is like a mini macro. You can use a subroutine to perform any operation that you would otherwise have to place in your macro several times (e.g., delete a block of text). There is no limit to the number of subroutines you can have in a macro. A subroutine is identified by two commands. The first command, {LABEL}, marks the beginning of a subroutine. The second command, {RETURN} marks the end. Since there may be more than one subroutine in a macro, there is always a unique name associated with each one. It is this name that you enter after the {CALL} command. For example, {SEARCH}test{SEARCH} {;}Search for the word "test"~ {CALL}delete~ {;}Commence delete subroutine~ {BOLD}This line was deleted{BOLD} {;}Place the bolded message in the document~ {RETURN} {;}Don't go on to the subroutine and return from this subroutine~ {LABEL}delete~ {;}Subroutine "delete"~ {Home}{Home}{Left} {;}Move to beginning of line~ {Del to EOL} {;}Delete the line~ {RETURN} {;}End of {IF} structure~ Note the {RETURN} command after the search. This example assumes that the search was called from another part of the macro. After the search is completed, the macro returns to the place from which this subroutine was called. {CANCEL OFF} The {CANCEL OFF} command is used to stop the Cancel key from performing its normal function (which is to stop macro execution). The default condition is for Cancel to be enabled ({CANCEL ON}). {CANCEL OFF} is useful if you want to be able to get a Cancel key as input from the user in the {CHAR}, {LOOK} or {TEXT} commands. Even if a macro is in {CANCEL OFF} state, pressing Ctrl-Break will generate a Cancel condition. {CANCEL ON} The {CANCEL ON} command is used to enable the Cancel key after it has been disabled with the {CANCEL OFF} command. See {CANCEL OFF} for more information. {CASE}value~case1~label1~case2~label2~...~~ The {CASE} command allows the macro to branch to one of several locations in the macro, depending on what the value is. For example, your macro might ask the user to answer yes or no to a prompt. If the answer is yes, the macro will perform one function. If the answer is no, another function will be performed. The commands that will perform these steps are as follows, {CHAR}1~Continue? (Y/N)~ {;}Assign y or n to var 1~ {CASE}{VAR 1}~ {;}Case: If var 1 contains...~ y~yes~Y~yes~ {;}y or Y, go to label yes~ n~no~N~no~ {;}n or N, go to label no~ ~ {;}End of Case statement~ {CALL}getchar~ {;}Call Getchar if none of the cases match~ It is often helpful to format the {CASE} statement (place it on several lines) so it is more readable. Notice that there is an extra tilde (~) required at the end of the {CASE} command. Both the upper and lower case of y and n are listed in the {CASE} statement because there must be an exact match of the value and one of the case options. If no match is found in the {CASE} statement (e.g., an i was pressed), execution will continue after the {CASE} statement (e.g., the {CALL}getchar~ command). The {CASE} command does not require that program execution return after the routine is completed. In other words, it does not CALL the routine, rather, it will GO to the routine. In this example, the {CALL}getchar~ command would not be executed unless a character other than n or y were pressed. If the {CASE} command were changed to {CASE CALL}, the subroutines would be CALLED, and macro execution would return to the {CALL}getchar~ command. {CASE CALL}value~case1~label1~case2~label2~...~~ The {CASE CALL} command is similar to the {CASE} command in that it can branch to different subroutines. The difference is that {CASE CALL} requires that program execution return after a subroutine has executed. See {CASE} above for more information. {CHAIN}macro~ The {CHAIN} command stores the name of the indicated macro and executes it after the current macro is completed. You can enter a full path name if you wish (the .WPM extension is not necessary). For example, the following macro is equivalent to WordPerfect 4.2's Repeating Conditional Macro Chain. It will execute the notfound macro when the search fails. {CHAIN}notfound~ {;}Execute the notfound macro when this macro is completed~ {ON NOT FOUND}{RETURN}~ {;}When the search fails, stop this macro, the chained macro will start~ {LABEL}loop~ {;}Begin the repeating macro~ {Search}at{Search} {;}Search for "at"~ {PAUSE} {;}Pause (allow user to edit)~ {GO}loop~ {;}Search was successful, repeat the search~ The section of the macro between the {LABEL} and {GO} commands is repeatedly executed until the search fails. As soon as the search fails, the notfound macro begins. Only the last macro chained at this level of nesting will be executed. If macros are nested, one macro may be chained at each level. See {NEST} for a discussion on nesting macros. {CHAR}variable~message~ The {CHAR} command prompts the user on the status line with a message and then waits until a single key is pressed. The key is then assigned to the variable. This command is useful to simulate WordPerfect menus and prompts. The user can press any key (including a feature key such as Search). If Cancel is pressed, the macro will end unless the {CANCEL OFF} or {ON CANCEL} commands have been previously executed in the macro. Once the key has been assigned to the variable, a {CASE}, {CASE CALL} or {IF} command can be used to perform different operations. For example, {CHAR}1~ {;}Prompt the user for input~ 1 Memo; 2 Letter; 3 Itinerary: 0~ {;}and assign the character to var 1~ {CASE CALL}{VAR 1}~ {;}Check var 1 and branch to~ 1~memo~ {;}the appropriate subroutine~ 2~letter~ 3~itin~ ~ {;}End of {CASE CALL} statement~ See Control Characters below for information on affecting the way messages are displayed. {DISPLAY OFF} The {DISPLAY OFF} command turns off the display of macro execution. When you create a macro, this command is automatically inserted into your macro. You can delete this command if you want the macro to display menus, inserted text, etc. as it is executing. In addition, you can turn macro display on or off while you are defining a macro with Macro Define. Press Macro Commands (Ctrl-Pg Up), select Display (2), and enter y or n to turn macro display on or off. In many cases, you will want to turn the display off because macro execution is faster when it doesn't display. An important exception to this is when a macro ends in a {PAUSE} or does a {PAUSE} at a menu. The display cannot be rewritten by the macro and so the display should be left on or turned on before entering the menu. {DISPLAY ON} The {DISPLAY ON} command is used to turn on the display of macro execution after it has been turned off by the {DISPLAY OFF} command (see {DISPLAY OFF} above). {ELSE} The {ELSE} command is used in connection with the {IF}, {IF EXISTS} and {END IF} commands. It marks the beginning of the commands which will execute should the {IF} value be false (see {IF} below). It often helps to think of {ELSE} as the word "otherwise". For example, in the steps below, if variable 1 contains a negative number, add 2. OTHERWISE, subtract 2. {IF}{VAR 1}<0~ {;}If var 1 is less than 0~ {ASSIGN}1~{VAR 1}+2~ {;}Add 2 to var 1~ {ELSE} {;}Otherwise~ {ASSIGN}1~{VAR 1}-2~ {;}subtract 2 from var 1~ {END IF} {;}End of {IF} statement~ The {ELSE} command does not have to be part of an {IF} statement. It should be used when there are certain steps that need to be performed only when the {IF} value is false. The commands below {END IF} will be executed whether or not the {IF} value is true. For example, in the steps below, "if variable 1 contains a negative number, convert it to its corresponding positive number. Then, multiply by 2 the number in variable 1 (which will be positive after going through the {IF} statement). {IF}{VAR 1}<0~ {;}If number in var 1 is negative~ {ASSIGN}1~-{VAR 0}~ {;}Change it to positive~ {END IF} {;}End of {IF} statement~ {ASSIGN}1~{VAR 1}*2~ {;}Multiply number in var 1 by 2~ Note that the {END IF} command is needed whether or not the {ELSE} statement is used. {END IF} The {END IF} command marks the end of an {IF} structure. See {IF} and {ELSE} for more information. {GO}label~ The {GO} command sends macro execution to another place in the current macro. It is used in conjunction with the {LABEL} command. (The label marks the place to go to.) For example, {IF}"{VAR 1}"="{Search}" {;}If var 1 contains {Search}~ {GO}search~ {;}go to the Search Label~ {END IF} ù ù (middle section of macro) ù {LABEL}Search~ {;}Perform the search~ (Steps of the search) {QUIT} {;}Stop macro execution~ This macro checks to see if the Search command has been entered in variable 1. Notice that the steps between {END IF} and {LABEL} will be skipped if variable 1 contains {Search}. Unlike the {CALL} command, {GO} does not require that the macro return. In the example, the macro will end after the search has been completed. The {GO} command is useful when you want a part of your macro to be executed several times. Whenever the same commands execute several times, that section of the macro is called a loop. For example, {LABEL}top~ {;}Top of the loop~ endless loop {;}type "endless loop"~ {GO}top~ {;}Go to top~ In this example, the words "endless loop" will be written continuously to the screen. There is no way to stop the macro without pressing Cancel, or Ctrl-Break, etc. Whenever you create a loop, it's very important to have a way for the loop to end. In the following example, a count is kept of the number of times the text has been written to the screen. After the tenth time, the loop ends. {ASSIGN}0~0~ {;}Assign 0 to var 0~ {LABEL}top~ {;}Top of the loop~ {ASSIGN}0~{VAR 0}+1~ {;}Add 1 to var 0~ Loop {VAR 0} {;}Type "loop" #~ {IF}{VAR 0}=10~ {;}If this is the tenth time~ {QUIT} {;}quit the macro~ {ELSE} {;}Otherwise,~ {GO}top~ {;}go to top (repeat the loop)~ {END IF} {;}End of {IF} structure~ {IF}value~ The {IF} statement is used to execute certain commands only if a certain condition exists. If the condition exists (the value is true) the commands directly below the {IF} command will be executed. The value is usually an expression or variable. A value is true if it is evaluated as a non-zero number. For example, when the expression 4=4 is evaluated, the result is -1 (which corresponds to true). The value is false if it results in a 0 or contains nothing at all. See Expression Evaluation below for more information. In the example below, the Setup menu is displayed only if the appropriate password is in variable 1. {IF}"{VAR 1}"="password" {;}If var 1 contains the password~ {Setup} {;}enter the Setup menu~ {END IF} Notice that quotes are placed around both {VAR 1} and the password. String values must be enclosed in quotes to be evaluated correctly. If the value is true (e.g., the contents of variable 1 equal the password), the commands directly after the {IF} are executed. If the value is false (or there is no value at all), the commands after {IF} are skipped, and execution continues after the {END IF} command. An {IF} statement always begins with {IF} and ends with {END IF}. If you want certain commands to be executed only when the value is not true, use the {ELSE} command (see {ELSE} above). It is possible to nest {IF} commands. See {STATE} below for an example of nested {IF} statements. {IF EXISTS}variable~ The {IF EXISTS} command checks for a value in the indicated variable. If there is a value, then the commands following {IF EXISTS} are executed. The format of an {IF EXISTS} statement is the same as that of an {IF} statement (see {IF} above). You might want a macro to know whether there is text in the other Document Editing Screen. For example, {Switch} {;}Switch to other document~ {Home}{Home}{Up} {;}Move to top of document~ {Block}{End}{Right} {;}Block the text~ {Macro Commands}31 {;}Assign the block to var 1~ {IF EXISTS}1~ {;}If there is anything in var 1~ {Prompt}The document is not empty~ {ELSE} {;}Otherwise (var 1 is empty)~ {GO}nofile~ {;}go to the label nofile~ {END IF} {;}End of {IF EXISTS} statement~ {IF EXISTS} is also useful when you want a macro to wait until a key is pressed (see {LOOK} below). {LABEL}name~ A {LABEL} command marks a place in the macro. After the place has been marked, macro execution can be sent directly there from any place in the macro. The {GO}, {CALL}, {CASE}, and {CASE CALL} commands are used to direct macro execution to the {LABEL}. There can be several labels in the same macro as long as each has a different name. If the name is duplicated, the first one in the macro is used. The other is ignored. The label name distinguishes each label from the others. Label names have no restrictions regarding length or the characters used (e.g., the label can include spaces). A {LABEL} is used to mark the beginning of a subroutine (see {CALL} above). {LOOK}variable~ The {LOOK} command checks to see if a character has been typed by the user. If a character has been typed, it is assigned to the variable. If a character has not been typed, the contents of the variable are deleted and execution is continued without stopping. {LOOK} is often useful inside a loop which waits for a character to be typed. For example, {LABEL}Wait~ {;}Top of the Wait loop~ {WAIT}1~ {;}Wait one tenth of a second. {LOOK}0~ {;}Check to see if a character has been typed~ {IF EXISTS}0~ {;}If there is a character in var 0 (it was typed), drop out of the loop~ {ELSE} {;}Otherwise (there was no character)~ {GO}wait~ {;}go to the top of the loop~ {END IF} {;}End of {IF} structure~ The WAIT command in this example is used to allow any background printing to take place before the user responds. {NEST}macro~ The {NEST} command transfers control to another macro. When that macro is completed, this macro resumes. It is as if the macro contents are placed where the {NEST} command is. If, there are certain procedures which you frequently use in your macros, you can assign them to macros, and then nest them when they are needed. You can enter a full path name if you wish (the .WPM extension is not necessary). For example, if you have a macro which saves a document on the screen, you can nest it within another macro. {IF}{VAR 0}~ {;}If var 0 is non-zero, save the document~ {NEST}save~ {;}Nest macro "save"~ {END IF} {;}End of {IF} structure~ You can nest macros several levels deep. For example, the main macro nests a second macro. The second macro nests a third. After the third macro has finished, the rest of the second macro is completed, and finally, the remaining part of the first macro is completed. You can have up to 20 levels of macro execution. Each {NEST} command uses 2 levels (one for executing the macro and one for a possible CHAIN command). Each CALL or {CASE CALL} command uses 1 level. Each variable also uses 1 level. {ON CANCEL}command~ The {ON CANCEL} command tells WordPerfect what should happen if a user presses Cancel or if a {RETURN CANCEL} command has been returned by a nested macro (or subroutine). When a Cancel occurs, WordPerfect will know what to do next only if it has already encountered the {ON CANCEL} command. For this reason, it is a good idea to place the command before a Cancel can occur. See {BREAK} for an example. The default is {RETURN CANCEL} if no {ON CANCEL} command is entered. The only other commands allowed are: {BREAK}, {CALL}, {GO}, {QUIT}, {RESTART}, {RETURN}, {RETURN ERROR}, and {RETURN NOT FOUND}. Since {GO} and {CALL} require a tilde (~) after the label, there must be two tilde marks (~ ~) at the end (e.g., {ON CANCEL}{GO}label~~. If no command is specified, the cancel condition is ignored and the macro continues executing as if there had been no cancel. Not only is the cancel condition ignored, but if the Cancel key was pressed, the key will be thrown away. In other words, if either a {LOOK} or {ORIGINAL KEY} were used, they would not detect that the Cancel key had been pressed. If you want the cancel key to be used as input, use the {CANCEL OFF} command. As the macro is executing, the last {ON CANCEL} command will be used. So if conditions change during macro execution, a new {ON CANCEL} command can change what will happen. Each level of execution has its own {ON CANCEL} option which defaults to {RETURN CANCEL}. For example, if a subroutine has been called by {CALL} or {CASE CALL}, it does not remember the {ON CANCEL} command which was entered in another location of the macro. When there is a cancel condition detected, the subroutine executes {ON CANCEL}{RETURN CANCEL}~, which means it stops executing and returns a cancel condition to the location from which it was called. When a new macro is executed or a subroutine is called, a new {ON CANCEL} command is required to override the default if desired. {ON ERROR}command~ The {ON ERROR} command tells WordPerfect what should happen if an error is detected in macro execution, in normal WordPerfect operations, or while you are in DOS. The default command is {RETURN ERROR} (see {ON CANCEL} above). {ON NOT FOUND}command~ The {ON NOT FOUND} command tells WordPerfect what should happen if a search fails (e.g., Search, Word Search, Replace or Name Search). The default command is {RETURN NOT FOUND} (see {ON CANCEL} above). See {CHAIN} for an example. During Name Search, if you enter a non-existent name, the Not Found Condition will not be generated at the first character which does not match. Name Search does not check for an exact match unless you press Ctrl-Enter "{HPg}" after the name. {ORIGINAL KEY} The {ORIGINAL KEY} command performs the original (unmapped) action of the last key entered at the keyboard. The last key pressed could be either a key that was read before the macro started (which may be the key which invoked the macro) or it would be a character input with a {CHAR}, {LOOK}, {TEXT}, or {PAUSE} command. This command is useful if your keyboard has been remapped with a keyboard definition (see Keyboard Definitions above). For example, you might want your macro to check if a user has typed a specific key, regardless of the keyboard definition. For example, {LOOK}1~ {;}Check to see if a key has been pressed. Assign it to var 1~ {IF}"{ORIGINAL KEY}"="{Exit}"~ {;}If the unmapped key is Exit~ {Exit} {;}Exit~ {END IF} {;}End of {IF} statement~ {PAUSE} The {PAUSE} command causes the macro to pause until Enter is pressed. This command allows the user to edit or type new text as if there were no macro running. {PAUSE} does not prompt the user. Because of this, the {PROMPT} and/or {BELL} commands are often used with {PAUSE}. {PROMPT}message~ The {PROMPT} command displays the message on the status line. See Control Characters below for information on affecting the way messages are displayed. {QUIT} The {QUIT} command terminates all macro execution. If macros are nested or chained, it will also stop that activity. {RESTART} The {RESTART} command terminates all macro execution at the end of the current subroutine or macro. This command can be used if you don't want a subroutine to return to a {CALL} or {CASE CALL} command. {RETURN} The {RETURN} command marks the end of a subroutine and signals the macro to return from a {CALL}, or {CASE CALL} command. If a macro is nested, {RETURN} signals the macro to return to the macro from which it was nested. If the macro is not nested and there is no {CALL} or {CASE CALL} to return to, {RETURN} marks the end of a macro (see {CALL} above). {RETURN CANCEL} The {RETURN CANCEL} command causes macro execution to leave the current level (subroutine or macro) and indicate Cancel to the higher level. Pressing the Cancel key while that part of the macro is executing performs the same function (see {RETURN} and {ON CANCEL} above). {RETURN ERROR} The {RETURN ERROR} command causes macro execution to leave the current level and indicate an error to the higher level (see {RETURN CANCEL} above). {RETURN NOT FOUND} The {RETURN NOT FOUND} command causes macro execution to leave the current level and indicate a search not found condition to the higher level (see {RETURN CANCEL} above). {SPEED}100th's seconds~ The {SPEED} command can slow down macro execution. It causes macro execution to wait the amount of time indicated between each key input. The default speed is no delay between characters (e.g., {SPEED}0~). {STATE} The {STATE} command indicates the current executional state of WordPerfect. This allows you to create macros which are aware of the environment in which they are executing. The states of WordPerfect are listed below. 3 Current Document 4 Main Editing Screen 8 Editing Structure Other than Main Document 16 Macro Definition Active 32 Macro Execution Active (always set) 64 Merge Active 128 Block Active 256 Typeover Active 512 Reveal Codes Active 1024 Yes/No Question Active State 8 (Editing Structure Other than Main Document) refers to a screen which is used for editing footnotes, headers, styles, etc. Macro Execution (32) is labeled as "always set" because the {STATE} command is always used in a macro as it is executing. You can determine what the state of WordPerfect is by forming an AND (&) expression with a value called a mask (e.g., {STATE}&3). The result of the operation will indicate what the current state of WordPerfect is. To choose a mask, determine which state(s) you want to check for. Note the numbers associated with each state and add them together. For example, if you want to know what document screen you are currently in (1,2 or 3), the mask value is 3. If you want to know if you are at the main editing screen (4) and if Reveal Codes is Active (512) the mask value is 516 (4+512=516). After you have determined the appropriate mask, create an AND expression, {ASSIGN}1~{STATE}&3~ {;}Assign the current document number to var 1~ {ASSIGN}2~{STATE}&516~ {;}Assign the result (either 4, 512, 516 or 0) to variable 2~ In this example, the mask values are 3 and 516. Variable 1 contains the current document number and variable 2 contains a number which indicates whether the Main Editing screen (4), Reveal Codes (512), Both (516) or neither (0) are active. If the result of the AND operation is 0, then the state you were checking for is not present. If the result is a non- zero number, then some (or all) of the states you checked for are present. For example, if you want to check for both types of editing screens, (4) and (8), the mask is 12. {STATE}&12 gives four types of information. If the result is 0, then neither the main editing screen or another editing screen is active (some type of menu is active). If the result is 4, the Document Editing screen is on. If the result is 8, a menu is active, but you are editing a style, footnote, etc. (e.g., you pressed Format while editing a footnote). If the result is 12, you are in the Document Editing Screen, and you are editing a style, footnote, etc. Since the {IF} command interprets 0 as false, you can form {IF} statements that will perform functions when a certain condition exists. For example, the Macros Keyboard contains a macro which takes you to the Main Editing screen from any menu. The following is a portion of the macro, {IF}{STATE}&4~ {;}If at the main editing screen, check for other states which may be present~ {IF}{STATE}&8~ {;}If in an editing structure~ {Exit} {;}exit to main editing screen~ {ELSE}{IF}{STATE}&64~ {;}If in a merge~ {^Q} {;}stop the merge.~ {ELSE}{IF}{STATE}&128~ {;}If Block is on~ {Block} {;}turn Block off.~ ù ù ù {END IF}{END IF}{END IF} {;}End of {IF} statements~ {END IF} {;}End of first {IF} statement~ When {STATE} is executed by itself (not in an expression), it returns a number which represents the total state of WordPerfect. All applicable numbers are added together. For example, if the cursor is in the Main Editing Screen (4) of Document 1 (1), and if Block is on (128) and a macro is executing (32), then the executional state of WordPerfect is 4+1+128+32=133. {STEP ON} The {Step On} command is useful for debugging macros. It causes the macro to execute one step at a time. Between each step, a message at the bottom of the screen indicates what the next key or command will be. (The key or command will execute when any key is pressed.) If the next step in the macro is a key (e.g., A), that key will be displayed. If it is a command (e.g., Save), a label followed by a number will be displayed. The five labels are: ùALT (Alt-Macro Execution) ùKEY CMD (WordPerfect Command, Cursor Control, etc.) ùKEY MACRO (Soft Keyboard Macro Execution) ùMACRO CMD (Specific Macro Command) ùVAR (Variable Execution) The number or letter following the label indicates the specific command. Examples: Label Command KEY CMD 41 Save MACRO CMD 1 {Assign} VAR 2 Variable 2 ALT A ALT-A macro KEY MACRO 13 Key Macro 13 The KEY MACRO number is assigned by WordPerfect when you define a keyboard macro. You can see the numbers in the keyboard definition editing screen (right-most column). The following table outlines the labels and numbers with their corresponding command. NUMERIC VALUES RETURNED BY THE {STEP ON} COMMAND ALT (A - Z) Letter Meaning (macro letter) Alt Macro KEY CMD (1 - 98) Decimal Meaning 0 ^@ - Compose 1 ^A 2 ^B - Page number 3 ^C - Merge from console 4 ^D - Merge Date 5 ^E - Merge End of record 6 ^F - Merge Field 7 ^G - Merge Macro 8 ^H - Home 9 ^I - Tab 10 ^J - Enter 11 ^K - Delete to End of Line 12 ^L - Delete to End of Page 13 ^M - Search value for [SRt] 14 ^N - Merge Next record 15 ^O - Merge Output prompt 16 ^P - Merge Primpary filename 17 ^Q - Merge Quit 18 ^R - Merge Return 19 ^S - Merge Secondary filename 20 ^T - Merge Text to printer 21 ^U - Merge Update the screen 22 ^V - ignore meaning of following code 23 ^W - Up 24 ^X - Right & Search wildcard - same as typical ? 25 ^Y - Left 26 ^Z - Down 27 ^[ - Escape 28 ^\ 29 ^] 30 ^^ - Reset Keyboard map 31 ^_ 32 Cancel 33 Forward search 34 Help 35 Indent 36 List files 37 Bold 38 Exit 39 Underline 40 Merge return 41 Save 44 Setup 45 Backwards search 46 Switch 47 Left/right indent 48 Date/outline 49 Center 50 Print 51 Format 52 Merge commands 53 Retrieve 56 Thesaurus 57 Search/replace 58 Reveal codes 59 Block 60 Mark Text 61 Flush right 62 Math/columns 63 Style 64 Graphics 65 Macro 68 Shell 69 Spell 70 Screen 71 Move 72 Text in/out 73 Tab align 74 Footnote 75 Font 76 Merge/sort 77 Define macro 80 Backspace 81 Delete right 82 Delete word 83 Word right 84 Word left 85 Home-home-right (by hitting end key) 86 Home-home-left (by hitting begin key on 88 Goto 89 PgUp 90 PgDn 91 Screen down 92 Screen up 93 Typeover 94 Left margin release (reverse tab) 95 Hard page (Ctrl-Enter) 96 Soft hyphen 97 Hard hyphen 98 Hard space KEY MACRO (1 - 254) Decimal Meaning (macro #) Macro Number MACRO CMD (1 - 45) Decimal Meaning 1 {ASSIGN}var~value~ 2 {BELL} 3 {BREAK} 4 {CALL}label~ 5 {CANCEL OFF} 6 {CANCEL ON} 7 {CASE}val~case1~label1~c2~l2~...~~ 8 {CASE CALL}val~c1~l1~c2~l2~...~~ 9 {CHAIN}file~ 10 {CHAR}var~message~ 11 {;}comment~ 12 {DISPLAY OFF} 13 {DISPLAY ON} 14 {ELSE} 16 {END IF} 20 {GO}label~ 21 {IF}value~ 22 {LABEL}label~ 23 {LOOK}var~ 24 {NEST}file~ 27 {ON CANCEL}action~ 28 {ON ERROR}action~ 29 {ON NOT FOUND}action~ 30 {PAUSE} 31 {PROMPT}message~ 32 {QUIT} 33 {RESTART} 34 {RETURN} 35 {RETURN CANCEL} 36 {RETURN ERROR} 37 {RETURN NOT FOUND} 38 {SPEED}100ths~ 39 {STEP ON} 40 {STATE} 41 {TEXT} 42 {WAIT}10ths~ 44 {Macro Commands} 45 {STEP OFF} VAR (0 - 9) Decimal Meaning (variable #) Variable Name The {Step On} feature is particularly useful when you want to track the contents of a variable. When a variable (e.g., {Var 1}) is encountered in the macro, its contents (if they exist) are displayed after the VAR 1 message. For example, if Variable 2 contains 14, the first message, VAR 2 is followed by a 1 which is then followed by a 4. During macro execution, press Exit (F7) to turn off the Step mode. Pressing Cancel (F1) will terminate the macro unless the macro traps Cancel (see {Cancel Off} above). {STEP OFF} The {STEP OFF} Command turns off single step execution after it has been turned on (see {STEP ON} above). {TEXT}variable~message~ The {TEXT} command prompts the user by displaying a message on the status line. It gets an input string (up to 120 characters) from the user and assigns it to the variable (see {CHAR} above). See Control Characters below for information on affecting the way messages are displayed. {WAIT}10th's second~ The {WAIT} command delays further execution of the macro for the indicated time. This command is useful when you want a message to be displayed (e.g., with {PROMPT}) for a certain amount of time. EXPRESSIONS Expressions are used for values in the {ASSIGN}, {CASE}, {CASE CALL}, and {IF} commands. Expressions can perform operations on either numbers or strings. NUMERIC EXPRESSIONS The following is a list of numeric expressions. The values must contain only numbers (or variables which contain numbers). If non-numeric values are found, or the expression is invalid, no operation is performed. The highest positive number you should use is 32,767. Internally, WordPerfect represents negative numbers as large positive numbers from 32,768 to 65,535. The terms n1 and n2 represent number 1 and number 2. For definitions of the terms used in this list, see Expression Terms below. Expression Operation !n1 The result is the logical NOT (bitwise) of the number n1. Example: !0 is -1. -n1 The result is the negative (opposite) of the number n1. Example: If variable 1 holds 5, -{VAR 1} is -5. n1+n2 Add n1 and n2. Example: 5+4 is 9. n1-n2 Subtract n2 from n1. Example: 10-1 is 9. n1*n2 Multiply n1 by n2. Example: 6*5 is 30. n1/n2 Divide n1 by n2 and return the integer result. Examples: 20/5 is 4. 5/2 is 2. n1%n2 Divide n1 by n2 and assign the remainder as the result. Examples: 20%5 is 0. 5%2 is 1. n1&n2 Logical AND (bitwise) n1 with n2. Examples: 7&4 is 4. 3&4 is 0. n1|n2 Logical OR (bitwise) n1 with n2. Examples: 7|4 is 7. 3|4 is 7. n1=n2 If n1 and n2 are equal, the result is true (-1). Otherwise, it is false (0). Example: If variable 1 holds 5, then {VAR 1}=5 is true and {VAR 1}=3 is false. n1!=n2 If n1 and n2 are not equal, the statement is true. Otherwise, it is false. Example: If variable 1 holds 5, then {VAR 1}!=3 is true and {VAR 1}!=5 is false. n1>n2 If n1 is greater than n2, the statement is true. Otherwise, it is false. Examples: 6>4 is true. 4>6 is false. n1