SQLSetPos-Funktion

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

Zusammenfassung
SQLSetPos legt die Cursorposition in einem Rowset fest und ermöglicht einer Anwendung das Aktualisieren von Daten im Rowset oder das Aktualisieren oder Löschen von Daten im Resultset.

Syntax

  
SQLRETURN SQLSetPos(  
      SQLHSTMT        StatementHandle,  
      SQLSETPOSIROW   RowNumber,  
      SQLUSMALLINT    Operation,  
      SQLUSMALLINT    LockType);  

Argumente

StatementHandle
[Eingabe] Anweisungshandle.

RowNumber
[Eingabe] Position der Zeile im Rowset, für die der mit dem Argument "Operation " angegebene Vorgang ausgeführt werden soll. Wenn RowNumber 0 ist, gilt der Vorgang für jede Zeile im Rowset.

Weitere Informationen finden Sie unter "Kommentare".

Vorgang
[Eingabe] Auszuführende Operation:

SQL_POSITION SQL_REFRESH SQL_UPDATE SQL_DELETE

Weitere Informationen finden Sie unter "Kommentare".

LockType
[Eingabe] Gibt an, wie die Zeile nach dem Ausführen des im Argument Operation angegebenen Vorgangs gesperrt wird.

SQL_LOCK_NO_CHANGE SQL_LOCK_EXCLUSIVE SQL_LOCK_UNLOCK

Weitere Informationen finden Sie unter "Kommentare".

Gibt zurück

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

Diagnostik

Wenn SQLSetPos 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 häufig von SQLSetPos 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.

Für alle SQLSTATEs, die SQL_SUCCESS_WITH_INFO oder SQL_ERROR (mit Ausnahme von 01xxx SQLSTATEs) zurückgeben können, wird SQL_SUCCESS_WITH_INFO zurückgegeben, wenn ein Fehler für einen oder mehrere, jedoch nicht alle Zeilen eines Mehrzeilenvorgangs auftritt, und SQL_ERROR zurückgegeben wird, wenn ein Fehler bei einem Einzelzeilenvorgang auftritt.

Kommentare

RowNumber-Argument

Das Argument RowNumber gibt die Nummer der Zeile im Rowset an, für die der durch das Argument Operation angegebene Vorgang ausgeführt werden soll. Wenn RowNumber 0 ist, gilt der Vorgang für jede Zeile im Rowset. RowNumber muss ein Wert von 0 bis zur Anzahl der Zeilen im Rowset sein.

Alle Vorgänge positionieren den Cursor auf der Zeile, die durch RowNumber angegeben wird. Für die folgenden Vorgänge ist eine Cursorposition erforderlich:

• Positionierte Aktualisierungs- und Löschanweisungen.

• Aufrufe an SQLGetData.

• Aufrufe von SQLSetPos mit den Optionen SQL_DELETE, SQL_REFRESH und SQL_UPDATE.

Wenn "RowNumber" beispielsweise 2 für einen Aufruf von SQLSetPos mit einem Vorgang von SQL_DELETE ist, wird der Cursor in der zweiten Zeile des Rowsets positioniert und diese Zeile gelöscht. Der Eintrag im Statusarray der Implementierungszeile (auf das attribut der SQL_ATTR_ROW_STATUS_PTR-Anweisung verweist) für die zweite Zeile wird in SQL_ROW_DELETED geändert.

Eine Anwendung kann beim Aufrufen von SQLSetPos eine Cursorposition angeben. Im Allgemeinen ruft es SQLSetPos mit dem SQL_POSITION- oder SQL_REFRESH-Vorgang auf, um den Cursor zu positionieren, bevor eine positionierte Aktualisierungs- oder Löschanweisung ausgeführt oder SQLGetData aufgerufen wird.

Operation-Argument

Das Argument Operation unterstützt die folgenden Vorgänge. Um zu ermitteln, welche Optionen von einer Datenquelle unterstützt werden, ruft eine Anwendung SQLGetInfo mit dem SQL_DYNAMIC_CURSOR_ATTRIBUTES1, SQL_FORWARD_ONLY_CURSOR_ATTRIBUTES1, SQL_KEYSET_CURSOR_ATTRIBUTES1 oder SQL_STATIC_CURSOR_ATTRIBUTES1 Informationstyp (je nach Cursortyp) auf.

