CLI の手引きおよび解説書

SQLProcedureColumns - プロシージャーの入力 / 出力情報を入手する

目的


仕様: DB2 CLI 2.1 ODBC 1.0  

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

構文

SQLRETURN SQLProcedureColumns(
                SQLHSTMT          StatementHandle,   /* hstmt */
                SQLCHAR      FAR  *CatalogName,      /* szProcCatalog */
                SQLSMALLINT       NameLength1,       /* cbProcCatalog */
                SQLCHAR      FAR  *SchemaName,       /* szProcSchema */
                SQLSMALLINT       NameLength2,       /* cbProcSchema */
                SQLCHAR      FAR  *ProcName,         /* szProcName */
                SQLSMALLINT       NameLength3,       /* cbProcName */
                SQLCHAR      FAR  *ColumnName,       /* szColumnName */
                SQLSMALLINT       NameLength4);      /* cbColumnName */

関数引き数


表 140. SQLProcedureColumns 引き数
データ・タイプ 引き数 使用法 説明
SQLHSTMT StatementHandle 入力 ステートメント・ハンドル。
SQLCHAR * CatalogName 入力 3 つの部分から成るプロシージャー名のカタログ修飾子。

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

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

DB2 (MVS/ESA 版) V 4.1 の場合、すべてのストアード・プロシージャーは 1 つのスキーマにあります。 SchemaName 引き数の唯一の受け入れ可能な値はヌル・ポインターです。 DB2 ユニバーサル・データベースの場合、SchemaName には有効なパターン値が含まれます。有効な検索パターンの詳細については、システム・カタログ情報の照会を参照してください。

SQLSMALLINT NameLength2 入力 SchemaName の長さ。
SQLCHAR * ProcName 入力 プロシージャー名で結果セットを修飾するためのパターン値 を入れられるバッファー。
SQLSMALLINT NameLength3 入力 ProcName の長さ。
SQLCHAR * ColumnName 入力 パラメーター名で結果セットを修飾するためのパターン値 を入れられるバッファー。この引き数は、 ProcName または SchemaName (あるいはその両方) に空ではない値を指定することにより、すでに制限されている結果セットをさらに修飾するために使用します。
SQLSMALLINT NameLength4 入力 ColumnName の長さ。

使用法

DB2 ユニバーサル・データベース バージョン 5 では、すべてのストアード・プロシージャー (SYSCAT.PROCEDURES と SYSCAT.PROCPARMS) に関する情報をサーバーに保管するのに使う 2 つのシステム・カタログ視点が導入されました。これらの視点については、付録 G, ストアード・プロシージャーのカタログ表示を参照してください。

バージョン 5 以前では、 DB2 CLI はストアード・プロシージャー登録の疑似カタログ表を使用していました。デフォルトで、DB2 CLI は新しいシステム・カタログ表示を使用することになります。アプリケーションで疑似カタログ表の使用が見込まれる場合、 CLI/ODBC 構成キーワード PATCH1 を 262144 に設定してください。詳細については、ストアード・プロシージャーの疑似カタログ表の置換を参照してください。

ストアード・プロシージャーが DB2 (MVS/ESA 版) V 4.1 サーバーまたはそれ以降のものにある場合、ストアード・プロシージャーの名前はサーバーの SYSIBM.SYSPROCEDURES カタログ表に登録される必要があります。

ストアード・プロシージャー・カタログの機能を提供しない他の DB2 サーバーのバージョンでは、空の結果セットが戻されます。

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

SQLProcedureColumns() は、PROCEDURE_CAT、PROCEDURE_SCHEM、 PROCEDURE_NAME、および COLUMN_TYPE の順序で結果セット内の情報を戻します。 『SQLProcedureColumns で戻される列』は、結果セット内の列をリストしています。アプリケーションは、将来のリリースで最終列以降の列が定義される可能性があることを認識する必要があります。

