The Message object

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:

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.

Message object properties

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:

  • TRUE -- The script processed the event. Do not call the default window Proc (DefWindowProc) after the event has been processed.

  • FALSE -- (Default) Call DefWindowProc after the event has been processed.

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.