Causing an Object Event

Use the Object class causeEvent method to trigger a user event, the sdeCauseEvent method for inter-system event notification in a Synchronized Database Environment (SDE), or the sdsCauseEvent method for inter-system event notification in a Synchronized Database System (SDS).

The sdeCauseEvent method combines the actions of the causeEvent and sdsCauseEvent methods, in that subscribers are notified of user events on the local system as well as on SDS secondary or primary systems, where applicable. In contrast, the causeEvent method would notify subscribers of a user event only on the primary database system and the sdsCauseEvent method only on the secondary database systems.

A corresponding notification is received by any objects that have registered an interest in the notification by using a begin notification method for that object or its class. (For more details, see "causeEvent", "sdeCauseEvent", or "sdsCauseEvent" under "Object Class", in Chapter 1 of the JADE Encyclopaedia of Classes.)

The parameters for the causeEvent method are listed in the following table.

Parameter	Description
eventType	Integer in the range User_Base_Event through User_Max_Event that represents the event being caused; that is, a number in the range 16 through User_Max_Event.
immediate	Boolean value specifying the timing of the event; false indicates that notifications occur at the end of transaction and true indicates that the notification is sent immediately. If the client is not within a begin/commit transaction cycle and this parameter is set to false, the notification waits for the next commit on that client.
userInfo	A value of any primitive type value (for example, a String or an Integer) or persistent object reference that is passed to the userNotification or userNotify event handlers when the event is notified. (Notifications containing binary and string (Binary, String, StringUtf8) data of up to 48K bytes can be sent across the network. For applications running within the server node, the limit for notifications containing binary or string data is 2G bytes. Note, however, that this applies only to single user and server applications. In multiuser applications, persistent notifications are sent via the database server, even if the receiving process is on the same node as the sender. In notification cause events, exception 1267 (Notification info object too big) is raised if the binary or string userInfo data exceeds the applicable value.)
	Although you should not use a transient object reference across nodes, you can use a shared transient object reference between applications on the same node.

The following example shows the use of the causeEvent method to set off a user notification for the b1 instance of the B class. The notification is given an event type of User_Base_Event to identify it, and the userInfo parameter is passed the contents of a text box. The userInfo parameter is passed into the userNotify event when the notification is received.

bttnClassUserEvnt_click(btn: Button input) updating;
begin
    b1.causeEvent(User_Base_Event, true, textBox5.text);
end;

The following example shows the use of the causeEvent method to set off a user notification for the c2 instance of the C class. The notification is given an event type of 17 to identify it, and the userInfo parameter is passed the contents of a text box. The userInfo parameter is passed into the userNotify event when the notification is received.

bttnUserEvnt_click(btn: Button input) updating;
begin
    c2.causeEvent(17, true, textBox6.text);
end;

The following example shows the use of the causeEvent method to reduce the price of shares for a company by 10 percent.

discountPrice() updating;
begin
    self.priorPrice := currentPrice;
    // don’t reduce the price below 20 cents
    if currentPrice > 0.20 then
        self.currentPrice := currentPrice * .90;
    endif;
    causeEvent(Price_Change, false, 0);
end;

The following example shows the use of the causeEvent method to notify other applications in the current node that this application is closing down.

finalize() updating;
begin
    endNotificationForSubscriber(self);
    myInterProcessCommunication.causeEvent(Application_Closing_Down,
                                           true, 0);
    // myInterProcessCommunication is a shared transient object used
    // to communicate with all applications in the node
end;

The behavior of the sdsCauseEvent method is database role-dependent. The three database role categories are listed in the following table.

Role	Action
Primary	When invoked within an SDS primary system, the sdsCauseEvent method audits the event for subsequent replay by SDS secondary databases. The event is not notified on the primary. The value of the immediate parameter must be false.
Secondary	When invoked within an SDS secondary system connected to a primary database server, the sdsCauseEvent method triggers a corresponding event on the same receiver object in the primary system. The user event is not notified on the secondary system. Events caused on a secondary are assumed to be immediate, so the immediate parameter is therefore ignored.
None	When invoked within a non-SDS-capable system (that is, the role is undefined), the method behavior is the same as the Object::causeEvent method.

The parameters for the sdsCauseEvent method are listed in the following table.

Parameter	Description
eventType	Integer in the range User_Base_Event through User_Max_Event that represents the event being caused; that is, a number in the range 16 through User_Max_Event.
immediate	You must set this parameter to false when the method is invoked from a primary system in a Synchronized Database Environment (SDE).
userInfo	A value of any primitive type value (for example, a String or an Integer) or persistent object reference that is passed to the userNotification or userNotify event handlers when the event is notified. (Notifications containing string and binary data of up to 48K bytes can be sent across the network.)

The parameters for the sdeCauseEvent method are listed in the following table.

Parameter	Description
eventType	Integer in the range User_Base_Event through User_Max_Event that represents the event being caused.
immediate	Boolean value specifying the timing of the event; false indicates that notifications occur at the end of transaction and true indicates that the notification is sent immediately. If the client is not within a begin/commit transaction cycle and this parameter is set to false, the notification waits for the next commit on that client.
	On a primary database, subscribers are notified only on the secondaries if the target object is persistent, the value of the immediate parameter is false, and the process is currently in transaction state. On a secondary database system, subscribers are notified on the primary database system only if the target object is persistent. The value of the immediate parameter is immaterial. However, subscribers are always notified immediately on the primary database system, even when the value of the immediate parameter is false, to defer notification on the secondary system.
userInfo	A value of any primitive type value (for example, a String or an Integer) or persistent object reference that is passed to the userNotification or userNotify event handlers when the event is notified. (Notifications containing string and binary data of up to 48K bytes can be sent across the network.)

For more details about inter-system communications in an SDE, see "Inter-System Event Notifications", in Chapter 10.