LockType-Argument

Das LockType-Argument bietet eine Möglichkeit, um die Parallelität von Anwendungen zu steuern. In den meisten Fällen unterstützen Datenquellen, die Parallelitätsebenen und Transaktionen unterstützen, nur den SQL_LOCK_NO_CHANGE Wert des LockType-Arguments . Das LockType-Argument wird in der Regel nur für dateibasierte Unterstützung verwendet.

Das LockType-Argument gibt den Sperrstatus der Zeile an, nachdem SQLSetPos ausgeführt wurde. Wenn der Treiber die Zeile nicht sperren kann, um den angeforderten Vorgang auszuführen oder das LockType-Argument zu erfüllen, wird SQL_ERROR und SQLSTATE 42000 (Syntaxfehler oder Zugriffsverletzung) zurückgegeben.

Obwohl das LockType-Argument für eine einzelne Anweisung angegeben ist, bezieht sich die Sperre auf dieselben Berechtigungen auf alle Anweisungen für die Verbindung. Insbesondere kann eine Sperre, die von einer Anweisung für eine Verbindung erworben wird, durch eine andere Anweisung für dieselbe Verbindung entsperrt werden.

Eine Zeile, die über SQLSetPos gesperrt ist, bleibt gesperrt, bis die Anwendung SQLSetPos für die Zeile aufruft, wobei LockType auf SQL_LOCK_UNLOCK festgelegt ist, oder bis die Anwendung SQLFreeHandle für die Anweisung oder SQLFreeStmt mit der option SQL_CLOSE aufruft. Für einen Treiber, der Transaktionen unterstützt, wird eine Zeile, die über SQLSetPos gesperrt ist, entsperrt, wenn die Anwendung SQLEndTran aufruft, um eine Transaktion für die Verbindung zu übernehmen oder zurückzusetzen (wenn ein Cursor geschlossen wird, wenn eine Transaktion zugesichert oder zurückgesetzt wird, wie durch die SQL_CURSOR_COMMIT_BEHAVIOR und SQL_CURSOR_ROLLBACK_BEHAVIOR von SQLGetInfo zurückgegebenen Informationstypen).

Das LockType-Argument unterstützt die folgenden Sperrtypen. Um zu ermitteln, welche Sperren von einer Datenquelle unterstützt werden, ruft eine Anwendung SQLGetInfo mit dem SQL_DYNAMIC_CURSOR_ATTRIBUTES1, SQL_FORWARD_ONLY_CURSOR_ATTRIBUTES1, SQL_KEYSET_CURSOR_ATTRIBUTES1 oder SQL_STATIC_CURSOR_ATTRIBUTES1 Informationstyp (je nach Cursortyp) auf.

Wenn ein Treiber SQL_LOCK_EXCLUSIVE unterstützt, aber keine SQL_LOCK_UNLOCK unterstützt, bleibt eine gesperrte Zeile gesperrt, bis eine der im vorherigen Absatz beschriebenen Funktionsaufrufe erfolgt.

Wenn ein Treiber SQL_LOCK_EXCLUSIVE unterstützt, aber keine SQL_LOCK_UNLOCK unterstützt, bleibt eine gesperrte Zeile gesperrt, bis die Anwendung SQLFreeHandle für die Anweisung oder SQLFreeStmt mit der Option SQL_CLOSE aufruft. Wenn der Treiber Transaktionen unterstützt und den Cursor beim Commit oder Rollback der Transaktion schließt, ruft die Anwendung SQLEndTran auf.

Für die Aktualisierungs- und Löschvorgänge in SQLSetPos verwendet die Anwendung das LockType-Argument wie folgt:

• Um sicherzustellen, dass sich eine Zeile nach dem Abrufen nicht ändert, ruft eine Anwendung SQLSetPos mit Operation auf SQL_REFRESH und LockType auf SQL_LOCK_EXCLUSIVE festgelegt.

• Wenn die Anwendung LockType auf SQL_LOCK_NO_CHANGE festlegt, garantiert der Treiber, dass ein Aktualisierungs- oder Löschvorgang nur erfolgreich ausgeführt wird, wenn die Anwendung SQL_CONCUR_LOCK für das Attribut SQL_ATTR_CONCURRENCY Anweisung angegeben hat.

