RDB::DataSet

super class

class methods

new : RDB::DataSet

methods

open : nil

データセットを開きます。

close : nil

データセットを閉じます。

self[i] : RDB::Field

[] は，データセット内で指定した項目を検索します。

VCL

find_field, field_by_name

[] を呼び出すと，指定した項目コンポーネントがデータセット内に存在するかどうかを判定できます。 i は検索する項目の名前 ( String ) またはインデックス ( Fixnum ) です。
項目が見つかった場合は， [] は指定した項目の RDB::Field オブジェクトを返します。それ以外の場合は， nil を返します。

fields : RDB::Fields

データセットのすべての非集計項目コンポーネントをリストします。

fields は，項目コンポーネントにアクセスできるようにします。項目が実行時に動的に生成されたのであれば， fields 内での項目コンポーネントの順序は，データセットの基になるテーブル内の列の順序と同じです。データセットが静的項目を使用している場合は，項目コンポーネントの順序は設計時に項目エディタで項目を指定した順序と同じです。

object_view が true ならば，項目は階層的に格納されます。つまり，オブジェクト項目の子項目がすべてそのオブジェクト項目によって参照され， RDB::Fields#fields のオブジェクト項目の後でシーケンシャルに表示されません。 object_view が false ならば，項目はシーケンシャルに格納されます ( フラットに格納されます ) 。つまり，オブジェクト項目の子項目がすべて RDB::Fields#fields にシーケンシャルに格納されます。

fields を使った項目へのアクセスは，次のような場合に便利です。

• データセット内の一部またはすべての項目に対して処理を繰り返す
• 実行時に，そのテーブルの内部データ構造がわからない
  アプリケーションで個々の項目のデータ型がわかっている場合は， fields を使って個々の項目値を読み書きすることができます。たとえば，次の文では項目値を編集ボックスの text に割り当てます。

edit1.text = cust_table.fields[6].to_s
# edit1.text = cust_table[6].to_s

注意

項目値の取り出しおよび割り当てには，持続的項目または [] を使うのが適切な方法です。

次の文では，編集ボックスの値を項目に割り当てます。

cust_table.edit
cust_table.fields[6] = edit1.text
# cust_table[6] = edit1.text
cust_table.post

注意

agg_fields は，すべてのデータセットの集合項目のコレクションです。したがって， agg_fields と fields はデータセットの項目の相互に排他的なコレクションです。これら 2 つのプロパティにすべてのデータセットの項目が含まれます。

first : nil

データセット内の最初のレコードにカーソルを移動します。

first を呼び出すと，データセット内の最初のレコードにカーソルを移動し，そのレコードをアクティブレコードにすることができます。 First はアクティブレコードに対するすべての変更を登録し，次の処理を実行します。

1. レコードバッファをクリアする
2. カーソルをデータセットの先頭に設定する
3. 最初のレコードを取り出し，カーソルをそのレコードに移動して，そのレコードをアクティブレコードにする
4. グリッドコントロールを埋めるためのデータなど，表示に必要な次のレコードを取り出す
5. bof を true に設定する
6. データコントロールおよびリンクされている詳細データセットが更新できるようにレコードの変更をブロードキャストする

last : nil

データセット内の最後のレコードにカーソルを移動します。

last を呼び出すと，データセット内の最後のレコードにカーソルを移動し，そのレコードをアクティブレコードにすることができます。 last はアクティブレコードに対するすべての変更を登録し，次の処理を実行します。

1. レコードバッファをクリアする
2. カーソルをデータセットの最後に設定する
3. 最後のレコードを取り出し，カーソルをそのレコードに移動してアクティブレコードにする
4. グリッドコントロールを埋めるためのデータなど，表示に必要な追加レコードを取り出す。
5. eof を true に設定する
6. データコントロールおよびリンクされている詳細データセットが更新できるようにレコードの変更をブロードキャストする

next : nil

データセット内の次のレコードにカーソルを移動します。

next を呼び出すと，データセット内の次のレコードにカーソルを移動し，そのレコードをアクティブレコードにすることができます。 next はアクティブレコードに対するすべての変更を登録し，次の処理を実行します。

1. before_scroll のイベントハンドラを呼び出す
2. bof および eof を false に設定する
3. 次のレコードを取り出し，カーソルをそのレコードに移動して，そのレコードをアクティブレコードにする
4. グリッドコントロールを埋めるためのデータなど，表示に必要な追加レコードを取り出す
5. カーソルがすでにデータセット内の最後のレコードにある場合は eof を true に設定する
6. データコントロールおよびリンクされている詳細データセットが更新できるようにレコードの変更をブロードキャストする

prior : nil

データセット内の前にレコードにカーソルを移動します。

prior を呼び出すと，データセット内の前のレコードにカーソルを移動し，そのレコードをアクティブレコードにすることができます。 prior はアクティブレコードに対するすべての変更を登録し，次の処理を実行します。

