Skip to main content

InterSystems IRIS Python モジュール･コア API

このセクションでは、InterSystems IRIS Python モジュールのコア関数の API ドキュメントを提供します。これらの関数を使用して、InterSystems IRIS のクラスやメソッドにアクセスし、InterSystems IRIS のトランザクション処理機能を使用したり、その他の InterSystems IRIS のコア・タスクを実行することができます。

概要

以下のテーブルに、iris モジュールのコア関数の概要を示します。組み込み Python からこのモジュールを利用するには、import iris を使用します。

グループ 関数
コードの実行 check_status()、routine()
ロックと並行処理の制御 lock()、unlock()
参照の作成 arrayref()、cls()、gref()、ref()
トランザクション処理* tcommit()、tlevel()、trollback()、trollbackone()、tstart()

*トランザクションを使用して InterSystems IRIS データベースの論理的な整合性を維持する方法は、"トランザクション処理" を参照してください。

arrayref(dictionary)

Python ディクショナリから ObjectScript 配列を作成し、その配列への参照を返します。

配列を引数として期待する以下の ObjectScript メソッドを持つ、User.ArrayTest という InterSystems IRIS クラスがあるとします。

ClassMethod WriteContents(myArray) [ Language = objectscript] 
{
   zwrite myArray
}

ClassMethod Modify(myArray) [ Language = objectscript]
{
   set myArray("new")=123
   set myArray("x","y","z")="xyz"
}

ClassMethod StoreGlobal(myArray)  [ Language = objectscript]
{
   kill ^MyGlobal
   if '$data(myArray) return "no data"
   merge ^MyGlobal = myArray
   return "ok"
}

メソッド WriteContents() は配列の内容を書き込み、Modify() は配列の内容を変更し、StoreGlobal() は配列の内容を取得してグローバルに格納します。

Python からディクショナリ myDict を作成し、iris.arrayref() を使用してその内容を ObjectScript 配列に配置し、その配列への参照を返します。その後、その参照を User.ArrayTest の 3 つのメソッドに渡すことができます。

>>> myDict = {2:{3:4}}
>>> myDict
{2: {3: 4}}
>>> a = iris.arrayref(myDict)
>>> a.value
{2: {3: 4}}
>>> iris.cls('User.ArrayTest').Modify(a)
>>> iris.cls('User.ArrayTest').WriteContents(a)
myArray(2,3)=4
myArray("new")=123
myArray("x","y","z")="xyz"
>>> iris.cls('User.ArrayTest').StoreGlobal(a)
'ok'

さらに、ObjectScript から、グローバル ^MyGlobal に配列と同じデータが含まれていることを確認できます。

USER>zwrite ^MyGlobal
^MyGlobal(2,3)=4
^MyGlobal("new")=123
^MyGlobal("x","y","z")="xyz"

ObjectScript 配列の詳細は、"多次元配列" を参照してください。

check_status(status)

status にエラーが含まれる場合に例外を生成します。エラー状態が発生していない場合は、None を返します。

必須の Name プロパティを持つ InterSystems IRIS クラス Sample.Company がある場合、Name プロパティなしでこのクラスのインスタンスを保存しようとすると、エラー・ステータスが生じます。以下の例では、iris.check_status() を使用して _Save() メソッドから返されたステータスを確認し、エラーが含まれる場合は例外をスローします。

>>> myCompany = iris.cls('Sample.Company')._New()
>>> myCompany.TaxID = '123456789'
>>> try:
...    status = myCompany._Save()
...    iris.check_status(status)
... except Exception as ex:
...    print(ex)
...
ERROR #5659: Property 'Sample.Company::Name(4@Sample.Company,ID=)' required

cls(class_name)

InterSystems IRIS クラスへの参照を返します。これにより、Python クラスと同じ方法でそのクラスのプロパティとメソッドにアクセスできます。iris.cls() を使用して、組み込み InterSystems IRIS クラスまたは自分で記述したカスタム InterSystems IRIS クラスの両方にアクセスできます。

以下の例では、iris.cls() を使用して、組み込み InterSystems IRIS クラス %SYS.SystemOpens in a new tab への参照を返します。その後、その GetInstanceName() メソッドを呼び出します。

>>> system = iris.cls('%SYS.System')
>>> print(system.GetInstanceName())
IRIS2023

gref(global_name)

InterSystems IRIS グローバルへの参照を返します。グローバルは、既に存在する場合も存在しない場合もあります。

