Python クライアント・クラス・リファレンス
この章では、Caché のクラスとデータ型が Python コードにどのようにマッピングされるかについて説明します。また、Caché Python バインディングでサポートされているクラスとメソッドについても詳しく説明します。ここで説明する内容は以下のとおりです。
-
データ型 — %BinaryOpens in a new tab データ。
-
接続 — Caché データベースのネームスペースへ物理的に接続するためのメソッド。
-
データベース — Caché オブジェクトのオープンと作成、クエリの作成、および Caché クラス・メソッドの実行に使用するメソッド。
-
オブジェクト — プロパティの取得と設定、オブジェクト・メソッドの実行、オブジェクトに関する情報の取得など、Caché オブジェクトを操作するためのメソッド。
-
クエリ — クエリを実行し、その結果を取得するためのメソッド。
-
時刻と日付 — Caché の %TimeOpens in a new tab データ型、%DateOpens in a new tab データ型、%Timestamp データ型にアクセスするためのメソッド。
-
ロケールとクライアント・バージョン — Caché のバージョン情報と Windows のロケール設定にアクセスするためのメソッド。
データ型
Caché のすべてのデータ型がサポートされています。個々のデータ型の詳細は、この後のセクションを参照してください。
-
Caché の %BinaryOpens in a new tab データ型は、Python の整数リストに対応しています。使用例は、"%Binary データの使用法" を参照してください。
-
%Library.ArrayOfDataTypesOpens in a new tab や %Library.ListOfDataTypesOpens in a new tab などのコレクションは、Caché %Collection クラスのオブジェクト・メソッドで操作します。使用例は、"%Collection オブジェクト" を参照してください。
-
Caché の %Library.ListOpens in a new tab 変数は、Python のリストにマップされます。リストには、String (通常の文字列または Unicode 文字列)、Integer、None、Double を含めることができます。使用例は、"%List 変数" を参照してください。
-
Caché の %TimeOpens in a new tab、%DateOpens in a new tab、および %Timestamp の各データ型は、Python バインディングの対応するクラスによってサポートされています。これらのクラスについては、"時刻と日付" を参照してください。
接続
intersys.pythonbind.connection パッケージのメソッドは、Caché データベースのネームスペースへ物理的に接続します。Connection オブジェクトは、Database オブジェクトの作成にのみ使用します。これは、Python バインディング・アプリケーションから Caché オブジェクトの操作を可能にする論理接続です。Connection メソッドの使用方法については、"Caché データベースへの接続" を参照してください。
以下は、connection のメソッド一覧です。
conn = intersys.pythonbind.connection()
conn.connect_now(url,user,password, timeout)
パラメータの詳細は、この後の "接続情報" を参照してください。
conn = intersys.pythonbind.connection()
conn.secure_connect_now(url, srv_principal, security_level, timeout)
Connection.secure_connect_now() は接続プロキシを返します。このプロキシを使用して、url で識別される Caché ネームスペースのプロキシを取得します。このメソッドには以下のパラメータを指定します。
-
url — URL 形式の詳細は、後述の "接続情報" を参照してください。
-
srv_principal — Kerberos の "プリンシパル" は Kerberos データベースで使用される ID であり、Kerberos KDC (鍵配布センター) とのみ共有される永続秘密鍵を所有します。さらに、資格情報が割り当てられ、Kerberos 認証プロトコルに関与することができます。
-
"ユーザ・プリンシパル" はユーザに関連付けられ、サービスを利用するユーザの認証を行うために使用されます。さらにその後、リソース (コンピュータ・アカウントや Caché サービスなど) の使用を認可するかどうかが判断されます。
-
"サービス・プリンシパル" はサービスに関連付けられ、ユーザ・プリンシパルを認証するために使用されます。またオプションで、ユーザ・プリンシパルに対してサービス・プリンシパル自体を認証することもできます。
-
"サービス・プリンシパル名" (srv_principal_name など) は、サービス・プリンシパルの名前を表す文字列です。一般的な形式は以下のとおりです。
<service>/<instance>@<REALM>
例えば以下のようになります。
cache/turbo.iscinternal.com@ISCINTERNAL.COM
Windows の場合、KDC はドメイン・コントローラに組み込まれ、サービス・プリンシパル名はドメイン・アカウントに関連付けられます。
プリンシパルの詳細は、お使いのシステムの Kerberos ドキュメントを参照してください。
-
-
security_level — "接続のセキュリティ・レベル" を設定します。これは、要求されたクライアント/サーバ・ネットワーク・セキュリティ・サービスを示す整数です。セキュリティ・レベルには以下の値を指定できます。
-
0 — なし。
-
1 — Kerberos クライアント/サーバ相互認証。データは保護されません。
-
2 — 1 と同じ。さらに、データ・ソースとコンテンツの整合性が保護されます。
-
3 — 2 と同じ。さらに、データが暗号化されます。
-
-
timeout — タイムアウトになるまで待機する秒数。
接続情報
Caché データベースに接続するには、以下の情報が必要です。
-
URL — アクセスするサーバとネームスペースを文字列として指定します。形式は次のとおりです。
<address>[<port>]:<namespace>
例えば、サンプル・プログラムは以下の接続文字列を使用します。
"localhost[1972]:Samples"
この文字列の構成要素は以下のとおりです。
-
<address> — サーバの TCP/IP アドレス、または完全修飾されたドメイン名 (FQDN)。サンプル・プログラムでは "localhost" (127.0.0.1) が使用されます。この場合、サーバと Python アプリケーションが同一マシン上に配置されているものとします。
-
<port> — この接続のサーバ TCP/IP ポート番号。IP アドレスとポートの組み合わせにより、一意な Caché サーバが指定されます。
-
<namespace> — 使用するオブジェクトが含まれている Caché ネームスペース。このネームスペースでは、Caché システム・クラスをコンパイルしておく必要があります。また、操作の対象となるオブジェクトはこのネームスペースに含まれている必要があります。サンプル・プログラムでは、SAMPLE ネームスペースのオブジェクトが使用されます。
-
-
username — 接続を行うユーザの名前。サンプル・プログラムでは、"_SYSTEM" (SQL システム・マネージャの既定のユーザ名) が使用されます。
-
password — 指定したユーザ名に関連付けられているパスワード。サンプル・プログラムでは既定の "SYS" が使用されます。
データベース
Database オブジェクトは、Caché ネームスペースへの論理接続を可能にします。intersys.pythonbind.Database パッケージのメソッドは、Caché オブジェクトのオープンまたは生成、クエリの作成、および Caché クラス・メソッドの実行に使用します。Database オブジェクトは、database = intersys.pythonbind.database(conn) を呼び出すことで作成されます。conn は intersys.pythonbind.connection オブジェクトです。Database オブジェクトの作成方法の詳細は、"Caché データベースへの接続" を参照してください。
以下は、Database のメソッド一覧です。
obj = database.create_new(type, init_val)
type で指定されたクラスから、Caché オブジェクトの新規インスタンスを生成します。通常、init_val は None です。このメソッドで生成されるオブジェクトの詳細は、"オブジェクト" を参照してください。
obj = database.open(class_name, oid, concurrency, timeout, res)
class_name で指定されたクラスとオブジェクトの oid を使用して、Caché オブジェクトのインスタンスをオープンします。concurrency 引数の既定値は -1 です。timeout は、ODBC クエリのタイムアウトです。
obj = database.openid(class_name, id, concurrency, timeout)
class_name で指定されたクラスとオブジェクトの id を使用して、Caché オブジェクトのインスタンスをオープンします。concurrency 引数の既定値は -1 です。timeout は、ODBC クエリのタイムアウトです。
value = database.run_class_method(class_name, method_name, [LIST])
クラス・メソッド method_name を実行します。このメソッドは、database の接続先となるネームスペースの class_name クラスのメンバです。引数は LIST として渡されます。Caché のクラス定義によっては、一部の引数を参照で渡すこともできます。返り値は、Caché メソッドの返り値と同じです。
オブジェクト
intersys.pythonbind.object パッケージのメソッドは、Caché オブジェクトへのアクセスを可能にします。Object オブジェクトは、intersys.pythonbind.database create_new() メソッドによって作成されます (詳細は、"データベース" を参照)。Object のメソッドの使用方法については、"Caché Object メソッドの使用法" を参照してください。
以下は、Object のメソッド一覧です。
value = object.get(prop_name)
Cachéobject オブジェクトの prop_name プロパティの値を返します。
value = object.run_obj_method(method_name, [LIST])
Cachéobject オブジェクトに対して method_name メソッドを実行します。引数は LIST として渡されます。Caché のクラス定義によっては、一部の引数を参照で渡すこともできます。返り値は、Caché メソッドの返り値と同じです。
object.set(prop_name, val)
Cachéobject オブジェクトの prop_name プロパティを val に設定します。
クエリ
intersys.pythonbind.query パッケージのメソッドによって、クエリの作成、パラメータの設定、クエリの実行、および結果の取得が可能になります。Query のメソッドの使用方法は、"クエリの使用法" を参照してください。
Query オブジェクトは以下のように生成されます。
query = intersys.pythonbind.query(database)
以下は、Query のメソッド一覧です。
クエリの作成
query.prepare(string)
string の SQL 文字列を使用してクエリを作成します。
query.prepare_class(class_name, query_name)
クラス定義にクエリを作成します。
パラメータの設定
query.set_par(idx, val)
idx パラメータに値 val を割り当てます。このメソッドは、同じパラメータに対して複数回呼び出すことができます。その場合、以前のパラメータ値は失われます。新しい値は別の型でもかまいません。set_par() メソッドは、パラメータの参照渡しをサポートしていません。
nullable = query.is_par_nullable(idx)
idx パラメータが Null 対応であれば 1 を返します。それ以外の場合は 0 を返します。
unbound = query.is_par_unbound(idx)
idx パラメータが未結合の場合は 1 を返します。それ以外の場合は 0 を返します。
num = query.num_pars()
クエリ内のパラメータ数を返します。
size = query.par_col_size(idx)
パラメータ列のサイズを返します。
num = query.par_num_dec_digits(idx)
パラメータの桁数を返します。
type = query.par_sql_type(idx)
パラメータの SQL 型を返します。
クエリの実行
query.execute()
set_par() の呼び出しで定義されているパラメータを使用して、結果セットを生成します。
結果の取得
data_row = query.fetch([None])
結果セットからデータ行を取得し、それをリストとして返します。取得するデータがない場合は、空のリストが返されます。
name = query.col_name(idx)
列の名前を返します。
length = query.col_name_length(idx)
列名の長さを返します。
sql_type = query.col_sql_type(idx)
列の SQL 型を返します。
num_cols = query.num_cols()
クエリ内の列数を返します。
時刻と日付
PTIME_STRUCTPtr、PDATE_STRUCTPtr、および PTIMESTAMP_STRUCTPtr の各パッケージは、それぞれ Caché の %TIME データ型、%DATE データ型、および %TIMESTAMP データ型の操作に使用します。
%TIME
PTIME_STRUCTPtr パッケージのメソッドは、Caché の %DATE データ構造の操作に使用します。時刻は hh:mm:ss 形式で表されます。例えば、午前 0 時 5 分 30 秒過ぎは 00:05:30 と表されます。以下は、Time のメソッド一覧です。
time = PTIME_STRUCTPtr.new()
新しい Time オブジェクトを生成します。
hour = time.get_hour()
時を返します。
minute = time.get_minute()
分を返します。
second = time.get_second()
秒を返します。
time.set_hour(hour)
時を設定します (0 ~ 23 の整数。0 は午前 0 時)。
time.set_minute(minute)
分を設定します (0 ~ 59 の整数)。
time.set_second(second)
秒を設定します (0 ~ 59 の整数)。
stringrep = time.toString()
時刻を hh:mm:ss 形式の文字列に変換します。
%DATE
PDATE_STRUCTPtr パッケージのメソッドは、Caché の %DATE データ構造の操作に使用します。日付は yyyy-mm-dd 形式で表されます。例えば、2003 年 12 月 24 日は 2003-12-24 と表されます。以下は、Date のメソッド一覧です。
date = PDATE_STRUCTPtr.new()
新しい Date オブジェクトを生成します。
year = date.get_year()
年を返します。
month = date.get_month()
月を返します。
day = date.get_day()
日を返します。
date.set_year(year)
年を設定します (4 桁の整数)。
date.set_month(month)
月を設定します (1 ~ 12 の整数)。
date.set_day(day)
日を設定します (1 ~ 各月の日数までの整数)。
stringrep = date.toString()
日付を yyyy-mm-dd 形式の文字列に変換します。
%TIMESTAMP
PTIMESTAMP_STRUCTPtr パッケージのメソッドは、Caché の %TIMESTAMP データ構造の操作に使用します。タイムスタンプは、yyyy-mm-dd<space>hh:mm:ss.fffffffff 形式で表されます。例えば、2003 年 12 月 24 日、午前 0 時 5 分 12.5 秒過ぎのタイムスタンプは以下のように表されます。
2003-12-24 00:05:12:500000000
以下は、TimeStamp のメソッド一覧です。
timestamp = PTIMESTAMP_STRUCTPtr.new()
新しい Timestamp オブジェクトを生成します。
year = timestamp.get_year()
yyyy 形式で年を返します。
month = timestamp.get_month()
mm 形式で月を返します。
day = timestamp.get_day()
dd 形式で日を返します。
hour = timestamp.get_hour()
hh 形式で時を返します。
minute = timestamp.get_minute()
mm 形式で分を返します。
second = timestamp.get_second()
ss 形式で秒を返します。
fraction = timestamp.get_fraction()
fffffffff 形式で秒の小数部分を返します。
timestamp.set_year(year)
年を設定します (4 桁の整数)。
timestamp.set_month(month)
月を設定します (1 ~ 12 の整数)。
timestamp.set_day(day)
日を設定します (1 ~ 各月の日数までの整数)。
timestamp.set_hour(hour)
時を設定します (0 ~ 23 の整数。0 は午前 0 時)。
timestamp.set_minute(minute)
分を設定します (0 ~ 59 の整数)。
timestamp.set_second(second)
秒を設定します (0 ~ 59 の整数)。
timestamp.set_fraction(fraction)
秒の小数部分を設定します (最大 9 桁の整数)。
stringrep = timestamp.toString()
タイムスタンプを yyyy-mm-dd hh:mm:ss.fffffffff 形式の文字列に変換します。
ロケールとクライアント・バージョン
intersys.pythonbind. 既定パッケージのメソッドは、Caché バージョン情報と Windows ロケール設定へのアクセスに使用します。以下は、これらのメソッドの一覧です。
clientver = intersys.pythonbind.get_client_version();
Python クライアント・マシン上で実行されている Caché のバージョンを確認します。
newlocale = intersys.pythonbind.setlocale(category, locale)
既定のロケールを設定し、新しいロケールのロケール文字列を返します。例えば以下のようになります。
newlocale = intersys.pythonbind.setlocale(0, "Russian") # 0 stands for LC_ALL
すべてのロケール・カテゴリを Russian に設定し、以下の文字列を返します。
Russian_Russia.1251
locale 引数が空文字列の場合は、現在の既定のロケール文字列が返されます。例えば、以下のコードを指定したとします。
intersys.pythonbind.setlocale(0, "English")
mylocale = intersys.pythonbind.setlocale(0, ""),"\n";
この場合、mylocale の値は次のようになります。
English_United States.1252
有効な category 値の一覧などの詳細は、MSDN ライブラリ (http://www.microsoft.com/japan/msdn/libraryOpens in a new tab) で、Visual C++ ランタイム・ライブラリの setlocale() 関数を参照してください。
intersys.pythonbind.set_thread_locale(lcid)
呼び出しスレッドのロケール ID (LCID) を設定します。実行時にロケールとの連係を必要とするアプリケーションは、このメソッドを呼び出して正しい変換を行う必要があります。
有効な LCID 値については、MSDN ライブラリ (http://www.microsoft.com/japan/msdn/libraryOpens in a new tab) にある "ロケール ID (LCID) の一覧" を参照してください。"LCID 一覧" で検索すると、この一覧が表示されます。現在の場所は以下のとおりです。
ロケール設定の詳細は、MSDN ライブラリで、"National Language Support (各国語サポート)" の SetThreadLocale() 関数を参照してください。