Chapter 11 Corel® PerfectScript® 8 Programming 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}]



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

Result: vElements = 90

Return Value

The number of elements in an array variable.

Syntax

numeric := array

//

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

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

Syntax

numeric := acosh (Value: numeric)

Parameters

Value

numeric Hyperbolic cosine.

Purpose

Pass a variable address (DLL call in-line parameter function).  See DLLCall.

Syntax

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

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

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

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

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

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.