Programming Interfaces Guide

Home

Chapter 2: The Embedded SQL Interface

Library functions

Windows 3.x request management functions

This section applies only to Windows 3.x development.

When using Interactive SQL under Windows 3.x, the Windows system is still active while Interactive SQL is waiting for a response from the database. This is not the default behavior of the interface DLL. Default behavior puts the hour glass cursor on the screen and forces the user to wait for completion of the request.

You can achieve application activity in Windows while a database request is in progress by providing a callback function. In this callback function you must not do another database request (except db_cancel_request ). You can use the db_is_working function in your message handlers to determine if you have a database request in progress.

This callback function in your application is called repeatedly while the database server is busy processing a request. You can then process Windows messages by calling GetMessage or PeekMessage . (These function calls allow Windows to be active.) The dblib6w.dll continually calls this function until the response from the database server is received.

Note:
Response in Windows message
The response from the server comes to your application via a Windows message. You must either dispatch this message (the interface DLL will receive the message), or call the db_process_message function with each message that you receive while in this callback function. The function returns TRUE if the message was the response; otherwise you can process the message normally by dispatching it.

The following two functions are used to register your application callback functions:

db_register_a_callback function

Prototype

void db_register_a_callback( struct sqlca *sqlca, a_db_callback_index index, FARPROC callback );

Description

This function is used to register Windows callback functions. To remove a callback, pass a null pointer as the callback function. You should call MakeProcInstance with your function address and pass that to the db_register_a_callback function.

If you do not register any callback functions, the default action is to do nothing. Your application blocks, waiting for the database response, and Windows changes the cursor to an hourglass.

The following values are allowed for the index parameter:

DB_CALLBACK_START
The prototype is as follows:
```
void FAR PASCAL db_start_request( struct sqlca *sqlca );
```
This function is called just before a database request is sent to the server.
DB_CALLBACK_FINISH
The prototype is as follows:
```
void FAR PASCAL db_finish_request( struct sqlca *sqlca );
```
This function is called after the response to a database request has been received by the interface DLL.
DB_CALLBACK_WAIT
The prototype is as follows:
```
void FAR PASCAL db_wait_request( struct sqlca *sqlca );
```
This function is called repeatedly by the interface DLL while the database server or client library is busy processing your database request.

The following is a sample DB_CALLBACK_WAIT callback function:

void FAR PASCAL db_wait_request( struct sqlca *sqlca )
{ MSG msg
  if( GetMessage( &msg, NULL, 0, 0 ) ) {
    ( !db_process_a_message( sqlca, &msg ) ) {
      if( !TranslateAccelerator( hWnd, hAccel, &msg ) ) {
      TranslateMessage( &msg )
      DispatchMessage( &msg )
      }
    }
  }
}

db_process_a_message function

Prototype

int db_process_a_message( struct sqlca *sqlca, MSG *msg );

Description

This function is called from within your db_wait_request callback function to determine if the message that you received from Windows was in fact the response to the active database request. The return value is TRUE if msg is the response. Return from the callback function and the Embedded SQL library DLL will process the response by returning to the call that generated the original request.


	Expand Search