Funzione SQLGetEnvAttr
Conformità
Versione introdotta: Conformità agli standard ODBC 3.0: ISO 92
Riepilogo
SQLGetEnvAttr restituisce l'impostazione corrente di un attributo di ambiente.
Sintassi
SQLRETURN SQLGetEnvAttr(
SQLHENV EnvironmentHandle,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER BufferLength,
SQLINTEGER * StringLengthPtr);
Argomenti
EnvironmentHandle
[Input] Handle dell'ambiente.
Attributo
[Input] Attributo da recuperare.
ValuePtr
[Output] Puntatore a un buffer in cui restituire il valore corrente dell'attributo specificato da Attribute.
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 ValuePtr punta a una stringa di caratteri, questo argomento deve essere la lunghezza di *ValuePtr. Se *ValuePtr è un numero intero, BufferLength viene ignorato. Se *ValuePtr è una stringa Unicode (quando si chiama SQLGetEnvAttrW), l'argomento BufferLength deve essere un numero pari. Se il valore dell'attributo non è una stringa di caratteri, BufferLength non viene usato.
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 o uguale a BufferLength, i dati in *ValuePtr vengono troncati a BufferLength meno la lunghezza di un 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 SQLGetEnvAttr 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 comunemente restituiti da SQLGetEnvAttr 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 il carattere di terminazione Null. La lunghezza del valore stringa non troncata viene restituita in *StringLengthPtr. (La funzione restituisce SQL_SUCCESS_WITH_INFO. |
| 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. |
| HY010 | Errore della sequenza di funzioni | (DM) SQL_ATTR_ODBC_VERSION non è ancora stato impostato tramite SQLSetEnvAttr. Non è necessario impostare SQL_ATTR_ODBC_VERSION in modo esplicito se si usa SQLAllocHandleStd. |
| 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. |
| HY092 | Identificatore di attributo/opzione non valido | Il valore specificato per l'argomento Attribute non è valido per la versione di ODBC supportata dal driver. |
| 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 ambiente ODBC valido per la versione di ODBC supportata dal driver, ma non è supportata dal driver. |
| IM001 | Il driver non supporta questa funzione | (DM) Il driver corrispondente a EnvironmentHandle non supporta la funzione. |
Commenti
Per un elenco di attributi, vedere SQLSetEnvAttr. Non esistono attributi di ambiente specifici del driver. Se Attribute specifica un attributo che restituisce una stringa, ValuePtr deve essere un puntatore a un buffer in cui restituire la stringa. La lunghezza massima della stringa, incluso il byte di terminazione Null, sarà BufferLength byte.
SQLGetEnvAttr può essere chiamato in qualsiasi momento tra l'allocazione e la liberazione di un handle di ambiente. Tutti gli attributi di ambiente impostati correttamente dall'applicazione per l'ambiente vengono mantenuti fino a quando non viene chiamato SQLFreeHandle in EnvironmentHandle con handleType di SQL_HANDLE_ENV. Più handle di ambiente possono essere allocati contemporaneamente in ODBC 3*.x*. Un attributo di ambiente in un ambiente non è interessato quando è stato allocato un altro ambiente.
Nota
L'attributo dell'ambiente SQL_ATTR_OUTPUT_NTS è supportato dalle applicazioni conformi agli standard. Quando viene chiamato SQLGetEnvAttr , Gestione driver ODBC 3*.x* restituisce sempre SQL_TRUE per questo attributo. SQL_ATTR_OUTPUT_NTS può essere impostato su SQL_TRUE solo tramite una chiamata a SQLSetEnvAttr.
Funzioni correlate
| Per informazioni su | Vedere |
|---|---|
| Restituzione dell'impostazione di un attributo di connessione | Funzione SQLGetConnectAttr |
| 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 |