Verwenden von Parameterarrays

Um Arrays von Parametern zu verwenden, ruft die Anwendung SQLSetStmtAttr mit einem Attributargument von SQL_ATTR_PARAMSET_SIZE auf, um die Anzahl der Parametersätze anzugeben. Es ruft SQLSetStmtAttr mit einem Attributargument von SQL_ATTR_PARAMS_PROCESSED_PTR auf, um die Adresse einer Variablen anzugeben, in der der Treiber die Anzahl der verarbeiteten Parametersätze zurückgeben kann, einschließlich Fehlersätze. Sie ruft SQLSetStmtAttr mit einem Attributargument von SQL_ATTR_PARAM_STATUS_PTR auf ein Array auf, in dem Statusinformationen für jede Zeile von Parameterwerten zurückgegeben werden. Der Treiber speichert diese Adressen in der Struktur, Standard für die Anweisung enthalten ist.

Hinweis

In ODBC 2.x, SQLParamOptions wurde aufgerufen, um mehrere Werte für einen Parameter anzugeben. In ODBC 3.x, der Aufruf von SQLParamOptions wurde durch Aufrufe von SQLSetStmtAttr ersetzt, um die attribute SQL_ATTR_PARAMSET_SIZE und SQL_ATTR_PARAMS_PROCESSED_ARRAY festzulegen.

Vor dem Ausführen der Anweisung legt die Anwendung den Wert jedes Elements jedes gebundenen Arrays fest. Wenn die Anweisung ausgeführt wird, verwendet der Treiber die darin gespeicherten Informationen, um die Parameterwerte abzurufen und an die Datenquelle zu senden. Wenn möglich, sollte der Treiber diese Werte als Arrays senden. Obwohl die Verwendung von Arrays von Parametern am besten implementiert wird, indem die SQL-Anweisung mit allen Parametern im Array mit einem einzigen Aufruf der Datenquelle ausgeführt wird, ist diese Funktion heute in DBMSs nicht weit verbreitet. Treiber können dies jedoch simulieren, indem sie eine SQL-Anweisung mehrmals mit einer einzigen Gruppe von Parametern ausführen.

Bevor eine Anwendung Arrays von Parametern verwendet, muss sichergestellt werden, dass sie von den von der Anwendung verwendeten Treibern unterstützt werden. Hierfür gibt es zwei Möglichkeiten:

• Verwenden Sie nur Treiber, die bekannt sind, um Arrays von Parametern zu unterstützen. Die Anwendung kann die Namen dieser Treiber hart codieren, oder der Benutzer kann angewiesen werden, nur diese Treiber zu verwenden. Benutzerdefinierte Anwendungen und vertikale Anwendungen verwenden häufig eine begrenzte Gruppe von Treibern.

• Überprüfen Sie, ob Arrays von Parametern zur Laufzeit unterstützt werden. Ein Treiber unterstützt Arrays von Parametern, wenn das attribut der SQL_ATTR_PARAMSET_SIZE-Anweisung auf einen Wert festgelegt werden kann, der größer als 1 ist. Generische Anwendungen und vertikale Anwendungen überprüfen häufig die Unterstützung von Arrays von Parametern zur Laufzeit.

Die Verfügbarkeit von Zeilenanzahlen und Resultsets in parametrisierter Ausführung kann durch Aufrufen von SQLGetInfo mit den Optionen SQL_PARAM_ARRAY_ROW_COUNTS und SQL_PARAM_ARRAY_SELECTS bestimmt werden. Bei INSERT-, UPDATE- und DELETE-Anweisungen gibt die Option SQL_PARAM_ARRAY_ROW_COUNTS an, ob einzelne Zeilenanzahlen (eine für jeden Parametersatz) verfügbar sind (SQL_PARC_BATCH) oder ob Zeilenanzahlen in einer Zeile (SQL_PARC_NO_BATCH) ausgeführt werden. Bei SELECT-Anweisungen gibt die Option SQL_PARAM_ARRAY_SELECTS an, ob für jeden Parametersatz (SQL_PAS_BATCH) ein Resultset verfügbar ist oder ob nur ein Resultset verfügbar ist (SQL_PAS_NO_BATCH). Wenn der Treiber die Ausführung von Resultset-generierenden Anweisungen mit einem Array von Parametern nicht zulässt, gibt SQL_PARAM_ARRAY_SELECTS SQL_PAS_NO_SELECT zurück. Es ist datenquellenspezifisch, ob Arrays von Parametern mit anderen Arten von Anweisungen verwendet werden können, insbesondere weil die Verwendung von Parametern in diesen Anweisungen datenquellenspezifisch wäre und nicht der ODBC SQL-Grammatik folgen würde.

Das Array, auf das das Attribut der SQL_ATTR_PARAM_OPERATION_PTR-Anweisung verweist, kann verwendet werden, um Zeilen von Parametern zu ignorieren. Wenn ein Element des Arrays auf SQL_PARAM_IGNORE festgelegt ist, wird der Satz von Parametern, die diesem Element entsprechen, vom SQLExecute - oder SQLExecDirect-Aufruf ausgeschlossen. Das Array, auf das das attribut SQL_ATTR_PARAM_OPERATION_PTR verweist, wird von der Anwendung zugewiesen und vom Treiber gelesen. Wenn abgerufene Zeilen als Eingabeparameter verwendet werden, können die Werte des Zeilenstatusarrays im Parametervorgangsarray verwendet werden.

Fehlerverarbeitung

