リテラル・プロパティの定義と使用

リテラル・プロパティの定義

リテラル・プロパティをクラス定義に追加するには、以下のいずれかのような要素をクラスに追加します。

Property PropName as Classname;

Property PropName as Classname [ Keywords ] ;

Property PropName as Classname(PARAM1=value,PARAM2=value) [ Keywords ] ;

Property PropName as Classname(PARAM1=value,PARAM2=value) ;

以下はその説明です。

• PropName は、プロパティの名前です。

• Classname は、このプロパティが基づくクラスです。これを省略すると、Classname は %StringOpens in a new tab であると見なされます。このプロパティをリテラル・プロパティとして定義するには、Classname を省略するか、Classname をデータ型クラスの名前として指定します。この章で後述する、“一般的なデータ型クラス” を参照してください。カスタムのデータ型クラスも使用できます。

• Keywords はプロパティ・キーワードを表します。このドキュメントで前述した “コンパイラ・キーワード” を参照してください。この章の後続のセクションでは、追加のキーワードについて説明します。

• PARAM1、PARAM2 などはプロパティ・パラメータです。使用可能なパラメータは、プロパティで使用されるクラスによって異なります。この章の後続のセクションでは、最も一般的なプロパティ・パラメータのリストを示します。

プロパティ・パラメータを含める場合は、パラメータを括弧で囲み、プロパティ・キーワードの前に置きます。プロパティ・キーワードを含める場合、キーワードは角括弧で囲みます。

例

例えば、クラスでは %IntegerOpens in a new tab データ型クラスを使用して、Count プロパティを定義できます。

Property Count As %Integer;

%IntegerOpens in a new tab がデータ型クラスなので、Count はデータ型プロパティになります。

データ型パラメータを使用して、データ型プロパティの許容値を制限できます。例えば、タイプ %IntegerOpens in a new tab のプロパティには、MAXVAL パラメータを指定できます。

Property Count As %Integer(MAXVAL = 100);

データ型プロパティ値を空文字列に設定するには、以下の形式のコードを使用します。

 Set object.Property = $C(0)

すべてのプロパティに照合タイプがあります。これにより、値を並べる方法 (先頭文字の大文字化が有効かどうかなど) が決まります。文字列の既定の照合タイプは、SQLUPPER です。照合の詳細は、"Caché SQL の使用法" の “Caché SQL の基礎” の章にある “データ照合” を参照してください。

プロパティの初期値式の定義

既定では、新しいオブジェクトを作成したときに、それぞれのプロパティは NULL になります。その代わりに、特定のプロパティの初期値として使用するように、ObjectScript 式を指定できます。式はオブジェクトが作成されるときに評価されます。

プロパティの初期値式を指定するには、プロパティ定義に InitialExpression キーワードを含めます。

Property PropName as Classname [ InitialExpression=expression ] ;

この expression は ObjectScript 式です (この式には、別の言語を使用できない点に注意してください)。詳細は、"Caché クラス定義リファレンス" の "InitialExpression" を参照してください。

必須としてのプロパティの定義

このオプションは、永続クラスのプロパティにのみ適用されます。(このオプションはリテラル・プロパティだけでなく、任意の種類のプロパティに適用されます。)

既定では、新しいオブジェクトを保存するときに、Caché は、そのオブジェクトのプロパティが NULL 以外の値を持つことを必要としません。プロパティは、NULL 以外の値を必要とするように定義できます。そのためには、プロパティ定義に Required キーワードを含めます。

Property PropName as Classname [ Required ] ;

これにより、プロパティに NULL 値を持つオブジェクトを保存しようとすると、Caché は以下のエラーを発行するようになります。

ERROR #5659: Property required

Required キーワードは SQL アクセスを使用したこのクラスのデータの挿入または変更の方法にも影響を及ぼします。特に、レコードの挿入または更新をする際に値が欠落しているとエラーが発生します。

計算プロパティの定義

Caché では、計算プロパティを定義できます。計算プロパティの値は ObjectScript で計算されます (他のプロパティに基づく場合もあります)。一般的なフレーズの計算プロパティ (または計算フィールド) には、以下のバリエーションの両方が含まれます。

• Always computed (常に計算) — このプロパティの値は、アクセスされるときに計算されます。データベースには保存されません。

• Triggered computed (トリガによって計算) — このプロパティの値は、トリガされたときに再計算されます (詳細は下記を参照)。

  プロパティが永続クラスで定義される場合、その値はデータベースに保存されます。

どちらの場合も、オブジェクト・アクセスや SQL クエリを使用するかどうかに関係なく、再計算が実行されます。

