SQLBindParameter 函式

  • 發行項

一致性
引進的版本：ODBC 2.0 標準合規性：ODBC

摘要
SQLBindParameter 會將緩衝區系結至 SQL 語句中的參數標記。 SQLBindParameter 支援系結至 Unicode C 數據類型，即使基礎驅動程式不支援 Unicode 數據也一樣。

注意

此函式會取代 ODBC 1.0 函式 SQLSetParam。 如需詳細資訊，請參閱。

語法

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

引數

StatementHandle
[輸入]語句句柄。

ParameterNumber
[輸入]參數編號，以遞增參數順序循序排序，從 1 開始。

InputOutputType
[輸入] 參數的類型。 如需詳細資訊，請參閱中的<InputOutputType 自變數>。

ValueType
[輸入]參數的 C 數據類型。 如需詳細資訊，請參閱中的<ValueType 自變數>。

ParameterType
[輸入]參數的 SQL 資料類型。 如需詳細資訊，請參閱中的<ParameterType 自變數>。

ColumnSize
[輸入]對應參數標記之數據行或表達式的大小。 如需詳細資訊，請參閱中的<ColumnSize 自變數>。

如果您的應用程式將在64位 Windows 作業系統上執行，請參閱 ODBC 64 位資訊。

DecimalDigits
[輸入]對應參數標記之數據行或表達式的十進位數。 如需數據行大小的詳細資訊，請參閱 數據行大小、十進位數、傳輸八進位長度和顯示大小。

ParameterValuePtr
[延遲輸入]參數數據的緩衝區指標。 如需詳細資訊，請參閱中的<ParameterValuePtr 自變數>。

BufferLength
[輸入/輸出]ParameterValuePtr 緩衝區的長度，以位元組為單位。 如需詳細資訊，請參閱中的<BufferLength 自變數>。

如果您的應用程式將在64位作業系統上執行，請參閱 ODBC 64位資訊。

StrLen_or_IndPtr
[延遲輸入]參數長度之緩衝區的指標。 如需詳細資訊，請參閱中的<StrLen_or_IndPtr自變數>。

傳回

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR或SQL_INVALID_HANDLE。

診斷

當 SQLBindParameter 傳回SQL_ERROR或SQL_SUCCESS_WITH_INFO時，可以藉由呼叫 SQLGetDiagRec 搭配 SQL_HANDLE_STMT 的 HandleType 和 StatementHandle 句柄來取得相關聯的 SQLSTATE 值。 下表列出 SQLBindParameter 通常傳回的 SQLSTATE 值，並說明此函式內容中的每個值;表示法 “（DM）” 在驅動程式管理員傳回的 SQLSTATE 描述之前。 除非另有說明，否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。

SQLSTATE 錯誤 描述
01000 一般警告 驅動程式特定的資訊訊息。 （函式會傳回SQL_SUCCESS_WITH_INFO。）
07006 受限制的數據類型屬性違規 ValueType 自變數所識別的數據類型無法轉換成 ParameterType 自變數所識別的數據類型。 請注意，這個錯誤可能會由 SQLExecDirect、SQLExecute 或 SQLPutData 在運行時間傳回，而不是由 SQLBindParameter 傳回。
07009 無效的描述元索引 （DM） 為 argument ParameterNumber 指定的值小於 1。
HY000 一般錯誤 發生錯誤，其中沒有特定的 SQLSTATE，也沒有定義任何實作特定的 SQLSTATE。 *MessageText 緩衝區中 SQLGetDiagRec 傳回的錯誤訊息描述錯誤及其原因。
HY001 記憶體配置錯誤 驅動程式無法配置支援執行或完成函式所需的記憶體。
HY003 無效的應用程式緩衝區類型 自變數 ValueType 指定的值不是有效的 C 數據類型或SQL_C_DEFAULT。
HY004 無效的 SQL 資料類型 針對 ParameterType 自變數指定的值既不是有效的 ODBC SQL 資料類型識別碼，也不是驅動程式所支援的驅動程式特定 SQL 數據類型識別碼。
HY009 無效的自變數值 （DM） argument ParameterValuePtr 是 null 指標、自變數StrLen_or_IndPtr為 null 指標，而且 inputOutputType 自變數未SQL_PARAM_OUTPUT。

（DM） SQL_PARAM_OUTPUT，其中 argument ParameterValuePtr 是 null 指標，C 類型是 char 或 binary，而 BufferLength （cbValueMax） 大於 0。
HY010 函式順序錯誤 （DM） 已針對與 StatementHandle 相關聯的連接句柄呼叫異步執行函式。 呼叫 SQLBindParameter 時，這個異步函式仍在執行中。

（DM） 已針對 StatementHandle 呼叫 SQLExecute、SQLExecDirect 或 SQLMoreResults，並傳回SQL_PARAM_DATA_AVAILABLE。 在擷取所有數據流參數的數據之前，會呼叫此函式。

（DM） 呼叫 StatementHandle 的異步執行函式，並在呼叫此函式時仍在執行。

（DM） 已針對 StatementHandle 呼叫 SQLExecute、SQLExecDirect、SQLBulkOperations 或 SQLSetPos，並傳回SQL_NEED_DATA。 在針對所有數據執行中參數或數據行傳送數據之前，會呼叫此函式。
HY013 記憶體管理錯誤 無法處理函式呼叫，因為基礎記憶體物件無法存取，可能是因為記憶體不足的情況。
HY021 不一致的描述元資訊 在一致性檢查期間檢查的描述元資訊不一致。 （請參閱 中的 一節SQLSetDescField.）

為自變數 DecimalDigits 指定的值超出 ParameterType 自變數所指定 SQL 數據類型數據行之數據源所支援的值範圍。
HY090 無效的字串或緩衝區長度 （DM） BufferLength 中的值小於 0。 （請參閱 中的 SQL_DESC_DATA_PTR欄位描述SQLSetDescField.）
HY104 無效的有效位數或小數位數值 針對 ColumnSize 或 DecimalDigits 自變數指定的值超出 ParameterType 自變數所指定之 SQL 數據類型數據行之數據源所支援的值範圍。
HY105 無效的參數類型 （DM） 為自變數 InputOutputType 指定的值無效。 （請參閱“批注”。）
HY117 連線 因為未知的交易狀態而暫停。 只允許中斷連線和唯讀函式。 （DM） 如需暫停狀態的詳細資訊，請參閱 SQLEndTran 函式。
HYC00 未實作選擇性功能 驅動程式或數據源不支援由針對 Argument ValueType 指定的值組合所指定的轉換，以及針對 ParameterType 指定之自變數的驅動程式特定值。

針對 ParameterType 自變數指定的值，是驅動程式所支援之 ODBC 版本的有效 ODBC SQL 資料類型識別碼，但驅動程式或數據源不支援。

驅動程式僅支援 ODBC 2。x 和自變數 ValueType 是下列其中一項：

SQL_C_NUMERIC SQL_C_SBIGINT SQL_C_UBIGINT

和附錄 D：數據類型中 C 數據類型中列出的 所有間隔 C 數據類型 。

