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);

函數引數

表 1. SQLBindParameter 引數
資料類型 引數 使用 說明
SQLHSTMT StatementHandle 輸入 陳述式控點。
SQLSMALLINT ParameterNumber 輸入 從 1 開始,從左到右循序排序的參數標記號碼。
SQLSMALLINT InputOutput類型 輸入 參數的類型。 實作參數描述子的 SQL_DESC_PARAMETER_TYPE 欄位值也會設為此引數。 支援的類型如下:
  • SQL_PARAM_INPUT: 參數標記與不是儲存程序 CALL 的 SQL 陳述式相關聯; 或者,它會標示儲存程序的輸入參數。

    處理陳述式時,參數的實際資料值會傳送至 資料來源: ParameterValuePtr 緩衝區必須包含有效的輸入資料值; Len_or_IndPtr 緩衝區必須包含對應的長度值或 SQL_NTS、SQL_NULL_DATA 或 (如果應該透過 SQLParamData()SQLPutData()傳送值) SQL_DATA_AT_EXEC。

  • SQL_PARAM_INPUT_OUTPUT: 參數標記與儲存程序的輸入/輸出參數相關聯。

    處理陳述式時,參數的實際資料值會傳送至 資料來源: ParameterValuePtr 緩衝區必須包含有效的輸入資料值; StrLen_or_IndPtr 緩衝區必須包含對應的長度值或 SQL_NTS、SQL_NULL_DATA 或 (如果應該透過 SQLParamData()SQLPutData()傳送值的話) SQL_DATA_AT_EXEC。

  • SQL_PARAM_OUTPUT: 參數標記與儲存程序的輸出參數相關聯。

    處理陳述式之後,輸出參數的資料會傳回至由 ParameterValuePtrStrLen_or_IndPtr指定的應用程式緩衝區,除非兩者都是 NULL 指標,否則會捨棄輸出資料。 如果輸出參數沒有回覆值,則 StrLen_or_IndPtr 會設為 SQL_NULL_DATA。

SQLSMALLINT ValueType 輸入 參數的 C 資料類型。 支援下列類型:
  • SQL_BIGINT
  • SQL_BINARY
  • SQL_BLOB
  • SQL_BLOB_LOCATOR
  • 變更開始SQL_BOOLEAN變更結束
  • SQL_CHAR
  • SQL_CLOB
  • SQL_CLOB_LOCATOR
  • SQL_DATETIME
  • SQL_DBCLOB
  • SQL_DBCLOB_LOCATOR
  • SQL_DECFLOAT
  • SQL_DECIMAL
  • SQL_DOUBLE
  • SQL_FLOAT
  • SQL_GRAPHIC
  • SQL_INTEGER
  • SQL_NUMERIC
  • SQL_REAL
  • SQL_SMALLINT
  • SQL_TYPE_DATE
  • SQL_TYPE_TIME
  • SQL 類型 _ 時間戳記
  • SQL_VARBINARY
  • SQL_VARCHAR
  • SQL_VARGRAPHIC
  • SQL_WCHAR
  • SQL_WVARCHAR

指定 SQL_C_DEFAULT 會將資料從其預設 C 資料類型傳送至 ParameterType中指出的類型。

SQLSMALLINT ParameterType 輸入 參數的 SQL 資料類型。 支援的類型如下:
  • SQL_BIGINT
  • SQL_BINARY
  • SQL_BLOB
  • SQL_BLOB_LOCATOR
  • 變更開始SQL_BOOLEAN變更結束
  • SQL_CHAR
  • SQL_CLOB
  • SQL_CLOB_LOCATOR
  • SQL_DATETIME
  • SQL_DBCLOB
  • SQL_DBCLOB_LOCATOR
  • SQL_DECFLOAT
  • SQL_DECIMAL
  • SQL_DOUBLE
  • SQL_FLOAT
  • SQL_GRAPHIC
  • SQL_INTEGER
  • SQL_NUMERIC
  • SQL_REAL
  • SQL_SMALLINT
  • SQL_TYPE_DATE
  • SQL_TYPE_TIME
  • SQL 類型 _ 時間戳記
  • SQL_VARBINARY
  • SQL_VARCHAR
  • SQL_VARGRAPHIC
  • SQL_WCHAR
  • SQL_WVARCHAR
  • SQL_XML