• Wenn die Anwendung SQL_CONCUR_ROWVER oder SQL_CONCUR_VALUES für das Attribut der SQL_ATTR_CONCURRENCY-Anweisung angibt, vergleicht der Treiber Zeilenversionen oder -werte und lehnt den Vorgang ab, wenn sich die Zeile seit dem Abrufen der Zeile geändert hat.

• Wenn die Anwendung SQL_CONCUR_READ_ONLY für das Attribut der SQL_ATTR_CONCURRENCY-Anweisung angibt, lehnt der Treiber aktualisierungs- oder Löschvorgänge ab.

Weitere Informationen zum attribut der SQL_ATTR_CONCURRENCY-Anweisung finden Sie unter SQLSetStmtAttr.

Status- und Vorgangsarrays

Die folgenden Status- und Vorgangsarrays werden beim Aufrufen von SQLSetPos verwendet:

• Das Zeilenstatusarray (wie durch das feld SQL_DESC_ARRAY_STATUS_PTR in der IRD und das Attribut der SQL_ATTR_ROW_STATUS_ARRAY-Anweisung) enthält Statuswerte für jede Datenzeile im Rowset. Der Treiber legt die Statuswerte in diesem Array nach einem Aufruf von SQLFetch, SQLFetchScroll, SQLBulkOperations oder SQLSetPos fest. Dieses Array wird durch das Attribut SQL_ATTR_ROW_STATUS_PTR-Anweisung verwiesen.

• Das Zeilenvorgangsarray (wie durch das Feld SQL_DESC_ARRAY_STATUS_PTR in der ARD und das Attribut der SQL_ATTR_ROW_OPERATION_ARRAY-Anweisung) enthält einen Wert für jede Zeile im Rowset, die angibt, ob ein Aufruf von SQLSetPos für einen Massenvorgang ignoriert oder ausgeführt wird. Jedes Element im Array wird entweder auf SQL_ROW_PROCEED (Standard) oder auf SQL_ROW_IGNORE festgelegt. Dieses Array wird durch das Attribut der SQL_ATTR_ROW_OPERATION_PTR-Anweisung verwiesen.

Die Anzahl der Elemente in den Status- und Vorgangsarrays muss der Anzahl der Zeilen im Rowset entsprechen (wie durch das Attribut der SQL_ATTR_ROW_ARRAY_SIZE-Anweisung definiert).

Informationen zum Zeilenstatusarray finden Sie unter SQLFetch. Informationen zum Zeilenvorgangsarray finden Sie weiter unten in diesem Abschnitt unter "Ignorieren einer Zeile in einem Massenvorgang".

Verwenden von SQLSetPos

Bevor eine Anwendung SQLSetPos aufruft, muss sie die folgende Schrittfolge ausführen:

1. Wenn die Anwendung SQLSetPos mit operation set to SQL_UPDATE aufruft, rufen Sie SQLBindCol (oder SQLSetDescRec) für jede Spalte auf, um den Datentyp anzugeben und Puffer für die Daten und Länge der Spalte zu binden.

2. Wenn die Anwendung SQLSetPos mit Operation set auf SQL_DELETE oder SQL_UPDATE aufruft, rufen Sie SQLColAttribute auf, um sicherzustellen, dass die zu löschenden oder aktualisierten Spalten aktualisierbar sind.

3. Rufen Sie SQLExecDirect, SQLExecute oder eine Katalogfunktion auf, um ein Resultset zu erstellen.

4. Rufen Sie SQLFetch oder SQLFetchScroll auf, um die Daten abzurufen.

Weitere Informationen zur Verwendung von SQLSetPos finden Sie unter Aktualisieren von Daten mit SQLSetPos.

Löschen von Daten mithilfe von SQLSetPos

Zum Löschen von Daten mit SQLSetPos ruft eine Anwendung SQLSetPos mit RowNumber auf die Nummer der zu löschenden Zeile und den Vorgangssatz auf SQL_DELETE.

Nachdem die Daten gelöscht wurden, ändert der Treiber den Wert im Zeilenstatusarray der Implementierung für die entsprechende Zeile in SQL_ROW_DELETED (oder SQL_ROW_ERROR).

