SQLSetDescRec 函式

  • 發行項

一致性
引進版本：ODBC 3.0 標準合規性：ISO 92

摘要
SQLSetDescRec 函式會 設定多個描述元欄位，這些欄位會影響系結至資料行或參數資料的資料類型和緩衝區。

語法

  
SQLRETURN SQLSetDescRec(  
      SQLHDESC      DescriptorHandle,  
      SQLSMALLINT   RecNumber,  
      SQLSMALLINT   Type,  
      SQLSMALLINT   SubType,  
      SQLLEN        Length,  
      SQLSMALLINT   Precision,  
      SQLSMALLINT   Scale,  
      SQLPOINTER    DataPtr,  
      SQLLEN *      StringLengthPtr,  
      SQLLEN *      IndicatorPtr);

引數

DescriptorHandle
[輸入]描述項控制碼。 這不得為 IRD 控制碼。

RecNumber
[輸入]表示包含要設定之欄位的描述元記錄。 描述項記錄是從 0 編號，記錄號碼 0 是書簽記錄。 這個引數必須等於或大於 0。 如果 RecNumber 大於 SQL_DESC_COUNT 的值，SQL_DESC_COUNTis變更為 RecNumber 的值 。

類型
[輸入]要設定描述項記錄SQL_DESC_TYPE欄位的值。

子類型
[輸入]對於類型為SQL_DATETIME或SQL_INTERVAL的記錄，這是要設定SQL_DESC_DATETIME_INTERVAL_CODE欄位的值。

長度
[輸入]要設定描述項記錄SQL_DESC_OCTET_LENGTH欄位的值。

有效位數
[輸入]要設定描述項記錄SQL_DESC_PRECISION欄位的值。

縮放規模
[輸入]要設定描述項記錄SQL_DESC_SCALE欄位的值。

DataPtr
[延遲的輸入或輸出]要設定描述項記錄SQL_DESC_DATA_PTR欄位的值。 DataPtr 可以設定為 Null 指標。

DataPtr 引數可以設定為 null 指標，將SQL_DESC_DATA_PTR欄位設定為 null 指標。 如果 DescriptorHandle 引數中的 控制碼與 ARD 相關聯，這會解除資料行的系結。

StringLengthPtr
[延遲的輸入或輸出]要設定描述項記錄SQL_DESC_OCTET_LENGTH_PTR欄位的值。 StringLengthPtr 可以設定為 null 指標，將SQL_DESC_OCTET_LENGTH_PTR欄位設定為 null 指標。

IndicatorPtr
[延遲的輸入或輸出]要設定描述項記錄SQL_DESC_INDICATOR_PTR欄位的值。 IndicatorPtr 可以設定為 null 指標，將SQL_DESC_INDICATOR_PTR欄位設定為 null 指標。

傳回

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR或SQL_INVALID_HANDLE。

診斷

當 SQLSetDescRec 傳回SQL_ERROR或SQL_SUCCESS_WITH_INFO時，可以呼叫 具有 SQL_HANDLE_DESC HandleType 的 SQLGetDiagRec 和 DescriptorHandle 的 HandleType 來取得相關聯的 SQLSTATE 值。 下表列出 SQLSetDescRec 通常傳 回的 SQLSTATE 值，並說明此函式內容中的每個值;標記法 「（DM）」 在驅動程式管理員傳回的 SQLSTATE 描述之前。 除非另有說明，否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。

SQLSTATE 錯誤 描述
01000 一般警告 驅動程式特定的資訊訊息。 （函式會傳回SQL_SUCCESS_WITH_INFO。）
07009 不正確描述元索引 RecNumber 引數設定為 0，而 描述元Handle 則參考 IPD 控制碼。

RecNumber 引數小於 0。

RecNumber 引數大於資料來源可支援的資料行或參數數目上限，而 DescriptorHandle 引數是 APD、IPD 或 ARD。

RecNumber 引數等於 0，而 DescriptorHandle 引數則參考隱含配置的 APD。 （此錯誤不會與明確配置的應用程式描述元一起發生，因為目前還不清楚明確配置的應用程式描述元是否為 APD 或 ARD，直到執行時間為止。
08S01 通訊連結失敗 驅動程式與驅動程式連線的資料來源之間的通訊連結在函式完成處理之前失敗。
HY000 一般錯誤 發生錯誤，其中沒有特定的 SQLSTATE，也沒有定義任何實作特定的 SQLSTATE。 *MessageText 緩衝區中 SQLGetDiagRec 傳 回的錯誤訊息描述錯誤及其原因。
HY001 記憶體配置錯誤 驅動程式無法配置支援執行或完成函式所需的記憶體。
HY010 函式順序錯誤 （DM） 描述項Handle 與 StatementHandle 相關聯，其會呼叫非同步執行函式（而非此函式），並在呼叫此函式時仍在執行中。

（DM） SQLExecute 、 SQLExecDirect 、 SQLBulkOperations 或 SQLSetPos 已針對 與 DescriptorHandle 相關聯並傳回SQL_NEED_DATA的 StatementHandle 呼叫。 在針對所有資料執行中參數或資料行傳送資料之前，會呼叫此函式。

（DM） 針對與 DescriptorHandle 相關聯的連接控制碼呼叫非同步執行函式。 呼叫 SQLSetDescRec 函式時 ，這個非同步函式仍在執行中。

（DM） SQLExecute 、 SQLExecDirect 或 SQLMoreResults 已針對與 DescriptorHandle 相關聯的 其中一個語句控制碼呼叫，並傳回SQL_PARAM_DATA_AVAILABLE。 在擷取所有資料流程參數的資料之前，會呼叫此函式。
HY013 記憶體管理錯誤 無法處理函式呼叫，因為基礎記憶體物件無法存取，可能是因為記憶體不足的情況。
HY016 無法修改實作資料列描述元 DescriptorHandle 引數與 IRD 相關聯。
HY021 不一致的描述元資訊 [ 類型 ] 欄位或與描述元中SQL_DESC_TYPE欄位相關聯的任何其他欄位無效或一致。