SQLINTEGER ColumnSize 輸入 對應參數標記的精準度。
  • 如果 ValueType 表示二進位或單位元組字串 (例如, SQL_CHAR) ,則這是此參數標記的長度上限 (以位元組為單位)。
  • 如果 ValueType 表示雙位元組字串 (例如, SQL_GRAPHIC) ,則這是此參數的長度上限 (以雙位元組字元為單位)。
  • 如果 ValueType 表示 SQL_DECIMAL 或 SQL_NUMERIC ,則這是小數位數上限。
  • 如果 ValueType 表示 SQL_TYPE_TIMESTAMP ,則這是針對此參數所傳送的長度上限 (以位元組為單位)。
  • 否則,會忽略此引數。
SQLSMALLINT DecimalDigits 輸入 如果 ParameterType 是 SQL_DECIMAL 或 SQL_NUMERIC ,則為對應參數的小數位數。 如果 ParameterType 是 SQL_TYPE_TIMESTAMP ,則這是時間戳記字元表示法中小數點右側的位數 (例如, yyyy-mm-dd hh:mm:ss.fff 的小數位數為 3)。

除了這裡提及的 ParameterType 值之外,還會忽略 DecimalDigits

SQLPOINTER ParameterValuePtr

輸入 (延遲) 及/或輸出 (延遲)

  • 在輸入 (InputOutput類型 設為 SQL_PARAM_INPUT 或 SQL_PARAM_INPUT_OUTPUT) 上,下列狀況為 true:

    在處理時,如果 StrLen_or_IndPtr 不包含 SQL_NULL_DATA 或 SQL_DATA_AT_EXEC ,則 ParameterValuePtr 會指向包含參數實際資料的緩衝區。

    如果 StrLen_or_IndPtr 包含 SQL_DATA_AT_EXEC ,則 ParameterValuePtr 是與此參數相關聯的應用程式定義 32 位元值。 這個 32 位元值會透過後續的 SQLParamData() 呼叫傳回給應用程式。

    如果呼叫 SQLParamOptions() 為參數指定多個值,則 ParameterValuePtrBufferLength 位元組之輸入緩衝區陣列的指標。

  • 在輸出上 (InputOutput類型 設為 SQL_PARAM_OUTPUT 或 SQL_PARAM_INPUT_OUTPUT) ,下列狀況為 true:

    ParameterValuePtr 指向儲存程序的輸出參數值儲存所在的緩衝區。

    如果 InputOutput類型 設為 SQL_PARAM_OUTPUT ,且 ParameterValuePtrStrLen_or_IndPtr 都是 NULL 指標,則會捨棄儲存程序呼叫中的輸出參數值或回覆值。

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 必須是雙位元組字元數,而不是位元組數。

當呼叫 SQLExecute()SQLExecDirect() ,且 StrLen_or_IndPtr 指向 SQL_DATA_AT_EXEC 值時,參數的資料會隨 SQLPutData()一起傳送。 此參數稱為 執行時資料 參數。

用法

參數標記以 "?" 表示 SQL 陳述式中的字元,並用來指出陳述式中的位置,當處理陳述式時,會在陳述式中替換應用程式提供的值。 此值是從應用程式變數取得。

在執行 SQL 陳述式之前,應用程式必須將變數連結至 SQL 陳述式中的每一個參數標記。 對於此函數, ParameterValuePtrStrLen_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 資料類型相容,否則會發生錯誤。

因為在處理陳述式之前,不會驗證 ParameterValuePtrStrLen_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 陳述式之後,會將參數的資料傳回給應用程式。 如果 ParameterValuePtrStrLen_or_IndPtr 引數都是空值指標,則 Db2 for i CLI 會捨棄輸出值。 如果資料來源未傳回輸出參數的值, Db2 for i CLI 會將 StrLen_or_IndPtr 緩衝區設為 SQL_NULL_DATA。
  • 對於此函數, ParameterValuePtrStrLen_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

錯誤狀況

表 2. SQLBindParameter SQLSTATE
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 指定的值。

參照