1. before_scroll のイベントハンドラを呼び出す
2. bof および eof を false に設定する
3. 前のレコードを取り出し，カーソルをそのレコードに移動して，そのレコードをアクティブレコードにする
4. グリッドコントロールを埋めるためのデータなど，表示に必要な追加レコードを取り出す。
5. カーソルがすでにデータセット内の最初のレコードにある場合は bof を true に設定する
6. データコントロールおよびリンクされている詳細データセットが更新できるようにレコードの変更をブロードキャストする

move_by(distance: Fixnum) : Fixnum

データセット内のアクティブレコードに相対する位置にカーソルを移動します。

move_by を呼び出すと，データセット内のアクティブレコードに相対する位置にカーソルを移動できます。 distance は移動するレコード数を示します。 distance が正の値である場合は次に進みます。 distance が負の値である場合は前に戻ります。 たとえば，次の文では， 10 レコード分前に戻ります。

move_by(-10)

move_by はアクティブレコードに対する変更をすべて登録し，次の処理を実行します。

1. before_scroll のイベントハンドラを呼び出す
2. bof および eof を false に設定する
3. distance が正の値の場合は，可能ならば distance の値を 0 になるまでデクリメントしながら繰り返しそれ以降のレコードを取得し，カーソルを最後に取得したレコードに移動し，そのレコードをアクティブレコードにする。ファイルの最後を超える移動を試みると， move_by は eof を true に設定する
4. distance が負の値の場合は，可能ならば distance の値を 0 になるまでインクリメントしながら繰り返し前にあるレコードを取得し，カーソルを最後に取得したレコードに移動し，そのレコードをアクティブレコードにする。ファイルの先頭を超える移動を試みると， move_by は bof を true に設定する
5. データベース対応コントロールおよびリンクされているデータセットが更新されるようにレコード変更についての情報をブロードキャストする
6. 実際に移動したレコード数を返す。ほとんどの場合，返り値は distance の絶対値になる。ただし， distance 分のレコードを移動する前にファイルの先頭または最後に到達した場合は，返り値は distance の絶対値より小さい値になる

edit : nil

データセット内のデータを編集できるようにします。

edit を呼び出すと，データセット内のアクティブレコードを編集可能にすることができます。 edit はデータセットの現在の状態を変更します。データセットが空ならば， edit は insert を呼び出します。それ以外の場合は， edit は次の処理を実行します。

1. check_browse_mode を呼び出して，未処理の変更があればそれを前のレコードに登録する
2. before_edit イベントハンドラを呼び出す
3. レコードを取り出す
4. データセットの状態を DS_EDIT にして，アプリケーションまたはユーザーがレコード内の項目を変更できるようにする
5. 関連付けられているコントロールに状態の変更をブロードキャストする
6. after_edit イベントハンドラを呼び出す
   編集が終了したら post を呼ぶことで変更されたレコードがデータベースに書き込まれます。
   
   

post : nil

変更されたレコードをデータベースに書き込む仮想メソッドです。

RDB::DataSet オブジェクトは変更されたレコードをデータベースに書き込む仮想メソッドを実装します。 edit ， insert ， append などのようにデータセットの状態を変更したり， first ， last ， next ， prior などのようにあるレコードから別のレコードへ移動するデータセットメソッドは，自動的に post を呼び出します。 RDB::DataSet のすべての下位オブジェクトは，データベースへレコードを書き込むために post を再宣言して実装します。

append : nil

データセットの最後に新しい空のレコードを追加します。

append は，次の手順でレコードを追加します。

1. データセットの最後で新しい空のレコードを開く
2. アクティブレコードを新しいレコードに設定する
   append を呼び出した後，アプリケーションはユーザーがそのレコードの項目にデータを入力できるようにし，次に，変更内容を post ( または apply_updates ，キャッシュアップデートが有効な場合 ) を使ってデータベースに登録することができます。新たに追加されたレコードは，次のいずれかの方法でデータベースに登録されます。
   

• インデックスの付いた Paradox および dBASE テーブルの場合，レコードはインデックスに基づいたデータセット内の位置に挿入される
• インデックスの付いていない Paradox および dBASE テーブルの場合，レコードはデータセット内の最後に追加される
• SQL データベースの場合，追加されたレコードの物理位置は実装によって異なる。インデックス付きテーブルの場合，インデックスが新しいレコードの情報で更新される

insert : nil

新しい空のレコードをデータセットに挿入します。

insert を呼び出すと，次の手順でレコードを挿入します

1. データセット内で新しい空のレコードを開く
2. アクティブレコードを新しいレコードに設定する
   insert を呼び出した後，アプリケーションはユーザーがそのレコードの項目にデータを入力できるようにし，次に， post ( または apply_updates ，キャッシュアップデートが有効な場合 ) を使って変更内容をデータベースに登録することができます。新たに挿入されたレコードは，次のいずれかの方法でデータベースに登録されます。
   

