共用方式為

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

參數

描述元Handle
[輸入]描述項句柄。 這不得為 IRD 句柄。

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

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

SubType
[輸入]對於類型為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時，可以呼叫 SQLGetDiagRec，並以 HandleType SQL_HANDLE_DESC 和 HandleDescriptorHandle來取得相關聯的 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，而參考隱含配置的 APD 的 DescriptorHandle 自變數。 （此錯誤不會與明確配置的應用程式描述元一起發生，因為目前還不清楚明確配置的應用程式描述元是否為 APD 或 ARD，直到運行時間為止。
08S01 通訊連結失敗 驅動程式與驅動程式連線的數據源之間的通訊連結在函式完成處理之前失敗。
HY000 一般錯誤 發生錯誤，其中沒有特定的 SQLSTATE，也沒有定義任何實作特定的 SQLSTATE。 *MessageText 緩衝區中 SQLGetDiagRec 所傳回的錯誤訊息會描述錯誤及其原因。
HY001 記憶體配置錯誤 驅動程式無法配置支援執行或完成函式所需的記憶體。
HY010 函式順序錯誤 （DM） 描述元Handle 與一個 StatementHandle 相關聯，其中會呼叫異步執行函式（而非此函式），並在呼叫此函式時仍在執行中。

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

（DM） 針對與 DescriptorHandle相關聯的連接句柄呼叫異步執行函式。 呼叫 SQLSetDescRec 函式時，這個異步函式仍在執行中。

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

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

評論

應用程式可以呼叫 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 上的字段，而且不需要描述元句柄。

注意

一律應該先設定語句屬性SQL_ATTR_USE_BOOKMARKS，再呼叫 sqlSetDescRec，並使用 0 的 RecNumber 自變數來設定書簽字段。 雖然這不是強制性的，但強烈建議這麼做。

一致性檢查

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

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

  • 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欄位必須是其中一個有效的日期時間或間隔代碼。 （請參閱 SQLSetDescField中SQL_DESC_DATETIME_INTERVAL_CODE欄位的描述。

  • 如果 [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 頭檔