$ORDER

次のローカル変数、またはローカル変数やグローバル変数の添え字を返します。

Synopsis

$ORDER(variable,direction,target)
$O(variable,direction,target)

パラメータ

variable	添え字付きのローカル変数、プロセス・プライベート・グローバル変数、またはグローバル変数です。配列の場合、添え字が必要です。配列名だけを指定することはできません。間接演算を使用して添え字なしのローカル変数を指定できます (以下の例を参照してください)。単純なオブジェクト・プロパティ参照を variable として指定することはできません。構文 obj.property を使用すると、多次元プロパティ参照を variable として指定できます。
direction	オプション — ターゲット配列を検索するための添え字順序です。添え字付き変数の値は、1 が昇順添え字 (既定) で、-1 は降順です。添え字なしのローカル変数では、1 (既定) が唯一許可される値です。
target	オプション — variable の次または前のノードの現在のデータ値を返します。次のノードか前のノードかは、direction の設定によって決定されます。target を指定するには direction 値を指定する必要があります。添え字なしのローカル変数では、direction は 1 に設定されなければなりません。variable が定義されていない場合、target 値はそのままで変化しません。target パラメータは、^$ROUTINE などの構造化システム変数 (SSVNs) とは一緒に使用できません。

概要

$ORDER は、主に、指定された開始ポイントから指定された添え字レベルで添え字付きの変数をループするのに使用されます。これは、照合順で一連の変数を返します。また、添え字の順序にギャップを設けることができます。

$ORDER が返す値は、使用するパラメータによって決まります。

$ORDER(variable) は、variable が添え字付きであれば、次の定義された添え字数を返します。返される添え字は、variable に指定したものと同じレベルです。例えば、$ORDER(^client(4,1,6)) は、次のサード・レベル添え字を返します。変数 ^client(4,1,7) が存在する場合、これは 7 になります。
$ORDER(variable) は、variable が添え字なしのローカル変数の場合、アルファベット照合順で次の定義済みのローカル変数名を返します。例えば $ORDER は、以下の順序で、以下の定義済みのローカル変数 a、a0a、a1、a1a、aa、b、bb、および c を返します (以下の例を参照してください)。
$ORDER(variable,direction) は、変数の次の添え字か前の添え字を返します。direction を 1 (次の添え字、既定) または -1 (前の添え字) として指定できます。
添え字なしのローカル変数では、$ORDER は direction 1 (次) の順序でのみ変数を返します。-1 (前) の direction を指定することはできません。これを行おうとすると <FUNCTION> エラーになります。
$ORDER(variable,direction,target) は変数に対する添え字を返し、target を現在のデータ値に設定します。これは direction 設定に応じて、添え字付きの変数に対する次の添え字、または前の添え字のいずれかになります。添え字なしのローカル変数では、target に対する現在のデータ値を返すために direction は 1 に設定されなければなりません。target パラメータは、^$ROUTINE などの構造化システム変数 (SSVNs) とは一緒に使用できません。ZBREAK コマンドでは、ウォッチポイントとしての target パラメータは指定できません。

返される最初の添え字

$ORDER ループは、指定された変数の次の変数、または最初の変数から開始できます。

指定されたポイントから開始： SET key=$ORDER(^mydata(99)) は、99 よりも 1 つ大きい添え字 (添え字 100) を返します (存在する場合)。引数で指定するノード (ここでは添え字 99) は存在している必要はありません。すべての正の添え字を返すには、SET key=$ORDER(^mydata(-1)) と指定できます。すべての負の添え字を返すには、SET key=$ORDER(^mydata(0),-1) と指定できます。
最初から開始： SET key=$ORDER(^mydata("")) は、照合順で最初の添え字付きの変数を返します。この方法は、レベルに正の添え字と同様に負の添え字が含まれているときに必要です。

