SQLGetDescRec-Funktion

  • Artikel

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

Zusammenfassung
SQLGetDescRec gibt die aktuellen Einstellungen oder Werte mehrerer Felder eines Deskriptordatensatzes zurück. Die zurückgegebenen Felder beschreiben den Namen, den Datentyp und die Speicherung von Spalten- oder Parameterdaten.

Syntax

  
SQLRETURN SQLGetDescRec(  
      SQLHDESC        DescriptorHandle,  
      SQLSMALLINT     RecNumber,  
      SQLCHAR *       Name,  
      SQLSMALLINT     BufferLength,  
      SQLSMALLINT *   StringLengthPtr,  
      SQLSMALLINT *   TypePtr,  
      SQLSMALLINT *   SubTypePtr,  
      SQLLEN *        LengthPtr,  
      SQLSMALLINT *   PrecisionPtr,  
      SQLSMALLINT *   ScalePtr,  
      SQLSMALLINT *   NullablePtr);

Argumente

DescriptorHandle
[Eingabe] Deskriptorhandle.

RecNumber
[Eingabe] Gibt den Deskriptordatensatz an, aus dem die Anwendung Informationen sucht. Deskriptordatensätze werden von 1 nummeriert, wobei datensatznummer 0 der Lesezeichendatensatz ist. Das RecNumber-Argument muss kleiner oder gleich dem Wert von SQL_DESC_COUNT sein. Wenn RecNumber kleiner oder gleich SQL_DESC_COUNT ist, die Zeile jedoch keine Daten für eine Spalte oder einen Parameter enthält, gibt ein Aufruf von SQLGetDescRec die Standardwerte der Felder zurück. (Weitere Informationen finden Sie unter Initialisierung von Deskriptorfeldern in SQLSetDescField.)

Name
[Ausgabe] Ein Zeiger auf einen Puffer, in dem das SQL_DESC_NAME Feld für den Deskriptordatensatz zurückgegeben werden soll.

Wenn Name NULL ist, gibt StringLengthPtr weiterhin die Gesamtanzahl der Zeichen (mit Ausnahme des NULL-Terminierungszeichens für Zeichendaten) zurück, die im Puffer zurückgegeben werden können, auf den der Name verweist.

BufferLength
[Eingabe] Länge des *Name-Puffers in Zeichen.

StringLengthPtr
[Ausgabe] Ein Zeiger auf einen Puffer, in dem die Anzahl der Zeichen von Daten zurückgegeben werden soll, die im *Name-Puffer zurückgegeben werden können, ohne das NULL-Terminierungszeichen. Wenn die Anzahl der Zeichen größer oder gleich BufferLength war, werden die Daten in *Name in BufferLength abzüglich der Länge eines NULL-Terminierungszeichens abgeschnitten und vom Treiber null beendet.

TypePtr
[Ausgabe] Ein Zeiger auf einen Puffer, in dem der Wert des SQL_DESC_TYPE Felds für den Deskriptordatensatz zurückgegeben werden soll.

SubTypePtr
[Ausgabe] Für Datensätze, deren Typ SQL_DATETIME oder SQL_INTERVAL ist, ist dies ein Zeiger auf einen Puffer, in dem der Wert des felds SQL_DESC_DATETIME_INTERVAL_CODE zurückgegeben werden soll.

LengthPtr
[Ausgabe] Ein Zeiger auf einen Puffer, in dem der Wert des SQL_DESC_OCTET_LENGTH Felds für den Deskriptordatensatz zurückgegeben werden soll.

PrecisionPtr
[Ausgabe] Ein Zeiger auf einen Puffer, in dem der Wert des SQL_DESC_PRECISION Felds für den Deskriptordatensatz zurückgegeben werden soll.

ScalePtr
[Ausgabe] Ein Zeiger auf einen Puffer, in dem der Wert des felds SQL_DESC_SCALE für den Deskriptordatensatz zurückgegeben werden soll.

NullablePtr
[Ausgabe] Ein Zeiger auf einen Puffer, in dem der Wert des SQL_DESC_NULLABLE Felds für den Deskriptordatensatz zurückgegeben werden soll.

Gibt zurück

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_NO_DATA oder SQL_INVALID_HANDLE.

