$DATA (ObjectScript)
Synopsis
$DATA(variable,target) $D(variable,target)
引数
引数 | 説明 |
---|---|
variable | 状態が確認される変数。ローカルあるいはグローバルの、添え字付きあるいは添え字なしの変数。この変数は未定義でもかまいません。単純なオブジェクト・プロパティ参照を variable として指定することはできません。構文 obj.property を使用すると、多次元プロパティ参照を variable として指定できます。 |
target | オプション — $DATA が variable の現在の値を返す変数。 |
概要
$DATA を使用して、処理する前に variable にデータがあるか否かを調べます。$DATA は、指定した変数についての情報を返します。variable 引数は、あらゆる変数 (ローカル変数、プロセス・プライベート・グローバル、またはグローバル) の名前にできます。また、添え字付き配列の要素を含めることができます。これは多次元オブジェクト・プロパティであってもかまいませんが、非多次元オブジェクト・プロパティであってはいけません。
可能な状態値は、以下のとおりです。
状態値 | 意味 |
---|---|
0 | 変数が未定義です。すべての参照によって <UNDEFINED エラーが発生します。 |
1 | 変数が存在し、データを含みますが、下位ノードはありません。NULL 文字列 ("") もデータと見なされます。 |
10 | 変数が下位ノード (他の配列要素の下方ポインタを含みます) を持つ配列要素を識別しますが、データは含みません。このような変数への直接参照は、<UNDEFINED> エラーになります。例えば、y(1) が定義されているものの、y が定義されておらず、$DATA (y) が 10 を返す場合、set x = y は <UNDEFINED> エラーを生成します。 |
11 | 変数が下位ノード (他の配列要素の下方ポインタも含みます) を持つ配列要素を識別し、データも含みます。この種類の変数は、式で参照できます。 |
モジュロ 2 (#2) 演算を使用して、ブーリアン値を $DATA から返すことができます。$DATA(var)#2 は、未定義のステータス・コード (0 および 10) には 0 を返し、定義済みのステータス・コード (1 および 11) には 1 を返します。
状態値 1 と 11 は、データの種類ではなく存在のみを示します。
%SYSTEM.ProcessOpens in a new tab クラスの Undefined()Opens in a new tab メソッドを使用すると、未定義の変数が見つかった場合の動作を設定できます。<UNDEFINED> エラーの詳細は、"$ZERROR" 特殊変数を参照してください。
$DATA によるロック、ルーチン、ジョブ、およびグローバルのテスト
-
$DATA(^$LOCK(lockname)) は、ロックが存在するかどうかをテストします。戻り値が異なることに注意してください。0 = ロックが存在しません。10 = ロックが存在します。ロックの下位ノードは判断できません。値 1 と 11 が返されることはありません。詳細は "^$LOCK" を参照してください。
-
$DATA(^$ROUTINE(routinename)) は、ルーチンの OBJ コード・バージョンが存在するかどうかをテストします。戻り値が異なることに注意してください。0 = ルーチンの OBJ コードが存在しません。1 = ルーチンの OBJ コードが存在します。値 10 と 11 が返されることはありません。詳細は "^$ROUTINE" を参照してください。
-
$DATA(^$JOB(jobnum)) は、ジョブが存在するかどうかをテストします。戻り値が異なることに注意してください。0 = ジョブが存在しません。1 = ジョブが存在します。値 10 と 11 が返されることはありません。詳細は "^$JOB" を参照してください。
-
$DATA(^$GLOBAL(globalname)) は、グローバルが存在するかどうかをテストします。戻りコードは変数の場合と同じで、0、1、10、および 11 です。詳細は "^$GLOBAL" を参照してください。
引数
variable
データの存在に対してテストされる変数:
-
variable は、ローカル変数、グローバル変数、またはプロセス・プライベート・グローバル (PPG) 変数のいずれかにすることができます。これは添え字付きでも添え字なしでもかまいません。
グローバル変数の場合は、拡張グローバル参照を含めることができます。添え字付きグローバル変数の場合は、ネイキッド・グローバル参照を使用して指定できます。未定義の添え字付きグローバル変数を参照するときでも、variable はネイキッド・インジケータをリセットするので、以下で説明されているように、今後のネイキッド・グローバル参照に影響が及びます。
-
variable は多次元オブジェクト・プロパティとすることができます。非多次元オブジェクト・プロパティとすることはできません。非多次元オブジェクト・プロパティで $DATA を使用しようとすると、<OBJECT DISPATCH> エラーが発生します。
例えば、%SQL.StatementMetadataOpens in a new tab クラスには、多次元プロパティ columnIndex と、非多次元プロパティ columnCount があります。以下の例では、最初の $DATA は値を返し、2 番目の $DATA は <OBJECT DISPATCH> エラーを返します。
SET x=##class(%SQL.StatementMetadata).%New() WRITE "columnIndex defined: ",$DATA(x.columnIndex),! WRITE "columnCount defined: ",$DATA(x.columnCount)
-
variable が ^$ROUTINE 構造化システム変数の場合、返される状態値は 1 または 0 が可能です。
target
オプションの引数です。ローカル変数名、プロセス・プライベート・グローバル名、またはグローバル名を指定します。この target 変数は定義する必要はありません。target が指定されている場合、$DATA は target に variable の現在のデータ値を書き込みます。variable が未定義の場合、target 値は変化しません。
ZBREAK コマンドでは、target 引数をウォッチポイントとして指定することはできません。
例
この例では、^client 配列から選択した範囲のレコードを書き込みます。^client 配列 は 3 段階のスパース配列で構成されています。最初の添え字には顧客名、第 2 添え字には顧客の住所、第 3 添え字には顧客の口座、口座番号、残高が含まれています。顧客は 4 種類までの口座を持つことができます。3 つの添え字のどこかに未定義の要素があるかもしれません。一般的なレコードの内容は、以下のようになる場合があります。
^client(5) John Jones ^client(5,1) 23 Bay Rd./Boston/MA 02049 ^client(5,1,1) Checking/45673/1248.00 ^client(5,1,2) Savings/27564/3270.00 ^client(5,1,3) Reserve Credit/32456/125.00 ^client(5,1,4) Loan/81263/460.00
以下のコードは 3 つの各配列添え字の出力を処理するために、別々のサブルーチンを提供します。各サブルーチンの始めに $DATA 関数を使用して、現在の配列要素をテストします。
Level 1、Level 2、Level 3 の $DATA=0 テストは、現在の配列要素が未定義であるかどうかをテストします。True であれば、コードはQUIT して前のレベルに戻ります。
Level 1 と Level 2 の $DATA=10 テストは、現在の配列要素がデータを含まずに、下位の要素へのポインタを含んでいるかどうかを調べます。True であれば、コードが "No Data" と書き出します。それから、コードは次の下位レベルの FOR ループ・プロセスに飛びます。このレベルの下に要素はないので、Level 3 の $DATA=10 テストは実行されません。
Level 2 と Level 3 の WRITE コマンドは、$PIECE 関数を使用して、現在の配列要素から適切な情報を取り出します。
Start Read !,"Output how many records: ",n
Read !,"Start with record number: ",s
For i=s:1:s+(n1) {
If $Data(^client(i)) {
If $Data(^client(i))=10 {
Write !," Name: No Data"
}
Else {
Write !," Name: " ,^client(i)
}
If $Data(^client(i,1)) {
If $Data(^client(i,1))=10 {
Write !,"Address: No Data"
}
Else {
Write !,"Address: ",$Piece(^client(i,1),"/",1)
Write " , ",$Piece(^client(i,1),"/",2)
Write " , ",$Piece(^client(i,1),"/",3)
}
}
For j=1:1:4 {
If $Data(^client(i,1,j)) {
Write !,"Account: ",$Piece(^client(i,1,j),"/",1)
Write " #: ",$Piece(^client(i,1,j),"/",2)
Write " Balance: ",$Piece(^client(i,1,j),"/",3)
}
}
}
}
Write !,"Finished."
Quit
実行されると、このコードは以下のような出力をする場合もあります。
Output how many records: 3 Start with record number: 10 Name: Jane Smith Address: 74 Hilltop Dr., Beverly, MA 01965 Account: Checking #: 34218 Balance: 876.72 Account: Reserve Credit #: 47821 Balance: 1200.00 Name: Thomas Brown Address: 46 Huron Ave., Medford, MA 02019 Account: Checking #: 59363 Balance: 205.45 Account: Savings #: 41792 Balance: 1560.80 Account: Reserve Credit #: 64218 Balance: 125.52 Name: Sarah Copley Address: No Data Account: Checking #: 30021 Balance: 762.28
ネイキッド・グローバル参照
$DATA は、グローバル変数と共に使用されるとき、ネイキッド・インジケータを設定します。ネイキッド・インジケータは、指定されたグローバル変数が定義されていない場合 (状態値は 0) でも設定されます。
同じグローバル変数への後続の参照は、以下の例で示されるようにネイキッド・グローバル参照を使用することができます。
IF $DATA(^A(1,2,3))#2 {
SET x=^(3) }
ネイキッド・グローバル参照とグローバル変数での $DATA の使用に関する詳細は、"グローバルの使用法" の "多次元ストレージの使用法 (グローバル)" を参照してください。
ネットワーク環境でのグローバル参照
定義されていないグローバル変数を繰り返し参照するために $DATA を使用すると (例えば、^x が定義されていない $DATA(^x(1)) など)、そのグローバル変数が ECP データ・サーバで定義されているかどうかをテストするネットワーク処理が常に必要となります。
定義されたグローバル変数内で、定義されていないノードを繰り返し参照するために $DATA を使用すると (例えば、^x にあるその他のノードがすべて定義済みの $DATA(^x(1)))、いったんグローバルの一部 (^x) がクライアント・キャッシュに格納された後には、ネットワーク処理が必要なくなります。
詳細は、"スケーラビリティ・ガイド" の "分散キャッシュ・アプリケーションの開発" を参照してください。
関連項目
-
KILL コマンド
-
SET コマンド
-
$GET 関数
-
$ORDER 関数
-
"グローバルの使用法" の "多次元ストレージの使用法 (グローバル)"