SQLSetStmtAttr-functie

Conformiteit
Versie geïntroduceerd: ODBC 3.0 Standaardnaleving: ISO 92

Samenvatting
SQLSetStmtAttr stelt attributen in die gerelateerd zijn aan een instructie.

Syntax

  
SQLRETURN SQLSetStmtAttr(  
     SQLHSTMT      StatementHandle,  
     SQLINTEGER    Attribute,  
     SQLPOINTER    ValuePtr,  
     SQLINTEGER    StringLength);  

Arguments

StatementHandle
[Invoer] Instructiehandgreep.

Attribuut
[Invoer] Optie om in te stellen, vermeld in "Reacties."

ValuePtr
[Invoer] Waarde wordt gekoppeld aan Attribuut. Afhankelijk van de waarde van Attribuut zal ValuePtr een van de volgende zijn:

• Een ODBC-descriptor-handvat.

• Een SQLUINTEGER-waarde.

• Een SQLULEN-waarde.

• Een verwijzing naar een van de volgende:

  • Een null-terminated tekenreeks.

  • Een binaire buffer.

  • Een waarde of array van het type SQLLEN, SQLULEN of SQLUSMALLINT.

  • Een door de bestuurder gedefinieerde waarde.

Als het Attribuut-argument een driver-specifieke waarde is, kan ValuePtr een getekend geheel getal zijn.

StringLength
[Invoer] Als Attribuut een ODBC-gedefinieerd attribuut is en ValuePtr wijst naar een tekenstring of een binaire buffer, zou dit argument de lengte van *ValuePtr moeten zijn. Als Attribuut een ODBC-gedefinieerd attribuut is en ValuePtr een geheel getal, wordt StringLength genegeerd.

Als Attribuut een door een driver gedefinieerd attribuut is, geeft de applicatie de aard van het attribuut aan bij de Driver Manager door het StringLength-argument in te stellen. StringLength kan de volgende waarden hebben:

• Als ValuePtr een pointer is naar een tekenstring, dan is StringLength de lengte van de string of SQL_NTS.

• Als ValuePtr een pointer is naar een binaire buffer, plaatst de applicatie het resultaat van de macro SQL_LEN_BINARY_ATTR(length) in StringLength. Dit plaatst een negatieve waarde in StringLength.

• Als ValuePtr een pointer is naar een waarde die anders is dan een tekenstring of een binaire string, dan zou StringLength de waarde SQL_IS_POINTER moeten hebben.

• Als ValuePtr een waarde met vaste lengte bevat, dan is StringLength ofwel SQL_IS_INTEGER of SQL_IS_UINTEGER, afhankelijk van toepassing.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR of SQL_INVALID_HANDLE.

Diagnostics

Wanneer SQLSetStmtAttr SQL_ERROR of SQL_SUCCESS_WITH_INFO teruggeeft, kan een bijbehorende SQLSTATE-waarde worden verkregen door SQLGetDiagRec aan te roepen met een HandleType van SQL_HANDLE_STMT en een Handle van StatementHandle. De volgende tabel geeft een overzicht van de SQLSTATE-waarden die vaak door SQLSetStmtAttr worden geretourneerd en legt elk uit in de context van deze functie; de notatie "(DM)" gaat vooraf aan de beschrijvingen van SQLSTATES die door de Driver Manager worden teruggegeven. De retourcode die is gekoppeld aan elke SQLSTATE-waarde is SQL_ERROR, tenzij anders vermeld.

Comments

Statementattributen voor een statement blijven van kracht totdat ze worden gewijzigd door een andere aanroep naar SQLSetStmtAttr of totdat de instructie wordt verwijderd door SQLFreeHandle aan te roepen. Het aanroepen van SQLFreeStmt met de optie SQL_CLOSE, SQL_UNBIND of SQL_RESET_PARAMS reset de statementattributen niet.

