Corel WordPerfect Office - X6 Macro Guide

Macro Guide

Contents

Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

PerfectScript macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Quattro Pro macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

VBA macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

Contents i

ii Contents

Introduction

Welcome to the Corel® WordPerfect® Office X6 Macro Guide!

This resource contains the following sections:

• PerfectScript macros

• Quattro Pro macros

•VBA macros

• Glossary

PerfectScript macros

PerfectScript™ is a command-based macro-programming language that you can use to automate tasks in
Corel® WordPerfect®, Corel® Quattro Pro®, and Corel® Presentations™. This resource contains basic
information about creating simple PerfectScript macros, as well as detailed, technical information about creating
more complex PerfectScript macros.

This section contains the following topics:

• “Understanding PerfectScript macros” on page 5 — explains the concepts that are associated with macros,
and shows how these concepts apply to PerfectScript macros.

• “Getting started with PerfectScript macros” on page 65 — introduces you to the PerfectScript utility,
which you can use to create macros quickly and easily.

• “Creating PerfectScript macros” on page 69 — examines how to create macros, either by migrating ones
that already exist or by recording or writing new ones.

• “Creating UI for PerfectScript macros” on page 79 — describes how to use a dialog box to create an
interface between the application and the user.

• “Debugging PerfectScript macros” on page 105 — demonstrates how to find and correct any errors in your
macros.

Quattro Pro macros

Quattro Pro macros are stored in notebook cells. Use this type of macro when a task is performed within
Quattro Pro.

This section contains the following topics:

• “Understanding Quattro Pro macros” on page 129 — provides a brief introduction to Quattro Pro macros.

• “Working with Quattro Pro macros” on page 131 — helps you create and edit, play and debug, and
convert Quattro Pro macros.

VBA macros

Microsoft® Visual Basic® for Applications (more commonly known as VBA) is a built-in programming
language that can automate repetitive functions and create intelligent solutions in WordPerfect Office X6. If
VBA 6.3 is installed on your computer, you can access the VBA Editor from within WordPerfect, Quattro Pro,
and Presentations.

VBA 6.3 is not included with WordPerfect Office X6. To use VBA macros, you must separately install
VBA 6.3.

Introduction 1

This section contains the following topics:

• “Understanding VBA macros” on page 135 — provides a brief introduction to VBA.

• “Getting started with VBA macros” on page 147 — lets you explore the VBA workspace in WordPerfect,
Quattro Pro, and Presentations.

• “Working with VBA macros” on page 157 — shows you how to create, run, and debug macros.

• “Creating UI for VBA macros” on page 163 — demonstrates how to provide dialog boxes, toolbars and
buttons, user interaction, and help for your macros.

• “Organizing and deploying VBA macros” on page 171 — helps you organize and deploy the macros you
create.

Glossary

This resource also contains a glossary (see page 173).

Please see the Macro Help (psh.chm) for detailed documentation on the available macro commands,
as well as a gallery of sample macros.

2 Introduction

PerfectScript macros

Understanding PerfectScript macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Getting started with PerfectScript macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Creating PerfectScript macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Creating UI for PerfectScript macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Debugging PerfectScript macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

PerfectScript macros 3

4 PerfectScript macros

Understanding PerfectScript macros

When performing repetitive or complex tasks in WordPerfect Office, you can save time by using PerfectScript
macros. In this section, you’ll learn the concepts that are associated with macros, and you’ll learn how these
concepts apply to PerfectScript macros.

This section contains the following topics:

• “Understanding PerfectScript macro concepts” on page 5

• “Using expressions in PerfectScript macro statements” on page 9

• “Using command statements in PerfectScript macros” on page 37

• “Using assignment statements in PerfectScript macros” on page 42

• “Using conditional statements in PerfectScript macros” on page 42

• “Using loop statements in PerfectScript macros” on page 45

• “Using calling statements in PerfectScript macros” on page 46

• “Using comment statements in PerfectScript macros” on page 60

• “Accessing external applications in PerfectScript macros” on page 60

• “Learning more about PerfectScript macros” on page 63

Understanding PerfectScript macro concepts

A macro specifies a sequence of actions that you can quickly repeat later. For example, a macro can automate a
WordPerfect task such as setting the margins, selecting a font, or creating a merge file.

To create macros for WordPerfect Office, you can use the PerfectScript macro-programming language.
PerfectScript is called a “command-based language” because it uses macro commands to store the results of an
action rather than storing the individual steps that are used to carry out that action.

You can also create macros for Quattro Pro by using the native macro-programming language for the
application. For information, see “Quattro Pro macros” on page 127.

You can also use Microsoft Visual Basic for Applications (VBA) to create macros for WordPerfect
Office. For information, see “VBA macros” on page 133.

A macro consists of a set of instructions or statements. By using the various types of macro statements, you can
create PerfectScript macros that automate anything from a basic task to a complex procedure. For more
information about macro statements, see “Understanding PerfectScript macro statements” on page 6.

Through the use of macro statements, PerfectScript lets you create macros that access applications
outside of WordPerfect Office. For more information, see “Accessing external applications in
PerfectScript macros” on page 60.

For even more information about macros, you can consult additional resources for WordPerfect Office.
For information, see “Learning more about PerfectScript macros” on page 63.

