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 的HandleTypeStatementHandle的 HandleType呼叫SQLGetDiagRec來取得相關聯的 SQLSTATE 值。 下表列出 SQLSpecialColumns 通常傳回的 SQLSTATE 值,並說明此函式內容中的每個值;標記法 「 (DM) 」 在驅動程式管理員傳回的 SQLSTATE 描述之前。 除非另有說明,否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。

SQLSTATE 錯誤 描述
01000 一般警告 驅動程式特定的資訊訊息。 (函式會傳回 SQL_SUCCESS_WITH_INFO.)
08S01 通訊連結失敗 驅動程式與驅動程式連線的資料來源之間的通訊連結在函式完成處理之前失敗。
24000 指標狀態無效 StatementHandle上開啟資料指標,並已呼叫 SQLFetchSQLFetchScroll 。 如果SQLFetch或 SQLFetchScroll 尚未傳回SQL_NO_DATA,而且如果SQLFetch 或 SQLFetchScroll傳回SQL_NO_DATA,驅動程式就會傳回此錯誤。

StatementHandle上開啟資料指標,但尚未呼叫 SQLFetchSQLFetchScroll
40001 序列化失敗 因為資源死結與另一筆交易,所以交易已回復。
40003 語句完成未知 在執行此函式時,相關聯的連線失敗,無法判斷交易的狀態。
HY000 一般錯誤 發生錯誤,其中沒有特定的 SQLSTATE,而且未定義任何實作特定的 SQLSTATE。 *MessageText緩衝區中SQLGetDiagRec傳回的錯誤訊息描述錯誤及其原因。
HY001 記憶體配置錯誤 驅動程式無法配置支援執行或完成函式所需的記憶體。
HY008 已取消作業 已針對 StatementHandle啟用非同步處理。 已呼叫函式,並在完成執行之前,在StatementHandle上呼叫SQLCancelSQLCancelHandle。 然後 ,在 StatementHandle上再次呼叫函式。

已呼叫函式,並在完成執行之前,從多執行緒應用程式中的不同執行緒呼叫SQLCancelSQLCancelHandle
HY009 Null 指標的使用無效 TableName引數是 Null 指標。

SQL_ATTR_METADATA_ID語句屬性設定為 SQL_TRUE、 CatalogName 引數是 null 指標,而 SQL_CATALOG_NAME InfoType 會傳回支援類別目錄名稱。

(DM) SQL_ATTR_METADATA_ID 語句屬性設定為 SQL_TRUE, 而 SchemaName 引數為 null 指標。
HY010 函式順序錯誤 (DM) 針對與 StatementHandle相關聯的連接控制碼呼叫非同步執行的函式。 呼叫 SQLSpecialColumns 時,此函式仍在執行中。

(DM) SQLExecuteSQLExecDirectSQLMoreResults 已針對 StatementHandle 呼叫並傳回SQL_PARAM_DATA_AVAILABLE。 在擷取所有串流參數的資料之前,會呼叫此函式。

(DM) 非同步執行的函式 (不是針對 StatementHandle 呼叫這個函式) ,而且在呼叫此函式時仍在執行。

(DM) SQLExecuteSQLExecDirectSQLBulkOperationsSQLSetPos 已針對 StatementHandle 呼叫並傳回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 已超過連線逾時 連線逾時期限在資料來源回應要求之前過期。 連線逾時期限是透過 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 用來傳回這些資料行的原因。 如需詳細資訊,請參閱 目錄資料的使用方式。

注意

如需 ODBC 目錄函式的一般使用、引數和傳回資料的詳細資訊,請參閱 目錄函式

如果沒有唯一識別資料表中每個資料列的資料行, SQLSpecialColumns 會傳回沒有資料列的資料列集;語句上 對 SQLFetchSQLFetchScroll 的後續呼叫會傳回SQL_NO_DATA。

如果 IdentifierTypeScopeNullable 引數指定資料來源不支援的特性, SQLSpecialColumns 會傳回空的結果集。

如果SQL_ATTR_METADATA_ID語句屬性設定為 SQL_TRUE,則 CatalogNameSchemaName 和 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) 。 應用程式應該從結果集結尾倒數,而不是指定明確的序數位置,以取得驅動程式特定資料行的存取權。 如需詳細資訊,請參閱 目錄函式傳回的資料

資料行名稱 資料行編號 資料類型 註解
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 非 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 整數 資料來源上資料行的大小。 如需資料行大小的詳細資訊,請參閱 資料行大小、十進位數、傳輸八位長度和顯示大小
BUFFER_LENGTH (ODBC 1.0) 6 整數 如果指定SQL_C_DEFAULT, 則為 SQLGetDataSQLFetch 作業上傳輸的資料位元組長度。 對於數值資料,此大小可能與儲存在資料來源上的資料大小不同。 這個值與字元或二進位資料的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 資料行。 相反的不是 true:即使 rowid 尚未變更,資料列中的其他資料行可能已經變更。

針對資料行類型傳回的資料行SQL_BEST_ROWID對於需要向前捲動和返回結果集中的應用程式很有用,以從一組資料列擷取最新的資料。 rowid 的資料行或資料行保證不會在該資料列上的位置變更。

即使資料指標不在資料列上,rowid 的資料行或資料行仍可能保持有效;應用程式可以藉由檢查結果集中的 SCOPE 資料行來判斷此情況。

針對資料行類型傳回的資料行SQL_ROWVER對於需要能夠檢查指定資料列中是否有任何資料行在使用 rowid 重新選取時更新資料列的應用程式很有用。 例如,在使用 rowid 重新選取資料列之後,應用程式可以將SQL_ROWVER資料行中的先前值與剛擷取的值進行比較。 如果SQL_ROWVER資料行中的值與先前的值不同,應用程式可以警示使用者顯示的資料已變更。

程式碼範例

如需類似函式的程式碼範例,請參閱 SQLColumns

如需下列資訊 請參閱
將緩衝區系結至結果集中的資料行 SQLBindCol 函數
取消語句處理 SQLCancel 函式
傳回資料表或資料表中的資料行 SQLColumns 函數
以順向方向擷取單一資料列或資料區塊 SQLFetch 函式
擷取資料區塊或捲動結果集 SQLFetchScroll 函數
傳回主鍵的資料行 SQLPrimaryKeys 函數

另請參閱

ODBC API 參考
ODBC 標頭檔