Funzione SQLSpecialColumns

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

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

  • L'insieme ottimale di colonne che identifica in modo univoco una riga nella tabella.

  • Colonne che vengono aggiornate automaticamente quando qualsiasi 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);

Arguments

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 l'insieme ottimale di colonne che, recuperando valori dalla colonna o dalle colonne, consente di identificare in modo univoco qualsiasi riga nella tabella specificata. Una colonna può essere sia una pseudo-colonna specificamente progettata per questo scopo (come in Oracle ROWID o Ingres TID) sia la colonna o le colonne di qualsiasi indice unico per la tabella.

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

CatalogName
[Input] Nome del catalogo per la tavola. Se un driver supporta cataloghi per alcune tabelle ma non per altre, ad esempio quando il driver recupera dati da diversi DBMS, una stringa vuota ("") indica quelle tabelle che non hanno cataloghi. CatalogName non può contenere un pattern di ricerca a stringhe.

Se l'attributo dell'istruzione SQL_ATTR_METADATA_ID è impostato su SQL_TRUE, CatalogName viene trattato come un identificatore e il suo caso non è significativo. Se è SQL_FALSE, CatalogName è un argomento ordinario; Viene trattato letteralmente, e il suo caso è significativo. Per altre informazioni, vedere Argomenti nelle Funzioni catalogo.

NameLength1
[Input] Lunghezza nei caratteri di *NomeCatalogo.

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

Se l'attributo dell'istruzione SQL_ATTR_METADATA_ID è impostato su SQL_TRUE, SchemaName viene trattato come un identificatore e il suo caso non è significativo. Se è SQL_FALSE, SchemaName è un argomento ordinario; Viene trattato letteralmente, e il suo caso è significativo.

NameLength2
[Input] Lunghezza nei caratteri di *NomeSchema.

TableName
[Input] Nome tabella. Questo argomento non può essere un puntatore nullo. TableName non può contenere un pattern di ricerca stringa.

Se l'attributo della SQL_ATTR_METADATA_ID istruzione è impostato su SQL_TRUE, TableName viene trattato come un identificatore e il suo caso non è significativo. Se è SQL_FALSE, TableName è un argomento ordinario; Viene trattato letteralmente, e il suo caso è significativo.

NameLength3
[Input] Lunghezza nei caratteri di *NomeTabella.

Ambito
[Input] Ambito minimo richiesto del rowid. Il rowid tornato potrebbe avere una portata maggiore. Deve essere uno dei seguenti:

SQL_SCOPE_CURROW: Il rowid è garantito valido solo quando è posizionato su quella fila. Una riselezione successiva usando rowid potrebbe non restituire una riga se la riga è stata aggiornata o cancellata da un'altra transazione.

SQL_SCOPE_TRANSACTION: Il rowid è garantito valido per tutta la durata della transazione in corso.

SQL_SCOPE_SESSION: Il rowid è garantito valido per tutta la durata della sessione (oltre i confini della transazione).

Annullabile
[Input] Determina se restituire colonne speciali che possono avere un valore NULL. Deve essere uno dei 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 è stato specificato. Le domande devono essere preparate per questo caso e richiedere SQL_NO_NULLS solo se è assolutamente necessario.

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

Returns

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, un valore SQLSTATE associato può essere ottenuto 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 li spiega nel contesto di questa funzione; la notazione "(DM)" precede le descrizioni degli stati SQL restituite dal Driver Manager. Il codice restituito associato a ogni valore SQLSTATE è SQL_ERROR, a meno che non sia specificato diversamente.

SQLSTATE Error Description
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 Un cursore era aperto sull'InstructionHandle, e erano stati chiamati SQLFetch o SQLFetchScroll . Questo errore viene restituito dal Driver Manager se SQLFetch o SQLFetchScroll non ha restituito SQL_NO_DATA e viene restituito dal driver se SQLFetch o SQLFetchScroll hanno restituito SQL_NO_DATA.

Un cursore era aperto sull'InstructionHandle, ma SQLFetch o SQLFetchScroll non erano stati chiamati.
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 SQL_ATTR_METADATA_ID istruzione era impostato su SQL_TRUE, l'argomento CatalogName era un puntatore nullo e l'InfoType SQL_CATALOG_NAME restituisce che i nomi dei cataloghi sono supportati.

(DM) L'attributo di istruzione SQL_ATTR_METADATA_ID era impostato su SQL_TRUE, e l'argomento SchemaName era un puntatore nullo.
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 veniva 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_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 era inferiore a 0 ma non uguale a SQL_NTS.

Il valore di uno degli argomenti di lunghezza superava il valore massimo di lunghezza per il nome corrispondente. La lunghezza massima di ciascun 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 fuori dalla portata (DM) È stato specificato un valore IdentifierType non valido.
HY098 Tipo di mirino fuori portata (DM) È stato specificato un valore di Scope non valido.
HY099 Tipo nullabile fuori dal raggio (DM) È stato specificato un valore nullabile non valido.
HY117 La connessione viene sospesa a causa dello stato sconosciuto della transazione. 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 la sorgente dati non supportano i cataloghi.

È stato specificato uno schema, e il driver o la sorgente dati non supportano 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_USE_BOOKMARKS è 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 Il 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 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.

