ASA Programming Guide
  The Database Tools Interface
    Using the database tools interface

Using callback functions

Several elements in DBTools structures are of type MSG_CALLBACK. These are pointers to callback functions.

Uses of callback functions 

Callback functions allow DBTools functions to return control of operation to the user's calling application. The DBTools library uses callback functions to handle messages sent to the user by the DBTools functions for four purposes:

• Confirmation    Called when an action needs to be confirmed by the user. For example, if the backup directory does not exist, the tools DLL asks if it needs to be created.

• Error message    Called to handle a message when an error occurs, such as when an operation is out of disk space.

• Information message    Called for the tools to display some message to the user (such as the name of the current table being backed up).

• Status information    Called for the tools to display the status of an operation (such as the percentage done when unloading a table).

Assigning a callback function to a structure 

You can directly assign a callback routine to the structure. The following statement is an example using a backup structure:

backup_info.errorrtn = (MSG_CALLBACK) MyFunction

MSG_CALLBACK is defined in the dllapi.h header file supplied with Adaptive Server Anywhere. Tools routines can call back to the Calling application with messages that should appear in the appropriate user interface, whether that be a windowing environment, standard output on a character-based system, or other user interface.

Confirmation callback function example 

The following example confirmation routine asks the user to answer YES or NO to a prompt and returns the user's selection:

extern short _callback ConfirmRtn(
      char far * question )
{
   int ret;
   if( question != NULL ) {
      ret = MessageBox( HwndParent, question,
      "Confirm", MB_ICONEXCLAMTION|MB_YESNO );
   }
   return( 0 );
}

Error callback function example 

The following is an example of an error message handling routine, which displays the error message in a message box.

extern short _callback ErrorRtn(
      char far * errorstr )
{
   if( errorstr != NULL ) {
      ret = MessageBox( HwndParent, errorstr,
      "Backup Error", MB_ICONSTOP|MB_OK );
   }
   return( 0 );
}

Message callback function example 

A common implementation of a message callback function outputs the message to the screen:

extern short _callback MessageRtn(
      char far * errorstr )
{
   if( messagestr != NULL ) {
   OutputMessageToWindow( messagestr );
   }
   return( 0 );
}

Status callback function example 

A status callback routine is called when the tools needs to display the status of an operation (like the percentage done unloading a table). Again, a common implementation would just output the message to the screen:

extern short _callback StatusRtn(
      char far * statusstr )
{
   if( statusstr == NULL ) {
      return FALSE;
   }
   OutputMessageToWindow( statustr );
   return TRUE;
}