Delen via

SQLSetDescRec, functie

  • Artikel

conformance
Versie geïntroduceerd: NALEVING van ODBC 3.0-standaarden: ISO 92

Samenvattings-
Met de functie SQLSetDescRec worden meerdere descriptorvelden ingesteld die van invloed zijn op het gegevenstype en de buffer die afhankelijk zijn van een kolom- of parametergegevens.

Syntaxis

  
SQLRETURN SQLSetDescRec(  
      SQLHDESC      DescriptorHandle,  
      SQLSMALLINT   RecNumber,  
      SQLSMALLINT   Type,  
      SQLSMALLINT   SubType,  
      SQLLEN        Length,  
      SQLSMALLINT   Precision,  
      SQLSMALLINT   Scale,  
      SQLPOINTER    DataPtr,  
      SQLLEN *      StringLengthPtr,  
      SQLLEN *      IndicatorPtr);

Argumenten

DescriptorHandle-
[Invoer] Descriptorgreep. Dit mag geen IRD-ingang zijn.

RecNumber
[Invoer] Geeft de descriptorrecord aan die de velden bevat die moeten worden ingesteld. Descriptorrecords worden genummerd van 0, waarbij recordnummer 0 de bladwijzerrecord is. Dit argument moet gelijk zijn aan of groter zijn dan 0. Als RecNumber groter is dan de waarde van SQL_DESC_COUNT, SQL_DESC_COUNTis gewijzigd in de waarde van RecNumber.

type
[Invoer] De waarde waarop het SQL_DESC_TYPE-veld voor de descriptorrecord moet worden ingesteld.

subtype
[Invoer] Voor records waarvan het type SQL_DATETIME of SQL_INTERVAL is, is dit de waarde waarop het SQL_DESC_DATETIME_INTERVAL_CODE veld moet worden ingesteld.

lengte
[Invoer] De waarde waarop het SQL_DESC_OCTET_LENGTH-veld voor de descriptorrecord moet worden ingesteld.

Precisie
[Invoer] De waarde waarop het SQL_DESC_PRECISION veld voor de descriptorrecord moet worden ingesteld.

schalen
[Invoer] De waarde waarop het SQL_DESC_SCALE-veld voor de descriptorrecord moet worden ingesteld.

DataPtr-
[Uitgestelde invoer of uitvoer] De waarde waarop het SQL_DESC_DATA_PTR-veld voor de descriptorrecord moet worden ingesteld. DataPtr- kan worden ingesteld op een null-aanwijzer.

Het argument DataPtr kan worden ingesteld op een null-aanwijzer om het SQL_DESC_DATA_PTR veld in te stellen op een null-aanwijzer. Als de ingang in de DescriptorHandle- argument is gekoppeld aan een ARD, wordt de kolom hiermee ontkoppeld.

StringLengthPtr-
[Uitgestelde invoer of uitvoer] De waarde waarop het SQL_DESC_OCTET_LENGTH_PTR-veld voor de descriptorrecord moet worden ingesteld. StringLengthPtr- kan worden ingesteld op een null-aanwijzer om het SQL_DESC_OCTET_LENGTH_PTR veld in te stellen op een null-aanwijzer.

IndicatorPtr-
[Uitgestelde invoer of uitvoer] De waarde waarop het SQL_DESC_INDICATOR_PTR-veld voor de descriptorrecord moet worden ingesteld. IndicatorPtr- kan worden ingesteld op een null-aanwijzer om het SQL_DESC_INDICATOR_PTR veld in te stellen op een null-aanwijzer.

Retourneert

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR of SQL_INVALID_HANDLE.

Diagnostiek

Wanneer SQLSetDescRec- SQL_ERROR of SQL_SUCCESS_WITH_INFO retourneert, kan een bijbehorende SQLSTATE-waarde worden verkregen door SQLGetDiagRec- aan te roepen met een HandleType- van SQL_HANDLE_DESC en een Handle van DescriptorHandle. De volgende tabel bevat de SQLSTATE-waarden die vaak worden geretourneerd door SQLSetDescRec- en legt elke waarden uit in de context van deze functie; de notatie (DM)' voorafgaat aan de beschrijvingen van SQLSTATEs die worden geretourneerd door Driver Manager. De retourcode die is gekoppeld aan elke SQLSTATE-waarde is SQL_ERROR, tenzij anders vermeld.

SQLSTATE Fout Beschrijving
01000 Algemene waarschuwing Stuurprogrammaspecifiek informatiebericht. (Functie retourneert SQL_SUCCESS_WITH_INFO.)
07009 Ongeldige descriptorindex Het argument RecNumber is ingesteld op 0 en de DescriptorHandle verwezen naar een IPD-ingang.