ほとんどの場合、 SQLProcedureColumns() への呼び出しはシステム・カタログに対して複雑で、それゆえに費用のかかる照会へとマップされるので、使用を節約する必要があります。それで呼び出しを繰り返すよりも、結果を保管しておく方が良いでしょう。

カタログ関数の結果セットの VARCHAR 列は、SQL92 の制限に従うように、 128 の最大長属性で宣言されています。 DB2 名は 128 文字よりも少ないので、アプリケーションは、出力バッファー用に 128 文字 (およびヌル終止符) を常にとっておくか、あるいは、接続している DBMS がサポートしている TABLE_CAT、TABLE_SCHEM、TABLE_NAME、および COLUMN_NAME 列の実際の長さをそれぞれ判別するために、 SQL_MAX_CATALOG_NAME_LEN、 SQL_MAX_SCHEMA_NAME_LEN、 SQL_MAX_TABLE_NAME_LEN、および SQL_MAX_COLUMN_NAME_LEN を使用して選択的に SQLGetInfo() を呼び出すようにすることができます。

SQL_ATTR_LONGDATA_COMPAT 接続属性が設定されている場合、LOB 列タイプは LONG VARCHAR、 LONG VARBINARY、または LONG VARGRAPHIC タイプとして報告されます。

将来のリリースでは、列が新たに追加されたり、既存の列の名前が変更されたりする可能性はありますが、現行の列の位置が変更されることはありません。これらの列は、バージョン 2 からバージョン 5 までの間に変更が加えられました。バージョン 5 以降のサーバーに対して、 SQLProcedureColumns() を使用するバージョン 2 DB2 CLI アプリケーションを実行する場合の詳細については、 SQLProcedureColumns() 戻り値の変更を参照してください。

SQLProcedureColumns で戻される列

列 1 PROCEDURE_CAT (VARCHAR(128))
これは常にヌルです。

列 2 PROCEDURE_SCHEM (VARCHAR(128))
PROCEDURE_NAME を含むスキーマの名前。 (これも DB2 (MVS/ESA 版) V 4.1 SQLProcedureColumns() 結果セットに対し NULL です)。

列 3 PROCEDURE_NAME (VARCHAR(128))
プロシージャーの名前。

列 4 COLUMN_NAME (VARCHAR(128))
パラメーターの名前。

列 5 COLUMN_TYPE (SMALLINT 非 NULL)
この行に関連したタイプ情報を識別します。値は次のとおりです。

列 6 DATA_TYPE (SMALLINT 非 NULL)
SQL データ・タイプ。

列 7 TYPE_NAME (VARCHAR(128) 非 NULL)
DATA_TYPE に対応するデータ・タイプの名前を表す文字ストリング。

列 8 COLUMN_SIZE (INTEGER)
DATA_TYPE 列の値が文字または 2 進ストリングであることを示す場合、この列にはバイトの最大長が含まれます。それがグラフィック (DBCS) ストリングであれば、これはパラメーターの 2 バイト文字の個数です。

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

数値データ・タイプの場合、これは結果表の NUM_PREC_RADIX 列の値に基づいて、列に許可されている合計桁数または合計ビット数のいずれかです。

表 194 も参照してください。

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

表 196 を参照してください。

列 10 DECIMAL_DIGITS (SMALLINT)
パラメーターの位取り。位取りが適用できないデータ・タイプの場合は NULL が戻されます。

表 195 を参照してください。

列 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。

パラメーターがヌル値を受け入れる場合は 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 列と同じです (DB2 CLI はインターバル・データ・タイプをサポートしていません)。

日時データ・タイプの場合、結果セットの SQL_DATA_TYPE フィールドは SQL_DATETIME になり、 SQL_DATETIME_SUB フィールドは特定の日時データ・タイプ (SQL_CODE_DATE、 SQL_CODE_TIME、または SQL_CODE_TIMESTAMP) のサブコードを戻します。

