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 input ステートメント・ハンドル。
SQLCHAR * szProcCatalog input 3 部構成のプロシージャー名のカタログ修飾子。

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

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

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

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

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

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

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

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

使用法

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

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

SQLProcedureColumns() は、PROCEDURE_CAT、PROCEDURE_SCHEM、 PROCEDURE_NAME、および COLUMN_TYPE の順序で、結果セットに入れて情報を戻します。 表3は、結果セットの列をリストアップしています。

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

カタログ関数の結果セットのVARCHAR列は、 1992年のANSI/ISO SQL標準の制限と一致させるため、最大長属性を128バイトとして宣言されています。 Db2 名は 128 バイト未満であるため、アプリケーションは、出力バッファー用に常に 128 バイト (および NUL 終止符) を別に確保するよう選択できます。 または、 SQLGetInfo()InfoType 引数を以下の各値に設定して呼び出すこともできます
  • 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 SQLBindCol()呼び出し、 SQLGetData() 呼び出し、および SQLBindParameter() 呼び出しで SQL_C_DEFAULT が指定されている場合に、このパラメーターからのデータを保管するための関連 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) 以下のいずれか 1 つです。
  • "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 と 等しくありません。
HYC0 0 ドライバーは使用できません。 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
  • Db2 ODBC は、プロシージャー名の修飾子としてカタログをサポートしていません。
  • 接続されているサーバーは、プロシージャー名の修飾子 としてスキーマ をサポートしていません。

制約事項

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;
}