Funzione SQLSetDescField
Conformità
Versione introdotta: Conformità agli standard ODBC 3.0: ISO 92
Riepilogo
SQLSetDescField imposta il valore di un singolo campo di un record descrittore.
Sintassi
SQLRETURN SQLSetDescField(
SQLHDESC DescriptorHandle,
SQLSMALLINT RecNumber,
SQLSMALLINT FieldIdentifier,
SQLPOINTER ValuePtr,
SQLINTEGER BufferLength);
Argomenti
DescriptorHandle
[Input] Handle del descrittore.
RecNumber
[Input] Indica il record descrittore contenente il campo che l'applicazione cerca di impostare. I record del descrittore sono numerati da 0, con il numero di record 0 come record del segnalibro. L'argomento RecNumber viene ignorato per i campi di intestazione.
FieldIdentifier
[Input] Indica il campo del descrittore il cui valore deve essere impostato. Per altre informazioni, vedere "FieldIdentifier Argument" nella sezione "Comments".
ValuePtr
[Input] Puntatore a un buffer contenente le informazioni sul descrittore o un valore intero. Il tipo di dati dipende dal valore di FieldIdentifier. Se ValuePtr è un valore intero, può essere considerato come 8 byte (SQLLEN), 4 byte (SQLINTEGER) o 2 byte (SQLSMALLINT), a seconda del valore dell'argomento FieldIdentifier .
BufferLength
[Input] Se FieldIdentifier è un campo definito da ODBC e ValuePtr punta a una stringa di caratteri o a un buffer binario, questo argomento deve essere la lunghezza di *ValuePtr. Per i dati stringa di caratteri, questo argomento deve contenere il numero di byte nella stringa.
Se FieldIdentifier è un campo definito da ODBC e ValuePtr è un numero intero, BufferLength viene ignorato.
Se FieldIdentifier è un campo definito dal driver, l'applicazione indica la natura del campo in Gestione driver impostando l'argomento BufferLength . BufferLength può avere i valori seguenti:
Se ValuePtr è un puntatore a una stringa di caratteri, BufferLength è la lunghezza della stringa o SQL_NTS.
Se ValuePtr è un puntatore a un buffer binario, l'applicazione inserisce il risultato della macro SQL_LEN_BINARY_ATTR(length) in BufferLength. In questo modo viene impostato un valore negativo in BufferLength.
Se ValuePtr è un puntatore a un valore diverso da una stringa di caratteri o una stringa binaria, BufferLength deve avere il valore SQL_IS_POINTER.
Se ValuePtr contiene un valore a lunghezza fissa, BufferLength è SQL_IS_INTEGER, SQL_IS_UINTEGER, SQL_IS_SMALLINT o SQL_IS_USMALLINT, se necessario.
Resi
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR o SQL_INVALID_HANDLE.
Diagnostica
Quando SQLSetDescField restituisce SQL_ERROR o SQL_SUCCESS_WITH_INFO, è possibile ottenere un valore SQLSTATE associato chiamando SQLGetDiagRec con handleTypedi SQL_HANDLE_DESC e handle di descrittoreHandle. La tabella seguente elenca i valori SQLSTATE comunemente restituiti da SQLSetDescField e ne spiega ognuno nel contesto di questa funzione. La notazione "(DM)" precede le descrizioni di SQLSTATEs restituite da Gestione driver. Il codice restituito associato a ogni valore SQLSTATE è SQL_ERROR, a meno che non sia specificato diversamente.
| SQLSTATE | Errore | Descrizione |
|---|---|---|
| 01000 | Avviso generale | Messaggio informativo specifico del driver. (La funzione restituisce SQL_SUCCESS_WITH_INFO. |
| 01S02 | Valore dell'opzione modificato | Il driver non supporta il valore specificato in *ValuePtr (se ValuePtr è un puntatore) o il valore in ValuePtr (se ValuePtr è un valore intero) o *ValuePtr non è valido a causa delle condizioni di lavoro dell'implementazione, quindi il driver ha sostituito un valore simile. (La funzione restituisce SQL_SUCCESS_WITH_INFO. |
| 07009 | Indice descrittore non valido | L'argomento FieldIdentifier era un campo record, l'argomento RecNumber era 0 e l'argomento DescriptorHandle faceva riferimento a un handle IPD. L'argomento RecNumber era minore di 0 e l'argomento DescriptorHandle faceva riferimento a un ARD o a un APD. L'argomento RecNumber è maggiore del numero massimo di colonne o parametri che l'origine dati può supportare e l'argomento DescriptorHandle fa riferimento a un APD o ARD. (DM) L'argomento FieldIdentifier è stato SQL_DESC_COUNT e l'argomento *ValuePtr era minore di 0. L'argomento RecNumber è uguale a 0 e l'argomento DescriptorHandle fa riferimento a un APD allocato in modo implicito. Questo errore non si verifica con un descrittore dell'applicazione allocato in modo esplicito, perché non è noto se un descrittore di applicazione allocato in modo esplicito è un descrittore APD o ARD fino all'ora di esecuzione. |
| 08S01 | Errore del collegamento di comunicazione | Collegamento di comunicazione tra il driver e l'origine dati a cui è stato connesso il driver non è riuscito prima del completamento dell'elaborazione della funzione. |
| 22001 | Dati stringa, troncati a destra | L'argomento FieldIdentifier è stato SQL_DESC_NAME e l'argomento BufferLength era un valore maggiore di SQL_MAX_IDENTIFIER_LEN. |
| HY000 | Errore generale: | Si è verificato un errore per il quale non è stato specificato SQLSTATE e per il quale non è stato definito alcun SQLSTATE specifico dell'implementazione. Il messaggio di errore restituito da SQLGetDiagRec nel buffer *MessageText descrive l'errore e la relativa causa. |
| HY001 | Errore di allocazione della memoria | Il driver non è riuscito ad allocare memoria necessaria per supportare l'esecuzione o il completamento della funzione. |
| HY010 | Errore della sequenza di funzioni | (DM) Il descrittoreHandle è stato associato a un StatementHandle per il quale è stata chiamata una funzione in esecuzione asincrona (non questa) ed era ancora in esecuzione quando è stata chiamata questa funzione. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations o SQLSetPos è stato chiamato per statementHandlecon cui è stato associato il descrittoreHandle e restituito SQL_NEED_DATA. Questa funzione è stata chiamata prima dell'invio dei dati per tutti i parametri o le colonne data-at-execution. (DM) È stata chiamata una funzione in esecuzione asincrona per l'handle di connessione associato a DescriptorHandle. Questa funzione asincrona era ancora in esecuzione quando è stata chiamata la funzione SQLSetDescField . (DM) SQLExecute, SQLExecDirect o SQLMoreResults è stato chiamato per uno degli handle di istruzione associati a DescriptorHandle e restituito SQL_PARAM_DATA_AVAILABLE. Questa funzione è stata chiamata prima del recupero dei dati per tutti i parametri trasmessi. |
| HY013 | Errore di gestione della memoria | Impossibile elaborare la chiamata di funzione perché non è stato possibile accedere agli oggetti di memoria sottostanti, probabilmente a causa di condizioni di memoria insufficiente. |
| HY016 | Impossibile modificare un descrittore di riga di implementazione | L'argomento DescriptorHandle è stato associato a un oggetto IRD e l'argomento FieldIdentifier non è stato SQL_DESC_ARRAY_STATUS_PTR o SQL_DESC_ROWS_PROCESSED_PTR. |
| HY021 | Informazioni sul descrittore incoerente | I campi SQL_DESC_TYPE e SQL_DESC_DATETIME_INTERVAL_CODE non formano un tipo SQL ODBC valido o un tipo SQL valido specifico del driver (per IPD) o un tipo C ODBC valido (per API o ARD). Le informazioni del descrittore controllate durante un controllo coerenza non sono coerenti. Vedere "Verifica coerenza" in SQLSetDescRec. |
| HY090 | Lunghezza della stringa o del buffer non valida | (DM) *ValuePtr è una stringa di caratteri e BufferLength è minore di zero, ma non è uguale a SQL_NTS. (DM) Il driver era un driver ODBC 2*.x*, il descrittore era un ARD, l'argomento ColumnNumber era impostato su 0 e il valore specificato per l'argomento BufferLength non era uguale a 4. |
| HY091 | Identificatore di campo del descrittore non valido | Il valore specificato per l'argomento FieldIdentifier non era un campo definito da ODBC e non era un valore definito dall'implementazione. L'argomento FieldIdentifier non è valido per l'argomento DescriptorHandle . L'argomento FieldIdentifier è un campo definito da ODBC di sola lettura. |
| HY092 | Identificatore di attributo/opzione non valido | Il valore in *ValuePtr non è valido per l'argomento FieldIdentifier . L'argomento FieldIdentifier è stato SQL_DESC_UNNAMED e ValuePtr è stato SQL_NAMED. |
| HY105 | Tipo di parametro non valido | (DM) Il valore specificato per il campo SQL_DESC_PARAMETER_TYPE non è valido. Per altre informazioni, vedere "Argomento InputOutputType " in SQLBindParameter. |
| HY117 | La connessione viene sospesa a causa dello stato sconosciuto della transazione. Sono consentite solo funzioni disconnesse e di sola lettura. | (DM) Per altre informazioni sullo stato sospeso, vedere Novità di ODBC 3.8. |
| HYT01 | Il timeout della connessione è scaduto | Periodo di timeout della connessione scaduto prima che l'origine dati rispondesse alla richiesta. Il periodo di timeout della connessione viene impostato tramite SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Il driver non supporta questa funzione | (DM) Il driver associato a DescriptorHandle non supporta la funzione. |
Commenti
Un'applicazione può chiamare SQLSetDescField per impostare qualsiasi campo descrittore uno alla volta. Una chiamata a SQLSetDescField imposta un singolo campo in un singolo descrittore. Questa funzione può essere chiamata per impostare qualsiasi campo in qualsiasi tipo di descrittore, a condizione che il campo possa essere impostato. Vedere la tabella più avanti in questa sezione.
Nota
Se una chiamata a SQLSetDescField ha esito negativo, il contenuto del record descrittore identificato dall'argomento RecNumber non è definito.
È possibile chiamare altre funzioni per impostare più campi descrittori con una singola chiamata della funzione. La funzione SQLSetDescRec imposta un'ampia gamma di campi che influiscono sul tipo di dati e sul buffer associati a una colonna o a un parametro (campi SQL_DESC_TYPE, SQL_DESC_DATETIME_INTERVAL_CODE, SQL_DESC_OCTET_LENGTH, SQL_DESC_PRECISION, SQL_DESC_SCALE, SQL_DESC_DATA_PTR, SQL_DESC_OCTET_LENGTH_PTR e SQL_DESC_INDICATOR_PTR). È possibile usare SQLBindCol o SQLBindParameter per creare una specifica completa per l'associazione di una colonna o di un parametro. Queste funzioni impostano un gruppo specifico di campi descrittore con una chiamata di funzione.
È possibile chiamare SQLSetDescField per modificare i buffer di associazione aggiungendo un offset ai puntatori di associazione (SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR o SQL_DESC_OCTET_LENGTH_PTR). In questo modo i buffer di associazione vengono modificati senza chiamare SQLBindCol o SQLBindParameter, che consente a un'applicazione di modificare SQL_DESC_DATA_PTR senza modificare altri campi, ad esempio SQL_DESC_DATA_TYPE.
Se un'applicazione chiama SQLSetDescField per impostare qualsiasi campo diverso da SQL_DESC_COUNT o i campi posticipati SQL_DESC_DATA_PTR, SQL_DESC_OCTET_LENGTH_PTR o SQL_DESC_INDICATOR_PTR, il record diventa non associato.
I campi di intestazione del descrittore vengono impostati chiamando SQLSetDescField con fieldIdentifier appropriato. Molti campi di intestazione sono anche attributi di istruzione, quindi possono essere impostati anche da una chiamata a SQLSetStmtAttr. In questo modo, le applicazioni possono impostare un campo descrittore senza prima ottenere un handle descrittore. Quando viene chiamato SQLSetDescField per impostare un campo di intestazione, l'argomento RecNumber viene ignorato.
Per impostare i campi del segnalibro viene utilizzato un valore RecNumber pari a 0.
Nota
L'attributo di istruzione SQL_ATTR_USE_BOOKMARKS deve essere sempre impostato prima di chiamare SQLSetDescField per impostare i campi dei segnalibri. Anche se questo non è obbligatorio, è fortemente consigliato.
Sequenza di campi del descrittore di impostazione
Quando si impostano i campi del descrittore chiamando SQLSetDescField, l'applicazione deve seguire una sequenza specifica:
L'applicazione deve prima impostare il campo SQL_DESC_TYPE, SQL_DESC_CONCISE_TYPE o SQL_DESC_DATETIME_INTERVAL_CODE.
Dopo aver impostato uno di questi campi, l'applicazione può impostare un attributo di un tipo di dati e i campi dell'attributo del tipo di dati vengono impostati sui valori predefiniti appropriati per il tipo di dati. L'impostazione predefinita automatica dei campi dell'attributo di tipo garantisce che il descrittore sia sempre pronto per l'uso dopo che l'applicazione ha specificato un tipo di dati. Se l'applicazione imposta in modo esplicito un attributo del tipo di dati, esegue l'override dell'attributo predefinito.
Dopo che uno dei campi elencati nel passaggio 1 è stato impostato e gli attributi del tipo di dati sono stati impostati, l'applicazione può impostare SQL_DESC_DATA_PTR. In questo modo viene richiesto un controllo di coerenza dei campi descrittore. Se l'applicazione modifica il tipo di dati o gli attributi dopo l'impostazione del campo SQL_DESC_DATA_PTR, il driver imposta SQL_DESC_DATA_PTR su un puntatore Null, disassociando il record. In questo modo l'applicazione deve completare i passaggi appropriati in sequenza, prima che il record del descrittore sia utilizzabile.
Inizializzazione dei campi di descrizione
Quando viene allocato un descrittore, i campi nel descrittore possono essere inizializzati in un valore predefinito, essere inizializzati senza un valore predefinito o non definiti per il tipo di descrittore. Le tabelle seguenti indicano l'inizializzazione di ogni campo per ogni tipo di descrittore, con "D" che indica che il campo viene inizializzato con un valore predefinito e "ND" che indica che il campo viene inizializzato senza un valore predefinito. Se viene visualizzato un numero, il valore predefinito del campo è tale numero. Le tabelle indicano anche se un campo è di lettura/scrittura (R/W) o di sola lettura (R).
I campi di un IRD hanno un valore predefinito solo dopo che l'istruzione è stata preparata o eseguita e l'IRD è stato popolato, non quando è stato allocato l'handle o il descrittore dell'istruzione. Finché l'IRD non è stato popolato, qualsiasi tentativo di ottenere l'accesso a un campo di un IRD restituirà un errore.
Alcuni campi descrittori sono definiti per uno o più tipi di descrittore (ARD e IRD e ID e IPD). Quando un campo non è definito per un tipo di descrittore, non è necessario per nessuna delle funzioni che usano tale descrittore.
I campi a cui è possibile accedere da SQLGetDescField non possono necessariamente essere impostati da SQLSetDescField. I campi che possono essere impostati da SQLSetDescField sono elencati nelle tabelle seguenti.
L'inizializzazione dei campi di intestazione è descritta nella tabella seguente.
| Nome campo intestazione | Tipo | L/S | Default |
|---|---|---|---|
| SQL_DESC_ALLOC_TYPE | SQLSMALLINT | ARD: R APD: R IRD: R IPD: R | ARD: SQL_DESC_ALLOC_AUTO per SQL_DESC_ALLOC_USER implicito o esplicito APD: SQL_DESC_ALLOC_AUTO per SQL_DESC_ALLOC_USER implicito o esplicito IRD: SQL_DESC_ALLOC_AUTO IPD: SQL_DESC_ALLOC_AUTO |
| SQL_DESC_ARRAY_SIZE | SQLULEN | ARD: R/W APD: R/W IRD: IPD inutilizzato: non usato | ARD:[1] APD:[1] IRD: IPD inutilizzato: non usato |
| SQL_DESC_ARRAY_STATUS_PTR | SQLUSMALLINT* | ARD: R/W APD: R/W IRD: R/W IPD: R/W | ARD: Null ptr APD: Null ptr IRD: Null ptr IPD: Null ptr |
| SQL_DESC_BIND_OFFSET_PTR | SQLLEN* | ARD: R/W APD: R/W IRD: IPD inutilizzato: non usato | ARD: Null ptr APD: Null ptr IRD: IPD inutilizzato: non usato |
| SQL_DESC_BIND_TYPE | SQLINTEGER | ARD: R/W APD: R/W IRD: IPD inutilizzato: non usato | ARD: SQL_BIND_BY_COLUMN APD: SQL_BIND_BY_COLUMN IRD: non usato IPD: inutilizzato |
| SQL_DESC_COUNT | SQLSMALLINT | ARD: R/W APD: R/W IRD: R IPD: R/W | ARD: 0 APD: 0 IRD: D IPD: 0 |
| SQL_DESC_ROWS_PROCESSED_PTR | SQLULEN* | ARD: APD inutilizzato: IRD inutilizzato: R/W IPD: R/W | ARD: APD inutilizzato: IRD inutilizzato: IPD ptr Null: Ptr Null ptr |
[1] Questi campi vengono definiti solo quando l'IPD viene popolato automaticamente dal driver. In caso contrario, non sono definiti. Se un'applicazione tenta di impostare questi campi, verrà restituito SQLSTATE HY091 (identificatore di campo descrittore non valido).
L'inizializzazione dei campi di record è come illustrato nella tabella seguente.
| Nome campo record | Tipo | L/S | Default |
|---|---|---|---|
| SQL_DESC_AUTO_UNIQUE_VALUE | SQLINTEGER | ARD: APD inutilizzato: IRD inutilizzato: R IPD: non usato | ARD: APD inutilizzato: IRD inutilizzato: D IPD: non usato |
| SQL_DESC_BASE_COLUMN_NAME | SQLCHAR * | ARD: APD inutilizzato: IRD inutilizzato: R IPD: non usato | ARD: APD inutilizzato: IRD inutilizzato: D IPD: non usato |
| SQL_DESC_BASE_TABLE_NAME | SQLCHAR * | ARD: APD inutilizzato: IRD inutilizzato: R IPD: non usato | ARD: APD inutilizzato: IRD inutilizzato: D IPD: non usato |
| SQL_DESC_CASE_SENSITIVE | SQLINTEGER | ARD: APD inutilizzato: IRD inutilizzato: R IPD: R | ARD: APD inutilizzato: IRD inutilizzato: D IPD: D[1] |
| SQL_DESC_CATALOG_NAME | SQLCHAR * | ARD: APD inutilizzato: IRD inutilizzato: R IPD: non usato | ARD: APD inutilizzato: IRD inutilizzato: D IPD: non usato |
| SQL_DESC_CONCISE_TYPE | SQLSMALLINT | ARD: R/W APD: R/W IRD: R IPD: R/W | ARD: SQL_C_ DEFAULT APD: SQL_C_ DEFAULT IRD: D IPD: ND |
| SQL_DESC_DATA_PTR | SQLPOINTER | ARD: R/W APD: R/W IRD: IPD inutilizzato: non usato | ARD: Null ptr APD: Null ptr IRD: Unused IPD: Unused[2] |
| SQL_DESC_DATETIME_INTERVAL_CODE | SQLSMALLINT | ARD: R/W APD: R/W IRD: R IPD: R/W | ARD: ND APD: ND IRD: D IPD: ND |
| SQL_DESC_DATETIME_INTERVAL_PRECISION | SQLINTEGER | ARD: R/W APD: R/W IRD: R IPD: R/W | ARD: ND APD: ND IRD: D IPD: ND |
| SQL_DESC_DISPLAY_SIZE | SQLLEN | ARD: APD inutilizzato: IRD inutilizzato: R IPD: non usato | ARD: APD inutilizzato: IRD inutilizzato: D IPD: non usato |
| SQL_DESC_FIXED_PREC_SCALE | SQLSMALLINT | ARD: APD inutilizzato: IRD inutilizzato: R IPD: R | ARD: APD inutilizzato: IRD inutilizzato: D IPD: D[1] |
| SQL_DESC_INDICATOR_PTR | SQLLEN * | ARD: R/W APD: R/W IRD: IPD inutilizzato: non usato | ARD: Null ptr APD: Null ptr IRD: IPD inutilizzato: non usato |
| SQL_DESC_LABEL | SQLCHAR * | ARD: APD inutilizzato: IRD inutilizzato: R IPD: non usato | ARD: APD inutilizzato: IRD inutilizzato: D IPD: non usato |
| SQL_DESC_LENGTH | SQLULEN | ARD: R/W APD: R/W IRD: R IPD: R/W | ARD: ND APD: ND IRD: D IPD: ND |
| SQL_DESC_LITERAL_PREFIX | SQLCHAR * | ARD: APD inutilizzato: IRD inutilizzato: R IPD: non usato | ARD: APD inutilizzato: IRD inutilizzato: D IPD: non usato |
| SQL_DESC_LITERAL_SUFFIX | SQLCHAR * | ARD: APD inutilizzato: IRD inutilizzato: R IPD: non usato | ARD: APD inutilizzato: IRD inutilizzato: D IPD: non usato |
| SQL_DESC_LOCAL_TYPE_NAME | SQLCHAR * | ARD: APD inutilizzato: IRD inutilizzato: R IPD: R | ARD: APD inutilizzato: IRD inutilizzato: D IPD: D[1] |
| SQL_DESC_NAME | SQLCHAR * | ARD: APD inutilizzato: IRD inutilizzato: R IPD: R/W | ARD: ND APD: ND IRD: D IPD: ND |
| SQL_DESC_NULLABLE | SQLSMALLINT | ARD: APD inutilizzato: IRD inutilizzato: R IPD: R | ARD: ND APD: ND IRD: D IPD: ND |
| SQL_DESC_NUM_PREC_RADIX | SQLINTEGER | ARD: R/W APD: R/W IRD: R IPD: R/W | ARD: ND APD: ND IRD: D IPD: ND |
| SQL_DESC_OCTET_LENGTH | SQLLEN | ARD: R/W APD: R/W IRD: R IPD: R/W | ARD: ND APD: ND IRD: D IPD: ND |
| SQL_DESC_OCTET_LENGTH_PTR | SQLLEN * | ARD: R/W APD: R/W IRD: IPD inutilizzato: non usato | ARD: Null ptr APD: Null ptr IRD: IPD inutilizzato: non usato |
| SQL_DESC_PARAMETER_TYPE | SQLSMALLINT | ARD: APD inutilizzato: IRD inutilizzato: IPD inutilizzato: R/W | ARD: APD inutilizzato: IRD inutilizzato: IPD inutilizzato: D=SQL_PARAM_INPUT |
| SQL_DESC_PRECISION | SQLSMALLINT | ARD: R/W APD: R/W IRD: R IPD: R/W | ARD: ND APD: ND IRD: D IPD: ND |
| SQL_DESC_ROWVER | SQLSMALLINT | ARD: inutilizzato APD: non usato IRD: R IPD: R |
ARD: inutilizzato APD: non usato IRD: ND IPD: ND |
| SQL_DESC_SCALE | SQLSMALLINT | ARD: R/W APD: R/W IRD: R IPD: R/W | ARD: ND APD: ND IRD: D IPD: ND |
| SQL_DESC_SCHEMA_NAME | SQLCHAR * | ARD: APD inutilizzato: IRD inutilizzato: R IPD: non usato | ARD: APD inutilizzato: IRD inutilizzato: D IPD: non usato |
| SQL_DESC_SEARCHABLE | SQLSMALLINT | ARD: APD inutilizzato: IRD inutilizzato: R IPD: non usato | ARD: APD inutilizzato: IRD inutilizzato: D IPD: non usato |
| SQL_DESC_TABLE_NAME | SQLCHAR * | ARD: APD inutilizzato: IRD inutilizzato: R IPD: non usato | ARD: APD inutilizzato: IRD inutilizzato: D IPD: non usato |
| SQL_DESC_TYPE | SQLSMALLINT | ARD: R/W APD: R/W IRD: R IPD: R/W | ARD: SQL_C_DEFAULT APD: SQL_C_DEFAULT IRD: D IPD: ND |
| SQL_DESC_TYPE_NAME | SQLCHAR * | ARD: APD inutilizzato: IRD inutilizzato: R IPD: R | ARD: APD inutilizzato: IRD inutilizzato: D IPD: D[1] |
| SQL_DESC_UNNAMED | SQLSMALLINT | ARD: APD inutilizzato: IRD inutilizzato: R IPD: R/W | ARD: ND APD: ND IRD: D IPD: ND |
| SQL_DESC_UNSIGNED | SQLSMALLINT | ARD: APD inutilizzato: IRD inutilizzato: R IPD: R | ARD: APD inutilizzato: IRD inutilizzato: D IPD: D[1] |
| SQL_DESC_UPDATABLE | SQLSMALLINT | ARD: APD inutilizzato: IRD inutilizzato: R IPD: non usato | ARD: APD inutilizzato: IRD inutilizzato: D IPD: non usato |
[1] Questi campi vengono definiti solo quando l'IPD viene popolato automaticamente dal driver. In caso contrario, non sono definiti. Se un'applicazione tenta di impostare questi campi, verrà restituito SQLSTATE HY091 (identificatore di campo descrittore non valido).
[2] Il campo SQL_DESC_DATA_PTR nell'IPD può essere impostato per forzare una verifica coerenza. In una chiamata successiva a SQLGetDescField o SQLGetDescRec, il driver non deve restituire il valore su cui è stato impostato SQL_DESC_DATA_PTR.
Argomento FieldIdentifier
L'argomento FieldIdentifier indica il campo descrittore da impostare. Un descrittore contiene l'intestazione del descrittore, costituita dai campi di intestazione descritti nella sezione successiva, "Campi intestazione" e zero o più record descrittori, costituiti dai campi record descritti nella sezione "Campi intestazione".
Campi intestazione
Ogni descrittore ha un'intestazione costituita dai campi seguenti:
SQL_DESC_ALLOC_TYPE [Tutti]
Questo campo di intestazione SQLSMALLINT di sola lettura specifica se il descrittore è stato allocato automaticamente dal driver o esplicitamente dall'applicazione. L'applicazione può ottenere, ma non modificare, questo campo. Il campo è impostato su SQL_DESC_ALLOC_AUTO dal driver se il descrittore è stato allocato automaticamente dal driver. È impostato su SQL_DESC_ALLOC_USER dal driver se il descrittore è stato allocato in modo esplicito dall'applicazione.
SQL_DESC_ARRAY_SIZE [descrittori di applicazioni]
Negli ARD questo campo di intestazione SQLULEN specifica il numero di righe nel set di righe. Questo è il numero di righe da restituire da una chiamata a SQLFetch o SQLFetchScroll o da usare tramite una chiamata a SQLBulkOperations o SQLSetPos.
Nelle API questo campo di intestazione SQLULEN specifica il numero di valori per ogni parametro.
Il valore predefinito di questo campo è 1. Se SQL_DESC_ARRAY_SIZE è maggiore di 1, SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR e SQL_DESC_OCTET_LENGTH_PTR delle matrici APD o ARD. La cardinalità di ogni matrice è uguale al valore di questo campo.
Questo campo nella ARD può essere impostato anche chiamando SQLSetStmtAttr con l'attributo SQL_ATTR_ROW_ARRAY_SIZE. Questo campo nel APD può essere impostato anche chiamando SQLSetStmtAttr con l'attributo SQL_ATTR_PARAMSET_SIZE.
SQL_DESC_ARRAY_STATUS_PTR [Tutti]
Per ogni tipo di descrittore, questo campo di intestazione SQLUSMALLINT * punta a una matrice di valori SQLUSMALLINT. Queste matrici sono denominate come segue: matrice di stato delle righe (IRD), matrice di stato dei parametri (IPD), matrice di operazioni di riga (ARD) e matrice di operazioni dei parametri (APD).
In IRD questo campo di intestazione punta a una matrice di stato di riga contenente i valori di stato dopo una chiamata a SQLBulkOperations, SQLFetch, SQLFetchScroll o SQLSetPos. La matrice include tutti gli elementi presenti nel set di righe. L'applicazione deve allocare una matrice di SQLUSMALLINTs e impostare questo campo in modo che punti alla matrice. Il campo è impostato su un puntatore Null per impostazione predefinita. Il driver popola la matrice, a meno che il campo SQL_DESC_ARRAY_STATUS_PTR non sia impostato su un puntatore Null, nel qual caso non vengono generati valori di stato e la matrice non viene popolata.
Attenzione
Il comportamento del driver non è definito se l'applicazione imposta gli elementi della matrice di stato della riga a cui punta il campo SQL_DESC_ARRAY_STATUS_PTR di IRD.
La matrice viene inizialmente popolata da una chiamata a SQLBulkOperations, SQLFetch, SQLFetchScroll o SQLSetPos. Se la chiamata non ha restituito SQL_SUCCESS o SQL_SUCCESS_WITH_INFO, il contenuto della matrice a cui punta questo campo non è definito. Gli elementi nella matrice possono contenere i valori seguenti:
SQL_ROW_SUCCESS: la riga è stata recuperata correttamente e non è stata modificata dopo l'ultimo recupero.
SQL_ROW_SUCCESS_WITH_INFO: la riga è stata recuperata correttamente e non è stata modificata dopo l'ultimo recupero. Tuttavia, è stato restituito un avviso relativo alla riga.
SQL_ROW_ERROR: si è verificato un errore durante il recupero della riga.
SQL_ROW_UPDATED: la riga è stata recuperata correttamente ed è stata aggiornata dopo l'ultimo recupero. Se la riga viene recuperata di nuovo, lo stato è SQL_ROW_SUCCESS.
SQL_ROW_DELETED: la riga è stata eliminata dopo l'ultimo recupero.
SQL_ROW_ADDED: la riga è stata inserita da SQLBulkOperations. Se la riga viene recuperata di nuovo, lo stato è SQL_ROW_SUCCESS.
SQL_ROW_NOROW: il set di righe si sovrappone alla fine del set di risultati e non viene restituita alcuna riga corrispondente a questo elemento della matrice di stato della riga.
Questo campo in IRD può essere impostato anche chiamando SQLSetStmtAttr con l'attributo SQL_ATTR_ROW_STATUS_PTR.
Il campo SQL_DESC_ARRAY_STATUS_PTR dell'IRD è valido solo dopo la restituzione di SQL_SUCCESS o SQL_SUCCESS_WITH_INFO. Se il codice restituito non è uno di questi, la posizione a cui punta SQL_DESC_ROWS_PROCESSED_PTR non è definita.
Nell'IPD questo campo di intestazione punta a una matrice di stato dei parametri contenente informazioni sullo stato per ogni set di valori di parametro dopo una chiamata a SQLExecute o SQLExecDirect. Se la chiamata a SQLExecute o SQLExecDirect non ha restituito SQL_SUCCESS o SQL_SUCCESS_WITH_INFO, il contenuto della matrice a cui punta questo campo non è definito. L'applicazione deve allocare una matrice di SQLUSMALLINTs e impostare questo campo in modo che punti alla matrice. Il driver popola la matrice, a meno che il campo SQL_DESC_ARRAY_STATUS_PTR non sia impostato su un puntatore Null, nel qual caso non vengono generati valori di stato e la matrice non viene popolata. Gli elementi nella matrice possono contenere i valori seguenti:
SQL_PARAM_SUCCESS: l'istruzione SQL è stata eseguita correttamente per questo set di parametri.
SQL_PARAM_SUCCESS_WITH_INFO: l'istruzione SQL è stata eseguita correttamente per questo set di parametri; Tuttavia, le informazioni di avviso sono disponibili nella struttura dei dati di diagnostica.
SQL_PARAM_ERROR: si è verificato un errore durante l'elaborazione di questo set di parametri. Altre informazioni sugli errori sono disponibili nella struttura dei dati di diagnostica.
SQL_PARAM_UNUSED: questo set di parametri è stato inutilizzato, probabilmente a causa del fatto che alcuni set di parametri precedenti hanno causato un errore che ha interrotto ulteriormente l'elaborazione o perché SQL_PARAM_IGNORE è stato impostato per tale set di parametri nella matrice specificata dal campo SQL_DESC_ARRAY_STATUS_PTR del APD.
SQL_PARAM_DIAG_UNAVAILABLE: le informazioni di diagnostica non sono disponibili. Un esempio è quando il driver considera matrici di parametri come unità monolitica e quindi non genera questo livello di informazioni sugli errori.
Questo campo nell'IPD può essere impostato anche chiamando SQLSetStmtAttr con l'attributo SQL_ATTR_PARAM_STATUS_PTR.
Nel campo dell'intestazione questo campo di intestazione punta a una matrice di operazioni di riga di valori che possono essere impostati dall'applicazione per indicare se questa riga deve essere ignorata per le operazioni SQLSetPos . Gli elementi nella matrice possono contenere i valori seguenti:
SQL_ROW_PROCEED: la riga è inclusa nell'operazione bulk usando SQLSetPos. Questa impostazione non garantisce che l'operazione venga eseguita nella riga. Se la riga ha lo stato SQL_ROW_ERROR nella matrice di stato della riga IRD, il driver potrebbe non essere in grado di eseguire l'operazione nella riga.
SQL_ROW_IGNORE: la riga viene esclusa dall'operazione bulk tramite SQLSetPos.
Se non vengono impostati elementi della matrice, tutte le righe vengono incluse nell'operazione bulk. Se il valore nel campo SQL_DESC_ARRAY_STATUS_PTR della ARD è un puntatore Null, tutte le righe vengono incluse nell'operazione bulk; l'interpretazione è uguale a se il puntatore punta a una matrice valida e tutti gli elementi della matrice sono stati SQL_ROW_PROCEED. Se un elemento della matrice è impostato su SQL_ROW_IGNORE, il valore nella matrice di stato della riga per la riga ignorata non viene modificato.
Questo campo nella ARD può essere impostato anche chiamando SQLSetStmtAttr con l'attributo SQL_ATTR_ROW_OPERATION_PTR.
In APD questo campo di intestazione punta a una matrice di operazioni di parametro di valori che possono essere impostati dall'applicazione per indicare se questo set di parametri deve essere ignorato quando viene chiamato SQLExecute o SQLExecDirect . Gli elementi nella matrice possono contenere i valori seguenti:
SQL_PARAM_PROCEED: il set di parametri è incluso nella chiamata SQLExecute o SQLExecDirect .
SQL_PARAM_IGNORE: il set di parametri viene escluso dalla chiamata SQLExecute o SQLExecDirect .
Se non vengono impostati elementi della matrice, tutti i set di parametri nella matrice vengono usati nelle chiamate SQLExecute o SQLExecDirect . Se il valore nel campo SQL_DESC_ARRAY_STATUS_PTR di APD è un puntatore Null, vengono utilizzati tutti i set di parametri; l'interpretazione è uguale a se il puntatore punta a una matrice valida e tutti gli elementi della matrice sono stati SQL_PARAM_PROCEED.
Questo campo nel APD può anche essere impostato chiamando SQLSetStmtAttr con l'attributo SQL_ATTR_PARAM_OPERATION_PTR.
SQL_DESC_BIND_OFFSET_PTR [descrittori di applicazioni]
Questo campo di intestazione SQLLEN * punta all'offset dell'associazione. È impostato su un puntatore Null per impostazione predefinita. Se questo campo non è un puntatore Null, il driver dereferenzia il puntatore e aggiunge il valore dereferenziato a ognuno dei campi posticipati con un valore non Null nel record del descrittore (SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR e SQL_DESC_OCTET_LENGTH_PTR) in fase di recupero e usa i nuovi valori puntatore durante l'associazione.
L'offset di associazione viene sempre aggiunto direttamente ai valori nei campi SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR e SQL_DESC_OCTET_LENGTH_PTR. Se l'offset viene modificato in un valore diverso, il nuovo valore viene comunque aggiunto direttamente al valore in ogni campo descrittore. Il nuovo offset non viene aggiunto al valore del campo più qualsiasi offset precedente.
Questo campo è un campo posticipato: non viene usato al momento dell'impostazione, ma viene usato in un secondo momento dal driver quando deve determinare gli indirizzi per i buffer di dati.
Questo campo nella ARD può essere impostato anche chiamando SQLSetStmtAttr con l'attributo SQL_ATTR_ROW_BIND_OFFSET_PTR. Questo campo nella ARD può essere impostato anche chiamando SQLSetStmtAttr con l'attributo SQL_ATTR_PARAM_BIND_OFFSET_PTR.
Per altre informazioni, vedere la descrizione dell'associazione a livello di riga in SQLFetchScroll e SQLBindParameter.
SQL_DESC_BIND_TYPE [descrittori di applicazioni]
Questo campo di intestazione SQLUINTEGER imposta l'orientamento dell'associazione da usare per l'associazione di colonne o parametri.
Negli ARD questo campo specifica l'orientamento dell'associazione quando SQLFetchScroll o SQLFetch viene chiamato sull'handle di istruzione associato.
Per selezionare l'associazione a livello di colonna per le colonne, questo campo è impostato su SQL_BIND_BY_COLUMN (impostazione predefinita).
Questo campo nella ARD può essere impostato anche chiamando SQLSetStmtAttr con l'attributo SQL_ATTR_ROW_BIND_TYPE.
Nelle API questo campo specifica l'orientamento dell'associazione da usare per i parametri dinamici.
Per selezionare l'associazione a livello di colonna per i parametri, questo campo è impostato su SQL_BIND_BY_COLUMN (impostazione predefinita).
Questo campo nel APD può essere impostato anche chiamando SQLSetStmtAttr con l'attributo SQL_ATTR_PARAM_BIND_TYPE.
SQL_DESC_COUNT [Tutti]
Questo campo di intestazione SQLSMALLINT specifica l'indice in base 1 del record con numeri più alti che contiene dati. Quando il driver imposta la struttura dei dati per il descrittore, deve anche impostare il campo SQL_DESC_COUNT per mostrare il numero di record significativi. Quando un'applicazione alloca un'istanza di questa struttura di dati, non è necessario specificare il numero di record per cui riservare spazio. Poiché l'applicazione specifica il contenuto dei record, il driver esegue qualsiasi azione necessaria per garantire che l'handle del descrittore faccia riferimento a una struttura di dati di dimensioni adeguate.
SQL_DESC_COUNT non è un conteggio di tutte le colonne di dati associate (se il campo si trova in un ARD) o di tutti i parametri associati (se il campo si trova in un APD), ma il numero del record numerato più alto. Se la colonna o il parametro con numero più alto non è associato, SQL_DESC_COUNT viene modificato nel numero della colonna o del parametro con numero più alto successivo. Se una colonna o un parametro con un numero minore del numero della colonna numerata più alta non è associato (chiamando SQLBindCol con l'argomento TargetValuePtr impostato su un puntatore Null o SQLBindParameter con l'argomento ParameterValuePtr impostato su un puntatore Null), SQL_DESC_COUNT non viene modificato. Se colonne o parametri aggiuntivi sono associati con numeri maggiori del record con numero più alto che contiene dati, il driver aumenta automaticamente il valore nel campo SQL_DESC_COUNT. Se tutte le colonne non sono associate chiamando SQLFreeStmt con l'opzione SQL_UNBIND, i campi SQL_DESC_COUNT nella ARD e IRD sono impostati su 0. Se SQLFreeStmt viene chiamato con l'opzione SQL_RESET_PARAMS, i campi di SQL_DESC_COUNT in APD e IPD sono impostati su 0.
Il valore in SQL_DESC_COUNT può essere impostato in modo esplicito da un'applicazione chiamando SQLSetDescField. Se il valore in SQL_DESC_COUNT viene ridotto in modo esplicito, tutti i record con numeri maggiori del nuovo valore in SQL_DESC_COUNT vengono effettivamente rimossi. Se il valore in SQL_DESC_COUNT è impostato in modo esplicito su 0 e il campo si trova in un ARD, vengono rilasciati tutti i buffer di dati ad eccezione di una colonna di segnalibro associato.
Il numero di record in questo campo di un ARD non include una colonna segnalibro associata. L'unico modo per annullare l'associazione di una colonna segnalibro consiste nell'impostare il campo SQL_DESC_DATA_PTR su un puntatore Null.
SQL_DESC_ROWS_PROCESSED_PTR [descrittori di implementazione]
In un oggetto IRD questo campo di intestazione SQLULEN * punta a un buffer contenente il numero di righe recuperate dopo una chiamata a SQLFetch o SQLFetchScroll o al numero di righe interessate in un'operazione bulk eseguita da una chiamata a SQLBulkOperations o SQLSetPos, incluse le righe di errore.
In un IPD questo campo di intestazione SQLUINTEGER * punta a un buffer contenente il numero di set di parametri elaborati, inclusi i set di errori. Se si tratta di un puntatore Null, non verrà restituito alcun numero.
SQL_DESC_ROWS_PROCESSED_PTR è valido solo dopo che SQL_SUCCESS o SQL_SUCCESS_WITH_INFO è stato restituito dopo una chiamata a SQLFetch o SQLFetchScroll (per un campo IRD) o SQLExecute, SQLExecDirect o SQLParamData (per un campo IPD). Se la chiamata che riempie il buffer a cui punta questo campo non restituisce SQL_SUCCESS o SQL_SUCCESS_WITH_INFO, il contenuto del buffer non è definito, a meno che non restituisca SQL_NO_DATA, nel qual caso il valore nel buffer è impostato su 0.
Questo campo nella ARD può essere impostato anche chiamando SQLSetStmtAttr con l'attributo SQL_ATTR_ROWS_FETCHED_PTR. Questo campo nel APD può anche essere impostato chiamando SQLSetStmtAttr con l'attributo SQL_ATTR_PARAMS_PROCESSED_PTR.
Il buffer a cui punta questo campo viene allocato dall'applicazione. Si tratta di un buffer di output posticipato impostato dal driver. È impostato su un puntatore Null per impostazione predefinita.
Campi record
Ogni descrittore contiene uno o più record costituiti da campi che definiscono parametri dinamici o dati di colonna, a seconda del tipo di descrittore. Ogni record è una definizione completa di una singola colonna o parametro.
SQL_DESC_AUTO_UNIQUE_VALUE [IRD]
Questo campo di record SQLINTEGER di sola lettura contiene SQL_TRUE se la colonna è una colonna con incremento automatico o SQL_FALSE se la colonna non è una colonna a incremento automatico. Questo campo è di sola lettura, ma la colonna di incremento automatico sottostante non è necessariamente di sola lettura.
SQL_DESC_BASE_COLUMN_NAME [IRD]
Questo campo record SQLCHAR * di sola lettura contiene il nome della colonna di base per la colonna del set di risultati. Se non esiste un nome di colonna di base , come nel caso di colonne che sono espressioni, questa variabile contiene una stringa vuota.
SQL_DESC_BASE_TABLE_NAME [IRD]
Questo campo record SQLCHAR * di sola lettura contiene il nome della tabella di base per la colonna del set di risultati. Se non è possibile definire o non è applicabile un nome di tabella di base, questa variabile contiene una stringa vuota.
SQL_DESC_CASE_SENSITIVE [descrittori di implementazione]
Questo campo di record SQLINTEGER di sola lettura contiene SQL_TRUE se la colonna o il parametro viene considerato come distinzione tra maiuscole e minuscole per le regole di confronto e i confronti oppure SQL_FALSE se la colonna non viene considerata come distinzione tra maiuscole e minuscole per le regole di confronto e i confronti o se si tratta di una colonna non carattere.
SQL_DESC_CATALOG_NAME [IRD]
Questo campo di record SQLCHAR * di sola lettura contiene il catalogo per la tabella di base che contiene la colonna. Il valore restituito dipende dal driver se la colonna è un'espressione o se la colonna fa parte di una vista. Se l'origine dati non supporta cataloghi o non è possibile determinare il catalogo, questa variabile contiene una stringa vuota.
SQL_DESC_CONCISE_TYPE [Tutti]
Questo campo di intestazione SQLSMALLINT specifica il tipo di dati conciso per tutti i tipi di dati, inclusi i tipi di dati datetime e interval.
I valori nei campi SQL_DESC_CONCISE_TYPE, SQL_DESC_TYPE e SQL_DESC_DATETIME_INTERVAL_CODE sono interdipendenti. Ogni volta che viene impostato uno dei campi, è necessario impostare anche l'altro. SQL_DESC_CONCISE_TYPE può essere impostato da una chiamata a SQLBindCol o SQLBindParameter o SQLSetDescField. SQL_DESC_TYPE può essere impostato da una chiamata a SQLSetDescField o SQLSetDescRec.
Se SQL_DESC_CONCISE_TYPE è impostato su un tipo di dati conciso diverso da un tipo di dati interval o datetime, il campo SQL_DESC_TYPE viene impostato sullo stesso valore e il campo SQL_DESC_DATETIME_INTERVAL_CODE è impostato su 0.
Se SQL_DESC_CONCISE_TYPE è impostato sul tipo di dati datetime o interval conciso, il campo SQL_DESC_TYPE viene impostato sul tipo dettagliato corrispondente (SQL_DATETIME o SQL_INTERVAL) e il campo SQL_DESC_DATETIME_INTERVAL_CODE viene impostato sul codice secondario appropriato.
SQL_DESC_DATA_PTR [Descrittori di applicazioni e ID IP]
Questo campo di record SQLPOINTER punta a una variabile che conterrà il valore del parametro (per le API) o il valore della colonna (per gli ARD). Questo campo è un campo posticipato. Non viene usato al momento dell'impostazione, ma viene usato in un secondo momento dal driver per recuperare i dati.
La colonna specificata dal campo SQL_DESC_DATA_PTR della ARD non è associato se l'argomento TargetValuePtr in una chiamata a SQLBindCol è un puntatore Null o se il campo SQL_DESC_DATA_PTR nel ARD viene impostato da una chiamata a SQLSetDescField o SQLSetDescRec a un puntatore Null. Altri campi non sono interessati se il campo SQL_DESC_DATA_PTR è impostato su un puntatore Null.
Se la chiamata a SQLFetch o SQLFetchScroll che riempie il buffer a cui punta questo campo non ha restituito SQL_SUCCESS o SQL_SUCCESS_WITH_INFO, il contenuto del buffer non è definito.
Ogni volta che viene impostato il campo SQL_DESC_DATA_PTR di APD, ARD o IPD, il driver verifica che il valore nel campo SQL_DESC_TYPE contenga uno dei tipi di dati ODBC C validi o un tipo di dati specifico del driver e che tutti gli altri campi che interessano i tipi di dati siano coerenti. La richiesta di una verifica coerenza è l'unico uso del campo SQL_DESC_DATA_PTR di un IPD. In particolare, se un'applicazione imposta il campo SQL_DESC_DATA_PTR di un IPD e successivamente chiama SQLGetDescField in questo campo, non viene necessariamente restituito il valore impostato. Per altre informazioni, vedere "Verifiche di coerenza" in SQLSetDescRec.
SQL_DESC_DATETIME_INTERVAL_CODE [Tutti]
Questo campo di record SQLSMALLINT contiene il codice secondario per il tipo di dati datetime o interval specifico quando il campo SQL_DESC_TYPE è SQL_DATETIME o SQL_INTERVAL. Questo vale sia per i tipi di dati SQL che per I tipi di dati C. Il codice è costituito dal nome del tipo di dati con "CODE" sostituito da "TYPE" o "C_TYPE" (per i tipi datetime) o "CODE" sostituiti da "INTERVAL" o "C_INTERVAL" (per i tipi di intervallo).
Se SQL_DESC_TYPE e SQL_DESC_CONCISE_TYPE in un descrittore dell'applicazione sono impostati su SQL_C_DEFAULT e il descrittore non è associato a un handle di istruzione, il contenuto di SQL_DESC_DATETIME_INTERVAL_CODE non è definito.
Questo campo può essere impostato per i tipi di dati datetime elencati nella tabella seguente.
| Tipi datetime | DATETIME_INTERVAL_CODE |
|---|---|
| SQL_TYPE_DATE/SQL_C_TYPE_DATE | SQL_CODE_DATE |
| SQL_TYPE_TIME/SQL_C_TYPE_TIME | SQL_CODE_TIME |
| SQL_TYPE_TIMESTAMP/SQL_C_TYPE_TIMESTAMP | SQL_CODE_TIMESTAMP |
Questo campo può essere impostato per i tipi di dati intervallo elencati nella tabella seguente.
| Tipo di intervallo | DATETIME_INTERVAL_CODE |
|---|---|
| SQL_INTERVAL_DAY/SQL_C_INTERVAL_DAY | SQL_CODE_DAY |
| SQL_INTERVAL_DAY_TO_HOUR/SQL_C_INTERVAL_DAY_TO_HOUR | SQL_CODE_DAY_TO_HOUR |
| SQL_INTERVAL_DAY_TO_MINUTE/SQL_C_INTERVAL_DAY_TO_MINUTE | SQL_CODE_DAY_TO_MINUTE |
| SQL_INTERVAL_DAY_TO_SECOND/SQL_C_INTERVAL_DAY_TO_SECOND | SQL_CODE_DAY_TO_SECOND |
| SQL_INTERVAL_HOUR/SQL_C_INTERVAL_HOUR | SQL_CODE_HOUR |
| SQL_INTERVAL_HOUR_TO_MINUTE/SQL_C_INTERVAL_HOUR_TO_MINUTE | SQL_CODE_HOUR_TO_MINUTE |
| SQL_INTERVAL_HOUR_TO_SECOND/SQL_C_INTERVAL_HOUR_TO_SECOND | SQL_CODE_HOUR_TO_SECOND |
| SQL_INTERVAL_MINUTE/SQL_C_INTERVAL_MINUTE | SQL_CODE_MINUTE |
| SQL_INTERVAL_MINUTE_TO_SECOND/SQL_C_INTERVAL_MINUTE_TO_SECOND | SQL_CODE_MINUTE_TO_SECOND |
| SQL_INTERVAL_MONTH/SQL_C_INTERVAL_MONTH | SQL_CODE_MONTH |
| SQL_INTERVAL_SECOND/SQL_C_INTERVAL_SECOND | SQL_CODE_SECOND |
| SQL_INTERVAL_YEAR/SQL_C_INTERVAL_YEAR | SQL_CODE_YEAR |
| SQL_INTERVAL_YEAR_TO_MONTH/SQL_C_INTERVAL_YEAR_TO_MONTH | SQL_CODE_YEAR_TO_MONTH |
Per altre informazioni sugli intervalli di dati e su questo campo, vedere Identificatori e descrittori del tipo di dati.
SQL_DESC_DATETIME_INTERVAL_PRECISION [Tutti]
Questo campo di record SQLINTEGER contiene la precisione iniziale dell'intervallo se il campo SQL_DESC_TYPE è SQL_INTERVAL. Quando il campo SQL_DESC_DATETIME_INTERVAL_CODE è impostato su un tipo di dati interval, questo campo viene impostato sulla precisione iniziale dell'intervallo predefinito.
SQL_DESC_DISPLAY_SIZE [IRD]
Questo campo di record SQLINTEGER di sola lettura contiene il numero massimo di caratteri necessari per visualizzare i dati dalla colonna.
SQL_DESC_FIXED_PREC_SCALE [descrittori di implementazione]
Questo campo di record SQLSMALLINT di sola lettura è impostato su SQL_TRUE se la colonna è una colonna numerica esatta e ha una precisione fissa e una scala diversa da zero oppure per SQL_FALSE se la colonna non è una colonna numerica esatta con precisione e scala fissa.
SQL_DESC_INDICATOR_PTR [descrittori di applicazioni]
Negli ARD questo campo di record SQLLEN * punta alla variabile indicatore. Questa variabile contiene SQL_NULL_DATA se il valore della colonna è NULL. Per le API, la variabile indicatore è impostata su SQL_NULL_DATA per specificare argomenti dinamici NULL. In caso contrario, la variabile è zero (a meno che i valori in SQL_DESC_INDICATOR_PTR e SQL_DESC_OCTET_LENGTH_PTR siano gli stessi puntatori).
Se il campo SQL_DESC_INDICATOR_PTR in un ARD è un puntatore Null, al driver viene impedito di restituire informazioni sul fatto che la colonna sia NULL o meno. Se la colonna è NULL e SQL_DESC_INDICATOR_PTR è un puntatore Null, viene restituito SQLSTATE 22002 (variabile indicatore obbligatoria ma non specificata) quando il driver tenta di popolare il buffer dopo una chiamata a SQLFetch o SQLFetchScroll. Se la chiamata a SQLFetch o SQLFetchScroll non ha restituito SQL_SUCCESS o SQL_SUCCESS_WITH_INFO, il contenuto del buffer non è definito.
Il campo SQL_DESC_INDICATOR_PTR determina se il campo a cui punta SQL_DESC_OCTET_LENGTH_PTR è impostato. Se il valore dei dati per una colonna è NULL, il driver imposta la variabile indicatore su SQL_NULL_DATA. Il campo a cui punta SQL_DESC_OCTET_LENGTH_PTR non viene quindi impostato. Se durante il recupero non viene rilevato un valore NULL, il buffer a cui punta SQL_DESC_INDICATOR_PTR è impostato su zero e il buffer a cui punta SQL_DESC_OCTET_LENGTH_PTR viene impostato sulla lunghezza dei dati.
Se il campo SQL_DESC_INDICATOR_PTR in un APD è un puntatore Null, l'applicazione non può utilizzare questo record descrittore per specificare argomenti NULL.
Questo campo è un campo posticipato: non viene usato al momento dell'impostazione, ma viene usato in un secondo momento dal driver per indicare il valore Nullbility (per gli ARD) o per determinare il supporto dei valori Null (per le API).
SQL_DESC_LABEL [IRD]
Questo campo record SQLCHAR * di sola lettura contiene l'etichetta o il titolo della colonna. Se la colonna non ha un'etichetta, questa variabile contiene il nome della colonna. Se la colonna è senza nome e senza etichetta, questa variabile contiene una stringa vuota.
SQL_DESC_LENGTH [Tutti]
Questo campo di record SQLULEN è la lunghezza massima o effettiva di una stringa di caratteri in caratteri o un tipo di dati binario in byte. È la lunghezza massima per un tipo di dati a lunghezza fissa o la lunghezza effettiva per un tipo di dati a lunghezza variabile. Il valore esclude sempre il carattere di terminazione Null che termina la stringa di caratteri. Per i valori il cui tipo è SQL_TYPE_DATE, SQL_TYPE_TIME, SQL_TYPE_TIMESTAMP o uno dei tipi di dati intervallo SQL, questo campo ha la lunghezza in caratteri della rappresentazione di stringa di caratteri del valore datetime o interval.
Il valore in questo campo può essere diverso dal valore per "length" come definito in ODBC 2*.x*. Per altre informazioni, vedere Appendice D: Tipi di dati.
SQL_DESC_LITERAL_PREFIX [IRD]
Questo campo di record SQLCHAR * di sola lettura contiene il carattere o i caratteri riconosciuti dal driver come prefisso per un valore letterale di questo tipo di dati. Questa variabile contiene una stringa vuota per un tipo di dati per il quale non è applicabile un prefisso letterale.
SQL_DESC_LITERAL_SUFFIX [IRD]
Questo campo record SQLCHAR * di sola lettura contiene il carattere o i caratteri riconosciuti dal driver come suffisso per un valore letterale di questo tipo di dati. Questa variabile contiene una stringa vuota per un tipo di dati per il quale non è applicabile un suffisso letterale.
SQL_DESC_LOCAL_TYPE_NAME [descrittori di implementazione]
Questo campo record SQLCHAR * di sola lettura contiene qualsiasi nome localizzato (lingua nativa) per il tipo di dati che può essere diverso dal nome normale del tipo di dati. Se non è presente alcun nome localizzato, viene restituita una stringa vuota. Questo campo è solo a scopo di visualizzazione.
SQL_DESC_NAME [descrittori di implementazione]
Questo campo di record SQLCHAR * in un descrittore di riga contiene l'alias di colonna, se applicabile. Se l'alias di colonna non si applica, viene restituito il nome della colonna. In entrambi i casi, il driver imposta il campo SQL_DESC_UNNAMED su SQL_NAMED quando imposta il campo SQL_DESC_NAME. Se non è presente alcun nome di colonna o alias di colonna, il driver restituisce una stringa vuota nel campo SQL_DESC_NAME e imposta il campo SQL_DESC_UNNAMED su SQL_UNNAMED.
Un'applicazione può impostare il campo SQL_DESC_NAME di un IPD su un nome di parametro o un alias per specificare i parametri della stored procedure in base al nome. Per altre informazioni, vedere Parametri di associazione per nome (parametri denominati)). Il campo SQL_DESC_NAME di un IRD è un campo di sola lettura; SQLSTATE HY091 (identificatore di campo descrittore non valido) verrà restituito se un'applicazione tenta di impostarla.
In IPD questo campo non è definito se il driver non supporta parametri denominati. Se il driver supporta parametri denominati ed è in grado di descrivere i parametri, il nome del parametro viene restituito in questo campo.
SQL_DESC_NULLABLE [descrittori di implementazione]
In IRD questo campo di record SQLSMALLINT di sola lettura è SQL_NULLABLE se la colonna può avere valori NULL, SQL_NO_NULLS se la colonna non dispone di valori NULL o SQL_NULLABLE_UNKNOWN se non è noto se la colonna accetta valori NULL. Questo campo si riferisce alla colonna del set di risultati, non alla colonna di base.
In IPD questo campo è sempre impostato su SQL_NULLABLE perché i parametri dinamici sono sempre nullable e non possono essere impostati da un'applicazione.
SQL_DESC_NUM_PREC_RADIX [Tutti]
Questo campo SQLINTEGER contiene un valore pari a 2 se il tipo di dati nel campo SQL_DESC_TYPE è un tipo di dati numerico approssimativo, perché il campo SQL_DESC_PRECISION contiene il numero di bit. Questo campo contiene un valore pari a 10 se il tipo di dati nel campo SQL_DESC_TYPE è un tipo di dati numerico esatto, perché il campo SQL_DESC_PRECISION contiene il numero di cifre decimali. Questo campo è impostato su 0 per tutti i tipi di dati non numerici.
SQL_DESC_OCTET_LENGTH [Tutti]
Questo campo di record SQLLEN contiene la lunghezza, in byte, di una stringa di caratteri o di un tipo di dati binario. Per i tipi di caratteri a lunghezza fissa o binari, si tratta della lunghezza effettiva in byte. Per i tipi di caratteri a lunghezza variabile o binari, si tratta della lunghezza massima in byte. Questo valore esclude sempre lo spazio per il carattere di terminazione Null per i descrittori di implementazione e include sempre lo spazio per il carattere di terminazione Null per i descrittori dell'applicazione. Per i dati dell'applicazione, questo campo contiene le dimensioni del buffer. Per le API, questo campo viene definito solo per i parametri di output o di input/output.
SQL_DESC_OCTET_LENGTH_PTR [descrittori di applicazioni]
Questo campo di record SQLLEN * punta a una variabile che conterrà la lunghezza totale in byte di un argomento dinamico (per i descrittori di parametri) o di un valore di colonna associato (per i descrittori di riga).
Per un APD, questo valore viene ignorato per tutti gli argomenti tranne la stringa di caratteri e il file binario; se questo campo punta a SQL_NTS, l'argomento dinamico deve essere terminato con null. Per indicare che un parametro associato sarà un parametro data-at-execution, un'applicazione imposta questo campo nel record appropriato del APD su una variabile che, in fase di esecuzione, conterrà il valore SQL_DATA_AT_EXEC o il risultato della macro SQL_LEN_DATA_AT_EXEC. Se è presente più di un campo di questo tipo, SQL_DESC_DATA_PTR può essere impostato su un valore che identifica in modo univoco il parametro per consentire all'applicazione di determinare quale parametro viene richiesto.
Se il campo OCTET_LENGTH_PTR di un ARD è un puntatore Null, il driver non restituisce informazioni sulla lunghezza per la colonna. Se il campo SQL_DESC_OCTET_LENGTH_PTR di un APD è un puntatore Null, il driver presuppone che le stringhe di caratteri e i valori binari siano con terminazione Null. I valori binari non devono essere terminati con null, ma devono essere assegnati una lunghezza per evitare il troncamento.
Se la chiamata a SQLFetch o SQLFetchScroll che riempie il buffer a cui punta questo campo non ha restituito SQL_SUCCESS o SQL_SUCCESS_WITH_INFO, il contenuto del buffer non è definito. Questo campo è un campo posticipato. Non viene usato al momento dell'impostazione, ma viene usato in un secondo momento dal driver per determinare o indicare la lunghezza dell'ottetto dei dati.
SQL_DESC_PARAMETER_TYPE [IPD]
Questo campo di record SQLSMALLINT è impostato su SQL_PARAM_INPUT per un parametro di input, SQL_PARAM_INPUT_OUTPUT per un parametro di input/output, SQL_PARAM_OUTPUT per un parametro di output, SQL_PARAM_INPUT_OUTPUT_STREAM per un parametro con flusso di input/output o SQL_PARAM_OUTPUT_STREAM per un parametro sottoposto a flusso di output. È impostato su SQL_PARAM_INPUT per impostazione predefinita.
Per un IPD, il campo viene impostato su SQL_PARAM_INPUT per impostazione predefinita se l'IPD non viene popolato automaticamente dal driver (l'attributo dell'istruzione SQL_ATTR_ENABLE_AUTO_IPD è SQL_FALSE). Un'applicazione deve impostare questo campo nell'IPD per i parametri che non sono parametri di input.
SQL_DESC_PRECISION [Tutti]
Questo campo di record SQLSMALLINT contiene il numero di cifre per un tipo numerico esatto, il numero di bit nella mantissa (precisione binaria) per un tipo numerico approssimativo o i numeri di cifre nel componente dei secondi frazionari per il tipo di dati SQL_TYPE_TIME, SQL_TYPE_TIMESTAMP o SQL_INTERVAL_SECOND. Questo campo non è definito per tutti gli altri tipi di dati.
Il valore in questo campo può essere diverso dal valore per "precisione" definito in ODBC 2*.x*. Per altre informazioni, vedere Appendice D: Tipi di dati.
SQL_DESC_ROWVER [descrittori di implementazione]
Questo campo SQLSMALLINTrecord indica se una colonna viene modificata automaticamente da DBMS quando viene aggiornata una riga, ad esempio una colonna del tipo "timestamp" in SQL Server. Il valore di questo campo di record è impostato su SQL_TRUE se la colonna è una colonna di controllo delle versioni delle righe e su SQL_FALSE in caso contrario. Questo attributo di colonna è simile alla chiamata di SQLSpecialColumns con IdentifierType di SQL_ROWVER per determinare se una colonna viene aggiornata automaticamente.
SQL_DESC_SCALE [Tutti]
Questo campo di record SQLSMALLINT contiene la scala definita per i tipi di dati decimali e numerici. Il campo non è definito per tutti gli altri tipi di dati.
Il valore in questo campo può essere diverso dal valore per "scale" come definito in ODBC 2*.x*. Per altre informazioni, vedere Appendice D: Tipi di dati.
SQL_DESC_SCHEMA_NAME [IRD]
Questo campo record SQLCHAR * di sola lettura contiene il nome dello schema della tabella di base che contiene la colonna. Il valore restituito dipende dal driver se la colonna è un'espressione o se la colonna fa parte di una vista. Se l'origine dati non supporta schemi o non è possibile determinare il nome dello schema, questa variabile contiene una stringa vuota.
SQL_DESC_SEARCHABLE [IRD]
Questo campo di record SQLSMALLINT di sola lettura è impostato su uno dei valori seguenti:
SQL_PRED_NONE se la colonna non può essere utilizzata in una clausola WHERE . Corrisponde al valore SQL_UNSEARCHABLE in ODBC 2*.x*.
SQL_PRED_CHAR se la colonna può essere usata in una clausola WHERE , ma solo con il predicato LIKE . Corrisponde al valore SQL_LIKE_ONLY in ODBC 2*.x*.
SQL_PRED_BASIC se la colonna può essere usata in una clausola WHERE con tutti gli operatori di confronto tranne LIKE. Corrisponde al valore SQL_EXCEPT_LIKE in ODBC 2*.x*.
SQL_PRED_SEARCHABLE se la colonna può essere usata in una clausola WHERE con qualsiasi operatore di confronto.
SQL_DESC_TABLE_NAME [IRD]
Questo campo record SQLCHAR * di sola lettura contiene il nome della tabella di base che contiene questa colonna. Il valore restituito dipende dal driver se la colonna è un'espressione o se la colonna fa parte di una vista.
SQL_DESC_TYPE [Tutti]
Questo campo di record SQLSMALLINT specifica il tipo di dati SQL o C conciso per tutti i tipi di dati, ad eccezione dei tipi di dati datetime e interval. Per i tipi di dati datetime e interval, questo campo specifica il tipo di dati dettagliato, ovvero SQL_DATETIME o SQL_INTERVAL.
Ogni volta che questo campo contiene SQL_DATETIME o SQL_INTERVAL, il campo SQL_DESC_DATETIME_INTERVAL_CODE deve contenere il codice secondario appropriato per il tipo conciso. Per i tipi di dati datetime, SQL_DESC_TYPE contiene SQL_DATETIME e il campo SQL_DESC_DATETIME_INTERVAL_CODE contiene un codice secondario per il tipo di dati datetime specifico. Per i tipi di dati interval, SQL_DESC_TYPE contiene SQL_INTERVAL e il campo SQL_DESC_DATETIME_INTERVAL_CODE contiene un codice secondario per il tipo di dati intervallo specifico.
I valori nei campi SQL_DESC_TYPE e SQL_DESC_CONCISE_TYPE sono interdipendenti. Ogni volta che viene impostato uno dei campi, è necessario impostare anche l'altro. SQL_DESC_TYPE può essere impostato da una chiamata a SQLSetDescField o SQLSetDescRec. SQL_DESC_CONCISE_TYPE può essere impostato da una chiamata a SQLBindCol o SQLBindParameter o SQLSetDescField.
Se SQL_DESC_TYPE è impostato su un tipo di dati conciso diverso da un tipo di dati interval o datetime, il campo SQL_DESC_CONCISE_TYPE viene impostato sullo stesso valore e il campo SQL_DESC_DATETIME_INTERVAL_CODE è impostato su 0.
Se SQL_DESC_TYPE è impostato sul tipo di dati datetime o interval dettagliato (SQL_DATETIME o SQL_INTERVAL) e il campo SQL_DESC_DATETIME_INTERVAL_CODE viene impostato sul codice secondario appropriato, il campo TYPE SQL_DESC_CONCISE viene impostato sul tipo conciso corrispondente. Il tentativo di impostare SQL_DESC_TYPE su uno dei tipi datetime o interval concisi restituirà SQLSTATE HY021 (informazioni del descrittore incoerente).
Quando il campo SQL_DESC_TYPE viene impostato da una chiamata a SQLBindCol, SQLBindParameter o SQLSetDescField, i campi seguenti vengono impostati sui valori predefiniti seguenti, come illustrato nella tabella seguente. I valori dei campi rimanenti dello stesso record non sono definiti.
| Valore di SQL_DESC_TYPE | Altri campi impostati in modo implicito |
|---|---|
| SQL_CHAR, SQL_VARCHAR, SQL_C_CHAR, SQL_C_VARCHAR | SQL_DESC_LENGTH è impostato su 1. SQL_DESC_PRECISION è impostato su 0. |
| SQL_DATETIME | Quando SQL_DESC_DATETIME_INTERVAL_CODE è impostato su SQL_CODE_DATE o SQL_CODE_TIME, SQL_DESC_PRECISION è impostato su 0. Quando è impostato su SQL_DESC_TIMESTAMP, SQL_DESC_PRECISION è impostato su 6. |
| SQL_DECIMAL, SQL_NUMERIC, SQL_C_NUMERIC | SQL_DESC_SCALE è impostato su 0. SQL_DESC_PRECISION è impostato sulla precisione definita dall'implementazione per il rispettivo tipo di dati. Vedere SQL to C: Numeric per informazioni su come associare manualmente un valore SQL_C_NUMERIC. |
| SQL_FLOAT, SQL_C_FLOAT | SQL_DESC_PRECISION è impostata sulla precisione predefinita definita dall'implementazione per SQL_FLOAT. |
| SQL_INTERVAL | Quando SQL_DESC_DATETIME_INTERVAL_CODE è impostato su un tipo di dati interval, SQL_DESC_DATETIME_INTERVAL_PRECISION è impostato su 2 (precisione iniziale dell'intervallo predefinito). Quando l'intervallo ha un componente secondi, SQL_DESC_PRECISION è impostato su 6 (precisione dei secondi di intervallo predefinita). |
Quando un'applicazione chiama SQLSetDescField per impostare i campi di un descrittore anziché chiamare SQLSetDescRec, l'applicazione deve prima dichiarare il tipo di dati. In questo caso, gli altri campi indicati nella tabella precedente vengono impostati in modo implicito. Se uno dei valori impostati in modo implicito non è accettabile, l'applicazione può quindi chiamare SQLSetDescField o SQLSetDescRec per impostare il valore inaccettabile in modo esplicito.
SQL_DESC_TYPE_NAME [descrittori di implementazione]
Questo campo di record SQLCHAR * di sola lettura contiene il nome del tipo dipendente dall'origine dati( ad esempio "CHAR", "VARCHAR" e così via). Se il nome del tipo di dati è sconosciuto, questa variabile contiene una stringa vuota.
SQL_DESC_UNNAMED [descrittori di implementazione]
Questo campo di record SQLSMALLINT in un descrittore di riga viene impostato dal driver su SQL_NAMED o SQL_UNNAMED quando imposta il campo SQL_DESC_NAME. Se il campo SQL_DESC_NAME contiene un alias di colonna o se l'alias di colonna non è applicabile, il driver imposta il campo SQL_DESC_UNNAMED su SQL_NAMED. Se un'applicazione imposta il campo SQL_DESC_NAME di un IPD su un nome di parametro o un alias, il driver imposta il campo SQL_DESC_UNNAMED dell'IPD su SQL_NAMED. Se non è presente alcun nome di colonna o un alias di colonna, il driver imposta il campo SQL_DESC_UNNAMED su SQL_UNNAMED.
Un'applicazione può impostare il campo SQL_DESC_UNNAMED di un IPD su SQL_UNNAMED. Un driver restituisce SQLSTATE HY091 (identificatore di campo descrittore non valido) se un'applicazione tenta di impostare il campo SQL_DESC_UNNAMED di un IPD su SQL_NAMED. Il campo SQL_DESC_UNNAMED di un IRD è di sola lettura; SQLSTATE HY091 (identificatore di campo descrittore non valido) verrà restituito se un'applicazione tenta di impostarla.
SQL_DESC_UNSIGNED [descrittori di implementazione]
Questo campo di record SQLSMALLINT di sola lettura è impostato su SQL_TRUE se il tipo di colonna è senza segno o non numerico oppure SQL_FALSE se il tipo di colonna è firmato.
SQL_DESC_UPDATABLE [IRD]
Questo campo di record SQLSMALLINT di sola lettura è impostato su uno dei valori seguenti:
SQL_ATTR_READ_ONLY se la colonna del set di risultati è di sola lettura.
SQL_ATTR_WRITE se la colonna del set di risultati è di lettura/scrittura.
SQL_ATTR_READWRITE_UNKNOWN se non è noto se la colonna del set di risultati è aggiornabile o meno.
SQL_DESC_UPDATABLE descrive l'updatabilità della colonna nel set di risultati, non la colonna nella tabella di base. L'updatabilità della colonna nella tabella di base su cui si basa questa colonna del set di risultati può essere diversa dal valore in questo campo. Indica se una colonna è aggiornabile può essere basata sul tipo di dati, sui privilegi utente e sulla definizione del set di risultati stesso. Se non è chiaro se una colonna è aggiornabile, SQL_ATTR_READWRITE_UNKNOWN deve essere restituita.
Controlli di coerenza
Una verifica coerenza viene eseguita automaticamente dal driver ogni volta che un'applicazione passa un valore per il campo SQL_DESC_DATA_PTR del ARD, APD o IPD. Se uno dei campi non è coerente con altri campi, SQLSetDescField restituirà SQLSTATE HY021 (informazioni del descrittore incoerente). Per altre informazioni, vedere "Verifica coerenza" in SQLSetDescRec.
Funzioni correlate
| Per informazioni su | Vedere |
|---|---|
| Associazione di una colonna | Funzione SQLBindCol |
| Associazione di un parametro | Funzione SQLBindParameter |
| Recupero di un campo descrittore | Funzione SQLGetDescField |
| Recupero di più campi descrittore | Funzione SQLGetDescRec |
| Impostazione di più campi descrittori | Funzione SQLSetDescRec |