驅動程式僅支援 3.50 之前的 ODBC 版本，且自變數 ValueType 已SQL_C_GUID。
HYT01 已超過連線逾時 在數據源回應要求之前，連線逾時期限已過期。 連線逾時期間是透過 SQLSet 設定 連線 Attr，SQL_ATTR_CONNECTION_TIMEOUT。
IM001 驅動程式不支援此函式 （DM） 與 StatementHandle 相關聯的驅動程式不支援 函式。

註解

應用程式會呼叫 SQLBindParameter ，以系結 SQL 語句中的每個參數標記。 系結會持續生效，直到應用程式再次呼叫 SQLBindParameter 、使用 SQL_RESET_PARAMS 選項呼叫 SQLFreeStmt ，或呼叫 SQLSetDescField 將 APD 的 SQL_DESC_COUNT 標頭字段設定為 0。

如需參數的詳細資訊，請參閱陳述式參數。 如需參數數據類型和參數標記的詳細資訊，請參閱 附錄 C：SQL 文法中的參數數據類型 和 參數標記 。

ParameterNumber 自變數

如果對 SQLBindParameter 呼叫中的 ParameterNumber 大於 SQL_DESC_COUNT 的值，則會呼叫 SQLSetDescField，將 SQL_DESC_COUNT 的值增加到 ParameterNumber。

InputOutputType 自變數

InputOutputType 自變數會指定參數的類型。 這個自變數會設定IPD的SQL_DESC_PARAMETER_TYPE欄位。 SQL 語句中未呼叫程式的所有參數，例如 INSERT 語句，都是 輸入參數。 程序呼叫中的參數可以是輸入、輸入/輸出或輸出參數。 （應用程式呼叫 SQLProcedureColumns 在過程調用中判斷參數的類型;無法判斷其類型的參數會假設為輸入參數。

InputOutputType 引數是下列其中一個值：

  • SQL_PARAM_INPUT。 參數會標記 SQL 語句中未呼叫程式的參數，例如 INSERT 語句，或標記程式中的輸入參數。 例如，INSERT INTO Employee VALUES （?, ?, ?） 中的參數是輸入參數，而 {call AddEmp（?, ?, ?）} 中的參數可以是輸入參數，但不一定是輸入參數。

    執行語句時，驅動程式會將 參數的數據傳送至數據源;*ParameterValuePtr 緩衝區必須包含有效的輸入值，或 *StrLen_or_IndPtr緩衝區必須包含SQL_NULL_DATA、SQL_DATA_AT_EXEC 或SQL_LEN_DATA_AT_EXEC宏的結果。

    如果應用程式無法在過程調用中判斷參數的類型，它會將 InputOutputType 設定為 SQL_PARAM_INPUT;如果數據源傳回參數的值，驅動程式就會捨棄它。

  • SQL_PARAM_INPUT_OUTPUT。 參數會在程式中標記輸入/輸出參數。 例如，{call GetEmpDept（？）} 中的參數是接受員工名稱並傳回員工部門名稱的輸入/輸出參數。

    執行語句時，驅動程式會將 參數的數據傳送至數據源;*ParameterValuePtr 緩衝區必須包含有效的輸入值，或 *StrLen_or_IndPtr緩衝區必須包含SQL_NULL_DATA、SQL_DATA_AT_EXEC 或SQL_LEN_DATA_AT_EXEC宏的結果。 執行語句之後，驅動程式會將 參數的數據傳回給應用程式;如果數據源未傳回輸入/輸出參數的值，驅動程式會將 *StrLen_or_IndPtr 緩衝區設定為SQL_NULL_DATA。

    注意

    當 ODBC 1.0 應用程式在 ODBC 2.0 驅動程式中呼叫 SQLSetParam 時，Driver Manager 會將這個轉換成 SQLBindParameter 的呼叫，其中 InputOutputType 自變數設定為 SQL_PARAM_INPUT_OUTPUT。

  • SQL_PARAM_OUTPUT。 參數會標記程式中的程式或輸出參數的傳回值;不論是哪一種情況，這些都稱為 輸出參數。 例如，{？=call GetNextEmpID} 中的參數是傳回下一個員工標識符的輸出參數。

    執行 語句之後，驅動程式會將參數的數據傳回給應用程式，除非 ParameterValuePtr 和 StrLen_or_IndPtr 自變數都是Null指標，在此情況下，驅動程式會捨棄輸出值。 如果數據源未傳回輸出參數的值，驅動程式會將 *StrLen_or_IndPtr 緩衝區設定為SQL_NULL_DATA。

  • SQL_PARAM_INPUT_OUTPUT_STREAM。 表示應該串流輸入/輸出參數。 SQLGetData 可以讀取元件中的參數值。 BufferLength 會被忽略，因為緩衝區長度將在 SQLGetData 的呼叫中決定。 StrLen_or_IndPtr緩衝區的值必須包含SQL_NULL_DATA、SQL_DEFAULT_PARAM、SQL_DATA_AT_EXEC或SQL_LEN_DATA_AT_EXEC宏的結果。 如果參數將在輸出中串流處理，則必須在輸入中系結為數據執行中 （DAE） 參數。 ParameterValuePtr 可以是 SQLParamData 會傳回的任何非 Null 指標值，做為使用者定義令牌，其值是搭配 ParameterValuePtr 傳遞的輸入和輸出。 如需詳細資訊，請參閱使用 SQLGetData 擷取輸出參數。

  • SQL_PARAM_OUTPUT_STREAM。 與輸出參數SQL_PARAM_INPUT_OUTPUT_STREAM相同。 *輸入時會忽略StrLen_or_IndPtr 。

下表列出 InputOutputType 和 *StrLen_or_IndPtr的不同組合：

InputOutputType *StrLen_or_IndPtr 結果 ParameterValuePtr 的備註
SQL_PARAM_INPUT SQL_LEN_DATA_AT_EXEC（len） 或 SQL_DATA_AT_EXEC 元件中的輸入 ParameterValuePtr 可以是 SQLParamData 將傳回的任何指標值，做為以 ParameterValuePtr 傳遞其值的使用者定義令牌。
SQL_PARAM_INPUT 非SQL_LEN_DATA_AT_EXEC（len） 或SQL_DATA_AT_EXEC 輸入系結緩衝區 ParameterValuePtr 是輸入緩衝區的位址。
SQL_PARAM_OUTPUT 在輸入時忽略。 輸出系結緩衝區 ParameterValuePtr 是輸出緩衝區的位址。
SQL_PARAM_OUTPUT_STREAM 在輸入時忽略。 串流輸出 ParameterValuePtr 可以是任何指標值，SQLParamData 會傳回為以 ParameterValuePtr 傳遞其值的使用者定義令牌。
SQL_PARAM_INPUT_OUTPUT SQL_LEN_DATA_AT_EXEC（len） 或 SQL_DATA_AT_EXEC 元件和輸出系結緩衝區中的輸入 ParameterValuePtr 是輸出緩衝區的位址，SQLParamData 也會傳回為以 ParameterValuePtr 傳遞其值的使用者定義令牌。
SQL_PARAM_INPUT_OUTPUT 非SQL_LEN_DATA_AT_EXEC（len） 或SQL_DATA_AT_EXEC 輸入系結緩衝區和輸出系結緩衝區 ParameterValuePtr 是共用輸入/輸出緩衝區的位址。
SQL_PARAM_INPUT_OUTPUT_STREAM SQL_LEN_DATA_AT_EXEC（len） 或 SQL_DATA_AT_EXEC 元件和串流輸出中的輸入 ParameterValuePtr 可以是任何非 Null 指標值，SQLParamData 會以使用者定義令牌的形式傳回，其值是使用 ParameterValuePtr 傳遞的輸入和輸出。