The proper form of macro c ompon ents is gov erned by a set o f rule s, or syntax. For more information about macro
syntax, see “Understanding PerfectScript macro syntax” on page 6.

If you structure your macros well, they will function well — and be much easier to edit. For more information
about macro structure, see “Understanding PerfectScript macro structure” on page 6.

Understanding PerfectScript macros 5

Understanding PerfectScript macro statements

If a macro represents a set of instructions, then a macro statement represents a single step in those instructions.
The simplest macro consists of only one statement, while the most complex macro consists of multiple
statements that are performed in sequence.

A group of related statements is called a “statement block.”

Some statements require an expression, which is a formula that represents a value. For more information about
expressions, see “Using expressions in PerfectScript macro statements” on page 9.

By combining expressions with other macro components, you can create any of the following types of
statements:

• command statements — consist of a macro command, which represents a single instruction (typically, an
action). For more information, see “Using command statements in PerfectScript macros” on page 37.

• assignment statements — assign a value to an expression. For more information, see “Using assignment
statements in PerfectScript macros” on page 42.

• conditional statements — execute a statement (or a group of statements) when a specified condition is met.
For more information, see “Using conditional statements in PerfectScript macros” on page 42.

• loop statements — execute a statement (or a group of statements) a specified number of times until (or while)
an expression is true. For more information, see “Using loop statements in PerfectScript macros” on
page 45.

• calling statements — call a statement (or a group of statements). For more information, see “Using calling
statements in PerfectScript macros” on page 46.

• comment statements — contain notes that explain the purpose of a macro without affecting its play. For more
information, see “Using comment statements in PerfectScript macros” on page 60.

Understanding PerfectScript macro syntax

The proper form of macro components is governed by a set of rules, or syntax. For a macro to work properly,
its code must use the correct syntax — that is, the code must be “syntactically correct.”

For each macro component that is described in this documentation, details on proper macro syntax are included.

Some macro statements are too lengthy to fit into a single line of macro code. If your macro editor
automatically inserts a hard return at the end of every line, you must insert an underscore character
(

_ ) at the end of each line that wraps. For information on specifying a macro editor, see “To specify

settings for editing macros” on page 67.

Understanding PerfectScript macro structure

If you structure your macros well, they will function well — and be much easier to edit.

You can structure a macro in several ways. The basic function of a macro is to accomplish a task by following a
series of steps, so the ideal structure for a macro depends on the task involved — and on the amount of code
that is required to carry out that task. For example, if a macro involves multiple tasks that require large amounts
of code, you can make the macro more manageable by breaking it into smaller pieces (called subroutines — see
“Understanding subroutines” on page 46).

From a structural standpoint, the two main types of macros are as follows:

6 Understanding PerfectScript macro concepts

• sequential macros — progress in steps from start to finish. For more information, see “Understanding
sequential macros” on page 7.

• procedural macros — progress in steps based on user intervention. For more information, see “Understanding
procedural macros” on page 7.

Understanding sequential macros

A sequential macro progresses in steps from start to finish. All steps are taken in the required order, and the
code is written to suit that purpose.

An example of a sequential macro follows:

HardReturn ()
HardReturn ()
GetString( var1; "Enter Name"; "Data Entry"; 100 )
Type (Text: var1)
HardReturn ()
GetString( var2; "Enter Address"; "Data Entry"; 100 )
Type( var2 )
HardReturn ()
HardReturn ()
Type (Text: "Dear " + var1 + ":")
HardReturn ()
HardReturn ()
Type (Text: "Yaddah Yaddah Yaddah")
HardReturn ()
HardReturn ()
HardReturn ()
Type (Text: "Sincerely,")
HardReturn ()
HardReturn ()
HardReturn ()
HardReturn ()
Type (Text: "Paul McRussell")
HardReturn ()
Type (Text: "Manager, Eat-a-Chicken Burger, Anywhere, USA")

Understanding procedural macros

A procedural macro progresses in steps based on user intervention, through the use of functions and procedures
(see “Understanding PerfectScript functions and procedures” on page 48). Using functions and procedures in a
macro lets the programmer compartmentalize code so it can be called from anywhere in the macro.
Compartmentalization breaks logical pieces of code into smaller segments, and these segments can be separated

Understanding PerfectScript macros 7

by use of the Label, Function, and Procedure commands (see “Understanding subroutines” on page 46).
Smaller pieces of code are easier to work with, and they are also easier to debug.

An example of a procedural macro follows:

HardReturn ()
HardReturn ()
//Call the function to get the name
sName = GetName()
Type (Text: sName)
HardReturn ()
//Call the function to get the address
sAddress = GetAddress()
Type (sAddress )
HardReturn ()
HardReturn ()
Type (Text: "Dear " + sName + ":")
HardReturn ()
HardReturn ()
Type (Text: "Yaddah Yaddah Yaddah")
HardReturn ()
HardReturn ()
HardReturn ()
Type (Text: "Sincerely,")
HardReturn ()
HardReturn ()
HardReturn ()
HardReturn ()
Type (Text: "Paul Russell")
HardReturn ()
Type (Text: "Manager, Eat-a-Burger, Anywhere, USA")
Function GetName()
GetString( sName; "Type in the name of the addressee"; _
"Enter Name"; 100 )
RETURN( sName )
EndFunction
Function GetAddress()
GetString( sAddress; "Type in the address of the addressee"; _
"Enter Address"; 100 )

