Condividi tramite

Pagina relativa alla funzione SQLBindParameter

  • Articolo

Conformità
Versione introdotta: Conformità agli standard ODBC 2.0: ODBC

Riepilogo
SQLBindParameter associa un buffer a un marcatore di parametro in un'istruzione SQL. SQLBindParameter supporta l'associazione a un tipo di dati Unicode C, anche se il driver sottostante non supporta i dati Unicode.

Nota

Questa funzione sostituisce la funzione ODBC 1.0 SQLSetParam. Per altre informazioni, vedere "Commenti".

Sintassi

  
SQLRETURN SQLBindParameter(  
      SQLHSTMT        StatementHandle,  
      SQLUSMALLINT    ParameterNumber,  
      SQLSMALLINT     InputOutputType,  
      SQLSMALLINT     ValueType,  
      SQLSMALLINT     ParameterType,  
      SQLULEN         ColumnSize,  
      SQLSMALLINT     DecimalDigits,  
      SQLPOINTER      ParameterValuePtr,  
      SQLLEN          BufferLength,  
      SQLLEN *        StrLen_or_IndPtr);

Argomenti

StatementHandle
[Input] Handle di istruzione.

ParameterNumber
[Input] Numero di parametro, ordinato in sequenza in ordine crescente dei parametri, a partire da 1.

InputOutputType
[Input] Tipo di parametro. Per altre informazioni, vedere "InputOutputType Argument" in "Comments".

ValueType
[Input] Tipo di dati C del parametro. Per altre informazioni, vedere "Argomento ValueType " in "Comments".

ParameterType
[Input] Tipo di dati SQL del parametro. Per altre informazioni, vedere "Argomento ParameterType " in "Comments".

ColumnSize
[Input] Dimensione della colonna o dell'espressione del marcatore di parametro corrispondente. Per altre informazioni, vedere "Argomento ColumnSize " in "Comments".

Se l'applicazione verrà eseguita in un sistema operativo Windows a 64 bit, vedere INFORMAZIONI SU ODBC a 64 bit.

DecimalDigits
[Input] Cifre decimali della colonna o dell'espressione del marcatore di parametro corrispondente. Per altre informazioni sulle dimensioni delle colonne, vedere Dimensioni delle colonne, Cifre decimali, Lunghezza ottetto di trasferimento e Dimensioni di visualizzazione.

ParameterValuePtr
[Input posticipato] Puntatore a un buffer per i dati del parametro. Per altre informazioni, vedere "ParameterValuePtr Argument" in "Comments".

BufferLength
[Input/Output] Lunghezza del buffer ParameterValuePtr in byte. Per altre informazioni, vedere "BufferLength Argument" in "Comments".

Vedere INFORMAZIONI SU ODBC a 64 bit, se l'applicazione verrà eseguita in un sistema operativo a 64 bit.

StrLen_or_IndPtr
[Input posticipato] Puntatore a un buffer per la lunghezza del parametro. Per altre informazioni, vedere "argomento StrLen_or_IndPtr " in "Commenti".

Valori restituiti

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR o SQL_INVALID_HANDLE.

Diagnostica

Quando SQLBindParameter 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 SQLBindParameter 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.
07006 Violazione dell'attributo del tipo di dati con restrizioni Il tipo di dati identificato dall'argomento ValueType non può essere convertito nel tipo di dati identificato dall'argomento ParameterType . Si noti che questo errore può essere restituito da SQLExecDirect, SQLExecute o SQLPutData in fase di esecuzione, anziché da SQLBindParameter.
07009 Indice descrittore non valido (DM) Il valore specificato per l'argomento ParameterNumber è minore di 1.
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.
HY003 Tipo di buffer dell'applicazione non valido Il valore specificato dall'argomento ValueType non è un tipo di dati C valido o SQL_C_DEFAULT.
HY004 Tipo di dati SQL non valido Il valore specificato per l'argomento ParameterType non era né un identificatore di tipo di dati SQL ODBC valido né un identificatore del tipo di dati SQL specifico del driver supportato dal driver.
HY009 Valore dell'argomento non valido (DM) L'argomento ParameterValuePtr era un puntatore Null, l'argomento StrLen_or_IndPtr era un puntatore Null e l'argomento InputOutputType non era SQL_PARAM_OUTPUT.

(DM) SQL_PARAM_OUTPUT, dove l'argomento ParameterValuePtr era un puntatore Null, il tipo C era char o binary e BufferLength (cbValueMax) era maggiore di 0.
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 è stato chiamato SQLBindParameter .

(DM) SQLExecute, SQLExecDirect o SQLMoreResults è stato chiamato per StatementHandle e restituito SQL_PARAM_DATA_AVAILABLE. Questa funzione è stata chiamata prima del recupero dei dati per tutti i parametri trasmessi.