注意

當應用程式將輸出或輸入輸出參數係結為數據流時，驅動程式必須決定允許哪些 SQL 類型。 驅動程式管理員不會為無效的 SQL 類型產生錯誤。

ValueType 自變數

ValueType 自變數會指定 參數的 C 數據類型。 這個自變數會設定APD的SQL_DESC_TYPE、SQL_DESC_CONCISE_TYPE和SQL_DESC_DATETIME_INTERVAL_CODE欄位。 這必須是附錄 D：數據類型之 C 數據類型 區段中的其中一個值。

如果 ValueType 自變數是其中一個間隔數據類型，則 APD 之 ParameterNumber 記錄的SQL_DESC_TYPE字段會設定為 SQL_INTERVAL，APD 的 SQL_DESC_CONCISE_TYPE 字段會設定為精簡的間隔數據類型，而 ParameterNumber 記錄的 SQL_DESC_DATETIME_INTERVAL_CODE 字段會設定為特定間隔數據類型的子程式代碼。 （請參閱 附錄 D：資料類型。）默認間隔前置精確度 （2） 和預設間隔秒精確度 （6），分別用於數據SQL_DESC_DATETIME_INTERVAL_PRECISION和SQL_DESC_PRECISION字段。 如果預設有效位數不合適，應用程式應該藉由呼叫 SQLSetDescField 或 SQLSetDescRec 明確設定描述元欄位。

如果 ValueType 自變數是 datetime 數據類型之一，則 APD 之 ParameterNumber 記錄的 SQL_DESC_TYPE 字段會設定為 SQL_DATETIME，APD 之 ParameterNumber 記錄的 SQL_DESC_CONCISE_TYPE 字段會設定為精簡的 datetime C 數據類型，而 ParameterNumber 記錄的 SQL_DESC_DATETIME_INTERVAL_CODE 字段會設定為特定 datetime 數據類型的子程序代碼。 （請參閱 附錄 D：資料類型。）

如果 ValueType 自變數是SQL_C_NUMERIC數據類型，則會針對數據使用SQL_DESC_PRECISION和SQL_DESC_SCALE欄位所設定的預設有效位數（也就是驅動程式定義）和預設小數位數 （0）。 如果預設有效位數或小數位數不合適，應用程式應該藉由呼叫 SQLSetDescField 或 SQLSetDescRec 明確設定描述元欄位。

SQL_C_DEFAULT指定參數值會從以 ParameterType 指定之 SQL 資料類型的預設 C 資料類型傳送。

您也可以指定擴充的 C 資料類型。 如需詳細資訊，請參閱 ODBC 的 C 資料類型。

如需詳細資訊，請參閱 附錄 D：數據類型中的預設 C 數據類型、 將數據從 C 轉換成 SQL 資料類型，以及 將數據從 SQL 轉換成 C 數據類型 。

ParameterType 自變數

這必須是附錄 D： 資料類型一節中列出的值，或者必須是驅動程式特定的值。 這個自變數會設定IPD的SQL_DESC_TYPE、SQL_DESC_CONCISE_TYPE和SQL_DESC_DATETIME_INTERVAL_CODE欄位。

如果 ParameterType 自變數是其中一個日期時間標識碼，IPD 的SQL_DESC_TYPE欄位會設定為 SQL_DATETIME，IPD 的SQL_DESC_CONCISE_TYPE欄位會設定為精簡的 datetime SQL 數據類型，而SQL_DESC_DATETIME_INTERVAL_CODE字段會設定為適當的 datetime 子程式代碼值。

如果 ParameterType 是其中一個間隔標識碼，IPD 的 SQL_DESC_TYPE 欄位會設定為 SQL_INTERVAL，IPD 的 SQL_DESC_CONCISE_TYPE 欄位會設定為精簡的 SQL 間隔數據類型，而 IPD 的 SQL_DESC_DATETIME_INTERVAL_CODE 欄位會設定為適當的間隔子碼。 IPD 的SQL_DESC_DATETIME_INTERVAL_PRECISION欄位會設定為間隔前置精確度，如果適用，SQL_DESC_PRECISION欄位會設定為間隔秒有效位數。 如果SQL_DESC_DATETIME_INTERVAL_PRECISION或SQL_DESC_PRECISION的預設值不適用，應用程式應該藉由呼叫 SQLSetDescField 來明確設定它。 如需上述任何欄位的詳細資訊，請參閱 SQLSetDescField。

如果 ValueType 自變數是SQL_NUMERIC數據類型，則會針對數據使用SQL_DESC_PRECISION和SQL_DESC_SCALE欄位所設定的預設有效位數（也就是驅動程式定義）和預設小數位數 （0）。 如果預設有效位數或小數位數不合適，應用程式應該藉由呼叫 SQLSetDescField 或 SQLSetDescRec 明確設定描述元欄位。

如需數據轉換方式的詳細資訊，請參閱 附錄 D：數據類型中的將數據從 C 轉換成 SQL 資料類型 ，以及 將數據從 SQL 轉換成 C 數據類型 。

ColumnSize 自變數

ColumnSize 自變數會指定對應至參數標記、該數據長度或兩者對應的數據行或表達式大小。 此自變數會根據 SQL 資料類型（ ParameterType 自變數）來設定 IPD 的不同欄位。 下列規則適用於此對應：

  • 如果 ParameterType 是SQL_CHAR、SQL_VARCHAR、SQL_LONGVARCHAR、SQL_BINARY、SQL_VARBINARY、SQL_LONGVARBINARY或其中一個精簡的 SQL 日期時間或間隔數據類型，則 IPD 的 SQL_DESC_LENGTH 欄位會設定為 ColumnSize 的值。 （如需詳細資訊，請參閱 附錄 D：數據類型中的數據行大小、十進位數、傳輸八位長度和顯示大小 區段。

  • 如果 ParameterType 是SQL_DECIMAL、SQL_NUMERIC、SQL_FLOAT、SQL_REAL或SQL_DOUBLE，IPD 的 SQL_DESC_PRECISION 字段會設定為 ColumnSize 的值。

  • 對於其他數據類型， 會忽略 ColumnSize 自變數。

如需詳細資訊，請參閱和<StrLen_or_IndPtr自變數>中的SQL_DATA_AT_EXEC。

DecimalDigits 自變數

