SQLSetEnvAttr Function

  • Articolo

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

Riepilogo
SQLSetEnvAttr imposta gli attributi che regolano gli aspetti degli ambienti.

Sintassi

  
SQLRETURN SQLSetEnvAttr(  
     SQLHENV      EnvironmentHandle,  
     SQLINTEGER   Attribute,  
     SQLPOINTER   ValuePtr,  
     SQLINTEGER   StringLength);

Argomenti

EnvironmentHandle
[Input] Handle dell'ambiente.

Attributo
[Input] Attributo da impostare, elencato in "Commenti".

ValuePtr
[Input] Puntatore al valore da associare a Attribute. A seconda del valore di Attribute, ValuePtr sarà un valore intero a 32 bit o puntare a una stringa di caratteri con terminazione Null.

StringLength
[Input] Se ValuePtr punta a una stringa di caratteri o a un buffer binario, questo argomento deve essere la lunghezza di *ValuePtr. Per i dati stringa di caratteri, questo argomento deve contenere il numero di byte nella stringa.

Se ValuePtr è un numero intero, StringLength viene ignorato.

Resi

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR o SQL_INVALID_HANDLE.

Diagnostica

Quando SQLSetEnvAttr 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 restituiti in genere da SQLSetEnvAttr 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. Se un driver non supporta un attributo di ambiente, l'errore può essere restituito solo durante il tempo di connessione.

