Uso di valori di lunghezza e indicatore

  • Articolo

Il buffer di lunghezza/indicatore viene usato per passare la lunghezza dei byte dei dati nel buffer dei dati o un indicatore speciale, ad esempio SQL_NULL_DATA, che indica che i dati sono NULL. A seconda della funzione per cui viene usato, il buffer di lunghezza/indicatore viene definito SQLINTEGER o SQLSMALLINT. Pertanto, è necessario un singolo argomento per descriverlo. Se il buffer dei dati è un buffer di input non differito, questo argomento contiene la lunghezza dei byte dei dati stessi o un valore indicatore. Viene spesso denominato StrLen_or_Ind o indicato con un nome simile. Ad esempio, il codice seguente chiama SQLPutData per passare un buffer pieno di dati. La lunghezza dei byte (ValueLen) viene passata direttamente perché il buffer dei dati (ValuePtr) è un buffer di input.

SQLCHAR      ValuePtr[50];  
SQLINTEGER   ValueLen;  
  
// Call local function to place data in ValuePtr. In ValueLen, return the  
// number of bytes of data placed in ValuePtr. If there is not enough  
// data, this will be less than 50.  
FillBuffer(ValuePtr, sizeof(ValuePtr), &ValueLen);  
  
// Call SQLPutData to send the data to the driver.  
SQLPutData(hstmt, ValuePtr, ValueLen);

Se il buffer dei dati è un buffer di input differito, un buffer di output non differito o un buffer di output, l'argomento contiene l'indirizzo del buffer di lunghezza/indicatore. Viene spesso denominato StrLen_or_IndPtr o indicato con un nome simile. Il codice seguente, ad esempio, chiama SQLGetData per recuperare un buffer pieno di dati. La lunghezza dei byte viene restituita all'applicazione nel buffer di lunghezza/indicatore (ValueLenOrInd), il cui indirizzo viene passato a SQLGetData perché il buffer di dati corrispondente (ValuePtr) è un buffer di output non differito.

SQLCHAR      ValuePtr[50];  
SQLINTEGER   ValueLenOrInd;  
SQLGetData(hstmt, 1, SQL_C_CHAR, ValuePtr, sizeof(ValuePtr), &ValueLenOrInd);

A meno che non sia vietato esplicitamente, un argomento di buffer di lunghezza/indicatore può essere 0 (se l'input non è differito) o un puntatore Null (in caso di input differito o di output). Per i buffer di input, il driver ignora la lunghezza dei byte dei dati. Viene restituito un errore durante il passaggio dei dati a lunghezza variabile, ma ciò è comune quando si passano dati a lunghezza fissa non Null, perché non è necessaria né una lunghezza né un valore indicatore. Per i buffer di output, il driver non restituisce la lunghezza dei byte dei dati o un valore indicatore. Si tratta di un errore se i dati restituiti dal driver sono NULL, ma ciò è comune durante il recupero di dati a lunghezza fissa e che non ammettono valori Null, perché non sono necessari né una lunghezza né un valore indicatore.

Come quando l'indirizzo di un buffer dei dati differito viene passato al driver, l'indirizzo di un buffer di lunghezza/indicatore differito deve rimanere valido finché il buffer non è associato.

Le lunghezze seguenti sono valide come valori di lunghezza/indicatore:

  • n, dove n> 0.

  • SQL_NTS. Una stringa inviata al driver nel buffer dei dati corrispondente ha terminazione Null; si tratta di un modo pratico per i programmatori C di passare stringhe senza dover calcolare la lunghezza dei byte. Questo valore è legale solo quando l'applicazione invia dati al driver. Quando il driver restituisce i dati all'applicazione, restituisce sempre la lunghezza effettiva dei byte dei dati.

I valori seguenti sono validi come valori di lunghezza/indicatore. SQL_NULL_DATA viene archiviato nel campo descrittore SQL_DESC_INDICATOR_PTR; tutti gli altri valori vengono archiviati nel campo descrittore SQL_DESC_OCTET_LENGTH_PTR.

  • SQL_NULL_DATA. Il dato è un valore di dati NULL e il valore nel buffer dei dati corrispondente viene ignorato. Questo valore è legale solo per i dati SQL inviati o recuperati dal driver.

  • SQL_DATA_AT_EXEC. Il buffer dei dati non contiene dati. I dati verranno invece inviati con SQLPutData quando viene eseguita l'istruzione o quando vengono chiamati SQLBulkOperations o SQLSetPos. Questo valore è legale solo per i dati SQL inviati al driver. Per altre informazioni, vedere SQLBindParameter, SQLBulkOperations e SQLSetPos.

  • Risultato della macro SQL_LEN_DATA_AT_EXEC (lunghezza). Questo valore è simile a SQL_DATA_AT_EXEC. Per ulteriori informazioni, vedere Invio di dati lunghi.

  • SQL_NO_TOTAL. Il driver non è in grado di determinare il numero di byte di dati lunghi ancora disponibili per la restituzione in un buffer di output. Questo valore è legale solo per i dati SQL recuperati dal driver.

  • SQL_DEFAULT_PARAM. Una procedura consiste nell'usare il valore predefinito di un parametro di input in una procedura anziché il valore nel buffer dei dati corrispondente.

  • SQL_COLUMN_IGNORE. SQLBulkOperations o SQLSetPos consistono nell'ignorare il valore nel buffer dei dati. Quando si aggiorna una riga di dati tramite una chiamata a SQLBulkOperations o SQLSetPos, il valore della colonna non viene modificato. Quando si inserisce una nuova riga di dati da una chiamata a SQLBulkOperations, il valore della colonna viene impostato sul valore predefinito oppure, se la colonna non ha un valore predefinito, su NULL.