SQLDescribeParam 関数
準拠
導入されたバージョン: ODBC 1.0 Standards Compliance: ODBC
まとめ
SQLDescribeParam は、準備された SQL ステートメントに関連付けられているパラメーター マーカーの説明を返します。 この情報は、IPD のフィールドでも使用できます。
構文
SQLRETURN SQLDescribeParam(
SQLHSTMT StatementHandle,
SQLUSMALLINT ParameterNumber,
SQLSMALLINT * DataTypePtr,
SQLULEN * ParameterSizePtr,
SQLSMALLINT * DecimalDigitsPtr,
SQLSMALLINT * NullablePtr);
引数
StatementHandle
[入力]ステートメント ハンドル。
ParameterNumber
[入力]パラメーター マーカー番号は、1 から始まるパラメーターの順序を増やして順番に並べ替えています。
DataTypePtr
[出力]パラメーターの SQL データ型を返すバッファーへのポインター。 この値は、IPD の SQL_DESC_CONCISE_TYPE レコード フィールドから読み取られます。 これは、「付録 D: データ型」の「 SQL データ型 」セクションの値のいずれか、またはドライバー固有の SQL データ型になります。
ODBC 3.x、SQL_TYPE_DATE、SQL_TYPE_TIME、またはSQL_TYPE_TIMESTAMPは、日付、時刻、タイムスタンプ のデータに対してそれぞれ *DataTypePtr で返されます。ODBC 2.x、SQL_DATE、SQL_TIME、またはSQL_TIMESTAMPが返されます。 ドライバー マネージャーは、ODBC 2. 時に必要なマッピングを実行しますx アプリケーションが ODBC 3. で動作していますx ドライバーまたは ODBC 3.x アプリケーションは ODBC 2. で動作していますx ドライバー。
ColumnNumber が 0 (ブックマーク列の場合) に等しい場合、可変長ブックマークの*DataTypePtr でSQL_BINARYが返されます。 (ブックマークが ODBC 3. で使用されている場合、SQL_INTEGERが返されます。x ODBC 2. を使用するアプリケーションx ドライバーまたは ODBC 2.x ODBC 3. を使用するアプリケーションx ドライバー)。)
詳細については、「付録 D: データ型」の「 SQL データ型 」を参照してください。 ドライバー固有の SQL データ型の詳細については、ドライバーのドキュメントを参照してください。
ParameterSizePtr
[出力]データ ソースで定義されている対応するパラメーター マーカーの列または式のサイズを文字で返すバッファーへのポインター。 列のサイズの詳細については、「 Column サイズ、10 進数、転送オクテットの長さ、および表示サイズを参照してください。
DecimalDigitsPtr
[出力]データ ソースで定義されている対応するパラメーターの列または式の 10 進数の桁数を返すバッファーへのポインター。 10 進数の詳細については、「 Column サイズ、10 進数、転送オクテットの長さ、および表示サイズを参照してください。
NullablePtr
[出力]パラメーターが NULL 値を許可するかどうかを示す値を返すバッファーへのポインター。 この値は、IPD の SQL_DESC_NULLABLE フィールドから読み取られます。 次のいずれか:
SQL_NO_NULLS: パラメーターは NULL 値を許可しません (これが既定値です)。
SQL_NULLABLE: パラメーターは NULL 値を許可します。
SQL_NULLABLE_UNKNOWN: ドライバーは、パラメーターが NULL 値を許可するかどうかを判断できません。
返品
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR、またはSQL_INVALID_HANDLE。
診断
SQLDescribeParamがSQL_ERRORまたはSQL_SUCCESS_WITH_INFOを返す場合、関連付けられた SQLSTATE 値を取得するには、SQL_HANDLE_STMTのHandleTypeとStatementHandleのHandleを使用してSQLGetDiagRecを呼び出します。 次の表は、通常、 SQLDescribeParam によって返される SQLSTATE 値を示し、この関数のコンテキストでそれぞれについて説明します。表記 "(DM)" は、ドライバー マネージャーによって返される SQLSTATE の説明の前にあります。 特に明記されていない限り、各 SQLSTATE 値に関連付けられている戻りコードはSQL_ERROR。
| SQLSTATE | エラー | 説明 |
|---|---|---|
| 01000 | 一般的な警告 | ドライバー固有の情報メッセージ。 (関数はSQL_SUCCESS_WITH_INFOを返します。 |
| 07009 | 記述子インデックスが無効です | (DM) 引数 ParameterNumber に指定された値が 1 未満です。 引数 ParameterNumber に指定された値が、関連付けられている SQL ステートメント内のパラメーターの数より大きかった。 パラメーター マーカーは、DML 以外のステートメントの一部でした。 パラメーター マーカーは、 SELECT リストの一部でした。 |
| 08S01 | 通信リンクエラー | ドライバーとドライバーが接続されたデータ ソース間の通信リンクは、関数の処理が完了する前に失敗しました。 |
| 21S01 | 挿入する値の一覧が列の一覧と一致しません | INSERT ステートメント内のパラメーターの数が、ステートメントで指定されたテーブル内の列数と一致しませんでした。 |
| HY000 | 一般的なエラー | 特定の SQLSTATE がなく、実装固有の SQLSTATE が定義されていないエラーが発生しました。 *MessageText バッファー内の SQLGetDiagRec によって返されるエラー メッセージには、エラーとその原因が記述されています。 |
| HY001 | メモリ割り当てエラー | ドライバーは、関数の実行または完了をサポートするために必要なメモリを割り当てませんでした。 |
| HY008 | 操作が取り消されました | StatementHandle に対して非同期処理が有効になりました。 関数が呼び出され、実行が完了する前に、 SQLCancel または SQLCancelHandle が StatementHandle で呼び出されました。 その後、 StatementHandle で関数が再度呼び出されました。 関数が呼び出され、実行が完了する前に、 SQLCancel または SQLCancelHandle がマルチスレッド アプリケーション内の別のスレッドから StatementHandle で呼び出されました。 |
| HY010 | 関数シーケンス エラー | (DM) SQLPrepare または SQLExecDirect を呼び出す前に、 StatementHandle を呼び出す前に関数が呼び出されました。 (DM) StatementHandle に関連付けられている接続ハンドルに対して非同期実行関数が呼び出されました。 この非同期関数は、 SQLDescribeParam 関数が呼び出されたときにまだ実行されていました。 (DM) 非同期実行関数 (この関数ではない) が StatementHandle に対して呼び出されこの関数が呼び出されたときにはまだ実行されていました。 (DM) SQLExecute、 SQLExecDirect、 SQLBulkOperations、または SQLSetPos が StatementHandle に対して呼び出され、SQL_NEED_DATAが返されました。 この関数は、すべての実行時データ パラメーターまたは列に対してデータが送信される前に呼び出されました。 |
| HY013 | メモリ管理エラー | メモリが不足している可能性があるため、基になるメモリ オブジェクトにアクセスできなかったため、関数呼び出しを処理できませんでした。 |
| HY117 | 不明なトランザクション状態のため、接続が中断されます。 切断関数と読み取り専用関数のみが許可されます。 | (DM) 中断状態の詳細については、「 SQLEndTran 関数を参照してください。 |
| HYT01 | 接続のタイムアウト | データ ソースが要求に応答する前に、接続タイムアウト期間の有効期限が切れています。 接続タイムアウト期間は、SQL_ATTR_CONNECTION_TIMEOUT SQLSetConnectAttr によって設定されます。 |
| IM001 | ドライバーは、この関数をサポートしていません | (DM) StatementHandle に関連付けられているドライバーは、関数をサポートしていません。 |
| IM017 | 非同期通知モードでポーリングが無効になっている | 通知モデルが使用されるたびに、ポーリングは無効になります。 |
| IM018 | SQLCompleteAsync は、このハンドルに対する前の非同期操作を完了するために呼び出されていません。 | ハンドルに対する前の関数呼び出しがSQL_STILL_EXECUTINGを返し、通知モードが有効になっている場合は、後処理を実行して操作を完了するために、 SQLCompleteAsync をハンドルで呼び出す必要があります。 |
Comments
パラメーター マーカーには、SQL ステートメントに表示される順序で、パラメーターの順序が 1 から始まる順に番号が付けられます。
SQLDescribeParam は、SQL ステートメント内のパラメーターの型 (入力、入力/出力、または出力) を返しません。 プロシージャの呼び出しを除き、SQL ステートメント内のすべてのパラメーターは入力パラメーターです。 プロシージャの呼び出しで各パラメーターの型を決定するために、アプリケーションは SQLProcedureColumns を呼び出します。
詳細については、「 パラメーターの指定」を参照してください。
コード例
次の例では、ユーザーに SQL ステートメントの入力を求め、そのステートメントを準備します。 次に、 SQLNumParams を呼び出して、ステートメントにパラメーターが含まれているかどうかを判断します。 ステートメントにパラメーターが含まれている場合は、 SQLDescribeParam を呼び出してそれらのパラメーターを記述し、 SQLBindParameter を呼び出してバインドします。 最後に、パラメーターの値をユーザーに求め、ステートメントを実行します。
SQLCHAR Statement[100];
SQLSMALLINT NumParams, i, DataType, DecimalDigits, Nullable;
SQLUINTEGER ParamSize;
SQLHSTMT hstmt;
// Prompt the user for a SQL statement and prepare it.
GetSQLStatement(Statement);
SQLPrepare(hstmt, Statement, SQL_NTS);
// Check to see if there are any parameters. If so, process them.
SQLNumParams(hstmt, &NumParams);
if (NumParams) {
// Allocate memory for three arrays. The first holds pointers to buffers in which
// each parameter value will be stored in character form. The second contains the
// length of each buffer. The third contains the length/indicator value for each
// parameter.
SQLPOINTER * PtrArray = (SQLPOINTER *) malloc(NumParams * sizeof(SQLPOINTER));
SQLINTEGER * BufferLenArray = (SQLINTEGER *) malloc(NumParams * sizeof(SQLINTEGER));
SQLINTEGER * LenOrIndArray = (SQLINTEGER *) malloc(NumParams * sizeof(SQLINTEGER));
for (i = 0; i < NumParams; i++) {
// Describe the parameter.
SQLDescribeParam(hstmt, i + 1, &DataType, &ParamSize, &DecimalDigits, &Nullable);
// Call a helper function to allocate a buffer in which to store the parameter
// value in character form. The function determines the size of the buffer from
// the SQL data type and parameter size returned by SQLDescribeParam and returns
// a pointer to the buffer and the length of the buffer.
AllocParamBuffer(DataType, ParamSize, &PtrArray[i], &BufferLenArray[i]);
// Bind the memory to the parameter. Assume that we only have input parameters.
SQLBindParameter(hstmt, i + 1, SQL_PARAM_INPUT, SQL_C_CHAR, DataType, ParamSize,
DecimalDigits, PtrArray[i], BufferLenArray[i],
&LenOrIndArray[i]);
// Prompt the user for the value of the parameter and store it in the memory
// allocated earlier. For simplicity, this function does not check the value
// against the information returned by SQLDescribeParam. Instead, the driver does
// this when the statement is executed.
GetParamValue(PtrArray[i], BufferLenArray[i], &LenOrIndArray[i]);
}
}
// Execute the statement.
SQLExecute(hstmt);
// Process the statement further, such as retrieving results (if any) and closing the
// cursor (if any). Code not shown.
// Free the memory allocated for each parameter and the memory allocated for the arrays
// of pointers, buffer lengths, and length/indicator values.
for (i = 0; i < NumParams; i++) free(PtrArray[i]);
free(PtrArray);
free(BufferLenArray);
free(LenOrIndArray);
関連する関数
| 情報 | 参照トピック |
|---|---|
| バッファーをパラメーターにバインドする | SQLBindParameter 関数 |
| ステートメント処理の取り消し | SQLCancel 関数 |
| 準備された SQL ステートメントの実行 | SQLExecute 関数 |
| 実行のためのステートメントの準備 | SQLPrepare 関数 |