Funzione SQLSpecialColumns

Conformità
Versione introdotta: Conformità agli standard ODBC 1.0: Open Group

Summary
SQLSpecialColumns recupera le informazioni seguenti sulle colonne all'interno di una tabella specificata:

  • Set ottimale di colonne che identifica in modo univoco una riga nella tabella.

  • Colonne che vengono aggiornate automaticamente quando un valore nella riga viene aggiornato da una transazione.

Sintassi

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

Argomenti

StatementHandle
[Input] Handle di istruzione.

IdentifierType
[Input] Tipo di colonna da restituire. Deve essere uno dei valori seguenti:

SQL_BEST_ROWID: restituisce la colonna o il set ottimale di colonne che, recuperando i valori dalla colonna o dalle colonne, consente l'identificazione univoca di qualsiasi riga della tabella specificata. Una colonna può essere una pseudocologa appositamente progettata per questo scopo (come in ORACLE ROWID o Ingres TID) o la colonna o le colonne di qualsiasi indice univoco per la tabella.

SQL_ROWVER: restituisce la colonna o le colonne nella tabella specificata, se presenti, che vengono aggiornate automaticamente dall'origine dati quando qualsiasi valore nella riga viene aggiornato da qualsiasi transazione (come in SQLBase ROWID o Sybase TIMESTAMP).

CatalogName
[Input] Nome del catalogo per la tabella. Se un driver supporta cataloghi per alcune tabelle, ma non per altre, ad esempio quando il driver recupera dati da dbMS diversi, una stringa vuota ("") indica le tabelle che non dispongono di cataloghi. CatalogName non può contenere un criterio di ricerca stringa.

Se l'SQL_ATTR_METADATA_ID dell'istruzione è impostato su SQL_TRUE, CatalogName viene considerato come identificatore e il relativo case non è significativo. Se è SQL_FALSE, CatalogName è un argomento normale. viene trattato letteralmente e il relativo caso è significativo. Per altre informazioni, vedere Argomenti in Funzioni del catalogo.

NameLength1
[Input] Lunghezza in caratteri *CatalogName.

SchemaName
[Input] Nome dello schema per la tabella. Se un driver supporta schemi per alcune tabelle, ma non per altre, ad esempio quando il driver recupera dati da dbMS diversi, una stringa vuota ("") indica le tabelle che non dispongono di schemi. SchemaName non può contenere un criterio di ricerca stringa.

Se l'SQL_ATTR_METADATA_ID dell'istruzione è impostato su SQL_TRUE, SchemaName viene considerato come identificatore e il relativo case non è significativo. Se è SQL_FALSE, SchemaName è un argomento normale. viene trattato letteralmente e il relativo caso è significativo.

NameLength2
[Input] Lunghezza in caratteri *SchemaName.

TableName
[Input] Nome della tabella. Questo argomento non può essere un puntatore Null. TableName non può contenere un criterio di ricerca stringa.

Se l'SQL_ATTR_METADATA_ID dell'istruzione è impostato su SQL_TRUE, TableName viene considerato come identificatore e il relativo case non è significativo. Se è SQL_FALSE, TableName è un argomento normale. viene trattato letteralmente e il relativo caso è significativo.

NameLength3
[Input] Lunghezza in caratteri *TableName.

Ambito
[Input] Ambito minimo richiesto del rowid. Il rowid restituito può avere un ambito maggiore. I possibili valori sono i seguenti:

SQL_SCOPE_CURROW: il rowid è garantito per essere valido solo quando è posizionato su tale riga. Una successiva selezione tramite rowid potrebbe non restituire una riga se la riga è stata aggiornata o eliminata da un'altra transazione.

SQL_SCOPE_TRANSACTION: il rowid è garantito per la durata della transazione corrente.

SQL_SCOPE_SESSION: il rowid è garantito per la durata della sessione (oltre i limiti della transazione).

Ammette i valori Null
[Input] Determina se restituire colonne speciali che possono avere un valore NULL. I possibili valori sono i seguenti:

