Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
Conformità
Versione introdotta: Conformità agli standard ODBC 3.0: ISO 92
Sommario
SQLSetEnvAttr imposta attributi che governano aspetti degli ambienti.
Sintassi
SQLRETURN SQLSetEnvAttr(
SQLHENV EnvironmentHandle,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER StringLength);
Arguments
EnvironmentHandle
[Input] Controllo ambientale.
Attributo
[Input] Attributo al set, elencato in "Commenti."
ValuePtr
[Input] Punta al valore da associare a Attributo. A seconda del valore di Attributo, ValuePtr sarà un valore intero a 32 bit o punta a una stringa di caratteri terminata nullo.
StringLength
[Input] Se ValuePtr punta a una stringa di caratteri o a un buffer binario, questo argomento dovrebbe essere della lunghezza di *ValuePtr. Per i dati della stringa di caratteri, questo argomento dovrebbe contenere il numero di byte nella stringa.
Se ValuePtr è un intero, StringLength viene ignorato.
Returns
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR o SQL_INVALID_HANDLE.
Diagnostica
Quando SQLSetEnvAttr restituisce SQL_ERROR o SQL_SUCCESS_WITH_INFO, un valore SQLSTATE associato può essere ottenuto chiamando SQLGetDiagRec con un HandleType di SQL_HANDLE_ENV e un Handle di EnvironmentHandle. La tabella seguente elenca i valori SQLSTATE tipicamente restituiti da SQLSetEnvAttr 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. Se un driver non supporta un attributo di ambiente, l'errore può essere restituito solo durante il tempo di connessione.
| SQLSTATE | Error | Description |
|---|---|---|
| 01000 | Avviso generale | Messaggio informativo specifico del driver. (La funzione restituisce SQL_SUCCESS_WITH_INFO. |
| 01S02 | Valore dell'opzione modificato | Il driver non supportava il valore specificato in ValuePtr e ne sostituiva uno 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 identificava un attributo ambiente che richiedeva un valore di stringa, e l'argomento ValuePtr era un puntatore nullo. |
| HY010 | Errore della sequenza di funzioni | (DM) Un handle di connessione è stato assegnato su 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 esplicitamente 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 inferiore a 0 ma non era SQL_NTS. |
| HY092 | Identificatore di attributo/opzione invalido | (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'attributo dell'argomento Attribute era un attributo valido dell'ambiente ODBC per la versione di ODBC supportata dal driver, ma non era supportato dal driver. (DM) L'argomento dell'Attributo era SQL_ATTR_OUTPUT_NTS, e ValuePtr era SQL_FALSE. |
Comments
Un'applicazione può chiamare SQLSetEnvAttr solo se non è allocato alcun handle di connessione nell'ambiente. Tutti gli attributi dell'ambiente impostati con successo dall'applicazione per l'ambiente persistono fino a quando SQLFreeHandle viene chiamato sull'ambiente. In ODBC 3.x possono essere assegnati simultaneamente più handle di ambiente.
Il formato delle informazioni impostate tramite ValuePtr dipende dall'Attributo specificato. SQLSetEnvAttr accetterà informazioni sugli attributi in uno dei due formati diversi: una stringa di caratteri terminata a nullo o un valore intero a 32 bit. Il formato di ogni attributo è indicato nella descrizione dell'attributo.
Non ci sono attributi ambientali specifici per il conducente.
Gli attributi di connessione non possono essere impostati tramite una chiamata a SQLSetEnvAttr. Provando a farlo verrà restituito SQLSTATE HY092 (identificatore di attributo/opzione non valido).
| Attributo | Contenuto di ValuePtr |
|---|---|
| SQL_ATTR_CONNECTION_POOLING (ODBC 3.8) | Un valore SQLUINTEGER a 32 bit che consente o disabilita il pool di connessione a livello di ambiente. Vengono utilizzati i valori seguenti: SQL_CP_OFF = Il pool di connessione è disattivato. Si tratta dell'impostazione predefinita. SQL_CP_ONE_PER_DRIVER = È supportato un singolo pool di connessione per ogni driver. Ogni connessione in un pool è associata a un driver. SQL_CP_ONE_PER_HENV = È supportato un singolo pool di connessione per ogni ambiente. Ogni connessione in un pool è associata a un unico ambiente. SQL_CP_DRIVER_AWARE = Usa la funzione di consapevolezza del pool di connessione del driver, se disponibile. Se il driver non supporta la consapevolezza del pool di connessione, SQL_CP_DRIVER_AWARE viene ignorato e viene utilizzato SQL_CP_ONE_PER_HENV. Per maggiori informazioni, vedere Pool di connessioni compatibile con il driver. In un ambiente in cui alcuni driver supportano e altri non supportano la consapevolezza del pool, SQL_CP_DRIVER_AWARE può attivare la funzione consapevolezza del connect-pool su chi supporta i driver, ma è equivalente a impostare per SQL_CP_ONE_PER_HENV su quei driver che non supportano la consapevolezza del pool. Il pool di connessione è 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 dell'ambiente nella chiamata a SQLSetEnvAttr è impostato su null, il che rende SQL_ATTR_CONNECTION_POOLING un attributo a livello di processo. Dopo aver abilitato il pool di connessioni, l'applicazione alloca un ambiente condiviso implicito chiamando SQLAllocHandle con l'argomento InputHandle impostato su SQL_HANDLE_ENV. Dopo che il pool di connessione è stato abilitato e un ambiente condiviso selezionato per un'applicazione, non SQL_ATTR_CONNECTION_POOLING può essere resettato per quell'ambiente, perché SQLSetEnvAttr viene chiamato con un handle null quando si imposta questo attributo. Se questo attributo è impostato mentre il pool di connessione è già abilitato su un ambiente condiviso, l'attributo influisce solo sugli ambienti condivisi che vengono assegnati successivamente. È anche possibile abilitare il pool di connessione su un ambiente. Si noti quanto segue riguardo al pool di connessione ambientale: - Abilitare il pool di connessione su un handle NULL è un attributo a livello di processo. Gli ambienti successivamente assegnati saranno un ambiente condiviso e erediteranno l'impostazione di pooling di connessione a livello di processo. - Dopo che un ambiente è stato allocato, un'applicazione può comunque modificare l'impostazione del suo pool di connessioni. - Se il pool di connessione ambientale è abilitato e il driver della connessione utilizza il pool di driver, il pooling ambientale prende la preferenza. SQL_ATTR_CONNECTION_POOLING è implementata all'interno del Driver Manager. Un driver non deve implementare SQL_ATTR_CONNECTION_POOLING. Le applicazioni ODBC 2.0 e 3.0 possono impostare questo attributo ambientale. Per altre informazioni, vedere la pagina relativa ai pool di connessioni ODBC. |
| SQL_ATTR_CP_MATCH (ODBC 3.0) | Un valore SQLUINTEGER a 32 bit che determina come viene scelta una connessione da un pool di connessioni. Quando viene chiamato SQLConnect o SQLDriverConnect , il Driver Manager determina quale connessione viene riutilizzata dal pool. Il Driver Manager cerca di abbinare 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 abbinamento. I seguenti valori sono usati per impostare il valore di questo attributo: SQL_CP_STRICT_MATCH = Solo le connessioni che corrispondono esattamente alle opzioni di connessione nella chiamata e agli attributi di connessione impostati dall'applicazione vengono riutilizzate. Si tratta dell'impostazione predefinita. SQL_CP_RELAXED_MATCH = Possono essere utilizzate connessioni con stringa di connessione parole chiave corrispondenti. Le parole chiave devono corrispondere, ma non tutti gli attributi di connessione devono corrispondere. Per maggiori informazioni su come il Driver Manager esegue la corrispondenza nella connessione a una connessione pooled, vedi SQLConnect. Per altre informazioni sul pool di connessioni, vedere Pool di connessioni ODBC. |
| SQL_ATTR_ODBC_VERSION (ODBC 3.0) | Un intero a 32 bit che determina se certe funzionalità mostrano un comportamento ODBC 2.x o ODBC 3.x . I seguenti valori sono usati per impostare il valore di questo attributo: SQL_OV_ODBC3_80 = Il Driver Manager e il driver mostrano il seguente comportamento ODBC 3.8: - Il driver restituisce e si aspetta codici ODBC 3.x per data, ora e timestamp. - Il driver restituisce codici ODBC 3.x SQLSTATE quando vengono chiamati SQLError, SQLGetDiagField o SQLGetDiagRec . - L'argomento CatalogName in una chiamata a SQLTables accetta un pattern di ricerca. - Il Driver Manager supporta l'estensibilità dei tipi dati C. Per maggiori informazioni sull'estensibilità dei tipi di dati C, vedi Tipi di Dati C in ODBC. Per maggiori informazioni, vedi Cosa c'è di nuovo in ODBC 3.8. SQL_OV_ODBC3 = Il Driver Manager e il driver mostrano il seguente comportamento ODBC 3.x : - Il driver restituisce e si aspetta codici ODBC 3.x per data, ora e timestamp. - Il driver restituisce codici ODBC 3.x SQLSTATE quando vengono chiamati SQLError, SQLGetDiagField o SQLGetDiagRec . - L'argomento CatalogName in una chiamata a SQLTables accetta un pattern di ricerca. - Il Driver Manager non supporta l'estensibilità del tipo di dati C. SQL_OV_ODBC2 = Il Driver Manager e il driver mostrano il seguente comportamento ODBC 2.x . Questo è particolarmente utile per un'applicazione ODBC 2.x che lavora con un driver ODBC 3.x . - Il driver restituisce e si aspetta codici ODBC 2.x per data, ora e timestamp. - Il driver restituisce codici ODBC 2.x SQLSTATE quando vengono chiamati SQLError, SQLGetDiagField o SQLGetDiagRec . - L'argomento CatalogName in una chiamata a SQLTables non accetta un pattern di ricerca. - Il Driver Manager non supporta l'estensibilità del tipo di dati C. Un'applicazione deve impostare questo attributo dell'ambiente prima di chiamare qualsiasi funzione che abbia un argomento SQLHENV, altrimenti la chiamata restituirà SQLSTATE HY010 (errore di sequenza funzione). Dipende dal conducente se esistano comportamenti aggiuntivi per questi segnali ambientali. - Per ulteriori informazioni, vedi Dichiarazione della versione ODBC dell'applicazione e dei cambiamenti comportamentali. |
| SQL_ATTR_OUTPUT_NTS (ODBC 3.0) | Un intero a 32 bit che determina come il driver restituisce i dati della stringa. Se SQL_TRUE, il driver restituisce i dati della stringa terminati in null. Se SQL_FALSE, il driver non restituisce i dati della stringa terminati in null. Questo attributo è predefinito SQL_TRUE. Una chiamata a SQLSetEnvAttr per impostarlo a SQL_TRUE restituisce SQL_SUCCESS. Una chiamata a SQLSetEnvAttr per impostarlo su SQL_FALSE restituisce SQL_ERROR e SQLSTATE HYC00 (Funzionalità opzionale non implementata). |
Funzioni correlate
| Per informazioni su | Vedi |
|---|---|
| Allocazione di un manico | Funzione SQLAllocHandle |
| Restituire l'impostazione di un attributo ambiente | Funzione SQLGetEnvAttr |