SQLProcedures() - プロシージャー名のリストを取得する

SQLProcedures() は、サーバーに登録されているプロシージャー名リストから、指定した 検索パターンと一致するもののリストを戻します。情報は、SQL 結果セットとして戻されます。 この結果セットは、 照会で生成される結果セットを処理するのと同じ関数を使用して、取り出すことができます。

SQLProcedures() の ODBC 仕様

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

構文

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

関数の引数

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

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

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

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

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

SQLSMALLINT cbProcSchema 入力 szProcSchema の長さ (バイト)。
SQLCHAR * szProcName 入力 表名によって結果セットを修飾するパターン値 を入れることができるバッファー。

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

SQLSMALLINT cbProcName 入力 szProcName の長さ (バイト)。

使用法

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

SQLProcedures() から戻された結果セットには、表 3 にリスト されている列が、示されている順序で入っています。 行は、PROCEDURE_CAT、 PROCEDURE_SCHEM、および PROCEDURE_NAME の順序になります。

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

カタログ関数の結果セットの 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 列の長さを判別

将来のリリースでは、列が新たに追加されたり、既存の列の名前が 変更される可能性はありますが、現行の列の位置が変更になることはありま せん。表 4 は、これらの列を示しています。

表 3. SQLProcedures() によって戻される列
列番号 列名 データ・タイプ 説明
1 PROCEDURE_CAT VARCHAR(128) これは常に NULL です。
2 PROCEDURE_SCHEM VARCHAR(128) PROCEDURE_NAME を含むスキーマの名前。
3 PROCEDURE_NAME VARCHAR(128) NOT NULL プロシージャーの名前。
4 NUM_INPUT_PARAMS INTEGER NOT NULL 入力パラメーター数。
5 NUM_OUTPUT_PARAMS INTEGER NOT NULL 出力パラメーター数。
6 NUM_RESULT_SETS INTEGER NOT NULL プロシージャーから戻される結果セット数。
7 REMARKS VARCHAR(254) プロシージャーに関する記述情報が含まれています。
8 PROCEDURE_TYPE SMALLINT プロシージャー・タイプを、以下のように定義します。
  • SQL_PT_UNKNOWN: プロシージャーが値を戻すかどうかを判別することは できません。
  • SQL_PT_PROCEDURE: 戻されるオブジェクトはプロシージャーです。つまり、 そのオブジェクトには戻り値がありません。
  • SQL_PT_FUNCTION: 戻されるオブジェクトは関数です。つまり、 そのオブジェクトには戻り値があります。
Db2 ODBC は常に SQL_PT_PROCEDURE を戻します。

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

戻りコード

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

診断

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

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

制約事項

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

例

以下の例は、サーバーに登録済みのプロシージャーのリストを 印刷するアプリケーションを示しています。 アプリケーションは、SQLProcedures() を使用して、これらのプロシージャーの取り出し、および検索パターンの設定を行います。
図 1. 登録済みプロシージャーのリストを印刷するアプリケーション
/* ... */
    printf("Enter Procedure Schema Name Search Pattern:¥n");
    gets(proc_schem.s);
    rc = SQLProcedures(hstmt, NULL, 0, proc_schem.s, SQL_NTS, "NTS);
    rc = SQLBindCol(hstmt, 2, SQL_C_CHAR, (SQLPOINTER) proc_schem.s, 129,
                    &proc_schem.ind);
    rc = SQLBindCol(hstmt, 3, SQL_C_CHAR, (SQLPOINTER) proc_name.s, 129,
                    &proc_name.ind);
    rc = SQLBindCol(hstmt, 7, SQL_C_CHAR, (SQLPOINTER) remarks.s, 255,
                    &remarks.ind);
    printf("PROCEDURE SCHEMA          PROCEDURE NAME            ¥n");
    printf("------------------------- ------------------------- ¥n");
    /* Fetch each row, and display */
    while ((rc = SQLFetch(hstmt)) == SQL_SUCCESS) {
        printf("schem.s, proc_name.s);
        if (remarks.ind != SQL_NULL_DATA) {
            printf("  (Remarks) 
        }
    }                           /* endwhile */
/* ... */