GetString

(PWS4 IIS4 IIS5)
GetString — Recordset を文字列として返します。

構文

recordset.GetString(StringFormat, NumRows, ColumnDelimiter, RowDelimiter, NullExpr)

パラメータ

recordset
Recordset オブジェクを指定します。
StringFormat
Recordset を文字列に変換する方法を示す StringFormatEnum 値を指定します。RowDelimiter、ColumnDelimiter、および NullExpr の各パラメータは、StringFormat に adClipString を指定した場合にのみ使用できます。
NumRows
省略可能です。Recordset から変換する行数を指定します。NumRows を指定しない場合、または Recordset の行数の合計より大きい値を指定した場合は、Recordset のすべての行が変換されます。
ColumnDelimiter
省略可能です。列の区切りに使う区切り文字を指定します。指定しなければ、タブが使用されます。
RowDelimiter
省略可能です。行の区切りに使う区切り文字を指定します。指定しなければ、復帰改行が使用されます。
NullExpr
省略可能です。Null 値に入れる式を指定します。指定しなければ、空文字列が使用されます。

戻り値

Recordset をバリアント型 (Variant) 変数 (BSTR) の文字列として返します。

説明

スキーマ データではなく、行のデータが文字列に保存されます。したがって、この文字列を使って Recordset を開くことはできません。

このメソッドは RDO の GetClipString メソッドに相当します。


GetRows

(PWS4 IIS4 IIS5)
GetRows — Recordset オブジェクトの複数のレコードを配列に取り込みます。

構文

recordset.GetRows( Rows, Start, Fields )

パラメータ

recordset
Recordset オブジェクを指定します。
Rows
省略可能です。取得するレコード数を示す GetRowsOptionEnum 値を指定します。既定値は adGetRowsRest です。
Start
省略可能です。GetRows 操作を開始するレコードのブックマークを評価する文字列型 (String) またはバリアント型 (Variant) の値を指定します。BookmarkEnum 値を使用することもできます。
Fields
省略可能です。単一のフィールド名または位置を表すバリアント型 (Variant) の値、あるいは複数のフィールド名または位置を表す値の並びをバリアント型 (Variant) の配列として指定します。指定したフィールドのデータのみが返されます。

戻り値

バリアント型 (Variant) の二次元配列の値を返します。

説明

GetRows メソッドでは、Recordset のレコードを二次元配列にコピーします。最初の添え字でフィールドを指定し、2 番目でレコード番号を指定します。GetRows メソッドからデータが返されると、変数 array は自動的に正しいサイズに調整されます。

Rows 引数の値を指定しない場合は、Recordset オブジェクトのすべてのレコードが取り込まれます。利用可能なレコード数よりも大きい値を指定した場合は、利用可能なレコード数のみが返されます。

ブックマークをサポートする Recordset オブジェクトの場合、Start 引数にレコードの Bookmark プロパティの値を指定すると、GetRows メソッドでデータの取得を開始するレコードを指定できます。

GetRows メソッドで返すフィールドを限定する場合は、Fields 引数に、単一のフィールド名または番号、あるいは、複数のフィールド名または番号の配列を指定します。

GetRows メソッドを呼び出すと、まだ読み込まれていない次のレコードがカレント レコードになります。レコードがそれ以上存在しない場合は、EOF プロパティが True に設定されます。


Find

(PWS4 IIS4 IIS5)
Find — Recordset から、指定した条件を満たす行を検索します。必要に応じて、検索の方向、開始行、および開始行からのオフセットを指定できます。条件が一致すれば、カレント行の位置は、検出されたレコードに設定されます。条件を満たす行がない場合は、カレント行の位置は Recordset の最後 (または最初) に設定されます。

構文

object.Find (Criteria, SkipRows, SearchDirection, Start)

パラメータ

object
Recordset オブジェクを指定します。
Criteria
検索に使用する列の名前、比較演算子、および値を指定するステートメントを含む文字列型 (String) の値を指定します。
SkipRows
省略可能です。検索を開始する、カレント行または Start ブックマークからの行のオフセットを指定する長整数型 (Long) の値を指定します。既定値は 0 です。既定では、カレント行から検索が開始されます。
SearchDirection
省略可能です。検索方向に向かって、カレント行または使用可能な次の行のいずれから検索を開始するかを指定する SearchDirectionEnum 値を指定します。検索に成功しなかった場合、この値に adSearchForward が指定されていると、Recordset の終わりで停止します。また、検索に成功しなかった場合、この値に adSearchBackward が指定されていると、Recordset の先頭で停止します。
Start
省略可能です。検索の開始位置として使用するバリアント型 (Variant) のブックマークを指定します。

