Condividi tramite

Funzione SQLSpecialColumns

  • Articolo

Conformità
Versione introdotta: Conformità standard ODBC 1.0: Gruppo aperto

Riepilogo
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 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 di identificare in modo univoco qualsiasi riga della tabella specificata. Una colonna può essere una pseudo-colonna progettata appositamente per questo scopo (come in ORACLE ROWID o TID in ingresso) oppure la colonna o le colonne di qualsiasi indice univoco per la tabella.

SQL_ROWVER: restituisce la colonna o le colonne della 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 altri, ad esempio quando il driver recupera i dati da diversi DBMS, una stringa vuota ("") indica le tabelle che non dispongono di cataloghi. CatalogName non può contenere un criterio di ricerca di stringhe.

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

NameLength1
[Input] Lunghezza in caratteri di *CatalogName.

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

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

NameLength2
[Input] Lunghezza in caratteri di *SchemaName.

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

Se l'attributo dell'istruzione SQL_ATTR_METADATA_ID è impostato su SQL_TRUE, TableName viene considerato come identificatore e il relativo case non è significativo. Se è SQL_FALedizione Standard, TableName è un argomento comune; viene trattato letteralmente e il relativo case è significativo.

NameLength3
[Input] Lunghezza in caratteri di *TableName.

Scope
[Input] Ambito minimo obbligatorio del rowid. Il rowid restituito può essere di un ambito maggiore. I possibili valori sono i seguenti:

SQL_SCOPE_CURROW: il rowid è garantito che sia valido solo se posizionato in tale riga. Se la riga è stata aggiornata o eliminata da un'altra transazione, è possibile che in un secondo momento venga riselezionata utilizzando rowid.

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

SQL_SCOPE_edizione Standard SSION: il rowid è garantito che sia valido per la durata della sessione (oltre i limiti delle transazioni).

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 è stato specificato SQL_NO_NULLS. 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.

Valori restituiti

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 handleTypedi SQL_HANDLE_STMT e handle di StatementHandle. La tabella seguente elenca i valori SQLSTATE comunemente restituiti da SQLSpecialColumns e spiega ognuno di essi 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, a meno che non sia specificato diversamente.

