SQLParamData-Funktion

  • Artikel

Konformität
Eingeführte Version: ODBC 1.0-Standards Compliance: ISO 92

Zusammenfassung
SQLParamData wird zusammen mit SQLPutData verwendet, um Parameterdaten zum Zeitpunkt der Anweisungsausführung und mit SQLGetData zum Abrufen gestreamter Ausgabeparameterdaten zu liefern.

Syntax

  
SQLRETURN SQLParamData(  
     SQLHSTMT       StatementHandle,  
     SQLPOINTER *   ValuePtrPtr);

Argumente

StatementHandle
[Eingabe] Anweisungshandle.

ValuePtrPtr
[Ausgabe] Zeiger auf einen Puffer, in dem die Adresse des in SQLBindParameter angegebenen ParameterValuePtr-Puffers (für Parameterdaten) oder die Adresse des targetValuePtr-Puffers zurückgegeben werden soll, der in SQLBindCol (für Spaltendaten) angegeben ist, wie im Feld SQL_DESC_DATA_PTR Deskriptordatensatz enthalten.

Gibt zurück

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NEED_DATA, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR, SQL_INVALID_HANDLE oder SQL_PARAM_DATA_AVAILABLE.

Diagnose

Wenn SQLParamData SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugeordneter SQLSTATE-Wert abgerufen werden, indem SQLGetDiagRec mit einem HandleType von SQL_HANDLE_STMT und einem Handle von StatementHandle aufgerufen wird. In der folgenden Tabelle sind die SQLSTATE-Werte aufgeführt, die in der Regel von SQLParamData zurückgegeben werden, und die einzelnen Werte werden im Kontext dieser Funktion erläutert. die Notation "(DM)" steht vor den Beschreibungen von SQLSTATEs, die vom Treiber-Manager zurückgegeben werden. Der Rückgabecode, der jedem SQLSTATE-Wert zugeordnet ist, ist SQL_ERROR, sofern nicht anders angegeben.

SQLSTATE Fehler BESCHREIBUNG
01000 Allgemeine Warnung Treiberspezifische Informationsmeldung. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.)
07006 Verletzung des eingeschränkten Datentyp-Attributs Der durch das ValueType-Argument in SQLBindParameter für den gebundenen Parameter identifizierte Datenwert konnte nicht in den Datentyp konvertiert werden, der durch das ParameterType-Argument in SQLBindParameter identifiziert wird.

Der für einen Parameter zurückgegebene Datenwert, der als SQL_PARAM_INPUT_OUTPUT oder SQL_PARAM_OUTPUT gebunden ist, konnte nicht in den Datentyp konvertiert werden, der durch das ValueType-Argument in SQLBindParameter identifiziert wird.

(Wenn die Datenwerte für eine oder mehrere Zeilen nicht konvertiert werden konnten, aber eine oder mehrere Zeilen erfolgreich zurückgegeben wurden, gibt diese Funktion SQL_SUCCESS_WITH_INFO zurück.)
08S01 Kommunikationslinkfehler Die Kommunikationsverbindung zwischen dem Treiber und der Datenquelle, mit der der Treiber verbunden wurde, ist fehlgeschlagen, bevor die Verarbeitung der Funktion abgeschlossen wurde.
22026 Zeichenfolgendaten, nicht übereinstimmende Länge Der SQL_NEED_LONG_DATA_LEN Informationstyp in SQLGetInfo lautete "Y", und es wurden weniger Daten für einen long-Parameter gesendet (der Datentyp war SQL_LONGVARCHAR, SQL_LONGVARBINARY oder ein langer datenquellenspezifischer Datentyp), als mit dem argument StrLen_or_IndPtr in SQLBindParameter angegeben wurde.

Der SQL_NEED_LONG_DATA_LEN Informationstyp in SQLGetInfo lautete "Y", und es wurden weniger Daten für eine lange Spalte gesendet (der Datentyp war SQL_LONGVARCHAR, SQL_LONGVARBINARY oder ein langer datenquellenspezifischer Datentyp), als im Längenpuffer angegeben wurde, der einer Spalte in einer Datenzeile entspricht, die mit SQLBulkOperations hinzugefügt oder aktualisiert oder mit SQLSetPos aktualisiert wurde.
40001 Serialisierungsfehler Die Transaktion wurde aufgrund eines Ressourcen-Deadlocks mit einer anderen Transaktion zurückgesetzt.
40003 Anweisungsabschluss unbekannt Die zugeordnete Verbindung ist während der Ausführung dieser Funktion fehlgeschlagen, und der Status der Transaktion kann nicht bestimmt werden.
HY000 Allgemeiner Fehler Es ist ein Fehler aufgetreten, für den kein spezifischer SQLSTATE-Wert vorhanden war und für den keine implementierungsspezifische SQLSTATE definiert wurde. Die von SQLGetDiagRec im *MessageText-Puffer zurückgegebene Fehlermeldung beschreibt den Fehler und seine Ursache.
HY001 Fehler bei der Speicherbelegung Der Treiber konnte arbeitsspeicher nicht zuordnen, der zur Unterstützung der Ausführung oder Fertigstellung der Funktion erforderlich ist.
HY008 Vorgang abgebrochen Die asynchrone Verarbeitung wurde für statementHandle aktiviert. Die Funktion wurde aufgerufen, und vor Abschluss der Ausführung wurde SQLCancel oder SQLCancelHandle für statementHandle aufgerufen. die Funktion wurde dann erneut für die StatementHandle aufgerufen.

