SQLProcedureColumns 関数 (CLI) - プロシージャーの入出力パラメーター情報の取得
仕様:
- CLI 2.1
- ODBC 1.0
構文
SQLRETURN SQLProcedureColumns(
SQLHSTMT StatementHandle, /* hstmt */
SQLCHAR *CatalogName, /* szProcCatalog */
SQLSMALLINT NameLength1, /* cbProcCatalog */
SQLCHAR *SchemaName, /* szProcSchema */
SQLSMALLINT NameLength2, /* cbProcSchema */
SQLCHAR *ProcName, /* szProcName */
SQLSMALLINT NameLength3, /* cbProcName */
SQLCHAR *ColumnName, /* szColumnName */
SQLSMALLINT NameLength4); /* cbColumnName */
関数引数
データ・タイプ | 引数 | 使用法 | 説明 |
---|---|---|---|
SQLHSTMT | StatementHandle | 入力 | ステートメント・ハンドル。 |
SQLCHAR * | CatalogName | 入力 | 3 つの部分から成る表名のカタログ修飾子。ターゲットの DBMS が 3 つの部分から成る名前をサポートしておらず、かつ CatalogName が NULL ポインターでなく、長さ 0 のストリングを指していない場合は、空の結果セットと SQL_SUCCESS が戻されます。それ以外の場合、これは、3 パート・ネーミングをサポートする DBMS の有効なフィルターです。 |
SQLSMALLINT | NameLength1 | 入力 | CatalogName を格納するのに必要な SQLCHAR エレメント (またはこの関数の Unicode 版の場合は SQLWCHAR エレメント) の数、または CatalogName がヌル終了ストリングの場合は SQL_NTS。 |
SQLCHAR * | SchemaName | 入力 | スキーマ名で結果セットを修飾するための パターン値 が入れられるバッファー。 DB2® for z/OS® の場合、ストアード・プロシージャーは 1 つのスキーマにあります。SchemaName 引数の唯一の受け入れ可能な値は NULL ポインターです。値を指定しても、空の結果セットと SQL_SUCCESS が戻されます。 DB2 for Linux, UNIX, and Windows の場合、SchemaName には有効なパターン値を入れることができます。 有効な検索パターンの詳細は、カタログ関数の入力引数の項を参照してください。 |
SQLSMALLINT | NameLength2 | 入力 | SchemaName を格納するのに必要な SQLCHAR エレメント (またはこの関数の Unicode 版の場合は SQLWCHAR エレメント) の数、または SchemaName がヌル終了ストリングの場合は SQL_NTS。 |
SQLCHAR * | ProcName | 入力 | プロシージャー名で結果セットを修飾するための パターン値 が入れられるバッファー。 |
SQLSMALLINT | NameLength3 | 入力 | ProcName を格納するのに必要な SQLCHAR エレメント (またはこの関数の Unicode 版の場合は SQLWCHAR エレメント) の数、または ProcName がヌル終了ストリングの場合は SQL_NTS。 |
SQLCHAR * | ColumnName | 入力 | パラメーター名で結果セットを修飾するための パターン値 が入れられるバッファー。この引数を使用するのは、 ProcName、SchemaName、またはその両方に空でない値を指定することによって既に限定されている結果セットをさらに修飾する場合です。 |
SQLSMALLINT | NameLength4 | 入力 | ColumnName を格納するのに必要な SQLCHAR エレメント (またはこの関数の Unicode 版の場合は SQLWCHAR エレメント) の数、または ColumnName がヌル終了ストリングの場合は SQL_NTS。 |
使用法
SQLProcedureColumns() 関数は、 PROCEDURE_CAT、 PROCEDURE_SCHEM、 PROCEDURE_NAME、および COLUMN_TYPE の順序で結果セット内の情報を戻します。SQLProcedureColumns で戻される列は、結果セット内の列をリストしています。
多くの場合に SQLProcedureColumns() 関数の呼び出しはシステム・カタログに対する複雑な (したがってコストのかかる) 照会にマッピングされるため、それらの呼び出しの使用回数を少なくし、呼び出しを繰り返すのではなく結果を保存するようにしてください。
SQL_MAX_CATALOG_NAME_LEN、SQL_MAX_SCHEMA_NAME_LEN、および SQL_MAX_COLUMN_NAME_LEN を指定した SQLGetInfo() を呼び出して、接続先の DBMS でサポートされている TABLE_CAT、TABLE_SCHEM、および COLUMN_NAME 列の実際の長さを判別することができます。
SQL_ATTR_LONGDATA_COMPAT 接続属性が設定されている場合、LOB 列タイプは LONG VARCHAR、LONG VARBINARY、または LONG VARGRAPHIC タイプとして報告されます。
将来のリリースでは、列が新たに追加されたり、 既存の列の名前が変更されたりする可能性はありますが、 現行の列の位置が変更されることはありません。
ストアード・プロシージャーが DB2 for z/OS サーバーにある場合、そのストアード・プロシージャーの名前をサーバーの SYSIBM.SYSPROCEDURES カタログ表に登録しなければなりません。V8 およびそれ以降のサーバーの場合、そのサーバーの SYSIBM.SYSROUTINES および SYSIBM.SYSPARAMS カタログ表にストアード・プロシージャーを登録しなければなりません。
ストアード・プロシージャー・カタログの機能を提供しない他の DB2 サーバーのバージョンでは、空の結果セットが戻されます。
CLI は、ストアード・プロシージャーに関連した入力、入出力および出力パラメーターに関する情報を戻しますが、ストアード・プロシージャーから戻される可能性のある結果セットに関する記述子情報を戻すことはできません。
SchemaName に値として *ALL を指定することで、非修飾ストアード・プロシージャー呼び出しの解決、およびカタログ API 呼び出しによるライブラリー検索が可能になります。CLI は接続されたデータベースですべての既存のスキーマを検索します。この動作は、CLI のデフォルトであるため、*ALL を指定する必要はありません。 また、SchemaFilter IBM® Data Server Driver 構成キーワードまたは Schema List CLI/ODBC 構成キーワードを *ALL に設定することもできます。
- 列 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 非 NULL)
- この行に関連した情報のタイプを識別します。戻される値は以下のとおりです。
- SQL_PARAM_INPUT は入力パラメーターです。
- SQL_PARAM_INPUT_OUTPUT は入出力パラメーターです。
- SQL_PARAM_OUTPUT は出力パラメーターです。
- ODBC 仕様で定義されていても戻されない値は以下のとおりです。
- SQL_PARAM_TYPE_UNKNOWN : パラメーター・タイプが不明です。
- SQL_RETURN_VALUE はプロシージャー列内のプロシージャーの戻り値です。
- SQL_RESULT_COL は、結果セット内の列です。
- 列 6 DATA_TYPE (SMALLINT 非 NULL)
- SQL データ・タイプ。
- 列 7 TYPE_NAME (VARCHAR(128) 非 NULL)
- DATA_TYPE に対応するデータ・タイプの名前を表す文字ストリング。
- 列 8 COLUMN_SIZE (INTEGER)
- SQL ルーチン内の XML 引数の場合、(XML 引数には長さがないため) ゼロが戻されます。
しかし、カタログ式外部ルーチンの場合、XML パラメーターは XML AS CLOB(n) として宣言されます。この場合、COLUMN_SIZE はカタログされた長さ、n です。
DATA_TYPE 列の値が文字ストリングまたはバイナリー・ストリングを示す場合、この列には SQLCHAR または SQLWCHAR エレメント数で表記した最大長が入れられます。DATA_TYPE 列の値が GRAPHIC (DBCS) ストリングの場合、COLUMN_SIZE はパラメーターの 2 バイトの SQLCHAR エレメントまたは SQLWCHAR エレメントの数になります。
日付、時刻、およびタイム・スタンプのデータ・タイプの場合は、文字データ・タイプに変換された場合に値を表示するために必要な SQLCHAR エレメントまたは SQLWCHAR エレメントの数の合計です。
CODEUNITS32 単位で定義された列では、列のコード単位の数が返されます。
数値データ・タイプの場合、COLUMN_SIZE 値は結果セット内の NUM_PREC_RADIX 列の値に基づいて、列に許可されている総桁数または合計ビット数のいずれかです。
データ・タイプ精度の表を参照してください。
- 列 9 BUFFER_LENGTH (INTEGER)
- SQL_C_DEFAULT が SQLBindCol()、SQLGetData() および SQLBindParameter() 呼び出しで指定された場合に、このパラメーターからのデータを保管するための関連する C バッファーの最大バイト。この長さには、NULL 終止符は含まれません。
厳密な数データ・タイプを出すには、長さとして小数部や符号も考慮されます。
SQL ルーチン内の XML 引数の場合、(XML 引数には長さがないため) ゼロが戻されます。 しかし、カタログ式外部ルーチンの場合、XML パラメーターは XML AS CLOB(n) として宣言されます。この場合、BUFFER_LENGTH はカタログされた長さ、n です。
データ・タイプ長の表を参照してください。
- 列 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 列にはそのパラメーターに入れられる小数桁数が含まれています。
数値データ・タイプの場合、DBMS は 10 または 2 の NUM_PREC_RADIX を戻すことができます。
基数が適用できないデータ・タイプの場合は NULL が戻されます。
- 列 12 NULLABLE (SMALLINT 非 NULL)
- パラメーターが NULL を受け入れない場合は SQL_NO_NULLS。
パラメーターが NULL 値を受け入れる場合は SQL_NULLABLE。
- 列 13 REMARKS (VARCHAR(254))
- パラメーターに関する記述情報を入れられます。
- 列 14 COLUMN_DEF (VARCHAR)
- 列のデフォルト値。
NULL をデフォルト値として指定した場合、この列は引用符で囲まれていない語 NULL です。切り捨てを行わないとデフォルト値を表すことができない場合、この列には単一引用符で囲まれていない TRUNCATED が入ります。デフォルト値を指定しなかった場合、この列は NULL です。
COLUMN_DEF の値は、TRUNCATED 以外の値であれば新しい列定義を生成するために使用できます。
- 列 15 SQL_DATA_TYPE (SMALLINT 非 NULL)
- SQL_DESC_TYPE 記述子のフィールドに表示される SQL データ・タイプの値。日時データ・タイプは除いて、
この列は DATA_TYPE 列と同じです (CLI はインターバル・データ・タイプをサポートしていません)。
日時データ・タイプの場合、結果セットの SQL_DATA_TYPE フィールドは SQL_DATETIME になり、SQL_DATETIME_SUB フィールドは特定の日時データ・タイプ (SQL_CODE_DATE、SQL_CODE_TIME、または SQL_CODE_TIMESTAMP) のサブコードを戻します。
- 列 16 SQL_DATETIME_SUB (SMALLINT)
- 日時データ・タイプのサブタイプ・コード。 他のすべてのデータ・タイプの場合、この列は NULL 値を戻します (CLI がサポートしていないインターバル・データ・タイプを含む)。
- 列 17 CHAR_OCTET_LENGTH (INTEGER)
- 文字データ・タイプ列 (CODEUNITS32 として定義されたものも含む) のバイト単位の最大長。 他のすべてのデータ・タイプの場合、この列は NULL を戻します。
- 列 18 ORDINAL_POSITION (INTEGER NOT NULL)
- この結果セットの COLUMN_NAME で指定されているパラメーターの序数部が入れられます。これは、CALL ステートメント上で提供される引数の元の位置です。 左端の引数の元の位置は、1 です。
- 列 19 IS_NULLABLE (Varchar)
-
- 列に NULL を含めることができない場合は、「NO」。
- 列に NULL が含まれる場合は、「YES」。
- NULL 可能かどうか不明の場合は、ゼロ長ストリング。
ISO SQL 準拠の DBMS は、空ストリングを戻すことができません。
この列に戻される値は、NULLABLE 列に戻される値とは異なります。(NULLABLE 列の説明を参照してください。)
- CLI が使用する列名は、X/Open CLI CAE 仕様のスタイルに準拠しています。列の名前、内容、および順序は、ODBC の SQLProcedureColumns() 結果セットで定義されているものと同じです。
- 2 つのモジュールに同じ名前のプロシージャーが組み込まれている場合、SQLProcedureColumns() は両方のプロシージャーに関する詳細を戻します。
戻りコード
- SQL_ERROR
- SQL_INVALID_HANDLE
- SQL_STILL_EXECUTING
- SQL_SUCCESS
- SQL_SUCCESS_WITH_INFO
診断
SQLSTATE | 説明 | 解説 |
---|---|---|
24000 | カーソル状態が無効です。 | カーソルはすでに、ステートメント・ハンドル上にオープンされています。 |
40003 08S01 | 通信リンクに障害が起きました。 | アプリケーションとデータ・ソースとの間の通信リンクが、関数の完了する前に失敗しました。 |
42601 | PARMLIST 構文エラーです。 | ストアード・プロシージャー・カタログ表の PARMLIST 値に、構文エラーがあります。 |
HY001 | メモリーの割り振りが失敗しました。 | DB2 CLI は、この関数の実行または完了をサポートするのに必要なメモリーを割り当てられません。プロセス・レベルのメモリーがアプリケーション・プロセスに使い尽くされた可能性があります。 プロセス・レベルのメモリー制限については、オペレーティング・システムの構成を調べてください。 |
HY008 | 操作が取り消されました。 | StatementHandle で非同期処理が使用できるようになりました。 関数が呼び出され、その実行が完了する前に、 SQLCancel() がマルチスレッド・アプリケーション内の別のスレッドから、 StatementHandle で呼び出されました。 その関数が再び StatementHandle で呼び出されました。 |
HY010 | 関数のシーケンス・エラーです。 | 実行時データ (SQLParamData()、SQLPutData()) 操作中に、 関数が呼び出されました。 BEGIN COMPOUND と END COMPOUND の SQL 操作中に、関数が呼び出されました。 非同期で実行中の関数 (この関数ではない) が StatementHandle で呼び出されましたが、 この関数の呼び出し時にはまだ実行中でした。 ステートメント・ハンドル上のステートメントが準備される前にこの関数が呼び出されました。 |
HY014 | これ以上ハンドルがありません。 | DB2 CLI は、リソースの制約のため、ハンドルを割り当てられません。 |
HY090 | ストリングまたはバッファーの長さが無効です。 | 名前の長さ引数のうちの 1 つの値は 0 より小さい値でしたが、SQL_NTS と等しくありませんでした。 |
HYT00 | タイムアウトになりました。 | データ・ソースが結果セットを戻す前に、タイムアウト期間が満了しました。 タイムアウト期間は、 SQLSetStmtAttr() の SQL_ATTR_QUERY_TIMEOUT 属性を使用して設定できます。 |
制限
SQLProcedureColumns() 関数は、ストアード・プロシージャーから戻された可能性のある結果セットの属性についての情報を戻しません。
ストアード・プロシージャー・カタログのサポートや、ストアード・プロシージャーのサポートを提供していない DB2 にアプリケーションを接続すると、SQLProcedureColumns() 関数は空の結果セットを戻します。
例
/* get input/output parameter information for a procedure */
sqlrc = SQLProcedureColumns(hstmt,
NULL,
0, /* catalog name not used */
(unsigned char *)colSchemaNamePattern,
SQL_NTS, /* schema name not currently used */
(unsigned char *)procname,
SQL_NTS,
colNamePattern,
SQL_NTS); /* all columns */