SQLSpecialColumns 函式
一致性
引進的版本：ODBC 1.0 標準合規性：開放群組
摘要
SQLSpecialColumns 会擷取指定數據表內數據行的下列資訊：
唯一識別數據表中數據列的最佳數據行集。
當交易更新數據列中任何值時自動更新的數據行。
語法
SQLRETURN SQLSpecialColumns(
SQLHSTMT StatementHandle,
SQLSMALLINT IdentifierType,
SQLCHAR * CatalogName,
SQLSMALLINT NameLength1,
SQLCHAR * SchemaName,
SQLSMALLINT NameLength2,
SQLCHAR * TableName,
SQLSMALLINT NameLength3,
SQLSMALLINT Scope,
SQLSMALLINT Nullable);
引數
StatementHandle
[輸入]語句句柄。
IdentifierType
[輸入]要傳回的數據行類型。 必須是下列其中一個值：
SQL_BEST_ROWID：從數據行或數據行擷取值，傳回最佳數據行或數據行集，允許唯一識別指定數據表中的任何數據列。 數據行可以是專為此目的設計的虛擬數據行（如 Oracle ROWID 或 Ingres TID），或是數據表中任何唯一索引的數據行或數據行。
SQL_ROWVER：傳回指定數據表中的數據行或數據行，如果有的話，當任何交易更新數據列中的任何值時，數據源就會自動更新數據行（如 SQLBase ROWID 或 Sybase TIMESTAMP 中）。
CatalogName
[輸入]數據表的目錄名稱。 如果驅動程式支援某些數據表的目錄，但不支援其他數據表，例如當驅動程式從不同的 DBMS 擷取數據時，空字串 （“”） 表示沒有目錄的數據表。 CatalogName 不能包含字串搜尋模式。
如果 SQL_ATTR_METADATA_ID 語句屬性設定為 SQL_TRUE， 則 CatalogName 會被視為標識碼，而且其大小寫並不重要。 如果它是SQL_FALSE，CatalogName 是一般自變數;它會以常值方式處理，而且其大小寫很重要。 如需詳細資訊，請參閱目錄函式中的引數。
NameLength1
[輸入]*CatalogName 的字元長度。
SchemaName
[輸入]數據表的架構名稱。 如果驅動程式支援某些數據表的架構，但不支援其他數據表，例如當驅動程式從不同的 DBMS 擷取數據時，空字串 （“”） 表示沒有架構的數據表。 SchemaName 不能包含字串搜尋模式。
如果 SQL_ATTR_METADATA_ID 語句屬性設定為 SQL_TRUE，則 SchemaName 會被視為標識碼，而且其大小寫並不重要。 如果它是SQL_FALSE，SchemaName 是一般自變數;它會以常值方式處理，而且其大小寫很重要。
NameLength2
[輸入]*SchemaName 的字元長度。
TableName
[輸入]數據表名稱。 這個自變數不可以是 Null 指標。 TableName 不能包含字串搜尋模式。
如果SQL_ATTR_METADATA_ID語句屬性設定為 SQL_TRUE，則 TableName 會被視為標識碼，而且其大小寫並不重要。 如果它是SQL_FALSE，TableName 是一般自變數;它會以常值方式處理，而且其大小寫很重要。
NameLength3
[輸入]*TableName 的字元長度。
範圍
[輸入]rowid 的最低必要範圍。 傳回的rowid可能範圍更大。 必須為下列其中一項：
SQL_SCOPE_CURROW：只有在位於該數據列上時，rowid 才保證有效。 如果數據列已由另一個交易更新或刪除數據列，則稍後使用 rowid 重新選取可能不會傳回數據列。
SQL_SCOPE_TRANSACTION：rowid 保證在目前交易期間有效。
SQL_SCOPE_SESSION：rowid 保證在會話期間有效（跨交易界限）。
可為 Null
[輸入]判斷是否要傳回可具有NULL值的特殊數據行。 必須為下列其中一項：
SQL_NO_NULLS：排除可具有 NULL 值的特殊數據行。 某些驅動程式不支援SQL_NO_NULLS，如果指定了SQL_NO_NULLS，這些驅動程式會傳回空的結果集。 只有在絕對必要的情況下，應用程式才應備妥此案例，並要求SQL_NO_NULLS。
SQL_NULLABLE：即使這些數據行可以有 NULL 值，仍會傳回特殊數據行。
傳回
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR或SQL_INVALID_HANDLE。
診斷
當 SQLSpecialColumns 傳回SQL_ERROR或SQL_SUCCESS_WITH_INFO時，可能會呼叫具有 SQL_HANDLE_STMT HandleType 和 StatementHandle Handle 的 HandleType 來取得相關聯的 SQLSTATE值。 下表列出 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，驅動程式就會傳回此錯誤。 語句上已開啟數據指標，但未呼叫 SQLFetch 或 SQLFetchScroll。 |
| 40001 | 串行化失敗 | 交易因為與另一個交易發生資源死結而回復。 |
| 40003 | 語句完成未知 | 此函式執行期間相關聯的連接失敗，且無法判斷交易的狀態。 |
| HY000 | 一般錯誤 | 發生錯誤，其中沒有特定的 SQLSTATE，也沒有定義任何實作特定的 SQLSTATE。 *MessageText 緩衝區中 SQLGetDiagRec 傳回的錯誤訊息描述錯誤及其原因。 |
| HY001 | 記憶體配置錯誤 | 驅動程式無法配置支援執行或完成函式所需的記憶體。 |
| HY008 | 作業已取消 | 已針對 StatementHandle 啟用異步處理。 已呼叫函式，並在完成執行之前，在 StatementHandle 上呼叫 SQLCancel 或 SQLCancelHandle。 然後在 StatementHandle 上再次呼叫函式。 呼叫函式，並在完成執行之前，從多線程應用程式中的不同線程呼叫語句Handle 或 SQLCancelHandle。 |
| HY009 | 無效的 Null 指標使用 | TableName 自變數是 Null 指標。 SQL_ATTR_METADATA_ID語句屬性已設定為 SQL_TRUE、CatalogName 自變數為 null 指標，而且 infoType SQL_CATALOG_NAME會傳回支援目錄名稱。 （DM） SQL_ATTR_METADATA_ID 語句屬性設定為 SQL_TRUE， 而 SchemaName 自變數為 null 指標。 |
| 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。 其中一個 length 自變數的值超過對應名稱的最大長度值。 使用 InfoType 值呼叫 SQLGetInfo，即可取得每個名稱的最大長度：SQL_MAX_CATALOG_NAME_LEN、SQL_MAX_SCHEMA_NAME_LEN或SQL_MAX_TABLE_NAME_LEN。 |
| HY097 | 超出範圍的數據行類型 | （DM） 已指定無效 的 IdentifierType 值。 |
| HY098 | 範圍類型超出範圍 | （DM） 指定了無效 的範圍 值。 |
| HY099 | 可為 Null 的類型超出範圍 | （DM） 已指定無效 的可為 Null 值。 |
| 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 | 已超過連線逾時 | 在數據源回應要求之前，連線逾時期限已過期。 連線逾時期間是透過 SQLSet 設定 連線 Attr，SQL_ATTR_CONNECTION_TIMEOUT。 |
| IM001 | 驅動程式不支援此函式 | （DM） 與 StatementHandle 相關聯的驅動程式不支援 函式。 |
| IM017 | 在異步通知模式中停用輪詢 | 每當使用通知模型時，輪詢就會停用。 |
| IM018 | 尚未呼叫 SQLCompleteAsync ，以完成此句柄上的先前異步操作。 | 如果句柄上的上一個函式呼叫傳回SQL_STILL_EXECUTING且啟用通知模式， 則必須在句柄上呼叫 SQLCompleteAsync ，才能執行後續處理並完成作業。 |
註解
當IdentifierType自變數SQL_BEST_ROWID時，SQLSpecialColumns 會傳回可唯一識別數據表中每個數據列的數據行。 這些數據行一律可用於 select-list 或 WHERE 子句。 SQLColumns 可用來傳回數據表數據行的各種資訊，不一定傳回可唯一識別每個數據列的數據行，或交易更新數據列中任何值時自動更新的數據行。 例如， SQLColumns 可能不會傳回 Oracle 虛擬資料行 ROWID。 這就是為什麼 SQLSpecialColumns 用來傳回這些數據行的原因。 如需進一步資訊，請參閱目錄資料使用方式。
注意
如需 ODBC 類別目錄函式的一般使用、自變數和傳回數據的詳細資訊，請參閱 目錄函式。
如果沒有可唯一識別數據表中每個數據列的數據行，SQLSpecialColumns 會傳回沒有數據列的數據列集;語句上的 SQLFetch 或 SQLFetchScroll 後續呼叫會傳回SQL_NO_DATA。
如果IdentifierType、Scope或 Nullable 自變數指定數據源不支援的特性，SQLSpecialColumns 會傳回空的結果集。
如果SQL_ATTR_METADATA_ID語句屬性設定為 SQL_TRUE， 則 CatalogName、 SchemaName 和 TableName 自變數會被視為標識符，因此在某些情況下，它們無法設定為 null 指標。 （如需詳細資訊，請參閱 Catalog Functions 中的自變數。
SQLSpecialColumns 會以依 SCOPE 排序的標準結果集傳回結果。
下列數據行已針對 ODBC 3.x 重新命名。 數據行名稱變更不會影響回溯相容性，因為應用程式會依數據行編號系結。
| ODBC 2.0 數據行 | ODBC 3.x 資料行 |
|---|---|
| PRECISION | COLUMN_SIZE |
| LENGTH | BUFFER_LENGTH |
| SCALE | DECIMAL_DIGITS |
若要判斷COLUMN_NAME數據行的實際長度，應用程式可以使用 SQL_MAX_COLUMN_NAME_LEN 選項呼叫 SQLGetInfo 。
下表列出結果集中的數據行。 驅動程式可以定義數據行 8 以外的其他數據行（PSEUDO_COLUMN）。 應用程式應該從結果集結尾倒數，而不是指定明確的序數位置，以存取驅動程式特定的數據行。 如需詳細資訊，請參閱 目錄函式傳回的數據。
| 資料行名稱 | Column number | 資料類型 | 註解 |
|---|---|---|---|
| SCOPE （ODBC 1.0） | 1 | Smallint | rowid 的實際範圍。 包含下列其中一個值： SQL_SCOPE_CURROW SQL_SCOPE_TRANSACTION SQL_SCOPE_SESSION 當IdentifierType SQL_ROWVER時，會傳回NULL。 如需每個值的描述，請參閱本節稍早的 中的 Scope 描述。 |
| COLUMN_NAME （ODBC 1.0） | 2 | Varchar not NULL | 資料行名稱。 驅動程式會針對沒有名稱的數據行傳回空字串。 |
| DATA_TYPE （ODBC 1.0） | 3 | Smallint not NULL | SQL 數據類型。 這可以是 ODBC SQL 資料類型或驅動程式特定的 SQL 資料類型。 如需有效的 ODBC SQL 資料類型清單，請參閱 SQL 資料類型。 如需驅動程式特定SQL數據類型的相關信息，請參閱驅動程序的檔。 |
| TYPE_NAME （ODBC 1.0） | 4 | Varchar not NULL | 數據源相依數據類型名稱;例如，“CHAR”、“VARCHAR”、“MONEY”、“LONG VARBINARY” 或 “CHAR （ ） FOR BIT DATA”。 |
| COLUMN_SIZE （ODBC 1.0） | 5 | 整數 | 數據源上數據行的大小。 如需數據行大小的詳細資訊，請參閱 數據行大小、十進位數、傳輸八進位長度和顯示大小。 |
| BUFFER_LENGTH （ODBC 1.0） | 6 | 整數 | 如果指定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資料行或資料行重新選取資料列，而且找不到資料列，則應用程式可以假設已刪除資料列或修改rowid資料行。 相反的是：即使 rowid 未變更，數據列中的其他數據行可能已變更。
針對數據行類型傳回的數據行SQL_BEST_ROWID對於需要在結果集中向前捲動和往後捲動的應用程式很有用，以便從一組數據列擷取最新的數據。 rowid 的數據行或數據行保證不會在位於該數據列時變更。
即使數據指標不在數據列上，rowid 的數據行或數據行仍然有效;應用程式可以藉由檢查結果集中的 SCOPE 資料行來判斷此情況。
針對數據行類型傳回的數據行SQL_ROWVER對於需要能夠檢查指定數據列中是否有任何數據行在使用 rowid 重新選取時更新數據列的應用程式很有用。 例如，在使用 rowid 重新選取數據列之後，應用程式可以將SQL_ROWVER數據行中的先前值與剛擷取的值進行比較。 如果SQL_ROWVER數據行中的值與上一個值不同，應用程式可以警示使用者顯示的數據已變更。
程式碼範例
如需類似函式的程式碼範例，請參閱 SQLColumns。
相關函數
| 如需下列資訊 | 請參閱 |
|---|---|
| 將緩衝區系結至結果集中的數據行 | SQLBindCol 函式 |
| 取消語句處理 | SQLCancel 函式 |
| 傳回數據表或數據表中的數據行 | SQLColumns 函式 |
| 以正向方向擷取單一數據列或數據區塊 | SQLFetch 函式 |
| 擷取數據區塊或捲動結果集 | SQLFetchScroll 函式 |
| 傳回主鍵的數據行 | SQLPrimaryKeys 函式 |