SQLSTATE Errore Descrizione
01000 Avviso generale Messaggio informativo specifico del driver. (La funzione restituisce SQL_SUCCESS_WITH_INFO.
01S02 Valore dell'opzione modificato Il driver non supporta il valore specificato in ValuePtr e ha sostituito un valore simile. (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.
HY009 Uso non valido del puntatore Null L'argomento Attribute ha identificato un attributo di ambiente che richiedeva un valore stringa e l'argomento ValuePtr era un puntatore Null.
HY010 Errore della sequenza di funzioni (DM) Un handle di connessione è stato allocato in EnvironmentHandle.

(DM) SQL_ATTR_ODBC_VERSION non è stato impostato con SQLSetEnvAttr e Attribute non è uguale a SQL_ATTR_ODBC_VERSION. 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.
HY024 Valore dell'attributo non valido Dato il valore attribute specificato, è stato specificato un valore non valido in ValuePtr.
HY090 Lunghezza della stringa o del buffer non valida L'argomento StringLength era minore di 0, ma non era SQL_NTS.
HY092 Identificatore di attributo/opzione non valido (DM) 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 è supportato dal driver.

(DM) L'argomento Attribute è stato SQL_ATTR_OUTPUT_NTS e ValuePtr è stato SQL_FALSE.

Commenti

Un'applicazione può chiamare SQLSetEnvAttr solo se non viene allocato alcun handle di connessione nell'ambiente. Tutti gli attributi di ambiente impostati correttamente dall'applicazione per l'ambiente persistono fino a quando non viene chiamato SQLFreeHandle nell'ambiente. Più handle di ambiente possono essere allocati contemporaneamente in ODBC 3.x.

Il formato delle informazioni impostate tramite ValuePtr dipende dall'attributo specificato. SQLSetEnvAttr accetterà le informazioni sugli attributi in uno dei due formati diversi: una stringa di caratteri con terminazione Null o un valore intero a 32 bit. Il formato di ogni attributo è indicato nella descrizione dell'attributo.

Non esistono attributi di ambiente specifici del driver.

Gli attributi di connessione non possono essere impostati da una chiamata a SQLSetEnvAttr. Se si tenta di eseguire questa operazione, verrà restituito SQLSTATE HY092 (identificatore di attributo/opzione non valido).

Attributo Contenuto di ValuePtr
SQL_ATTR_CONNECTION_POOLING (ODBC 3.8) Valore SQLUINTEGER a 32 bit che abilita o disabilita il pool di connessioni a livello di ambiente. È possibile scegliere i seguenti valori:

SQL_CP_OFF = Il pool di connessioni è disattivato. Si tratta dell'impostazione predefinita.

SQL_CP_ONE_PER_DRIVER = Per ogni driver è supportato un singolo pool di connessioni. Ogni connessione in un pool è associata a un driver.

SQL_CP_ONE_PER_HENV = Per ogni ambiente è supportato un singolo pool di connessioni. Ogni connessione in un pool è associata a un ambiente.

SQL_CP_DRIVER_AWARE = Usare la funzionalità di riconoscimento del pool di connessioni del driver, se disponibile. Se il driver non supporta la consapevolezza del pool di connessioni, SQL_CP_DRIVER_AWARE viene ignorato e viene usato SQL_CP_ONE_PER_HENV. Per altre informazioni, vedere Pool di connessioni compatibile con driver. In un ambiente in cui alcuni driver supportano e alcuni driver non supportano la consapevolezza del pool di connessioni, SQL_CP_DRIVER_AWARE può abilitare la funzionalità di riconoscimento del pool di connessioni su tali driver di supporto, ma equivale a impostare su SQL_CP_ONE_PER_HENV su tali driver che non supportano la funzionalità di riconoscimento del pool di connessioni.

Il pool di connessioni è abilitato chiamando SQLSetEnvAttr per impostare l'attributo SQL_ATTR_CONNECTION_POOLING su SQL_CP_ONE_PER_DRIVER o SQL_CP_ONE_PER_HENV. Questa chiamata deve essere eseguita prima che l'applicazione allochi l'ambiente condiviso per il quale deve essere abilitato il pool di connessioni. L'handle di ambiente nella chiamata a SQLSetEnvAttr è impostato su Null, che rende SQL_ATTR_CONNECTION_POOLING un attributo a livello di processo. Dopo l'abilitazione del pool di connessioni, l'applicazione alloca un ambiente condiviso implicito chiamando SQLAllocHandle con l'argomento InputHandle impostato su SQL_HANDLE_ENV.

Dopo aver abilitato il pool di connessioni e aver selezionato un ambiente condiviso per un'applicazione, SQL_ATTR_CONNECTION_POOLING non può essere reimpostato per tale ambiente, perché SQLSetEnvAttr viene chiamato con un handle di ambiente Null durante l'impostazione di questo attributo. Se questo attributo è impostato mentre il pool di connessioni è già abilitato in un ambiente condiviso, l'attributo influisce solo sugli ambienti condivisi allocati successivamente.

È anche possibile abilitare il pool di connessioni in un ambiente. Tenere presente quanto segue sul pool di connessioni all'ambiente:

- L'abilitazione del pool di connessioni in un handle NULL è un attributo a livello di processo. Gli ambienti allocati successivamente saranno un ambiente condiviso e erediteranno l'impostazione del pool di connessioni a livello di processo.
- Dopo l'allocazione di un ambiente, un'applicazione può comunque modificare l'impostazione del pool di connessioni.
- Se il pool di connessioni all'ambiente è abilitato e il driver della connessione usa il pooling di driver, il pool di ambienti ha la preferenza.

SQL_ATTR_CONNECTION_POOLING viene implementato all'interno di Gestione driver. Un driver non deve implementare SQL_ATTR_CONNECTION_POOLING. Le applicazioni ODBC 2.0 e 3.0 possono impostare questo attributo di ambiente.

Per altre informazioni, vedere la pagina relativa ai pool di connessioni ODBC.
SQL_ATTR_CP_MATCH (ODBC 3.0) Valore SQLUINTEGER a 32 bit che determina la modalità di scelta di una connessione da un pool di connessioni. Quando viene chiamato SQLConnect o SQLDriverConnect, Gestione driver determina quale connessione viene riutilizzata dal pool. Gestione driver tenta di associare le opzioni di connessione nella chiamata e gli attributi di connessione impostati dall'applicazione alle parole chiave e agli attributi di connessione delle connessioni nel pool. Il valore di questo attributo determina il livello di precisione dei criteri di corrispondenza.

Per impostare il valore di questo attributo vengono usati i valori seguenti:

SQL_CP_STRICT_MATCH = Vengono riutilizzate solo le connessioni che corrispondono esattamente alle opzioni di connessione nella chiamata e gli attributi di connessione impostati dall'applicazione. Si tratta dell'impostazione predefinita.

SQL_CP_RELAXED_MATCH = È possibile usare le connessioni con parole chiave delle stringhe di connessione corrispondenti. Le parole chiave devono corrispondere, ma non tutti gli attributi di connessione devono corrispondere.

Per altre informazioni su come Gestione driver esegue la corrispondenza nella connessione a una connessione in pool, vedere SQLConnect. Per altre informazioni sul pool di connessioni, vedere Pool di connessioni ODBC.
SQL_ATTR_ODBC_VERSION (ODBC 3.0) Intero a 32 bit che determina se determinate funzionalità presentano comportamenti ODBC 2.x o ODBC 3.x . Per impostare il valore di questo attributo vengono usati i valori seguenti:

SQL_OV_ODBC3_80 = Gestione driver e driver presentano il comportamento ODBC 3.8 seguente:

- Il driver restituisce e prevede codici ODBC 3.x per data, ora e timestamp.
- Il driver restituisce codici SQLSTATE ODBC 3.x quando viene chiamato SQLError, SQLGetDiagField o SQLGetDiagRec .
- L'argomento CatalogName in una chiamata a SQLTables accetta un criterio di ricerca.
- Gestione driver supporta l'estendibilità del tipo di dati C. Per altre informazioni sull'estendibilità del tipo di dati C, vedere Tipi di dati C in ODBC.

Per altre informazioni, vedere Novità di ODBC 3.8.

SQL_OV_ODBC3 = Gestione driver e driver presentano il comportamento ODBC 3.x seguente:

- Il driver restituisce e prevede codici ODBC 3.x per data, ora e timestamp.
- Il driver restituisce codici SQLSTATE ODBC 3.x quando viene chiamato SQLError, SQLGetDiagField o SQLGetDiagRec .
- L'argomento CatalogName in una chiamata a SQLTables accetta un criterio di ricerca.
- Gestione driver non supporta l'estendibilità del tipo di dati C.

SQL_OV_ODBC2 = Gestione driver e driver presentano il comportamento ODBC 2.x seguente. Ciò è particolarmente utile per un'applicazione ODBC 2.x che usa un driver ODBC 3.x .

- Il driver restituisce e prevede codici ODBC 2.x per data, ora e timestamp.
- Il driver restituisce codici SQLSTATE ODBC 2.x quando viene chiamato SQLError, SQLGetDiagField o SQLGetDiagRec .
- L'argomento CatalogName in una chiamata a SQLTables non accetta un criterio di ricerca.
- Gestione driver non supporta l'estendibilità del tipo di dati C.

Un'applicazione deve impostare questo attributo di ambiente prima di chiamare qualsiasi funzione con un argomento SQLHENV oppure la chiamata restituirà SQLSTATE HY010 (errore della sequenza di funzioni). È specifico del driver se esiste un comportamento aggiuntivo per questi flag ambientali.

- Per altre informazioni, vedere Dichiarazione della versione ODBC dell'applicazione e delle modifiche comportamentali.
SQL_ATTR_OUTPUT_NTS (ODBC 3.0) Intero a 32 bit che determina il modo in cui il driver restituisce dati stringa. Se SQL_TRUE, il driver restituisce dati stringa con terminazione Null. Se SQL_FALSE, il driver non restituisce dati stringa con terminazione Null.

Per impostazione predefinita, questo attributo viene SQL_TRUE. Una chiamata a SQLSetEnvAttr per impostarla su SQL_TRUE restituisce SQL_SUCCESS. Una chiamata a SQLSetEnvAttr per impostarla su SQL_FALSE restituisce SQL_ERROR e SQLSTATE HYC00 (funzionalità facoltativa non implementata).
Per informazioni su Vedere
Allocazione di un handle Funzione SQLAllocHandle
Restituzione dell'impostazione di un attributo di ambiente Funzione SQLGetEnvAttr

Vedi anche

Riferimento API ODBC
File di intestazione ODBC
Novità di ODBC 3.8