C++ バインディングの使用法

Caché データベースへの接続

Caché データベースへの物理的な接続を確立するには、d_connection クラスのインスタンスを生成します。d_connection はプロキシ・クラスであり、Conn_t (接続) クラス・インスタンスへのスマート・ポインタとして動作します。これは、参照する Conn_t オブジェクトの最後の参照が範囲外となったときに、自動的に Conn_t::disconnect() を呼び出します。つまり、ユーザは Conn_t::disconnect() を直接呼び出す必要はなく、Database オブジェクトは、誤って切断されることのない有効な接続を必ず保持していることを意味します。Conn_t は、これらのすべての接続に対し、共通のインタフェースを提供します。

d_connection オブジェクトで Database オブジェクトを初期化するには、d_connection オブジェクトが参照する Conn_t オブジェクトが接続されていて、他の Database インスタンスによって使用されていない必要があります。d_connection オブジェクトがこれらの要件を満たしているかどうかをテストするには、is_connected() 関数および is_busy() 関数を使用します。例えば、conn という名前の d_connection オブジェクトをテストする場合は、以下を実行します。

   if (!conn->is_connected())
   // code that makes conn point to an active connection

アクティブな接続を指していない d_connection オブジェクトは役に立たないため、そのコンストラクタはプライベートに設定されます。d_connection オブジェクトを生成するには、アクティブな接続を指す d_connection オブジェクトを返す Conn_t::connect() を呼び出す以外に方法はありません。接続が確立できない場合、d_connection オブジェクトはアクティブでない接続を参照します。

TCP/IP 接続クラスは、tcp_conn です。そのスタティック connect() メソッドは、以下の引数を取ります。

• “host[port]:namespace” 形式の接続文字列

• ユーザ名

• パスワード

• タイムアウト値

• エラー値 — 接続に失敗した場合にエラー情報が含まれる、Db_err のオプションのアドレスです。

例えば以下のように記述します。

   Db_err conn_err;
   d_connection conn = tcp_conn::connect("localhost[1972]:Samples",
         "_SYSTEM", "SYS", 0, &conn_err);
   if (conn_err) {
      // error handling
      std::cerr << conn_err << '\n';
      return -1;
   }
   try {
      // establish the logical connection to Cache'
      Database db(conn);
      // code to use db here
   }
   catch(const Db_err& err) {
      // handle an error from the C++ binding library
      std::cout << err << std::endl;
   }

C++ バインディング・アプリケーションのサンプル

このセクションでは、Caché C++ バインディングの使用例として、単純な C++ アプリケーションについて説明します。

サンプル・プログラムは Caché SAMPLES データベースに接続し、そのデータベース内に保存されている Sample.PersonOpens in a new tab オブジェクトのインスタンスを開いて変更し、それをデータベースに再度保存します。

   #include "../Sample_Person.h"
   #include "../Sample_Address.h"
   
   typedef d_ref<Sample_Person> d_Sample_Person;
   
   int main()
   {
      // establish the physical connection to Cache'
      Db_err conn_err;
      d_connection conn = tcp_conn::connect("localhost[1972]:Samples",
                                            "_SYSTEM", "SYS", 0, &conn_err);
      if (conn_err)
      {
         std::cerr << conn_err << '\n';
         return -1;
      }
   
      try {
         // establish the logical connection to Cache'
         Database db(conn);
   
         std::wstring id;
         std::cout << "Enter ID of Person object to be opened:\n";
         std::wcin >> id;
   
         // open a Sample.Person object using %OpenId
         d_Sample_Person person = Sample_Person::openid(&db, id.c_str());
   
         // Fetch some properties of this object
         std::cout << "Name " << person->getName() << '\n'
                  ~<< "City " << person->getHome()->getCity() << '\n'
                  ~<< '\n';
   
         // Modify some properties
         person->getHome()->setCity("Ulan Bator");
   
         // Save the object to the database
         person->save();
   
         // Report the new residence of this person
         std::cout << "New City: " << person->getHome()->getCity() << '\n';
   
         return 0;
      }
      catch(const Db_err& err) {
         std::cerr << err << '\n';
         return -1;
      }
   
      // all objects are closed automatically
   }

プロキシ・オブジェクトのキャスト

P が Q のサブクラスで、コンパイル時にタイプ確認が実行される場合、d_ref<P> を d_ref<Q> にキャストすることができます。以下はその例です。

   d_ref<Sample_Employee> e1 = Sample_Employee::openid(&db, L"1");
   d_ref<Sample_Person> p1 = e1; // ok
   d_ref<Sample_Employee> e2 = p1; // gives a compile time error

