SQLSetStmtAttr

Il driver ODBC di SQL Server Native Client non supporta il modello del cursore misto (keyset/dinamico). I tentativi di impostare la dimensione del keyset utilizzando SQL_ATTR_KEYSET_SIZE non riescono se il set di valori non è uguale a 0.

L'applicazione imposta SQL_ATTR_ROW_ARRAY_SIZE su tutte le istruzioni per dichiarare il numero di righe restituito su una chiamata di funzione SQLFetch o SQLFetchScroll. Nelle istruzioni che indicano un cursore del server il driver utilizza SQL_ATTR_ROW_ARRAY_SIZE per determinare la dimensione del blocco di righe che il server genera per soddisfare una richiesta di recupero dal cursore. Nelle dimensioni del blocco di un cursore dinamico, l'ordinamento e l'appartenenza delle righe sono fissi se il livello di isolamento della transazione è sufficiente per assicurare letture ripetibili delle transazioni di cui è stato eseguito il commit. Il cursore è completamente dinamico al di fuori del blocco indicato da questo valore. Le dimensioni del blocco del cursore del server sono completamente dinamiche e possono essere modificate in qualsiasi momento durante l'elaborazione del recupero.

SQLSetStmtAttr e parametri con valori di tabella

SQLSetStmtAttr può essere utilizzato per impostare SQL_SOPT_SS_PARAM_FOCUS nel descrittore di parametri dell'applicazione (APD) prima di accedere ai campi di descrizione per le colonne dei parametri con valori di tabella.

Se viene effettuato un tentativo di impostare SQL_SOPT_SS_PARAM_FOCUS sull'ordinale di un parametro che non è un parametro con valori di tabella, SQLSetStmtAttr restituisce SQL_ERROR e viene creato un record di diagnostica con SQLSTATE = HY024 e il messaggio "Valore di attributo non valido". SQL_SOPT_SS_PARAM_FOCUS non viene modificato al momento della restituzione di SQL_ERROR.

L'impostazione di SQL_SOPT_SS_PARAM_FOCUS su 0 ripristina l'accesso ai record del descrittore per i parametri.

SQLSetStmtAttr può essere utilizzato anche per impostare SQL_SOPT_SS_NAME_SCOPE. Per ulteriori informazioni, vedere la sezione SQL_SOPT_SS_NAME_SCOPE più avanti in questo argomento.

Per ulteriori informazioni, vedere Metadati del parametro con valori di tabella per le istruzioni preparate.

Per ulteriori informazioni sui parametri con valori di tabella, vedere Parametri con valori di tabella (ODBC).

Supporto di SQLSetStmtAttr per colonne di tipo sparse

SQLSetStmtAttr può essere utilizzato per impostare SQL_SOPT_SS_NAME_SCOPE. Per ulteriori informazioni, vedere la sezione SQL_SOPT_SS_NAME_SCOPE più avanti in questo argomento. Per ulteriori informazioni sulle colonne di tipo sparse, vedere Supporto per colonne di tipo sparse (ODBC).

Attributi di istruzione

Il driver ODBC di SQL Server Native Client supporta anche gli attributi di istruzione seguenti specifici del driver.

SQL_SOPT_SS_CURSOR_OPTIONS

L'attributo SQL_SOPT_SS_CURSOR specifica se il driver utilizzerà opzioni delle prestazioni specifiche del driver sui cursori. SQLGetData non è consentito quando si impostano queste opzioni. L'impostazione predefinita è SQL_CO_OFF. Queste opzioni sono valide solo in caso di connessione a un'istanza di SQL Server versione 7.0 o successiva. Il valore ValuePtr è di tipo SQLLEN.

Valore ValuePtr

Descrizione

SQL_CO_OFF

Predefinito. Disabilita i cursori fast forward-only, di sola lettura e di recupero automatico, abilita SQLGetData sui cursori forward-only, di sola lettura. Quando SQL_SOPT_SS_CURSOR_OPTIONS è impostato su SQL_CO_OFF, il tipo di cursore non cambia. Ciò significa che il cursore fast forward-only resterà tale. Per modificare il tipo di cursore, l'applicazione deve impostare ora un tipo di cursore diverso utilizzando SQLSetStmtAttr/SQL_ATTR_CURSOR_TYPE.

SQL_CO_FFO

Abilita i cursori fast forward-only, di sola lettura e di recupero automatico, disabilita SQLGetData sui cursori forward-only, di sola lettura.

SQL_CO_AF

Abilita l'opzione per il recupero automatico su qualsiasi tipo di cursore. Quando questa opzione è impostata per un handle di istruzione, SQLExecute o SQLExecDirect genererà un'istruzione SQLFetchScroll (SQL_FIRST) implicita. Il cursore è aperto e il primo batch di righe viene restituito in un solo round trip al server.

SQL_CO_FFO_AF

