Funzione SQLSetDescRec

Conformità
Versione introdotta: Conformità agli standard ODBC 3.0: ISO 92

Summary
La funzione SQLSetDescRec imposta più campi di descrizione che influiscono sul tipo di dati e sul buffer associati a una colonna o a dati di parametro.

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. Non deve essere un handle IRD.

RecNumber
[Input] Indica il record del 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 viene modificato nel valore di RecNumber.

Tipo
[Input] Valore su cui impostare il campo SQL_DESC_TYPE per il record del descrittore.

Sottotipo
[Input] Per i record il cui SQL_DATETIME o SQL_INTERVAL, questo è il valore su cui impostare il SQL_DESC_DATETIME_INTERVAL_CODE campo.

Length
[Input] Valore su cui impostare il campo SQL_DESC_OCTET_LENGTH per il record del descrittore.

Precisione
[Input] Valore su cui impostare il campo SQL_DESC_PRECISION per il record del descrittore.

Scalabilità
[Input] Valore su cui impostare il campo SQL_DESC_SCALE per il record del descrittore.

DataPtr
[Input o output posticipato] Valore su cui impostare il campo SQL_DESC_DATA_PTR per il record del descrittore. DataPtr può essere impostato su un puntatore Null.

L'argomento DataPtr può essere impostato su un puntatore Null per impostare SQL_DESC_DATA_PTR campo su un puntatore Null. Se l'handle nell'argomento DescriptorHandle è associato a un ARD, la colonna viene disassociato.

StringLengthPtr
[Input o output posticipato] Valore su 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 su cui impostare il campo SQL_DESC_INDICATOR_PTR per il record del descrittore. IndicatorPtr può essere impostato su un puntatore Null per impostare SQL_DESC_INDICATOR_PTR campo su un puntatore Null.

Restituisce

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 handletype SQL_HANDLE_DESC e handle di DescriptorHandle. La tabella seguente elenca i valori SQLSTATE comunemente restituiti da SQLSetDescRec e illustra ognuno di essi nel contesto di questa funzione. la notazione "(DM)" precede le descrizioni di SQLSTATE restituite da Gestione driver. Il codice restituito associato a ogni valore SQLSTATE è SQL_ERROR, se non 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 DescriptorHandle 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 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 di applicazione allocato in modo esplicito perché non è noto se un descrittore dell'applicazione allocato in modo esplicito è un APD o ARD fino al momento dell'esecuzione.
08S01 Errore del collegamento di comunicazione Il 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 esiste un SQLSTATE specifico e per il quale non è stato definito 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.
HY010 Errore della sequenza di funzione (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 è stata chiamata questa funzione.

(DM) SQLExecute, SQLExecDirect, SQLBulkOperations o SQLSetPos è stato chiamato per StatementHandle a cui DescriptorHandle è stato associato 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 in modo asincrono per l'handle di connessione associato a DescriptorHandle. Questa funzione asincrona 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 sono stati restituiti SQL_PARAM_DATA_AVAILABLE. Questa funzione è stata chiamata prima del recupero dei dati per tutti i parametri trasmessi.
HY013 Errore di gestione della memoria Non è stato possibile 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 IRD.
HY021 Informazioni sui descrittori incoerenti Il campo Type o qualsiasi altro campo associato al campo SQL_DESC_TYPE nel descrittore non era valido o coerente.

Le informazioni sul descrittore controllate durante una verifica coerenza non erano coerenti. Vedere "Verifiche di coerenza" più avanti in questa sezione.
HY090 Lunghezza di stringa o buffer non valida (DM) Il driver era un driver ODBC 2.x, il descrittore era un ARD, l'argomento ColumnNumber è stato impostato su 0 e il valore specificato per l'argomento BufferLength non era uguale a 4.
HY117 La connessione è stata sospesa a causa di uno stato di transazione sconosciuto. Sono consentite solo le funzioni di disconnessione e di sola lettura. (DM) Per altre informazioni sullo stato sospeso, vedere Funzione SQLEndTran.
HYT01 Timeout della connessione scaduto Il periodo di timeout della connessione è scaduto prima che l'origine dati risponda 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 del descrittore identificato dall'argomento RecNumber non è definito.

Quando si associa una colonna o un parametro, SQLSetDescRec consente di modificare più campi che interessano l'associazione senza chiamare SQLBindCol o SQLBindParameter o effettuare più chiamate a SQLSetDescField. SQLSetDescRec può impostare campi su un descrittore attualmente non 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 sola chiamata e non richiede un handle di descrittore.

Nota

L'attributo SQL_ATTR_USE_BOOKMARKS deve essere sempre impostato prima di chiamare SQLSetDescRec con un argomento RecNumber di 0 per impostare i campi del segnalibro. Anche se non è obbligatorio, è fortemente consigliato.

Verifiche di coerenza

Il driver verifica automaticamente la coerenza ogni volta che un'applicazione imposta il SQL_DESC_DATA_PTR di un APD, ARD o IPD. Se uno dei campi non è coerente con altri campi, SQLSetDescRec restituirà SQLSTATE HY021 (informazioni sul descrittore incoerente).

Ogni volta che un'applicazione imposta il campo SQL_DESC_DATA_PTR di un 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 viene chiamato SQLSetDescRec per un APD, ARD o IPD. Questa verifica coerenza include i controlli seguenti sui campi del descrittore:

  • Il SQL_DESC_TYPE deve essere uno dei tipi ODBC C o SQL o un tipo di SQL driver. Il SQL_DESC_CONCISE_TYPE deve essere uno dei tipi ODBC C o SQL validi o un tipo C o SQL specifico del driver, inclusi i tipi concisi datetime e interval.

  • Se il campo SQL_DESC_TYPE record è 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 SQL_DESC_TYPE campo 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 seconds o uno dei tipi di dati interval con un componente time, il campo SQL_DESC_PRECISION viene verificato come una precisione in secondi valida.

  • Se il SQL_DESC_CONCISE_TYPE è un tipo di dati interval, il campo SQL_DESC_DATETIME_INTERVAL_PRECISION viene verificato come valore di precisione iniziale dell'intervallo valido.

Il 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 una verifica coerenza su un IRD. Il valore su cui SQL_DESC_DATA_PTR campo dell'IPD è impostato non è effettivamente archiviato e non può essere recuperato da una chiamata a SQLGetDescField o SQLGetDescRec; L'impostazione viene impostata solo per forzare la verifica coerenza.

Per informazioni su Vedere
Associazione di una colonna Funzione SQLBindCol
Associazione di un parametro Pagina relativa alla funzione SQLBindParameter
Recupero di un singolo campo descrittore Funzione SQLGetDescField
Recupero di più campi di descrizione Funzione SQLGetDescRec
Impostazione di singoli campi di descrizione Funzione SQLSetDescField

Vedere anche

Informazioni di riferimento sulle API ODBC
File di intestazione ODBC