SQLSetDescRec-funktion
Efterlevnad
Version introducerad: ODBC 3.0 Standardefterlevnad: ISO 92
Sammanfattning
Funktionen SQLSetDescRec anger flera beskrivande fält som påverkar datatypen och bufferten som är bunden till en kolumn eller parameterdata.
Syntax
SQLRETURN SQLSetDescRec(
SQLHDESC DescriptorHandle,
SQLSMALLINT RecNumber,
SQLSMALLINT Type,
SQLSMALLINT SubType,
SQLLEN Length,
SQLSMALLINT Precision,
SQLSMALLINT Scale,
SQLPOINTER DataPtr,
SQLLEN * StringLengthPtr,
SQLLEN * IndicatorPtr);
Argument
DescriptorHandle
[Indata] Descriptor-handtag. Detta får inte vara ett IRD-handtag.
RecNumber
[Indata] Anger den deskriptorpost som innehåller de fält som ska anges. Deskriptorposter numreras från 0, där postnummer 0 är bokmärkesposten. Det här argumentet måste vara lika med eller större än 0. Om RecNumber är större än värdet för SQL_DESC_COUNT ändras SQL_DESC_COUNTis till värdet för RecNumber.
typ
[Indata] Det värde som du vill ange fältet SQL_DESC_TYPE till för beskrivningsposten.
SubType
[Indata] För poster vars typ är SQL_DATETIME eller SQL_INTERVAL är detta det värde som fältet SQL_DESC_DATETIME_INTERVAL_CODE ska anges till.
längd
[Indata] Värdet som du vill ange fältet SQL_DESC_OCTET_LENGTH för beskrivningsposten till.
Precision
[Indata] Värdet som du vill ange fältet SQL_DESC_PRECISION till för beskrivningsposten.
Skala
[Indata] Det värde som fältet SQL_DESC_SCALE för beskrivningsposten ska anges till.
DataPtr
[Uppskjutna indata eller utdata] Det värde som fältet SQL_DESC_DATA_PTR för beskrivningsposten ska anges till.
DataPtr kan ställas in på en null-pekare.
Argumentet DataPtr kan anges till en nullpekare för att ange fältet SQL_DESC_DATA_PTR till en null-pekare. Om handtaget i argumentet DescriptorHandle är associerat med en ARD avbinds kolumnen.
StringLengthPtr
[Uppskjutna indata eller utdata] Värdet som fältet SQL_DESC_OCTET_LENGTH_PTR för beskrivningsposten ska anges till.
StringLengthPtr kan ställas in på en null-pekare för att ange fältet SQL_DESC_OCTET_LENGTH_PTR till en null-pekare.
IndicatorPtr
[Uppskjutna indata eller utdata] Det värde som fältet SQL_DESC_INDICATOR_PTR för beskrivningsposten ska anges till.
IndicatorPtr kan ställas in på en null-pekare för att ange fältet SQL_DESC_INDICATOR_PTR till en null-pekare.
Returnerar
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR eller SQL_INVALID_HANDLE.
Diagnostik
När SQLSetDescRec- returnerar SQL_ERROR eller SQL_SUCCESS_WITH_INFO kan du hämta ett associerat SQLSTATE-värde genom att anropa SQLGetDiagRec med en HandleType- av SQL_HANDLE_DESC och en Handle för DescriptorHandle. I följande tabell visas de SQLSTATE-värden som ofta returneras av SQLSetDescRec och förklarar var och en i kontexten för den här funktionen. notationen "(DM)" föregår beskrivningarna av SQLSTATEs som returneras av Driver Manager. Returkoden som är associerad med varje SQLSTATE-värde är SQL_ERROR, om inget annat anges.
| SQLSTATE | Fel | Beskrivning |
|---|---|---|
| 01000 | Allmän varning | Informationsmeddelande för drivrutinsspecifikt. (Funktionen returnerar SQL_SUCCESS_WITH_INFO.) |
| 07009 | Ogiltigt deskriptorindex | Argumentet RecNumber angavs till 0 och DescriptorHandle- refererade till en IPD-referens. Argumentet RecNumber var mindre än 0. Argumentet RecNumber var större än det maximala antalet kolumner eller parametrar som datakällan kan stödja, och argumentet DescriptorHandle var en APD, IPD eller ARD. Argumentet RecNumber var lika med 0 och argumentet DescriptorHandle refererade till en implicit allokerad APD. (Det här felet uppstår inte med en uttryckligen allokerad programbeskrivning eftersom det inte är känt om en uttryckligen allokerad programbeskrivning är en APD eller ARD förrän körningstiden.) |
| 08S01 | Kommunikationslänkfel | Kommunikationslänken mellan drivrutinen och datakällan som drivrutinen var ansluten till misslyckades innan funktionen slutförde bearbetningen. |
| HY000 | Allmänt fel | Ett fel uppstod för vilket det inte fanns någon specifik SQLSTATE och för vilken ingen implementeringsspecifik SQLSTATE definierades. Felmeddelandet som returneras av SQLGetDiagRec i bufferten *MessageText beskriver felet och orsaken. |
| HY001 | Fel vid minnesallokering | Drivrutinen kunde inte allokera minne som krävs för körning eller slutförande av funktionen. |
| HY010 | Funktionssekvensfel | (DM) DescriptorHandle- var associerad med en StatementHandle- som en asynkront kör funktion (inte den här) anropades för och fortfarande kördes när den här funktionen anropades. (DM) SQLExecute, SQLExecDirect, SQLBulkOperationseller SQLSetPos anropades för StatementHandle- som DescriptorHandle var associerad med och returnerades SQL_NEED_DATA. Den här funktionen anropades innan data skickades för alla data-at-execution-parametrar eller kolumner. (DM) En asynkront körande funktion anropades för anslutningshandtaget som är associerat med DescriptorHandle. Den här asynkrona funktionen kördes fortfarande när funktionen SQLSetDescRec anropades. (DM) SQLExecute, SQLExecDirecteller SQLMoreResults anropades för någon av de instruktionsreferenser som är associerade med DescriptorHandle och returnerade SQL_PARAM_DATA_AVAILABLE. Den här funktionen anropades innan data hämtades för alla strömmade parametrar. |
| HY013 | Minneshanteringsfel | Det gick inte att bearbeta funktionsanropet eftersom det inte gick att komma åt underliggande minnesobjekt, möjligen på grund av minnesbrist. |
| HY016 | Det går inte att ändra en beskrivning av en implementeringsrad | Argumentet DescriptorHandle var associerat med en IRD. |
| HY021 | Inkonsekvent beskrivningsinformation | Fältet Typ, eller något annat fält som är associerat med fältet SQL_DESC_TYPE i beskrivningen, var inte giltigt eller konsekvent. Beskrivningsinformationen som kontrollerades under en konsekvenskontroll var inte konsekvent. (Se "Konsekvenskontroller" senare i det här avsnittet.) |
| HY090 | Ogiltig sträng- eller buffertlängd | (DM) Drivrutinen var en ODBC-2.x drivrutin, beskrivningen var en ARD, argumentet ColumnNumber angavs till 0 och värdet som angavs för argumentet BufferLength inte var lika med 4. |
| HY117 | Anslutningen pausas på grund av okänt transaktionstillstånd. Endast frånkopplings- och skrivskyddade funktioner tillåts. | (DM) Mer information om inaktiverat tillstånd finns i SQLEndTran Function. |
| HYT01 | Tidsgränsen för anslutningen har upphört att gälla | Tidsgränsen för anslutningen löpte ut innan datakällan svarade på begäran. Tidsgränsen för anslutningen anges via SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Drivrutinen stöder inte den här funktionen | (DM) Drivrutinen som är associerad med DescriptorHandle stöder inte funktionen. |
Kommentarer
Ett program kan anropa SQLSetDescRec för att ange följande fält för en enskild kolumn eller parameter:
SQL_DESC_TYPE
SQL_DESC_DATETIME_INTERVAL_CODE (för poster vars typ är SQL_DATETIME eller SQL_INTERVAL)
SQL_DESC_OCTET_LENGTH
SQL_DESC_PRECISION
SQL_DESC_SCALE
SQL_DESC_DATA_PTR
SQL_DESC_OCTET_LENGTH_PTR
SQL_DESC_INDICATOR_PTR
Not
Om ett anrop till SQLSetDescRec misslyckas, är innehållet i den deskriptorpost som identifieras av argumentet RecNumber odefinierat.
När du binder en kolumn eller parameter kan du SQLSetDescRec ändra flera fält som påverkar bindningen utan att anropa SQLBindCol eller SQLBindParameter eller göra flera anrop till SQLSetDescField. SQLSetDescRec kan ange fält på en beskrivning som för närvarande inte är associerad med en -instruktion. Observera att SQLBindParameter anger fler fält än SQLSetDescRec, kan ange fält på både en APD och en IPD i ett anrop och kräver inte någon beskrivningsreferens.
Not
Instruktionsattributet SQL_ATTR_USE_BOOKMARKS bör alltid anges innan du anropar SQLSetDescRec med ett RecNumber argument 0 för att ange bokmärkesfält. Även om detta inte är obligatoriskt rekommenderas det starkt.
Konsekvenskontroller
En konsekvenskontroll utförs automatiskt av drivrutinen när ett program anger fältet SQL_DESC_DATA_PTR för en APD, ARD eller IPD. Om något av fälten är inkonsekvent med andra fält returnerar SQLSetDescRec SQLSTATE HY021 (inkonsekvent beskrivningsinformation).
När ett program anger SQL_DESC_DATA_PTR fältet för en APD, ARD eller IPD kontrollerar drivrutinen att värdet för fältet SQL_DESC_TYPE och de värden som gäller för det SQL_DESC_TYPE fältet är giltiga och konsekventa. Den här kontrollen utförs alltid när SQLBindParameter eller SQLBindCol- anropas eller när SQLSetDescRec- anropas för en APD, ARD eller IPD. Den här konsekvenskontrollen innehåller följande kontroller av deskriptorfält:
Fältet SQL_DESC_TYPE måste vara en av de giltiga ODBC C- eller SQL-typerna eller en drivrutinsspecifik SQL-typ. Fältet SQL_DESC_CONCISE_TYPE måste vara en av de giltiga ODBC C- eller SQL-typerna eller en drivrutinsspecifik C- eller SQL-typ, inklusive de koncisa datumtids- och intervalltyperna.
Om fältet SQL_DESC_TYPE post är SQL_DATETIME eller SQL_INTERVAL måste fältet SQL_DESC_DATETIME_INTERVAL_CODE vara en av de giltiga datum- eller intervallkoderna. (Se beskrivningen av fältet SQL_DESC_DATETIME_INTERVAL_CODE i SQLSetDescField.)
Om fältet SQL_DESC_TYPE anger en numerisk typ verifieras fälten SQL_DESC_PRECISION och SQL_DESC_SCALE vara giltiga.
Om det SQL_DESC_CONCISE_TYPE fältet är en tids- eller tidsstämpeldatatyp, en intervalltyp med en sekundkomponent eller en av intervalldatatyperna med en tidskomponent, verifieras fältet SQL_DESC_PRECISION vara en giltig sekunders precision.
Om SQL_DESC_CONCISE_TYPE är en intervalldatatyp verifieras fältet SQL_DESC_DATETIME_INTERVAL_PRECISION vara ett giltigt intervallledande precisionsvärde.
Fältet SQL_DESC_DATA_PTR för en IPD anges normalt inte. Ett program kan dock göra det för att tvinga fram en konsekvenskontroll av IPD-fält. Det går inte att utföra en konsekvenskontroll på en IRD. Värdet som det SQL_DESC_DATA_PTR fältet för IPD är inställt på lagras inte och kan inte hämtas av ett anrop till SQLGetDescField eller SQLGetDescRec; inställningen görs endast för att framtvinga konsekvenskontrollen.
Relaterade funktioner
| Mer information om | Se |
|---|---|
| Binda en kolumn | SQLBindCol Function |
| Binda en parameter | SQLBindParameter Function |
| Hämta ett enda deskriptorfält | SQLGetDescField Function |
| Hämta flera deskriptorfält | SQLGetDescRec-funktion |
| Ange enkla deskriptorfält | SQLSetDescField-funktion |