Die Funktion wurde aufgerufen, und bevor die Ausführung abgeschlossen wurde, wurde SQLCancel oder SQLCancelHandle für die StatementHandle aus einem anderen Thread in einer Multithreadanwendung aufgerufen.
HY010 Funktionssequenzfehler (DM) Der vorherige Funktionsaufruf war kein Aufruf von SQLExecDirect, SQLExecute, SQLBulkOperations oder SQLSetPos , bei dem der Rückgabecode SQL_NEED_DATA wurde, oder der vorherige Funktionsaufruf war ein Aufruf von SQLPutData.

Der vorherige Funktionsaufruf war ein Aufruf von SQLParamData.

(DM) Eine asynchron ausgeführte Funktion wurde für das Verbindungshandle aufgerufen, das dem StatementHandle zugeordnet ist. Diese asynchrone Funktion wurde noch ausgeführt, als die FUNKTION SQLParamData aufgerufen wurde.

(DM) Eine asynchron ausgeführte Funktion (nicht diese) wurde für das StatementHandle aufgerufen und wurde noch ausgeführt, als diese Funktion aufgerufen wurde.

SQLExecute, SQLExecDirect, SQLBulkOperations oder SQLSetPos wurde für statementHandle aufgerufen und SQL_NEED_DATA zurückgegeben. SQLCancel wurde aufgerufen, bevor Daten für alle Daten bei der Ausführungsparameter oder -spalten gesendet wurden.
HY013 Fehler bei der Speicherverwaltung Der Funktionsaufruf konnte nicht verarbeitet werden, weil auf die zugrunde liegenden Speicherobjekte nicht zugegriffen werden konnte, möglicherweise aufgrund von geringen Arbeitsspeicherbedingungen.
HY117 Die Verbindung wird aufgrund eines unbekannten Transaktionsstatus angehalten. Nur trenn- und schreibgeschützte Funktionen sind zulässig. (DM) Weitere Informationen zum angehaltenen Zustand finden Sie unter SQLEndTran-Funktion.
HYT01 Verbindungstimeout abgelaufen Der Zeitraum für das Verbindungstimeout ist abgelaufen, bevor die Datenquelle auf die Anforderung geantwortet hat. Der Verbindungstimeoutzeitraum wird über SQLSetConnectAttr festgelegt, SQL_ATTR_CONNECTION_TIMEOUT.
IM001 Treiber unterstützt diese Funktion nicht. (DM) Der Treiber, der dem StatementHandle entspricht, unterstützt die Funktion nicht.
IM017 Abruf ist im asynchronen Benachrichtigungsmodus deaktiviert. Wenn das Benachrichtigungsmodell verwendet wird, wird die Abfrage deaktiviert.
IM018 SQLCompleteAsync wurde nicht aufgerufen, um den vorherigen asynchronen Vorgang für dieses Handle abzuschließen. Wenn der vorherige Funktionsaufruf für das Handle SQL_STILL_EXECUTING zurückgibt und der Benachrichtigungsmodus aktiviert ist, muss SQLCompleteAsync für das Handle aufgerufen werden, um die Nachverarbeitung durchzuführen und den Vorgang abzuschließen.

Wenn SQLParamData aufgerufen wird, während Daten für einen Parameter in einer SQL-Anweisung gesendet werden, kann ein beliebiger SQLSTATE-Wert zurückgegeben werden, der von der Funktion zurückgegeben werden kann, die zum Ausführen der Anweisung aufgerufen wird (SQLExecute oder SQLExecDirect). Wenn es aufgerufen wird, während Daten für eine Spalte gesendet werden, die mit SQLBulkOperations aktualisiert oder hinzugefügt wird oder mit SQLSetPos aktualisiert wird, kann ein beliebiger SQLSTATE-Wert zurückgegeben werden, der von SQLBulkOperations oder SQLSetPos zurückgegeben werden kann.

Kommentare

SQLParamData kann aufgerufen werden, um Daten bei der Ausführung für zwei Zwecke bereitzustellen: Parameterdaten, die in einem Aufruf von SQLExecute oder SQLExecDirect verwendet werden, oder Spaltendaten, die verwendet werden, wenn eine Zeile durch einen Aufruf von SQLBulkOperations aktualisiert oder hinzugefügt oder durch einen Aufruf von SQLSetPos aktualisiert wird. Zur Ausführungszeit gibt SQLParamData an die Anwendung einen Indikator zurück, welche Daten der Treiber benötigt.

