Chapter 11

See Graphic

Corel® PerfectScript™ Programming Commands





Corel® PerfectScript™ 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.
 
Syntax numeric := ~ numeric
 
Return Value Returns the bitwise complement of a number (toggles binary value 1 to 0, or 0 to 1).

**

Purpose Operator. Precedence level 2. See Arithmetic Operators in Chapter 4: Expressions.
 
Syntax numeric := numeric ** numeric
 
Return Value Returns the left operand raised to the power of the right operand.

 
Examples

vResult = 2**3

Result: vResult = 8 (2 to the 3rd power)


*

Purpose Operator. Precedence level 3. See Arithmetic Operators in Chapter 4: Expressions.
 
Syntax numeric := numeric * numeric
 
Return Value Return the product of two numbers.

/

Purpose Operator. Precedence level 3. See Arithmetic Operators in Chapter 4: Expressions.
 
Syntax numeric := numeric / numeric
 
Return Value Return the floating point quotient of two numbers.

%

Purpose Operator. Precedence level 3. See Arithmetic Operators in Chapter 4: Expressions.
 
Syntax numeric := numeric % numeric
 
Return Value Return the floating point division remainder.

+

Purpose Operator. Precedence level 4. See Arithmetic Operators in Chapter 4: Expressions.
 
Syntax numeric := numeric + numeric
 
Return Value Sum of two numbers.
 
Examples

vNmbr := 10 + 10

Result: vNmbr = 20


+

Purpose Operator. Precedence level 4. See Arithmetic Operators in Chapter 4: Expressions.
 
Syntax string := string + string
 
Return Value The result of concatentating two strings.
 
Examples

vStr := "abcdefg" + "xyz"

Result: vStr = "abcdefgxyz"


-

Purpose Operator. Precedence level 4. See Arithmetic Operators in Chapter 4: Expressions.
 
Syntax numeric := numeric - numeric
 
Return Value Difference between two numbers.
 
Examples

vNmbr := 10 - 10

Result: vNmbr = 0


-

Purpose Operator. Precedence level 4. See Arithmetic Operators in Chapter 4: Expressions.
 
Syntax string := string - string
 
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"


<<

Purpose Operator. Precedence level 5. See Bitwise Operators in Chapter 4: Expressions.
 
Syntax numeric := numeric << numeric
 
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.

>>

Purpose

Operator. Precedence level 5. See Bitwise Operators in Chapter 4: Expressions.

 
Syntax numeric := numeric >> numeric
 
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.

<<<

Purpose Operator. Precedence level 5. See Bitwise Operators in Chapter 4: Expressions.
 
Syntax numeric := numeric <<< numeric
 
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.

>>>

Purpose Operator. Precedence level 5. See Bitwise Operators in Chapter 4: Expressions.
 
Syntax numeric := numeric >>> numeric
 
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.

=

Purpose

The = operator has two functions. See Operators in Chapter 4: Expressions.

Assignment Operator. Precedence level 10. Assign a value to a variable (synonym for ":="). See =.

Relational Equality Operator. Precedence level 6. Determines if operands are equal.

 
Syntax boolean := any = any
 
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


<>

Purpose Operator. Precedence level 6. Synonym for "!=". See Relational Operators in Chapter 4: Expressions.
 
Syntax

boolean := any <> any

 
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


!=

Purpose Operator. Precedence level 6. Synonym for "<>". See Relational Operators in Chapter 4: Expressions.
 
Syntax boolean := any != any
 
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


<

Purpose Operator. Precedence level 6. See Relational Operators in Chapter 4: Expressions.
 
Syntax boolean := any < any
 
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.

<=

Purpose Operator. Precedence level 6. See Relational Operators in Chapter 4: Expressions.
 
Syntax boolean := any <= any
 
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.

>

Purpose Operator. Precedence level 6. See Relational Operators in Chapter 4: Expressions.
 
Syntax boolean := any > any
 
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.

>=

Purpose Operator. Precedence level 6. See Relational Operators in Chapter 4: Expressions.
 
Syntax boolean := any >= any
 
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.

&

Purpose Operator. Precedence level 7. See Bitwise Operators in Chapter 4: Expressions.
 
Syntax numeric := numeric & numeric
 
Return Value Return bitwise AND of two numbers. Bit result is 1 if both bits are 1, 0 if not.

|

