SQLPrimaryKeys() - 表の主キー列を取得する
SQLPrimaryKeys() は、表の主キーを構成する列名のリストを戻します。情報は、SQL 結果セットとして戻されます。 この結果セットは、 照会で生成される結果セットを処理するのと同じ関数を使用して、取り出すことができます。
SQLPrimaryKeys() の ODBC 仕様
| ODBC 仕様レベル | X/Open CLI CAE 仕様 | ISO CLI 仕様 |
|---|---|---|
| 1.0 | なし | なし |
構文
SQLRETURN SQLPrimaryKeys (SQLHSTMT hstmt,
SQLCHAR FAR *szCatalogName,
SQLSMALLINT cbCatalogName,
SQLCHAR FAR *szSchemaName,
SQLSMALLINT cbSchemaName,
SQLCHAR FAR *szTableName,
SQLSMALLINT cbTableName);
関数の引数
次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。
| データ・タイプ | 引数 | 使用法 | 説明 |
|---|---|---|---|
| SQLHSTMT | hstmt | 入力 | ステートメント・ハンドル。 |
| SQLCHAR * | szCatalogName | 入力 | 3 部構成の表名のカタログ修飾子。 これは、NULL ポインターまたは長さゼロのストリングでなければなりません。 |
| SQLSMALLINT | cbCatalogName | 入力 | szCatalogName の長さ (バイト)。 |
| SQLCHAR * | szSchemaName | 入力 | 表名のスキーマ修飾子。 |
| SQLSMALLINT | cbSchemaName | 入力 | szSchemaName の長さ (バイト)。 |
| SQLCHAR * | szTableName | 入力 | 表名。 |
| SQLSMALLINT | cbTableName | 入力 | szTableName の長さ (バイト)。 |
使用法
SQLPrimaryKeys() は、単一の表の主キー列を戻します。 検索パターンを使用してスキーマ修飾子または表名を指定することはできません。
結果セットには 表 3 にリストされている列が、TABLE_CAT、 TABLE_SCHEM、TABLE_NAME、および ORDINAL_POSITION の順序で入ります。
多くの場合、SQLPrimaryKeys() への呼び出しは、システム・カタログに対する複雑な (したがって、コストのかかる) 照会にマップされることになるため、その慎重に使用し、呼び出しを繰り返さずに、 結果を保管するようにしてください。
- SQL_MAX_CATALOG_NAME_LEN -- 接続されたデータベース管理システムがサポートする TABLE_CAT 列の長さを判別
- SQL_MAX_SCHEMA_NAME_LEN -- 接続されたデータベース管理システムがサポートする TABLE_SCHEM 列の長さを判別
- SQL_MAX_TABLE_NAME_LEN -- 接続されたデータベース管理システムがサポートする TABLE_NAME 列の長さを判別
- SQL_MAX_COLUMN_NAME_LEN -- 接続されたデータベース管理システムがサポートする COLUMN_NAME 列の長さを判別
将来のリリースでは、列が新たに追加されたり、既存の列の名前が 変更される可能性はありますが、現行の列の位置が変更になることはありま せん。次の表は、この関数が生成する結果セットの それぞれの列についてリストしています。
| 列番号 | 列名 | データ・タイプ | 説明 |
|---|---|---|---|
| 1 | TABLE_CAT | VARCHAR(128) | これは常に NULL です。 |
| 2 | TABLE_SCHEM | VARCHAR(128) | TABLE_NAME を含むスキーマの名前。 |
| 3 | TABLE_NAME | VARCHAR(128) NOT NULL | 指定した表の名前。 |
| 4 | COLUMN_NAME | VARCHAR(128) NOT NULL | 主キー列の名前。 |
| 5 | KEY_SEQ | SMALLINT NOT NULL | 1 から始まる主キー列シーケンス番号。 |
| 6 | PK_NAME | VARCHAR(128) | 主キー ID。 データ・ソースに適用できない場合は、NULL 値を含みます。 |
Db2 ODBC が使用する列名は、X/Open CLI CAE 仕様のスタイルに準拠しています。列タイプ、内容、および順序は、ODBC の SQLPrimaryKeys() 結果セット で定義されているものと同じです。
指定した表に主キーが含まれていない場合、空の結果セットが戻されます。
戻りコード
- SQL_SUCCESS
- SQL_SUCCESS_WITH_INFO
- SQL_ERROR
- SQL_INVALID_HANDLE
診断
次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。
| SQLSTATE | 説明 | 説明 |
|---|---|---|
| 24000 | カーソル状態が無効です。 | ステートメント・ハンドルに関連したカーソルは既に オープンされています。 |
| 40003 または 08S01 | 通信リンクに障害が起きました。 | 関数が完了する前に、アプリケーションとデータ・ソース間の 通信リンクで障害が発生しました。 |
| HY001 | メモリーの割り振りに失敗しました。 | Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。 |
| HY010 | 関数シーケンス・エラーが発生しました。 | この関数は、実行時データの操作時に呼び出されました。(すなわち、SQLParamData() または SQLPutData() 関数を使用するプロシージャー実行中に関数が呼び出されました。) |
| HY014 | これ以上ハンドルがありません。 | Db2 ODBC は、内部リソースが少ないためにハンドルを割り振ることができません。 |
| HY090 | ストリングまたはバッファーの長さが無効です。 | 名前の長さ引数のうちの 1 つの値は 0 より小さい値でしたが、SQL_NTS と 等しくありません。 |
| HYC00 | ドライバーは使用できません。 | Db2 ODBC は、表名の修飾子として catalog はサポートしていません。 |
例
/* ... */
#include <sqlcli1.h>
void main()
{
SQLCHAR rgbDesc_20];
SQLCHAR szTableName_20];
SQLCHAR szSchemaName_20];
SQLCHAR rgbValue_20];
SQLINTEGER pcbValue;
SQLHENV henv;
SQLHDBC hdbc;
SQLHSTMT hstmt;
SQLSMALLINT pscDesc;
SQLINTEGER pdDesc;
SQLRETURN rc;
/*******************************************************************/
/* Initialization... */
/*******************************************************************/
if( SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv)!= SQL_SUCCESS )
{
fprintf( stdout, "Error in SQLAllocHandle¥n" );
exit(1);
}
if( SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc)!= SQL_SUCCESS )
{
fprintf( stdout, "Error in SQLAllocHandle¥n" );
exit(1);
}
if( SQLConnect( hdbc,
NULL, SQL_NTS,
NULL, SQL_NTS,
NULL, SQL_NTS ) != SQL_SUCCESS )
{
fprintf( stdout, "Error in SQLConnect¥n" );
exit(1);
}
if( SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt)!= SQL_SUCCESS )
{
fprintf( stdout, "Error in SQLAllocHandle¥n" );
exit(1);
}
/*******************************************************************/
/* Get primary key for table 'myTable' by using SQLPrimaryKeys */
/*******************************************************************/
rc = SQLPrimaryKeys( hstmt,
NULL, SQL_NTS,
(SQLCHAR*)szSchemaName, SQL_NTS,
(SQLCHAR*)szTableName, SQL_NTS );
if( rc != SQL_SUCCESS )
{
goto exit;
}
/*
* Because all we need is the ordinal position, we'll bind column 5 from
* the result set.
*/
rc = SQLBindCol( hstmt,
5,
SQL_C_CHAR,
(SQLPOINTER)rgbValue,
20,
&pcbValue );
if( rc != SQL_SUCCESS )
{
goto exit;
}
/*
* Fetch data...
*/
if( SQLFetch( hstmt ) != SQL_SUCCESS )
{
goto exit;
}
/*******************************************************************/
/* Get data type for that column by calling SQLColAttribute(). */
/*******************************************************************/
rc = SQLColAttribute( hstmt,
pcbValue,
SQL_COLUMN_TYPE,
rgbDesc,
20,
&pcbDesc,
&pfDesc );
if( rc != SQL_SUCCESS )
{
goto exit;
}
/*
* Display the data type.
*/
fprintf( stdout, "Data type ==>
exit:
/*******************************************************************/
/* Clean up the environment... */
/*******************************************************************/
SQLEndTran(SQL_HANDLE_DBC, hdbc, SQL_ROLLBACK);
SQLDisconnect( hdbc );
SQLFreeHandle(SQL_HANDLE_DBC, hdbc);
SQLFreeHandle(SQL_HANDLE_ENV, henv);
}