説明

criteria には、単一列の名前のみを指定できます。このメソッドでは、複数列の検索はサポートしていません。

Criteria の比較演算子には、”>” (より大きい)、”<" (より小さい)、"=" (等しい)、">=” (以上)、”<=" (以下)、"<>” (等しくない)、または “like” (パターン マッチング) を使用できます。

Criteria の値には、文字列、浮動小数点数、または日付を使用できます。文字列の値は単一引用符または “#” (シャープ記号) で囲みます。たとえば、「state = ‘WA’」または「state = #WA#」のように指定します。日付の値は “#” (シャープ記号) で囲みます。たとえば、「start_date > #7/22/97#」のように指定します。

比較演算子に “like” を使用する場合、文字列値にアスタリスク (*) を含めると、1 つまたは複数の文字または部分文字列を検索することができます。たとえば、「state like ‘M*’」と指定すると、Maine や、Massachusetts が該当します。また、文字列の先頭と末尾にアスタリスクを使用して、その間に含まれる部分文字列を検索することもできます。たとえば、「state like ‘*as*’」と指定すると、Alaska、Arkansas、および Massachusetts が該当します。

前の例のように、アスタリスクは、検索文字列の末尾のみに使用するか、または検索文字列の先頭と末尾の両方で使用することができます。ただし、先頭のみのワイルドカード (‘*str’) または文字列中のワイルドカード (‘s*r’) としてアスタリスクを使用することはできません。この場合は、エラーが発生します。

注意 Find メソッドを呼び出す前にカレント行の位置が設定されていない場合は、エラーが発生します。Find メソッドを呼び出す前に、MoveFirst などの、行の位置を設定するメソッドを呼び出す必要があります。


CompareBookmarks

(PWS4 IIS4 IIS5)
CompareBookmarks — 2 つのブックマークを比較して、相対的な位置を示す値を返します。

構文

result = recordset.CompareBookmarks(Bookmark1, Bookmark2)

パラメータ

Bookmark1
最初の行のブックマークを指定します。
Bookmark2
2 番目の行のブックマークを指定します。

戻り値

ブックマークで表される 2 つのレコードの行位置の相対的な関係を示す CompareEnum 値を返します。

説明

ブックマークは、同じ Recordset オブジェクト、または Recordset オブジェクトとそのクローンに適用する必要があります。異なる Recordset オブジェクトのブックマークを比較した場合、同じソースまたはコマンドで作成されたブックマークであっても、信頼できる結果は得られません。また、 Recordset オブジェクトの基になるプロバイダがブックマークの比較をサポートしていない場合も同様です。

ブックマークは、Recordset オブジェクトの行を一意に識別します。ブックマークを取得するには、カレント行の Bookmark プロパティを使います。

ブックマークのデータ型はプロバイダ固有であるため、データ型はバリアント型で表されます。たとえば、SQL Server のブックマークは、DBTYPE_R8 型 (倍精度浮動小数点数型) です。ADO では、このデータ型は、サブタイプが倍精度浮動小数点型のバリアント型として表されます。

ブックマークを比較するときには、 ADO はどんな種類の強制試行も行いません。値は、そのまま比較が行われるプロバイダに渡されます。CompareBookmarks メソッドに渡されるブックマークに、異なる型の変数が格納されている場合、「引数が間違った型、許容範囲外、または競合しています。」という型不一致エラーが発生します。

無効なブックマークや、不正に作成されたブックマークは、エラーの原因になります。


Delete

(PWS4 IIS4 IIS5)
Delete — カレント レコードまたはレコードのグループを削除します。

構文

recordset.Delete AffectRecords

パラメータ

AffectRecords
Delete メソッドで操作するレコード数を決める AffectEnum 値を指定します。既定値は adAffectCurrent です。

戻り値

値を返しません。

説明

Delete メソッドを使うと、Recordset オブジェクトのカレントレコードまたはレコードのグループは削除の対象としてマークされます。レコードを削除できない Recordset オブジェクトの場合はエラーが発生します。即時更新モードでは、削除は直ちにデータベースに反映されます。レコードの削除に失敗した場合 (データベースの整合性違反などのため)、レコードは Update の呼び出し後も編集モードのままになります。そのため、カレントレコードから移動する (たとえば、Close、Move、または NextRecordset を使用する) 前に、CancelUpdate で更新をキャンセルする必要があります。

バッチ更新モードでは、キャッシュ内の削除されるレコードにマークされますが、実際の削除は UpdateBatch メソッドが呼び出されるまで行われません。(削除されたレコードを参照するには、Filter プロパティを使用します。)

