Chapter 5

Conditional, Loop, and Calling Statements

Some statements can alter the sequential play of macro commands. For example,

SetBrushWidth(BrushWidth: 25)

SetBrushWidth(BrushWidth: 75)

sets a 25-pixel Paint Brush width and then a 75-pixel Paint Brush width. The second command overrides the first. A control statement can select which SetBrushWidth to play depending on a condition being true.

Switch (Test)

Caseof 1: SetBrushWidth(BrushWidth: 25)

Caseof 2: SetBrushWidth(BrushWidth: 75)

Default: SetBrushWidth(BrushWidth: 50)

Endswitch

Explanation: If variable Test equals 1, set a 25-pixel Paint Brush width. If Test equals 2, set a 75-pixel Paint Brush width. If Test equals any value except 1 or 2, set a 50-pixel Paint Brush width. The value of Test can be determined by a programming command such as Menu or GetNumber.

Macros support conditional statements, loop statements, and miscellaneous control statements such as Call, Go, and Quit.

Conditional Statements

Conditional statements execute a statement or statement block when an expression is true, or when a variable matches a constant.

Macros support the following conditional statements:

• Case
• If
• Switch

Case

Case executes a Label statement when Test (user-defined variable) matches a constant value.

Case (Test; {1; Start; 2; Next}; Other)

...(other statements)...

Label (Start)

...statement block...

Label (Next)

...statement block...

Label (Other)

...statement block...

Explanation: If Test matches 1, call Label(Start). If Test matches 2, call Label(Next). If there is no match, call Label(Other).

Case Call is a similar statement which expects a Return after a Label statement. See also PerfectScript Case and Case Call commands.

If-Else-Endif

If-Else-Endif executes a statement or statement block when an expression is true.

If (x = 5)

...statement block...

Else

...statement block...

Endif

Explanation: Execute the first statement block if the expression x = 5 is true (if x equals 5). If not true, execute the second statement block. Else is optional.

If (Expression)

...statement block...

Endif

Explanation: If Expression is true, execute the statement block. If not true, execute the first statement after Endif. Expression must evaluate to true or false. See Relational Expressions in Chapter 4: Expressions and PerfectScript If command.

Switch-EndSwitch

Switch-EndSwitch executes a statement or statement block when <Test> matches <Selector>.

Switch (<Test>)

Caseof <Selector>:

...statement block...

Caseof <Selector>:

...statement block...

Caseof <Selector>:

...statement block...

Default:

...statement block...

EndSwitch

Explanation: If <Test>matches <Selector>, the statement block after Caseof <Selector> is executed.

Statement blocks can include calling a subroutine; see Subroutines later in this chapter. If Continue follows a statement block, the next statement block is automatically executed. See also PerfectScript Switch command.

Loop Statements

Loop statements execute a statement or statement block a specified number of times, until an expression is true, or while an expression is true.

Macros support the following loop statements:

• For
• Repeat
• While

For-EndFor

For-EndFor executes a statement or statement block a specified number of times.

For (<ControlVariable>; <InitialValue>; <TerminateExp>; <IncrementExp>)

...statement block....

EndFor

Explanation: <InitialValue> initializes <Control Variable>. <TerminateExp> tests the value of <ControlVariable>. <IncrementExp> increases the value of <ControlVariable> until <TerminateExp> is false and the loop ends. If <TerminateExp> is initally False, then the statements will not execute since the test is checked at the start of the loop.

For(x; 1; x <5; x + 1)

...statement block...

EndFor

Explanation: x is initialized to 1, statement block executes while x is less than 5, and x is incremented by 1 at the end of each loop.

Similar loop statements are ForEach and ForNext. See Relational Expressions in Chapter 4: Expressions, and PerfectScript For, ForEach, and ForNext commands.

Repeat-Until

Repeat-Until executes a statement or statement block until an expression is true. All Repeat statements execute at least once because the expression is checked at the end of the loop.

Repeat

...statement block...

Until (x > = 10)

Explanation: Execute statement block until the expression x >= 10 is true (until x is greater than or equal to 10). The value of x must change in the loop to make the expression true or the loop never ends. For example,

Repeat

...statement block...

x := x + 1

Until (x >= 10)

Explanation: Increment x by 1 (x := x + 1) at the end of each loop until x is greater than or equal to 10. See Relational Expressions in Chapter 4: Expressions and PerfectScript Repeat command.