SQL_NO_NULLS: escludere colonne speciali che possono avere valori NULL. Alcuni driver non possono supportare SQL_NO_NULLS e questi driver restituiranno un set di risultati vuoto se SQL_NO_NULLS specificato. Le applicazioni devono essere preparate per questo caso e richiedere SQL_NO_NULLS solo se è assolutamente necessario.

SQL_NULLABLE: restituisce colonne speciali anche se possono avere valori NULL.

Restituisce

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR o SQL_INVALID_HANDLE.

Diagnostica

Quando SQLSpecialColumns restituisce SQL_ERROR o SQL_SUCCESS_WITH_INFO, è possibile ottenere un valore SQLSTATE associato chiamando SQLGetDiagRec con un HandleType di SQL_HANDLE_STMT e un Handle di StatementHandle. La tabella seguente elenca i valori SQLSTATE comunemente restituiti da SQLSpecialColumns e spiega ognuno nel contesto di questa funzione. la notazione "(DM)" precede le descrizioni di SQLSTATEs restituite da Gestione driver. Il codice restituito associato a ogni valore SQLSTATE SQL_ERROR, se non diversamente specificato.

SQLSTATE Errore Descrizione
01000 Avviso generale Messaggio informativo specifico del driver. La funzione restituisce SQL_SUCCESS_WITH_INFO.
08S01 Errore del collegamento di comunicazione Il collegamento di comunicazione tra il driver e l'origine dati a cui è stato connesso il driver non è riuscito prima del completamento dell'elaborazione della funzione.
24000 Stato del cursore non valido È stato aperto un cursore in StatementHandle ed è stato chiamato SQLFetch o SQLFetchScroll. Questo errore viene restituito da Gestione driver se SQLFetch o SQLFetchScroll non ha restituito SQL_NO_DATA e viene restituito dal driver se SQLFetch o SQLFetchScroll ha restituito SQL_NO_DATA.

Un cursore era aperto in StatementHandle, ma SQLFetch o SQLFetchScroll non era stato chiamato.
40001 Errore di serializzazione È stato eseguito il rollback della transazione a causa di un deadlock della risorsa con un'altra transazione.
40003 Completamento istruzione sconosciuto La connessione associata non è riuscita durante l'esecuzione di questa funzione e non è possibile determinare lo stato della transazione.
HY000 Errore generale: Si è verificato un errore per il quale non è stato definito un SQLSTATE specifico e per il quale non è stato definito ALCUN VALORE SQLSTATE specifico dell'implementazione. Il messaggio di errore restituito da SQLGetDiagRec nel buffer * MessageText descrive l'errore e la relativa causa.
HY001 Errore di allocazione della memoria Il driver non è stato in grado di allocare la memoria necessaria per supportare l'esecuzione o il completamento della funzione.
HY008 Operation canceled L'elaborazione asincrona è stata abilitata per StatementHandle. La funzione è stata chiamata e prima del completamento dell'esecuzione, è stato chiamato SQLCancel o SQLCancelHandle in StatementHandle. La funzione è stata quindi chiamata di nuovo in StatementHandle.

La funzione è stata chiamata e prima del completamento dell'esecuzione, SQLCancel o SQLCancelHandle è stato chiamato su StatementHandle da un thread diverso in un'applicazione multithread.
HY009 Uso non valido del puntatore Null L'argomento TableName era un puntatore Null.

L SQL_ATTR_METADATA_ID'attributo dell'istruzione è stato impostato su SQL_TRUE, l'argomento CatalogName era un puntatore Null e l'SQL_CATALOG_NAME InfoType restituisce che i nomi del catalogo sono supportati.

(DM) L'attributo SQL_ATTR_METADATA_ID'istruzione è stato impostato su SQL_TRUE e l'argomento SchemaName era un puntatore Null.
HY010 Errore della sequenza di funzioni (DM) È stata chiamata una funzione in esecuzione asincrona per l'handle di connessione associato a StatementHandle. Questa funzione era ancora in esecuzione quando è stato chiamato SQLSpecialColumns.

