Uso delle matrici di parametri

Per usare matrici di parametri, l'applicazione chiama SQLSetStmtAttr con un argomento Attribute di SQL_ATTR_PARAMSET_SIZE per specificare il numero di set di parametri. Chiama SQLSetStmtAttr con un argomento Attribute di SQL_ATTR_PARAMS_PROCESSED_PTR per specificare l'indirizzo di una variabile in cui il driver può restituire il numero di set di parametri elaborati, inclusi i set di errori. Chiama SQLSetStmtAttr con un argomento Attribute di SQL_ATTR_PARAM_STATUS_PTR in modo che punti a una matrice in cui restituire informazioni sullo stato per ogni riga di valori di parametro. Il driver archivia questi indirizzi nella struttura che gestisce per l'istruzione.

Nota

In ODBC 2.x, SQLParamOptions è stato chiamato per specificare più valori per un parametro. In ODBC 3.x, la chiamata a SQLParamOptions è stata sostituita dalle chiamate a SQLSetStmtAttr per impostare gli attributi SQL_ATTR_PARAMSET_SIZE e SQL_ATTR_PARAMS_PROCESSED_ARRAY.

Prima di eseguire l'istruzione, l'applicazione imposta il valore di ogni elemento di ogni matrice associata. Quando l'istruzione viene eseguita, il driver usa le informazioni archiviate per recuperare i valori dei parametri e inviarli all'origine dati; se possibile, il driver deve inviare questi valori come matrici. Anche se l'uso di matrici di parametri è meglio implementato eseguendo l'istruzione SQL con tutti i parametri nella matrice con una singola chiamata all'origine dati, attualmente questa funzionalità non è ampiamente disponibile nei DBMS. Tuttavia, i driver possono simularla eseguendo più volte un'istruzione SQL, ognuna con un singolo set di parametri.

Prima che un'applicazione usi matrici di parametri, è necessario assicurarsi che siano supportate dai driver usati dall'applicazione. A questo scopo è possibile procedere in due modi:

• Usare solo driver noti per supportare matrici di parametri. L'applicazione può impostare come hardcoded i nomi di questi driver, oppure è possibile invitare l'utente a usare solo questi driver. Le applicazioni personalizzate e le applicazioni verticali usano in genere un set limitato di driver.

• Verificare il supporto di matrici di parametri in fase di esecuzione. Un driver supporta matrici di parametri se è possibile impostare l'attributo dell'istruzione SQL_ATTR_PARAMSET_SIZE su un valore maggiore di 1. Le applicazioni generiche e le applicazioni verticali in genere controllano il supporto di matrici di parametri in fase di esecuzione.

La disponibilità dei conteggi delle righe e dei set di risultati nell'esecuzione parametrizzata può essere determinata chiamando SQLGetInfo con le opzioni SQL_PARAM_ARRAY_ROW_COUNTS e SQL_PARAM_ARRAY_SELECTS. Per le istruzioni INSERT, UPDATE e DELETE, l'opzione SQL_PARAM_ARRAY_ROW_COUNTS indica se i conteggi delle singole righe (uno per ogni set di parametri) sono disponibili (SQL_PARC_BATCH) o se per i conteggi delle righe viene eseguito il rollup in uno (SQL_PARC_NO_BATCH). Perle istruzioni SELECT, l'opzione SQL_PARAM_ARRAY_SELECTS indica se un set di risultati è disponibile per ogni set di parametri (SQL_PAS_BATCH) o se è disponibile un solo set di risultati (SQL_PAS_NO_BATCH). Se il driver non consente l'esecuzione di istruzioni di generazione di set di risultati con una matrice di parametri, SQL_PARAM_ARRAY_SELECTS restituisce SQL_PAS_NO_SELECT. Il fatto se sia possibile usare matrici di parametri con altri tipi di istruzioni o meno dipende dall’origine dati, soprattutto perché l'uso di parametri in queste istruzioni sarebbe specifico dell'origine dati e non seguirebbe la grammatica SQL ODBC.

La matrice a cui punta l'attributo di istruzione SQL_ATTR_PARAM_OPERATION_PTR può essere utilizzata per ignorare le righe di parametri. Se un elemento della matrice è impostato su SQL_PARAM_IGNORE, il set di parametri corrispondenti a tale elemento viene escluso dalla chiamata SQLExecute o SQLExecDirect. La matrice a cui punta l'attributo SQL_ATTR_PARAM_OPERATION_PTR viene allocata e compilata dall'applicazione e letta dal driver. Se le righe recuperate vengono usate come parametri di input, i valori della matrice di stato della riga possono essere usati nella matrice di operazioni del parametro.

Errore di elaborazione