如果 ParameterType 為 SQL_TYPE_TIME、SQL_TYPE_TIMESTAMP、SQL_INTERVAL_SECOND、SQL_INTERVAL_DAY_TO_SECOND、SQL_INTERVAL_HOUR_TO_SECOND 或 SQL_INTERVAL_MINUTE_TO_SECOND，IPD 的SQL_DESC_PRECISION字段會設定為 DecimalDigits。 如果 ParameterType 是SQL_NUMERIC或SQL_DECIMAL，IPD 的SQL_DESC_SCALE字段會設定為 DecimalDigits。 若為所有其他數據類型， 則會忽略 DecimalDigits 自變數。

ParameterValuePtr 自變數

ParameterValuePtr 自變數指向呼叫 SQLExecute 或 SQLExecDirect 時，包含參數的實際數據。 數據必須是 ValueType 自變數所指定的表單。 這個自變數會設定APD的SQL_DESC_DATA_PTR欄位。 只要 *StrLen_or_IndPtr是SQL_NULL_DATA或SQL_DATA_AT_EXEC，應用程式就可以將ParameterValuePtr自變數設定為 null 指標。 （這隻適用於輸入或輸入/輸出參數。

如果 *StrLen_or_IndPtr 是SQL_LEN_DATA_AT_EXEC（length） 宏或SQL_DATA_AT_EXEC的結果， 則 ParameterValuePtr 是與 參數相關聯的應用程式定義指標值。 它會透過 SQLParamData 傳回至應用程式。 例如，ParameterValuePtr 可能是非零標記，例如參數編號、數據的指標，或應用程式用來系結輸入參數之結構的指標。 不過，請注意，如果參數是輸入/輸出參數， ParameterValuePtr 必須是將儲存輸出值之緩衝區的指標。 如果SQL_ATTR_PARAMSET_SIZE語句屬性中的值大於 1，應用程式可以使用 SQL_ATTR_PARAMS_PROCESSED_PTR 語句屬性所指向的值，以及 ParameterValuePtr 自變數。 例如， ParameterValuePtr 可能會指向值陣列，而應用程式可能會使用 SQL_ATTR_PARAMS_PROCESSED_PTR 指向的值，從陣列擷取正確的值。 如需詳細資訊，請參閱本節稍後的。

如果 InputOutputType 自變數SQL_PARAM_INPUT_OUTPUT或SQL_PARAM_OUTPUT，ParameterValuePtr 會指向驅動程式傳回輸出值的緩衝區。 如果程式傳回一或多個結果集，則在處理所有結果集/數據列計數之前，不保證會設定 *ParameterValuePtr 緩衝區。 如果在處理完成之前未設定緩衝區，則除非 SQLMoreResults 傳回SQL_NO_DATA，否則無法使用輸出參數和傳回值。 呼叫 具有 SQL_CLOSE 選項的 SQLCloseCursor 或 SQLFreeStmt 會導致捨棄這些值。

如果 SQL_ATTR_PARAMSET_SIZE 語句屬性中的值大於 1，ParameterValuePtr 會指向陣列。 單一 SQL 語句會處理輸入或輸入/輸出參數的完整輸入值陣列，並傳回輸入/輸出或輸出參數的輸出值數組。

BufferLength 自變數

針對字元和二進位 C 數據，BufferLength 自變數會指定 *ParameterValuePtr 緩衝區的長度（如果是單一元素），或 *ParameterValuePtr 數組中元素的長度（如果SQL_ATTR_PARAMSET_SIZE語句屬性中的值大於 1）。 這個自變數會設定APD的SQL_DESC_OCTET_LENGTH記錄欄位。 如果應用程式指定多個值， 則會使用 BufferLength 來判斷 *ParameterValuePtr 陣列中值的位置，無論是在輸入和輸出上。 針對輸入/輸出和輸出參數，它會用來判斷是否要在輸出上截斷字元和二進位 C 數據：

  • 針對字元 C 數據，如果可用的位元組數目大於或等於 BufferLength，則 *ParameterValuePtr 中的數據會截斷為 BufferLength，減少 Null 終止字元的長度，而且由驅動程式以 Null 終止。

  • 對於二進位 C 數據，如果可用的位元元組數目大於 BufferLength，則 *ParameterValuePtr 中的數據會截斷為 BufferLength 位元組。

對於所有其他 C 數據類型， 會忽略 BufferLength 自變數。 *ParameterValuePtr 緩衝區的長度（如果是單一元素）或 *ParameterValuePtr 陣列中的元素長度（如果應用程式呼叫具有屬性自變數 SQL_ATTR_PARAMSET_SIZE的 SQLSetStmtAttr，以指定每個參數的多個值），則假設為 C 數據類型的長度。

針對數據流輸出或串流輸入/輸出參數，會忽略 BufferLength 自變數，因為緩衝區長度是在 SQLGetData 中指定。

注意

當 ODBC 1.0 應用程式在 ODBC 3 中呼叫 SQLSetParam 時。x 驅動程式，驅動程式管理員會將這個轉換成 SQLBindParameter 的呼叫，其中 BufferLength 自變數一律SQL_SETPARAM_VALUE_MAX。 因為如果 ODBC 3，驅動程式管理員會傳回錯誤。x 應用程式會將 BufferLength 設定為 SQL_SETPARAM_VALUE_MAX ODBC 3。x 驅動程式可以使用這個來判斷 ODBC 1.0 應用程式何時呼叫它。

注意

在 SQLSetParam 中，應用程式指定 *ParameterValuePtr 緩衝區長度的方式，讓驅動程式可以傳回字元或二進位數據，以及應用程式將字元或二進位參數值數位傳送至驅動程式的方式，都是驅動程式定義的。

StrLen_or_IndPtr自變數

StrLen_or_IndPtr自變數指向呼叫 SQLExecute 或 SQLExecDirect 時包含下列其中一項的緩衝區。 （這個自變數會設定應用程式參數指標的SQL_DESC_OCTET_LENGTH_PTR和SQL_DESC_INDICATOR_PTR記錄欄位。

  • 儲存在 *ParameterValuePtr 中的參數值長度。 除了字元或二進位 C 數據之外，這會忽略此專案。

  • SQL_NTS。 參數值是 Null 終止的字串。

  • SQL_NULL_DATA。 參數值為 NULL。

  • SQL_DEFAULT_PARAM。 程式是使用參數的預設值，而不是從應用程式擷取的值。 這個值只有在 ODBC 標準語法中呼叫的程式才有效，而且只有在 InputOutputType 自變數SQL_PARAM_INPUT、SQL_PARAM_INPUT_OUTPUT或SQL_PARAM_INPUT_OUTPUT_STREAM時才有效。 當 *StrLen_or_IndPtr為SQL_DEFAULT_PARAM時，輸入參數會忽略 ValueType、ParameterType、ParameterType、ColumnSize、DecimalDigits、BufferLength 和 ParameterValuePtr 自變數，而且只會用來定義輸入/輸出參數的輸出參數值。

  • SQL_LEN_DATA_AT_EXEC（length） 宏的結果。 參數的數據將會隨 SQLPutData 一起傳送。 如果 ParameterType 自變數是 sqlGetInfo 中SQL_LONGVARBINARY、SQL_LONGVARCHAR或長數據源特定數據類型，而驅動程式會針對 SQLGetInfo 中SQL_NEED_LONG_DATA_LEN資訊型別傳回 “Y”，length 是要針對參數傳送的數據字節數目;否則，length 必須是非負值且會被忽略。 如需詳細資訊，請參閱本節稍後的。

    例如，若要指定 10,000 個字節的數據將會在 一或多個呼叫中使用 SQLPutData 傳送，針對SQL_LONGVARCHAR參數，應用程式會將 *StrLen_or_IndPtr 設定為 SQL_LEN_DATA_AT_EXEC（10000）。

  • SQL_DATA_AT_EXEC。 參數的數據將會隨 SQLPutData 一起傳送。 當 ODBC 1.0 應用程式呼叫 ODBC 3 時，會使用此值。x 驅動程式。 如需詳細資訊，請參閱本節稍後的。

