SQLSetStmtAttr 関数

準拠
導入されたバージョン: ODBC 3.0 標準コンプライアンス: ISO 92

まとめ
SQLSetStmtAttr は、 ステートメントに関連する属性を設定します。

構文

  
SQLRETURN SQLSetStmtAttr(  
     SQLHSTMT      StatementHandle,  
     SQLINTEGER    Attribute,  
     SQLPOINTER    ValuePtr,  
     SQLINTEGER    StringLength);  

引数

StatementHandle
[入力]ステートメント ハンドル。

属性
[入力][コメント] に表示される、設定するオプション。

ValuePtr
[入力]属性に関連付ける値。 Attribute の値に応じて、ValuePtr は次のいずれかになります。

• ODBC 記述子ハンドル。

• SQLUINTEGER 値。

• SQLULEN 値。

• 次のいずれかを指すポインター。

  • null で終わる文字列。

  • バイナリ バッファー。

  • SQLLEN、SQLULEN、または SQLUSMALLINT 型の値または配列。

  • ドライバー定義の値。

Attribute 引数がドライバー固有の値の場合、ValuePtr は符号付き整数である可能性があります。

StringLength
[入力]Attribute が ODBC で定義された属性で、ValuePtr が文字列またはバイナリ バッファーを指している場合、この引数は *ValuePtr の長さである必要があります。 属性が ODBC で定義された属性で、ValuePtr が整数の場合、StringLength は無視されます。

属性がドライバー定義の属性の場合、アプリケーションは、StringLength 引数を設定することによって、ドライバー マネージャーに属性の性質を示します。 StringLength には、次の値を指定できます。

• ValuePtr が文字列へのポインターの場合、StringLength は文字列またはSQL_NTSの長さです。

• ValuePtr がバイナリ バッファーへのポインターである場合、アプリケーションは SQL_LEN_BINARY_ATTR(length) マクロの結果を StringLength に配置します。 これにより、StringLength に負の 値が配置されます。

• ValuePtr が文字列またはバイナリ文字列以外の値へのポインターである場合、StringLength には値SQL_IS_POINTER必要があります。

• ValuePtr に固定長の値が含まれている場合、StringLength は必要に応じてSQL_IS_INTEGERまたはSQL_IS_UINTEGERです。

返品

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、またはSQL_INVALID_HANDLE。

診断

SQLSetStmtAttr がSQL_ERRORまたはSQL_SUCCESS_WITH_INFOを返す場合、関連付けられている SQLSTATE 値を取得するには、SQL_HANDLE_STMTの HandleType と StatementHandle のハンドルを使用して SQLGetDiagRec を呼び出します。 次の表に、SQLSetStmtAttr によって一般的に返される SQLSTATE 値を示し、この関数のコンテキストでそれぞれについて説明します。表記 "(DM)" は、ドライバー マネージャーによって返される SQLSTATEs の説明の前にあります。 特に明記されていない限り、各 SQLSTATE 値に関連付けられている戻りコードはSQL_ERROR。

Comments

ステートメントのステートメント属性は、SQLSetStmtAttr の別の呼び出しによって変更されるまで、または SQLFreeHandle を呼び出してステートメントが削除されるまで有効です。 SQL_CLOSE、SQL_UNBIND、または SQL_RESET_PARAMS オプションを使用して SQLFreeStmt を呼び出しても、ステートメント属性はリセットされません。

一部のステートメント属性は、データ ソースが ValuePtr で指定された値をサポートしていない場合に、同様の値の 置換をサポートします。 このような場合、ドライバーはSQL_SUCCESS_WITH_INFOと SQLSTATE 01S02 を返します (オプション値が変更されました)。 たとえば、 Attribute がSQL_ATTR_CONCURRENCYで ValuePtr がSQL_CONCUR_ROWVERされている場合、データ ソースがこれをサポートしていない場合、ドライバーはSQL_CONCUR_VALUESを置き換え、SQL_SUCCESS_WITH_INFOを返します。 置換された値を特定するために、アプリケーションは SQLGetStmtAttr を呼び出します。

ValuePtr で設定される情報の形式は、指定された属性によって異なります。 SQLSetStmtAttr は、2 つの異なる形式 (文字列または整数値) のいずれかで属性情報を受け取ります。 それぞれの形式は属性の説明に記載されています。 この形式は、SQLGetStmtAttr の各属性に対して返される情報に適用されます。 SQLSetStmtAttr の ValuePtr 引数が指す文字列の長さは StringLength です。

記述子フィールドを設定するステートメント属性

多くのステートメント属性は、記述子のヘッダー フィールドに対応しています。 これらの属性を設定すると、実際には記述子フィールドが設定されます。 SQLSetDescField ではなく SQLSetStmtAttr の呼び出しによってフィールドを設定すると、関数呼び出しに記述子ハンドルを取得する必要がないという利点があります。

対応するステートメント属性が設定された結果として記述子フィールドが設定された場合、このフィールドは、StatementHandle 引数によって識別されるステートメントに現在関連付けられている適用可能な記述子に対してのみ設定され、属性設定は将来そのステートメントに関連付けられる記述子には影響しません。 ステートメント属性でもある記述子フィールドが SQLSetDescField の呼び出しによって設定されると、対応するステートメント属性が設定されます。 明示的に割り当てられた記述子がステートメントから関連付け解除されている場合、ヘッダー フィールドに対応するステートメント属性は、暗黙的に割り当てられた記述子のフィールドの値に戻ります。

ステートメントが割り当てられると (SQLAllocHandle を参照)、4 つの記述子ハンドルが自動的に割り当てられ、ステートメントに関連付けられます。 明示的に割り当てられた記述子ハンドルをステートメントに関連付けるには、SQL_HANDLE_DESCの fHandleType で SQLAllocHandle を呼び出して記述子ハンドルを割り当て、SQLSetStmtAttr を呼び出して記述子ハンドルをステートメントに関連付けます。

次の表のステートメント属性は、記述子ヘッダー フィールドに対応しています。

ステートメント属性

現在定義されている属性と、その属性が導入された ODBC のバージョンを次の表に示します。さまざまなデータ ソースを利用するために、ドライバーによってより多くの属性が定義されることが予想されます。 属性の範囲は ODBC によって予約されています。ドライバー開発者は、オープン グループから独自のドライバー固有の使用のために値を予約する必要があります。 詳細については、「ドライバー固有のデータ型、記述子の種類、情報の種類、診断型、および属性」を参照してください。

[1] これらの関数は、記述子が実装記述子であり、アプリケーション記述子ではない場合にのみ非同期的に呼び出すことができます。

列方向のバインドと行方向のバインドを参照してください。

関連する関数

参照

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