Abilita i cursori fast forward-only con l'opzione di recupero automatico. Produce gli stessi risultati della specifica contemporanea di SQL_CO_AF e SQL_CO_FFO.

Quando queste opzioni sono impostate, il server chiude automaticamente il cursore quando rileva che l'ultima riga è stata recuperata. L'applicazione deve ancora chiamare SQLFreeStmt (SQL_CLOSE) o SQLCloseCursor, ma il driver non deve inviare la notifica di chiusura al server.

Se l'elenco di selezione contiene una colonna di tipo text, ntext o image, il cursore fast forward-only viene convertito in un cursore dinamico e SQLGetData è consentito.

SQL_SOPT_SS_DEFER_PREPARE

L'attributo SQL_SOPT_SS_DEFER_PREPARE determina se l'istruzione viene preparata immediatamente o posticipata fino all'esecuzione di SQLExecute, SQLDescribeCol o SQLDescribeParam. In SQL Server 7.0 e versioni precedenti questa proprietà viene ignorata (nessuna preparazione posticipata). Il valore ValuePtr è di tipo SQLLEN.

Valore ValuePtr

Descrizione

SQL_DP_ON

Predefinito. Dopo avere chiamato SQLPrepare, la preparazione dell'istruzione viene posticipata fino alla chiamata di SQLExecute o fino all'esecuzione dell'operazione della metaproprietà (SQLDescribeCol o SQLDescribeParam).

SQL_DP_OFF

L'istruzione viene preparata all'esecuzione di SQLPrepare.

SQL_SOPT_SS_REGIONALIZE

L'attributo SQL_SOPT_SS_REGIONALIZE viene utilizzato per determinare la conversione dei dati a livello di istruzione. L'attributo fa sì che il driver rispetti l'impostazione locale del client durante la conversione dei valori di data, ora e valuta nelle stringhe di caratteri. La conversione viene effettuata dai tipi di dati nativi di SQL Server solo in stringhe di caratteri.

Il valore ValuePtr è di tipo SQLLEN.

Valore ValuePtr

Descrizione

SQL_RE_OFF

Predefinito. Il driver non converte i dati di tipo data, ora e valuta in stringhe di caratteri mediante l'impostazione locale del client.

SQL_RE_ON

Il driver utilizza l'impostazione locale del client durante la conversione dei dati di tipo data, ora e valuta in stringhe di caratteri.

Ai dati di tipo valuta, numerico, data e ora vengono applicate le impostazioni di conversione internazionali. L'impostazione di conversione è applicabile solo alle conversioni di output quando i valori di valuta, data, ora o numerici vengono convertiti in stringhe di caratteri.

Nota

Quando l'opzione di istruzione SQL_SOPT_SS_REGIONALIZE è impostata, il driver utilizza le impostazioni locali del Registro di sistema per l'utente corrente. Il driver non rispetta le impostazioni locali correnti del thread, qualora siano state impostate dall'applicazione, chiamando ad esempio SetThreadLocale.

La modifica del comportamento internazionale di un'origine dati può generare un errore nell'applicazione. Un'applicazione che analizza le stringhe relative alla data e ne prevede la visualizzazione in base a quanto definito da ODBC, potrebbe essere influenzata negativamente dalla modifica di questo valore.

SQL_SOPT_SS_TEXTPTR_LOGGING

L'attributo SQL_SOPT_SS_TEXTPTR_LOGGING attiva o disattiva la registrazione di operazioni su colonne contenenti dati di tipo text o image. Il comportamento predefinito consiste nel registrare queste operazioni (SQL_TL_ON). Il valore ValuePtr è di tipo SQLLEN.

Valore ValuePtr

Descrizione

SQL_TL_OFF

Disabilita la registrazione di operazioni eseguite su dati di tipo text e image.

SQL_TL_ON

Predefinito. Abilita la registrazione di operazioni eseguite su dati di tipo testo e immagini.

SQL_SOPT_SS_HIDDEN_COLUMNS

L'attributo SQL_SOPT_SS_HIDDEN_COLUMNS espone nel set di risultati le colonne nascoste in un'istruzione SELECT FOR BROWSE di SQL Server. Per impostazione predefinita, il driver non espone queste colonne. Il valore ValuePtr è di tipo SQLLEN.

Valore ValuePtr

Descrizione

SQL_HC_OFF

Predefinito. Le colonne FOR BROWSE sono nascoste dal set di risultati.

SQL_HC_ON

Espone colonne FOR BROWSE.

SQL_SOPT_SS_QUERYNOTIFICATION_MSGTEXT

L'attributo SQL_SOPT_SS_QUERYNOTIFICATION_MSGTEXT restituisce il testo del messaggio per la richiesta di notifica di query.

SQL_SOPT_SS_QUERYNOTIFICATION_OPTIONS