以下の例は、iris.gref() を使用して、変数 day をグローバル ^day への参照に設定します。

>>> day = iris.gref('^day')

次の例は、^day(1, "name") に格納された値を出力し、それらのキーに現在値が格納されていないため、None を出力します。次に、値 "Sunday" をその場所に格納し、格納された値を取得して出力します。

>>> print(day[1, 'name'])
None
>>> day[1, 'name'] = 'Sunday'
>>> print(day[1, 'name'])
Sunday

InterSystems IRIS グローバル参照で使用できるメソッドの詳細は、"グローバル参照 API" を参照してください。

グローバルに関する背景情報は、"グローバルの概要" を参照してください。

lock(lock_list, timeout_value, locktype)

ロック名のリスト、オプションのタイムアウト値 (秒)、オプションのロック・タイプを指定して、ロックを設定します。locktype が "S" の場合、共有ロックであることを示します。

InterSystems IRIS では、ロックは、複数のユーザまたはプロセスが同じリソース (通常はグローバル) に同時にアクセスしたり、変更を加えるのを防ぐために使用されます。例えば、リソースに書き込むプロセスは排他ロック (既定) を要求して、別のプロセスがそのリソースに同時に読み取りや書き込みを行わないようにする必要があります。リソースを読み取るプロセスは共有ロックを要求して、別のプロセスがそのリソースを同時に読み取ることはできるが、リソースに書き込むことはできないようにすることができます。プロセスはタイムアウト値を指定して、リソースが利用可能になるまで永久に待機しないようにすることができます。

以下の例では、iris.lock() を使用して、^one および ^two というロックに対して排他ロックを要求します。要求が成功した場合、この呼び出しは True を返します。

>>> iris.lock(['^one','^two'])
True

その後、別のプロセスが ^one に対して共有ロックを要求し、最初のプロセスが 30 秒以内にロックを解放しなかった場合、以下の呼び出しは False を返します。

>>> iris.lock(['^one'],30,'S')
False

保護するリソースが使用されなくなったら、プロセスは unlock() を使用してロックを放棄する必要があります。

InterSystems IRIS でのロックの使用方法の詳細は、"ロックと並行処理の制御" を参照してください。

ref(value)

指定された値を使用して iris.ref オブジェクトを作成します。これは、ObjectScript メソッドに引数を参照渡しする必要がある場合に便利です。

以下の例は、iris.ref() を使用して、値 2000 の iris.ref オブジェクトを作成します。

>>> calories = iris.ref(2000)
>>> calories.value
2000

InterSystems IRIS クラス User.Diet に、これから摂取する食品の名前とその日の現在のカロリー摂取量を引数として取る Eat() いうメソッドがあり、その calories が参照によって渡され、新しいカロリー摂取量で更新されるとします。以下の例は、Eat() の呼び出し後に、変数 calories の値が 2000 から 2250 に更新されたことを示しています。

>>> iris.cls('User.Diet').Eat('hamburger', calories)
>>> calories.value
2250

ObjectScript での引数の参照渡しの詳細は、"引数の渡し方の指示" を参照してください。

routine(routine, args)

オプションで指定されたタグで、InterSystems IRIS ルーチンを呼び出します。呼び出しで渡す必要のある引数は、ルーチン名の後にコンマで区切って指定します。

以下の例では、%SYS ネームスペースでの実行時に、iris.routine() を使用してルーチン ^SECURITY を呼び出します。

>>> iris.routine('^SECURITY')
 
 
1) User setup
2) Role setup
3) Service setup
4) Resource setup
.
.
.

2 つの数値を加算する関数 Sum() を持つルーチン ^Math がある場合、以下の例では 4 と 3 を加算します。

>>> sum = iris.routine('Sum^Math',4,3)
>>> sum
7

ObjectScript でルーチンを使用する方法の詳細は、"ルーチン" を参照してください。

tcommit()

InterSystems IRIS トランザクションの正常終了を表します。

iris.tcommit() を使用してトランザクションの正常終了を表し、入れ子レベルを 1 デクリメントします。

>>> iris.tcommit()

トランザクションを適切に入れ子にするには、すべての iris.tstart() を iris.tcommit() とペアにする必要があります。

トランザクション中でないときに iris.tcommit() を呼び出すと、値 <COMMAND> で例外が発生します。

"tstart()"、"tlevel()"、"trollback()"、"trollbackone()" も参照してください。