Sommige statementattributen ondersteunen substitutie van een vergelijkbare waarde als de databron de in ValuePtr gespecificeerde waarde niet ondersteunt. In zulke gevallen retourneert de driver SQL_SUCCESS_WITH_INFO en SQLSTATE 01S02 (Optionwaarde gewijzigd). Als bijvoorbeeld Attribuut SQL_ATTR_CONCURRENCY is en ValuePtr SQL_CONCUR_ROWVER, en als de databron dit niet ondersteunt, vervangt de driver SQL_CONCUR_VALUES en geeft SQL_SUCCESS_WITH_INFO terug. Om de gesubstitueerde waarde te bepalen, roept een applicatie SQLGetStmtAttr aan.

Het formaat van de informatieset met ValuePtr hangt af van het gespecificeerde attribuut. SQLSetStmtAttr accepteert attribuutinformatie in een van twee verschillende formaten: een tekenstring of een geheel getal. Het formaat van elk wordt vermeld in de beschrijving van het attribuut. Dit formaat geldt voor de informatie die wordt gegenereerd voor elk attribuut in SQLGetStmtAttr. Tekenstrings waarnaar worden verwezen door het ValuePtr-argument van SQLSetStmtAttr hebben een lengte van StringLength.

Statement-attributen die descriptorvelden instellen

Veel statement-attributen komen overeen met een headerveld van een descriptor. Het instellen van deze attributen resulteert in het instellen van de descriptorvelden. Het instellen van velden via een aanroep naar SQLSetStmtAttr in plaats van naar SQLSetDescField heeft als voordeel dat er geen descriptorhandle hoeft te worden verkregen voor de functieaanroep.

Wanneer een descriptorveld wordt ingesteld als gevolg van het bijbehorende statement-attribuut dat wordt ingesteld, wordt het veld alleen ingesteld voor de toepasselijke descriptors die momenteel gekoppeld zijn aan de statement die door het StatementHandle-argument is geïdentificeerd, en de attribuutinstelling beïnvloedt geen descriptors die in de toekomst aan die statement kunnen worden gekoppeld. Wanneer een descriptorveld dat ook een statement-attribuut is, wordt ingesteld door een aanroep naar SQLSetDescField, wordt het bijbehorende statement-attribuut ingesteld. Als een expliciet toegewezen descriptor losstaat van een statement, zal een statementattribuut dat overeenkomt met een headerveld terugkeren naar de waarde van het veld in de impliciet toegewezen descriptor.

Wanneer een instructie wordt toegewezen (zie SQLAllocHandle), worden automatisch vier descriptorhandles toegewezen en aan de instructie gekoppeld. Expliciet toegewezen descriptor-handles kunnen aan de instructie worden gekoppeld door SQLAllocHandle aan te roepen met een fHandleType van SQL_HANDLE_DESC om een descriptorhandle toe te wijzen en vervolgens SQLSetStmtAttr aan te roepen om de descriptorhandle aan de instructie te koppelen.

De statementattributen in de volgende tabel komen overeen met de headervelden van de descriptor.

Verklaringskenmerken

De momenteel gedefinieerde attributen en de versie van ODBC waarin ze zijn geïntroduceerd, worden weergegeven in de volgende tabel; Er wordt verwacht dat er meer attributen door bestuurders zullen worden gedefinieerd om gebruik te maken van verschillende databronnen. Een reeks attributen wordt door ODBC gereserveerd; driverontwikkelaars moeten waarden reserveren voor hun eigen driver-specifieke gebruik van Open Group. Zie Driver-Specific gegevenstypen, descriptortypen, informatietypen, diagnostische typen en kenmerken voor meer informatie.

[1] Deze functies kunnen alleen asynchroon worden aangeroepen als de descriptor een implementatiedescriptor is, geen applicatiedescriptor.

Zie Column-Wise Binding en Row-Wise Binding.

Gerelateerde functies

Zie ook

ODBC-API-verwijzing
ODBC-headerbestanden