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.
tan
Purpose
Get the tangent of an angle in radians.
Return Value
Tangent of an angle in radians.
Syntax
numeric := tan (Angle: numeric)
Parameters
Angle
numeric Angle in radians
tanh
Purpose
Get the hyperbolic tangent of an angle in radians.
Return Value
Hyperbolic tangent of an angle in radians.
Syntax
numeric := tanh (Angle: numeric)
Parameters
Angle
numeric The angle in radians
TimeHour
Purpose
Return a number representing the hour on a 24- hour clock.
Return Value
Number if successful, or DateAndTime.Error! if not.
Syntax
numeric := TimeHour ([Time: numeric])
Parameters
Time
numeric (optional) If missing, the current system time is used.
TimeHundredth
Purpose
Return a number representing hundredths of a second.
Return Value
Number if successful, or DateAndTime.Error! if not.
Syntax
numeric := TimeHundredth ([Time: numeric])
Parameter
Time
numeric (optional) If missing, the current system hundredths of a second is used.
TimeMinute
Purpose
Return a number representing the minute.
Return Value
Number if successful, or DateAndTime.Error! if not.
Syntax
numeric := TimeMinute ([Time: numeric])
Parameters
Time
numeric (optional) If missing, the current system minute is used.
TimeSecond
Purpose
Return a number representing the second.
Return Value
Number if successful, or DateAndTime.Error! if not.
Parameter
If missing, the current system second is used.
Syntax
numeric := TimeSecond ([Time: numeric])
Parameters
Time
numeric (optional) If missing, the current system second is used.
TimeString
Purpose
Return the time in a string.
vCurrentTime := TimeString (; "h:m:ss tt")
MessageBox (x; "TimeString"; vCurrentTime)
Result (format): 3:52:34 PMMacro Com Title = Return Value
String if successful, or empty string ("") if not.
Parameters
Time
numeric (optional) If missing, the current system time is used.
Format
string (optional)
Specify a time string format. If missing, the current Windows Control Panel format is used. See the example above.
Hours
h (hours without leading zeros for single digit hours-12 hour clock)
hh (hours with leading zeros for single digit hours-12 hour clock)
H (hours without leading zeros for single digit hours-24 hour clock)
HH (hours with leading zeros for single digit hours-24 hour clock)
Minutes
m (minutes without leading zeros for single digit numbers)
mm (minutes with leading zeros for single digit minutes)
Seconds
s (seconds without leading zeros for single digit seconds)
ss (seconds with leading zeros for single digit seconds)
Time Marker
t (one character time marker: ‘a’ or ‘p’)
tt (multi-character time marker: ‘am’ or ‘pm’)
Syntax
string := TimeString ([Time: numeric]; [Format: string])
TimeZoneInfo
Purpose
Return information about the current time zone and time change.
Return Value
Requested information. InfoItem parameter describes the type of data returned for each item.
Syntax
any := TimeZoneInfo (InfoItem: enumeration; [TimeChangeoverType: enumeration])
Parameters
InfoItem
enumeration Item on which to get information. Some items use the TimeChangeoverType parameter to specify Standard or Daylight time. The first five items ignore this parameter.
TimeZoneNumber! (numeric) Time zone number for this time zone. Time zones West of Greenwich are negative. Times zones East of Greenwich are positive. Some local time zones have offsets that include half hours. The time zone number is the TimeZoneUTCOffset divided by 60 minutes (number of offset hours). If the offset includes a half hour, the returned time zone is some number plus 0.5.
TimeZoneUTCOffset! (numeric) The offset in minutes from Universal Coordinated Time (UTC), or Greenwich mean time. This value is constant, and does not depend on Standard or Daylight Saving time. It is the solar offset of the time zone relative to Greenwich. To find the total offset from UTC for a time changeover, add TimeChangeoverOffset! to this value for that time changeover type.
IsStandardTime!
(boolean) True if the current time changeover is Standard Time, False if not.
IsDaylightSavingTime!
(boolean) True if the current time changeover is Daylight Saving Time, False is not.
TimeChangeoverType!
(enumeration) The current time changeover. The following items use the TimeChangeoverType parameter to determine the time changeover type on which to return information.
UnknownTime!
Unable to determine current time changeover.
StandardTime!
Standard Time is in effect.
DaylightSavingTime!
Daylight Saving Time is in effect.
TimeZoneName!
(string) Name of the current time zone, including the specified time changeover type designator.
TimeChangeoverStartDate!
(numeric) Start date and time of the specified time changover.
TimeChangeoverOffset!
(numeric) The offset added to TimeZoneUTCOffset for the specified time changeover, in the current time zone. This gets the current local time in relation to UTC (Greenwich mean time).
TimeChangeoverType
enumeration (optional) Time changeover type for which to get information. If missing, CurrentTime! is used.
CurrentTime!
Use the current time changeover information.
StandardTime!
Use standard time changeover information.
DaylightSavingTime!
Use daylight saving time changeover information.
ToInitialCaps
Purpose
Capitalize the first character in a string, or the first character of the words in a string.
Return Value
The mixed case equivalent of a specified string.
Syntax
string := ToInitialCaps (String: string; [Style: enumeration])
Parameters
String
string The string to convert.
Style
enumeration (optional) Default: FirstOfEachWord!
FirstCharOnly!
Capitalize the first character in the string.
FirstOfEachWord!
Capitalize the first character of every word in the string.
ToLower
Purpose
Convert uppercase letters to lowercase.
The value returned by ToLower can be assigned to a variable or used directly by a statement such as If.
vAnswer := "YES"
vAnswer := ToLower(vAnswer)
Result: vAnswer equals lowercase yes
If(ToLower(vAnswer) = "yes")
Beep
Else
Quit
EndIf
Explanation: Beep if vAnswer equals lowercase yes.
Example
Appendix A: 8040
Return Value
The lowercase equivalent of uppercase letters.
Syntax
string := ToLower (String: string)
Parameters
String
string A string to convert.
ToUpper
Purpose
Convert lowercase letters to uppercase.
The value returned by ToUpper can be assigned to a variable or used directly by a statement such as If.
vAnswer := "yes"
vAnswer := ToUpper(vAnswer)
Result: vAnswer equals uppercase YES
If(ToUpper(vAnswer) = "YES")
Beep
Else
Quit
EndIf
Explanation: Beep if vAnswer equals uppercase YES.
Example
Appendix A: 8005
Return Value
The uppercase equivalent of lowercase letters.
Syntax
string := ToUpper (String: string)
Parameters
String
string A string to convert.
True
Purpose
The constant boolean value TRUE.
Syntax
boolean := True
UnitStr
Purpose
Convert a measurement to a character string.
If a unit of measure is not specified, the default is WordPerfect (WP) units. To change the default, use DefaultUnits. The following example converts WP units to centimeters and returns the result as a string:
Units := UnitStr(1200; Centimeters!)
Result: vUnits equals "2.540000C"
The next example converts centimeters to millimeters and returns the result as a string:
DefaultUnits(Centimeters!)
vUnits := UnitStr(1.0; Millimeters!)
Result: vUnits equals "10.000000M"
The next example converts inches to centimeters and returns the result as a string:
vUnits := UnitStr(2.0i; Centimeters!)
Result: vUnits equals "5.080000C"
See StrUnit to convert a string of numbers to a measurement expression.
Return Value
A measurement expressed as a string.
Syntax
string := UnitStr (Value: any; Units: enumeration)
Parameters
Value
any A real number measurement. Unless you specifiy a unit of measure, the default is WP Units. To change the default, use DefaultUnits.
Units
enumeration The unit of measure that Value converts to.
Centimeters!
Inches!
Millimeters!
Points!
(72 per inch)
WPUnits!
(1200 per inch)
WP1200ths!
(1200 per inch)
Until
Purpose
Specify the condition for closing a Repeat control loop. See Repeat.
Example
Appendix A: 8004
Syntax
Until (<Test> boolean)
Use
Purpose
Specify a macro file with functions and/or procedures that can be called from another macro.
Use is a non-executable statement that can occur anywhere in a macro. A macro with a calling statement to a function or procedure in another macro file must include a Use statement that identifies the file.
A Use macro file that includes only function and/or procedure statements must be compiled like any macro file (see Macro File Libraries in Chapter 5: Conditional, Loop, and Calling Statements). Corel PerfectScript automatically compiles uncompiled Use macros. Macro execution stops if the macro will not compile.
Macro files identified by multiple Use statements are searched from first to last. Thus a parent macro always calls the first occurrence of a function or procedure with the same name in different Use files.
Example
Appendix A: 8042
Syntax
Use (<MacroFile> string)
Parameters
<MacroFile>
string The path and name of a macro file. You cannot substitute string with a variable.
Value
Purpose
Return the value of an enumeration or the internal product command ID value for a command.
Syntax
any := Value (<Value> any)
Parameters
<Value>
any An enumeration or command.
Notes
If specifying a product command name, do not enclose the command in quotes. For example, x := Value(MessageBox).
If specifying a product command parameter enumeration, use the product command name, a period, the parameter name, a period, and the enumeration. For example, x := Value(MessageBox.Style.OKCancel!).
If using this command to obtain the value of a product command return enumeration value, specify the product command name, a period, and the return enumeration name. For example, x := Value(PersistAll.On!).
Using Value to obtain enumeration values is optional. The following syntax is also correct: x := MessageBox.Style.OKCancel! or x := PersistAll.On!
ValueType
Purpose
Return data type information about a variable or a value.
Return Value
If Type is specified, then return True if Value is of the specified Type, or False if not. If Type if not specified, the actual data type of Value is returned as an enumeration. The possible enumerations are:
Boolean!
WPString!
AnsiString!
OemString!
Float!
Integer!
DateTime!
Centimeters!
Inches!
Millimeters!
Points!
WPUnits!
Object!
Examples
Declare vNmbr = 10.0
If (ValueType.Type.Float!)
MessageBox (x; "ValueType"; ValueType (vNmbr; Float!)
Endif
Result: MessageBox displays True
If (ValueType(vNmbr) = ValueType.Type.Integer!)
Beep
Else
MessageBox (x; "ValueType"; "vNmbr is not an integer value")
Endif
Result: MessageBox displays "vNmbr is not an integer value"
Syntax
enumeration or boolean := ValueType (Value: any; [Type: enumeration])
Parameters
Value
any The value to be tested (any valid expression including a variable name).
Type
enumeration (optional) The type to test for. True if Value is of the specified Type, or False if not. If missing, the data type of Value is returned.
Boolean!
Value must be a boolean value.
String!
Include WPString, AnsiString, and OemString.
WPString!
Corel WordPerfect string.
AnsiString!
Ansi string.
OemString!
OEM string.
Numeric!
Include all Number! and Measurement! types.
Number!
Include Float! and Integer!
Float!
Floating point value.
Integer!
Integer value.
DateTime!
DateTime value, stored as a numeric by the Date and Time commands. See Date and Time commands for more information.
Measurement!
Include Centimeters!, Inches!, Millimeters!, Points! and WPUnits!.
Centimeters!
Centimeters measurement value.
Inches!
Inches measurement value.
Millimeters!
Millimeters measurement value.
Points!
Points measurement value.
WPUnits!
WP Units measurement value.
Object!
OLEObject variable.
VarErrChk
Purpose
Determine how a macro responds to uninitialized variables, or variables not assigned a value.
Example
Appendix A: 8040
Return Value
Off!
Previous VarErrChk state was Off!
On!
Previous VarErrChk state was On!
Syntax
enumeration := VarErrChk ([State: enumeration])
Parameters
State
enumeration (optional) Specify the state of variable checking. The default is VarErrChk(On!). If missing, the current state is returned without changing it.
Off!
Ignore uninitialized variables by temporarily assigning a value of 0.
On!
Display a run-time Error message when a macro attempts to use an uninitialized variable, and end the macro.
VersionInfo
Purpose
Return an item’s version information.
Return Value
Syntax
string or numeric := VersionInfo (VersionInfo: string or enumeration; [VersionItem: enumeration])
Parameters
VersionInfo
string or enumeration A filename or enumeration of a predefined item.
"<filename>" Return version information about a specified file.
PlatformVersion!
Return version information about the platform.
PerfectFitVersion!
Return version information about PerfectFit.
PerfectScriptVersion!
Return version information about PerfectScript.
VersionItem
enumeration (optional) The type of version information to return. If missing, FullVersion! | Numeric! is used.
FullVersion!
Return the full version, including the major, minor, maintenance or build number and sub-build number.
Item to return:
MajorVersion!
Return the major version number only.
MinorVersion!
Return the minor version number only.
MaintenanceVersion!
Return the maintenance version or build number only.
BuildNumber!
Return the maintenance version or build number only.
SubBuildNumber!
Return the sub-build number only.
Format of the item to return:
Numeric!
Return the item as a numeric value in the form: Mmmmnnn where M is the major version number, mmm is the minor version number (0 padded to three digits), and nnnn is the build number (0 padded to four digits).
String!
Return the item as a string value in the form: "M.mm.nnn" where "M" is the major version number, "mm" is the minor version number (0 padded to two digits, and "nnn" is the build number (0 padded to three digits).
Wait
Purpose
Pause macro execution. Time is measured in tenths of a second. The maximum pause is one minute, or Wait(600).
Example
Appendix A: 8025
Syntax
Wait (TenthsOfSeconds: numeric)
Parameters
TenthsOfSeconds
numeric A number from zero to 600. Divide the number by 10 to calculate the number of seconds.
While
Purpose
A loop statement that executes while the expression at the top of the loop is true (see Loop Statements in Chapter 5: Conditional, Loop, and Calling Statements).
The loop does not execute the first time unless Test is true. When Test is false, the first statement after EndWhile is executed.
Example
Appendix A: 8012
Example
The general form of a While statement is:
While (<Test> boolean)
...statement block...
EndWhile
Syntax
While (<Test> boolean)
Parameters
<Test>
boolean Evaluate to true or false.
With
Purpose
Define a local block, in which the current default product or object is temporarily changed. After EndWith the previous default product or object is restored. With-EndWith statements can be nested, which establishes nested blocks of localized default object prefixes.
Syntax
With (ObjectVariable: variable)
Parameters
ObjectVariable
variable New default product or object prefix for the statements inside the With block. Default prefixes can be replaced with "..", which informs the macro compiler that the method or property name following the ".." belongs to the current default prefix.
WordCount
Purpose
Count the words in a string.
Return Value
The number of words in a string.
Syntax
numeric := WordCount (String: string; [WordLength: numeric]; [SeparatorChars: string]; [Option: enumeration])
Parameters
String
string The string containing words.
WordLength
numeric (optional) The length of words to count. If missing, or less than or equal to zero, all words are counted.
SeparatorChars
string (optional) The character(s) used to separate words. If missing, white space characters are used.
Option
enumeration (optional) The type of counting to perform. If missing, the value of WordLength determines which words are counted. Default: CountWords!
CountWords!
See the WordLength parameter.
CountShorter!
Count words shorter than the specified length.
CountLonger!
Count words longer than the specified length.
ShortestLength!
Return the length of the shortest word (ignore WordLength).
LongestLength!
Return the length of the longest word (ignore WordLength).
AverageLength!
Return the average word length (ignore WordLength).
WPString
Purpose
Pass a value as a Corel WordPerfect string (DLL call in-line parameter function). See DLLCall.
ReturnValue
string
Syntax
string := WPString (<Value> string)
XOR
Purpose
Operator. Precedence level 9. Combine two relationship expressions. See Logical Operators and Logical Expressions in Chapter 4: Expressions.
Return Value
True if only one expression is true, or False if both are true or both are false.
Syntax
boolean := boolean XOR boolean