SQLBindParameter-Funktion

Konformität
Version eingeführt: ODBC 2.0-Standardscompliance: ODBC

Zusammenfassung
SQLBindParameter bindet einen Puffer an eine Parametermarkierung in einer SQL-Anweisung. SQLBindParameter unterstützt die Bindung an einen Unicode C-Datentyp, auch wenn der zugrunde liegende Treiber Unicode-Daten nicht unterstützt.

Syntax

  
SQLRETURN SQLBindParameter(  
      SQLHSTMT        StatementHandle,  
      SQLUSMALLINT    ParameterNumber,  
      SQLSMALLINT     InputOutputType,  
      SQLSMALLINT     ValueType,  
      SQLSMALLINT     ParameterType,  
      SQLULEN         ColumnSize,  
      SQLSMALLINT     DecimalDigits,  
      SQLPOINTER      ParameterValuePtr,  
      SQLLEN          BufferLength,  
      SQLLEN *        StrLen_or_IndPtr);  

Argumente

StatementHandle
[Eingabe] Anweisungshandle.

ParameterNumber
[Eingabe] Parameternummer, sequenziell in zunehmender Parameterreihenfolge sortiert, beginnend bei 1.

InputOutputType
[Eingabe] Der Typ des Parameters. Weitere Informationen finden Sie unter "InputOutputType Argument" in "Comments".

ValueType
[Eingabe] Der C-Datentyp des Parameters. Weitere Informationen finden Sie unter "ValueType Argument" in "Comments".

ParameterType
[Eingabe] Der SQL-Datentyp des Parameters. Weitere Informationen finden Sie unter "ParameterType Argument" in "Comments".

ColumnSize
[Eingabe] Die Größe der Spalte oder des Ausdrucks der entsprechenden Parametermarkierung. Weitere Informationen finden Sie unter "ColumnSize-Argument " in "Kommentare".

Wenn Ihre Anwendung auf einem 64-Bit-Windows-Betriebssystem ausgeführt wird, lesen Sie ODBC 64-Bit-Informationen.

DecimalDigits
[Eingabe] Die Dezimalziffern der Spalte oder des Ausdrucks der entsprechenden Parametermarkierung. Weitere Informationen zur Spaltengröße finden Sie unter "Spaltengröße", "Dezimalziffern", "Oktettlänge übertragen" und "Anzeigegröße".

ParameterValuePtr
[Verzögerte Eingabe] Ein Zeiger auf einen Puffer für die Daten des Parameters. Weitere Informationen finden Sie unter "ParameterValuePtr Argument" in "Comments".

BufferLength
[Eingabe/Ausgabe] Länge des ParameterValuePtr-Puffers in Bytes. Weitere Informationen finden Sie unter "BufferLength Argument" in "Comments".

Siehe ODBC 64-Bit-Informationen, wenn Ihre Anwendung auf einem 64-Bit-Betriebssystem ausgeführt wird.

StrLen_or_IndPtr
[Verzögerte Eingabe] Ein Zeiger auf einen Puffer für die Länge des Parameters. Weitere Informationen finden Sie unter "StrLen_or_IndPtr Argument" in "Kommentare".

Gibt zurück

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR oder SQL_INVALID_HANDLE.

Diagnostik

Wenn SQLBindParameter 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 SQLBindParameter 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.

Kommentare

Eine Anwendung ruft SQLBindParameter auf, um jede Parametermarkierung in einer SQL-Anweisung zu binden. Bindungen bleiben wirksam, bis die Anwendung SQLBindParameter erneut aufruft, SQLFreeStmt mit der option SQL_RESET_PARAMS aufruft oder SQLSetDescField aufruft, um das SQL_DESC_COUNT Kopfzeilenfeld der APD auf 0 festzulegen.

Weitere Informationen zu Parametern finden Sie unter "Anweisungsparameter". Weitere Informationen zu Parameterdatentypen und Parametermarkierungen finden Sie in Anhang C: SQL Grammar unter Parameterdatentypen und Parametermarkierungen .

ParameterNumber-Argument

Wenn ParameterNumber im Aufruf von SQLBindParameter größer als der Wert von SQL_DESC_COUNT ist, wird SQLSetDescField aufgerufen, um den Wert von SQL_DESC_COUNT auf ParameterNumber zu erhöhen.

InputOutputType-Argument

Das Argument InputOutputType gibt den Typ des Parameters an. Dieses Argument legt das SQL_DESC_PARAMETER_TYPE Feld der IPD fest. Alle Parameter in SQL-Anweisungen, die keine Prozeduren aufrufen, z. B. INSERT-Anweisungen, sind Eingabeparameter. Parameter in Prozeduraufrufen können Eingabe-, Eingabe-/Ausgabe- oder Ausgabeparameter sein. (Eine Anwendung ruft SQLProcedureColumns zum Bestimmen des Typs eines Parameters in einem Prozeduraufruf; Parameter, deren Typ nicht bestimmt werden kann, werden als Eingabeparameter angenommen.)

Das InputOutputType-Argument ist einer der folgenden Werte:

• SQL_PARAM_INPUT. Der Parameter kennzeichnet einen Parameter in einer SQL-Anweisung, die keine Prozedur aufruft, z. B. eine INSERT-Anweisung , oder einen Eingabeparameter in einer Prozedur markiert. Beispielsweise sind die Parameter in INSERT INTO Employee VALUES (?, ?, ?) Eingabeparameter, während die Parameter in {call AddEmp(?, ?, ?)} eingabeparameter sein können, aber nicht unbedingt Eingabeparameter sind.

  Wenn die Anweisung ausgeführt wird, sendet der Treiber Daten für den Parameter an die Datenquelle; Der *ParameterValuePtr-Puffer muss einen gültigen Eingabewert enthalten, oder der *StrLen_or_IndPtr Puffer muss SQL_NULL_DATA, SQL_DATA_AT_EXEC oder das Ergebnis des SQL_LEN_DATA_AT_EXEC Makros enthalten.

  Wenn eine Anwendung den Typ eines Parameters in einem Prozeduraufruf nicht ermitteln kann, legt sie InputOutputType auf SQL_PARAM_INPUT fest. Wenn die Datenquelle einen Wert für den Parameter zurückgibt, verwirft der Treiber ihn.

• SQL_PARAM_INPUT_OUTPUT. Der Parameter kennzeichnet einen Eingabe-/Ausgabeparameter in einer Prozedur. Der Parameter in {call GetEmpDept(?)} ist beispielsweise ein Eingabe-/Ausgabeparameter, der den Namen eines Mitarbeiters akzeptiert und den Namen der Abteilung des Mitarbeiters zurückgibt.

  Wenn die Anweisung ausgeführt wird, sendet der Treiber Daten für den Parameter an die Datenquelle; Der *ParameterValuePtr-Puffer muss einen gültigen Eingabewert enthalten, oder der *StrLen_or_IndPtr Puffer muss SQL_NULL_DATA, SQL_DATA_AT_EXEC oder das Ergebnis des SQL_LEN_DATA_AT_EXEC Makros enthalten. Nachdem die Anweisung ausgeführt wurde, gibt der Treiber Daten für den Parameter an die Anwendung zurück. wenn die Datenquelle keinen Wert für einen Eingabe-/Ausgabeparameter zurückgibt, legt der Treiber den Puffer *StrLen_or_IndPtr auf SQL_NULL_DATA fest.

  Hinweis

  Wenn eine ODBC 1.0-Anwendung SQLSetParam in einem ODBC 2.0-Treiber aufruft, konvertiert der Treiber-Manager dies in einen Aufruf von SQLBindParameter, in dem das InputOutputType-Argument auf SQL_PARAM_INPUT_OUTPUT festgelegt ist.

