SQLSpecialColumns-funktion

Överensstämmelse
Version introducerad: ODBC 1.0 Standardsefterlevnad: Open Group

Summary
SQLSpecialColumns hämtar följande information om kolumner inom en specificerad tabell:

• Den optimala uppsättningen kolumner som unikt identifierar en rad i tabellen.

• Kolumner som automatiskt uppdateras när något värde i raden uppdateras av en transaktion.

Syntax

  
SQLRETURN SQLSpecialColumns(  
     SQLHSTMT      StatementHandle,  
     SQLSMALLINT   IdentifierType,  
     SQLCHAR *     CatalogName,  
     SQLSMALLINT   NameLength1,  
     SQLCHAR *     SchemaName,  
     SQLSMALLINT   NameLength2,  
     SQLCHAR *     TableName,  
     SQLSMALLINT   NameLength3,  
     SQLSMALLINT   Scope,  
     SQLSMALLINT   Nullable);  

Arguments

StatementHandle
[Indata] Instruktionshandtag.

IdentifierType
[Input] Typ av kolumn att returnera. Måste vara något av följande värden:

SQL_BEST_ROWID: Returnerar den optimala kolumnen eller uppsättningen av kolumner som, genom att hämta värden från kolumnen eller kolumnerna, gör det möjligt att identifiera vilken rad som helst i den angivna tabellen entyd. En kolumn kan vara antingen en pseudokolumn som är specifikt utformad för detta ändamål (som i Oracle ROWID eller Ingres TID) eller kolumnen eller kolumnerna i vilket unikt index som helst för tabellen.

SQL_ROWVER: Returnerar kolumnen eller kolumnerna i den angivna tabellen, om sådana finns, som automatiskt uppdateras av datakällan när något värde i raden uppdateras av någon transaktion (som i SQLBase ROWID eller Sybase TIMESTAMP).

CatalogName
[Input] Katalognamnet för bordet. Om en drivrutin stödjer kataloger för vissa tabeller men inte för andra, till exempel när drivrutinen hämtar data från olika databaser, betecknar en tom sträng ("") de tabeller som inte har kataloger. CatalogName kan inte innehålla ett strängsökningsmönster.

Om attributet SQL_ATTR_METADATA_ID sats sätts till SQL_TRUE behandlas CatalogName som en identifierare och dess fall är inte signifikant. Om det är SQL_FALSE är CatalogName ett vanligt argument; Den behandlas bokstavligt, och dess fall är betydelsefullt. Mer information finns i Argument i Katalogfunktioner.

NameLength1
[Input] Längd i tecken i *CatalogName.

Schema-namn
[Input] Schemanamnet för tabellen. Om en drivrutin stöder scheman för vissa tabeller men inte för andra, till exempel när drivrutinen hämtar data från olika databassystem, betecknar en tom sträng ("") de tabeller som inte har scheman. SchemaName kan inte innehålla ett strängsökningsmönster.

Om attributet SQL_ATTR_METADATA_ID är satt till SQL_TRUE behandlas SchemaName som en identifierare och dess fall är inte signifikant. Om det är SQL_FALSE är SchemaName ett vanligt argument; Den behandlas bokstavligt, och dess fall är betydelsefullt.

NameLength2
[Input] Längd i tecken i *SchemaName.

TableName
[Indata] Tabellnamn. Detta argument kan inte vara en nollpekare. TableName kan inte innehålla ett strängsökningsmönster.

Om attributet SQL_ATTR_METADATA_ID sats sätts till SQL_TRUE behandlas TableName som en identifierare och dess fall är inte signifikant. Om det är SQL_FALSE är TableName ett vanligt argument; Den behandlas bokstavligt, och dess fall är betydelsefullt.

NameLength3
[Input] Längd i tecken av *TableName.

Scope
[Input] Minsta nödvändiga omfattning av rowid. Den återvändande rowiden kan vara av större omfattning. Måste vara något av följande:

SQL_SCOPE_CURROW: Rowiden är garanterad att vara giltig endast när den står på den raden. En senare omval med rowid kanske inte returnerar en rad om raden uppdaterades eller raderades av en annan transaktion.

SQL_SCOPE_TRANSACTION: Rowid är garanterat giltigt under hela den aktuella transaktionens varaktighet.

SQL_SCOPE_SESSION: Rowid är garanterad att vara giltig under hela sessionen (över transaktionsgränser).

Nullbar
[Input] Avgör om specialkolumner som kan ha ett NULL-värde ska returneras. Måste vara något av följande:

