SQLProcedureColumns() - プロシージャー入出力パラメーター情報を取得する

SQLProcedureColumns() は、プロシージャーに関連した入出力パラメーターのリストを戻します。情報は、SQL 結果セットとして戻されます。 この結果セットは、 照会で生成される結果セットを処理するのと同じ関数を使用して、取り出すことができます。

SQLProcedureColumns() の ODBC 仕様

表 1. SQLProcedureColumns() の仕様
ODBC 仕様レベル X/Open CLI CAE 仕様 ISO CLI 仕様
1.0 なし なし

構文

SQLRETURN   SQLProcedureColumns (
                              SQLHSTMT          hstmt,
                              SQLCHAR      FAR  *szProcCatalog,
                              SQLSMALLINT       cbProcCatalog,
                              SQLCHAR      FAR  *szProcSchema,
                              SQLSMALLINT       cbProcSchema,
                              SQLCHAR      FAR  *szProcName,
                              SQLSMALLINT       cbProcName,
                              SQLCHAR      FAR  *szColumnName,
                              SQLSMALLINT       cbColumnName);

関数の引数

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

表 2. SQLProcedureColumns() の引数
データ・タイプ 引数 使用法 説明
SQLHSTMT hstmt 入力 ステートメント・ハンドル。
SQLCHAR * szProcCatalog 入力 3 部構成のプロシージャー名のカタログ修飾子。

これは、NULL ポインターまたは長さゼロのストリングでなければなりません。

SQLSMALLINT cbProcCatalog 入力 szProcCatalog の長さ (バイト)。これは、0 に設定する必要があります。
SQLCHAR * szProcSchema 入力 スキーマ名で結果セットを修飾するためのパターン値 を入れることができるバッファー。

結果セットをスキーマ名で修飾しない場合は、この引数に対しては NULL ポインターまたは長さゼロのストリングを使用してください。

SQLSMALLINT cbProcSchema 入力 szProcSchema の長さ (バイト)。
SQLCHAR * szProcName 入力 プロシージャー名で結果セットを修飾する ためのパターン値 を入れることができるバッファー。

結果セットをプロシージャー名で修飾しない場合は、この引数に対して NULL ポインターまたは長さゼロのストリングを使用してください。

SQLSMALLINT cbProcName 入力 szProcName の長さ (バイト)。
SQLCHAR * szColumnName 入力 パラメーター名で結果セットを修飾する ためのパターン値 を入れることができるバッファー。 この引数は、szProcName あるいは szProcSchema (または、その両方) に対して 空でない値を指定することの制約を既に受けている結果セットをさらに修飾するために使用します。

結果セットをパラメーター名で修飾する必要がない場合は、この引数で NULL ポインターまたは長さゼロのストリングを使用してください。

SQLSMALLINT cbColumnName 入力 szColumnName の長さ (バイト)。

使用法

登録済みストアード・プロシージャーを SYSIBM.SYSROUTINES カタログ表に 定義します。ストアード・プロシージャー・カタログの機能を提供しない サーバーでは、空の結果セットが戻されます。

Db2® ODBC は、ストアード・プロシージャーに関連した入力パラメーター、 入出力パラメーター、および出力パラメーターの情報を戻しますが、 戻された結果セットの記述子情報についての情報を戻すことはできません。

SQLProcedureColumns() は、PROCEDURE_CAT、PROCEDURE_SCHEM、 PROCEDURE_NAME、および COLUMN_TYPE の順序で、結果セットに入れて情報を戻します。表 3 には、結 果セットにある列の一覧を記載してあります。

多くの場合、SQLProcedureColumns() への呼び出しは、システム・カタログに対する複雑な (したがって、 コストのかかる) 照会にマップされることになるため、慎重に使用し、呼び出しを繰り返さずに、 結果を保管するようにしてください。

カタログ関数の結果セットの VARCHAR 列は、128 バイトの最大長属性で宣言されて おり、ANSI/ISO SQL 規格 (1992) の制限との整合性があります。Db2 名は 128 バイトより短いため、アプリケーションでは 常に 128 バイト (加えて、NUL 終止符) を出力バッファーに取っておくように選択できます。あるいは、引数 InfoType を以下のそれぞれの値に 設定して、SQLGetInfo() を呼び出すこともできます。
  • 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 列の長さを判別

アプリケーションでは、将来のリリースで最終列以降の列が定義される 可能性があることを認識しておく必要があります。 将来のリリースでは、列が新たに追加されたり、既存の列の名前が 変更される可能性はありますが、現行の列の位置が変更になることはありま せん。次の表は、これらの列を示しています。