(DM) SQLExecute, SQLExecDirect o SQLMoreResults è stato chiamato per StatementHandle e ha restituito SQL_PARAM_DATA_AVAILABLE. Questa funzione è stata chiamata prima del recupero dei dati per tutti i parametri trasmessi.

(DM) Una funzione in esecuzione asincrona (non questa) è stata chiamata per StatementHandle ed era ancora in esecuzione quando è stata chiamata questa funzione.

(DM) SQLExecute, SQLExecDirect, SQLBulkOperations o SQLSetPos sono stati chiamati per StatementHandle e sono stati restituiti SQL_NEED_DATA. Questa funzione è stata chiamata prima dell'invio dei dati per tutti i parametri o le colonne data-at-execution.
HY013 Errore di gestione della memoria Impossibile elaborare la chiamata di funzione perché non è stato possibile accedere agli oggetti di memoria sottostanti, probabilmente a causa di condizioni di memoria insufficiente.
HY090 Lunghezza della stringa o del buffer non valida (DM) Il valore di uno degli argomenti di lunghezza è minore di 0 ma non è uguale a SQL_NTS.

Il valore di uno degli argomenti di lunghezza ha superato il valore di lunghezza massima per il nome corrispondente. La lunghezza massima di ogni nome può essere ottenuta chiamando SQLGetInfo con i valori InfoType: SQL_MAX_CATALOG_NAME_LEN, SQL_MAX_SCHEMA_NAME_LEN o SQL_MAX_TABLE_NAME_LEN.
HY097 Tipo di colonna non compreso nell'intervallo È stato specificato un valore IdentifierType non valido.
HY098 Tipo di ambito non compreso nell'intervallo (DM) È stato specificato un valore ambito non valido.
HY099 Tipo nullable non compreso nell'intervallo (DM) È stato specificato un valore nullable non valido.
HY117 La connessione è stata sospesa a causa di uno stato di transazione sconosciuto. Sono consentite solo funzioni di disconnessione e di sola lettura. (DM) Per altre informazioni sullo stato sospeso, vedere Funzione SQLEndTran.
HYC00 Funzionalità facoltativa non implementata È stato specificato un catalogo e il driver o l'origine dati non supporta i cataloghi.

È stato specificato uno schema e il driver o l'origine dati non supporta gli schemi.

La combinazione delle impostazioni correnti degli attributi SQL_ATTR_CONCURRENCY e SQL_ATTR_CURSOR_TYPE'istruzione non è supportata dal driver o dall'origine dati.

L SQL_ATTR_USE_BOOKMARKS dell'istruzione è stato impostato su SQL_UB_VARIABLE e l'attributo dell'istruzione SQL_ATTR_CURSOR_TYPE è stato impostato su un tipo di cursore per cui il driver non supporta i segnalibri.
HYT00 Timeout Il periodo di timeout della query è scaduto prima che l'origine dati restituisce il set di risultati richiesto. Il periodo di timeout viene impostato tramite SQLSetStmtAttr, SQL_ATTR_QUERY_TIMEOUT.
HYT01 Timeout della connessione scaduto Il periodo di timeout della connessione è scaduto prima che l'origine dati risponda alla richiesta. Il periodo di timeout della connessione viene impostato tramite SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001 Il driver non supporta questa funzione (DM) Il driver associato a StatementHandle non supporta la funzione .
IM017 Il polling è disabilitato in modalità di notifica asincrona Ogni volta che viene usato il modello di notifica, il polling è disabilitato.
IM018 SQLCompleteAsync non è stato chiamato per completare l'operazione asincrona precedente su questo handle. Se la chiamata di funzione precedente sull'handle restituisce SQL_STILL_EXECUTING e se la modalità di notifica è abilitata, è necessario chiamare SQLCompleteAsync sull'handle per eseguire la post-elaborazione e completare l'operazione.

Commenti