Q が実際に P のサブクラスであることがわかっている場合、d_ref<Q> を d_ref<P> にキャストすることも可能ですが、NULL に関連するインタフェースと同様、関数呼び出し dynamic_cast() ではなく、conv_to() を介して実行する必要があります。これは、P と Q の間が、"isa" リレーションシップであるためです。conv_to は、参照によって渡された引数として結果を含む d_ref< > を取得し、変換が不可能な場合は、これを NULL に設定します。以下はその例です。

   d_ref<Sample_Employee> e1 = Sample_Employee::openid(&db, L"1");
   d_ref<Sample_Person> p2 = e1;
   d_ref<Sample_Employee> e2; p2.conv_to(e2);

リソースの管理

d_ref< > は、自身が指すプロキシ・オブジェクトに関連するすべてのシステム・リソースを、自動的に管理します。以下はその例です。

   d_ref<Sample_Person> p1 = Sample_Person::openid(&db, L"1"); 
   p1->setDOB(1970,2,1); 
   d_ref<Sample_Person> p2 = p1->getSpouse(); 
   change_to_spouse(p2); // p2 points to the same server object as p1 

1 行目の openid() は、Sample_Person のスタティック・メソッドで、d_ref<Sample_Person> のインスタンスを生成します。2 行目では、インスタンスを使用して Person オブジェクトの誕生日を変更します。3 行目では、p2 がその人の配偶者を指すように設定し、4 行目では p2 が p1 と同じ人を指すように変更します。p1 および p2 によって取得されたすべてのリソースは、p1 および p2 が範囲外となったときに、自動的に開放されます。

インタフェース

タイプ T の要素を持つ %ListOfObjectsOpens in a new tab は、タイプ d_obj_coln_type<T> の要素を持つ d_obj_vector<T> として生成され、d_ref<T> として操作できます。タイプ T の要素を持つ %ArrayOfObjectsOpens in a new tab は、タイプ d_obj_coln_type<T> の要素も持つ d_obj_map<T> として生成されます。

タイプ T の要素を持つ %ListOfDataTypesOpens in a new tab は、タイプ d_prim_coln_type<T> の要素を持つ d_prim_vector<T> として生成され、T として操作できます。タイプ T の要素を持つ %ArrayOfDataTypesOpens in a new tab は、タイプ d_prim_coln_type<T> の要素も持つ d_prim_map<T> として生成されます。

他のオブジェクトと同様に、コレクションは d_ref<T> 経由で操作する必要があります。つまり、スタティック・メソッド create_new() と openref() を呼び出すことにより、インスタンスを生成することができます。これらのメソッドは、シリアル・オブジェクトに対するプロキシの初期化に使用します。

d_obj_coln_type<T> と d_prim_coln_type<T> は、T から構築できます。つまり、d_obj_coln_type<T> または d_prim_coln_type<T> をとるすべての関数は、その引数が定数であれば、T によって呼び出すこともできます。

例

以下は、単純なコレクションの使用例です。

CPP.Coln クラスがプロパティ Lst を持つと、以下により C++ バインディング内でそのプロパティにアクセスすることができます。Lst は %ListOfObjectsOpens in a new tab で、1 つ以上の Sample.PersonOpens in a new tab のインスタンスを保持します。

   d_ref< d_obj_vector<Sample_Person> > list = obj->getLst();

obj は、タイプ d_ref<CPP_Coln> のオブジェクトです。

コレクション内で list が指す 3 番目の Sample.PersonOpens in a new tab　には、以下によりアクセスできます。

   (*list)[2]

または

   *(list->begin()+2)

person の名前には、以下によりアクセスできます。

   (*list)[2]->getName()

または

   (*(list->begin()+2))->getName()

list が d_ref<T> なので、"." の代わりに "->" を使用します。これは、実際のオブジェクトへのポインタのように動作します。

(d_ref<Sample.Person> 型の) p は、list が指すコレクションに以下のように挿入できます。

   list->push_back(p);

コレクション内で list が指す 2 番目の Sample.PersonOpens in a new tab は、以下により消去できます。

   list->erase(list->begin()+1);

コレクション内で list が指すすべての person は、以下により印刷できます。

   class Print_person : public std::unary_function<d_ref<Sample_Person>, int> { 
   private:
      std::ostream& out; 
   public:
      explicit Print_person(std::ostream& o)
         : out(o)
         {};
      result_type operator()(const argument_type& p) const;
         { out << p->getName() << std::endl; return 0; };
   };
   void print_people(d_ref<CPP_Coln>& obj) 
   {
      d_ref< d_obj_vector<Sample_Person> > list = obj->getLst();
      std::for_each(list->begin(), list->end(), Print_person(std::cout)); 
   };

