Freigeben über

SQLSetDescRec-Funktion

  • Artikel

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

Zusammenfassung
Die SQLSetDescRec--Funktion 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 Textmarkendatensatz ist. Dieses Argument muss gleich oder größer als 0 sein. Wenn RecNumber- größer als der Wert von SQL_DESC_COUNT ist, SQL_DESC_COUNTis in den Wert RecNumbergeändert.

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

SubType-
[Eingabe] Bei Datensätzen, 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.

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

Skalierungs-
[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 feld SQL_DESC_DATA_PTR für den Deskriptordatensatz festgelegt werden soll. DataPtr- kann auf einen Nullzeiger festgelegt werden.

Das DataPtr--Argument kann auf einen Nullzeiger festgelegt werden, um das feld SQL_DESC_DATA_PTR auf einen Nullzeiger festzulegen. Wenn das Handle im DescriptorHandle Argument einem ARD zugeordnet ist, wird die Spalte dadurch getrennt.

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

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

Ertrag

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR oder SQL_INVALID_HANDLE.

Diagnostik

Wenn SQLSetDescRec SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugeordneter SQLSTATE-Wert durch Aufrufen SQLGetDiagRec mit einem HandleType- von SQL_HANDLE_DESC und einem Handle von DescriptorHandle-abgerufen werden. In der folgenden Tabelle sind die SQLSTATE-Werte aufgeführt, die häufig von SQLSetDescRec- zurückgegeben werden und die einzelnen Werte im Kontext dieser Funktion erläutert werden. 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 die DescriptorHandle- auf ein IPD-Handle verwiesen.

Das argument RecNumber war kleiner als 0.

Das argument RecNumber war größer als die maximale Anzahl von Spalten oder Parametern, die von der Datenquelle unterstützt werden können, und das argument DescriptorHandle argument war eine APD, IPD oder ARD.

Das argument RecNumber war gleich 0, und das DescriptorHandle Argument verweist auf eine implizit zugeordnete APD. (Dieser Fehler tritt nicht mit einem explizit zugewiesenen Anwendungsdeskriptor auf, da er nicht bekannt ist, ob es sich bei einem explizit zugewiesenen Anwendungsdeskriptor um eine APD oder ARD handelt, bis die Ausführung erfolgt.)
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 dessen Ursache.
HY001 Speicherzuweisungsfehler Der Treiber konnte speicher nicht zuordnen, der erforderlich ist, um die Ausführung oder den Abschluss der Funktion zu unterstützen.
HY010 Funktionssequenzfehler (DM) Die DescriptorHandle- wurde einer StatementHandle- zugeordnet, für die eine asynchron ausgeführte Funktion (nicht diese) aufgerufen wurde und noch ausgeführt wurde, als diese Funktion aufgerufen wurde.

(DM) SQLExecute, SQLExecDirect, SQLBulkOperationsoder SQLSetPos wurde für die StatementHandle- aufgerufen, mit der die DescriptorHandle- zugeordnet und SQL_NEED_DATA zurückgegeben wurde. Diese Funktion wurde aufgerufen, bevor Daten für alle Daten bei ausführungsparametern oder -spalten gesendet wurden.

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

(DM) SQLExecute, SQLExecDirect-oder SQLMoreResults- wurde für einen der Anweisungshandles aufgerufen, die dem DescriptorHandle- zugeordnet sind und SQL_PARAM_DATA_AVAILABLE zurückgegeben wurden. Diese Funktion wurde aufgerufen, bevor Daten für alle gestreamten Parameter abgerufen wurden.
HY013 Speicherverwaltungsfehler Der Funktionsaufruf konnte nicht verarbeitet werden, da auf die zugrunde liegenden Speicherobjekte nicht zugegriffen werden konnte, möglicherweise aufgrund geringer Arbeitsspeicherbedingungen.
HY016 Ein Implementierungszeilendeskriptor kann nicht geändert werden. Das DescriptorHandle Argument wurde einem IRD zugeordnet.
HY021 Inkonsistente Beschreibungsinformationen Das feld Type oder ein anderes Feld, das dem feld SQL_DESC_TYPE im Deskriptor zugeordnet ist, war ungültig oder konsistent.

Beschreibungsinformationen, die während einer Konsistenzüberprüfung überprüft wurden, waren nicht konsistent. (Siehe "Konsistenzüberprüfungen", weiter unten in diesem Abschnitt.)
HY090 Ungültige Zeichenfolgen- oder Pufferlänge (DM) Der Treiber war ein ODBC-2.x Treiber, der Deskriptor war ein ARD, das ColumnNumber Argument wurde auf 0 festgelegt, und der für das Argument angegebene Wert BufferLength nicht gleich 4.
HY117 Die Verbindung wird aufgrund des unbekannten Transaktionsstatus angehalten. Es sind nur Trenn- und schreibgeschützte Funktionen zulässig. (DM) Weitere Informationen zum angehaltenen Zustand finden Sie unter SQLEndTran Function.
HYT01 Verbindungstimeout abgelaufen Der Zeitraum für das Verbindungstimeout ist abgelaufen, bevor die Datenquelle auf die Anforderung geantwortet hat. Der Verbindungstimeoutzeitraum wird über SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT festgelegt.
IM001 Dieser Treiber unterstützt diese Funktion nicht. (DM) Der 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 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

Anmerkung

Wenn ein Aufruf von SQLSetDescRec fehlschlägt, sind die Inhalte des vom RecNumber Arguments identifizierten Deskriptordatensatz nicht definiert.

Beim Binden einer Spalte oder eines Parameters können Sie SQLSetDescRec- mehrere Felder ändern, die sich auf die Bindung auswirken, ohne SQLBindCol oder SQLBindParameter- oder mehrere Aufrufe an SQLSetDescField. SQLSetDescRec- felder für einen Deskriptor festlegen können, der derzeit keiner Anweisung zugeordnet ist. Beachten Sie, dass SQLBindParameter- mehr Felder als SQLSetDescRec-festlegt, Felder für eine APD und eine IPD in einem Aufruf festlegen können und kein Deskriptorhandle erforderlich ist.

Anmerkung

Das SQL_ATTR_USE_BOOKMARKS-Attribut der Anweisung sollte immer festgelegt werden, bevor SQLSetDescRec- mit einem RecNumber Argument 0 zum Festlegen von Textmarkenfeldern aufgerufen wird. Dies ist zwar nicht obligatorisch, wird jedoch dringend empfohlen.

Konsistenzprüfungen

Eine Konsistenzüberprüfung wird vom Treiber automatisch 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 Beschreibungsinformationen) 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 anwendbaren Werte gültig und konsistent sind. Diese Überprüfung wird immer ausgeführt, wenn SQLBindParameter- oder SQLBindCol- aufgerufen wird oder wenn SQLSetDescRec- für eine APD, ARD oder IPD aufgerufen wird. Diese Konsistenzüberprüfung umfasst die folgenden Überprüfungen von Deskriptorfeldern:

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

  • Wenn das SQL_DESC_TYPE Datensatzfeld SQL_DATETIME oder SQL_INTERVAL ist, muss das feld SQL_DESC_DATETIME_INTERVAL_CODE einer der gültigen Datums- 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 feld SQL_DESC_CONCISE_TYPE ein Zeit- oder Zeitstempeldatentyp, ein Intervalltyp mit einer Sekundenkomponente oder eines der Intervalldatentypen mit einer Zeitkomponente ist, wird das feld SQL_DESC_PRECISION überprüft, um eine gültige Sekundengenauigkeit zu sein.

  • Wenn es sich bei dem SQL_DESC_CONCISE_TYPE um einen Intervalldatentyp handelt, wird das feld SQL_DESC_DATETIME_INTERVAL_PRECISION überprüft, um ein gültiges Intervall mit führendem Genauigkeitswert zu sein.

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

Informationen zu Siehe
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

Siehe auch

ODBC-API-Referenz
ODBC-Headerdateien