Aktualisieren von Daten mit SQLSetPos

Eine Anwendung kann den Wert für eine Spalte entweder im gebundenen Datenpuffer oder mit einem oder mehreren Aufrufen von SQLPutData übergeben. Spalten, deren Daten mit SQLPutData übergeben werden, werden als Daten bei ausführungsspalten bezeichnet. Diese werden häufig zum Senden von Daten für SQL_LONGVARBINARY und SQL_LONGVARCHAR Spalten verwendet und können mit anderen Spalten gemischt werden.

So aktualisieren Sie Daten mit SQLSetPos, einer Anwendung:

1. Platziert Werte in den Daten- und Längen-/Indikatorpuffern, die an SQLBindCol gebunden sind:

   • Bei normalen Spalten platziert die Anwendung den neuen Spaltenwert im *TargetValuePtr-Puffer und die Länge dieses Werts im *StrLen_or_IndPtr Puffer. Wenn die Zeile nicht aktualisiert werden soll, platziert die Anwendung SQL_ROW_IGNORE im Element dieser Zeile des Zeilenvorgangsarrays.

   • Bei Daten bei Ausführungsspalten platziert die Anwendung einen anwendungsdefinierten Wert, z. B. die Spaltennummer, im *TargetValuePtr-Puffer . Der Wert kann später verwendet werden, um die Spalte zu identifizieren.

     Die Anwendung platziert das Ergebnis des Makros SQL_LEN_DATA_AT_EXEC(Länge) im *StrLen_or_IndPtr puffer. Wenn der SQL-Datentyp der Spalte SQL_LONGVARBINARY, SQL_LONGVARCHAR oder ein langer datenquellenspezifischer 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 es sich um einen nicht negativen Wert handeln und ignoriert werden.

2. Ruft SQLSetPos auf, wobei das Argument Operation auf SQL_UPDATE festgelegt ist, um die Datenzeile zu aktualisieren.

   • Wenn keine Daten bei ausführungsspalten vorhanden sind, ist der Vorgang abgeschlossen.

   • Wenn Daten bei ausführungsspalten vorhanden sind, gibt die Funktion SQL_NEED_DATA zurück und fährt mit Schritt 3 fort.

3. Ruft SQLParamData auf, um die Adresse des *TargetValuePtr-Puffers für die erste zu verarbeitende Datenspalte abzurufen. SQLParamData gibt SQL_NEED_DATA zurück. Die Anwendung ruft den anwendungsdefinierte Wert aus dem *TargetValuePtr-Puffer ab.

   Hinweis

   Obwohl datenbasierte Ausführungsparameter mit Daten bei ausführungsspalten vergleichbar sind, unterscheidet sich der von SQLParamData zurückgegebene Wert für jeden.

   Hinweis

   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 oder durch Festlegen von Deskriptoren mit SQLSetDescRec gebunden. Der von SQLParamData zurückgegebene Wert ist ein 32-Bit-Wert, der im ParameterValuePtr-Argument an SQLBindParameter übergeben wird.

   Hinweis

   Daten bei ausführungsspalten sind Spalten in einem Rowset, für die Daten mit SQLPutData gesendet werden, wenn eine Zeile mit SQLSetPos aktualisiert wird. Sie sind mit SQLBindCol gebunden. Der von SQLParamData zurückgegebene Wert ist die Adresse der Zeile im *TargetValuePtr-Puffer , der verarbeitet wird.

4. Ruft SQLPutData einmal auf, um Daten für die Spalte zu senden. Es sind mehrere Aufrufe erforderlich, wenn nicht alle Datenwerte im in SQLPutData angegebenen *TargetValuePtr-Puffer zurückgegeben werden können. Mehrere Aufrufe von SQLPutData für dieselbe Spalte 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.

5. Ruft SQLParamData erneut auf, um zu signalisieren, dass alle Daten für die Spalte gesendet wurden.

   • Wenn weitere Daten bei ausführungsspalten vorhanden sind, gibt SQLParamData SQL_NEED_DATA und die Adresse des TargetValuePtr-Puffers für die nächste daten-at-execution-Spalte zurück, die verarbeitet werden soll. Die Anwendung wiederholt die Schritte 4 und 5.

   • Wenn keine Datenspalten mehr vorhanden sind, ist der Vorgang 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 SQLSetPos zurückgegeben werden kann.