如果 StrLen_or_IndPtr 為 Null 指標，驅動程式會假設所有輸入參數值都是非 NULL，且該字元和二進位數據會以 Null 終止。 如果 InputOutputType 是SQL_PARAM_OUTPUT或SQL_PARAM_OUTPUT_STREAM且 ParameterValuePtr 和 StrLen_or_IndPtr 都是 Null 指標，驅動程式會捨棄輸出值。

注意

當參數的數據類型SQL_C_BINARY時，強烈建議您不要指定StrLen_or_IndPtr的 Null 指標。 為了確保驅動程式不會意外截斷SQL_C_BINARY數據， StrLen_or_IndPtr 應該包含有效長度值的指標。

如果 InputOutputType 自變數是SQL_PARAM_INPUT_OUTPUT、SQL_PARAM_OUTPUT、SQL_PARAM_INPUT_OUTPUT_STREAM或SQL_PARAM_OUTPUT_STREAM，StrLen_or_IndPtr指向驅動程式傳回SQL_NULL_DATA的緩衝區、可在 *ParameterValuePtr 中傳回的位元組數（不包括字元數據的 null 終止位元組），或SQL_NO_TOTAL（如果無法判斷傳回的位元組數）。 如果程式傳回一或多個結果集，在擷取所有結果之前，不保證會設定 *StrLen_or_IndPtr 緩衝區。

如果 SQL_ATTR_PARAMSET_SIZE 語句屬性中的值大於 1，StrLen_or_IndPtr指向 SQLLEN 值的陣列。 這些可以是本節稍早所列的任何值，並使用單一 SQL 語句處理。

傳遞參數值

應用程式可以在 *ParameterValuePtr 緩衝區或對 SQLPutData 進行一或多個呼叫時，傳遞參數的值。 使用 SQLPutData 傳遞數據的參數稱為 數據執行 中參數。 這些通常用來傳送SQL_LONGVARBINARY和SQL_LONGVARCHAR參數的數據，並可與其他參數混合。

若要傳遞參數值，應用程式會執行下列步驟序列：

  1. 針對每個參數呼叫 SQLBindParameter，以系結參數值 （ParameterValuePtr 自變數） 和長度/指標的緩衝區 （StrLen_or_IndPtr 自變數）。 對於數據執行參數，ParameterValuePtr 是應用程式定義的指標值，例如參數編號或數據的指標。 此值稍後會傳回，並可用來識別 參數。

  2. 在 *ParameterValuePtr 和 *StrLen_or_IndPtr 緩衝區中放置輸入和輸出參數的值：

    • 針對一般參數，應用程式會將參數值放在 *ParameterValuePtr 緩衝區中，並將該值的長度放在 *StrLen_or_IndPtr 緩衝區中。 如需詳細資訊，請參閱 設定參數值。

    • 針對數據執行參數，應用程式會將SQL_LEN_DATA_AT_EXEC（length） 宏的結果（在呼叫 ODBC 2.0 驅動程式時）放在 *StrLen_or_IndPtr 緩衝區中。

  3. 呼叫 SQLExecute 或 SQLExecDirect 來執行 SQL 語句。

    • 如果沒有執行時的數據參數，程式就會完成。

    • 如果有任何數據執行中參數，函式會傳回SQL_NEED_DATA。

  4. 呼叫 SQLParamData，以擷取 SQLBindParameter 的 ParameterValuePtr 自變數中指定的應用程式定義值，以便處理第一個執行中數據參數。 SQLParamData 會傳回SQL_NEED_DATA。

    注意

    雖然數據執行時參數類似於數據執行數據行，但 SQLParamData 所傳回的值會針對每個數據行不同。 數據執行參數是 SQL 語句中的參數，當語句以 SQLExecDirect 或 SQLExecute 執行時，會使用 SQLPutData 傳送數據。 它們會與 SQLBindParameter 系結。 SQLParamData 傳回的值是傳遞至 ParameterValuePtr 自變數中 SQLBindParameter 的指標值。 數據執行數據行是數據列集中的數據行，當數據列更新或以 SQLBulkOperations 或 SQLSetPos 更新時，數據會以 SQLPutData 傳送數據。 它們會與 SQLBindCol 系結。 SQLParamData 傳回的值是正在處理的 *TargetValuePtr 緩衝區中數據列位址（由 SQLBindCol 呼叫所設定）。

  5. 呼叫 SQLPutData 一或多次以傳送參數的數據。 如果數據值大於 SQLPutData 中指定的 *ParameterValuePtr 緩衝區，則需要一個以上的呼叫;只有在將字元 C 數據傳送至具有字元、二進位或數據源特定數據類型的數據行，或將二進位 C 數據傳送至具有字元的數據行時，才允許對相同參數的 SQLPutData 進行多次呼叫。 binary 或數據源特定的數據類型。

  6. 再次呼叫 SQLParamData ，以發出已針對 參數傳送所有數據的訊號。

    • 如果有更多執行中數據參數， SQLParamData 會傳回SQL_NEED_DATA，並傳回要處理的下一個執行中數據參數的應用程式定義值。 應用程式會重複步驟 4 和 5。

    • 如果沒有其他執行中數據參數，程式就會完成。 如果語句成功執行， SQLParamData 會傳回SQL_SUCCESS或SQL_SUCCESS_WITH_INFO;如果執行失敗，則會傳回SQL_ERROR。 此時， SQLParamData 可以傳回任何 SQLSTATE，此 SQLSTATE 可由用來執行語句的函式傳回（SQLExecDirect 或 SQLExecute）。

      在應用程式擷取語句所產生的所有結果集之後，可以在 *ParameterValuePtr 和 *StrLen_or_IndPtr 緩衝區中取得任何輸入/輸出或輸出參數的輸出值。

呼叫 SQLExecute 或 SQLExecDirect 會將 語句置於SQL_NEED_DATA狀態。 此時，應用程式只能使用 語句或與 語句相關聯的連接句柄呼叫 SQLCancel、SQLGetDiagField、SQLGetDiagRec、SQLGetFunctions、SQLParamData 或 SQLPutData。 如果它會呼叫任何其他具有 語句的函式或與 語句相關聯的連接，則函式會傳回 SQLSTATE HY010 （函數順序錯誤）。 當 SQLParamData 或 SQLPutData 傳回錯誤、SQLParamData 傳回SQL_SUCCESS或SQL_SUCCESS_WITH_INFO，或取消語句時，語句會離開SQL_NEED_DATA狀態。

