SQLSetDescRec-Funktion

  • Artikel

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

Zusammenfassung
Die FUNKTION SQLSetDescRec legt mehrere Deskriptorfelder fest, die sich auf den Datentyp und den Puffer auswirken, der an spalten- oder Parameterdaten gebunden ist.

Syntax

  
SQLRETURN SQLSetDescRec(  
      SQLHDESC      DescriptorHandle,  
      SQLSMALLINT   RecNumber,  
      SQLSMALLINT   Type,  
      SQLSMALLINT   SubType,  
      SQLLEN        Length,  
      SQLSMALLINT   Precision,  
      SQLSMALLINT   Scale,  
      SQLPOINTER    DataPtr,  
      SQLLEN *      StringLengthPtr,  
      SQLLEN *      IndicatorPtr);

Argumente

DescriptorHandle
[Eingabe] Deskriptorhandle. Dies darf kein IRD-Handle sein.

RecNumber
[Eingabe] Gibt den Deskriptordatensatz an, der die festzulegenden Felder enthält. Deskriptordatensätze werden von 0 nummeriert, wobei datensatznummer 0 der Lesezeichendatensatz ist. Dieses Argument muss gleich oder größer 0 sein. Wenn RecNumber größer als der Wert von SQL_DESC_COUNT ist, SQL_DESC_COUNTis in den Wert von RecNumber geändert.

Typ
[Eingabe] Der Wert, auf den das SQL_DESC_TYPE Feld für den Deskriptordatensatz festgelegt werden soll.

Untertyp
[Eingabe] Für Datensätze, deren Typ SQL_DATETIME oder SQL_INTERVAL ist, ist dies der Wert, auf den das feld SQL_DESC_DATETIME_INTERVAL_CODE festgelegt werden soll.

Länge
[Eingabe] Der Wert, auf den das feld SQL_DESC_OCTET_LENGTH für den Deskriptordatensatz festgelegt werden soll.

Genauigkeit
[Eingabe] Der Wert, auf den das SQL_DESC_PRECISION Feld für den Deskriptordatensatz festgelegt werden soll.

Scale (Skalieren)
[Eingabe] Der Wert, auf den das feld SQL_DESC_SCALE für den Deskriptordatensatz festgelegt werden soll.

DataPtr
[Verzögerte Eingabe oder Ausgabe] Der Wert, auf den das SQL_DESC_DATA_PTR Feld für den Deskriptordatensatz festgelegt werden soll. DataPtr kann auf einen NULL-Zeiger festgelegt werden.

Das DataPtr-Argument kann auf einen NULL-Zeiger festgelegt werden, um das SQL_DESC_DATA_PTR Feld auf einen NULL-Zeiger festzulegen. Wenn das Handle im DescriptorHandle-Argument einer ARD zugeordnet ist, wird die Bindung der Spalte aufheben.

StringLengthPtr
[Verzögerte Eingabe oder Ausgabe] Der Wert, auf den das SQL_DESC_OCTET_LENGTH_PTR Feld für den Deskriptordatensatz festgelegt werden soll. StringLengthPtr kann auf einen NULL-Zeiger festgelegt werden, um das SQL_DESC_OCTET_LENGTH_PTR Feld auf einen NULL-Zeiger festzulegen.

IndicatorPtr
[Verzögerte Eingabe oder Ausgabe] Der Wert, auf den das SQL_DESC_INDICATOR_PTR Feld für den Deskriptordatensatz festgelegt werden soll. IndicatorPtr kann auf einen NULL-Zeiger festgelegt werden, um das SQL_DESC_INDICATOR_PTR Feld auf einen NULL-Zeiger festzulegen.

Gibt zurück

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR oder SQL_INVALID_HANDLE.

Diagnose

Wenn SQLSetDescRec SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugeordneter SQLSTATE-Wert abgerufen werden, indem SQLGetDiagRec mit einem HandleType von SQL_HANDLE_DESC und einem Handle von DescriptorHandle aufgerufen wird. In der folgenden Tabelle sind die SQLSTATE-Werte aufgeführt, die häufig von SQLSetDescRec zurückgegeben werden, und die einzelnen Werte werden im Kontext dieser Funktion erläutert. die Notation "(DM)" steht vor den Beschreibungen von SQLSTATEs, die vom Treiber-Manager zurückgegeben werden. Der Rückgabecode, der jedem SQLSTATE-Wert zugeordnet ist, ist SQL_ERROR, sofern nicht anders angegeben.

SQLSTATE Fehler BESCHREIBUNG
01000 Allgemeine Warnung Treiberspezifische Informationsmeldung. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.)
07009 Ungültiger Deskriptorindex Das Argument RecNumber wurde auf 0 festgelegt, und descriptorHandle verweist auf ein IPD-Handle.

Das RecNumber-Argument war kleiner als 0.

Das RecNumber-Argument war größer als die maximale Anzahl von Spalten oder Parametern, die die Datenquelle unterstützen kann, und das Argument DescriptorHandle war eine APD, IPD oder ARD.

