SQLGetTypeInfo() - データ・タイプ情報を取得する

SQLGetTypeInfo() は、Db2® ODBC に関連付けられたデータベース管理システムが サポートするデータ・タイプについての情報を戻します。この情報は、SQL 結果セットとして戻されます。 この結果セットの列は、照会処理に 使用するものと同じ関数を使用して、受け取ることができます。

SQLGetTypeInfo() の ODBC 仕様

表 1. SQLGetTypeInfo() の仕様
ODBC 仕様レベル X/Open CLI CAE 仕様 ISO CLI 仕様
1.0 あり あり

構文

SQLRETURN   SQLGetTypeInfo   (SQLHSTMT          hstmt,
                              SQLSMALLINT       fSqlType);

関数の引数

次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。

表 2. SQLGetTypeInfo() の引数
データ・タイプ 引数 使用法 説明
SQLHSTMT hstmt 入力 ステートメント・ハンドルを指定します。
SQLSMALLINT fSqlType 入力 照会される SQL データ・タイプを指定します。 以下のデータ・タイプを指定する値がサポートされます。
  • SQL_ALL_TYPES
  • SQL_BIGINT
  • SQL_BINARY
  • SQL_BLOB
  • SQL_CHAR
  • SQL_CLOB
  • SQL_DBCLOB
  • SQL_DECFLOAT
  • SQL_DECIMAL
  • SQL_DOUBLE
  • SQL_FLOAT
  • SQL_GRAPHIC
  • SQL_INTEGER
  • SQL_LONGVARBINARY
  • SQL_LONGVARCHAR
  • SQL_LONGVARGRAPHIC
  • SQL_NUMERIC
  • SQL_REAL
  • SQL_ROWID
  • SQL_SMALLINT
  • SQL_TYPE_DATE
  • SQL_TYPE_TIME
  • SQL_TYPE_TIMESTAMP
  • SQL_VARBINARY
  • SQL_VARCHAR
  • SQL_VARGRAPHIC
  • SQL_XML
値 SQL_ALL_TYPES が指定されている場合は、サポートされるすべてのデータ・タイプに 関する情報が、TYPE_NAME の昇順で戻されます。 サポートされないデータ・タイプはすべて、結果セットには存在しません。

使用法

SQLGetTypeInfo() は、結果セットを生成するため、本質的には照会を実行することに相当 します。照会と同様に、SQLGetTypeInfo() を呼び出すと、カーソルが生成され、トランザクションが開始されます。このステートメント・ハンドルで別のステートメントを作成して実行するには、 カーソルをクローズする必要があります。

引数 fSqlType に無効値を指定して SQLGetTypeInfo() を呼び出すと、 空の結果セットが戻されます。

表 3 は、この関数が生成する結果セットの それぞれの列について記述しています。

将来のリリースで、列が新たに追加されたり、既存の列の名前が 変更される可能性はありますが、現行の列の位置は変わりません。 戻されるデータ・タイプは、CREATE TABLE、ALTER TABLE ステートメントで 使用できるデータ・タイプです。ロケーター・データ・タイプなどの非永続的なデータ・タイプは、 戻される結果セットの一部にはなりません。ユーザー定義のデータ・タイプも戻されません。

表 3. SQLGetTypeInfo() により戻される列
位置 列名 データ・タイプ 説明
1 TYPE_NAME VARCHAR(128) NOT NULL SQL データ定義言語データ・タイプ名の文字表現が入ります。例えば、VARCHAR、BLOB、DATE、 INTEGER。
2 DATA_TYPE SMALLINT NOT NULL SQL データ・タイプ定義値が入ります。例えば、SQL_VARCHAR、 SQL_BLOB、 SQL_TYPE_DATE、 SQL_INTEGER。
3 COLUMN_SIZE INTEGER データ・タイプが文字ストリングかバイナリー・ストリングである場合、この列には最大長 (バイト単位) が入ります。 このデータ・タイプが、グラフィック (DBCS) ストリングの場合、この列にはその列の 2 バイト文字の数が入ります。データ・タイプが XML の場合、ゼロが戻されます。

日付、時刻、タイム・スタンプのデータ・タイプの場合、 これは、文字に変換されたときに値の表示に必要な文字数の合計です。

数値データ・タイプの場合、この列には桁数の合計が入ります。

