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 handleType di 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

Vedi anche

Riferimento API ODBC
File di intestazione ODBC