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