• 一次インデックスの付いた Paradox テーブルの場合，レコードはインデックスに基づいたデータセット内の位置に挿入される
• 一次インデックスの付いていない Paradox テーブルの場合，レコードはデータセット内の現在のカーソル位置に挿入される
• dBASE ， FoxPro ，および Access テーブルの場合，レコードはデータセットの最後に物理的に追加される。インデックスがアクティブになった場合，新しいレコードがインデックスに関連した位置に表示されることもあるが，レコードは実際にはテーブルの最後に格納されている
• SQL データベースの場合，追加先の物理位置は実装によって異なる。インデックスの付いたテーブルの場合，インデックスが新しいレコードの情報で更新される

delete : nil

アクティブレコードを削除し，カーソルを次のレコードに移動します。

delete を呼び出すと，アクティブレコードをデータベースから削除できます。データセットがアクティブでない場合は， delete は例外を生成します。それ以外の場合は， delete は次の処理を実行します。

1. データセットが空でないことを確認する ( 空の場合は例外が生成される )
2. check_browse_mode を呼び出して，未処理の変更があればそれを前のレコードに登録する
3. before_delete イベントハンドラを呼び出す
4. レコードを削除する
5. レコードに割り当てられていたバッファを解放する
6. データセットを DS_BROWSE モードに設定する
7. データセットを同期し直してカーソルを次の削除されていないレコードに置く
8. after_delete イベントハンドラを呼び出す
9. after_scroll イベントハンドラを呼び出す

locate(key_field, key_value, options) : boolean

locate は，指定したレコードをデータセット内で検索し，そのレコードをアクティブレコードにします。DataSet の下位クラス（ Table, Query ）で使えます。

key_field

検索したい項目名

key_value

検索したい値

options : Array of Fixnum (TLocateOptions)

LO_CASE_INSENSITIVE

大文字小文字の区別なし

LO_PARTIAL_KEY

部分一致

• 利用可能なインデックスがあればそれを使って高速に検索します。

locate_ex(key_field, key_value) : Boolean

基本的には locate と同じですが、部分一致で見つかるまでキーを縮小します。ただし 10 回試みて見つからない場合には false を返します。

• rdb.rb による拡張仕様です。

properties

state : Fixnum (DataSetState)

データセットの現在の操作モード

state を調べると，データセットの現在の操作モードを判定できます。 state はデータセット内のデータについてどんな操作 ( たとえば，既存レコードの編集や新しいレコードの挿入など ) を行うことができるかを表します。アプリケーションがデータを処理するのにつれて，データセットの状態は常に変化します。

データセットを開くと， state は DS_INACTIVE から DS_BROWSE へと変更されます。アプリケーションは edit を呼び出してデータセットの状態を DS_EDIT に変えたり， insert を呼び出してデータセットの状態を DS_INSERT に変えたりすることができます。データセットが Table オブジェクトの場合は，アプリケーションは set_key または set_range を呼び出して，データセットの状態を DS_SET_KEY に変えることができます。

編集，挿入，削除，変更を登録したり取り消したりすると， state は現在の状態から DS_BROWSE へと変わります。データセットを閉じると，現在の状態から DS_INACTIVE へと変わります。

DS_CALC_FIELDS ， DS_FILTER ， DS_NEW_VALUE ， DS_OLD_VALUE ， DS_CUR_VALUE など，一部の状態は，アプリケーションから直接見たり，設定したりすることはできません。これらの状態は， on_calc_field および on_filter_record イベントが発生したとき，またはアプリケーションが特定の項目プロパティにアクセスしたときに自動的に設定されます。

bof? : Boolean

カーソルがデータセットの最初のレコードにあるかどうか

bof ( ファイルの先頭 ) を参照すると，カーソルがデータセットの最初のレコードにあるかどうかを判別できます。 bof が true ならば，カーソルはデータセットの最初の行にあります。 bof が true になるのは，アプリケーションが以下の処理を行ったときです。

• データセットを開いた直後
• データセットの first を呼び出した
• データセットの prior を呼び出したが，失敗した ( カーソルがすでにデータセットの最初の行にあったため )
• 空の範囲またはデータセットに対して set_range を呼び出した
  その他の場合 bof はすべて false です。
  
  

eof? : Boolean

カーソルがデータセットの最後のレコードにあるかどうか

eof ( ファイルの最後 ) を参照すると，カーソルがデータセットの最後のレコードにあるかどうかを判別できます。 eof が true ならば，カーソルは確実にデータセットの最後の行にあります。 eof が true になるのは，アプリケーションが以下の処理を行ったときです。

