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.


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