Quando l'argomento IdentifierType SQL_BEST_ROWID, SQLSpecialColumns restituisce la colonna o le colonne che identificano in modo univoco ogni riga della tabella. Queste colonne possono sempre essere usate in un elenco di selezione o in una clausola WHERE. SQLColumns, usato per restituire un'ampia gamma di informazioni sulle colonne di una tabella, non restituisce necessariamente le colonne che identificano in modo univoco ogni riga o le colonne che vengono aggiornate automaticamente quando un qualsiasi valore della riga viene aggiornato da una transazione. Ad esempio, SQLColumns potrebbe non restituire la pseudocolonna ROWID oracle. Per questo motivo viene usato SQLSpecialColumns per restituire queste colonne. Per altre informazioni, vedere Usi dei dati del catalogo.

Nota

Per altre informazioni sull'utilizzo generale, sugli argomenti e sui dati restituiti delle funzioni del catalogo ODBC, vedere Funzioni del catalogo.

Se non sono presenti colonne che identificano in modo univoco ogni riga della tabella, SQLSpecialColumns restituisce un set di righe senza righe. una chiamata successiva a SQLFetch o SQLFetchScroll sull'istruzione restituisce SQL_NO_DATA.

Se gli argomenti IdentifierType, Scope o Nullable specificano caratteristiche non supportate dall'origine dati, SQLSpecialColumns restituisce un set di risultati vuoto.

Se l'attributo dell'istruzione SQL_ATTR_METADATA_ID è impostato su SQL_TRUE, gli argomenti CatalogName, SchemaName e TableName vengono considerati identificatori, pertanto non possono essere impostati su un puntatore Null in determinate situazioni. Per altre informazioni, vedere Argomenti nelle funzioni del catalogo.

SQLSpecialColumns restituisce i risultati come set di risultati standard, ordinati in base a SCOPE.

Le colonne seguenti sono state rinominate per ODBC 3.x. Le modifiche al nome della colonna non influiscono sulla compatibilità con le versioni precedenti perché le applicazioni vengono associate in base al numero di colonna.

Colonna ODBC 2.0 Colonna ODBC 3.x
PRECISION COLUMN_SIZE
LENGTH BUFFER_LENGTH
SCALE DECIMAL_DIGITS

Per determinare la lunghezza effettiva della colonna COLUMN_NAME, un'applicazione può chiamare SQLGetInfo con l'SQL_MAX_COLUMN_NAME_LEN predefinita.

Nella tabella seguente sono elencate le colonne nel set di risultati. Le colonne aggiuntive oltre la colonna 8 (PSEUDO_COLUMN) possono essere definite dal driver. Un'applicazione deve ottenere l'accesso alle colonne specifiche del driver contando verso il basso dalla fine del set di risultati anziché specificando una posizione ordinale esplicita. Per altre informazioni, vedere Dati restituiti da Funzioni di catalogo.

Nome colonna Numero di colonna Tipo di dati Commenti
SCOPE (ODBC 1.0) 1 Smallint Ambito effettivo del rowid. Contiene uno dei valori seguenti:

SQL_SCOPE_CURROW SQL_SCOPE_TRANSACTION SQL_SCOPE_SESSION

