SQLBindParameter -將參數標記連結至緩衝區
SQLBindParameter()
用來將 SQL 陳述式中的 (連結) 參數標記與應用程式變數相關聯。 當呼叫 SQLExecute()
或 SQLExecDirect()
時,資料會從應用程式傳送至「資料庫管理系統 (DBMS)」。 傳送資料時可能會發生資料轉換。
此函數也必須用來將應用程式儲存體連結至儲存程序的參數,其中參數可以是輸入及/或輸出。
語法
SQLRETURN SQLBindParameter(SQLHSTMT StatementHandle,
SQLSMALLINT ParameterNumber,
SQLSMALLINT InputOutputType,
SQLSMALLINT ValueType,
SQLSMALLINT ParameterType,
SQLINTEGER ColumnSize,
SQLSMALLINT DecimalDigits,
SQLPOINTER ParameterValuePtr,
SQLINTEGER BufferLength,
SQLINTEGER *StrLen_or_IndPtr);
函數引數
資料類型 | 引數 | 使用 | 說明 |
---|---|---|---|
SQLHSTMT | StatementHandle | 輸入 | 陳述式控點。 |
SQLSMALLINT | ParameterNumber | 輸入 | 從 1 開始,從左到右循序排序的參數標記號碼。 |
SQLSMALLINT | InputOutput類型 | 輸入 | 參數的類型。 實作參數描述子的 SQL_DESC_PARAMETER_TYPE 欄位值也會設為此引數。 支援的類型如下:
|
SQLSMALLINT | ValueType | 輸入 | 參數的 C 資料類型。 支援下列類型:
指定 SQL_C_DEFAULT 會將資料從其預設 C 資料類型傳送至 ParameterType中指出的類型。 |
SQLSMALLINT | ParameterType | 輸入 | 參數的 SQL 資料類型。 支援的類型如下:
|
SQLINTEGER | ColumnSize | 輸入 | 對應參數標記的精準度。
|
SQLSMALLINT | DecimalDigits | 輸入 | 如果 ParameterType 是 SQL_DECIMAL 或 SQL_NUMERIC ,則為對應參數的小數位數。 如果 ParameterType 是 SQL_TYPE_TIMESTAMP ,則這是時間戳記字元表示法中小數點右側的位數 (例如, yyyy-mm-dd hh:mm:ss.fff 的小數位數為 3)。 除了這裡提及的 ParameterType 值之外,還會忽略 DecimalDigits 。 |
SQLPOINTER | ParameterValuePtr | 輸入 (延遲) 及/或輸出 (延遲) |
|
SQLINTEGER | BufferLength | 輸入 | 未被使用。 |
SQLINTEGER * | StrLen_or_IndPtr | 輸入 (延遲) ,輸出 (延遲) | 如果這是輸入或輸入/輸出參數,則這是指向位置的指標,該位置包含 (處理陳述式時) 儲存在 ParameterValuePtr的參數標記值長度。 若要指定參數記號的空值,此儲存體位置必須包含 SQL_NULL_DATA。 若要指定參數記號的延伸指示器值,此儲存體位置必須包含 SQL_UNASSIGNED 或 SQL_DEFAULT_PARAM。 必須將 SQL_ATTR_EXTENDED_INDICATORS 連線屬性設為 SQL_TRUE ,才能允許使用其中一個值。 如果 ValueType 是 SQL_C_CHAR ,則此儲存體位置必須包含儲存在 ParameterValuePtr中的資料確切長度,或者如果 ParameterValuePtr 中的內容以空值結尾,則包含 SQL_NTS。 對於 ParameterValuePtr的所有值,如果 ValueType 指出 LOB 資料,則此儲存體位置必須包含儲存在 ParameterValuePtr的資料長度。 此長度值必須以位元組為單位來指定,而不是以雙位元組字元數來指定。 如果 ValueType 指出字元資料 (明確地或隱含地使用 SQL_C_DEFAULT) ,且此指標設為 NULL ,則會假設應用程式一律在 ParameterValuePtr中提供以空值結尾的字串。 這也意味著此參數標記永不具有空值。 如果 ValueType 指定任何形式的雙位元組字元資料,則 StrLen_or_IndPtr 必須是雙位元組字元數,而不是位元組數。 當呼叫 |
用法
參數標記以 "?" 表示 SQL 陳述式中的字元,並用來指出陳述式中的位置,當處理陳述式時,會在陳述式中替換應用程式提供的值。 此值是從應用程式變數取得。
在執行 SQL 陳述式之前,應用程式必須將變數連結至 SQL 陳述式中的每一個參數標記。 對於此函數, ParameterValuePtr 及 StrLen_or_IndPtr 是延遲引數; 處理陳述式時,儲存體位置必須有效且包含輸入資料值。 這表示將 SQLExecDirect()
或 SQLExecute()
呼叫保留在與 SQLBindParameter()
呼叫相同的程序範圍中,或這些儲存體位置必須以靜態或廣域方式動態配置或宣告。
參數記號是由數字 (ParameterNumber) 所參照,並從左到右依序編號為對應的? 出現在陳述式文字中,從 1 開始。
在使用 SQL_DROP 或 SQL_RESET_PARAMS 選項呼叫 SQLFreeStmt()
之前,或在針對相同參數 ParameterNumber 號碼再次呼叫 SQLBindParameter()
之前,此函數所連結的所有參數都仍然有效。
處理 SQL 陳述式及結果之後,應用程式可能想要重複使用陳述式控點來處理不同的 SQL 陳述式。 如果參數標記規格不同 (參數數目、長度或類型) ,則應該使用 SQL_RESET_PARAMS 來呼叫 SQLFreeStmt()
,以重設或清除參數連結。
ValueType 所提供的 C 緩衝區資料類型必須與 ParameterType所指出的 SQL 資料類型相容,否則會發生錯誤。
因為在處理陳述式之前,不會驗證 ParameterValuePtr 及 StrLen_or_IndPtr 所參照變數中的資料,所以在呼叫 SQLExecute()
或 SQLExecDirect()
之前不會偵測或報告資料內容或格式錯誤。
SQLBindParameter()
基本上是透過提供指定參數是輸入、輸入及輸出還是輸出的方法,來延伸 SQLSetParam()
函數的功能。 適當處理儲存程序的參數需要此資訊。
InputOutputType 引數指定參數的類型。 SQL 陳述式中未呼叫程序的所有參數都是輸入參數。 儲存程序呼叫中的參數可以是輸入、輸入/輸出或輸出參數。 即使 DB2® 儲存程序引數慣例通常暗示所有程序引數都是輸入/輸出,應用程式設計師仍可以選擇在 SQLBindParameter()
上更確切地指定輸入或輸出本質,以遵循更嚴格的編碼樣式。 此外,請注意這些類型應該與使用 SQL CREATE PROCEDURE 陳述式登錄儲存程序時所指定的參數類型一致。
- 如果應用程式無法判定程序呼叫中參數的類型,請將 InputOutput類型 設為 SQL_PARAM_Input; 如果資料來源傳回參數值,則 Db2® for i CLI 會捨棄該參數。
- 如果應用程式已將參數標示為 SQL_PARAM_INPUT_OUTPUT 或 SQL_PARAM_OUTPUT ,且資料來源未傳回值,則 Db2 for i CLI 會將 StrLen_or_IndPtr 緩衝區設為 SQL_NULL_DATA。
- 如果應用程式將參數標示為 SQL_PARAM_OUTPUT ,則在處理 CALL 陳述式之後,會將參數的資料傳回給應用程式。 如果 ParameterValuePtr 及 StrLen_or_IndPtr 引數都是空值指標,則 Db2 for i CLI 會捨棄輸出值。 如果資料來源未傳回輸出參數的值, Db2 for i CLI 會將 StrLen_or_IndPtr 緩衝區設為 SQL_NULL_DATA。
- 對於此函數, ParameterValuePtr 及 StrLen_or_IndPtr 都是延遲引數。 如果 InputOutputType 設為 SQL_PARAM_INPUT 或 SQL_PARAM_INPUT_OUTPUT ,則處理陳述式時,儲存體位置必須有效且包含輸入資料值。 這表示將
SQLExecDirect()
或SQLExecute()
呼叫保留在與SQLBindParameter()
呼叫相同的程序範圍中,或者必須動態配置或靜態/廣域宣告這些儲存體位置。同樣地,如果 InputOutput類型 設為 SQL_PARAM_OUTPUT 或 SQL_PARAM_INPUT_OUTPUT ,則 ParameterValuePtr 及 StrLen_or_IndPtr 緩衝區位置必須保持有效,直到處理 CALL 陳述式為止。
當使用 SQLBindParameter()
將應用程式變數連結至儲存程序的輸出參數時,如果 ParameterValuePtr 緩衝區在記憶體中的 StrLen_or_IndPtr 緩衝區之後連續放置,則 Db2 for i CLI 可以提供一些效能加強功能。 例如:
struct { SQLINTEGER StrLen_or_IndPtr;
SQLCHAR ParameterValuePtr[MAX_BUFFER];
} column;
對於十進位浮點資料類型,可以使用預設符號 C 資料類型常數來指定 32、64 或 128 的精準度。 例如,若要指定精準度為 128 個位元組的十進位浮點資料類型, ValueType 可以設為 SQL_C_DECIMAL128。
回覆碼
- SQL_SUCCESS
- SQL_SUCCESS_WITH_INFO
- SQL_ERROR
- SQL_INVALID_HANDLE
錯誤狀況
SQL狀態 | 說明 | 說明 |
---|---|---|
07006 | 轉換無效 | 從 ValueType 引數所識別的資料值轉換為 ParameterType 引數所識別的資料類型,不是有意義的轉換。 (例如,從 SQL_C_DATE 轉換為 SQL_DOUBLE。) |
40003 08S01 | 通訊鏈結失敗 | 在完成功能之前,應用程式與資料來源之間的通訊鏈結失敗。 |
58004 | 非預期的系統失敗 | 無法復原的系統錯誤。 |
HY001 | 記憶體配置失敗 | Db2 for i CLI 無法配置支援處理或完成函數所需的記憶體。 |
HY003 | 程式類型超出範圍 | 引數 ParameterNumber 指定的值不是有效的資料類型或 SQL_C_DEFAULT。 |
HY004 | SQL 資料類型超出範圍 | 指定給引數 ParameterType 的值不是有效的 SQL 資料類型。 |
HY009 | 引數值無效 | 引數 ParameterValuePtr 是空值指標,引數 StrLen_or_IndPtr 是空值指標,而 InputOutputType 不是 SQL_PARAM_OUTPUT。 |
HY010 | 函數順序錯誤 | 在 SQLExecute() 或 SQLExecDirect() 已傳回 SQL_NEED_DATA 之後呼叫函數,但尚未針對所有 data-at-execution 參數傳送資料。 |
HY013 | 非預期的記憶體處理錯誤 | Db2 for i CLI 無法存取支援處理或完成函數所需的記憶體。 |
HY014 | 控點太多 | 已配置控點數上限。 |
HY021 | 描述子資訊不一致 | 在一致性檢查期間檢查的描述子資訊不一致。 |
HY090 | 字串或緩衝區長度無效 | 指定給 BufferLength 引數的值小於 0。 |
HY093 | 參數號碼無效 | 指定給 ValueType 引數的值小於 1 或大於 資料來源支援的參數數目上限。 |
HY094 | 小數位數值無效 | 為 ParameterType 指定的值為 SQL_DECIMAL 或 SQL_NUMERIC ,且為 DecimalDigits 指定的值小於 0 或大於引數 ParamDef (精準度) 的值。 為 ParameterType 指定的值為 SQL_C_TIMESTAMP ,且 ParameterType 的值為 SQL_CHAR 或 SQL_VARCHAR ,且 DecimalDigits 的值小於 0 或大於 12。 |
HY104 | 精準度值無效 | 為 ParameterType 指定的值為 SQL_DECIMAL 或 SQL_NUMERIC ,且為 ParamDef 指定的值小於 1。 |
HY105 | 參數類型無效 | InputOutput類型 不是 SQL_PARAM_INPUT、SQL_PARAM_OUTPUT 或 SQL_PARAM_INPUT_OUTPUT 之一。 |
HYC00 | 驅動程式無法使用 | Db2 for i CLI 或資料來源不支援由指定給引數 ValueType 的值與指定給引數 ParameterType的值組合指定的轉換。 Db2 for i CLI 或資料來源不支援為引數 ParameterType 指定的值。 |