以下の例では、数字の昇順で正負両方のファースト・レベル添え字を返しています。

    SET mydata(1)="a",mydata(-3)="C",mydata(5)="e",mydata(-5)="E"
   // Get first subscript
   SET key=$ORDER(mydata(""))
   WHILE (key'="") {
     WRITE key,!
     // Get next subscript 
     SET key = $ORDER(mydata(key))
   }

$ORDER が指定されたレベルで添え字の最後に到達すると、NULL 文字列 ("") を返します。ループの中で $ORDER を使用するときは、必ずこの値のテストを含める必要があります。

$ORDER を使用することで、定義済みのローカル変数の限定されたサブセットを返すことができます。引数なしの WRITE を使用することで、定義済みのローカル変数をすべて表示できます。

例

この例では、ローカル変数を返しています。$ORDER は、添え字付きのグローバル変数や添え字付きのプロセス・プライベート・グローバル変数を返すこともできます。

以下の例では、WHILE ループで $ORDER を使用して、mydata(n) グローバルのファースト・レベル添え字をすべて返しています。

    SET mydata(1)="a",mydata(3)="c",mydata(7)="g"
   // Get first subscript
   SET key=$ORDER(mydata(""))
   WHILE (key'="") {
     WRITE key,!
     // Get next subscript 
     SET key = $ORDER(mydata(key))
   }

以下の例では、WHILE ループで $ORDER を使用して、mydata(1,n) グローバルのセカンド・レベル添え字をすべて返しています。ファースト・レベル添え字とサード・レベル添え字は無視されます。この例では、添え字の数と対応する変数値の両方を返しています。

   SET mydata(1,1)="a",mydata(1,3)="c",mydata(1,3,1)="lcase",mydata(1)="A",mydata(1,7)="g"
   SET key=$ORDER(mydata(1,""),1,target)
   WHILE (key'="") {
     WRITE key," = ",target,!
     // Get next subscript 
     SET key = $ORDER(mydata(1,key),1,target)
   }

以下の例で、多次元プロパティは variable 値として使用されます。この例では、定義されているすべてのネームスペースの名前を target パラメータに返します。

  SET obj = ##class(%ResultSet).%New("%SYS.Namespace:List")
  DO obj.Execute()
    SET target="blank", x=""
  WHILE target'="" {
     DO obj.Next()
     SET rval=$ORDER(obj.Data(x),1,target)
     IF rval="Nsp",target'="" {
     WRITE "Namespace: ",target,! }
     ELSE {WRITE !,"Done!"  RETURN}
   }

以下の例では、WHILE ループで $ORDER を使用して、添え字なしのローカル変数を返しています。ローカル変数は照合順で返されます。この例では、ローカル変数名とそれらの値の両方を返しています。添え字なしのローカル変数をループする際、間接演算子 @ を使用する必要があります。この例では、照合順で b の次のローカル変数から開始しています (この場合、bminus)。その後、照合順でその後のすべての定義済みのローカル変数をループします。変数 foo と target をリストしないようにするために、これらの変数は、ローカル変数ではなく、プロセス・プライベート・グローバルとして定義されます。

   SET a="great",b="good",bminus="pretty good",c="fair",d="poor",f="failure"
   SET ^||foo="b"
   SET ^||foo=$ORDER(@^||foo,1,^||target)
   WHILE ^||foo '= "" {
   WRITE ^||foo," = ",^||target,!
   SET ^||foo=$ORDER(@^||foo,1,^||target)
       }

メモ

$ORDER の使用

$ORDER は、通常、連続した整数の添え字を使用しない配列のノードを検索するために、ループ処理と共に使用されます。$ORDER は、次の既存のノードの添え字を返すだけです。以下はその例です。

   SET struct=""
   FOR  {
     SET struct=$ORDER(^client(struct)) 
     QUIT:struct=""
     WRITE !,^client(struct)
   }

上述のルーチンは、^client グローバル配列にある上位レベル・ノードの値すべてを出力します。

