Funzione SQLGetDescRec

  • Articolo

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.

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

Vedi anche

Riferimento API ODBC
File di intestazione ODBC