Reference: The Merge toolbar and programming commands
The Merge toolbar displays at the top of the document window when you create a form document or a data file for a merge. You can control a merge and edit merge files by using the Merge toolbar.
You can also control a merge by using merge programming commands. The merge commands are similar to codes used in computer programming languages. For example, you need to specify parameters for some commands, and you can create subroutines, a set of commands that can be repeated in a merge.
Using the Merge toolbar
When you create a form document or a data file for a merge, the Merge toolbar displays at the top of the document window.
You can control a merge and perform specific merge functions by using the Merge toolbar. The Merge toolbar is context-sensitive, which means that the buttons available on the Merge toolbar change according to the task you are performing. For example, you would see different buttons for performing a keyboard merge and for editing a data table file.
You cannot hide the Merge toolbar for a merge form document or merge data file. If it is not visible, then the active file is not a form document or a merge data file.
Prompting for user input and message display
Several commands are used to display a message for, or request information from, the person running the merge. You can use a message to inform the user of the progress of the merge or you can use a prompt to remind the user of the kind of information needed in a fill-in form.
The following table lists commands displaying a message or prompt and shows how they differ from each other:
Command Action and user input
PROMPT (followed by WAIT) Displays message for the duration of the WAIT command; no user input is required.
STATUSPROMPT Displays message until another message is displayed; no user input is required.
KEYBOARD Displays message and asks for keyboard input; text is inserted in the document. The user types information and clicks Continue on the Merge toolbar (or presses Alt + Enter).
GETSTRING Displays message and asks for keyboard input; text is assigned to a variable. The user types information and presses Enter.
CHAR Displays message and asks for one-character input; the character is assigned to a variable. The user types one character.
LOOK No message; checks whether a key has been pressed. If a key has been pressed, the key is assigned to a variable; otherwise, the variable is deleted. The user types one character or nothing (merge does not pause for input).
Reusing commands with subroutines
You can create a subroutine to call a set of commands which are repeated several times in a merge. You do not need to add them each time. You can add them once, label them as a subroutine, then return to them (or call them) each time you want them to run.
The three commands used to define and call a subroutine are described in the following table.
Command Action and user input
CALL(label) Stops the merge and directs it to execute the subroutine. The label parameter must match the name of the label.
LABEL(labelname) Marks the beginning of the subroutine. The labelname parameter is a unique name that identifies the subroutine.
RETURN Marks the end of the subroutine and returns the merge to the line after the CALL command. If you do not add the RETURN command, the merge will continue in an infinite loop or will not continue correctly.
Using multiple files and macros in a merge
A merge can consist of more than one data file or form file, and it can include multiple macros. This may be useful if you want to merge different documents with the same data or if you have multiple data sources to merge. There are three ways to connect merge files: nesting, chaining, and substituting.
Nesting
Nesting a file or macro is like calling a subroutine. The merge pauses while the nested file or macro runs, then continues after the nested file has finished. This is useful if you use certain procedures frequently in your merges because you can save them in smaller files.
You can have multiple levels of nesting, a merge file can nest a second file or macro, which in turn nests another file, and so on. The three nest commands are described in the following table.
Command Action and user input
NESTDATA(filename) Changes to another data source. After that data has been merged with the form file, the merge returns to the first data source. Include a full path with the filename.
NESTFORM(filename) Pauses the merge and changes to another form file. After that file has merged completely, the original merge continues. Include a full path with the filename.
NESTMACRO(macroname) Pauses the merge, plays the macro, then continues the merge after the macro ends. You do not need to add a full path or the .wcm filename extension to the name of the macro.
Chaining
Chaining another file or macro starts that file or macro when the original merge is finished. This is one way to run multiple merges one after the other instead of starting each one manually. Only one chain command is used in a merge file; if there is more than one, the last one is used. The three chain commands are described in the following table.
Command Action and user input
CHAINDATA(filename) Merges records from the second file when all records from the first data source have been merged. Include a full path with the filename.
CHAINFORM(filename) Merges the new form file when the original form file has finished. Include a full path with the filename.
CHAINMACRO(macroname) Plays the macro after the merge has finished. You do not need to add a full path or the .wcm filename extension to the name of the macro.
Substituting
Substituting another form or data file is another way to change from one merge file to another. However, a substitute command moves the merge immediately to the second file without finishing the original merge file. When this happens, the new merge does not return to the original merge. The two substitute commands are described in the following table.
Command Action and user input
SUBSTDATA(filename) Changes to the new data file and begins merging its records. Include a full path with the filename.
SUBSTFORM(filename) Changes to the new form file and begins executing the merge commands in the file. Include a full path with the filename.
Understanding merge code parameters
Most merge programming codes use parameters (also called arguments). In the following table, parameters are enclosed in parentheses and any optional parameters are enclosed in square brackets. When there are two or more parameters, they are separated with a semicolon.
Merge code parameters
You need to enter the correct parameters and arguments as required for the merge code. The following table lists parameters and their arguments.
Parameter What you do
(expr);(subexpr) Enter a number, string, variable, command, expression, or combination of these
(label) Enter a unique label name
(var) Enter a unique variable name
(field) Enter a unique name or field number
(filename) Enter a filename, including the full path
(macroname) Enter a unique macro name; the full path is optional and no .wcm extension is needed.
(title) Enter the title of the dialog box
(prompt);(message) Enter information to display on the screen
(comment) Enter a description of what the merge does; this does not display on screen.
Merge programming commands
WordPerfect merge programming commands let you program a merge. Many commands are similar to those in other programming languages. The following commands can be used in merge. For more information about each command, click on the command name to link to the command's Help topic. For information on merging, see "Merging documents."
ASSIGN(var;expr)
ASSIGNLOCAL(var;expr)
BEEP
BREAK
CALL(label)
CANCELOFF
CANCELON
CAPS(expr)
CASEOF(expr[;...;expr])
CHAINDATA(filename)
CHAINFORM(filename)
CHAINMACRO(macroname)
CHAR(var[;prompt][;title])
CODES(merge codes)
COMMENT(comment)
CONTINUE
CTON(character)
DATE
DEFAULT
DISPLAYSTOP
DOCUMENT(filename)
ELSE
EMBEDMACRO(macro statements)
ENDFIELD
ENDFOR
ENDIF
ENDRECORD
ENDSWITCH
ENDWHILE
FIELD(field)
FIELDNAMES(name1;...;nameN)
FIRSTCAP(expr)
FOREACH(var;expr1;...;exprN)
FORNEXT(var;start;stop[;step])
GETSTRING(var[;prompt][;title])
GO(label)
IF(expr)
IFBLANK(field)
IFEXISTS(var)
IFNOTBLANK(field)
INSERT(text)
KEYBOARD([prompt])
LABEL(label)
LOOK(var)
MRGCMND(merge codes)
NESTDATA(filename)
NESTFORM(filename)
NESTMACRO(macroname)
NEXT
NEXTRECORD
NTOC(number)
ONCANCEL(action)
ONERROR(action)
PAGEOFF
PAGEON
POSTNET(string)
PRINT
PROCESSOFF
PROCESSON
PROMPT(message)
QUIT
REPEATROW
RETURN
RETURNCANCEL
RETURNERROR
REWRITE
STATUSPROMPT(message)
STEPOFF
STEPON
STOP
STRLEN(expr)
STRPOS(expr;subexpr)
SUBSTDATA(filename)
SUBSTFORM(filename)
SUBSTR(expr;start;length)
SWITCH(expr)
SYSTEM(sysvar)
TOLOWER(expr)
TOUPPER(expr)
VARIABLE(var)
WAIT(10ths second)
WHILE(expr)
ASSIGN(var;expr)
Use ASSIGN to assign the value returned by expr to the global variable var. You do not need to enclose the expression in quotes.
Expressions are evaluated, and the result is assigned to the variable.
Non-numeric characters and expressions that cannot be evaluated numerically are treated as strings.
After a value has been assigned to a variable, the variable command VARIABLE(var) can be placed anywhere you would normally place the variable contents. To erase a variable (remove it from memory), leave the expr argument empty. For example, you could use the command ASSIGN(Fred;) to erase a variable named Fred. When you erase a variable, it no longer "exists." For information, see IFEXISTS(var).
To assign a local variable, see ASSIGNLOCAL(var;expr).
In the following example, variable Fred is first assigned a value, then an expression, then a string.
CODES(
ASSIGN(Fred;3)
Assign 3 to variable Fred.
ASSIGN(Fred;VARIABLE(Fred)*2)
Multiply old value of variable Fred by 2; assign the result (6) as the new value of variable Fred.
ASSIGN(Fred;WordPerfect)
Assign the string "WordPerfect" to variable Fred.
VARIABLE(Fred)
Return the value of the variable to the document.
)
BEEP
Use BEEP to cause your computer to beep. This command is often useful in combination with CHAR, KEYBOARD, PROMPT, STATUSPROMPT, and GETSTRING, which prompt the user. You can also use it to signal various points of the merge, such as the end of a lengthy process.
The following example sounds a beep at each keyboard pause. The user enters the requested information, then click Continue on the Merge feature bar or presses ALT + ENTER (ENDFIELD) to continue to the next prompt.
MEMO
To: BEEP KEYBOARD(Enter To information)
From: BEEP KEYBOARD(Enter From information)
Date: DATE
Subject: BEEP KEYBOARD(Enter Subject information)
BREAK
Use BREAK to exit from a loop before it would normally end. The location of the command and the type of file it is in determine how it functions.
The rules that govern how BREAK functions are listed below:
Each of the following rules assumes that the previous rules do not hold.
If BREAK is encountered within a FORNEXT or WHILE structure, execution moves to the end of the structure (just after the ENDFOR or ENDWHILE). If these structures are nested, execution moves after the ENDFOR or ENDWHILE command of the current level.
If BREAK is encountered in a nested file, execution returns to the parent file.
If BREAK is encountered in a form file, the merge moves to the top of the form file and continues with the next data record.
If BREAK is encountered in a data file, the merge is terminated.
The following example uses BREAK to exit an infinite loop when the correct number is guessed.
CODES(
ASSIGN(Actual Number;SUBSTR(SYSTEM(random);3;1))
WHILE(1)
CHAR(Guess;Guess a number between 0 - 9?;Guessing Game)
IF(VARIABLE(Guess)=VARIABLE(Actual Number))
BEEP
PROMPT(Correct, the number was VARIABLE(Actual Number))
WAIT(30)
BREAK
ELSE
PROMPT(Sorry, the number wasn't VARIABLE(Guess))
WAIT(10)
ENDIF
ENDWHILE
)
CALL(label)
Use CALL to transfer execution to the label subroutine. When execution of the subroutine is completed (when a RETURN is encountered in the subroutine), execution returns to the command following CALL. For more information about subroutines and labels, see Levels.
The example below is a form file that creates a data file. The Info subroutine is called to get the information for each record.
GETSTRING prompts the user to enter information and assigns the information to a variable. MRGCMND places the necessary merge codes into the data file being created.
When no name is entered for variable name, that variable is erased.
IFEXISTS then returns a false (0), and QUIT is executed, ending the merge.
GETSTRING(name;Enter Name or choose Cancel to Quit;Name)
IFEXISTS(name)
ELSE
QUIT
ENDIF
GETSTRING(address;Enter Address;Address)
GETSTRING(city;Enter City;City)
GETSTRING(state;Enter State;State)
GETSTRING(zip;Enter ZIP Code;ZIP Code)
RETURN
)
CANCELOFF
Use CANCELOFF to stop the ESC key from performing its normal function. CANCELOFF is useful to prevent a user from stopping a merge by pressing ESC.
CANCELOFF
(During this part of the merge, pressing Cancel does not end the merge.)
CANCELON
(During this part of the merge, pressing Cancel does not end the merge.)
CANCELON
Use CANCELON to enable the ESC key after it has been disabled with the CANCELOFF command.
For an example of CANCELON, see CANCELOFF.
CAPS(expr)
Use CAPS to capitalize the first character of each word in the returned expression expr.
To change all letters in a returned expression to uppercase or lowercase, see TOUPPER or TOLOWER. To capitalize just the first word, see FIRSTCAP.
In the example below, CAPS capitalizes the first letter of each word in the name, address, and city variables. TOUPPER capitalizes both letters of the state abbreviation. FIRSTCAP capitalizes the first letter of the first word in the comments string. TOLOWER ensures that the merge will continue if either an uppercase or a lowercase "y" is assigned to VARIABLE(char).
Use CASEOF when using the SWITCH command. When you use CASEOF, you can enter multiple merge expressions within the parentheses.
For examples of CASEOF, see SWITCH and FORNEXT.
CHAINDATA(filename)
Use CHAINDATA to begin using records from the named data file, when the end of the current data file is reached. This command is especially useful if you have broken a large data file into several smaller files. If you insert CHAINDATA in the smaller data files, they will act like one data file.
The following example shows how a large data file has been broken into two smaller files. When you specify the first small file as the data file in a merge, the records of the second small file will be used as soon as those in the first small file are completed.
First Small File:
FIELDNAMES(name;status) ENDRECORD
====================================
PROCESSON CHAINDATA(file2)PROCESSOFF COMMENT(
The PROCESS commands ensure that the CHAINDATA command executes.
The merge stores the CHAINDATA command and filename, then executes it
when the current data file has ended.)
JoseENDFIELD
StaffENDFIELD
ENDRECORD
====================================
(additional records)
====================================
BarbaraENDFIELD
ProfessionalENDFIELD
ENDRECORD
Second Small File (named FILE2 in the default directory):
FIELDNAMES(name;status)
ENDRECORD
====================================
JulieENDFIELD
Part-timeENDFIELD
ENDRECORD
====================================
(additional records)
====================================
ShojiENDFIELD
Leave of AbsenceENDFIELD
ENDRECORD
====================================
CHAINFORM(filename)
Use CHAINFORM to continue the merge with an additional form file after all records have been merged with the current form file.
The following example uses CHAINFORM to merge an envelope form file with the current data file.
CHAINFORM(envelope.frm)
(body of form file)
CHAINMACRO(macroname)
Use CHAINMACRO to start the named macro at the end of the merge, if the merge terminates normally. You can place CHAINMACRO anywhere in the form file.
Only the last macro chained during the merge is executed.
In the following example, the chained macro print.wcm executes when the merge is complete.
CHAINMACRO(print)
COMMENT(Chain the macro PRINT.WCM when the merge is complete.)
DATE
Dear FIELD(Name),
(rest of the letter)
Sincerely,
Chris Smith
CHAR(var[;prompt][;title])
Use CHAR to prompt the user to input a single character. CHAR prompts you with a message and waits until you press a single key.
The pressed key is assigned to the specified variable var. Prompt is the information displayed in the dialog box telling the user what to do.
Title is the title of the dialog box created during the merge.
For an example of CHAR, see CTON.
CODES(merge codes)
Use CODES to enter merge codes and have the merge ignore any formatting or text you might add. The merge carries out all the merge commands inside the CODES parentheses but ignores any text or formatting (such as hard returns). To enter text or formatting inside the CODES parentheses, use the INSERT command.
The following would occur in a form file. When merging with a data file, the example pauses the merge at each record and lets you choose which records you want to merge.
CODES(
LABEL(top)
ASSIGN(field;FIELD(1))
EMBEDMACRO(
PERSIST(fld)
PROMPT("Which name would you like to merge? ";" OK to merge "+field+"?";2)
PAUSE
ENDPROMPT
)
IF(VARIABLE(fld)=2)
INSERT(FIELD(1))
INSERT(FIELD(2))
INSERT(FIELD(3))
====================================
ENDIF
NEXTRECORD
GO(top)
)
For another example of CODES, see CTON.
COMMENT(comment)
Use COMMENT to include comments that will make the merge easier to understand. Merge ignores everything between the COMMENT parentheses.
For an example of COMMENT, see CTON.
CONTINUE
Use CONTINUE at the end of a CASEOF statement to execute the commands in the next CASEOF statement.
For examples of CONTINUE, see SWITCH and FORNEXT.
CTON(character)
Use CTON (Character to number) to convert a character (any character in the WordPerfect character sets) to a unique number (its WordPerfect "key value"). CTON performs the inverse (opposite) function of NTOC. You can use the key value to calculate the WordPerfect character set value.
To calculate the character set value for a given character
1 Use CTON to obtain the key value.
2 Divide the key value by 256.
The quotient is the number of the WordPerfect character set (0-12).
The remainder is the character number in the character set (0-255).
The following example calculates the character set value for a character. Because all the variables are local, this file could be nested within another file and would not change any of the original file's variables, even if they have the same name. The comments in the first part of this merge do not need to be in a COMMENT command, because they are within the CODES command. The final comment must be in a COMMENT command, or it will be inserted in the merged document.
CODES(
ASSIGNLOCAL(char;0)
Initialize a local variable named char.
CHAR(char;Type a character;Display Character Set Value)
Assign input to the variable char.
ASSIGNLOCAL(set;CTON(VARIABLE(char))/256)
Assign quotient to a variable named set.
ASSIGNLOCAL(num;CTON(VARIABLE(char))%256)
Assign remainder to a variable named num.
)
VARIABLE(set),VARIABLE(num)
COMMENT(Write out the character set value.)
DATE
Use DATE to insert the current date in merged documents, as formatted in the Date format feature. The merged file will contain the current date as indicated by your computer's internal clock.
For an example of DATE, see BEEP.
DEFAULT
Use DEFAULT with the SWITCH command to cover all cases not covered by CASEOF. When the expression being tested is different from all the CASEOF expressions, the merge executes DEFAULT.
For examples of DEFAULT, see SWITCH and FORNEXT.
DISPLAYSTOP
Use DISPLAYSTOP to stop the display of text after a KEYBOARD command. For example, after a KEYBOARD command, the merge displays as many as 1000 characters ahead. DISPLAYSTOP placed in text after KEYBOARD stops the text from displaying from that point on.
DATE
FIELD(name)
FIELD(address)
FIELD(city)
Dear FIELD(name):
It has come to our attention that your bill has not been paid. Please send us $KEYBOARD(Enter how much they owe us-Press ALT+ENTER or choose Continue when done), which is the balance of your unpaid account.DISPLAYSTOP
If the balance of your account is not paid in KEYBOARD(Enter how many days-Press ALT + ENTER or choose Continue when done) days, we will be forced to take legal action.DISPLAYSTOP
If you have already made arrangements to settle your account, please disregard this notice.
The rest of the letter after DISPLAYSTOP does not display on the screen while the user is prompted to type information at the keyboard.
This removes distracting information from the screen, so users can focus their attention on the area where they are to enter information.
DOCUMENT(filename)
Use DOCUMENT to insert the named document into the merged document at the DOCUMENT command. The document is not processed as a merge file, so any merge commands in the inserted document are included in the file but not executed. This command is commonly used for inserting variable paragraphs in contracts and similar documents (often called document assembly) or for building a form or data file.
In the following example, DOCUMENT inserts the document called oneroom.mrg in the merged document if the variable rooms is equal to 1, or it inserts the document tworooms.mrg if the variable rooms is not equal to 1.
CODES(
CHAR(rooms;Enter the number of rooms (1 or 2); Number of Rooms)
IF(VARIABLE(rooms)=1)
DOCUMENT(c:\mrgfiles\oneroom.mrg)
ELSE
DOCUMENT(c:\mrgfiles\tworooms.mrg)
ENDIF
)
ELSE
Use ELSE with IF, IFBLANK, IFEXISTS, IFNOTBLANK, and ENDIF. ELSE marks the beginning of the commands that execute should the IF value be zero (false).
ELSE is not a required 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 zero (false).
Commands that appear after ENDIF execute whether or not the IF value is true.
For an example of ELSE, see DOCUMENT.
EMBEDMACRO(macro statements)
Use EMBEDMACRO to embed macro commands within a merge. You can enter any macro command inside the EMBEDMACRO parentheses. The macro commands are compiled the first time they are encountered during the merge.
For an example of EMBEDMACRO, see CODES.
ENDFIELD
Use ENDFIELD to signal the end of a field in a data file. A hard return [HRt] is automatically inserted with this command to make the file easier to read.
When you insert this command, the number of the field where the cursor is currently located displays at the bottom of the window. If you use FIELDNAMES, the name of the field appears instead of the number.
Records in the following data file have three fields:
International ExportingENDFIELD
(801) 555-4421ENDFIELD
George WileyENDFIELD
ENDRECORD
====================================
Tradewinds, Inc.ENDFIELD
(409) 555-3567ENDFIELD
Susan EscherENDFIELD
ENDRECORD
====================================
ENDFOR
Use ENDFOR to signal the end of FORNEXT and FOREACH loops.
For an example of ENDFOR, see FORNEXT.
ENDIF
Use ENDIF to mark the end of an IF structure. ENDIF is used with IF, IFBLANK, IFEXISTS, IFNOTBLANK, and ELSE.
For an example of ENDIF, see DOCUMENT.
ENDRECORD
Use ENDRECORD to signal the end of a record in a data file. A hard page break is inserted automatically with this command to make the file easier to read.
When you insert this command, the number of the field where the cursor is currently located displays at the bottom of the window. If you use FIELDNAMES, the name of the field appears instead of the number.
For examples of ENDRECORD, see ENDFIELD and FIELDNAMES.
ENDSWITCH
Use ENDSWITCH to end a SWITCH statement.
For an example of ENDSWITCH, see SWITCH.
ENDWHILE
Use ENDWHILE to signal the end of a WHILE loop.
For an example of ENDWHILE, see NEXTRECORD.
FIELD(field)
Use FIELD to insert the contents of the named (or numbered) field in the merged document or in another merge command.
In the following example, the contents of the name and address fields are inserted in the letter.
FIELD(name)
FIELD(address)
Dear FIELD(name):
For additional examples of FIELD, see DISPLAYSTOP.
FIELDNAMES(name1;...;nameN)
Use FIELDNAMES to declare the names and order of the fields in a data file. Using this command in the data file allows you to reference the fields by name in a form file, which is usually easier than remembering the order of the fields and referencing them by number.
WordPerfect places FIELDNAMES at the top of the data file. It must be located at the top of the file to work correctly. If records have more fields than those declared in FIELDNAMES, additional fields are numbered. When initially inserted, the command and field names are all on one line. You may find it easier to read if you put each field name on a separate line, as in the example below. A hard page code [HPg] is automatically inserted when you insert ENDRECORD.
After you insert this command, the name or number of the field where the cursor is currently located displays on the status bar at the bottom of the window.
In the following example, the first three fields of each record are named using FIELDNAMES. The additional fields are not named and are therefore numbered Field 4, Field 5, and so on.
FIELDNAMES(
company;
phone;
contact;
)ENDRECORD
====================================
International ExportingENDFIELD
(801) 555-4421ENDFIELD
George WileyENDFIELD
FurnitureENDFIELD
45ENDFIELD
$1.5 millionENDFIELD
ENDRECORD
====================================
Tradewinds, Inc.ENDFIELD
(409) 555-3567ENDFIELD
Susan EscherENDFIELD
MemorabiliaENDFIELD
200ENDFIELD
$2.0 millionENDFIELD
ENDRECORD
====================================
For another example of FIELDNAMES, see CHAINDATA.
FIRSTCAP(expr)
Use FIRSTCAP to capitalize the first letter of the first word in the returned expression expr.
For an example of FIRSTCAP, see CAPS.
FOREACH(var;expr1;...;exprN)
Use FOREACH to assign a list of items to one variable var. The merge then executes the subsequent commands for each expr listed in FOREACH, changing var to the next value at the end of each loop.
For example, the following codes assign different days of the week to the variable weekday until it matches the field day.
Use FORNEXT to execute a series of commands a certain number of times. The commands between FORNEXT and ENDFOR are executed once for each value of var between start and stop inclusive, as incremented by step.
The start, stop, and step values can be entered in the command as expressions, variables, or other commands. Each expression, variable, or command is evaluated, and the resulting value is assigned to the variable. The step value is optional; its default value is 1 (or -1, if stop is less than start).
In any FORNEXT loop, ENDFOR must be used to determine the end of the series of commands included in the loop. ENDFOR sends execution to the top of the loop for the next iteration. You can also use NEXT to send execution to the next iteration, but you must still include ENDFOR to mark the end of the loop.
FORNEXT initializes the variable with the start value. If the variable has not been assigned, it is defined as a local variable. You do not need to pre-assign the variable. Each subsequent time FORNEXT is executed (at the top of the loop), the variable is incremented by the step value.
The example below uses a FORNEXT loop to apply a SWITCH statement once for each character in the sentence that is entered.
CODES(
GETSTRING(sentence;Type a sentence;Sentence To Be Evaluated)
Use GETSTRING to prompt the user by displaying a dialog box.
Information returned by the dialog box is assigned to the variable var.
Prompt is the information displayed in the dialog box telling the user what to do. Title is the title of the dialog box created during the merge.
For an example of GETSTRING, see CAPS.
GO(label)
Use GO to transfer execution to the location in the merge file indicated by label. It is used in conjunction with LABEL, which marks the place to which execution is transferred.
GO is useful when you want to skip a part of your merge or transfer control to another part based on a condition. Unlike CALL, GO does not require the merge to return to that point of execution.
For an example of GO, see CAPS.
IF(expr)
Use IF to execute a set of commands only if a certain condition exists.
If the condition exists (expr is evaluated to be true), the commands between the IF and ENDIF are executed. If an ELSE is included, the commands between the IF and ELSE are executed if the expression is true; otherwise, the commands between the ELSE and ENDIF are executed.
The expr argument is usually a logical expression. An expression 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.
An IF statement always begins with IF and ends with ENDIF. If you want certain commands to execute only when the value is not true, use ELSE.
For an example of IF, see DOCUMENT.
IFBLANK(field)
IFBLANK(field) Use IFBLANK to execute a set of commands if the indicated field is blank. Be sure to end the set of commands to be executed with an ENDIF command. See also IFNOTBLANK.
In the following example, the data file records have a Title field and a Name field. The merge determines if the Title field of the current record is blank. If it is blank, only the name is inserted in the merged document. Otherwise, the merge inserts the title before the name.
CODES(
IFBLANK(title)
If the Title field is blank in this record,
INSERT(FIELD(name))
Write out just the Name.
ELSE
Otherwise,
INSERT(FIELD(title) FIELD(name))
Write the Title before the Name.
ENDIF
End of IFBLANK statement.
)
IFEXISTS(var)
Use IFEXISTS to check if the indicated variable has been defined. If it has, the commands following IFEXISTS are executed. Like other IF statements, IFEXISTS requires an ENDIF and can use an ELSE command.
The following commands could be placed at the end of any form file.
They cancel the merge if any key is pressed.
LOOK(Key)
IFEXISTS(Key)
STOP
ENDIF
IFNOTBLANK(field)
Use IFNOTBLANK to execute a set of commands if the indicated field is not blank. Be sure to end the set of commands to be executed with an ENDIF command. See also IFBLANK.
In the following example, the data merge file records have a Title field and a Name field. The merge determines if the Title field of the current record is blank. If it is not, the title is inserted before the name. Otherwise, the merge inserts only the name.
CODES(
IFNOTBLANK(title)
If the Title field is not blank in this record,
INSERT(FIELD(title) FIELD(name))
Write the Title before the Name.
ELSE
Otherwise,
INSERT(FIELD(name))
Write out only the Name.
ENDIF
End of IFNOTBLANK statement.
)
INSERT(text)
Use INSERT to enter text or formatting inside a CODES command.
For example, the merge will not recognize a hard return inside the CODES parentheses. To make the merge return a hard return, use INSERT, then press hard return.
For examples of INSERT, see IFNOTBLANK and NESTMACRO(macroname).
KEYBOARD([prompt])
Use KEYBOARD to pause an executing merge so the user can enter information from the keyboard. As many as 1,000 characters of the form file are displayed. Merge codes are displayed using the current display setting. The merge continues when you click Continue on the Merge feature bar or press ALT + ENTER (ENDFIELD).
While an executing merge is paused at KEYBOARD, you can execute QUIT, NEXTRECORD, or STOP from the keyboard.
In the following example, the KEYBOARD commands pause to let you enter the "From:," "To:," and "Subject:" text as the merge is executed.
MEMO
To: BEEP KEYBOARD(Enter To information)
From: BEEP KEYBOARD(Enter From information)
Date: DATE
Subject: BEEP KEYBOARD(Enter Subject information)
If KEYBOARD is executed within another merge command, a dialog box displays with the indicated prompt. You cannot execute commands from the keyboard, but any text entered at the prompt is inserted into the merged document.
LABEL(label)
Use LABEL to mark a place in the merge file. Execution can be sent directly to the label from any place in the merge file. CALL and GO are used to send execution to the label.
The label name distinguishes one label from another. Label names can be as many as 30 characters long, including spaces. Different labels in the same merge file must have different names. If a name is duplicated, the first one is used, and the other is ignored.
Do not assign a label and local variable the same name, or the merge may not function properly.
For examples of LABEL, see CALL and CAPS.
LOOK(var)
Use LOOK to determine if a key has been pressed. If it has, that key is assigned to the variable; it is not executed. If no key has been pressed, the variable is deleted; execution continues without stopping.
For an example of LOOK, see IFEXISTS.
MRGCMND(merge codes)
Use MRGCMND to insert text, codes, and commands in the document being created by the merge. Any text, codes, or merge commands that appear between the MRGCMND parentheses are sent directly to the merged document without the commands being interpreted or executed.
For an example of MRGCMND, see CALL.
NESTDATA(filename)
Use NESTDATA to interrupt the use of the current data file and switch to another data file during the merge. The parent data file then continues only when the merge on the nested data file has been completed. You can nest data files as many as 10. For information, see Levels.
If you nest from within one data file to another, be careful to avoid infinite loops. Use CANCEL or BREAK to terminate the loop.
When you nest a data file, the switch to that file occurs immediately.
When you chain data files, the switch to the new data file is made when the end of the current data file is reached. For more information, see CHAINDATA.
For an example of NESTDATA, see NESTFORM.
NESTFORM(filename)
Use NESTFORM to turn control of the merge over to another form file. When the commands in the nested file have been executed, control returns to the original form file, where execution resumes after NESTFORM. For information on how to change the data file, see NESTDATA.
You can nest form files as many as 10. Using NESTFORM without specifying a filename is the same as using SUBSTFORM with the current form filename as the argument. In this case, NESTFORM does not use one of the 10 nest levels. For more information, see Levels.
FIELD(name),
It has been a pleasure serving you this year.
CODES(
IF(FIELD(balance)!=0)
NESTDATA(transact.dat)
NESTFORM(invoice.frm)
ENDIF
)
Sincerely,
NESTMACRO(macroname)
Use NESTMACRO to execute the named macro during a merge.
When the macro is finished, the merge continues with the code following NESTMACRO.
Macros created in earlier versions of WordPerfect (before version 6.x) will need to be converted.
The following example nests a macro that computes the interest on an account balance.
CODES(
ASSIGN(balance;FIELD(balance))
NESTMACRO(calcint)
INSERT(Interest on this balance is VARIABLE(interest))
)
NEXT
Use NEXT to execute the next iteration of a FORNEXT, FOREACH, or WHILE loop. Usually, the ENDFOR or ENDWHILE that ends the loop sends execution to the next iteration. However, you can use NEXT to send execution to the next iteration from anywhere within the loop. For example, you may use nested IF statements as part of the loop. Then, when a certain condition is true, execution will skip the rest of the commands in the loop and go to the next iteration. In this case, you would use NEXT at the point where you want the next iteration to begin.
Even if you use NEXT in a loop, you must still use an ENDFOR or ENDWHILE to mark the end of the loop.
The following merge writes **********@@@@@.
CODES(
FORNEXT(i;1;15;1)
Repeat the loop 15 times, starting at 1, ending at 15, in
increments of 1.
IF(VARIABLE(i)10)
If variable i is greater than 10,
INSERT(@)
write an @,
NEXT
and skip to the next iteration of this FORNEXT loop.
ENDIF
INSERT(*)
Write an * each time the loop is completed.
ENDFOR
)
NEXTRECORD
Use NEXTRECORD to move the record pointer in the data file to the next record. If it does not find the next record, it ends the merge or returns the merge to the previous data file if the data file was nested.
While an executing merge is paused at KEYBOARD, you can execute NEXTRECORD from the keyboard.
In this example, the data file is searched until the variable company name matches the company field in the data file. When a match is found, the contents of the amount field for that record in the data file are written to the merged document.
CODES(
WHILE(VARIABLE(Company Name)!=FIELD(Company))
NEXTRECORD
ENDWHILE
)
FIELD(Amount)
NTOC(number)
Use NTOC (Number to character) to convert a WordPerfect key value or character set number to its character equivalent. It performs the inverse function of CTON. For example, the NTOC of 294 is ╟.
To calculate the key value for a given character set value
Multiply the character set number by 256, then add the number of the character.
For example, "╟" is character number 38 in Character Set 1.
Multiply 256 times 1 (256), then add 38 (294). The NTOC of 294 is ╟.
NTOC will return nothing if you enter a number that is not equivalent to a character.
The following example prompts for a number, then returns the character equivalent.
GETSTRING(num;Enter a key value number;)
NTOC(VARIABLE(num))
ONCANCEL(action)
Use ONCANCEL to specify what the merge does if you press ESC (Cancel) or if a RETURNCANCEL has been returned by a subroutine, a nested macro, or a nested merge. When a Cancel occurs, the merge performs the default action (STOP) if it has not already encountered the ONCANCEL command. For this reason, it is a good idea to place the command before a Cancel can occur, otherwise execution will terminate when ESC is pressed. If no action is specified in ONCANCEL, the cancel is ignored, and execution continues as if there had been no cancel.
Valid actions available with this command are:
BREAK
CALL
GO
QUIT
RETURN
RETURNCANCEL
RETURNERROR
STOP
When ESC is pressed, the last ONCANCEL command encountered in the file is executed.
ONCANCEL is local to the file in which it is encountered. It cannot be used from other files. For example, a data file cannot use ONCANCEL from a form file.
In the following example, if you press ESC during the merge, the end subroutine is executed.
CODES(
ONCANCEL(GO(end))
If ESC is pressed during the merge, execute the End
subroutine.
(commands in form file)
STOP
LABEL(end)
Beginning of End subroutine.
PROMPT(Merge canceled prematurely.)
Send notification message.
WAIT(40)
Display message for 4 seconds.
STOP
Terminate execution.
)
For another example of ONCANCEL, see RETURNCANCEL.
ONERROR(action)
Use ONERROR to tell WordPerfect what to do if an error is detected in merge execution or if a RETURNERROR has been returned by a subroutine or nested macro or merge.
Inserting ONERROR without an action causes the merge to ignore the error and continue execution when possible.
The errors that can be trapped with this command are:
File not found
Print queue errors
End of file condition returned by a NEXTRECORD
If you chain a file that does not exist or is not found, the error condition is not generated until the merge tries to execute the chained file (that is, at the end of the current merge file). For more information, see also CHAINDATA, CHAINFORM(filename), and CHAINMACRO.
The default action is STOP. For a list of other possible actions, see ONCANCEL.
ONERROR is local to the file in which it is encountered. It cannot be seen from other files. For example, a data file cannot use ONERROR from a form file.
In the following example, a new form file is nested. ONERROR specifies that subroutine error be executed if the file is not found when the merge tries to nest it.
CODES( ONERROR(GO(error))
If an error is generated, execute the Error subroutine.
(more merge commands)
NESTFORM(invoice.frm)
(more merge commands)
STOP
LABEL(error)
If the file was not found when the merge tried to nest it,
execution moves here.
PROMPT(File not found. Move INVOICE.FRM to default directory and start merge again.)
Send a message to the user.
WAIT(15)
Display the message for 1.5 seconds.
STOP
Terminate execution.
)
For another example of ONERROR, see RETURNERROR.
PAGEOFF
Use PAGEOFF to eliminate the hard page code [HPg] between copies of the form file in the merged document. Use PAGEON to begin inserting hard page codes again after you have used PAGEOFF.
PAGEON and PAGEOFF are global to the merge; they may be included in any form or data file and are in effect for all the files in the merge until the opposite command is encountered. PAGEOFF and PAGEON override the option set in the Merge Run dialog box.
These commands are useful for merging labels or for including multiple records in a document. You can also use PAGEOFF with PRINT to eliminate blank pages between copies of the merged document when merging to the printer.
For an example of PAGEOFF, see PAGEON.
PAGEON
Use PAGEON to reinstate the use of hard page codes between copies of the form file in the merged document. See also PAGEOFF.
In the example below, the nested form file, list.pf, creates a list of players on a given team. The final result of the merge is a list of the players on each team, one team per page.
CODES(
ASSIGN(team;FIELD(team))
Assign the current field to a global variable so that the nested
form file can use it.
INSERT(These people are on Team FIELD(team):)
PAGEOFF
This command prevents the insertion of a hard page between
iterations of the nested form file.
NESTFORM(list.frm)
This form file produces a list using the Name field of
all records whose Team field matches the current Team variable.
PAGEON
This command restores the use of page breaks to allow one team
list per page.
)
POSTNET(string)
Use POSTNET to insert a POSTNET bar code into a form file for letters, envelopes, or labels. For the string parameter, you can type the bar code digits or enter a field for the digits.
The following is a sample form file for an envelope including the return address and a POSTNET bar code:
JASPER DEAN
2745 CHARLES DU DRE PKWY
MADISON WI 53725-9876
POSTNET(FIELD(zipcode))
FIELD(name)
FIELD(address)
FIELD(city/state) FIELD(zipcode)
When this form file is merged, the mailing address will return a different name, address, city/state, and bar code for each record.
PRINT
Use PRINT to send the current merged text to the printer. Once the text is sent to the printer, it is no longer in the merged document.
When you merge to the printer using this command, the usual page break is still inserted between each iteration of the form file. To eliminate the extra page between each copy, insert PAGEOFF before PRINT as shown in the example.
The data file to be used with the form file in the following example contains 1,000 records. If you were to merge it to the document window, the resulting document would have 1,000 pages. This merge uses PRINT to send each letter to the printer as soon as it is merged.
ABC COMPANY
245 WEST CENTER STREET LONG BEACH CA 90807
DATE
FIELD(name)
FIELD(company)
Dear FIELD(firstname):
Thank you for your inquiry regarding our new product.
(rest of letter)
Sincerely,
Amy Wilcox
Product Manager
PAGEOFF PRINT
PROCESSOFF
Use PROCESSOFF to end a PROCESSON command.
For an example of PROCESSON and PROCESSOFF, see CHAINDATA.
PROCESSON
Use PROCESSON with PROCESSOFF in a data merge file to ensure that codes are processed even if they are not in the field or record being processed by the form file.
For an example of PROCESSON and PROCESSOFF, see CHAINDATA.
PROMPT(message)
Use PROMPT to display a message that gives instructions to the user.
For examples of PROMPT, see ONCANCEL and ONERROR.
QUIT
Use QUIT to stop the execution of the merge. For example, while a merge is paused at KEYBOARD, you can execute QUIT from the keyboard.
In a merge, the rest of the form file after QUIT is written out to the resulting merged document before the merge terminates, but any commands after QUIT are not executed. If you don't want the rest of the form file written out, use STOP instead of QUIT.
If QUIT is used in a data file, the data file is abandoned at that point.
However, the rest of the form file is written out (but not processed) just as if the command had been encountered in the form file. The merge then terminates.
The following example is a standard memo sent by a personnel department to all employees before their six-month salary review. The merge ends just after the DATE command, but the rest of the memo is written out to the resulting merged document.
MEMO
To: KEYBOARD(Enter To information)
From: Kim Charleston, Personnel
Date: DATE QUIT
Subject: Six-month Review Preparation
====================================
(rest of memo)
REPEATROW
Use REPEATROW when merging information into a table from a data file. The REPEATROW command in a row inserts that row for each record in the data file.
RETURN
Use RETURN to mark the end of a subroutine and signal the merge to return from a CALL command. RETURN must be paired with CALL, or an error message displays.
For an example of RETURN, see CALL.
RETURNCANCEL
Use RETURNCANCEL to cause execution to leave the current level and return a Cancel to the next higher level. For more information, see Levels.
In this example, RETURNCANCEL is used to return a cancel from a status checking subroutine.
CODES(
ONCANCEL(GO(send message))
(During this part of the merge, if the user presses Cancel,
execution is transferred to the Send Message label.)
CALL(check status)
(more merge commands)
STOP
LABEL(check status)
IF(VARIABLE(chk)=0)
RETURNCANCEL
ELSE
RETURN
ENDIF
)
If the chk variable equals FALSE (0), then the ONCANCEL condition is executed; if it is TRUE, then it returns without executing the ONCANCEL condition.
RETURNERROR
Use RETURNERROR to cause execution to leave the current level and return an error to the next higher level. For more information, see Levels.
In this example, RETURNERROR returns an error from a subroutine that nests a form file.
CODES(
ONERROR(GO(error))
If an error is generated, execute the Error subroutine.
(more merge commands)
CALL(getfile)
(more merge commands)
STOP
LABEL(getfile)
ONERROR(RETURNERROR)
NESTFORM(invoice.frm)
RETURN
LABEL(error)
If the file was not found when the merge tried to nest it,
execution moves here.
PROMPT(File not found. Move INVOICE.FRM to default directory and start merge again.)
Send a message to the user.
WAIT(15)
Display the message for 1.5 seconds.
STOP
Terminate execution
)
REWRITE
Use REWRITE to rewrite the document window. Since none of the merged document is written to the document window during a merge, you may want to use this command to display what has been merged at a certain point.
In the following example, REWRITE is used to view each letter on the screen as it is merged.
ABC COMPANY
245 WEST CENTER STREET LONG BEACH CA 90807
DATE
FIELD(name)
FIELD(company)
Dear FIELD(firstname):
Thank you for your inquiry regarding our new product.
(rest of the letter)
Sincerely,
Amy Wilcox
Product Manager
REWRITE
STATUSPROMPT(message)
Use STATUSPROMPT to display a message. The message is displayed during the merge. The message stays in the message window until it is cleared by another command that uses the message window, such as another STATUSPROMPT or a KEYBOARD command.
For example, if you always run two merges one after the other, you could use STATUSPROMPT to display the prompt "Merge 1 has been completed" at the end of the first merge.
(Main body of first form file)
STATUSPROMPT(Merge 1 has been completed.)
You could then clear the message window at the end of the second merge by using STATUSPROMPT with no parameters.
(Main body of second form file)
STATUSPROMPT()
STEPOFF
Use STEPOFF to turn off a single step execution after it has been turned on. See also STEPON.
STEPON
Use STEPON for debugging merges. It causes the merge to execute one step at a time. Between each step, a message indicates what the next command is. The command executes when the user presses any key. Each character is displayed after it is written out to the resulting document.
You may find it useful to step through merges with Reveal Codes on.
(This section will execute normally.)
STEPON
(This section will execute one keystroke at a time.)
STEPOFF
(This section will execute normally.)
STOP
Use STOP to stop all execution. It is similar to QUIT, except that the rest of the form file is not read in. If this command is found in a nested file, execution is not returned to the parent file. Chained files are also not executed.
While an executing merge is paused at KEYBOARD, you can execute STOP from the keyboard.
For an example of STOP, see IFEXISTS.
STRLEN(expr)
Use STRLEN to determine the length of a variable or of the value returned by an expression. This command is useful for validating or restricting the length of user input.
You can use FIELD, VARIABLE, text, or complex expressions in the argument expr.
For an example of STRLEN, see SUBSTR.
STRPOS(expr;subexpr)
Use STRPOS to determine the position of a subexpr within an expr.
For an example of STRPOS, see SUBSTR.
SUBSTDATA(filename)
Use SUBSTDATA to change to the named data file and start with the first record in that file. The merge does not return to the original data file. If you substitute a file that is not found, or no file, an error is returned. You can use ONERROR to determine what should happen if this error occurs.
In the following example, two data files are used, each sorted by ZIP Code in descending order, so that any records where the ZIP field is blank will be at the end of the file. SUBSTDATA causes the records with no ZIP Code to be skipped, and the next data file to be used.
CODES(
IFBLANK(ZIP)
SUBSTDATA(file2.dat)
ENDIF
)
SUBSTFORM(filename)
Use SUBSTFORM to change to the named form file. SUBSTFORM is similar to NESTFORM and CHAINFORM. The difference is that the named form file is used instead of the current form file from the point of this command on. The merge does not return to the original form file; no commands following this one in the original form file are executed. Local variables in a previous form file are erased.
If you substitute either a file that is not found or no file, an error is returned. You can use ONERROR to determine what should happen if this error occurs.
In the following example, the data file has a Days Overdue field. The merge begins using the form file invoice.frm, which substitutes a different form file depending on the number in the Days Overdue field.
At the end of each substituted file, the record pointer is moved to the next record, and invoice.frm is substituted, so that it will execute again.
CODES(
ASSIGN(days;FIELD(Days Overdue) DIV 30)
SWITCH(VARIABLE(days))
CASEOF(0)
SUBSTFORM(under30.frm)
CASEOF(1)
SUBSTFORM(under60.frm)
CASEOF(2)
SUBSTFORM(under90.frm)
DEFAULT
SUBSTFORM(90&over.frm)
ENDSWITCH
)
In this example, the following code would be placed at the end of each substituted form file.
(body of file)
NEXTRECORD
SUBSTFORM(invoice.frm)
SUBSTR(expr;start;length)
Use SUBSTR to extract a portion (substring) of the expression specified in the expr parameter. You can specify which part of the expression to use with the start and length parameters. The start parameter counts from the left side of the expr. The length parameter specifies how many characters are included in the substring.
For example, if a form file contains the statement SUBSTR(think;2;2), the substring "hi" is inserted into the merged document. The start parameter has the value 2, so the substring begins with the second character in the expr parameter ("h."). The count parameter has the value 2, so the substring contains two characters ("h" and "i").
You can use FIELD, VARIABLE, text, or complex expressions in the argument expr.
In this example, the data file has a name field where the names are stored in the format "Last, First." SUBSTR extracts the first name from the name field. STRPOS is used to find the beginning of the first name (2 characters after the start of the comma and space). STRLEN is used to find the length of the first name (by subtracting the starting position of the first name from the length of the full name).
Use SWITCH with CASEOF, CONTINUE, DEFAULT, and ENDSWITCH to evaluate input and execute different functions depending on the input.
The expression in SWITCH must match the expression in CASEOF exactly. For example, "y" does not match "Y." If no match is found in the SWITCH statement, execution continues after the SWITCH statement. You can use DEFAULT as the last case in the command to handle all cases that do not match. You can use CONTINUE to perform the commands for more than one case.
In the following example, SWITCH is used to include certain documents in the merge file based on the value of the class field in a data file. If the class field does not match any of the first three cases, DEFAULT is executed, and the file general.fil is included in the merged document.
Because each of the other cases ends with CONTINUE, the DEFAULT case and any cases following the one selected are executed along with the case selected. For example, if the class field contains 2nd, then the files 2ndclass.fil, 3rdclass.fil, and general.fil would all be included in the merged document for that record.
Dear FIELD(name):
You have chosen to travel FIELD(class) class. This allows you to enjoy the following benefits during your trip:
CODES(
SWITCH(FIELD(class))
CASEOF(1st)
DOCUMENT(1stclass.fil)
CONTINUE
CASEOF(2nd)
DOCUMENT(2ndclass.fil)
CONTINUE
CASEOF(3rd)
DOCUMENT(3rdclass.fil)
CONTINUE
DEFAULT
DOCUMENT(general.fil)
ENDSWITCH
)
For another example of SWITCH, see FORNEXT.
SYSTEM(sysvar)
Use SYSTEM to return the value of the given system variable. System variables allow the merge to be aware of the current state of WordPerfect.
In the following example, the merge includes only the first three records of the form file. When the merge reaches the fourth page of the resulting merge document, it stops.
CODES(
IF(SYSTEM(Page)=4)
STOP
ENDIF
)
(Body of the form file)
System variables are listed on the Parameter Entry dialog box when you choose the SYSTEM command.
TOLOWER(expr)
Use TOLOWER to lowercase each character in the returned expression expr.
For an example of TOLOWER, see CAPS.
TOUPPER(expr)
Use TOUPPER to uppercase each character in the returned expression expr.
For an example of TOUPPER, see CAPS.
VARIABLE(var)
Use VARIABLE to access the contents of global and local variables. If you have both a global and a local variable with the same name, this command accesses the local variable. There is no way to access global variables while local variables of the same name exist. For an explanation of global and local variables, see Merge variables.
After you assign a value to a variable (using ASSIGN(var;expr) or ASSIGNLOCAL(var;expr)), you can place the VARIABLE command anywhere you would normally place the variable contents. You can place it as an argument for another command, as part of an argument for another command, or by itself.
For an example of VARIABLE, see SUBSTR.
WAIT(10ths second)
Use WAIT to delay further execution of the merge for the indicated time. This command is useful when you want a message to be displayed for a certain amount of time. The wait time is specified in tenths of a second (20 = 2 seconds).
For an example of WAIT, see ONCANCEL.
WHILE(expr)
Use WHILE to execute commands repeatedly. While the expression expr is true, the commands between WHILE and ENDWHILE are repeatedly executed. This command is like FORNEXT, except that it does not increment a value each time through the loop. In order to end the loop, you must use BREAK or another command that will force the expression to be evaluated as false. For more information, see Loops.
Remember that if you use a variable in expr, the variable must already exist before the WHILE command is executed.
For an example of WHILE, see NEXTRECORD.
ASSIGNLOCAL(var;expr)
Use ASSIGNLOCAL to assign the value returned by expr to the local variable var. Local variables are accessible only to the current file; they are deleted when the merge is finished or the file is exited. See also ASSIGN(var;expr)
For an example of ASSIGNLOCAL, see CTON.
Working with levels, loops, and merge variables
The following topics provide information about using levels, loops, and merge variables when you program a merge.
Levels
Loops
Merge variables
System variables compared to user defined variables
Global variables compared to local variables
Naming variables
Variable contents
Assigning variables
Executing variables
Variable duration
Operations on variables
Levels
In a merge document you can have as many as 40 levels of execution per file. IF commands do not require a level; they can be nested indefinitely. Each SWITCH, FORNEXT, or WHILE uses one level.
NESTMACRO, NESTFORM, and NESTDATA do not require an execution level, because each nested file has 40 new execution levels.
However, they do require a nesting level. You can nest files 10 deep.
Merge uses separate stacks to maintain execution levels and nesting levels.
Merge variables
A variable represents a place in memory where data is stored. As its name indicates, the data in a variable is changeable. You can use variables to calculate and keep track of text and numeric values that change during a merge.
System variables compared to user defined variables
There are two major types of variables in WordPerfect: system variables and user-defined variables. System variables are variables that WordPerfect creates and maintains; they contain information about the current state of the application. You cannot change the names or contents of these variables, but you can use their contents at any given time. System variables are listed on the Parameter Entry dialog box when you choose the System command.
User-defined variables are variables that you create. You determine the name and contents of these variables when you assign them. You can also perform operations on them to change their contents. There are two subcategories of user-defined variables: global and local.
Global variables compared to local variables
Global variables are accessible from anywhere inside a merge or a macro. All global merge variables can be read by macros; macro variables can be read by merge commands if the PERSIST command is used in the macro.
Local variables are available only in Merge and are stored in a place in memory separate from global variables. They are accessible only from the file in which they are defined. For example, if you create a local variable named Number in a form file, the data file or other form files cannot access the information stored in it. When you nest merge files, the local variables in the parent file cannot be used in the nested file.
When you return to the parent file, the local variables in the nested file no longer exist, but the local variables in the parent file are once again accessible.
Local variables take precedence over global variables. For example, suppose you have both a global and a local variable named Number. If you try to access the global variable Number from inside a file where the local variable Number is accessible, you will get the contents of the local variable. The global variable Number still exists, but is inaccessible until you are no longer accessing the current merge file.
Naming variables
Variable names can be as many as 30 characters long for both global and local variables. Although you can use the same name for a local and a global variable, you cannot use the same name for any two local variables or any two global variables. You should not use the same name for a local variable and a label.
Variable names are not case sensitive. Abc, AbC, ABC, and abc are read as the same variable.
Variables receive their names when they are assigned. For more information, see Assigning variables.
Variable contents
All user-defined variables can contain text or numbers. A user-defined variable can hold 127 characters.
Assigning variables
You assign a global variable with ASSIGN and a local variable with ASSIGNLOCAL. For example, the following two statements assign two different variables, one global and one local:
ASSIGN(Number;45)
ASSIGNLOCAL(Number;36)
ASSIGN creates a global variable named Number with "45" as its contents. ASSIGNLOCAL creates a separate, local variable named Number with "36" as its contents. For more information, see ASSIGN(var;expr) and ASSIGNLOCAL(var;expr).
In addition to using ASSIGN and ASSIGNLOCAL, the following commands also assign variables:
CHAR
FOREACH
GETSTRING
LOOK
The following rules determine whether the variable assigned by CHAR, GETSTRING, and LOOK are local or global in a merge:
If a local variable with the name used in the command exists, the command assigns the value to the local variable.
If no local variable with the name used in the command exists, but a global variable by that name does exist, the command assigns the value to the global variable.
If no variable with the name used in the command exists, a global variable of that name is created and assigned by the command.
FOR and FOREACH in Merge assign variables by the same rules as above, except that if no variable with the name used in the command exists (the third rule), a local variable is created and assigned by the command. This feature allows recursion using FOR and FOREACH in Merge.
If a variable already exists and you assign new contents to it, the previous contents will be replaced without warning.
Executing variables
You can execute (write out) a variable anywhere you want its contents to appear. For example, by executing a variable you can do the following:
Use the contents of the variable as a subroutine
Insert the contents as text in a document or in the message strings of programming commands
Provide variable arguments in other programming commands
To execute a variable, use VARIABLE. For example, the statement VARIABLE(Number) would execute the variable named Number.
Variable duration
Local variables exist only in the file in which they are defined. Once you quit the file that defined the variables or once the merge ends, the local variables are erased (and the memory assigned to them is released). However, the contents of global variables remain in memory until you exit WordPerfect. To conserve memory, you should use local variables instead of global variables whenever possible.
If you want to erase a variable without exiting a file or exiting WordPerfect, assign nothing to the variable by using the following commands: ASSIGN(var;) or ASSIGNLOCAL(var;). These commands empty the variable of its contents and release the memory used by the variable. After you use this command, the variable no longer exists. It is a good idea to empty variables at the beginning of the merge in which they are used (unless the merge assigns new contents to them).
Operations on variables
All variables can be compared to each other, and user-defined variables can have other operations performed on them. Operations are performed using various programming commands. See "Working with merge expressions" and "Merge Programming Commands."
Loops
Whenever the same commands repeat several times, that section of the merge is called a loop. When you create a loop, it is very important to have a way for the loop to end. If the loop does not have an end, there is no way to stop execution without pressing ESC or CTRL + ENTER.
There are many types of loops you can create with merge programming commands.
You can use an IF structure or you can use FORNEXT or WHILE. You can also create loops by going to or calling subroutines (with GO or CALL). The structure you should use for any given loop depends on the task you are trying to accomplish.
Working with merge expressions
Merge expressions are used to determine values in the ASSIGN, ASSIGNLOCAL, CAPS, CASEOF, CTON, FIRSTCAP, FOREACH, FORNEXT, IF, NTOC, STRLEN, STRPOS, SUBSTR, SWITCH, TOLOWER, TOUPPER, and WHILE commands. Expressions can perform operations on either numbers or strings.
The following topics explain how to use expressions when you program a merge in WordPerfect:
Numeric expressions
String expressions
Expression evaluation
Operator precedence
String delimiters
Other merge delimiters
Numeric expressions
Numeric expression values must contain only integers (or variables that contain integers).
You can use signed numbers in expressions. The highest positive number you can use is 2,147,483,647. Numbers higher than that are considered negative in WordPerfect. For information, see Negative numbers. The lowest negative number you can use is --2,147,483,648.
If you try to use an invalid numeric expression, the expression is treated as a text string. Examples of invalid numeric expressions are characters other than numbers and valid operators or expressions that evaluate to numbers outside the numeric limits.
The following is a list of numeric expressions. In this list, the terms n1 and n2 represent number 1 and number 2. Although only a single operator is illustrated in each example below, you can use several operators as well as parentheses in expressions. For definitions of the operations used in the following table, see "Expression terms."
Expression Operation
NOT n1 Returns the logical (0 or -1) NOT of n1.
Examples: NOT 0 is -1. NOT 2 is 0.
!n1 Returns the arithmetic (bitwise) NOT of n1.
Examples: !0 is -1. !2 is -3.
-n1 Returns the negative of n1.
Example: If variable Num holds 5, -VARIABLE(Num) is -5.
n1+n2 Returns the sum of n1 and n2.
Example: 5+4 is 9.
n1-n2 Returns the difference of n1 and n2.
Example: 10-1 is 9.
n1*n2 Returns the product of n1 and n2.
Example: 6*5 is 30.
n1/n2 or n1 DIV n2 Returns the integer quotient of n1 and n2.
Examples: 20/5 is 4. 5 DIV 2 is 2.
n1%n2 or n1 MOD n2 Returns the remainder of the quotient of n1 and n2.
Examples: 20%5 is 0. 5 MOD 2 is 1.
n1 AND n2 Returns the logical (0 or -1) AND of n1 and n2.
Examples: 0 AND -1 is 0. 3 AND 4 is -1.
n1 & n2 Returns the arithmetic (bitwise) AND of n1 and n2.
Examples: 7&4 is 4. 3&4 is 0.
n1 OR n2 Returns the logical (0 or -1) OR of n1 and n2.
Examples: 0 OR -1 is -1. 3 OR 4 is -1.
n1|n2 Returns the arithmetic (bitwise) OR of n1 and n2.
Examples: 7|4 is 7. 3|4 is 7.
n1 XOR n2 Returns the logical (0 or -1) XOR (exclusive OR) of n1 and n2.
Examples: 0 XOR -1 is -1. 3 XOR 4 is 0.
n1=n2 Returns a true value (-1) if n1 and n2 are equal; otherwise, returns a false value (0).
Examples: If variable 1 holds 5, then VARIABLE(1)=5 is true, and VARIABLE(1)=3 is false.
n1!=n2 or n1<>n2 Returns a true value (-1) if n1 and n2 are not equal; otherwise, returns a false value (0).
Examples: If variable 1 holds 5, then VARIABLE(1)!=3 is true, and VARIABLE(1)<>5 is false.
n1>n2 Returns a true value (-1) if n1 is greater than n2; otherwise, returns a false value (0).
Examples: 6>4 is true. 4>6 is false.
n1<n2 Returns a true value (-1) if n1 is less than n2; otherwise, returns a false value (0).
Examples:2<10 is true. 10<2 is false.
n1>=n2 Returns a true value (-1) if n1 is greater than or equal to n2; otherwise, returns a false value (0).
Examples: 6>=6 is true. 4>=6 is false.
n1<=n2 Returns a true value (-1) if n1 is less than or equal to n2; otherwise, returns a false value (0).
Examples: 2<=2 is true. 10<=2 is false.
Expression evaluation
An expression must be written according to the rules and syntax in this appendix for WordPerfect to evaluate it correctly. The following information will help you create and use expressions.
When an expression is encountered in a command, the expression is evaluated first, and the result of the expression is used to complete the command. For example, in the statement ASSIGN(1;VARIABLE(1)+1), the expression is VARIABLE(1)+1.
When the expression is evaluated, the contents of variable 1 are incremented by one. The assignment is then performed, replacing the old contents of variable 1 with the result of the expression.
In several of the expressions, the result of the operation is either true or false. WordPerfect assigns a numeric value to true (-1) and false (0). These values were chosen because they are opposites (numeric complements) of each other. For information, see Bitwise NOT in "Expression Terms." WordPerfect interprets any non-zero numeric value as true, but when it assigns a value for true, it assigns -1.
In the following example, the first assignment statement assigns false (0) to variable 1, the second assignment statement assigns true (-1), the logical opposite of false, to variable 1, and the third assignment statement assigns true (-1) to variable 1.
ASSIGN(1;5=4)
ASSIGN(1;NOT VARIABLE(1))
ASSIGN(1;5!=4)
The order in which the various operators are applied in an expression is not simply the order in which they occur. WordPerfect uses an order of precedence that determines which operators are used first, second, and so forth. For example, in the expression 4+7*8, there is a different result depending on whether the addition is performed before or after the multiplication. For more information about the order of evaluation, see Operator Precedence.
Operator precedence
WordPerfect supports expressions with several operators. Therefore, an order of evaluation must be followed. The operator precedence is similar to the precedence for mathematical operators. The following table shows the order in which operators are applied:
2. * (multiply), / (divide), DIV (divide), % (mod), MOD (mod)
3. - (subtract), + (add)
4. < (less than), > (greater than), = (equal to), != (not equal to), <= (less than or equal to), >= (greater than or equal to) Relational operators also work on strings.
5. & (bitwise AND), AND (logical AND), | (bitwise OR), OR (logical OR), XOR (exclusive OR)
You can override the operator precedence by placing parentheses around the elements you want evaluated first. Elements inside of parentheses are always evaluated before the elements outside. If parentheses are nested, the innermost parentheses are evaluated first.
In the expression 4+7*8, the multiplication (7*8) is performed first, followed by the addition, because multiplication has a higher precedence than addition. The result is 60. To perform the addition first, type (4+7)*8. In this case, the result is 88.
String delimiters
A string delimiter is a character that marks the beginning or end of a string. In string operations, quotation marks (") serve as string delimiters. In most cases, string delimiters are not needed. Any expression that cannot be evaluated as a valid numeric expression is considered a string.
However, if you want an expression to remain a string even though it could be evaluated as a numeric expression, surround the expression with quotation marks. For example, if you assign a phone number to a variable, but do not surround the number in quotes, the phone number is evaluated as a numeric expression. For example, the command ASSIGN(1;555-1555) assigns the result of subtracting 1555 from 555 (-1000) to variable 1. The command ASSIGN(1;"555-1555") assigns the string 555-1555 to variable 1.
Other merge delimiters
A merge delimiter is a word or character that marks the beginning or end of a parameter or argument. Word delimiters can include such reserved words as AND, OR, NOT.
Semi-colons (;) serve as merge delimiters in merge commands with multiple parameters (SUBSTR(expr;start;length). When a semi-colon is encountered during the merge, it is treated as ending the parameter unless the parameter is within quotation marks.
String expressions
A string is any sequence of one or more characters, including spaces. For example, 245, Strawberry, QB12, Z, and Personal Computer are strings. Quotation marks are not necessary to define strings.
The expressions outlined in the following table are used to compare strings. The terms s1 and s2 represent string 1 and string 2.
Expression Operation
s1=s2 Returns a true value (-1) if string 1 is identical (including case) to string 2; otherwise, returns a false value (0).
Examples: blue=blue is true. blue=BLUE is false.
s1!=s2 or s1<>s2 Returns a true value (-1) if string 1 is not identical (including case) to string 2; otherwise, returns a false value (0).
Examples: If variable 1 holds the string "thread," then VARIABLE(1)!=rope is true, and VARIABLE(1)<>thread is false.
s1>s2 Returns a true value (-1) if string 1 is greater than* string 2; otherwise, returns a false value (0).
Examples: abcd>aabcd is true. a>A is true.
s1<s2 Returns a true value (-1) if string 1 is less than* string 2; otherwise, returns a false value (0).
Examples: aabcd<abcd is true. A<a is true.
s1>=s2 Returns a true value (-1) if string 1 is greater than* or equal to string 2; otherwise, returns a false value (0).
Examples: abcd>=abcd is true. a>=A is true.
s1<=s2 Returns a true value (-1) if string 1 is less than* or equal to string 2; otherwise, returns a false value (0).
Examples: abcd<=abcd is true. A<=a is true.
* In a string comparison, the WordPerfect character set values are compared. For information, see WordPerfect character set values.
Expression terms
The following are technical terms used in the discussion of expressions. Understanding these terms is not essential to performing merges. These definitions are provided for those who are familiar with basic programming concepts.
Bitwise Operation
Bitwise AND (&)
Bitwise NOT (!)
Bitwise OR (|)
Evaluate the Expression
Exclusive OR (XOR)
Logical AND (AND)
Logical NOT (NOT)
Logical OR (OR)
Negative Numbers
WordPerfect character set values
Bitwise operation
In computer language, numbers are represented as a series of 16 bits. A bit can only have a value of 1 or 0. Each 16-bit series (or column) represents a numeric value (such as 1, 2, 4, 8 and so on). The following table outlines some values and their corresponding bits.
Value Bits
0 0000000000000000
-1 1111111111111111
-3 1111111111111101
-21 1111111111101011
3 0000000000000011
4 0000000000000100
7 0000000000000111
21 0000000000010101
47 0000000000101111
A bitwise operation works on one column at a time (starting with the right column) using a single bit from each number. The operation is done 16 times so each bit of each number is operated on.
Bitwise AND (&)
A bitwise AND operation compares the bits of two numbers. When both numbers have a 1 bit in the same position (for example, there is a 1 bit in column 1 [the right column] of the first number and the second number), a 1 is placed in that position in the result. The following table demonstrates the way the expression 21&47 is evaluated.
Value Bits
21 0000000000010101
47 0000000000101111
21&47 0000000000000101
The resulting bits represent the number 5, so 21&47=5.
Bitwise NOT (!)
A bitwise NOT operation takes the bits of the number and complements them. For example, if the expression is !0 (0 is 0000000000000000), the resulting value is -1 (-1 is 1111111111111111).
Bitwise OR (|)
A bitwise OR operation compares the bits of both numbers. When either number has a 1 bit in the same position (for example, there is a 1 bit in column 1 [the right column] of the first number or the second number), a 1 is placed in that position in the result. For example, the expression 21|47 is evaluated as shown in the following table:
Value Bits
21 0000000000010101
47 0000000000101111
21|47 0000000000111111
The resulting bits represent the number 63, so 21|47=63.
Evaluate the expression
Perform the operation(s) on the expression.
Exclusive OR (XOR)
A logical XOR operation evaluates two expressions and returns a true (-1) if one, but not both, of the expressions is true. If both expressions are false or both are true, XOR returns a false (0). For example, 1=1 XOR 2=3 is true (-1), because only one of the expressions being evaluated is true. 6>3 XOR 3>1 is false (0), because both expressions are true.
Logical AND (AND)
A logical AND operation evaluates two expressions and returns a true (-1) if both expressions are true. In all other cases, it returns a false (0). For example, 1=1 AND 2=3 is false (0), because one of the expressions being evaluated is false. 6>3 AND 3>1 is true (-1), because both expressions are true.
Logical NOT (NOT)
A logical NOT operation returns the logical opposite (0 or --1) of the expression. WordPerfect interprets any nonzero numeric value as true, but when it assigns a value for true, it assigns -1. For example, NOT 2 is false (0), because 2 is evaluated as true. NOT 0 is true (-1).
Logical OR (OR)
A logical OR operation evaluates two expressions and returns a true (-1) if either or both expressions are true. If both expressions are false, it returns a false (0). For example, 1=1 OR 2=3 is true (-1), because one of the expressions being evaluated is true.
6<3 OR 3<1 is false (0), because both expressions are false.
Negative numbers
In WordPerfect, negative numbers are represented as large positive numbers, from 2,147,483,648 to 4,294,967,295. The number
4,294,967,295 is -1, 4,294,967,294 is -2, and so on. To determine the number WordPerfect uses to represent any given negative number from -1 to -2,147,483,648, use the following formula:
4,294,967,296 - |x|
where x is the negative number whose equivalent you are trying to find. For example, to find the equivalent of -3,
4,294,967,296 - 3 = 4,294,967,293
To find the negative number (n) represented by a given equivalent, use this formula:
x - 4,294,967,296=n
where x is the equivalent. For example, to find the negative number represented by 4,294,967,293,
4,294,967,293 - 4,294,967,296 = -3
You can assign variables to be negative numbers by using the minus (-) operator or by using the WordPerfect equivalent. Do not use commas or other punctuation in the equivalent. For example,
ASSIGN(number;-1)
is the same as
ASSIGN(number;4294967295)
For more information about creating numeric expressions, see Numeric Expressions.
WordPerfect character set values
WordPerfect assigns a unique value to each character in each WordPerfect character set. For more information, see the descriptions for the CTON and NTOC commands under "Merge Programming Commands." This is called the WordPerfect character set value. In a string comparison, the character set values are compared.
For characters in the same character set, one character is considered "less than" another character if the first character comes before the second character. For example, in character set 0, "3" is less than "4" and "A" is less than "a." For characters in different character sets, the character from the character set with the lower numerical value is considered "less than" the character from the higher numerical character set. For example, any character from character set 2 is less than any character from character set 3.