プロパティ・キーワードは 5 つあります (SqlComputed、SqlComputeCode、SqlComputeOnChange、Transient、Calculated)。これらはプロパティ計算の是非と、計算方法を制御します。以下のテーブルに可能な組合せをまとめます。

計算プロパティを定義するには、以下の手順を実行します。

• プロパティ定義に SqlComputed キーワードを含めます。(つまり、SqlComputed キーワードを true に指定します。)

• プロパティ定義に SqlComputeCode キーワードを含めます。このキーワードの値には、プロパティの値を設定する ObjectScript コードの行を指定します (中括弧で囲む)。このとき、"Caché クラス定義リファレンス" のリファレンス “プロパティ・キーワード” にある “SqlComputeCode” で規定された規則に従います。以下に例を示します。

  Property FullName As %String [ SqlComputeCode = {set {*}={FirstName}_" "_{LastName}}, SqlComputed ];
  

  

• プロパティが常に計算されるようにするには、プロパティ定義で Calculated キーワードを true に指定します。

  また、プロパティがトリガによって計算されるようにする場合は、Calculated および Transient キーワードをプロパティ定義に含めません。(つまり、必ず両方のキーワードを false にします。)

• プロパティがトリガによって計算される場合は、必要に応じて SqlComputeOnChange を指定します。

  このキーワードは 1 つ以上のプロパティを指定できます。これらのプロパティの値が変更されると、トリガされたプロパティは再計算されます。プロパティ名には、SqlFieldName で指定された名前 (この章で後述) 以外を使用する必要があります。以下に例を示します (意図的に改行を入れてあります)。

  Property messageId As %Integer [ 
  SqlComputeCode = { set {*}=$Select({Status}="":0,1:$List($List($Extract({Status},3,$Length({Status}))))) }, 
  SqlComputed, SqlComputeOnChange = Status ];
  

  

  その他の例を示します (意図的に改行を入れてあります)。

  Property Test2 As %String [ SqlComputeCode = { set {*}={Refprop1}_{Refprop2}}, SqlComputed, 
  SqlComputeOnChange = (Refprop1, Refprop2) ];
  

  

  SqlComputeOnChange の値には、値 %%INSERT または %%UPDATE も含めることができます。詳細は、"SqlComputeOnChange" を参照してください。

このフィールドのインデックス付けを予定している場合は、非決定的コードではなく、決定的コードOpens in a new tabを使用します。非決定的コードは、古いインデックス・キー値を確実に削除することができないため、Caché は非決定的コードの結果に対するインデックスを保持できません。(決定的コードは、同じ引数を渡された場合はいつでも同じ値を返します。例えば、$h を返すコードは、$h が関数の制御外で変更されているため、非決定的です。)

"Caché クラス定義リファレンス" の "Calculated" キーワードも参照してください。この章で後述する、“計算プロパティの SQL プロジェクションの制御” も参照してください。

多次元プロパティの定義

多次元になるプロパティを定義できます。つまり、プロパティを多次元配列のように機能させるということです。これを行うには、プロパティ定義に MultiDimensional キーワードを含めます。

Property PropName as Classname [ MultiDimensional ] ;

このプロパティは、以下の点で他のプロパティとは異なります。

• Caché は、このプロパティにプロパティ・メソッドを提供しません (このドキュメントで後述する “プロパティ・メソッドの使用とオーバーライド” を参照)。

• オブジェクトを検証または保存するときに、無視されます。

• アプリケーションにそれを明示的に保存するコードが含まれていない場合、ディスクに保存されません。

• ActiveX や Java によって公開できません。

• SQL テーブルに格納できず、SQL テーブルでも公開されません。

多次元プロパティはあまり使用されませんが、オブジェクトの状態に関する情報を一時的に格納する場合に有用な方法を提供します。

この章で後述する、“多次元プロパティの値の指定” も参照してください。

一般的なデータ型クラス

Caché は多数のデータ型クラスを提供します。これらの中で、最も一般的に使用されるクラスを以下に示します。

特殊な使用を目的とした追加のデータ型クラスが数多くあります。これらの型の大部分は、ここにリストしたクラスのサブクラスです。詳細は、インターシステムズ・クラス・リファレンスを参照してください。

各データ型クラスは、いくつかのキーワードを指定します。これらのキーワードにより、Caché SQL でのデータ型の使用方法や、クライアント・システムでのデータ型の投影方法を制御します。

• SqlCategory — Caché SQL エンジンが処理を実行するときに、データ型に使用される SQL カテゴリを指定します。

• OdbcType — データ型が ODBC 経由でアクセスされた場合、使用される ODBC タイプを指定します。

• ClientDataType — データ型がクライアント・アプリケーション経由でアクセスされた場合、使用している Java あるいは ActiveX タイプを指定します。