如果應用程式在驅動程式仍然需要數據執行參數時呼叫 SQLCancel ，驅動程式會取消語句執行;然後應用程式可以再次呼叫 SQLExecute 或 SQLExecDirect 。

擷取串流輸出參數

當應用程式將 InputOutputType 設定為SQL_PARAM_INPUT_OUTPUT_STREAM或SQL_PARAM_OUTPUT_STREAM時，輸出參數值必須由一或多個對 SQLGetData 的呼叫擷取。 當驅動程式具有要傳回應用程式的數據流輸出參數值時，它會傳回SQL_PARAM_DATA_AVAILABLE，以回應下列函式的呼叫：SQLMoreResults、SQLExecute 和 SQLExecDirect。 應用程式會呼叫 SQLParamData 來判斷可用的參數值。

如需SQL_PARAM_DATA_AVAILABLE和串流輸出參數的詳細資訊，請參閱 使用 SQLGetData 擷取輸出參數。

使用參數陣列

當應用程式準備具有參數標記並傳入參數陣列的語句時，有兩種不同的方式可以執行。 其中一種方式是讓驅動程式依賴後端的數位處理功能，在此情況下，具有參數數位的整個語句會被視為一個不可部分完成的單位。 Oracle 是支援數位處理功能的數據源範例。 實作這項功能的另一種方式是讓驅動程序產生一批SQL語句、參數陣列中每個參數集的一個SQL語句，以及執行批次。 參數陣列不能與UPDATE WHERE CURRENT OF語句搭配使用。

處理參數陣列時，可以使用個別結果集/數據列計數（每個參數集各一個）或結果集/數據列計數匯總成一個。 SQLGetInfo 中的SQL_PARAM_ARRAY_ROW_COUNTS選項會指出每個參數集的數據列計數是否可用（SQL_PARC_BATCH），或只有一個數據列計數可用（SQL_PARC_NO_BATCH）。

SQLGetInfo 中的SQL_PARAM_ARRAY_SELECTS選項指出每個參數集都可使用結果集（SQL_PAS_BATCH），還是只有一個結果集可用（SQL_PAS_NO_BATCH）。 如果驅動程式不允許使用參數數位執行結果集產生語句，SQL_PARAM_ARRAY_SELECTS會傳回SQL_PAS_NO_SELECT。

如需詳細資訊，請參閱 SQLGetInfo 函式。

為了支持參數數位，SQL_ATTR_PARAMSET_SIZE語句屬性會設定為指定每個參數的值數目。 如果欄位大於 1，則 APD 的SQL_DESC_DATA_PTR、SQL_DESC_INDICATOR_PTR和SQL_DESC_OCTET_LENGTH_PTR欄位必須指向陣列。 每個陣列的基數等於 SQL_ATTR_PARAMSET_SIZE的值。

APD 的SQL_DESC_ROWS_PROCESSED_PTR欄位指向緩衝區，其中包含已處理的參數集數目，包括錯誤集。 處理每個參數集時，驅動程式會將新的值儲存在緩衝區中。 如果這是 Null 指標，則不會傳回任何數位。 使用參數陣列時，即使設定函式傳回SQL_ERROR，APD SQL_DESC_ROWS_PROCESSED_PTR 欄位所指向的值仍會填入。 如果傳回SQL_NEED_DATA，則APD SQL_DESC_ROWS_PROCESSED_PTR欄位所指向的值會設定為正在處理的參數集。

系結參數陣列並 執行UPDATE WHERE CURRENT OF 語句時，會發生的情況是驅動程序定義。

Column-Wise 參數係結

在數據行式系結中，應用程式會將不同的參數和長度/指標陣列系結至每個參數。

若要使用數據行系結，應用程式會先將 SQL_ATTR_PARAM_BIND_TYPE 語句屬性設定為 SQL_PARAM_BIND_BY_COLUMN。 （這是預設值。針對要繫結的每個資料行，應用程式會執行下列步驟：

  1. 配置參數緩衝區陣列。

  2. 配置長度/指標緩衝區的陣列。

    注意

    如果使用數據行型系結時，應用程式會直接寫入描述項，則可以將個別數位件用於長度和指標數據。

  3. 使用下列自變數呼叫 SQLBindParameter ：

    • ValueType 是參數緩衝區陣列中單一專案的 C 類型。

    • ParameterType 是參數的 SQL 類型。

    • ParameterValuePtr 是參數緩衝區陣列的位址。

    • BufferLength 是參數緩衝區陣列中單一元素的大小。 當數據是固定長度的數據時，會忽略 BufferLength 自變數。

    • StrLen_or_IndPtr是長度/指標陣列的位址。

如需如何使用這項資訊的詳細資訊，請參閱本節稍後的中的。 如需參數數據行系結的詳細資訊，請參閱 係結參數陣列。

Row-Wise 參數係結

在數據列系結中，應用程式會定義結構，其中包含要系結之每個參數的參數和長度/指標緩衝區。

若要使用資料列系結，應用程式會執行下列步驟：

  1. 定義結構來保存單一參數集（包括參數和長度/指標緩衝區），並配置這些結構的陣列。

    注意

    如果使用數據列系結時，應用程式會直接寫入描述項，則可以將個別欄位用於長度和指標數據。

  2. 將 SQL_ATTR_PARAM_BIND_TYPE 語句屬性設定為包含單一參數集的結構大小，或設定為將系結參數之緩衝區實例的大小。 長度必須包含所有系結參數的空間，以及結構或緩衝區的任何填補，以確保當系結參數的位址以指定的長度遞增時，結果會指向下一個數據列中相同參數的開頭。 當您在 ANSI C 中使用 sizeof 運算符時，會保證此行為。

  3. 針對要系結的每個參數，使用下列自變數呼叫 SQLBindParameter ：

    • ValueType 是系結至數據行的參數緩衝區成員類型。

    • ParameterType 是參數的 SQL 類型。

    • ParameterValuePtr 是第一個數位元素中參數緩衝區成員的位址。

    • BufferLength 是參數緩衝區成員的大小。

    • StrLen_or_IndPtr是要系結之長度/指標成員的位址。

如需如何使用這項資訊的詳細資訊，請參閱本節稍後的<ParameterValuePtr 自變數>。 如需參數數據列系結的詳細資訊，請參閱 參數的係結陣列。

錯誤資訊

如果驅動程式未以批次方式實作參數數位（SQL_PARAM_ARRAY_ROW_COUNTS選項等於 SQL_PARC_NO_BATCH），則會處理錯誤情況，就像執行了一個語句一樣。 如果驅動程式實作參數陣列做為批次，應用程式可以使用IPD的SQL_DESC_ARRAY_STATUS_PTR標頭欄位來判斷 SQL 語句的參數，或導致 SQLExecDirect 或 SQLExecute 在參數數位列中的哪個參數傳回錯誤。 此欄位包含每個參數值數據列的狀態資訊。 如果欄位指出發生錯誤，診斷數據結構中的欄位將會指出失敗之參數的數據列和參數編號。 陣列中的元素數目將由APD中的SQL_DESC_ARRAY_SIZE標頭欄位定義，而此欄位可由 SQL_ATTR_PARAMSET_SIZE 語句屬性設定。