Das RecNumber-Argument war gleich 0, und das Argument DescriptorHandle verweist auf eine implizit zugeordnete APD. (Dieser Fehler tritt bei einem explizit zugeordneten Anwendungsdeskriptor nicht auf, da bis zur Ausführungszeit nicht bekannt ist, ob ein explizit zugeordneter Anwendungsdeskriptor eine APD oder ARD ist.)
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.
HY000 Allgemeiner Fehler Es ist ein Fehler aufgetreten, für den kein spezifischer SQLSTATE-Wert vorhanden war und für den keine implementierungsspezifische SQLSTATE definiert wurde. Die von SQLGetDiagRec im *MessageText-Puffer zurückgegebene Fehlermeldung beschreibt den Fehler und seine Ursache.
HY001 Fehler bei der Speicherbelegung Der Treiber konnte keinen Arbeitsspeicher zuordnen, der für die Unterstützung der Ausführung oder Fertigstellung der Funktion erforderlich ist.
HY010 Funktionssequenzfehler (DM) Das DescriptorHandle wurde einem StatementHandle zugeordnet, für das eine asynchron ausgeführte Funktion (nicht diese) aufgerufen wurde und noch ausgeführt wurde, als diese Funktion aufgerufen wurde.

(DM) SQLExecute, SQLExecDirect, SQLBulkOperations oder SQLSetPos wurde für den StatementHandle aufgerufen, dem descriptorHandle zugeordnet und SQL_NEED_DATA zurückgegeben wurde. Diese Funktion wurde aufgerufen, bevor Daten für alle Daten bei der Ausführungsparameter oder -spalten gesendet wurden.

(DM) Eine asynchron ausgeführte Funktion wurde für das Verbindungshandle aufgerufen, das dem DescriptorHandle zugeordnet ist. Diese aynchrone Funktion wurde noch ausgeführt, als die Funktion SQLSetDescRec aufgerufen wurde.

(DM) SQLExecute, SQLExecDirect oder SQLMoreResults wurde für eines der Anweisungshandles aufgerufen, die dem DescriptorHandle zugeordnet sind, und SQL_PARAM_DATA_AVAILABLE zurückgegeben. Diese Funktion wurde aufgerufen, bevor Daten für alle gestreamten Parameter abgerufen wurden.
HY013 Fehler bei der Speicherverwaltung Der Funktionsaufruf konnte nicht verarbeitet werden, weil auf die zugrunde liegenden Speicherobjekte nicht zugegriffen werden konnte, möglicherweise aufgrund von geringen Arbeitsspeicherbedingungen.
HY016 Ein Implementierungszeilendeskriptor kann nicht geändert werden. Das DescriptorHandle-Argument wurde einer IRD zugeordnet.
HY021 Inkonsistente Deskriptorinformationen Das Feld Typ oder jedes andere Feld, das dem SQL_DESC_TYPE Feld im Deskriptor zugeordnet ist, war ungültig oder konsistent.

Die während einer Konsistenzprüfung überprüften Deskriptorinformationen waren nicht konsistent. (Siehe "Konsistenzprüfungen" weiter unten in diesem Abschnitt.)
HY090 Ungültige Zeichenfolgen- oder Pufferlänge (DM) Der Treiber war ein ODBC 2.x-Treiber , der Deskriptor eine ARD, das ColumnNumber-Argument wurde auf 0 festgelegt, und der für das Argument BufferLength angegebene Wert war nicht gleich 4.
HY117 Die Verbindung wird aufgrund eines unbekannten Transaktionsstatus angehalten. Nur trenn- und schreibgeschützte Funktionen sind zulässig. (DM) Weitere Informationen zum angehaltenen Zustand finden Sie unter SQLEndTran-Funktion.
HYT01 Verbindungstimeout abgelaufen Der Zeitraum für das Verbindungstimeout ist abgelaufen, bevor die Datenquelle auf die Anforderung geantwortet hat. Der Verbindungstimeoutzeitraum wird über SQLSetConnectAttr festgelegt, SQL_ATTR_CONNECTION_TIMEOUT.
IM001 Der Treiber unterstützt diese Funktion nicht. (DM) Der dem DescriptorHandle zugeordnete Treiber unterstützt die Funktion nicht.

Kommentare

Eine Anwendung kann SQLSetDescRec aufrufen, um die folgenden Felder für eine einzelne Spalte oder einen einzelnen Parameter festzulegen:

  • SQL_DESC_TYPE

  • SQL_DESC_DATETIME_INTERVAL_CODE (für Datensätze, deren Typ SQL_DATETIME oder SQL_INTERVAL ist)

  • SQL_DESC_OCTET_LENGTH

  • SQL_DESC_PRECISION

  • SQL_DESC_SCALE

  • SQL_DESC_DATA_PTR

  • SQL_DESC_OCTET_LENGTH_PTR

  • SQL_DESC_INDICATOR_PTR

