SQLDescribeCol-funktion

Överensstämmelse
Version introducerad: ODBC 1.0 Standardefterlevnad: ISO 92

Summary
SQLDescribeCol returnerar resultatbeskrivaren – kolumnnamn, typ, kolumnstorlek, decimalsiffror och nullbarhet – för en kolumn i resultatuppsättningen. Denna information finns också tillgänglig inom IRD:s områden.

Syntax

  
SQLRETURN SQLDescribeCol(  
      SQLHSTMT       StatementHandle,  
      SQLUSMALLINT   ColumnNumber,  
      SQLCHAR *      ColumnName,  
      SQLSMALLINT    BufferLength,  
      SQLSMALLINT *  NameLengthPtr,  
      SQLSMALLINT *  DataTypePtr,  
      SQLULEN *      ColumnSizePtr,  
      SQLSMALLINT *  DecimalDigitsPtr,  
      SQLSMALLINT *  NullablePtr);  

Arguments

StatementHandle
[Indata] Instruktionshandtag.

Kolumnnummer
[Input] Kolumnnummer för resultatdata, ordnat sekventiellt i ökande kolumnordning, med start från 1. Argumentet ColumnNumber kan också sättas till 0 för att beskriva bokmärkeskolumnen.

KolumnNamn
[Utdata] Pekare till en nollterminerad buffert där kolumnnamnet ska returneras. Detta värde läses från IRD:ns SQL_DESC_NAME fält. Om kolumnen är namnlös eller kolumnnamnet inte kan bestämmas, returnerar drivrutinen en tom sträng.

Om ColumnName är NULL kommer NameLengthPtr ändå att returnera det totala antalet tecken (exklusive null-termineringstecknet för teckendata) som finns tillgängliga att returnera i bufferten som ColumnName pekar på.

BufferLength
[Input] Längden på *ColumnName-bufferten , i tecken.

NameLengthPtr
[Utdata] Pekare till en buffert där det totala antalet tecken (exklusive null-termination) kan returneras i *KolumnNamn. Om antalet tecken som kan returneras är större än eller lika med BufferLength, förkortas kolumnnamnet i *ColumnName till BufferLength minus längden på ett null-termineringstecken.

DataTypePtr
[Utdata] Peka till en buffert där man returnerar kolumnens SQL-datatyp. Detta värde läses från IRD:ns SQL_DESC_CONCISE_TYPE fält. Detta kommer att vara ett av värdena i SQL Data Types, eller en drivrutinsspecifik SQL-datatyp. Om datatypen inte kan bestämmas, returnerar drivrutinen SQL_UNKNOWN_TYPE.

I ODBC 3. x, SQL_TYPE_DATE, SQL_TYPE_TIME eller SQL_TYPE_TIMESTAMP returneras i *DataTypePtr för datum-, tid- eller tidsstämpeldata, respektive; i ODBC 2. x, SQL_DATE, SQL_TIME eller SQL_TIMESTAMP returneras. Driver Manager utför de nödvändiga mappningarna när en ODBC 2 är en dator. x applikation fungerar med en ODBC 3. x-drivrutin eller när en ODBC 3. x-applikationen fungerar med en ODBC 2. X-drivrutin .

När Kolumnnummer är lika med 0 (för en bokmärkeskolumn) returneras SQL_BINARY i *DataTypePtr för bokmärken med variabel längd. (SQL_INTEGER returneras om bokmärken används av en ODBC 3. x applikation som fungerar med en ODBC 2. x driver eller av en ODBC 2. x applikation som fungerar med en ODBC 3. X-drivrutin .)

För mer information om dessa datatyper, se SQL Data Types i Appendix D: Data Types. Information om drivrutinsspecifika SQL-datatyper finns i drivrutinsdokumentationen.

ColumnSizePtr
[Utdata] Pekare till en buffert där man returnerar kolumnens storlek (i tecken) på datakällan. Om kolumnstorleken inte kan bestämmas, returnerar drivrutinen 0. För mer information om kolumnstorlek, se Kolumnstorlek, decimalsiffror, Transfer Oktett Length och Display Size i Appendix D: Data Types.

DecimalDigitsPtr
[Utdata] Pekare till en buffert där man returnerar antalet decimalsiffror i kolumnen på datakällan. Om antalet decimalsiffror inte kan bestämmas eller inte är tillämpligt, returnerar föraren 0. För mer information om decimalsiffror, se Kolumnstorlek, Decimalsiffror, Överföring av oktettlängd och Visningsstorlek i Appendix D: Datatyper.

NullablePtr
[Utdata] Pekare till en buffert där ett värde returneras som visar om kolumnen tillåter NULL-värden. Detta värde läses från IRD:ns SQL_DESC_NULLABLE fält. Värdet är något av följande:

SQL_NO_NULLS: Kolumnen tillåter inte NULL-värden.

SQL_NULLABLE: Kolumnen tillåter NULL-värden.

SQL_NULLABLE_UNKNOWN: Drivrutinen kan inte avgöra om kolumnen tillåter NULL-värden.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR eller SQL_INVALID_HANDLE.

Diagnostics

När SQLDescribeCol returnerar antingen SQL_ERROR eller SQL_SUCCESS_WITH_INFO kan ett associerat SQLSTATE-värde erhållas genom att anropa SQLGetDiagRec med en HandleType av SQL_HANDLE_STMT och ett Handle of StatementHandle. Följande tabell listar de SQLSTATE-värden som vanligtvis returneras av SQLDescribeCol och förklarar var och en i kontexten av denna funktion; notationen "(DM)" föregår beskrivningarna av SQLSTATE som returneras av Driver Manager. Returkoden som är associerad med varje SQLSTATE-värde är SQL_ERROR, om inget annat anges.

SQLDescribeCol kan returnera vilken SQLSTATE som helst som kan returneras av SQLPrepare eller SQLExecute när de anropas efter SQLPrepare och före SQLExecute, beroende på när datakällan utvärderar SQL-satsen kopplad till satshandtaget.

Av prestandaskäl bör en applikation inte anropa SQLDescribeCol innan en sats exekveras.

Comments

En applikation anropar vanligtvis SQLDescribeCol efter ett anrop till SQLPrepare och före eller efter det tillhörande anropet till SQLExecute. En applikation kan också anropa SQLDescribeCol efter ett anrop till SQLExecDirect. Mer information finns i Metadata för resultatuppsättning.

SQLDescribeCol hämtar kolumnnamn, typ och längd som genereras av ett SELECT-uttalande . Om kolumnen är ett uttryck är *ColumnName antingen en tom sträng eller ett drivrutinsdefinierat namn.

Relaterade funktioner

Relaterat innehåll

• ODBC API-referens
• ODBC-huvudfiler