Invio di dati lunghi

I DBMS definiscono dati lunghi come dati di tipo carattere o binari su una determinata dimensione, ad esempio 254 caratteri. Potrebbe non essere possibile archiviare un intero elemento di dati lunghi in memoria, ad esempio quando l'elemento rappresenta un documento di testo lungo o una bitmap. Poiché tali dati non possono essere archiviati in un singolo buffer, l'origine dati li invia al driver in parti con SQLPutData quando viene eseguita l'istruzione. I parametri per i quali i dati vengono inviati in fase di esecuzione sono noti come parametri 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.

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

1. Passa un valore a 32 bit che identifica il parametro nell'argomento ParameterValuePtr in SQLBindParameter anziché passare l'indirizzo di un buffer. Questo valore non viene analizzato dal driver. Verrà restituito all'applicazione in un secondo momento, quindi dovrebbe significare qualcosa per l'applicazione. Ad esempio, potrebbe trattarsi del numero del parametro o dell'handle di un file contenente dati.

2. Passa l'indirizzo di un buffer di lunghezza/indicatore nell'argomento StrLen_or_IndPtr di SQLBindParameter.

3. Archivia SQL_DATA_AT_EXEC o il risultato della macro SQL_LEN_DATA_AT_EXEC(lunghezza) nel buffer di lunghezza/indicatore. Entrambi questi valori indicano al driver che i dati per il parametro verranno inviati con SQLPutData. SQL_LEN_DATA_AT_EXEC(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 da poter preallocare 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.

4. Chiama SQLExecute o SQLExecDirect. Il driver rileva che un buffer di lunghezza/indicatore contiene il valore SQL_DATA_AT_EXEC o il risultato della macro SQL_LEN_DATA_AT_EXEC(lunghezza) e restituisce SQL_NEED_DATA come valore restituito della funzione.

5. 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 che identifica il parametro data-at-execution. Se è presente più di un parametro data-at-execution, l'applicazione deve usare questo valore per determinare il parametro per cui inviare dati; Il driver non è necessario per richiedere dati per i parametri di data-at-execution in un ordine specifico.

6. Chiama SQLPutData per inviare i dati dei parametri al driver. Se i dati dei parametri non rientrano in un singolo buffer, come spesso accade 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.

7. Chiama di nuovo SQLParamData per indicare che sono stati inviati tutti i dati per il parametro . Se sono presenti parametri di data-at-execution per i quali i dati non sono stati inviati, il driver restituisce SQL_NEED_DATA e il valore che identifica il parametro successivo; l'applicazione torna al passaggio 6. Se i dati sono stati inviati per tutti i parametri data-at-execution, l'istruzione viene eseguita. SQLParamData restituisce SQL_SUCCESS o SQL_SUCCESS_WITH_INFO e può restituire qualsiasi valore restituito o diagnostica che SQLExecute o SQLExecDirect possa restituire.

Dopo SQLExecute o SQLExecDirect restituisce SQL_NEED_DATA e prima che i dati siano stati inviati completamente per l'ultimo parametro 'data-at-execution', l'istruzione si trova in uno stato *Need Data*. Mentre un'istruzione si trova in uno stato Need Data, 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.

Per un esempio di invio di dati in fase di esecuzione, vedere la descrizione della funzione SQLPutData .