Wenn Daten aktualisiert wurden, ändert der Treiber den Wert im Zeilenstatusarray der Implementierung für die entsprechende Zeile in SQL_ROW_UPDATED.

Wenn der Vorgang abgebrochen wird oder ein Fehler in SQLParamData oder SQLPutData auftritt, nachdem SQLSetPos SQL_NEED_DATA zurückgibt und bevor Daten für alle Daten bei ausführungsspalten gesendet werden, kann die Anwendung nur SQLCancel, SQLGetDiagField, SQLGetDiagRec, SQLGetFunctions, SQLParamData oder SQLPutData für die Anweisung oder die Verbindung aufrufen, die der Anweisung zugeordnet ist. Wenn sie eine andere Funktion für die Anweisung oder die verbindung der Anweisung aufruft, gibt die Funktion SQL_ERROR und SQLSTATE HY010 (Funktionssequenzfehler) zurück.

Wenn die Anwendung SQLCancel aufruft, während der Treiber weiterhin Daten für Daten bei ausführungsspalten benötigt, bricht der Treiber den Vorgang ab. Die Anwendung kann dann SQLSetPos erneut aufrufen. Das Abbrechen wirkt sich nicht auf den Cursorzustand oder die aktuelle Cursorposition aus.

Wenn die SELECT-Liste der dem Cursor zugeordneten Abfragespezifikation mehrere Verweise auf dieselbe Spalte enthält, unabhängig davon, ob ein Fehler generiert wird oder der Treiber die duplizierten Verweise ignoriert und die angeforderten Vorgänge ausführt, wird treiberdefiniert.

Ausführen von Massenvorgängen

Wenn das Argument RowNumber 0 ist, führt der Treiber den im Argument "Operation" angegebenen Vorgang für jede Zeile im Rowset aus, die einen Wert von SQL_ROW_PROCEED in seinem Feld im Zeilenvorgangsarray aufweist, auf das durch SQL_ATTR_ROW_OPERATION_PTR -Anweisungsattribut verwiesen wird. Dies ist ein gültiger Wert des RowNumber-Arguments für ein Argument "Operation " von SQL_DELETE, SQL_REFRESH oder SQL_UPDATE, aber nicht SQL_POSITION. SQLSetPos mit einem Vorgang von SQL_POSITION und einer RowNumber gleich 0 gibt SQLSTATE HY109 (Ungültige Cursorposition) zurück.

Wenn ein Fehler auftritt, der sich auf das gesamte Rowset bezieht, z. B. SQLSTATE HYT00 (Timeout abgelaufen), gibt der Treiber SQL_ERROR und den entsprechenden SQLSTATE zurück. Der Inhalt der Rowsetpuffer ist nicht definiert, und die Cursorposition ist unverändert.

Wenn ein Fehler auftritt, der sich auf eine einzelne Zeile bezieht, tritt der Treiber auf:

• Legt das Element für die Zeile im Zeilenstatusarray fest, auf das das attribut der SQL_ATTR_ROW_STATUS_PTR-Anweisung auf SQL_ROW_ERROR verweist.

• Stellt einen oder mehrere zusätzliche SQLSTATEs für den Fehler in der Fehlerwarteschlange hinzu und legt das feld SQL_DIAG_ROW_NUMBER in der Diagnosedatenstruktur fest.

Nachdem der Fehler oder die Warnung verarbeitet wurde, wird SQL_SUCCESS_WITH_INFO zurückgegeben, wenn der Treiber den Vorgang für die verbleibenden Zeilen im Rowset abgeschlossen hat. Daher enthält die Fehlerwarteschlange für jede Zeile, die einen Fehler zurückgegeben hat, null oder mehr zusätzliche SQLSTATEs. Wenn der Treiber den Vorgang beendet, nachdem er den Fehler oder die Warnung verarbeitet hat, wird SQL_ERROR zurückgegeben.

Wenn der Treiber Warnungen zurückgibt, z. B. SQLSTATE 01004 (Daten abgeschnitten), werden Warnungen zurückgegeben, die für das gesamte Rowset oder unbekannte Zeilen im Rowset gelten, bevor die Fehlerinformationen zurückgegeben werden, die für bestimmte Zeilen gelten. Sie gibt Warnungen für bestimmte Zeilen zusammen mit anderen Fehlerinformationen zu diesen Zeilen zurück.