• SQL_PARAM_OUTPUT. Der Parameter kennzeichnet den Rückgabewert einer Prozedur oder eines Ausgabeparameters in einer Prozedur; in beiden Fällen werden diese als Ausgabeparameter bezeichnet. Der Parameter in {?=call GetNextEmpID} ist beispielsweise ein Ausgabeparameter, der die nächste Mitarbeiter-ID zurückgibt.

  Nachdem die Anweisung ausgeführt wurde, gibt der Treiber Daten für den Parameter an die Anwendung zurück, es sei denn, die Argumente ParameterValuePtr und StrLen_or_IndPtr sind nullzeiger, in diesem Fall verwirft der Treiber den Ausgabewert. Wenn die Datenquelle keinen Wert für einen Ausgabeparameter zurückgibt, legt der Treiber den Puffer *StrLen_or_IndPtr auf SQL_NULL_DATA fest.

• SQL_PARAM_INPUT_OUTPUT_STREAM. Gibt an, dass ein Eingabe-/Ausgabeparameter gestreamt werden soll. SQLGetData kann Parameterwerte in Teilen lesen. BufferLength wird ignoriert, da die Pufferlänge beim Aufruf von SQLGetData bestimmt wird. Der Wert des StrLen_or_IndPtr Puffers muss SQL_NULL_DATA, SQL_DEFAULT_PARAM, SQL_DATA_AT_EXEC oder das Ergebnis des SQL_LEN_DATA_AT_EXEC Makros enthalten. Ein Parameter muss als DAE-Parameter (Data-at-Execution) bei der Eingabe gebunden werden, wenn er bei der Ausgabe gestreamt wird. ParameterValuePtr kann ein beliebiger Nicht-Null-Zeigerwert sein, der von SQLParamData als benutzerdefiniertes Token zurückgegeben wird, dessen Wert für Eingabe und Ausgabe mit ParameterValuePtr übergeben wurde. Weitere Informationen finden Sie unter Abrufen von Ausgabeparametern mit SQLGetData.

• SQL_PARAM_OUTPUT_STREAM. Identisch mit SQL_PARAM_INPUT_OUTPUT_STREAM für einen Ausgabeparameter. * StrLen_or_IndPtr wird bei der Eingabe ignoriert.

In der folgenden Tabelle sind verschiedene Kombinationen von InputOutputType und *StrLen_or_IndPtr aufgeführt:

ValueType-Argument

Das Argument ValueType gibt den Datentyp C des Parameters an. Dieses Argument legt die Felder SQL_DESC_TYPE, SQL_DESC_CONCISE_TYPE und SQL_DESC_DATETIME_INTERVAL_CODE der APD fest. Dies muss einer der Werte im Abschnitt "C-Datentypen " in Anhang D: Datentypen sein.

Wenn das Argument ValueType eines der Intervalldatentypen ist, wird das SQL_DESC_TYPE Feld des ParameterWert-Datensatzes der APD auf SQL_INTERVAL festgelegt, das SQL_DESC_CONCISE_TYPE Feld der APD auf den prägnanten Intervalldatentyp festgelegt, und das SQL_DESC_DATETIME_INTERVAL_CODE Feld des ParameterWert-Datensatzes wird auf einen Untercode für den spezifischen Intervalldatentyp festgelegt. (Siehe Anhang D: Datentypen.) Die Standardintervallpräzision (2) und die Standardintervallsekundengenauigkeit (6), wie in den Feldern SQL_DESC_DATETIME_INTERVAL_PRECISION und SQL_DESC_PRECISION der APD festgelegt, werden für die Daten verwendet. Wenn die Standardgenauigkeit nicht geeignet ist, sollte die Anwendung das Deskriptorfeld explizit durch einen Aufruf von SQLSetDescField oder SQLSetDescRec festlegen.

Wenn das Argument ValueType eines der Datetime-Datentypen ist, wird das SQL_DESC_TYPE Feld des ParameterWert-Datensatzes der APD auf SQL_DATETIME festgelegt, wird das SQL_DESC_CONCISE_TYPE Feld des ParameterWert-Datensatzes der APD auf den präzisen Datentyp "Datetime C" festgelegt, und das SQL_DESC_DATETIME_INTERVAL_CODE Feld des ParameterWert-Datensatzes wird auf einen Untercode für den bestimmten Datetime-Datentyp festgelegt. (Siehe Anhang D: Datentypen.)

Wenn das ValueType-Argument ein SQL_C_NUMERIC Datentyp ist, werden die Standardgenauigkeit (treiberdefiniert) und die Standardskala (0) wie in den Feldern SQL_DESC_PRECISION und SQL_DESC_SCALE der APD für die Daten verwendet. Wenn die Standardgenauigkeit oder -skalierung nicht geeignet ist, sollte die Anwendung das Deskriptorfeld explizit durch einen Aufruf von SQLSetDescField oder SQLSetDescRec festlegen.

SQL_C_DEFAULT gibt an, dass der Parameterwert vom Standardmäßigen C-Datentyp für den mit ParameterType angegebenen SQL-Datentyp übertragen wird.

Sie können auch einen erweiterten C-Datentyp angeben. Weitere Informationen finden Sie unter C-Datentypen in ODBC.

Weitere Informationen finden Sie unter Standard-C-Datentypen, Konvertieren von Daten aus C in SQL-Datentypen und Konvertieren von Daten aus SQL in C-Datentypen in Anhang D: Datentypen.

ParameterType-Argument

Dies muss einer der Werte sein, die im Abschnitt "SQL-Datentypen " von Anhang D: Datentypen aufgeführt sind, oder es muss sich um einen treiberspezifischen Wert handeln. Mit diesem Argument werden die Felder SQL_DESC_TYPE, SQL_DESC_CONCISE_TYPE und SQL_DESC_DATETIME_INTERVAL_CODE der IPD festgelegt.

Wenn das ParameterType-Argument einer der Datetime-IDs ist, wird das SQL_DESC_TYPE Feld der IPD auf SQL_DATETIME festgelegt, das SQL_DESC_CONCISE_TYPE Feld der IPD wird auf den präzisen SQL-Datentyp "datetime" festgelegt, und das feld SQL_DESC_DATETIME_INTERVAL_CODE wird auf den entsprechenden Wert für die Datumstime-Untercodierung festgelegt.

Wenn ParameterType einer der Intervallbezeichner ist, wird das SQL_DESC_TYPE Feld der IPD auf SQL_INTERVAL festgelegt, das SQL_DESC_CONCISE_TYPE Feld der IPD auf den präzisen SQL-Intervalldatentyp festgelegt, und das SQL_DESC_DATETIME_INTERVAL_CODE Feld der IPD wird auf die entsprechende Intervalluntercodierung festgelegt. Das SQL_DESC_DATETIME_INTERVAL_PRECISION Feld der IPD wird auf die Intervallpräzision festgelegt, und das feld SQL_DESC_PRECISION wird ggf. auf die Genauigkeit von Intervall sekunden festgelegt. Wenn der Standardwert von SQL_DESC_DATETIME_INTERVAL_PRECISION oder SQL_DESC_PRECISION nicht geeignet ist, sollte die Anwendung sie explizit durch Aufrufen von SQLSetDescField festlegen. Weitere Informationen zu einem dieser Felder finden Sie unter SQLSetDescField.

Wenn das ValueType-Argument ein SQL_NUMERIC Datentyp ist, werden die Standardgenauigkeit (treiberdefiniert) und die Standardskala (0) wie in den Feldern SQL_DESC_PRECISION und SQL_DESC_SCALE der IPD für die Daten verwendet. Wenn die Standardgenauigkeit oder -skalierung nicht geeignet ist, sollte die Anwendung das Deskriptorfeld explizit durch einen Aufruf von SQLSetDescField oder SQLSetDescRec festlegen.

Informationen dazu, wie Daten konvertiert werden, finden Sie unter Konvertieren von Daten aus C in SQL-Datentypen und Konvertieren von Daten aus SQL in C-Datentypen in Anhang D: Datentypen.

ColumnSize-Argument