在一致性檢查期間檢查的描述元資訊不一致。 （請參閱本節稍後的。
HY090 不正確字串或緩衝區長度 （DM） 驅動程式是 ODBC 2.x 驅動程式，描述元是 ARD、 ColumnNumber 引數設定為 0，而針對 BufferLength 指定的 值不等於 4。
HY117 連線因為未知的交易狀態而暫停。 只允許中斷連線和唯讀函式。 （DM） 如需暫停狀態的詳細資訊，請參閱 SQLEndTran 函式 。
HYT01 已超過連線逾時 在資料來源回應要求之前，連線逾時期限已過期。 連線逾時期間是透過 SQLSetConnectAttr 來設定，SQL_ATTR_CONNECTION_TIMEOUT。
IM001 驅動程式不支援此函式 （DM） 與 DescriptorHandle 相關聯的 驅動程式不支援 函式。

註解

應用程式可以呼叫 SQLSetDescRec ，為單一資料行或參數設定下欄欄位：

  • SQL_DESC_TYPE

  • SQL_DESC_DATETIME_INTERVAL_CODE （針對類型為SQL_DATETIME或SQL_INTERVAL的記錄）

  • SQL_DESC_OCTET_LENGTH

  • SQL_DESC_PRECISION

  • SQL_DESC_SCALE

  • SQL_DESC_DATA_PTR

  • SQL_DESC_OCTET_LENGTH_PTR

  • SQL_DESC_INDICATOR_PTR

注意

如果對 SQLSetDescRec 的呼叫 失敗，則 RecNumber 引數所 識別的描述項記錄內容未 定義。

系結資料行或參數時， SQLSetDescRec 可讓您變更影響系結的多個欄位，而不需要呼叫 SQLBindCol 或 SQLBindParameter 或 多次呼叫 SQLSetDescField 。 SQLSetDescRec 可以在目前未與 語句關聯的描述元上設定欄位。 請注意， SQLBindParameter 會設定比 SQLSetDescRec 更多的 欄位，可以在一次呼叫中同時設定 APD 和 IPD 上的欄位，而且不需要描述元控制碼。

注意

在呼叫 SQLSetDescRec 之前，應一律設定語句屬性SQL_ATTR_USE_BOOKMARKS，其 自 變數為 0，以設定書簽欄位。 雖然這不是強制性的，但強烈建議這麼做。

一致性檢查

每當應用程式設定 APD、ARD 或 IPD 的SQL_DESC_DATA_PTR欄位時，驅動程式會自動執行一致性檢查。 如果任何欄位與其他欄位不一致， SQLSetDescRec 會傳回 SQLSTATE HY021 （不一致的描述元資訊）。

每當應用程式設定 APD、ARD 或 IPD 的SQL_DESC_DATA_PTR欄位時，驅動程式就會檢查SQL_DESC_TYPE欄位的值，以及適用于該SQL_DESC_TYPE欄位的值有效且一致。 呼叫 SQLBindParameter 或 SQLBindCol 時 ，或呼叫 APID、ARD 或 IPD 的 SQLSetDescRec 時 ，一律會執行這項檢查。 此一致性檢查包含下列描述項欄位的檢查：

  • SQL_DESC_TYPE欄位必須是其中一個有效的 ODBC C 或 SQL 類型，或是驅動程式特定的 SQL 類型。 SQL_DESC_CONCISE_TYPE欄位必須是其中一個有效的 ODBC C 或 SQL 類型，或是驅動程式特定的 C 或 SQL 類型，包括簡潔的日期時間和間隔類型。

  • 如果SQL_DESC_TYPE記錄欄位是SQL_DATETIME或SQL_INTERVAL，則SQL_DESC_DATETIME_INTERVAL_CODE欄位必須是其中一個有效的日期時間或間隔代碼。 （請參閱 中 SQL_DESC_DATETIME_INTERVAL_CODE欄位的描述SQLSetDescField .）

  • 如果 [SQL_DESC_TYPE] 欄位指出數數值型別，則會驗證SQL_DESC_PRECISION和SQL_DESC_SCALE欄位是否有效。

  • 如果 [SQL_DESC_CONCISE_TYPE] 欄位是時間或時間戳記資料類型、具有秒元件的間隔類型，或是具有時間元件的其中一個間隔資料類型，則SQL_DESC_PRECISION欄位會驗證為有效的秒數有效位數。

  • 如果SQL_DESC_CONCISE_TYPE是間隔資料類型，SQL_DESC_DATETIME_INTERVAL_PRECISION欄位會驗證為有效的間隔前置有效位數值。

通常不會設定 IPD 的 SQL_DESC_DATA_PTR 欄位；不過，應用程式可以這麼做，以強制 IPD 欄位執行一致性檢查。 無法在 IRD 執行一致性檢查。 IPD 的 SQL_DESC_DATA_PTR 欄位設定為的值不會實際儲存，而且無法透過呼叫 SQLGetDescField 或 SQLGetDescRec 來擷取；進行此設定只會強制進行一致性檢查。

如需下列資訊 請參閱
系結資料行 SQLBindCol 函式
系結參數 SQLBindParameter 函式
取得單一描述元欄位 SQLGetDescField 函式
取得多個描述元欄位 SQLGetDescRec 函式
設定單一描述元欄位 SQLSetDescField 函式

另請參閱

ODBC API 參考
ODBC 標頭檔