Chapter 11: Ma to Mo

Chapter 11

Corel® PerfectScript™ Programming Commands

Corel® PerfectScript™ 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.

MacroArgs[ ]

Purpose

An array variable that contains parameter arguments passed to it by Chain, Nest, or Run, or on the command line with the /m- option.

// Macro: MAIN.WCM
// Include the full path if the macro is not in the default
// macros directory
RUN("TSTMACRO"; {"x"; "y"; "z"})

// Macro: TSTMACRO.WCM
// Compile, then play MAIN.WCM
vElements := DIMENSIONS(MacroArgs[ ]; 0)
IF(vElements != 0)
 FORNEXT(x; 1; vElements; 1)
  MESSAGEBOX(z; "Element Values"; "MacroArgs[" + x + "] = " + MacroArgs[x])
 ENDFOR
ELSE
 BEEP
 MESSAGEBOX(z; "Error"; "No values passed"; IconExclamation!)
ENDIF

Result: x y z

Syntax

any := MacroArgs[<Index> numeric]

MacroDialogResult

Purpose	MacroDialogResult is a predefined macro variable that is updated to reflect the status of the Dialog commands. These commands are functions that mostly return the same value placed into MacroDialogResult. The list of commands below are followed by the values placed into MacroDialogResult if successful or if not successful. Command Name: successful / not successful DialogDefine: dialog name / empty string ("") DialogDestroy: True / False DialogShow (callback dialog): dialog handle / 0 DialogShow (non-callback): control name / empty string ("") The return value for this command is different when the control is the OK or Cancel control. MacroDialogResult returns "1" for OK, and "2" for Cancel. This command returns "OKBttn" and "CancelBttn". DialogDisplay: True / False DialogDismiss: control name / empty string ("") See the description of the non-callback DialogShow command above. DialogUndisplay: True / False DialogHandle: dialog handle / 0 DialogLoad: dialog handle / 0 DialogSave: True / False DialogDelete: True / False DoesDialogExist: True / False DialogSetProperties: True/ False DialogControlUpdate: True/ False DialogControlQuery: True / False DialogAddListItem: item index / -1 All the following commands return the control name if successful, an empty string ("") if not: DialogAddBitmap DialogAddCheckBox DialogAddColorWheel DialogAddComboBox DialogAddControl DialogAddCounter DialogAddDate DialogAddEditBox DialogAddFileNameBox DialogAddFrame DialogAddGroupBox DialogAddHLine DialogAddHotSpot DialogAddIcon DialogAddListBox DialogAddPopupButton DialogAddProgress DialogAddPushButton DialogAddRadioButton DialogAddScrollBar DialogAddText DialogAddViewer DialogAddVLine

Syntax	string := MacroDialogResult

MacroInfo

Purpose

Return information about the system, the state of a macro, or a label or routine within a macro.

Return Value

any depending on the information requested. For example, string if the platform name is requested, or numeric if the platform version is requested.

Discussion

The macro system keeps track of called labels and routines, the data that is specific to each one, and the call depth of each one. If the main section of a macro calls label "A" which calls procedure "B" which calls function "C", the following is true:

Call depth is 2 (call depth is 0 when the macro starts), and the data for A, B, and C is maintained by the macro system. The current label/routine is C. If data for C is needed, specify CallLevel as Current!. If data for B is needed, specify CallLevel as Previous! (B was the routine that called C). If data for A is needed, specify CallLevel as Previous! + 1. Whenever data is needed for a routine before Previous!, specify CallLevel as Previous! + 1, Previous + 2, and so forth.

You may also specify a numeric value for CallLevel parameters, which simplifies getting data on all active label or routine calls using a For loop. For example, specify Current! as Previous! as 3, and so forth. Start the loop at 0, and use MacroInfo (CallDepth!) to end the loop at the call depth return value.

Syntax

any := MacroInfo

(InfoItem: enumeration; [CallLevel: enumeration or numeric]; {[ItemData: any]})

Parameters