8 Understanding PerfectScript macro concepts

RETURN( sAddress )
EndFunction

Using expressions in PerfectScript macro statements

Macros consist of statements. Some macro statements involve an action that must be captured as an
expression. An expression is a formula that represents a value.

To create expressions, you use the following macro components:

• variables — store a single value at a time, but this value can change during macro play. For more
information, see “Understanding PerfectScript variables” on page 10.

• constants — store a single value at a time, and this value cannot change during macro play. For more
information, see “Understanding PerfectScript constants” on page 21.

• operators — are symbols (such as
For more information, see “Understanding PerfectScript operators” on page 21.

Understanding expressions

Expressions are created by combining variables or constants (or both) with operators — or by combining other
expressions with operators.

The following examples contain expressions that involve variables and operators.

+, -, *, and %) that combine variables and constants to determine a value.

Example Result

x := "John Doe"

vLeftMargin := 5i

ResultOfOperation := 3 + 4

z := z + 1

The variable x equals the character string John Doe.

The variable vLeftMargin equals the measurement 5i.

The variable ResultOfOperation equals 7 (that is, the result of
the numeric expression

3 + 4).

The variable z equals the value of z + 1. However, a variable can
contain only one value at a time, so the original value of

z is lost

unless previously assigned to another variable.

x := y > 1

If (y>1)
Beep
EndIf

The variable x equals the result of the relational expression y > 1
(that is,
equals

x equals True if y contains a value greater than 1, or it

False if y contains a value less than or equal to 1).

The result of y>1 is evaluated without assigning the result to a
variable. The computer beeps if the value of
is, if the result of the expression
skipped if the value of
of the expression equals

y is less than or equal to 1 (that is, if the result

False).

y>1 equals True). The beep is