Das ColumnSize-Argument gibt die Größe der Spalte oder des Ausdrucks an, die der Parametermarkierung, der Länge dieser Daten oder beides entspricht. Dieses Argument legt je nach SQL-Datentyp (ParameterType-Argument) unterschiedliche Felder der IPD fest. Die folgenden Regeln gelten für diese Zuordnung:

• Wenn ParameterType SQL_CHAR, SQL_VARCHAR, SQL_LONGVARCHAR, SQL_BINARY, SQL_VARBINARY, SQL_LONGVARBINARY oder einer der prägnanten SQL-Datentypen für Datums- oder Intervalldaten ist, wird das feld SQL_DESC_LENGTH der IPD auf den Wert von ColumnSize festgelegt. (Weitere Informationen finden Sie unter Spaltengröße, Dezimalziffern, Abschnitt "Oktettlänge übertragen" und Abschnitt "Anzeigegröße " in Anhang D: Datentypen.)

• Wenn ParameterType SQL_DECIMAL, SQL_NUMERIC, SQL_FLOAT, SQL_REAL oder SQL_DOUBLE ist, wird das SQL_DESC_PRECISION Feld der IPD auf den Wert von ColumnSize festgelegt.

• Bei anderen Datentypen wird das Argument ColumnSize ignoriert.

Weitere Informationen finden Sie unter "Übergeben von Parameterwerten" und SQL_DATA_AT_EXEC in "StrLen_or_IndPtr Argument".

DecimalDigits-Argument

Wenn ParameterType SQL_TYPE_TIME, SQL_TYPE_TIMESTAMP, SQL_INTERVAL_SECOND, SQL_INTERVAL_DAY_TO_SECOND, SQL_INTERVAL_HOUR_TO_SECOND oder SQL_INTERVAL_MINUTE_TO_SECOND ist, wird das feld SQL_DESC_PRECISION der IPD auf DecimalDigits festgelegt. Wenn ParameterType SQL_NUMERIC oder SQL_DECIMAL ist, wird das SQL_DESC_SCALE Feld der IPD auf DecimalDigits festgelegt. Für alle anderen Datentypen wird das Argument DecimalDigits ignoriert.

ParameterValuePtr-Argument

Das ParameterValuePtr-Argument verweist auf einen Puffer, der beim Aufrufen von SQLExecute oder SQLExecDirect die tatsächlichen Daten für den Parameter enthält. Die Daten müssen in dem formular sein, das durch das ValueType-Argument angegeben wird. Dieses Argument legt das SQL_DESC_DATA_PTR Feld der APD fest. Eine Anwendung kann das ParameterValuePtr-Argument auf einen Nullzeiger festlegen, solange *StrLen_or_IndPtr SQL_NULL_DATA oder SQL_DATA_AT_EXEC ist. (Dies gilt nur für Eingabe- oder Eingabe-/Ausgabeparameter.)

Wenn *StrLen_or_IndPtr das Ergebnis des Makros SQL_LEN_DATA_AT_EXEC(Länge) oder SQL_DATA_AT_EXEC ist, ist ParameterValuePtr ein anwendungsdefinierter Zeigerwert, der dem Parameter zugeordnet ist. Sie wird über SQLParamData an die Anwendung zurückgegeben. ParameterValuePtr kann z. B. ein Nicht-Null-Token wie eine Parameternummer, ein Zeiger auf Daten oder ein Zeiger auf eine Struktur sein, die von der Anwendung zum Binden von Eingabeparametern verwendet wurde. Beachten Sie jedoch, dass ParameterValuePtr ein Zeiger auf einen Puffer sein muss, in dem der Ausgabewert gespeichert wird, wenn der Parameter ein Eingabe-/Ausgabeparameter ist. Wenn der Wert im attribut der SQL_ATTR_PARAMSET_SIZE-Anweisung größer als 1 ist, kann die Anwendung den Wert verwenden, auf den die SQL_ATTR_PARAMS_PROCESSED_PTR-Anweisungsattribut verweist, zusammen mit dem ParameterValuePtr-Argument . ParameterValuePtr kann z. B. auf ein Array von Werten zeigen, und die Anwendung kann den Wert verwenden, auf den SQL_ATTR_PARAMS_PROCESSED_PTR verweist, um den richtigen Wert aus dem Array abzurufen. Weitere Informationen finden Sie weiter unten in diesem Abschnitt unter "Übergeben von Parameterwerten".

Wenn das InputOutputType-Argument SQL_PARAM_INPUT_OUTPUT oder SQL_PARAM_OUTPUT ist, verweist ParameterValuePtr auf einen Puffer, in dem der Treiber den Ausgabewert zurückgibt. Wenn die Prozedur einen oder mehrere Resultsets zurückgibt, wird der *ParameterValuePtr-Puffer erst festgelegt, wenn alle Resultsets/Zeilenanzahlen verarbeitet wurden. Wenn der Puffer erst festgelegt wird, wenn die Verarbeitung abgeschlossen ist, sind die Ausgabeparameter und Rückgabewerte erst verfügbar, wenn SQLMoreResults SQL_NO_DATA zurückgibt. Wenn Sie SQLCloseCursor oder SQLFreeStmt mit einer Option von SQL_CLOSE aufrufen, werden diese Werte verworfen.

Wenn der Wert im attribut der SQL_ATTR_PARAMSET_SIZE-Anweisung größer als 1 ist, verweist ParameterValuePtr auf ein Array. Eine einzelne SQL-Anweisung verarbeitet das vollständige Array von Eingabewerten für einen Eingabe- oder Eingabe-/Ausgabeparameter und gibt ein Array von Ausgabewerten für einen Eingabe-/Ausgabeparameter zurück.

BufferLength-Argument

Für Zeichen- und Binäre C-Daten gibt das Argument BufferLength die Länge des *ParameterValuePtr-Puffers (wenn es sich um ein einzelnes Element handelt) oder die Länge eines Elements im *ParameterValuePtr-Array an (wenn der Wert im attribut der SQL_ATTR_PARAMSET_SIZE-Anweisung größer als 1 ist). Mit diesem Argument wird das SQL_DESC_OCTET_LENGTH Datensatzfeld der APD festgelegt. Wenn die Anwendung mehrere Werte angibt, wird BufferLength verwendet, um die Position von Werten im *ParameterValuePtr-Array zu bestimmen, sowohl für die Eingabe als auch für die Ausgabe. Bei Eingabe-/Ausgabe- und Ausgabeparametern wird ermittelt, ob zeichen- und binäre C-Daten für die Ausgabe abgeschnitten werden sollen:

• Wenn für Zeichen C-Daten die Anzahl der zurückzugebenden Bytes größer oder gleich BufferLength ist, werden die Daten in "*ParameterValuePtr " auf "BufferLength " abgeschnitten und vom Treiber null beendet.

• Wenn bei binären C-Daten die Anzahl der zurückzugebenden Bytes größer als BufferLength ist, werden die Daten in "*ParameterValuePtr " in "BufferLength Bytes" abgeschnitten.

Für alle anderen Typen von C-Daten wird das Argument BufferLength ignoriert. Die Länge des *ParameterValuePtr-Puffers (wenn es sich um ein einzelnes Element handelt) oder die Länge eines Elements im *ParameterValuePtr-Array (wenn die Anwendung SQLSetStmtAttr mit einem Attributargument von SQL_ATTR_PARAMSET_SIZE aufruft, um mehrere Werte für jeden Parameter anzugeben) wird als Länge des C-Datentyps angenommen.

Bei gestreamten Ausgabe- oder Streameingabe-/Ausgabeparametern wird das Argument BufferLength ignoriert, da die Pufferlänge in SQLGetData angegeben ist.

StrLen_or_IndPtr Argument

Das argument StrLen_or_IndPtr verweist auf einen Puffer, der, wenn SQLExecute oder SQLExecDirect aufgerufen wird, einen der folgenden Enthält. (Mit diesem Argument werden die SQL_DESC_OCTET_LENGTH_PTR- und SQL_DESC_INDICATOR_PTR Datensatzfelder der Zeiger des Anwendungsparameters festgelegt.)