• 空のデータセットを開いた
• データセットの last を呼び出した
• データセットの next を呼び出したが，失敗した ( カーソルがすでにデータセットの最後の行にあったため )
• 空の範囲またはデータセットに対して set_range を呼び出した
  その他の場合 eof はすべて false です。
  
  

  参考

  eof と bof がいずれも true ならば，データセットまたは範囲は空です。
  
  

active : Boolean

データセットが開いているかどうかを示します。

active は，データセットとデータベース内のデータとの接続を判定したり設定したりできます。

active が false ならば，データセットは閉じられており，データセットはデータベースからデータを読み出したり，データベースにデータを書き込んだりすることはできません。

active が true ならば，データベースからデータを読み出したり，データベースにデータを書き込んだりすることができます。

active を true に設定すると，以下の処理を行うことができます。

• before_open を呼び出す。
• データセットの状態を DS_BROWSE に設定する。
• データセットを open する。
• after_open を呼び出す。
  データセットを open するときにエラーが発生した場合，データセットの状態は DS_INACTIVE に設定され，データセットは閉じます。
  
  アプリケーションは，データベースのステータスに影響を及ぼす他のプロパティや，アプリケーションでデータを表示するコントロールを変更する前に， active を false に設定する必要があります。
  
  

  注意

  open メソッドを呼び出すと active は true に設定され， close メソッドを呼び出すと active は false に設定されます。
  
  

auto_calc_fields : Boolean

auto_calc_fields は， calc_fields event の発生を制御します。

auto_calc_fields を設定すると，データセット処理中に計算項目を更新するために，いつ calc_fields event が発生するかを制御できます。計算項目は値をアクティブレコード内の 1 つまたは複数の項目の値から派生させ，場合によってはその値に追加処理を行う項目です。

auto_calc_fields が true ならば ( デフォルト ) ， calc_fields event は次の場合に発生します。

• データセットが開いた。
• データセットの状態が DS_EDIT になった。
• フォーカスが 1 つの可視コントロールから別の可視コントロールへ，またはデータベース対応グリッドの 1 つの列から別の列へ移り，レコードに変更が加えられた。
• データベースからレコードを取り出した。
  アプリケーションがユーザーによるデータの変更を許可している場合は， calc_fields event は頻繁に発生します。
  
  そのような場合には， auto_calc_fields を false に設定すれば， on_calc_fields が呼び出される回数を少なくすることができます。
  
  auto_calc_fields が false ならば，レコード内の個々の項目に変更が加えられたときに on_calc_fields は呼び出されません。
  
  

auto_refresh : Boolean

サーバーによって生成された項目値が自動的に再フェッチされるかを指定します。 auto_refresh が false( デフォルト ) の場合，レコードがポストされたときに自動インクリメント項目およびデフォルト値を含む項目に対してサーバーが作成する値は，データセットによって自動的に再フェッチされません。かわりに，アプリケーションは，データセットの refresh を呼び出してこれらの項目値を更新する必要があります。

auto_refresh が true の場合，これらの項目値は， refresh を明示的に呼び出さずに自動的に更新できます。

注意

データベースドライバによっては，どの項目が自動インクリメント項目か，またはどの項目がデフォルト値を含むかを判断できません。このような場合には，更新する必要があるすべての項目の auto_generate_value を設定して，この情報を提供する必要があります。同様に，データセットが問い合わせまたはストアドプロシージャを表す場合にも，項目コンポーネントの auto_generate_value を設定する必要があります。

cached_updates :

database_name :

default_index :

filter :

filter_options :

filtered :

object_view :

session_name :

update_mode :

event handlers

after_cancel

after_close

after_delete

after_edit

after_insert

after_open

after_post

after_scroll

before_cancel

before_close

before_delete

before_edit

before_insert

before_open

before_post

before_scroll

on_calc_fields

on_delete_error(action, e) : action

アプリケーションがレコードを削除しようとして例外が生成されたときに発生します。

on_delete_error イベントハンドラを記述すると，アプリケーションがレコードを削除しようとして失敗したときに発生する例外を処理することができます。 DataSet はレコードの削除に失敗したデータセットです。 e は，例外エラーメッセージが入ったデータベースエラーオブジェクトです。これによりアプリケーションはエラーメッセージを表示できるようになります。 action はこのデータセットがエラーにどのように応答するかを示します。

on_delete_error が呼び出されたときは， action は必ず DA_FAIL に設定されています。エラーハンドラが自分を呼び出したエラー状態を訂正できる場合は， action を DA_RETRY に設定してからハンドラを終了します。 action が DA_RETRY のときは，削除処理が再試行されます。エラー状況が訂正できない場合， action を DA_FAIL ではなく DA_ABORT に設定すれば，エラーメッセージが表示されないようにすることもできます ( 必要な場合 ) 。

on_edit_error

on_filter_record

on_new_record

on_post_error