このコマンドによりオブジェクトレコードの個々の属性を削除、追加、
修正することが可能となります。オブジェクトはオブジェクト ID
object_to_changeにより指定します。最初の
配列 remove は、削除する属性のリストです。
二番目の配列 add は、加えたい属性のリストです。
ある属性を修正するためには、古い属性を削除し、新規に追加する
必要があります。hw_modifyobject() は、
削除する属性の値が文字列または配列でない限り、つねに属性を追加する前に
属性の削除を行います。
最後のパラメータは、修正を再帰的に行うかどうかを指定します。 1 は、再帰的な修正を意味します。オブジェクトのいくつかを修正できない 場合、通知されることなくスキップされます。 hw_error() は、いくつかのオブジェクトが 修正されなかったことからエラーを発生しない可能性があります。
二つの配列のキーは属性の名前です。各配列要素の値は、配列または文字列 またはその他のものとすることができます。配列の場合、各属性の 値は、各要素のキーにコロンと各要素の値を加えたものから構成されます。 文字列の場合、属性の値として指定します。空文字列を指定すると その属性は完全に削除されます。値が文字列でも配列でもなく、整数の ような他のものである場合、その属性に関して処理は全く行われません。 このような動作は、既存の属性に新規の値を追加するのではなく、 完全に新規の属性を追加したい場合に必要です。remove 配列がその属性に 関する空の文字列を含む場合、値が存在しないため、その属性の削除は 失敗します。続いてその属性に新規の値を追加する処理も同じく失敗します。 属性の値を例えば 0 に設定すると削除することさえできませんが、 加算は実行可能です。
値 'books' を有する属性 'Name' を 'articles' に変更したい場合、 二つの配列を作成し、hw_modifyobject() をコールする 必要があります。
注意: 'Title' のような多言語属性は、2つの方法で修正可能です。 この場合、 'language':'title' という基本形式で属性の値を与えるか、 下記のように各言語毎に配列の要素を与えることにより指定します。 まずは、以下の例を見てみましょう。
注意: この例では、 'Title' という名前の属性を全て削除し、 属性 'Title' を新規に追加しています。 全ての属性を再帰的に削除したい場合には、これは簡便な方法です。
注意: ある名前を有する全ての属性を削除する必要がある場合には、 属性の値として空の文字列を渡してください。
注意: 属性 'Title', 'Description' , 'Keyword' のみが 言語指定用の接頭辞を正しく処理します。 これらの属性において言語指定用接頭辞が指定されていない場合、 接頭辞 'xx' が割りつけられます。
注意: 'Name' 属性もやや特殊です。いくつかの場合には、完全に削除することは できません。 'Change of base attribute' というエラーメッセージが発生する可能性が あります(いつこのエラーが発生するかは明らかではありません) 。 このため、新しい Name をまず追加してから、古いものを削除する 必要があります。
注意: この関数のコールの前後に hw_getandlock() および hw_unlock() をコールする必要はありません。 hw_modifyobject() は内部的にこの処理を 行います。
成功した場合に TRUE を、失敗した場合に FALSE を返します。