• Die Länge des parameterwerts, der in *ParameterValuePtr gespeichert ist. Dies wird außer zeichen- oder binären C-Daten ignoriert.

• SQL_NTS. Der Parameterwert ist eine mit Null beendete Zeichenfolge.

• SQL_NULL_DATA. Der Parameterwert ist NULL.

• SQL_DEFAULT_PARAM. Eine Prozedur besteht darin, den Standardwert eines Parameters anstelle eines aus der Anwendung abgerufenen Werts zu verwenden. Dieser Wert ist nur in einer Prozedur gültig, die in der kanonischen ODBC-Syntax aufgerufen wird, und dann nur, wenn das InputOutputType-Argument SQL_PARAM_INPUT, SQL_PARAM_INPUT_OUTPUT oder SQL_PARAM_INPUT_OUTPUT_STREAM ist. Wenn *StrLen_or_IndPtr SQL_DEFAULT_PARAM ist, werden die Argumente ValueType, ParameterType, ColumnSize, DecimalDigits, BufferLength und ParameterValuePtr für Eingabeparameter ignoriert und nur zum Definieren des Ausgabeparameterwerts für Eingabe-/Ausgabeparameter verwendet.

• Das Ergebnis des makros SQL_LEN_DATA_AT_EXEC(länge) Die Daten für den Parameter werden mit SQLPutData gesendet. Wenn das ParameterType-Argument SQL_LONGVARBINARY, SQL_LONGVARCHAR oder einen langen datenquellenspezifischen Datentyp ist und der Treiber "Y" für den SQL_NEED_LONG_DATA_LEN Informationstyp in SQLGetInfo zurückgibt, ist die Länge die Anzahl der Bytes, die für den Parameter gesendet werden sollen. Andernfalls muss die Länge ein nicht negativer Wert sein und ignoriert werden. Weitere Informationen finden Sie weiter unten in diesem Abschnitt unter "Übergeben von Parameterwerten".

  Um beispielsweise anzugeben, dass 10.000 Byte mit SQLPutData in einem oder mehreren Aufrufen für einen SQL_LONGVARCHAR-Parameter gesendet werden, legt eine Anwendung *StrLen_or_IndPtr auf SQL_LEN_DATA_AT_EXEC(10000) fest.

• SQL_DATA_AT_EXEC. Die Daten für den Parameter werden mit SQLPutData gesendet. Dieser Wert wird von ODBC 1.0-Anwendungen verwendet, wenn sie ODBC 3 aufrufen.x-Treiber . Weitere Informationen finden Sie weiter unten in diesem Abschnitt unter "Übergeben von Parameterwerten".

Wenn StrLen_or_IndPtr ein Nullzeiger ist, geht der Treiber davon aus, dass alle Eingabeparameterwerte ungleich NULL sind und dass zeichen- und binäre Daten null-beendet sind. Wenn InputOutputType SQL_PARAM_OUTPUT oder SQL_PARAM_OUTPUT_STREAM und ParameterValuePtr und StrLen_or_IndPtr beide Nullzeiger sind, verwirft der Treiber den Ausgabewert.

Wenn das InputOutputType-Argument SQL_PARAM_INPUT_OUTPUT, SQL_PARAM_OUTPUT, SQL_PARAM_INPUT_OUTPUT_STREAM oder SQL_PARAM_OUTPUT_STREAM ist, verweist StrLen_or_IndPtr auf einen Puffer, in dem der Treiber SQL_NULL_DATA zurückgibt, die Anzahl der Bytes, die in *ParameterValuePtr zurückgegeben werden können (mit Ausnahme des Nullendpunktbytes von Zeichendaten), oder SQL_NO_TOTAL (wenn die Anzahl der zurückzugebenden Bytes nicht bestimmt werden kann). Wenn die Prozedur einen oder mehrere Resultsets zurückgibt, wird der *StrLen_or_IndPtr Puffer erst festgelegt, wenn alle Ergebnisse abgerufen wurden.

Wenn der Wert im attribut der SQL_ATTR_PARAMSET_SIZE-Anweisung größer als 1 ist, verweist StrLen_or_IndPtr auf ein Array von SQLLEN-Werten. Hierbei kann es sich um einen der weiter oben in diesem Abschnitt aufgeführten Werte handeln und mit einer einzelnen SQL-Anweisung verarbeitet werden.

Übergeben von Parameterwerten

Eine Anwendung kann den Wert für einen Parameter entweder im *ParameterValuePtr-Puffer oder mit einem oder mehreren Aufrufen von SQLPutData übergeben. Parameter, deren Daten mit SQLPutData übergeben werden, werden als "data-at-execution "-Parameter bezeichnet. Diese werden in der Regel verwendet, um Daten für SQL_LONGVARBINARY und SQL_LONGVARCHAR Parameter zu senden und können mit anderen Parametern gemischt werden.

Um Parameterwerte zu übergeben, führt eine Anwendung die folgende Abfolge von Schritten aus:

1. Ruft SQLBindParameter für jeden Parameter auf, um Puffer für den Wert des Parameters (ParameterValuePtr-Argument ) und länge/Indikator (StrLen_or_IndPtr Argument) zu binden. Für Daten bei Ausführungsparametern ist ParameterValuePtr ein anwendungsdefinierter Zeigerwert, z. B. eine Parameternummer oder ein Zeiger auf Daten. Der Wert wird später zurückgegeben und kann verwendet werden, um den Parameter zu identifizieren.

2. Platziert Werte für Eingabe- und Eingabe-/Ausgabeparameter in den Puffern *ParameterValuePtr und *StrLen_or_IndPtr :

   • Bei normalen Parametern platziert die Anwendung den Parameterwert im *ParameterValuePtr-Puffer und die Länge dieses Werts im *StrLen_or_IndPtr Puffer. Weitere Informationen finden Sie unter Festlegen von Parameterwerten.

   • Bei Datenausführungsparametern platziert die Anwendung das Ergebnis des Makros SQL_LEN_DATA_AT_EXEC(Länge) (beim Aufrufen eines ODBC 2.0-Treibers) im *StrLen_or_IndPtr-Puffer .

3. Ruft SQLExecute oder SQLExecDirect auf, um die SQL-Anweisung auszuführen.

   • Wenn keine Data-at-Execution-Parameter vorhanden sind, ist der Prozess abgeschlossen.

   • Wenn Daten bei ausführungsparametern vorhanden sind, gibt die Funktion SQL_NEED_DATA zurück.

4. Ruft SQLParamData auf, um den im ParameterValuePtr-Argument von SQLBindParameter angegebenen anwendungsdefinierten Wert abzurufen, damit der erste zu verarbeitende Data-at-Execution-Parameter verarbeitet werden kann. SQLParamData gibt SQL_NEED_DATA zurück.

   Hinweis

   Obwohl Daten bei ausführungsparametern daten at-execution-Spalten ähneln, ist der von SQLParamData zurückgegebene Wert für jeden unterschiedlich. Daten bei ausführungsparametern sind Parameter in einer SQL-Anweisung, für die Daten mit SQLPutData gesendet werden, wenn die Anweisung mit SQLExecDirect oder SQLExecute ausgeführt wird. Sie sind mit SQLBindParameter gebunden. Der von SQLParamData zurückgegebene Wert ist ein Zeigerwert, der im ParameterValuePtr-Argument an SQLBindParameter übergeben wird. Bei Datenausführungsspalten handelt es sich um Spalten in einem Rowset, für die Daten mit SQLPutData gesendet werden, wenn eine Zeile mit SQLBulkOperations aktualisiert oder mit SQLSetPos aktualisiert oder aktualisiert wird. Sie sind mit SQLBindCol gebunden. Der von SQLParamData zurückgegebene Wert ist die Adresse der Zeile im *TargetValuePtr-Puffer (durch einen Aufruf von SQLBindCol festgelegt), der verarbeitet wird.