表 3. SQLProcedureColumns() によって戻される列
列番号 列名 データ・タイプ 説明
1   PROCEDURE_CAT VARCHAR(128) このフィールドは常に NULL です。
2   PROCEDURE_SCHEM VARCHAR(128) PROCEDURE_NAME を含むスキーマの 名前。(Db2 for z/OS® SQLProcedureColumns() の結果セットの場合、これも NULL です。)
3   PROCEDURE_NAME VARCHAR(128) プロシージャーの名前。
4   COLUMN_NAME VARCHAR(128) パラメーターの名前。
5   COLUMN_TYPE SMALLINT NOT NULL この行に関連したタイプ情報を識別します。 値は、以下のとおりです。
  • SQL_PARAM_TYPE_UNKNOWN: パラメーター・タイプは不明です。1
  • SQL_PARAM_INPUT : このパラメーターは入力パラメーターです。
  • SQL_PARAM_INPUT_OUTPUT : このパラメーターは入出力パラメーターです。
  • SQL_PARAM_OUTPUT : このパラメーターは出力パラメーターです。
  • SQL_RETURN_VALUE: プロシージャー列は、プロシージャーの戻り値です。1
  • SQL_RESULT_COL: このパラメーターは、実際には結果セットの列です。1

    要件: SQL_PARAM_OUTPUT および SQL_RETURN_VALUE サポートの場合、ODBC 2.0 以上 が必要です。

6   DATA_TYPE SMALLINT NOT NULL SQL データ・タイプ。
7   TYPE_NAME VARCHAR(128) NOT NULL DATA_TYPE に対応するデータ・タイプの名前を表す文字ストリング。
8   COLUMN_SIZE INTEGER DATA_TYPE 列の値が文字ストリングまたはバイナリー・ストリングであることを示す場合、 この列にはバイト単位の最大長が入っています。 グラフィック (DBCS) ストリングの場合は、パラメーターの 2 バイト文字の数です。

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

数値データ・タイプの場合、これは、結果セットの NUM_PREC_RADIX 列の値によって異なり、 列で可能な桁の総数またはビットの総数のいずれかです。

ネイティブ SQL プロシージャー内の XML データ・タイプの場合、ゼロが返されます (XML データ・タイプに長さはありません)。

9   BUFFER_LENGTH INTEGER SQL_C_DEFAULT が SQLBindCol()、SQLGetData()、および SQLBindParameter() 呼び出しで指定された場合、このパラメーターからのデータを保管するための関連する C バッファーの最大バイト数。 この長さには、NUL 終止符はいずれも含まれていません。 正確な数値データ・タイプの場合、小数点と符号も長さに数えられます。

ネイティブ SQL プロシージャー内の XML データ・タイプの場合、ゼロが返されます (XML データ・タイプに長さはありません)。

10   DECIMAL_DIGITS SMALLINT パラメーターの位取り。位取りが適用できないデータ・タイプの場合は NULL が戻されます。
11   NUM_PREC_RADIX SMALLINT 10、2、または NULL の いずれか。DATA_TYPE が近似の数値データ・タイプである場合、 この列には値 2 が含まれており、COLUMN_SIZE 列にはそのパラメーターで 許されているビット数が含まれています。

DATA_TYPE が正確な数値データ・タイプの場合、この列には値 10 が 含まれており、COLUMN_SIZE 列と DECIMAL_DIGITS 列にはそのパラメーターに 許されている小数桁数が含まれています。

数値データ・タイプの場合、データベース管理システムは 10 もしくは 2 の NUM_PREC_RADIX を 戻すことができます。

基数が適用できないデータ・タイプの場合は NULL が戻されます。

12   NULLABLE SMALLINT NOT NULL パラメーターが NULL 値を受け入れない場合は SQL_NO_NULLS。

パラメーターが NULL 値を受け入れる場合は SQL_NULLABLE。

13   REMARKS VARCHAR(254) パラメーターに関する記述情報が入ります。
14   COLUMN_DEF VARCHAR(254) 列のデフォルト値。 デフォルト値が何であるかによって、次の ように異なります。
  • デフォルト値が数値リテラルの場合、この列には単一引用符で 囲まれていない数値リテラルの文字表記が含まれています。
  • 文字ストリングの場合、この列は単一引用符で囲まれた ストリングです。
  • デフォルト値が DATE、TIME、および TIMESTAMP 列などの疑似リテラル の場合、この列には、単一引用符で囲まれていない疑似リテラ ルのキーワード (例えば、CURRENT DATE) が入ります。
  • NULL の場合、この列は、単一引用符で囲ま れていない NULL を戻します。

切り捨てなしではデフォルト値を表すことができない場合、この列に は単一引用符で囲まれていない TRUNCATED が入ります。 デフォルト値が指定されていない場合、 この列は NULL です。