Het argument RecNumber is kleiner dan 0.

Het argument RecNumber is groter dan het maximum aantal kolommen of parameters dat door de gegevensbron kan worden ondersteund. Het argument DescriptorHandle argument was een APD, IPD of ARD.

Het argument RecNumber is gelijk aan 0 en het argument DescriptorHandle verwijst naar een impliciet toegewezen APD. (Deze fout treedt niet op met een expliciet toegewezen toepassingsdescriptor omdat deze niet bekend is of een expliciet toegewezen toepassingsdescriptor een APD of ARD is totdat de uitvoering is uitgevoerd.)
08S01 Communicatiekoppelingsfout De communicatiekoppeling tussen het stuurprogramma en de gegevensbron waarmee het stuurprogramma is verbonden, is mislukt voordat de verwerking van de functie is voltooid.
HY000 Algemene fout Er is een fout opgetreden waarvoor er geen specifieke SQLSTATE is en waarvoor geen implementatiespecifieke SQLSTATE is gedefinieerd. Het foutbericht dat is geretourneerd door SQLGetDiagRec- in de *MessageText buffer beschrijft de fout en de oorzaak ervan.
HY001 Fout bij geheugentoewijzing Het stuurprogramma kan geen geheugen toewijzen dat nodig is om de uitvoering of voltooiing van de functie te ondersteunen.
HY010 Fout in functiereeks (DM) De DescriptorHandle- is gekoppeld aan een StatementHandle- waarvoor een asynchroon uitgevoerde functie (niet deze) werd aangeroepen en nog steeds werd uitgevoerd toen deze functie werd aangeroepen.

(DM) SQLExecute, SQLExecDirect, SQLBulkOperationsof SQLSetPos is aangeroepen voor de StatementHandle- waarmee de DescriptorHandle- is gekoppeld en SQL_NEED_DATA is geretourneerd. Deze functie is aangeroepen voordat gegevens werden verzonden voor alle parameters of kolommen voor uitvoering van gegevens.

(DM) Er is een asynchroon uitgevoerde functie aangeroepen voor de verbindingsgreep die is gekoppeld aan de DescriptorHandle-. Deze asynchrone functie werd nog steeds uitgevoerd toen de SQLSetDescRec--functie werd aangeroepen.

(DM) SQLExecute, SQLExecDirectof SQLMoreResults is aangeroepen voor een van de instructiegrepen die zijn gekoppeld aan de DescriptorHandle- en SQL_PARAM_DATA_AVAILABLE geretourneerd. Deze functie is aangeroepen voordat gegevens zijn opgehaald voor alle gestreamde parameters.
HY013 Fout bij geheugenbeheer De functie-aanroep kan niet worden verwerkt omdat de onderliggende geheugenobjecten niet kunnen worden geopend, mogelijk vanwege weinig geheugen.
HY016 Kan de beschrijving van een implementatierij niet wijzigen Het argument DescriptorHandle is gekoppeld aan een IRD.
HY021 Inconsistente beschrijvingsinformatie Het -veld of een ander veld dat is gekoppeld aan het SQL_DESC_TYPE veld in de descriptor, is ongeldig of consistent.

Descriptorgegevens die tijdens een consistentiecontrole zijn gecontroleerd, waren niet consistent. (Zie Consistentiecontroles verderop in deze sectie.)
HY090 Ongeldige tekenreeks- of bufferlengte (DM) Het stuurprogramma was een ODBC-2.x stuurprogramma, de descriptor was een ARD, het argument ColumnNumber is ingesteld op 0 en de waarde die is opgegeven voor het argument BufferLength niet gelijk is aan 4.
HY117 De verbinding is onderbroken vanwege een onbekende transactiestatus. Alleen de verbinding verbreken en alleen-lezenfuncties zijn toegestaan. (DM) Zie SQLEndTran Functionvoor meer informatie over de onderbroken status.
HYT01 Time-out voor verbinding verlopen De time-outperiode voor de verbinding is verlopen voordat de gegevensbron op de aanvraag heeft gereageerd. De time-outperiode voor de verbinding wordt ingesteld via SQLSetConnectAttr-, SQL_ATTR_CONNECTION_TIMEOUT.
IM001 Stuurprogramma biedt geen ondersteuning voor deze functie (DM) Het stuurprogramma dat is gekoppeld aan de DescriptorHandle- biedt geen ondersteuning voor de functie.

Opmerkingen