SQL_NO_DATA wird zurückgegeben, wenn RecNumber größer als die aktuelle Anzahl von Deskriptordatensätzen ist.

SQL_NO_DATA wird zurückgegeben, wenn DescriptorHandle ein IRD-Handle ist und sich die Anweisung im Zustand vorbereitet oder ausgeführt befindet, aber kein geöffneter Cursor zugeordnet war.

Diagnose

Wenn SQLGetDescRec 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 in der Regel von SQLGetDescRec 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.)
01004 Zeichenfolgendaten, rechts abgeschnitten Der Puffer *Name war nicht groß genug, um das gesamte Deskriptorfeld zurückzugeben. Daher wurde das Feld abgeschnitten. Die Länge des unwahren Deskriptorfelds wird in *StringLengthPtr zurückgegeben. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.)
07009 Ungültiger Deskriptorindex Das Argument FieldIdentifier war ein Datensatzfeld, das RecNumber-Argument wurde auf 0 festgelegt, und das Argument DescriptorHandle war ein IPD-Handle.

(DM) Das RecNumber-Argument wurde auf 0 und das Attribut der SQL_ATTR_USE_BOOKMARKS-Anweisung auf SQL_UB_OFF festgelegt, und das Argument DescriptorHandle war ein IRD-Handle.

Das RecNumber-Argument war kleiner als 0.
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 den Arbeitsspeicher nicht zuordnen, der für die Unterstützung der Ausführung oder Vervollständigung der Funktion erforderlich ist.
HY007 Zugeordnete Anweisung ist nicht vorbereitet DescriptorHandle war einer IRD zugeordnet, und das zugehörige Anweisungshandle befand sich nicht im Zustand vorbereitet oder ausgeführt.
HY010 Funktionssequenzfehler (DM) 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) DescriptorHandle wurde einem StatementHandle zugeordnet, für den SQLExecute, SQLExecDirect, SQLBulkOperations oder SQLSetPos aufgerufen 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 asynchrone Funktion wurde noch ausgeführt, als SQLGetDescRec aufgerufen wurde.
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.
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 Treiber unterstützt diese Funktion nicht. (DM) Der Treiber, der DescriptorHandle zugeordnet ist, unterstützt die Funktion nicht.

Kommentare

Eine Anwendung kann SQLGetDescRec aufrufen, um die Werte der folgenden Deskriptorfelder für eine einzelne Spalte oder einen einzelnen Parameter abzurufen:

  • SQL_DESC_NAME

  • 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_NULLABLE

SQLGetDescRec ruft die Werte für Headerfelder nicht ab.

Eine Anwendung kann die Rückgabe der Einstellung eines Felds verhindern, indem das Argument, das dem Feld entspricht, auf einen NULL-Zeiger festgelegt wird.

Wenn eine Anwendung SQLGetDescRec aufruft, um den Wert eines Felds abzurufen, das für einen bestimmten Deskriptortyp nicht definiert ist, gibt die Funktion SQL_SUCCESS zurück, aber der für das Feld zurückgegebene Wert ist nicht definiert. Das Aufrufen von SQLGetDescRec für das SQL_DESC_NAME- oder SQL_DESC_NULLABLE Feld einer APD oder ARD gibt beispielsweise SQL_SUCCESS, aber einen nicht definierten Wert für das Feld zurück.

Wenn eine Anwendung SQLGetDescRec aufruft, um den Wert eines Felds abzurufen, das für einen bestimmten Deskriptortyp definiert ist, das jedoch keinen Standardwert aufweist und noch nicht festgelegt wurde, gibt die Funktion SQL_SUCCESS zurück, aber der für das Feld zurückgegebene Wert ist nicht definiert. Weitere Informationen finden Sie unter Initialisierung von Deskriptorfeldern in SQLSetDescField.

Die Werte von Feldern können auch einzeln durch einen Aufruf von SQLGetDescField abgerufen werden. Eine Beschreibung der Felder in einem Deskriptorheader oder Datensatz finden Sie unter SQLSetDescField. Weitere Informationen zu Deskriptoren finden Sie unter Deskriptoren.

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

Weitere Informationen

ODBC-API-Referenz
ODBC-Headerdateien