5. Ruft SQLPutData einmal auf, um Daten für den Parameter zu senden. Mehrere Aufrufe sind erforderlich, wenn der Datenwert größer als der in SQLPutData angegebene *ParameterValuePtr-Puffer ist. Mehrere Aufrufe von SQLPutData für denselben Parameter sind nur zulässig, wenn Zeichen C-Daten an eine Spalte mit einem Zeichen, einer Binärdatei oder einem datenquellenspezifischen Datentyp oder beim Senden von Binären C-Daten an eine Spalte mit einem Zeichen gesendet werden, binär oder datenquellenspezifischer Datentyp.

6. Ruft SQLParamData erneut auf, um zu signalisieren, dass alle Daten für den Parameter gesendet wurden.

   • Wenn weitere Data-at-Execution-Parameter vorhanden sind, gibt SQLParamData SQL_NEED_DATA und den anwendungsdefinierten Wert für den nächsten zu verarbeitenden Data-at-Execution-Parameter zurück. Die Anwendung wiederholt die Schritte 4 und 5.

   • Wenn keine datenbasierten Parameter mehr vorhanden sind, ist der Prozess abgeschlossen. Wenn die Anweisung erfolgreich ausgeführt wurde, gibt SQLParamData SQL_SUCCESS oder SQL_SUCCESS_WITH_INFO zurück. Wenn die Ausführung fehlgeschlagen ist, wird SQL_ERROR zurückgegeben. Zu diesem Zeitpunkt kann SQLParamData jeden SQLSTATE-Wert zurückgeben, der von der Funktion zurückgegeben werden kann, die zum Ausführen der Anweisung verwendet wird (SQLExecDirect oder SQLExecute).

     Ausgabewerte für alle Eingabe-/Ausgabeparameter sind in den Puffern *ParameterValuePtr und *StrLen_or_IndPtr verfügbar, nachdem die Anwendung alle von der Anweisung generierten Resultsets abgerufen hat.

Durch Aufrufen von SQLExecute oder SQLExecDirect wird die Anweisung in einen SQL_NEED_DATA Zustand versetzt. An diesem Punkt kann die Anwendung nur SQLCancel, SQLGetDiagField, SQLGetDiagRec, SQLGetFunctions, SQLParamData oder SQLPutData mit der Anweisung oder dem Verbindungshandle aufrufen, das der Anweisung zugeordnet ist. Wenn sie eine andere Funktion mit der Anweisung oder der Verbindung aufruft, die der Anweisung zugeordnet ist, gibt die Funktion SQLSTATE HY010 (Funktionssequenzfehler) zurück. Die Anweisung verlässt den SQL_NEED_DATA Zustand, wenn SQLParamData oder SQLPutData einen Fehler zurückgibt, SQLParamData SQL_SUCCESS oder SQL_SUCCESS_WITH_INFO zurückgibt oder die Anweisung abgebrochen wird.

Wenn die Anwendung SQLCancel aufruft, während der Treiber weiterhin Daten für Daten bei der Ausführung benötigt, bricht der Treiber die Ausführung der Anweisung ab; die Anwendung kann dann SQLExecute oder SQLExecDirect erneut aufrufen.

Abrufen von streamten Ausgabeparametern

Wenn eine Anwendung InputOutputType auf SQL_PARAM_INPUT_OUTPUT_STREAM oder SQL_PARAM_OUTPUT_STREAM festlegt, muss der Ausgabeparameterwert von einem oder mehreren Aufrufen von SQLGetData abgerufen werden. Wenn der Treiber über einen streamten Ausgabeparameterwert verfügt, der an die Anwendung zurückgegeben werden soll, wird SQL_PARAM_DATA_AVAILABLE als Reaktion auf einen Aufruf der folgenden Funktionen zurückgegeben: SQLMoreResults, SQLExecute und SQLExecDirect. Eine Anwendung ruft SQLParamData auf, um zu bestimmen, welcher Parameterwert verfügbar ist.

Weitere Informationen zu SQL_PARAM_DATA_AVAILABLE und gestreamten Ausgabeparametern finden Sie unter Abrufen von Ausgabeparametern mithilfe von SQLGetData.

Verwenden von Parameterarrays

Wenn eine Anwendung eine Anweisung mit Parametermarkierungen vorbereitet und ein Array von Parametern übergibt, gibt es zwei verschiedene Möglichkeiten, dies auszuführen. Eine Möglichkeit besteht darin, dass sich der Treiber auf die Arrayverarbeitungsfunktionen des Back-Ends stützt, in diesem Fall wird die gesamte Anweisung mit dem Array von Parametern als eine atomige Einheit behandelt. Oracle ist ein Beispiel für eine Datenquelle, die Arrayverarbeitungsfunktionen unterstützt. Eine weitere Möglichkeit zum Implementieren dieses Features besteht darin, dass der Treiber einen Batch von SQL-Anweisungen, eine SQL-Anweisung für jeden Satz von Parametern im Parameterarray generiert und den Batch ausführt. Arrays von Parametern können nicht mit einer UPDATE WHERE CURRENT OF-Anweisung verwendet werden.

Wenn ein Array von Parametern verarbeitet wird, können einzelne Resultsets/Zeilenanzahlen (eine für jeden Parametersatz) verfügbar sein, oder Ergebnissätze/Zeilenanzahlen können in einer bereitgestellt werden. Die option SQL_PARAM_ARRAY_ROW_COUNTS in SQLGetInfo gibt an, ob Zeilenanzahlen für jede Gruppe von Parametern (SQL_PARC_BATCH) verfügbar sind oder nur eine Zeilenanzahl verfügbar ist (SQL_PARC_NO_BATCH).

Die option SQL_PARAM_ARRAY_SELECTS in SQLGetInfo gibt an, ob für jeden Parametersatz (SQL_PAS_BATCH) ein Resultset verfügbar ist oder nur ein Resultset verfügbar ist (SQL_PAS_NO_BATCH). Wenn der Treiber die Ausführung einer Resultset-generierenden Anweisung mit einem Array von Parametern nicht zulässt, gibt SQL_PARAM_ARRAY_SELECTS SQL_PAS_NO_SELECT zurück.

Weitere Informationen finden Sie unter SQLGetInfo-Funktion.

Um Arrays von Parametern zu unterstützen, wird das attribut der SQL_ATTR_PARAMSET_SIZE-Anweisung festgelegt, um die Anzahl der Werte für jeden Parameter anzugeben. Wenn das Feld größer als 1 ist, müssen die Felder SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR und SQL_DESC_OCTET_LENGTH_PTR der APD auf Arrays verweisen. Die Kardinalität der einzelnen Arrays entspricht dem Wert SQL_ATTR_PARAMSET_SIZE.

Das SQL_DESC_ROWS_PROCESSED_PTR Feld der APD verweist auf einen Puffer, der die Anzahl der parameter enthält, die verarbeitet wurden, einschließlich Fehlersätzen. Während jeder Parametersatz verarbeitet wird, speichert der Treiber einen neuen Wert im Puffer. Wenn es sich um einen Nullzeiger handelt, wird keine Zahl zurückgegeben. Wenn Arrays von Parametern verwendet werden, wird der wert, auf den das feld SQL_DESC_ROWS_PROCESSED_PTR der APD verweist, auch dann aufgefüllt, wenn SQL_ERROR von der Einstellungsfunktion zurückgegeben wird. Wenn SQL_NEED_DATA zurückgegeben wird, wird der wert, auf den das feld SQL_DESC_ROWS_PROCESSED_PTR der APD verweist, auf den Satz von Parametern festgelegt, die verarbeitet werden.

Was auftritt, wenn ein Array von Parametern gebunden ist und eine UPDATE WHERE CURRENT OF-Anweisung ausgeführt wird, wird treiberdefiniert.

Column-Wise-Parameterbindung

In spaltenweiser Bindung bindet die Anwendung separate Parameter- und Längen-/Indikatorarrays an jeden Parameter.

