SQLProcedureColumns()
- プロシージャー入出力パラメーター情報を取得する
SQLProcedureColumns()
は、プロシージャーに関連した入出力パラメーターのリストを戻します。 情報は、SQL 結果セット内に戻されます。 この結果セットは、
照会で生成される結果セットを処理するのと同じ関数を使用して、取り出すことができます。
SQLProcedureColumns()
の ODBC 仕様
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);
関数引数
次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。
データ・タイプ | 引数 | 使用 | 説明 |
---|---|---|---|
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()
への呼び出しは、システム・カタログに対する複雑な (したがって、
コストのかかる) 照会にマップされることになるため、慎重に使用し、呼び出しを繰り返さずに、
結果を保管するようにしてください。
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 列の長さを判別
アプリケーションでは、将来のリリースで最終列以降の列が定義される 可能性があることを認識しておく必要があります。 将来のリリースでは、列が新たに追加されたり、既存の列の名前が 変更される可能性はありますが、現行の列の位置が変更になることはありま せん。 次の表は、これらの列を示しています。
列番号 | 列名 | データ・タイプ | 説明 |
---|---|---|---|
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 | この行に関連したタイプ情報を識別します。 次の値を使用できます。
|
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) | 列のデフォルト値。 デフォルト値が何であるかによって、次の
ように異なります。
切り捨てなしではデフォルト値を表すことができない場合、この列に は単一引用符で囲まれていない 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 | 日時データ・タイプのサブタイプ・コード。
|
17 | CHAR_OCTET_LENGTH | INTEGER | 文字データ・タイプ列の最大長 (バイト)。 ネイティブ SQL プロシージャー内の XML データ・タイプの場合、ゼロが返されます (XML データ・タイプに長さはありません)。 その他のすべてのデータ・タイプに対して、この列はヌル値を返します。 |
18 | ORDINAL_POSITION | INTEGER NOT NULL | この結果セット内の COLUMN_NAME によって示されたパラメーターの順序を表す位置が 含まれます。 これは、CALL ステートメントで提供される引数の順序を表す位置です。 左端の引数の元の位置は、1 です。 |
19 | IS_NULLABLE | VARCHAR(128) | 以下のいずれか 1 つです。
|
注:
|
Db2 ODBC によって使用される列名は、X/Open CLI CAE 仕様スタイルに従います。 列タイプ、内容、および順序は、ODBC の SQLProcedureColumns()
結果セット
で定義されているものと同じです。
戻りコード
SQLProcedureColumns()
は、呼び出された後、次のいずれかの値を戻します。- SQL_SUCCESS
- SQL_SUCCESS_WITH_INFO
- SQL_ERROR
- SQL_INVALID_HANDLE
診断
次の表は、この関数が生成する各 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 が戻されます。
|
制約事項
SQLProcedureColumns()
は、ストアード・プロシージャーが
戻す可能性のある結果セットの属性についての情報は戻しません。
アプリケーションがストアドプロシージャまたはストアドプロシージャカタログのサポートを提供していない Db2 サーバーに接続されている場合、 SQLProcedureColumns()
は空の結果セットを返します。
例
/******************************************************************/
/* 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,
¶meter_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;
}