符合性
推出版本：ODBC 1.0 標準合規性：開放群組
總結
SQLSpecialColumns 會取得指定資料表中欄位的以下資訊：
唯一識別表格中某一列的最佳欄位集合。
欄位在資料列中任一值被交易更新時自動更新。
Syntax
SQLRETURN SQLSpecialColumns(
SQLHSTMT StatementHandle,
SQLSMALLINT IdentifierType,
SQLCHAR * CatalogName,
SQLSMALLINT NameLength1,
SQLCHAR * SchemaName,
SQLSMALLINT NameLength2,
SQLCHAR * TableName,
SQLSMALLINT NameLength3,
SQLSMALLINT Scope,
SQLSMALLINT Nullable);
論點
StatementHandle
[輸入]語句句柄。
識別型別
[輸入]要回傳的欄位類型。 必須是下列其中一個值：
SQL_BEST_ROWID：回傳最佳欄位或欄位集合，透過從欄位取得值，允許指定資料表中任一列唯一識別。 欄位可以是專門為此目的設計的偽欄位（如 Oracle ROWID 或 Ingres TID），或是表格中任意唯一索引的欄位。
SQL_ROWVER：回傳指定資料表中，當資料來源自動更新該列中任何值時（如 SQLBase ROWID 或 Sybase TIMESTAMP）的欄位（如有）。
目錄名稱
[輸入]表格名稱。 若驅動程式支援某些資料表的目錄，但不支援其他資料表，例如當驅動從不同資料庫管理系統（DBMS）取得資料時，空字串（“”）表示那些沒有目錄的資料表。
目錄名稱 不能包含字串搜尋模式。
若SQL_ATTR_METADATA_ID語句屬性設為 SQL_TRUE，目錄 名稱 被視為識別碼，其大小寫不重要。 如果是SQL_FALSE，目錄 名稱 是一個普通的參數;它被字面上處理，且其案例意義重大。 如需詳細資訊，請參閱目錄函式中的引數。
名稱長度1
[輸入]*目錄名稱的字元長度。
結構描述名稱
[輸入]表格的結構名稱。 如果驅動程式支援某些資料表的結構，但不支援其他資料表，例如當驅動從不同資料庫管理系統（DBMS）取得資料時，空字串（“”）表示那些沒有結構的資料表。
SchemaName 不能包含字串搜尋模式。
若SQL_ATTR_METADATA_ID語句屬性設為 SQL_TRUE，SchemaName 被視為識別碼，其情況不重要。 如果是 SQL_FALSE，SchemaName 是一個普通參數;它被字面上處理，且其案例意義重大。
名稱長度2
[輸入]*SchemaName.
TableName
[輸入]桌名。 此參數不可能是空指標。
TableName 不能包含字串搜尋模式。
若 SQL_ATTR_METADATA_ID 陳述句屬性設為 SQL_TRUE，TableName 被視為識別碼，其大小寫不具意義。 如果是 SQL_FALSE，TableName 就是普通參數;它被字面上處理，且其案例意義重大。
名稱長度3
[輸入]*TableName 字元長度。
Scope
[輸入]這是 rowid 的最低要求範圍。 回歸的 rowid 可能範圍更大。 必須是下列其中一項：
SQL_SCOPE_CURROW：rowid 只有在該列位置時才保證有效。 若該列被其他交易更新或刪除，之後使用 rowid 重新選取時，可能無法回傳該列。
SQL_SCOPE_TRANSACTION：rowid 保證在當前交易期間有效。
SQL_SCOPE_SESSION：rowid 保證在整個會話期間（跨越交易邊界）有效。
可為空值
[輸入]決定是否回傳特殊欄位，這些欄位可能為 NULL 值。 必須是下列其中一項：
SQL_NO_NULLS：排除可能有 NULL 值的特殊欄位。 部分驅動程式無法支援SQL_NO_NULLS，若指定SQL_NO_NULLS，這些驅動程式會回傳空白結果集。 申請應為此案做好準備，並僅在絕對必要時申請SQL_NO_NULLS。
SQL_NULLABLE：即使欄位可能為 NULL，也回傳它們。
Returns
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR或SQL_INVALID_HANDLE。
Diagnostics
當 SQLSpecialColumns 回傳 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 時，可透過呼叫 SQLGetDiagRec 取得相應的 SQLSTATE 值，並將 HandleType 為 SQL_HANDLE_STMT，Handle 為 StatementHandle。 下表列出 SQLSpecialColumns 常見回傳的 SQLSTATE 值，並在此函式的情境中解釋每個值;「（DM）」符號會置於驅動程式管理器回傳的 SQLSTATE 描述前。 除非另有說明，否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。
| SQLSTATE | 錯誤 | 說明 |
|---|---|---|
| 01000 | 一般警告 | 驅動程式特定的資訊訊息。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| 08S01 | 通訊連結故障 | 驅動程式與驅動程式連線的數據源之間的通訊連結在函式完成處理之前失敗。 |
| 24000 | 無效的數據指標狀態 |
StatementHandle 上開啟游標，並呼叫了 SQLFetch 或 SQLFetchScroll。 若 SQLFetch 或 SQLFetchScroll 未回傳SQL_NO_DATA，驅動程式會回傳此錯誤;若 SQLFetch 或 SQLFetchScroll 回傳SQL_NO_DATA，驅動程式也會回傳此錯誤。 StatementHandle 上開啟游標，但尚未呼叫 SQLFetch 或 SQLFetchScroll。 |
| 40001 | 串行化失敗 | 交易因為與另一個交易發生資源死結而回復。 |
| 40003 | 語句完成未知 | 此函式執行期間相關聯的連接失敗，且無法判斷交易的狀態。 |
| HY000 | 一般誤差 | 發生錯誤，其中沒有特定的 SQLSTATE，也沒有定義任何實作特定的 SQLSTATE。 *MessageText 緩衝區中 SQLGetDiagRec 傳回的錯誤訊息描述錯誤及其原因。 |
| HY001 | 記憶體配置錯誤 | 驅動程式無法配置支援執行或完成函式所需的記憶體。 |
| HY008 | 行動取消 | 已針對 StatementHandle 啟用異步處理。 已呼叫函式，並在完成執行之前，在 StatementHandle 上呼叫 SQLCancel 或 SQLCancelHandle。 然後在 StatementHandle 上再次呼叫函式。 呼叫函式，並在完成執行之前，從多線程應用程式中的不同線程呼叫語句Handle 或 SQLCancelHandle。 |
| HY009 | 無效的 Null 指標使用 |
TableName 參數是空指標。 SQL_ATTR_METADATA_ID 陳述屬性設為 SQL_TRUE，CatalogName 參數為空指標，SQL_CATALOG_NAME InfoType 回傳支援目錄名稱。 （DM） SQL_ATTR_METADATA_ID 陳述句屬性設為 SQL_TRUE，SchemaName 參數為空指標。 |
| HY010 | 函式順序錯誤 | （DM） 已針對與 StatementHandle 相關聯的連接句柄呼叫異步執行函式。 當呼叫 SQLSpecialColumns 時，這個函式仍在執行中。 （DM） 已針對 StatementHandle 呼叫 SQLExecute、SQLExecDirect 或 SQLMoreResults，並傳回SQL_PARAM_DATA_AVAILABLE。 在擷取所有數據流參數的數據之前，會呼叫此函式。 （DM） 呼叫 StatementHandle 的異步執行函式（而非此函式），並在呼叫此函式時仍在執行中。 （DM） 已針對 StatementHandle 呼叫 SQLExecute、SQLExecDirect、SQLBulkOperations 或 SQLSetPos，並傳回SQL_NEED_DATA。 在針對所有數據執行中參數或數據行傳送數據之前，會呼叫此函式。 |
| HY013 | 記憶體管理錯誤 | 無法處理函式呼叫，因為基礎記憶體物件無法存取，可能是因為記憶體不足的情況。 |
| HY090 | 無效的字串或緩衝區長度 | （DM） 其中一個長度參數的值小於 0，但不等於 SQL_NTS。 其中一個長度參數的值超過了對應名稱的最大長度值。 每個名稱的最大長度可透過呼叫 SQLGetInfo 以 InfoType 值取得：SQL_MAX_CATALOG_NAME_LEN、SQL_MAX_SCHEMA_NAME_LEN 或 SQL_MAX_TABLE_NAME_LEN。 |
| HY097 | 欄位類型超出範圍 | （DM） 指定了一個無效的 IdentifierType 值。 |
| HY098 | 望遠鏡類型超出範圍 | （DM） 指定了一個無效 的範圍 值。 |
| HY099 | 可歸零型別超出範圍 | （DM） 指定了一個無效 的 Nullable 值。 |
| HY117 | 聯機因為未知的交易狀態而暫停。 只允許中斷連線和唯讀函式。 | （DM） 如需暫停狀態的詳細資訊，請參閱 SQLEndTran 函式。 |
| HYC00 | 未實作選擇性功能 | 指定了一個目錄，但驅動程式或資料來源不支援目錄。 已指定結構，驅動程式或資料來源不支援結構。 驅動程式或數據源不支援SQL_ATTR_CONCURRENCY和SQL_ATTR_CURSOR_TYPE語句屬性的目前設定組合。 SQL_ATTR_USE_BOOKMARKS語句屬性已設定為 SQL_UB_VARIABLE，且SQL_ATTR_CURSOR_TYPE語句屬性已設定為驅動程式不支援書籤的數據指標類型。 |
| HYT00 | 逾時期限已到 | 查詢逾時期在資料來源回傳請求的結果集前已過期。 逾時期間是透過 SQLSetStmtAttr 來設定，SQL_ATTR_QUERY_TIMEOUT。 |
| HYT01 | 連線已逾時 | 在數據源回應要求之前，連線逾時期限已過期。 線上逾時期間是透過 SQLSetConnectAttr 來設定，SQL_ATTR_CONNECTION_TIMEOUT。 |
| IM001 | 驅動程式不支援此函式 | （DM） 與 StatementHandle 相關聯的驅動程式不支援 函式。 |
| IM017 | 在異步通知模式中停用輪詢 | 每當使用通知模型時，輪詢就會停用。 |
| IM018 | 尚未呼叫 SQLCompleteAsync ，以完成此句柄上的先前異步操作。 | 如果句柄上的上一個函式呼叫傳回SQL_STILL_EXECUTING且啟用通知模式， 則必須在句柄上呼叫 SQLCompleteAsync ，才能執行後續處理並完成作業。 |
評論
當 IdentifierType 參數被SQL_BEST_ROWID時， SQLSpecialColumns 會回傳唯一識別表格中每一列的欄位。 這些欄位可以隨時用於 選擇清單 或 WHERE 子句。 SQLColumns 用於回傳資料表欄位的各種資訊，但不一定回傳能唯一識別每列的欄位，或是當交易更新時，列中任一值會自動更新的欄位。 例如， SQLColumns 可能不會回傳 Oracle 偽欄位的 ROWID。 這就是為什麼使用 SQLSpecialColumns 來回傳這些欄位。 如需進一步資訊，請參閱目錄資料使用方式。
Note
欲了解更多關於 ODBC 目錄函式的一般用途、參數及回傳資料，請參見 目錄函式。
如果沒有欄位能唯一識別每一列， SQLSpecialColumns 會回傳一個沒有列的列集;後續呼叫 SQLFetch 或 SQLFetchScroll 對該語句會回傳 SQL_NO_DATA。
若 IdentifierType、 Scope 或 Nullable 參數指定了資料來源不支援的特性， SQLSpecialColumns 會回傳一個空的結果集。
若 SQL_ATTR_METADATA_ID 陳述式屬性設為 SQL_TRUE，則 CatalogName、 SchemaName 與 TableName 參數被視為識別碼，因此在某些情況下無法設定為空指標。 （更多資訊請參見 目錄函數中的參數。）
SQLSpecialColumns 以標準結果集的形式回傳結果，依 SCOPE 排序。
以下欄位已更名為 ODBC 3.x。 欄位名稱的變更不會影響向下相容性，因為應用程式是以欄位編號綁定的。
| ODBC 2.0 欄位 | ODBC 3.x 欄 |
|---|---|
| PRECISION | 欄位大小 |
| 長度 | 緩衝區長度 |
| 規模 | 小數位數 |
為了確定COLUMN_NAME欄位的實際長度，應用程式可以呼叫 SQLGetInfo 並啟用 SQL_MAX_COLUMN_NAME_LEN 選項。
下表列出結果集中的欄位。 第 8 欄（PSEUDO_COLUMN）之外的其他欄位可由驅動程式定義。 應用程式應透過從結果集末端倒數而非指定明確序數位置，來取得驅動程式專屬欄位的存取權。 欲了解更多資訊，請參閱 目錄函數回傳的資料。
| 欄位名稱 | 欄號 | 資料類型 | 評論 |
|---|---|---|---|
| 範圍（ODBC 1.0） | 1 | Smallint | 真正的 rowid 範圍。 包含以下其中一個值： SQL_SCOPE_CURROW SQL_SCOPE_TRANSACTION SQL_SCOPE_SESSION 當 IdentifierType 被 SQL_ROWVER 時，會回傳 NULL。 關於每個值的描述，請參見本節前半部分「語法」中的 範圍 描述。 |
| COLUMN_NAME（ODBC 1.0） | 2 | Varchar 不是 NULL | 欄位名稱。 驅動程式會回傳一個沒有名稱的欄位的空字串。 |
| DATA_TYPE（ODBC 1.0） | 3 | Smallint 不是 NULL | SQL 數據類型。 這可以是 ODBC SQL 資料類型或驅動程式特定的 SQL 資料類型。 有關有效 ODBC SQL 資料型態的清單，請參見 SQL 資料型別。 如需驅動程式特定SQL數據類型的相關信息，請參閱驅動程序的檔。 |
| TYPE_NAME（ODBC 1.0） | 4 | Varchar 不是 NULL | 數據源相依數據類型名稱;例如，“CHAR”、“VARCHAR”、“MONEY”、“LONG VARBINARY” 或 “CHAR （ ） FOR BIT DATA”。 |
| COLUMN_SIZE（ODBC 1.0） | 5 | Integer | 資料來源欄位的大小。 欲了解更多關於欄位大小的資訊，請參閱欄位 大小、十進位數字、傳輸八重奏長度及顯示大小。 |
| BUFFER_LENGTH（ODBC 1.0） | 6 | Integer | 如果指定SQL_C_DEFAULT，SQLGetData 或 SQLFetch 作業上傳輸的數據長度。 對於數值數據，此大小可能與儲存在數據源上的數據大小不同。 此值可能與字元資料欄位COLUMN_SIZE不同。 更多資訊請參閱欄位 大小、小數位、傳輸八重奏長度及顯示大小。 |
| DECIMAL_DIGITS（ODBC 1.0） | 7 | Smallint | 資料來源欄位的十進位數字。 對於不適用小數位的資料型別，會回傳 NULL。 欲了解更多關於十進位數字的資訊，請參閱欄 大小、十進位數字、傳輸八重奏長度及顯示大小。 |
| PSEUDO_COLUMN（ODBC 2.0） | 8 | Smallint | 表示該欄位是否為偽欄位，例如 Oracle ROWID： SQL_PC_UNKNOWN SQL_PC_NOT_PSEUDO SQL_PC_PSEUDO 注意： 為最大互通性，偽欄位不應以 SQLGetInfo 回傳的識別碼引用字元引用。 |
應用程式取得 SQL_BEST_ROWID 值後，可以用這些值在定義範圍內重新選取該列。 SELECT 陳述式保證會回傳無列或只回傳一列。
如果應用程式根據 rowid 欄位重新選取某一列，但找不到該列，應用程式可以假設該列已被刪除或列多欄位被修改。 反之則不成立：即使行狀元未變，列中其他欄位也可能改變。
欄位類型 SQL_BEST_ROWID 回傳欄位對於需要在結果集內前後捲動以從一組資料列中取得最新資料的應用程式非常有用。 rowid 的欄位在該欄位上時保證不會改變。
即使游標未位於該行上，該行的欄位仍可能有效;應用程式可透過檢查結果集中的 SCOPE 欄位來判斷。
欄位類型 SQL_ROWVER 回傳欄位對於需要檢查該列在重新選取該列時是否已更新的應用程式非常有用。 例如，在使用 rowid 重新選取一列後，應用程式可以比較SQL_ROWVER欄中先前的值與剛取得的值。 如果SQL_ROWVER欄位的值與前一個值不同，應用程式可以提醒使用者顯示資料已變更。
程式碼範例
類似函式的程式碼範例請參見 SQLColumns。
相關函數
| 如需相關信息 | 看！ |
|---|---|
| 將緩衝區系結至結果集中的數據行 | SQLBindCol 函式 |
| 取消語句處理 | SQLCancel 函式 |
| 在表格中回傳欄位 | SQLColumns 函式 |
| 以僅向前向的方向擷取單一列或資料區塊 | SQLFetch 函式 |
| 擷取數據區塊或捲動結果集 | SQLFetchScroll 函式 |
| 返回主鍵的欄位 | SQLPrimaryKeys 函式 |