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 | 入力 | ステートメント・ハンドル。 |
| SQLCHAR * | szProcCatalog | 入力 | 3 部構成のプロシージャー名のカタログ修飾子。 これは、NULL ポインターまたは長さゼロのストリングでなければなりません。 |
| SQLSMALLINT | cbProcCatalog | 入力 | szProcCatalog の長さ (バイト)。これは、0 に設定する必要があります。 |
| SQLCHAR * | szProcSchema | 入力 | スキーマ名で結果セットを修飾するためのパターン値 を入れることができるバッファー。 結果セットをスキーマ名で修飾しない場合は、この引数に対しては NULL ポインターまたは長さゼロのストリングを使用してください。 |
| SQLSMALLINT | cbProcSchema | 入力 | szProcSchema の長さ (バイト)。 |
| SQLCHAR * | szProcName | 入力 | プロシージャー名で結果セットを修飾する
ためのパターン値 を入れることができるバッファー。
結果セットをプロシージャー名で修飾しない場合は、この引数に対して NULL ポインターまたは長さゼロのストリングを使用してください。 |
| SQLSMALLINT | cbProcName | 入力 | szProcName の長さ (バイト)。 |
| SQLCHAR * | szColumnName | 入力 | パラメーター名で結果セットを修飾する
ためのパターン値 を入れることができるバッファー。
この引数は、szProcName あるいは szProcSchema (または、その両方) に対して
空でない値を指定することの制約を既に受けている結果セットをさらに修飾するために使用します。
結果セットをパラメーター名で修飾する必要がない場合は、この引数で NULL ポインターまたは長さゼロのストリングを使用してください。 |
| SQLSMALLINT | cbColumnName | 入力 | szColumnName の長さ (バイト)。 |
使用法
登録済みストアード・プロシージャーを SYSIBM.SYSROUTINES カタログ表に 定義します。ストアード・プロシージャー・カタログの機能を提供しない サーバーでは、空の結果セットが戻されます。
Db2® ODBC は、ストアード・プロシージャーに関連した入力パラメーター、 入出力パラメーター、および出力パラメーターの情報を戻しますが、 戻された結果セットの記述子情報についての情報を戻すことはできません。
SQLProcedureColumns() は、PROCEDURE_CAT、PROCEDURE_SCHEM、 PROCEDURE_NAME、および COLUMN_TYPE の順序で、結果セットに入れて情報を戻します。表 3 には、結 果セットにある列の一覧を記載してあります。
多くの場合、SQLProcedureColumns() への呼び出しは、システム・カタログに対する複雑な (したがって、 コストのかかる) 照会にマップされることになるため、慎重に使用し、呼び出しを繰り返さずに、 結果を保管するようにしてください。
- 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 | SQL_C_DEFAULT が SQLBindCol()、SQLGetData()、および SQLBindParameter() 呼び出しで指定された場合、このパラメーターからのデータを保管するための関連する 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) | 次のいずれかです。
|
注:
|
|||
Db2 ODBC が使用する列名は、X/Open CLI CAE 仕様のスタイルに準拠しています。列タイプ、内容、および順序は、ODBC の 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 と 等しくありません。 |
| HYC00 | ドライバーは使用できません。 | 次の 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;
}