Um die spaltenweise Bindung zu verwenden, legt die Anwendung zunächst das attribut der SQL_ATTR_PARAM_BIND_TYPE-Anweisung auf SQL_PARAM_BIND_BY_COLUMN fest. (Dies ist die Standardeinstellung.) Damit jede Spalte gebunden werden kann, führt die Anwendung die folgenden Schritte aus:

1. Weist ein Parameterpufferarray zu.

2. Weist ein Array von Längen-/Indikatorpuffern zu.

   Hinweis

   Wenn die Anwendung direkt in Deskriptoren schreibt, wenn spaltenweise Bindung verwendet wird, können separate Arrays für Längen- und Indikatordaten verwendet werden.

3. Ruft SQLBindParameter mit den folgenden Argumenten auf:

   • ValueType ist der C-Typ eines einzelnen Elements im Parameterpufferarray.

   • ParameterType ist der SQL-Typ des Parameters.

   • ParameterValuePtr ist die Adresse des Parameterpufferarrays.

   • BufferLength ist die Größe eines einzelnen Elements im Parameterpufferarray. Das Argument BufferLength wird ignoriert, wenn es sich bei den Daten um Daten mit fester Länge handelt.

   • StrLen_or_IndPtr ist die Adresse des Längen -/Indikatorarrays.

Weitere Informationen zur Verwendung dieser Informationen finden Sie unter "ParameterValuePtr Argument" in "Comments", weiter unten in diesem Abschnitt. Weitere Informationen zur spaltenweisen Bindung von Parametern finden Sie unter Binding Arrays of Parameters.

Row-Wise-Parameterbindung

In zeilenweiser Bindung definiert die Anwendung eine Struktur, die Parameter- und Längen-/Indikatorpuffer enthält, damit jeder Parameter gebunden werden kann.

Um zeilenweise Bindung zu verwenden, führt die Anwendung die folgenden Schritte aus:

1. Definiert eine Struktur, die einen einzelnen Satz von Parametern (einschließlich Parameter- und Längen-/Indikatorpuffern) enthält, und weist ein Array dieser Strukturen zu.

   Hinweis

   Wenn die Anwendung direkt in Deskriptoren schreibt, wenn zeilenweise Bindung verwendet wird, können separate Felder für Längen- und Indikatordaten verwendet werden.

2. Legt das attribut der SQL_ATTR_PARAM_BIND_TYPE-Anweisung auf die Größe der Struktur fest, die einen einzelnen Satz von Parametern oder die Größe einer Instanz eines Puffers enthält, an die die Parameter gebunden werden. Die Länge muss Platz für alle gebundenen Parameter und alle Abstände der Struktur oder des Puffers enthalten, um sicherzustellen, dass das Ergebnis auf den Anfang desselben Parameters in der nächsten Zeile zeigt, wenn die Adresse eines gebundenen Parameters mit der angegebenen Länge erhöht wird. Wenn Sie den Sizeof-Operator in ANSI C verwenden, ist dieses Verhalten garantiert.

3. Ruft SQLBindParameter mit den folgenden Argumenten für jeden zu bindenden Parameter auf:

   • ValueType ist der Typ des Parameterpufferelements, das an die Spalte gebunden werden soll.

   • ParameterType ist der SQL-Typ des Parameters.

   • ParameterValuePtr ist die Adresse des Parameterpufferelements im ersten Arrayelement.

   • BufferLength ist die Größe des Parameterpufferelements.

   • StrLen_or_IndPtr ist die Adresse des längen-/Indikatorelements, das gebunden werden soll.

Weitere Informationen zur Verwendung dieser Informationen finden Sie weiter unten in diesem Abschnitt unter "ParameterValuePtr-Argument ". Weitere Informationen zur zeilenweisen Bindung von Parametern finden Sie in den Bindungsarrays von Parametern.

Fehlerinformationen

Wenn ein Treiber Parameterarrays nicht als Batches implementiert (die option SQL_PARAM_ARRAY_ROW_COUNTS entspricht SQL_PARC_NO_BATCH), werden Fehlersituationen behandelt, als ob eine Anweisung ausgeführt wurde. Wenn der Treiber Parameterarrays als Batches implementiert, kann eine Anwendung das SQL_DESC_ARRAY_STATUS_PTR Headerfeld der IPD verwenden, um zu bestimmen, welcher Parameter einer SQL-Anweisung oder welcher Parameter in einem Array von Parametern dazu führte, dass SQLExecDirect oder SQLExecute einen Fehler zurückgibt. Dieses Feld enthält Statusinformationen für jede Zeile mit Parameterwerten. Wenn das Feld angibt, dass ein Fehler aufgetreten ist, geben Felder in der Diagnosedatenstruktur die Zeilen- und Parameternummer des fehlgeschlagenen Parameters an. Die Anzahl der Elemente im Array wird durch das SQL_DESC_ARRAY_SIZE Kopfzeilenfeld in der APD definiert, das durch das attribut SQL_ATTR_PARAMSET_SIZE-Anweisung festgelegt werden kann.

Wenn SQLExecute oder SQLExecDirect SQL_ERROR zurückgibt, enthalten die Elemente im Array, auf das das feld SQL_DESC_ARRAY_STATUS_PTR in der IPD verweist, SQL_PARAM_ERROR, SQL_PARAM_SUCCESS, SQL_PARAM_SUCCESS_WITH_INFO, SQL_PARAM_UNUSED oder SQL_PARAM_DIAG_UNAVAILABLE.

Für jedes Element in diesem Array enthält die Diagnosedatenstruktur mindestens einen Statusdatensätze. Das feld SQL_DIAG_ROW_NUMBER der Struktur gibt die Zeilennummer der Parameterwerte an, die den Fehler verursacht haben. Wenn es möglich ist, den bestimmten Parameter in einer Reihe von Parametern zu ermitteln, die den Fehler verursacht haben, wird die Parameternummer in das Feld SQL_DIAG_COLUMN_NUMBER eingegeben.

SQL_PARAM_UNUSED wird eingegeben, wenn ein Parameter nicht verwendet wurde, da in einem früheren Parameter ein Fehler aufgetreten ist, der SQLExecute oder SQLExecDirect zum Abbrechen gezwungen hat. Wenn z. B. 50 Parameter vorhanden sind und beim Ausführen der 10th-Gruppe von Parametern, die dazu geführt haben, dass SQLExecute oder SQLExecDirect abgebrochen wurde, wird SQL_PARAM_UNUSED in das Statusarray für Parameter 41 bis 50 eingegeben.

SQL_PARAM_DIAG_UNAVAILABLE wird eingegeben, wenn der Treiber Arrays von Parametern als monolithische Einheit behandelt, sodass diese einzelne Fehlerstufe nicht generiert wird.

Einige Fehler bei der Verarbeitung einer einzelnen Gruppe von Parametern führen dazu, dass die nachfolgenden Parametersätze im Array beendet werden. Andere Fehler wirken sich nicht auf die Verarbeitung nachfolgender Parameter aus. Welche Fehler die Verarbeitung beenden, ist treiberdefiniert. Wenn die Verarbeitung nicht beendet wird, werden alle Parameter im Array verarbeitet, SQL_SUCCESS_WITH_INFO wird als Ergebnis des Fehlers zurückgegeben, und der durch SQL_ATTR_PARAMS_PROCESSED_PTR definierte Puffer wird auf die Gesamtanzahl der verarbeiteten Parametersätze (gemäß definition durch das Attribut SQL_ATTR_PARAMSET_SIZE-Anweisung) festgelegt, der Fehlersätze enthält.

Wenn SQLExecute oder SQLExecDirect vor Abschluss der Verarbeitung aller Parametersätze in einem Parameterarray zurückgegeben werden, z. B. wenn SQL_ERROR oder SQL_NEED_DATA zurückgegeben wird, enthält das Statusarray Statuswerte für diese Parameter, die bereits verarbeitet wurden. Die Position, auf die das Feld SQL_DESC_ROWS_PROCESSED_PTR in der IPD verweist, enthält die Zeilennummer im Parameterarray, die den SQL_ERROR oder SQL_NEED_DATA Fehlercode verursacht hat. Wenn ein Array von Parametern an eine SELECT-Anweisung gesendet wird, wird die Verfügbarkeit von Statusarraywerten treiberdefiniert; sie sind möglicherweise verfügbar, nachdem die Anweisung ausgeführt wurde oder wenn Resultsets abgerufen werden.