SQLSTATE Errore Descrizione
01000 Avviso generale Messaggio informativo specifico del driver. (La funzione restituisce SQL_SUCCESS_WITH_INFO.
08S01 Errore del collegamento di comunicazione 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 e è 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 è stato aperto in StatementHandle, ma SQLFetch o SQLFetchScroll non è 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 specificato SQLSTATE e per il quale non è stato definito alcun 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 è riuscito ad allocare memoria necessaria per supportare l'esecuzione o il completamento della funzione.
HY008 Operazione annullata L'elaborazione asincrona è stata abilitata per StatementHandle. La funzione è stata chiamata e prima di completare l'esecuzione, SQLCancel o SQLCancelHandle è stata chiamata 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 è un puntatore Null.

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

(DM) L'attributo dell'istruzione SQL_ATTR_METADATA_ID è 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 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 è ancora in esecuzione quando questa funzione è stata chiamata.

(DM) SQLExecute, SQLExecDirect, SQLBulkOperations o SQLSetPos è stato chiamato per StatementHandle e restituito SQL_Nedizione EnterpriseD_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 era 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 (DM) È stato specificato un valore IdentifierType non valido.
HY098 Tipo di ambito non compreso nell'intervallo (DM) È stato specificato un valore scope non valido.
HY099 Tipo nullable non compreso nell'intervallo (DM) È stato specificato un valore Nullable non valido.
HY117 Connessione ion viene sospesa a causa di uno stato di transazione sconosciuto. Sono consentite solo funzioni disconnesse 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 delle istruzioni SQL_ATTR_CONCURRENCY e SQL_ATTR_CURSOR_TYPE non è supportata dal driver o dall'origine dati.

L'attributo di istruzione SQL_ATTR_Uedizione Standard_BOOKMARKS è stato impostato su SQL_UB_VARIABLE e l'attributo dell'istruzione SQL_ATTR_CURSOR_TYPE è stato impostato su un tipo di cursore per il quale il driver non supporta i segnalibri.
HYT00 Timeout scaduto Periodo di timeout della query scaduto prima che l'origine dati restituisca il set di risultati richiesto. Il periodo di timeout viene impostato tramite SQLSetStmtAttr, SQL_ATTR_QUERY_TIMEOUT.
HYT01 Il timeout della connessione è scaduto Periodo di timeout della connessione scaduto prima che l'origine dati rispondesse alla richiesta. Il periodo di timeout della connessione viene impostato tramite SQLSet Connessione Attr, 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 una clausola select-list o WHERE . SQLColumns, utilizzato 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 colonne che vengono aggiornate automaticamente quando un valore nella riga viene aggiornato da una transazione. Ad esempio, SQLColumns potrebbe non restituire lo pseudocolonna Oracle ROWID. Ecco perché SQLSpecialColumns viene usato per restituire queste colonne. Per altre informazioni, vedere Uses of Catalog Data.For more information, see Uses of Catalog Data.

Nota

Per altre informazioni sull'utilizzo generale, gli argomenti e i 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 nell'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, ordinato in base all'ambito.

Le colonne seguenti sono state rinominate per ODBC 3.x. Le modifiche apportate al nome della colonna non influiscono sulla compatibilità con le versioni precedenti perché le applicazioni si associano per 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'opzione SQL_MAX_COLUMN_NAME_LEN.

Nella tabella seguente sono elencate le colonne nel set di risultati. Le colonne aggiuntive successive alla colonna 8 (P edizione StandardUDO_COLUMN) possono essere definite dal driver. Un'applicazione deve ottenere l'accesso alle colonne specifiche del driver con il conteggio dalla fine del set di risultati anziché specificare una posizione ordinale esplicita. Per altre informazioni, vedere Dati restituiti dalle funzioni del catalogo.

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

SQL_SCOPE_CURROW SQL_SCOPE_TRANSACTION SQL_SCOPE_edizione Standard SSION

Null viene restituito quando IdentifierType è SQL_ROWVER. Per una descrizione di ogni valore, vedere la descrizione dell'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 Tipo di dati SQL. Può trattarsi di un tipo di dati SQL ODBC o di un tipo di dati SQL specifico del driver. Per un elenco dei tipi di dati SQL ODBC validi, vedere Tipi di dati SQL. Per informazioni sui tipi di dati SQL specifici del 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 Intero Dimensioni della colonna nell'origine dati. Per altre informazioni sulle dimensioni delle colonne, vedere Dimensioni delle colonne, Cifre decimali, Lunghezza ottetto trasferimento e Dimensioni di visualizzazione.
BUFFER_LENGTH (ODBC 1.0) 6 Intero Lunghezza in byte di dati trasferiti in un'operazione SQLGetData o SQLFetch se viene specificato SQL_C_DEFAULT. Per i dati numerici, queste dimensioni possono essere diverse dalle dimensioni dei dati archiviati nell'origine dati. Questo valore potrebbe essere diverso da COLUMN_SIZE colonna per i dati di tipo carattere. Per altre informazioni, vedere Dimensioni delle colonne, Cifre decimali, Lunghezza ottetto di trasferimento 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 delle colonne, Cifre decimali, Lunghezza ottetto di trasferimento e Dimensioni di visualizzazione.
P edizione StandardUDO_COLUMN (ODBC 2.0) 8 Smallint Indica se la colonna è una pseudo-colonna, ad esempio Oracle ROWID:

SQL_PC_UNKNOWN SQL_PC_NOT_Pedizione Standard UDO SQL_PC_Pedizione Standard UDO Nota: per l'interoperabilità massima, le pseudo-colonne non devono essere racchiuse tra virgolette di identificatore restituite da SQLGetInfo.

Dopo che l'applicazione recupera i valori per SQL_BEST_ROWID, l'applicazione può usare questi valori per deselezionare nuovamente tale riga all'interno dell'ambito definito. L'istruzione edizione Standard LECT garantisce la restituzione di nessuna riga o di 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. L'opposto non è vero: anche se il rowid non è stato modificato, è possibile che le altre colonne della riga siano state modificate.

Le colonne restituite per il tipo di colonna 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 dell'id riga non vengano modificate mentre sono posizionate in tale riga.

La colonna o le colonne dell'id riga possono rimanere valide anche quando il cursore non è posizionato sulla riga; L'applicazione può determinare questa situazione controllando la colonna SCOPE nel set di risultati.

Le colonne restituite per il tipo di colonna SQL_ROWVER sono utili per le applicazioni che richiedono la possibilità di controllare se le colonne di una determinata riga sono state aggiornate mentre la riga è stata rielezione utilizzando il rowid. Ad esempio, dopo aver riselezionato una riga usando rowid, l'applicazione può confrontare i valori precedenti nelle colonne SQL_ROWVER con quelli appena recuperati. Se il valore in una colonna SQL_ROWVER è diverso dal valore precedente, l'applicazione può avvisare l'utente che i dati nella visualizzazione 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 delle istruzioni Funzione SQLCancel
Restituzione delle colonne in una tabella o in tabelle 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 Funzione SQLPrimaryKeys

Vedi anche

Riferimento API ODBC
File di intestazione ODBC