SQLDescribeCol 関数
準拠
導入されたバージョン: ODBC 1.0 Standards Compliance: ISO 92
まとめ
SQLDescribeCol は、結果セット内の 1 つの列に対して、結果記述子 (列名、型、列サイズ、10 進数、null 許容) を返します。 この情報は、IRD のフィールドでも使用できます。
構文
SQLRETURN SQLDescribeCol(
SQLHSTMT StatementHandle,
SQLUSMALLINT ColumnNumber,
SQLCHAR * ColumnName,
SQLSMALLINT BufferLength,
SQLSMALLINT * NameLengthPtr,
SQLSMALLINT * DataTypePtr,
SQLULEN * ColumnSizePtr,
SQLSMALLINT * DecimalDigitsPtr,
SQLSMALLINT * NullablePtr);
引数
StatementHandle
[入力]ステートメント ハンドル。
ColumnNumber
[入力]1 から始まる列の順序で順番に並べ替えられた結果データの列番号。 引数 ColumnNumber を 0 に設定して、ブックマーク列を記述することもできます。
[ColumnName]
[出力]列名を返す null で終わるバッファーへのポインター。 この値は、IRD の SQL_DESC_NAME フィールドから読み取られます。 列に名前が付いていない場合、または列名を特定できない場合、ドライバーは空の文字列を返します。
ColumnName が NULL の場合でも、NameLengthPtr は、ColumnName が指すバッファーで返すために使用できる文字数 (文字データの null 終端文字を除く) を返します。
BufferLength
[入力]*ColumnName バッファーの長さ (文字数)。
NameLengthPtr
[出力]*ColumnName で返すために使用できる文字数 (null 終了を除く) を返すバッファーへのポインター。 返される文字数が BufferLength 以上の場合、*ColumnName の列名は BufferLength から null 終端文字の長さを引いた値に切り捨てられます。
DataTypePtr
[出力]列の SQL データ型を返すバッファーへのポインター。 この値は、IRD の SQL_DESC_CONCISE_TYPE フィールドから読み取られます。 これは、 SQL データ型の値のいずれか、またはドライバー固有の SQL データ型になります。 データ型を特定できない場合、ドライバーはSQL_UNKNOWN_TYPEを返します。
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 (ブックマーク列の場合) に等しい場合、SQL_BINARYは可変長ブックマークの *DataTypePtr で返されます。 (SQL_INTEGERは、ブックマークが ODBC 3 で使用されている場合に返されます。x ODBC 2 を使用するアプリケーション。x ドライバーまたは ODBC 2。x ODBC 3 を使用するアプリケーション。x ドライバー。)
これらのデータ型の詳細については、「付録 D: データ型」の「SQL データ型 」を参照してください。 ドライバー固有の SQL データ型の詳細については、ドライバーのドキュメントを参照してください。
ColumnSizePtr
[出力]データ ソースの列のサイズ (文字数) を返すバッファーへのポインター。 列のサイズを決定できない場合、ドライバーは 0 を返します。 列サイズの詳細については、「付録 D: データ型」の 「列サイズ、10 進数、転送オクテット長、および表示サイズ 」を参照してください。
DecimalDigitsPtr
[出力]データ ソースの列の 10 進数を返すバッファーへのポインター。 10 進数の桁数を特定できない場合、または該当しない場合、ドライバーは 0 を返します。 10 進数の詳細については、「付録 D: データ型」の 「列のサイズ、10 進数、転送オクテットの長さ、および表示サイズ 」を参照してください。
NullablePtr
[出力]列で NULL 値が許可されるかどうかを示す値を返すバッファーへのポインター。 この値は、IRD の 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。
診断
SQLDescribeCol が SQL_ERROR または SQL_SUCCESS_WITH_INFO を返す場合、関連付けられている SQLSTATE 値を取得するには、HandleType が SQL_HANDLE_STMT で、Handle of StatementHandle を指定して SQLGetDiagRec を呼び出します。 次の表に、 SQLDescribeCol によって一般的に返される SQLSTATE 値の一覧を示し、この関数のコンテキストでそれぞれについて説明します。"(DM)" という表記は、ドライバー マネージャーによって返される SQLSTATEs の説明の前にあります。 特に明記されていない限り、各 SQLSTATE 値に関連付けられた戻りコードはSQL_ERRORされます。
| SQLSTATE | エラー | 説明 |
|---|---|---|
| 01000 | 一般的な警告 | ドライバー固有の情報メッセージ。 (関数はSQL_SUCCESS_WITH_INFOを返します。 |
| 01004 | 文字列データ、右切り捨て | バッファー *ColumnName が列名全体を返すには十分な大きさではないので、列名は切り捨てられました。 *NameLengthPtr では、未使用の列名の長さが返されます。 (関数はSQL_SUCCESS_WITH_INFOを返します。 |
| 07005 | カーソル指定ではない準備済みステートメント | StatementHandle に関連付けられているステートメントは、結果セットを返しませんでした。 説明する列が存在しません。 |
| 07009 | 記述子インデックスが無効です | (DM) 引数 ColumnNumber に指定された値が 0 で、SQL_ATTR_USE_BOOKMARKS ステートメント オプションがSQL_UB_OFFされました。 引数 ColumnNumber に指定された値が、結果セット内の列数より大きかった。 |
| 08S01 | 通信リンクエラー | ドライバーとドライバーが接続されているデータ ソース間の通信リンクは、関数の処理が完了する前に失敗しました。 |
| HY000 | 一般的なエラー | 特定の SQLSTATE がなく、実装固有の SQLSTATE が定義されていないエラーが発生しました。 *MessageText バッファー内の SQLGetDiagRec によって返されるエラー メッセージは、エラーとその原因を説明します。 |
| HY001 | メモリ割り当てエラー | ドライバーは、関数の実行または完了をサポートするために必要なメモリを割り当てることができませんでした。 |
| HY008 | 操作が取り消されました | StatementHandle に対して非同期処理が有効になりました。 関数が呼び出され、実行が完了する前に、 StatementHandle で SQLCancel または SQLCancelHandle が呼び出されました。 その後、 StatementHandle で関数が再度呼び出されました。 関数が呼び出され、実行が完了する前に、マルチスレッド アプリケーションの別のスレッドから StatementHandle で SQLCancel または SQLCancelHandle が呼び出されました。 |
| HY010 | 関数シーケンス エラー | (DM) StatementHandle に関連付けられている接続ハンドルに対して非同期実行関数が呼び出されました。 この非同期関数は、 SQLDescribeCol が 呼び出されたときにまだ実行されていました。 (DM) StatementHandle に対して SQLExecute、SQLExecDirect、または SQLMoreResults が呼び出され、SQL_PARAM_DATA_AVAILABLE返されました。 この関数は、すべてのストリーミング パラメーターのデータが取得される前に呼び出されました。 (DM) 非同期実行関数 (この関数ではなく) が StatementHandle に対して呼び出され、この関数が呼び出されたときにまだ実行されていました。 (DM) 関数は、ステートメント ハンドルで SQLPrepare、 SQLExecute、またはカタログ関数を呼び出す前に呼び出されました。 (DM) StatementHandle に対して SQLExecute、SQLExecDirect、SQLBulkOperations、または SQLSetPos が呼び出され、SQL_NEED_DATA返されました。 この関数は、すべての実行時データ パラメーターまたは列に対してデータが送信される前に呼び出されました。 |
| HY013 | メモリ管理エラー | メモリが不足している可能性があるため、基になるメモリ オブジェクトにアクセスできなかったため、関数呼び出しを処理できませんでした。 |
| HY090 | 文字列またはバッファーの長さが無効です | (DM) 引数 BufferLength に指定された値が 0 未満でした。 |
| HY117 | トランザクションの状態が不明なため、接続が中断されます。 切断と読み取り専用の関数のみが許可されます。 | (DM) 中断状態の詳細については、「 SQLEndTran 関数」を参照してください。 |
| HYT01 | 接続のタイムアウト | データ ソースが要求に応答する前に、接続タイムアウト期間の有効期限が切れています。 接続タイムアウト期間は、 SQLSetConnectAttr (SQL_ATTR_CONNECTION_TIMEOUT) によって設定されます。 |
| IM001 | ドライバーは、この関数をサポートしていません | (DM) StatementHandle に関連付けられているドライバーは、 関数をサポートしていません。 |
| IM017 | 非同期通知モードでポーリングが無効になっている | 通知モデルが使用されるたびに、ポーリングは無効になります。 |
| IM018 | SQLCompleteAsync は、このハンドルで前の非同期操作を完了するために呼び出されていません。 | ハンドルの前の関数呼び出しがSQL_STILL_EXECUTINGを返し、通知モードが有効になっている場合は、処理後に処理を実行して操作を完了するために、 SQLCompleteAsync をハンドルで呼び出す必要があります。 |
SQLDescribeCol は、 SQLPrepare の後と SQLExecute の前に呼び出されたときに SQLPrepare または SQLExecute によって返される SQLSTATE を返すことができます。これは、データ ソースがステートメント ハンドルに関連付けられている SQL ステートメントを評価するタイミングに応じて異なります。
パフォーマンス上の理由から、アプリケーションはステートメントを実行する前に SQLDescribeCol を 呼び出さないでください。
説明
アプリケーションは通常、SQLPrepare の呼び出しの後、および SQLExecute の関連付けられた呼び出しの前後に SQLDescribeCol を呼び出します。 アプリケーションでは、SQLExecDirect の呼び出し後に SQLDescribeCol を呼び出すこともできます。 詳細については、「 結果セットメタデータ」を参照してください。
SQLDescribeCol は 、 SELECT ステートメントによって生成された列名、型、および長さを取得します。 列が式の場合、*ColumnName は空の文字列またはドライバー定義の名前です。
Note
ODBC では、Open Group および SQL Access Group Call Level Interface 仕様で SQLDescribeCol のオプションが指定されていない場合でも、SQL_NULLABLE_UNKNOWNが拡張機能としてサポートされています。
関連する関数
| 対象 | 解決方法については、 |
|---|---|
| 結果セット内の列へのバッファーのバインド | SQLBindCol |
| ステートメント処理の取り消し | SQLCancel |
| 結果セット内の列に関する情報を返す | SQLColAttribute |
| 複数行のデータをフェッチする | SQLFetch |
| 結果セット列の数を返す | SQLNumResultCols |
| 実行のためのステートメントの準備 | SQLPrepare |