entity.save( )

4D v18

entity.save( )

説明

entity.save( ) メソッドはデータクラスにリレートされたテーブル内のエンティティに対する変更を保存します。エンティティを作成したあと、あるいはエンティティに対して保存したい変更を行ったあとにはこのメソッドを呼び出す必要があります。

保存オペレーションは、少なくとも一つのエンティティ属性が"touched"の場合にのみ実行されます(entity.touched( ) およびentity.touchedAttributes( ) メソッドを参考のこと)。そうでない場合、メソッドは何もしません(トリガは呼び出されません)。

マルチユーザー、あるいはマルチプロセスアプリケーションにおいて、entity.save( ) メソッドは"オプティミスティック・ロック"機構のもとで実行されます。これはレコードが保存されるたびに内部的なロックスタンプが自動的に増加していくという機構です。詳細な情報については、エンティティロッキングのページを参照してください。

デフォルトで、mode 引数が省略された場合、修正された属性にかかわらず、同じエンティティが他のプロセスあるいは他のユーザーによって同時に変更された場合にはエラーを返します(以下参照)。
そうでない場合、mode 引数にはdk auto merge オプションを渡すことができます。自動マージモードが有効化されている場合、異なるプロセス/ユーザーによって同時に同じエンティティに変更を行っても異なる属性に対する変更であればエラーは生成されません。エンティティに保存されるデータは、非カレント変更の組み合わせ(あるいは"マージ(併合)")になります(変更が同じ属性に対し行われた場合には、自動マージモードであっても保存は失敗し、エラーが返されます)。

注: 自動マージモードはピクチャー属性、オブジェクト属性、テキスト型属性に対しては、レコード外に保存されている場合には利用できません。これらの属性で変更を結合した場合にはdk status stamp has changed エラーになります。

結果オブジェクト

entity.save( ) によって返されたオブジェクトには以下のプロパティが格納されます:

プロパティ		型	詳細
success		ブール	保存アクションが成功した場合にはtrue、それ以外の場合にはfalse
			*dk auto merge オプションが使用されていた場合にのみ利用可能:*
autoMerged		ブール	自動マージが実行された場合にはtrue、それ以外の場合にはfalse
			*エラーの場合にのみ利用可能:*
status(*)		数値	エラーコード、以下参照
statusText(*)		テキスト	エラーの詳細、以下参照
			*ペシミスティック・ロックエラーの場合にのみ利用可能:*
lockKindText		テキスト	"Locked by record"
lockInfo		オブジェクト	ロックの元についての情報
	task_id	数値	プロセスID
	user_name	テキスト	マシン上でのセッションユーザー名
	user4d_id	テキスト	4Dデータベースディレクトリでのユーザー名
	host_name	テキスト	マシン名
	task_name	テキスト	プロセス名
	client_version	テキスト
			深刻なエラーの場合にのみ利用可能(深刻なエラーとは、プライマリーキーを重複させようとした、ディスクがいっぱいであった、などです):
errors		オブジェクトのコレクション
	message	テキスト	エラーメッセージ
	componentSignature	テキスト	内部コンポーネント署名(例 "dmbg" はデータベースコンポーネントを表します)
	errCode	数値	エラーコード

(*) エラー時にはResult オブジェクトのstatus あるいは statusText プロパティに以下のいずれかの値が返されます:

定数	値	コメント
dk status automerge failed	6	(dk auto merge オプションが使用されたときのみ) エンティティを保存するときに自動マージオプションが失敗しました。割り当てられたstatusText: "自動マージ失敗"
dk status entity does not exist anymore	5	エンティティはもうデータ内に存在していません。このエラーは以下のような場合に起き得ます: エンティティがドロップされている(スタンプは変更されていて、メモリ空間は解放されている) エンテイィ亭はドロップされていて、他のプライマリーキー値を持っているもので置き換えられている(スタンプは変更されていて、新しいエンティティがメモリ空間を使用している)。entity.drop( )を使用している場合、このエラーはdk force drop if stamp changed オプションを使用した場合に返される場合があります。entity.lock( )を使用している場合、このエラーはdk reload if stamp changed オプションを使用した場合に返される場合があります。割り当てられたstatusText: "エンティティはもう存在しません"
dk status locked	3	エンティティはペシミスティック・ロックでロックされています。割り当てられたstatusText: "既にロックされています"
dk status serious error	4	深刻なエラーとは低レベルのデータベースエラー(例:重複キーなど)、ハードウェアエラーなどです。割り当てられたstatusText: "その他のエラー"
dk status stamp has changed	2	エンティティの内部的なスタンプ値がデータ内に保存されているエンティティのものと合致しません(オプティミスティック・ロック)。 entity.save( ) の場合: dk auto merge オプションが使用されていない場合に限りエラー entity.drop( ) の場合: dk force drop if stamp changed オプションが使用されていない場合に限りエラー entity.lock( ) の場合: dk reload if stamp changed オプションが使用されていない場合に限りエラー割り当てられたstatusText: "スタンプが変更されています"

例題 1

新しいエンティティを作成する場合を考えます:

 C_OBJECT($status;$employee)

 $employee:=ds.Employee.new()

 $employee.firstName:="Mary"

 $employee.lastName:="Smith"

 $status:=$employee.save()

 If($status.success)

    ALERT("Employee created")

 End if

例題 2

エンティティをdk auto merge オプションを使わずに更新する場合を考えます:

 C_OBJECT($status;$employees;$employee)

 $employees:=ds.Employee.query("lastName=:1";"Smith")

 $employee:=$employees.first()

 $employee.lastName:="Mac Arthur"

 $status:=$employee.save()

 Case of

    :($status.success)

       ALERT("Employee updated")

    :($status.status=dk status stamp has changed)

       ALERT($status.statusText)

 End case

例題 3

エンティティをdk auto merge オプションを使用して更新する場合を考えます:

 C_OBJECT($status;$employees;$employee)

 

 $employees:=ds.Employee.query("lastName=:1";"Smith")

 $employee:=$employees.first()

 $employee.lastName:="Mac Arthur"

 $status:=$employee.save(dk auto merge)

 Case of

    :($status.success)

       ALERT("Employee updated")

    :($status.status=dk status automerge failed)

       ALERT($status.statusText)

 End case

参照

entity.drop( )
entity.getStamp( )
entity.isNew( )