Click here to view and discuss this page in DocCommentXchange. In the future, you will be sent there automatically.

SQL Anywhere 11.0.1 (Deutsch) » SQL Anywhere Server - Programmierung » SQL Anywhere Datenzugriff-APIs » SQL Anywhere Embedded SQL » Referenz der Bibliotheksfunktionen

 

db_register_a_callback-Funktion

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

Diese Funktion registriert Callback-Funktionen:

Falls Sie keine Callback-Funktion DB_CALLBACK_WAIT registrieren, ist die voreingestellte Reaktion, nichts zu tun. Ihre Anwendung wird blockiert, während sie auf die Antwort der Datenbank wartet. Sie müssen eine Callback-Funktion für die MESSAGE TO CLIENT-Anweisung registrieren. Weitere Hinweise finden Sie unter MESSAGE-Anweisung.

Um einen Callback zu löschen, übergeben Sie einen Null-Zeiger als callback-Funktion.

Die folgenden Werte sind für den Parameter index erlaubt:

  • 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 );

    Weitere Hinweise finden Sie unter LogFile-Verbindungsparameter [LOG].

  • 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 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.

    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. Mehrere unterschiedliche Nachrichtentypen können unterschiedlich behandelt werden. Die möglichen Nachrichtentypen sind MESSAGE_TYPE_INFO, MESSAGE_TYPE_WARNING, MESSAGE_TYPE_ACTION und MESSAGE_TYPE_STATUS. Diese Konstanten sind in sqldef.h definiert. 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.

    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.