$QUERY (ObjectScript)
構文
$QUERY(reference,direction,target)
$Q(reference,direction,target)
引数
引数 | 説明 |
---|---|
reference | パブリック・ローカル変数名とグローバル変数名 (およびオプションとしてその添え字) に評価される参照。単純なオブジェクト・プロパティを reference として指定することはできません。構文 obj.property を使用すると、多次元プロパティ参照を reference として指定できます。 |
direction | オプション — 配列を検索する方向。前方 = 1、後方 = -1。既定値は前方です。 |
target | オプション — $QUERY の評価結果として返された reference の現在のデータ値を返します。例えば、reference が ^a(1) で、$QUERY が ^a(2) を返す場合、target は値 ^a(2) になります。 |
概要
$QUERY はパブリック・ローカル配列とグローバル配列を物理的にスキャンします。順番で、指定した配列ノードの次にある、定義されたノードの完全参照 (名前と添え字) を返します。そのようなノードが存在しない場合、$QUERY は NULL 文字列を返します。
引数
reference
この引数は、パブリック変数またはグローバル変数に評価される必要があります。$QUERY は、プライベート変数をスキャンできません。
この引数は多次元オブジェクト・プロパティとすることができます。非多次元オブジェクト・プロパティとすることはできません。非多次元オブジェクト・プロパティで $QUERY を使用しようとすると、<OBJECT DISPATCH> エラーが発生します。
返されるグローバル参照は、同じ下位レベルか、reference 引数で指定された上位レベルです。添え字を指定せずに reference を指定すると、$QUERY は配列内で最初に定義されたノードを返します。
direction
direction が指定されていない場合、既定の方向は前方向です。方向を指定したい場合は、引数値の 1 が配列を前方向に、引数値 -1 が配列を後方向に検索します。
target
オプションで、target 変数を指定できます。target 変数を指定したい場合は、direction 引数を指定する必要があります。
$QUERY の評価で返される値が NULL 文字列 ("") の場合、target 値は変更されません。
ZBREAK コマンドでは、target 引数をウォッチポイントとして指定することはできません。
例
以下の例は、ユーザ指定配列の全ノードのデータ値を出力するための汎用ルーチンを示しています。任意のレベル数の配列に対応できます。コードは、$ORDER 関数の例にあるコードと同じ処理を実行します。23 行が必要になるのではなく、6 行のみが必要になります。処理できるレベル数についての制限はありません。
Start READ !,"Array name: ",ary QUIT:ary=""
SET queryary=$QUERY(@ary@(""))
WRITE !,@queryary
FOR {
SET queryary=$QUERY(@queryary)
QUIT:queryary=""
WRITE !,@queryary
}
WRITE !,"Finished."
QUIT
最初の SET コマンドは、添え字付き間接指定を持つ $QUERY を使用して、データを含む最初の既存ノードにグローバル参照を初期化します。詳細は、"間接 (@)" を参照してください。($ORDER のように、$QUERY は NULL 文字列を受け入れ、配列の最初の添え字を指定します)。最初の WRITE コマンドは、最初に見つかったノードの値を出力します。省略すると、最初のノードはスキップされます。
FOR ループでは、$QUERY は、次のノードを検索して、グローバル参照を更新するのに使用されます。その後グローバル参照の内容は WRITE コマンドで出力します。後置条件付きの QUIT は、$QUERY が配列の最後に到達したことを示す NULL 文字列 ("") を見つけると、ループを終了します。
ポインタ・ノード ($DATA=11) と端末ノード ($DATA=1) を見分ける場合以外には、$DATA テストは必要ありません。
配列を検索する $QUERY の使用法
$QUERY を繰り返し使用すると、定義されているノードを順番に返しながら、配列全体を左から右、上から下に検索できます。$QUERY は reference で指定した添え字により決定されるポイントから開始できます。水平軸と垂直軸の両方を使用して処理します。以下はその例です。
SET exam=$QUERY(^client(4,1,2))
この例に基づいて、$QUERY は 3 レベル配列を仮定し、以下の値のうちのいずれかを返す場合があります。
値 | 以下の場合に $QUERY により返される |
---|---|
^client(4,1,3) | ^client(4,1,3) が存在してデータを含む場合。 |
^client(4,2) | ^client(4,1,3) またはそのデータは存在しないが、^client(4,2) が存在してデータを含む場合。 |
^client(5) | ^client(4,1,3) と ^client(4,2) は存在しないか、またはデータを含まず、^client(5) が存在してデータを含む場合。 |
NULL 文字列 ("") | 以前のグローバル参照が一切存在せず、データも含まない場合。$QUERY は配列の最後に到達しています。 |
$QUERY は、direction 値 -1 を使用して、配列全体を逆方向に、右から左、下から上へと検索します。
$ORDER と比較しての $QUERY
$QUERY がグローバル参照全体を返すのに対し、$ORDER は次のノードの添え字のみを返すため、この 2 つの関数は異なります。$ORDER は、1 つのレベルのノード全体で、水平軸のみに沿って進みます。
$QUERY は、データを含む既存のノードのみを選択するという点でも、$ORDER とは異なります。$ORDER は、データを含むか否かに関係なく、既存のノードを選択します。$ORDER は存在の暗黙のテストを行いますが ($DATA'=0)、$QUERY は存在とデータ両方の暗黙のテストを行います ($DATA'=0 and $DATA'=10)。しかし、$QUERY は、データを含むポインタ・ノード ($DATA=11) と終端ノード ($DATA=1) を識別しません。この識別を行うには、コードに適切な $DATA テストを含める必要があります。
$ORDER と同様、$QUERY は、通常、連続した整数の添え字を使用しない配列のノードを検索するために、ループ処理と共に使用されます。$QUERY は、値を持つ次のノードのグローバル参照を返すだけです。$QUERY は、グローバル配列をアクセスするための非常に密度の高いコードを提供しています。
$NAME 関数と $ORDER 関数同様、$QUERY は、ネイキッド・グローバル参照と共に使用できます。これは配列名なしで指定され、直前に実行されたグローバル参照を指定します。以下はその例です。
SET a=^client(1)
SET x=2
SET z=$QUERY(^(x))
最初の SET コマンドは、参照レベルを含む現在のグローバル参照を作成します。2 番目の SET コマンドは、添え字と共に使用する変数を設定しています。$QUERY 関数は、ネイキッド・グローバル参照を使用して、^client(2) の次のノードのグローバル参照全体を返します。例えば返り値は、^client(2,1) あるいは ^client(3) になります。
$QUERY と $ZREFERENCE
$QUERY reference 引数がグローバル参照でない場合、$ZREFERENCE は変更されません。
$QUERY reference 引数がグローバル参照の場合 :
-
$QUERY がグローバル参照を返す場合、$ZREFERENCE はそのグローバル参照に設定されます。
-
$QUERY が空の文字列を返す場合 :
-
$QUERY reference 引数が添え字付きのグローバル参照の場合、$ZREFERENCE は reference 引数に設定されます。ネイキッド参照の場合、reference 引数は拡張されます。
-
$QUERY reference 引数が添え字なしのグローバル参照の場合 :
direction が前方向の場合、$ZREFERENCE は、空文字列 "" である単一の添え字と共に reference 引数グローバルに設定されます。例えば、$QUERY(^a,1) は空文字列を返し、$ZREFERENCE を ^a("") に設定します。
direction が後方向の場合、$ZREFERENCE は変更されません。
-
$QUERY と拡張グローバル参照
%SYSTEM.ProcessOpens in a new tab クラスの RefInKind()Opens in a new tab メソッドを使用して、$QUERY が拡張グローバル参照形式でグローバル参照を返すかどうかを、プロセスごとに制御できます。システム全体の既定の動作は、Config.MiscellaneousOpens in a new tab クラスの RefInKindOpens in a new tab プロパティで設定できます。
拡張グローバル参照の詳細は、"拡張グローバル参照" を参照してください。
関連項目
-
$DATA 関数
-
$NAME 関数
-
$ORDER 関数
-
$QLENGTH 関数
-
$QSUBSCRIPT 関数
-
$ZREFERENCE 特殊変数