Condividi tramite

Funzione SQLSetConnectAttr

  • Articolo

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

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

Nota

Per altre informazioni sul mapping di questa funzione a quando un'applicazione ODBC 3*.x* utilizza un driver ODBC 2*.x*, vedere Mapping di funzioni di sostituzione per compatibilità con le versioni precedenti delle applicazioni.

Sintassi

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

Argomenti

ConnectionHandle
[Input] Handle di connessione.

Attributo
[Input] Attributo da recuperare.

ValuePtr
[Output] Puntatore alla memoria in cui restituire il valore corrente dell'attributo specificato da Attribute. Per gli attributi di tipo integer, alcuni driver possono scrivere solo il bit inferiore a 32 bit o 16 bit di un buffer e lasciare invariato il bit di ordine superiore. Pertanto, le applicazioni devono usare un buffer di SQLULEN e inizializzare il valore su 0 prima di chiamare questa funzione.

Se ValuePtr è NULL, StringLengthPtr restituirà comunque il numero totale di byte (escluso il carattere di terminazione null per i dati di tipo carattere) da restituire nel buffer a cui punta 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 numero 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 Attribute è un attributo definito dal driver, l'applicazione indica la natura dell'attributo a Gestione driver impostando l'argomento BufferLength . BufferLength può avere i valori seguenti:

  • 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. In questo modo viene impostato un valore negativo in BufferLength.

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

  • Se *ValuePtr contiene un tipo di dati a lunghezza fissa, BufferLength è SQL_IS_INTEGER o SQL_IS_UINTEGER, in base alle esigenze.

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

Resi

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, è possibile ottenere un valore SQLSTATE associato dalla struttura dei dati di diagnostica chiamando SQLGetDiagRec con handleTypedi SQL_HANDLE_DBC e handle di ConnectionHandle. La tabella seguente elenca i valori SQLSTATE restituiti in genere da SQLGetConnectAttr 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.
01004 Dati stringa, troncati a destra I dati restituiti in *ValuePtr sono stati troncati per essere BufferLength meno la lunghezza di un carattere di terminazione Null. La lunghezza del valore stringa non troncata viene restituita in *StringLengthPtr. (La funzione restituisce SQL_SUCCESS_WITH_INFO.
08003 Connessione non aperta (DM) È stato specificato un valore di attributo che richiede 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 dei dati di diagnostica dall'argomento MessageText in SQLGetDiagField 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.
HY010 Errore della sequenza di funzioni (DM) SQLBrowseConnect è stato chiamato per ConnectionHandlee restituito SQL_NEED_DATA. Questa funzione è stata chiamata prima che SQLBrowseConnect restituisca SQL_SUCCESS_WITH_INFO o SQL_SUCCESS.

(DM) SQLExecute, SQLExecDirect o SQLMoreResults è stato chiamato per 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 è minore di zero ma non uguale a SQL_NTS.
HY092 Identificatore di attributo/opzione non valido Il valore specificato per l'argomento Attribute non è valido per la versione di ODBC supportata dal driver.
HY114 Il driver non supporta l'esecuzione asincrona a livello di connessione (DM) Un'applicazione ha tentato di abilitare l'esecuzione asincrona di funzioni con SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE per un driver che non supporta operazioni di connessione asincrone.
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'argomento Attribute è un attributo di connessione ODBC valido per la versione di ODBC supportata dal driver, ma non è supportata 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.

Commenti

Per informazioni generali sugli attributi di connessione, vedere Attributi di connessione.

Per un elenco di attributi che è possibile impostare, vedere SQLSetConnectAttr. Si noti 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 Null, sarà BufferLength byte.

A seconda dell'attributo, un'applicazione non deve stabilire una connessione prima di chiamare SQLGetConnectAttr. Tuttavia, se sqlGetConnectAttr viene chiamato 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 non è valido. Questi attributi si applicano a tutte le connessioni. SQLGetConnectAttr restituirà SQL_ERROR o SQL_INVALID_HANDLE se un altro argomento non è valido.

Sebbene un'applicazione possa impostare attributi di istruzione tramite SQLSetConnectAttr, un'applicazione non può usare SQLGetConnectAttr per recuperare i valori dell'attributo dell'istruzione. Deve chiamare SQLGetStmtAttr per recuperare l'impostazione degli attributi dell'istruzione.

Entrambi gli attributi di connessione SQL_ATTR_AUTO_IPD e SQL_ATTR_CONNECTION_DEAD possono essere restituiti da una chiamata a SQLGetConnectAttr , ma non possono essere impostati da una chiamata a SQLSetConnectAttr.

Nota

Non è disponibile alcun supporto asincrono per SQLGetConnectAttr. Quando si implementa SQLGetConnectAttr, un driver può migliorare le prestazioni riducendo al minimo il numero di volte in cui le informazioni vengono inviate o richieste dal server.

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

Vedi anche

Riferimento API ODBC
File di intestazione ODBC