SQLGetDescField-funktion

Överensstämmelse
Version introducerad: ODBC 3.0 Standardsefterlevnad: ISO 92

Summary
SQLGetDescField returnerar den aktuella inställningen eller värdet för ett enskilt fält i en deskriptorpost.

Syntax

  
SQLRETURN SQLGetDescField(  
     SQLHDESC        DescriptorHandle,  
     SQLSMALLINT     RecNumber,  
     SQLSMALLINT     FieldIdentifier,  
     SQLPOINTER      ValuePtr,  
     SQLINTEGER      BufferLength,  
     SQLINTEGER *    StringLengthPtr);  

Arguments

DescriptorHandle
[Input] Beskrivningshandtag.

RecNumber
[Input] Anger deskriptorposten från vilken ansökan söker information. Deskriptorposter numreras från 0, där post nummer 0 är bokmärkesposten. Om argumentet FieldIdentifier indikerar ett headerfält ignoreras RecNumber . Om RecNumber är mindre än eller lika med SQL_DESC_COUNT men raden inte innehåller data för en kolumn eller parameter, kommer ett anrop till SQLGetDescField att returnera standardvärdena för fälten. (För mer information, se "Initialisering av deskriptorfält" i SQLSetDescField.)

FieldIdentifier
[Input] Anger fältet för den beskrivare vars värde ska returneras. För mer information, se avsnittet "FieldIdentifier Argument " i SQLSetDescField.

ValuePtr
[Utdata] Peka till en buffert där man returnerar deskriptorinformationen. Datatypen beror på värdet på FieldIdentifier.

Om ValuePtr är heltalstyp bör applikationer använda en buffert av SQLULEN och initialisera värdet till 0 innan denna funktion anropas, eftersom vissa drivrutiner kan skriva de lägre 32- eller 16-bitarna i en buffert och låta den högre ordningens biten vara oförändrad.

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

BufferLength
[Input] Om FieldIdentifier är ett ODBC-definierat fält och ValuePtr pekar på en teckensträng eller en binär buffert, bör detta argument vara längden på *ValuePtr. Om FieldIdentifier är ett ODBC-definierat fält och *ValuePtr är ett heltal, ignoreras BufferLength . Om värdet i *ValuePtr är av en Unicode-datatyp (vid anrop av SQLGetDescFieldW), måste BufferLength-argumentet vara ett jämnt tal.

Om FieldIdentifier är ett drivrutinsdefinierat fält anger applikationen fältets natur till Driver Manager genom att sätta argumentet BufferLength . BufferLength kan ha följande värden:

• Om *ValuePtr är en pekare till en teckensträng, så är BufferLength längden på strängen eller SQL_NTS.

• Om *ValuePtr är en pekare till en binär buffert, placerar applikationen resultatet av makrot SQL_LEN_BINARY_ATTR(längd) i BufferLength. Detta placerar ett negativt värde i BufferLength.

• Om *ValuePtr är en pekare till ett annat värde än en teckensträng eller binär sträng, så bör BufferLength ha värdet SQL_IS_POINTER.

• Om *ValuePtr innehåller en datatyp med fast längd, så är BufferLength antingen SQL_IS_INTEGER, SQL_IS_UINTEGER, SQL_IS_SMALLINT eller SQL_IS_USMALLINT, beroende på vad som är lämpligt.

StringLengthPtr
[Utdata] Pekare till bufferten där det totala antalet byte (exklusive antalet byte som krävs för null-termineringstecknet) ska returneras i *ValuePtr.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_NO_DATA eller SQL_INVALID_HANDLE.

SQL_NO_DATA returneras om RecNumber är större än det aktuella antalet deskriptorposter.

SQL_NO_DATA returneras om DescriptorHandle är ett IRD-handtag och satsen är i förberedd eller exekverad status men ingen öppen markör var kopplad till den.

Diagnostics

När SQLGetDescField returnerar SQL_ERROR eller SQL_SUCCESS_WITH_INFO kan ett associerat SQLSTATE-värde erhållas genom att anropa SQLGetDiagRec med HandleType av SQL_HANDLE_STMT och ett Handle av StatementHandle. Följande tabell listar de SQLSTATE-värden som vanligtvis returneras av SQLGetDescField 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.

Comments

En applikation kan anropa SQLGetDescField för att returnera värdet av ett enda fält i en deskriptorpost. Ett anrop till SQLGetDescField kan returnera inställningen för vilket fält som helst i vilken deskriptortyp som helst, inklusive headerfält, postfält och bokmärkesfält. En applikation kan få inställningarna för flera fält i samma eller olika deskriptorer, i godtycklig ordning, genom att göra upprepade anrop till SQLGetDescField. SQLGetDescField kan också anropas för att returnera drivrutinsdefinierade deskriptorfält.

Av prestandaskäl bör en applikation inte anropa SQLGetDescField för en IRD innan en sats exekveras.

Inställningarna för flera fält som beskriver namn, datatyp och lagring av kolumn- eller parameterdata kan också hämtas i ett enda anrop till SQLGetDescRec. SQLGetStmtAttr kan anropas för att returnera inställningen för ett enda fält i beskrivarhuvudet som också är ett statementattribut. SQLColAttribute, SQLDescribeCol och SQLDescribeParam returnerar post- eller bokmärkesfält.

När en applikation anropar SQLGetDescField för att hämta värdet av ett fält som är odefinierat för en viss deskriptortyp, returnerar funktionen SQL_SUCCESS men värdet som returneras för fältet är odefinierat. Till exempel, att anropa SQLGetDescField för SQL_DESC_NAME eller SQL_DESC_NULLABLE fält i en APD eller ARD kommer att returnera SQL_SUCCESS men ett odefinierat värde för fältet.

När en applikation anropar SQLGetDescField för att hämta värdet av ett fält som är definierat för en viss deskriptortyp men som inte har något standardvärde och ännu inte har satts, returnerar funktionen SQL_SUCCESS men värdet som returneras för fältet är odefinierat. För mer information om initialisering av deskriptorfält och beskrivningar av fälten, se "Initialisering av deskriptorfält" i SQLSetDescField. För mer information om deskriptorer, se Descriptors.

Relaterade funktioner

Relaterat innehåll

• ODBC API-referens
• ODBC-huvudfiler