Funzione SQLGetConnectAttr

Conformità
Versione introdotta: Conformità agli standard ODBC 3.0: ISO 92

Sommario
SQLGetConnectAttr restituisce l'impostazione corrente di un attributo di connessione.

Note

Per maggiori informazioni su cosa mappa questa funzione il Driver Manager quando un'applicazione ODBC 3*.x* lavora con un driver ODBC 2*.x*, vedi Mappatura delle funzioni di sostituzione per la compatibilità retroattiva delle applicazioni.

Sintassi

  
SQLRETURN SQLGetConnectAttr(  
     SQLHDBC        ConnectionHandle,  
     SQLINTEGER     Attribute,  
     SQLPOINTER     ValuePtr,  
     SQLINTEGER     BufferLength,  
     SQLINTEGER *   StringLengthPtr);

Arguments

ConnectionHandle
[Input] Identificatore di connessione.

Attributo
[Input] Attribuisce per recuperare.

ValuePtr
[Output] Un puntatore alla memoria in cui restituire il valore corrente dell'attributo specificato da Attributo. Per gli attributi di tipo intero, alcuni driver possono scrivere solo i 32 o 16 bit inferiori di un buffer e lasciare invariato il bit di ordine superiore. Pertanto, le applicazioni dovrebbero utilizzare un buffer di SQLULEN e inizializzare il valore a 0 prima di chiamare questa funzione.

Se ValuePtr è NULL, StringLengthPtr restituirà comunque il numero totale di byte (escluso il carattere di null-termination per i dati del carattere) disponibili nel buffer indicato da ValuePtr.

BufferLength
[Input] Se Attribute è un attributo definito da ODBC e ValuePtr punta a una stringa di caratteri o a un buffer binario, questo argomento deve essere la lunghezza di *ValuePtr. Se Attribute è un attributo definito da ODBC e *ValuePtr è un intero, BufferLength viene ignorato. Se il valore in *ValuePtr è una stringa Unicode (quando si chiama SQLGetConnectAttrW), l'argomento BufferLength deve essere un numero pari.

Se l'Attributo è definito dal driver, l'applicazione indica la natura dell'attributo al Driver Manager impostando l'argomento BufferLength . BufferLength può avere i seguenti valori:

  • Se *ValuePtr è un puntatore a una stringa di caratteri, BufferLength è la lunghezza della stringa.

  • Se *ValuePtr è un puntatore a un buffer binario, l'applicazione inserisce il risultato della macro SQL_LEN_BINARY_ATTR(length) in BufferLength. Questo attribuisce un valore negativo a BufferLength.

  • Se *ValuePtr è un puntatore a un valore diverso da una stringa di caratteri o binaria, BufferLength dovrebbe avere il valore SQL_IS_POINTER.

  • Se *ValuePtr contiene un tipo di dato a lunghezza fissa, BufferLength è SQL_IS_INTEGER o SQL_IS_UINTEGER, a seconda dei conti.

StringLengthPtr
[Output] Un puntatore a un buffer in cui restituire il numero totale di byte (escluso il carattere di terminazione nulla) disponibili da restituire in *ValuePtr. Se il valore dell'attributo è una stringa di caratteri e il numero di byte disponibili da restituire è maggiore di BufferLength meno la lunghezza del carattere di null-termination, i dati in *ValuePtr vengono troncati a BufferLength meno la lunghezza del carattere di null-termination e vengono null-terminati dal driver.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR o SQL_INVALID_HANDLE.

Diagnostica