SQL_NO_NULLS: Uteslut specialkolumner som kan ha NULL-värden. Vissa drivrutiner kan inte stödja SQL_NO_NULLS, och dessa drivrutiner returnerar en tom resultatuppsättning om SQL_NO_NULLS specificerades. Ansökningar bör förberedas för detta fall och begära SQL_NO_NULLS endast om det absolut krävs.

SQL_NULLABLE: Returnera speciella kolumner även om de kan ha NULL-värden.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR eller SQL_INVALID_HANDLE.

Diagnostics

När SQLSpecialColumns returnerar 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 av StatementHandle. Följande tabell listar de SQLSTATE-värden som vanligtvis returneras av SQLSpecialColumns 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

När IdentifierType-argumentet är SQL_BEST_ROWID returnerar SQLSpecialColumns kolumnen eller kolumnerna som unikt identifierar varje rad i tabellen. Dessa kolumner kan alltid användas i en select-list eller WHERE-klausul . SQLColumns, som används för att returnera olika typer av information på kolumnerna i en tabell, returnerar inte nödvändigtvis de kolumner som unikt identifierar varje rad, eller kolumner som automatiskt uppdateras när något värde i raden uppdateras av en transaktion. Till exempel kanske SQLColumns inte returnerar Oracle-pseudokolumnen ROWID. Det är därför SQLSpecialColumns används för att returnera dessa kolumner. Mer information finns i Användning av katalogdata.

Om det inte finns några kolumner som entydigt identifierar varje rad i tabellen, returnerar SQLSpecialColumns en radmängd utan rader; ett efterföljande anrop till SQLFetch eller SQLFetchScroll på satsen returnerar SQL_NO_DATA.

Om argumenten IdentifierType, Scope eller Nullable specificerar egenskaper som inte stöds av datakällan, returnerar SQLSpecialColumns en tom resultatuppsättning.

Om attributet SQL_ATTR_METADATA_ID satsen sätts till SQL_TRUE behandlas argumenten CatalogName,SchemaName och TableName som identifierare, så de kan inte sättas till en nullpekare i vissa situationer. (För mer information, se Argument i katalogfunktioner.)

SQLSpecialColumns returnerar resultaten som en standardmängd resultat, ordnade efter SCOPE.

Följande kolumner har bytt namn för ODBC 3.x. Kolumnnamnsändringarna påverkar inte bakåtkompatibilitet eftersom applikationer binds efter kolumnnummer.

För att bestämma den faktiska längden på kolumnen COLUMN_NAME kan en applikation anropa SQLGetInfo med alternativet SQL_MAX_COLUMN_NAME_LEN.

I följande tabell visas kolumnerna i resultatuppsättningen. Ytterligare kolumner utöver kolumn 8 (PSEUDO_COLUMN) kan definieras av drivrutinen. En applikation bör få tillgång till drivrutinsspecifika kolumner genom att räkna ner från slutet av resultatuppsättningen istället för att specificera en explicit ordinal position. Mer information finns i Data som returneras av katalogfunktioner.

Efter att applikationen hämtat värden för SQL_BEST_ROWID kan den använda dessa värden för att återvälja raden inom det definierade omfånget. SELECT-satsen garanteras returnera antingen inga rader eller en rad.

Om en applikation väljer om en rad baserat på rowid-kolumnen eller kolumnerna och raden inte hittas, kan applikationen anta att raden har tagits bort eller att rowid-kolumnerna har ändrats. Det motsatta är inte sant: även om rowiden inte har ändrats kan de andra kolumnerna i raden ha ändrats.

Kolumner som returneras för kolumntyp SQL_BEST_ROWID är användbara för applikationer som behöver scrolla framåt och tillbaka inom en resultatuppsättning för att hämta den senaste datan från en rad rader. Kolumnen eller kolumnerna i rowiden är garanterade att inte ändras medan de är placerade på den raden.

Kolumnen eller kolumnerna i rowiden kan förbli giltiga även när markören inte är placerad på raden; applikationen kan avgöra detta genom att kontrollera kolumnen SCOPE i resultatuppsättningen.

Kolumner som returneras för kolumntyp SQL_ROWVER är användbara för applikationer som behöver möjligheten att kontrollera om några kolumner i en viss rad har uppdaterats medan raden valts om med rowid. Till exempel, efter att ha valt en rad igen med rowid kan applikationen jämföra tidigare värden i de SQL_ROWVER kolumnerna med de som just hämtats. Om värdet i en SQL_ROWVER kolumn skiljer sig från det föregående kan applikationen varna användaren om att data på skärmen har ändrats.

Kodexempel

För ett kodexempel på en liknande funktion, se SQLColumns.

Relaterade funktioner

Relaterat innehåll

• ODBC API-referens
• ODBC-huvudfiler