Invio di dati Long

I DBMS definiscono come dati Long qualsiasi carattere o dato binario che supera una determinata dimensione, per esempio 254 caratteri. Potrebbe non essere possibile archiviare un intero oggetto di dati Long in memoria, ad esempio quando l’oggetto rappresenta un documento di testo lungo o una bitmap. Poiché tali dati non possono essere archiviati in un buffer singolo, 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 data-at-execution.

Nota

Un'applicazione può 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 essere archiviati in un singolo buffer, in genere non vi è motivo di usare SQLPutData. È molto più semplice associare il buffer e consentire al driver di riprendere i dati dal buffer.

Per inviare dati in fase di esecuzione, l'applicazione esegue le operazioni 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. In un secondo momento verrà restituito all'applicazione, quindi dovrebbe avere un significato 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 i 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 Long a un'origine dati che deve conoscere il numero di byte dei dati long che verranno inviati in modo tale 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ò ignorarla.

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 Long, 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 per quale parametro inviare dati; il driver non deve richiedere dati per i parametri 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 accade spesso con dati Long, 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 dati stringa con 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 ha inviato tutti i dati per il parametro. Se vi sono parametri data-at-execution per cui 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 possano restituire.

Dopo che SQLExecute o SQLExecDirect restituiscono SQL_NEED_DATA e prima che i dati siano stati inviati completamente per l'ultimo parametro data-at-execution, l'istruzione è in stato Need Data. Quando un’istruzione è in 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 riporta allo stato precedente. Per altre informazioni, vedere Appendice B: Tabelle di transizione di stato ODBC.

Per un esempio di invio di dati nei tempi di esecuzione, vedere la descrizione della funzione SQLPutData.