Dati lunghi e SQLSetPos e SQLBulkOperations

Come accade con i parametri nelle istruzioni SQL, è possibile inviare dati lunghi quando si aggiornano righe con SQLBulkOperations o SQLSetPos o quando si inseriscono righe con SQLBulkOperations. I dati vengono inviati in parti, con più chiamate a SQLPutData. Le colonne per le quali i dati vengono inviati in fase di esecuzione sono note come colonne di dati in fase di esecuzione.

Annotazioni

Un'applicazione può effettivamente inviare qualsiasi tipo di dati in fase di esecuzione con SQLPutData, anche se solo i dati di tipo carattere e binario possono essere inviati in parti. Tuttavia, se i dati sono sufficientemente piccoli da adattarsi a un singolo buffer, in genere non esiste alcun motivo per usare SQLPutData. È molto più semplice associare il buffer e consentire al driver di recuperare i dati dal buffer.

Poiché le colonne di dati lunghe in genere non sono associate, l'applicazione deve associare la colonna prima di chiamare SQLBulkOperations o SQLSetPos e annullare l'associazione dopo aver chiamato SQLBulkOperations o SQLSetPos. La colonna deve essere associata perché SQLBulkOperations o SQLSetPos opera solo su colonne associate e deve essere non associato in modo che SQLGetData possa essere usato per recuperare i dati dalla colonna.

Per inviare dati in fase di esecuzione, l'applicazione esegue le operazioni seguenti:

1. Inserisce un valore a 32 bit nel buffer del set di righe anziché un valore di dati. Questo valore verrà restituito all'applicazione in un secondo momento, quindi l'applicazione deve impostarla su un valore significativo, ad esempio il numero della colonna o l'handle di un file contenente dati.

2. Imposta il valore nel buffer di lunghezza/indicatore sul risultato della macro SQL_LEN_DATA_AT_EXEC(lunghezza). Questo valore indica al driver che i dati per il parametro verranno inviati con SQLPutData. Il valore di lunghezza viene usato quando si inviano dati lunghi a un'origine dati che deve conoscere il numero di byte di dati lunghi che verranno inviati in modo che possa preallocare lo spazio. Per determinare se un'origine dati richiede questo valore, l'applicazione chiama SQLGetInfo con l'opzione SQL_NEED_LONG_DATA_LEN. Tutti i driver devono supportare questa macro; se l'origine dati non richiede la lunghezza dei byte, il driver può ignorarlo.

3. Chiama SQLBulkOperations o SQLSetPos. Il driver individua che un buffer di lunghezza/indicatore contiene il risultato della macro SQL_LEN_DATA_AT_EXEC(lunghezza) e restituisce SQL_NEED_DATA come valore restituito della funzione.

4. Chiama SQLParamData in risposta al valore restituito SQL_NEED_DATA. Se è necessario inviare dati lunghi, SQLParamData restituisce SQL_NEED_DATA. Nel buffer a cui punta l'argomento ValuePtrPtr , il driver restituisce il valore univoco inserito dall'applicazione nel buffer del set di righe. Se è presente più di una colonna data-at-execution, l'applicazione usa questo valore per determinare la colonna per cui inviare i dati; il driver non è tenuto a richiedere dati per le colonne data-at-execution in alcun ordine particolare.

5. Chiama SQLPutData per inviare i dati della colonna al driver. Se i dati della colonna non rientrano in un singolo buffer, come accade spesso con dati lunghi, l'applicazione chiama ripetutamente SQLPutData per inviare i dati in parti; spetta al driver e all'origine dati riassemblare i dati. Se l'applicazione passa una stringa a terminazione null, il driver o l'origine dati deve rimuovere il carattere di terminazione null come parte del processo di riassemblaggio.

6. Chiama di nuovo SQLParamData per indicare che sono stati inviati tutti i dati per la colonna. Se sono presenti colonne di dati in fase di esecuzione per cui i dati non sono stati inviati, il driver restituisce SQL_NEED_DATA e il valore univoco per la colonna data-at-execution successiva; l'applicazione torna al passaggio 5. Se i dati sono stati inviati per tutte le colonne "data-at-execution," i dati della riga vengono trasmessi all'origine dei dati. SQLParamData restituisce quindi SQL_SUCCESS o SQL_SUCCESS_WITH_INFO e può restituire qualsiasi SQLSTATE che SQLBulkOperations o SQLSetPos possa restituire.

Dopo che SQLBulkOperations o SQLSetPos restituisce SQL_NEED_DATA e prima che i dati siano stati inviati completamente per l'ultima colonna data-at-execution, l'istruzione si trova in uno stato di necessità di dati. In questo stato, l'applicazione può chiamare solo SQLPutData, SQLParamData, SQLCancel, SQLGetDiagField o SQLGetDiagRec; tutte le altre funzioni restituiscono SQLSTATE HY010 (errore della sequenza di funzioni). La chiamata a SQLCancel annulla l'esecuzione dell'istruzione e la restituisce allo stato precedente. Per altre informazioni, vedere Appendice B: Tabelle di transizione dello stato ODBC.