Caché Python バインディング

Caché Python バインディングを使用すれば、Python アプリケーションから Caché オブジェクトを簡単かつ直接的に操作できます。Python プログラムは、Caché 上のデータベースに接続し、そのデータベースにオブジェクトを作成したり、オブジェクトを開いたりできます。また、オブジェクトのプロパティの操作、オブジェクトの保存、オブジェクトに対するメソッドの実行、およびクエリの実行も可能です。Caché のすべてのデータ型がサポートされています。

Python バインディングは、同時実行性とトランザクション制御を含め、オブジェクト・データベースの永続性を完全にサポートしています。また、Caché サーバと Python アプリケーションを別々のマシン上に配置する場合でも、ネットワーク・トラフィックを最小限に抑える高度なデータ・キャッシング方式が採用されています。

このドキュメントは、Python および標準の Python モジュールを理解していることを前提としています。Caché には、Python インタープリタや開発環境は含まれていません。

Python バインディング・アーキテクチャ

Caché Python バインディングを使用すると、Python アプリケーションは Caché サーバ上のオブジェクトと相互運用できます。Python バインディングは以下のコンポーネントで構成されます。

intersys.pythonbind モジュール — Caché データベースに格納されているオブジェクトに対する透過的な接続を、Python アプリケーションに提供する Python C 拡張です。
Caché オブジェクト・サーバ — Python クライアントと Caché データベース・サーバ間の通信を管理する高性能なサーバ・プロセスです。標準ネットワーク・プロトコル (TCP/IP) を使用して通信し、Caché がサポートしているプラットフォームであれば、どのプラットフォーム上でも動作します。Caché オブジェクト・サーバは、Python、Perl、C++、Java、JDBC、ODBC など、すべての Caché 言語バインディングで使用します。

基本機能は以下のように動作します。

Caché 内で 1 つ以上のクラスを定義します。これらのクラスは、Caché データベースに格納される永続オブジェクト、または、Caché サーバで動作する一時的なオブジェクトです。
実行時、Python アプリケーションは Caché サーバに接続します。その後、Caché サーバ内に格納されているオブジェクトのインスタンスにアクセスできます。Caché は、すべての通信とクライアント側のデータ・キャッシングを自動的に管理します。実行時のアーキテクチャは以下のとおりです。
- Caché データベース・サーバ (複数可)。
- Python インタープリタ ("Python クライアント要件" を参照してください)。
- Python アプリケーション。実行時、Python アプリケーションは、オブジェクト接続インタフェースまたは標準 ODBC インタフェースのいずれかを使用して、Caché に接続します。Python アプリケーションと Caché サーバ間のすべての通信は、TCP/IP プロトコルを使用します。

クイックスタート

ここでは、Python バインディングの中核となる基本的な機能をいくつか紹介します。

接続の確立とデータベースの取得

   conn = intersys.pythonbind.connection()
   conn.connect_now(url,user,password, None)
   database = intersys.pythonbind.database(conn)

database は、url で指定したネームスペースへの論理接続です。

既存のオブジェクトを開く
```
   person =  database.openid("Sample.Person",str(id),-1,-1)
```
person は、Caché サーバ上の Sample.Person オブジェクトへの論理接続です。

新規オブジェクトの作成

   person =  database.create_new("Sample.Person", None)

プロパティの設定と取得

   person.set("Name","Doe, Joe A")
   name = person.get("Name")

メソッドの実行

   answer = person.run_obj_method("Addition",[17,20])

オブジェクトの保存
```
   person.run_obj_method("%Save",[])
```
保存されているオブジェクトの ID の取得
```
   id = person.run_obj_method("%Id",[])
```

クエリの実行

   sqlstring ="SELECT ID, Name, DOB, SSN \
               FROM SAMPLE.PERSON \
               WHERE Name %STARTSWITH ?"
   query = intersys.pythonbind.query(database)
   query.prepare(sqlstring)
   query.set_par(1,"A")
   query.execute();
   while 1:
      cols = query.fetch([None])
      if len(cols) == 0: break
      print cols

インストールと構成

標準の Caché インストールでは、Caché Python バインディングに必要なすべてのファイルが <cachesys>/dev/Python に配置されます(ご使用のシステムの <cachesys> の場所については、"Caché インストール・ガイド" の "Caché の既定のインストール・ディレクトリ" を参照してください)。以下のインストール手順を完了すると、Python サンプル・プログラムを実行できます。