4 LITERAL_PREFIX VARCHAR(128) Db2 がこのデータ・タイプのリテラルの接頭部として認識する文字が入ります。 リテラル接頭部が適用不能なデータ・タイプの場合は、この列は NULL です。
5 LITERAL_SUFFIX VARCHAR(128) Db2 がこのデータ・タイプのリテラルの接尾部として認識する文字が入ります。 リテラル接尾部が適用不能なデータ・タイプの場合は、この列は NULL です。
6 CREATE_PARAMS VARCHAR(128) 複数の値の一覧がコンマで区切られて入ります。 これらの値は、CREATE TABLE または ALTER TABLE SQL ステートメントのデータ・タイプで 指定できる各パラメーターに対応しています。 結果セットのこの列には、以下の中から 1 つ以上の値が現れます。
  • LENGTH -- TYPE_NAME 列のデータ・タイプの長さを指定できることを示しています。
  • PRECISION -- TYPE_NAME 列のデータ・タイプの精度を指定できることを示しています。
  • SCALE -- TYPE_NAME 列のデータ・タイプの位取りを指定できることを示しています。
  • NULL 標識 -- TYPE_NAME 列のデータ・タイプのいずれのパラメーターも指定できないことを示しています。

使用法: CREATE_PARAMS 列によって、アプリケーションでデータ定義言語ビルダーのインターフェースをカスタマイズできます。データ定義言語ビルダー とは、表などの データベース・オブジェクトを作成するアプリケーションの一部分です。CREATE_PARAMS を使用 して、データ・タイプを定義するのに必要な引数の個数を決定し、 その後、ローカライズされたテキストを使用してデータ定義言語ビルダー上のコントロールにラベルを付けます。

7 NULLABLE SMALLINT NOT NULL データ・タイプが NULL 値を受け入れるかどうかを示します。 この列は、以下のいずれかの値を含んでいます。
  • SQL_NO_NULLS -- NULL 値は許可されないことを示しています。
  • SQL_NULLABLE -- NULL 値は許可されることを示しています。
8 CASE_SENSITIVE SMALLINT NOT NULL 照合するために、データ・タイプの大/小文字の区別を扱えるか どうかを示します。 この列は、以下のいずれかの値を含んでいます。
  • SQL_TRUE -- 大/小文字の区別があることを示しています。
  • SQL_FALSE -- 大/小文字の区別がないことを示しています。
9 SEARCHABLE SMALLINT NOT NULL WHERE 文節でのデータ・タイプの使用方法を示します。 この列は、以下のいずれかの値を含んでいます。
  • SQL_UNSEARCHABLE -- WHERE 文節では、データ・タイプが使用できないことを示しています。
  • SQL_LIKE_ONLY -- データ・タイプを WHERE 文節で使用できますが、LIKE 述部がある場合 に限られることを示しています。
  • SQL_ALL_EXCEPT_LIKE -- LIKE を除くすべての比較演算子を用いてデータ・タイプ を WHERE 文節で使用できることを示しています。
  • SQL_SEARCHABLE -- どの比較演算子を指定した WHERE 文節においてもこのデータ・タイプを 使用できることを示しています。
10 UNSIGNED_ATTRIBUTE SMALLINT データ・タイプが符号なしであるかどうかを示します。 この列は、以下のいずれかの値を含んでいます。
  • SQL_TRUE -- データ・タイプは符号なしであることを示しています。
  • SQL_FALSE -- データ・タイプは符号付きであることを示しています。
  • NULL -- この属性はデータ・タイプには適用されないことを示しています。
11 FIXED_PREC_SCALE SMALLINT NOT NULL データ・タイプが厳密な数であり、かつ常に同じ精度と 位取りである場合には、値 SQL_TRUE が入ります。そうでない場合には、SQL_FALSE が入ります。
12 AUTO_INCREMENT SMALLINT 行が挿入されたときに、このデータ・タイプの列が自動的に 固有の値に設定される場合には SQL_TRUE が入ります。 そうでない場合には SQL_FALSE が入ります。
13 LOCAL_TYPE_NAME VARCHAR(128) データ・タイプの正規名とは異なる、データ・タイプの ローカライズされた (自国語の) 名前が入ります。ローカライズされた名前がない場合は、 この列には NULL 標識が入ります。

この列は表示専用です。 ストリングの文字セットはロケールに依存しており、 通常はデータベースのデフォルト文字セットです。