Wenn eine Anwendung SQLExecute, SQLExecDirect, SQLBulkOperations oder SQLSetPos aufruft, gibt der Treiber SQL_NEED_DATA zurück, wenn Daten bei der Ausführung benötigt werden. Eine Anwendung ruft dann SQLParamData auf, um zu bestimmen, welche Daten gesendet werden sollen. Wenn der Treiber Parameterdaten benötigt, gibt der Treiber im *ValuePtrPtrPtr-Ausgabepuffer den Wert zurück, den die Anwendung in den Rowsetpuffer eingefügt hat. Die Anwendung kann diesen Wert verwenden, um zu bestimmen, welche Parameterdaten der Treiber anfordert. Wenn der Treiber Spaltendaten benötigt, gibt der Treiber im Puffer *ValuePtrPtr die Adresse zurück, an die die Spalte ursprünglich gebunden war, wie folgt:

Gebundene Adresse + Bindungsoffset + ((Zeilenzahl - 1) x Elementgröße)

wobei die Variablen wie in der folgenden Tabelle angegeben definiert sind.

Variable BESCHREIBUNG
Gebundene Adresse Die Adresse, die mit dem Argument TargetValuePtr in SQLBindCol angegeben wurde.
Bindungsoffset Der Wert, der an der adresse gespeichert wird, die mit dem SQL_ATTR_ROW_BIND_OFFSET_PTR-Anweisungsattribut angegeben ist.
Row Number Die 1-basierte Nummer der Zeile im Rowset. Für Einzeilenabrufe, die standardmäßig sind, ist dies 1.
Elementgröße Der Wert des SQL_ATTR_ROW_BIND_TYPE-Anweisungsattributs für Daten- und Längen-/Indikatorpuffer.

Außerdem wird SQL_NEED_DATA zurückgegeben. Dies ist ein Indikator für die Anwendung, dass sqlPutData aufgerufen werden soll, um die Daten zu senden.

Die Anwendung ruft SQLPutData so oft wie nötig auf, um die Daten bei der Ausführung für die Spalte oder den Parameter zu senden. Nachdem alle Daten für die Spalte oder den Parameter gesendet wurden, ruft die Anwendung SQLParamData erneut auf. Wenn SQLParamData erneut SQL_NEED_DATA zurückgibt, müssen Daten für einen anderen Parameter oder eine andere Spalte gesendet werden. Daher ruft die Anwendung erneut SQLPutData auf. Wenn alle Daten zur Ausführung für alle Parameter oder Spalten gesendet wurden, gibt SQLParamData SQL_SUCCESS oder SQL_SUCCESS_WITH_INFO zurück, der Wert in *ValuePtrPtrPtr ist undefiniert, und die SQL-Anweisung kann ausgeführt werden, oder der SQLBulkOperations - oder SQLSetPos-Aufruf kann verarbeitet werden.

Wenn SQLParamData Parameterdaten für eine durchsuchte Update- oder Delete-Anweisung bereitstellt, die sich nicht auf Zeilen in der Datenquelle auswirkt, gibt der Aufruf von SQLParamData SQL_NO_DATA zurück.

Weitere Informationen dazu, wie Daten bei Ausführungsparameterdaten zur Ausführungszeit der Anweisung übergeben werden, finden Sie unter Übergeben von Parameterwerten in SQLBindParameter und Senden von langen Daten. Weitere Informationen dazu, wie Daten bei der Ausführungsspalte aktualisiert oder hinzugefügt werden, finden Sie im Abschnitt "Using SQLSetPos" in SQLSetPos, "Performing Bulk Aktualisierungen Using Bookmarks" in SQLBulkOperations und Long Data and SQLSetPos and SQLBulkOperations.

SQLParamData kann aufgerufen werden, um gestreamte Ausgabeparameter abzurufen. Wenn SQLMoreResults, SQLExecute, SQLGetData oder SQLExecDirect SQL_PARAM_DATA_AVAILABLE zurückgibt, rufen Sie SQLParamData auf, um zu bestimmen, welcher Parameter einen Wert zur Verfügung hat. Weitere Informationen zu SQL_PARAM_DATA_AVAILABLE und gestreamten Ausgabeparametern finden Sie unter Abrufen von Ausgabeparametern mithilfe von SQLGetData.

Codebeispiel

Weitere Informationen finden Sie unter SQLPutData.

Informationen über Finden Sie unter
Binden eines Puffers an einen Parameter SQLBindParameter-Funktion
Abbrechen der Anweisungsverarbeitung SQLCancel-Funktion
Zurückgeben von Informationen zu einem Parameter in einer -Anweisung SQLDescribeParam-Funktion
Ausführen einer SQL-Anweisung SQLExecDirect-Funktion
Ausführen einer vorbereiteten SQL-Anweisung SQLExecute-Funktion
Senden von Parameterdaten zur Ausführungszeit SQLPutData-Funktion

Weitere Informationen

ODBC-API-Referenz
ODBC-Headerdateien
Abrufen von Ausgabeparametern mithilfe von SQLGetData