While-EndWhile

While-EndWhile executes a statement or statement block while an expression is true. While statements never execute unless the expression is true because the expression is checked at the start of the loop.

While (x <= 10)

...statement block...

EndWhile

Explanation: Execute statement block while the expression x <= 10 is true (while x is less than or equal to 10). If x is greater than 10, the loop does not execute. The value of x must change in the loop to make the expression true or the loop never ends.

While (x <= 10)

...statement block...

x := x + 1

EndWhile

Explanation: Increment x by 1 (x := x + 1) at the end of each loop while x is less than or equal to 10. See Relational Expressions in Chapter 4: Expressions and PerfectScript While command.

Calling Statements

Calling statements call a subroutine, which is one or more statements grouped as one item. (Subroutines are explained later in this chapter.)

Macros support the following calling statements:

• Call
• Go
• Subroutine Name

Call

Call has one parameter, which is the name of a subroutine to call. Return directs macro execution to the statement that follows Call (see PerfectScript Call and Run commands).

Call (ExSub)

...other statements...

Label (ExSub)

...statement block...

Return

Explanation: Call(ExSub) directs macro execution to Label(ExSub), where the statement block is executed. Return directs macro execution to the first statement after Call(ExSub).

Go

Go has one parameter, which is the name of a subroutine to jump to. Macro execution continues from the point of the subroutine and does not return (statements between Go and the subroutine do not execute). Return ends a macro or directs macro execution to the statement that follows a Run command (see PerfectScript Go and Run commands).

Go (ExSub)

...other statements...

Label (ExSub)

...statement block...

Return

Explanation: Go(ExSub) directs macro execution to Label(ExSub), where the statement block is executed. Return ends the macro.

Subroutine Name

Subroutine name performs the same action as a Call statement. For example,

Call InitializeVariables (<Parameter>; <Parameter>)

InitializeVariables (<Parameter>; <Parameter>)

both call a function or procedure named InitializeVariables. (Functions and procedures are explained below.) If the second example calls a function, you can assign a return value to a variable with a statement such as

x := InitializeVariables (<Parameter>; <Parameter>)

Subroutines

Subroutines consist of one or more statements that execute when the subroutine is called by Call, Go, Case, Case Call, or the name of the subroutine.

Macros support the following subroutines:

• Labels
• Functions
• Procedures
• Callbacks

Labels

Labels have one parameter, which is the name of the subroutine. Label names must begin with a character, consist of one or more letters or numbers, are limited to 30 characters, and can have an optional trailing @ sign. Labels generally include one or more statements followed by Return or Quit. Label statements execute the same as other macro statements and do not have to be called. See also PerfectScript Label command.

Functions

Functions can have zero or more parameters which receive values from a calling statement (calling statements are explained earlier in this chapter) and return a value. A function without parameters performs like a Label, except it cannot execute unless called. Function names must begin with a character, consist of one or more letters or numbers, are limited to 30 characters, and can have an optional trailing @ sign. The following rules apply to functions:

• Functions begin with the word FUNCTION and end with ENDFUNC.
• Functions do not execute unless called.
• Calling statements consist of a function name, which can be followed by zero or more parameter values that pass to the function. If there are no parameters, empty parentheses must follow the function name.
• The number of parameters in a calling statement must match the number of function parameters.
• A function cannot be defined inside another subroutine.
• Functions can be placed anywhere in a macro or in a macro library file (see PerfectScript Use command).
• Functions can be called from a subroutine, or a function can call itself (functions are recursive).
• Function variables are private to the function. A variable with the same name as a function variable can be used elsewhere in the macro without conflict.
• Functions can include Label statements which are not visible outside the function. A Label statement inside a function should not have the same name as a function or procedure.
• Functions accept Return statements with no parameters (return 0); or a value contained in a variable that is the result of a function; or an enumerated type that asserts a Cancel, Error, or Not Found condition; or an enumerated type that asserts a Cancel, Error, or Not Found condition, and a value contained in a variable that is the result of a function operation. See PerfectScript Return command.

Procedures

Procedures can have zero or more parameters which receive a value from a calling statement (calling statements are explained earlier in this chapter). A procedure cannot return a value. A procedure without parameters performs like Label, except it cannot execute unless called. Procedure names must begin with a character, consist of one or more letters or numbers, are limited to 30 characters, and can have an optional trailing @ sign. The following rules apply to procedures:

• Procedures begin with the word PROCEDURE and end with ENDPROC.
• Procedures cannot execute unless called.
• Calling statements consist of a procedure name, which can be followed by zero or more parameter values that are passed to the procedure. If there are no parameters, empty parentheses must follow the procedure name.
• The number of parameters in a calling statement must match the number of procedure parameters.
• A procedure cannot be defined inside another subroutine.
• Procedures can be placed anywhere in a macro, or in a macro library file (see PerfectScript Use command).
• Procedures can be called from a subroutine, or a procedure can call itself (procedures are recursive).
• Procedure variables are private to the procedure. A variable with the same name as a procedure variable can be used elsewhere in the macro without conflict.
• Procedures can include Label statements which are not visible outside the procedure. A Label statement inside a procedure should not have the same name as a procedure or function.
• Procedures accept Return statements with no parameters (directs macro execution to the statement that follows a procedure's caller); or with one parameter (an enumerated type that asserts a Cancel, Error, or Not Found condition). See PerfectScript Return command.

Callbacks

When a macro executes a callback routine, global return and parameter array variables are automatically created by the macro system that are accessible to the callback routine. The callback routine can access the callback parameter array for information about the callback event, and will place its return value (if any) in the callback return variable.

The parameters for the callback are placed into a global array variable that has the same name as the callback label. The return value (if any) returned from callback routines is placed in a (non-array) global variable that has the same name as the callback label. For example, parameters would be passed to callback routine 'MsgHandler' in an array called 'MsgHandler[ ]', and any return value would be placed into a variable called 'MsgHandler'.

The return value, the number of callback array entries, and the values contained in the callback array depend on the type of callback being called. The callback type is found in the first ([1]) entry of the callback array. The callback array element count can be retrieved by using the Dimensions command, or by accessing the [0] callback array element.

Callback Data Description

When a macro executes a callback routine, global return and parameter array variables are automatically created by the macro system that are accessible to the callback routine.  The callback routine can access the callback parameter array for information about the callback event, and will place its return value (if any) in the callback return variable.

The parameters for the callback are placed into a global array variable that has the same name as the callback label.  The return value (if any) returned from callback routines is placed in a (non-array) global variable that has the same name as the callback label.  For example, parameters would be passed to callback routine ‘MsgHandler’ in an array called ‘MsgHandler[ ]’, and any return value would be placed into a variable called ‘MsgHandler’.

The return value, the number of callback array entries, and the values contained in the callback array depend on the type of callback being called.  The callback type is found in the first ([1]) entry of the callback array.  The callback array element count can be retrieved by using the Dimensions command, or by accessing the [0] callback array element.

Callback array entries

RTN Callback return value (depends on [1])

[0] Count of elements in callback array

[1] Callback type:

[2...] (Repeating depends on [1])

Entries for Mouse callback (type 0 - CBTYPE_MOUSE)

This type of callback is no longer supported.

Entries for Key and Keystring callback (type 1 - CBTYPE_KEY)

This type of callback is no longer supported.

Entries for Product token (command) callback (type 2 - CBTYPE_TOKEN)

This type of callback is no longer supported.

Entries for Dialog callbacks (type 3 - CBTYPE_DIALOG)

This type of callback is setup by the DialogShow and CoachSetDialogFilter commands.

Elements [6] to [11] have different meanings for each Windows message (contained in [5]).  See Windows 95 documentation for more information.  When [5] is:

272 = WM_INITDIALOG

Sent just before the dialog is first displayed. This message is sent BEFORE the values of the controls are set from their associated variables.  If the values of any controls are changed when responding to this message, the values will be changed again by the macro system to reflect the contents of the variables associated with the controls.

This message is for notification only, and cannot be altered or prevented.

RTN Callback return value not used

[0..2], [4..5], [8..11] are described above.

1272 = MX_POST_INITDIALOG (only sent from DialogShow, not sent from CoachSetDialogFilter)

This message is sent when the dialog is first displayed, AFTER the values of the controls are set from their associated variables. If the values of any controls need to be changed when the dialog is displayed to something other than the initial values from the associated variables, they should be set in response to this message. This message is for notification only, and cannot be altered or prevented.

RTN Callback return value not used

[0..2], [4..5], [7..11] are described above.

2 = WM_DESTROY

Sent when the dialog goes down.

This message is for notification only, and cannot be altered or prevented.

RTN Callback return value not used

[0..2], [4..11] are described above

6 = WM_ACTIVATE

Sent when the dialog is activated or deactivated.

This message is for notification only, and cannot be altered or prevented.

RTN Callback return value not used

[0..2], [4..6], [8..9] are described above

3 = WM_MOVE (sent from Dialog Show and CoachSetDialogFilter commands)

Sent when the dialog is moved to a new location.

This message is for notification only, and cannot be altered or prevented.

RTN Callback return value not used

[0..2], [4..7], [10..11] are described above

5 = WM_SIZE (only sent from DialogShow, not sent from CoachSetDialogFilter)

This message is sent when the dialog is sized.

This message is for notification only, and cannot be altered or prevented.

RTN Callback return value not used

[0..2], [4..5], [7], [10..11] are described above

22 = WM_ENDSESSION (only sent from DialogShow, not sent from CoachSetDialogFilter)

This message is sent when the Windows session is about to be terminated.

This message is for notification only, and cannot be altered or prevented.

RTN Callback return value not used

[0..2], [4..5], [8..11] are as described above

-552 = TCN_SELCHANGING

Sent when a different tab on a tab control is selected.

This message can be altered by the callback by returning a value in the callback return variable.

[0..2], [4..7], [10] are as described above

4104 = WPMSG_SET_NSLB_POPUP

Sent when a name search text box pops up on a name search list box.

RTN Callback return value not used

[0..2], [4..7] are as described above

276 = WM_HSCROLL (sent from DialogShow, and not from CoachSetDialogFilter)

277 = WM_VSCROLL (sent from DialogShow, and not from CoachSetDialogFilter)

Sent when the user clicks on a scroll bar control.

This message is for notification only, and cannot be altered or prevented.

RTN Callback return value not used

[0..2], [4..6], [8..9] are as described above

274 = WM_SYSCOMMAND (only sent from DialogShow, an not from CoachSetDialogFilter)

Sent when the user presses Alt+F4, chooses Close from the system menu, or double clicks the system menu.

This message is for notification only, and cannot be altered or prevented.

RTN Callback return value not used

[0..2], [4..10] are as described above

273 = WM_COMMAND

Sent when the user interacts with a control or menu item on the dialog.

These messages can be altered by the callback if sent from the CoachSetDialogFilter command, by returning a value in the callback return variable.

[0..2], [4..6], [8..9] are as described above

Popup Button Menu items:

Windows ListBox:

WP ListBox:

Windows ComboBox:

WP ComboBox:

Color control:

Counter control:

Push Button:

Radiexo Button:

Checkbox:

Edit Box:

FileNameEntry:

Date control:

Bitmap:

HotSpot:

Popup Menu Button:

Menu item id - Dividing this by 100 gives the position of the item in the menu

Controls:

Control id or:

Entries for MessageBox callback (type 4 - CBTYPE_CBTMSGBOX)

This type of callback is no longer supported.

Macro File Libraries

Macro file libraries contain functions and/or procedures that can be called from another macro and must be compiled.

The command Use specifies a macro that contains functions and/or procedures. It usually precedes calling statements to a macro file library. The following example contains two functions:

Function Add(x)

x := x + 50

Return (x)

EndFunc

Function Subtract(x)

x:= x - 25

Return (x)

EndFunc

Explanation: Function Add receives a value in variable x. 50 is added to x and returned to the function’s caller. Function Subtract receives a value in another variable named x. 25 is subtracted from x and returned to the function’s caller. If this example was saved and compiled as LIBRARY.WCM, the next example includes statements that call the Add and Subtract functions:

Application (WP; “WordPerfect”; Default; “EN”)

Use (“C:\...\LIBRARY.WCM”)

z := Add(50)

z := Subtract(z)

If (z = 75)

Beep // computer beeps because z equals 75

EndIf

Explanation: After function Add is called, 100 is returned in variable z. After function Subtract is called, 75 is returned in variable z. The computer beeps because the expression z = 75 is true.

The previous example with function calling statements in shorthand notation:

Application (WP; “WordPerfect”; Default; “EN”)

Use (“C:\...\LIBRARY.WCM”)

z := Add(Subtract(50))

If (z = 75)

Beep // computer beeps because z equals 75

EndIf