$ORDER は既存のノードの添え字を返しますが、値が含まれていないノードもあります。ループの中で $ORDER を使用して、データをコマンド (WRITE など) に送るときは、値なしノードの $DATA チェックを含める必要があります。例えば、前述の例での WRITE コマンドは、以下のように後置条件テストを付けて指定できます。

   WRITE:($DATA(^client(struct))#10) !,^client(struct)

このテストには、値なしポインタ・ノードと値なし端末ノードの場合が含まれます。コードが単純な FOR ループでは処理できないとき、ブロック構造化された DO にその一部を委任できます。

グローバル参照

variable は、グローバル変数である場合、異なるネームスペース内のグローバルを指定して、拡張グローバル参照を含めることができます。存在しないネームスペースを指定した場合、Caché は <NAMESPACE> エラーを発行します。特権を持たないネームスペースを指定した場合、Caché は <PROTECT> エラーを発行し、続けてグローバル名とデータベース・パスを表示します (例： <PROTECT> ^myglobal(1),c:\intersystems\cache\mgr\)。

variable　は、添え字付きのグローバル変数である場合、ネイキッド・グローバル参照にできます。ネイキッド・グローバル参照は配列名なしで指定され、最近実行されたグローバル参照を示します。以下はその例です。

   SET var1=^client(4,5)
   SET var2=$ORDER(^(""))
   WRITE "var1=",var1,!,"var2=",var2

最初の SET コマンドは、参照に対する添え字レベルを含む現在のグローバル参照を設定します。$ORDER 関数はネイキッド・グローバル参照を使用して、このレベルの最初の添え字を返します。例えば、この添え字付きグローバルが定義されている場合、^client(4,1) を示す値 1 を返します。^client(4,1) が定義されておらず、この添え字付きグローバルが定義されている場合は、^client(4,2) を示す値 2 を返す、というようになります。

$ORDER の 3 つのパラメータはすべて、ネイキッド・グローバル参照を取るか、グローバル参照を指定することができます。ただし、direction が明示的なグローバル参照を指定している場合、後に続くネイキッド・グローバル参照は direction グローバル参照を使用しません。以下の例に示すように、引き続き、前に構築されたグローバル参照を使用します。

   SET ^client(4,3)="Jones"
   SET ^client(4,5)="Smith"
   SET ^dir(1)=-1
   SET rtn=$ORDER(^client(4,5),-1)
   WRITE $ZREFERENCE,!  
      /* naked global ref is ^client(4,5) */
   SET rtn=$ORDER(^client(4,5),^dir(1))
   WRITE $ZREFERENCE,!
      /* NOTE: naked global ref is ^client(4,5) */
   SET rtn=$ORDER(^client(4,5),^dir(1),^(1))
   WRITE $ZREFERENCE
      /* NOTE: naked global ref is ^client(4,1) */
   WRITE ^client(4,1),!
   SET rtn=$ORDER(^client(4,5),^dir(1),^targ(1))
   WRITE $ZREFERENCE
      /* naked global ref is ^targ(1) */
   WRITE ^targ(1),!
   SET ^rtn(1)=$ORDER(^client(4,5),^dir(1),^targ(2))
   WRITE $ZREFERENCE
      /* naked global ref is ^rtn(1) */
   WRITE ^targ(2)

詳細は、"Caché グローバルの使用法" の "ネイキッド・グローバル参照" を参照してください。

$ORDER と $DOUBLE の添え字

$DOUBLE 浮動小数点数は、添え字識別子として使用できます。ただし、添え字識別子として使用した場合、$DOUBLE 値は文字列に変換されます。$ORDER はこのタイプの添え字を返すとき、$DOUBLE 浮動小数点数ではなく、数値文字列として返します。

$ORDER と $NEXT

$ORDER は、$NEXT と類似しています。両関数とも指定したノードに照合順で次の同位ノードの添え字を返します。ただし、以下に示すように、$ORDER と $NEXT には、異なる起動コードと失敗コードがあります。

	$NEXT	$ORDER
起動ポイント	-1	NULL 文字列
失敗コード	-1	NULL 文字列

$ORDER は NULL 文字列で起動し、終了するため、正と負の両方の添え字を持つノードを正しく返します。