active

Topic group Related topics

Specifies whether an object is open and active or closed.

Property of

Database, DataModRef, Query, StoredProc

Description

When created, a new session’s default database is active since it does not require any setup. Other Database, DataModRef, Query, and StoredProc objects do require setup, so their active property defaults to false. Once they have been set up, set their active property to true to open the object and make it active.

When a Query or StoredProc object’s active property is set to true, its canOpen event is called. If there is no canOpen event handler, or the event handler returns true, the object is activated. In a Query object, the SQL statement in its sql property is executed; in a StoredProc object, the stored procedure named in its procedureName property is called. Then the object’s onOpen event is fired.

To close the object, set its active property to false. Closing an object closes all objects below it in the class hierarchy. Attempting to close a Query or StoredProc object calls its canClose event. If there is no canClose event handler, or the event handler returns true, the object is closed. Closing a Database object closes all its Query and StoredProc objects. After the objects are closed, all the Query and StoredProc objects’ onClose events are fired.

Activating and deactivating an object implicitly calls a number of advanced methods. You may override or completely redefine these methods for custom data classes; in typical usage, don’t touch them. When you set active to true (methods associated with a Database object will not function properly when the database is not active), a Database object’s open( ) method is called; activating a query or stored procedure calls prepare( ), then execute( ). When you set active to false, a Database object’s close( ) method is called; deactivating a query or stored procedure calls its unprepare( ) method. These methods are called as part of the activation or deactivation of the object, before the onOpen or onClose event.

Closing a query or a StoredProc object that generated a rowset attempts to write any changes to its rowset’s current row buffer, and to apply all cached updates or commit all logged changes. To circumvent this, you must call the abandon( ), abandonUpdates( ), and/or rollback( ) before the object’s onClose event—for example, during the canClose event or before setting the active property to false—because onClose fires after the object has already closed.

Once an object has been closed, you may change its properties if desired and reopen it by setting its active property back to true.