This document describes new and improved features in PerfectScript. It includes new features and changes since PerfectOffice 3.0. This version of this document also includes the undocumented features and commands.
Document Change Log
9/8/97 JDan 1.0 - Document created to document changes implemented in PerfectOffice 3.0 / WordPerfect 6.
Quick Overview of PerfectOffice 3.0 Macro Compatibility
This section provides a quick overview of things you may need to do to your PerfectOffice 3.0 (WPWin 6.1) macros to make them work in PerfectScript 7. The next section, Modified and Improved Commands and Language Features, provides more extensive details.
72% ran without change
15% had to be changed because of DLLCall usage, Callback changes for Windows 95, or BIF usage that is no longer applicable because settings are now in the Windows Registry
10% had to be changed because of changes to WordPerfect or Draw commands
2% had to be changed because of new reserved words in PerfectScript (MAX, SIN, COS, etc.) and WordPerfect 5.2 syntax that is no longer supported
PerfectScript (the program--PS70.EXE)
• can now debug a macro from the PerfectScript menus
• the compiler and interpreter are now DLLs rather than EXEs which results in faster compilation and faster running macros
• added /c-filename command-line option to compile a macro
• added /x-filename command-line option to debug a macro
• added /e-filename command-line option to edit a macro for Edit along with Play and Compile from the Win95 Explorer
• can now compile multiple macros simultaneously
• smaller and faster macro object
• an option is provided in preferences to record all product prefixes, even for the default application
• the user interface for PerfectScript has been revamped and now includes a toolbar and window showing active macros and their states (see the next section for details)
PerfectScript Interface Changes
Advanced / Hidden Features, Settings and Keystrokes in the macro system
The PerfectScript Macro system has a number of hidden features and settings that are not documented, and not supported. These are used primarily for internal debugging and testing, and may contain bugs. Direct access to these features and settings from the user interface of the MacroFacility (PS70) is controlled by a specific registry setting. This registry setting is (note the leading space in the name of the value):
HKEY_CURRENT_USER\Software\PerfectOffice\PerfectScript\7\Settings\" Show Hidden Settings" = 1 (DWORD value)
If this setting does not exist, or has a value of 0, then direct access is not available. When this setting does exist, with a value of 1, then additional settings are available in the "Settings" dialog.
This registry setting can only be set by running the registry editor (regedit.exe) and manually adding or modifying this registry setting, and cannot be be toggled on/off through a command accelerator key sequence in the MacroFacility.
Hidden BIF settings
All hidden registry settings (except those stated below) can be accessed in the "Settings" dialog of the MacroFacility.
(none)
Command Inserter
Dialog Editor and Dialog Statements
Dialog Editor is now modeless so multiple dialogs can be edited simultaneously and the macro code and the dialog can be edited together. Cut, copy, paste between dialogs now supported. More compatibility between old-style DIALOG statements and dialogs created with Dialog Editor. For example, old-style statements will now work on new-style dialogs. Dialogs created with old-style dialog statements can now be saved as new-style dialogs, etc.
From the dialog browser you can copy dialogs to the clipboard. These dialogs can then be pasted into other macros or pasted as textual dialog macro statements into documents or other text editors.
Macro Debugger
A simple macro debugger has been added.
Obsolete Commands and Language Features
In a future release of the macro system, there are some commands that may or may not be supported. Users are encouraged to replace these commands with their functional equivalents (if any) as soon as possible. For backward macro compatibility, these commands will continue to be supported, but they will no longer be documented in the command browser or in the macro help information. These commands may be eliminated in some future release.
...
Enumerations for built-in commands
The keyword parameter values for built-in commands of the macro system have been changed to enumerations, and have had a trailing "!" symbol added to the names. This is to bring the syntax of the built-in commands into conformity with the product commands. This eefects the following keywords:
Application - Default - Use Default!
Cancel - On, Off - Use On! and Off!
Error - On, Off - Use On! and Off!
NotFound - On, Off - Use On! and Off!
DLLCall, DLLCall Prototype - Bool, DWord, Integer, Real, String, Word, AnsiString, OemString, WPString, Void - Use Bool!, DWord!, Integer!, Real!, String!, Word!, AnsiString!, OemString!, WPString!, Void!
Menu, MenuList - Digit, Letter - Use Digit! and Letter!
VarErrChk - On, Off - Use On! and Off!
DefaultUnits - Centimeters, Inches, Millimeters, Points, WPUnits, WP12000ths - Use Centimeters!, Inches!, Millimeters!, Points!, WPUnits!, WP12000ths!
AssertCancel, AssertError, AssertNotFound
The functionality of these commands is available through the Assert command, specifying the desired condition to assert in the Condition parameter as CancelCondition!, ErrorCondition! or NotFoundCondition!.
CancelOn, CancelOff
The functionality of these commands is available through the Cancel command, specifying On! or Off! as the state parameter.
ErrorOn, ErrorOff
The functionality of these commands is available through the Error command, specifying On! or Off! as the state parameter.
NotFoundOn, NotFoundOff
The functionality of these commands is available through the NotFound command, specifying On! or Off! as the state parameter.
DialogDisplay
Use the DialogShow command.
DialogUndisplay
Use the DialogDismiss command.
DialogSendMessage
This command was never fully implemented, and has been removed from the documented command list.
ReturnCancel, ReturnError, ReturnNotFound
Use the Return command, specifying the desired condition to assert in the Condition parmeter as CancelCondition!, ErrorCondition! or NotFoundCondition!.
VarErrOn, VarErrOff
The functionality of these commands is available through the VarErrChk command, specifying On! or Off! as the state parameter.
Modified and Improved Commands and Language Features
This section describes changes to existing commands and, where applicable, incompatibilities that may arise with old (PerfectOffice 3.0 and prior) macros. In this section, "..." indicates places where existing capabilities have not been changed.
various commands
various commands
In the 5.1/5.2 version of the macro language, no commands could be called as functions to return values. All commands, including built-in programming commands and product commands, had to be called as procedures. Any output values were returned in variables that were passed to these 'procedures' as parameters (usually the first parameter). In the 6.0/6.1 release, the concept of functions was introduced, and many of the 'value returning procedure' commands were changed to allow them to be called as functions that would return values. For the most part, this change was made to the built-in programming commands and a few product commands of the macro system itself. Though the capability was available to our product applications, WPWin did not use this feature, and all the programming commands that were part of the Macro Facility also did not implement this. For compatibility with the 5.1/5.2 release, all programming commands that were changed from procedures to functions, continued to accept the procedure call format even though we only documented the function format. In this new release, the remainder of the 'value returninig procedure' programming commands that were still called and documented as procedures have been changed to functions, while still retaining their procedure calling format for compatibility with previous releases.
The commands that were changed in the 6.0/6.1 release were already documented properly in that release, and are included here for informational use only. They were:
AppLocate, DDERequest, Fraction, Integer, NumStr, StrLen, StrNum, StrPos, SubStr
The commands that have been changed in this release need to be documented as functions. They are:
DialogHandle, BIFFilePath, RegionGetWindowText, RegionGetSelectedText, RegionGetCheck, RegionIsVisible, DDEInitiate, DLLLoad, OnDDEAdvise Call
This dual procedure/function calling format can cause a potential confusion on the user's part. If one of these 'dual' calling format commands is called as a function, then the result is returned from the command (not as a parameter). If it is called as a procedure, then a new first parameter must be specified, which is the name of a variable to receive the result value. For example:
a := StrLen ("this is a string") // function format - 'a' gets result
StrLen (a; "this is a string") // procedure format - 'a' gets result
The confusion arises when these 'dual' format commands are compared to functions that do not support this 'dual' format. A'normal' function, may also be called as a procedure, but when it is, it does not accept a new first parameter to receive the result value. The result is lost if called in a procedure format. For example:
a := NToC (65) // function format - 'a' gets result
NToC (65) // procedure format - result is lost
If an attempt is made to call a 'dual' format command in a procedure format without the new first parameter, then a compile error will usually result. For example:
StrLen ("this is a string") // procedure format - will generate compile error
This procedure call to StrLen doesn't appear to be different than the procedure call to NToC, and since both are documented as functions taking a single parameter, then a user could become confused as to why one generates a compile error and the other doesn't. However, a procedure call to NToC or StrLen without keeping the result is senseless, since the result of performing the command has been lost, and so the command has performed no useful purpose. Because of this, we feel that this situation will rarely occur, and is worth the compatibility that is gained.
There is another group of commands that were introduced in the 6.0/6.1 release and documented as procedures, that returned a secondary status result to an output variable parameter. It is a secondary result value, because it returned the status of performing the command, and the main result of calling the command was either the actions the command performed, or was returned in other parameters. This output parameter was optional, and if specified was the name of a variable to receive the output status result. If not specified, no status was returned. These procedure commands have been changed to functions, but they still accept the optional output variable parameter. The output status result is returned in the output variable parameter (if present), AND as the return value of the function. Since the output result was just a secondary status result value, it was quite common to ignore this value, and call this command without the output status variable parameter. If these commands were changed to allow the 'dual' calling format, they would be documented as functions. And since it is common to ignore the return value, then users would tend to call these using the procedure calling format. But because of the compatibility issue, the procedure would require a new first parameter to receive the result value. We have found that since the function format documentation does not show the new first parameter format, that this parameter was being left off, and compile errors were a common result. Therefore, these commands are now functions that also have the first parameter for a copy of the output result as part of their documented format. Doing this prevents users from calling them as procedures with the first parameter left off. These commands are:
BIFInfo, BIFRead, BIFWrite, MessageBox
Application
Application statement (and EndApp and NewDefault statements) no longer limits product prefixes to two characters and will now usually be the name of the product itself. This improves readability of macros when more than one product is involved in the macro.
Assert (Condition:enumeration or numeric)
Assert now accepts a condition code of CancelCondition!, ErrorCondition! or NotFoundCondition!.
Break ([<StatementName>label>])
This command accepts the name of the statement to break out of.
[StatementName] This is the name of the statement that this Break statement goes with. This parameter is completely optional, and if specified, does not have to match the actual statement that is goes with, but is allowed in order to allow the macro to be more self documenting.
Dialog and Region commands
In previous releases, the DialogDefine statement created the dialog immediately. In this release, the dialog data is assembled in memory and the dialog is not actually created until a DialogLoad or DialogShow command. This means that Region commands that reference the dialog or its controls will not work until after the DialogShow has occurred. Similarly, DialogHandle will not work until a DialogLoad or DialogShow has occurred.
EndFunc ([<Name>label])
EndProc ([<Name>label])
These commands accept optional parameter.
[Name] This is the name of the Function or Procedure that this EndFunc or EndProc command goes with. This parameter is completely optional, and if specified, does not have to match the Name used in the Function or Procedure command, and is allowed to allow the macro to be more self documenting.
EndFunction ([<Name>label])
EndProcedure ([<Name>label])
These commands are synonyms of the EndFunc and EndProc commands.
Next ([<StatementName>label>])
This command accepts the name of the statement to continue to the next iteration of.
[StatementName] This is the name of the statement that this Next statement goes with. This parameter is completely optional, and if specified, does not have to match the actual statement that is goes with, but is allowed in order to allow the macro to be more self documenting.
New Commands and Language features
This section describes new commands and language features which have been added.
new reserved words
new reserved keywords
New keywords have been added to the macro language. These keywords are reserved words and may not be used as variable or label names in macros. In addition to these new reserved keywords, the name of any new commands are also considered reserved words, since those names also cannot be used as variable or label names. (However, just because a new reserved keyword is on this list, does not imply that there is a new command or feature by that name that can be accessed.) The new reserved keywords that have been added are:
Several new commands have been added, which are now reserved words, but they do not need to be listed separately. See below for the list of new commands.
...
Break [Switch]
Break [For]
Break [ForNext]
Break [ForEach]
Break [Repeat]
Break [While]
Next [For]
Next [ForNext]
Next [ForEach]
Next [Repeat]
Next [While]
EnvVariableGet
EnvVariableSet
Value
Bugs Fixes and Corrections