y is greater than 1 (that

The following example contains expressions that involve variables, constants, and operators. The value
is used as a variable, while the values
expressions from these values:

0, 4, and -1 are used as constants. The operators - and = are used to create

vCount - 1, vCount = 0, and vCount = 4.

vCount

Function BeepBeep(vCount)
Repeat

Understanding PerfectScript macros 9

Beep
Wait(3)
vCount := vCount - 1
Until(vCount = 0)
Return
EndFunc
ForEach(vCount; {1; 2; 3; 4; 5})
If(vCount = 4)
Break
EndIf
BeepBeep(vCount)
Wait(5)
EndFor

MessageBox(x; "BREAK"; "Variable vCount equals 4"; IconInformation!)

Quit

For more information about the types of expressions that you can create, see “Understanding PerfectScript
expression types” on page 32.

Understanding PerfectScript variables

A variable stores a single value at a time, but this value can change during macro play.

Variables must be “declared” before they can be used. Declaring a variable instructs PerfectScript to set aside
memory for the variable.

Assigning a value to — or “initializing” — a variable involves pointing that variable to the memory cell where
its desired value is stored. If desired, variables can be initialized with a value at the time of declaration. Although
the value of a variable can belong to any data type, the most common data types for variables are numbers and
character strings.

For more information about declaring and initializing variables, see “Declaring and initializing variables” on
page 11.

Unlike other programming languages, PerfectScript does not force the programmer to specify the type
of data to be stored in a variable.

When a variable is declared, it is assigned to one of four types:

• local variables — pertain only to the current macro. By default, variables are automatically declared local if
no variable type is specified. For more information, see “Working with local variables” on page 12.

• global variables — pertain to the current macro and to macros that are called by the
commands. For more information, see “Working with global variables” on page 14.

• persistent variables — pertain to any PerfectScript macro, for as long as PerfectScript is running. For more
information, see “Working with persistent variables” on page 15.

Run and Chain

10 Using expressions in PerfectScript macro statements

• constant variables — represent a value that cannot change during macro play. For more information, see
“Working with constant variables” on page 16.

Two additional kinds of variables require special attention:

•A system variable is a type of macro command that contains current system information such as
the current chart type or the default directory. For example, the PerfectScript system variable

ErrorNumber contains the error value of a Cancel, Error, or Not Found condition (as

illustrated in line 44 of the annotated macro sample ASSERT.WCM in the Macro Help
[psh.chm]). Similarly, the WordPerfect system variable
name of the default folder for WordPerfect macros to a variable named

?PathMacros assigns the path and

vMacroPath, which is

updated to reflect any changes to the directory. For more information about system variables,
see “Understanding macro commands” on page 37.

•An implicit variable is a variable that is defined by PerfectScript. For example the

MacroDialogResult variable contains the control value of the button that releases a dialog

box (see “Releasing dialog boxes by using PerfectScript code” on page 102).

The type of a variable determines its visibility (or scope) and its duration in memory, so it’s important to
understand when to use each variable type. If you try to access a variable from a line of code in which that
variable is not visible, an “out-of-scope” error is generated.

In addition to variable type, the following factors determine the scope of a variable:

• where the variable is declared — for example, in the main body, in a function, in a procedure, in
another macro, or in a separate program altogether

• which line of code is currently executing

You can check whether a variable exists. For more information, see “Determining whether variables exist” on
page 16.

When a variable is no longer required, you can discard it. For more information, see “Discarding variables” on
page 17.

If you want to assign a collection of data to a single variable name, you can use an array. The rules for using
arrays are the same as for using variables. For more information, see “Working with arrays” on page 18.

Declaring and initializing variables

When you declare a macro, you specify a name for it.

For best results, it is highly recommended that you give your variables a descriptive name. Variable names have
the following standards:

• They must begin with a letter.

• They can include any other combination of letters or numbers.

• They must be 50 characters or fewer in length.

• They are not case-sensitive.

Optionally, you can initialize a variable at its time of declaration by using an assignment operator (

:= or =) to

specify a value.

By following a few simple conventions for naming variables, you can make your macro code easier to
understand. For instance, variables that have a string value should have a name that begins with a lowercase

s,

as in the following examples:

sFirstName := "Dave"

Understanding PerfectScript macros 11

sAddress := "1625 East Nowhere St."
sBirthday := "6/12/69"

Similarly, variables that have a numeric value should have a name that begins with a lowercase n, as in the
following examples:

nAge := 25
nTotal := 145.97

In the preceding examples, all declared variables are local, by default, because no variable type is
specified.

Working with local variables

Local variables pertain only to the current macro. Local variables are the default variable type and, as such,
should be used in most situations. You can use the PerfectScript programming commands

Declare or Local

to create local variables.

Variables that are declared in user-defined functions and user-defined procedures are local to those
subroutines. For more information about subroutines, functions, and procedures, see “Understanding
subroutines” on page 46.

Local variables can be declared in the following way:

Declare ( sQReport )

or

Local ( sQReport )

Local variables can be declared and intitialized in the following way:

sQReport := "Q4"
Declare ( sQReport := "Q4" )

or

sQReport := "Q4"
Local ( sQReport := "Q4" )

If you want, you can use the Declare command or the Local command to declare and initialize more than one
local variable at a time. Variables are separated by a semicolon (

Declare (sFilename := "c:\test.wpd"; sTemp; nCount; cMainCount:=10)

;), as in the following example:

When a local variable is declared, it is assigned to the local-variable table. Variables in the local-variable table
are visible only until the end of the level of code in which they are declared. The level of code usually refers to
the main body or a subroutine (that is, a function or procedure). Consider the following sample code:

FileNew
/* Declare sName as a local variable and initialize to the string value "Dave" */
vName := "Dave"
/* Call the procedure */
TypeName ( )
Quit

12 Using expressions in PerfectScript macro statements

Procedure TypeName ( )
/* This variable is out of scope. It has not been declared in the procedure TypeName

*/
Type ( vName )
HardReturn
EndProcedure

The preceding code assigns the string "Dave" to the variable. It then calls the procedure which tries to type
the contents of the variable. Because the variable is out of scope within this procedure, the following error occurs
when playing the macro:

Undefined variable ‘VNAME’ has been referenced. Check line 9 of macro file

‘test.wcm.’

Consider the following sample code:

...
/* Variables declared in the main body are visible in the main body */
vNameMain := "Dave"
NewScope ( )
/* When processing this Procedure vNameMain is not visible */
NewScope2 ( )
/* When processing this Function vNameMain is not visible */
...
Quit
// Subroutines . . .
Procedure NewScope ( )
/* Local variables declared in a procedure are visible only in that procedure */
NameNewScope := "Fred"
...
EndProcedure
Function NewScope2 ( )
/* Local variables declared in a function are visible only in that function */
vNameNewScope2 := "John"
...
EndFunction

In the preceding code, all three variables (VNameMain, NameNewScope, and VNameNewScope2) are named
differently. However, these variables could have been named the same and still have been completely unique
variables — each one holding different data — because they are each declared at a different level of the macro
and therefore each have their own scope.

Understanding PerfectScript macros 13

Working with global variables

Global variables pertain to the current macro and to macros that are called by the Run and Chain commands.
Although a necessity in some cases, global variables should be used with care. You can use the PerfectScript
programming command

Global to create global variables.

Global variables can be declared in the following way:

Global ( nCount )

Global variables can be declared and initialized in the following way:

Global ( sFilename := "c:\Expense.wpd" )

If you create two variables with the same name (for example, Declare x and Global x), the following
statement specifies that the global variable

Global x:=5

x is assigned the value 5:

If you want, you can use the Global command to declare and initialize more than global variable at a

time by separating variables with a semicolon (

;).

When a variable is declared global, it is assigned to the global-variable table. Variables assigned to the global­variable table are in scope anytime after they are declared, and they exist until the end of the macro in which
they are declared. If a global variable is declared on the very first line of a macro, it is accessible in the main
body, in subroutines, and in other macros that are started with the commands

Run or Chain. The following is

an example of a global variable in use:

...
/* The global variable is not yet declared and not yet accessible */
Global ( sGlobalName := "Fred" )
/* Any reference after this to the variable sGlobalName accesses the global variable

*/

...
/* Call the function */
DoSomething ( )
Type ( sGlobalName )
...
/* sGlobalName ceases to exist when the macro ends */
Quit
Procedure DoSomething ( )
/* Change the value of the global variable to "Dave" */
sGlobalName := "Dave"
...
EndProcedure

In the preceding example, the procedure is called after the global variable sGlobalName is declared and
initialized. Inside this procedure, the contents of the variable are changed from
commands

DoSomething and Procedure DoSomething allow you to start another macro from within the

"Fred" to "Dave". The

current macro and, therefore, to access and change any variables that are declared global in the current macro.

14 Using expressions in PerfectScript macro statements

Working with persistent variables

Persistent variables pertain to any PerfectScript macro, for as long as PerfectScript is running. Although a
necessity in some cases, persistent variables should be used with care. You can use the PerfectScript
programming command

Global command to create global variables.

Persist to create persistent variables — in much the same way as you can use the

Persistent variables can be declared in the following way:

Persist ( VariableName )

Persistent variables can be declared and initialized in the following way:

Persist ( VariableName := Value )
PersistAll ( On! )
...
/* All variables declared in the default manner are now persiste nt instead of local*/
VariableName := Value
...
PersistAll ( Off! )

The preceding example uses the PersistAll command to change the default variable-declaration method from
local to persistent and back again. All variables between
are declared as

Persistent variables. This technique is useful when you want an entire block of variables to be

PersistAll ( On! ) and PersistAll ( Off! )

persistent.

If you want, you can use the
at a time by separating variables with a semicolon (

Persist command to declare and initialize more than persistent variable

;).

When a variable is declared persistent, it is assigned to the persistent-variable table. Variables in the persistent
table remain in scope and exist until PerfectScript shuts down.

PerfectScript does not shut down until all the applications that use PerfectScript (WordPerfect,
Quattro Pro, and Presentations) have shut down.

Persistent variables are visible during merges and, as such, provide an effective method for passing values
between macros and merges. If you need to use data during a merge, use persistent variables. For best results,
give persistent variables a descriptive name, and denote their data type.

The following example of a persistent variable requires the use of two macros and includes a test that determines
whether the variable has been initialized.

The first macro in this example is as follows:

Persist ( sAppName := "WordPerfect Suite 8" )
MessageBox( retVal; sAppName; "Left margin equals: " + ?MarginLeft )
Run ( "Macro2.wcm" )

The second macro in this example is as follows:

MessageBox(retVal; sAppName; "Right margin equals: " + ?MarginRight)

The following example illustrates scope by using local and persistent variables:

Persist ( x := "This is persistent variable x" )

Understanding PerfectScript macros 15

CreateOutline()
// Original variable value remains unchanged.
MessageBox ( retVal ; "Information"; "The variable x = " + x )
Quit
Procedure CreateOutline ( )
/* PerfectScript will look first at the local variable table. If a variable exists

in that table, that variable will be used before the persistent variable. By
creating a local variable inside the function, we will force PerfectScript to find
the local variable. This local variable x will be destroyed when execution returns
from this subroutine. */

Local ( x := 0 )
ForNext ( x; 1; 10 )
// for loop creates a basic outline
vCharacter := NTOC(96) + x
Tab()
Type ( "(" + vCharacter + ")" )
Indent()
HardReturn()
EndFor
EndProcedure

Working with constant variables

Constant variables — also called “constants” — represent a value that cannot change during macro play. As
such, constants must be initialized upon declaration, and their assigned value cannot change. Constants should
be used sparingly, if at all.

Expressions are formed by using operators (see “Understanding PerfectScript operators” on page 21) to combine
constants with other types of variables. For more information about constants, see “Understanding PerfectScript
constants” on page 21.

Determining whether variables exist

You can use the Exists command to determine whether a variable exists — that is, whether it has been declared
and initialized. The following sample code shows how to use the

// Declare and initialize a variable’s Name := "Fred"
// Use Exists to see if the variable still exists as a local variable
If ( Exists ( sName; Local! ) )
...
EndIf
...
Quit

Exists command:

The Exists command returns a value after checking the specified variable against the variable tables. The
variable tables are checked in the following order: local, then global, then persistent.

16 Using expressions in PerfectScript macro statements

If you specify a variable-table parameter for the Exists command, a value of True is returned if that variable
is found in the specified variable table. If the variable is not found in the specified variable table, a value of

False

is returned. The following example illustrates this scenario:

If( Exists ( x ; Global!) = TRUE )
x := 147
Else
Global ( x := 147 )
EndIf

If you do not specify a variable-table parameter for the Exists command, one of the following values is
returned:

•

NotFound! or 0 — indicates that the variable does not exist in any variable table

•

Local! or 1 — indicates that the variable exists in the local-variable table

•

Global! or 2 — indicates that the variable exists in the global-variable table

•

Persistent! or 3 — indicates that the variable exists in the persistent-variable table

The following example illustrates this scenario:

Persist( x := 3 )
If ( Exists( x ) = Exists.Persistent!)
MessageBox ( retVar; "Variable"; "This variable Exists in the _
Persist variable pool (" + Exists ( x ) + ")" )
EndIf

Discarding variables

You can use the Discard command to remove a variable from memory by deleting it from its associated variable
table. The following sample code shows how to use the

// Declare and initialize a variable
sName := "Fred"
...
// Free the memory used by vName
Discard ( sName )
// sName no longer exists and cannot be accessed
...
Quit

Discard command:

The Discard command searches the variable tables in the following order: local, then global, then persistent.
If variables with the same name exist in different variable tables, you may need to use the

Discard command

multiple times, as in the following sample code:

While(Exists(VariableName))
Discard(VariableName)
EndWhile

Understanding PerfectScript macros 17

Working with arrays

If you want, you can assign a collection of data to a single variable name by creating an “array.” The elements in
a PerfectScript array can be declared and initialized in the same ways as variables. Unlike other programming
languages, however, PerfectScript lets you assign the elements in an array to different data types. PerfectScript
arrays therefore provide a powerful way to control large amounts of data on one or more dimensions.

To use an array, you must first declare it and initialize its elements. When a macro is played, a run-time error is
incurred for each array element that is not both declared and initialized.

The commands for declaring arrays are the same as for declaring variables:

Persist. At declaration, an array requires the following items:

Declare, Local, Global and

• an alphanumeric (case-insensitive) name that begins with a letter and is limited to 50 characters

• a subscript, marked in brackets (

[]), that specifies how many array elements to create

The following commands declare a one-dimensional array that contains five elements:

Declare(aMyArray[5]) — declares a one-dimensional, five-element local array

•

•

Local(aMyArray[5]) — declares a one-dimensional, five-element local array

•

Global(aGlobalArray[5]) — declares a one-dimensional, five-element global array

•

Persist(aPersistArray[5]) — declares a one-dimensional, five-element persistent array

Every array contains a hidden element called

0. This element stores the total number of elements in the

array (not including itself), and an attempt to assign any other value to this element generates an error

message. In the previous examples, the declared array actually includes six elements if you include

element

0.

The preceding examples declare an array but do not initialize its elements. Before you can use an array, you must
individually initialize each array element. To initialize an array element, you must specify the array name; the
subscript (or index) number of the array element, enclosed in brackets (

[]); and the desired value for the array

element. The following example illustrates how to initialize each element in an array after declaring the array.

// Declare a 5-element array
Declare ( aMyArray[5] )
// Initialize each of the five elements
aMyArray[1] := "One"
aMyArray[2] := "Two"
aMyArray[3] := "Three"
aMyArray[4] := "Four"
aMyArray[5] := "Five"

You can simplify the process of initializing array elements after declaring an array by using the following syntax:

Declare ( aMyArray[5]; nCount := 0 )
ForEach (x; {"One"; "Two"; "Three"; "Four"; "Five"})
nCount := nCount +1
aMyArray[ nCount ] := x
EndFor

18 Using expressions in PerfectScript macro statements

If you want, you can initialize an array upon its declaration (in which case, the number of elements need not be
specified). The following commands declare and initialize a one-dimensional array that contains five elements:

Declare(aMyArray[]:={"One";"Two";"Three";"Four";"Five"}) — declares and initiatlizes a one-

•
dimensional, five-element local array

•

Local(aMyArray[]:={"One";"Two";"Three";"Four";"Five"}) — declares and initiatlizes a one-

dimensional, five-element local array

aMyArray[]:={"One";"Two";"Three";"Four";"Five"} — declares and initiatlizes a one-

•
dimensional, five-element local array

Global(aGlobalArray[]:={"One";"Two";"Three";"Four";"Five"}) — declares and initiatlizes a

•
one-dimensional, five-element global array

•

Persist(aPersistArray[]:={"One";"Two";"Three";"Four";"Five"}) — declares and initiatlizes

a one-dimensional, five-element persistent array

PerfectScript arrays can have up to ten dimensions. A two-dimensional array is like a table with rows and
columns: Each cell in the table is an individual element.

For declaring a multi-dimensional array, the syntax of the subscript operator (
of dimensions is followed by a semicolon (

;), which is followed by the number elements within each dimension.

[]) is as follows: The number

The following example shows how to declare a three-dimensional array in which each dimension has five
elements:

Declare ( aMyArray[3;5] )

Each dimension can have up to 32,767 elements (depending on available memory), and each element can be
individually accessed and initialized. For accessing and initializing an element in a multi-dimensional array, the
syntax of the subscript operator (
semicolon (

;), which is followed by the subscript (or index) number of the element within that dimension.

[]) is as follows: The dimension number of the element is followed by a

The following syntax specifies the first element in the first dimension:

aMyArray[1;1] := "1-1"

The following syntax specifies the third element in the second dimension:

aMyArray[2;3] := "2-3"

The following stynax specifies the fifth element in the third dimension:

aMyArray[3;5] := "3-5"

Multi-dimensional arrays, like one-dimensional arrays, can be initialized at their time of declaration. In this
scenario, the number of elements in each dimension does not need to be explicitly stated because it is implied
by the actual initialization of those elements. In addition, the dimensions are separated by a semicolon (

;). The

following example illustrates this syntax:

aMyArray[] :=
{{"1-1"; "1-2"; "1-3"; "1-4"; "1-5"}; // First row
{"2-1"; "2-2"; "2-3"; "2-4"; "2-5"}; // Second row
{"3-1"; "3-2"; "3-3"; "3-4"; "3-5"} } // Third row

PerfectScript provides a special form of initialization for multi-dimensional arrays. This form, called a slice (...),
lets you initialize the elements on a single dimension by repeating the last-initialized element throughout that
dimension. When initializing with a slice, you must fully initialize at least one row in each dimension to define
the extent of the slice. The following example illustrates the syntax for using a slice:

Understanding PerfectScript macros 19

// Declares a three-dimensional array (3x3x6) initializing all elements wit h a slice
aMyArray[] :=
{ { {1;1;1;1;1;1}; // First dimension, first row
{1; ... }; // First dimension, second row, replicated with value 1
{1; ... } }; // First dimension, third row
{{2;2;2;2;2;2}; // Second dimension, first row
{2; ... }; // Second dimension, second row
{2; ... } }; // Second dimension, third row
{{3;3;3;3;3;3}; // Third dimension, first row
{3; 4, ... }; // Third dimension, second row, replicated with value 4
{3; 1; ... } } } // Third dimension, third row, replicated with _ value 1

You can use the Dimensions command to return the following information about an array:

• total number of dimensions in the array

• total number of elements in the array

• number of elements in each dimension

• index range

In some cases, you must declare an array dynamically and therefore cannot be sure how many dimensions are
contained in the array. The

Dimensions command allows a macro to act dynamically by querying the size of

an array:

aFiles[] := GetFileList() // returns an array of random size
ForNext (x; 1; Dimensions( aFiles[]; 0 ) )
// Dimensions queries the array for the size
FileOpen ( aFiles[x] )
FooterA(Create!)
Type ( "McRae's Eat-a-Burger ")
SubStructureExit()
FileSave ( aFiles[x]; WordPerfect_60! )
Close()
EndFor
Function GetFileList()
... // statement block that creates an array (sized) dynamically
Return ( ArrayOfFiles[] )
EndFunction

Please note that MacroArgs[] is a special PerfectScript array that contains values that are passed to the macro
by the commands

// Macro: MAIN.WCM
// Include full path if macro not
// in default macros directory

Chain, Nest, or Run. The following example illustrates the MacroArgs[] array.

20 Using expressions in PerfectScript macro statements

Run("TSTMACRO"; {"x"; "y"; "z"})

// Macro: TSTMACRO.WCM
// Compile, then play MAIN.WCM
vElements = Dimensions (MacroArgs[]; 0)
If (vElements != 0)
ForNext (x; 1; vElements; 1)
MessageBox (z; "Element Values"; "MacroArgs[" + x + "] = " + _
MacroArgs[x])
EndFor
Else
Beep
MessageBox (z; "Error"; "No values passed"; IconExclamation!)
EndIf
// Result: x y z

Understanding PerfectScript constants

A constant — also called a constant variable — represents a value that cannot change during macro play.

By contrast, most variables represent a value that can change during macro play. For more information,
see “Understanding PerfectScript variables” on page 10.

Constants must be initialized upon declaration, and their assigned value cannot change. You can declare and
initiatlize a constant in the following way:

Constant ( WPCLASSNAME := "WordPerfect.8.32" )

A compile-time error occurs if a constant is misused in one of the following ways:

• if the constant is not initialized upon declaration — for example, if the declaration statement is missing an
assignment operator (

:=) or an assigned value (or both)

• if an attempt is made to assign a different value to a constant after it has been declared and initialized

You can set constants apart from other variables by giving them a name that appears entirely in capital
letters. This naming convention is the generally accepted practice in C/C++ and other programming
languages.

Understanding PerfectScript operators

Operators are used to combine variables (see “Understanding PerfectScript variables” on page 10) and
constants (see “Understanding PerfectScript constants” on page 21) into expressions — and even to combine
expressions into other expressions. In PerfectScript, operators can be either “unary” or “binary.”

Unary operators are symbols or words that represent an operation on only one operand or expression. The
following table lists the unary operators that are available in PerfectScript.

Understanding PerfectScript macros 21

Operator Action Example and result

+

-

NOT

~

Multiplies an operand by +1

Multiplies an operand by -1

Inverts the result of relational and logical
expressions

To g gle s a bi n ar y v a lu e (that is, converts 1 to

0, and 0 to 1)

+5

Result: +5 (that is, 5 * +1)

-10

Result: -10 (that is, 10 * -1)

See “Understanding logical operators” on page 26.

See “Understanding bitwise operators” on page 28.

Binary operators are symbols or words that represent an operation on two operands or expressions. In the
following example, the binary plus operator (
assigns the result of the arithmetic expression

x := 3 + 4

+) adds the operands 3 and 4, and the assignment operator (:=)

3 + 4 to variable x.

All PerfectScript operators can be classified into the following functional categories:

• assignment operators — symbols that assign the value of a right-operand expression to a left-operand variable.
For more information, see “Understanding assignment operators” on page 22.

• arithmetic operators — symbols or words that represent a mathematical operation on two operands. For more
information, see “Understanding arithmetic operators” on page 23.

• relational operators — symbols that represent a relational operation on two operands, such that the operation
result equals either true or false. For more information, see “Understanding relational operators” on
page 24.

• logical operators — words that represent a logical relationship between conditions, or that invert a condition.
For more information, see “Understanding logical operators” on page 26.

• bitwise operators — symbols that represent a bitwise operation on two integer operands. For more
information, see “Understanding bitwise operators” on page 28.

When used together to form an expression, operators are evaulated by PerfectScript based on precedence level.
For more information about operator precedence, see “Understanding operator precedence” on page 30.

For detailed information on each operator, please see the “Operators” topic in the PerfectScript
Command Reference section of the Macro Help (psh.chm).

Understanding assignment operators

Assignment operators are symbols that assign the value of a right-operand expression to a left-operand variable.

The following table lists the assignment operators that are available in PerfectScript.

Operator Action Example and result

:= or = Assignment of a value to a variable

22 Using expressions in PerfectScript macro statements

x := "John Doe"

Result: The variable x equals the character string

John Doe.

Understanding arithmetic operators

Arithmetic operators are symbols or words that represent a mathematical operation on two operands.

All arithmetic operators are binary operators.

The following table lists the arithmetic operators that are available in PerfectScript.

Operator Action Example and result

*

/

-

+

%

MOD

Multiplication

Division

Subtraction of numbers and
reduction of strings

Addition of numbers and
concatenation of strings

Floating point modulus division
— returns remainder of floating­point division

Integer modulus division —
returns remainder of integer
division

vStr := "abcdefg" - "efg"

Result: vStr equals "abcd" (by reduction of strings)

vStr := "abcd" + "efg"

Result: vStr equals "abcdefg" (by concatenation of strings)

x:=10.1 % 3

Result: x equals 1.1

x := 9 % 3

Result: x equals 0

x := 10 MOD 3

Result: x equals 1

x := 10.1 MOD 3

Result: error (because MOD cannot be used on real numbers)

DIV

Integer division — returns
integer portion of integer division

x := 10 DIV 3

Result: x equals 3

x := 9 DIV 3

Result: x equals 3

x := 9.1 DIV 3.5

Result: error (because DIV cannot be used on real numbers)

**

Exponentiation — raises a
number to a power

vResult = 2**3

Result: vResult = 8 (that is, 2 to the power of 3)

vResult = 4**2

Result: vResult = 16 ( that is, 4 to the power of 2)

Understanding PerfectScript macros 23

Understanding relational operators

Relational operators are symbols that represent a relational operation on two operands. The operation result

True or False.

equals

All relational operators are binary operators.

The following table lists the relational operators that are available in PerfectScript.

Operator Action Example and result

>

>=

<

<=

Greater than

Greater than or equal to

Less than

Less than or equal to

x := 10
z := (x>5)

Result: z equals True (because x is greater than 5)

x := 10
If (x>=10)
Beep
Else
Quit
EndIf

Result: The computer beeps because the result of expression x >=

10

equals True (that is, x equals 10). The Else statement is

skipped, so the

x := 10
z := (x<5)

Quit command does not end the macro.

Result: z equals False (becuase x is not less than 5)

x := 20
If (x<=10)
Beep
Else
Quit
EndIf

Result: The computer does not beep because the result of expression

x <= 10 equals False (that is, x is greater than 10). The Else

statement is played, so the

Quit command ends the macro.

24 Using expressions in PerfectScript macro statements

Operator Action Example and result

=

<>

Equal to

Note: Whereas

True regardless of whether

LIKE is

the compared strings are
identical in case,

= is case-

sensitive.

Not equal to

x := 10
z := (x=5)

Result: z equals False (because x is not equal to 5)

x := 10
z := (x = 10)

Result: z equals True (becuase x is equal to 10)

x := "Abc"
z := (x = "Abc")

Result: z equals True ( because x is equal to "Abc")

x := "Abc"
z := (x = "abc")

Result: z equals False (because x must be the same as "Abc",
including case)

!=

Not equal to

x := 10
z := (x!=5)

Result: z equals True (because x is not equal to 5)

x := 12
z := (x !=12)

Result: z equals False (because x is equal to 12)

Understanding PerfectScript macros 25

Operator Action Example and result

IN

LIKE

Membership

Case-insensitive string
equality

Note: Whereas

= is True

only if the compared strings
are identical in case,

LIKE

disregards case altogether.

z := 3 IN {1; 2; 3}

Result: z equals True

z := 3 IN (1; 2; 4}

Result: z equals False

z := {1; 2; 3} IN {1; 2; 3}

Result: z equals True

z := {1; 2} IN {1; 2; 3}

Result: z equals True

z := {1; 2; 3} IN {1; 2; 4}

Result: z equals False

z := ("abc" LIKE "Abc")

Result: z equals True

Understanding logical operators

Logical operators are words that either invert one condition or represent a logical relationship between
conditions. A condition is the result of a relational expression (see “Understanding relational expressions” on
page 36).

Most logical operators are binary operators. The exception is

NOT.

The following table lists the logical operators that are available in PerfectScript.

Operator Action Example and result

NOT

26 Using expressions in PerfectScript macro statements

Inverts the result of a relational
expression

See also the detailed NOT examples that follow this table.

x := 8
If ((x<10) AND NOT (x=5))
Beep
EndIf

Result: The result of the logical expression equals True
( because

x is not equal to 5).

x is less than 10, AND NOT x is equal to 5, or