(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.
HY021 Informazioni sul descrittore incoerente Le informazioni del descrittore controllate durante un controllo coerenza non sono coerenti. Vedere la sezione "Verifiche coerenza" in SQLSetDescField.

Il valore specificato per l'argomento DecimalDigits non è compreso nell'intervallo di valori supportati dall'origine dati per una colonna del tipo di dati SQL specificato dall'argomento ParameterType .
HY090 Lunghezza della stringa o del buffer non valida (DM) Il valore in BufferLength era minore di 0. Vedere la descrizione del campo SQL_DESC_DATA_PTR in SQLSetDescField.
HY104 Precisione o valore di scala non valido Il valore specificato per l'argomento ColumnSize o DecimalDigits non è compreso nell'intervallo di valori supportati dall'origine dati per una colonna del tipo di dati SQL specificato dall'argomento ParameterType .
HY105 Tipo di parametro non valido (DM) Il valore specificato per l'argomento InputOutputType non è valido. (Vedere "Comments.")
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 driver o l'origine dati non supporta la conversione specificata dalla combinazione del valore specificato per l'argomento ValueType e il valore specifico del driver specificato per l'argomento ParameterType.

Il valore specificato per l'argomento ParameterType è un identificatore di tipo di dati ODBC SQL valido per la versione di ODBC supportata dal driver, ma non è supportata dal driver o dall'origine dati.

Il driver supporta solo ODBC 2.x e l'argomento ValueType è uno dei seguenti:

SQL_C_NUMERIC SQL_C_SBIGINT SQL_C_UBIGINT

e tutti i tipi di dati C intervallo elencati in Tipi di dati C nell'Appendice D: Tipi di dati.

Il driver supporta solo le versioni ODBC precedenti alla 3.50 e l'argomento ValueType è stato SQL_C_GUID.
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.

Commenti

Un'applicazione chiama SQLBindParameter per associare ogni marcatore di parametro in un'istruzione SQL. Le associazioni rimangono attive finché l'applicazione non chiama di nuovo SQLBindParameter , chiama SQLFreeStmt con l'opzione SQL_RESET_PARAMS oppure chiama SQLSetDescField per impostare il campo di intestazione SQL_DESC_COUNT del APD su 0.

Per ulteriori informazioni sui parametri, vedere Parametri di istruzione. Per altre informazioni sui tipi di dati dei parametri e sui marcatori di parametro, vedere Parametri tipi di dati e marcatori di parametro nell'Appendice C: Grammatica SQL.

Argomento ParameterNumber

Se ParameterNumber nella chiamata a SQLBindParameter è maggiore del valore di SQL_DESC_COUNT, viene chiamato SQLSetDescField per aumentare il valore di SQL_DESC_COUNT a ParameterNumber.

Argomento InputOutputType

L'argomento InputOutputType specifica il tipo del parametro. Questo argomento imposta il campo SQL_DESC_PARAMETER_TYPE dell'IPD. Tutti i parametri nelle istruzioni SQL che non chiamano procedure, ad esempio le istruzioni INSERT, sono parametri di input. I parametri nelle chiamate di procedura possono essere parametri di input, input/output o output. (Chiamate di un'applicazioneSQLProcedureColumns per determinare il tipo di un parametro in una chiamata di routine. I parametri il cui tipo non può essere determinato vengono considerati parametri di input.

L'argomento InputOutputType è rappresentato da uno dei valori seguenti:

  • SQL_PARAM_INPUT. Il parametro contrassegna un parametro in un'istruzione SQL che non chiama una routine, ad esempio un'istruzione INSERT o contrassegna un parametro di input in una routine. Ad esempio, i parametri in INSERT INTO Employee VALUES (?, ?, ?) sono parametri di input, mentre i parametri in {call AddEmp(?, ?, ?)} possono essere, ma non necessariamente, parametri di input.

    Quando l'istruzione viene eseguita, il driver invia i dati per il parametro all'origine dati; il buffer *ParameterValuePtr deve contenere un valore di input valido oppure il buffer *StrLen_or_IndPtr deve contenere SQL_NULL_DATA, SQL_DATA_AT_EXEC o il risultato della macro SQL_LEN_DATA_AT_EXEC.

    Se un'applicazione non riesce a determinare il tipo di un parametro in una chiamata di routine, imposta InputOutputType su SQL_PARAM_INPUT; se l'origine dati restituisce un valore per il parametro, il driver lo rimuove.

  • SQL_PARAM_INPUT_OUTPUT. Il parametro contrassegna un parametro di input/output in una routine. Ad esempio, il parametro in {call GetEmpDept(?)} è un parametro di input/output che accetta il nome di un dipendente e restituisce il nome del reparto del dipendente.

    Quando l'istruzione viene eseguita, il driver invia i dati per il parametro all'origine dati; il buffer *ParameterValuePtr deve contenere un valore di input valido oppure il buffer *StrLen_or_IndPtr deve contenere SQL_NULL_DATA, SQL_DATA_AT_EXEC o il risultato della macro SQL_LEN_DATA_AT_EXEC. Dopo l'esecuzione dell'istruzione, il driver restituisce i dati per il parametro all'applicazione; se l'origine dati non restituisce un valore per un parametro di input/output, il driver imposta il buffer *StrLen_or_IndPtr su SQL_NULL_DATA.

    Nota

    Quando un'applicazione ODBC 1.0 chiama SQLSetParam in un driver ODBC 2.0, Gestione driver lo converte in una chiamata a SQLBindParameter in cui l'argomento InputOutputType è impostato su SQL_PARAM_INPUT_OUTPUT.

  • SQL_PARAM_OUTPUT. Il parametro contrassegna il valore restituito di una routine o di un parametro di output in una routine; in entrambi i casi, questi parametri sono noti come parametri di output. Ad esempio, il parametro in {?=call GetNextEmpID} è un parametro di output che restituisce l'ID dipendente successivo.

    Dopo l'esecuzione dell'istruzione, il driver restituisce i dati per il parametro all'applicazione, a meno che gli argomenti ParameterValuePtr e StrLen_or_IndPtr siano entrambi puntatori Null, nel qual caso il driver rimuove il valore di output. Se l'origine dati non restituisce un valore per un parametro di output, il driver imposta il buffer *StrLen_or_IndPtr su SQL_NULL_DATA.

  • SQL_PARAM_INPUT_OUTPUT_STREAM. Indica che deve essere trasmesso un parametro di input/output. SQLGetData può leggere i valori dei parametri nelle parti. BufferLength viene ignorato perché la lunghezza del buffer verrà determinata alla chiamata di SQLGetData. Il valore del buffer di StrLen_or_IndPtr deve contenere SQL_NULL_DATA, SQL_DEFAULT_PARAM, SQL_DATA_AT_EXEC o il risultato della macro SQL_LEN_DATA_AT_EXEC. Un parametro deve essere associato come parametro DAE (Data-At-Execution) all'input se verrà trasmesso all'output. ParameterValuePtr può essere qualsiasi valore puntatore non Null che verrà restituito da SQLParamData come token definito dall'utente il cui valore è stato passato con ParameterValuePtr per input e output. Per altre informazioni, vedere Recupero di parametri di output tramite SQLGetData.

  • SQL_PARAM_OUTPUT_STREAM. Uguale a SQL_PARAM_INPUT_OUTPUT_STREAM, per un parametro di output. * StrLen_or_IndPtr viene ignorato all'input.

Nella tabella seguente sono elencate diverse combinazioni di InputOutputType e *StrLen_or_IndPtr:

InputOutputType *StrLen_or_IndPtr Risultato Osservazioni su ParameterValuePtr
SQL_PARAM_INPUT SQL_LEN_DATA_AT_EXEC(len) o SQL_DATA_AT_EXEC Input in parti ParameterValuePtr può essere qualsiasi valore del puntatore che verrà restituito da SQLParamData come token definito dall'utente il cui valore è stato passato con ParameterValuePtr.
SQL_PARAM_INPUT Non SQL_LEN_DATA_AT_EXEC(len) o SQL_DATA_AT_EXEC Buffer associato all'input ParameterValuePtr è l'indirizzo del buffer di input.
SQL_PARAM_OUTPUT Ignorato all'input. Buffer associato all'output ParameterValuePtr è l'indirizzo del buffer di output.
SQL_PARAM_OUTPUT_STREAM Ignorato all'input. Output trasmesso ParameterValuePtr può essere qualsiasi valore del puntatore, che verrà restituito da SQLParamData come token definito dall'utente il cui valore è stato passato con ParameterValuePtr.
SQL_PARAM_INPUT_OUTPUT SQL_LEN_DATA_AT_EXEC(len) o SQL_DATA_AT_EXEC Input in parti e buffer associato all'output ParameterValuePtr è l'indirizzo del buffer di output, che verrà restituito anche da SQLParamData come token definito dall'utente il cui valore è stato passato con ParameterValuePtr.
SQL_PARAM_INPUT_OUTPUT Non SQL_LEN_DATA_AT_EXEC(len) o SQL_DATA_AT_EXEC Buffer associato all'input e buffer associato all'output ParameterValuePtr è l'indirizzo del buffer di input/output condiviso.
SQL_PARAM_INPUT_OUTPUT_STREAM SQL_LEN_DATA_AT_EXEC(len) o SQL_DATA_AT_EXEC Input in parti e output trasmesso ParameterValuePtr può essere qualsiasi valore puntatore non Null, che verrà restituito da SQLParamData come token definito dall'utente il cui valore è stato passato con ParameterValuePtr per input e output.

Nota

Il driver deve decidere quali tipi SQL sono consentiti quando un'applicazione associa un parametro di output o di output di input come trasmesso. Gestione driver non genererà un errore per un tipo SQL non valido.

Argomento ValueType

L'argomento ValueType specifica il tipo di dati C del parametro . Questo argomento imposta i campi SQL_DESC_TYPE, SQL_DESC_CONCISE_TYPE e SQL_DESC_DATETIME_INTERVAL_CODE dell'APD. Deve essere uno dei valori nella sezione Tipi di dati C dell'Appendice D: Tipi di dati.

Se l'argomento ValueType è uno dei tipi di dati interval, il campo SQL_DESC_TYPE del record ParameterNumber dell'APD viene impostato su SQL_INTERVAL, il campo SQL_DESC_CONCISE_TYPE del APD viene impostato sul tipo di dati intervallo conciso e il campo SQL_DESC_DATETIME_INTERVAL_CODE del record ParameterNumber viene impostato su un sottocodice per il tipo di dati intervallo specifico. (Vedere Appendice D: Tipi di dati. La precisione iniziale dell'intervallo predefinito (2) e la precisione dei secondi di intervallo predefinita (6), come impostato nei campi SQL_DESC_DATETIME_INTERVAL_PRECISION e SQL_DESC_PRECISION rispettivamente del APD, vengono usati per i dati. Se la precisione predefinita non è appropriata, l'applicazione deve impostare in modo esplicito il campo descrittore tramite una chiamata a SQLSetDescField o SQLSetDescRec.

Se l'argomento ValueType è uno dei tipi di dati datetime, il campo SQL_DESC_TYPE del record ParameterNumber dell'APD viene impostato su SQL_DATETIME, il campo SQL_DESC_CONCISE_TYPE del record ParameterNumber dell'APD viene impostato sul tipo di dati datetime C conciso e il campo SQL_DESC_DATETIME_INTERVAL_CODE del record ParameterNumber viene impostato su un codice secondario per il tipo di dati datetime specifico. (Vedere Appendice D: Tipi di dati.

Se l'argomento ValueType è un tipo di dati SQL_C_NUMERIC, la precisione predefinita (definita dal driver) e la scala predefinita (0), come impostato nei campi SQL_DESC_PRECISION e SQL_DESC_SCALE del APD, vengono utilizzati per i dati. Se la precisione o la scala predefinita non è appropriata, l'applicazione deve impostare in modo esplicito il campo descrittore tramite una chiamata a SQLSetDescField o SQLSetDescRec.

SQL_C_DEFAULT specifica che il valore del parametro deve essere trasferito dal tipo di dati C predefinito per il tipo di dati SQL specificato con ParameterType.

È anche possibile specificare un tipo di dati C esteso. Per altre informazioni, vedere Tipi di dati C in ODBC.

Per altre informazioni, vedere Tipi di dati C predefiniti, Conversione di dati da C a tipi di dati SQL e conversione di dati da SQL a tipi di dati C nell'Appendice D: Tipi di dati.

Argomento ParameterType

Deve essere uno dei valori elencati nella sezione Tipi di dati SQL dell'Appendice D: Tipi di dati oppure deve essere un valore specifico del driver. Questo argomento imposta i campi SQL_DESC_TYPE, SQL_DESC_CONCISE_TYPE e SQL_DESC_DATETIME_INTERVAL_CODE dell'IPD.

Se l'argomento ParameterType è uno degli identificatori datetime, il campo SQL_DESC_TYPE dell'IPD viene impostato su SQL_DATETIME, il campo SQL_DESC_CONCISE_TYPE dell'IPD viene impostato sul tipo di dati SQL datetime conciso e il campo SQL_DESC_DATETIME_INTERVAL_CODE viene impostato sul valore del codice secondario datetime appropriato.

Se ParameterType è uno degli identificatori di intervallo, il campo SQL_DESC_TYPE dell'IPD viene impostato su SQL_INTERVAL, il campo SQL_DESC_CONCISE_TYPE dell'IPD viene impostato sul tipo di dati intervallo SQL conciso e il campo SQL_DESC_DATETIME_INTERVAL_CODE dell'IPD viene impostato sul codice secondario dell'intervallo appropriato. Il campo SQL_DESC_DATETIME_INTERVAL_PRECISION dell'IPD viene impostato sulla precisione iniziale dell'intervallo e il campo SQL_DESC_PRECISION viene impostato sulla precisione dei secondi di intervallo, se applicabile. Se il valore predefinito di SQL_DESC_DATETIME_INTERVAL_PRECISION o SQL_DESC_PRECISION non è appropriato, l'applicazione deve impostarla in modo esplicito chiamando SQLSetDescField. Per altre informazioni su uno di questi campi, vedere SQLSetDescField.

Se l'argomento ValueType è un tipo di dati SQL_NUMERIC, la precisione predefinita (definita dal driver) e la scala predefinita (0), come impostato nei campi SQL_DESC_PRECISION e SQL_DESC_SCALE dell'IPD, vengono usati per i dati. Se la precisione o la scala predefinita non è appropriata, l'applicazione deve impostare in modo esplicito il campo descrittore tramite una chiamata a SQLSetDescField o SQLSetDescRec.

Per informazioni sulla modalità di conversione dei dati, vedere Conversione di dati da C a tipi di dati SQL e conversione di dati da SQL a tipi di dati C nell'Appendice D: Tipi di dati.

Argomento ColumnSize

L'argomento ColumnSize specifica le dimensioni della colonna o dell'espressione che corrisponde all'indicatore di parametro, alla lunghezza dei dati o a entrambi. Questo argomento imposta campi diversi dell'IPD, a seconda del tipo di dati SQL (argomento ParameterType ). A questo mapping si applicano le regole seguenti:

  • Se ParameterType è SQL_CHAR, SQL_VARCHAR, SQL_LONGVARCHAR, SQL_BINARY, SQL_VARBINARY, SQL_LONGVARBINARY o uno dei tipi di dati datetime o interval SQL concisi, il campo SQL_DESC_LENGTH dell'IPD viene impostato sul valore di ColumnSize. Per altre informazioni, vedere Dimensione colonna, Cifre decimali, Lunghezza ottetto trasferimento e sezione Dimensioni visualizzazione nell'Appendice D: Tipi di dati.

  • Se ParameterType è SQL_DECIMAL, SQL_NUMERIC, SQL_FLOAT, SQL_REAL o SQL_DOUBLE, il campo SQL_DESC_PRECISION dell'IPD viene impostato sul valore di ColumnSize.

  • Per altri tipi di dati, l'argomento ColumnSize viene ignorato.

Per altre informazioni, vedere "Passaggio dei valori dei parametri" e SQL_DATA_AT_EXEC in "argomento StrLen_or_IndPtr ".

Argomento DecimalDigits

Se ParameterType è SQL_TYPE_TIME, SQL_TYPE_TIMESTAMP, SQL_INTERVAL_SECOND, SQL_INTERVAL_DAY_TO_SECOND, SQL_INTERVAL_HOUR_TO_SECOND o SQL_INTERVAL_MINUTE_TO_SECOND, il campo SQL_DESC_PRECISION dell'IPD viene impostato su DecimalDigits. Se ParameterType è SQL_NUMERIC o SQL_DECIMAL, il campo SQL_DESC_SCALE dell'IPD viene impostato su DecimalDigits. Per tutti gli altri tipi di dati, l'argomento DecimalDigits viene ignorato.

Argomento ParameterValuePtr

L'argomento ParameterValuePtr punta a un buffer che, quando viene chiamato SQLExecute o SQLExecDirect , contiene i dati effettivi per il parametro. I dati devono essere nel formato specificato dall'argomento ValueType . Questo argomento imposta il campo SQL_DESC_DATA_PTR di APD. Un'applicazione può impostare l'argomento ParameterValuePtr su un puntatore Null, purché *StrLen_or_IndPtr sia SQL_NULL_DATA o SQL_DATA_AT_EXEC. Questo vale solo per i parametri di input o input/output.

Se *StrLen_or_IndPtr è il risultato della macro SQL_LEN_DATA_AT_EXEC(length) o SQL_DATA_AT_EXEC, ParameterValuePtr è un valore del puntatore definito dall'applicazione associato al parametro . Viene restituito all'applicazione tramite SQLParamData. Ad esempio, ParameterValuePtr potrebbe essere un token diverso da zero, ad esempio un numero di parametro, un puntatore ai dati o un puntatore a una struttura usata dall'applicazione per associare i parametri di input. Si noti tuttavia che se il parametro è un parametro di input/output, ParameterValuePtr deve essere un puntatore a un buffer in cui verrà archiviato il valore di output. Se il valore nell'attributo dell'istruzione SQL_ATTR_PARAMSET_SIZE è maggiore di 1, l'applicazione può usare il valore a cui punta l'attributo dell'istruzione SQL_ATTR_PARAMS_PROCESSED_PTR insieme all'argomento ParameterValuePtr . Ad esempio, ParameterValuePtr potrebbe puntare a una matrice di valori e l'applicazione potrebbe usare il valore a cui punta SQL_ATTR_PARAMS_PROCESSED_PTR per recuperare il valore corretto dalla matrice. Per altre informazioni, vedere "Passaggio dei valori dei parametri" più avanti in questa sezione.

Se l'argomento InputOutputType è SQL_PARAM_INPUT_OUTPUT o SQL_PARAM_OUTPUT, ParameterValuePtr punta a un buffer in cui il driver restituisce il valore di output. Se la routine restituisce uno o più set di risultati, non è garantito che il buffer *ParameterValuePtr venga impostato fino a quando non vengono elaborati tutti i set di risultati/conteggi di righe. Se il buffer non viene impostato fino al completamento dell'elaborazione, i parametri di output e i valori restituiti non sono disponibili finché SQLMoreResults non restituisce SQL_NO_DATA. La chiamata a SQLCloseCursor o SQLFreeStmt con un'opzione di SQL_CLOSE causerà l'eliminazione di questi valori.

Se il valore nell'attributo dell'istruzione SQL_ATTR_PARAMSET_SIZE è maggiore di 1, ParameterValuePtr punta a una matrice. Una singola istruzione SQL elabora la matrice completa di valori di input per un parametro di input o input/output e restituisce una matrice di valori di output per un parametro di input/output o di output.

Argomento BufferLength

Per i dati C di tipo carattere e binario, l'argomento BufferLength specifica la lunghezza del buffer *ParameterValuePtr (se è un singolo elemento) o la lunghezza di un elemento nella matrice *ParameterValuePtr (se il valore nell'attributo dell'istruzione SQL_ATTR_PARAMSET_SIZE è maggiore di 1). Questo argomento imposta il campo record SQL_DESC_OCTET_LENGTH del APD. Se l'applicazione specifica più valori, BufferLength viene usato per determinare la posizione dei valori nella matrice *ParameterValuePtr , sia nell'input che nell'output. Per i parametri di input/output e di output, viene usato per determinare se troncare i dati di carattere e binari C nell'output:

  • Per i dati C di tipo carattere, se il numero di byte disponibili per la restituzione è maggiore o uguale a BufferLength, i dati in *ParameterValuePtr vengono troncati a BufferLength meno la lunghezza di un carattere di terminazione Null e terminano con null dal driver.

  • Per i dati C binari, se il numero di byte disponibili per la restituzione è maggiore di BufferLength, i dati in *ParameterValuePtr vengono troncati in byte BufferLength .

Per tutti gli altri tipi di dati C, l'argomento BufferLength viene ignorato. La lunghezza del buffer *ParameterValuePtr (se è un singolo elemento) o la lunghezza di un elemento nella matrice *ParameterValuePtr (se l'applicazione chiama SQLSetStmtAttr con un argomento Attribute di SQL_ATTR_PARAMSET_SIZE per specificare più valori per ogni parametro) viene considerata la lunghezza del tipo di dati C.

Per i parametri di input/output trasmessi in streaming, l'argomento BufferLength viene ignorato perché la lunghezza del buffer è specificata in SQLGetData.

Nota

Quando un'applicazione ODBC 1.0 chiama SQLSetParam in odbc 3.Driver x , Gestione driver converte questo valore in una chiamata a SQLBindParameter in cui l'argomento BufferLength è sempre SQL_SETPARAM_VALUE_MAX. Poiché Gestione driver restituisce un errore se odbc 3.x application imposta BufferLength su SQL_SETPARAM_VALUE_MAX, odbc 3.X Driver può usare questa opzione per determinare quando viene chiamata da un'applicazione ODBC 1.0.

Nota

In SQLSetParam, il modo in cui un'applicazione specifica la lunghezza del buffer *ParameterValuePtr in modo che il driver possa restituire dati di tipo carattere o binario e il modo in cui un'applicazione invia una matrice di valori di parametri di tipo carattere o binario al driver, sono definiti dal driver.

argomento StrLen_or_IndPtr

L'argomento StrLen_or_IndPtr punta a un buffer che, quando viene chiamato SQLExecute o SQLExecDirect, contiene uno dei seguenti elementi. Questo argomento imposta i campi SQL_DESC_OCTET_LENGTH_PTR e SQL_DESC_INDICATOR_PTR record dei puntatori ai parametri dell'applicazione.

  • Lunghezza del valore del parametro archiviato in *ParameterValuePtr. Questa operazione viene ignorata, ad eccezione dei dati C di tipo carattere o binario.

  • SQL_NTS. Il valore del parametro è una stringa con terminazione Null.

  • SQL_NULL_DATA. Il valore del parametro è NULL.

  • SQL_DEFAULT_PARAM. Una routine consiste nell'usare il valore predefinito di un parametro, anziché un valore recuperato dall'applicazione. Questo valore è valido solo in una routine chiamata nella sintassi canonica ODBC e quindi solo se l'argomento InputOutputType è SQL_PARAM_INPUT, SQL_PARAM_INPUT_OUTPUT o SQL_PARAM_INPUT_OUTPUT_STREAM. Quando *StrLen_or_IndPtr è SQL_DEFAULT_PARAM, gli argomenti ValueType, ParameterType, ColumnSize, DecimalDigits, BufferLength e ParameterValuePtr vengono ignorati per i parametri di input e vengono usati solo per definire il valore del parametro di output per i parametri di input/output.

  • Risultato della macro SQL_LEN_DATA_AT_EXEC(length). I dati per il parametro verranno inviati con SQLPutData. Se l'argomento ParameterType è SQL_LONGVARBINARY, SQL_LONGVARCHAR o un tipo di dati specifico dell'origine dati long e il driver restituisce "Y" per il tipo di informazioni SQL_NEED_LONG_DATA_LEN in SQLGetInfo, la lunghezza è il numero di byte di dati da inviare per il parametro. In caso contrario, la lunghezza deve essere un valore non negativo e viene ignorata. Per altre informazioni, vedere "Passaggio dei valori dei parametri" più avanti in questa sezione.

    Ad esempio, per specificare che verranno inviati 10.000 byte di dati con SQLPutData in una o più chiamate, per un parametro SQL_LONGVARCHAR, un'applicazione imposta *StrLen_or_IndPtr su SQL_LEN_DATA_AT_EXEC(10000).

  • SQL_DATA_AT_EXEC. I dati per il parametro verranno inviati con SQLPutData. Questo valore viene usato dalle applicazioni ODBC 1.0 quando chiamano ODBC 3.x driver. Per altre informazioni, vedere "Passaggio dei valori dei parametri" più avanti in questa sezione.

Se StrLen_or_IndPtr è un puntatore Null, il driver presuppone che tutti i valori dei parametri di input siano non NULL e che i dati di tipo carattere e binario vengano terminati con null. Se InputOutputType è SQL_PARAM_OUTPUT o SQL_PARAM_OUTPUT_STREAM e ParameterValuePtr e StrLen_or_IndPtr sono entrambi puntatori Null, il driver rimuove il valore di output.

Nota

Gli sviluppatori di applicazioni sono fortemente sconsigliati di specificare un puntatore Null per StrLen_or_IndPtr quando il tipo di dati del parametro è SQL_C_BINARY. Per assicurarsi che un driver non tronca in modo imprevisto SQL_C_BINARY dati, StrLen_or_IndPtr deve contenere un puntatore a un valore di lunghezza valido.

Se l'argomento InputOutputType è SQL_PARAM_INPUT_OUTPUT, SQL_PARAM_OUTPUT, SQL_PARAM_INPUT_OUTPUT_STREAM o SQL_PARAM_OUTPUT_STREAM, StrLen_or_IndPtr punta a un buffer in cui il driver restituisce SQL_NULL_DATA, il numero di byte disponibili per la restituzione in *ParameterValuePtr (escluso il byte di terminazione null dei dati di tipo carattere) o SQL_NO_TOTAL (se non è possibile determinare il numero di byte disponibili per la restituzione). Se la procedura restituisce uno o più set di risultati, il buffer *StrLen_or_IndPtr non viene garantito di essere impostato fino a quando non vengono recuperati tutti i risultati.

Se il valore nell'attributo dell'istruzione SQL_ATTR_PARAMSET_SIZE è maggiore di 1, StrLen_or_IndPtr punta a una matrice di valori SQLLEN. Questi valori possono essere uno qualsiasi dei valori elencati in precedenza in questa sezione e vengono elaborati con una singola istruzione SQL.

Passaggio dei valori dei parametri

Un'applicazione può passare il valore di un parametro nel buffer *ParameterValuePtr o con una o più chiamate a SQLPutData. I parametri i cui dati vengono passati con SQLPutData sono noti come parametri di data-at-execution . Questi vengono in genere usati per inviare dati per i parametri SQL_LONGVARBINARY e SQL_LONGVARCHAR e possono essere misti con altri parametri.

Per passare i valori dei parametri, un'applicazione esegue la sequenza di passaggi seguente:

  1. Chiama SQLBindParameter per ogni parametro per associare buffer per il valore del parametro (argomento ParameterValuePtr ) e length/indicator (argomento StrLen_or_IndPtr ). Per i parametri data-at-execution, ParameterValuePtr è un valore puntatore definito dall'applicazione, ad esempio un numero di parametro o un puntatore ai dati. Il valore verrà restituito in un secondo momento e può essere usato per identificare il parametro.

  2. Inserisce i valori per i parametri di input e input/output nei buffer *ParameterValuePtr e *StrLen_or_IndPtr:

    • Per i parametri normali, l'applicazione inserisce il valore del parametro nel buffer *ParameterValuePtr e la lunghezza di tale valore nel buffer *StrLen_or_IndPtr . Per altre informazioni, vedere Impostazione dei valori dei parametri.

    • Per i parametri data-at-execution, l'applicazione inserisce il risultato della macro SQL_LEN_DATA_AT_EXEC(lunghezza) (quando si chiama un driver ODBC 2.0) nel buffer *StrLen_or_IndPtr .

  3. Chiama SQLExecute o SQLExecDirect per eseguire l'istruzione SQL.

    • Se non sono presenti parametri di data-at-execution, il processo viene completato.

    • Se sono presenti parametri di data-at-execution, la funzione restituisce SQL_NEED_DATA.

  4. Chiama SQLParamData per recuperare il valore definito dall'applicazione specificato nell'argomento ParameterValuePtr di SQLBindParameter per il primo parametro data-at-execution da elaborare. SQLParamData restituisce SQL_NEED_DATA.

    Nota

    Sebbene i parametri di data-at-execution siano simili alle colonne data-at-execution, il valore restituito da SQLParamData è diverso per ognuno di essi. I parametri data-at-execution sono parametri in un'istruzione SQL per cui i dati verranno inviati con SQLPutData quando l'istruzione viene eseguita con SQLExecDirect o SQLExecute. Sono associati a SQLBindParameter. Il valore restituito da SQLParamData è un valore del puntatore passato a SQLBindParameter nell'argomento ParameterValuePtr . Le colonne data-at-execution sono colonne in un set di righe per cui i dati verranno inviati con SQLPutData quando una riga viene aggiornata o aggiunta con SQLBulkOperations o aggiornata con SQLSetPos. Sono associati a SQLBindCol. Il valore restituito da SQLParamData è l'indirizzo della riga nel buffer *TargetValuePtr (impostato da una chiamata a SQLBindCol) che viene elaborato.

  5. Chiama SQLPutData una o più volte per inviare dati per il parametro . Se il valore dei dati è maggiore del buffer *ParameterValuePtr specificato in SQLPutData, sono necessarie più chiamate a SQLPutData per lo stesso parametro solo quando si inviano dati C carattere a una colonna con un tipo di dati di tipo carattere, binario o specifico dell'origine dati o quando si inviano dati C binari a una colonna con un carattere, tipo di dati binario o specifico dell'origine dati.

  6. Chiama di nuovo SQLParamData per segnalare che tutti i dati sono stati inviati per il parametro .

    • Se sono presenti più parametri di data-at-execution, SQLParamData restituisce SQL_NEED_DATA e il valore definito dall'applicazione per il parametro data-at-execution successivo da elaborare. L'applicazione ripete i passaggi 4 e 5.

    • Se non sono presenti altri parametri di data-at-execution, il processo viene completato. Se l'istruzione è stata eseguita correttamente, SQLParamData restituisce SQL_SUCCESS o SQL_SUCCESS_WITH_INFO; se l'esecuzione non è riuscita, restituisce SQL_ERROR. A questo punto, SQLParamData può restituire qualsiasi SQLSTATE che può essere restituito dalla funzione usata per eseguire l'istruzione (SQLExecDirect o SQLExecute).

      I valori di output per tutti i parametri di input/output o di output sono disponibili nei buffer *ParameterValuePtr e *StrLen_or_IndPtr dopo che l'applicazione recupera tutti i set di risultati generati dall'istruzione .

La chiamata a SQLExecute o SQLExecDirect inserisce l'istruzione in uno stato SQL_NEED_DATA. A questo punto, l'applicazione può chiamare solo SQLCancel, SQLGetDiagField, SQLGetDiagRec, SQLGetFunctions, SQLParamData o SQLPutData con l'istruzione o l'handle di connessione associato all'istruzione . Se chiama qualsiasi altra funzione con l'istruzione o la connessione associata all'istruzione , la funzione restituisce SQLSTATE HY010 (errore di sequenza di funzione). L'istruzione lascia lo stato SQL_NEED_DATA quando SQLParamData o SQLPutData restituisce un errore, SQLParamData restituisce SQL_SUCCESS o SQL_SUCCESS_WITH_INFO oppure l'istruzione viene annullata.

Se l'applicazione chiama SQLCancel mentre il driver necessita ancora di dati per i parametri di data-at-execution, il driver annulla l'esecuzione dell'istruzione. L'applicazione può quindi chiamare di nuovo SQLExecute o SQLExecDirect .

Recupero di parametri di output trasmessi

Quando un'applicazione imposta InputOutputType su SQL_PARAM_INPUT_OUTPUT_STREAM o SQL_PARAM_OUTPUT_STREAM, il valore del parametro di output deve essere recuperato da una o più chiamate a SQLGetData. Quando il driver ha un valore del parametro di output trasmesso per tornare all'applicazione, restituirà SQL_PARAM_DATA_AVAILABLE in risposta a una chiamata alle funzioni seguenti: SQLMoreResults, SQLExecute e SQLExecDirect. Un'applicazione chiama SQLParamData per determinare il valore del parametro disponibile.

Per altre informazioni sui parametri di output SQL_PARAM_DATA_AVAILABLE e trasmessi, vedere Recupero di parametri di output tramite SQLGetData.

Uso delle matrici di parametri

Quando un'applicazione prepara un'istruzione con marcatori di parametro e passa una matrice di parametri, è possibile eseguire questa operazione in due modi diversi. Un modo consiste nel fare in modo che il driver si basi sulle funzionalità di elaborazione matrice del back-end, nel qual caso l'intera istruzione con la matrice di parametri viene considerata come un'unità atomica. Oracle è un esempio di origine dati che supporta le funzionalità di elaborazione delle matrici. Un altro modo per implementare questa funzionalità consiste nel generare un batch di istruzioni SQL, un'istruzione SQL per ogni set di parametri nella matrice di parametri ed eseguire il batch. Non è possibile utilizzare matrici di parametri con un'istruzione UPDATE WHERE CURRENT OF .

Quando viene elaborata una matrice di parametri, è possibile eseguire il rollup di singoli set di risultati/conteggi di righe (uno per ogni set di parametri) oppure è possibile eseguire il rollup di set di risultati/righe. L'opzione SQL_PARAM_ARRAY_ROW_COUNTS in SQLGetInfo indica se i conteggi delle righe sono disponibili per ogni set di parametri (SQL_PARC_BATCH) o se è disponibile un solo numero di righe (SQL_PARC_NO_BATCH).

L'opzione SQL_PARAM_ARRAY_SELECTS in SQLGetInfo indica se un set di risultati è disponibile per ogni set di parametri (SQL_PAS_BATCH) o se è disponibile un solo set di risultati (SQL_PAS_NO_BATCH). Se il driver non consente l'esecuzione di un'istruzione di generazione del set di risultati con una matrice di parametri, SQL_PARAM_ARRAY_SELECTS restituisce SQL_PAS_NO_SELECT.

Per altre informazioni, vedere Funzione SQLGetInfo.

Per supportare matrici di parametri, l'attributo dell'istruzione SQL_ATTR_PARAMSET_SIZE è impostato per specificare il numero di valori per ogni parametro. Se il campo è maggiore di 1, il SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR e i campi SQL_DESC_OCTET_LENGTH_PTR del APD devono puntare a matrici. La cardinalità di ogni matrice è uguale al valore di SQL_ATTR_PARAMSET_SIZE.

Il campo SQL_DESC_ROWS_PROCESSED_PTR dell'APD punta a un buffer contenente il numero di set di parametri elaborati, inclusi i set di errori. Durante l'elaborazione di ogni set di parametri, il driver archivia un nuovo valore nel buffer. Se si tratta di un puntatore Null, non verrà restituito alcun numero. Quando vengono utilizzate matrici di parametri, il valore a cui punta il campo SQL_DESC_ROWS_PROCESSED_PTR del APD viene popolato anche se SQL_ERROR viene restituito dalla funzione di impostazione. Se viene restituito SQL_NEED_DATA, il valore a cui punta il campo SQL_DESC_ROWS_PROCESSED_PTR del APD viene impostato sul set di parametri elaborati.

Ciò che si verifica quando viene associata una matrice di parametri e viene eseguita un'istruzione UPDATE WHERE CURRENT OF viene definita dal driver.

Associazione di parametri a livello di colonna

Nell'associazione a livello di colonna, l'applicazione associa matrici di parametri e indicatori/lunghezza separati a ogni parametro.

Per usare l'associazione a livello di colonna, l'applicazione imposta innanzitutto l'attributo dell'istruzione SQL_ATTR_PARAM_BIND_TYPE su SQL_PARAM_BIND_BY_COLUMN. Questa è l'impostazione predefinita. Per associare ogni colonna, l'applicazione esegue i passaggi seguenti:

  1. Alloca una matrice di buffer dei parametri.

  2. Alloca una matrice di buffer di lunghezza/indicatore.

    Nota

    Se l'applicazione scrive direttamente nei descrittori quando viene usata l'associazione a livello di colonna, è possibile usare matrici separate per i dati di lunghezza e indicatore.

  3. Chiama SQLBindParameter con gli argomenti seguenti:

    • ValueType è il tipo C di un singolo elemento nella matrice di buffer dei parametri.

    • ParameterType è il tipo SQL del parametro .

    • ParameterValuePtr è l'indirizzo della matrice di buffer dei parametri.

    • BufferLength è la dimensione di un singolo elemento nella matrice di buffer dei parametri. L'argomento BufferLength viene ignorato quando i dati sono a lunghezza fissa.

    • StrLen_or_IndPtr è l'indirizzo della matrice di lunghezza/indicatore.

Per altre informazioni sull'uso di queste informazioni, vedere "ParameterValuePtr Argument" in "Comments" più avanti in questa sezione. Per altre informazioni sull'associazione a colonne di parametri, vedere Binding Arrays of Parameters.

Associazione di parametri row-wise

Nell'associazione a livello di riga, l'applicazione definisce una struttura che contiene buffer di parametri e lunghezza/indicatore per ogni parametro da associare.

Per usare l'associazione a livello di riga, l'applicazione esegue i passaggi seguenti:

  1. Definisce una struttura per contenere un singolo set di parametri (inclusi i buffer di parametri e di lunghezza/indicatore) e alloca una matrice di queste strutture.

    Nota

    Se l'applicazione scrive direttamente nei descrittori quando viene usata l'associazione a livello di riga, è possibile usare campi separati per i dati di lunghezza e indicatore.

  2. Imposta l'attributo dell'istruzione SQL_ATTR_PARAM_BIND_TYPE sulle dimensioni della struttura che contiene un singolo set di parametri o sulle dimensioni di un'istanza di un buffer in cui verranno associati i parametri. La lunghezza deve includere spazio per tutti i parametri associati e qualsiasi spaziatura interna della struttura o del buffer, per assicurarsi che quando l'indirizzo di un parametro associato viene incrementato con la lunghezza specificata, il risultato punterà all'inizio dello stesso parametro nella riga successiva. Quando si usa l'operatore sizeof in ANSI C, questo comportamento è garantito.

  3. Chiama SQLBindParameter con gli argomenti seguenti per ogni parametro da associare:

    • ValueType è il tipo del membro del buffer dei parametri da associare alla colonna.

    • ParameterType è il tipo SQL del parametro .

    • ParameterValuePtr è l'indirizzo del membro del buffer dei parametri nel primo elemento della matrice.

    • BufferLength è la dimensione del membro del buffer dei parametri.

    • StrLen_or_IndPtr è l'indirizzo del membro di lunghezza/indicatore da associare.

Per altre informazioni sull'uso di queste informazioni, vedere "ParameterValuePtr Argument" più avanti in questa sezione. Per altre informazioni sull'associazione a livello di riga dei parametri, vedere Binding Arrays of Parameters.

Informazioni sull'errore

Se un driver non implementa matrici di parametri come batch (l'opzione SQL_PARAM_ARRAY_ROW_COUNTS è uguale a SQL_PARC_NO_BATCH), le situazioni di errore vengono gestite come se fosse stata eseguita un'istruzione. Se il driver implementa matrici di parametri come batch, un'applicazione può usare il campo intestazione SQL_DESC_ARRAY_STATUS_PTR dell'IPD per determinare quale parametro di un'istruzione SQL o quale parametro in una matrice di parametri ha causato la restituzione di un errore in SQLExecDirect o SQLExecute . Questo campo contiene informazioni sullo stato per ogni riga di valori di parametro. Se il campo indica che si è verificato un errore, i campi nella struttura dei dati di diagnostica indicherà la riga e il numero di parametro del parametro non riuscito. Il numero di elementi nella matrice verrà definito dal campo di intestazione SQL_DESC_ARRAY_SIZE nel APD, che può essere impostato dall'attributo dell'istruzione SQL_ATTR_PARAMSET_SIZE.

Nota

Il campo intestazione SQL_DESC_ARRAY_STATUS_PTR nel APD viene usato per ignorare i parametri. Per altre informazioni sull'esclusione dei parametri, vedere la sezione successiva "Ignora un set di parametri".

Quando SQLExecute o SQLExecDirect restituisce SQL_ERROR, gli elementi della matrice a cui punta il campo SQL_DESC_ARRAY_STATUS_PTR nell'IPD conterranno SQL_PARAM_ERROR, SQL_PARAM_SUCCESS, SQL_PARAM_SUCCESS_WITH_INFO, SQL_PARAM_UNUSED o SQL_PARAM_DIAG_UNAVAILABLE.

Per ogni elemento in questa matrice, la struttura dei dati di diagnostica contiene uno o più record di stato. Il campo SQL_DIAG_ROW_NUMBER della struttura indica il numero di riga dei valori dei parametri che hanno causato l'errore. Se è possibile determinare il parametro specifico in una riga di parametri che ha causato l'errore, il numero di parametro verrà immesso nel campo SQL_DIAG_COLUMN_NUMBER.

SQL_PARAM_UNUSED viene immesso quando non è stato usato un parametro perché si è verificato un errore in un parametro precedente che ha forzato SQLExecute o SQLExecDirect ad interrompere l'interruzione. Ad esempio, se sono presenti 50 parametri e si è verificato un errore durante l'esecuzione del primo set di parametri che hanno causato l'interruzione di SQLExecute o SQLExecDirect , SQL_PARAM_UNUSED viene immesso nella matrice di stato per i parametri da 41 a 50.

SQL_PARAM_DIAG_UNAVAILABLE viene immesso quando il driver considera matrici di parametri come unità monolitica, quindi non genera questo singolo livello di parametro delle informazioni sull'errore.

Alcuni errori nell'elaborazione di un singolo set di parametri causano l'arresto dell'elaborazione dei set di parametri successivi nella matrice. Altri errori non influiscono sull'elaborazione dei parametri successivi. Gli errori che arresteranno l'elaborazione sono definiti dal driver. Se l'elaborazione non viene arrestata, tutti i parametri nella matrice vengono elaborati, SQL_SUCCESS_WITH_INFO viene restituito come risultato dell'errore e il buffer definito da SQL_ATTR_PARAMS_PROCESSED_PTR viene impostato sul numero totale di set di parametri elaborati (come definito dall'attributo dell'istruzione SQL_ATTR_PARAMSET_SIZE), che include i set di errori.

Attenzione

Il comportamento ODBC quando si verifica un errore nell'elaborazione di una matrice di parametri è diverso in ODBC 3.x di quanto fosse in ODBC 2.x. In ODBC 2.x, la funzione ha restituito SQL_ERROR ed elaborazione interrotta. Il buffer a cui punta l'argomento pirow di SQLParamOptions contiene il numero della riga di errore. In ODBC 3.x, la funzione restituisce SQL_SUCCESS_WITH_INFO ed elaborazione può arrestare o continuare. Se continua, il buffer specificato da SQL_ATTR_PARAMS_PROCESSED_PTR verrà impostato sul valore di tutti i parametri elaborati, inclusi quelli che hanno generato un errore. Questa modifica nel comportamento può causare problemi per le applicazioni esistenti.

Quando SQLExecute o SQLExecDirect viene restituito prima di completare l'elaborazione di tutti i set di parametri in una matrice di parametri, ad esempio quando viene restituito SQL_ERROR o SQL_NEED_DATA, la matrice di stato contiene gli stati per i parametri già elaborati. La posizione a cui fa riferimento il campo SQL_DESC_ROWS_PROCESSED_PTR nell'IPD contiene il numero di riga nella matrice di parametri che ha causato il codice di errore SQL_ERROR o SQL_NEED_DATA. Quando una matrice di parametri viene inviata a un'istruzione SELECT, la disponibilità dei valori della matrice di stato è definita dal driver; possono essere disponibili dopo l'esecuzione dell'istruzione o durante il recupero dei set di risultati.

Ignorare un set di parametri

Il campo SQL_DESC_ARRAY_STATUS_PTR di APD (impostato dall'attributo dell'istruzione SQL_ATTR_PARAM_STATUS_PTR) può essere usato per indicare che un set di parametri associati in un'istruzione SQL deve essere ignorato. Per indirizzare il driver a ignorare uno o più set di parametri durante l'esecuzione, un'applicazione deve seguire questa procedura:

  1. Chiamare SQLSetDescField per impostare il campo di intestazione SQL_DESC_ARRAY_STATUS_PTR di APD in modo che punti a una matrice di valori SQLUSMALLINT in modo da contenere informazioni sullo stato. Questo campo può essere impostato anche chiamando SQLSetStmtAttr con un attributo di SQL_ATTR_PARAM_OPERATION_PTR, che consente a un'applicazione di impostare il campo senza ottenere un handle del descrittore.

  2. Impostare ogni elemento della matrice definita dal campo SQL_DESC_ARRAY_STATUS_PTR di APD su uno dei due valori seguenti:

    • SQL_PARAM_IGNORE, per indicare che la riga è esclusa dall'esecuzione dell'istruzione.

    • SQL_PARAM_PROCEED, per indicare che la riga è inclusa nell'esecuzione dell'istruzione.

  3. Chiamare SQLExecDirect o SQLExecute per eseguire l'istruzione preparata.

Le regole seguenti si applicano alla matrice definita dal campo SQL_DESC_ARRAY_STATUS_PTR del APD:

  • Il puntatore è impostato su Null per impostazione predefinita.

  • Se il puntatore è Null, vengono usati tutti i set di parametri, come se tutti gli elementi fossero impostati su SQL_ROW_PROCEED.

  • L'impostazione di un elemento su SQL_PARAM_PROCEED non garantisce che l'operazione userà tale particolare set di parametri.

  • SQL_PARAM_PROCEED è definito come 0 nel file di intestazione.

Un'applicazione può impostare il campo SQL_DESC_ARRAY_STATUS_PTR in APD in modo che punti alla stessa matrice a cui punta il campo SQL_DESC_ARRAY_STATUS_PTR in IRD. Ciò è utile quando si associano parametri a dati di riga. I parametri possono quindi essere ignorati in base allo stato dei dati della riga. Oltre a SQL_PARAM_IGNORE, i codici seguenti causano l'ignorare un parametro in un'istruzione SQL: SQL_ROW_DELETED, SQL_ROW_UPDATED e SQL_ROW_ERROR. Oltre a SQL_PARAM_PROCEED, i codici seguenti determinano l'esecuzione di un'istruzione SQL: SQL_ROW_SUCCESS, SQL_ROW_SUCCESS_WITH_INFO e SQL_ROW_ADDED.

Ribinding dei parametri

Un'applicazione può eseguire una delle due operazioni per modificare un'associazione:

  • Chiamare SQLBindParameter per specificare una nuova associazione per una colonna già associata. Il driver sovrascrive l'associazione precedente con quella nuova.

  • Specificare un offset da aggiungere all'indirizzo del buffer specificato dalla chiamata di associazione a SQLBindParameter. Per altre informazioni, vedere la sezione successiva"Rebinding with Offsets".

Ribinding con offset

La riassociazione dei parametri è particolarmente utile quando un'applicazione dispone di una configurazione dell'area del buffer che può contenere molti parametri, ma una chiamata a SQLExecDirect o SQLExecute usa solo alcuni parametri. Lo spazio rimanente nell'area del buffer può essere usato per il set successivo di parametri modificando l'associazione esistente da un offset.

Il campo intestazione SQL_DESC_BIND_OFFSET_PTR nel APD punta all'offset di associazione. Se il campo è diverso da Null, il driver dereferenzia il puntatore e, se nessuno dei valori nel SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR e SQL_DESC_OCTET_LENGTH_PTR campi è un puntatore Null, aggiunge il valore dereferenziato a tali campi nei record del descrittore in fase di esecuzione. I nuovi valori del puntatore vengono usati quando vengono eseguite le istruzioni SQL. L'offset rimane valido dopo la riassociazione. Poiché SQL_DESC_BIND_OFFSET_PTR è un puntatore all'offset anziché all'offset stesso, un'applicazione può modificare direttamente l'offset, senza dover chiamare SQLSetDescField o SQLSetDescRec per modificare il campo del descrittore. Il puntatore è impostato su Null per impostazione predefinita. Il campo SQL_DESC_BIND_OFFSET_PTR della ARD può essere impostato da una chiamata a SQLSetDescField o da una chiamata a SQLSetStmtAttr con fAttribute di SQL_ATTR_PARAM_BIND_OFFSET_PTR.

L'offset di associazione viene sempre aggiunto direttamente ai valori nei campi SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR e SQL_DESC_OCTET_LENGTH_PTR. Se l'offset viene modificato in un valore diverso, il nuovo valore viene comunque aggiunto direttamente al valore in ogni campo descrittore. Il nuovo offset non viene aggiunto alla somma del valore del campo ed eventuali offset precedenti.

Descrittori

La modalità di associazione di un parametro è determinata dai campi delle API e degli IPD. Gli argomenti in SQLBindParameter vengono usati per impostare tali campi descrittori. I campi possono essere impostati anche dalle funzioni SQLSetDescField , anche se SQLBindParameter è più efficiente da usare perché l'applicazione non deve ottenere un handle descrittore per chiamare SQLBindParameter.

Attenzione

La chiamata a SQLBindParameter per un'istruzione può influire su altre istruzioni. Ciò si verifica quando la ARD associata all'istruzione viene allocata in modo esplicito ed è associata anche ad altre istruzioni. Poiché SQLBindParameter modifica i campi dell'APD, le modifiche si applicano a tutte le istruzioni a cui è associato questo descrittore. Se questo non è il comportamento richiesto, l'applicazione deve dissociare questo descrittore dalle altre istruzioni prima di chiamare SQLBindParameter.

Concettualmente, SQLBindParameter esegue i passaggi seguenti in sequenza:

  1. Chiama SQLGetStmtAttr per ottenere l'handle APD.

  2. Chiama SQLGetDescField per ottenere il campo di SQL_DESC_COUNT APD e se il valore dell'argomento ColumnNumber supera il valore di SQL_DESC_COUNT, chiama SQLSetDescField per aumentare il valore di SQL_DESC_COUNT a ColumnNumber.

  3. Chiama SQLSetDescField più volte per assegnare valori ai campi seguenti di APD:

    • Imposta SQL_DESC_TYPE e SQL_DESC_CONCISE_TYPE sul valore di ValueType, ad eccezione del fatto che se ValueType è uno degli identificatori concisi di un sottotipo datetime o interval, imposta SQL_DESC_TYPE rispettivamente su SQL_DATETIME o SQL_INTERVAL, imposta SQL_DESC_CONCISE_TYPE sull'identificatore conciso e imposta SQL_DESC_DATETIME_INTERVAL_CODE sul codice secondario datetime o interval corrispondente.

    • Imposta il campo SQL_DESC_OCTET_LENGTH sul valore di BufferLength.

    • Imposta il campo SQL_DESC_DATA_PTR sul valore di ParameterValue.

    • Imposta il campo SQL_DESC_OCTET_LENGTH_PTR sul valore di StrLen_or_Ind.

    • Imposta il campo SQL_DESC_INDICATOR_PTR anche sul valore di StrLen_or_Ind.

    Il parametro StrLen_or_Ind specifica sia le informazioni sull'indicatore che la lunghezza del valore del parametro.

  4. Chiama SQLGetStmtAttr per ottenere l'handle IPD.

  5. Chiama SQLGetDescField per ottenere il campo di SQL_DESC_COUNT ipD e se il valore dell'argomento ColumnNumber supera il valore di SQL_DESC_COUNT, chiama SQLSetDescField per aumentare il valore di SQL_DESC_COUNT a ColumnNumber.

  6. Chiama SQLSetDescField più volte per assegnare valori ai campi seguenti dell'IPD:

    • Imposta SQL_DESC_TYPE e SQL_DESC_CONCISE_TYPE sul valore di ParameterType, ad eccezione del fatto che se ParameterType è uno degli identificatori concisi di un sottotipo datetime o interval, imposta SQL_DESC_TYPE rispettivamente su SQL_DATETIME o SQL_INTERVAL, imposta SQL_DESC_CONCISE_TYPE sull'identificatore conciso e imposta SQL_DESC_DATETIME_INTERVAL_CODE sul codice secondario datetime o interval corrispondente.

    • Imposta una o più SQL_DESC_LENGTH, SQL_DESC_PRECISION e SQL_DESC_DATETIME_INTERVAL_PRECISION, in base a ParameterType.

    • Imposta SQL_DESC_SCALE sul valore di DecimalDigits.

Se la chiamata a SQLBindParameter ha esito negativo , il contenuto dei campi descrittore che sarebbe stato impostato nel APD non è definito e il campo SQL_DESC_COUNT dell'APD rimane invariato. Inoltre, i campi SQL_DESC_LENGTH, SQL_DESC_PRECISION, SQL_DESC_SCALE e SQL_DESC_TYPE del record appropriato nell'IPD non sono definiti e il campo SQL_DESC_COUNT dell'IPD rimane invariato.

Conversione di chiamate da e verso SQLSetParam

Quando un'applicazione ODBC 1.0 chiama SQLSetParam in odbc 3.x driver, ODBC 3.x Driver Manager esegue il mapping della chiamata come illustrato nella tabella seguente.

Chiamare dall'applicazione ODBC 1.0 Chiamare a ODBC 3.Driver x
SQLSetParam( StatementHandle, ParameterNumber, ValueType, ParameterType, LengthPrecision, ParameterScale, ParameterValuePtr, StrLen_or_IndPtr); SQLBindParameter( StatementHandle, ParameterNumber, SQL_PARAM_INPUT_OUTPUT, ValueType, ParameterType, ColumnSize, DecimalDigits, ParameterValuePtr, SQL_SETPARAM_VALUE_MAX, StrLen_or_IndPtr);

Esempi

R. Usare la funzione SQLBindParameter

Nell'esempio seguente un'applicazione prepara un'istruzione SQL per inserire i dati nella tabella ORDERS. Per ogni parametro nell'istruzione, l'applicazione chiama SQLBindParameter per specificare il tipo di dati ODBC C e il tipo di dati SQL del parametro e per associare un buffer a ogni parametro. Per ogni riga di dati, l'applicazione assegna valori di dati a ogni parametro e chiama SQLExecute per eseguire l'istruzione.

Nell'esempio seguente si presuppone che nel computer sia presente un'origine dati ODBC denominata Northwind associata al database Northwind.

Per altri esempi di codice, vedere Funzione SQLBulkOperations, funzione SQLProcedures, funzione SQLPutData e funzione SQLSetPos.

// SQLBindParameter_Function.cpp  
// compile with: ODBC32.lib  
#include <windows.h>  
#include <sqltypes.h>  
#include <sqlext.h>  
  
#define EMPLOYEE_ID_LEN 10  
  
SQLHENV henv = NULL;  
SQLHDBC hdbc = NULL;  
SQLRETURN retcode;  
SQLHSTMT hstmt = NULL;  
SQLSMALLINT sCustID;  
  
SQLCHAR szEmployeeID[EMPLOYEE_ID_LEN];  
SQL_DATE_STRUCT dsOrderDate;  
SQLINTEGER cbCustID = 0, cbOrderDate = 0, cbEmployeeID = SQL_NTS;  
  
int main() {  
   retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);  
   retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER*)SQL_OV_ODBC3, 0);   
  
   retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);   
   retcode = SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)5, 0);  
  
   retcode = SQLConnect(hdbc, (SQLCHAR*) "Northwind", SQL_NTS, (SQLCHAR*) NULL, 0, NULL, 0);  
   retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);  
  
   retcode = SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR, EMPLOYEE_ID_LEN, 0, szEmployeeID, 0, &cbEmployeeID);  
   retcode = SQLBindParameter(hstmt, 2, SQL_PARAM_INPUT, SQL_C_SSHORT, SQL_INTEGER, 0, 0, &sCustID, 0, &cbCustID);  
   retcode = SQLBindParameter(hstmt, 3, SQL_PARAM_INPUT, SQL_C_TYPE_DATE, SQL_TIMESTAMP, sizeof(dsOrderDate), 0, &dsOrderDate, 0, &cbOrderDate);  
  
   retcode = SQLPrepare(hstmt, (SQLCHAR*)"INSERT INTO Orders(CustomerID, EmployeeID, OrderDate) VALUES (?, ?, ?)", SQL_NTS);  
  
   strcpy_s((char*)szEmployeeID, _countof(szEmployeeID), "BERGS");  
   sCustID = 5;  
   dsOrderDate.year = 2006;  
   dsOrderDate.month = 3;  
   dsOrderDate.day = 17;  
  
   retcode = SQLExecute(hstmt);  
}

