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.

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.
 
Examples Appendix A: 8078
 
Return Value Name of the current directory.
 
Syntax string := GetCurrentDirectory ()

GetFileAttributes

Purpose

Return DOS file attributes.

 
Examples 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.
 
Examples Appendix A: 8084
 
Return Value

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

 
Examples 
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.
 
Examples 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.

 
Examples 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.
 
Examples 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.
 
Examples 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.

 
Examples 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
 
Examples Appendix A: 8004
 
Syntax
If (<Test> boolean)
...<statement block>
Else
...<statement block>
EndIf
 
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 (<PlatformID>)
 ...statement block...
EndIfPlatform
 
Examples Appendix A: 8057
 
Syntax
IfPlatform ([{<PlatformID> enumeration; ...}])
...<statement block>
ElseIfPlatform ([{<PlatformID> enumeration; ...}])
...<statement block>
EndIfPlatform
 
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.

 
Examples 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.

 
Examples 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.

 
Examples 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.

 
Examples 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

boolean
 
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.

 
Examples 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.