Purpose Operator. Precedence level 7. See Bitwise Operators in Chapter 4: Expressions.
 
Syntax numeric := numeric | numeric
 
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.

^

Purpose Operator. Precedence level 7. See Bitwise Operators in Chapter 4: Expressions.
 
Syntax numeric := numeric ^ numeric
 
Return Value Return the bitwise XOR (exclusive OR) of two numbers. The bit result is 0 if the bits match, 1 if not.

:=

Purpose Operator. Precedence level 10. Assign a value to a variable. Synonym for "=" (assignment operator).
 
Syntax variable := any

=

Purpose

The = operator has two functions. See Operators in Chapter 4: Expressions.

Relational Equality Operator. Precedence level 6. Determines if operands are equal. See =.

Assignment Operator. Precedence level 10. Assign a value to a variable (synonym for ":=").

 
Syntax variable = any

[ ]

Purpose Operator.
 
Syntax any := array[{<index> numeric; ...}]
 
Return Value The specified element of an array.

[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

 
Syntax numeric := array[0]
 
Return Value The number of elements in an array variable.

//

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.

 
Syntax
numeric := AbsVal (Value: numeric)
 
Return Value Absolute value of a value.
 
Parameters
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.
 
Syntax
numeric := acos (Value: numeric)
 
Return Value Angle in radians.
 
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.
 
Syntax
numeric := acosh (Value: numeric)
 
Return Value Angle in radians.
 
Parameters
Value numeric Hyperbolic cosine.

Address

Purpose Pass a variable address (DLL call in-line parameter function). See DLLCall.
 
Syntax
variable := Address (<VariableName> variable)
 
Parameters
<VariableName> variable The variable to get the address of.

AND

Purpose Operator. Precedence level 8. Combine two relationship expressions. See Logical Operators and Logical Expressions in Chapter 4: Expressions.
 
Syntax boolean := boolean AND boolean
 
Return Value True if both expressions are true, False if not.

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.
 
Syntax
numeric := AppActivate (Window: numeric or string; [State: enumeration])
 
Return Value

Window handle.

 
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.
 
Examples Appendix A: 8001

hWnd = AppLocate("Program Manager")
If(hWnd) // if hWnd not equal to 0
   AppActivate(hWnd)
Else
   Quit
EndIf


AppClose

Purpose Close an application by its title or window handle.

 
Syntax
boolean := AppClose (Window: numeric or string)
 

ReturnValue

True if successful, False if not.
 
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.
 
Examples Appendix A: 8096


AppExecute

Purpose Start an application and specify how its window is displayed.
 
Syntax
numeric := AppExecute (CommandLine: string; [State: enumeration])
 
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
 
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.
 
Examples Appendix A: 8000, 8001

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.

 
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.

 
Examples Appendix A: 8000

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.

 
Syntax
numeric := AppLocate (WindowTitle: string)
 
Return Value The window handle of the window found in the search, or 0 if no window is found.
 
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.
 
Examples Appendix A: 8001

AppShow

Purpose Specify an application's display state. Identify the application by title or window handle.
 
Syntax
numeric := AppShow (Window: numeric or string; [State: enumeration])
 
Return Value Window handle.
 
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.
 
Examples Appendix A: 8096

asin

Purpose Get an angle in radians for a specified sine. This is called the arc, or inverse sine.
 
Syntax
numeric := asin (Value: numeric)
 
Return Value Angle in radians.
 
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.
 
Syntax
numeric := asinh (Value: numeric)
 
Return Value Angle in radians.
 
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
 
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.

 
Examples Appendix A: 8002

atan

Purpose Get the angle in radians for a specified tangent. This is called the arc, or inverse tangent.
 
Syntax
numeric := atan (Value: numeric)
 
Return Value Angle in radians.
 
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.
 
Syntax
numeric := atan2 (Value: numeric; Value2: numeric)
 
Return Value Angle in radians.
 
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.
 
Syntax
numeric := atanh (Value: numeric)
 
Return Value Angle in radians.
 
Parameters
Value numeric Hyperbolic tangent.

Average

Purpose Get the average of a list of values.
 
Syntax
numeric := Average ({Value: numeric; ...})
 
Return Value Average of a list of values.
 
Parameters
Value numeric Use a semicolon to separate values.
 
Examples

vAvg := Average (2; 4; 6; 8)

Result: vAvg = 5.0