注意

APD 中的SQL_DESC_ARRAY_STATUS_PTR標頭字段是用來忽略參數。 如需忽略參數的詳細資訊，請參閱下一節「忽略一組參數」。

當 SQLExecute 或 SQLExecDirect 傳回SQL_ERROR時，IPD 中SQL_DESC_ARRAY_STATUS_PTR欄位所指向的陣列元素將包含SQL_PARAM_ERROR、SQL_PARAM_SUCCESS、SQL_PARAM_SUCCESS_WITH_INFO、SQL_PARAM_UNUSED或SQL_PARAM_DIAG_UNAVAILABLE。

在此陣列中的每個元素中，診斷數據結構會包含一或多個狀態記錄。 結構的SQL_DIAG_ROW_NUMBER欄位表示造成錯誤的參數值列號。 如果可以判斷造成錯誤之參數數據列中的特定參數，則會在 [SQL_DIAG_COLUMN_NUMBER] 欄位中輸入參數編號。

當參數尚未使用時，會輸入SQL_PARAM_UNUSED，因為先前參數發生錯誤，導致 SQLExecute 或 SQLExecDirect 中止。 例如，如果在執行導致 SQLExecute 或 SQLExecDirect 中止的第四十組參數時發生 50 個參數，則會在參數 41 到 50 的狀態陣列中輸入SQL_PARAM_UNUSED。

當驅動程式將參數陣列視為整合型單位時，會輸入SQL_PARAM_DIAG_UNAVAILABLE，因此不會產生這個個別參數層級的錯誤資訊。

處理單一參數集時發生某些錯誤，導致處理陣列中後續的參數集停止。 其他錯誤不會影響後續參數的處理。 哪些錯誤會停止處理是驅動程式定義的。 如果未停止處理，則會處理數位中的所有參數，SQL_SUCCESS_WITH_INFO會因為錯誤而傳回，而 SQL_ATTR_PARAMS_PROCESSED_PTR 定義的緩衝區會設定為已處理的參數集總數（如 SQL_ATTR_PARAMSET_SIZE 語句屬性所定義），其中包含錯誤集。

警告

當 ODBC 3 中參數數位處理時發生錯誤時，ODBC 行為會有所不同。x 比 ODBC 2 中的 x。x. 在 ODBC 2 中。x，函式傳回SQL_ERROR且處理已停止。 SQLParamOptions pirow 自變數所指向的緩衝區包含錯誤數據列的數目。 在 ODBC 3 中。x，函式會傳回SQL_SUCCESS_WITH_INFO，處理可能會停止或繼續。 如果繼續，SQL_ATTR_PARAMS_PROCESSED_PTR所指定的緩衝區將會設定為已處理的所有參數值，包括導致錯誤的參數。 這種行為變更可能會導致現有應用程式發生問題。

當 SQLExecute 或 SQLExecDirect 在完成參數陣列中所有參數集的處理之前傳回時，例如傳回SQL_ERROR或SQL_NEED_DATA時，狀態陣列會包含已處理之參數的狀態。 IPD 中SQL_DESC_ROWS_PROCESSED_PTR欄位所指向的位置，包含造成SQL_ERROR或SQL_NEED_DATA錯誤碼的參數陣列中的數據列編號。 當參數陣列傳送至 SELECT 語句時，狀態陣列值的可用性會由驅動程式定義;在語句執行之後，或擷取結果集之後，就可以使用它們。

忽略一組參數

APD 的SQL_DESC_ARRAY_STATUS_PTR欄位（如 SQL_ATTR_PARAM_STATUS_PTR 語句屬性所設定）可用來指出應該忽略 SQL 語句中的一組系結參數。 若要指示驅動程式在執行期間忽略一或多個參數集，應用程式應該遵循下列步驟：

  1. 呼叫 SQLSetDescField 以設定 APD 的SQL_DESC_ARRAY_STATUS_PTR標頭欄位，以指向 SQLUSMALLINT 值的數位，以包含狀態資訊。 您也可以藉由呼叫 SQLSetStmtAttr 搭配 SQL_ATTR_PARAM_OPERATION_PTR 的 Attribute 來設定此欄位，這可讓應用程式在不取得描述元句柄的情況下設定欄位。

  2. 將 APD SQL_DESC_ARRAY_STATUS_PTR 欄位所定義的陣列每個元素設定為兩個值的其中一個：

    • SQL_PARAM_IGNORE，表示數據列已從語句執行中排除。

    • SQL_PARAM_PROCEED，表示數據列包含在語句執行中。

  3. 呼叫 SQLExecDirect 或 SQLExecute 來執行備妥的語句。

下列規則適用於 APD SQL_DESC_ARRAY_STATUS_PTR 欄位所定義的數位：

  • 根據預設，指標會設定為 null。

  • 如果指標為 null，則會使用所有參數集，就像所有元素都設定為SQL_ROW_PROCEED一樣。

  • 將項目設定為 SQL_PARAM_PROCEED 不保證作業會使用該特定參數集。

  • SQL_PARAM_PROCEED在頭檔中定義為 0。

應用程式可以將APD中的SQL_DESC_ARRAY_STATUS_PTR欄位設定為指向與 IRD 中SQL_DESC_ARRAY_STATUS_PTR欄位所指向的相同陣列。 當將參數係結至數據列數據時，這會很有用。 然後，您可以根據數據列數據的狀態來忽略參數。 除了SQL_PARAM_IGNORE之外，下列程式代碼還會導致忽略 SQL 語句中的參數：SQL_ROW_DELETED、SQL_ROW_UPDATED和SQL_ROW_ERROR。 除了SQL_PARAM_PROCEED之外，下列程式代碼還會導致 SQL 語句繼續：SQL_ROW_SUCCESS、SQL_ROW_SUCCESS_WITH_INFO和SQL_ROW_ADDED。

重新係結參數

應用程式可以執行兩個作業之一來變更系結：

  • 呼叫 SQLBindParameter ，為已經系結的數據行指定新的系結。 驅動程式會以新的系結覆寫舊的系結。

  • 指定要加入至 SQLBindParameter 系結呼叫所指定之緩衝區位址的位移。 如需詳細資訊，請參閱下一節「使用 Offsets 重新系結」。

使用 Offsets 重新系結

當應用程式具有可包含許多參數的緩衝區區域設定，但對SQLExecDirect 或 SQLExecute 的呼叫只使用少數參數時，參數的重新系結特別有用。 緩衝區區域中的剩餘空間可以透過位移修改現有的系結，以用於下一組參數。