14 MINIMUM_SCALE SMALLINT SQL データ・タイプの最小位取りが入ります。 データ・タイプが固定位取りの場合、MINIMUM_SCALE 列と MAXIMUM_SCALE 列には同じ値が入ります。 位取りが適用できない場合は、NULL が戻されます。
15 MAXIMUM_SCALE SMALLINT SQL データ・タイプの最大位取りが入ります。位取りが適用できない場合は、NULL が戻されます。 最大位取りがデータベース管理システム内で個別に定義されておらず、その代わりに列の最大長と同じものとして定義されている場合、 この列には COLUMN_SIZE 列と同じ値が入ります。

戻りコード

SQLGetTypeInfo() は、呼び出された後、次のいずれかの値を戻します。
  • SQL_SUCCESS
  • SQL_ERROR
  • SQL_INVALID_HANDLE

診断

次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。

表 4. SQLGetTypeInfo() の SQLSTATE
SQLSTATE 説明 説明
08S01 通信リンクに障害が起きました。 関数が完了する前に、アプリケーションとデータ・ソース間の 通信リンクで障害が発生しました。
24000 カーソル状態が無効です。 ステートメント・ハンドルでカーソルがオープン状態です。
HY001 メモリーの割り振りに失敗しました。 Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。
HY004 SQL データ・タイプが無効です。 引数 fSqlType に無効な値が指定されています。
HY010 関数シーケンス・エラーが発生しました。 この関数は、実行時データの操作時に呼び出されました。(すなわち、SQLParamData() または SQLPutData() 関数を使用するプロシージャー実行中に関数が呼び出されました。)

制約事項

以下の ODBC 指定の SQL データ・タイプ (および対応 する fSqlType 定義値) は、IBM® リレーショナル・データベース管理システムではサポートされていません。
データ・タイプ
fSqlType
TINYINT
SQL_TINYINT
BIT
SQL_BIT

例

以下の例 は、SQLGetTypeInfo() を使用して、データベース管理システムが サポートする ODBC データ・タイプをチェックするアプリケーションを示しています。
図 1. 現行のサーバーがサポートするデータ・タイプをチェックするアプリケーション
 /******************************************************************/
 /*  Invoke SQLGetTypeInfo to retrieve SQL data types supported.   */
 /******************************************************************/
#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include <sqlca.h>
#include "sqlcli1.h"
  /******************************************************************/
  /* Invoke SQLGetTypeInfo to retrieve all SQL data types supported */
  /* by data source.                                                */
  /******************************************************************/
