The Message object is a predefined PowerBuilder global object (like the default Transaction object SQLCA and the Error object) that is used in scripts to process Microsoft Windows events that are not PowerBuilder-defined events.
When a Microsoft Windows event occurs that is not a PowerBuilder-defined event, PowerBuilder populates the Message object with information about the event.
Other uses of the Message object
The Message object is also used:
-
To communicate parameters between windows when you open and close them
For more information, see the descriptions of OpenWithParm, OpenSheetWithParm, and CloseWithReturn in the section called “OpenWithParm” in PowerScript Reference, the section called “OpenSheetWithParm” in PowerScript Reference, and the section called “CloseWithReturn” in PowerScript Reference.
-
To pass information to an event if optional parameters were used in TriggerEvent or PostEvent
For more information, see the section called “TriggerEvent” in PowerScript Reference and the section called “PostEvent” in PowerScript Reference.
Customizing the Message object
You can customize the global Message object used in your application by defining a standard class user object inherited from the built-in Message object. In the user object, you can add additional properties (instance variables) and functions. You then populate the user-defined properties and call the functions as needed in your application.
For more information about defining standard class user objects, see the section called “Building a standard class user object” in Users Guide.
The first four properties of the Message object correspond to the first four properties of the Microsoft Windows message structure.
|
Property |
Datatype |
Use |
|---|---|---|
|
Handle |
Integer |
The handle of the window or control. |
|
Number |
Integer |
The number that identifies the event (this number comes from Windows). |
|
WordParm |
UnsignedInt |
The word parameter for the event (this parameter comes from Windows). The parameter's value and meaning are determined by the event. |
|
LongParm |
Long |
The long parameter for the event (this number comes from Windows). The parameter's value and meaning are determined by the event. |
|
DoubleParm |
Double |
A numeric or numeric variable. |
|
StringParm |
String |
A string or string variable. |
|
PowerObjectParm |
PowerObject |
Any PowerBuilder object type including structures. |
|
Processed |
Boolean |
A boolean value set in the script for the user-defined event:
|
|
ReturnValue |
Long |
The value you want returned to Windows when Message.Processed is TRUE. When Message.Processed is FALSE, this attribute is ignored. |
Use the values in the Message object in the event script that caused the Message object to be populated. For example, suppose the FileExists event contains the following script. OpenWithParm displays a response window that asks the user if it is OK to overwrite the file. The return value from FileExists determines whether the file is saved:
OpenWithParm( w_question, & "The specified file already exists. " + & "Do you want to overwrite it?" ) IF Message.StringParm = "Yes" THEN RETURN 0 // File is saved ELSE RETURN -1 // Saving is canceled END IF
For information on Microsoft message numbers and parameters, see the Microsoft Software Developer's Kit (SDK) documentation.