B. Eseguire una stored procedure usando un parametro denominato

Nell'esempio seguente un'applicazione esegue una stored procedure di SQL Server usando un parametro denominato.

// SQLBindParameter_Function_2.cpp  
// compile with: ODBC32.lib  
// sample assumes the following stored procedure:  
// use northwind  
// DROP PROCEDURE SQLBindParameter  
// GO  
//   
// CREATE PROCEDURE SQLBindParameter @quote int  
// AS  
// delete from orders where OrderID >= @quote  
// GO  
#include <windows.h>  
#include <sqltypes.h>  
#include <sqlext.h>  
  
SQLHDESC hIpd = NULL;  
SQLHENV henv = NULL;  
SQLHDBC hdbc = NULL;  
SQLRETURN retcode;  
SQLHSTMT hstmt = NULL;  
SQLCHAR szQuote[50] = "100084";  
SQLINTEGER cbValue = SQL_NTS;  
  
int main() {  
   retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);  
   retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER*)SQL_OV_ODBC3, 0);   
  
   retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);   
   retcode = SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)5, 0);  
  
   retcode = SQLConnect(hdbc, (SQLCHAR*) "Northwind", SQL_NTS, (SQLCHAR*) NULL, 0, NULL, 0);  
   retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);  
  
   retcode = SQLPrepare(hstmt, (SQLCHAR*)"{call SQLBindParameter(?)}", SQL_NTS);  
   retcode = SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR, 50, 0, szQuote, 0, &cbValue);  
   retcode = SQLGetStmtAttr(hstmt, SQL_ATTR_IMP_PARAM_DESC, &hIpd, 0, 0);  
   retcode = SQLSetDescField(hIpd, 1, SQL_DESC_NAME, "@quote", SQL_NTS);  
  
   retcode = SQLExecute(hstmt);  
}
Per informazioni su Vedere
Restituzione di informazioni su un parametro in un'istruzione Funzione SQLDescribeParam
Esecuzione di un'istruzione SQL Funzione SQLExecDirect
Esecuzione di un'istruzione SQL preparata Funzione SQLExecute
Rilascio di buffer di parametri nell'istruzione Funzione SQLFreeStmt
Restituzione del numero di parametri di istruzione Funzione SQLNumParams
Restituzione del parametro successivo per l'invio di dati per Funzione SQLParamData
Specifica di più valori di parametro Funzione SQLParamOptions
Invio dei dati dei parametri in fase di esecuzione Funzione SQLPutData

Vedi anche

Riferimento API ODBC
File di intestazione ODBC
Recupero di parametri di output tramite SQLGetData