15   SQL_DATA_TYPE SMALLINT NOT NULL SQL データ・タイプ。 この列は、DATA_TYPE 列と同じです。 日時データ・タイプの場合、 結果セット内の SQL_DATA_TYPE フィールドは SQL_DATETIME であり、SQL_DATETIME_SUB フィールドは、 特定の日時データ・タイプのサブコード (SQL_CODE_DATE、SQL_CODE_TIME または SQL_CODE_TIMESTAMP) を 戻します。
16   SQL_DATETIME_SUB SMALLINT 日時データ・タイプのサブタイプ・コード :
  • SQL_CODE_DATE
  • SQL_CODE_TIME
  • SQL_CODE_TIMESTAMP
その他のデータ・タイプに対してはすべて、この列は NULL 値を戻します。
17   CHAR_OCTET_LENGTH INTEGER 文字データ・タイプ列の最大長 (バイト単位)。 ネイティブ SQL プロシージャー内の XML データ・タイプの場合、ゼロが返されます (XML データ・タイプに長さはありません)。 その他のすべてのデータ・タイプに対して、この列はヌル値を返します。
18  ORDINAL_POSITION INTEGER NOT NULL この結果セット内の COLUMN_NAME によって示されたパラメーターの順序を表す位置が 含まれます。これは、CALL ステートメントで提供される引数の順序を表す位置です。 左端の引数の順序を表す位置は 1 です。
19   IS_NULLABLE VARCHAR(128) 次のいずれかです。
  • "NO" (列が NULL 値を含まない場合)
  • "YES" (列が NULL 値を含む可能性がある場合)
  • 長さゼロのストリング (NULL 可能かどうか不明の場合)
この列に戻される値は、NULLABLE 列に戻される値とは異なります。 (NULLABLE 列の説明を参照してください)
注:
  1. これの値は戻されません。

Db2 ODBC が使用する列名は、X/Open CLI CAE 仕様のスタイルに準拠しています。列タイプ、内容、および順序は、ODBC の SQLProcedureColumns() 結果セット で定義されているものと同じです。

戻りコード

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

診断

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

表 4. SQLProcedureColumns() の SQLSTATE
SQLSTATE 説明 説明
08S01 通信リンクに障害が起きました。 関数が完了する前に、アプリケーションとデータ・ソース間の 通信リンクで障害が発生しました。
24000 カーソル状態が無効です。 カーソルはステートメント・ハンドルでオープンしています。
42601 PARMLIST 構文エラーが発生しました。 ストアード・プロシージャーのカタログ表の PARMLIST 値には、 構文エラーが含まれています。
HY001 メモリーの割り振りに失敗しました。 Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。
HY010 関数シーケンス・エラーが発生しました。 この関数は、実行時データの操作時に呼び出されました。(すなわち、SQLParamData() または SQLPutData() 関数を使用するプロシージャー実行中に関数が呼び出されました。)
HY014 これ以上ハンドルがありません。 Db2 ODBC は、内部リソースが少ないためにハンドルを割り振ることができません。
HY090 ストリングまたはバッファーの長さが無効です。 名前の長さ引数のうちの 1 つの値は 0 より小さい値でしたが、SQL_NTS と 等しくありません。
HYC00 ドライバーは使用できません。 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
  • Db2 ODBC は、プロシージャー名の修飾子として catalog をサポートしません。
  • 接続されているサーバーは、プロシージャー名の修飾子 としてスキーマ をサポートしていません。

制約事項

SQLProcedureColumns() は、ストアード・プロシージャーが 戻す可能性のある結果セットの属性についての情報は戻しません。

アプリケーションが、ストアード・プロシージャーに対するサポート またはストアード・プロシージャー・カタログに対するサポートを提供 しない Db2 サーバーに接続されている場合、SQLProcedureColumns() は空の結果セットを戻します。

例

以下の例 は、プロシージャーに関連した入力、入出力、 および出力パラメーターを取り出すアプリケーションを示しています。
図 1. プロシージャー関連のパラメーターを取り出すアプリケーション
 /******************************************************************/
 /*  Invoke SQLProcedureColumns and enumerate all rows retrieved.  */
 /******************************************************************/
