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.
DateAddDays
Purpose
Add a specified number of days to Date (parameter).
Return Value
A date with the specified number of days added. An error returns DateAndTime.Error!.
Syntax
numeric := DateAddDays ([Date: numeric]; Days: numeric)
Parameters
Date
numeric Add days to this date. If missing, the current date is used.
Days
numeric Number of days to add to Date (parameter).
DateAddMonths
Purpose
Add a specified number of months to a specified date.
Return Value
Date with the specified number of months added. An error returns DateAndTime.Error!.
Syntax
numeric := DateAddMonths ([Date: numeric]; Months: numeric; [EndOfMonth: enumeration])
Parameters
Date
numeric (optional) Date to add months to. If missing, the current date is used.
Months
numeric Number of months to add to Date.
EndOfMonth
enumeration (optional) Return the last day or same day in the specified month. If missing, EndOfMonth! is used.
SameDay!
If the date is March 15 and one month is added, April 15 is returned.
EndOfMonth!
If the date is April 30 and one month is added, May 31 is returned.
DateAddWeeks
Purpose
Add a specified number of weeks to a specified date.
Return Value
A date with the specified number of weeks added. An error returns DateAndTime.Error!.
Syntax
numeric := DateAddWeeks ([Date: numeric]; Weeks: numeric; [FirstOfWeek: enumeration])
Parameters
Date
numeric Add weeks to this date. If missing, the current date is used.
Weeks
numeric Number of weeks to add to Date (parameter).
FirstOfWeek
enumeration (optional) Day of the week to return for the return date. If missing, Current! is used.
Current!
Return the date of the same day of the week as the current day.
Sunday!
Return Sunday’s date for the specified week.
Monday!
Return Monday’s date for the specified week.
Tuesday!
Return Tuesday’s date for the specified week.
Wednesday!
Return Wednesday’s date for the specified week.
Thursday!
Return Thursday’s date for the specified week.
Friday!
Return Friday’s date for the specified week.
Saturday!
Return Saturday’s date for the specified week.
DateAddYears
Purpose
Add a specified number of years to a specified date.
Return Value
Date with a specified number of years added. An error returns DateAndTime.Error!.
Syntax
numeric := DateAddYears ([Date: numeric]; Years: numeric)
Parameters
Date
numeric (optional) Date to add years to. If missing, the current date is used.
Years
numeric Number of years to add to Date.
DateAndTime
Purpose
Return a value representing the date and time.
The earliest valid date is January 1, 1601.
Return Value
A number representing the current day, month, year, hour, minute, second, and hundredths of a second is returned if the corresponding parameter is not used. If an error occurs, the enumeration value of Error! is returned.
Examples
DateAndCurrentTime := DateAndTime()
MessageBox (x; "Date"; DateString (TodaysDate))
MessageBox (x; "Time"; TimeString (TodaysDate))
Explanation: MessageBox 1 displays the current date. MessageBox 2 displays current time.
vResult := DateAndTime (15; 10; 1994; 00; 10; 10; 10)
vDate := DateString (vResult)
vTime := TimeString (vResult)
MessageBox (x; "Date"; vDate)
MessageBox (x; "Time"; vTime)
Explanation: Messagebox 1 displays 10/15/94. Messagebox 2 displays 12:10:10 AM.
Syntax
numeric or enumeration := DateAndTime ([Day: numeric]; [Month: enumeration or numeric]; [Year: numeric]; [Hour: numeric]; [Minutes: numeric]; [Seconds: numeric]; [Hundredths: numeric])
Parameters
Day
numeric (optional) A number representing a day of the week.
Month
enumeration or numeric (optional) One of the following enumerations, or a number representing a month (number in brackets).
January!
[1]
February!
[2]
March!
[3]
April!
[4]
May!
[5]
June!
[6]
July!
[7]
August!
[8]
September!
[9]
October!
[10]
November!
[11]
December!
[12]
Year
numeric (optional) A number representing a year. Example: 1997.
Hour
numeric (optional) A number representing an hour.
Minutes
numeric (optional) A number representing a minute.
Seconds
numeric (optional) A number representing a second.
Hundredths
numeric (optional) A number representing hundredths of a second.
DateDay
Purpose
Return a numeric value representing a day of the month.
Example
Appendix A: 8097
Return Value
Check for an error (illegal date) by comparing the return value to DateAndTime.Error!.
Example
vDay := DateDay()
Messagebox (x; "Day of the Month"; vDay)
Result (current system day): 17
Syntax
numeric := DateDay ([Date: numeric])
Parameters
Date
numeric (optional) A number representing a date, or the system date if not used. For a number, see DateAndTime.
DateDayOfYear
Purpose
Return the number of a day in the year.
Return Value
Number of the day in the year specified by the Date parameter. An error returns DateAndTime.Error!.
Syntax
numeric := DateAddWeeks ([Date: numeric])
Parameters
Date
numeric (optional) Date for which to return the number of the day.
DateDaysInMonth
Purpose
Return the number of days in a specified month.
Return Value
Number of days in a specified month (takes Leap year into account). An error returns DateAndTime.Error!.
Syntax
numeric := DateDaysInMonth ([Month: enumeration or numeric]; [Year: numeric])
Parameters
Month
enumeration or numeric (optional) Month for which to return the number of days. If missing, the current month is used. You can also specify a numeric value to represent the month. For example, 1 for January, 2 for February, and so on.
January!
February!
March!
April!
May!
June!
July!
August!
September!
October!
November!
December!
Year
numeric (optional) Year in which to return the number of days in the specified month. If missing, the current year is used.
DateDaysInYear
Purpose
Return the number of days in a specified year.
Return Value
Number of calendar days in a specified year. An error returns DateAndTime.Error!.
Syntax
numeric := DateDaysInYear ([Year: numeric])
Parameters
Year
numeric (optional) Year for which to return the number of calendar days. If missing, the current year is used. Leap years are taken into consideration.
DateIsLeapYear
Purpose
Determine whether a specified year is a leap year.
Return Value
True if leap year, False if not. Leap years are evenly divisible by 4. This is not true of a century year (year evenly divisible by 100), unless the year is evenly divisible by 400. The year 2000 is a leap year, but 1900 was not.
Syntax
boolean := DateIsLeapYear ([Year: numeric])
Parameters
Year
numeric (optional) Year to check for leap year. If missing, the current year is used.
DateMonth
Purpose
Return an enumeration representing the month.
Example
Appendix A: 8097
Return Value
Check for an error (illegal date) by comparing the return value to DateMonth.Error! or DateAndTime.Error!.
January!
February!
March!
April!
May!
June!
July!
August!
September!
October!
November!
December!
Error!
Example
// Assume the current month is February
vMonth := DateMonth()
MessageBox (x; "Month"; vMonth)
Result (current system month): 2 or February!
Syntax
enumeration or numeric := DateMonth ([Date: numeric])
Parameters
Date
numeric (optional) A number representing a date, or the system date if not used. For a number, see DateAndTime.
DateMonthName
Purpose
Return the name of a month.
Return Value
An empty string ("") is returned for an illegal date.
Examples
vDate := DateAndTime (1; 12; 1996)
vMonth := DateMonthName (vDate)
MessageBox (x; "Month"; vMonth)
Result: December
vDate := DateAndTime (1; 12; 1996)
vMonth := DateMonthName (vDate; Short!)
MessageBox (x; "Month"; vMonth)
Result: Dec
Syntax
string := DateMonthName ([Date: numeric]; [Type: enumeration])
Parameters
Date
numeric (optional) A number representing a date, or the system date if not used. For a number, see DateAndTime.
Type
enumeration (optional) Default: Long!
Short!
Month is abbreviated.
Long!
Month is spelled out.
DateOfMonthEnd
Purpose
Return the date for the end of a specified month.
Return Value
Date for the end of a specified month. An error returns DateAndTime.Error!.
Syntax
numeric := DateOfMonthEnd ([Month: enumeration or numeric]; [Year: numeric])
Parameters
Month
enumeration or numeric (optional) Month for which to return the end-of-month date. If missing, the current month is used. You can also use numbers to specify the month. For example, 1 for January, 2 for February, and so on.
January!
February!
March!
April!
May!
June!
July!
August!
September!
October!
November!
December!
Years
numeric (optional) Year in which to return the end-of-month date for Month. If missing, the current year is used.
DateOfNthDay
Purpose
Return the date for a specified day in a year.
Return Value
Date of a specified day number. An error returns DateAndTime.Error!.
Syntax
numeric := DateOfNthDay (Nth: numeric; [Year: numeric])
Parameters
Nth
numeric Day number for which to return the date.
Year
numeric (optional) Year in which to return the date of a specified day. If missing, the current year is used.
DateOfNthWeek
Purpose
Return the date for a specified week.
Return Value
Date of a specified week number. An error returns DateAndTime.Error!.
Syntax
numeric := DateOfNthWeek (Nth: numeric; [Year: numeric]; [FirstDayOfWeek: enumeration])
Parameters
Nth
numeric Week number for which to return the date.
Year
numeric (optional) Year in which to return the date of a specified week. If missing, the current year is used.
FirstDayOfWeek
enumeration (optional) Day of the week for the date to return. If missing, Sunday! is used.
Sunday!
Monday!
Tuesday!
Wednesday!
Thursday!
Friday!
Saturday!
DateOfNthWeekDay
Purpose
Return the date for a specified weekday in a specified month.
Return Value
Date of the nth weekday in a specified month. An error returns DateAndTime.Error!.
Syntax
numeric := DateOfNthWeekDay (Nth: enumeration or numeric; DayOfWeek: enumeration; [Month: enumeration]; [Year: numeric])
Parameters
Nth
enumeration or numeric Number of the weekday in a specified month and year. Numeric values range from 1 to 5, or use one of the following enumerations:
First!
Return the date of the first specified weekday.
Last!
Return the date of the last specified weekday.
DayOfWeek
enumeration Day of the week to return.
Sunday!
Monday!
Tuesday!
Wednesday!
Thursday!
Friday!
Saturday!
Month
enumeration (optional) Month for which to return the date of a specified weekday. If missing, the current month is used.
January!
February!
March!
April!
May!
June!
July!
August!
September!
October!
November!
December!
Year
numeric (optional) Year for which to return the date of a specified weekday. If missing, the current year is used.
DateString
Purpose
Return the date in a string.
Return Value
An empty string ("") is returned for an illegal date.
Examples
vNmbrDate := DateAndTime (1; 1; 2000)
vDate := DateString (vNmbrDate; ; "dd/MM/yyyy (dddd)")
MessageBox (x; "Date String"; vDate)
Result: 01/01/2000 (Saturday)
vDate := DateString (; Short!)
MessageBox (x; "System Date"; vDate)
Result (system date): 2/17/96
vDate := DateString (; Long!)
MessageBox (x; "System Date"; vDate)
Result (system date): Saturday, February 17, 1996
Syntax
string := DateString ([Date: numeric]; [Type: enumeration]; [Format: string])
Parameters
Date
numeric (optional) A number representing a date, or the system date if not used. For a number, see DateAndtime.
Type
enumeration (optional) If missing, Short! is used.
Short!
Date represented as digits.
Long!
Date spelled out.
Format
string (optional) Specify a date string format. If missing, the current system format from the Windows Control Panel is used. See the example above.
Day (month)
d (digits without leading zeros for single- digit days)
dd (digits with leading zeros for single- digit days)
Day (week)
ddd (three-letter abbreviation)
dddd (day of the week)
Month
M (digits without leading zeros for single- digit months)
MM (digits with leading zeros for single- digit months)
MMM (three-letter abbreviation)
MMMM (month spelled out)
Year
y (last digit only)
yy (last two digits)
yyyy (four digits)
Period/Era
gg (ignored if era string is not associated)
DateWeekday
Purpose
Return an enumeration representing the day of the week.
Return Value
Check for an error (illegal date) by comparing the return value to DateWeekday.Error! or DateAndTime.Error!.
Sunday!
Monday!
Tuesday!
Wednesday!
Thursday!
Friday!
Saturday!
Error!
Example
vDate := DateAndTime (1; 1; 2000)
If(DateWeekday(vDate) = DateWeekday.Date.Saturday!)
MessageBox (x; "Day of the Week"; "Saturday")
Endif
Result: MessageBox displays "Saturday."
Syntax
enumeration := DateWeekday ([Date: numeric])
Parameters
Date
numeric (optional) A number representing a date, or the system date if not used. For a number, see DateAndTime.
DateWeekdayName
Purpose
Return the name of a day of the week.
Return Value
An empty string ("") is returned for an illegal date.
Example
vDate := DateAndTime (17; 2; 1996)
vWeekday := DateWeekdayName (vDate; Short!)
MessageBox (x; "Weekday"; vWeekday)
Result: Sat
Syntax
string := DateWeekdayName ([Date: numeric]; [Type: enumeration])
Parameters
Date
numeric (optional) A number representing a date, or the system date if not used. For a number, see DateAndTime.
Type
enumeration (optional) Default: Long!
Short!
Weekday is abbreviated.
Long!
Weekday is spelled out.
DateWeekOfYear
Purpose
Return the week number for a specified date.
Return Value
Week number for a specified date. An error returns DateAndTime.Error!.
Syntax
numeric := DateWeekOfYear ([Date: numeric]; [FirstDayOfWeek: enumeration])
Parameters
Date
numeric (optional) Date for which to return the week.
FirstDayOfWeek
enumeration (optional) Day of the week that week starts on. If missing, Sunday! is used.
Sunday!
Monday!
Tuesday!
Wednesday!
Thursday!
Friday!
Saturday!
DateYear
Purpose
Return a value representing a year.
Example
Appendix A: 8097
Return Value
Check for an error (illegal date) by comparing the return value to DateAndTime.Error!.
Example
vYear := DateYear()
MessageBox (x; "Year"; vYear)
Result (system date): 1996
Syntax
numeric := DateYear ([Date: numeric])
Parameters
Date
numeric (optional) A number representing a date, or the system date if not used. For a number, see DateAndTime.
DDEExecute
Purpose
Send a command string to a server application. See the server application’s documentation for command names and syntax.
Example
Appendix A: 8014
Syntax
DDEExecute (ConversationID: numeric; Command: string)
Parameters
ConversationID
numeric A number that links the server and client applications. DDEInitiate returns ConversationID.
Command
string A command to execute.
DDEExecuteExt
Purpose
Send a command to a server application, and return a value that indicates if the command was successfully processed. See the server application’s documentation for command names and syntax.
Example
Appendix A: 8015
Return Value
A number greater than 0 if successful, or 0 if not.
Syntax
numeric := DDEExecuteExt (ConversationID: numeric; Command: string; TimeOut: numeric; [Label: label])
Parameters
ConversationID
numeric A number that links the server and client applications. DDEInitiate returns ConversationID.
Command
string A command to execute.
TimeOut
numeric Asychronous DDE: Set TimeOut to 0 or a negative value. DDE returns immediately, and notifies the macro that the command was delivered. When the server application acknowledges receiving the command, DDE notifies the macro and the macro calls Label. The return value is invalid for asychronous DDE, because the server application has not yet processed the command.
Synchronous DDE: Set TimeOut to a positive integer, which specifies the maximum number of milliseconds to wait while the server application processes the command. The result is returned when the command is processed or DDE times out (command is not processed within the specified time). See Return Value above.
Label
label (optional) The Label to call when the server application acknowledges receiving the command (see the TimeOut parameter above). If the Label statement does not include Return, macro behavior is unpredictable.
If Label is missing, DDEExecuteExt works similar to DDEExecute.
DDEInitiate
Purpose
Start a DDE conversation with a server application, and return a conversation ID. A conversation must be started between server and client applications before you can use commands such as DDEPoke, DDERequest, and DDEExecute.
Example
Appendix A: 8014
Return Value
A number that links the server and client applications is returned, or 0 if the conversation is not started.
Syntax
numeric := DDEInitiate (ServiceName: string; TopicName: string)
Parameters
ServiceName
string A DDE service name. See a server application’s documentation.
"WPWin7_Macros" (WordPerfect 8)
"Presentations" (Presentations 7)
"WPWin60_Macros" (WordPerfect 6.1)
"GroupWise" (GroupWise 4.1)
TopicName
string A topic name. See the server application’s documentation.
"Commands" (WordPerfect 8)
"Command" (Presentations)
"Commands" (WordPerfect 6.1)
"Command" (GroupWise 4.1)
DDEPoke
Purpose
Assign data to an item in a server application.
Example
Appendix A: 8017
Syntax
DDEPoke (ConversationID: numeric; ItemName: string; ItemData: string)
Parameters
ConversationID
numeric A number that links the server and client applications. DDEInitiate returns ConversationID.
ItemName
string A server application item. See the server application’s documentation for item names.
ItemData
string The data to assign to a server application item.
Note
Check your server application documentation to see if it supports XTYP_POKE transactions. Many applications do not.
DDERequest
Purpose
Get the contents of a server application item.
Example
Appendix A: 8016
Return Value
Contents of the server application item specified by ItemName.
Syntax
string := DDERequest (ConversationID: numeric; ItemName: string)
Parameters
ConversationID
numeric A number that links the server and client applications. DDEInitiate returns ConversationID.
ItemName
string The name of a server application item.
Note
Check your server application documentation to see if it supports XTYP_REQUEST transactions. Many applications do not.
DDETerminate
Purpose
End a DDE conversation with a server application.
Example
Appendix A: 8016
Syntax
DDETerminate (ConversationID: numeric)
Parameters
ConversationID
numeric A number that links the server and client applications. DDEInitiate returns ConversationID.
DDETerminateAll
Purpose
End all DDE conversations.
Example
Appendix A: 8014
Syntax
DDETerminateAll ()
Declare
Purpose
Create a local variable or array, which stores as many variables, constants, or expressions as memory allows.
An array can have up to 10 dimensions, and up to 32,767 elements per dimension depending on the amount of available memory. In the following example, Declare creates ArrayA with element in each array is assigned a value. Parentheses are optional.
Declare(ArrayA[10]; ArrayB[5])
ArrayA[3] := "John"
Explanation: Assigns “John” to the third element in ArrayA.
ArrayB[5] := ArrayA[3]
Explanation: Assigns “John” to the fifth element in ArrayB.
In the next example, Declare creates a two- dimensional array (ArrayC) with 100 elements (10 rows and 10 columns). One element is assigned a value.
Declare ArrayC[10;10]
ArrayC[2;3] := 3+6
Explanation: Assigns 9 to the element at row 2, column 3.
Example
Appendix A: 8018
Syntax
Declare ({<VariableName> variable := <Value> any})
Parameters
<VariableName>
variable The name of a local variable or array. Use a semicolon to separate names when declaring more than one variable or array. If an array is declared, enclose the array indices in brackets. Use a semicolon to separate elements in a multi-dimensional array.
<Value>
any (optional) The value assigned to <Variable> at the time of declaration. For example, Persist vTest = 20. vTest equals 20 at run time. If missing, the value of <Variable> is undefined.
Default:
Purpose
Specify the code to execute when no CaseOF <Selector> matches the control expression in a Switch statement. See Switch.
Syntax
Default:
DefaultUnits
Purpose
Specify the default unit of measure, and return the previous unit of measure. You can set a new value, and then restore the previous value.
Example
Appendix A: 8006
Return Values
The previous unit value.
None!
Centimeters!
Inches!
Millimeters!
Points!
WPUnits!
Examples
In the first example, Advance uses the default unit of measure (WPUnits!). In the second, Advance overrides the default unit of measure and uses inches. In the third, DefaultUnits specifies centimeters as the default unit of measure.
Advance(AdvanceFromTop!; 4)
Explanation: Advance insertion point 4 WPUnits.
Advance(AdvanceFromTop!; 4")
Explanation: Advance insertion point 4 inches.
DefaultUnits(Centimeters!)
Advance(AdvanceFromTop!; 4)
Explanation: Advance insertion point 4 centimeters.
The default unit of measure is effective until changed by another DefaultUnits command. If not specified by DefaultUnits, the default unit of measure is WPUnits!.
Discussion
None! has been added to the list of possible units. Normally, when a non-units value such as 1200 is combined with a units value such as unit type. If the default unit type is WPUnits,
1.0C + 1200 = 3.54C (1200 WPUnits = 2.54C)
If, however, the default unit is set to None!, the non-units value assumes the unit type of the value it is combined with (no conversion is performed). For example,
1.0C + 1200 = 1201.0C
With the default unit set to None!, 1200 assumes the unit type of centimeter.
Syntax
enumeration := DefaultUnits ([Units: enumeration])
Parameters
Units
enumeration (optional) A unit of measure. If missing, the current default unit of measure is returned, but no new unit of measure is set.
None!
Centimeters!
Inches!
Millimeters!
Points!
(One Point equals 1/72 of an inch)
WPUnits!
(One WordPerfect unit equals 1/1200 of an inch)
WP1200ths!
(Synonym for WPUnits!)
DegreesToRadians
Purpose
Convert an angle in degrees to radians.
Return Value
Angle in radians.
Syntax
numeric := DegreesToRadians (Degrees: numeric)
Parameters
Degrees
numeric Angle in degrees.
DeleteDirectory
Purpose
Delete a directory.
Example
Appendix A: 8080
Return Value
True if successful, False if not.
Syntax
boolean := DeleteDirectory (DirectoryName: string; [Prompts: enumeration])
Parameters
DirectoryName
string Include the full path.
Prompts
enumeration (optional) Default: NoPrompts!
NoPrompts!
Prompts!
Prompt if the directory does not exist.
DeleteFile
Purpose
Delete a file(s).
Example
Appendix A: 8086
Return Value
True if successful, False if not.
Syntax
boolean := DeleteFile (Filename: string; [Prompts: enumeration])
Parameters
Filename
string Include the full path and filename. Use with caution. If a file is not specified, all files in the directory are deleted.
Prompts
enumeration (optional) Default: NoPrompts!
NoPrompts!
Prompts!
Prompt if the file does not exist.