InfoItem	enumeration	Specify an InfoItem (the data type returned is in italics).
	System Information:
	ComputerName!	string	Named assigned to the computer.
	UserName!	string	Name of currently logged in user.
	WindowsDirectory!	string	Windows directory path.
	SystemDirectory!	string	Windows System directory path.
	PlatformName!	string	Name of the current platform. Currently the platform names that are returned are: "Win32s" for Windows 3.1 with Win32s "Win95" for Windows 95 "WinNT" for Windows NT
	PlatformVersion!	numeric	Version of the platform.
	PlatformVersionString!	string	Version of the platform.
	PerfectFitVersion!	numeric	Version of PerfectFit.
	PerfectFitVersionString!	string	Version of PerfectFit.
	PerfectScriptVersion!	numeric	Version of PerfectScript.
	PerfectScriptVersionString!	string	Version of PerfectScript.
	PerfectScriptLanguageCode!	string	Language code of PerfectScript.
	PerfectScriptLanguageName!	string	Language name of PerfectScript.
	Macro Information:
	DialogsExist!	boolean	Do macro dialogs exist.
	BreakpointsExist!	boolean	Do macro break points exist.
	ErrorNumber!	numeric	ERRORNUMBER value.
	ErrorText!	string	Additional error text associated with the last error.
	AbortingTokenName!	string	Name of the product command token (if any) that caused the last error.
	MacroDialogResult!	any	Same as MacroDialogResult.
	MacroArgs!	array	MacroArgs[] array.
	CallDepth!	numeric	The current call depth: 0 = main.
	Label or Routine Information:
	InRoutine!	boolean	Are you in a routine (or label).
	InCallback!	boolean	Is this a callback.
	InAssert!	boolean	Is this an Assert call.
	FileName!	string	File the routine is in.
	LineNumber!	numeric	Source line number.
	LabelOrRoutineName!	label	Label or routine name.
	SourceLine!	string	Source line if available for the specified CallLevel (source is available for macros compiled with debug).
	ChainFileName!	string	Name of any Chain file.
	ChainFileArgs!	array	Arguments to any Chain file.
	DefaultUnits!	numeric	Default units type.
	PersistAllOn!	boolean	State of PersistAll.
	VarErrChkOn!	boolean	State of VarErrChkOn.
	CancelOn!	boolean	State of Cancel condition.
	CancelSetup!	boolean	Does Cancel condition have an associated label.
	CancelCall!	boolean	Will Cancel call or goto an associated label.
	CancelHandler!	label	Label of the cancel handler.
	ExitOn!	boolean	Return the exit handler state. Equivalent to ExitHandlerState() = ExitHandlerState.On!
	ExitSetup!	boolean	Return whether an exit hanlder has been established. Equivalent to the statement OnExit() != ""
	ExitCall!	boolean	Return True if an exit handler has been established.
	ExitHandler!	label	Return the label of the established exit handler. Equivalent to OnExit()
	ErrorOn!	boolean	State of Error condition.
	ErrorSetup!	boolean	Does Error condition have an associated label.
	ErrorCall!	boolean	Will Error call or goto an associated label.
	ErrorHandler!	label	Label of the error handler.
	NotFoundOn!	boolean	State of NotFound condition.
	NotFoundSetup!	boolean	Does NotFound condition have an associated label.
	NotFoundCall!	boolean	Will NotFound call or goto an associated label.
	NotFoundHandler!	label	Label of the NotFound handler.
	UserDefinedConditonOn!	boolean	Is a user- defined condition on.
	UserDefinedConditionSetup!	boolean	Does a user-defined condition have an associated label.
	UserDefinedConditionCall!	boolean	Will UserDefinedCondition call or goto an associated label.
	UserDefinedConditionHandler!	label	Label of the UserDefined condition.
CallLevel	enumeration or numeric	(optional) Used by some InfoItem types; specifies the label or routine call data is requested for. See Discussion above. Default: Current!
	Current!
	Previous!
ItemData	any	(optional/repeating) Used by some InfoItem types; specifies additional data needed by the specified item. For example, UserDefinedCondition types require the user-defined condition number for which to return information. See OnCondition for specifying a user-defined condition number.

MantissaPart

Purpose

Get the mantissa portion of a numeric value.

vMntsa := MantissaPart(3.2e18)

Result: vMntsa = 3.2

Return Value

Mantissa portioin of a numeric value.

Syntax

numeric := MantissaPart

(Value: numeric)

Parameters

Value

numeric

A fractional number (return the mantissa part of).

Max

Purpose

Get the maximum value of a list of values.

Return Value

Maximum value of a list of values.

Syntax

numeric := Max

({Value: numeric; ...})

Parameters

Value

numeric

The list of values. Separate multiple values with a semicolon.

Menu

Purpose

Display a menu of user-defined items.

Menu is used with statements such as Case, Case Call, and If to execute a statement that corresponds to a selected menu item. To dismiss a menu, press Alt or Esc.

Examples

Appendix A: 8002

Syntax

Menu	(<MenuPick> variable; <MnemonicType> enumeration; [<HorizontalPosition> numeric]; [<VerticalPosition> numeric]; {<MenuChoice> string; ...})