Ignorieren einer Reihe von Parametern

Das SQL_DESC_ARRAY_STATUS_PTR Feld der APD (wie durch das Attribut der SQL_ATTR_PARAM_STATUS_PTR-Anweisung festgelegt) kann verwendet werden, um anzugeben, dass eine Reihe gebundener Parameter in einer SQL-Anweisung ignoriert werden soll. Um den Treiber anzuweisen, einen oder mehrere Parametersätze während der Ausführung zu ignorieren, sollte eine Anwendung die folgenden Schritte ausführen:

1. Rufen Sie SQLSetDescField auf, um das SQL_DESC_ARRAY_STATUS_PTR Kopfzeilenfeld der APD festzulegen, um auf ein Array von SQLUSMALLINT-Werten zu verweisen, die Statusinformationen enthalten sollen. Dieses Feld kann auch durch Aufrufen von SQLSetStmtAttr mit einem Attribut von SQL_ATTR_PARAM_OPERATION_PTR festgelegt werden, wodurch eine Anwendung das Feld festlegen kann, ohne ein Deskriptorhandle zu erhalten.

2. Legen Sie jedes Element des Arrays fest, das durch das feld SQL_DESC_ARRAY_STATUS_PTR der APD definiert wird, auf einen von zwei Werten:

   • SQL_PARAM_IGNORE, um anzugeben, dass die Zeile von der Ausführung der Anweisung ausgeschlossen ist.

   • SQL_PARAM_PROCEED, um anzugeben, dass die Zeile in der Ausführung der Anweisung enthalten ist.

3. Rufen Sie SQLExecDirect oder SQLExecute auf, um die vorbereitete Anweisung auszuführen.

Die folgenden Regeln gelten für das Array, das durch das feld SQL_DESC_ARRAY_STATUS_PTR der APD definiert wird:

• Der Zeiger ist standardmäßig auf NULL festgelegt.

• Wenn der Zeiger null ist, werden alle Parametersätze verwendet, als ob alle Elemente auf SQL_ROW_PROCEED festgelegt wurden.

• Das Festlegen eines Elements auf SQL_PARAM_PROCEED garantiert nicht, dass der Vorgang diesen bestimmten Parametersatz verwendet.

• SQL_PARAM_PROCEED ist in der Headerdatei als 0 definiert.

Eine Anwendung kann das SQL_DESC_ARRAY_STATUS_PTR Feld in der APD so festlegen, dass es auf dasselbe Array verweist, auf das das feld SQL_DESC_ARRAY_STATUS_PTR in der IRD verweist. Dies ist nützlich, wenn Parameter an Zeilendaten gebunden werden. Parameter können dann entsprechend dem Status der Zeilendaten ignoriert werden. Zusätzlich zu SQL_PARAM_IGNORE führen die folgenden Codes dazu, dass ein Parameter in einer SQL-Anweisung ignoriert wird: SQL_ROW_DELETED, SQL_ROW_UPDATED und SQL_ROW_ERROR. Zusätzlich zu SQL_PARAM_PROCEED führen die folgenden Codes dazu, dass eine SQL-Anweisung fortgesetzt wird: SQL_ROW_SUCCESS, SQL_ROW_SUCCESS_WITH_INFO und SQL_ROW_ADDED.

Parameter für die Neubindung

Eine Anwendung kann eine von zwei Vorgängen ausführen, um eine Bindung zu ändern:

• Rufen Sie SQLBindParameter auf, um eine neue Bindung für eine bereits gebundene Spalte anzugeben. Der Treiber überschreibt die alte Bindung mit dem neuen.

• Geben Sie einen Offset an, der der Pufferadresse hinzugefügt werden soll, die durch den Bindungsaufruf an SQLBindParameter angegeben wurde. Weitere Informationen finden Sie im nächsten Abschnitt " Rebinding with Offsets".

Neubindung mit Offsets

Die Neubindung von Parametern ist besonders nützlich, wenn eine Anwendung über eine Pufferbereichseinrichtung verfügt, die viele Parameter enthalten kann, aber ein Aufruf von SQLExecDirect oder SQLExecute verwendet nur einige der Parameter. Der verbleibende Platz im Pufferbereich kann für den nächsten Satz von Parametern verwendet werden, indem die vorhandene Bindung durch einen Offset geändert wird.

Das SQL_DESC_BIND_OFFSET_PTR Kopfzeilenfeld in der APD verweist auf den Bindungsoffset. Wenn das Feld ungleich NULL ist, leitet der Treiber den Zeiger ab und fügt, wenn keiner der Werte im SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR und SQL_DESC_OCTET_LENGTH_PTR Felder ein Nullzeiger ist, den abgeleiteten Wert zu diesen Feldern in den Deskriptordatensätzen zur Ausführungszeit hinzu. Die neuen Zeigerwerte werden verwendet, wenn die SQL-Anweisungen ausgeführt werden. Der Offset bleibt nach der Neubindung gültig. Da SQL_DESC_BIND_OFFSET_PTR ein Zeiger auf den Offset anstelle des Offsets selbst ist, kann eine Anwendung den Offset direkt ändern, ohne SQLSetDescField oder SQLSetDescRec aufrufen zu müssen, um das Deskriptorfeld zu ändern. Der Zeiger ist standardmäßig auf NULL festgelegt. Das SQL_DESC_BIND_OFFSET_PTR Feld der ARD kann durch einen Aufruf von SQLSetDescField oder durch einen Aufruf von SQLSetStmtAttr mit einem fAttribute von SQL_ATTR_PARAM_BIND_OFFSET_PTR festgelegt werden.

Der Bindungsoffset wird immer direkt zu den Werten in den Feldern SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR und SQL_DESC_OCTET_LENGTH_PTR hinzugefügt. Wenn der Offset in einen anderen Wert geändert wird, wird der neue Wert weiterhin direkt zum Wert in jedem Deskriptorfeld hinzugefügt. Der neue Offset wird nicht zur Summe des Feldwerts und früheren Offsets hinzugefügt.

Deskriptoren

Wie ein Parameter gebunden ist, wird durch Felder der APDs und IPDs bestimmt. Die Argumente in SQLBindParameter werden verwendet, um diese Deskriptorfelder festzulegen. Die Felder können auch von den SQLSetDescField-Funktionen festgelegt werden, obwohl SQLBindParameter effizienter zu verwenden ist, da die Anwendung kein Deskriptorhandle zum Aufrufen von SQLBindParameter abrufen muss.

Konzeptionell führt SQLBindParameter die folgenden Schritte in Sequenz aus:

1. Ruft SQLGetStmtAttr auf, um das APD-Handle abzurufen.

2. Ruft SQLGetDescField auf, um das SQL_DESC_COUNT-Feld der APD abzurufen, und wenn der Wert des ColumnNumber-Arguments den Wert von SQL_DESC_COUNT überschreitet, ruft SQLSetDescField auf, um den Wert von SQL_DESC_COUNT auf ColumnNumber zu erhöhen.

