Chapter 11
Corel® PerfectScript® 8 Programming Commands
Three new macro commands have been added: MacroCompile, MacroIsCompiled, and MacroPlay. See online Help for information about these commands. Also, the following commands have been changed: DialogAddControl, DialogDelete, FileFind, FileNameDialog, GetFileAttributes, MacroInfo, OLEAutomation, and SetFileAttributes. See online Help for information about these commands.
~
Purpose
Operator. Precedence level 1. See Bitwise Operators in Chapter 4: Expressions.
Return Value
Returns the bitwise complement of a number (toggles binary value 1 to 0, or 0 to 1).
Syntax
numeric := ~ numeric
**
Purpose
Operator. Precedence level 2. See Arithmetic Operators in Chapter 4: Expressions.
Return Value
Returns the left operand raised to the power of the right operand.
Example
vResult = 2**3
Result: vResult = 8 (2 to the 3rd power)
Syntax
numeric := numeric ** numeric
*
Purpose
Operator. Precedence level 3. See Arithmetic Operators in Chapter 4: Expressions.
Return Value
Return the product of two numbers.
Syntax
numeric := numeric * numeric
/
Purpose
Operator. Precedence level 3. See Arithmetic Operators in Chapter 4: Expressions.
Return Value
Return the floating point quotient of two numbers.
Syntax
numeric := numeric / numeric
%
Purpose
Operator. Precedence level 3. See Arithmetic Operators in Chapter 4: Expressions.
Return Value
Return the floating point division remainder.
Syntax
numeric := numeric % numeric
+
Purpose
Operator. Precedence level 4. See Arithmetic Operators in Chapter 4: Expressions.
Return Value
Sum of two numbers.
Examples
vNmbr := 10 + 10
Result: vNmbr = 20
Syntax
numeric := numeric + numeric
+
Purpose
Operator. Precedence level 4. See Arithmetic Operators in Chapter 4: Expressions.
Return Value
The result of concatentating two strings.
Examples
vStr := "abcdefg" + "xyz"
Result: vStr = "abcdefgxyz"
Syntax
string := string + string
-
Purpose
Operator. Precedence level 4. See Arithmetic Operators in Chapter 4: Expressions.
Return Value
Difference between two numbers.
Examples
vNmbr := 10 - 10
Result: vNmbr = 0
Syntax
numeric := numeric - numeric
-
Purpose
Operator. Precedence level 4. See Arithmetic Operators in Chapter 4: Expressions.
Return Value
Result of removing one string from another. If the right string does not occur in the left string, the left string is returned unchanged.
Examples
vStr := "abcdefg" - "cd"
Result: vStr = "abefg"
Syntax
string := string - string
<<
Purpose
Operator. Precedence level 5. See Bitwise Operators in Chapter 4: Expressions.
Return Value
Return the numeric result of shifting bits one or more positions to the left. Bits shifted off the left end are lost. This operator works only on integer data.
Syntax
numeric := numeric << numeric
>>
Purpose
Operator. Precedence level 5. See Bitwise Operators in Chapter 4: Expressions.
Return Value
Return the numeric result of shifting bits one or more positions to the right. Bits shifted off the right end are lost. This operator works only on integer data.
Syntax
numeric := numeric >> numeric
<<<
Purpose
Operator. Precedence level 5. See Bitwise Operators in Chapter 4: Expressions.
Return Value
Return the numeric result of rotating bits one or more positions to the left. Rotated bits off the left end are inserted on the right end of the value. This operator works only on integer data.
Syntax
numeric := numeric <<< numeric
>>>
Purpose
Operator. Precedence level 5. See Bitwise Operators in Chapter 4: Expressions.
Return Value
Return the numeric result of rotating bits one or more positions to the right. Rotated bits off the right end are inserted on the left end of the value. This operator works only on integer data.
Syntax
numeric := numeric >>> numeric
=
Purpose
The = operator has two functions. See Relational Operators in Chapter 4: Expressions.
Relational Operator
Operator. Precedence level 6.
Return Value
Returns True if two operands are equal, or False if not.
This operator is defined for values and arrays. Two arrays are equal if they have the same number of dimensions and all corresponding elements are equal.
Examples
z := {1; 2; 3} = {1; 2; 3}
Result: z = True
z := {1; 2; 3} = {1; 3; 2}
Result: z = False
z := {1; 2; 3} = {1; 2; 3; 4}
Result: z = False
Operator Assigning Value
Operator. Precedence level 10.
Assigns a value to a variable (synonym for ":=").
Syntax
boolean := any = any variable = any
<>
Purpose
Operator. Precedence level 6. Synonym for “!=”. See Relational Operators in Chapter 4: Expressions.
Return Value
False if two operands are equal, True if not.
This operator is defined for values and arrays. Two arrays are not equal if they have different dimensions or if at least one corresponding element is not equal.
Examples
z := {1; 2; 3} <> {1; 2; 3}
Result: z = False
z := {1; 2; 3} <> {1; 3; 2}
Result: z = True
z := {1; 2; 3} <> {1; 2; 3; 4}
Result: z = True
Syntax:= any <> any
!=
Purpose
Operator. Precedence level 6. Synonym for “<>”. See Relational Operators in Chapter 4: Expressions.
Return Value
False if two operands are equal, True if not.
This operator is defined for values and arrays. Two arrays are not equal if they have different dimensions or if at least one corresponding element is not equal.
Examples
z := {1; 2; 3} != {1; 2; 3}
Result: z = False
z := {1; 2; 3} != {1; 3; 2}
Result: z = True
z := {1; 2; 3} != {1; 2; 3; 4}
Result: z = True
Syntax
boolean := any != any
<
Purpose
Operator. Precedence level 6. See Relational Operators in Chapter 4: Expressions.
Return Value
True if the left operand is less than the right, False if not. For strings, returns True if the left operand alphabetically precedes the right.
Syntax
boolean := any < any
<=
Purpose
Operator. Precedence level 6. See Relational Operators in Chapter 4: Expressions.
Return Value
Return True if the left operand is less than or equal to the right, False if not. For strings, returns True if the left operand alphabetically precedes, or is identical (including case) to the right.
Syntax
boolean := any <= any
>
Purpose
Operator. Precedence level 6. See Relational Operators in Chapter 4: Expressions.
Return Value
Return True if the left operand is greater than the right, False if not. For strings, returns True if the right operand alphabetically precedes the left.
Syntax
boolean := any > any
>=
Purpose
Operator. Precedence level 6. See Relational Operators in Chapter 4: Expressions.
Return Value
Return True if the left operand is greater than or equal to the right, False if not. For strings, returns True if the right operand alphabetically precedes, or is identical (including case) to the left.
Syntax
boolean := any >= any
&
Purpose
Operator. Precedence level 7. See Bitwise Operators in Chapter 4: Expressions.
Return Value
Return bitwise AND of two numbers. Bit result is 1 if both bits are 1, 0 if not.
Syntax
numeric := numeric & numeric
|
Purpose
Operator. Precedence level 7. See Bitwise Operators in Chapter 4: Expressions.
Return Value
Return the bitwise OR of two numbers. The bit result is 1 if either bit is 1, and 0 if both bits are 0.
Syntax
numeric := numeric | numeric
^
Purpose
Operator. Precedence level 7. See Bitwise Operators in Chapter 4: Expressions.
Return Value
Return the bitwise XOR (exclusive OR) of two numbers. The bit result is 0 if the bits match, 1 if not.
Syntax
numeric := numeric ^ numeric
:=
Purpose
Operator. Precedence level 10. Assign a value to a variable. Synonym for “=” (assignment operator).
Syntax
variable := any
=
Purpose
The = operator has two functions.
Relational Operator
Operator. Precedence level 6.
Return Value
Returns True if two operands are equal, or False if not. See Relational Operators in Chapter 4: Expressions.
This operator is defined for values and arrays. Two arrays are equal if they have the same number of dimensions and all corresponding elements are equal.
Examples
z := {1; 2; 3} = {1; 2; 3}
Result: z = True
z := {1; 2; 3} = {1; 3; 2}
Result: z = False
z := {1; 2; 3} = {1; 2; 3; 4}
Result: z = False
Operator Assigning Value
Operator. Precedence level 10.
Assigns a value to a variable.
Syntax
boolean := any = any any := variable = any
[ ]
Purpose
Operator.
Return Value
The specified element of an array.
Syntax
any := array[{<index> numeric}]
[0]
Purpose
Operator. Specify zero as the index regardless of the number of dimensions.
The same value is returned by the command vElements := Dimensions (array[]; 0). See Dimensions command.
Declare Array[3; 5; 6]
vElements := Array[0]
Result: vElements = 90
Return Value
The number of elements in an array variable.
Syntax
numeric := array[0]
//
Purpose
The compiler ignores all text between // and the next hard return [HRt].
Comment text does not affect macro execution. The comment line, including spaces, has a maximum length of 512 characters.
Syntax
// <CommentText>
/* */
Purpose
The compiler ignores all text between /* and */ (// comments end at the next hard return [HRt]). Comment text does not affect macro execution.
Comment blocks can be nested. If nested, a comment terminator (*/) must occur for every comment start (/*). The count must match. A /* */ statement on a line after // is ignored.
A block of macro statements can be commented out by a comment block with a /* on a line above the statements and a */ on a line below. Without removing /* and */, the statements can be reactivated by putting a // statement before /* and */, which comments out the comment markers.
Syntax
/* <CommentText> */
AbsVal
Purpose
Get the absolute value of a value.
The absolute value is the distance a value is from zero, and is always positive. If the value is negative, the absolute value is the positive equivalent of the same value. The absolute value of a positive value is the same value.
Return Value
Absolute value of a value.
Syntax
numeric := AbsVal (Value: numeric)
Parameter
Value
numeric Get the absolute value of this value.
acos
Purpose
Get an angle in radians for a specified cosine. This is called the arc, or inverse cosine.
Return Value
Angle in radians.
Syntax
numeric := acos (Value: numeric)
Parameters
Value
numeric Cosine.
acosh
Purpose
Get an angle in radians whose hyperbolic cosine is specified. This is called the arc, or inverse hyperbolic cosine.
Return Value
Angle in radians.
Syntax
numeric := acosh (Value: numeric)
Parameters
Value
numeric Hyperbolic cosine.
Address
Purpose
Pass a variable address (DLL call in-line parameter function). See DLLCall.
Syntax
variable := Address (<VariableName> variable)
AND
Purpose
Operator. Precedence level 8. Combine two relationship expressions. See Logical Operators and Logical Expressions in Chapter 4: Expressions.
Return Value
True if both expressions are true, False if not.
Syntax
boolean := boolean AND boolean
AnsiString
Purpose
Pass value as an ANSI string (DLL call in-line parameter function). See DLLCall.
Syntax
string := AnsiString (<Value> string)
AppActivate
Purpose
Activate and display a window, using the window title or the window handle. AppActivate returns the window handle, or use AppLocate to get the window handle.
Return Value
Window handle.
Example
Appendix A: 8001
hWnd = AppLocate("Program Manager")
If(hWnd) // if hWnd not equal to 0
AppActivate(hWnd)
Else
Quit
EndIf
Syntax
numeric := AppActivate (Window: numeric or string; [State: enumeration])
Parameters
Window
numeric or string A window handle or title. Titles must match a window title exactly unless you use an asterisk as a wildcard character. Titles are case sensitive. Use AppLocate to get the window handle.
State
enumeration (optional) Set the Window to this state. If missing, no new state is set, and, if minimized, the window is restored. See AppExecute for a description of possible enumerations.
AppClose
Purpose
Close an application by its title or window handle.
ReturnValue
True if successful, False if not.
Example
Appendix A: 8096
Syntax
boolean := AppClose (Window: numeric or string)
Parameters
Window
numeric or string A title or window handle. Titles must match window titles exactly unless you use an asterisk as a wildcard character. Titles are case sensitive. Use AppLocate to get the window handle.
AppExecute
Purpose
Start an application and specify how its window is displayed.
Return Value
Application handle (unique number) if the application is successfully started, or an error value less than or equal to 32 if not. For the list of error values, refer to your Windows 95 documentation.
Check error values with code similar to the following:
vError := AppExecuteExt (string; enumeration)
Switch(vError)
CaseOF 0: ...statement block...
CaseOF 2: ...statement block...
EndSwitch
Example
Appendix A: 8000, 8001
Syntax
numeric := AppExecute (CommandLine: string; [State: enumeration])
Parameters
CommandLine
string Path and filename of an application.
State
enumeration (optional) Specifies how an application’s window is displayed. If missing, CurrentState! is used.
Hide!Hide the window. AppLocate and DDEInitiate return the window handle of a hidden window. DDEExecute sends a command string to a hidden window. AppActivate activates a hidden window. Accelerator keys choose a hidden window’s menu options.
Normal!Show the window at normal size.
Maximize!
Maximize the window to full screen size and activate it.
Minimize!
Minimize the window to an icon and activate it.
MinimizeNoActivate!
Minimize the window to an icon. The active window remains active.
MinimizeActivateTopLevel!
Minimize the window and activate the next window.
CurrentState!
Activate and show the window in its current size and position.
CurrentStateNoActivate!
Display the window in its current state. The active window remains active.
RecentStateNoActivate!
Display the window in its most recent size and position. The active window remains active.
Restore!
Activate and display the window, restoring the original size.
Default!
The default state specified by the application.
AppExecuteExt
Purpose
The same as AppExecute. See AppExecute.
Syntax
numeric := AppExecuteExt (CommandLine: string; [State: enumeration])
Application
Purpose
Identify, for the compiler, an application to use in a macro.
Application is a non-executable statement that can occur anywhere in a macro, but it must precede product commands to the application it identifies.
Applications used in the macro automatically start unless they are already active. The user cannot terminate an application used in a macro until the macro ends.
Example
Appendix A: 8000
Syntax
Application (<ProductPrefix> identifier; <ApplicationName> string; <Default> enumeration; <Language> string)
Parameters
<ProductPrefix>
identifier A word identifier that begins with a letter. Characters after the first can be letters or numbers. ProductPrefix directs product commands to non-default applications. It is also used in NewDefault and EndApp statements. Use a period to attach ProductPrefix to a product command. If WordPerfect is the application and WP is the product prefix, WP.AboutDlg is a valid command statement. A recorded macro specifies the product name as the product prefix.
<ApplicationName>
string The name of an application. For example, "WordPerfect" for Corel WordPerfect 8.
<Default>
enumeration (optional) An enumeration that identifies the default application. If not specified, ApplicationName is not the default.
Product commands to the default application do not require a product prefix.
Default!
Specifies ApplicationName as the default.
<Language>
string (optional) The application’s language code. For example, "EN" is the language code for all English forms. If not specified, the command uses the language of the current macro system.
AppLocate
Purpose
Return a window handle.
AppLocate compares a name to the title bar text of all open windows. If a match is found, the window handle of the matching window is returned. If the search criteria matches more than one window, the window handle of the most recently opened window is returned. If no match is found, zero is returned.
You can use an asterisk (*) as a wildcard character at any position in the AppLocate parameter. If the parameter contains only an asterisk, AppLocate returns the window handle of the active window.
Example
Appendix A: 8001
Return Value
The window handle of the window found in the search, or 0 if no window is found.
Syntax
numeric := AppLocate (WindowTitle: string)
Parameters
WindowTitle
string A window title. This parameter must match the window title exactly unless you use an asterisk as a wildcard character. Titles are case sensitive.
AppShow
Purpose
Specify an application’s display state. Identify the application by title or window handle.
Example
Appendix A: 8096
Return Value
Window handle.
Syntax
numeric := AppShow (Window: numeric or string; [State: enumeration])
Parameters
Window
numeric or string A title or window handle. Titles must match window titles exactly unless you use an asterisk as a wildcard character. Titles are case sensitive. Use AppLocate to get the window handle.
State
enumeration (optional) Display states. If missing, CurrentState! is used.
Hide!
Hide the window. AppLocate and DDEInitiate return the window handle of a hidden window. DDEExecute sends a command string to a hidden window. AppActivate activates a hidden window. Accelerator keys choose a hidden window’s menu options.
Normal!
Show the window at normal size.
Maximize!
Maximize the window to full screen size and activate it.
Minimize!
Minimize the window to an icon and activate it.
MinimizeNoActivate!
Minimize the window to an icon. The active window remains active.
MinimizeActivateTopLevel!
Minimize the window and activate the next window.
CurrentState!
Activate and show the window in its current size and position.
CurrentStateNoActivate!
Display the window in its current state. The active window remains active.
RecentStateNoActivate!
Display the window in its most recent size and position. The active window remains active.
Restore!
Activate and display the window, restoring the original size.
Default!
The default state specified by the application.
asin
Purpose
Get an angle in radians for a specified sine. This is called the arc, or inverse sine.
Return Value
Angle in radians.
Syntax
numeric := asin (Value: numeric)
Parameters
Value
numeric Sine.
asinh
Purpose
Get an angle in radians for a specified hyperbolic sine. This is called the arc, or inverse hyperbolic sine.
Return Value
Angle in radians.
Syntax
numeric := asinh (Value: numeric)
Parameters
Value
numeric Hyperbolic sine.
Assert
Purpose
Create a Cancel, Error, or Not Found condition, or user-defined condition. See OnCondition.
A Cancel, Error, Not Found, or user condition stops a macro unless preceded by OnCancel, OnError, OnNotFound, or OnCondition, which direct macro execution to a specified Label. Assert has no effect when preceded by Cancel(Off!), Error(Off!), NotFound(Off!), or OnCondition(<Condition>; Off!
An error value is assigned to variable ErrorNumber when one of the conditions occur. The values are:
ErrorNumber.CancelConditionAsserted!
ErrorNumber.ErrorConditionAsserted!
ErrorNumber.NotFoundConditionAsserted!
ErrorNumber.UserDefinedCondition!
You cannot assign a value to ErrorNumber.
Use code similar to the following to check all conditions with one subroutine (see Subroutines in Chapter 5: Conditional, Loop, and Calling Statements).
OnError(Condition)
OnCancel(Condition)
OnNotFound(Condition)
...other statements...
Label(Condition)
Switch(ErrorNumber)
CaseOF ErrorNumber.ErrorConditionAsserted!: ...statement block...
CaseOF ErrorNumber.CancelConditionAsserted!: ...statement block...
CaseOF ErrorNumber.NotFoundConditionAsserted!: ...statement block...
EndSwitch
Example
Appendix A: 8002
Syntax
Assert (Condition: enumeration or numeric)
Parameters
Condition
enumeration or numeric A condition to assert.
CancelCondition!
Stop a macro unless preceded by OnCancel.
ErrorCondition!
Stop a macro unless preceded by OnError.
ExitCondition!
Stop a macro as if a Quit command was encountered.
NotFoundCondition!
Stop a macro unless preceded by OnNotFound.
UserDefinedCondition!
Stop a macro on a user-defined condition, unless preceded by OnCondition. For example, if you define condition 101, Assert(101) or Assert(UserDefinedCondition! + 1) directs macro execution to the Label identified by OnCondition.
See OnCondition for a description of how to specify a user-defined condition number.
atan
Purpose
Get the angle in radians for a specified tangent. This is called the arc, or inverse tangent.
Return Value
Angle in radians.
Syntax
numeric := atan (Value: numeric)
Parameters
Value
numeric Tangent.
atan2
Purpose
Get the angle in radians for a specified tangent that is Value / Value2. This is called the arc, or inverse tangent.
Return Value
Angel in radians.
Syntax
numeric := atan2 (Value: numeric; Value2: numeric)
Parameters
Value
numeric Numerator of a tangent.
Value2
numeric Denominator of a tangent.
atanh
Purpose
Get an angle in radians for a specified hyperbolic tangent. This is called the arc, or inverse hyperbolic tangent.
Return Value
Angel in radians.
Syntax
numeric := atanh (Value: numeric)
Parameters
Value
numeric Hyperbolic tangent.
Average
Purpose
Get the average of a list of values.
vAvg := Average (2; 4; 6; 8)
Result: vAvg = 5.0
Return Value
Average of a list of values.
Syntax
numeric := Average ({Value: numeric})
Parameters
Value
numeric Use a semicolon to separate values.