Teilen über


Senden von Long-Daten

DBMSs definieren lange Daten als beliebige Zeichen oder Binärdaten über eine bestimmte Größe, z. B. 254 Zeichen. Möglicherweise ist es nicht möglich, ein gesamtes Element langer Daten im Arbeitsspeicher zu speichern, z. B. wenn das Element ein langes Textdokument oder eine Bitmap darstellt. Da solche Daten nicht in einem einzigen Puffer gespeichert werden können, sendet die Datenquelle sie an den Treiber in Teilen mit SQLPutData , wenn die Anweisung ausgeführt wird. Parameter, für die Daten zur Ausführungszeit gesendet werden, werden als Data-at-Execution-Parameter bezeichnet.

Hinweis

Eine Anwendung kann tatsächlich jede Art von Daten zur Ausführungszeit mit SQLPutData senden, obwohl nur Zeichen- und Binärdaten in Teilen gesendet werden können. Wenn die Daten jedoch klein genug sind, um in einen einzelnen Puffer zu passen, gibt es in der Regel keinen Grund, SQLPutData zu verwenden. Es ist viel einfacher, den Puffer zu binden und dem Treiber das Abrufen der Daten aus dem Puffer zu ermöglichen.

Zum Senden von Daten zur Ausführungszeit führt die Anwendung die folgenden Aktionen aus:

  1. Übergibt einen 32-Bit-Wert, der den Parameter im ParameterValuePtr-Argument in SQLBindParameter identifiziert, anstatt die Adresse eines Puffers zu übergeben. Dieser Wert wird nicht vom Treiber analysiert. Sie wird später an die Anwendung zurückgegeben, daher sollte sie etwas für die Anwendung bedeuten. Beispielsweise kann es sich um die Nummer des Parameters oder das Handle einer Datei handeln, die Daten enthält.

  2. Übergibt die Adresse eines Längen-/Indikatorpuffers im StrLen_or_IndPtr-Argument von SQLBindParameter.

  3. Speichert SQL_DATA_AT_EXEC oder das Ergebnis des Makros SQL_LEN_DATA_AT_EXEC(länge) im Längen-/Indikatorpuffer. Beide Werte geben dem Treiber an, dass die Daten für den Parameter mit SQLPutData gesendet werden. SQL_LEN_DATA_AT_EXEC(Länge) wird verwendet, wenn lange Daten an eine Datenquelle gesendet werden, die wissen muss, wie viele Byte lange Daten gesendet werden, damit sie Platz vorschreiben kann. Um festzustellen, ob für eine Datenquelle dieser Wert erforderlich ist, ruft die Anwendung SQLGetInfo mit der Option SQL_NEED_LONG_DATA_LEN auf. Alle Treiber müssen dieses Makro unterstützen; wenn für die Datenquelle keine Bytelänge erforderlich ist, kann der Treiber sie ignorieren.

  4. Ruft SQLExecute oder SQLExecDirect auf. Der Treiber ermittelt, dass ein Längen-/Indikatorpuffer den Wert SQL_DATA_AT_EXEC oder das Ergebnis des Makros SQL_LEN_DATA_AT_EXEC(Länge) enthält und SQL_NEED_DATA als Rückgabewert der Funktion zurückgibt.

  5. Ruft SQLParamData als Reaktion auf den SQL_NEED_DATA Rückgabewert auf. Wenn lange Daten gesendet werden müssen, gibt SQLParamData SQL_NEED_DATA zurück. Im Puffer, auf den das ValuePtrPtr-Argument verweist, gibt der Treiber den Wert zurück, der den Parameter "data-at-execution" identifiziert. Wenn mehr als ein Data-at-Execution-Parameter vorhanden ist, muss die Anwendung diesen Wert verwenden, um zu bestimmen, für welchen Parameter Daten gesendet werden sollen; der Treiber ist nicht erforderlich, um Daten für Daten bei ausführungsparametern in einer bestimmten Reihenfolge anzufordern.

  6. Ruft SQLPutData auf, um die Parameterdaten an den Treiber zu senden. Wenn die Parameterdaten nicht in einen einzelnen Puffer passen, wie es häufig bei langen Daten der Fall ist, ruft die Anwendung SQLPutData wiederholt auf, um die Daten in Teilen zu senden. Es liegt an dem Treiber und der Datenquelle, die Daten neu zusammenzufügen. Wenn die Anwendung null-beendete Zeichenfolgendaten übergibt, muss der Treiber oder die Datenquelle das Nullendpunktzeichen im Rahmen des Erneutassembly-Prozesses entfernen.

  7. Ruft SQLParamData erneut auf, um anzugeben, dass alle Daten für den Parameter gesendet wurden. Wenn datenbasierte Ausführungsparameter vorhanden sind, für die keine Daten gesendet wurden, gibt der Treiber SQL_NEED_DATA und den Wert zurück, der den nächsten Parameter identifiziert; die Anwendung kehrt zu Schritt 6 zurück. Wenn Daten für alle Daten bei ausführungsparametern gesendet wurden, wird die Anweisung ausgeführt. SQLParamData gibt SQL_SUCCESS oder SQL_SUCCESS_WITH_INFO zurück und kann jeden Rückgabewert oder jede Diagnose zurückgeben, die SQLExecute oder SQLExecDirect zurückgeben kann.

Nachdem SQLExecute oder SQLExecDirect SQL_NEED_DATA zurückgibt und die Daten für den letzten Data-at-Execution-Parameter vollständig gesendet wurden, befindet sich die Anweisung in einem Need Data-Zustand. Während sich eine Anweisung in einem Need Data-Zustand befindet, kann die Anwendung nur SQLPutData, SQLParamData, SQLCancel, SQLGetDiagField oder SQLGetDiagRec aufrufen. Alle anderen Funktionen geben SQLSTATE HY010 zurück (Funktionssequenzfehler). Durch Aufrufen von SQLCancel wird die Ausführung der Anweisung abgebrochen und an den vorherigen Zustand zurückgegeben. Weitere Informationen finden Sie in Anhang B: ODBC-Zustandsübergangstabellen.

Ein Beispiel für das Senden von Daten zur Ausführungszeit finden Sie in der BESCHREIBUNG der SQLPutData-Funktion .