Parameters

<MenuPick>	variable	A number is returned in this variable, whether numbers or letters are used to reference menu items (see the MenuType parameter). For numbers, the range is 1 to 9. For letters, the range is 1 to 26. A returns 1, B returns 2, and so forth. 0 is returned if Alt or Esc is pressed.
<MnemonicType>	enumeration	Determine whether a letter or number is displayed to the left of a menu item.
	Digit!	Numbers (1-9)
	Letter!	Alphabetic characters (A-Z)
<HorizontalPosition>	numeric	(optional) The number of pixels from the left side of the main window to the left side of the menu. To center the menu horizontally, leave this parameter blank.
<VerticalPosition>	numeric	(optional) The number of pixels from the top of the main window to the top of the menu. To center the menu vertically, leave this parameter blank.
{<MenuChoice>}	string	The menu item text. You may list up to 9 menu items referenced by numbers, or up to 26 referenced by letters. Enclose menu items in braces ({}) separated by a semicolon. Menu(vSelection; Letter!; 50; 50; {"Option 1"; "Option 2"; "Option 3"}) To select an item: click it, select it with Tab and press Enter, or press the corresponding letter or number.

MenuList

Purpose

Display a menu of user-defined items.

This command is included for DOS compatibility. The Windows equivalent is Menu.

MenuList is used with statements such as Case, Case Call, and If to execute a statement that corresponds to a selected menu item. To dismiss a menu, press Alt or Esc.

Examples

Appendix A: 8002

Syntax

MenuList

(<VariableName> variable; {<MenuChoice> string; ...}; [<Title> string]; [<HorizontalPosition> numeric]; [<VerticalPosition> numeric])

Parameters

<VariableName>	variable	A number is returned in this variable, whether numbers or letters are used to reference menu items (see the MenuChoice parameter). For numbers, the range is 1 to 9. For letters, the range is 1 to 26. A returns 1, B returns 2, and so forth. 0 is returned if Alt or Esc is pressed.
{<MenuChoice>}	string	The menu item text, enclosed in braces ({}) and separated by a semicolon. MenuList(vSelection; {"Option 1"; "Option 2"; "Option 3"}; "Title") To select an item: click it, select it with Tab and press Enter, or press the corresponding letter or number. Nine items or less are displayed with a number to the left of the menu item. More than nine are displayed with a letter. The range is 1 to 26.
<Title>	string	The text displayed in the title bar.
<HorizontalPosition>	numeric	(optional) The number of pixels from the left side of the main window to the left side of the menu. To center the menu horizontally, leave this parameter blank.
<VerticalPosition>	numeric	(optional) The number of pixels from the top of the main window to the top of the menu. To center the menu vertically, leave this parameter blank.

MessageBox

Purpose

Display a message box.

Provide a limited set of buttons and icons, and an option to include up to 10 different parameter strings in the message.

Examples Appendix A: 8011

Return Value The control value of the button that dismisses the message box is returned in this variable. The return button values are:

Error!

OKButton!

CancelButton!

AbortButton!

RetryButton!

IgnoreButton!

YesButton!

NoButton!

If there is not enough memory to create the message box, 0 is returned.

Syntax

enumeration := MessageBox

([Status: variable]; [Caption: string]; Message: string; [Style: enumeration]; {[ParameterData: string]})

Parameters