Een toepassing kan SQLSetDescRec- aanroepen om de volgende velden in te stellen voor één kolom of parameter:

  • SQL_DESC_TYPE

  • SQL_DESC_DATETIME_INTERVAL_CODE (voor records waarvan het type is SQL_DATETIME of 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

Notitie

Als een aanroep naar SQLSetDescRec- mislukt, is de inhoud van de descriptorrecord die is geïdentificeerd door het argument RecNumber niet gedefinieerd.

Wanneer u een kolom of parameter bindt, kunt u SQLSetDescRec- meerdere velden wijzigen die van invloed zijn op de binding zonder SQLBindCol- of SQLBindParameter- aan te roepen of meerdere aanroepen naar SQLSetDescField-aan te roepen. SQLSetDescRec- kan velden instellen op een descriptor die momenteel niet is gekoppeld aan een instructie. Houd er rekening mee dat SQLBindParameter meer velden instelt dan SQLSetDescRec-, velden kan instellen op zowel een APD als een IPD in één aanroep en geen descriptor-handle vereist.

Notitie

Het instructiekenmerk SQL_ATTR_USE_BOOKMARKS moet altijd worden ingesteld voordat u SQLSetDescRec- aanroept met een RecNumber argument van 0 om bladwijzervelden in te stellen. Hoewel dit niet verplicht is, wordt het sterk aanbevolen.

Consistentiecontroles

Er wordt automatisch een consistentiecontrole uitgevoerd door het stuurprogramma wanneer een toepassing het SQL_DESC_DATA_PTR veld van een APD, ARD of IPD instelt. Als een van de velden inconsistent is met andere velden, retourneert SQLSetDescRec- SQLSTATE HY021 (inconsistente descriptorgegevens).

Wanneer een toepassing het SQL_DESC_DATA_PTR veld van een APD, ARD of IPD instelt, controleert het stuurprogramma of de waarde van het SQL_DESC_TYPE veld en de waarden die van toepassing zijn op dat SQL_DESC_TYPE veld geldig en consistent zijn. Deze controle wordt altijd uitgevoerd wanneer SQLBindParameter- of SQLBindCol- wordt aangeroepen of wanneer SQLSetDescRec- wordt aangeroepen voor een APD, ARD of IPD. Deze consistentiecontrole bevat de volgende controles voor descriptorvelden:

  • Het SQL_DESC_TYPE veld moet een van de geldige ODBC C- of SQL-typen of een stuurprogrammaspecifiek SQL-type zijn. Het SQL_DESC_CONCISE_TYPE veld moet een van de geldige ODBC C- of SQL-typen of een stuurprogrammaspecifiek C- of SQL-type zijn, inclusief de beknopte datum/tijd- en intervaltypen.

  • Als het SQL_DESC_TYPE recordveld is SQL_DATETIME of SQL_INTERVAL, moet het SQL_DESC_DATETIME_INTERVAL_CODE veld een van de geldige datum/tijd- of intervalcodes zijn. (Zie de beschrijving van het veld SQL_DESC_DATETIME_INTERVAL_CODE in SQLSetDescField.)

  • Als in het SQL_DESC_TYPE veld een numeriek type wordt aangegeven, worden de SQL_DESC_PRECISION- en SQL_DESC_SCALE-velden geverifieerd als geldig.

  • Als het SQL_DESC_CONCISE_TYPE veld een tijd- of tijdstempelgegevenstype is, een intervaltype met een secondenonderdeel of een van de intervalgegevenstypen met een tijdonderdeel, wordt het SQL_DESC_PRECISION veld gecontroleerd op een geldige secondenprecisie.

  • Als het SQL_DESC_CONCISE_TYPE een gegevenstype interval is, wordt het SQL_DESC_DATETIME_INTERVAL_PRECISION veld geverifieerd als een geldige, voorloopprecisiewaarde voor een interval.

Het SQL_DESC_DATA_PTR veld van een IPD is normaal gesproken niet ingesteld; Een toepassing kan dit echter doen om een consistentiecontrole van IPD-velden af te dwingen. Een consistentiecontrole kan niet worden uitgevoerd op een IRD. De waarde waarop het SQL_DESC_DATA_PTR veld van de IPD is ingesteld, wordt niet daadwerkelijk opgeslagen en kan niet worden opgehaald door een aanroep naar SQLGetDescField of SQLGetDescRec-; de instelling wordt alleen gemaakt om de consistentiecontrole af te dwingen.

Voor informatie over Zien
Een kolom binden SQLBindCol-functie
Een parameter binden SQLBindParameter-functie
Eén descriptorveld verkrijgen SQLGetDescField-functie
Meerdere descriptorvelden verkrijgen SQLGetDescRec-functie
Velden met één descriptor instellen SQLSetDescField-functie

Zie ook

ODBC-API-verwijzing
ODBC-headerbestanden