Application development > Using callbacks

Sometimes an application needs to be notified of a specific type of database engine event in order to complete an operation or to provide the user with information. The advantage of using callbacks is that BDE can get a user's response without interrupting the normal application process flow.

The following rules must be strictly followed in a callback function:

•No other BDE calls can be made inside the callback function.

•BDE is not re-entrant during the callback function. The application must not yield to Windows within the callback function. For example, if the application displays a dialog box in Windows inside a callback function, the dialog box must be System Modal.

Types of callbacks

The application can choose to be notified of many different types of events, depending on which callback type it registers. The application can specify the following callback types in a call to DbiRegisterCallback.

Callback	Description
cbGENPROGRESS	Informs applications about the progress made during large batch operations.
cbRESTRUCTURE	Supplies information about an impending action and requests a response from the caller.
cbBATCHRESULT	Batch processing results.
cbTABLECHANGED	Notifies user that table has changed.
cbCANCELQRY	Allows user to cancel a Sybase query.
cbINPUTREQ	A BDE driver requests input from user.
cbDBASELOGIN	Enables clients to access encrypted dBASE tables.
cbFIELDRECALC	Field(s) recalculation.
cbTRACE	Trace.
cbDBLOGIN	Database login.
cbDELAYEDUPD	Cached updates callback.
cbNBROFCBS	Number of callbacks.

Callback function declarations and associated parameter lists, function return types, and callback data types are defined in the BDE header file for the particular BDE-using programming tool used (for Borland C, this header file is called IDAPI.H, for C++Builder, it is BDE.HPP, and for Delphi it is BDE.INT).

Return codes

The application responds to a callback by issuing a return code that commands an appropriate action:

Return code	Action description
cbrUSEDEF	Take default action.
cbrCONTINUE	Continue.
cbrABORT	Abort the operation.
cbrCHKINPUT	Input given.
cbrYES	Take requested action.
cbrNO	Do not take requested action.
cbrPARTIALASSIST	Assist in completing the job.

Registering a general progress report callback

Suppose that an application must copy a million-record table, and you want to periodically display a progress report on screen indicating the progress of the copy operation. You would use the following procedure:

1.Write the body of the of the progress callback function, declaring it with an associated predefined parameter list:
typedef CBRType far *pCBRType;
typedef CBRType (DBIFN * pfDBICallBack)
(
CBType ecbType, // Callback type
UINT32 iClientData, // Client callback data
pVOID pCbInfo // Call back info/Client
Input
);

2.The application allocates memory for the buffer pCbBuf to be used for passing data back and forth from the application to the function, and pointing to a CBPROGRESSDesc structure.
typedef struct
{
INT16 iPercentDone; // Percentage done
DBIMSG szMsg; // Message to display
} CBPROGRESSDesc;
typedef CBPROGRESSDesc far * pCBPROGRESSDesc;

3.To register a callback, the application calls DbiRegisterCallback passing cbGENPROGRESS as the value for ecbType.

4.The application issues a call to DbiBatchMove.

5.BDE returns either a percentage done (in the iPercentDone parameter of the CBPROGRESSDesc structure), or a message string to display on the status bar. The application can assume that if the iPercentDone value is negative, the message string is valid; otherwise, the application needs to consider the value of iPercentDone. The message string format is <Text String><:><Value> to allow easy international translations. For example: Records copied: 250

6.To continue processing the application returns the code cbrUSEDEF. The application can abort the BDE function call in progress by returning cbrABORT.