ASA Programming Interfaces Guide

Home

ASA Programming Interfaces Guide

Chapter 2: The Embedded SQL Interface

Library functions

Request management functions

The default behavior of the interface DLL is for applications to wait for completion of each database request before carrying out other functions. This behavior can be changed using request management functions. For example, when using Interactive SQL, the operating system is still active while Interactive SQL is waiting for a response from the database, and Interactive SQL carries out some tasks in that time.

You can achieve application activity 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.

The

db_register_a_callback

function is used to register your application callback functions:

db_cancel_request function

Prototype

int db_cancel_request( struct sqlca *sqlca );

Description

Cancels the currently active database server request. This function will check to make sure a database server request is active before sending the cancel request. If the function returns 1, then the cancel request was sent; if it returns 0, then no request was sent.

A non-zero return value means that the request was not canceled. There are a few critical timing cases where the cancel request and the response from the database or server "cross". In these cases, the cancel simply has no effect, even though the function still returns TRUE.

The db_cancel_request function can be called asynchronously. This function and db_is_working are the only functions in the database interface library that can be called asynchronously using an SQLCA that might be in use by another request.

If you cancel a request that is carrying out a cursor operation, the position of the cursor is indeterminate. You must locate the cursor by its absolute position, or close it, following the cancel.

db_is_working function

Prototype

unsigned db_is_working( struct sqlca *sqlca );

Description

Returns 1 if your application has a database request in progress that uses the given sqlca, and 0 if there is no request in progress that uses the given sqlca.

This function can be called asynchronously. This function and db_cancel_request are the only functions in the database interface library that can be called asynchronously using an SQLCA that might be in use by another request.

db_register_a_callback function

Prototype

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

Description

This function registers callback functions.

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.

To remove a callback, pass a null pointer as the callback function.

The following values are allowed for the index parameter:

DB_CALLBACK_START
The prototype is as follows:
```
void SQL_CALLBACK 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 SQL_CALLBACK 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_START and DB_CALLBACK_FINISH are used only on Windows 95/98, Windows NT, and Windows CE.

DB_CALLBACK_WAIT

The prototype is as follows:

void SQL_CALLBACK 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 SQL_CALLBACK 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 )
      }
    }
  }
}

You would register this callback as follows:

db_register_a_callback( &sqlca, 
   DBCALLBACK_MESSAGE, 
   (SQL_CALLBACK_PARM)&db_wait_request );

DB_CALLBACK_MESSAGE
This is used to enable the application to handle messages received from the server during the processing of a request.
The callback prototype is as follows:
```
void SQL_CALLBACK message_callback( SQLCA* sqlca,
                 unsigned short msg_type,
                 an_sql_code code,
                 unsigned length,
                 char*  msg )
```
The msg_type parameter states how important the message is, and you may wish to handle different message types in different ways. The available message types are MESSAGE_TYPE_INFO, MESSAGE_TYPE_WARNING, MESSAGE_TYPE_ACTION and MESSAGE_TYPE_STATUS. These constants are defined in sqldef.h. The code field is an identifier. The length field tells you how long the message is. The message is not null-terminated, since it might be right in the data stream that we got from the server.
For example, the Interactive SQL callback displays STATUS and INFO message in the message window, while messages of type ACTION and WARNING go to a dialog box. If an application does not register this callback, there is a default callback, which causes all messages to be written to the server logfile (if debugging is on and a logfile is specified). In addition, messages of type MESSAGE_TYPE_WARNING and MESSAGE_TYPE_ACTION are more prominently displayed, in an operating system-dependent manner.


	Expand Search