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

4/13/98 JDan 2.46 - Update return value types of some commands.

12/8/97 JDan 2.45 - Add EndFunction and EndProcedure.

10/2/97 JDan 2.44 - List the return enumerations from the DefaultUnits command.

9/8/97 JDan 2.43 - Minor changes.

8/4/97 JDan 2.42 - Minor cleanup to document.

10/3/96 JDan 2.41 - Correct the use of the ANY parameter type to the specific types accepted by RoundOff.

6/27/96 SteveCa Documented change in MacroDialogResult on dialog editor dialogs.

6/26/96 SteveCa Documented the fact that popdown button controls are no longer supported in Dialog Editor.

4/16/96 JDan DateWeekday and DateMonth now return enumerations rather than numbers, and DateAndTime accepts an enumeration for the month.

4/15/96 JDan BinaryPack and BinaryUnpack use raw binary data, not any.

4/12/96 JDan Add section describing all callback array values. Also added section to compatibility section addressing 32 bit concerns for callback array entries.

4/11/96 DCooper Added element 10 (hiword of wparam) and 11 (loword of wparam) to the dialog callback array.

3/28/96 SteveCa Removed statement about NoValidate! not working in DialogAddFilenameBox (because it DOES work now). Also added new section on PerfectOffice 3.0 macro compatibility.

3/27/96 JDan Described the 'Beginning' parameter of the StrPos and CharPos commands.

3/27/96 SteveCa Described some potential problems using BIF calls when running PerfectOffice 3.0 apps.

3/11/96 JDan Added ConvertType command.

3/11/96 JDan Parameters and return value of RoundOff command changed from Numeric to Any to accept measurements without converting to the current default units first. So if a Centimeters value is rounded, the return value will also be in Centimeters.

3/7/96 SteveCa BIF is now backward compatible

3/5/96 JDan Corrected description of several commands that support both procedure and function calling syntaxes. The commands affected were CharLen, CharPos, CToN, NToC, StrUnit, SubChar, ToLower, ToUpper, UnitStr, AppExecuteExt, BIFInfo, BIFRead, BIFWrite, DDEExecuteExt, MessageBox and OnDDEAdvise Call.

3/4/96 JDan Corrected error in description of IntegerPart and ExponentPart. They refered to the mantissa, not the integer or exponent.

2/29/96 JDan RegionGetCheck and GetFileAttributes command used to return numeric values. They now return enumerations whose values are compatible with the numeric values they used to return.

2/28/96 JDan Add clarification of the change in the "Icon" numeric parameter of the Prompt command to the "Style" enumeration parameter, and the change in the "ShowWindow" numeric parameter of the AppExecuteExt command to the "State" enumeration parameter. Also add a description of the changes to the PersistAll command.

2/27/96 JDan Add clarification of version info returned from MacroInfo.

