ASA Programming Guide
  Embedded SQL Programming
    Library function reference

db_register_a_callback function

Prototype 

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

Description 

This function registers callback functions.

If you do not register a DB_CALLBACK_WAIT callback, 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_DEBUG_MESSAGE    The supplied function is called once for each debug message and is passed a null-terminated string containing the text of the debug message. The string normally has a newline character (\n) immediately before the terminating null character. The prototype of the callback function is as follows:

  void SQL_CALLBACK debug_message_callback(
  SQLCA *sqlca,
  char * message_string );

• DB_CALLBACK_START    The prototype is as follows:

  void SQL_CALLBACK start_callback( SQLCA *sqlca );

  This function is called just before a database request is sent to the server. DB_CALLBACK_START is used only on Windows.

• DB_CALLBACK_FINISH    The prototype is as follows:

  void SQL_CALLBACK finish_callback( SQLCA * sqlca );

  This function is called after the response to a database request has been received by the interface DLL. DB_CALLBACK_FINISH is used only on Windows operating systems.

• DB_CALLBACK_CONN_DROPPED    The prototype is as follows:

  void SQL_CALLBACK conn_dropped_callback (
  SQLCA *sqlca,
  char *conn_name );

  This function is called when the database server is about to drop a connection because of a liveness timeout, through a DROP CONNECTION statement, or because the database server is being shut down. The connection name conn_name is passed in to allow you to distinguish between connections. If the connection was not named, it has a value of NULL.

• DB_CALLBACK_WAIT    The prototype is as follows:

  void SQL_CALLBACK wait_callback( SQLCA *sqlca );

  This function is called repeatedly by the interface library while the database server or client library is busy processing your database request.

  You would register this callback as follows:

  db_register_a_callback( &sqlca,
     DBCALLBACK_WAIT,
     (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 char msg_type,
  an_SQL_code code,
  unsigned short 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.

  For example, the Interactive SQL callback displays STATUS and INFO message in the Messages pane, while messages of type ACTION and WARNING go to a dialog. 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.