削除されたレコードからフィールド値を取得しようとすると、エラーが発生します。カレントレコードを削除した後は、別のレコードに移動するまで、削除されたレコードがカレントレコードになります。削除されたレコードから移動した後は、そのレコードにアクセスできなくなります。

トランザクションで削除レコードをネストしている場合、RollbackTrans メソッドを使って削除レコードを復活することができます。バッチ更新モードでは、CancelBatch を使って実行されていない削除をキャンセルすることができます。

基になるデータとの競合 (たとえば、ほかのユーザーによってレコードが既に削除されている場合など) が原因でレコードの削除に失敗した場合、プロバイダから Errors コレクションに警告が返されますが、プログラムの実行は停止されません。要求したすべてのレコードで競合が発生した場合にのみ、実行時エラーが発生します。

Unique Table ダイナミック プロパティが設定されており、Recordset が複数のテーブルに対する JOIN 操作の実行結果である場合、Delete メソッドは、Unique Table プロパティで指定されたテーブルからのみ行を削除できます。


Close

(PWS4 IIS4 IIS5)
Close — 開いているオブジェクトおよびそれに従属するすべてのオブジェクトを閉じます。

構文

object.Close

パラメータ

object
Recordset オブジェクを指定します。

戻り値

値を返しません。

説明

Close メソッドを使って、Connection オブジェクト、Record オブジェクト、Recordset オブジェクト、または Stream オブジェクトを閉じ、関連するすべてのシステムリソースを解放します。オブジェクトを閉じてもメモリからは削除されず、プロパティ設定を変更してもう一度開くことができます。メモリからオブジェクトを完全に削除するには、オブジェクトを閉じて、オブジェクト変数を Nothing (Visual Basic の場合) に設定します。

Close メソッドを使って Recordset オブジェクト、Record オブジェクト、または Stream オブジェクトを閉じると、関連するデータと、そのデータに対するこのオブジェクトからの排他アクセスがすべて解放されます。その後で Open メソッドを呼び出して、同じ属性または更新された属性を持つオブジェクトを再度開くことができます。

Recordset オブジェクトが閉じているときに、開いているカーソルを必要とするメソッドを呼び出すと、エラーが発生します。

即時更新モードで編集しているときに Close メソッドを呼び出すと、エラーが発生します。この場合は、先に Update メソッドまたは CancelUpdate メソッドを呼び出してください。バッチ更新モードの実行中に Recordset オブジェクトを閉じると、最後に UpdateBatch メソッドを実行した後に行われた変更がすべて失われます。

Clone メソッドを使って開いている Recordset オブジェクトのコピーを作成した場合、元のオブジェクトまたはクローンを閉じてもほかのコピーには影響しません。


Clone

(PWS4 IIS4 IIS5)
Clone — 既存の Recordset オブジェクトから Recordset オブジェクトの複製を作成します。必要に応じて、複製を読み取り専用に指定できます。

構文

Set rstDuplicate = rstOriginal.Clone (LockType)

パラメータ

rstDuplicate
作成する Recordset オブジェクトの複製を表すオブジェクト変数を指定します。
rstOriginal
複製元の Recordset オブジェクトを表すオブジェクト変数を指定します。
LockType
省略可能です。複製元の Recordset オブジェクトのロックの種類を適用するか、または読み取り専用にするかを LockTypeEnum 値で指定します。有効な値は、adLockUnspecified または adLockReadOnly です。

説明

Clone メソッドを使うと、Recordset オブジェクトの複製を複数作成できます。特に、レコードセットの複数のカレント レコードを保持したい場合に、このメソッドを使用します。Clone メソッドを使うと、同じ定義を設定して新規 Recordset オブジェクトを作成して開くよりも効率的です。

元の Recordset オブジェクトの Filter プロパティは、クローンには適用されません。結果をフィルタするには、新しい Recordset の Filter プロパティを設定します。既存の Filter 値をコピーする最も簡単な方法は、次のように値を直接代入することです。(rsNew.Filter = rsOriginal.Filter)

作成したクローンのカレント レコードは、最初のレコードに設定されます。

1 つの Recordset オブジェクトに加えた変更は、カーソルの種類にかかわらず、すべてのクローンで参照できます。ただし、複製元の Recordset オブジェクトで Requery を実行した後は、クローンは複製元の Recordset オブジェクトと同期しなくなります。

複製元の Recordset を閉じても、そのクローンは開いたままです。また、クローンを閉じても、複製元またはほかのクローンは開いています。

ブックマークをサポートする Recordset オブジェクトだけがクローンを作成できます。ブックマークの値は共通です。したがって、1 つの Recordset オブジェクトのブックマークで、すべてのクローンの同じレコードを参照できます。