Wenn "RowNumber " gleich 0 ist und "Operation " SQL_UPDATE, SQL_REFRESH oder SQL_DELETE ist, wird die Anzahl der Zeilen , auf denen SQLSetPos ausgeführt wird, durch das attribut SQL_ATTR_ROWS_FETCHED_PTR-Anweisung verwiesen.

Wenn "RowNumber " gleich 0 ist und "Operation " SQL_DELETE, SQL_REFRESH oder SQL_UPDATE ist, entspricht die aktuelle Zeile nach dem Vorgang der aktuellen Zeile vor dem Vorgang.

Ignorieren einer Zeile in einem Massenvorgang

Das Zeilenvorgangsarray kann verwendet werden, um anzugeben, dass eine Zeile im aktuellen Rowset während eines Massenvorgangs mit SQLSetPos ignoriert werden soll. Damit der Treiber während eines Massenvorgangs eine oder mehrere Zeilen ignoriert, sollte eine Anwendung die folgenden Schritte ausführen:

1. Rufen Sie SQLSetStmtAttr auf, um das attribut der SQL_ATTR_ROW_OPERATION_PTR-Anweisung auf ein Array von SQLUSMALLINTs zu verweisen. Dieses Feld kann auch durch Aufrufen von SQLSetDescField festgelegt werden, um das SQL_DESC_ARRAY_STATUS_PTR Kopfzeilenfeld der ARD festzulegen, was erfordert, dass eine Anwendung das Deskriptorhandle abruft.

2. Legen Sie jedes Element des Zeilenvorgangsarray auf einen von zwei Werten fest:

   • SQL_ROW_IGNORE, um anzugeben, dass die Zeile für den Massenvorgang ausgeschlossen ist.

   • SQL_ROW_PROCEED, um anzugeben, dass die Zeile im Massenvorgang enthalten ist. (Dies ist der Standardwert.)

3. Rufen Sie SQLSetPos auf, um den Massenvorgang auszuführen.

Die folgenden Regeln gelten für das Zeilenvorgangsarray:

• SQL_ROW_IGNORE und SQL_ROW_PROCEED wirken sich nur auf Massenvorgänge mit SQLSetPos mit einem Vorgang von SQL_DELETE oder SQL_UPDATE aus. Sie wirken sich nicht auf Aufrufe von SQLSetPos mit einem Vorgang von SQL_REFRESH oder SQL_POSITION aus.

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

• Wenn der Zeiger null ist, werden alle Zeilen aktualisiert, als ob alle Elemente auf SQL_ROW_PROCEED festgelegt wurden.

• Das Festlegen eines Elements auf SQL_ROW_PROCEED garantiert nicht, dass der Vorgang in dieser bestimmten Zeile ausgeführt wird. Wenn beispielsweise eine bestimmte Zeile im Rowset den Status SQL_ROW_ERROR hat, kann der Treiber diese Zeile möglicherweise nicht aktualisieren, unabhängig davon, ob die Anwendung SQL_ROW_PROCEED angegeben hat. Eine Anwendung muss immer das Zeilenstatusarray überprüfen, um festzustellen, ob der Vorgang erfolgreich war.

• SQL_ROW_PROCEED wird in der Headerdatei als 0 definiert. Eine Anwendung kann das Zeilenvorgangsarray auf 0 initialisieren, um alle Zeilen zu verarbeiten.

• Wenn die Elementnummer "n" im Zeilenvorgangsarray auf SQL_ROW_IGNORE festgelegt ist und SQLSetPos aufgerufen wird, um einen Massenaktualisierungs- oder Löschvorgang auszuführen, bleibt die nth Zeile im Rowset nach dem Aufruf von SQLSetPos unverändert.

• Eine Anwendung sollte automatisch eine schreibgeschützte Spalte auf SQL_ROW_IGNORE festlegen.

Ignorieren einer Spalte in einem Massenvorgang

