SQLPrimaryKeys 函式
一致性
引進的版本：ODBC 1.0 標準合規性：ODBC
摘要
SQLPrimaryKeys 會傳回組成資料表主鍵的資料行名稱。 驅動程式會將資訊當作結果集傳回。 此函式不支援在單一呼叫中從多個資料表傳回主鍵。
語法
SQLRETURN SQLPrimaryKeys(
SQLHSTMT StatementHandle,
SQLCHAR * CatalogName,
SQLSMALLINT NameLength1,
SQLCHAR * SchemaName,
SQLSMALLINT NameLength2,
SQLCHAR * TableName,
SQLSMALLINT NameLength3);
引數
StatementHandle
[輸入]語句控制碼。
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 的字元長度 。
傳回
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR或SQL_INVALID_HANDLE。
診斷
當 SQLPrimaryKeys 傳回SQL_ERROR或SQL_SUCCESS_WITH_INFO時，可以藉由呼叫 SQLGetDiagRec 搭配 SQL_HANDLE_STMT 的 HandleType 和 StatementHandle 句 柄 來取得相關聯的 SQLSTATE 值。 下表列出 SQLPrimaryKeys 通常傳 回的 SQLSTATE 值，並說明此函式內容中的每個值;標記法 「（DM）」 在驅動程式管理員傳回的 SQLSTATE 描述之前。 除非另有說明，否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。
| SQLSTATE | 錯誤 | 描述 |
|---|---|---|
| 01000 | 一般警告 | 驅動程式特定的資訊訊息。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| 08S01 | 通訊連結失敗 | 驅動程式與驅動程式連線的資料來源之間的通訊連結在函式完成處理之前失敗。 |
| 24000 | 不正確資料指標狀態 | （DM） 語句上已開啟 資料指標，並 已呼叫 SQLFetch 或 SQLFetchScroll 。 語句上已開啟 資料指標，但 未呼叫 SQLFetch 或 SQLFetchScroll 。 |
| 40001 | 序列化失敗 | 交易因為與另一個交易發生資源死結而回復。 |
| 40003 | 語句完成未知 | 此函式執行期間相關聯的連接失敗，且無法判斷交易的狀態。 |
| HY000 | 一般錯誤 | 發生錯誤，其中沒有特定的 SQLSTATE，也沒有定義任何實作特定的 SQLSTATE。 *MessageText 緩衝區中 SQLGetDiagRec 傳 回的錯誤訊息描述錯誤及其原因。 |
| HY001 | 記憶體配置錯誤 | 驅動程式無法配置支援執行或完成函式所需的記憶體。 |
| HY008 | 作業已取消 | 已針對 StatementHandle 啟用非同步處理。 已呼叫函式，並在完成執行之前， 在 StatementHandle 上 呼叫 SQLCancel 或 SQLCancelHandle 。 然後在 StatementHandle 上 再次呼叫函式。 呼叫函式，並在完成執行之前， 從多執行緒應用程式中的不同執行緒呼叫 語句Handle 或 SQLCancelHandle 。 |
| HY009 | 不正確 Null 指標使用 | （DM） TableName 引數是 Null 指標。 SQL_ATTR_METADATA_ID語句屬性已設定為 SQL_TRUE、 CatalogName 引數為 null 指標，而 具有SQL_CATALOG_NAME資訊類型的 SQLGetInfo 會傳回支援目錄名稱的 SQLGetInfo 。 （DM） SQL_ATTR_METADATA_ID 語句屬性設定為 SQL_TRUE， 而 SchemaName 引數為 null 指標。 |
| HY010 | 函式順序錯誤 | （DM） 已針對與 StatementHandle 相關聯的連接控制碼呼叫非同步執行函式。 呼叫 SQLPrimaryKeys 函式時 ，這個非同步函 式仍在執行中。 （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，且相關聯的 name 引數不是 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 ，才能執行後續處理並完成作業。 |
註解
SQLPrimaryKeys 會以標準結果集的形式傳回結果，依TABLE_CAT、TABLE_SCHEM、TABLE_NAME和KEY_SEQ排序。 如需如何使用這項資訊的資訊，請參閱 目錄資料的 使用方式。
下列資料行已針對 ODBC 3 重新命名。 x . 資料行名稱變更不會影響回溯相容性，因為應用程式會依資料行編號系結。
| ODBC 2.0 資料行 | ODBC 3. x 欄 |
|---|---|
| TABLE_QUALIFIER | TABLE_CAT |
| TABLE_OWNER | TABLE_SCHEM |
若要判斷TABLE_CAT、TABLE_SCHEM、TABLE_NAME和COLUMN_NAME資料行的實際長度，請使用SQL_MAX_CATALOG_NAME_LEN、SQL_MAX_SCHEMA_NAME_LEN、SQL_MAX_TABLE_NAME_LEN和SQL_MAX_COLUMN_NAME_LEN選項呼叫 SQLGetInfo 。
注意
如需 ODBC 類別目錄函式的一般使用、引數和傳回資料的詳細資訊，請參閱 目錄函式 。
下表列出結果集中的資料行。 驅動程式可以定義資料行 6 以外的其他資料行（PK_NAME）。 應用程式應該從結果集結尾倒數，而不是指定明確的序數位置，以存取驅動程式特定的資料行。 如需詳細資訊，請參閱 目錄函 式傳回的資料。
| 資料行名稱 | Column number | 資料類型 | 註解 |
|---|---|---|---|
| TABLE_CAT （ODBC 1.0） | 1 | Varchar | 主鍵資料表目錄名稱;如果不適用於資料來源，則為 Null。 如果驅動程式支援某些資料表的目錄，但不支援其他資料表，例如當驅動程式從不同的 DBMS 擷取資料時，它會針對沒有目錄的資料表傳回空字串 （「」）。 |
| TABLE_SCHEM （ODBC 1.0） | 2 | Varchar | 主鍵資料表架構名稱;如果不適用於資料來源，則為 Null。 如果驅動程式支援某些資料表的架構，但不支援其他資料表，例如當驅動程式從不同的 DBMS 擷取資料時，它會針對沒有架構的資料表傳回空字串 （「」）。 |
| TABLE_NAME （ODBC 1.0） | 3 | Varchar not Null | 主鍵資料表名稱。 |
| COLUMN_NAME （ODBC 1.0） | 4 | Varchar not Null | 主鍵資料行名稱。 驅動程式會針對沒有名稱的資料行傳回空字串。 |
| KEY_SEQ （ODBC 1.0） | 5 | Smallint not Null | 索引鍵中的資料行序號（從 1 開始）。 |
| PK_NAME （ODBC 2.0） | 6 | Varchar | 主鍵名稱。 如果不適用於資料來源，則為 Null。 |
程式碼範例
請參閱 SQLForeignKeys 。
相關函數
| 如需下列資訊 | 請參閱 |
|---|---|
| 將緩衝區系結至結果集中的資料行 | SQLBindCol 函式 |
| 取消語句處理 | SQLCancel 函式 |
| 擷取資料區塊或捲動結果集 | SQLFetchScroll 函式 |
| 以正向方向擷取單一資料列或資料區塊 | SQLFetch 函式 |
| 傳回外鍵的資料行 | SQLForeignKeys 函式 |
| 傳回資料表統計資料和索引 | SQLStatistics 函式 |