Comments

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, che viene utilizzato per restituire una varietà di informazioni sulle colonne di una tabella, non restituisce necessariamente le colonne che identificano in modo univoco ogni riga, né le colonne che vengono automaticamente aggiornate quando un valore nella riga viene aggiornato tramite una transazione. Ad esempio, SQLColumns potrebbe non restituire il pseudo-colonna Oracle ROWID. Ecco perché SQLSpecialColumns viene usato per restituire queste colonne. Per altre informazioni, vedere Usi dei dati del catalogo.

Note

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

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

Se gli argomenti IdentifierType, Scope o Nullable specificano caratteristiche non supportate dalla sorgente dati, SQLSpecialColumns restituisce un insieme di risultati vuoto.

Se l'attributo SQL_ATTR_METADATA_ID istruzione è impostato su SQL_TRUE, gli argomenti CatalogName, SchemaName e TableName sono trattati come identificatori, quindi non possono essere impostati su un puntatore nullo in determinate situazioni. (Per maggiori informazioni, vedi Argomentazioni nelle Funzioni del Catalogo.)

SQLSpecialColumns restituisce i risultati come insieme di risultati standard, ordinato tramite SCOPE.

Le colonne seguenti sono state rinominate per ODBC 3.x. I cambiamenti nel nome delle colonne non influiscono sulla retrocompatibilità perché le applicazioni si assegnano per numero di colonna.

Colonna ODBC 2.0 Colonna ODBC 3.x
PRECISION COLUMN_SIZE
Lunghezza BUFFER_LENGTH
SCALA CIFRE_DECIMALI

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. Colonne aggiuntive oltre la colonna 8 (PSEUDO_COLUMN) possono essere definite dal driver. Un'applicazione dovrebbe accedere alle colonne specifiche del driver contando alla rovescia dalla fine del set di risultati invece di specificare una posizione ordinale esplicita. Per altre informazioni, vedere Dati restituiti dalle funzioni del catalogo.

Nome della colonna Numero di colonna Tipo di dati Comments
SCOPE (ODBC 1.0) 1 Smallint La portata reale del tumulto. Contiene uno dei seguenti valori:

SQL_SCOPE_CURROW SQL_SCOPE_TRANSACTION SQL_SCOPE_SESSION

NULL viene restituito quando IdentifierType è SQL_ROWVER. Per una descrizione di ogni valore, vedi la descrizione di Scope in "Sintassi", più avanti 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 di tipi di dati SQL ODBC validi, vedi 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 La dimensione della colonna sulla fonte dati. Per maggiori informazioni sulla dimensione della colonna, vedi Dimensione della colonna, Cifre Decimali, Lunghezza dell'Ottetto di Trasferimento e Dimensione del Display.
BUFFER_LENGTH (ODBC 1.0) 6 Intero Lunghezza in byte di dati trasferiti in un'operazione di SQLGetData o SQLFetch se si specifica SQL_C_DEFAULT. Per i dati numerici, queste dimensioni possono essere diverse dalle dimensioni dei dati archiviati nell'origine dati. Questo valore potrebbe differire da COLUMN_SIZE colonna per i dati dei caratteri. Per ulteriori informazioni, vedi Dimensione della colonna, Cifre Decimali, Lunghezza dell'Ottetto di Trasferimento e Dimensione del Display.
DECIMAL_DIGITS (ODBC 1.0) 7 Smallint Le cifre decimali della colonna sulla fonte dati. NULL viene restituito per i tipi di dati in cui le cifre decimali non sono applicabili. Per maggiori informazioni sulle cifre decimali, vedi Dimensione della colonna, Cifre Decimali, Lunghezza dell'Ottetto di Trasferimento e Dimensione del Display.
PSEUDO_COLUMN (ODBC 2.0) 8 Smallint Indica se la colonna è una pseudo-colonna, come Oracle ROWID:

SQL_PC_UNKNOWN SQL_PC_NOT_PSEUDO SQL_PC_PSEUDO Nota: Per la massima interoperabilità, le pseudo-colonne non devono essere citate con il carattere di citazione dell'identificatore restituito da SQLGetInfo.

Dopo che l'applicazione recupera i valori per SQL_BEST_ROWID, può utilizzare questi valori per selezionare nuovamente quella riga all'interno dell'ambito definito. L'istruzione SELECT garantisce di restituire nessuna riga o una riga.

Se un'applicazione riseleziona una riga basandosi sulla colonna o sulle colonne rowid e la riga non viene trovata, l'applicazione può assumere che la riga sia stata eliminata o che le colonne rowid siano state modificate. Il contrario non è vero: anche se il rowid non è cambiato, le altre colonne della riga potrebbero essere cambiate.

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

La colonna o le colonne del rowid possono rimanere valide anche quando il cursore non è posizionato sulla riga; l'applicazione può determinarlo controllando la colonna SCOPE nell'insieme dei risultati.

Le colonne restituite per il tipo di colonna SQL_ROWVER sono utili per applicazioni che necessitano della possibilità di verificare se alcune colonne di una determinata riga sono state aggiornate mentre la riga è stata riselezionata usando 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 differisce dal valore precedente, l'applicazione può avvisare l'utente che i dati sul display sono cambiati.

Esempio di codice

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

Per informazioni su Vedi
Associazione di un buffer a una colonna in un set di risultati Funzione SQLBindCol
Annullamento dell'elaborazione delle istruzioni Funzione SQLCancel
Restituire le colonne in una o più tabelle Funzione SQLColumns
Recupero di una singola riga o di un blocco di dati in direzione solo in avanti 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

Contenuti correlati

  • Last updated on