int main( )
{
   SQLHENV         hEnv    = SQL_NULL_HENV;
   SQLHDBC         hDbc    = SQL_NULL_HDBC;
   SQLHSTMT        hStmt   = SQL_NULL_HSTMT;
   SQLRETURN       rc      = SQL_SUCCESS;
   SQLINTEGER      RETCODE = 0;
   (void) printf ("**** Entering CLIP06.¥n¥n");
  /*****************************************************************/
  /* Allocate environment handle                                   */
  /*****************************************************************/
   RETCODE = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &hEnv);
   if (RETCODE != SQL_SUCCESS)
     goto dberror;
  /*****************************************************************/
  /* Allocate connection handle to DSN                             */
  /*****************************************************************/
   RETCODE = SQLAllocHandle(SQL_HANDLE_DBC, hEnv, &hDbc);
   if( RETCODE != SQL_SUCCESS )      // Could not get a Connect Handle
     goto dberror;
  /*****************************************************************/
  /* CONNECT TO data source (STLEC1)                               */
  /*****************************************************************/
   RETCODE = SQLConnect(hDbc,        // Connect handle
                        (SQLCHAR *) "STLEC1", // DSN
                        SQL_NTS,     // DSN is nul-terminated
                        NULL,        // Null UID
                        0   ,
                        NULL,        // Null Auth string
                        0);
   if( RETCODE != SQL_SUCCESS )      // Connect failed
     goto dberror;
  /*****************************************************************/
  /* Retrieve SQL data types from DSN                              */
  /*****************************************************************/
  // local variables to Bind to retrieve TYPE_NAME, DATA_TYPE,
  // COLUMN_SIZE and NULLABLE
   struct                    // TYPE_NAME is VARCHAR(128)
   {
     SQLSMALLINT  length;
     SQLCHAR      name [128];
     SQLINTEGER   ind;
   } typename;
   SQLSMALLINT data_type;    // DATA_TYPE is SMALLINT
   SQLINTEGER  data_type_ind;
   SQLINTEGER  column_size;  // COLUMN_SIZE is integer
   SQLINTEGER  column_size_ind;
   SQLSMALLINT nullable;     // NULLABLE is SMALLINT
   SQLINTEGER  nullable_ind;
  /*****************************************************************/
  /* Allocate statement handle                                     */
  /*****************************************************************/
   rc = SQLAllocHandle(SQL_HANDLE_STMT, hDbc, &hStmt);
   if (rc != SQL_SUCCESS)
     goto exit;
  /*****************************************************************/
  /*                                                               */
  /* Retrieve native SQL types from DSN ------------>              */
  /*                                                               */
  /*  The result set consists of 15 columns. We only bind          */
  /*  TYPE_NAME, DATA_TYPE, COLUMN_SIZE and NULLABLE. Note: Need   */
  /*  not bind all columns of result set -- only those required.   */
  /*                                                               */
  /*****************************************************************/
   rc = SQLGetTypeInfo (hStmt,
                        SQL_ALL_TYPES);
   if (rc != SQL_SUCCESS)
     goto exit;
   rc = SQLBindCol (hStmt,           // bind TYPE_NAME
                    1,
                    SQL_CHAR,
                    (SQLPOINTER) typename.name,
                    128,
                    &typename.ind);
   if (rc != SQL_SUCCESS)
     goto exit;
   rc = SQLBindCol (hStmt,           // bind DATA_NAME
                    2,
                    SQL_C_DEFAULT,
                    (SQLPOINTER) &data_type,
                    sizeof(data_type),
                    &data_type_ind);
   if (rc != SQL_SUCCESS)
     goto exit;rc = SQLBindCol (hStmt,           // bind COLUMN_SIZE
                    3,
                    SQL_C_DEFAULT,
                    (SQLPOINTER) &column_size,
                    sizeof(column_size),
                    &column_size_ind);
   if (rc != SQL_SUCCESS)
     goto exit;
   rc = SQLBindCol (hStmt,           // bind NULLABLE
                    7,
                    SQL_C_DEFAULT,
                    (SQLPOINTER) &nullable,
                    sizeof(nullable),
                    &nullable_ind);
   if (rc != SQL_SUCCESS)
     goto exit;
  /*****************************************************************/
  /* Fetch all native DSN SQL Types and print Type Name, Type,     */
  /* Precision and nullability.                                    */
  /*****************************************************************/
   while ((rc = SQLFetch (hStmt)) == SQL_SUCCESS)
   {
     (void) printf ("**** Type Name is %s. Type is %d. Precision is %d.",
                    typename.name,
                    data_type,
                    column_size);
     if (nullable == SQL_NULLABLE)
       (void) printf (" Type is nullable.¥n");
     else
       (void) printf (" Type is not nullable.¥n");
   }
   if (rc == SQL_NO_DATA_FOUND)   // if result set exhausted reset
     rc = SQL_SUCCESS;            // rc to OK
  /*****************************************************************/
  /* Free statement handle                                         */
  /*****************************************************************/
   rc = SQLFreeHandle(SQL_HANDLE_STMT, hStmt);
   if (RETCODE != SQL_SUCCESS)       // An advertised API failed
     goto dberror;
  /*****************************************************************/
  /* DISCONNECT from data source                                   */
  /*****************************************************************/
   RETCODE = SQLDisconnect(hDbc);
   if (RETCODE != SQL_SUCCESS)
     goto dberror;
  /*****************************************************************/
  /* Deallocate connection handle                                  */
  /*****************************************************************/
   RETCODE = SQLFreeHandle(SQL_HANDLE_DBC, hDbc);
   if (RETCODE != SQL_SUCCESS)
     goto dberror;
   /*****************************************************************/
  /* Free environment handle                                       */
  /*****************************************************************/
   RETCODE = SQLFreeHandle(SQL_HANDLE_ENV, hEnv);
   if (RETCODE == SQL_SUCCESS)
     goto exit;
     dberror:
     RETCODE=12;
     exit:
     (void) printf ("**** Exiting  CLIP06.¥n¥n");
     return(RETCODE);
}