Python クライアント要件

Caché は intersys.pythonbind モジュールを介して、クライアント側の Python をサポートします。このモジュールは、Caché サーバとの通信に必要な接続機能とキャッシング機能を実装します。

このモジュールを使用するには以下の環境が必要です。

Python バージョン 2.7 または Python 3.0+。Windows では、ActiveState ディストリビューション、 ActivePython© (www.activestate.comOpens in a new tab) のみをサポートします。
Python C 拡張を生成するための C++ コンパイラ。Windows の場合は Visual Studio .NET 2008 以降が必要です (ActiveState ディストリビューションに必要)。UNIX® の場合は GCC が必要です。
Python ディストリビューションとコンパイラのどちらのビットネスも、Caché のビットネスと一致する必要があります。つまり、64 ビット・システムには、64 ビット・バージョンの Python とコンパイラが必要です。また、32 ビット・システムには、32 ビット・バージョンの Python とコンパイラが必要です。
RedHat Linux では、python サンプルをコンパイルするために、python-devel パッケージをインストールする必要があります。
PATH には <cachesys>\bin ディレクトリを含める必要があります(ご使用のシステムの <cachesys> の場所については、"Caché インストール・ガイド" の "Caché の既定のインストール・ディレクトリ" を参照してください)。
C コンパイルとリンクをサポートする環境変数を設定します。手順は以下のセクションを参照してください。

UNIX® インストール

PATH および LD_LIBRARY_PATH に <cachesys>/bin が含まれていることを確認します。(ご使用のシステムの <cachesys> の場所については、"Caché インストール・ガイド" の "Caché の既定のインストール・ディレクトリ" を参照してください)。
以下はその例です。
```
   export PATH=/usr/cachesys/bin:$PATH
   export LD_LIBRARY_PATH=/usr/cachesys/bin:$LD_LIBRARY_PATH
```
Note:

Mac OS X では LD_LIBRARY_PATH の代わりに DYLD_LIBRARY_PATH を使用します。以下に例を示します。
```
   export DYLD_LIBRARY_PATH=/usr/cachesys/bin:$DYLD_LIBRARY_PATH
```
setup.py を実行します ( <cachesys>/dev/python にあります)。
```
   python setup.py  install
```
以下のプロンプトが表示されます。
```
   enter directory where you installed Cache'
```
このプロンプトで、 <cachesys> の場所を指定します。以下はその例です。
```
   /usr/cachesys
```
作成された lib と include のパスが表示されます。
```
   libdir=/usr/cachesys/bin
   include dir=/usr/cachesys/dev/cpp/include
```
test.py (dev/python/samples に配置) を実行してインストール結果をテストします。
```
   python test.py
```
<cachesys>/dev/python からはテスト・プログラムを実行しないでください。この場所ではテスト・プログラムが pythonbind モジュールを検出できません。python パスは相対パスなので、代わりに intersys サブディレクトリからファイルを選択します。

Windows 環境でのインストール

Microsoft C/C++ コンパイラを実行できるように、パスおよび環境が設定されていることを確認します。Microsoft 社の指示に従ってください。例えば、コマンド行から以下を実行します。
```
   vsvars32.bat
```
以上が 32 ビット・システムの場合です。または以下を実行します。
```
   vcvarsall.bat x64
```
以上が 64 ビット・システムの場合です。これらのファイルは、Microsoft C/C++ コンパイラを使用するためのパスと環境変数を設定します。ファイルの場所は、使用している Visual Studio のバージョンによって異なるため、Microsoft 社のドキュメントを参照して、これら .bat ファイルの場所を特定してください。
setup.py を実行します ( <cachesys>/dev/python にあります)。(ご使用のシステムの <cachesys> の場所については、"Caché インストール・ガイド" の "Caché の既定のインストール・ディレクトリ" を参照してください)。
```
   python setup.py install
```
以下のプロンプトが表示されます。
```
   enter directory where you installed Cache'
```
このプロンプトで、 <cachesys> の場所を指定します。以下はその例です。
```
   C:\Intersystems\Cache
```
作成された lib と include のパスが表示されます。
```
   libdir=C:\Intersystems\Cache\dev\cpp\lib
   include dir=C:\Intersystems\Cache\dev\cpp\include
```
test.py ( <cachesys>\dev\python\samples に配置) を実行して、インストール結果をテストします。
```
   python test.py
```
<cachesys>\dev\python からはテスト・プログラムを実行しないでください。この場所ではテスト・プログラムが pythonbind モジュールを検出できません。python パスは相対パスなので、代わりに intersys サブディレクトリからファイルを選択します。