列 16 SQL_DATETIME_SUB (SMALLINT)
日時データ・タイプのサブタイプ・コード。他のすべてのデータ・タイプの場合、この列は NULL を戻します (DB2 CLI がサポートしていないインターバル・データ・タイプを含む)。

列 17 CHAR_OCTET_LENGTH (INTEGER)
文字データ・タイプ列のバイト単位の最大長。他のすべてのデータ・タイプの場合、この列は NULL を戻します。

列 18 ORDINAL_POSITION (INTEGER NOT NULL)
この結果セットの COLUMN_NAME で指定されているパラメーターの順序数が入れられます。これは、CALL ステートメント上で提供される引き数の元の位置です。左端の引き数の元の位置は、1 です。

列 19 IS_NULLABLE (Varchar)

ヌル可能かどうかを判別する際には、ISO 規則に従います。

ISO SQL 準拠の DBMS は、空ストリングを戻すことができません。

この列に戻される値は、NULLABLE 列に戻される値とは異なります。 (NULLABLE 列の説明を参照してください。)

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

戻りコード

診断


表 141. SQLProcedureColumns SQLSTATE
SQLSTATE 説明 解説
24000 カーソル状態が無効です。 カーソルはすでに、ステートメント・ハンドル上にオープンされています。
40003 08S01 通信リンクに障害が起きました。 アプリケーションとデータ・ソースとの間の通信リンクが、関数の完了する前に失敗しました。
42601 PARMLIST 構文エラーです。 ストアード・プロシージャー・カタログ表の PARMLIST 値に、構文エラーがあります。
HY001 メモリーの割り振り失敗です。 DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。
HY008 操作が取り消しになりました。

非同期処理が StatementHandle に対して使用可能になりました。関数が呼び出され、その実行が完了する前に、 SQLCancel()StatementHandle で呼び出されました。そして、関数が再び StatementHandle で呼び出されました。

関数が呼び出され、その実行が完了する前に、 SQLCancel() が複数スレッドのアプリケーション内の別のスレッドから、 StatementHandle で呼び出されました。

HY010 関数の順序エラーです。

実行時データ (SQLParamData()SQLPutData()) 操作中に、関数が呼び出されました。

BEGIN COMPOUND と END COMPOUND SQL の操作中に、関数が呼び出されました。

非同期実行関数 (この関数ではない) が StatementHandle で呼び出され、この関数は、呼び出し時に依然実行中でした。

HY014 もはやハンドルはありません。 DB2 CLI は、内部資源が原因でハンドルを割り当てることができませんでした。
HY090 ストリングまたはバッファー長が無効です。 名前の長さ引き数のうちの 1 つの値は 0 より小さい値でしたが、 SQL_NTS と等しくありませんでした。
HYC00 ドライバーが機能していません。 DB2 CLI は、プロシージャー名の修飾子として カタログ をサポートしません。

接続されているサーバーは、プロシージャー名の修飾子として スキーマ をサポートしません。

HYT00 タイムアウトになりました。 データ・ソースが結果セットを返す前に、タイムアウト期間が満了しました。タイムアウトは、 Windows 3.1 や Macintosh System 7 のようなマルチタスクではないシステム上でのみサポートされています。タイムアウト期間は、 SQLSetConnectAttr() の SQL_ATTR_QUERY_TIMEOUT 属性を使用して設定することができます。

制約

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

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

CLI サンプル stpcli.c

(ここで完全サンプル stpcli.c を使用することもできます 。)

/* From the CLI sample STPCLI.C */
/* ... */
    rc = SQLProcedureColumns(hstmt, NULL, 0,
                             stpSchemaPattern, SQL_NTS, 
                             stpNamePattern, SQL_NTS,
                             colNamePattern, SQL_NTS);
    
 

参照


[ ページのトップ | 前ページ | 次ページ | 目次 | 索引 ]