tlevel()

トランザクションが現在進行中かどうかを検出し、入れ子レベルを返します。iris.tstart() を呼び出すと入れ子レベルがインクリメントされ、iris.tcommit() を呼び出すと入れ子レベルがデクリメントされます。値がゼロの場合、トランザクション中でないことを示します。

以下の例は、トランザクションのさまざまな入れ子レベルで iris.level() が返す値を示しています。

>>> iris.tlevel()
0
>>> iris.tstart()
>>> iris.tstart()
>>> iris.tlevel()
2
>>> iris.tcommit()
>>> iris.tlevel()
1

"tstart()"、"tcommit()"、"trollback()"、"trollbackone()" も参照してください。

trollback()

現在進行中のトランザクションをすべてロール・バックし、ジャーナリングされたすべてのデータベース値を最初のトランザクションの開始時の値にリストアします。また、トランザクションの入れ子レベルを 0 にリセットします。

この簡単な例では、グローバル ^a(1) を値 “hello” に初期化します。その後、トランザクションを開始して、^a(1) を値 “goodbye” に設定します。ただし、トランザクションがコミットされる前に、iris.trollback() を呼び出します。これにより、トランザクションの入れ子レベルが 0 にリセットされ、^a(1) がトランザクション開始前に保持していた値にリストアされます。

>>> a = iris.gref('^a')
>>> a[1] = 'hello'
>>> iris.tstart()
>>> iris.tlevel()
1
>>> a[1] = 'goodbye'
>>> iris.trollback()
>>> iris.tlevel()
0
>>> a[1]
'hello'

"tstart()"、"tcommit()"、"tlevel()"、"trollbackone()" も参照してください。

trollbackone()

入れ子になったトランザクションの現在のレベル、つまり、直近の iris.tstart() よって開始されたトランザクションをロール・バックします。また、トランザクションの入れ子レベルを 1 デクリメントします。

この例では、グローバル ^a(1) を値 4、^b(1) を値 “lemon” に初期化します。その後、トランザクションを開始して、^a(1) を 9 に設定します。次に、入れ子になったトランザクションを開始して、^b(1) を “lime” に設定します。その後、iris.trollbackone() を呼び出して内側のトランザクションをロール・バックし、iris.commit() を呼び出して外側のトランザクションをコミットします。つまり、^a(1) は新しい値を保持しますが、^b(1) は元の値にロール・バックされます。

>>> a = iris.gref('^a')
>>> b = iris.gref('^b')
>>> a[1] = 4
>>> b[1] = 'lemon'
>>> iris.tstart()
>>> iris.tlevel()
1
>>> a[1] = 9
>>> iris.tstart()
>>> iris.tlevel()
2
>>> b[1] = 'lime'
>>> iris.trollbackone()
>>> iris.tlevel()
1
>>> iris.tcommit()
>>> iris.tlevel()
0
>>> a[1]
9
>>> b[1]
'lemon'

"tstart()"、"tcommit()"、"tlevel()"、"trollback()" も参照してください。

tstart()

InterSystems IRIS トランザクションの開始を表します。

トランザクションはコマンドの集まりで、トランザクションが成功したと見なすにはそれらすべてのコマンドを完了する必要があります。例えば、ある銀行口座から別の銀行口座に送金するトランザクションがある場合、最初の口座からの引き出しと 2 番目の口座への預け入れの両方が成功した場合にのみ、トランザクションは成功したと言えます。トランザクションが失敗した場合、データベースはトランザクション開始前の状態にロール・バックすることができます。

iris.start() を使用してトランザクションの開始を表し、トランザクションの入れ子レベルを 1 インクリメントします。

>>> iris.tstart()

"tcommit()"、"tlevel()"、"trollback()"、"trollbackone()" も参照してください。

InterSystems IRIS のトランザクション処理の仕組みの詳細は、"トランザクション処理" を参照してください。

unlock(lock_list, timeout_value, locktype)

ロック名のリスト、オプションのタイムアウト値 (秒)、オプションのロック・タイプを指定して、ロックを削除します。

コードによってロックを設定し、リソースへのアクセスを制御している場合は、それらのリソースの使用が終了したら、アンロックする必要があります。

以下の例では、iris.unlock() を使用して、^one および ^two というロックを解除します。

>>> iris.unlock(['^one','^two'])
True

"lock()" も参照してください。

グローバル参照 APINext section
FeedbackOpens in a new tab