L'attributo SQL_SOPT_SS_QUERYNOTIFICATION_OPTIONS specifica le opzioni utilizzate per la richiesta di notifica di query. Tali opzioni vengono specificate in una stringa con la sintassi name=value come indicato di seguito. L'applicazione è responsabile della creazione del servizio e della lettura delle notifiche all'esterno della coda.

La sintassi delle opzioni delle notifiche di query è la seguente:

service=<service-name>[;(local database=<database>|broker instance=<broker instance>)]

Ad esempio:

service=mySSBService;local database=mydb

SQL_SOPT_SS_QUERYNOTIFICATION_TIMEOUT

L'attributo SQL_SOPT_SS_QUERYNOTIFICATION_TIMEOUT specifica per quanti secondi la notifica di query deve rimanere attiva. Il valore predefinito è 432000 secondi (5 giorni). Il valore ValuePtr è di tipo SQLLEN.

SQL_SOPT_SS_PARAM_FOCUS

L'attributo SQL_SOPT_SS_PARAM_FOCUS specifica lo stato attivo per le chiamate SQLBindParameter, SQLGetDescField, SQLSetDescField, SQLGetDescRec e SQLSetDescRec successive.

Il tipo per SQL_SOPT_SS_PARAM_FOCUS è SQLULEN.

L'impostazione predefinita è 0 e indica che queste chiamate riguardano i parametri che corrispondono a indicatori di parametro nell'istruzione SQL. Se l'impostazione corrisponde al numero di un parametro con valori di tabella, queste chiamate riguardano le colonne del parametro con valori di tabella. Se l'impostazione corrisponde a un valore diverso dal numero un parametro con valori di tabella, queste chiamate restituiscono l'errore IM020: "Lo stato attivo del parametro non fa riferimento a un parametro con valori di tabella".

SQL_SOPT_SS_NAME_SCOPE

L'attributo SQL_SOPT_SS_NAME_SCOPE specifica l'ambito del nome per le chiamate di funzione di catalogo successive. Il set di risultati restituito da SQLColumns dipende dall'impostazione di SQL_SOPT_SS_NAME_SCOPE.

Il tipo per SQL_SOPT_SS_NAME_SCOPE è SQLULEN.

Valore ValuePtr

Descrizione

SQL_SS_NAME_SCOPE_TABLE

Predefinito.

In caso di utilizzo di parametri con valori di tabella, indica che è necessario che vengano restituiti i metadati per le tabelle effettive.

In caso di utilizzo della caratteristica delle colonne di tipo sparse, SQLColumns restituirà solo le colonne che non sono membri di column_set di tipo sparse.

SQL_SS_NAME_SCOPE_TABLE_TYPE

Indica che l'applicazione richiede metadati per un tipo di tabella, anziché una tabella effettiva. Le funzioni di catalogo devono restituire metadati per i tipi di tabella. L'applicazione passa quindi TYPE_NAME del parametro con valori di tabella come parametro TableName.

SQL_SS_NAME_SCOPE_EXTENDED

In caso di utilizzo della caratteristica delle colonne di tipo sparse, SQLColumns restituisce tutte le colonne, indipendentemente dall'appartenenza di column_set.

SQL_SS_NAME_SCOPE_SPARSE_COLUMN_SET

In caso di utilizzo della caratteristica delle colonne di tipo sparse, SQLColumns restituisce solo le colonne che non sono membri del column_set di tipo sparse.

SQL_SS_NAME_SCOPE_DEFAULT

Equivale a SQL_SS_NAME_SCOPE_TABLE.

SS_TYPE_CATALOG_NAME e SS_TYPE_SCHEMA_NAME vengono utilizzati con i parametri CatalogName e SchemaName, rispettivamente, per identificare il catalogo e lo schema per il parametro con valori di tabella. Quando un'applicazione ha completato il recupero dei metadati per i parametri con valori di tabella, deve impostare nuovamente SQL_SOPT_SS_NAME_SCOPE sul valore predefinito di SQL_SS_NAME_SCOPE_TABLE.

Quando SQL_SOPT_SS_NAME_SCOPE è impostato su SQL_SS_NAME_SCOPE_TABLE, le query ai server collegati non riescono. Le chiamate a SQLColumns o SQLPrimaryKeys con un catalogo che contiene un componente server non riescono.

Se si tenta di impostare SQL_SOPT_SS_NAME_SCOPE su un valore non valido, viene restituito SQL_ERROR e un record di diagnostica viene generato con SQLSTATE HY024 e il messaggio "Valore attributo non valido".

Se una funzione di catalogo diversa da SQLTables, SQLColumnso SQLPrimaryKeys viene chiamata quando SQL_SOPT_SS_NAME_SCOPE dispone di un valore diverso da SQL_SS_NAME_SCOPE_TABLE, viene restituito SQL_ERROR. Viene generato un record di diagnostica con SQLSTATE HY010 e il messaggio "Errore nella sequenza della funzione (SQL_SOPT_SS_NAME_SCOPE non è impostato su SQL_SS_NAME_SCOPE_TABLE)".