sqlca   Ein Zeiger auf eine SQLCA-Struktur.

index   Ein Index-Wert, der den Callback-Typ angibt, wie im Folgenden beschrieben.

callback   Die Adresse einer benutzerdefinierten Callback-Funktion.

DB_CALLBACK_DEBUG_MESSAGE   Die bereitgestellte Funktion wird für jede Debug-Meldung einmal aufgerufen. Ihr wird eine auf NULL endende Zeichenfolge übergeben, die den Text der Debug-Meldung enthält. Eine Debug-Meldung ist eine Meldung, die in der LogFile-Datei protokolliert wird. Damit eine Debug-Meldung an dieses Callback übergeben wird, muss der LogFile-Verbindungsparameter verwendet werden. Die Zeichenfolge enthält gewöhnlich eine Zeilenendmarke (\n) unmittelbar vor dem beendenden NULL-Zeichen. Der Prototyp der Callback-Funktion lautet folgendermaßen:

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

DB_CALLBACK_START   Der Prototyp sieht wie folgt aus:

void SQL_CALLBACK start_callback( SQLCA * sqlca );

Diese Funktion wird unmittelbar vor dem Absenden einer Datenbankanforderung an den Server aufgerufen. DB_CALLBACK_START wird nur unter Windows verwendet.

DB_CALLBACK_FINISH   Der Prototyp sieht wie folgt aus:

void SQL_CALLBACK finish_callback( SQLCA * sqlca );

Diese Funktion wird aufgerufen, nachdem die Antwort auf eine Datenbankanforderung von der DBLIB-Schnittstellen-DLL empfangen wurde. DB_CALLBACK_FINISH wird nur unter Windows-Betriebssystemen verwendet.

DB_CALLBACK_CONN_DROPPED   Der Prototyp sieht wie folgt aus:

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

Diese Funktion wird aufgerufen, wenn der Datenbankserver im Begriff ist, die Verbindung aufgrund einer Verfügbarkeitszeitüberschreitung zu verlieren, von einer DROP CONNECTION-Anweisung oder weil der Server heruntergefahren wird. Der Verbindungsname conn_name wird übergeben, sodass Sie zwischen den Verbindungen unterscheiden können. Wenn die Verbindung nicht benannt war, hat sie den Wert NULL.

DB_CALLBACK_WAIT   Der Prototyp sieht wie folgt aus:

void SQL_CALLBACK wait_callback( SQLCA * sqlca );

Diese Funktion wird wiederholt von der Schnittstellenbibliothek aufgerufen, während der Datenbankserver oder die Clientbibliothek mit dem Abarbeiten Ihrer Datenbankanforderung beschäftigt sind.

So würden Sie diesen Callback registrieren:

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

DB_CALLBACK_MESSAGE   Diese Funktion ermöglicht es der Anwendung, Nachrichten vom Server zu verarbeiten, während dieser eine Anforderung abarbeitet. Nachrichten können vom Datenbankserver an die Clientanwendung unter Verwendung der SQL MESSAGE-Anweisung gesendet werden. Nachrichten können auch von lang laufenden Datenbankserver-Anweisungen generiert werden.

Der Callback-Prototyp sieht wie folgt aus:

void SQL_CALLBACK message_callback(
SQLCA * sqlca,
unsigned char msg_type,
an_sql_code code,
unsigned short length,
char *  msg
);

Der msg_type-Parameter gibt an, wie wichtig die Nachricht ist. Unterschiedliche Nachrichtentypen können verschieden behandelt werden. Die folgenden zulässigen Werte für Nachrichtentyp sind in sqldef.h festgelegt.

Das Feld code kann einen SQLCODE übergeben, der der Nachricht zugeordnet ist. Anderfalls ist der Wert "0". Das Feld length gibt die Länge der Nachricht an. Die Meldung endet nicht mit NULL. SQL Anywhere DBLIB und ODBC-Clients können mithilfe der DB_CALLBACK_MESSAGE-Parameter Meldungen zum Verarbeitungsfortschritt empfangen.

