Funzione SQLSetDescRec
Conformità
Versione introdotta: Conformità agli standard ODBC 3.0: ISO 92
Riepilogo
La funzione SQLSetDescRec imposta più campi descrittori che influiscono sul tipo di dati e sul buffer associati a una colonna o ai dati dei parametri.
Sintassi
SQLRETURN SQLSetDescRec(
SQLHDESC DescriptorHandle,
SQLSMALLINT RecNumber,
SQLSMALLINT Type,
SQLSMALLINT SubType,
SQLLEN Length,
SQLSMALLINT Precision,
SQLSMALLINT Scale,
SQLPOINTER DataPtr,
SQLLEN * StringLengthPtr,
SQLLEN * IndicatorPtr);
Argomenti
DescriptorHandle
[Input] Handle del descrittore. Questo non deve essere un handle IRD.
RecNumber
[Input] Indica il record descrittore che contiene i campi da impostare. I record del descrittore sono numerati da 0, con il numero di record 0 come record del segnalibro. Questo argomento deve essere uguale o maggiore di 0. Se RecNumber è maggiore del valore di SQL_DESC_COUNT, SQL_DESC_COUNTis modificato nel valore di RecNumber.
Tipo
[Input] Valore a cui impostare il campo SQL_DESC_TYPE per il record descrittore.
Sottotipo
[Input] Per i record il cui tipo è SQL_DATETIME o SQL_INTERVAL, si tratta del valore a cui impostare il campo SQL_DESC_DATETIME_INTERVAL_CODE.
Lunghezza
[Input] Valore a cui impostare il campo SQL_DESC_OCTET_LENGTH per il record descrittore.
Precisione
[Input] Valore a cui impostare il campo SQL_DESC_PRECISION per il record descrittore.
Ridimensiona
[Input] Valore a cui impostare il campo SQL_DESC_SCALE per il record descrittore.
DataPtr
[Input o output posticipato] Valore a cui impostare il campo SQL_DESC_DATA_PTR per il record descrittore. DataPtr può essere impostato su un puntatore Null.
L'argomento DataPtr può essere impostato su un puntatore Null per impostare il campo SQL_DESC_DATA_PTR su un puntatore Null. Se l'handle nell'argomento DescriptorHandle è associato a un ARD, verrà annullata l'associazione della colonna.
StringLengthPtr
[Input o output posticipato] Valore a cui impostare il campo SQL_DESC_OCTET_LENGTH_PTR per il record del descrittore. StringLengthPtr può essere impostato su un puntatore Null per impostare il campo SQL_DESC_OCTET_LENGTH_PTR su un puntatore Null.
IndicatorPtr
[Input o output posticipato] Valore a cui impostare il campo SQL_DESC_INDICATOR_PTR per il record descrittore. IndicatorPtr può essere impostato su un puntatore Null per impostare il campo SQL_DESC_INDICATOR_PTR su un puntatore Null.
Resi
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR o SQL_INVALID_HANDLE.
Diagnostica
Quando SQLSetDescRec 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 SQLSetDescRec e spiega ognuno di essi 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. |
| 07009 | Indice descrittore non valido | L'argomento RecNumber è stato impostato su 0 e il DescrittoreHandle ha fatto riferimento a un handle IPD. L'argomento RecNumber è minore di 0. L'argomento RecNumber è maggiore del numero massimo di colonne o parametri che l'origine dati può supportare e l'argomento DescriptorHandle è un oggetto APD, IPD o ARD. 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. |
| 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 aynchronous era ancora in esecuzione quando è stata chiamata la funzione SQLSetDescRec . (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. |
| HY021 | Informazioni sul descrittore incoerente | Il campo Tipo o qualsiasi altro campo associato al campo SQL_DESC_TYPE nel descrittore non è valido o coerente. Le informazioni del descrittore controllate durante un controllo coerenza non sono coerenti. Vedere "Verifiche di coerenza" più avanti in questa sezione. |
| HY090 | Lunghezza della stringa o del buffer non valida | (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. |
| 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 Funzione SQLEndTran. |
| 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 SQLSetDescRec per impostare i campi seguenti per una singola colonna o parametro:
SQL_DESC_TYPE
SQL_DESC_DATETIME_INTERVAL_CODE (per i record il cui tipo è SQL_DATETIME o SQL_INTERVAL)
SQL_DESC_OCTET_LENGTH
SQL_DESC_PRECISION
SQL_DESC_SCALE
SQL_DESC_DATA_PTR
SQL_DESC_OCTET_LENGTH_PTR
SQL_DESC_INDICATOR_PTR
Nota
Se una chiamata a SQLSetDescRec ha esito negativo, il contenuto del record descrittore identificato dall'argomento RecNumber non è definito.
Quando si associa una colonna o un parametro, SQLSetDescRec consente di modificare più campi che influiscono sull'associazione senza chiamare SQLBindCol o SQLBindParameter o effettuare più chiamate a SQLSetDescField. SQLSetDescRec può impostare campi in un descrittore non attualmente associato a un'istruzione . Si noti che SQLBindParameter imposta più campi rispetto a SQLSetDescRec, può impostare campi sia in un APD che in un IPD in una chiamata e non richiede un handle descrittore.
Nota
L'attributo di istruzione SQL_ATTR_USE_BOOKMARKS deve essere sempre impostato prima di chiamare SQLSetDescRec con un argomento RecNumber pari a 0 per impostare i campi del segnalibro. Anche se questo non è obbligatorio, è fortemente consigliato.
Controlli di coerenza
Un controllo di coerenza viene eseguito automaticamente dal driver ogni volta che un'applicazione imposta il campo SQL_DESC_DATA_PTR di un APD, ARD o IPD. Se uno dei campi non è coerente con altri campi, SQLSetDescRec restituirà SQLSTATE HY021 (informazioni del descrittore incoerente).
Ogni volta che un'applicazione imposta il campo SQL_DESC_DATA_PTR di un oggetto APD, ARD o IPD, il driver verifica che il valore del campo SQL_DESC_TYPE e i valori applicabili a tale campo SQL_DESC_TYPE siano validi e coerenti. Questo controllo viene sempre eseguito quando viene chiamato SQLBindParameter o SQLBindCol o quando SQLSetDescRec viene chiamato per un APD, ARD o IPD. Questa verifica coerenza include i controlli seguenti sui campi del descrittore:
Il campo SQL_DESC_TYPE deve essere uno dei tipi ODBC C o SQL validi o un tipo SQL specifico del driver. Il campo SQL_DESC_CONCISE_TYPE deve essere uno dei tipi ODBC C o SQL validi oppure un tipo C o SQL specifico del driver, inclusi i tipi datetime e interval concisi.
Se il campo del record SQL_DESC_TYPE è SQL_DATETIME o SQL_INTERVAL, il campo SQL_DESC_DATETIME_INTERVAL_CODE deve essere uno dei codici datetime o interval validi. Vedere la descrizione del campo SQL_DESC_DATETIME_INTERVAL_CODE in SQLSetDescField.
Se il campo SQL_DESC_TYPE indica un tipo numerico, i campi SQL_DESC_PRECISION e SQL_DESC_SCALE vengono verificati come validi.
Se il campo SQL_DESC_CONCISE_TYPE è un tipo di dati time o timestamp, un tipo di intervallo con un componente secondi o uno dei tipi di dati intervallo con un componente time, il campo SQL_DESC_PRECISION viene verificato come una precisione di secondi valida.
Se il SQL_DESC_CONCISE_TYPE è un tipo di dati interval, il campo SQL_DESC_DATETIME_INTERVAL_PRECISION viene verificato che sia un valore di precisione iniziale intervallo valido.
Il campo SQL_DESC_DATA_PTR di un IPD non è in genere impostato; Tuttavia, un'applicazione può eseguire questa operazione per forzare una verifica coerenza dei campi IPD. Non è possibile eseguire un controllo di coerenza su un IRD. Il valore su cui il campo SQL_DESC_DATA_PTR dell'IPD non è effettivamente archiviato e non può essere recuperato da una chiamata a SQLGetDescField o SQLGetDescRec. L'impostazione viene eseguita solo per forzare la verifica coerenza.
Funzioni correlate
| Per informazioni su | Vedere |
|---|---|
| Associazione di una colonna | Funzione SQLBindCol |
| Associazione di un parametro | Funzione SQLBindParameter |
| Recupero di un singolo campo descrittore | Funzione SQLGetDescField |
| Recupero di più campi descrittore | Funzione SQLGetDescRec |
| Impostazione di campi di descrittore singolo | Funzione SQLSetDescField |