^$LOCK (ObjectScript)
構文
^$|nspace|LOCK(lock_name,info_type,pid)
^$|nspace|L(lock_name,info_type,pid)
引数
引数 | 説明 |
---|---|
|nspace| または [nspace] |
オプション — 拡張 SSVN 参照。明示的なネームスペース名か、暗黙のネームスペースのいずれかです。角括弧 (["nspace"])、または垂直バー (|"nspace"|) で囲まれた、引用符付きの文字列に評価されなければなりません。ネームスペース名は、大文字と小文字を区別しません。ネームスペース名はすべて大文字で格納および表示されます。 |
lock_name | 文字列に評価される式。添え字付き、または添え字なしのロック変数名を含みます。リテラルの場合は引用符付きの文字列として指定する必要があります。 |
info_type | オプション — 引用符付きの文字列として指定される、すべて大文字の文字列のキーワードに解決される式。info_type は、lock_name について返される情報のタイプを指定します。可能なオプションは、"OWNER"、"FLAGS"、"MODE"、および "COUNTS" です。^$LOCK をスタンドアロン関数として呼び出す場合は必須です。 |
pid | オプション — "COUNTS" キーワードと共に使用します。ロックの所有者のプロセス ID を指定する整数です。指定した場合は、最大で 1 つのリスト要素が "COUNTS" に返されます。省略した場合または 0 を指定した場合は、指定したロックの所有者ごとにリスト要素が 1 つ返されます。pid はその他の info_type キーワードには影響しません。 |
概要
^$LOCK 構造化システム変数は、現在のネームスペースにあるロックまたはローカル・システム上の指定したネームスペースにあるロックに関する情報を返します。^$LOCK の使用方法には以下の 2 種類があります。
-
info_type を指定し、指定のロックに関する情報を返すスタンドアロン関数として使用する。
-
info_type を指定せずに、$DATA、$ORDER、または $QUERY の各関数の引数として使用する。
^$LOCK は、ローカル・システムのロック・テーブルからロック・テーブル情報を取得します。リモート・サーバ上のロック・テーブルからの情報は返しません。
ECP 環境での ^$LOCK
-
ローカル・システム:ローカル・システムにより保持されているロックの ^$LOCK を呼び出す場合、^$LOCK の動作は ECP なしの場合と同じになります。ただし 1 つの例外として、"FLAGS" info_type は、ロックが ECP 環境にあることを示すアスタリスク (*) を返します。つまり、リモート InterSystems IRIS インスタンスは、解除されてもロックを保持できるということです。
-
アプリケーション・サーバ:アプリケーション・サーバ上で、別のサーバで保持されているロックに対して、ECP (データ・サーバまたは別のアプリケーション・サーバのいずれか) を介して ^$LOCK を呼び出す場合、^$LOCK は何も情報を返しません。これはロックが存在していない場合の動作と同じです。
-
データ・サーバ:データ・サーバ上で、アプリケーション・サーバによって保持されているロックに対して ^$LOCK を呼び出す場合、^$LOCK の動作は、以下のようにローカル・システム上の場合と多少異なります。
-
"OWNER":^$LOCK を呼び出すデータ・サーバに接続されたアプリケーション・サーバによってロックが保持されている場合、^$LOCK(lockname, "OWNER") は “ECPConfigurationName:MachineName:InstanceName” を、ロックを保持しているインスタンスに返しますが、ロックを保持している具体的なプロセスは識別しません。
-
"FLAGS":^$LOCK を呼び出すデータ・サーバに接続されたアプリケーション・サーバによってロックが保持されている場合、排他ロックに対する ^$LOCK(lockname, "FLAGS") は “Z” フラグを返します。この "Z" は、InterSystems IRIS では ECP 環境以外で使用されなくなった従来のロックのタイプを示しています。
-
"MODE":^$LOCK を呼び出すデータ・サーバに接続されたアプリケーション・サーバによってロックが保持されている場合、排他ロックに対する ^$LOCK(lockname, "MODE") は、“X” の代わりに “ZAX” を返します。ZA は、InterSystems IRIS では ECP 環境以外で使用されなくなった従来のロックのタイプを示しています。共有ロックの場合、^$LOCK(lockname, "MODE") は、ローカル・ロックに対するのと同じ “S” を返します。
-
引数
nspace
このオプションの引数では、拡張 SSVN 参照を使用することで他のネームスペースのグローバルを指定できます。ネームスペースは、引用符付きの文字列リテラルまたは変数として、明示的にネームスペース名を指定するか、もしくは暗黙のネームスペースを指定します。ネームスペース名は、大文字と小文字を区別しません。括弧付き構文 ["USER"] か、環境構文 |"USER"| のいずれかを使用します。nspace 区切り文字の前後にスペースを使用することはできません。
以下のメソッドを使用して、ネームスペースが定義されているかどうかをテストすることができます。
WRITE ##class(%SYS.Namespace).Exists("USER"),! ; an existing namespace
WRITE ##class(%SYS.Namespace).Exists("LOSER") ; a non-existent namespace
$NAMESPACE 特殊変数を使用して、現在のネームスペースを決定できます。現在のネームスペースを変更するお勧めの方法は、NEW $NAMESPACE に続けて SET $NAMESPACE="nspacename" を使用することです。
lock_name
文字列に評価される式。添え字付き、または添え字なしのロック変数名を含みます。ロック変数 (一般にはグローバル変数) は、LOCK コマンドを使用して定義します。
info_type
info_type キーワードは、^$LOCK をスタンドアロン関数として呼び出す場合は必須で、^$LOCK を別の関数の引数として使用する場合はオプションです。info_type は、引用符付きの文字列として大文字で指定する必要があります。
-
"OWNER" を指定すると、ロックの所有者のプロセス ID (pid) が返されます。ロックが共有ロックである場合は、そのロックの所有者すべてのプロセス ID のコンマ区切りリストが返されます。指定したロックが存在しない場合、^$LOCK は空の文字列を返します。
-
"FLAGS" を指定すると、ロックの状態が返されます。返される値は "D" (ロック解除を保留中)、"P" (ロックを保留中)、"N" (ノード・ロック。下位ノードはロックされません)、"Z" (ZAX モードでのロック)、"L" (ロックが失われた状態。サーバは既にこのロックを持っていません)、または "*" (リモート・ロック) です。指定したロックが標準のロック状態にある場合、または指定したロックが存在しない場合、^$LOCK は空の文字列を返します。
-
"MODE" を指定すると、現在のノードのロック・モードが返されます。返される値は、X (排他ロック・モード)、S (共有ロック・モード)、および ZAX (ZALLOCATE ロック・モード) です。指定したロックが存在しない場合、^$LOCK は空の文字列を返します。
-
"COUNTS" を指定すると、指定したバイナリ・リスト構造としてロックのカウントが返されます。排他ロックでは、このリストにある要素は 1 つです。共有ロックの場合、このリストにはロックの所有者ごとに 1 つずつの要素があります。pid 引数を使用して、指定したロック所有者のリスト要素のみが返るようにすることができます。各要素には、所有者の pid、排他モードのインクリメント・カウント、および共有モードのインクリメント・カウントが記録されています。排他モードと共有モードのインクリメント・カウントが両方とも 0 (または、" ") である場合、このロックは 'ZAX' モードです。インクリメント・カウントの後には 'D' が付記されていることがあります。これは、現在のトランザクションではロックは解除されていますが、トランザクションがコミットまたはロールバックされるまでロックの解放が遅延することを示しています。指定したロックが存在しない場合、^$LOCK は空の文字列を返します。
info_type キーワードは、すべて大文字で指定する必要があります。無効な info_type キーワードを指定すると、<SUBSCRIPT> エラーが生成されます。
pid
ロック所有者のプロセス ID。"COUNTS" キーワードを使用している場合にのみ意味があります。"COUNTS" の返り値を最大でも 1 つのリスト要素に制限するために使用します。pid はどのプラットフォームでも整数で指定します。pid が lock_name の所有者のプロセス ID と一致する場合、^$LOCK は、この所有者の "COUNTS" リスト要素を返します。pid が lock_name の所有者のプロセス ID と一致しない場合、^$LOCK は空の文字列を返します。pid に 0 を指定することは、pid を省略することと同じです。^$LOCK は、"COUNTS" リスト要素をすべて返します。pid 引数は、"OWNER"、"FLAGS"、または "MODE" の各キーワードでも使用できますが、無視されます。
例
以下の例は、排他ロックの場合に info_type キーワードにより返される値を示しています。
LOCK ^B(1,1) ; define lock
WRITE !,"lock owner: ",^$LOCK("^B(1,1)","OWNER")
WRITE !,"lock flags: ",^$LOCK("^B(1,1)","FLAGS")
WRITE !,"lock mode: ",^$LOCK("^B(1,1)","MODE")
WRITE !,"lock counts: "
ZZDUMP ^$LOCK("^B(1,1)","COUNTS")
LOCK -^B(1,1) ; delete lock
以下の例は、排他ロックの増減によって info_type の "COUNTS" で返される値がどのように変化するかを示しています。
LOCK ^B(1,1) ; define exclusive lock
ZZDUMP ^$LOCK("^B(1,1)","COUNTS")
LOCK +^B(1,1) ; increment lock
ZZDUMP ^$LOCK("^B(1,1)","COUNTS")
LOCK +^B(1,1) ; increment lock again
ZZDUMP ^$LOCK("^B(1,1)","COUNTS")
LOCK -^B(1,1) ; decrement lock
ZZDUMP ^$LOCK("^B(1,1)","COUNTS")
LOCK -^B(1,1) ; decrement lock again
ZZDUMP ^$LOCK("^B(1,1)","COUNTS")
LOCK -^B(1,1) ; delete exclusive lock
以下の例は、共有ロックの増減によって info_type の "COUNTS" で返される値がどのように変化するかを示しています。
LOCK ^S(1,1)#"S" ; define shared lock
ZZDUMP ^$LOCK("^S(1,1)","COUNTS")
LOCK +^S(1,1)#"S" ; increment lock
ZZDUMP ^$LOCK("^S(1,1)","COUNTS")
LOCK +^S(1,1)#"S" ; increment lock again
ZZDUMP ^$LOCK("^S(1,1)","COUNTS")
LOCK -^S(1,1)#"S" ; decrement lock
ZZDUMP ^$LOCK("^S(1,1)","COUNTS")
LOCK -^S(1,1)#"S" ; decrement lock again
ZZDUMP ^$LOCK("^S(1,1)","COUNTS")
LOCK -^S(1,1)#"S" ; delete shared lock
以下の例は $DATA、$ORDER、$QUERY 関数に対して、^$LOCK を引数として使用する方法を表しています。
$DATA に対する引数としての ^$LOCK
$DATA(^$|nspace|LOCK(lock_name))
^$LOCK は $DATA に対する引数として、ロック名が ^$LOCK 内のノードとして存在するか否かを示す整数値を返します。以下のテーブルは、$DATA が返すことができる整数値を示しています。
値 | 意味 |
---|---|
0 | ロック名情報は存在しない |
10 | ロック名情報が存在する |
このコンテキストで使用される $DATA が返すことができるのは、0 または 10 だけであることに注意してください。10 は、指定したロックが存在することを意味します。ロックに下位ノードがあるかどうかを判断することや、1 や 11 を返すことはできません。
以下の例は、現在のネームスペースにロック名が存在するかどうかを調べています。最初の WRITE は 10 を返し (ロック名が存在する)、次の WRITE は 0 を返します (ロック名が存在しない)。
LOCK ^B(1,2) ; define lock
WRITE !,$DATA(^$LOCK("^B(1,2)"))
LOCK -^B(1,2) ; delete lock
WRITE !,$DATA(^$LOCK("^B(1,2)"))
$ORDER に対する引数としての ^$LOCK
$ORDER(^$|nspace|LOCK(lock_name),direction)
^$LOCK は $ORDER に対する引数として、指定したロック名に対する照合順序で、次または前の ^$LOCK ロック名ノードを返します。そのようなロック名が ^$LOCK ノードとして存在しない場合、$ORDER は NULL 文字列を返します。
ロックは、大文字/小文字を区別する文字列照合順で返されます。名前付きロックの添え字は、数値の照合を使用して、添え字ツリー順で返されます。
direction 引数は、次のロック名を返すか、前のロック名を返すかを指定します。direction 引数を指定しない場合、InterSystems IRIS は、指定したロック名に対する照合順序で、次のロック名を返します。詳細は、"$ORDER" 関数を参照してください。
以下のサブルーチンは SAMPLES ネームスペースにあるロックを検索し、LOCKET というローカル配列にあるロック名を格納します。
LOCKARRAY
SET lname=""
FOR I=1:1 {
SET lname=$ORDER(^$|"SAMPLES"|LOCK(lname))
QUIT:lname=""
SET LOCKET(I)=lname
WRITE !,"the lock name is: ",lname
}
WRITE !,"All lock names listed"
QUIT
$QUERY に対する引数としての ^$LOCK
$QUERY(^$|nspace|LOCK(lock_name))
^$LOCK は $QUERY に対する引数として、指定したロック名に対する照合順序で、次のロック名を返します。^$LOCK のノードとして定義された次のロック名が存在しない場合は、$QUERY は NULL 文字列を返します。
ロックは、大文字/小文字を区別する文字列照合順で返されます。名前付きロックの添え字は、数値の照合を使用して、添え字ツリー順で返されます。
次の例では、現在のネームスペースに 5 つのグローバル・ロック名が (順不同で) 作成されます。
LOCK (^B(1),^A,^D,^A(1,2,3),^A(1,2))
WRITE !,"lock name: ",$QUERY(^$LOCK(""))
WRITE !,"lock name: ",$QUERY(^$LOCK("^C"))
WRITE !,"lock name: ",$QUERY(^$LOCK("^A(1,2)"))
$QUERY は、添え字付きまたは添え字なしのすべてのグローバル・ロック変数名を文字列として処理し、文字列照合順序内で取得します。したがって、$QUERY(^$LOCK("")) は、照合順序で最初のロック名 (^$LOCK("^A") またはより照合順序の高い InterSystems IRIS 定義ロック) を取得します。$QUERY(^$LOCK("^C")) は、照合順序内で、存在しない ^C の次に当たるロック名 ^$LOCK("^D") を取得します。$QUERY(^$LOCK("^A(1,2)")) は、照合順序内でその後に続く ^$LOCK("^A(1,2,3)") を取得します。
関連項目
-
LOCK コマンド
-
$DATA 関数
-
$ORDER 関数
-
$QUERY 関数
-
$NAMESPACE 特殊変数