Zum Beispiel zeigt die Interactive SQL Callback-Funktion STATUS- und INFO-Nachrichten im Nachrichtenfenster an, während Nachrichten vom Typ ACTION und WARNING in einem Fenster erscheinen. Wenn eine Anwendung diese Callback-Funktion nicht registriert, gibt es eine Standard-Callback-Funktion, die alle Nachrichten in die Serverlogdatei schreibt (wenn der Debug-Modus eingestellt und eine Logdatei angegeben ist). Zusätzlich werden Nachrichten vom Typ MESSAGE_TYPE_WARNING und MESSAGE_TYPE_ACTION betriebssystemabhängig auffälliger dargestellt.

Wenn ein Nachrichten-Callback von der Anwendung nicht registriert wird, werden an den Client gesendete Nachrichten in der Logdatei gespeichert, sofern der LogFile-Verbindungsparameter angegeben ist. Außerdem werden auf Windows-Betriebssystemen an den Client gesendete ACTION- oder STATUS-Nachrichten in einem Fenster angezeigt, und auf Unix-Betriebssystemen in stderr protokolliert.

DB_CALLBACK_VALIDATE_FILE_TRANSFER   Dies wird verwendet, um eine Callback-Funktion zur Dateiübertragungsvalidierung zu registrieren. Bevor sie eine Übertragung zulässt, ruft die Clientbibliothek das Validierungs-Callback auf, falls vorhanden. Falls die Client-Datenübertragung während der Ausführung von indirekten Anweisungen angefordert wird, z.B. aus einer gespeicherten Prozedur heraus, lässt die Clientbibliothek die Übertragung nur zu, wenn die Clientanwendung ein Validierungs-Callback registriert hat. Die Bedingungen, unter denen ein Validierungsaufruf durchgeführt wird, werden unten ausführlich beschrieben.

Der Callback-Prototyp sieht wie folgt aus:

int SQL_CALLBACK file_transfer_callback(
SQLCA * sqlca,
char * file_name,
int is_write
);

Der Parameter file_name ist der Name der zu lesenden oder zu schreibenden Datei. Der Parameter is_write ist 0, wenn ein Lesevorgang (Übertragung vom Client zum Datenbankserver) angefordert wird, und Nicht-Null bei einem Schreibvorgang. Die Callback-Funktion sollte 0 zurückgeben, wenn die Übertragung nicht zulässig ist, ansonsten Nicht-Null.

Aus Gründen der Datensicherheit protokolliert der Datenbankserver den Ursprung von Anweisungen, die eine Dateiübertragung anfordern. Der Datenbankserver ermittelt, ob die Anweisung direkt von der Clientanwendung empfangen wurde. Wenn er die Datenübertragung vom Client initiiert, sendet der Datenbankserver die Informationen über den Ursprung der Anweisung an die Clientsoftware. Seinerseits erlaubt die Embedded SQL Clientbibliothek nur dann eine bedingungslose Übertragung, wenn die Datenübertragung aufgrund der Ausführung einer Anweisung angefordert wird, die direkt von der Clientanwendung gesendet wird. Ansonsten muss die Anwendung den oben beschriebenen Validierungs-Callback registriert haben. Wenn dieser fehlt, wird die Übertragung verweigert und die Anweisung schlägt mit einem Fehler fehl. Beachten Sie: Wenn die Clientanweisung eine bereits in der Datenbank vorhandene gespeicherte Prozedur aufruft, wird die Ausführung der gespeicherten Prozedur selbst nicht als eine vom Client initiierte Anweisung angesehen. Wenn die Clientanwendung allerdings explizit eine temporäre gespeicherte Prozedur erstellt, führt die Ausführung der gespeicherten Prozedur dazu, dass der Datenbankserver die Prozedur als eine vom Client initiierte behandelt. Wenn die Clientanwendung eine Batchanweisung ausführt, wird auf gleiche Weise die Ausführung der Batchanweisung als eine angesehen, die direkt von der Clientanwendung durchgeführt wird.