分享方式:


SQLSetDescField 函式

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

摘要
SQLSetDescField 會設定描述元記錄之單一欄位的值。

語法

SQLRETURN SQLSetDescField(  
     SQLHDESC      DescriptorHandle,  
     SQLSMALLINT   RecNumber,  
     SQLSMALLINT   FieldIdentifier,  
     SQLPOINTER    ValuePtr,  
     SQLINTEGER    BufferLength);  

引數

DescriptorHandle
[輸入]描述項控制碼。

RecNumber
[輸入]指出描述項記錄,其中包含應用程式要設定的欄位。 描述項記錄是從 0 編號,記錄號碼 0 是書簽記錄。 標頭 欄位會忽略 RecNumber 引數。

FieldIdentifier
[輸入]指出要設定其值之描述元的欄位。 如需詳細資訊,請參閱一節中的「 FieldIdentifier 引數」。

ValuePtr
[輸入]包含描述元資訊或整數值的緩衝區指標。 資料類型取決於 FieldIdentifier 的值 。 如果 ValuePtr 是整數值,視 FieldIdentifier 引數的值 而定,它可以視為 8 個位元組 (SQLLEN)、4 個位元組 (SQLINTEGER) 或 2 個位元組 (SQLSMALLINT)。

BufferLength
[輸入]如果 FieldIdentifier 是 ODBC 定義的欄位,而 ValuePtr 指向字元字串或二進位緩衝區,則此引數應該是 * ValuePtr 的長度。 對於字元字串資料,這個引數應該包含字串中的位元組數目。

如果 FieldIdentifier 是 ODBC 定義的欄位,而 ValuePtr 是整數, 則會忽略 BufferLength

如果 FieldIdentifier 是驅動程式定義的欄位,應用程式會藉由設定 BufferLength 引數,將欄位的性質指示給驅動程式管理員。 BufferLength 可以具有下列值:

  • 如果 ValuePtr 是字元字串的指標, 則 BufferLength 是字串的長度或SQL_NTS。

  • 如果 ValuePtr 是二進位緩衝區的指標,則應用程式會將SQL_LEN_BINARY_ATTR( length ) 宏的結果放在 BufferLength 。 這會在 BufferLength 放置負值。

  • 如果 ValuePtr 是字元字串或二進位字串以外的值指標,則 BufferLength 的值應該SQL_IS_POINTER。

  • 如果 ValuePtr 包含固定長度的值,則 BufferLength 會視需要SQL_IS_INTEGER、SQL_IS_UINTEGER、SQL_IS_SMALLINT或SQL_IS_USMALLINT。

傳回

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR或SQL_INVALID_HANDLE。

診斷

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

SQLSTATE 錯誤 描述
01000 一般警告 驅動程式特定的資訊訊息。 (函式會傳回SQL_SUCCESS_WITH_INFO。)
01S02 選項值已變更 驅動程式不支援在 *ValuePtr 中指定的值 (如果 ValuePtr 是指標)或 ValuePtr 中的 值(如果 ValuePtr 是整數值),或 *ValuePtr 因實作工作條件而無效,因此驅動程式會取代類似的值。 (函式會傳回SQL_SUCCESS_WITH_INFO。)
07009 不正確描述元索引 FieldIdentifier 引數是記錄欄位、 RecNumber 引數為 0,而 DescriptorHandle 引數則參考 IPD 控制碼。

RecNumber 引數小於 0,而 描述元Handle 引數則參考了 ARD 或 APD。

RecNumber 引數大於資料來源可支援的資料行或參數數目上限,以及 參考 APD 或 ARD 的 DescriptorHandle 引數。

(DM) FieldIdentifier 引數SQL_DESC_COUNT,而 *ValuePtr 引數小於 0。

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

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

(DM) 針對與 DescriptorHandle 相關聯的連接控制碼呼叫非同步執行函式。 呼叫 SQLSetDescField 函式時 ,這個非同步函式仍在執行中。

(DM) SQLExecute SQLExecDirect SQLMoreResults 已針對與 DescriptorHandle 相關聯的 其中一個語句控制碼呼叫,並傳回SQL_PARAM_DATA_AVAILABLE。 在擷取所有資料流程參數的資料之前,會呼叫此函式。
HY013 記憶體管理錯誤 無法處理函式呼叫,因為基礎記憶體物件無法存取,可能是因為記憶體不足的情況。
HY016 無法修改實作資料列描述元 DescriptorHandle 引數與 IRD 相關聯,而且 FieldIdentifier 引數未SQL_DESC_ARRAY_STATUS_PTR或SQL_DESC_ROWS_PROCESSED_PTR。
HY021 不一致的描述元資訊 SQL_DESC_TYPE和SQL_DESC_DATETIME_INTERVAL_CODE欄位不會形成有效的 ODBC SQL 類型或有效的驅動程式特定 SQL 類型(適用于 IPD)或有效的 ODBC C 類型(適用于 APD 或 ARD)。

在一致性檢查期間檢查的描述元資訊不一致。 (請參閱 中的 「一致性檢查」SQLSetDescRec .)
HY090 不正確字串或緩衝區長度 (DM) *ValuePtr 是字元字串,BufferLength 小於零, 但不等於SQL_NTS。

(DM) 驅動程式是 ODBC 2*.x* 驅動程式,描述元是 ARD, ColumnNumber 引數設定為 0,而針對 BufferLength 指定的 值不等於 4。
HY091 不正確描述元欄位識別碼 FieldIdentifier 引數指定的 值不是 ODBC 定義的欄位,也不是實作定義的值。

DescriptorHandle 引數的 FieldIdentifier 引數無效。

FieldIdentifier 引數是唯讀的 ODBC 定義欄位。
HY092 不正確屬性/選項識別碼 *ValuePtr 中的 值對 FieldIdentifier 引數無效。