3. Ruft SQLSetDescField mehrmals auf, um den folgenden Feldern der APD Werte zuzuweisen:

   • Legt SQL_DESC_TYPE und SQL_DESC_CONCISE_TYPE auf den Wert von ValueType fest. Wenn ValueType einer der prägnanten Bezeichner eines Datetime- oder Intervalluntertyps ist, legt er SQL_DESC_TYPE auf SQL_DATETIME oder SQL_INTERVAL fest, legt SQL_DESC_CONCISE_TYPE auf den prägnanten Bezeichner fest und legt SQL_DESC_DATETIME_INTERVAL_CODE auf den entsprechenden Datetime- oder Intervalluntercode fest.

   • Legt das feld SQL_DESC_OCTET_LENGTH auf den Wert von BufferLength fest.

   • Legt das feld SQL_DESC_DATA_PTR auf den Wert von ParameterValue fest.

   • Legt das feld SQL_DESC_OCTET_LENGTH_PTR auf den Wert von StrLen_or_Ind fest.

   • Legt das feld SQL_DESC_INDICATOR_PTR auch auf den Wert von StrLen_or_Ind fest.

   Der parameter StrLen_or_Ind gibt sowohl die Indikatorinformationen als auch die Länge für den Parameterwert an.

4. Ruft SQLGetStmtAttr auf, um das IPD-Handle abzurufen.

5. Ruft SQLGetDescField auf, um das SQL_DESC_COUNT-Feld der IPD abzurufen, und wenn der Wert des ColumnNumber-Arguments den Wert von SQL_DESC_COUNT überschreitet, ruft SQLSetDescField auf, um den Wert von SQL_DESC_COUNT auf ColumnNumber zu erhöhen.

6. Ruft SQLSetDescField mehrmals auf, um den folgenden Feldern der IPD Werte zuzuweisen:

   • Legt SQL_DESC_TYPE und SQL_DESC_CONCISE_TYPE auf den Wert von ParameterType fest, mit der Ausnahme, dass ParameterType einer der präzisen Bezeichner eines Datetime- oder Intervalluntertyps ist, SQL_DESC_TYPE auf SQL_DATETIME bzw. SQL_INTERVAL festgelegt wird, legt SQL_DESC_CONCISE_TYPE auf den prägnanten Bezeichner fest und legt SQL_DESC_DATETIME_INTERVAL_CODE auf die entsprechende Datetime- oder Intervalluntercode fest.

   • Legt einen oder mehrere SQL_DESC_LENGTH, SQL_DESC_PRECISION und SQL_DESC_DATETIME_INTERVAL_PRECISION entsprechend ParameterType fest.

   • Legt SQL_DESC_SCALE auf den Wert von DecimalDigits fest.

Wenn der Aufruf von SQLBindParameter fehlschlägt, sind der Inhalt der Deskriptorfelder, die sie in der APD festgelegt hätte, nicht definiert, und das SQL_DESC_COUNT Feld der APD ist unverändert. Darüber hinaus sind die Felder SQL_DESC_LENGTH, SQL_DESC_PRECISION, SQL_DESC_SCALE und SQL_DESC_TYPE des entsprechenden Eintrags in der IPD nicht definiert, und das SQL_DESC_COUNT Feld der IPD bleibt unverändert.

Konvertierung von Aufrufen in und von SQLSetParam

Wenn eine ODBC 1.0-Anwendung SQLSetParam in einem ODBC 3 aufruft.x-Treiber, ODBC 3.Der x-Treiber-Manager ordnet den Anruf wie in der folgenden Tabelle dargestellt zu.

Beispiele

A. Verwenden der SQLBindParameter-Funktion

Im folgenden Beispiel bereitet eine Anwendung eine SQL-Anweisung zum Einfügen von Daten in die ORDERS-Tabelle vor. Für jeden Parameter in der Anweisung ruft die Anwendung SQLBindParameter auf, um den ODBC C-Datentyp und den SQL-Datentyp des Parameters anzugeben und einen Puffer an jeden Parameter zu binden. Für jede Datenzeile weist die Anwendung jedem Parameter Datenwerte zu und ruft SQLExecute auf, um die Anweisung auszuführen.

Im folgenden Beispiel wird davon ausgegangen, dass Sie über eine ODBC-Datenquelle auf Ihrem Computer mit dem Namen Northwind verfügen, der der Northwind-Datenbank zugeordnet ist.

Weitere Codebeispiele finden Sie unter SQLBulkOperations Function, SQLProcedures Function, SQLPutData Function und SQLSetPos Function.

// SQLBindParameter_Function.cpp  
// compile with: ODBC32.lib  
#include <windows.h>  
#include <sqltypes.h>  
#include <sqlext.h>  
  
#define EMPLOYEE_ID_LEN 10  
  
SQLHENV henv = NULL;  
SQLHDBC hdbc = NULL;  
SQLRETURN retcode;  
SQLHSTMT hstmt = NULL;  
SQLSMALLINT sCustID;  
  
SQLCHAR szEmployeeID[EMPLOYEE_ID_LEN];  
SQL_DATE_STRUCT dsOrderDate;  
SQLINTEGER cbCustID = 0, cbOrderDate = 0, cbEmployeeID = SQL_NTS;  
  
int main() {  
   retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);  
   retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER*)SQL_OV_ODBC3, 0);   
  
   retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);   
   retcode = SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)5, 0);  
  
   retcode = SQLConnect(hdbc, (SQLCHAR*) "Northwind", SQL_NTS, (SQLCHAR*) NULL, 0, NULL, 0);  
   retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);  
  
   retcode = SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR, EMPLOYEE_ID_LEN, 0, szEmployeeID, 0, &cbEmployeeID);  
   retcode = SQLBindParameter(hstmt, 2, SQL_PARAM_INPUT, SQL_C_SSHORT, SQL_INTEGER, 0, 0, &sCustID, 0, &cbCustID);  
   retcode = SQLBindParameter(hstmt, 3, SQL_PARAM_INPUT, SQL_C_TYPE_DATE, SQL_TIMESTAMP, sizeof(dsOrderDate), 0, &dsOrderDate, 0, &cbOrderDate);  
  
   retcode = SQLPrepare(hstmt, (SQLCHAR*)"INSERT INTO Orders(CustomerID, EmployeeID, OrderDate) VALUES (?, ?, ?)", SQL_NTS);  
  
   strcpy_s((char*)szEmployeeID, _countof(szEmployeeID), "BERGS");  
   sCustID = 5;  
   dsOrderDate.year = 2006;  
   dsOrderDate.month = 3;  
   dsOrderDate.day = 17;  
  
   retcode = SQLExecute(hstmt);  
}  

B. Ausführen einer gespeicherten Prozedur mithilfe eines benannten Parameters

Im folgenden Beispiel führt eine Anwendung eine gespeicherte SQL Server-Prozedur mit einem benannten Parameter aus.

// SQLBindParameter_Function_2.cpp  
// compile with: ODBC32.lib  
// sample assumes the following stored procedure:  
// use northwind  
// DROP PROCEDURE SQLBindParameter  
// GO  
//   
// CREATE PROCEDURE SQLBindParameter @quote int  
// AS  
// delete from orders where OrderID >= @quote  
// GO  
#include <windows.h>  
#include <sqltypes.h>  
#include <sqlext.h>  
  
SQLHDESC hIpd = NULL;  
SQLHENV henv = NULL;  
SQLHDBC hdbc = NULL;  
SQLRETURN retcode;  
SQLHSTMT hstmt = NULL;  
SQLCHAR szQuote[50] = "100084";  
SQLINTEGER cbValue = SQL_NTS;  
  
int main() {  
   retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);  
   retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER*)SQL_OV_ODBC3, 0);   
  
   retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);   
   retcode = SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)5, 0);  
  
   retcode = SQLConnect(hdbc, (SQLCHAR*) "Northwind", SQL_NTS, (SQLCHAR*) NULL, 0, NULL, 0);  
   retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);  
  
   retcode = SQLPrepare(hstmt, (SQLCHAR*)"{call SQLBindParameter(?)}", SQL_NTS);  
   retcode = SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR, 50, 0, szQuote, 0, &cbValue);  
   retcode = SQLGetStmtAttr(hstmt, SQL_ATTR_IMP_PARAM_DESC, &hIpd, 0, 0);  
   retcode = SQLSetDescField(hIpd, 1, SQL_DESC_NAME, "@quote", SQL_NTS);  
  
   retcode = SQLExecute(hstmt);  
}  

Verwandte Funktionen

Weitere Informationen

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