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が返されます。 (SQL_INTEGERは、ODBC 3 でブックマークが使用されている場合に返されます。x ODBC 2 を使用するアプリケーション。x ドライバーまたは ODBC 2。x ODBC 3 を使用するアプリケーション。x ドライバー)。)

詳細については、「付録 D: データ型」の「SQL データ 型」を参照してください。 ドライバー固有の SQL データ型の詳細については、ドライバーのドキュメントを参照してください。

ParameterSizePtr
[出力]データ ソースで定義されている対応するパラメーター マーカーの列または式のサイズを文字数で返すバッファーへのポインター。 列サイズの詳細については、「 列サイズ」、「10 進数」、「転送オクテット長」、「表示サイズ」を参照してください。

DecimalDigitsPtr
[出力]データ ソースで定義されている対応するパラメーターの列または式の 10 進数の桁数を返すバッファーへのポインター。 10 進数の詳細については、「 列サイズ」、「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)" は、ドライバー マネージャーによって返される SQLSTATEs の説明の前にあります。 特に明記されていない限り、各 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 で関数が再度呼び出されました。

関数が呼び出され、実行が完了する前に、マルチスレッド アプリケーション内の別のスレッドから StatementHandle で SQLCancel または SQLCancelHandle が呼び出されました。
HY010 関数シーケンス エラー (DM) 関数は、StatementHandle に対して SQLPrepare または SQLExecDirect を呼び出す前に呼び出されました。

(DM) StatementHandle に関連付けられている接続ハンドルに対して非同期実行関数が呼び出されました。 この非同期関数は、 SQLDescribeParam 関数が呼び出されたときにも実行されていました。

(DM) 非同期実行関数 (この関数ではなく) が StatementHandle に対して呼び出され、この関数が呼び出されたときにはまだ実行されていました。

(DM) StatementHandle に対して SQLExecute、SQLExecDirect、SQLBulkOperations、または SQLSetPos が呼び出され、SQL_NEED_DATA返されました。 この関数は、すべての実行時データ パラメーターまたは列に対してデータが送信される前に呼び出されました。
HY013 メモリ管理エラー メモリ不足の可能性があるため、基になるメモリ オブジェクトにアクセスできなかったため、関数呼び出しを処理できませんでした。
HY117 不明なトランザクション状態が原因で接続が中断されます。 切断関数と読み取り専用関数のみが許可されます。 (DM) 中断状態の詳細については、「 SQLEndTran 関数」を参照してください。
HYT01 接続のタイムアウト データ ソースが要求に応答する前に、接続タイムアウト期間の有効期限が切れています。 接続タイムアウト期間は、 SQLSetConnectAttr (SQL_ATTR_CONNECTION_TIMEOUT) によって設定されます。
IM001 ドライバーは、この関数をサポートしていません (DM) StatementHandle に関連付けられているドライバーは、 関数をサポートしていません。
IM017 非同期通知モードでポーリングが無効になっている 通知モデルを使用するたびに、ポーリングは無効になります。
IM018 SQLCompleteAsync は、このハンドルで前の非同期操作を完了するために呼び出されていません。 ハンドルの前の関数呼び出しがSQL_STILL_EXECUTINGを返し、通知モードが有効になっている場合は、処理後に処理を実行して操作を完了するために、 SQLCompleteAsync をハンドルで呼び出す必要があります。

説明

パラメーター マーカーには、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 an 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 関数

参照

ODBC API リファレンス
ODBC ヘッダー ファイル