#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include <sqlca.h>
#include "sqlcli1.h"
int main( )
{
   SQLHENV         hEnv    = SQL_NULL_HENV;
   SQLHDBC         hDbc    = SQL_NULL_HDBC;
   SQLHSTMT        hStmt   = SQL_NULL_HSTMT;
   SQLRETURN       rc      = SQL_SUCCESS;
   SQLINTEGER      RETCODE = 0;
   char            *pDSN = "STLEC1";
   char            procedure_name [20];
   char            parameter_name [20];
   char            ptype          [20];
   SQLSMALLINT     parameter_type = 0;
   SQLSMALLINT     data_type = 0;
   char            type_name      [20];
   SWORD           cbCursor;
   SDWORD          cbValue3;
   SDWORD          cbValue4;
   SDWORD          cbValue5;
   SDWORD          cbValue6;
   SDWORD          cbValue7;
   char            ProcCatalog [20] = {0};
   char            ProcSchema  [20] = {0};
   char            ProcName    [20] = {"DOIT
   char            ColumnName  [20] = {"P
   SQLSMALLINT     cbProcCatalog = 0;
   SQLSMALLINT     cbProcSchema  = 0;
   SQLSMALLINT     cbProcName    = strlen(ProcName);
   SQLSMALLINT     cbColumnName  = strlen(ColumnName);
 
   (void) printf ("**** Entering CLIP12.¥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 *) pDSN, // DSN
                        SQL_NTS,     // DSN is nul-terminated
                        NULL,        // Null UID
                        0   ,
                        NULL,        // Null Auth string
                        0);
   if( RETCODE != SQL_SUCCESS )      // Connect failed
     goto dberror;
  /*****************************************************************/
  /* Allocate statement handles                                    */
  /*****************************************************************/
  rc = SQLAllocHandle(SQL_HANDLE_STMT, hDbc, &hStmt);
  if (rc != SQL_SUCCESS)
    goto exit;
  /*****************************************************************/
  /* Invoke SQLProcedureColumns and retrieve all rows within       */
  /* answer set.                                                   */
  /*****************************************************************/
  rc = SQLProcedureColumns (hStmt                  ,
                            (SQLCHAR *) ProcCatalog,
                            cbProcCatalog          ,
                            (SQLCHAR *) ProcSchema ,
                            cbProcSchema           ,
                            (SQLCHAR *) ProcName   ,
                            cbProcName             ,
                            (SQLCHAR *) ColumnName ,
                            cbColumnName);

  if (rc != SQL_SUCCESS)
  {
    (void) printf ("**** SQLProcedureColumns Failed.¥n");
    goto dberror;
  }
  rc = SQLBindCol (hStmt,           // bind procedure_name
                   3,
                   SQL_C_CHAR,
                   procedure_name,
                   sizeof(procedure_name),
                   &cbValue3);
  if (rc != SQL_SUCCESS)
  {
    (void) printf ("**** Bind of procedure_name Failed.¥n");
    goto dberror;
  }
  rc = SQLBindCol (hStmt,           // bind parameter_name
                   4,
                   SQL_C_CHAR,
                   parameter_name,
                   sizeof(parameter_name),
                   &cbValue4);
  if (rc != SQL_SUCCESS)
  {
    (void) printf ("**** Bind of parameter_name Failed.¥n");
    goto dberror;
  }
  rc = SQLBindCol (hStmt,           // bind parameter_type
                   5,
                   SQL_C_SHORT,
                   &parameter_type,
                   0,
                   &cbValue5);
  if (rc != SQL_SUCCESS)
  {
    (void) printf ("**** Bind of parameter_type Failed.¥n");
    goto dberror;
  }
  rc = SQLBindCol (hStmt,           // bind SQL data type
                   6,
                   SQL_C_SHORT,
                   &data_type,
                   0,
                   &cbValue6);
  if (rc != SQL_SUCCESS)
  {
    (void) printf ("**** Bind of data_type Failed.¥n");
    goto dberror;
  }
  rc = SQLBindCol (hStmt,           // bind type_name
                   7,
                   SQL_C_CHAR,
                   type_name,
                   sizeof(type_name),
                   &cbValue7);
  if (rc != SQL_SUCCESS)
  {
    (void) printf ("**** Bind of type_name Failed.¥n");
    goto dberror;
  }
  /*****************************************************************/
  /* Answer set is available - Fetch rows and print parameters for */
  /* all procedures.                                               */
  /*****************************************************************/
  while ((rc = SQLFetch (hStmt)) == SQL_SUCCESS)
  {
    (void) printf ("**** Procedure Name = %s. Parameter %s",
                   procedure_name,
                   parameter_name);
    switch (parameter_type)
    {
      case SQL_PARAM_INPUT        :
        (void) strcpy (ptype, "INPUT");
        break;
      case SQL_PARAM_OUTPUT       :
        (void) strcpy (ptype, "OUTPUT");
        break;
      case SQL_PARAM_INPUT_OUTPUT :
        (void) strcpy (ptype, "INPUT/OUTPUT");
        break;
      default                     :
        (void) strcpy (ptype, "UNKNOWN");
        break;
    }
    (void) printf (" is %s. Data Type is %d. Type Name is %s.¥n",
                   ptype     ,
                   data_type ,
                   type_name);
  }
  /*****************************************************************/
  /* Deallocate statement handles -- statement is no longer in a   */
  /* prepared state.                                               */
  /*****************************************************************/
  rc = SQLFreeHandle(SQL_HANDLE_STMT, hStmt);
  /*****************************************************************/
  /* 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  CLIP12.¥n¥n");
   return RETCODE;
}