Viene restituito NULL quando IdentifierType è SQL_ROWVER. Per una descrizione di ogni valore, vedere la descrizione di Ambito in "Sintassi" più indietro in questa sezione.
COLUMN_NAME (ODBC 1.0) 2 Varchar non NULL Nome colonna. Il driver restituisce una stringa vuota per una colonna che non ha un nome.
DATA_TYPE (ODBC 1.0) 3 Smallint non NULL SQL tipo di dati. Può trattarsi di un tipo di SQL ODBC o di un tipo di dati SQL driver. Per un elenco dei tipi di dati SQL ODBC validi, vedere SQL tipi di dati. Per informazioni sui tipi di dati SQL driver, vedere la documentazione del driver.
TYPE_NAME (ODBC 1.0) 4 Varchar non NULL Nome del tipo di dati dipendente dall'origine dati. ad esempio"CHAR", "VARCHAR", "MONEY", "LONG VARBINARY" o "CHAR ( ) FOR BIT DATA".
COLUMN_SIZE (ODBC 1.0) 5 Integer Dimensioni della colonna nell'origine dati. Per altre informazioni sulle dimensioni della colonna, vedere Dimensioni della colonna, Cifre decimali, Trasferisci lunghezza ottetto e Dimensioni di visualizzazione.
BUFFER_LENGTH (ODBC 1.0) 6 Integer Lunghezza in byte dei dati trasferiti in un'operazione SQLGetData o SQLFetch se SQL_C_DEFAULT specificato. Per i dati numerici, queste dimensioni possono essere diverse da quelle dei dati archiviati nell'origine dati. Questo valore è lo stesso della colonna COLUMN_SIZE dati di tipo carattere o binario. Per altre informazioni, vedere Dimensioni colonna, Cifre decimali, Trasferisci lunghezza ottetto e Dimensioni di visualizzazione.
DECIMAL_DIGITS (ODBC 1.0) 7 Smallint Cifre decimali della colonna nell'origine dati. Viene restituito NULL per i tipi di dati in cui le cifre decimali non sono applicabili. Per altre informazioni sulle cifre decimali, vedere Dimensioni della colonna, Cifre decimali, Transfer Octet Length e Display Size.
PSEUDO_COLUMN (ODBC 2.0) 8 Smallint Indica se la colonna è una pseudo-colonna, ad esempio Oracle ROWID:

SQL_PC_UNKNOWN SQL_PC_NOT_PSEUDO SQL_PC_PSEUDO nota: per la massima interoperabilità, le pseudocolonni non devono essere racchiuse tra virgolette dell'identificatore restituite da SQLGetInfo.

Dopo che l'applicazione ha recuperato i SQL_BEST_ROWID, l'applicazione può usare questi valori per selezionare nuovamente la riga all'interno dell'ambito definito. È garantito che l'istruzione SELECT non restituirà alcuna riga o una riga.

Se un'applicazione seleziona nuovamente una riga in base alla colonna o alle colonne rowid e la riga non viene trovata, l'applicazione può presupporre che la riga sia stata eliminata o che le colonne rowid siano state modificate. Il contrario non è vero: anche se il rowid non è stato modificato, le altre colonne nella riga potrebbero essere state modificate.

Le colonne restituite per il SQL_BEST_ROWID sono utili per le applicazioni che devono scorrere avanti e indietro all'interno di un set di risultati per recuperare i dati più recenti da un set di righe. È garantito che la colonna o le colonne del rowid non cambino mentre sono posizionate su tale riga.

La colonna o le colonne del rowid possono rimanere valide anche quando il cursore non è posizionato sulla riga. L'applicazione può determinare questo problema controllando la colonna SCOPE nel set di risultati.

Le colonne restituite per il tipo di colonna SQL_ROWVER sono utili per le applicazioni che necessitano della possibilità di controllare se le colonne in una determinata riga sono state aggiornate mentre la riga è stata riselezionata usando rowid. Ad esempio, dopo aver riselezionato una riga usando rowid, l'applicazione può confrontare i valori precedenti nelle colonne SQL_ROWVER con quelle appena recuperate. Se il valore in una SQL_ROWVER è diverso dal valore precedente, l'applicazione può avvisare l'utente che i dati sullo schermo sono stati modificati.

Esempio di codice

Per un esempio di codice di una funzione simile, vedere SQLColumns.

Per informazioni su Vedere
Associazione di un buffer a una colonna in un set di risultati Funzione SQLBindCol
Annullamento dell'elaborazione dell'istruzione Funzione SQLCancel
Restituzione delle colonne in una tabella o in una tabella Funzione SQLColumns
Recupero di una singola riga o di un blocco di dati in una direzione forward-only Funzione SQLFetch
Recupero di un blocco di dati o scorrimento di un set di risultati Funzione SQLFetchScroll
Restituzione delle colonne di una chiave primaria SQLPrimaryKeys Function

Vedere anche

Informazioni di riferimento sulle API ODBC
File di intestazione ODBC