Wenn beim Ausführen der Anweisung ein Fehler auftritt, gibt die Ausführungsfunktion einen Fehler zurück und legt die Zeilennummervariable auf die Nummer der Zeile fest, die den Fehler enthält. Es ist datenquellenspezifisch, ob alle Zeilen außer dem Fehlersatz ausgeführt werden oder ob alle Zeilen vor (aber nicht nach) der Fehlersatz ausgeführt werden. Da Sätze von Parametern verarbeitet werden, legt der Treiber den durch das Attribut der SQL_ATTR_PARAMS_PROCESSED_PTR-Anweisung angegebenen Puffer auf die Anzahl der aktuell verarbeiteten Zeile fest. Wenn alle Sätze außer dem Fehlersatz ausgeführt werden, legt der Treiber diesen Puffer auf SQL_ATTR_PARAMSET_SIZE fest, nachdem alle Zeilen verarbeitet wurden.

Wenn das attribut der SQL_ATTR_PARAM_STATUS_PTR-Anweisung festgelegt wurde, gibt SQLExecute oder SQLExecDirect das Parameterstatusarray zurück, das den Status der einzelnen Parametersätze bereitstellt. Das Parameterstatusarray wird von der Anwendung zugewiesen und vom Treiber ausgefüllt. Die Elemente geben an, ob die SQL-Anweisung für die Zeile der Parameter erfolgreich ausgeführt wurde oder ob beim Verarbeiten der Parametermenge ein Fehler aufgetreten ist. Wenn ein Fehler aufgetreten ist, legt der Treiber den entsprechenden Wert im Parameterstatusarray auf SQL_PARAM_ERROR fest und gibt SQL_SUCCESS_WITH_INFO zurück. Die Anwendung kann das Statusarray überprüfen, um zu bestimmen, welche Zeilen verarbeitet wurden. Mithilfe der Zeilennummer kann die Anwendung häufig den Fehler korrigieren und die Verarbeitung fortsetzen.

Wie das Parameterstatusarray verwendet wird, wird durch die SQL_PARAM_ARRAY_ROW_COUNTS und SQL_PARAM_ARRAY_SELECTS Optionen bestimmt, die von einem Aufruf von SQLGetInfo zurückgegeben werden. Für INSERT-, UPDATE- und DELETE-Anweisungen wird das Parameterstatusarray mit Statusinformationen gefüllt, wenn SQL_PARC_BATCH für SQL_PARAM_ARRAY_ROW_COUNTS zurückgegeben wird, aber nicht, wenn SQL_PARC_NO_BATCH zurückgegeben wird. Bei SELECT-Anweisungen wird das Parameterstatusarray ausgefüllt, wenn SQL_PAS_BATCH für SQL_PARAM_ARRAY_SELECT zurückgegeben wird, aber nicht, wenn SQL_PAS_NO_BATCH oder SQL_PAS_NO_SELECT zurückgegeben wird.

Data-at-Execution-Parameter

Wenn eines der Werte im Längen-/Indikatorarray SQL_DATA_AT_EXEC oder das Ergebnis des Makros SQL_LEN_DATA_AT_EXEC(länge) ist, werden die Daten für diese Werte in der üblichen Weise mit SQLPutData gesendet. Die folgenden Aspekte dieses Prozesses weisen besondere Anmerkungen auf, da sie nicht leicht offensichtlich sind:

• Wenn der Treiber SQL_NEED_DATA zurückgibt, muss er die Adresse der Zeilennummervariable auf die Zeile festlegen, für die Daten benötigt werden. Wie im einzelwertigen Fall kann die Anwendung keine Annahmen über die Reihenfolge treffen, in der der Treiber Parameterwerte innerhalb einer einzigen Gruppe von Parametern anfordert. Wenn bei der Ausführung eines Data-at-Execution-Parameters ein Fehler auftritt, wird der durch das Attribut SQL_ATTR_PARAMS_PROCESSED_PTR Anweisung angegebene Puffer auf die Nummer der Zeile festgelegt, für die der Fehler aufgetreten ist, der Status für die Zeile im Zeilenstatusarray, das durch das attribut SQL_ATTR_PARAM_STATUS_PTR-Anweisung angegeben wird, auf SQL_PARAM_ERROR festgelegt ist, und der Aufruf von SQLExecute, SQLExecDirect, SQLParamData oder SQLPutData gibt SQL_ERROR zurück. Der Inhalt dieses Puffers ist nicht definiert, wenn SQLExecute, SQLExecute, SQLExecDirect oder SQLParamData SQL_STILL_EXECUTING zurückgeben.

• Da der Treiber den Wert im ParameterValuePtr-Argument von SQLBindParameter nicht für Data-at-execution-Parameter interpretiert, wenn die Anwendung einen Zeiger auf ein Array bereitstellt, extrahiert SQLParamData nicht und gibt ein Element dieses Arrays an die Anwendung zurück. Stattdessen wird der skalare Wert zurückgegeben, den die Anwendung bereitgestellt hat. Dies bedeutet, dass der von SQLParamData zurückgegebene Wert nicht ausreicht, um den Parameter anzugeben, für den die Anwendung Daten senden muss. Die Anwendung muss auch die aktuelle Zeilennummer berücksichtigen.

  Wenn nur einige Elemente eines Arrays von Parametern Daten bei der Ausführung sind, muss die Anwendung die Adresse eines Arrays in ParameterValuePtr übergeben, das Elemente für alle Parameter enthält. Dieses Array wird normalerweise für die Parameter interpretiert, die keine Daten bei ausführungsparametern sind. Für die Daten-at-Execution-Parameter ist der Wert , den SQLParamData für die Anwendung bereitstellt, die normalerweise verwendet werden kann, um die Daten zu identifizieren, die der Treiber bei dieser Gelegenheit anfordert, immer die Adresse des Arrays.