SQLParamData-Funktion

  • Artikel

Konformität
Version eingeführt: ODBC 1.0 Standards Compliance: ISO 92

Zusammenfassung
SQLParamData wird zusammen mit SQLPutData verwendet, um Parameterdaten zur Ausführungszeit der Anweisung 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 parameterValuePtr-Puffers zurückgegeben werden soll, der in SQLBindParameter (für Parameterdaten) angegeben ist, oder die Adresse des in SQLBindCol (für Spaltendaten) angegebenen TargetValuePtr-Puffers, wie im SQL_DESC_DATA_PTR Deskriptor-Datensatzfeld 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.

Diagnostik

Wenn SQLParamData SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugeordneter SQLSTATE-Wert durch Aufrufen von SQLGetDiagRec mit einem HandleType von SQL_HANDLE_STMT und einem Handle of StatementHandle abgerufen werden. In der folgenden Tabelle sind die SQLSTATE-Werte aufgeführt, die in der Regel von SQLParamData zurückgegeben werden, und jede wird 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 Error Beschreibung
01000 Allgemeiner Warnhinweis 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 wurde.

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

(Wenn die Datenwerte für eine oder mehrere Zeilen nicht konvertiert werden konnten, aber mindestens eine Zeile 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 war "Y", und weniger Daten wurden für einen langen Parameter gesendet (der Datentyp wurde SQL_LONGVARCHAR, SQL_LONGVARBINARY oder ein langer datenquellenspezifischer Datentyp) als mit dem argument StrLen_or_IndPtr in SQLBindParameter angegeben.

Der SQL_NEED_LONG_DATA_LEN Informationstyp in SQLGetInfo war "Y", und weniger Daten wurden für eine lange Spalte gesendet (der Datentyp wurde SQL_LONGVARCHAR, SQL_LONGVARBINARY oder ein langer datenquellenspezifischer Datentyp) als im Längenpuffer angegeben, der einer Spalte in einer Zeile mit Daten entspricht, die mit SQLBulkOperations hinzugefügt oder mit SQLSetPos aktualisiert oder aktualisiert wurde.
40001 Serialisierungsfehler Die Transaktion wurde aufgrund eines Ressourcen-Deadlocks mit einer anderen Transaktion zurückgesetzt.
40003 Abschluss der Anweisung unbekannt Fehler bei der zugehörigen Verbindung während der Ausführung dieser Funktion, 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 dessen Ursache.
HY001 Speicherzuweisungsfehler 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 bevor sie die Ausführung abgeschlossen hat, wurde SQLCancel oder SQLCancelHandle für das StatementHandle aufgerufen. Die Funktion wurde dann erneut für die Anweisungshandle aufgerufen.

Die Funktion wurde aufgerufen, und bevor sie die Ausführung abgeschlossen hat, wurde SQLCancel oder SQLCancelHandle für das StatementHandle von 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 war, 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 den Verbindungshandle aufgerufen, der dem StatementHandle zugeordnet ist. Diese asynchrone Funktion wurde noch ausgeführt, als die SQLParamData-Funktion 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 das StatementHandle aufgerufen und SQL_NEED_DATA zurückgegeben. SQLCancel wurde aufgerufen, bevor Daten für alle Daten bei ausführungsparametern oder -spalten gesendet wurden.
HY013 Speicherverwaltungsfehler Der Funktionsaufruf konnte nicht verarbeitet werden, da auf die zugrunde liegenden Speicherobjekte nicht zugegriffen werden konnte, möglicherweise aufgrund geringer Arbeitsspeicherbedingungen.
HY117 Die Verbindung wird aufgrund des unbekannten Transaktionsstatus angehalten. Es sind nur Trenn- und schreibgeschützte Funktionen zulässig. (DM) Weitere Informationen zum angehaltenen Zustand finden Sie unter SQLEndTran Function.
HYT01 Verbindungstimeout abgelaufen Der Zeitraum für das Verbindungstimeout ist abgelaufen, bevor die Datenquelle auf die Anforderung geantwortet hat. Der Verbindungstimeoutzeitraum wird über SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT festgelegt.
IM001 Dieser Treiber unterstützt diese Funktion nicht. (DM) Der Treiber, der der StatementHandle entspricht, unterstützt die Funktion nicht.
IM017 Die Abrufung ist im asynchronen Benachrichtigungsmodus deaktiviert. Immer wenn das Benachrichtigungsmodell verwendet wird, ist die Abrufung 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 Nachbearbeitung durchzuführen und den Vorgang abzuschließen.

Wenn SQLParamData beim Senden von Daten für einen Parameter in einer SQL-Anweisung aufgerufen wird, kann jede SQLSTATE zurückgegeben werden, die von der Funktion zurückgegeben werden kann, die aufgerufen wird, um die Anweisung auszuführen (SQLExecute oder SQLExecDirect). Wenn sie beim Senden von Daten für eine Spalte aufgerufen wird, die aktualisiert oder mit SQLBulkOperations hinzugefügt oder mit SQLSetPos aktualisiert wird, kann jeder SQLSTATE zurückgegeben werden, der von SQLBulkOperations oder SQLSetPos zurückgegeben werden kann.

Kommentare

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

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

Gebundener Adressbindungsoffset + (Zeilennummer - 1) x Elementgröße) +

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

Variable Beschreibung
Gebundene Adresse Die Adresse, die mit dem TargetValuePtr-Argument in SQLBindCol angegeben wurde.
Bindungsoffset Der wert, der an der adresse gespeichert ist, die mit dem attribut SQL_ATTR_ROW_BIND_OFFSET_PTR-Anweisung angegeben ist.
Row Number Die 1-basierte Nummer der Zeile im Rowset. Bei Einzeilenabrufen, bei denen es sich um die Standardeinstellung handelt, ist dies 1.
Elementgröße Der Wert des attributs der SQL_ATTR_ROW_BIND_TYPE-Anweisung für Daten- und Längen-/Indikatorpuffer.

Sie gibt auch SQL_NEED_DATA zurück, bei dem es sich um einen Indikator für die Anwendung handelt, mit dem 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 bei ausführungsdaten für alle Parameter oder Spalten gesendet wurden, gibt SQLParamData SQL_SUCCESS oder SQL_SUCCESS_WITH_INFO zurück, der Wert in *ValuePtrPtr 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 Aktualisierungs- oder Löschanweisung 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 "Passing Parameter Values" in SQLBindParameter and Sending Long Data. Weitere Informationen zum Aktualisieren oder Hinzufügen von Daten zur Ausführung von Spaltendaten finden Sie im Abschnitt "Using SQLSetPos" in SQLSetPos, "Performing Bulk Updates 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 verfügbar hat. Weitere Informationen zu SQL_PARAM_DATA_AVAILABLE und gestreamten Ausgabeparametern finden Sie unter Abrufen von Ausgabeparametern mithilfe von SQLGetData.

Codebeispiel

Siehe SQLPutData.

Weitere Informationen zu Siehe
Binden eines Puffers an einen Parameter SQLBindParameter-Funktion
Abbrechen der Verarbeitung von Anweisungen 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