Hinweis

Wenn ein Aufruf von SQLSetDescRec fehlschlägt, ist der Inhalt des durch das RecNumber-Argument identifizierten Deskriptordatensatzes nicht definiert.

Beim Binden einer Spalte oder eines Parameters können Sie mit SQLSetDescRec mehrere Felder ändern, die sich auf die Bindung auswirken, ohne SQLBindCol oder SQLBindParameter aufzurufen oder mehrere Aufrufe von SQLSetDescField auszuführen. SQLSetDescRec kann Felder für einen Deskriptor festlegen, der derzeit nicht einer Anweisung zugeordnet ist. Beachten Sie, dass SQLBindParameter mehr Felder als SQLSetDescRec festlegt, Felder sowohl für eine APD als auch für eine IPD in einem Aufruf festlegen kann und kein Deskriptorhandle erfordert.

Hinweis

Das Anweisungsattribut SQL_ATTR_USE_BOOKMARKS sollte immer festgelegt werden, bevor SQLSetDescRec mit dem RecNumber-Argument 0 aufgerufen wird, um Lesezeichenfelder festzulegen. Dies ist zwar nicht obligatorisch, wird jedoch dringend empfohlen.

Konsistenzprüfungen

Eine Konsistenzprüfung wird automatisch vom Treiber durchgeführt, wenn eine Anwendung das SQL_DESC_DATA_PTR Feld einer APD, ARD oder IPD festlegt. Wenn eines der Felder mit anderen Feldern inkonsistent ist, gibt SQLSetDescRec SQLSTATE HY021 (Inkonsistente Deskriptorinformationen) zurück.

Wenn eine Anwendung das SQL_DESC_DATA_PTR Feld einer APD, ARD oder IPD festlegt, überprüft der Treiber, ob der Wert des felds SQL_DESC_TYPE und die für dieses SQL_DESC_TYPE Feld geltenden Werte gültig und konsistent sind. Diese Überprüfung wird immer durchgeführt, wenn SQLBindParameter oder SQLBindCol aufgerufen wird oder wenn SQLSetDescRec für eine APD, ARD oder IPD aufgerufen wird. Diese Konsistenzprüfung umfasst die folgenden Überprüfungen für Deskriptorfelder:

  • Das SQL_DESC_TYPE Feld muss einer der gültigen ODBC C- oder SQL-Typen oder ein treiberspezifischer SQL-Typ sein. Das SQL_DESC_CONCISE_TYPE Feld muss einer der gültigen ODBC C- oder SQL-Typen oder ein treiberspezifischer C- oder SQL-Typ sein, einschließlich der präzisen Datetime- und Intervalltypen.

  • Wenn das Feld SQL_DESC_TYPE Datensatz SQL_DATETIME oder SQL_INTERVAL ist, muss das feld SQL_DESC_DATETIME_INTERVAL_CODE einer der gültigen datetime- oder Intervallcodes sein. (Siehe Beschreibung des felds SQL_DESC_DATETIME_INTERVAL_CODE in SQLSetDescField.)

  • Wenn das Feld SQL_DESC_TYPE einen numerischen Typ angibt, werden die Felder SQL_DESC_PRECISION und SQL_DESC_SCALE als gültig überprüft.

  • Wenn das SQL_DESC_CONCISE_TYPE Feld ein Zeit- oder Zeitstempeldatentyp, ein Intervalltyp mit einer Sekundenkomponente oder einer der Intervalldatentypen mit einer Zeitkomponente ist, wird das SQL_DESC_PRECISION Feld als gültige Sekundengenauigkeit überprüft.

  • Wenn der SQL_DESC_CONCISE_TYPE ein Intervalldatentyp ist, wird das SQL_DESC_DATETIME_INTERVAL_PRECISION Feld als gültiger intervallführender Genauigkeitswert überprüft.

Das SQL_DESC_DATA_PTR Feld einer IPD ist normalerweise nicht festgelegt. Eine Anwendung kann dies jedoch tun, um eine Konsistenzprüfung von IPD-Feldern zu erzwingen. Eine Konsistenzprüfung kann nicht für eine IRD durchgeführt werden. Der Wert, auf den das Feld SQL_DESC_DATA_PTR der IPD festgelegt ist, wird nicht tatsächlich gespeichert und kann nicht durch einen Aufruf von SQLGetDescField oder SQLGetDescRec abgerufen werden. die Einstellung wird nur vorgenommen, um die Konsistenzprüfung zu erzwingen.

Informationen über Finden Sie unter
Binden einer Spalte SQLBindCol-Funktion
Binden eines Parameters SQLBindParameter-Funktion
Abrufen eines einzelnen Deskriptorfelds SQLGetDescField-Funktion
Abrufen mehrerer Deskriptorfelder SQLGetDescRec-Funktion
Festlegen einzelner Deskriptorfelder SQLSetDescField-Funktion

Weitere Informationen

ODBC-API-Referenz
ODBC-Headerdateien