2/27/96 JDan Change names of log functions from log, log2, log10 to ln, lg and log (per Donald Knuth in 'The Art of Computer Programming", Vol 2(?)).

2/22/96 AlanG Added description of the 'check this macro for viri' token that will be passed to the dll's in the PS Third Party dll chain.

2/19/96 JDan Add description of math tokens.

2/19/96 JDan Clarify expression operator precedence levels. Document the new "IN" operator, and the "-" operator for string reduction, and "=" and "!=" for array comparisons.

2/12/96 SteveCa Changed the "Abs" token to "AbsVal" so as not to conflict with the "Abs" token that is in Quattro Pro.

2/9/96 JDan Added description of the FileNameDialog command.

2/7/96 SteveCa Clarification on NetCancelConnection

2/2/96 JDan Document the BinaryPack, BinaryUnPack and SizeOf commands.

2/1/96 SteveCa Added new data types (PFByte, PFWord, PFBool) to the RegistrySetValue token.

1/29/96 JDan Corrected typo in command name: ToChars is really StrToChars.

1/26/96 SteveCa Support for Creative's TextAssist text-to-speech system added.

1/26/96 SteveCa Added a clarification on RegistrySetValue.

1/24/96 JimmyB Added /e command-line option for editing macros with Play, Compile, and Edit from the Win95 Explorer

1/23/96 SteveCa In RegistryQueryValue and RegistrySetValue, document how to obtain and set the Default (unnamed) value for a key.

1/22/96 SteveCa Rearranged some things and alphabetized some others; fixed DialogSetProperties

1/19/96 JimmyB Modified the SetFileDateAndTime and GetFileDateAndTime commands to use the new date values for Date and Time functions.

1/12/96 AlanG Removed the FLAGS param from the DialogSetProperties token.

1/8/96 SteveCa On DialogAddFilenameBox, the NoValidate! style is now obsolete.

1/5/96 AlanG DialogAddScrollBar token -- Styles Left!, Top!, Right!, and Bottom! do not have anything to do with the initial position of the thumb within the scroll bar control.

12/28/95 JDan Added new item types and associated parameter to MacroInfo command: UserConditionOn!, UserConditionCall!, UserConditionLabel!.

12/28/95 JDan Document new parameter values for Assert.

12/27/95 JDan Document new return values from existing condition handler commands: Error, Cancel, NotFound, VarErrChk, OnCancel, OnCancel Call, OnError, OnError Call, OnNotFound, OnNotFound Call.

12/27/95 JDan Document user defined condition handler commands: OnCondition, OnCondition Call, Condition.

12/27/95 JDan Documented new string routines.

12/22/95 JDan Documented ValueType command.

12/18/95 JimmyB Documented changes to PerfectScript Interface

12/13/95 SteveCa Added CoachMessageBoxEx from Dave Cooper.

12/13/95 SteveCa Clean up document; reordered some sections; listed additional new tokens (to be documented later by Dan Broadhead)

12/5/95 AlanG Named region (Regionxxx) tokens and the PerfectScript user dialog tokens -- Clarification.

11/30/95 JDan Added None! To DefaultUnits, and made it return the previous default units type.

11/27/95 SteveCa Copy dialog to clipboard and paste into document now works.

11/22/95 JDan Added CONSTANT statement.

11/22/95 JDan Changed platform id in IFPLATFORM statement.

11/22/95 AlanG Added optional focus param to DialogShow, DialogShow parent param no longer ignored for old style dlgs.

11/20/95 JDan Document ** operator.

11/17/95 JDan Document access to array element [0].

11/17/95 JDan Document new MacroInfo command.

11/17/95 JimmyB Added CallbackWait and CallbackResume commands

11/10/95 AlangG Document how DialogDismiss and DialogDestroy should work with MDE dialogs.

10/27/95 SteveCa Documented that on DialogDefine, the NoFrame! style no longer does anything.

10/23/95 Bhunsaker Documented DialogAddCounter and DialogSetProperties (set font size) better.

10/18/95 SteveCa Document ability to record product prefixes on all product commands (including those of the "default" product)

10/10/95 Bhunsaker Removed recently added styles (since 16 bit release) unsupported in DialogEditor for all DialogAddXXX commands. Made changes to DialogAddCounter functionality. Maximum and minimum allowable values are listed under DialogAddCounter section.

10/6/95 AlanG Documented DialogLoad, DoesDialogExist, DialogSave, and maximum length allowed for a dialog name.

10/4/95 SteveCa Documented additional incompatibilities with old macros

10/2/95 SteveCa Described how, when using DialogDefine, the dialog is not actually created until DialogShow occurs.

9/29/95 SteveCa MMSpeak and MMSpeakClipboard changes

9/22/95 SteveCa improved/added multimedia tokens

9/7/95 SteveCa Added some new Network tokens; enhanced Prompt token

9/05/95 Bhunsaker Added a new macro command DialogSetProperties. This dialog will be used in conjunction with the DialogDefine token. Hopefully this will be less confusing to the typical user than having too many parameters for one token. The parameters correspond to settings allowed in the new dialogs.

9/01/95 Bhunsaker removed unsupported styles for DialogDefine and DialogAddEditBox, (Aug. 25th), added styles to DialogDefine, (Aug. 18th) other styles were added to the following tokens : DialogAddCheckBox, DialogAddComboBox, DialogAddCounter, DialogAddEditBox, DialogAddFileNameBox, DialogAddListBox, DialogAddPushButton, DialogAddRadioButton, DialogAddScrollBar, DialogAddText. (Aug. 10th) added new macro commands DialogAddBitmap, DialogAddProgress, DialogAddDate.

8/31/95 SteveCa documented error return codes for Registry functions

8/30/95 JDan Clarify ErrorNumber description, describe function format of what used to be procedures, describe which built in programming commands have been made into macro product commands

8/29/95 SteveCa documented the date and time format strings

8/24/95 SteveCa added Net tokens

8/23/95 JDan Added a date/time parameter to date and time tokens - added a new date token

8/23/95 SteveCa changed PerfectScript version from 3.0 to 7

8/22/95 SteveCa added DateString and TimeString

8/21/95 SteveCa Removed ? from Date and Time tokens; added new Date token

8/18/95 SteveCa Added Date and Time tokens

8/17/95 SteveCa Command Inserter: insert whole command

8/16/95 SteveCa minor changes to Registry tokens

8/15/95 SteveCa Added the new Registry tokens

8/03/95 SteveCa Reformatted; added the new App tokens

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.

• All DLLCall statements need to be reviewed and possibly changed to accomodate the 32-bit environment. In particular, calls to Windows APIs (in user.dll, kernel.dll, and gdi.dll) will need to be changed to use the 32-bit Windows DLLs and account for any parameter changes.
• You may have to change variable, label, function names if the name is now a reserved word (ie, if there is a new token with that name like sin, cos, etc.).
• BIF calls need to be reviewed and possibly changed. Settings for 32-bit applications are stored in the Windows Registry. You can use the new Registry tokens to access settings for Corel Office 7. Other usages of the BIF may or may not work. If another PerfectOffice 3.0 application is running (GroupWise, WordPerfect 6.1, Presentations 3.0, Quattro Pro) then BIFWrite calls will not work on the Public! and Private! BIFs because those applications open the BIF exclusively and thus prevent changes to the file from any other applications.
• SubStr, NumStr, and StrPos can no longer be used the way they were in WPWin 5.2. This was allowed in WPWin 6.1 as a transition, but is no longer supported.
• DialogHandle will not work until a DialogLoad or DialogShow has occurred. In PerfectOffice 3.0 it worked as soon as DialogDefine was used.
• Dialog sizing may need to be adjusted slightly to get the same look as in PerfectOffice 3.0.
• Calling DialogDismiss on a dialog-editor dialog that does not use a callback will produce an error.
• The platform name is now Win95! rather than Win!. This allows you to recognize Windows95 separate from Windows 3.x in the IfPlatform statement.
• All dialog callbacks should be reviewed and possibly changed to accomodate the 32-bit environment. In particular, entries in the callback array for dialog callbacks that refer to the wParam (entry [6]), lParam ([7]) and the hiword ([8]) and loword ([9]) of the lParam, should be carefully reviewed as the wParam has been made into a DWORD, and many values have been moved between the wParam and the lParam.
• Popdown button controls are no longer supported in Dialog Editor. This control is no longer used in any Corel WordPerfect application.
• When macro dialogs are dismissed, MacroDialogResult will contain "1" if OK is pressed and "2" if Cancel is pressed. In PerfectOffice 3.0, it contained "OkBttn" or "CancelBttn" if the dialog was created with dialog editor, and "1" or "2" if created with Dialog statements.
• Of 168 PerfectOffice 3.0 macros from WordPerfect Magazine:

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 is now tokenized so it is enabled for Third-Party add-ons. In other words, it can now have a Third Party DLL chain. Currently, only a single token is sent:

MacroStart (<PlayLibraryStruct>rawbinary)

This token will be passed to the third party chain when a macro is about to be played, but has not yet been opened by PerfectScript. The intent is for a third party DLL to check the macro (for a virus, etc), and return a status back to PerfectScript. No message will be given to the user from PerfectScript; all messages to the user must be generated and displayed from within the DLL that is processing this token.

TokenID = 1

Application = "PerfectScript"

ParamCount = 1

Requestor = [will vary]

MacroID = [will vary]

rgParam[0].eType = eParmRawBinary (94)

rgParam[0].uData.lpvPtr = ptr to MAC_PLAYLIBRARY structure

Third Party return values:

DLL_HAN_NOT_HANDLED -- no dll checked it, go ahead and play it.

DLL_HAN_NO_ERROR -- a dll looked at it, and said it was good, play it

All other return values -- do NOT play the macro

PerfectScript Interface Changes

The interface to PerfectScript has been changed to make it easier to use and to show what actions are being performed by PerfectScript. A list view has been added in the client area to list which macros are being played, compiled, and recorded. The View menu allows, in addition to showing or hiding the toolbar, selecting Large Icon, Small Icon, List, or Detailed view for the list view.

The File menu has been changed to work with a selected item in the list view. Stop, Pause, and Break refer to the macro selected in the list view. Stop will stop the macro from playing, compiling, or recording. Pause will pause playing or recording macros. If a macro is already paused, Pause will resume playing or recording of that macro. Break will break into a playing macro and bring up the debugger. Also, if the user clicks the right mouse button on a macro the Stop, Pause, Break menu will pop up as a context menu. From the keyboard, Delete will perform a Stop, Space will cause a macro to Pause, or resume if it is already paused, and Ctrl-Break will Break. Buttons have been added to toolbar perform a Stop or a Pause.

In all views, the macro name is shown. In Details view, the Macro, Status, Location, and Requestor are displayed. The Macro column shows the macro name. The Status column indicates the action being performed by the macro. The actions are Playing, Paused, Compiling, Recording, and Paused Record. The Location column displays the location or path to the macro. The Requestor column lists the application which started the playing or compiling of a macro.

Advanced / Hidden Features, Settings and Keystrokes in PerfectScript

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 keystrokes Macro Facility (PS70)

Control Shift Alt Key Command

Control Alt F10 key Compile

Shift Alt Insert key Registered Apps

Control Shift Insert key Command Inserter 1

Control Shift Alt Insert key Command Inserter 2

Hidden keystrokes in the Command Inserter

Control Shift Alt Key Command

Control Shift Insert button Dump Command List

Control Shift Alt Insert button Brief Command Dump

Hidden registry settings

All hidden registry settings (except those stated below) can be accessed in the "Settings" dialog of the MacroFacility.

"Prefered Interface Language" = (string) "US" (default="US")

"Time Out Tkn App Launch" = (DWORD) (default = 300)

"Prompt on Tkn App Launch" = (DWORD) 1 or 0 (default=0)

Hidden preference dialog settings

The following preference settings are accessable from the "Settings" dialog of the MacroFacility when the Advanced / Hidden settings are enabled:

General page

Show icon during compile

Show icon during play

Show progress during play [not used]

Debug page

Show full routine data

Show actual variable data types

Show "Internal Variables" button

Show "Runtime Stack" button

Show "Object Code" button

Show "Load" and "Save" buttons

Display all breakpoints

Debugger startup file

Compile page

Convert commas to semicolons

Ignore trailing semicolons

Ask to overwrite current object

Ask for listing filename

Ask to overwrite listing file

Generate detailed listing

Generate opcode statistics

Display compile warnings

Display compile errors

Display compile fatal errors

Display compile message %d [not used]

Command Browser page

Use theta indexes

Show actual data types

Show all PIDs

Show all parameters

Show all enumerations

Show token ids

Show enumeration values

Show enumeration return type control [not used]

Command Inserter

Added help button to dialog, and context-sensitive button to caption to allow help on the dialog and help on the highlighted command. Changed "Command Type" from popup button to combobox. Changed layout. Combined former Macro Facility, Compiler, and Interpreter tokens into one PerfectScript list. Remember Command Type between invocations in the same session. In edit box, spaces are added between parameters so lines will wrap properly when inserted into WordPerfect. When the Insert button is pressed while the command edit field is empty, a template of the entire command with all its parameters is inserted.

If the Control and Shift keys are held down when clicking on the Insert button in the command inserter, then a text file is produced that contains a full list of all the commands for the currently selected product, their parameters and enumerations. Whatever settings are enabled for the command inserter in the advanced / hidden Command Browser page of the Preference Settings, will also be relected in the dump file produced (such as the use of the theta index, the display of all parameters and all enumerations, the display of enumeration values, etc).

If the Control, Shift and Alt keys are held down when clicking on the Insert button, then a brief dump is produced as above, but does not include the short help line descriptions for each command.

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

Extensive work has been done on the integrated macro debugger. A full description of its capabilities will follow...

Obsolete Commands and Language Features

In a future release of PerfectScript, 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.

CoachFilterAdd.Type.Mouse!

CoachFilterAdd.Type.Key!

CoachFilterAdd.Type.KeyString!

CoachMessageBox

DialogAddFileNameBox.Style.NoValidate!

HiWord

LoWord

Word

SendKeys.MarkupLanguage.WPWin6x!

SendKeys Wait

CoachFilterAdd.Type.Mouse!, CoachFilterAdd.Type.Key!, CoachFilterAdd.Type.KeyString!

These values are obsolete, and no new equivalents.

CoachMessageBox

The functionality of this command has been replaced by the CoachMessageBoxEx command. Use this new command from now on.

DialogAddFileNameBox.Style.NoValidate!

This enumeration has been removed, and ihas no new equivalent.

HiWord, LoWord, Word

These DLLCall inline functions have no effect on Windows 95, and are not needed. Calls to these commands can be removed.

SendKeys.MarkupLanguage.WPWin6x!

This enumeration has been renamed to New!. Use this new enumeration.

SendKeys Wait

This command does not function properly on Windows95, and was changed to do the same as SendKeys. Neither of these commands function quite right on Windows95, but the SendKeys command will continue to be documented for compatibility, while the SendKeys Wait command will no longer be documented.

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.

expression operator precedence levels

With the addition of the new "**" operator (described in the section below), the expression operator precedence levels have been renumbered. A new precedence level was inserted for this new operator between levels 1 and 2, forming a new level 2, causing all precedence levels starting with the old level 2 to be increased by 1. The new operator precedence table is now as follows:

new level old level operators

1 1 NOT, ~, unary +, unary -

2 <new> **, ^^, \

3 2 *, /, %, DIV, MOD

4 3 +, -

5 4 <<, >>, <<<, >>>

6 5 =, <>, !=, <, <=, >, >=, IN, LIKE, USING

7 6 &, |, ^

8 7 AND

9 8 OR, XOR

10 9 :=, = (assignment), :=: (swap)

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:

BIFFilePath, DialogHandle, DDEInitiate, DLLLoad, OnDDEAdvise Call, RegionGetWindowText, RegionGetSelectedText, RegionGetCheck, RegionIsVisible

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

various commands

Most of the programming commands have been converted to product tokens of the macro system (as the Dialog... commands have always been). This has enabled named parameter passing for these commands, just like any other product command. Other than specifying the parameter names, no special note needs to be made of this difference for these commands. The following commands have been changed:

AppActivate, AppExecute, AppExecuteExt, AppLocate, Assert, [AssertCancel], [AssertError], [AssertNotFound], Beep, Cancel, [CancelOff], [CancelOn], Chain, CharLen, CharPos, CToN, DDEExecute, DDEExecuteExt, DDEInitiate, DDEPoke, DDERequest, DDETerminate, DDETerminateAll, DefaultUnits, DllFree, DLLLoad, EndPrompt, Error, [ErrorOff], [ErrorOn], Fraction, GetNumber, GetString, GetUnits, Nest, NotFound, [NotFoundOff], [NotFoundOn], NToC, NumStr, OnCancel, OnCancel Call, OnDDEAdvise Call, OnError, OnError Call, OnNotFound, OnNotFound Call, Pause, PersistAll, Prompt, Quit, Run, SendKeys, SendKeys Wait, Speed, StrLen, StrNum, StrPos, StrUnit, SubChar, SubStr, ToLower, ToUpper, UnitStr, VarErrChk, [VarErrChkOff], [VarErrChkOn], Wait.

(commands in [ ] are not to be documented, but are retained for backward compatibility).

commands that no longer allow the WPWin 5.2 format

The commands SubStr, NumStr, and StrPos can no longer be used the way they were in WPWin 5.2. The format and parameter order that is documented for PerfectScript 7 must be used. This is the same order and format introduced with and documented in WordPerfect 6.0 and PerfectOffice3.0. This is because the order of parameters was changed in that release for WPDos 6.0 compatibility.

callbacks

When a macro executes a callback routine, global return and parameter array variables are automatically created by the macro system that are accessible to the callback routine. The callback routine can access the callback parameter array for information about the callback event, and will place its return value (if any) in the callback return variable. The parameters for the callback are placed into a global array variable that has the same name as the callback label. The return value (if any) returned from callback routines is placed in a (non-array) global variable that has the same name as the callback label. For example, parameters would be passed to callback routine 'MsgHandler' in an array called 'MsgHandler[ ]', and any return value would be placed into a variable called 'MsgHandler'.

The return value, the number of callback array entries, and the values contained in the callback array depend on the type of callback being called. The callback type is found in the first ([1]) entry of the callback array. The callback array element count can be retrieved by using the Dimensions command, or by accessing the [0] callback array element.

Callback array entries:

This type of callback is setup by the CoachFilterAdd command.

RTN Callback return value (depends on [1])

[0] Count of elements in callback array

[1] Callback type:

0 = CBTYPE_MOUSE - Mouse callback (CoachFilterAdd command)

1 = CBTYPE_KEY - Key and Keystring callback (CoachFilterAdd command)

2 = CBTYPE_TOKEN - Product token (command) callback (CoachFilterAdd command)

3 = CBTYPE_DIALOG - Dialog callback (DialogShow and CoachSetDialogFilter commands)

4 = CBTYPE_CBTMSGBOX - MessageBox callback (CoachMessageBox command)

[2]... ..., etc (depends on [1])

Entries for Mouse callback (type 0 - CBTYPE_MOUSE)

This type of callback is no longer supported. See the CoachInputControl command.

Entries for Key and Keystring callback (type 1 - CBTYPE_KEY)

This type of callback is no longer supported. See the CoachInputControl command.

Entries for Product token (command) callback (type 2 - CBTYPE_TOKEN)

This type of callback is setup by the CoachFilterAdd command.

RTN Callback return value:

undefined = Pass the event to the application

0 = Pass the event to the application

1 = Discard the event

[0] Callback array contains 7 elements plus 1 for each token parameter (count in [6])

[1] Callback type 2 = CBTYPE_TOKEN

-1 = Error - The callback array is not complete.

0 = Match - The user's actions exactly match the defined actions.

1 = No match - The user's actions do not match the defined actions.

2 = Partial match - The user's actions partially match the defined actions.

3 = Regression - The event undoes previous events, such as a Backspace. A regression is not match. Received only if LabelType is Any! or NonMatch!.

4 = Quit filter - The callback is not called.

[3] Name of application that sent this token

[4] Macro id of the macro that sent this token (if sent by a macro)

[5] Product token id

[6] Number of parameters for this token

[7] Token flags

[8] Value of first parameter

[9] Value of second parameter

[10]... Value of ..., etc

Entries for Dialog callbacks (type 3 - CBTYPE_DIALOG)

This type of callback is setup by the DialogShow and CoachSetDialogFilter commands.

RTN Callback return value (only if [5] = WM_COMMAND (273) and from CoachSetDialogFilter, else not used):

undefined = Send the event to the application

0 = Send the event to the application

1 = Don't send the event to the application

[0] Callback array contains 11 elements

[1] Callback type 3 = CBTYPE_DIALOG

[2] Dialog name

[3] Control name (if [5] = WM_COMMAND (273) and not a menu item, or if [5] = TCN_SELCHANGING (-552), else "")

[4] Dialog window handle

[5] Windows message id being sent (see below)

[6] Value of the 32-bit DWORD wParam parameter that was received with the message

[7] Value of the 32-bit DWORD lParam parameter that was received with the message

[8] Value of the HIWORD of the lParam parameter [7] that was received with the message

[9] Value of the LOWORD of the lParam parameter [7] that was received with the message

[10] Value of the HIWORD of the wParam parameter [6] that was received with the message

[11] Value of the LOWORD of the wParam parameter [6] that was received with the message

Elements [6] to [11] have different meanings for each Windows message (contained in [5]). See Windows 95 documentation for more information. When [5] is:

272 = WM_INITDIALOG

Sent when the dialog is first displayed.

This message is for notification only, and cannot be altered or prevented.

RTN Callback return value not used

[6] Window handle of the control that will receive focus

2 = WM_DESTROY

Sent when the dialog goes down.

This message is for notification only, and cannot be altered or prevented.

RTN Callback return value not used

6 = WM_ACTIVATE

Sent when the dialog is activated or deactivated.

This message is for notification only, and cannot be altered or prevented.

RTN Callback return value not used

[7] Window handle of the window being activated or deactivated

[10] Minimized flag (non-zero means minimized)

[11] Dialog activation state:

0 = WA_INACTIVE (dialog becomes inactive)

1 = WA_ACTIVE (dialog becomes active)

2 = WA_CLICKACTIVE (dialog becomes active from mouse click)

3 = WM_MOVE (only sent from CoachSetDialogFilter)

Sent when the dialog is moved to a new location.

This message is for notification only, and cannot be altered or prevented.

RTN Callback return value not used

[8] New X position

[9] New Y position

276 = WM_HSCROLL (not sent from CoachSetDialogFilter),

277 = WM_VSCROLL (not sent from CoachSetDialogFilter)

Sent when the user clicks on a scroll bar control.

This message is for notification only, and cannot be altered or prevented.

RTN Callback return value not used

[7] Window handle of the ScrollBar control

[10] Position of thumb in ScrollBar control (if [11] = 4 or 5, else not used)

[11] Scroll notification code:

6 = SB_TOP

HOME key pressed - scroll to the top or left

7 = SB_BOTTOM

END key pressed - scroll to the bottom or right

8 = SB_ENDSCROLL

Scroll bar activity ended

0 = SB_LINEDOWN

Down or Right arrow clicked - scroll ahead 1 line

1 = SB_LINEUP

Up or Left arraw clicked - scroll back 1 line

2 = SB_PAGEDOWN

Area between Down or Right arrow and thumb clicked - scroll ahead 1 page

3 = SB_PAGEUP

Area between Up or Left arrow and thumb clicked - scroll back 1 page

4 = SB_THUMBPOSITION

Position of thumb after it is dragged is in [10]

5 = SB_THUMBTRACK

Current position of thumb as it is dragged is in [10]

274 = WM_SYSCOMMAND (not sent from CoachSetDialogFilter)

Sent when the user presses Alt+F4, chooses Close from the system menu, or double clicks the system menu.

This message is for notification only, and cannot be altered or prevented.

RTN Callback return value not used

[11] Menu item id of system menu item selected:

61536 if Close, Alt+F4 or double click on system menu

273 = WM_COMMAND

Sent when the user interacts with a control or menu item on the dialog.

These messages can be altered by the callback if sent from the CoachSetDialogFilter command, by returning a value in the callback return variable.

RTN Callback return value (used only from CoachSetDialogFilter command):

undefined = Send the event to the application

0 = Send the event to the application

1 = Don't send the event to the application

[3] Control name or number, or:

"" if from a menu item

"OKBttn" if from the predefined OK button

"CancelBttn" if from the predefined Cancel button

[7] Control window handle ("" if from a menu item)

[10] Notification code (depends on the control type):

Menu items:

(not used)

ListBox:

2 = LBN_DBLCLK - Item was double clicked

ComboBox:

2 = CBN_DBLCLK - Item was double clicked

Button:

0 = BN_CLICKED - Button was clicked

5 = BN_DOUBLECLICKED - Button was double clicked

FileNameEntry:

0 = FNEN_DLGDISMISS - Open Dialog was dismissed

1 = FNEN_DLGRAISE - Open Dialog was displayed

HotSpot:

0 = BMPN_CLICKED - Bitmap was clicked

5 = BMPN_DOUBLECLICKED - Bitmap was double clicked

[11] Control id or menu item id (depends on the control type):

Menu item:

Menu item id

Controls:

Control id or:

1 if from the predefined OK button

2 if from the predefined Cancel button

-552 = TCN_SELCHANGING

Sent when a different tab on a tab control is selected.

This message can be altered by the callback by returning a value in the callback return variable.

RTN Callback return value (used only from CoachSetDialogFilter command):

undefined = Send the event to the application

0 = Send the event to the application

1 = Don't send the event to the application

[3] Control name

[9] Zero based tab index number (the first tab is 0)

[11] Tab control id

Entries for MessageBox callback (type 4 - CBTYPE_CBTMSGBOX)

This type of callback is setup by the CoachMessageBoxEx command.

Callbacks called only if Modality parameter is not Simple!.

RTN Callback return value not used

[0] Callback array contains 4 elements

[1] Callback type 4 = CBTYPE_CBTMSGBOX

[2] Name of the message box

[3] Name of the control

[4] Control state:

0 = Checked, pressed or clicked

1 = Unchecked, not pressed, or not clicked

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.

AppActivate

AppActivate now accepts as its first parameter either a Window Handle or a String.

AppExecute

AppExecute now supports starting non-program files (by using Windows' associations).

AppExecuteExt

The ShowWindow command of AppExecuteExt has been renamed to State, and is an enumeration rather than a numeric. Enumerations have been defined for all the former numeric values.

Assert (Condition:enumeration or numeric)

Assert now accepts either a predefined condition code (CancelCondition!, ErrorCondition! or NotFoundCondition!), or a user defined condition number. See the OnCondition command for a description of how to specify a user defined condition number.

Condition The condition type to assert.

NoCondition!

PauseCondition!

PauseResumeCondition!

DDEAdviseCondition!

DDEExecuteCondition!

CallbackCondition!

UserCancelCondition!

UserErrorCondition!

UserNotFoundCondition!

BIF functions

The BIF commands (BIFFilePath, BIFInfo, BIFRead, BIFWrite) are provided for backward compatibility only and will be removed from the language in a future release. Settings are now located in the Windows Registry and can be accessed with the new Registry commands in PerfectScript 7. Note that if a user is running an application from PerfectOffice 3.0 (including GroupWise, Notify, etc.), that BIFWrite calls will not work on the Public! and Private! BIFs because those BIFs are in use by an application.

enumeration := Cancel / Error / NotFound / VarErrChk ([State:enumeration])

These commands have been modified to return the previous state of the specified condition as well as set the new state. The new state is now optional, and if missing, then the previous state is still returned, but no new state is set. This allows the current state to be retrieved without changing it. The values returned are:

On! The condition was previously in the on state (enabled).

Off! The condition was previously in the off state (disabled).

DefaultUnits

DefaultUnits now returns the previous default units value as a return value. This allows the previous value to be saved, a new value to be set, and the previous value to be restored. The parameter for default units is also optional, so if no parameter is specified, then the current default units can be obtained while not changing it to something else. The return value is an enumeration with one of the following values:

None!, Centimeters!, Inches!, Millimeters!, Points!, or WPUnits!.

None! has been added to the enumeration list for the Units parameter. Normally, when a non-units value (such as 1200) is combined with a units value (such as 1.0C), the non-units value is assumed to be of the current default units type (specified by this command; initially starting with WPUnits!). It is then converted from the current default units to the units type of the units value it is being combined with, and then the combining operation is performed. This means that if the current default units is WPUnits, that 1.0C+1200 would be 3.54C, since 1200 is assumed to be WPUnits, and 1200 WPUints is 1 inch, which is 2.54C, added to 1.0C makes 3.54C. If the default units is set to None!, then the non-units value is assumed to be of the same units type as the units value it is being combined with, and no conversion is performed. In this case, 1.0C+1200 would be 1201.0C, since the 1200 is assumed to be of the same type as the 1.0C, which is C, so 1.0C+1200C = 1201.0C.

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.

Dialog names are now limited to 25 characters in both the Macro Dialog Editor and the text- based dialog statements

Dialog Sizing

In previous versions of Windows, specifying the dialog size included the caption and borders. In Windows 95, captions and borders can be sized by a user, so it doesn't make sense to specify dialog sizes that include these dimensions because such dialogs would not necessarily display correctly in another user's environment. So in PerfectScript 7, dialog sizes as specified in DialogDefine and in the Macro Dialog Editor do not include the space required for the caption and borders.

DialogAdd...

The DialogAdd... commands can now add controls to dialogs created with the Macro Dialog Editor.

DialogAddCounter

Now allows counters of various unit formats. They are:

DisplayNormal! - range is -2147483647 to 2147483647

DisplayWPU! - range is same as for DisplayNormal!

DisplayPercent! - range is same as for DisplayNormal!

DisplayPoints! - range is -4294967.0 to 4294966.0

DisplayInches! - range is -59651.0 to 59652.0

DisplayInches2! - range is same as for DisplayInches!

DisplayI_Inches! - range is same as for DisplayInches!

DisplayCentimeters! - range is -151518.0 to 151519.0

DisplayMillimeters! - range is -1515513.0 to 1515514.0

DisplayFixedPoint! - range is -32767.0 to 32767.0

If a min, max, step or initial value exceed any of these ranges then the min or max value is substituted in place of the out of range value.

When a value is entered with no unit of measure type attached to it (24 as opposed to 24i), the value entered is assumed to be of the same type as the counter type NOT THE DEFAULT UNITS TYPE.

DialogAddScrollBar (styles and behavior)

The Left!, Right!, Top!, and Bottom! styles only refer to the placement of the scroll control within the control window.

Vertical controls can be positioned in the control window on the:

LEFT VScroll! | Left! // left side of control window

RIGHT VScroll! | Right! // right side of control window

FULL VScroll! // full size of control window

Horizontal controls can be positioned in the control window on the:

TOP HScroll! | Top! // top side of control window

BOTTOM HScroll! | Bottom! // bottom side of control window

FULL HScroll! // full size of control window.

These styles (Left!, Right!, Top!, and Bottom!) do not refer to the placement of the thumb within the scroll control. By default, the thumb will be positioned at the minimum position of the scroll bar. This default position will be overridden by any value that is placed in the macro variable passed in to the DialogAddScrollBar command.

DialogDefine

The NoFrame! style on the DialogDefine statement will no longer work. In Win95, removing a frame also removes the caption bar. So to remain most compatible with previous releases, the NoFrame! style will still compile but will be non-functional.

DialogDismiss and DialogDestroy

When using a dialog that is of Macro Dialog Editor format (resides in the prefix area, and can be edited using the Macro Dialog Editor), if the dialog has no callback, the dialog is destroyed when the user pushes any button on the dialog. At that point, any subsequent calls referencing that dialog will result in an error. Consider the following macro:

DialogShow ("MDEDlg"; "PerfectScript")

DialogDismiss ("MDEDlg"; "OKBttn")

This macro will cause an error when the DialogDismiss token is processed because the macro system no longer knows anything about the dialog. The button push to close the dialog also ended and destroyed it. Consider the following macro which has a callback:

DialogShow ("D_1"; "PerfectScript"; CallHere)

DialogDismiss ("D_1"; "OKBttn")

DialogDestroy ("D_1")

Quit

Label (CallHere)

Return

DialogShow puts up the dialog, and the macro keeps executing macro instructions, so it would then be dismissed (hidden), and finally destroyed as a result of tokens being sent.

DialogShow

now accepts an optional fourth parameter to specify the control to receive initial focus. In addition, the parent parameter can now be used with old style dialogs to specify a parent for the dialog. For callback dialogs, a WM_INITDIALOG (value 272) is now sent on dialog creation in callback array [5].

DLLCall

Existing macros that use DLLCall must be rewritten to work in Windows 95. This is because DLLs and the APIs provided by those DLLs either do not exist or have been changed to work in the new 32-bit Windows 95.

ErrorNumber

ErrorNumber is now a programming command that returns the last error number. Users will not notice any difference in how ErrorNumber is used, and for now does not return any new information. This 'variable' as well as the other built in 'variables', should be documented in the same section as the commands (using the same notation and syntax) so that users can find them when looking in the documentation.

GetFileDateAndTime (Filename: string)

Returns a numeric value representing the date and time the file was last written to. The value is compatible with the value returned from the DateAndTime function and can be converted to a string by calling the DateString and TimeString functions. In previous releases this token returned the number of seconds since January 1, 1980, in a bit encoded format that was not documented.

Filename The name of the file.

GetFileAttributes

This command used to return a numeric value specifying the attributes of the specified file. This command now returns enumerated values to specify the attributes. The enumerations have the same values as the numerical values returned before. The 6.1 documentation essetially documented the return values are numerical values, but also listed enumerations for them too (though one of the values [Error!] was wrong). The enumerations returned (and their numerical values) are:

Error! = -1

Normal! = 0

ReadOnly! = 1

Hidden! = 2

System! = 4

Label! = 8

Directory! = 16

Archived! = 32

IfPlatform / EndIfPlatform

The platform ID for the macro system on Windows 95 is now "Win95!". The platform ID of "Win32!" is also accepted. The old value of "Win" is no longer recognized, and is reserved for 16-bit Windows 3.x.

MMPlay

now accepts an optional parameter called Options which allows you to specify one of the following:

DontWait! start playing and return immediately (this is the default and if the options parameter is not present, it will assume this default)

Wait! wait for the play to finish before proceeding to the next macro statement

The MMPlay token now returns a value. The value is a handle that can be passed to the new command MMStopPlay.

MMSpeak and MMSpeakClipboard

In PerfectOffice 3.0, there were three text-to-speech products supported. These were TextAssist, ProVoice, and Monologue. In this version of PerfectScript, the Lernout and Hauspie, the Centigram TruVoice, and the Creative TextAssist text-to-speech systems are supported.

label := OnCancel/OnCancel Call / OnError/OnError Call / OnNotFound/OnNotFound Call ([Label:label])

These commands have been modified to return the label that was previously associated with the specified condition (Cancel, Error or NotFound) as well as set the new label. If there was no label, then "" is returned. The label paramter is optional, and if missing, the label associated with this condition is cleared, resetting the condition handling back to its initial state.

PersistAll

The PersistAll command has been modified to accept an optional parameter to specify if the Persistent variable state should be turned on or off, and will now return the previous state of the that condition as well as set the new state. The new state is optional, and if missing, then the previous state is still returned, but no new state is set. This allows the current state to be retrieved without changing it. The values returned are:

On! PersistAll was previously in the on state (enabled).

Off! PersistAll was previously in the off state (disabled).

Prompt

The Icon parameter of the Prompt command is now an enumeration rather than a numeric and has been renamed Style. Enumerations have been defined for the previous numeric values to specify the icon types, and some new enumerations have been added to define additional style settings.

It now accepts a NoButtons! flag to show a prompt without OK or Cancel buttons. This is useful for displaying "Please Wait" messages. When using the NoButtons! flag, you should not use a Pause statement immediately following; rather you should use the EndPrompt method of removing the Prompt. For example:

Prompt ("Prompt with no buttons"; "Please wait for 10 seconds"; NoButtons!)

.... other things you do here

EndPrompt ()

The Prompt command also now accepts a Pause! flag, which will cause the Prompt command to pause until the OK button is pressed (the same as following the Prompt command with a Pause command).

The Beep! flag causes a beep to occur when the prompt is displayed. This is the same as following the Prompt command with a Beep command.

Region tokens (Region...) and user dialog commands (Dialog...) -- clarificiation on dependancy.

The Region... tokens, can NOT be used on a user dialog until that dialog has either been loaded using DialogLoad or shown with DialogShow. DialogLoad creates the dialog in memory but does not display it. DialogShow displays it.

One of the changes made when moving to Win95 was to just keep information about the dialog as it was being constructed. This information is not a dialog until a DialogLoad or DialogShow command, at which time the dialog and controls are actually created, have window handles, and become entities that can have named regions. Up to that point, named regions have no meaning, since there is no window to associate the name with.

The 16-bit, one-by-one window creation as the dialog was being described has been discontinued, in favor of storing information and creating the dialog all at once, which gives a performance gain. Another driving factor was the combining of the Macro Dialog Editor dialogs and the text based dialogs onto a single underlying functionality for consistency and performance.

RegionGetCheck

This command used to be a procedure that returned a numerical value indicating the checked state of the region to the output variable. This command is now a function that returns an enumeration to indicate the state. The enumerations returned have the same numerical values that were returned before. The enumerations (and their numerical values) returned are:

Up! = 0

Down! = 1

Checked! = 1

Unchecked! = 0

Indeterminate! = 2

RegionRemoveListItem

now removes an item with an exact match before it removes a partial match item

SetFileDateAndTime (Filename: string; DateAndTime: numeric)

Changes the date and time a file was last written to.

Filename The name of the file

DateAndTime A numeric value returned from a call to the DateAndTime function. In previous releases this parameter expected the number of seconds since January 1, 1980, in a bit encoded format that was not documented.

The return value is True for success, False otherwise.

StrPos and CharPos

The StrPos and CharPos commands now have a new trailing parameter, called 'Beginning', which indicates the character to start the search at. This parameter is optional, and defaults to 1, the beginning of the string (which is the same behavior as previoous versions).

New Commands and Language features

This section describes new commands and language features which have been added.

**, ^^ exponentiation operator

This operator raises the left operand to the power of the right operand. The precedence level of this operand is between level 1 (NOT, ~, unary +, unary -) and level 2 (*, /, %, DIV, MOD). For example, 2**3 is 8 (2 to the 3rd power).

\ root operator

This operator takes the right operand root of the left operand. The precedence level of this operand is between level 1 (NOT, ~, unary +, unary -) and level 2 (*, /, %, DIV, MOD). For example, 8 \ 3 is 2 (the 3rd root of 8).

:=: swap operator

This operator will swap the left and right operands. This operator is not currently implemented.

- string reduction operator

This operator removes the first occurance of the right string operand from the left string operand. If the right string does not occur within the left string, then the right string is returned unchanged. Just as + for strings returns adds 2 strings together like adding 2 numbers, - for strings removes a string from another like removing a number from another does for numbers. The precedence level of this operand is the same as - for numbers (new precedence level 3). For example, "abcbcdefghi" - "bc" is "abcdefghi" (the first "bc" string removed from "abcbcdefghi").

=,!=,<> equality and non-equality operators

This operator is now defined for arrays. Two arrays are equal, if they have the same number of dimensions, and all corresponding elements are equal. Two arrays are not equal if the dimensions are not equal, or if any corresponding elements are not equal (not if all are not equal, but if any single element is not equal to its corresponding element in the other array). The precedence level of these operators are still the same as they were. For example, {1;2;3} = {1;2;3} is TRUE, {1;2;3] = {1;3;2} is FALSE, {1;2;3} = {1;2;3;4} is FALSE, {1;2;3} != {1;2;4} is TRUE.

<<<,>>> rotate operators

These operators rotate the left operand by the number of bit positions specified by the right operand. Rotating is like shifting (<<, >>), except bits shifted out of a number are lost, but bits rotated out of a number are inserted at the other end. These operators, like the shift operators, can only function on integer numeric data types. The precedence level of these operators are the same as the precedence level of the shift operators (new precedence level 5).

IN membership operator

This operator returns a boolean value indicating whether the left operand is contained in the right operand. The right operand must always be an array, and the left operand may be a simple value, or may be an array. If the left operand is a simple value, then TRUE is returned if the left operand is equal to one of the elements of the right operand array. If the left operand is an array, then TRUE is returned is every element of the left operand array is equal to some element of the right operand array. The precedence level of this operand is the same as the relational operators (=, <>, !=, <, <=, >, >=) (new precedence level 6). For example, 3 IN {1;2;3} is TRUE, but 3 IN {1;2;4} is FALSE, {1;2;3} IN {1;2;3} is TRUE, {1;2;3} IN {1;2;3;4} is TRUE, but {1;2;3} in {1;2;4} is FALSE.

[0] array element count

This is not a command, but this is an access to the [0] element of an array. When a access to the [0] element of an array is made, the number of elements in the array is returned. This is the same value that is returned from the command Dimensions (array[ ]; 0). Note that only a single zero index is specified, regardless of the number of dimensions the array was declared with.

new reserved words

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.

IN, ...

multi-dimensional array literals:

a[ ] := {{{1;2}; {3;4}; {5;6}}; {{7;8}; {9;10}; {11;12}}}

a[ ] is a 2 x 3 x 2 array

expandable multi-dimensional array literals:

a[ ] := {{1;...}; {2;3;4}; {5;6;...}}

(The first ... expands (replicates) the value 1 to fill the first dimension (adds 2 more elements), and the second ... expands the value 6 (adds 1 more element) to create a 3 x 3 array.

numeric := AbsVal (Value:numeric)

Return the absolute value of a value

Value The value to return the absolute value of.

numeric := acos (Value:numeric)

Return the angle in radians for a specified cosine (inverse (arc) cosine)

Value The cosine to return the angle in radians for.

numeric := acosh (Value:numeric)

Return the angle in radians for a specified hyperbolic cosine (inverse (arc) hyperbolic cosine)

Value The hyperbolic cosine to return the angle in radians for.

AppClose (Window)

AppClose closes a running application by sending a WM_CLOSE message to the specified window.

Window can be either a string (possibly containing wildcards) or a window handle returned from AppLocate.

AppShow (Window; State)

AppShow changes the display characteristics of a running application or window.

Window can be either a string (possibly containing wildcards) or a window handle returned from AppLocate.

numeric := asin (Value:numeric)

Return the angle in radians for a specified sine (inverse (arc) sine)

Value The sine to return the angle in radians for.

numeric := asinh (Value:numeric)

Return the angle in radians for a specified hyperbolic sine (inverse (arc) hyperbolic sine)

Value The hyperbolic sine to return the angle in radians for.

numeric := atan (Value:numeric)

Return the angle in radians for a specified tangent (inverse (arc) tangent)

Value The tangent to return the angle in radians for.

numeric := atan2 (Value:numeric Value2:numeric)

Return the angle in radians for a tangent that is Value / Value2 (inverse (arc) tangent)

Value The numerator of the tangent to return the angle in radians for.

Value2 The denominator of the tangent to return the angle in radians for.

numeric := atanh (Value:numeric)

Return the angle in radians for a specified hyperbolic tangent (inverse (arc) hyperbolic tangent)

Value The hyperbolic tangent to return the angle in radians for.

numeric := Average ({Value:numeric})

Return the average value of a list of values

Value This is the list of values to determine the average of. This parameter may be repeated multiple times.

raw binary data := BinaryPack(Value:any; TotalSize:numeric or enumeration; [{Offset:enumeration or numeric; Type:enumeration; Size:enumeration or numeric}])

Pack data into a raw binary data form

Value The value to be packed into a raw binary form.

[TotalSize] The total size of the raw binary value to be produced. If missing or specified as Auto!, then the raw binary data will assume the size of all of its parts combined. This value is currently ignored, and should be ommitted.

{ The next 3 parameters form an optional repeating group. If 1 parameter in the group is specified, than all must be specified. The parameters of this repeating parameter group specify the attributes of the value to be packed into the raw binary data value. Multiple groups of these parameters may be specified, each describing one value to be packed. Currently, only 1 group is permitted.

[Offset] The beginning offset (starting at 0), within the raw binary data value to pack this Value into. This is the offset of the first byte of the data value. If this value is missing or specified as Auto!, then the next available offset (starting at 0) is used. Any gaps in the final raw binary data value may contain undefined data (garbage).

[Type] The type that Value is to be packed into. If missing, Auto! is used.

Auto! or Detect! The actual data type of the Value parameter is used.

Byte! Pack the value into a byte (1..n bytes [1]).

Word! Pack the value into a word (2 bytes [2]).

DWord! Pack the value into a double word (4 bytes [4]).

Real! Pack the value into a 'C' double (8 bytes [8]).

Integer! Pack the value into a 'C' long (1, 2, 4 bytes [4]).

Boolean! Pack the value into a Windows BOOL (1, 2, 4 bytes [4]).

WPString! Pack the value into a WordPerfect string (2 byte characters [length+1]).

AnsiString! Pack the value into an ANSI string (1 byte characters [length+1]).

HexString! Pack the value into direct binary data from a string of hex characters (1 byte characters [length]).

[Size] The size in bytes that the raw binary form of this value should occupy. If missing or specified as Auto!, the default size of the Type is used (shown above in [ ]). For types Word!, DWord! and Real!, the size must agree with the default size for that type.

For Integer! and Boolean!, sizes of 1, 2 or 4 may be specified.

For Byte!, any size may be specified, which will repeat the specified byte that many times.

For WPString! and AnsiString!, the length of the string (plus 1 for the NULL termination) is used (WPStrings consist of 2 byte characters). If the size is larger than the string value, then the excess bytes are zero filled.

For HexString!, each pair of 2 characters in the string value are converted to a binary byte and packed into the result. If Size is shorter, then only that many bytes are packed. If Size is longer, then the excess bytes are zero filled.

}

any (numeric, string, ..., array) := BinaryUnPack (Value:raw binary data; {Offset:numeric or enumeration; Type:enumeration; Size:numeric or enumeration})

UnPack data from a raw binary data value

return-value The return value in the value that is unpacked. If there is more than one set of repeating parameters, then an array of values is returned, one value for each repeating group.

Value The raw binary value that a value is to be unpacked from.

{ The next 3 parameters form a repeating group. If 1 parameter in the group is specified, than all must be specified, and at least one group must be specified. The parameters of this repeating parameter group specify the attributes of the value to be unpacked from the raw binary data value. Multiple groups of th