Status	variable	(optional) The control value of the button that dismisses the message box (see Return Value above). The semicolon is still required if not used.
Caption	string	(optional) The title bar text. Default: "PerfectScript"
Message	string	The message box text. Icons appear to the left of the message. Control buttons are centered below the message. If HasParameters! style is used, a caret (^) followed by a number inserts the corresponding ParameterData message in its place (see the ParameterData parameter below). Use two carets (^^) to insert a caret as part of the message string. Use NToC(0F90Ah) to insert a hard return code in the message string. For example, MessageBox(vAns; "Title"; "First line" + NToC(0F90Ah) + "Second line"; IconInformation!) creates two lines above the control button. The next example creates three lines, including one blank line: HdReturn = NToC(0F90Ah) MessageBox(vAns; "Title"; "First line" + HdReturn + HdReturn + "Second line"; IconInformation!)
Style	enumeration	(optional) The message box styles. Type \| between enumerations to combine styles. Select only one style from each group	Default: OK! \| IconNone! \| DefButton1!
	Button enumerations are:
	AbortRetryIgnore!	(Abort, Retry, and Ignore)
	OK!	(OK - default if no button is specified)
	OKCancel!	(OK and Cancel)
	RetryCancel!	(Retry and Cancel)
	YesNo!	(Yes and No)
	YesNoCancel!	(Yes, No, and Cancel)
	Icon enumerations are:
	IconNone!	(No icon (default if no icon is specified))
	IconAsterisk!	(Lowercase "i" in a blue circle)
	IconExclamation!	(Exclamation point in a yellow circle)
	IconHand!	(Stop sign in a red circle)
	IconInformation!	(Lowercase "i" in a blue circle)
	IconWarning!	(Exclamation point in a yellow circle)
	IconError!	(Stop sign in a red circle)
	IconQuestion!	(Question mark in a green circle)
	IconStop!	(Stop sign in a red circle)
	Default button enumerations are:
	DefButton1!
	DefButton2!
	DefButton3!
	Modality enumerations are:
	ApplicationModal!	(You can switch to another application, but you must dismiss the message box (click a control button) before the macro resumes. ApplicationModal! is the default if either SystemModal! or TaskModal! is not specified.)
	SystemModal!	(You must dismiss the message box before the macro resumes, and before you can switch to another application.)
	TaskModal!	(You can switch to another application, but you must dismiss the message box (click a control button) before the macro resumes.)
	Miscellaneous enumerations are:
	Beep!	(Beep when the message box is displayed.)
	HasParameters!	(Notifies MessageBox box that a caret (^) followed by a number in the Message parameter is to be replaced by the corresponding character string in the ParameterData parameter.)
{ParameterData}	string	(optional) The text for the Message parameter (numbering begins with 0). Up to 10 parameters separated by semicolons are allowed. For example, `v0 := "Yes to continue, or" v1 := "No to quit." MessageBox(x; "Title"; "Select ^0 ^1"; YesNo! \| IconStop! \| HasParameters!; {v0; v1})` fills the Message parameter with "Select Yes to continue, or No to quit." If HasParameters! is not used, Message contains "Select ^0 ^1". If not specified, no parameters are substituted into Message.

Min

Purpose

Get the minimum value of a list of values.

Return Value

Minimum value of a list of values.

Syntax

numeric := Min

({Value: numeric; ...})

Parameters

Value

numeric

The list of values. Separate multiple values with a semicolon.

MMPlay

Purpose

Play a sound file.

Play a audio (WAV) file, an Audio-Visual Interleave (AVI) movie file, or a Musical Instrument Digital Interface (MIDI) file, or speaks an ASCII text file (see MMSpeak). Speech requires text-to-speech drivers like those shipped with some sound boards. Audio and MIDI files require the appropriate sound card.

Examples

Appendix A: 8025

Return Value

A handle that can be passed to MMStopPlay.

Syntax

numeric := MMPlay

(Filename: string; [Options: enumeration])

Parameters

Filename	string	The path and name of a sound file. The appropriate driver for each file type must be installed.
Options	enumeration	(optional) Default: DontWait!
	DontWait!	Start playing and go immediately to the next macro statement (has no effect on some systems).
	Wait!	Start playing and wait for play to finish before going to the next macro statement.

MMSpeak

Purpose

Speak an ASCII file or ASCII text.

Examples

Appendix A: 8026

Syntax

MMSpeak

(String: string)

Parameters

String

string

The path and name of an ASCII file, or a string, or a variable containing a string. A text-to-speech driver must be installed in the Windows System directory. Products supported are: Lernout and Hauspie, Centigram TruVoice, and CreativeTextAssist (SoundBlaster).

MMSpeakClipboard

Purpose	Speak text saved to the Clipboard. A text-to-speech driver must be installed. Products supported are: Lernout and Hauspie, Centigram TruVoice, and the Creative TextAssist.

Examples	Appendix A: 8026

Syntax	MMSpeakClipboard ()

MMStopPlay

Purpose

Stop a multimedia file started with MMPlay, with the DontWait! option set. With the Wait! option set, MMStopPlay has no effect.

Syntax

MMStopPlay

(Handle: numeric)

Parameters

Handle

numeric

Returned by MMPlay.

MMStopSpeech

Purpose	Stop a speech (text) file started with MMPlay (ASCII file), MMSpeak, or MMSpeakClipboard. After a text file begins to speak, control immediately returns to the macro. Use MMStopSpeech to stop speaking a text file.

Examples	Appendix A: 8026

Syntax	MMStopSpeech ()

MOD

Purpose	Operator. Precedence level 3. See Arithmetic Operators in Chapter 4: Expressions.

Return Value	Return the integer remainder of the quotient of two numbers.

Syntax	numeric := numeric MOD numeric