Funzione SQLDescribeParam
Conformità
Versione introdotta: Conformità agli standard ODBC 1.0: ODBC
Riepilogo
SQLDescribeParam restituisce la descrizione di un marcatore di parametro associato a un'istruzione SQL preparata. Queste informazioni sono disponibili anche nei campi dell'IPD.
Sintassi
SQLRETURN SQLDescribeParam(
SQLHSTMT StatementHandle,
SQLUSMALLINT ParameterNumber,
SQLSMALLINT * DataTypePtr,
SQLULEN * ParameterSizePtr,
SQLSMALLINT * DecimalDigitsPtr,
SQLSMALLINT * NullablePtr);
Argomenti
StatementHandle
[Input] Handle di istruzione.
ParameterNumber
[Input] Numero dell'indicatore di parametro ordinato in modo sequenziale in ordine di parametro crescente, a partire da 1.
DataTypePtr
[Output] Puntatore a un buffer in cui restituire il tipo di dati SQL del parametro. Questo valore viene letto dal campo di record SQL_DESC_CONCISE_TYPE dell'IPD. Questo sarà uno dei valori nella sezione Tipi di dati SQL dell'Appendice D: Tipi di dati o un tipo di dati SQL specifico del driver.
In ODBC 3.X, SQL_TYPE_DATE, SQL_TYPE_TIME o SQL_TYPE_TIMESTAMP verranno restituiti rispettivamente in *DataTypePtr per i dati di data, ora o timestamp; in ODBC 2.verranno restituiti x, SQL_DATE, SQL_TIME o SQL_TIMESTAMP. Gestione driver esegue i mapping necessari quando un odbc 2.L'applicazione x funziona con odbc 3.x driver o quando un ODBC 3.L'applicazione x funziona con odbc 2.x driver.
Quando ColumnNumber è uguale a 0 (per una colonna di segnalibro), SQL_BINARY viene restituito in *DataTypePtr per i segnalibri a lunghezza variabile. (SQL_INTEGER viene restituito se i segnalibri vengono utilizzati da un ODBC 3.Applicazione x che utilizza un'applicazione ODBC 2.driver x o da odbc 2.Applicazione x che funziona con ODBC 3.x driver.)
Per altre informazioni, vedere Tipi di dati SQL nell'Appendice D: Tipi di dati. Per informazioni sui tipi di dati SQL specifici del driver, vedere la documentazione del driver.
ParameterSizePtr
[Output] Puntatore a un buffer in cui restituire le dimensioni, in caratteri, della colonna o dell'espressione del marcatore di parametro corrispondente come definito dall'origine dati. Per altre informazioni sulle dimensioni delle colonne, vedere Dimensioni delle colonne, Cifre decimali, Lunghezza ottetto di trasferimento e Dimensioni di visualizzazione.
DecimalDigitsPtr
[Output] Puntatore a un buffer in cui restituire il numero di cifre decimali della colonna o dell'espressione del parametro corrispondente, come definito dall'origine dati. Per altre informazioni sulle cifre decimali, vedere Dimensioni delle colonne, Cifre decimali, Lunghezza ottetto trasferimento e Dimensioni di visualizzazione.
NullablePtr
[Output] Puntatore a un buffer in cui restituire un valore che indica se il parametro consente valori NULL. Questo valore viene letto dal campo SQL_DESC_NULLABLE dell'IPD. Uno dei seguenti:
SQL_NO_NULLS: il parametro non consente valori NULL (questo è il valore predefinito).
SQL_NULLABLE: il parametro consente valori NULL.
SQL_NULLABLE_UNKNOWN: il driver non è in grado di determinare se il parametro consente valori NULL.
Valori restituiti
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR o SQL_INVALID_HANDLE.
Diagnostica
Quando SQLDescribeParam restituisce SQL_ERROR o SQL_SUCCESS_WITH_INFO, è possibile ottenere un valore SQLSTATE associato chiamando SQLGetDiagRec con handleType di SQL_HANDLE_STMT e handle di StatementHandle. La tabella seguente elenca i valori SQLSTATE restituiti in genere da SQLDescribeParam 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. |
| 07009 | Indice descrittore non valido | (DM) Il valore specificato per l'argomento ParameterNumber è minore di 1. Il valore specificato per l'argomento ParameterNumber è maggiore del numero di parametri nell'istruzione SQL associata. L'indicatore di parametro faceva parte di un'istruzione non DML. L'indicatore di parametro faceva parte di un elenco SELECT . |
| 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. |
| 21S01 | L'elenco di valori di inserimento non corrisponde all'elenco di colonne | Il numero di parametri nell'istruzione INSERT non corrisponde al numero di colonne nella tabella denominata nell'istruzione . |
| 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. |
| HY008 | Operazione annullata | L'elaborazione asincrona è stata abilitata per StatementHandle. La funzione è stata chiamata e prima di completare l'esecuzione, SQLCancel o SQLCancelHandle è stata chiamata in StatementHandle. La funzione è stata quindi chiamata di nuovo in StatementHandle. La funzione è stata chiamata e prima del completamento dell'esecuzione, SQLCancel o SQLCancelHandle è stato chiamato su StatementHandle da un thread diverso in un'applicazione multithread. |
| HY010 | Errore della sequenza di funzioni | (DM) La funzione è stata chiamata prima di chiamare SQLPrepare o SQLExecDirect per StatementHandle. (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 SQLDescribeParam . (DM) Una funzione in esecuzione asincrona (non questa) è stata chiamata per StatementHandle ed è 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. |
| 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 StatementHandle non supporta la funzione. |
| IM017 | Il polling è disabilitato in modalità di notifica asincrona | Ogni volta che viene usato il modello di notifica, il polling è disabilitato. |
| IM018 | SQLCompleteAsync non è stato chiamato per completare l'operazione asincrona precedente su questo handle. | Se la chiamata di funzione precedente sull'handle restituisce SQL_STILL_EXECUTING e se la modalità di notifica è abilitata, è necessario chiamare SQLCompleteAsync sull'handle per eseguire la post-elaborazione e completare l'operazione. |
Commenti
I marcatori di parametro vengono numerati in ordine di parametro crescente, a partire da 1, nell'ordine in cui vengono visualizzati nell'istruzione SQL.
SQLDescribeParam non restituisce il tipo (input, input/output o output) di un parametro in un'istruzione SQL. Ad eccezione delle chiamate alle procedure, tutti i parametri nelle istruzioni SQL sono parametri di input. Per determinare il tipo di ogni parametro in una chiamata a una routine, un'applicazione chiama SQLProcedureColumns.
Per altre informazioni, vedere Descrizione dei parametri.
Esempio di codice
L'esempio seguente richiede all'utente un'istruzione SQL e quindi prepara tale istruzione. Chiama quindi SQLNumParams per determinare se l'istruzione contiene parametri. Se l'istruzione contiene parametri, chiama SQLDescribeParam per descrivere tali parametri e SQLBindParameter per associarli. Infine, richiede all'utente i valori di qualsiasi parametro e quindi esegue l'istruzione .
SQLCHAR Statement[100];
SQLSMALLINT NumParams, i, DataType, DecimalDigits, Nullable;
SQLUINTEGER ParamSize;
SQLHSTMT hstmt;
// Prompt the user for a SQL statement and prepare it.
GetSQLStatement(Statement);
SQLPrepare(hstmt, Statement, SQL_NTS);
// Check to see if there are any parameters. If so, process them.
SQLNumParams(hstmt, &NumParams);
if (NumParams) {
// Allocate memory for three arrays. The first holds pointers to buffers in which
// each parameter value will be stored in character form. The second contains the
// length of each buffer. The third contains the length/indicator value for each
// parameter.
SQLPOINTER * PtrArray = (SQLPOINTER *) malloc(NumParams * sizeof(SQLPOINTER));
SQLINTEGER * BufferLenArray = (SQLINTEGER *) malloc(NumParams * sizeof(SQLINTEGER));
SQLINTEGER * LenOrIndArray = (SQLINTEGER *) malloc(NumParams * sizeof(SQLINTEGER));
for (i = 0; i < NumParams; i++) {
// Describe the parameter.
SQLDescribeParam(hstmt, i + 1, &DataType, &ParamSize, &DecimalDigits, &Nullable);
// Call a helper function to allocate a buffer in which to store the parameter
// value in character form. The function determines the size of the buffer from
// the SQL data type and parameter size returned by SQLDescribeParam and returns
// a pointer to the buffer and the length of the buffer.
AllocParamBuffer(DataType, ParamSize, &PtrArray[i], &BufferLenArray[i]);
// Bind the memory to the parameter. Assume that we only have input parameters.
SQLBindParameter(hstmt, i + 1, SQL_PARAM_INPUT, SQL_C_CHAR, DataType, ParamSize,
DecimalDigits, PtrArray[i], BufferLenArray[i],
&LenOrIndArray[i]);
// Prompt the user for the value of the parameter and store it in the memory
// allocated earlier. For simplicity, this function does not check the value
// against the information returned by SQLDescribeParam. Instead, the driver does
// this when the statement is executed.
GetParamValue(PtrArray[i], BufferLenArray[i], &LenOrIndArray[i]);
}
}
// Execute the statement.
SQLExecute(hstmt);
// Process the statement further, such as retrieving results (if any) and closing the
// cursor (if any). Code not shown.
// Free the memory allocated for each parameter and the memory allocated for the arrays
// of pointers, buffer lengths, and length/indicator values.
for (i = 0; i < NumParams; i++) free(PtrArray[i]);
free(PtrArray);
free(BufferLenArray);
free(LenOrIndArray);
Funzioni correlate
| Per informazioni su | Vedere |
|---|---|
| Associazione di un buffer a un parametro | Funzione SQLBindParameter |
| Annullamento dell'elaborazione delle istruzioni | Funzione SQLCancel |
| Esecuzione di un'istruzione SQL preparata | Funzione SQLExecute |
| Preparazione di un'istruzione per l'esecuzione | Funzione SQLPrepare |