APD 中的SQL_DESC_BIND_OFFSET_PTR標頭欄位會指向系結位移。 如果欄位為非 Null，驅動程式會取值指標，而且，如果SQL_DESC_DATA_PTR、SQL_DESC_INDICATOR_PTR和SQL_DESC_OCTET_LENGTH_PTR欄位中沒有任何值是 Null 指標，請在運行時間將取值值新增至描述元記錄中的這些欄位。 執行 SQL 語句時，會使用新的指標值。 重新系結之後，位移仍然有效。 由於SQL_DESC_BIND_OFFSET_PTR是位移的指標，而不是位移本身，因此應用程式可以直接變更位移，而不需要呼叫 SQLSetDescField 或 SQLSetDescRec 來變更描述元欄位。 根據預設，指標會設定為 null。 ARD 的SQL_DESC_BIND_OFFSET_PTR欄位可以透過呼叫 SQLSetDescField 或呼叫具有 fAttribute SQL_ATTR_PARAM_BIND_OFFSET_PTR的 SQLSetStmtAttr 來設定。

系結位移一律會直接新增至SQL_DESC_DATA_PTR、SQL_DESC_INDICATOR_PTR和SQL_DESC_OCTET_LENGTH_PTR欄位中的值。 如果位移變更為不同的值，新值仍會直接新增至每個描述元欄位中的值。 新的位移不會新增至域值的總和任何先前的位移。

描述項

參數係結的方式取決於 APD 和 IPD 的欄位。 SQLBindParameter 中的自變數可用來設定這些描述元字段。 SQLSetDescField 函式也可以設定欄位，雖然 SQLBindParameter 使用效率更高，因為應用程式不需要取得描述元句柄來呼叫 SQLBindParameter。

警告

針對一個語句呼叫 SQLBindParameter 可能會影響其他語句。 當明確配置與語句相關聯的 ARD，也與其他語句相關聯時，就會發生這種情況。 由於 SQLBindParameter 會修改 APD 的欄位，因此修改會套用至與此描述元相關聯的所有語句。 如果這不是必要的行為，應用程式應該在呼叫 SQLBindParameter 之前，將這個描述元與其他語句解除關聯。

在概念上， SQLBindParameter 會依序執行下列步驟：

  1. 呼叫 SQLGetStmtAttr 以取得 APD 句柄。

  2. 呼叫 SQLGetDescField 以取得 APD 的SQL_DESC_COUNT欄位，如果 ColumnNumber 自變數的值超過 SQL_DESC_COUNT 的值，則會呼叫 SQLSetDescField，將 SQL_DESC_COUNT 的值增加到 ColumnNumber。

  3. 多次呼叫 SQLSetDescField ，將值指派給 APD 的下列欄位：

    • 將SQL_DESC_TYPE和SQL_DESC_CONCISE_TYPE設定為 ValueType 的值，但如果 ValueType 是 datetime 或 interval 子類型的其中一個精簡標識符，則會分別將SQL_DESC_TYPE設定為SQL_DATETIME或SQL_INTERVAL，並將SQL_DESC_CONCISE_TYPE設定為精簡標識符，並將SQL_DESC_DATETIME_INTERVAL_CODE設定為對應的 datetime 或 interval 子程式代碼。

    • 將 [SQL_DESC_OCTET_LENGTH] 字段設定為 BufferLength 的值。

    • 將 [SQL_DESC_DATA_PTR] 字段設定為 ParameterValue 的值。

    • 將 [SQL_DESC_OCTET_LENGTH_PTR] 字段設定為 StrLen_or_Ind 的值。

    • 將 [SQL_DESC_INDICATOR_PTR] 欄位也設定為 StrLen_or_Ind 的值。

    StrLen_or_Ind參數同時指定指標資訊和參數值的長度。

  4. 呼叫 SQLGetStmtAttr 以取得 IPD 句柄。

  5. 呼叫 SQLGetDescField 以取得 IPD 的SQL_DESC_COUNT字段，如果 ColumnNumber 自變數的值超過 SQL_DESC_COUNT 的值，則會呼叫 SQLSetDescField，將 SQL_DESC_COUNT 的值增加到 ColumnNumber。

  6. 多次呼叫 SQLSetDescField ，將值指派給 IPD 的下列欄位：

    • 將SQL_DESC_TYPE和SQL_DESC_CONCISE_TYPE設定為ParameterType的值，不同之處在於，如果ParameterType是datetime或interval子類型的其中一個精簡標識符，則會分別將SQL_DESC_TYPE設定為SQL_DATETIME或SQL_INTERVAL，並將SQL_DESC_CONCISE_TYPE設定為精簡標識符，並將SQL_DESC_DATETIME_INTERVAL_CODE設定為對應的 datetime 或 interval 子程式代碼。

    • 視 ParameterType 設定一或多個SQL_DESC_LENGTH、SQL_DESC_PRECISION和SQL_DESC_DATETIME_INTERVAL_PRECISION。

    • 將SQL_DESC_SCALE設定為 DecimalDigits 的值。

如果對 SQLBindParameter 的呼叫失敗，則會未定義在 APD 中設定的描述元欄位內容，且 APD 的SQL_DESC_COUNT欄位不會變更。 此外，IPD 中適當記錄的SQL_DESC_LENGTH、SQL_DESC_PRECISION、SQL_DESC_SCALE和SQL_DESC_TYPE欄位未定義，且 IPD 的SQL_DESC_COUNT欄位不會變更。

從 SQLSetParam 來回轉換呼叫

當 ODBC 1.0 應用程式在 ODBC 3 中呼叫 SQLSetParam 時。x 驅動程式，ODBC 3。x 驅動程式管理員會對應呼叫，如下表所示。

由 ODBC 1.0 應用程式呼叫 呼叫 ODBC 3。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）：

範例

A. 使用 SQLBindParameter 函式

在下列範例中，應用程式會準備 SQL 語句，以將數據插入 ORDERS 數據表。 針對語句中的每個參數，應用程式會呼叫 SQLBindParameter 來指定 ODBC C 數據類型和 參數的 SQL 數據類型，以及將緩衝區系結至每個參數。 針對每個數據列，應用程式會將數據值指派給每個參數，並呼叫 SQLExecute 來執行 語句。

下列範例假設您計算機上的 ODBC 數據源稱為 Northwind，且與 Northwind 資料庫相關聯。

如需更多程式代碼範例，請參閱 SQLBulkOperations 函式、 SQLProcedures 函式、 SQLPutData 函式和 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. 使用具名參數執行預存程式

在下列範例中，應用程式會使用具名參數執行 SQL Server 預存程式。

// 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);  
}
如需下列資訊 請參閱
傳回語句中參數的相關信息 SQLDescribeParam 函式
執行 SQL 語句 SQLExecDirect 函式
執行備妥的 SQL 語句 SQLExecute 函式
釋放語句上的參數緩衝區 SQLFreeStmt 函式
傳回語句參數的數目 SQLNumParams 函式
傳回要傳送數據的下一個參數 SQLParamData 函式
指定多個參數值 SQLParamOptions 函式
在運行時間傳送參數數據 SQLPutData 函式

另請參閱

ODBC API 參考
ODBC 標頭檔
使用 SQLGetData 擷取輸出參數