Caché サーバ構成

Caché サーバで Python クライアントを使用するうえで、特別な構成はほとんど必要ありません。Caché に付属の Python サンプル・プログラムは、Caché を既定でインストールすると、変更を加えなくても動作します。このセクションでは、Python に関連するサーバ設定とそれらの変更方法について説明します。

Caché サーバに接続するすべての Python クライアントには、以下の情報が必要です。

サーバ IP アドレス、ポート番号、および Caché ネームスペースを指定する URL。
ユーザ名およびパスワード。

既定では、Python サンプル・プログラムは以下の接続情報を使用します。

URL ： "localhost[1972]:Samples"
ユーザ名： "_SYSTEM"
パスワード： "SYS"

問題が発生した場合は、以下の点を確認してください。

Caché サーバがインストール済みで稼動していることを確認します。
Caché サーバを実行しているマシンの IP アドレスを確認します。Python サンプル・プログラムでは "localhost" が使用されます。サンプル・プログラムで別のシステムを既定とする場合は、コード内の接続文字列を変更する必要があります。
待ち受け状態になっている Caché サーバの TCP/IP ポート番号を確認します。Python サンプル・プログラムでは "1972" が使用されます。サンプル・プログラムで別のポートを既定とする場合は、サンプル・コード内で番号を変更する必要があります。
接続を確立する際に、有効なユーザ名とパスワードを使用していることを確認します (ユーザ名とパスワードは、管理ポータルを使用して管理できます)。Python サンプル・プログラムは、管理者のユーザ名 "_SYSTEM" と既定のパスワード "SYS" または "sys" を使用します。通常、サーバのインストール後に既定のパスワードを変更します。サンプル・プログラムで異なるユーザ名とパスワードを既定にする場合は、サンプル・コードを変更する必要があります。
接続 URL に有効な Caché ネームスペースがあることを確認してください。ネームスペースは、プログラムで使用するクラスとデータを含む必要があります。Python サンプルは、Caché で事前にインストールされている SAMPLES ネームスペースに接続します。

サンプル・プログラム

Caché の標準インストールには、Caché Python バインディングの使用法を示すサンプル・プログラム・セットが含まれます。これらのサンプル・プログラムは以下の場所に格納されています。

<cachesys>/dev/Python/samples/

(ご使用のシステムの <cachesys> の場所については、"Caché インストール・ガイド" の "Caché の既定のインストール・ディレクトリ" を参照してください)。

以下のサンプル・プログラムが用意されています。

CPTest2.py — Sample.PersonOpens in a new tab のインスタンスのプロパティを取得および設定します。
CPTest3.py — 埋め込みオブジェクト Sample.Person.Home のプロパティを取得します。
CPTest4.py — 埋め込みオブジェクト Sample.Person.Home を更新します。
CPTest5.py — データ型コレクションを処理します。
CPTest6.py — ByName クエリの結果セットを処理します。
CPTest7.py — ダイナミック SQL クエリの結果セットを処理します。
CPTest8.py — employee サブクラスおよび company/employee リレーションシップを処理します。

これらすべてのアプリケーションは、 SAMPLES ネームスペースの Sample パッケージにあるクラスを使用します (Atelier でアクセス可能)。

引数

サンプル・プログラムはさまざまなスイッチによって制御されます。これらのスイッチは、プログラムへの引数としてコマンド行に入力できます。引数を入力しない場合は、既定値が渡されます。

例えば、CPTest2.py は以下のオプションの引数を受け取ります。

-user — ログイン時に使用するユーザ名 (既定値は "_SYSTEM")。
-password — 使用するパスワード (既定値は "SYS")。
-host — 接続先のホスト・コンピュータ (既定値は "localhost")。
-port — 使用するポート (既定値は "1972")。

-user 引数は以下のように指定します。

   python CPTest2.py -user _MYUSERNAME

CPTest7.py サンプルは、SQL クエリに渡される -query 引数を受け取ります。

   python CPTest7.py -query A

このクエリは、文字 "A" で始まる名前を含むすべての Sample.Person レコードを列挙します。