以上のことから、データ型を選択する際には、ニーズに応じた適切なクライアント・プロジェクションを持つクラスを選択する必要があります (該当する場合)。後続のサブセクションを利用して、適切なデータ型クラスを選択してください。適切なクラスがない場合、“データ型クラスの定義” の章で説明するように、独自のデータ型クラスを作成できます。

主要なプロパティ・パラメータ

プロパティによっては、その動作に作用するように、そのプロパティのパラメータを指定できます。例えば、パラメータでは、最大値と最小値、表示に使用する形式、照合、特定のシナリオに使用する区切り文字などを指定できます。パラメータは、インスペクタで指定することも、クラス定義に直接入力して指定することもできます。以下に例を示します。

Property MyProperty as MyType (MYPARAMETER="some value");

一部のパラメータは、あらゆるタイプのすべてのプロパティに使用できます。これらのパラメータは、以下のとおりです。

• CALCSELECTIVITY — テーブル・チューニング機能でプロパティの selectivity を計算するかどうかを制御します。通常は、このパラメータを既定 (1) のままにしておくことが最良です。詳細は、"Caché SQL 最適化ガイド" の “テーブルのチューニング” を参照してください。

• CAPTION — クライアント・アプリケーションで、このプロパティに使用するキャプションです。

• EXTERNALSQLNAME — リンク・テーブルで使用します。このパラメータでは、このプロパティのリンク先の外部テーブルにあるフィールドの名前を指定します。リンク・テーブル・ウィザードは、クラス生成時にこのパラメータをプロパティごとに指定します。リモート・データベースの SQL フィールドの名前は、さまざまな理由 (リモート・データベースのフィールド名が Caché の予約語であるなど) で Caché サーバ上のプロパティ名と異なる必要がある場合があります。リンク・テーブルの詳細は、"Caché SQL の使用法" の “The Link Table Wizard” を参照してください。

  プロパティ・パラメータ EXTERNALSQLNAME には、SQLFieldName コンパイラ・キーワードとは別の用途があり、それらの項目には別の値を保持できます。SQLFieldName では、Caché データベース内の投影された SQL フィールド名を指定します。また、EXTERNALSQLNAME はリモート・データベース内のフィールド名です。

• EXTERNALSQLTYPE — リンク・テーブルで使用します。このパラメータでは、このプロパティのリンク先の外部テーブルにあるフィールドの SQL タイプを指定します。リンク・テーブル・ウィザードは、クラス生成時にこのパラメータをプロパティごとに指定します。"EXTERNALSQLNAME" を参照してください。

• JAVATYPE — このプロパティの投影先になる Java データ型です。

ほとんどのプロパティ・パラメータは、データ型クラスで定義されるため、クラス固有のものになります。次のセクションを参照してください。

クラス固有のプロパティ・パラメータ

前のセクションには、すべてのプロパティに使用できるパラメータがリストされています。その他の使用可能なパラメータは、プロパティで使用されるクラスによって異なります。この章でリストしたデータ型クラスがサポートするパラメータを以下のテーブルにリストします。パラメータは、3 つの列にグループ分けされています。1) 多くのデータ型クラスに存在するパラメータ、または頻繁に見かけるパラメータ。2) XML および SOAP のコンテキストでのみ意味を持つパラメータ。および 3) 少数のデータ型クラスにのみ出現するパラメータ、またはほとんど見かけないパラメータ。

* この特殊な目的のクラスは、Caché への移行にのみ使用します。

列挙プロパティの定義

数多くのプロパティが、VALUELIST パラメータと DISPLAYLIST パラメータをサポートしています。これらを使用して、列挙プロパティを定義します。

プロパティに有効な値のリストを指定するには、VALUELIST パラメータを使用します。VALUELIST のフォームは、区切り文字で区切った論理値のリストで、区切り文字が最初の文字になります。以下はその例です。

Property Color As %String(VALUELIST = ",red,green,blue");

この例で VALUELIST は、有効な値が “red”、“green”、“blue” であることを指定し、区切り文字としてコンマを使用します。同様に、

Property Color As %String(VALUELIST = " red green blue");

上の文は同じリストを指定しますが、区切り文字としてスペースを使用しています。

プロパティはリストの値に限定され、データ型の妥当性検証コードは、その値がリストにあるかどうかだけを調べます。リストがなければ、値は特に限定されません。

DISPLAYLIST は、リストがある場合、プロパティの LogicalToDisplay() メソッドで返される対応する表示値を表す追加リストです。

表示値を取得する方法の例は、この章で後述する、“プロパティ・メソッドの使用法” のセクションを参照してください。

リテラル・プロパティの値の指定