Se si verifica un errore durante l'esecuzione dell'istruzione, la funzione di esecuzione restituisce un errore e imposta la variabile numero di riga sul numero della riga contenente l'errore. Il fatto che tutte le righe ad eccezione del set di errori vengano eseguite o meno, o se tutte le righe prima (ma non dopo) del set di errori vengano eseguite dipende dall’origine dati. Poiché elabora set di parametri, il driver imposta il buffer specificato dall'attributo dell'istruzione SQL_ATTR_PARAMS_PROCESSED_PTR sul numero della riga attualmente in fase di elaborazione. Se vengono eseguiti tutti i set ad eccezione dei set di errori, il driver imposta il buffer su SQL_ATTR_PARAMSET_SIZE dopo l'elaborazione di tutte le righe.

Se è stato impostato l'attributo dell'istruzione SQL_ATTR_PARAM_STATUS_PTR, SQLExecute o SQLExecDirect restituiscono la matrice di stato del parametro, che fornisce lo stato di ogni set di parametri. La matrice di stato del parametro viene allocata dall'applicazione e compilata dal driver. Gli elementi indicano se l'istruzione SQL è stata eseguita correttamente per la riga di parametri o se si è verificato un errore durante l'elaborazione del set di parametri. Se si è verificato un errore, il driver imposta il valore corrispondente nella matrice di stato del parametro su SQL_PARAM_ERROR e restituisce SQL_SUCCESS_WITH_INFO. L'applicazione può controllare la matrice di stato per determinare quali righe sono state elaborate. Usando il numero di riga, l'applicazione spesso può correggere l'errore e riprendere l'elaborazione.

Il modo in cui viene usata la matrice di stato dei parametri è determinato dalle opzioni SQL_PARAM_ARRAY_ROW_COUNTS e SQL_PARAM_ARRAY_SELECTS restituite da una chiamata a SQLGetInfo. Per le istruzioni INSERT, UPDATE e DELETE, la matrice di stato del parametro viene compilata con informazioni sullo stato se SQL_PARC_BATCH viene restituito per SQL_PARAM_ARRAY_ROW_COUNTS, ma non se viene restituito SQL_PARC_NO_BATCH. Per le istruzioni SELECT, la matrice di stato del parametro viene compilata se SQL_PAS_BATCH viene restituito per SQL_PARAM_ARRAY_SELECT, ma non se vengono restituiti SQL_PAS_NO_BATCH o SQL_PAS_NO_SELECT.

Parametri data-at-execution

Se uno dei valori nella matrice di lunghezza/indicatore è SQL_DATA_AT_EXEC o il risultato della macro SQL_LEN_DATA_AT_EXEC (lunghezza), i dati per tali valori vengono inviati con SQLPutData nel modo consueto. Gli aspetti seguenti di questo processo meritano un commento speciale perché non sono immediatamente evidenti:

• Quando il driver restituisce SQL_NEED_DATA, deve impostare l'indirizzo della variabile numero di riga sulla riga per cui sono necessari i dati. Come nel caso a valore singolo, l'applicazione non può fare ipotesi sull'ordine in cui il driver richiederà i valori dei parametri all'interno di un singolo set di parametri. Se si verifica un errore nell'esecuzione di un parametro data-at-execution, il buffer specificato dall'attributo dell'istruzione SQL_ATTR_PARAMS_PROCESSED_PTR viene impostato sul numero della riga in cui si è verificato l'errore, lo stato della riga nella matrice di stato della riga specificata dall'attributo dell'istruzione SQL_ATTR_PARAM_STATUS_PTR viene impostato su SQL_PARAM_ERROR e la chiamata a SQLExecute, SQLExecDirect, SQLParamData o SQLPutData restituisce SQL_ERROR. Il contenuto di questo buffer non è definito se SQLExecute, SQLExecDirect o SQLParamData restituiscono SQL_STILL_EXECUTING.

• Poiché il driver non interpreta il valore nell'argomento ParameterValuePtr di SQLBindParameter per i parametri data-at-execution, se l'applicazione fornisce un puntatore a una matrice, SQLParamData non estrae e restituisce un elemento di questa matrice all'applicazione. Restituisce invece il valore scalare fornito dall'applicazione. Ciò significa che il valore restituito da SQLParamData non è sufficiente per specificare il parametro per il quale l'applicazione deve inviare dati. L'applicazione deve considerare anche il numero di riga corrente.

  Quando solo alcuni degli elementi di una matrice di parametri sono parametri data-at-execution, l'applicazione deve passare l'indirizzo di una matrice in ParameterValuePtr che contiene elementi per tutti i parametri. Questa matrice viene interpretata normalmente per i parametri che non sono parametri data-at-execution. Per i parametri data-at-execution, il valore fornito da SQLParamData all'applicazione, che normalmente può essere usato per identificare i dati richiesti dal driver in questa occasione, è sempre l'indirizzo della matrice.