SQLParamData-Funktion
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.
Verwandte Funktionen
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