db_register_a_callback Function

This function registers callback functions.

Syntax

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

Parameters

sqlca – A pointer to a SQLCA structure.
index – An index value identifying the type of callback as described below.
callback – The address of a user-defined callback function.

Remarks

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. You must register a callback for the MESSAGE TO CLIENT statement.

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. A debug message is a message that is logged to the LogFile file. In order for a debug message to be passed to this callback, the LogFile connection parameter must be used. The string normally has a newline character (\n) immediately before the terminating null character. The prototype of the callback function is as follows:
The supplied function is called once for each debug message and is passed a null-terminated string containing the text of the debug message. A debug message is a message that is logged to the LogFile file. In order for a debug message to be passed to this callback, the LogFile connection parameter must be used. 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:
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:
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 DBLIB interface DLL. DB_CALLBACK_FINISH is used only on Windows operating systems.
DB_CALLBACK_CONN_DROPPED – The prototype is as follows:
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:
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,
   DB_CALLBACK_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. Messages can be sent to the client application from the database server using the SQL MESSAGE statement. Messages can also be generated by long running database server statements.
This is used to enable the application to handle messages received from the server during the processing of a request. Messages can be sent to the client application from the database server using the SQL MESSAGE statement. Messages can also be generated by long running database server statements.

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. You may want to handle different message types in different ways. The following possible values for msg_type are defined in sqldef.h.
- MESSAGE_TYPE_INFO – The message type was INFO.
- MESSAGE_TYPE_WARNING – The message type was WARNING.
- MESSAGE_TYPE_ACTION – The message type was ACTION.
- MESSAGE_TYPE_STATUS – The message type was STATUS.
- MESSAGE_TYPE_PROGRESS – The message type was PROGRESS. This type of message is generated by long running database server statements such as BACKUP DATABASE and LOAD TABLE.
The code field may provide a SQLCODE associated with the message, otherwise the value is 0. The length field tells you how long the message is. The message is not null-terminated. SAP Sybase IQ DBLIB and ODBC clients can use the DB_CALLBACK_MESSAGE parameter to receive progress messages.

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

When a message callback is not registered by the application, messages sent to the client are saved to the log file when the LogFile connection parameter is specified. Also, ACTION or STATUS messages sent to the client appear in a window on Windows operating systems and are logged to stderr on Unix operating systems.
DB_CALLBACK_VALIDATE_FILE_TRANSFER – This is used to register a file transfer validation callback function. Before allowing any transfer to take place, the client library will invoke the validation callback, if it exists. If the client data transfer is being requested during the execution of indirect statements such as from within a stored procedure, the client library will not allow a transfer unless the client application has registered a validation callback. The conditions under which a validation call is made are described more fully below.
This is used to register a file transfer validation callback function. Before allowing any transfer to take place, the client library will invoke the validation callback, if it exists. If the client data transfer is being requested during the execution of indirect statements such as from within a stored procedure, the client library will not allow a transfer unless the client application has registered a validation callback. The conditions under which a validation call is made are described more fully below.

The callback prototype is as follows:
```
int SQL_CALLBACK file_transfer_callback(
SQLCA * sqlca,
char * file_name,
int is_write
);
```
The file_name parameter is the name of the file to be read or written. The is_write parameter is 0 if a read is requested (transfer from the client to the server), and non-zero for a write. The callback function should return 0 if the file transfer is not allowed, non-zero otherwise.

For data security, the server tracks the origin of statements requesting a file transfer. The server determines if the statement was received directly from the client application. When initiating the transfer of data from the client, the server sends the information about the origin of the statement to the client software. On its part, the embedded SQL client library allows unconditional transfer of data only if the data transfer is being requested due to the execution of a statement sent directly by the client application. Otherwise, the application must have registered the validation callback described above, in the absence of which the transfer is denied and the statement fails with an error. If the client statement invokes a stored procedure already existing in the database, then the execution of the stored procedure itself is considered not to have been for a client initiated statement. However, if the client application explicitly creates a temporary stored procedure then the execution of the stored procedure results in the server treating the procedure as having been client initiated. Similarly, if the client application executes a batch statement, then the execution of the batch statement is considered as being done directly by the client application.