Funzione SQLDataSources
Conformità
Versione introdotta: Conformità agli standard ODBC 1.0: ISO 92
Riepilogo
SQLDataSources restituisce informazioni su un'origine dati. Questa funzione viene implementata solo da Gestione driver.
Sintassi
SQLRETURN SQLDataSources(
SQLHENV EnvironmentHandle,
SQLUSMALLINT Direction,
SQLCHAR * ServerName,
SQLSMALLINT BufferLength1,
SQLSMALLINT * NameLength1Ptr,
SQLCHAR * Description,
SQLSMALLINT BufferLength2,
SQLSMALLINT * NameLength2Ptr);
Argomenti
EnvironmentHandle
[Input] Handle dell'ambiente.
Direzione
[Input] Determina l'origine dati su cui Gestione driver restituisce informazioni. I possibili valori sono i seguenti:
SQL_FETCH_NEXT (per recuperare il nome dell'origine dati successiva nell'elenco), SQL_FETCH_FIRST (da recuperare dall'inizio dell'elenco), SQL_FETCH_FIRST_USER (per recuperare il primo DSN utente) o SQL_FETCH_FIRST_SYSTEM (per recuperare il primo DSN di sistema).
Quando Direction è impostato su SQL_FETCH_FIRST, le chiamate successive a SQLDataSources con Direction impostata su SQL_FETCH_NEXT restituiscono DSN utente e di sistema. Quando Direction è impostato su SQL_FETCH_FIRST_USER, tutte le chiamate successive a SQLDataSources con Direction impostato su SQL_FETCH_NEXT restituiscono solo DSN utente. Quando Direction è impostato su SQL_FETCH_FIRST_SYSTEM, tutte le chiamate successive a SQLDataSources con Direction impostata su SQL_FETCH_NEXT restituiscono solo DSN di sistema.
ServerName
[Output] Puntatore a un buffer in cui restituire il nome dell'origine dati.
Se ServerName è NULL, NameLength1Ptr restituirà comunque il numero totale di caratteri (escluso il carattere di terminazione Null per i dati di tipo carattere) da restituire nel buffer a cui punta ServerName.
BufferLength1
[Input] Lunghezza del buffer *ServerName , in caratteri; questo non deve essere più lungo di SQL_MAX_DSN_LENGTH più il carattere di terminazione Null.
NameLength1Ptr
[Output] Puntatore a un buffer in cui restituire il numero totale di caratteri (escluso il carattere di terminazione Null) disponibile per la restituzione in *ServerName. Se il numero di caratteri disponibili per la restituzione è maggiore o uguale a BufferLength1, il nome dell'origine dati in *ServerName viene troncato a BufferLength1 meno la lunghezza di un carattere di terminazione Null.
Descrizione
[Output] Puntatore a un buffer in cui restituire la descrizione del driver associato all'origine dati. Ad esempio, dBASE o SQL Server.
Se Description è NULL, NameLength2Ptr restituirà comunque il numero totale di caratteri (escluso il carattere di terminazione Null per i dati di tipo carattere) da restituire nel buffer a cui punta Descrizione.
BufferLength2
[Input] Lunghezza in caratteri del buffer *Description .
NameLength2Ptr
[Output] Puntatore a un buffer in cui restituire il numero totale di caratteri (escluso il carattere di terminazione Null) disponibile per la restituzione in *Descrizione. Se il numero di caratteri disponibili per la restituzione è maggiore o uguale a BufferLength2, la descrizione del driver in *Description viene troncata a BufferLength2 meno la lunghezza di un carattere di terminazione Null.
Resi
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR o SQL_INVALID_HANDLE.
Diagnostica
Quando SQLDataSources restituisce SQL_ERROR o SQL_SUCCESS_WITH_INFO, è possibile ottenere un valore SQLSTATE associato chiamando SQLGetDiagRec con handleTypedi SQL_HANDLE_ENV e handle di EnvironmentHandle. La tabella seguente elenca i valori SQLSTATE restituiti in genere da SQLDataSources e ne 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, a meno che non sia specificato diversamente.
| SQLSTATE | Errore | Descrizione |
|---|---|---|
| 01000 | Avviso generale | (DM) Messaggio informativo specifico di Gestione driver. (La funzione restituisce SQL_SUCCESS_WITH_INFO. |
| 01004 | Dati stringa, troncati a destra | (DM) Il buffer *ServerName non era sufficientemente grande da restituire il nome completo dell'origine dati. Pertanto, il nome è stato troncato. La lunghezza dell'intero nome dell'origine dati viene restituita in *NameLength1Ptr. (La funzione restituisce SQL_SUCCESS_WITH_INFO. (DM) Il buffer *Descrizione non era sufficientemente grande da restituire la descrizione completa del driver. Pertanto, la descrizione è stata troncata. La lunghezza della descrizione dell'origine dati non troncata viene restituita in *NameLength2Ptr. (La funzione restituisce SQL_SUCCESS_WITH_INFO. |
| HY000 | Errore generale: | (DM) Si è verificato un errore per il quale non è stato definito SQLSTATE specifico e per cui non è stato definito 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 | (DM) Gestione driver non è riuscito ad allocare memoria necessaria per supportare l'esecuzione o il completamento della funzione. |
| HY010 | Errore della sequenza di funzioni | (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. |
| 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 specificato per l'argomento BufferLength1 è minore di 0. (DM) Il valore specificato per l'argomento BufferLength2 è minore di 0. |
| HY103 | Codice di recupero non valido | (DM) Il valore specificato per l'argomento Direction non è uguale a SQL_FETCH_FIRST, SQL_FETCH_FIRST_USER, SQL_FETCH_FIRST_SYSTEM o SQL_FETCH_NEXT. |
| 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. |
Commenti
Poiché SQLDataSources viene implementato in Gestione driver, è supportato per tutti i driver indipendentemente dalla conformità degli standard di un determinato driver.
Un'applicazione può chiamare SQLDataSources più volte per recuperare tutti i nomi delle origini dati. Gestione driver recupera queste informazioni dalle informazioni di sistema. Quando non sono presenti più nomi di origine dati, Gestione driver restituisce SQL_NO_DATA. Se SQLDataSources viene chiamato con SQL_FETCH_NEXT immediatamente dopo che restituisce SQL_NO_DATA, restituirà il primo nome dell'origine dati. Per informazioni su come un'applicazione usa le informazioni restituite da SQLDataSources, vedere Scelta di un'origine dati o di un driver.
Se SQL_FETCH_NEXT viene passato a SQLDataSources la prima volta che viene chiamato, restituirà il primo nome dell'origine dati.
Il driver determina il mapping dei nomi delle origini dati alle origini dati effettive.
Funzioni correlate
| Per informazioni su | Vedere |
|---|---|
| Individuazione ed elenco dei valori necessari per la connessione a un'origine dati | Funzione SQLBrowseConnect |
| Connessione a un'origine dati | Funzione SQLConnect |
| Connessione a un'origine dati tramite una stringa di connessione o una finestra di dialogo | Funzione SQLDriverConnect |
| Restituzione di descrizioni e attributi del driver | Funzione SQLDrivers |