Funzione SQLGetStmtAttr

  • Articolo

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

Riepilogo
SQLGetStmtAttr restituisce l'impostazione corrente di un attributo di istruzione.

Nota

Per altre informazioni su ciò che Gestione driver esegue il mapping di questa funzione a quando un ODBC 3.L'applicazione x funziona con odbc 2.x driver, vedere Mapping di funzioni di sostituzione per la compatibilità con le versioni precedenti delle applicazioni.

Sintassi

  
SQLRETURN SQLGetStmtAttr(  
     SQLHSTMT        StatementHandle,  
     SQLINTEGER      Attribute,  
     SQLPOINTER      ValuePtr,  
     SQLINTEGER      BufferLength,  
     SQLINTEGER *    StringLengthPtr);

Argomenti

StatementHandle
[Input] Handle di istruzione.

Attributo
[Input] Attributo da recuperare.

ValuePtr
[Output] Puntatore a un buffer in cui restituire il valore dell'attributo specificato in Attribute.

Se ValuePtr è NULL, StringLengthPtr restituirà comunque il numero totale di byte (escluso il carattere di terminazione null per i dati di tipo carattere) da restituire nel buffer a cui punta ValuePtr.

BufferLength
[Input] Se Attribute è un attributo definito da ODBC e ValuePtr punta a una stringa di caratteri o a un buffer binario, questo argomento deve essere la lunghezza di *ValuePtr. Se Attribute è un attributo definito da ODBC e *ValuePtr è un numero intero, BufferLength viene ignorato. Se il valore restituito in *ValuePtr è una stringa Unicode (quando si chiama SQLGetStmtAttrW), l'argomento BufferLength deve essere un numero pari.

Se Attribute è un attributo definito dal driver, l'applicazione indica la natura dell'attributo a 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 tipo di dati a lunghezza fissa, BufferLength è SQL_IS_INTEGER o SQL_IS_UINTEGER, in base alle esigenze.

StringLengthPtr
[Output] Puntatore a un buffer in cui restituire il numero totale di byte (escluso il carattere di terminazione Null) da restituire in *ValuePtr. Se il valore dell'attributo è una stringa di caratteri e il numero di byte disponibili per la restituzione è maggiore o uguale a BufferLength, i dati in *ValuePtr vengono troncati a BufferLength meno la lunghezza di un carattere di terminazione Null e terminano con null dal driver.

Resi

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR o SQL_INVALID_HANDLE.

Diagnostica

Quando SQLGetStmtAttr restituisce SQL_ERROR o SQL_SUCCESS_WITH_INFO, è possibile ottenere un valore SQLSTATE associato chiamando SQLGetDiagRec con handleTypedi SQL_HANDLE_STMT e handle di StatementHandle. La tabella seguente elenca i valori SQLSTATE comunemente restituiti da SQLGetStmtAttr 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.
01004 Dati stringa, troncati a destra I dati restituiti in *ValuePtr sono stati troncati per essere BufferLength meno la lunghezza di un carattere di terminazione Null. La lunghezza del valore stringa non troncata viene restituita in *StringLengthPtr. (La funzione restituisce SQL_SUCCESS_WITH_INFO.
24000 Stato del cursore non valido L'argomento Attribute è stato SQL_ATTR_ROW_NUMBER e il cursore non è stato aperto oppure il cursore è stato posizionato prima dell'inizio del set di risultati o dopo la fine del set di risultati.
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 nell'argomento 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) È stata chiamata una funzione in esecuzione asincrona per l'handle di connessione associato a StatementHandle. Questa funzione asincrona era ancora in esecuzione quando è stata chiamata la funzione SQLGetStmtAttr .

(DM) È stata chiamata una funzione in esecuzione asincrona per StatementHandle ed era ancora in esecuzione quando questa funzione è stata chiamata.

(DM) SQLExecute, SQLExecDirect, SQLBulkOperations o SQLSetPos è stato chiamato per StatementHandle e restituito SQL_NEED_DATA. Questa funzione è stata chiamata prima dell'invio dei dati per tutti i parametri o le colonne data-at-execution.
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.
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.
HY092 Identificatore di attributo/opzione non valido Il valore specificato per l'argomento Attribute non è valido per la versione di ODBC supportata dal driver.
HY109 Posizione del cursore non valida L'argomento Attribute è stato SQL_ATTR_ROW_NUMBER e la riga è stata eliminata o non è stato possibile recuperare.
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.
HYC00 Funzionalità facoltativa non implementata Il valore specificato per l'argomento Attribute è un attributo di istruzione ODBC valido per la versione di ODBC supportata dal driver, ma non è supportato dal driver.
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 corrispondente a StatementHandle non supporta la funzione.

Commenti

Per informazioni generali sugli attributi delle istruzioni, vedere Attributi istruzione.

Una chiamata a SQLGetStmtAttr restituisce in *ValuePtr il valore dell'attributo di istruzione specificato in Attribute. Tale valore può essere un valore SQLULEN o una stringa di caratteri con terminazione Null. Se il valore è un valore SQLULEN, alcuni driver possono scrivere solo il bit inferiore a 32 bit o 16 bit di un buffer e lasciare invariato il bit di ordine superiore. Pertanto, le applicazioni devono usare un buffer di SQLULEN e inizializzare il valore su 0 prima di chiamare questa funzione. Inoltre, gli argomenti BufferLength e StringLengthPtr non vengono utilizzati. Se il valore è una stringa con terminazione Null, l'applicazione specifica la lunghezza massima di tale stringa nell'argomento BufferLength e il driver restituisce la lunghezza di tale stringa nel buffer *StringLengthPtr .

Per consentire alle applicazioni che chiamano SQLGetStmtAttr di usare ODBC 2.x drivers, viene mappata una chiamata a SQLGetStmtAttr in Gestione driver a SQLGetStmtOption.

Gli attributi di istruzione seguenti sono di sola lettura, quindi possono essere recuperati da SQLGetStmtAttr, ma non impostati da SQLSetStmtAttr:

  • SQL_ATTR_IMP_PARAM_DESC

  • SQL_ATTR_IMP_ROW_DESC

  • SQL_ATTR_ROW_NUMBER

Per un elenco di attributi che possono essere impostati e recuperati, vedere SQLSetStmtAttr.

Per informazioni su Vedere
Restituzione dell'impostazione di un attributo di connessione Funzione SQLGetConnectAttr
Impostazione di un attributo di connessione Funzione SQLSetConnectAttr
Impostazione di un attributo di istruzione Funzione SQLSetStmtAttr

Vedi anche

Riferimento API ODBC
File di intestazione ODBC