FieldIdentifier 引數已SQL_DESC_UNNAMED,且 ValuePtr 已SQL_NAMED。
HY105 不正確參數類型 (DM) 為SQL_DESC_PARAMETER_TYPE欄位指定的值無效。 (如需詳細資訊,請參閱 」 SQLBindParameter 中的 InputOutputType Argument「 區段。
HY117 連線因為未知的交易狀態而暫停。 只允許中斷連線和唯讀函式。 (DM) 如需暫停狀態的詳細資訊,請參閱 ODBC 3.8 的新功能。
HYT01 已超過連線逾時 在資料來源回應要求之前,連線逾時期限已過期。 連線逾時期間是透過 SQLSetConnectAttr 來設定,SQL_ATTR_CONNECTION_TIMEOUT。
IM001 驅動程式不支援此函式 (DM) 與 DescriptorHandle 相關聯的 驅動程式不支援 函式。

註解

應用程式可以呼叫 SQLSetDescField ,一次設定任何描述元欄位。 對 SQLSetDescField 的一次呼叫 會在單一描述元中設定單一欄位。 您可以呼叫此函式來設定任何描述元類型中的任何欄位,前提是可以設定欄位。 (請參閱本節稍後的表格。

注意

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

您可以呼叫其他函式,以使用函式的單一呼叫來設定多個描述元欄位。 SQLSetDescRec 函式會設定各種欄位,這些欄位會影響系結至資料行或參數的資料類型和緩衝區(SQL_DESC_TYPE、SQL_DESC_DATETIME_INTERVAL_CODE、SQL_DESC_OCTET_LENGTH、SQL_DESC_PRECISION、SQL_DESC_SCALE、SQL_DESC_DATA_PTR、SQL_DESC_OCTET_LENGTH_PTR和SQL_DESC_INDICATOR_PTR欄位)。 SQLBindCol SQLBindParameter 可用來製作資料行或參數系結的完整規格。 這些函式會設定具有一個函式呼叫的特定描述元欄位群組。

您可以呼叫 SQLSetDescField ,藉由將位移新增至系結指標來變更系結緩衝區(SQL_DESC_DATA_PTR、SQL_DESC_INDICATOR_PTR或SQL_DESC_OCTET_LENGTH_PTR)。 這會變更系結緩衝區,而不呼叫 SQLBindCol SQLBindParameter ,這可讓應用程式變更SQL_DESC_DATA_PTR而不變更其他欄位,例如SQL_DESC_DATA_TYPE。

如果應用程式呼叫 SQLSetDescField 來設定SQL_DESC_COUNT以外的任何欄位,或SQL_DESC_DATA_PTR、SQL_DESC_OCTET_LENGTH_PTR或SQL_DESC_INDICATOR_PTR的延遲欄位,記錄就會變成未系結。

描述項標頭欄位是藉由使用適當的 FieldIdentifier 呼叫 SQLSetDescField 來設定。 許多標頭欄位也是語句屬性,因此也可以透過呼叫 SQLSetStmtAttr 來設定它們。 這可讓應用程式設定描述元欄位,而不需要先取得描述項控制碼。 呼叫 SQLSetDescField 來設定標頭欄位時 會忽略 RecNumber 引數。

0 的 RecNumber 可用來設定書簽欄位。

注意

在呼叫 SQLSetDescField 以設定書簽欄位之前,應該一律設定語句屬性SQL_ATTR_USE_BOOKMARKS。 雖然這不是強制性的,但強烈建議這麼做。

設定描述項欄位的順序

藉由呼叫 SQLSetDescField 來設定描述元欄位時,應用程式必須遵循特定順序:

  1. 應用程式必須先設定 [SQL_DESC_TYPE]、[SQL_DESC_CONCISE_TYPE] 或 [SQL_DESC_DATETIME_INTERVAL_CODE] 欄位。

  2. 設定其中一個欄位之後,應用程式可以設定資料類型的屬性,而驅動程式會將資料類型屬性欄位設定為資料類型的適當預設值。 自動預設類型屬性欄位可確保一旦應用程式指定資料類型,描述項一律可供使用。 如果應用程式明確設定資料類型屬性,則會覆寫預設屬性。

  3. 設定步驟 1 中列出的其中一個欄位,並設定資料類型屬性之後,應用程式就可以設定SQL_DESC_DATA_PTR。 這會提示描述項欄位的一致性檢查。 如果應用程式在設定SQL_DESC_DATA_PTR欄位之後變更資料類型或屬性,驅動程式會將SQL_DESC_DATA_PTR設定為 null 指標,並將記錄解除系結。 這會強制應用程式在描述項記錄可供使用之前,依序完成適當的步驟。

描述項欄位的初始設定

配置描述元時,描述元中的欄位可以初始化為預設值、不使用預設值初始化,或未定義描述元類型的欄位。 下表指出每個描述項類型之欄位的初始化,「D」表示欄位是以預設值初始化,而 「ND」 表示欄位是未使用預設值初始化。 如果顯示數位,欄位的預設值就是該數位。 資料表也會指出欄位是可讀寫的 (R/W) 還是唯讀的 (R)。

IRD 的欄位只有在準備或執行語句且已填入 IRD 之後,才會有預設值,而不是配置語句控制碼或描述元時。 在填入 IRD 之前,任何取得 IRD 欄位存取權的嘗試都會傳回錯誤。

某些描述元欄位會針對一或多個描述元類型定義,但並非全部定義描述元類型(ARD 和 IRD,以及 APD 和 IPD)。 未定義描述元類型的欄位時,任何使用該描述元的函式都不需要此欄位。

SQLGetDescField 可以存取 的欄位不一定由 SQLSetDescField 設定。 下表列出 SQLSetDescField 可以設定 的欄位。

標頭欄位的初始化會在下列資料表中概述。

標頭功能變數名稱 類型 R/W 預設
SQL_DESC_ALLOC_TYPE SQLSMALLINT ARD: R APD: R IRD: R IPD: R ARD:隱含或明確SQL_DESC_ALLOC_USER的SQL_DESC_ALLOC_AUTO

APD:明確隱含或SQL_DESC_ALLOC_USER的SQL_DESC_ALLOC_AUTO

IRD:SQL_DESC_ALLOC_AUTO

IPD:SQL_DESC_ALLOC_AUTO
SQL_DESC_ARRAY_SIZE SQLULEN ARD:R/W APD:R/W IRD:未使用的 IPD:未使用 ARD:[1] APD:[1] IRD:未使用的 IPD:未使用
SQL_DESC_ARRAY_STATUS_PTR SQLUSMALLINT* ARD:R/W APD:R/W IRD:R/W IPD:R/W ARD: Null ptr APD: Null ptr IRD: Null ptr IPD: Null ptr
SQL_DESC_BIND_OFFSET_PTR SQLLEN* ARD:R/W APD:R/W IRD:未使用的 IPD:未使用 ARD: Null ptr APD: Null ptr IRD: 未使用的 IPD: 未使用
SQL_DESC_BIND_TYPE SQLINTEGER ARD:R/W APD:R/W IRD:未使用的 IPD:未使用 ARD: SQL_BIND_BY_COLUMN

APD:SQL_BIND_BY_COLUMN

IRD:未使用

IPD:未使用
SQL_DESC_COUNT SQLSMALLINT ARD:R/W APD:R/W IRD:R IPD:R/W ARD: 0 APD: 0 IRD: D IPD: 0
SQL_DESC_ROWS_PROCESSED_PTR SQLULEN* ARD:未使用的 APD:未使用的 IRD:R/W IPD:R/W ARD:未使用的 APD:未使用的 IRD:Null ptr IPD:Null ptr

[1] 只有在驅動程式自動填入 IPD 時,才會定義這些欄位。 如果沒有填入,則不會定義。 如果應用程式嘗試設定這些欄位,將會傳回 SQLSTATE HY091 (無效描述元欄位識別碼)。

記錄欄位的初始化如下表所示。

記錄功能變數名稱 類型 R/W 預設
SQL_DESC_AUTO_UNIQUE_VALUE SQLINTEGER ARD:未使用的 APD:未使用的 IRD:R IPD:未使用 ARD:未使用的 APD:未使用的 IRD:D IPD:未使用
SQL_DESC_BASE_COLUMN_NAME SQLCHAR * ARD:未使用的 APD:未使用的 IRD:R IPD:未使用 ARD:未使用的 APD:未使用的 IRD:D IPD:未使用
SQL_DESC_BASE_TABLE_NAME SQLCHAR * ARD:未使用的 APD:未使用的 IRD:R IPD:未使用 ARD:未使用的 APD:未使用的 IRD:D IPD:未使用
SQL_DESC_CASE_SENSITIVE SQLINTEGER ARD:未使用的 APD:未使用的 IRD:R IPD:R ARD:未使用的 APD:未使用的 IRD:D IPD:D[1]
SQL_DESC_CATALOG_NAME SQLCHAR * ARD:未使用的 APD:未使用的 IRD:R IPD:未使用 ARD:未使用的 APD:未使用的 IRD:D IPD:未使用
SQL_DESC_CONCISE_TYPE SQLSMALLINT ARD:R/W APD:R/W IRD:R IPD:R/W ARD: SQL_C_預設 APD: SQL_C_預設 IRD: D IPD: ND
SQL_DESC_DATA_PTR SQLPOINTER ARD:R/W APD:R/W IRD:未使用的 IPD:未使用 ARD: Null ptr APD: Null ptr IRD: 未使用的 IPD: 未使用[2]
SQL_DESC_DATETIME_INTERVAL_CODE SQLSMALLINT ARD:R/W APD:R/W IRD:R IPD:R/W ARD: ND APD: ND IRD: D IPD: ND
SQL_DESC_DATETIME_INTERVAL_PRECISION SQLINTEGER ARD:R/W APD:R/W IRD:R IPD:R/W ARD: ND APD: ND IRD: D IPD: ND
SQL_DESC_DISPLAY_SIZE SQLLEN ARD:未使用的 APD:未使用的 IRD:R IPD:未使用 ARD:未使用的 APD:未使用的 IRD:D IPD:未使用
SQL_DESC_FIXED_PREC_SCALE SQLSMALLINT ARD:未使用的 APD:未使用的 IRD:R IPD:R ARD:未使用的 APD:未使用的 IRD:D IPD:D[1]
SQL_DESC_INDICATOR_PTR SQLLEN * ARD:R/W APD:R/W IRD:未使用的 IPD:未使用 ARD: Null ptr APD: Null ptr IRD: 未使用的 IPD: 未使用
SQL_DESC_LABEL SQLCHAR * ARD:未使用的 APD:未使用的 IRD:R IPD:未使用 ARD:未使用的 APD:未使用的 IRD:D IPD:未使用
SQL_DESC_LENGTH SQLULEN ARD:R/W APD:R/W IRD:R IPD:R/W ARD: ND APD: ND IRD: D IPD: ND
SQL_DESC_LITERAL_PREFIX SQLCHAR * ARD:未使用的 APD:未使用的 IRD:R IPD:未使用 ARD:未使用的 APD:未使用的 IRD:D IPD:未使用
SQL_DESC_LITERAL_SUFFIX SQLCHAR * ARD:未使用的 APD:未使用的 IRD:R IPD:未使用 ARD:未使用的 APD:未使用的 IRD:D IPD:未使用
SQL_DESC_LOCAL_TYPE_NAME SQLCHAR * ARD:未使用的 APD:未使用的 IRD:R IPD:R ARD:未使用的 APD:未使用的 IRD:D IPD:D[1]
SQL_DESC_NAME SQLCHAR * ARD:未使用的 APD:未使用的 IRD:R IPD:R/W ARD: ND APD: ND IRD: D IPD: ND
SQL_DESC_NULLABLE SQLSMALLINT ARD:未使用的 APD:未使用的 IRD:R IPD:R ARD: ND APD: ND IRD: D IPD: ND
SQL_DESC_NUM_PREC_RADIX SQLINTEGER ARD:R/W APD:R/W IRD:R IPD:R/W ARD: ND APD: ND IRD: D IPD: ND
SQL_DESC_OCTET_LENGTH SQLLEN ARD:R/W APD:R/W IRD:R IPD:R/W ARD: ND APD: ND IRD: D IPD: ND
SQL_DESC_OCTET_LENGTH_PTR SQLLEN * ARD:R/W APD:R/W IRD:未使用的 IPD:未使用 ARD: Null ptr APD: Null ptr IRD: 未使用的 IPD: 未使用
SQL_DESC_PARAMETER_TYPE SQLSMALLINT ARD:未使用的 APD:未使用的 IRD:未使用的 IPD:R/W ARD:未使用的 APD:未使用的 IRD:未使用的 IPD:D=SQL_PARAM_INPUT
SQL_DESC_PRECISION SQLSMALLINT ARD:R/W APD:R/W IRD:R IPD:R/W ARD: ND APD: ND IRD: D IPD: ND
SQL_DESC_ROWVER SQLSMALLINT ARD:未使用

APD:未使用

IRD:R

IPD:R
ARD:未使用

APD:未使用

IRD:ND

IPD:ND
SQL_DESC_SCALE SQLSMALLINT ARD:R/W APD:R/W IRD:R IPD:R/W ARD: ND APD: ND IRD: D IPD: ND
SQL_DESC_SCHEMA_NAME SQLCHAR * ARD:未使用的 APD:未使用的 IRD:R IPD:未使用 ARD:未使用的 APD:未使用的 IRD:D IPD:未使用
SQL_DESC_SEARCHABLE SQLSMALLINT ARD:未使用的 APD:未使用的 IRD:R IPD:未使用 ARD:未使用的 APD:未使用的 IRD:D IPD:未使用
SQL_DESC_TABLE_NAME SQLCHAR * ARD:未使用的 APD:未使用的 IRD:R IPD:未使用 ARD:未使用的 APD:未使用的 IRD:D IPD:未使用
SQL_DESC_TYPE SQLSMALLINT ARD:R/W APD:R/W IRD:R IPD:R/W ARD: SQL_C_DEFAULT APD: SQL_C_DEFAULT IRD: D IPD: ND
SQL_DESC_TYPE_NAME SQLCHAR * ARD:未使用的 APD:未使用的 IRD:R IPD:R ARD:未使用的 APD:未使用的 IRD:D IPD:D[1]
SQL_DESC_UNNAMED SQLSMALLINT ARD:未使用的 APD:未使用的 IRD:R IPD:R/W ARD: ND APD: ND IRD: D IPD: ND
SQL_DESC_UNSIGNED SQLSMALLINT ARD:未使用的 APD:未使用的 IRD:R IPD:R ARD:未使用的 APD:未使用的 IRD:D IPD:D[1]
SQL_DESC_UPDATABLE SQLSMALLINT ARD:未使用的 APD:未使用的 IRD:R IPD:未使用 ARD:未使用的 APD:未使用的 IRD:D IPD:未使用

[1] 只有在驅動程式自動填入 IPD 時,才會定義這些欄位。 如果沒有填入,則不會定義。 如果應用程式嘗試設定這些欄位,將會傳回 SQLSTATE HY091 (無效描述元欄位識別碼)。

[2] IPD 中的SQL_DESC_DATA_PTR欄位可以設定為強制一致性檢查。 在後續對 SQLGetDescField SQLGetDescRec 的呼叫中,驅動程式不需要傳回已設定SQL_DESC_DATA_PTR的值。

FieldIdentifier 引數

FieldIdentifier 引數會指出要設定的描述元欄位。 描述項包含 描述項標頭, 包含下一節「標頭欄位」和零或多個 描述元記錄中所述的標題欄位, 其中包含「標頭欄位」一節下一節所述的記錄欄位。

標頭欄位

每個描述項都有一個標頭,其中包含下欄欄位:

SQL_DESC_ALLOC_TYPE [全部]
這個唯讀的 SQLSMALLINT 標頭欄位會指定描述元是由驅動程式自動設定,還是由應用程式明確配置。 應用程式可以取得但無法修改此欄位。 如果驅動程式自動設定描述元,欄位會設定為驅動程式SQL_DESC_ALLOC_AUTO。 如果應用程式明確配置描述項,則驅動程式會將它設定為SQL_DESC_ALLOC_USER。

SQL_DESC_ARRAY_SIZE [應用程式描述項]
在 ARD 中,這個 SQLULEN 標頭欄位會指定資料列集中的資料列數目。 這是呼叫 SQLFetch SQLFetchScroll 所要傳回的資料列數目,或是由呼叫 SQLBulkOperations SQLSetPos 來操作的資料列數目。

在 APD 中,這個 SQLULEN 標頭欄位會指定每個參數的值數目。

此欄位的預設值為 1。 如果SQL_DESC_ARRAY_SIZE大於 1、SQL_DESC_DATA_PTR、SQL_DESC_INDICATOR_PTR,以及 APD 或 ARD 的SQL_DESC_OCTET_LENGTH_PTR指向陣列。 每個陣列的基數等於此欄位的值。

您也可以使用 SQL_ATTR_ROW_ARRAY_SIZE 屬性呼叫 SQLSetStmtAttr ,以設定 ARD 中的此欄位。 您也可以使用 SQL_ATTR_PARAMSET_SIZE 屬性呼叫 SQLSetStmtAttr ,以設定 APD 中的此欄位。

SQL_DESC_ARRAY_STATUS_PTR [全部]
對於每個描述元類型,這個 SQLUSMALLINT * 標頭欄位會指向 SQLUSMALLINT 值的陣列。 這些陣列的名稱如下:資料列狀態陣列 (IRD)、參數狀態陣列 (IPD)、資料列作業陣列 (ARD),以及參數運算陣列 (APD)。

在 IRD 中,此標頭欄位會指向在呼叫 SQLBulkOperations 、SQLFetch、 SQLFetchScroll SQLSetPos 之後,包含狀態值的資料列狀態陣列。 陣列具有與資料列集中的資料列數目一樣多的專案。 應用程式必須配置 SQLUSMALLINT 的陣列,並將此欄位設定為指向陣列。 欄位預設會設定為 Null 指標。 驅動程式會填入陣列 - 除非SQL_DESC_ARRAY_STATUS_PTR欄位設定為 null 指標,在此情況下不會產生狀態值,而且陣列未填入。

警告

如果應用程式設定 IRD SQL_DESC_ARRAY_STATUS_PTR 欄位所指向的資料列狀態陣列元素,則驅動程式行為是未定義的。

陣列一開始會由對 SQLBulkOperations 、SQLFetch、 SQLFetchScroll SQLSetPos 的呼叫 填入。 如果呼叫未傳回SQL_SUCCESS或SQL_SUCCESS_WITH_INFO,則此欄位指向的陣列內容未定義。 陣列中的元素可以包含下列值:

  • SQL_ROW_SUCCESS:資料列已成功擷取,且自上次擷取之後尚未變更。

  • SQL_ROW_SUCCESS_WITH_INFO:資料列已成功擷取,且自上次擷取之後尚未變更。 不過,系統有傳回關於該資料列的警告。

  • SQL_ROW_ERROR:擷取資料列時發生錯誤。

  • SQL_ROW_UPDATED:資料列已成功擷取,且自上次擷取之後已更新。 如果再次擷取資料列,其狀態會SQL_ROW_SUCCESS。

  • SQL_ROW_DELETED:資料列自上次擷取後已刪除。

  • SQL_ROW_ADDED:資料列是由 SQLBulkOperations 插入。 如果再次擷取資料列,其狀態會SQL_ROW_SUCCESS。

  • SQL_ROW_NOROW:資料列集重迭結果集的結尾,而且沒有傳回任何對應至資料列狀態陣列這個專案的資料列。

您也可以使用 SQL_ATTR_ROW_STATUS_PTR 屬性呼叫 SQLSetStmtAttr 來設定 IRD 中的此欄位。

只有在傳回SQL_SUCCESS或SQL_SUCCESS_WITH_INFO之後,IRD 的SQL_DESC_ARRAY_STATUS_PTR欄位才有效。 如果傳回碼不是其中之一,則未定義SQL_DESC_ROWS_PROCESSED_PTR所指向的位置。

在 IPD 中,此標頭欄位會指向參數狀態陣列,其中包含呼叫 SQLExecute SQLExecDirect 之後每個參數值集的狀態資訊。 如果對 SQLExecute SQLExecDirect 的呼叫 未傳回SQL_SUCCESS或SQL_SUCCESS_WITH_INFO,則此欄位指向的陣列內容未定義。 應用程式必須配置 SQLUSMALLINT 的陣列,並將此欄位設定為指向陣列。 驅動程式會填入陣列 - 除非SQL_DESC_ARRAY_STATUS_PTR欄位設定為 null 指標,在此情況下不會產生狀態值,而且陣列未填入。 陣列中的元素可以包含下列值:

  • SQL_PARAM_SUCCESS:已成功針對這組參數執行 SQL 語句。

  • SQL_PARAM_SUCCESS_WITH_INFO:已成功針對這組參數執行 SQL 語句;不過,診斷資料結構中提供警告資訊。

  • SQL_PARAM_ERROR:處理這組參數時發生錯誤。 診斷資料結構中提供其他錯誤資訊。

  • SQL_PARAM_UNUSED:此參數集未使用,可能是因為某些先前的參數集造成錯誤而中止進一步處理,或因為已針對 APD SQL_DESC_ARRAY_STATUS_PTR 欄位所指定的陣列中的參數集設定SQL_PARAM_IGNORE。

  • SQL_PARAM_DIAG_UNAVAILABLE:無法使用診斷資訊。 例如,當驅動程式將參數陣列視為整合型單位時,因此不會產生這個錯誤資訊層級。

IPD 中的這個欄位也可以藉由使用 SQL_ATTR_PARAM_STATUS_PTR 屬性呼叫 SQLSetStmtAttr 來設定。

在 ARD 中,此標頭欄位會指向應用程式可以設定的值資料列作業陣列,以指出 SQLSetPos 作業是否要忽略 此資料列。 陣列中的元素可以包含下列值:

  • SQL_ROW_PROCEED:資料列會包含在使用 SQLSetPos 的大量作業中。 (此設定不保證作業會發生在資料列上。如果資料列的狀態SQL_ROW_ERROR IRD 資料列狀態陣列中,驅動程式可能無法在資料列中執行作業。

  • SQL_ROW_IGNORE:資料列會從使用 SQLSetPos 的大量作業中排除。

如果未設定陣列的專案,則所有資料列都會包含在大量作業中。 如果 ARD SQL_DESC_ARRAY_STATUS_PTR 欄位中的值是 Null 指標,則所有資料列都會包含在大量作業中;解譯與指向有效陣列的指標和陣列的所有元素都SQL_ROW_PROCEED相同。 如果陣列中的元素設定為SQL_ROW_IGNORE,則忽略資料列之資料列狀態陣列中的值不會變更。

ARD 中的這個欄位也可以藉由使用 SQL_ATTR_ROW_OPERATION_PTR 屬性呼叫 SQLSetStmtAttr 來設定。

在 APD 中,此標頭欄位會指向應用程式可以設定的值參數作業陣列,以指出呼叫 SQLExecute SQLExecDirect ,是否要忽略這個參數集。 陣列中的元素可以包含下列值:

  • SQL_PARAM_PROCEED:SQLExecute SQLExecDirect 呼叫中包含 一組參數。

  • SQL_PARAM_IGNORE:參數集會從 SQLExecute SQLExecDirect 呼叫中排除。

如果未設定陣列的專案,陣列中的所有參數集合都會用於 SQLExecute SQLExecDirect 呼叫中。 如果 APD SQL_DESC_ARRAY_STATUS_PTR 欄位中的值是 Null 指標,則會使用所有參數集;解譯與指向有效陣列的指標和陣列的所有元素都SQL_PARAM_PROCEED相同。

您也可以使用 SQL_ATTR_PARAM_OPERATION_PTR 屬性呼叫 SQLSetStmtAttr ,以設定 APD 中的這個欄位。

SQL_DESC_BIND_OFFSET_PTR [應用程式描述項]
此 SQLLEN * 標頭欄位會指向系結位移。 預設會將它設定為 Null 指標。 如果此欄位不是 Null 指標,驅動程式會在擷取時取值指標,並將取值加入至在描述元記錄中具有非 Null 值的每個延遲欄位(SQL_DESC_DATA_PTR、SQL_DESC_INDICATOR_PTR和SQL_DESC_OCTET_LENGTH_PTR),並在系結時使用新的指標值。

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

此欄位是 延後欄位 :它不會在設定時使用,但稍後由驅動程式在需要判斷資料緩衝區位址時使用。

ARD 中的這個欄位也可以藉由使用 SQL_ATTR_ROW_BIND_OFFSET_PTR 屬性呼叫 SQLSetStmtAttr 來設定。 ARD 中的這個欄位也可以藉由使用 SQL_ATTR_PARAM_BIND_OFFSET_PTR 屬性呼叫 SQLSetStmtAttr 來設定。

如需詳細資訊,請參閱 SQLFetchScroll SQLBindParameter 中的資料 列系結描述。

SQL_DESC_BIND_TYPE [應用程式描述項]
這個 SQLUINTEGER 標頭欄位會設定系結方向,以用於系結資料行或參數。

在 ARD 中,當相關聯語句控制碼上呼叫 SQLFetchScroll SQLFetch ,此欄位會指定系結方向。

若要選取資料行的資料行明智系結,此欄位會設定為 SQL_BIND_BY_COLUMN (預設值)。

您也可以使用 SQL_ATTR_ROW_BIND_TYPE Attribute 呼叫 SQLSetStmtAttr 來設定 ARD 中的這個欄位。

在 APD 中,此欄位會指定要用於動態參數的系結方向。

若要選取參數的資料行系結,此欄位會設定為 SQL_BIND_BY_COLUMN (預設值)。

您也可以使用 SQL_ATTR_PARAM_BIND_TYPE Attribute 呼叫 SQLSetStmtAttr ,以設定 APD 中的此欄位。

SQL_DESC_COUNT [全部]
這個 SQLSMALLINT 標頭欄位會指定包含資料之最高編號記錄的 1 起始索引。 當驅動程式設定描述項的資料結構時,它也必須設定 [SQL_DESC_COUNT] 欄位,以顯示有多少筆記錄很重要。 當應用程式佈建此資料結構的實例時,不需要指定要保留空間的記錄數目。 當應用程式指定記錄的內容時,驅動程式會採取任何必要的動作,以確保描述元控制碼參考適當大小的資料結構。

SQL_DESC_COUNT不是系結的所有資料行計數(如果欄位位於 ARD 中),或系結的所有參數計數(如果欄位位於 APD 中),而是最高編號記錄的數目。 如果最高編號的資料行或參數未系結,則SQL_DESC_COUNT會變更為下一個最高編號的資料行或參數數目。 如果具有小於最高編號資料行數目的資料行或參數未系結(藉由呼叫 TARGETValuePtr 引數設定為 Null 指標的 SQLBindCol ,或是 將 ParameterValuePtr 引數設為 null 指標的 SQLBindParameter ),則不會變更SQL_DESC_COUNT。 如果其他資料行或參數系結的數位大於包含資料的最高編號記錄,驅動程式會自動增加SQL_DESC_COUNT欄位中的值。 如果呼叫具有 [SQL_UNBIND] 選項的 SQLFreeStmt ,則 ARD 和 IRD 中的SQL_DESC_COUNT欄位會設定為 0,以取消 系結所有資料行。 如果使用 [SQL_RESET_PARAMS] 選項呼叫 SQLFreeStmt ,則 APD 和 IPD 中的SQL_DESC_COUNT欄位會設定為 0。

SQL_DESC_COUNT中的值可以透過呼叫 SQLSetDescField ,由應用程式明確設定。 如果明確減少SQL_DESC_COUNT中的值,則會有效移除所有數位大於新值SQL_DESC_COUNT的記錄。 如果SQL_DESC_COUNT中的值明確設定為 0,且欄位位於 ARD 中,則會釋放系結書簽資料行以外的所有資料緩衝區。

ARD 此欄位中的記錄計數不包含系結書簽資料行。 解除系結書簽資料行的唯一方法是將SQL_DESC_DATA_PTR欄位設定為 null 指標。

SQL_DESC_ROWS_PROCESSED_PTR [實作描述項]
在 IRD 中,這個 SQLULEN * 標頭欄位指向緩衝區,其中包含呼叫 SQLFetch 或 SQLFetchScroll 之後所擷取的資料列數目,或呼叫 SQLBulkOperations SQLSetPos 所執行之大量作業中受影響的資料列數目,包括錯誤資料列。

在 IPD 中,這個 SQLUINTEGER * 標頭欄位會指向緩衝區,其中包含已處理的參數集數目,包括錯誤集。 如果這是 Null 指標,則不會傳回任何數位。

只有在呼叫 SQLFetch 或 SQLFetchScroll 或 SQLFetchScroll 或 SQLExecute、SQLExecute SQLExecDirect SQLParamData (適用于 IPD 欄位) 之後 ,SQL_SUCCESS SQL_SUCCESS_WITH_INFO SQL_DESC_ROWS_PROCESSED_PTR才有效。 如果填入此欄位所指向之緩衝區的呼叫不會傳回SQL_SUCCESS或SQL_SUCCESS_WITH_INFO,則緩衝區的內容不會定義,除非它傳回SQL_NO_DATA,在此情況下,緩衝區中的值會設定為 0。

ARD 中的這個欄位也可以藉由使用 SQL_ATTR_ROWS_FETCHED_PTR 屬性呼叫 SQLSetStmtAttr 來設定。 您也可以使用 SQL_ATTR_PARAMS_PROCESSED_PTR 屬性呼叫 SQLSetStmtAttr ,以設定 APD 中的這個欄位。

應用程式會配置此欄位所指向的緩衝區。 這是驅動程式所設定的延遲輸出緩衝區。 預設會將它設定為 Null 指標。

記錄欄位

每個描述項都包含一或多個記錄,其中包含定義資料行資料或動態參數的欄位,視描述項的類型而定。 每個記錄都是單一資料行或參數的完整定義。

SQL_DESC_AUTO_UNIQUE_VALUE [IRD]
如果資料行是自動遞增資料行,則這個唯讀 SQLINTEGER 記錄欄位包含SQL_TRUE,如果資料行不是自動遞增資料行,則SQL_FALSE。 此欄位是唯讀的,但基礎自動遞增資料行不一定是唯讀的。

SQL_DESC_BASE_COLUMN_NAME [IRD]
這個唯讀 SQLCHAR * 記錄欄位包含結果集資料行的基底資料行名稱。 如果基底資料行名稱不存在(就運算式的資料行而言),此變數會包含空字串。

SQL_DESC_BASE_TABLE_NAME [IRD]
這個唯讀的 SQLCHAR * 記錄欄位包含結果集資料行的基表名稱。 如果無法定義或不適用基表名稱,此變數會包含空字串。

SQL_DESC_CASE_SENSITIVE [實作描述項]
如果資料行或參數被視為區分大小寫的定序和比較,則此唯讀 SQLINTEGER 記錄欄位包含SQL_TRUE;如果資料行未被視為區分大小寫的定序和比較,或資料行為非字元資料行,則為SQL_FALSE。

SQL_DESC_CATALOG_NAME [IRD]
這個唯讀 SQLCHAR * 記錄欄位包含包含資料行之基表的目錄。 如果資料行是運算式,或者如果資料行是檢視的一部分,則傳回值是驅動程式相依的。 如果資料來源不支援目錄或無法判斷目錄,此變數會包含空字串。

SQL_DESC_CONCISE_TYPE [全部]
這個 SQLSMALLINT 標頭欄位會指定所有資料類型的精簡資料類型,包括 datetime 和 interval 資料類型。

SQL_DESC_CONCISE_TYPE、SQL_DESC_TYPE和SQL_DESC_DATETIME_INTERVAL_CODE欄位中的值是相互相依的。 每次設定其中一個欄位時,也必須設定另一個欄位。 SQL_DESC_CONCISE_TYPE可以透過呼叫 SQLBindCol SQLBindParameter SQLSetDescField 來設定。 SQL_DESC_TYPE可以透過呼叫 SQLSetDescField SQLSetDescRec 來設定。

如果SQL_DESC_CONCISE_TYPE設定為間隔或日期時間資料類型以外的精簡資料類型,SQL_DESC_TYPE欄位會設定為相同的值,且SQL_DESC_DATETIME_INTERVAL_CODE欄位設定為 0。

如果SQL_DESC_CONCISE_TYPE設定為精簡的日期時間或間隔資料類型,則SQL_DESC_TYPE欄位會設定為對應的詳細資訊類型(SQL_DATETIME或SQL_INTERVAL),且SQL_DESC_DATETIME_INTERVAL_CODE欄位會設定為適當的副程式代碼。

SQL_DESC_DATA_PTR [應用程式描述元和 IPD]
此 SQLPOINTER 記錄欄位指向將包含參數值 (適用于 APD) 或資料行值 (適用于 ARD) 的變數。 此欄位是 延後欄位 。 它不會在設定時使用,但稍後由驅動程式用來擷取資料。

如果 呼叫 SQLBindCol 的 TargetValuePtr 引數是 null 指標,或是 ARD 中的SQL_DESC_DATA_PTR欄位是由呼叫 SQLSetDescField SQLSetDescRec 設定 為 null 指標,則 ARD 的 SQL_DESC_DATA_PTR 欄位所指定的資料行是未系結的。 如果SQL_DESC_DATA_PTR欄位設定為 null 指標,則其他欄位不會受到影響。

如果呼叫 填入此欄位所指向之緩衝區的 SQLFetch SQLFetchScroll 未傳回SQL_SUCCESS或SQL_SUCCESS_WITH_INFO,則未定義緩衝區的內容。

每當設定 APD、ARD 或 IPD 的SQL_DESC_DATA_PTR欄位時,驅動程式就會檢查 [SQL_DESC_TYPE] 欄位中的值是否包含其中一個有效的 ODBC C 資料類型或驅動程式特定的資料類型,以及影響資料類型的所有其他欄位都一致。 提示一致性檢查是唯一使用 IPD SQL_DESC_DATA_PTR 欄位。 具體而言,如果應用程式設定 IPD 的 SQL_DESC_DATA_PTR 欄位,且稍後在此欄位上呼叫 SQLGetDescField ,則不一定傳回它已設定的值。 如需詳細資訊,請參閱 SQLSetDescRec 中的

SQL_DESC_DATETIME_INTERVAL_CODE [全部]
當SQL_DESC_TYPE欄位是SQL_DATETIME或SQL_INTERVAL時,這個 SQLSMALLINT 記錄欄位包含特定日期時間或間隔資料類型的子碼。 這適用于 SQL 和 C 資料類型。 程式碼是由資料類型名稱所組成,以 「TYPE」 或 「C_TYPE」 取代 「TYPE」 或 「C_TYPE」 或 「CODE」 取代 「INTERVAL」 或 「C_INTERVAL」 (適用于間隔類型)。

如果應用程式描述元中的SQL_DESC_TYPE和SQL_DESC_CONCISE_TYPE設定為 SQL_C_DEFAULT,且描述項未與語句控制碼相關聯,則未定義SQL_DESC_DATETIME_INTERVAL_CODE的內容。

下表所列的 datetime 資料類型可以設定此欄位。

Datetime 類型 DATETIME_INTERVAL_CODE
SQL_TYPE_DATE/SQL_C_TYPE_DATE SQL_CODE_DATE
SQL_TYPE_TIME/SQL_C_TYPE_TIME SQL_CODE_TIME
SQL_TYPE_TIMESTAMP/ SQL_C_TYPE_TIMESTAMP SQL_CODE_TIMESTAMP

下表所列的間隔資料類型可以設定此欄位。

間隔類型 DATETIME_INTERVAL_CODE
SQL_INTERVAL_DAY/ SQL_C_INTERVAL_DAY SQL_CODE_DAY
SQL_INTERVAL_DAY_TO_HOUR/ SQL_C_INTERVAL_DAY_TO_HOUR SQL_CODE_DAY_TO_HOUR
SQL_INTERVAL_DAY_TO_MINUTE/ SQL_C_INTERVAL_DAY_TO_MINUTE SQL_CODE_DAY_TO_MINUTE
SQL_INTERVAL_DAY_TO_SECOND/ SQL_C_INTERVAL_DAY_TO_SECOND SQL_CODE_DAY_TO_SECOND
SQL_INTERVAL_HOUR/SQL_C_INTERVAL_HOUR SQL_CODE_HOUR
SQL_INTERVAL_HOUR_TO_MINUTE/ SQL_C_INTERVAL_HOUR_TO_MINUTE SQL_CODE_HOUR_TO_MINUTE
SQL_INTERVAL_HOUR_TO_SECOND/ SQL_C_INTERVAL_HOUR_TO_SECOND SQL_CODE_HOUR_TO_SECOND
SQL_INTERVAL_MINUTE/ SQL_C_INTERVAL_MINUTE SQL_CODE_MINUTE
SQL_INTERVAL_MINUTE_TO_SECOND/ SQL_C_INTERVAL_MINUTE_TO_SECOND SQL_CODE_MINUTE_TO_SECOND
SQL_INTERVAL_MONTH/ SQL_C_INTERVAL_MONTH SQL_CODE_MONTH
SQL_INTERVAL_SECOND/ SQL_C_INTERVAL_SECOND SQL_CODE_SECOND
SQL_INTERVAL_YEAR/ SQL_C_INTERVAL_YEAR SQL_CODE_YEAR
SQL_INTERVAL_YEAR_TO_MONTH/ SQL_C_INTERVAL_YEAR_TO_MONTH SQL_CODE_YEAR_TO_MONTH

如需資料間隔和此欄位的詳細資訊,請參閱 資料類型識別碼和描述元

SQL_DESC_DATETIME_INTERVAL_PRECISION [全部]
如果SQL_DESC_TYPE欄位是SQL_INTERVAL,這個 SQLINTEGER 記錄欄位會包含間隔前置精確度。 當 [SQL_DESC_DATETIME_INTERVAL_CODE] 欄位設定為間隔資料類型時,此欄位會設定為預設間隔前置精確度。

SQL_DESC_DISPLAY_SIZE [IRD]
這個唯讀的 SQLINTEGER 記錄欄位包含顯示資料行資料所需的字元數上限。

SQL_DESC_FIXED_PREC_SCALE [實作描述項]
如果資料行是精確的數值資料行且具有固定有效位數和非零小數位數,則這個唯讀 SQLSMALLINT 記錄欄位會設定為SQL_TRUE,如果資料行不是固定有效位數和小數位數的精確數值資料行,則為SQL_FALSE。

SQL_DESC_INDICATOR_PTR [應用程式描述項]
在 ARD 中,這個 SQLLEN * 記錄欄位會指向指標變數。 如果資料行值為 Null,則此變數包含SQL_Null_DATA。 針對 APD,指標變數會設定為 SQL_Null_DATA,以指定 Null 動態引數。 否則,變數為零(除非SQL_DESC_INDICATOR_PTR和SQL_DESC_OCTET_LENGTH_PTR中的值是相同的指標)。

如果 ARD 中的SQL_DESC_INDICATOR_PTR欄位是 Null 指標,則無法傳回資料行是否為 Null 的相關資訊。 如果資料行為 Null,且SQL_DESC_INDICATOR_PTR為 Null 指標,當驅動程式在呼叫 SQLFetch SQLFetchScroll 之後嘗試填入緩衝區時,會傳回 SQLSTATE 22002 (需要指標變數但未提供)。 如果對 SQLFetch SQLFetchScroll 的呼叫 未傳回SQL_SUCCESS或SQL_SUCCESS_WITH_INFO,則未定義緩衝區的內容。

SQL_DESC_INDICATOR_PTR欄位會決定是否已設定SQL_DESC_OCTET_LENGTH_PTR所指向的欄位。 如果資料行的資料值為 Null,驅動程式會將指標變數設定為 SQL_Null_DATA。 然後不會設定SQL_DESC_OCTET_LENGTH_PTR所指向的欄位。 如果在擷取期間未遇到 Null 值,則由 SQL_DESC_INDICATOR_PTR 指向的緩衝區會設定為零,而 SQL_DESC_OCTET_LENGTH_PTR 所指向的緩衝區會設定為數據長度。

如果 APD 中的SQL_DESC_INDICATOR_PTR欄位是 Null 指標,應用程式就無法使用此描述元記錄來指定 Null 引數。

此欄位是 延後欄位 :它不會在設定時使用,但稍後由驅動程式用來指出可為 Null 性(適用于 ARD)或判斷可為 Null 性(適用于 APD)。

SQL_DESC_LABEL [IRD]
這個唯讀 SQLCHAR * 記錄欄位包含資料行標籤或標題。 如果資料行沒有標籤,此變數會包含資料行名稱。 如果資料行未命名且未標記,則此變數會包含空字串。

SQL_DESC_LENGTH [全部]
此 SQLULEN 記錄欄位是字元字串的最大或實際長度,或是以位元組為單位的二進位資料類型。 它是固定長度資料類型的最大長度,或可變長度資料類型的實際長度。 其值一律會排除結束字元字串的 Null 終止字元。 對於類型為SQL_TYPE_DATE、SQL_TYPE_TIME、SQL_TYPE_TIMESTAMP或其中一個 SQL 間隔資料類型的值,此欄位具有 datetime 或 interval 值字元字串表示的字元長度。

此欄位中的值可能與 ODBC 2*.x* 中所定義的 「length」 值不同。 如需詳細資訊,請參閱 附錄 D:資料類型

SQL_DESC_LITERAL_PREFIX [IRD]
這個唯讀 SQLCHAR * 記錄欄位包含驅動程式辨識為這個資料類型常值前置詞的字元或字元。 此變數包含的資料類型空字串,其常值前置詞不適用。

SQL_DESC_LITERAL_SUFFIX [IRD]
這個唯讀 SQLCHAR * 記錄欄位包含驅動程式辨識為此資料類型常值尾碼的字元或字元。 此變數包含的資料類型空字串,其常值尾碼不適用。

SQL_DESC_LOCAL_TYPE_NAME [實作描述項]
這個唯讀 SQLCHAR * 記錄欄位包含任何可能不同于資料類型之一般名稱的當地語系化(原生語言)名稱。 如果沒有當地語系化的名稱,則會傳回空字串。 此欄位僅供顯示之用。

SQL_DESC_NAME [實作描述項]
如果套用,則資料列描述元中的這個 SQLCHAR * 記錄欄位包含資料行別名。 如果資料行別名不適用,則會傳回資料行名稱。 在任一情況下,驅動程式會在設定SQL_DESC_NAME欄位時,將SQL_DESC_UNNAMED欄位設定為SQL_NAMED。 如果沒有資料行名稱或資料行別名,驅動程式會在 [SQL_DESC_NAME] 欄位中傳回空字串,並將SQL_DESC_UNNAMED欄位設定為 SQL_UNNAMED。

應用程式可以將 IPD 的 SQL_DESC_NAME 欄位設定為參數名稱或別名,以依名稱指定預存程式參數。 (如需詳細資訊,請參閱 依名稱系結參數 (具名參數) . IRD 的SQL_DESC_NAME欄位是唯讀欄位;如果應用程式嘗試設定 SQLSTATE HY091 ,將會傳回不正確描述元欄位識別碼。

在 IPD 中,如果驅動程式不支援具名參數,此欄位就不會定義。 如果驅動程式支援具名參數且能夠描述參數,則會在此欄位中傳回參數名稱。

SQL_DESC_NullABLE [實作描述項]
在 IRD 中,如果資料行可以有 Null 值,就會SQL_NullABLE這個唯讀 SQLSMALLINT 記錄欄位,如果資料行沒有 Null 值,則SQL_NO_NullS,如果不知道資料行是否接受 Null 值,則SQL_NullABLE_UNKNOWN。 此欄位與結果集資料行有關,而不是基底資料行。

在 IPD 中,此欄位一律設定為 SQL_NullABLE,因為動態參數一律可為 Null,而且無法由應用程式設定。

SQL_DESC_NUM_PREC_RADIX [全部]
如果 [SQL_DESC_TYPE] 欄位中的資料類型是近似數值資料類型,則此 SQLINTEGER 欄位包含 2 的值,因為SQL_DESC_PRECISION欄位包含位數。 如果SQL_DESC_TYPE欄位中的資料類型是精確的數值資料類型,則此欄位包含 10 的值,因為SQL_DESC_PRECISION欄位包含小數位數。 此欄位會針對所有非數值資料類型設定為 0。

SQL_DESC_OCTET_LENGTH [全部]
此 SQLLEN 記錄欄位包含字元字串或二進位資料類型的長度,以位元組為單位。 對於固定長度字元或二進位類型,這是以位元組為單位的實際長度。 對於可變長度字元或二進位類型,這是位元組的最大長度。 這個值一律會針對實作描述元排除 Null 終止字元的空間,並且一律包含應用程式描述元之 Null 終止字元的空間。 針對應用程式資料,此欄位包含緩衝區的大小。 針對 APD,此欄位只會針對輸出或輸入/輸出參數定義。

SQL_DESC_OCTET_LENGTH_PTR [應用程式描述項]
這個 SQLLEN * 記錄欄位會指向變數,該變數將包含動態引數的總長度(針對參數描述元)或系結資料行值(針對資料列描述元)。

針對 APD,除了字元字串和二進位之外,所有引數都會忽略此值;如果此欄位指向 SQL_NTS,則動態引數必須以 Null 結束。 若要指出系結參數將會是資料執行參數,應用程式會將 APD 適當記錄中的這個欄位設定為變數,在執行時間會包含值SQL_DATA_AT_EXEC或SQL_LEN_DATA_AT_EXEC宏的結果。 如果有多個這類欄位,SQL_DESC_DATA_PTR可以設定為可唯一識別參數的值,以協助應用程式判斷所要求的參數。

如果 ARD 的OCTET_LENGTH_PTR欄位是 Null 指標,則驅動程式不會傳回資料行的長度資訊。 如果 APD 的SQL_DESC_OCTET_LENGTH_PTR欄位是 Null 指標,驅動程式會假設字元字串和二進位值會以 Null 終止。 (二進位值不應以 Null 結束,但應指定長度以避免截斷。

如果呼叫 填入此欄位所指向之緩衝區的 SQLFetch SQLFetchScroll 未傳回SQL_SUCCESS或SQL_SUCCESS_WITH_INFO,則未定義緩衝區的內容。 此欄位是 延後欄位 。 它不會在設定時使用,但稍後由驅動程式用來判斷或指出資料的八位長度。

SQL_DESC_PARAMETER_TYPE [IPD]
這個 SQLSMALLINT 記錄欄位會設定為輸入參數的SQL_PARAM_INPUT、輸入/輸出參數的SQL_PARAM_INPUT_OUTPUT、輸出參數的SQL_PARAM_OUTPUT、輸入/輸出資料流程參數的SQL_PARAM_INPUT_OUTPUT_STREAM,或輸出資料流程參數的SQL_PARAM_OUTPUT_STREAM。 預設會將它設定為 SQL_PARAM_INPUT。

針對 IPD,如果驅動程式未自動填入 IPD,欄位預設會設定為SQL_PARAM_INPUT (SQL_ATTR_ENABLE_AUTO_IPD 語句屬性是SQL_FALSE)。 應用程式應該針對不是輸入參數的參數,在 IPD 中設定此欄位。

SQL_DESC_PRECISION [全部]
這個 SQLSMALLINT 記錄欄位包含精確數數值型別的位數、近似數數值型別的 mantissa (二進位有效位數) 中的位數,或SQL_TYPE_TIME、SQL_TYPE_TIMESTAMP或SQL_INTERVAL_SECOND資料類型的小數秒陣列件中的位數。 此欄位未針對所有其他資料類型定義。

此欄位中的值可能與 ODBC 2*.x* 中所定義的「precision」 值不同。 如需詳細資訊,請參閱 附錄 D:資料類型

SQL_DESC_ROWVER [實作描述項]
這個 SQLSMALLINTrecord 欄位指出當資料列更新時,DBMS 是否自動修改資料行(例如 SQL Server 中類型為 「timestamp」 的資料行)。 如果資料行是資料列版本設定資料行,則此記錄欄位的值會設定為 SQL_TRUE,否則為 SQL_FALSE。 這個資料行屬性類似于呼叫 SQLSpecialColumns 且識別碼為 SQL_ROWVER,以判斷資料行是否自動更新。

SQL_DESC_SCALE [全部]
這個 SQLSMALLINT 記錄欄位包含十進位和數值資料類型的已定義小數位數。 欄位是針對所有其他資料類型未定義的。

此欄位中的值可能與 ODBC 2*.x* 中所定義的「scale」 值不同。 如需詳細資訊,請參閱 附錄 D:資料類型

SQL_DESC_SCHEMA_NAME [IRD]
這個唯讀 SQLCHAR * 記錄欄位包含包含資料行之基表的架構名稱。 如果資料行是運算式,或者如果資料行是檢視的一部分,則傳回值是驅動程式相依的。 如果資料來源不支援架構,或無法判斷架構名稱,此變數會包含空字串。

SQL_DESC_SEARCHABLE [IRD]
這個唯讀 SQLSMALLINT 記錄欄位會設定為下列其中一個值:

  • 如果資料行不能用於 WHERE 子句, SQL_PRED_NONE。 (這與 ODBC 2*.x*中的SQL_UNSEARCHABLE值相同)

  • SQL_PRED_CHAR如果資料行可用於 WHERE 子句, 但只能搭配 LIKE 述詞使用。 (這與 ODBC 2*.x*中的SQL_LIKE_ONLY值相同)

  • SQL_PRED_BASIC如果資料行可用於 WHERE 子句中 ,除了 LIKE 以外的 所有比較運算子。 (這與 ODBC 2*.x*中的SQL_EXCEPT_LIKE值相同)

  • SQL_PRED_SEARCHABLE如果資料行可用於 WHERE 子句中 ,則為任何比較運算子。

SQL_DESC_TABLE_NAME [IRD]
這個唯讀 SQLCHAR * 記錄欄位包含包含此資料行的基表名稱。 如果資料行是運算式,或者如果資料行是檢視的一部分,則傳回值是驅動程式相依的。

SQL_DESC_TYPE [全部]
這個 SQLSMALLINT 記錄欄位會針對日期時間和間隔資料類型以外的所有資料類型指定精簡的 SQL 或 C 資料類型。 對於 datetime 和 interval 資料類型,此欄位會指定詳細資訊資料類型,這是SQL_DATETIME或SQL_INTERVAL。

每當此欄位包含SQL_DATETIME或SQL_INTERVAL時,SQL_DESC_DATETIME_INTERVAL_CODE欄位必須包含適合精簡類型的副程式代碼。 對於 datetime 資料類型,SQL_DESC_TYPE包含SQL_DATETIME,而 SQL_DESC_DATETIME_INTERVAL_CODE 欄位則包含特定 datetime 資料類型的子碼。 針對間隔資料類型,SQL_DESC_TYPE包含SQL_INTERVAL,而SQL_DESC_DATETIME_INTERVAL_CODE欄位包含特定間隔資料類型的子碼。

SQL_DESC_TYPE和SQL_DESC_CONCISE_TYPE欄位中的值是相互相依的。 每次設定其中一個欄位時,也必須設定另一個欄位。 SQL_DESC_TYPE可以透過呼叫 SQLSetDescField SQLSetDescRec 來設定。 SQL_DESC_CONCISE_TYPE可以透過呼叫 SQLBindCol SQLBindParameter SQLSetDescField 來設定。

如果SQL_DESC_TYPE設定為間隔或 datetime 資料類型以外的精簡資料類型,則SQL_DESC_CONCISE_TYPE欄位會設定為相同的值,且SQL_DESC_DATETIME_INTERVAL_CODE欄位設定為 0。

如果SQL_DESC_TYPE設定為詳細資訊日期時間或間隔資料類型(SQL_DATETIME或SQL_INTERVAL),且SQL_DESC_DATETIME_INTERVAL_CODE欄位設定為適當的副程式代碼,SQL_DESC_CONCISE TYPE 欄位會設定為對應的精簡類型。 嘗試將SQL_DESC_TYPE設定為其中一個精簡的日期時間或間隔類型,將會傳回 SQLSTATE HY021 (不一致的描述元資訊)。

當呼叫 SQLBindCol SQLBindParameter SQLSetDescField 來設定 SQL_DESC_TYPE欄位時,下欄欄位會設定為下列預設值,如下表所示。 相同記錄的其餘欄位值未定義。

SQL_DESC_TYPE值 其他欄位會隱含設定
SQL_CHAR、SQL_VARCHAR、SQL_C_CHAR、SQL_C_VARCHAR SQL_DESC_LENGTH設為 1。 SQL_DESC_PRECISION設定為 0。
SQL_DATETIME 當SQL_DESC_DATETIME_INTERVAL_CODE設定為SQL_CODE_DATE或SQL_CODE_TIME時,SQL_DESC_PRECISION會設定為 0。 當它設定為SQL_DESC_TIMESTAMP時,SQL_DESC_PRECISION會設定為 6。
SQL_DECIMAL、SQL_NUMERIC、SQL_C_NUMERIC SQL_DESC_SCALE設為 0。 SQL_DESC_PRECISION會設定為個別資料類型的實作定義有效位數。

如需如何手動系結SQL_C_NUMERIC值的資訊,請參閱 SQL to C:數值
SQL_FLOAT,SQL_C_FLOAT SQL_DESC_PRECISION會設定為 SQL_FLOAT 實作定義的預設精確度。
SQL_INTERVAL 當SQL_DESC_DATETIME_INTERVAL_CODE設定為間隔資料類型時,SQL_DESC_DATETIME_INTERVAL_PRECISION會設定為 2(預設間隔前置精確度)。 當間隔有秒元件時,SQL_DESC_PRECISION會設定為 6(預設間隔秒有效位數)。

當應用程式呼叫 SQLSetDescField 來設定描述元的欄位,而不是呼叫 SQLSetDescRec 時,應用程式必須先宣告資料類型。 這樣做時,會隱含地設定上一個資料表中指出的其他欄位。 如果隱含設定的任何值都無法接受,應用程式就可以呼叫 SQLSetDescField SQLSetDescRec 來明確設定無法接受的值。

SQL_DESC_TYPE_NAME [實作描述項]
這個唯讀 SQLCHAR * 記錄欄位包含資料來源相依類型名稱(例如 「CHAR」、「VARCHAR」 等等)。 如果資料類型名稱未知,此變數會包含空字串。

SQL_DESC_UNNAMED [實作描述項]
當驅動程式設定SQL_DESC_NAME欄位時,此 SQLSMALLINT 記錄欄位是由驅動程式設定為SQL_NAMED或SQL_UNNAMED。 如果SQL_DESC_NAME欄位包含資料行別名,或資料行別名不適用,驅動程式會將SQL_DESC_UNNAMED欄位設定為SQL_NAMED。 如果應用程式將 IPD 的 SQL_DESC_NAME 欄位設定為參數名稱或別名,驅動程式會將 IPD 的 SQL_DESC_UNNAMED 欄位設定為 SQL_NAMED。 如果沒有資料行名稱或資料行別名,驅動程式會將SQL_DESC_UNNAMED欄位設定為SQL_UNNAMED。

應用程式可以將 IPD 的 SQL_DESC_UNNAMED 欄位設定為 SQL_UNNAMED。 如果應用程式嘗試將 IPD 的SQL_DESC_UNNAMED欄位設定為SQL_NAMED,驅動程式會傳回 SQLSTATE HY091 (不正確描述元欄位識別碼)。 IRD 的SQL_DESC_UNNAMED欄位是唯讀的;如果應用程式嘗試設定 SQLSTATE HY091 ,將會傳回不正確描述元欄位識別碼。

SQL_DESC_UNSIGNED [實作描述項]
如果資料行類型為不帶正負號或非數值,則這個唯讀 SQLSMALLINT 記錄欄位會設定為SQL_TRUE;如果資料行類型為帶正負號,則為SQL_FALSE。

SQL_DESC_UPDATABLE [IRD]
這個唯讀 SQLSMALLINT 記錄欄位會設定為下列其中一個值:

  • 如果結果集資料行是唯讀的,SQL_ATTR_READ_ONLY。

  • 如果結果集資料行是讀寫,SQL_ATTR_WRITE。

  • 如果不知道結果集資料行是否可更新,SQL_ATTR_READWRITE_UNKNOWN。

SQL_DESC_UPDATABLE描述結果集中資料行的可更新性,而不是基表中的資料行。 此結果集資料行所依據之基表中的資料行可更新性,可能與此欄位中的值不同。 資料行是否可以根據資料類型、使用者許可權和結果集本身的定義來更新。 如果不清楚資料行是否可更新,則應該傳回SQL_ATTR_READWRITE_UNKNOWN。

一致性檢查

每當應用程式傳入 ARD、APD 或 IPD SQL_DESC_DATA_PTR 欄位的值時,驅動程式會自動執行一致性檢查。 如果任何欄位與其他欄位不一致, SQLSetDescField 會傳回 SQLSTATE HY021(不一致的描述元資訊)。 如需詳細資訊,請參閱 SQLSetDescRec 中的

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

另請參閱

ODBC 標頭檔
ODBC API 參考