Quando SQLGetConnectAttr restituisce SQL_ERROR o SQL_SUCCESS_WITH_INFO, un valore SQLSTATE associato può essere ottenuto dalla struttura dati diagnostica chiamando SQLGetDiagRec con un HandleType di SQL_HANDLE_DBC e un Handle di ConnectionHandle. La tabella seguente elenca i valori SQLSTATE tipicamente restituiti da SQLGetConnectAttr e spiega ciascuno 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.
01004 Dati stringa, troncati a destra I dati restituiti in *ValuePtr sono stati troncati per essere BufferLength meno la lunghezza di un carattere a terminazione nulla. La lunghezza del valore della stringa non runcata viene restituita in *StringLongPtr. (La funzione restituisce SQL_SUCCESS_WITH_INFO.
08003 Connessione non aperta (DM) È stato specificato un valore di Attributo che richiedeva una connessione aperta.
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.
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 dalla struttura dati diagnostica tramite l'argomento MessageText in SQLGetDiagField descrive l'errore e la sua causa.
HY001 Errore di allocazione della memoria Il driver non è riuscito ad allocare memoria necessaria per supportare l'esecuzione o il completamento della funzione.
HY010 Errore della sequenza di funzioni (DM) SQLBrowseConnect veniva chiamato per il ConnectionHandle e restituiva SQL_NEED_DATA. Questa funzione veniva chiamata prima che SQLBrowseConnect restituisse SQL_SUCCESS_WITH_INFO o SQL_SUCCESS.

(DM) SQLExecute, SQLExecDirect o SQLMoreResults veniva chiamato per il ConnectionHandle 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) *ValuePtr è una stringa di caratteri, e BufferLength era inferiore a zero ma non uguale a SQL_NTS.
HY092 Identificatore di attributo/opzione invalido Il valore specificato per l'argomento Attributo non era valido per la versione di ODBC supportata dal driver.
HY114 Il driver non supporta l'esecuzione di funzioni asincrone a livello di connessione (DM) Un'applicazione ha tentato di abilitare l'esecuzione di funzioni asincrone con SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE per un driver che non supporta operazioni di connessione asincrona.
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 Il valore specificato per l'attributo dell'argomento Attributo era un valido attributo di connessione ODBC per la versione di ODBC supportata dal driver, ma non era supportato dal driver.
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 che corrisponde a ConnectionHandle non supporta la funzione.

Comments

Per informazioni generali sugli attributi di connessione, vedi Attributi di Connessione.

Per un elenco degli attributi che possono essere impostati, vedi SQLSetConnectAttr. Nota che se Attribute specifica un attributo che restituisce una stringa, ValuePtr deve essere un puntatore a un buffer per la stringa. La lunghezza massima della stringa restituita, incluso il carattere di terminazione nulla, sarà byte BufferLength .

A seconda dell'attributo, un'applicazione non deve stabilire una connessione prima di chiamare SQLGetConnectAttr. Tuttavia, se viene chiamato SQLGetConnectAttr e l'attributo specificato non ha un valore predefinito e non è stato impostato da una chiamata precedente a SQLSetConnectAttr, SQLGetConnectAttr restituirà SQL_NO_DATA.

Se Attribute è SQL_ATTR_ TRACE o SQL_ATTR_ TRACEFILE, ConnectionHandle non deve essere valido, e SQLGetConnectAttr non restituirà SQL_ERROR o SQL_INVALID_HANDLE se ConnectionHandle è invalido. Queste caratteristiche valgono per tutte le connessioni. SQLGetConnectAttr restituirà SQL_ERROR o SQL_INVALID_HANDLE se un altro argomento è invalido.

Sebbene un'applicazione possa impostare attributi di un'istruzione usando SQLSetConnectAttr, un'applicazione non può usare SQLGetConnectAttr per recuperare i valori degli attributi dell'istruzione; deve chiamare SQLGetStmtAttr per recuperare l'impostazione degli attributi delle istruzioni.

Sia SQL_ATTR_AUTO_IPD che SQL_ATTR_CONNECTION_DEAD attributi di connessione possono essere restituiti tramite una chiamata a SQLGetConnectAttr , ma non possono essere impostati tramite una chiamata a SQLSetConnectAttr.

Note

Non esiste alcun supporto asincrono per SQLGetConnectAttr. Quando si implementa SQLGetConnectAttr, un driver può migliorare le prestazioni minimizzando il numero di volte in cui queste informazioni vengono inviate o richieste dal server.

Per informazioni su Vedi
Restituzione dell'impostazione di un attributo di istruzione Funzione SQLGetStmtAttr
Impostazione di un attributo di connessione Funzione SQLSetConnectAttr
Impostazione di un attributo ambiente Funzione SQLSetEnvAttr
Impostazione di un attributo di istruzione Funzione SQLSetStmtAttr

Contenuti correlati

  • Last updated on