Funzione SQLGetDescRec
Conformità
Versione introdotta: Conformità agli standard ODBC 3.0: ISO 92
Riepilogo
SQLGetDescRec restituisce le impostazioni o i valori correnti di più campi di un record descrittore. I campi restituiti descrivono il nome, il tipo di dati e l'archiviazione dei dati della colonna o dei parametri.
Sintassi
SQLRETURN SQLGetDescRec(
SQLHDESC DescriptorHandle,
SQLSMALLINT RecNumber,
SQLCHAR * Name,
SQLSMALLINT BufferLength,
SQLSMALLINT * StringLengthPtr,
SQLSMALLINT * TypePtr,
SQLSMALLINT * SubTypePtr,
SQLLEN * LengthPtr,
SQLSMALLINT * PrecisionPtr,
SQLSMALLINT * ScalePtr,
SQLSMALLINT * NullablePtr);
Argomenti
DescriptorHandle
[Input] Handle del descrittore.
RecNumber
[Input] Indica il record descrittore da cui l'applicazione cerca informazioni. I record del descrittore sono numerati da 1, con il numero di record 0 come record del segnalibro. L'argomento RecNumber deve essere minore o uguale al valore di SQL_DESC_COUNT. Se RecNumber è minore o uguale a SQL_DESC_COUNT ma la riga non contiene dati per una colonna o un parametro, una chiamata a SQLGetDescRec restituirà i valori predefiniti dei campi. Per altre informazioni, vedere "Inizializzazione dei campi descrittore" in SQLSetDescField.
Nome
[Output] Puntatore a un buffer in cui restituire il campo SQL_DESC_NAME per il record del descrittore.
Se Name è NULL, StringLengthPtr restituirà comunque il numero totale di caratteri (escluso il carattere di terminazione Null per i dati di tipo carattere) da restituire nel buffer a cui punta nome.
BufferLength
[Input] Lunghezza del buffer *Name , in caratteri.
StringLengthPtr
[Output] Puntatore a un buffer in cui restituire il numero di caratteri di dati disponibili per la restituzione nel buffer *Name , escluso il carattere di terminazione Null. Se il numero di caratteri è maggiore o uguale a BufferLength, i dati in *Name vengono troncati a BufferLength meno la lunghezza di un carattere di terminazione Null e terminano con null dal driver.
TypePtr
[Output] Puntatore a un buffer in cui restituire il valore del campo SQL_DESC_TYPE per il record del descrittore.
SubTypePtr
[Output] Per i record il cui tipo è SQL_DATETIME o SQL_INTERVAL, si tratta di un puntatore a un buffer in cui restituire il valore del campo SQL_DESC_DATETIME_INTERVAL_CODE.
LengthPtr
[Output] Puntatore a un buffer in cui restituire il valore del campo SQL_DESC_OCTET_LENGTH per il record del descrittore.
PrecisionPtr
[Output] Puntatore a un buffer in cui restituire il valore del campo SQL_DESC_PRECISION per il record del descrittore.
ScalePtr
[Output] Puntatore a un buffer in cui restituire il valore del campo SQL_DESC_SCALE per il record del descrittore.
NullablePtr
[Output] Puntatore a un buffer in cui restituire il valore del campo SQL_DESC_NULLABLE per il record del descrittore.
Resi
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_NO_DATA o SQL_INVALID_HANDLE.
SQL_NO_DATA viene restituito se RecNumber è maggiore del numero corrente di record del descrittore.
SQL_NO_DATA viene restituito se DescriptorHandle è un handle IRD e l'istruzione si trova nello stato preparato o eseguito, ma non è stato associato alcun cursore aperto.
Diagnostica
Quando SQLGetDescRec 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 restituiti in genere da SQLGetDescRec e 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. |
| 01004 | Dati stringa, troncati a destra | Il buffer *Nome non è sufficientemente grande da restituire l'intero campo descrittore. Pertanto, il campo è stato troncato. La lunghezza del campo descrittore non modificato viene restituita in *StringLengthPtr. (La funzione restituisce SQL_SUCCESS_WITH_INFO. |
| 07009 | Indice descrittore non valido | L'argomento FieldIdentifier era un campo record, l'argomento RecNumber era impostato su 0 e l'argomento DescriptorHandle era un handle IPD. (DM) L'argomento RecNumber è stato impostato su 0 e l'attributo dell'istruzione SQL_ATTR_USE_BOOKMARKS è stato impostato su SQL_UB_OFF e l'argomento DescriptorHandle era un handle IRD. L'argomento RecNumber è minore di 0. |
| 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 la memoria necessaria per supportare l'esecuzione o il completamento della funzione. |
| HY007 | Istruzione associata non preparata | Il descrittoreHandle è stato associato a un IRD e l'handle di istruzione associato non era nello stato preparato o eseguito. |
| HY010 | Errore della sequenza di funzioni | (DM) DescriptorHandle è stato associato a un StatementHandle per il quale è stata chiamata una funzione in esecuzione asincrona (non questa) ed era ancora in esecuzione quando questa funzione è stata chiamata. (DM) DescriptorHandle è stato associato a un statementHandle per cui è stato SQL_NEED_DATA chiamato SQLExecute, SQLExecDirect, SQLBulkOperations o SQLSetPos . 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 è stato chiamato SQLGetDescRec . |
| 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. |
| 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 SQLGetDescRec per recuperare i valori dei campi descrittori seguenti per una singola colonna o parametro:
SQL_DESC_NAME
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_NULLABLE
SQLGetDescRec non recupera i valori per i campi di intestazione.
Un'applicazione può impedire la restituzione dell'impostazione di un campo impostando l'argomento corrispondente al campo su un puntatore Null.
Quando un'applicazione chiama SQLGetDescRec per recuperare il valore di un campo non definito per un particolare tipo di descrittore, la funzione restituisce SQL_SUCCESS ma il valore restituito per il campo non è definito. Ad esempio, la chiamata a SQLGetDescRec per il campo SQL_DESC_NAME o SQL_DESC_NULLABLE di un APD o ARD restituirà SQL_SUCCESS ma un valore non definito per il campo.
Quando un'applicazione chiama SQLGetDescRec per recuperare il valore di un campo definito per un particolare tipo di descrittore, ma che non ha ancora un valore predefinito e non è ancora stato impostato, la funzione restituisce SQL_SUCCESS ma il valore restituito per il campo non è definito. Per altre informazioni, vedere "Inizializzazione dei campi del descrittore" in SQLSetDescField.
I valori dei campi possono essere recuperati singolarmente anche da una chiamata a SQLGetDescField. Per una descrizione dei campi in un'intestazione o un record descrittore, vedere SQLSetDescField. Per altre informazioni sui descrittori, vedere Descrittori.
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 |
| Impostazione di più campi descrittori | Funzione SQLSetDescRec |