リテラル・プロパティに値を指定するには、以下に示すように SET コマンド、OREF、およびドット構文を使用します。

 SET oref.MyProp=value

oref は OREF、MyProp は対応するオブジェクトのプロパティです。value は、リテラル値に評価される ObjectScript 式です。以下に例を示します。

 SET patient.LastName="Muggles"
 SET patient.HomeAddress.City="Carver"
 SET mrn=##class(MyApp.MyClass).GetNewMRN()
 set patient.MRN=mrn

リテラル値は、プロパティ・タイプに対して有効な論理値にする必要があります。例えば、%BooleanOpens in a new tab に基づくプロパティには、1 または 0 を使用します。もう 1 つ例を挙げると、列挙プロパティの場合、値は、VALUELIST パラメータで指定された項目のいずれかにする必要があります。

多次元プロパティの値の指定

多次元プロパティについては、プロパティの添え字に応じて値を指定できます。以下に例を示します。

 set oref.MyStateProp("temp1")=value1
 set oref.MyStateProp("temp2")=value2
 set oref.MyStateProp("temp3")=value3

多次元プロパティは、オブジェクトで使用するための一時的な情報を保持する際に役立ちます。このようなプロパティはディスクに保存されません。

プロパティ・メソッドの使用法

それぞれのプロパティは、生成されたクラス・メソッドのセットをクラスに追加します。これらのメソッドには、propnameIsValid()、propnameLogicalToDisplay()、propnameDisplayToLogical()、propnameLogicalToODBC()、propnameODBCToLogical() などが含まれます。propname はプロパティの名前です。これらのメソッドの一部は、%Property クラスから継承され、その他のメソッドはプロパティが基づくデータ型クラスから継承されます。メソッドの詳細とリストは、“データ型クラスの定義” の章を参照してください。

Caché はこれらメソッドを内部的に使用し、ユーザもこれらを直接呼び出すことができます。どの場合も、引数はプロパティ値です。例えば、以下のようになります。

SAMPLES>set p=##class(DeepSee.Study.Patient).%OpenId(1)
 
SAMPLES>w p.Gender
M
SAMPLES>w ##class(DeepSee.Study.Patient).GenderLogicalToDisplay(p.Gender)
Male

リテラル・プロパティの SQL プロジェクションの制御

このドキュメントで前述したように、永続クラスは SQL テーブルとして投影されます。そのクラスでは、すべてのプロパティが SQL に投影されます。ただし、以下の例外を除きます。

• Transient プロパティ (ただし、サブセクション “計算プロパティの SQL プロジェクションの制御” を参照すること)

• Calculated プロパティ (ただし、サブセクション “計算プロパティの SQL プロジェクションの制御” を参照すること)

• プライベート・プロパティ

• 多次元プロパティ

このセクションでは、リテラル・プロパティについて詳しく説明します。

フィールド名の指定

既定では、プロパティ (SQL に投影される場合) は、そのプロパティと同じ名前の SQL フィールドとして投影されます。別のフィールド名を指定する場合は、プロパティ・キーワード SqlFieldName を使用します。(プロパティ名が SQL 予約語の場合、このキーワードを使用する必要があります)。例えば、“select“ という名前の %StringOpens in a new tab プロパティがある場合、投影された名前を以下の構文で定義します。

Property select As %String [ SqlFieldName = selectfield ];

プロパティの名前が SQL 予約語の場合、そのプロジェクションには別の名前を指定する必要があります。

列番号の指定

システムでは、各フィールドに一意の列番号が自動的に割り当てられます。列番号の割り当てを制御するには、以下の例で示すように、プロパティ・キーワード SqlColumnNumber を指定します。

Property RGBValue As %String [ SqlColumnNumber = 3 ];

SqlColumnNumber に指定する値は 1 より大きい整数にする必要があります。SqlColumnNumber キーワードを引数なしに使用すると、Caché はテーブルで保持されていなくて固定位置を持たない列番号を割り当てます。

指定された SQL 列番号を持つプロパティがある場合、Caché は他のプロパティに列番号を割り当てます。割り当てられた列番号の開始値は、指定された SQL 列番号に続く最高値です。

SqlColumnNumber キーワードの値は継承されます。

データ型クラスとプロパティ・パラメータの影響

特定のプロパティで使用されるデータ型クラスは、SQL プロジェクションに影響を与えます。具体的には、データ型の SQL カテゴリ (SqlCategory キーワードで定義) により、プロパティを投影する方法を制御します。該当する場合は、プロパティ・パラメータも影響を与えます。

例えば、以下のようなプロパティ定義を考えてみます。

Property Name As %String(MAXLEN = 30);

このプロパティは、最大長が 30 文字の文字列フィールドとして投影されます。