Function DbRegisterClient() Foundation
Registers an object to receive messages from a work area.
DbRegisterClient( <object> ) --> lSuccess
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().
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.
// 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
If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.