Xbase++ - Function DbRegisterClient()

Registers an object to receive messages from a work area.

DbRegisterClient( <object> ) --> lSuccess

The parameter <object> is the object to register to receive messages from the current work area.

The return value of DbRegisterClient() is .T. (true) when the object could be registered in the current work area, otherwise it is .F. (false).

The function DbRegisterClient() synchronizes a database engine (DBE) and an object. When a file is opened via USE or DbUseArea(), a database object (DBO) is created based on the current DBE. The DBO manages the files in the work area, and represents the work area.

In a GUI application, Xbase Parts are used to represent the data stored in a file (field variables). A dialog window is generally used along with XbpSLE objects to display data from a work area on the screen. Using DbRegisterClient(), the objects that display data from a work area are registered with the work area (to be precise: with the database object which manages the work area).

Only objects that support the :notify() method can be registered. A database object calls the :notify() method of all registered objects before and after performing database operations.

When an object is registered in a work area (DBO), it automatically receives messages about database operations performed in the work area. Such messages are especially significant in programming GUI applications where multiple windows can simultaneously display or manage data from a single database. When a database operation occurs in a work area, the xbeDBO_Notify event is generated and all registered objects are sequentially notified. The objects must support the method :notify().

The method :notify() must be redefined by the programmer as new classes are derived from existing ones. An example for this method can be found in the program ..\SOURCE\SAMPLES\APPS\MDIDEMO\DATADLG.PRG.

When the function AppEvent() returns the event code xbeDBO_Notify, a numeric value identifying a database operation is in the first message parameter mp1. Constants are defined in the DMLB.CH file for the possible values. These are listed in the following table:

Constant	Description
DBO_CLOSE_REQUEST	File in work area will be closed
DBO_BULK_REQUEST	Time consuming database operation begins
DBO_BULK_COMPLETE	Time consuming database operation ends
DBO_CHANGE_ORDER	Order of records changed (logical or physical order)
DBO_TABLE_UPDATE	Data in current record modified
DBO_TABLE_DELETED	Record deleted
DBO_TABLE_APPEND	New record created
DBO_MOVE_PROLOG	Record pointer will be moved
DBO_MOVE_DONE	Movement of record pointer ends
DBO_GOTOP	Record pointer set to beginning of file
DBO_GOBOTTOM	Record pointer set to the end of file

When one of the database operations listed in this table is performed in the work area, the DBO calls the :notify() method of all registered objects and passes the appropriate message to it.

Register objects in a database engine


// This program illustrates the effect of DbRegisterClient() 
// based on the DbGet class which is derived from the Get 
// class and includes the method :notify() in the example. 
// For programming using DbGet objects, two directives are 
// shown which reproduce the @...GET and the READ command 
// for DbGet objects. The Main procedure is the actual test 
// program. The F6 and F7 keys are associated with code blocks 
// that move the record pointer. The DbGet objects are updated 
// after each skip based on the :notify() method. 

#include "Dmlb.ch" 
#include "AppEvent.ch" 

* Simplified GET command for DbGet objects 
#command  @ <nRow>, <nCol> DBGET <Var> ; 
      =>  aadd( getList, DbGet():new( <nRow>, <nCol>, ; 
                         anchorCB(@<Var>) ):display() ) 

* READ Command for DbGet objects 
#command  DBREAD ; 
      =>  DbRegisterClient( GetList\[1] ) ;; 
          ReadModal( GetList ) ;; 
          DbDeRegisterClient( GetList\[1] ) ;; 
          GetList := {} 

******************************************************************** 
* Get class for database fields -> with Notify method 
******************************************************************** 
CLASS DbGet FROM Get 
   EXPORTED: 
   METHOD notify 
ENDCLASS 

******************************************************************** 
* Notify method: redisplay GetList when record pointer is moved 
******************************************************************** 
METHOD DbGet:notify( nEvent, mp1, mp2 ) 

   IF nEvent == xbeDBO_Notify             // Notify event 
      IF mp1 == DBO_MOVE_DONE             // skip has ended 
         AEval( GetList(), ;              // current GetList 
                 {|oGet| ;                // DbGet object 
                   oGet:varGet(), ;       // read field 
                   oGet:updateBuffer()} ) // update edit buffer 
      ENDIF 
   ENDIF 
RETURN 

******************************************************************** 
* Example for DbGet objects 
******************************************************************** 
PROCEDURE Main 
   LOCAL GetList := {} 

   CLS 
   USE Customer EXCLUSIVE 

   SetMouse( .T. ) 

   @ 24, 2     SAY  "<F6> = Forward  " 
   @ 24, Col() SAY  "<F7> = Back" 
   SetAppEvent( xbeK_F6, {|| DbSkip( 1 )} )  // skip during 
   SetAppEvent( xbeK_F7, {|| DbSkip(-1 )} )  // READ 

   @ 10,10 DBGET Customer->FName 
   @ 12,10 DBGET Customer->LName 
   DBREAD 

   CLOSE Customer 
RETURN

Function DbRegisterClient() Foundation