Chapter 11

See Graphic.

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.


gcf

Purpose

Return the greatest common factor of a list of values.

The greatest common factor is the largest number that will divide evenly into all the specified values. If the values have no common factor, 1 is returned.

Return Value

Greatest common factor of a list of values.

Syntax

numeric := gcf ({Value: numeric})

Parameters

Value

numeric The list of values. Multiple values are separated by a semicolon.


GetCurrentDirectory

Purpose

Get the name of the current directory.

Example

Appendix A: 8078

Return Value

Name of the current directory.

Syntax

string := GetCurrentDirectory ()


GetFileAttributes

Purpose

Return DOS file attributes.

Example

Appendix A: 8082

Return Value

One of the following values, or a negative number if an error occurs. GetFileAttributes can return more than one value at a time. Use bitwise operators to determine the values.

Error!

Normal!

ReadOnly!

Hidden!

System!

Label!

Directory!

Archived!

File has changed since the last save.

Syntax

enumeration := GetFileAttributes (Filename: string)

Parameters

Filename

string Include the full path.


GetFileDateAndTime

Purpose

Return a number representing the date and time a file was last written to.  Use DateString and TimeString functions to convert the number to a string.

Example

Appendix A: 8084

Return Value

A number representing a date and time, or -1 if an error occurs.

Example

vNumber = GetFileDateAndTime("c:\...\<filename>")

vDate = DateString(vNumber)

vTime = TimeString(vNumber)

MessageBox(;; vDate + " " + vTime)

Explanation: Displays date and time <filename> was created.

Syntax

numeric := GetFileDateAndTime (Filename: string)

Parameters

Filename

string Include the full path and filename.


GetNumber

Purpose

Display a dialog box that contains an edit control to enter an integer or real number.

Example

Appendix A: 8004

Syntax

GetNumber (VariableName: variable; [Prompt: string]; [Title: string])

Parameters

VariableName

variable The number entered in the edit box is returned in this variable.

Prompt

string (optional) The text displayed above the edit control. Use NToC(0F90Ah) to insert a hard return code in the prompt string. For example,

GetNumber(vAns; "First line" + NToC(0F90Ah) + "Second line"; "Title")

creates two lines above the edit box. The next example creates three lines, including one blank line:

HdReturn = NToC(0F90Ah)

GetNumber(vAns; "First line" + HdReturn + HdReturn + "Second line"; "Title")

Title

string (optional) The text displayed in the title bar.


GetObject

Purpose

Obtains the instance of an OLE object.

Return Value

Instance that identifies an OLE object. After an OLE object variable is assigned an object instance, commands can be called, and values obtained and set for the object variable. When the object and variable are no longer needed, use the Discard command to destroy the object instance.

Syntax

