Funzione SQLGetEnvAttr

  • Articolo

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.

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

Vedi anche

Riferimento API ODBC
File di intestazione ODBC