Um unnötige Verarbeitungsdiagnosen zu vermeiden, die durch versuchte Aktualisierungen an einer oder mehreren schreibgeschützten Spalten generiert werden, kann eine Anwendung den Wert im gebundenen Längen-/Indikatorpuffer auf SQL_COLUMN_IGNORE festlegen. Weitere Informationen finden Sie unter SQLBindCol.

Codebeispiel

Im folgenden Beispiel ermöglicht eine Anwendung es einem Benutzer, die Tabelle ORDERS zu durchsuchen und den Bestellstatus zu aktualisieren. Der Cursor ist keysetgesteuert mit einer Rowsetgröße von 20 und verwendet optimistische Parallelitätssteuerelemente, die Zeilenversionen vergleichen. Nachdem jedes Rowset abgerufen wurde, druckt die Anwendung sie und ermöglicht es dem Benutzer, den Status einer Bestellung auszuwählen und zu aktualisieren. Die Anwendung verwendet SQLSetPos , um den Cursor in der ausgewählten Zeile zu positionieren und eine positionierte Aktualisierung der Zeile auszuführen. (Fehlerbehandlung wird aus Gründen der Übersichtlichkeit weggelassen.)

#define ROWS 20  
#define STATUS_LEN 6  
  
SQLCHAR        szStatus[ROWS][STATUS_LEN], szReply[3];  
SQLINTEGER     cbStatus[ROWS], cbOrderID;  
SQLUSMALLINT   rgfRowStatus[ROWS];  
SQLUINTEGER    sOrderID, crow = ROWS, irow;  
SQLHSTMT       hstmtS, hstmtU;  
  
SQLSetStmtAttr(hstmtS, SQL_ATTR_CONCURRENCY, (SQLPOINTER) SQL_CONCUR_ROWVER, 0);  
SQLSetStmtAttr(hstmtS, SQL_ATTR_CURSOR_TYPE, (SQLPOINTER) SQL_CURSOR_KEYSET_DRIVEN, 0);  
SQLSetStmtAttr(hstmtS, SQL_ATTR_ROW_ARRAY_SIZE, (SQLPOINTER) ROWS, 0);  
SQLSetStmtAttr(hstmtS, SQL_ATTR_ROW_STATUS_PTR, (SQLPOINTER) rgfRowStatus, 0);  
SQLSetCursorName(hstmtS, "C1", SQL_NTS);  
SQLExecDirect(hstmtS, "SELECT ORDERID, STATUS FROM ORDERS ", SQL_NTS);  
  
SQLBindCol(hstmtS, 1, SQL_C_ULONG, &sOrderID, 0, &cbOrderID);  
SQLBindCol(hstmtS, 2, SQL_C_CHAR, szStatus, STATUS_LEN, &cbStatus);  
  
while ((retcode == SQLFetchScroll(hstmtS, SQL_FETCH_NEXT, 0)) != SQL_ERROR) {  
   if (retcode == SQL_NO_DATA_FOUND)  
      break;  
   for (irow = 0; irow < crow; irow++) {  
      if (rgfRowStatus[irow] != SQL_ROW_DELETED)  
         printf("%2d %5d %*s\n", irow+1, sOrderID, NAME_LEN-1, szStatus[irow]);  
   }  
   while (TRUE) {  
      printf("\nRow number to update?");  
      gets_s(szReply, 3);  
      irow = atoi(szReply);  
      if (irow > 0 && irow <= crow) {  
         printf("\nNew status?");  
         gets_s(szStatus[irow-1], (ROWS * STATUS_LEN));  
         SQLSetPos(hstmtS, irow, SQL_POSITION, SQL_LOCK_NO_CHANGE);  
         SQLPrepare(hstmtU,  
          "UPDATE ORDERS SET STATUS=? WHERE CURRENT OF C1", SQL_NTS);  
         SQLBindParameter(hstmtU, 1, SQL_PARAM_INPUT,  
            SQL_C_CHAR, SQL_CHAR,  
            STATUS_LEN, 0, szStatus[irow], 0, NULL);  
         SQLExecute(hstmtU);  
      } else if (irow == 0) {  
         break;  
      }  
   }  
}  

Weitere Beispiele finden Sie unter Positioned Update- und Delete-Anweisungen und Aktualisieren von Zeilen im Rowset mit SQLSetPos.

Verwandte Funktionen

Weitere Informationen

ODBC-API-Referenz
ODBC-Headerdateien