OLEObjectVariable := GetObject ([FileName: string]; [ClassName: string]

Parameters

FileName

string (optional) Name of the file associated with an OLE object. Find the object type using the Windows filename extension associations. If missing, ClassName is used.

ClassName

string (optional) Class name of the OLE object to obtain, also called the ProgID. This must be the name of a register OLD automation object. If missing, FileName is used.


GetString

Purpose

Display a dialog box that contains an edit control to enter a character string.

Example

Appendix A: 8037

Syntax

GetString (VariableName: variable; [Prompt: string]; [Title: string]; [Length: numeric])

Parameters

VariableName

variable The character string entered in the edit box is returned in this variable.

Prompt

string (optional) The text displayed above the edit control. Use NToC(0F90Ah) to insert a hard return code in the prompt string. For example,

GetString(vAns; "First line" + NToC(0F90Ah) + "Second line"; "Title")

creates two lines above the edit box. The next example creates three lines, including one blank line:

HdReturn = NToC(0F90Ah)

GetString(vAns; "First line" + HdReturn + HdReturn + "Second line"; "Title")

Title

string (optional) The text displayed in the title bar.

Length

numeric (optional) The maximum number of characters the edit control accepts. The default is unlimited.


GetUnits

Purpose

Display a dialog box that contains an edit control to enter a number and unit of measure.

The units of measure are " (inches); i (inches); c (centimeters); m (millimeters); p (points-72 per inch); and w (WordPerfect units- specified, the default is WordPerfect units. To change the default, use DefaultUnits.

Example

Appendix A: 8006

Syntax

GetUnits (VariableName: variable; [Prompt: string]; [Title: string])

Parameters

VariableName

variable The number and unit of measure entered in the edit box is returned in this variable. If no unit of measure is specified, the default is returned.

Prompt

string (optional) The text displayed above the edit control. Use NToC(0F90Ah) to insert a hard return code in the prompt string. For example,

GetUnits(vAns; "First line" + NToC(0F90Ah) + "Second line"; "Title")

creates two lines above the edit box. The next example creates three lines, including one blank line:

HdReturn = NToC(0F90Ah)

GetUnits(vAns; "First line" + HdReturn + HdReturn + "Second line"; "Title")

Title

string (optional) The text displayed in the title bar.


Global

Purpose

Declare global variables and arrays, and assign them to the global variable table. Global variables can be used in Run or Chain macros.

Example

Appendix A: 8009

Syntax

Global ({<VariableName> variable := <Value> any})

Parameters

<VariableName>

variable One or more user-defined variables separated by a semicolon. Variables must begin with a letter and can include any other combination of letters or numbers. Parentheses are optional. For example,

Global Variable; Variable

Global(Variable; Variable)

are both valid statements. The following example declares global arrays with 10 elements and 20 elements:

Global FirstArray[10]; NextArray[20]

The last example simultaneously declares a variable and assigns a value:

Global x := 2

or...

Global x

x := 2

If you create two variables with the same name (for example, Global x and Persist x), the following statement

Global x := 5

specifies which variable x is assigned the value 5.

<Value>

any (optional) The value assigned to <Variable> at time of declaration. For example, Global vTest = 20. vTest equals 20 at run time. If missing, the value of <Variable> is undefined.


Go

Purpose

Jump to a Label statement and do not return. Go is generally used to exit multiple layers of nested statements, or to create a loop.

Example

Appendix A: 8038

Syntax

Go (<Label> label)

Parameters

<Label>

label The name of a label. It begins with a letter and consists of one or more letters or numbers.


GoOnLine

Purpose

Start an online service at a specified location.

Syntax

GoOnLine ([Service: enumeration]; [Location: string])

Parameters

Service

enumeration (optional) If missing, Internet! is used.

Internet!

CompuServe!

Other!

Location

string (optional) Service location at which to start. For example, GoOnLine(Internet!; "http://home.netscape.com") starts the default internet browser at the Netscape Navigator home page. For CompuServe, this is the "GO" location. If Service is Other!, Location is the command line to execute and is required.


If

Purpose

A conditional statement that determines whether a statement (or statement block) is executed.  See Conditional Statements in Chapter 5: Conditional, Loop, and Calling Statements.

If <Test> is true, the statements between If and Else are executed. If <Test> is false, the statements between Else and EndIf are execu

Else is optional. If <Test> is false and Else is not used, the macro skips the statements between If and EndIf, and executes the first statement after EndI

EndIf closes an If statement.

The general form of an If statement is:

If (<Test> )

...statement block...

Else

...statement block...

EndIf

Example

Appendix A: 8004

Syntax

If (<Test> boolean)

Parameters

<Test>

boolean Evaluate to true or false.


IfPlatform

Purpose

A conditional statement that specifies a platform or platforms for which subsequent statements are compiled.

If the current platform matches one of the specified platforms, the statements between IfPlatform and EndIfPlatform are compiled and executed.

EndIfPlatform closes an IfPlatform statement.

The general form of an IfPlatform statement is:

IfPlatform (<PlatformID>)

...statement block...

ElseIfPlatform

...statement block...

EndIfPlatform

Example

Appendix A: 8057

Syntax

IfPlatform ([{<PlatformID> enumeration}])

Parameters

<PlatformID>

enumeration (optional/repeating) One or more platform identifiers. Separate multiple platforms with a semicolon.

If equal, the body of the statements are compiled. If this parameter is missing, the statement body is ignored as if a recognized ID was not specified.

This is a compile-time only statement. Use MacroInfo or VersionInfo to get platform type and version numbers at runtime.

WIN!

Win32!

Win95!

WinNT!

_Version8!

This enumeration is recognized if the macro is compiled using the PerfectScript version 8 macro system.


IN

Purpose

Operator.  Precedence level 6.

Return Value (arrays)

True if the left operand is contained in the right operand, or False is not. The left operand may be a value or an array. The right operand must be an array.

If the left operand is a value equal to one of the elements in the right operand array, True is returned.

If the left operand is an array, and every element in the array is equal to some element in the right operand array, True is returned.

Examples

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

Result: z = 3

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

Result: z = False

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

Result: z = True

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

Result: z = True

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

Result: z = False

Notes

If the left operand is a simple value, and the right operand is an array, and the left operand is in an element of the array, the index in the array of the left operand value is returned. If the array is a single dimensional array, this index is a direct index into the array. If the array is multidimensional, this is a composite index that represents the index where this value would be found if all elements in the array were laid out in a long single dimensional array in column major order. For example,

12 IN {{1;3;4;7;8};{5;9;2;12;0}}

will return 9. It is really at index [2; 4] in a multidimensional array. This array is 2 rows of 5 elements. If this array were laid out as a single dimensional array in column major order, it would look like the array {1;3;4;7;8;5;9;2;12;0}. 12 is at index 9 in this array.

Return Value (strings)

If the left hand value is not a substring of the right hand value, False is returned. If the left hand value is a substring, the substring index in string is returned (1 based index). This command is case- sensitive. If a case-insensitive comparison is desired, use Toupper on both the left and right values. If the left operand is an empty string, True is returned.

Syntax

boolean or numeric := value or array IN array boolean or numeric := string IN string


Include

Purpose

Specify a file with executable statements, functions, and/or procedures to include in a macro.  The functions and procedures can be called from the macro.

Include is a non-executable statement that can occur anywhere in a macro. Include files are automatically compiled with the macro. Return or Quit statements in an Include file end all macro execution.

Example

Appendix A: 8091

Syntax

Include (<FileName> string)

Parameters

<FileName>

string The path and name of a macro file. You cannot substitute string with a variable.


Indirect

Purpose

Create variable and label names out of a combination of character strings and/or numbers.  Indirect can also be used on the left hand side of an assignment statement (Indirect(variable) := any).

Use Indirect wherever you would use a variable. On the right side of an assignment statement, variable must be declared and initialized before Indirect. You can use Indirect to call a Label, but not to create one.

State1 := "Utah"

x := Indirect("State" + 1) // x equals "Utah"

State1 := "Utah"

State2 := "Idaho"

State3 := "Arizona"

ForNext(Nmbr; 1; 3; 1)

Type("State of " + Indirect("State"+ Nmbr))

HardReturn

EndFor

Explanation: Types three lines: State of Utah, State of Idaho, and State of Arizona.

ForNext(x; 1; 3; 1)

Call(Indirect("Lab" + x))

EndFor

Quit

Label(Lab1)

...statement block...

Return

Label(Lab2)

...statement block...

Return

Label(Lab3)

...statement block...

Return

Explanation: Call three Labels with a single Call statement in a ForNext loop.

Example

Appendix A: 8022

Return Value

The contents of <VariableName>.

Syntax

any := Indirect (<VariableName> string) Indirect (<VariableName> string) := any

Parameters

<VariableName>

string Character strings and/or numbers are concatenated to form variable and Label names. You cannot use Indirect to create a subroutine name.


Integer

Purpose

Return the integer portion of a real number.

If Value does not contain an integer, 0 is returned. A negative real number is rounded up to the next integer value, and a positive real number is rounded down.

Example

Appendix A: 8023

Return Value

An integer.

vInteger := Integer(1.5)

Result: vInteger equals 1

vResult := Integer(1.77 * 2)

Result: vResult equals 3

vZero := Integer(.7)

Result: vZero equals 0

vNegative := Integer(-1.77)

Result: vNegative equals -2

Syntax

numeric := Integer (Value: numeric)

Parameters

Value

numeric A real number.


IntegerPart

Purpose

Return the integer portion of a numeric value (the integer of 3.2 is 3.0).

vInt := IntegerPart (3.2)

Result: vInt = 3.0

Return Value

Integer portion of a numeric value.

Syntax

numeric := IntegerPart (Value: numeric)

Parameters

Value

numeric A fractional number (return integer part of).


Label

Purpose

Identify a macro subroutine, which generally includes a statement block followed by Return or Quit.  See Subroutines in Chapter 5: Conditional, Loop, and Calling Statements.

Label is used by Call, Case, Case Call, Go, OnCancel, OnCancel Call, OnError, OnError Call, OnNotFound, OnNotFound Call, OnDDEAdvise Call, DDEExecuteExt.

Example

Appendix A: 8002

Syntax

Label (<Label> label)

Parameters

<Label>

label The name of a label. It begins with a letter and consists of one or more letters or numbers.


lcm

Purpose

Get the least common multiple of a list of values.

The least common multiple is the smallest number that all specified values are multiples of. If the values have no common multiple, 1 is returned.

Return Value

Least common multiple of a list of values.

Syntax

numeric := lcm ({Value: numeric})

Parameters

Value

numeric The list of values. Multiple values are separated by a semicolon.


lg

Purpose

Get the base 2 binary logarithm of a value.

Return Value

Base 2 binary logarithm of a value.

Syntax

numeric := lg (Value: numeric)

Parameters

Value

numeric Return the binary logarithm of this value.


LIKE

Purpose

Operator.  Precedence level 6. Performs an equality comparison.

Return Value

Syntax

boolean := any LIKE any


ln

Purpose

Get the base e (natural or napierian) logarithm of a value.

Return Value

Base e logarithm of a value.

Syntax

numeric := ln (Value: numeric)

Parameters

Value

numeric Return the natural logarithm of this value.


Local

Purpose

Declare local variables and arrays, and assign them to the local variable table.

Variables are Local by default. The Local variable table is removed from memory when the current routine in the macro ends.

Example

Appendix A: 8022

Syntax

Local ({<VariableName> variable := <Value> any})

Parameters

<VariableName>

variable One or more user-defined variables separated by a semicolon. Variables must begin with a letter and can include any other combination of letters or numbers. Separate multiple variables with a semicolon. Parentheses are optional. For example,

Local VariableName; VariableName

Local(VariableName; VariableName)

are both valid statements. The next example declares local arrays with 10 elements and 20 elements:

Local FirstArray[10]; NextArray[20]

The last example simultaneously declares a variable and assigns a value:

Local x := 2

or...

Local x

x := 2

If you create two variables with the same name (for example, Global x and Local x), the following statement

Local x := 5

specifies which variable x is assigned the value 5.

<Value>

any (optional) The value assigned to <Variable> at time of declaration. For example, Local vTest = 20. vTest equals 20 at run time. If missing, the value of <Variable> is undefined.


log

Purpose

Get the base 10 (common) logarithm of a value.

Return Value

Base 10 logarithm of a value.

Syntax

numeric := log (Value: numeric)

Parameters

Value

numeric Return the common logarithm of this value.


logn

Purpose

Get the base n logarithm of a value.

Return Value

Base n logarithm of a value.

Syntax

numeric := logn (Value: numeric; Base: numeric)

Parameters

Value

numeric Return the logarithm of this value.

Base

numeric The base of the logarithm to return.