発生した Recordset イベントは、すべての Recordset クローンでも発生します。ただし、複製された Recordset 間でカレント レコードが異なる可能性があるため、クローンではそのイベントが無効である場合もあります。たとえば、1 つのフィールドの値を変更すると、変更された Recordset とすべてのクローンで WillChangeField イベントが発生します。変更された Recordset の WillChangeField の Fields パラメータは変更された正しいフィールドを返しますが、複製された Recordset の Fields パラメータではそうならない場合があります。複製された (変更されていない) Recordset の WillChangeField イベントの Fields パラメータは、単にそのクローンのカレント レコードのフィールドを参照するだけであり、そのレコードは、変更が発生した元の Recordset のカレント レコードとは異なる可能性があります。


CancelUpdate

(PWS4 IIS4 IIS5)
CancelUpdate — Update メソッドを呼び出す前に行った、Recordset オブジェクトのカレント行または新規行、または Record オブジェクトの Fields コレクションに加えたすべての変更をキャンセルします。

構文

record.CancelUpdate

パラメータ

record
Recordset オブジェクを指定します。

説明

CancelUpdate メソッドを使って、カレント行に加えた変更をすべてキャンセルしたり、新規に追加した行を破棄します。Update メソッドを呼び出した後は、カレント行または新規行に加えた変更をキャンセルすることはできません。ただし、RollbackTrans メソッドでロールバックできるトランザクションの一部か、またはバッチ更新の一部である場合は除きます。バッチ更新の場合は、CancelUpdate メソッドまたは CancelBatch メソッドで Update をキャンセルできます。

新規行を追加しているときに CancelUpdate メソッドを呼び出すと、AddNew を呼び出す前にカレントであった行がカレント行になります。

編集モードでカレント レコードから移動する (たとえば、Move、NextRecordset、Close などを使用する) 場合は、CancelUpdate を使用してすべての保留中の変更をキャンセルすることができます。データ ソースの更新が成功しなかった場合 (たとえば、参照整合性違反によって削除の試みが失敗したことにより、Delete の呼び出しの後に Recordset が編集モードのままになった場合など) には、この処理が必要になる場合があります。

Recordの場合

CancelUpdate メソッドは、Field オブジェクトの保留中の挿入または削除をすべてキャンセルし、既存のフィールドの保留中の更新をキャンセルして元の値に戻します。Fields コレクションのすべてのフィールドの Status プロパティは、adFieldOK に設定されます。


CancelBatch

(PWS4 IIS4 IIS5)
CancelBatch — 保留中のバッチ更新をキャンセルします。

構文

recordset.CancelBatch AffectRecords

パラメータ

AffectRecords
省略可能です。CancelBatch メソッドで操作するレコード数を示す AffectEnum 値を指定します。

戻り値

値を返しません。

説明

CancelBatch メソッドを使って、バッチ更新モードの Recordset の保留中の更新をすべてキャンセルします。即時更新モードの Recordset では、adAffectCurrent を指定せずに CancelBatch メソッドを呼び出すと、エラーが発生します。

カレントレコードの編集中または新規レコードの追加中に CancelBatch メソッドを呼び出すと、まず、CancelUpdate メソッドが呼び出され、キャッシュされているすべての変更がキャンセルされます。その後で、Recordset の保留中の変更がすべてキャンセルされます。

CancelBatch メソッドの呼び出し後、新規レコードを追加中に呼び出した場合は特に、カレントレコードを特定できない可能性があります。このため、CancelBatch メソッドの実行後に、カレント レコードの位置を Recordset の特定の位置に設定することをお勧めします。たとえば、MoveFirst メソッドを呼び出します。

基になるデータとの競合 (たとえば、ほかのユーザーによってレコードが既に削除されている場合) が原因で未処理の更新がキャンセルできない場合、プロバイダは Errors コレクションに警告を返しますがプログラムの実行は停止しません。要求したすべてのレコードで競合が発生した場合にのみ、実行時エラーが発生します。競合しているレコードを特定するには、Filter プロパティ (adFilterAffectedRecords) と Status プロパティを使用します。


Cancel

(PWS4 IIS4 IIS5)
Cancel — 非同期メソッド呼び出しのうち、保留中のものの実行をキャンセルします。

構文

object.Cancel

パラメータ

object
Recordset オブジェクを指定します。

設定値と戻り値

Cancel メソッドを使って、非同期メソッド (adAsyncConnect、adAsyncExecute、または adAsyncFetch のオプションを指定して呼び出すメソッド) の呼び出しの実行を中止します。

説明

Recordset オブジェクを指定した場合、Openメソッドが中止されます。