メソッドでのコレクション要素の使用法

通常、コレクション・プロキシの実際のタイプが (T または d_ref<T>ではなく) d_prim_coln_type<T> または d_obj_coln_type<T> であることに注意を払う必要はありません。しかし、これらのタイプ (T または d_ref<T>) は、非定数引数として関数に使用することができません (定数引数としては使用できます)。この間違った使用法に起因するコンパイル・エラーに対処することができた場合でも、表面上は値が変更されていてもコレクション内の値は変更されません。コレクションの要素の値を適切に変更するには、テンポラリを使用し、その後プロキシ・オブジェクトの要素に変更された値を割り当てます。以下はその例です。

   d_ref<Sample_Person> p = (*list)[2]; 
   change_to_someone_else(p); 
   (*list)[2] = p; 

しかし、calc_some_value() がその引数を変更しなければ、以下も適切に動作します。

   int val = calc_some_value((*list)[2]);

コレクション・プロキシのデータ

C++ 標準ライブラリ・フレームワークに適合するためには、コレクションのプロキシはデータを持つ必要があります。つまり、同じコレクションの 2 種類のプロキシはサーバ上のデータ、およびコレクションの表記を変更しますが、お互いについて関知しないため、同期がとれない可能性があります。同じタイプのプロキシ・オブジェクト経由でコレクションにアクセスしている場合は、この問題は発生しません (通常はこの用法)。しかし、そのタイプが異なる場合は、発生する恐れがあります。

データベース・クラス・メソッドの使用法

入れ子になったトランザクションは、Database クラスの以下のメソッドを使用して実行できます (LC_Database クラスからも継承されます)。

• tstart() — 入れ子になったトランザクションの新しいレベルを開始します。

• tcommit() — トランザクションの現在のレベルをコミット済みとしてマークします。最も外側のレベルをコミットすると、トランザクション全体がコミットされます。

• trollback() — トランザクションのすべてのレベルをロールバックします。

• tlevel() — 現在のトランザクション・レベルを返します。

以下はその例です。

   for (i = 0; i < numPersons; i++) {
      db->tstart()
   // perform the transaction
      {...}
      if (goodtransaction)
         db->tcommit();
      else
         db->trollback();
   }

プロキシ・オブジェクトの save()、insert()、update()、または delete_object() メンバ関数が呼び出されると、tstart() および tcommit() の各メソッドも暗黙的に呼び出されます。これにより、トランザクション範囲の一時的なロックと、エラー時のロールバック動作が保証されます。

トランザクション・クラス・メソッドの使用法

Transaction クラスでは、例外発生時の自動的なロールバック動作が保証されます。commit() または rollback() のいずれも呼び出されていないときに、Transaction オブジェクトが範囲外になると、そのトランザクションはロールバックされます。このクラスでは、入れ子になったトランザクションは許可されません。

Transaction メソッドの動作は以下のとおりです。

• Transaction() — コンストラクタがトランザクションを開始します (tstart() の呼び出しを必要とする Database オブジェクトとは異なります)。

• Transaction::commit() — トランザクションをコミットします。同じ Transaction オブジェクトに対して commit() を複数回呼び出しても何も実行されません (入れ子になったトランザクションの複数レベルでコミットを実行するために繰り返し呼び出すことのできる Database::tcommit() とは異なります)。

• Transaction::rollback() — トランザクションをロールバックします。トランザクションがコミットまたはロールバックされる前に Transaction オブジェクトが範囲外になると、自動的に呼び出されます。

以下はその例です。

   for (i = 0; i < numPersons; i++) {
      Transaction tran(db);
   // perform the transaction
      {...}
   // transaction will rolled back if an exception 
   // occurs before this point
      if (goodtransaction)
         tran->commit();
      else
         tran->rollback();
   }

上記のように、Transaction オブジェクトは以下でインスタンス化する必要があります。

   Transaction tran(db);

以下の方法は使用しません。

   Transaction tran = new Transaction(db);

オブジェクトが new を使用してヒープから割り当てられている場合、そのオブジェクトは範囲外になっても自動的には破棄されないため、トランザクションはロールバックされません。

Light C++ バインディング・アプリケーションでは、プロジェクション・クラスのメンバ関数 save()、delete_object()、insert()、または update() 内で例外がスローされると、自動的にロールバックが発生します。Transaction クラスのインスタンスが例外のスローされた範囲内に自動変数として宣言されており、その範囲内で例外がキャッチされない限り、他のコンテキストでスローされた例外によってトランザクションが自動的にロールバックされることはありません。