Oracle Tuxedo C リファレンス

セクション 3c - C 関数

C 言語アプリケーション トランザクション モニタ インタフェースについて

機能説明

アプリケーション トランザクション モニタ インタフェース (ATMI: Application-to-Transaction Monitor Interface) は、アプリケーションとトランザクション処理システムとの間に介在し、ATMI インタフェースと呼ばれています。このインタフェースは、リソースのオープンとクローズ、トランザクションの管理、型付きバッファの管理、要求/応答型サービス呼び出しや会話型サービス呼び出しの起動などを行う関数呼び出しを提供します。

コミュニケーション パラダイム

ATMI リファレンス ページに記述されている関数呼び出しには、特定のコミュニケーション モデルがあります。このモデルは、クライアント プロセスとサーバ プロセスが要求および応答の各メッセージを使用して如何にコミュニケートできるかという観点から表現されています。

コミュニケーションの基本的パラダイムとして、要求/応答型と会話型の 2 つがあります。要求/応答型サービスは、サービス要求とそれに関わるデータによって呼び出されます。要求/応答型サービスは、要求を 1 つだけ受け取ることができ (該当サービス ルーチンに入った時点で)、かつ応答も 1 つだけ送信することができます (該当サービス ルーチンから戻った時点で)。一方、会話型サービスは接続要求によって呼び出されます。このとき、オープンされた接続を参照する手段が必要です (すなわち、以後の接続ルーチンを呼び出す際に使用される記述子)。接続が確立され、サービス ルーチンが呼び出されると、以降、接続プログラムあるいは会話型サービスは、その接続が解除されるまでアプリケーションで定義されたようにデータの送受信を行えるようになります。

なお、プロセスは要求/応答型と会話型によるコミュニケーションのいずれをも行うことができますが、両方のサービス要求を受け付けることはできません。以下の節では、これら 2 種類のコミュニケーション パラダイムについてその概要を説明します。

Oracle Tuxedo ATMI システムのクライアント/サーバ用要求/応答型パラダイム

要求/応答型のコミュニケーションの場合、クライアントは要求を送り、応答を受け取ることができる 1 つのプロセスとして定義されています。定義によれば、クライアントは要求を受け取ったり、応答を送ったりすることはできません。その代わり、クライアントはいくつでも要求を送ることができ、またそれと同時に応答を待ったり、あるいは適宜ある一定数の応答を受け取ったりすることができます。場合によっては、クライアントは応答を必要としない要求を送ることもできます。tpinit() と tpterm() を使用すれば、クライアントは Oracle Tuxedo ATMI システム アプリケーションと結合および分離することができます。

一方、要求/応答型サーバは一度に 1 つのサービス要求を受け取り、その要求に対して 1 つの応答を返すことができるプロセスと定義されています。ただし、サーバがマルチスレッドであれば、一度に複数の要求を受け取り、一度に複数の応答を返すことができます。サーバは特定の要求を処理しながら、一方で要求/応答型要求あるいは会話型要求を出し、それらの応答を受け取ることにより、クライアントのように働くこともできます。サーバはこうした能力の故に、リクエスタと呼ばれることもあります。ただし、クライアント プロセスとサーバ プロセスはどちらもリクエスタになることができます (実際、クライアントはリクエスタ以外の何物でもありません)。

要求/応答型サーバは別の要求/応答型サーバに要求を送る (転送する) ことができます。この場合、最初のサーバは受け取った要求を別のサーバに渡すだけで、応答を受け取ることは期待しません。この連鎖の中の最後のサーバがその要求に対する応答をもとのリクエスタに送ります。この転送ルーチンの利用によって、もとのリクエスタは最終的にその応答を受け取ることができるのです。

サーバとサービス ルーチンの利用から、Oracle Tuxedo ATMI システム アプリケーションの作成に構造化手法をとることが可能になります。サーバサイドでは、アプリケーション作成者は、要求の受信や応答の送信といったコミュニケーションの詳細ではなく、サービスによって実行する事柄に関する作業に専念すればよいのです。コミュニケーション上の詳細の多くは Oracle Tuxedo ATMI システムの main が処理するため、サービス ルーチンを作成するときにはある一定の規則に従う必要があります。サーバは、そのサービス ルーチンを終了する時点で、tpreturn() を使用して応答を送ったり、あるいは tpforward() を使用して要求を転送したりできます。サービスはその他の作業を行ったり、この時点以後別のプロセスとコミニュニケートすることは許されません。そのため、サーバが実行するサービスは、要求が受け取られたときに開始され、応答が送信あるいは要求が転送された時点で終了します。

要求メッセージと応答メッセージとの間には、本質的に異なる点があります。要求にはそれが送信される以前には関連するコンテキストはありませんが、応答にはあるという点です。たとえば、ある要求を送る際に、呼び出し側はアドレッシング情報を与えなければなりませんが、応答は常にその要求を出したプロセスに返されます。つまり、応答の場合には、要求が出されるときに与えられたアドレッシング情報が維持されていて、応答の送信側はそのあて先になんら手を加えることはできません。この両者の相違点については、tpcall() のルーチンのパラメータと説明で明らかにされています。

要求メッセージはその送信時に特定の優先順位が付与されます。この優先順位にしたがって、要求はキューから取り出されます。つまり、サーバはキューの中で最も優先順位の高い要求から順に取り出すのです。ただし、要求がいつまでもキューの中に残されてしまうのを防ぐために、優先順位に関係なく、最も長くキューに入っている要求が一定間隔で取り出されます。デフォルト設定では、要求の優先順位はその要求が送られるサービス名に対応させて付けられます。サービス名にはシステムのコンフィグレーション時に優先順位を与えることができます (「UBBCONFIG(5)」参照)。特に定義されていない場合には、デフォルトの優先順位が使用されます。この優先順位は、tpcall(3c) に説明のあるルーチン (tpsprio()) を使用して実行時に設定することができます。呼び出し側はこの方法により、メッセージ送信時にコンフィグレーションまたはデフォルトの優先順位を変更できます。

Oracle Tuxedo ATMI システムのクライアント/サーバ用会話型パラダイム

会話型のコミュニケーションの場合、クライアントは、会話接続を行うことはできるが、接続要求を受け付けることはできないプログラムと定義されています。

一方、会話型サーバは、接続要求を受け取ることができるプログラムです。接続が確立され、サービス ルーチンが呼び出されると、以降、接続プログラムあるいは会話型サービスは、その接続が解除されるまでアプリケーションで定義されたようにデータの送受信を行えるようになります。会話は半二重方式で行われます。つまり、接続の一方の側が制御権をもってデータを送信し、他方の側は制御権を渡されるまではデータを送信できません。シングルスレッド サーバでは、接続中のサーバは「予約状態」になり、他のプログラムがそのサーバに接続することはできません。しかしマルチスレッド サーバに接続しても、そのサーバが 1 プロセスの専用サーバとして予約状態になることはなく、複数のクライアントのスレッドから要求を受け取ることができます。

要求/応答型サーバの場合と同様、会話型サーバは他の要求を出したり、他のサーバとの接続を行うことによりリクエスタとして機能できます。一方、要求/応答型サーバと異なり、会話型サーバは要求を別のサーバに転送することはできません。このため、会話型サーバによって実行される会話型サービスは、要求を受け取った時点で開始され、tpreturn() を介して最終的な応答が送信された時点で終了します。

接続が確立されると、その接続記述子から、参加プロセス (参加リソース) に関するアドレッシング情報を得るために必要なコンテキストが分かります。メッセージは、アプリケーション側の規定に従って送受信することができます。要求メッセージ応答メッセージとの間には本質的な相違はなく、またメッセージの優先順位に関する規定もありません。

メッセージの配信

会話モードの場合でも、要求/応答モードの場合でも、メッセージの送受信とは、アプリケーションの 2 つのユニット間のコミュニケーションを意味します。ほとんどの場合、メッセージによって応答または少なくとも承認が送られることになります。ですから、メッセージが確実に受信されたことが確認できます。しかし、メッセージ (システムが生成したメッセージやアプリケーションが生成したメッセージ) の中には、応答や承認を得ることができないものもあります。たとえば、システムは tpnotify() を TPACK() フラグなしで使用して非請求メッセージを送信でき、アプリケーションは tpacall() を TPNOREPLY() フラグ付きで使用して、メッセージを送信を行うことができます。受信プログラムのメッセージ キューがいっぱいになった場合は、メッセージは失われます。

送信側と受信側が別のマシンにある場合、コミュニケーションは、ネットワークでメッセージを送受信する BRIDGE プロセス間で行われます。回線異常により、配信失敗の可能性が生じます。このような状況によって、イベントの発生や ULOG メッセージの書き込みを行っても、このイベントや ULOG メッセージと失われたメッセージを結びつけることは容易ではありません。

Oracle Tuxedo ATMI システムの目的は広域ネットワークで大量のメッセージを処理することなので、前述のような小さな配信異常を検知して調整できるようにはプログラムされていません。このような理由から、すべてのメッセージを確実に配信できるという保証はありません。

メッセージのシーケンス (順序付け)

tpsend() および tprecv() を使用してメッセージを交換する会話型モデルの場合、メッセージ ヘッダにシーケンス番号を付加し、送信された順番に受信します。サーバまたはクライアントが順序の誤ったメッセージを受け取ると会話が停止して、進行中のすべてのトランザクションはロールバックし、メッセージ LIBTUX 1572「会話型シーケンス番号が間違っています」がログに記録されます。

要求/応答モードでは、システムがメッセージを順序付けることはありません。アプリケーション ロジックが順番を付けた場合、アプリケーションがこのシーケンスをモニタし制御する責任があります。BRIDGE プロセス用の複数ネットワーク アドレスをサポートすることで実現する並列メッセージ送信を行うことにより、メッセージが送信順に受信されない可能性が高まります。関連するアプリケーションによって、各 BRIDGE プロセスで使用する単一ネットワークアドレスを指定することができ、またメッセージにシーケンス番号を付加したり、定期的な承認を要求したりすることもできます。

キュー メッセージ モデル

Oracle Tuxedo ATMI システムのキュー メッセージ モデルは、要求メッセージの完了を待たず、そのメッセージが後で処理されるようにキューに登録し、またオプションとしてキューに入れられた応答メッセージを介して応答が得られるようにします。メッセージをキューに登録したり応答をキューから取り出すための ATMI 関数は、tpenqueue() と tpdequeue() です。これらの関数は、Oracle Tuxedo ATMI システムのアプリケーション プロセスの全ての型 (クライアント、サーバ、会話型) のいずれのプロセスからも呼び出せます。キューに登録するアプリケーションもキューから取り出すアプリケーションも、サーバまたはクライアントとして指定されていない場合、関数 tpenqueue() と tpdequeue() をピア ツー ピア通信に使用することができます。

キュー メッセージ機能は、XA 準拠のリソース マネージャで提供されます。永続的なメッセージはトランザクション内でキューへの登録および取り出しが行われ、一度に処理されます。

ATMI トランザクション

Oracle Tuxedo ATMI システムは、トランザクションの定義および管理について、相互に排他的な 2 つの関数をサポートしています。Oracle Tuxedo システムの ATMI トランザクション境界関数 (名前の先頭が tp) と X/Open の TX インタフェース関数 (名前の先頭が tx_) です。X/Open では TX インタフェースのベースとして ATMI のトランザクション境界関数が使用されるので、TX インタフェースの構文およびセマンティクスは、ATMI とほとんど同じです。この項では、ATMI のトランザクション概念について概要を述べます。次の項では、TX インタフェースについて補足説明します。

Oracle Tuxedo ATMI システムにおけるトランザクションは、全体としてある結果を導く、あるいは何も結果を示さない 1 つの論理的な作業単位を定義するときに使用します。トランザクションにより、多くのプロセスによって (そして、おそらく様々な場所で) なされる作業を 1 つの作業単位として扱うことができます。トランザクションの開始者は tpbegin() および tpcommit() または tpabort() を使用してトランザクション内での操作内容を記述します。

開始プロセスはまた、tpsuspend() を呼び出して現在のトランザクションでの作業を中断することもできます。他のプロセスが tpresume() を呼び出して、中断されているトランザクションの開始プロセスの役割を引き継ぐこともできます。トランザクションの開始プロセスとして、プロセスは、tpsuspend()、tpcommit() または tpabort() のいずれかを呼び出す必要があります。したがって、あるプロセスがトランザクションを終了し、別のプロセスがトランザクションを開始することができます。

サービスを呼び出すプロセスがトランザクション モードにあると、呼び出されたサービス ルーチンも同じトランザクションのためにトランザクション モードに入ります。このプロセスがトランザクション モードでない場合、サービスがトランザクション モードで呼び出されるかどうかは、コンフィグレーション ファイルにおいて該当サービスにどのようなオプションが指定されているかによって決まります。トランザクション モードで呼び出されないサービスは、それが呼び出された時点から終了時点までの間に複数のトランザクションを定義できます。一方、トランザクション モードで呼び出されたサービス ルーチンは、1 つのトランザクションにのみ関与し、終了するまでそのトランザクションでの作業を続けます。なお、接続をトランザクション モードにアップグレードすることはできません。会話中に tpbegin() が呼び出されると、会話はそのトランザクションの外側で維持されます (tpconnect() が TPNOTRAN() フラグで呼び出された場合と同様)。

別のプロセスによって起動されたトランザクションに加わるサービスを、参加リソースと呼びます。トランザクションは常に、1 つの開始プロセスをもち、かついくつかの参加リソースをもつことができます。同じトランザクションでの作業を行うためにサービスを 2 回以上呼び出すことができます。tpcommit() あるいは tpabort() を呼び出すことができるのは、トランザクションの開始プロセスだけです (つまり、tpbegin() または tpresume() のいずれかを呼び出すプロセス)。参加リソースは、tpreturn() あるいは tpforward() を使用することによりトランザクションの結果に影響を与えます。これらの 2 つの呼び出しはそれぞれ、サービス ルーチンの終わり、およびそのルーチンがトランザクションの中で担当する部分を終了したことを示すものです。

TX トランザクション

TX インタフェースによって定義されるトランザクションは、ATMI 関数によって定義されるトランザクションと実質的に同じです。アプリケーション開発者は、クライアントとサービスのルーチンを作成する場合、どちらの関数も使用できますが、同一プロセス内に異なる関数を混在させることはできません。つまり、1 つのプロセスで tpbegin() を呼び出した後に tx_commit() を呼び出すことはできません。

TX インタフェースには、移植性の高い方法でリソース マネージャのオープンとクローズを行う 2 つの呼び出し tx_open() および tx_close() があります。トランザクションは、tx_begin() で開始され、tx_commit() または tx_rollback() のいずれかで完了します。tx_info() は、トランザクション情報を取り出す際に使用されます。また、トランザクションにオプションを設定する 3 つの呼び出し、tx_set_commit_return()、tx_set_transaction_control()、および tx_set_transaction_timeout() があります。TX インタフェースには、ATMI の tpsuspend() と tpresume() に相当するものはありません。

TX インタフェースには、ATMI トランザクションについて定義されているセマンティクスおよび規則の他にも、ここで説明しておくべきセマンティクスがいくつかあります。TX インタフェースを使用するサービス ルーチン開発者は、tpsvrinit() を呼び出す独自の tx_open() ルーチンを使用する必要があります。Oracle Tuxedo ATMI システムが提供するデフォルトの tpsvrinit() は、tpopen() を呼び出します。tpsvrdone() についても同じことがあてはまります。TX インタフェースを使用している場合は、サービス ルーチン開発者は、tx_close() を呼び出す独自の tpsvrdone() を使用しなければなりません。

次に、TX インタフェースには、ATMI にはない別のセマンティクスが 2 つあります。それは、連鎖および非連鎖トランザクションと、トランザクション特性です。

連鎖および非連鎖トランザクション

TX インタフェースは、トランザクション実行の連鎖モードおよび非連鎖モードをサポートしています。デフォルトでは、クライアント ルーチンおよびサービス ルーチンは、非連鎖モードで実行されます。この場合、アクティブなトランザクションが完了した際、新しいトランザクションは tx_begin() が呼び出されるまで開始されません。

連鎖モードでは、新しいトランザクションは、現在のトランザクションが完了すると、暗黙に開始されます。つまり、tx_commit() または tx_rollback() が呼び出されると、Oracle Tuxedo ATMI システムは、現在のトランザクションの完了を調整し、制御を呼び出し側に返す前に新しいトランザクションを開始します (異常終了の条件によっては、新しいトランザクションを開始できない場合もあります)。

クライアント ルーチンおよびサービス ルーチンは、tx_set_transaction_control() を呼び出すことによって連鎖モードのオンとオフを切り替えます。連鎖モードと非連鎖モードの間の遷移により、その次の tx_commit() 呼び出しまたは tx_rollback() 呼び出しの動作が変わります。tx_set_transaction_control() の呼び出しでは、呼び出し側のトランザクション モードのオンとオフの切り替えは行いません。

tx_close() は、呼び出し側がトランザクション モードにあるときには呼び出すことができないため、連鎖モードで実行中の呼び出し側が tx_close() を呼び出すには、非連鎖モードに切り替えて、現在のトランザクションを完了してから呼び出さなければなりません。

トランザクション特性

クライアント ルーチンまたはサービス ルーチンは、tx_info() を呼び出すことによって、そのルーチンのトランザクション特性の現在の値を取得したり、そのルーチンがトランザクション モードで実行中であるかどうかを判別したりすることができます。

アプリケーション プログラムの状態には、いくつかのトランザクション特性があります。呼び出し側は、tx_set_*() 関数の呼び出しによってこれらの特性を指定します。クライアント ルーチンまたはサービス ルーチンが特性の値を設定している場合は、異なる値を呼び出し側が指定するまでは、その値が有効のままです。呼び出し側が tx_info() を使用して特性の値を取得しても、これによって値が変更されることはありません。

エラー処理

多くの場合、ATMI 機能には 1 つまたは複数のエラー リターンがあります。エラーの条件は、エラーの他には考えられない戻り値で示されます。この値は通常、エラー時で -1、間違ったフィールド識別子 (BADFLDID) またはアドレスの場合 0 となります。エラー タイプは外部整数 tperrno でも参照することができます。正常な呼び出しによって tperrno がリセットされることはないので、エラーを検出した後にしか呼び出しのテストを行ってはいけません。

tpstrerror() 関数は標準エラー出力へのメッセージを生成します。この関数では 1 つの引数、つまり整数 (tperrno にセットされている) を必要とし、LIBTUX_CAT のエラー メッセージ テキストへのポインタを返します。このポインタは userlog() の引数として使用できます。

現行スレッドで最後の Oracle Tuxedo ATMI システム呼び出し時にエラーが発生した場合、エラーの詳細をさらに調べるには手順が 3 つあり、その第一段階として tperrordetail() を使用することができます。tperrordetail() は整数を返しますが、この整数は、エラーメッセージが含まれる文字列へのポインタを取り出す、tpstrerrordetail() の引数として使用します。ポインタは userlog または fprintf() の引数として使用できます。

エラーコードのうち、ATMI 関数で生成できるものについては、ATMI のマニュアル ページで説明しています。F_error() と F_error32() 関数は、FML エラーの標準エラー出力にメッセージを出力します。この関数は、パラメータを 1 つ (文字列) 取り、コロンと空白を付加してその引数文字列を出力します。次に、エラー メッセージとその後に続く復帰改行文字を出力します。表示されたエラー メッセージは Ferror() または Ferror32() で定義したエラー番号に対応しています。これらはエラーが発生した時点で設定されます。

エラー メッセージのテキストをメッセージ カタログから取り出す時、Fstrerror() およびこれに相当する Fstrerror32() を使用することができます。これらによって userlog の引数として使用できるポインタを返します。

エラー コードのうち、FML 機能で生成できるものについては、マニュアルの FML の項目で説明しています。

タイムアウト

Oracle Tuxedo ATMI システムには 3 種類のタイムアウトがあります。1 つはトランザクションの開始から終了までの期間に関連するもの、2 つめはブロッキング コールで呼び出し側が制御権を再度入手するまでブロック状態を維持する最大時間に関連するものです。3 つめはサービスのタイムアウトです。これは呼び出しの秒数がコンフィグレーション ファイルの SERVICES セクションにおける SVCTIMEOUT パラメータで指定された秒数を越えた時に発生します。

最初のタイムアウトは、tpbegin() を使用してトランザクションを開始するときに指定します (詳細については、「tpbegin(3c)」を参照)。2 つ目のタイムアウトは、tpcall(3c) に定義されている Oracle Tuxedo ATMI システムのコミュニケーション ルーチンを使用する際に発生することがあります。これらのルーチンの呼び出し側は一般に、まだ届いていない応答を待っている間はブロック状態になります。これらの呼び出し側はデータの送信を行うこともブロックされることがあります (たとえば、要求キューがいっぱいの場合など)。呼び出し側がブロック状態になる最大時間は、Oracle Tuxedo ATMI システムのコンフィグレーション ファイルに記述されているパラメータによって決まります。詳細については、「UBBCONFIG(5)」の BLOCKTIME パラメータの項を参照してください。

ブロッキング タイムアウトは呼び出し側がトランザクション モードにないときにデフォルトの設定によって実行されます。クライアントあるいはサーバがトランザクション モードにあると、そのトランザクションが開始したときに指定されたタイムアウト値が働き、UBBCONFIG ファイルに指定されているブロッキング タイムアウト値の影響は受けません。

トランザクション タイムアウトが発生すると、トランザクション モードで行われた非同期の要求に対する応答は失効状態になることがあります。つまり、あるプロセスが、トランザクション モードで送信された要求に対する特定の非同期応答の到着を待っているときに、トランザクション タイムアウトが発生すると、その応答の記述子が無効になります。同様に、トランザクション タイムアウトが発生すると、そのトランザクションに関連付けられている記述子に対してイベントが生成され、その記述子は無効になります。一方、ブロッキング タイムアウトが発生した場合、該当する記述子は無効にならず、応答を待機しているプロセスはその応答を待機するための呼び出しを再度出すことができます。

サービス タイムアウト機構によって、未知の、または予期しないシステム エラーが原因でフリーズする可能性のあるプロセスについて、システムが強制終了を行うことができます。要求/応答サービス時にサービス タイムアウトが発生すると、Oracle Tuxedo ATMI システムによって、フリーズしたサービスを実行中のサーバ プロセスが強制終了され、エラーコード TPESVCERR が戻ります。サービス タイムアウトが会話型サービスで発生した場合は、TP_EVSVCERR イベントが返ります。

トランザクションがタイムアウトになった場合、そのトランザクションがアボートされる前の接続のうち、TPNOREPLY、TPNOTRAN、および TPNOBLOCK 付きの tpacall() への呼び出しのみが有効です。

リリース 6.4 から、TPESVCERR エラー コードに関する詳細が追加されました。タイムアウトのしきい値を超えたためにサービスが失敗した場合、イベント .SysServiceTimeout がポストされます。

動的サービス宣言

デフォルトの設定では、サーバのサービスは、サーバのブート時に宣言され、サーバの停止時にその宣言が解除されます。サーバは、それが提供するサービス セットに対する制御を実行時に必要とする場合、tpadvertise() および tpunadvertise() を使用します。これらのルーチンは、該当サーバが複数サーバ、単一キュー (MSSQ) セットに属していないかぎり、呼び出し側サーバが提供するサービスだけに影響します。MSSQ セットのサーバはすべて同じサービス セットを提供しなければならないため、これらのルーチンもまた呼び出し側の MSSQ セットを共有するすべてのサーバの宣言に影響します。

バッファ管理

プロセスはその生成当初、バッファをもちません。メッセージの送信前に tpalloc() を使用してバッファを割り当てなければなりません。送信元のデータはこの後、割り当てられたバッファに一旦入れた後、送信することができます。このバッファは特有の構造をもっています。この構造は、tpalloc() 関数に type 引数を付けて指定します。ある種の構造にはさらに分類が必要になるので、サブタイプも与えることができるようになっています (たとえば、特定タイプの C 構造体など)。

メッセージを受け取る際には、アプリケーション データを受け取ることができるバッファが必要です。このバッファは tpalloc() によって作成されたものでなければなりません。なお、Oracle Tuxedo ATMI システムのサーバはその main においてバッファを割り当てますが、このバッファのアドレスはサービス呼び出し時に要求/応答型サービスまたは会話型サービスに渡されます (このバッファの扱い方の詳細については、「tpservice(3c)」を参照)。

メッセージの受信に使用するバッファは、送信に使用するバッファとは扱い方が若干異なります。バッファの大きさとアドレスはメッセージの受信にともなって変わります。これは、システムが内部で受信コールに渡されたバッファを、バッファを処理するのに使用する内部バッファと交換するからです。バッファ サイズは、受信にともない増加することも減少することもあります。増加するか減少するかは、すべて送信側から送られたデータの量と、受信側が送信側からデータを受け取るために必要な内部データのフローによって決まります。バッファ サイズに影響を与える要素は数多くあり、圧縮、異なるマシン タイプからのメッセージの受信、使用されるバッファ タイプの postrecv() 関数のアクションなどが挙げられます (「buffer(3c)」を参照)。ワークステーション クライアントのバッファ サイズは、通常ネイティブ クライアントのバッファ サイズとは異なります。

受信バッファは、メッセージを受信する実際の容器というよりプレースホルダであると考えたほうがよいでしょう。システムは、渡したバッファ サイズをヒントとして使用することもあるので、バッファを予想される応答を入れられるだけの大きさにすることには意味があります。

送信側では、バッファ タイプは割り当てられた容量まで満たされないこともあります (たとえば、FML や STRING バッファは送信に使われただけの大きさです)。ひとつの整数フィールドを含む 100K の FML32 バッファは、その整数だけを含むより小さいバッファとして送られます。

これは、受信者が送信者の割り当てたバッファ サイズより小さく、送信されたデータのサイズより大きいバッファを受け取るということです。たとえば、10K バイトの STRING バッファが割り当てられ、文字列 "HELLO" がその中にコピーされた場合は、6 バイトのみが送られますが、受信者は 1K から 4K バイトのバッファを受け取ることになります (他の要素によりこれより大きかったり小さかったりします)。Oracle Tuxedo ATMI システムは、受信メッセージがすべての送信されたデータを含んでいることは保証しますが、すべてのフリー スペースまで保証するわけではありません。

応答を受信するプロセスは、バッファ サイズの変更を知らせ (tptypes() を使用します)、必要な場合は割り当てをやり直します。受信者のバッファ サイズを変える Oracle Tuxedo ATMI 関数はすべて、バッファ内のデータ量を返すので、応答を受信するたびにバッファ サイズを確認するのが標準になるでしょう。

メッセージの送受信には同じデータ バッファを使用することができます。また、それぞれのメッセージに対して別々のデータ バッファを割り当てることも可能です。通常は、呼び出しプロセスが tpfree() を使用してそのバッファを解放します。ただし、ごく限られたケースでは、Oracle Tuxedo ATMI システムが呼び出し側のバッファを解放します。バッファの使い方の詳細については、tpfree() などの通信関数の説明を参照してください。

バッファ タイプ スイッチ

tmtype_sw_t 構造体は、新しいバッファ タイプをプロセスのバッファ タイプ スイッチ tm_typesw() に追加するために必要とされる記述です。スイッチ要素は typesw(5) に定義されています。このエントリに使用される関数名は、Oracle Tuxedo ATMI システムまたは独自のバッファ タイプを作成するアプリケーションによって定義される実際の関数名のテンプレートとなります。これらの関数名は、簡単にスイッチ要素にマップできます。テンプレート名を作成するには、関数ポインタの要素名の最初に _tm を追加します。たとえば、要素 initbuf のテンプレート名は、_tminitbuf になります。

要素 type は NULL 以外とし、最大 8 文字とします。この要素がスイッチ内でユニークでない場合、subtype() は NULL 以外でなければなりません。

要素 subtype() には NULL、最大 16 文字の文字列、または * (ワイルドカード文字) のいずれかを使用できます。type() と subtype() の組み合わせは、スイッチ内でユニークに要素を指定するものでなければなりません。

1 つのタイプに対して、複数のサブタイプが存在してもかまいまいせん。すべてのサブタイプを特定のタイプに対して同じように扱う場合には、ワイルドカード文字 "*" を使用することができます。なお、サブタイプを区別する必要がある場合には、関数 tptypes() を使用して、バッファのタイプとサブタイプを弁別することができます。ある特定のタイプ内で一定のサブタイプのサブセットを個別に扱う必要があり、残りを同様に扱う場合には、特定の値でまとめるサブタイプは、ワイルドカードで指定する前にスイッチ内に指定しておく必要があります。このため、まずスイッチ内のタイプとサブタイプの検索が上から下の方向に行われ、ワイルドカードによるサブタイプのエントリは、残りの一致するタイプを受け付けることになります。

要素 dfltsize() は、バッファの割り当てまたは再割り当てを行うときに使用します。tpalloc() と tprealloc() の実行では、dfltsize() の値か、または tpalloc() および tprealloc() 関数の size パラメータ値の、どちらか大きい方の値を使用して、バッファの作成または再割り当てが行われます。固定サイズの C 構造体などの場合、バッファ サイズはその構造体と同じにするべきです。dfltsize() をこの値に設定すると、呼び出し側はバッファが渡されるルーチンに対してそのバッファ長を指定する必要はなくなります。dfltsize() は 0 あるいはそれ以下にすることができます。ただし、tpalloc() や tprealloc() を呼び出して、その size パラメータも 0 もしくはそれ以下であると、このルーチンは異常終了します。dfltsize() は 0 よりも大きい値に設定することをお勧めします。

Oracle Tuxedo ATMI システムには、5 つの基本バッファ タイプがあります。

上記のバッファ タイプの中の 2 つには、同等のタイプがあります。X_OCTET は CARRAY と同じであり、X_C_TYPE および X_COMMON は VIEW と同じです。X_C_TYPE は、VIEW がサポートするすべての要素をサポートします。これに対し、X_COMMON は、long、short、character のみをサポートします。X_COMMON は、C と COBOL の両方のプログラムがやりとりする際に、使用してください。

アプリケーションで独自のバッファ タイプを使用する場合には、tm_typesw() 配列にそのインスタンスを追加します。バッファ タイプを追加したり削除したりする場合は、配列の終わりに NULL エントリをそのまま残しておくようにしてください。ただし、NULL 名をもつバッファ タイプを使用することはできません。buildserver() または buildclient() コマンドラインに、-f オプションを用いてソースまたはオブジェクト ファイルを明示的に指定することにより、アプリケーション クライアントまたはサーバが、新しいバッファ タイプ スイッチにリンクされます。

非請求通知

上記のように定義されたクライアント/サーバ間でのやりとりの境界外からメッセージをアプリケーション クライアントに送る方法は 2 通りあります。第 1 の方法は、tpbroadcast() によって実現されるブロードキャスト機構です。この関数により、アプリケーション クライアント、サーバおよび管理者は割り当てられた名前に基づいて選択されるクライアントに型付きバッファ メッセージをブロードキャストすることができます。クライアントに割り当てられる名前は、一部はアプリケーションにより TPINIT 型付きバッファに tpinit() 実行時に渡される情報ごとに、また一部はクライアントがアプリケーションのアクセスに使用するプロセッサに基づいてシステムにより決められます。

もう 1 つの方法は、以前のあるいは現在のサービス要求から識別される特定クライアントによる通知方法です。各サービス要求には、そのサービス要求を出したクライアントを特定するユニークなクライアント識別子が含まれています。サービス ルーチン内で tpcall() や tpforward() が呼び出されても、そのサービス要求の連鎖に対応する元のクライアントは変更されません。クライアント識別子は保存しておき、アプリケーション サービス間で受け渡すことができます。この方法で特定されたクライアントに対する通知は、関数 tpnotify() を使用して行います。

プロセスごとのシングルコンテキストとマルチ コンテキスト

Oracle Tuxedo ATMI システムでは、クライアント プログラムはプロセスごとに 1 つまたは複数のアプリケーションとの関連を作成することができます。TPINIT 構造体の flags フィールドに TPMULTICONTEXTS パラメータを指定して tpinit() が呼び出された場合は、複数のクライアント コンテキストを使用できます。tpinit() が暗黙的に呼び出された場合、NULL パラメータによって呼び出された場合、または flags フィールドに TPMULTICONTEXTS を指定せずに呼び出された場合は、1 つのアプリケーションとの関連しか作成できません。

シングルコンテキスト モードでは、tpinit() を 2 回以上呼び出す場合 (つまり、クライアントが既にアプリケーションに参加した後に呼び出す場合) は、何もアクションは実行されず、成功を示す戻り値が返されます。

マルチコンテキスト モードの場合、tpinit() の呼び出しのたびに新しいアプリケーション関連が作成されます。アプリケーションは、tpgetctxt() を呼び出すことによって、このアプリケーション関連を表すハンドルを取得することができます。同じプロセス内のどのスレッドも、tpsetctxt() を呼び出してスレッドのコンテキストを設定することができます。

いったんアプリケーションでシングルコンテキスト モードが選択された場合は、すべてのアプリケーション関連が終了するまで、すべての tpinit() 呼び出しでシングルコンテキスト モードを指定する必要があります。同様に、アプリケーションでマルチコンテキスト モードが選択された場合は、すべてのアプリケーション関連が終了するまで、すべての tpinit() 呼び出しでマルチコンテキスト モードを指定する必要があります。

サーバ プログラムは 1 つのアプリケーションとしか関連付けられないため、クライアントとして機能することはありません。ただし、各サーバ プログラム内に、複数のサーバ ディスパッチ コンテキストがある場合もあります。各サーバ ディスパッチ コンテキストは、それぞれのスレッド内で機能します。

表 2 は、クライアント プロセス内で発生する、非初期化状態、シングルコンテキスト モードで初期化された状態、およびマルチコンテキスト モードで初期化された状態の遷移を示しています。

クライアント スレッドのコンテキスト状態の変化

マルチコンテキストのアプリケーションでは、いろいろな関数を呼び出すと、呼び出し側スレッド、および呼び出し側プロセスと同じコンテキストでアクティブなその他のスレッドのコンテキスト状態が変化します。次の図は、tpinit()、tpsetctxt()、および tpterm() 関数を呼び出した場合のコンテキスト状態の変化を示しています。tpgetctxt() 関数を呼び出しても、コンテキスト状態は変化しません。

表 3 は、tpinit()、tpsetctxt()、および tpterm() を呼び出した場合のコンテキスト状態の変化を示します。いずれの状態もスレッド固有のものであり、マルチコンテキストのアプリケーションの一部を構成するときは、スレッドごとに状態が異なります。一方、前掲の表 (「プロセスごとのコンテキスト モード」) に示されるコンテキスト状態は、それぞれプロセス全体に適用されます。

スレッド プログラミングのサポート

Oracle Tuxedo ATMI システムは、いくつかの方法でプログラミングされたマルチスレッド プログラミングをサポートしています。プロセスでシングルコンテキスト モードが使用されている場合に、アプリケーションで新しいスレッドが作成されると、これらのスレッドではそのプロセスの Oracle Tuxedo ATMI コンテキストを共有します。クライアントでは、あるスレッドがシングルコンテキスト モードで tpinit() 呼び出しを発行すると、他のスレッドは ATMI 呼び出しを発行します。たとえば、1 つのスレッドが tpacall() を発行すると、同じプロセス内の別のスレッドは tpgetrply() を発行します。

マルチコンテキスト モードの場合、最初のスレッドは Oracle Tuxedo ATMI アプリケーションに関連付けられません。スレッドは、tpsetctxt() を呼び出して既存のアプリケーション関連に参加するか、TPMULTICONTEXTS フラグを設定した tpinit() を呼び出して新しい関連を作成します。

シングルコンテキスト モードかマルチコンテキスト モードかに関わりなく、ATMI 操作が適切なタイミングで実行されるようにスレッドを調整するのは、アプリケーションの役目です。

アプリケーションは、OS スレッド関数を使って、アプリケーション サーバ内に追加スレッドを生成できます。これらの新しいスレッドは、Oracle Tuxedo ATMI システムから独立して動作できます。また、いずれかのサーバ ディスパッチ スレッドと同じコンテキストで動作することもできます。最初、アプリケーション生成サーバ スレッドは、どのサーバ ディスパッチ コンテキストにも関連していません。アプリケーションに作成されたサーバ スレッドは、tpsetctxt() を呼び出し、サーバ ディスパッチ スレッドとの関連を確立します。アプリケーションに作成されたサーバ スレッドは、ディスパッチされたスレッドが tpreturn() または tpforward() を呼び出す前に、すべての ATMI 呼び出しを終了していなければなりません。Oracle Tuxedo ATMI システムによってディスパッチされたサーバ スレッドは、tpsetctxt() を呼び出すことはできません。また、アプリケーション生成スレッドは、コンテキストと関連付けられていない場合、暗黙的に tpinit() を発生させる ATMI を呼び出すことができません。それに対して、ディスパッチャによって作成されたスレッドは、常にコンテキストと関連付けられているため、ATMI 呼び出しに失敗することはありません。すべてのサーバ スレッドで、tpinit() の呼び出しは禁止されています。

マルチスレッドのアプリケーションでは、TPINVALIDCONTEXT 状態で動作するスレッドが、多数の ATMI 関数を呼び出すことは禁止されています。次のリストは、このような環境で呼び出し可能な関数と呼び出し不可能な関数を示しています。

Oracle Tuxedo ATMI システムでは、TPINVALIDCONTEXT 状態で動作するスレッドは以下の関数を呼び出すことができます。

Oracle Tuxedo ATMI システムでは、TPINVALIDCONTEXT 状態で動作するスレッドは以下の関数を呼び出すことができません。

C 言語の ATMI の戻り値とその他の定義

ルーチンは、次に挙げる戻り値とフラグの定義を使用します。異なるトランザクション モニタで変更や再コンパイルなしにアプリケーションを使用するためには、各システムで次に示すようにそのフラグと戻り値を定義しておかなければなりません。

 /*
  * 次の定義は atmi.h に含まれなければならない
  */
 
 
 
 /* サービス ルーチンへのフラグ */
 
  #define TPNOBLOCK     0x00000001 /* 非ブロック送信/受信 */
  #define TPSIGRSTRT    0x00000002 /* 割り込み時受信再開 */
  #define TPNOREPLY     0x00000004 /* 応答なしを想定 */
  #define TPNOTRAN      0x00000008 /* トランザクション モードでは送信しない */
  #define TPTRAN        0x00000010 /* トランザクション モードで送信 */
  #define TPNOTIME      0x00000020 /* タイムアウトなし */
  #define TPABSOLUTE    0x00000040 /* 絶対的な優先順位を指定 */
  #define TPGETANY      0x00000080 /* 有効応答を取り込み */
  #define TPNOCHANGE    0x00000100 /* 受信バッファのマッチング */
  #define RESERVED_BIT1 0x00000200 /* 将来の使用のために予約 */
  #define TPCONV        0x00000400 /* 会話型サービス */
  #define TPSENDONLY    0x00000800 /* 送信専用モード */
  #define TPRECVONLY    0x00001000 /* 受信専用モード */
  #define TPACK         0x00002000 /* */
 
 /* tpreturn() へのフラグ - xa.h にも定義されている */
  #define TPFAIL        0x20000000 /* tpreturn に対するサービスの FAILURE */
  #define TPEXIT        0x08000000 /* サービスの終了によるサービスの FAILURE */
  #define TPSUCCESS     0x04000000 /* tpreturn に対するサービスの SUCCESS */
 
 /* tpscmt() へのフラグ - 有効な TP_COMMIT_CONTROL
  * 特性値
  */
  #define TP_CMT_LOGGED 0x01       /* コミット決定を記録後、
                                    * リターン */
  #define TP_CMT_COMPLETE 0x02     /* コミット完了後、
                                    * リターン */
 
 
 
 /* クライアント識別子構造 */
  struct clientid_t {
  long clientdata[4];              /* 内部での使用のため予約 */
  }
  typedef struct clientid_t CLIENTID;
  /* コンテキスト識別子構造 */
  typedef long TPCONTEXT_T;
  /* サービス ルーチンへのインタフェース */
  struct tpsvcinfo {
  name[32];
  long flags;                      /* サービス属性の説明 */
  char *data;                      /* データを指すポインタ */
  long len;                        /* 要求データ長 */
  int cd;                          /* (flags  TPCONV) が
  * 真のとき接続記述子 */
  long appkey;                     /* アプリケーション認証用のクライアント 
  * キー */
  CLIENTID cltid;                  /* 発行元クライアント用の
   * クライアント識別子 */
  };
 
 typedef struct tpsvcinfo TPSVCINFO;
 
 /* tpinit(3) インタフェース構造 */
  #define MAXTIDENT                30
 
 struct tpinfo_t {
  char usrname[MAXTIDENT+2];       /* クライアント ユーザ名 */
  char cltname[MAXTIDENT+2];       /* アプリケーション クライアント名 */
  char passwd[MAXTIDENT+2];        /* アプリケーション パスワード */
  long flags;                      /* 初期化フラグ */
  long datalen;                    /* アプリケーション固有のデータの長さ */
  long data;                       /* アプリケーション データのプレースホルダ */
  };
  typedef struct tpinfo_t TPINIT;
 
 /* tpsuspend(3) と tpresume(3) に渡されるトランザクション ID 構造体 */
  struct tp_tranid_t {
  long info[6];                    /* 内部的に定義 */
  };
 
 typedef struct tp_tranid_t TPTRANID;
 
 /* TPINIT のフラグ */
  #define TPU_MASK                 0x00000007     /* 非請求通知
                                                   * マスク */
  #define TPU_SIG                  0x00000001     /* シグナル ベース
                                    * の通知 */
  #define TPU_DIP                  0x00000002     /* ディップ イン ベース
                                    * の通知 */
  #define TPU_IGN                  0x00000004     /* 非請求
                                                   * メッセージを無視 */
  #define TPU_THREAD               0x00000040     /* THREAD 通知 */
  #define TPSA_FASTPATH            0x00000008     /* システム アクセス ==
                                                   * fastpath */
  #define TPSA_PROTECTED           0x00000010     /* システム アクセス ==
                                                   * protected */
  #define TPMULTICONTEXTS          0x00000020     /* 各プロセスの
                                                   * マルチ コンテキスト関連 */
  /*  /Q tpqctl_t データ構造体                  */
  #define TMQNAMELEN               15
  #define TMMSGIDLEN               32
  #define TMCORRIDLEN              32
 
 struct tpqctl_t {                 /* キュー プリミティブの制御パラメータ */
  long flags;                      /* どの値が設定されているかを指示 */
  long deq_time;                   /* キューから取り出すときの絶対時間/相対時間 */
  long priority;                   /* 登録優先順位 */
  long diagnostic;                 /* 異常終了の原因 */
  char msgid[TMMSGIDLEN];          /* 既存メッセージの ID (要求をそのメッセージの前に登録するため) */
  char corrid[TMCORRIDLEN];        /* メッセージを識別するときに使用される相関識別子 */
  char replyqueue[TMQNAMELEN+1];   /* 応答メッセージ用キューの名前 */
  char failurequeue[TMQNAMELEN+1]; /* 異常終了メッセージ用キューの名前 */
  CLIENTID cltid;                  /* 発信元クライアントの */
                                   /* クライアント識別子 */
  long urcode;                     /* アプリケーション ユーザ戻り値 */
  long appkey;                     /* アプリケーション認証用のクライアント キー */
  long delivery_qos;               /* 配信サービスの品質 */
  long reply_qos;                  /* 応答メッセージのサービス品質 */
  long exp_time                    /* 有効期限 */
  };
  typedef struct tpqctl_t TPQCTL;
 
 /* 有効な /Q 構造体要素 - フラグに設定 */
  #ifndef TPNOFLAGS
  #define TPNOFLAGS                0x00000    /* フラグの設定なし  -  取得できない */
  #endif
  #define TPQCORRID                0x00001    /* 相関 id を設定/取得 */
  #define TPQFAILUREQ              0x00002    /* 障害キューを設定/取得 */
  #define TPQBEFOREMSGID           0x00004    /* メッセージ id の前にキューに登録 */
  #define TPQGETBYMSGIDOLD         0x00008    /* 使用回避 */
  #define TPQMSGID                 0x00010    /* enq/deq メッセージの msgid を取得 */
  #define TPQPRIORITY              0x00020    /* メッセージ優先順位を設定/取得 */
  #define TPQTOP                   0x00040    /* キューの先頭に登録 */
  #define TPQWAIT                  0x00080    /* キューからの解除を待機 */
  #define TPQREPLYQ                0x00100    /* 応答キューを設定/取得 */
  #define TPQTIME_ABS              0x00200    /* 絶対時間を設定 */
  #define TPQTIME_REL              0x00400    /* 相対時間を設定 */
  #define TPQGETBYCORRIDOLD        0x00800    /* 使用回避 */
  #define TPQPEEK                  0x01000    /* 非破壊的なキューからの取り出し */
  #define TPQDELIVERYQOS           0x02000    /* 配信サービスの品質 */
  #define TPQREPLYQOS              0x04000    /* 応答メッセージのサービス品質 */
  #define TPQEXPTIME_ABS           0x08000    /* 絶対有効期限 */
  #define TPQEXPTIME_REL           0x10000    /* 相対有効期限 */
  #define TPQEXPTIME_NONE          0x20000    /* 有効期限なし */
  #define TPQGETBYMSGID            0x40008    /* msgid によるキューからの取り出し */
  #define TPQGETBYCORRID           0x80800    /* corrid によるキューからの取り出し */

 /* TPQCTL 構造のサービス品質フィールドのための有効フラグ */
  #define TPQQOSDEFAULTPERSIST     0x00001    /* キューのデフォルトの持続性 */
                                              /* ポリシー */
  #define TPQQOSPERSISTENT         0x00002    /* ディスク メッセージ */
  #define TPQQOSNONPERSISTENT      0x00004    /* メモリ メッセージ */

 /* エラー リターン コード */
  extern int tperrno;
  extern long tpurcode;
 
 /* tperrno 値 - エラー コード */
  * マニュアル ページで、下記のエラー コードが返される可能性のある
  * コンテキストに関する説明がある。
  */
 
  #define TPMINVAL                 0          /* 最小のエラー メッセージ */
  #define TPEABORT                 1
  #define TPEBADDESC               2
  #define TPEBLOCK                 3
  #define TPEINVAL                 4
  #define TPELIMIT                 5
  #define TPENOENT                 6
  #define TPEOS                    7
  #define TPEPERM                  8
  #define TPEPROTO                 9
  #define TPESVCERR                10
  #define TPESVCFAIL               11
  #define TPESYSTEM                12
  #define TPETIME                  13
  #define TPETRAN                  14
  #define TPGOTSIG                 15
  #define TPERMERR                 16
  #define TPEITYPE                 17
  #define TPEOTYPE                 18
  #define TPERELEASE               19
  #define TPEHAZARD                20
  #define TPEHEURISTIC             21
  #define TPEEVENT                 22
  #define TPEMATCH                 23
  #define TPEDIAGNOSTIC            24
  #define TPEMIB                   25
  #define TPMAXVAL                 26         /* 最大のエラー メッセージ */
 
 /* 会話 - イベント */
  #define TPEV_DISCONIMM           0x0001
  #define TPEV_SVCERR              0x0002
  #define TPEV_SVCFAIL             0x0004
  #define TPEV_SVCSUCC             0x0008
  #define TPEV_SENDONLY            0x0020
 
 /* /Q 診断コード            */
  #define QMEINVAL                 -1
  #define QMEBADRMID               -2
  #define QMENOTOPEN               -3
  #define QMETRAN                  -4
  #define QMEBADMSGID              -5
  #define QMESYSTEM                -6
  #define QMEOS                    -7
  #define QMEABORTED               -8
  #define QMENOTA                  QMEABORTED
  #define QMEPROTO                 -9
  #define QMEBADQUEUE              -10
  #define QMENOMSG                 -11
  #define QMEINUSE                 -12
  #define QMENOSPACE               -13
  #define QMERELEASE               -14
  #define QMEINVHANDLE             -15
  #define QMESHARE                 -16

 /* イベント ブローカ メッセージ */
  #define TPEVSERVICE              0x00000001
  #define TPEVQUEUE                0x00000002
  #define TPEVTRAN                 0x00000004
  #define TPEVPERSIST              0x00000008
 
 /* サブスクリプション制御構造 */
  struct tpevctl_t {
      long flags;
      char name1[XATMI_SERVICE_NAME_LENGTH];
      char name2[XATMI_SERVICE_NAME_LENGTH];
      TPQCTL qctl;
  };
  typedef struct tpevctl_t TPEVCTL;

C 言語の TX の戻り値とその他の定義

TX ルーチンは、次に挙げる戻り値とフラグの定義を使用します。異なるトランザクション モニタで変更や再コンパイルなしにアプリケーションを使用するためには、各システムで次に示すようにそのフラグと戻り値を定義しておかなければなりません。

#define TX_H_VERSION           0           /* このヘッダ ファイルの
                                            * 現バージョン/
 
 /*
  * トランザクション識別子
  */
  #define XIDDATASIZE          128         /* サイズ (バイト数) */
  struct xid_t {
         long formatID;                    /* 形式識別子 */
         long gtrid_length;                /* 64 以下の値 */
         long bqual_length;                /* 64 以下の値 */
         char data[XIDDATASIZE];
  };
  typedef struct xid_t XID;
  /*
  * 形式識別子が -1 の場合は、XID が NULL であることを意味する
  */
 
 /*
  * tx_ ルーチンの定義
  */
  /* commit の戻り値 */
  typedef long COMMIT_RETURN;
  #define TX_COMMIT_COMPLETED 0
  #define TX_COMMIT_DECISION_LOGGED 1
 
 /* トランザクション制御の値 */
  typedef long TRANSACTION_CONTROL;
  #define TX_UNCHAINED 0
  #define TX_CHAINED 1
 
 /* トランザクション タイムアウトのタイプ */
  typedef long TRANSACTION_TIMEOUT;
 
 /* トランザクションの状態値 */
  typedef long TRANSACTION_STATE;
  #define TX_ACTIVE 0
  #define TX_TIMEOUT_ROLLBACK_ONLY 1
  #define TX_ROLLBACK_ONLY 2
 
 /* tx_info() で格納される構造体 */
  struct tx_info_t {
         XID xid;
         COMMIT_RETURN when_return;
         TRANSACTION_CONTROL transaction_control;
         TRANSACTION_TIMEOUT transaction_timeout;
         TRANSACTION_STATE   transaction_state;
  };
  typedef struct tx_info_t TXINFO;
 
 
 /*
  * tx_() の戻り値
  * (トランザクション マネージャがアプリケーションに報告する)
  */
  #define TX_NOT_SUPPORTED            1 /* サポートされていないオプション */
  #define TX_OK                       0 /* 正常実行 */
  #define TX_OUTSIDE                 -1 /* アプリケーションは、リソース マネージャの
                                         * ローカル トランザクションにある */
  #define TX_ROLLBACK                -2 /* トランザクションが
                                         * ロールバックされた */
  #define TX_MIXED                   -3 /* トランザクションが
                                         * 部分的にコミットされ、
                                         * 部分的にロールバックされた*/
  #define TX_HAZARD                  -4 /* トランザクションが
                                         * 部分的にコミットされ、
                                         * 部分的にロールバックされた可能性がある */
  #define TX_PROTOCOL_ERROR          -5 /* ルーチンが不適切な
                                         * コンテキストで呼び出された */
  #define TX_ERROR                   -6 /* 一時的なエラー */
  #define TX_FAIL                    -7 /* 致命的なエラー */
  #define TX_EINVAL                  -8 /* 無効な引数が指定された */
  #define TX_COMMITTED               -9 /* トランザクションが
                                         * ヒューリスティックにコミットされた */
 
  #define TX_NO_BEGIN                -100 /* トランザクションがコミットされたことに加え、
                                           * 新しいトランザクションが
                                           * 開始できなかった */
  #define TX_ROLLBACK_NO_BEGIN       (TX_ROLLBACK+TX_NO_BEGIN)
                                          /* トランザクションがロールバックされたことに加え、
                                           * 新しいトランザクションが
                                           * 開始できなかった */
  #define TX_MIXED_NO_BEGIN          (TX_MIXED+TX_NO_BEGIN)
                                          /* 混合条件が発生したことに加え、
                                           * 新しいトランザクションが開始できなかった */
  #define TX_HAZARD_NO_BEGIN         (TX_HAZARD+TX_NO_BEGIN)
                                          /* ハザードがあることに加え、
                                           * 新しいトランザクションが開始できなかった */
  #define TX_COMMITTED_NO_BEGIN      (TX_COMMITTED+TX_NO_BEGIN)
                                          /* トランザクションがヒューリスティックにコミットされたことに加え、
                                           * 新しいトランザクションが
                                           * 開始できなかった */

ATMI の状態遷移

Oracle Tuxedo ATMI システムは、各プロセスの状態を記録し、各種の関数呼び出しやオプションごとに正当な状態遷移が行われているかどうかを検証します。この状態情報には、プロセスのタイプ (要求/応答型サーバ、会話型サーバ、またはクライアント)、初期化状態 (初期化済み、非初期化)、リソースの管理状態 (クローズまたはオープン)、プロセスのトランザクション状態およびすべての非同期要求および接続記述子の状態などがあります。不正な状態遷移が行われようとすると、呼び出された関数は異常終了し、tperrno が TPEPROTO に設定されます。この情報に関する正規の状態と遷移について、次の表に示します。

表 4 は、要求/応答型サーバ、会話型サーバおよびクライアントがどの関数を呼び出すことができるかを示しています。ただし、tpsvrinit()、tpsvrdone()、tpsvrthrinit()、および tpsvrthrdone() はこの表には示してありません。これらの関数はアプリケーションが提供する関数ですが、アプリケーションからは呼び出されず、Oracle Tuxedo ATMI システムによって呼び出されます。

以下に示す表は、特に明記されていないかぎり、クライアントとサーバ両方に適用されます。なお、ある種の関数はクライアントとサーバの両方が呼び出せるとは限らないので (例: tpinit())、以下の状態遷移の中には両方のプロセス タイプには適用できないものがあります。上記の表を参照して、目的のプロセスから特定の関数を呼び出すことができるかどうかを判断するようにしてください。

次の表は、クライアント プロセスがトランザクション マネージャで初期化され登録されているかどうかを示しています。この表では、シングルコンテキスト モードのオプションとして tpinit() を使用するものとします。したがって、シングルコンテキストのクライアントは、多数の ATMI 関数の中のどれか (たとえば、tpconnect() または tpcall()) を発行することによって、暗黙的にアプリケーションを結合することができます。次のいずれかにあてはまる場合は、クライアントは tpinit() を使用しなければなりません。

サーバは tpsvrinit() 関数が呼び出される前に Oracle Tuxedo ATMI システムの main() によって初期化状態になり、tpsvrdone() 関数が返された後、Oracle Tuxedo ATMI システムの main() によって非初期化状態になります。なお、下記のすべての表において、関数がエラーを起こした場合、特に明記されていないかぎり、プログラムの状態は変わりません。

以降の表は、前提条件として状態が I₁ であると想定しています (tpinit()、tpsetctxt()、または Oracle Tuxedo ATMI システムの main() を介してこの状態でプロセスが到着したかどうかに関わりなく)。

表 6 は、クライアントまたはサーバのプロセスに対応するリソース マネージャが初期化されているかいないかに応じて、そのプロセスの状態を示しています。

表 7 は、プロセスがトランザクションに対応しているかどうかに関してそのプロセスの状態を示したものです。サーバの場合、状態 T₁ と T₂ への遷位は、前提条件として状態 R₁ を想定しています (たとえば、tpopen() はそれ以降 tpclose() または tpterm() への呼び出しがないものとして呼び出されています)。

表 8 は、tpacall() が返す 1 つの要求記述子の状態を示すものです。

表 9 は、tpconnect() が返す、あるいは TPSVCINFO 構造でサービス呼び出しを行うことによって得られる接続記述子の状態を示したものです。接続記述子をとらないプリミティブの場合、特に明記されていないかぎり、状態の変化はすべての接続記述子に適用されます。

状態には次のものがあります。

TX の状態遷移

Oracle Tuxedo ATMI システムでは、プロセスが必ず TX 関数を正しい順序で呼び出すことが確認されます。不正の状態遷移が試行される (つまり、ブランクの遷移エントリの状態から呼び出しを行う) と、呼び出された関数は、TX_PROTOCOL_ERROR を返します。TX 関数の正当な状態と遷移を、表 10 に示します。異常終了を返す呼び出しの場合、この表で特に明記されていないかぎり、状態遷移は行われません。Oracle Tuxedo ATMI システムのクライアントまたはサーバはすべて、TX 関数を使用できます。

状態は、次のように定義されています。

関連項目

buffer(3c)、tpadvertise(3c)、tpalloc(3c)、tpbegin(3c)、tpcall(3c)、tpconnect(3c)、tpgetctxt(3c)、tpinit(3c)、tpopen(3c)、tpservice(3c)、tpsetctxt(3c), tuxtypes(5)、typesw(5)

AEMsetblockinghook(3c)

名前

AEMsetblockinghook() - アプリケーション固有のブロッキング フック関数を確立

形式

#include <atmi.h>  
int AEMsetblockinghook(_TM_FARPROC)

機能説明

AEMsetblockinghook() は、Mac のタスクで ATMI ネットワーキング ソフトウェアがブロッキング ATMI 呼び出しを実装するための新しい関数をインストールできる「Mac 対応 ATMI エクステンション」です。この関数には、インストールするブロッキング関数の関数アドレスへのポインタが必要です。

ATMI ブロッキング呼び出しを処理する、デフォルトの関数はすでに用意されています。AEMsetblockinghook() 関数によって、アプリケーションは、「ブロッキング」時にデフォルト関数の代わりに独自の関数を実行することができます。NULL ポインタを指定してこの関数を呼び出すと、ブロッキング フック関数はデフォルトの関数にリセットされます。

アプリケーションが ATMI ブロッキング操作を呼び出すと、ブロッキング操作が起動し、次の疑似コードで示すようなループが開始します。

for(;;) {  
        execute operation in non-blocking mode  
        if error
               break;
        if operation complete  
               break;  
        while(BlockingHook())  
                 ;  
}

戻り値

AEMsetblockinghook() は、以前にインストールされたブロッキング関数のプロシージャ インスタンスへのポインタを返します。AEMsetblockinghook() 関数を呼び出すアプリケーションまたはライブラリは、必要に応じて復元できるように、この戻り値を保存する必要があります。「ネスト」が重要でない場合は、アプリケーションは AEMsetblockinghook() によって返された値を廃棄し、最終的に AEMsetblockinghook (NULL) を使ってデフォルト メカニズムを復元することができます。AEMsetblockinghook() はエラー時には NULL を返し、tperrno を設定してエラー条件を示します。

エラー

異常終了時には、AEMsetblockinghook() は tperrno を次の値に設定します。

[TPEPROTO]

移植性

このインタフェースは、Mac クライアントでのみサポートされています。

注意事項

アプリケーションが tpterm(3c) を呼び出すと、ブロッキング関数はリセットされます。

AEOaddtypesw(3c)

名前

AEOaddtypesw() - 実行時にユーザ定義のバッファ タイプをインストールまたはリプレース

形式

#include <atmi.h>  
#include <tmtypes.h>  
 
int FAR PASCAL AEOaddtypesw(TMTYPESW *newtype)

機能説明

AEOaddtypesw() は、OS/2 クライアントが実行時に、新しいユーザ定義のバッファ タイプをインストールするか、既存のユーザ定義のバッファ タイプをリプレースするための、「OS/2 の ATMI 拡張機能」です。この関数の引数は、インストールするバッファ タイプに関する情報を含む、TMTYPESW 構造体を指すポインタです。

type() と subtype() がすでにインストールされているバッファ タイプと一致する場合は、すべての情報が新しいバッファ タイプにリプレースされます。情報が type() フィールドおよび subtype() フィールドと一致しない場合は、Oracle Tuxedo ATMI システムによって登録された既存のバッファ タイプに、新しいバッファ タイプが追加されます。新しいバッファ タイプの場合は、呼び出し処理に含まれる WSH および他の Oracle Tuxedo ATMI システムのプロセスが新しいバッファ タイプで作成されているようにします。

TMTYPESW 配列内の関数ポインタは、EXPORTS セクションにあるアプリケーションのモジュール定義ファイルに表示されていなければなりません。

アプリケーションでは、Oracle Tuxedo ATMI システム定義のバッファ タイプのルーチンも使用できます。また、アプリケーションおよび Oracle Tuxedo ATMI システム バッファ ルーチンを、あるユーザ定義のバッファ タイプ内で混在させることができます。

戻り値

AEOaddtypesw() は、正常終了時には、システム内のユーザ バッファ タイプの数を返します。異常終了時には -1 を返し、tperrno を設定してエラー条件を示します。

エラー

異常終了時には、AEOaddtypesw() は tperrno を次のいずれかの値に設定します。

[TPEINVAL]

[TPESYSTEM]

移植性

このインタフェースは、Windows クライアントでのみサポートされます。タイプ スイッチをインストールする場合は、Oracle Tuxedo ATMI システム タイプスイッチ DLL に追加することをお勧めします。詳細については、『Oracle Tuxedo アプリケーションの設定』を参照してください。

注意事項

FAR PASCAL は、16 ビット OS/2 環境でのみ使用します。

使用例

  #include <os2.h>
  #include <atmi.h>
  #include <tmtypes.h>
 
  int FAR PASCAL Nfinit(char FAR *, long);
  int (FAR PASCAL * lpFinit)(char FAR *, long);
  int FAR PASCAL Nfreinit(char FAR *, long);
  int (FAR PASCAL * lpFreinit)(char FAR *, long);
  int FAR PASCAL Nfuninit(char FAR *, long);
  int (FAR PASCAL * lpFuninit)(char FAR *, long);
 
  TMTYPESW        newtype =
  {
  “MYFML”, ““,  1024,           NULL,           NULL,
  NULL,           _fpresend,      _fpostsend,     _fpostrecv,     _fencdec,
  _froute
  };
 
     newtype.initbuf = Nfinit;
     newtype.reinitbuf = Nfreinit;
     newtype.uninitbuf = Nfuninit;
 
     if(AEOaddtypesw(newtype) == -1) {
             userlog(“AEOaddtypesw failed %s”,  tpstrerror(tperrno));
     }
  int
  FAR PASCAL
  Nfinit(char FAR *ptr, long len)
  {
        ......
        return(1);
  }
 
  int
  FAR PASCAL
  Nfreinit(char FAR *ptr, long len)
  {
        ......
        return(1);
  }
 
  int
  FAR PASCAL
  Nfuninit(char FAR *ptr, long mdlen)
  {
         ......
         return(1);
  }

アプリケーション モジュール定義ファイル:

  ; EXAMPLE.DEF file
 
  NAME         EXAMPLE
 
  DESCRIPTION  'EXAMPLE for OS/2'
 
  EXETYPE      OS/2
 
 
  EXPORTS
          Nfinit
          Nfreinit
          Nfuninit
           ....

関連項目

buildwsh(1)、buffer(3c)、typesw(5)

AEPisblocked(3c)

名前

AEPisblocked() - 進行中のブロッキング呼び出しが存在するかどうかの確認

形式

#include <atmi.h>
int far pascal AEPisblocked(void)

機能説明

AEPisblocked() は、OS/2 プレゼンテーション マネージャ用拡張 ATMI 関数の 1 つです。この関数を使用することにより、OS/2 プレゼンテーション マネージャのタスクは、タスクの実行が前のブロッキング呼び出しの完了を待っている最中にあるかどうかを判断できます。

戻り値

AEPisblocked() は、完了待ちのブロッキング関数が存在する場合は 1 を、それ以外の場合は 0 を返します。

エラー

エラーは返されません。

移植性

このインタフェースは、OS/2 プレゼンテーション マネージャのクライアントにおいてのみサポートされます。

注釈

ATMI ブロッキング呼び出しは、アプリケーションから見ると「ブロック」しているように見えますが、OS/2 PM ATMI DLL は、プロセッサの制御権を放棄して他のアプリケーションが実行できるようにしなければなりません。このことは、ブロッキング呼び出しを発行したアプリケーションが、受信メッセージによって再入する可能性があることを意味します。このような場合は、AEPisblocked() 関数を使用すると、タスクが再入したのが未終了のブロッキング呼び出しの完了を待っている最中だったかどうかを確認できます。ATMI では、未終了の呼び出しが単一スレッド内に 2 つ以上存在することは禁止されているので、注意してください。

関連項目

AEMsetblockinghook(3c)

AEWsetunsol(3c)

名前

AEWsetunsol() - Oracle Tuxedo ATMI 任意イベントに対する Windows メッセージの掲示

形式

#include <windows.h>
#include <atmi.h>
int far pascal AEWsetunsol(HWND hWnd, WORD wMsg)

機能説明

Microsoft Windows のプログラミング環境によっては、Oracle Tuxedo ATMI システムの非請求メッセージを Windows イベント メッセージ キューに送った方がよい場合があります。

AEWsetunsol() は、どのウィンドウに通知を行うか (hWnd)、またどの Windows メッセージ タイプを掲示するか (wMsg) を制御します。Oracle Tuxedo ATMI の非請求メッセージが到達すると、Windows のメッセージが掲示されます。lParam() は Oracle Tuxedo ATMI システムのバッファ ポインタに設定されます。メッセージがなければ、ゼロに設定されます。lParam() がゼロでなければ、アプリケーションは tpfree() を呼び出し、バッファを解放する必要があります。

wMsg がゼロであれば、その後の非請求メッセージはログに入れられ、無視されます。

マルチスレッドのアプリケーションでは、TPINVALIDCONTEXT 状態のスレッドは、AEWsetunsol() 呼び出しを発行することはできません。

戻り値

AEWsetunsol() は、エラー発生時には -1 を返し、エラー条件を示す tperrno を設定します。

エラー

異常終了時には、AEWsetunsol() は tperrno を次のいずれかの値に設定します。

[TPESYSTEM]

[TPEOS]

移植性

このインタフェースは、Microsoft Windows クライアントでしか利用できません。

注意事項

Windows メッセージを掲示する AEWsetunsol() は、tpsetunsol() コールバック ルーチンと同時に起動することはできません。最後の tpsetunsol() 要求あるいは AEWsetunsol() 要求が、非請求メッセージを処理する方法を決定します。

関連項目

tpsetunsol(3c)

buffer(3c)

名前

buffer() - tmtype_sw_t における要素の意味

形式

int     /* 新しいデータ バッファの初期化 */
_tminitbuf(char *ptr, long len)
int    /* 再割り当てされたデータ バッファ */
_tmreinitbuf(char *ptr, long len)
int    /* 解放するデータ バッファの初期化解除 */
_tmuninitbuf(char *ptr, long len)
long   /* 送信前のバッファの処理 */
_tmpresend(char *ptr, long dlen, long mdlen)
void   /* 送信後のバッファの処理 */
_tmpostsend(char *ptr, long dlen, long mdlen)
long   /* 受信後のバッファの処理 */
_tmpostrecv(char *ptr, long dlen, long mdlen)
long   /* 伝送形式とバッファの間のエンコード/デコード */
_tmencdec(int op, char *encobj, long elen, char *obj, long olen)
int    /* データに基づきルーティングのサーバ グループを決定 */
_tmroute(char *routing_name, char *service, char *data, long \  len, char *group)
int    /* バッファのデータのブール式を評価 */
_tmfilter(char *ptr, long dlen, char *expr, long exprlen)
int    /* 形式文字列に基づくバッファのデータの抽出 */
_tmformat(char *ptr, long dlen, char *fmt, char *result, long \  maxresult) 
long   /* 送信前、おそらくコピー生成前のバッファの処理 */
_tmpresend2(char *iptr, long ilen, long mdlen, char *optr, long olen, long *flags )
long  /* マルチバイト コード セットのエンコードの変換 */ 
_tmconvmb(char *ibufp, long ilen, char *enc_name, char *obufp, long olen, long 
*flags)

機能説明

このマニュアル ページでは、tmtype_sw_t 構造体に定義されている要素とルーチンの意味について説明します。ここでの説明は、プロセスのバッファ タイプ スイッチ tm_typesw に新しいバッファ タイプを追加するときに必要になります。スイッチ要素は typesw(5) に定義されています。また、このエントリで使用されている関数名は、Oracle Tuxedo ATMI システムによって定義されている実際の関数名、および独自のバッファ タイプを追加するアプリケーションで定義されている関数名のテンプレートです。これらの名前は、非常に簡単にスイッチ要素に対応付けられます。テンプレート名は、各関数ポインタの要素名とその前に付く _tm で構成されます (たとえば、要素 initbuf の関数名は _tminitbuf() になります)。

要素 type は NULL 以外とし、最大 8 文字でなければなりません。また、要素 subtype には NULL、最大 16 文字の文字列、またはワイルドカード文字 "*" を指定できます。type がスイッチ内でユニークでない場合、subtype を使用しなければなりません。type と subtype の組み合わせは、スイッチ内でユニークに要素を指定するものでなければなりません。

1 つのタイプに対して、複数のサブタイプが存在してもかまいまいせん。すべてのサブタイプを特定のタイプに対して同じように扱う場合には、ワイルドカード文字 "*" を使用することができます。ただし、サブタイプを区別する必要がある場合には、関数 tptypes() を使用して、バッファのタイプとサブタイプを弁別できます。ある特定のタイプ内で一定のサブタイプのサブセットを個別に扱う必要があり、残りを同様に扱う場合には、特定の値でまとめるサブタイプはそのサブタイプをワイルドカードで指定する前にスイッチ内に指定しておく必要があります。このため、まずスイッチ内のタイプとサブタイプの検索が上から下の方向に行われ、ワイルドカードによるサブタイプのエントリは、残りの一致するタイプを受け付けることになります。

要素 dfltsize() は、バッファの割り当てまたは再割り当てを行うときに使用します。tpalloc() と tprealloc() は、dfltsize() およびこれらのルーチンの size パラメータのうち大きい方を使用してバッファの作成または再割り当てを行うことを意味します。固定サイズの C 構造体などの場合、バッファ サイズはその構造体と同じにするべきです。dfltsize() をこの値に設定すると、呼び出し側はバッファが渡されるルーチンに対してそのバッファの長さを指定する必要はなくなります。dfltsize() は 0 あるいはそれ以下にすることができます。ただし、tpalloc() や tprealloc() を呼び出して、その size パラメータも 0 もしくはそれ以下であると、このルーチンは異常終了します。このため、dfltsize() を 0 以下の値に設定することはお勧めできません。

ルーチンの詳細

以下に指定する関数の名前は、Oracle Tuxedo ATMI システム内で使用されるテンプレート名です。新しいルーチンをバッファ タイプ スイッチに追加するアプリケーションは、そのアプリケーションあるいはライブラリ ルーチンが提供する実際の関数に対応する名前を使用しなければなりません。NULL 関数ポインタがバッファ タイプ スイッチ エントリに格納されている場合、Oracle Tuxedo ATMI システムは正しい数と引数タイプをとり、デフォルトの値を返すデフォルト関数を呼び出します。

_tminitbuf()

_tminitbuf() は、バッファの割り当て後、tpalloc() の中から呼び出されます。_tminitbuf() は新しいバッファを指すポインタ ptr とそのサイズを渡されるので、適切にバッファを初期化することができます。len は tpalloc() に渡されるより大きな長さであり、かつそのタイプのスイッチ エントリに dfltsize() で指定されるデフォルト値です。なお、ptr は、tpalloc() と tprealloc() の意味合いから NULL には決してなりません。正常終了すると、ptr が tpalloc() の呼び出し側に返されます。

複数のサブタイプの処理に 1 つのスイッチ エントリを使用する場合、_tminitbuf() の作成者は tptypes() を使用してそのサブタイプを特定することができます。

バッファを初期化しなおす必要がない場合には、NULL 関数ポインタを使用します。

正常終了の場合、_tminitbuf() は 1 を返します。異常終了の場合には、-1 を返し、これによって tpalloc() も異常終了を示す tperrno を TPESYSTEM に返します。

_tmreinitbuf

_tmreinitbuf() はほとんど _tminitbuf() と同様に働きます。ただし、この関数は再割り当てされたバッファを初期化しなおすときに使用します。このルーチンは、バッファの再割り当ての後、tprealloc() の中から呼び出されます。

バッファを初期化しなおす必要がない場合には、NULL 関数ポインタを使用します。

正常終了の場合、_tmreinitbuf() は 1 を返します。異常終了の場合には、-1 を返し、これにより tprealloc() も異常終了を示す tperrno を TPESYSTEM に返します。

_tmuninitbuf

_tmuninitbuf() は、データ バッファの解放前に tpfree() から呼び出されます。_tmuninitbuf() には、データ バッファのアプリケーション部分を指すポインタとそのサイズが渡されるので、これを使用してそのバッファに関連する構造体や状態情報を消去することができます。ptr は、tpfree() のもつ意味合いから決して NULL にはなりません。ただし、_tmuninitbuf() でバッファ自体を解放しないようにしてください。tpfree() 関数は、データ バッファのすべての FLD_PTR フィールドで自動的に呼び出されます。

バッファを解放する前に何も処理が必要とされない場合には、NULL 関数ポインタを使用してください。

正常終了の場合、_tmuninitbuf() は 1 を返します。異常終了の場合には、-1 が返され、tpfree() はログ メッセージを出力します。

_tmpresend

_tmpresend() は、tpcall()、tpacall()、tpconnect()、tpsend()、tpbroadcast()、tpnotify()、tpreturn()、あるいは tpforward() でバッファが送られる前に呼び出されます。また、_tmroute() の後 (ただし _tmencdec() の前) にも呼び出されます。ptr() が NULL でない場合、このルーチンにより、バッファの送信前にバッファに対する前処理を行うことができます。_tmpresend() の最初の引数 ptr は、送信呼び出しに渡されるアプリケーション データ バッファです。2 番目の引数 dlen は、送信呼び出しに渡されるデータの長さです。また、3 番目の引数 mdlen は、データがおかれるバッファの実際の長さです。

この関数に関する重要な条件の 1 つは、関数が返るときに、ptr が指すデータが「そのまま」送られるようにすることです。つまり、_tmencdec() が呼び出されるのはバッファが異なるマシンに送られる場合だけであるので、_tmpresend() は戻る際に、ptr が指すバッファのどの要素も、そのバッファに隣接しないデータを指すポインタとならないようにしなければならないのです。

データに対して前処理が必要なく、呼び出し側が指定したデータ量が送信すべきデータ量と同じ場合、NULL 関数ポインタを使用します。デフォルトのルーチンは dlen を返し、バッファに対して何もしません。

_tmpresend2() が NULL 以外の場合、_tmpresend() は呼び出されず、代わりに _tmpresend2() が呼び出されます。

正常終了の場合、_tmpresend() は送信するデータ量を返します。異常終了の場合には、-1 を返し、_tmpresend() の呼び出し側も異常終了を示す tperrno を TPESYSTEM に返します。

_tmpostsend()

_tmpostsend() は、tpcall()、tpbroadcast()、tpnotify()、tpacall()、tpconnect()、または tpsend() でバッファが送信された後呼び出されます。このルーチンにより、バッファの送信後、関数が戻る前にバッファに対して後処理を行うことができます。送信呼び出しに渡されるバッファは戻り時に異なっていてはならないので、_tmpostsend() を呼び出して、_tmpresend() によってなされたバッファへの変更を修復します。この関数の最初の引数 ptr は、_tmpresend() の実行結果として送信されたデータを指すポインタです。2 番目の引数 dlen は、_tmpresend() から返されるデータの長さです。3 番目の引数 mdlen は、データがおかれるバッファの実際の長さです。このルーチンは、ptr が NULL 以外の場合にのみ呼び出されます。

後処理が必要ない場合には、NULL 関数ポインタを指定します。

_tmpostrecv

_tmpostrecv() は、バッファを受信した後、おそらく tpgetrply()、tpcall()、tprecv()、あるいは Oracle Tuxedo ATMI システムのサーバ用の関数でデコードされた後、アプリケーションに返される前に呼び出されます。ptr が NULL でない場合は、_tmpostrecv() により、バッファが受信された後、アプリケーションに渡される前にそのバッファに対して後処理を行うことができます。最初の引数 ptr は、受信したバッファのデータ部分を指すポインタです。2 番目の引数 dlen は、_tmpostrecv() に入るデータのサイズを指定します。また、3 番目の引数 mdlen は、データがおかれるバッファの実際のサイズです。

_tmpostrecv() が後処理でデータ長を変更した場合は、新しいデータ長を返す必要があります。返される長さは、使用された呼び出しに基づく方法でアプリケーションに渡されます (たとえば、tpcall() は呼び出し側が戻り時にチェックする引数の 1 つにデータ長を設定します)。

後処理が成功するには、バッファの大きさが十分でない可能性があります。容量がさらに必要な場合、_tmpostrecv() は望ましいバッファ サイズの負の絶対値を返します。次いで呼び出しルーチンはバッファの大きさを変更し、_tmpostrecv() を再度呼び出します。

データに対して後処理が不要で、受け取ったデータ量がアプリケーションに返されるデータ量と同じであれば、NULL 関数ポインタを使用します。デフォルトのルーチンは dlen を返し、バッファに対して何もしません。

正常終了の場合、_tmpostrecv() は、そのバッファが対応する受信呼び出しから渡されるときにアプリケーションが知っているべきデータの長さを返します。異常終了の場合、-1 を返し、_tmpostrecv() の呼び出し側も異常終了を示す tperrno を TPESYSTEM に返します。

_tmencdec

_tmencdec() は、異なるデータ表現を使用するマシン間でネットワークを介してバッファを送受信するときにエンコード/デコードを行うために使用します。Oracle Tuxedo ATMI システムでは、XDR の使用が推奨されていますが、このルーチンの意味合いに則っていればどのようなエンコード/デコード方式をとってもかまいません。

この関数は tpcall()、tpacall()、tpbroadcast()、tpnotify()、tpconnect()、tpsend()、tpreturn()、または tpforward() によって呼び出され、呼び出し側のバッファをエンコードします。ただし、この関数は異なるマシンにバッファを送るときにのみ呼び出します。これらの呼び出しの中で、_tmencdec() は _tmroute() と _tmpresend() の後で呼び出されます。ここで、_tmencdec() に渡されるバッファには、そのバッファに隣接しないデータを指すポインタが含まれない、という _tmpresend() の説明を思い出してください。

受信側では、tprecv()、tpgetrply()、tpcall() の受信側、およびサーバ用の関数はすべて _tmencdec() を呼び出して、異なるマシンからバッファを受け取った後、_tmpostrecv() を呼び出す前にこのバッファをデコードします。

_tmencdec() の最初の引数 op は、この関数がデータのエンコードまたはデコードのいずれを行うかを指定します。op には TMENCODE または TMDECODE のいずれかを指定します。

op に TMENCODE を指定すると、encobj は Oracle Tuxedo ATMI システムによって割り当てられたバッファを指します (このバッファにデータのエンコード版が複写されます)。非エンコード データは obj におかれます。つまり、op が TMENCODE であると、_tmencdec() は obj をそのエンコード形式に変換し、結果を encobj に入れます。encobj が指すバッファのサイズは elen によって指定され、obj によって示されるバッファの長さ (olen) の少なくとも 4 倍です。olen は、_tmpresend によって返される長さです。_tmencdec() は、エンコードされたデータの長さを encobj (つまり、実際に送信するデータ量) で返します。_tmencdec() は、この関数に渡されるバッファのいずれも解放しないものとします。

op に TMDECODE を指定すると、encobj は Oracle Tuxedo ATMI システムによって割り当てられたバッファを指します (このバッファにデータのエンコード版がおかれます)。バッファの長さは elen です。obj は、encobj が指すバッファ (ここにデコードされたデータが複写されます) と少なくとも同じサイズを持つバッファのポインタです。obj の長さは、olen です。obj はアプリケーションによって最終的に返されるバッファであるため、Oracle Tuxedo ATMI システムは _tmencdec() を呼び出す前に、デコード データを収めるのに十分な大きさになるようこのバッファのサイズを大きくすることができます。_tmencdec() は、デコード データのサイズを obj に返します。_tmencdec() が戻ると、_tmpostrecv() がその最初の引数として obj、2 番目の引数として _tmencdec() の戻り値、そして 3 番目の引数として olen をとって呼び出されます。_tmencdec() は、この関数に渡されるバッファのいずれも解放しないものとします。

_tmencdec() は、NULL 以外のデータをエンコードあるいはデコードする必要がある場合にのみ呼び出されます。

異なるマシンがネットワーク上に存在する場合でもデータにデコードあるいはエンコードを行う必要がない場合には、NULL 関数ポインタを使用します。このルーチンは olen (op は TMENCODE と同じ) あるいは elen (op は TMDECODE と同じ) のいずれかを返します。

正常終了の場合、_tmencdec() は、上述のように負でないバッファ長を返します。異常終了の場合、-1 を返し、_tmencdec() の呼び出し側も異常終了を示す tperrno を TPESYSTEM に返します。

_tmroute

メッセージは、デフォルトの設定では、要求されたサービスを提供する任意のサーバ グループにルーティングされます。UBBCONFIG ファイルに記述する各サービス エントリでは、ROUTING パラメータを使用して該当サービスのルーティング基準の論理名を指定することができます。複数のサービスが同じルーティング基準を共有することができます。あるサービスがルーティング基準名を指定されている場合、_tmroute() を使用して、メッセージ中のデータに基づいてそのメッセージが送信されるサーバ グループを判別します。データとサーバ グループのこの対応付け方法を、「データ依存型ルーティング」と呼んでいます。_tmroute() の呼び出しは、バッファの送信前 (そして、_tmpresend() と _tmencdec() が呼び出される前) に tpcall()、tpacall()、tpconnect()、および tpforward() で行います。

routing_name は、ルーティング基準の論理名 (UBBCONFIG ファイルに指定されている) であり、データ依存ルーティングを必要とするサービスと関連付けられています。service は、要求の対象となるサービスの名前です。パラメータ data は、要求で送出されるデータを指し、len はそのデータの長さです。ここで説明している他のルーチンと異なり、_tmroute() は ptr が NULL の場合でも呼び出されます。group パラメータは、要求の送り先になるグループの名前を返すときに使用します。このグループ名は、UBBCONFIG ファイルに記述されているグループ名の 1 つ (および、そのグループが選択されたときにアクティブであったグループ名) と一致していなければなりません。要求を指定サービスを提供する任意のサーバに送ることができる場合、group を NULL 文字列に設定し、この関数が 1 を返すようにしてください。

データ依存ルーティングが該当バッファ タイプに必要とされない場合には、NULL 関数ポインタを使用してください。このルーチンは group を NULL 文字列に設定し、1 を返します。

正常終了の場合、_tmroute() は 1 を返します。異常終了の場合、-1 を返し、_tmroute() の呼び出し側も異常終了を返します。これにより、tperrno が TPESYSTEM にセットされます。サーバあるいはサービスが利用できないために _tmroute() が異常終了した場合は、tperrno は TPENOENT にセットされます。

group が無効なサーバ グループの名前に設定されると、_tmroute() を呼び出す関数はエラーを返し、tperrno を TPESYSTEM に設定します。

_tmfilter()

_tmfilter() は、tppost() によってポストされたバッファの内容を分析するためにイベント ブローカ サーバによって呼び出されます。サブスクライバ (tpsubscribe()) が提供した式がバッファの内容を基に評価されます。式が真の場合、_tmfilter() は 1 を返し、イベント ブローカはサブスクライバへの通知処理を実行します。_tmfilter() が 0 を返した場合は、イベント ブローカはこのポストをサブスクリプションの「一致」とみなしません。

exprlen が -1 の場合、expr は NULL で終わる文字列とみなされます。それ以外の場合、expr は exprlen バイトのバイナリ データとみなされます。exprlen が 0 の場合は、式がないことを示します。

フィルタリングがこのバッファ タイプに適用しない場合は、NULL 関数ポインタを指定します。デフォルトのルーチンは、式がないか、expr が空の NULL で終わる文字列の場合は 1 を返します。それ以外の場合、デフォルトのルーチンは 0 を返します。

_tmformat()

_tmformat() は、fmt という形式指定に従って、バッファのデータを表示可能な文字列に変換するためにイベント ブローカ サーバによって呼び出されます。イベント ブローカは、userlog または system 通知処理の入力のためにポストされたバッファを文字列に変換します。

出力は、result が指すメモリの位置に文字列として格納されます。result には、終端 NULL 文字を含めて最大 maxresult バイト書き込まれます。result の大きさが十分でない場合は、_tmformat() は出力を切り捨てます。出力文字列は、必ず NULL で終わります。

正常終了の場合、_tmformat() は負でない整数を返します。1 は正常終了、2 は出力文字列が切り捨てられたことを示します。異常終了の場合、-1 を返し、result に空の文字列を格納します。

形式設定がこのバッファ タイプに適用しない場合は、NULL 関数ポインタを指定します。デフォルトのルーチンが後を引き継ぎ、result に空の文字列を返します。

_tmpresend2

_tmpresend2() は、tpcall()、tpacall()、tpconnect()、tpsend()、tpbroadcast()、tpnotify()、tpreturn()、および tpforward() でバッファが送られる前に呼び出されます。また、_tmroute() の後 (ただし _tmencdec() の前) にも呼び出されます。iptr が NULL 以外の場合、このルーチンにより、バッファの送信前に、バッファに対する前処理を行うことができます。

_tmpresend2() の最初の引数 iptr は、送信呼び出しに渡されるアプリケーション データ バッファです。2 番目の引数 ilen は、送信呼び出しに渡されるデータの長さです。3 番目の引数 mdlen は、データがおかれるバッファの実際の長さです。

_tmpresend() とは異なり、_tmpresend2() は必要な処理がすべて終了した後で、ポインタ optr を受信し、これを使って iptr のデータを置くバッファを指すポインタを渡します。このポインタを使用するのは、入力バッファを修正する代わりに、_tmpresend2() が修正したデータに新しいバッファを使用する場合です。5 番目の引数 olen は、optr バッファのサイズです。6 番目の引数 flags は、処理されるバッファが親バッファ (送信先バッファ) かどうかを _tmpresend2() に通知します。_tmpresend2() は flags 引数を返して、処理結果を示します。

optr バッファの大きさが不十分で、後処理ができない場合があります。容量がさらに必要な場合、_tmpresend2() は必要なバッファ サイズの負の絶対値を返します。optr バッファの olen バイトはすべて維持されます。次に呼び出しルーチンがバッファの大きさを変更し、_tmpresend2() を再度呼び出します。

データに対して後処理が不要で、受け取ったデータ量がアプリケーションに返されるデータ量と同じであれば、NULL 関数ポインタを使用します。デフォルトのルーチンは ilen を返し、バッファに対して何もしません。

以下は、_tmpresend2() に入力可能なフラグです。

[TMPARENT]

flags で返されるフラグは、_tmpresend2() の結果を示します。可能な値は次のとおりです。

[TMUSEIPTR]

[TMUSEOPTR]

TMUSEOPTR が返された場合、メッセージ伝送後の処理が _tmpresend() の処理とは異なります。つまり、iptr バッファは変更されず、_tmpostsend() は呼び出されません。TMUSEIPTR が返された場合、_tmpostsend() で呼び出されるように _tmpresend() が呼び出されます。optr バッファの割り当てと、解放またはキャッシュは、呼び出し側が行います。

型付きバッファにこの方法を用いるのは、次のような理由によります。

_tmpresend2() 関数は、関数が返るときに、バッファ内の送信データをそのまま送信できるようにします。_tmencdec() は類似しないマシンにバッファが送信される場合にだけ呼び出されるため、_tmpresend2() は、すべてのデータが送信されるバッファ内に隣接して保存されるようにします。

データに対する前処理が不要で、呼び出し側が指定したデータ量が送信すべきデータ量と同じ場合、バッファ タイプ スイッチの _tmpresend2() に NULL の関数ポインタを指定します。_tmpresend2() が NULL の場合、デフォルト設定によって _tmpresend() が呼び出されます。

正常終了時には、_tmpresend2() は送信するデータ量を返します。より大きなバッファが必要な場合は、必要なバッファ サイズの負の絶対値を返します。異常終了時には -1 を返し、これによって _tmpresend2() の呼び出し側も異常終了を返して tperrno を TPESYSTEM に設定します。

_tmconvmb

_tmconvmb() は、tmpostrecv() がマルチバイト データをソースのエンコードから対象のエンコードに変換した後に呼び出されます。_tmconvmb() の最初の引数 ibufp は、変換するバイトのストリーム (マルチバイト データ) を指すポインタです。2 番目の引数 ilen は、ibufp 内のバイト数です。3 番目の引数 enc_name は、処理で使用するいずれかのエンコード名です。MBSTRING バッファの場合、この引数は対象のエンコード名になります。FML32 バッファの場合、この引数はソースのエンコード名になります。

_tmconvmb() は、必要なコード セットのエンコードの変換がすべて終了した後で、ポインタ obufp を受信し、これを使って ibufp のデータを置くバッファを指すポインタを渡します。このポインタを使用するのは、入力ポインタを修正する代わりに、_tmconvmb() が変換したデータに新しいバッファを使用する場合です。5 番目の引数 olen は、obufp バッファのサイズです。_tmconvmb() は flags 引数を返して、処理結果を示します。

obufp バッファのサイズが不十分で、後処理ができない場合があります。容量がさらに必要な場合、_tmconvmb() は必要なバッファ サイズの負の絶対値を返します。ibufp バッファの ilen バイトはすべて維持されます。次に呼び出しルーチンがバッファの大きさを変更し、_tmconvmb() を再度呼び出します。

データのコード セットのエンコード変換が必要ない場合、送信側のプロセスのエンコード名と受信側のプロセスのエンコード名が同じ場合は、NULL 関数ポインタを指定します。デフォルトのルーチンは ilen を返し、バッファに対して変換を行いません。コード セットのエンコードの変換方法が不明の場合、この関数は -1 を返します。

flags で返される値は、_tmconvmb() の結果を示します。可能な値は次のとおりです。

[TMUSEIPTR]

[TMUSEOPTR]

正常終了時には、_tmconvmb() は、コード セットのエンコードの変換が行われたデータ バッファの大きさを返します。より大きなバッファが必要な場合は、必要なバッファ サイズの負の絶対値を返します。異常終了時には -1 を返し、これによって _tmconvmb() の呼び出し側も異常終了を返して tperrno を TPESYSTEM に設定します。

関連項目

tpacall(3c)、tpalloc(3c)、tpcall(3c)、tpconnect(3c)、tpdiscon(3c)、tpfree(3c)、tpgetrply(3c)、tpgprio(3c)、tprealloc(3c)、tprecv(3c)、tpsend(3c)、tpsprio(3c)、tptypes(3c)、tuxtypes(5)

catgets(3c)

名前

catgets() - プログラム メッセージの読み取り

形式

#include <nl_types.h> 
char *catgets (nl_catd catd, int set_num, int msg_num, char *s)

機能説明

catgets() は、セット set_num 内のメッセージ msg_num を、catd で指定されたメッセージ カタログから読み取ります。catd は、先に呼び出された catopen() から返されたカタログ記述子です。s は、デフォルトのメッセージ文字列を指すポインタであり、指定されたメッセージ カタログが現在利用できない場合に、catgets() から返されます。

マルチスレッドのアプリケーションのスレッドは、TPINVALIDCONTEXT を含むどんなコンテキスト状態でも、catgets() を呼び出すことができます。

診断

指定されたメッセージが正常に取り出されると、catgets() は NULL で終了するメッセージ文字列を収める内部バッファ領域を指すポインタを返します。catd によって指定されているメッセージ カタログがその時点で利用できないために呼び出しが異常終了した場合には、s を指すポインタが返されます。

関連項目

catopen、catclose(3c)

catopen、catclose(3c)

名前

catopen()、catclose() - メッセージ カタログのオープン/クローズ

形式

#include <nl_types.h> 
nl_catd catopen (char *name, int oflag) 
int catclose (nl_catd catd)

機能説明

catopen() はメッセージ カタログをオープンし、カタログ記述子を返します。name は開くメッセージ カタログの名前を指定します。name に「/」があると、次にくる name はメッセージ カタログのパス名を示します。それ以外の場合、環境変数 NLSPATH が使用されます。NLSPATH が環境にない場合や、NLSPATH で指定されたパスでメッセージ カタログをオープンできない場合には、デフォルトのパスが使用されます (nl_types(5) を参照)。

メッセージ カタログの名前とそれらの格納場所は、システムによって異なる可能性があります。個々のアプリケーションは、それぞれのニーズに従ってメッセージ カタログの名前を付けたり、格納場所を指定したりすることができます。したがって、カタログを格納する場所を指定するためのメカニズムが必要となります。

NLSPATH 変数では、メッセージ カタログの格納場所を検索パスの形式で指定したり、メッセージ カタログ ファイルに対応するネーミング規則を使用することができます。次に例を示します。

NLSPATH=/nlslib/%L/%N.cat:/nlslib/%N/%L

メタキャラクタ % は、置換フィールドを示します。この例で、%L は LANG 環境変数の現在の設定と置き替わります (下記の項を参照)。また、%N は catopen() に渡される name パラメータの値と置き替わります。このため、上例で、catopen() はまず /nlslib/$LANG/name.cat、次に /nlslib/name/$LANG を検索して、目的のメッセージ カタログを見つけようとします。

NLSPATH は通常、システム全体にわたって有効になるよう設定されるので (すなわち、/etc/profile)、メッセージ カタログに関連する格納場所とネーミング規則をプログラムもユーザも意識する必要はありません。

次の表は、メタキャラクタ セットのリストです。

LANG 環境変数では、ネイティブ言語、地域の習慣および文字セットに関してユーザの要求条件を ASCII 文字列の形式 (LANG=language[_territory[.codeset]]) で指定することができます。

オーストリアで使用されるドイツ語を話すユーザが、ISO 8859/1 コードセットを用いている端末を使用する場合、LANG 環境変数は次のように設定します。

LANG=De_A.88591

この設定により、ユーザは関連するカタログ (存在すれば) を見つけることができるはずです。

LANG 変数が設定されていない場合、setlocale(3c) によって返される LC_MESSAGES の値が使用されます。この値が NULL の場合、nl_types(5) に定義されているデフォルトのパスが使用されます。

引数 oflag() は使用されません。この引数は将来使用する予定であり、現在は必ずゼロを指定してください。このフィールドの値を別の値に変更した場合の動作は不定です。

catclose() は catd によって指定されたメッセージ カタログをクローズします。

マルチスレッドのアプリケーションのスレッドは、TPINVALIDCONTEXT を含むどんなコンテキスト状態でも、catopen() または catclose() 呼び出すことができます。

診断

正常終了の場合、catopen() は、以後の catgets() および catclose() の呼び出し時に使用するメッセージ カタログ記述子を返します。異常終了であれば、catopen() は (nl_catd) -1 を返します。catclose() は、正常終了のとき 0、異常終了のとき -1 を返します。

関連項目

catgets(3c)、setlocale(3c)、nl_types(5)

decimal(3c)

名前

decimal() - 十進数変換および算術ルーチン

形式

#include “decimal.h”  

int
lddecimal(cp, len, np)        /* 十進数をロード */
char*cp;         /* 入力 : 圧縮した形式の位置 */

int
len;             /* 入力 : 圧縮した形式の長さ */
dec_t*np;        /* 出力 : dec_t 形式の位置 */

void
stdecimal(np, cp, len)       /* 十進数を格納 */
dec_t*np;        /* 入力 : dec_t 形式の位置 */
char*cp;         /* 出力 : 圧縮した形式の位置 */
int len;         /* 入力 : 圧縮した形式の長さ */

int
deccmp(n1, n2)   /* 2 つの十進数を比較 */
dec_t*n1;        /* 入力 : 比較する数 */
dec_t*n2;        /* 入力 : 比較する数 */

int
dectoasc(np, cp, len, right) /* dec_t をアスキーに変換 */
dec_t*np;        /* 入力 : 変換する数 */
char*cp;         /* 出力 : 変換後の数 */
int len;         /* 入力 : 出力文字列の長さ */
int right;       /* 入力 : 小数点以下の数 */

int
deccvasc(cp, len, np)        /* アスキーを dec_t に変換 */
char*cp;         /* 入力 : 変換する数 */
int len;         /* 入力 : 変換する数の最大長 */
dec_t*np;        /* 出力 : 変換後の数 */

int
dectoint(np, ip)             /* int を dec_t に変換 */
dec_t*np;        /* 入力 : 変換する数 */
int *ip;         /* 出力 : 変換後の数 */

int
deccvint(in, np) /* dec_t を int に変換 */
int in;          /* 入力 : 変換する数 */
dec_t*np;        /* 出力 : 変換後の数 */

int
dectolong(np, lngp)         /* dec_t を long に変換 */
dec_t*np;        /* 入力 : 変換する数 */
long*lngp;       /* 出力 : 変換後の数 */

int
deccvlong(lng, np)        /* long を dec_t に変換 */
longlng;        /* 入力 : 変換する数 */
dec_t*np;       /* 出力 : 変換後の数 */

int
dectodbl(np, dblp)        /* dec_t を double に変換 */
dec_t*np;       /* 入力 : 変換する数 */
double *dblp;   /* 出力 : 変換後の数 */

int
deccvdbl(dbl, np)        /* double を dec_t に変換 */
double *dbl;        /* 入力 : 変換する数 */
dec_t*np;       /* 出力 : 変換後の数 */

int
dectoflt(np, fltp)        /* dec_t を float に変換 */
dec_t*np;       /* 入力 : 変換する数 */
float*fltp;     /* 出力 : 変換後の数 */

int
deccvflt(flt, np)         /* float を dec_t に変換 */
double *flt;    /* 入力 : 変換する数 */
dec_t*np;       /* 出力 : 変換後の数 */

int
decadd(*n1, *n2, *n3)     /* 2 つの十進数の加算を行う */
dec_t*n1;        /* 入力 : 加数 */
dec_t*n2;        /* 入力 : 加数 */
dec_t*n3;        /* 出力 : 合計 */

int
decsub(*n1, *n2, *n3)     /* 2 つの十進数の減算を行う */
dec_t*n1;        /* 入力 : 被減数 */
dec_t*n2;        /* 入力 : 減数 */
dec_t*n3;        /* 出力 : 差 */

int
decmul(*n1, *n2, *n3)     /* 2 つの十進数の乗算を行う */
dec_t*n1;        /* 入力 : 被乗数 */
dec_t*n2;        /* 入力 : 被乗数 */
dec_t*n3;        /* 出力 : 積 */

int
decdiv(*n1, *n2, *n3)    /* 2 つの十進数の除算を行う */
dec_t*n1;        /* 入力 : 被除数 */
dec_t*n2;        /* 入力 : 除数 */
dec_t*n3;        /* 出力 : 商 */

機能説明

これらの関数を使用すると Oracle Tuxedo ATMI システムにおいてパック十進データを格納、変換、および操作することができます。Oracle Tuxedo ATMI システムにおいて表現される十進数のデータ型の形式は、CICS でのその表現とは異なることに注意してください。

マルチスレッドのアプリケーションのスレッドは、TPINVALIDCONTEXT を含むどんなコンテキスト状態でも、10 進数の変換関数を呼び出すことができます。

ネイティブの十進数表現

十進数は、Oracle Tuxedo ATMI システム上では dec_t 構造体を使用して表現されます。この構造体の定義を次に示します。

#define DECSIZE                 16
struct decimal {
       short dec_exp;           /* 指数底 100  */
       short dec_pos;           /* 符号 : 1=pos、0=neg、-1=null */
       short dec_ndgts;         /* 有効桁数 */
       char  dec_dgts[DECSIZE]; /* 実際の桁数底 100 */
};
typedef struct decimal dec_t;

プログラマは、dec_t 構造体に直接アクセスする必要はありません。基本的なデータ構造体を理解するためにこの構造体を提示します。莫大な十進数データを格納する必要がある場合、より圧縮した形式を得るために stdecimal()、lddecimal() 関数を使用します。dectoasc()、dectoint()、dectolong()、dectodbl() および dectoflt() を使用すると、十進数から他のデータ タイプへ変換することができます。deccvasc()、deccvint()、deccvlong()、deccvdbl() および deccvflt() を使用すると、他のデータ タイプから十進数のデータ タイプに変換することができます。deccmp() は、2 つの十進数を比較する関数です。1 番目の十進数が 2 番目の十進数より小さい場合、-1 を返します。2 つの十進数が等しい場合、0 を返します。1 番目の十進数が 2 番目の十進数より大きい場合 1 を返します。どちらかの引数が無効である場合、-1 以外の負の値を返します。decadd()、decsub()、decmul() および decdiv() は、十進数の算術演算を行います。

戻り値

特に指定がない限り、これらの関数は、正常終了時には 0 を返し、エラー時には負の数を返します。

getURLEntityCacheDir(3c)

名前

getURLEntityCacheDir() - DTD、スキーマ、およびエンティティ ファイルがキャッシュされている場所の絶対パスを取得する Xerces クラス メソッドの指定

形式

char * getURLEntityCacheDir()

機能説明

getURLEntityCacheDir() は、呼び出し側が DTD、スキーマ、およびエンティティ ファイルがキャッシュされている場所を検索する必要がある場合に呼び出されるメソッドで、キャッシュされたファイルの場所の絶対パスを返します。このメソッドは、以下の 2 つの Xerces オブジェクトと組み合わせて排他的に使用されます。

getURLEntityCaching(3c)

名前

GetURLEntityCaching() - DTD、スキーマ、およびエンティティ ファイルのキャッシュ機構の取得する Xerces クラス メソッドの指定

形式

bool getURLEntityCaching()

機能説明

GetURLEntityCaching() は、DTD、スキーマ、およびエンティティ ファイルのキャッシュが有効になっているか無効になっているかを検索する必要がある場合に呼び出されるメソッドで、戻り値は、キャッシュが有効になっている場合は true、無効になっている場合は false です。このメソッドは、以下の 2 つの Xerces オブジェクトと組み合わせて排他的に使用されます。

gp_mktime(3c)

名前

gp_mktime() - tm 構造体をカレンダー時間に変換します。

形式

#include <time.h>  
time_t gp_mktime (struct tm *timeptr);

機能説明

gp_mktime() は、timeptr が指す tm 構造体で表現される時間をカレンダー時間 (1970 年 1 月 1 日から数えた秒数) に変換します。

tm 構造体の形式は次の通りです。

struct tm {
  int tm_sec;     /* その分からの秒数 [0, 61] */
  int tm_min;     /* その時間からの分数 [0, 59] */
  int tm_hour;    /* 深夜 12 時からの時間数 [0, 23] */
  int tm_mday;    /* その月の日付 [1, 31] */
  int tm_mon;     /* 1 月からの月数 [0, 11] */
  int tm_year;    /* 1900 年からの年数 */
  int tm_wday;    /* 日曜日からの日数 [0, 6] */
  int tm_yday;    /* 1 月 1 日からの日数 [0, 365] */
  int tm_isdst;   /* 夏時間のフラグ */
};

gp_mktime() は、カレンダー時間を計算する以外に、指定された tm 構造体を正規化します。構造体の tm_wday メンバーと tm_yday メンバーの元の値は無視され、他のメンバーの元の値は、構造体の定義で示される範囲に制限されません。正常終了の場合、tm_wday および tm_yday の値は適切に設定されます。他のメンバーは指定されたカレンダー時間を表すように設定されますが、それらの値は、正しい範囲内に収まるように強制されます。tm_mday の最終的な値は、tm_mon および tm_year が決まるまで設定されません。

構造体の各メンバーの元の値は、決められた範囲よりも大きくても小さくてもかまいません。たとえば、tm_hour が -1 なら、深夜 12 時の 1 時間前、tm_mday が 0 ならその月の 1 日前、tm_mon が -2 なら、tm_year の 1 月の 2 ヵ月前を意味します。

tm_isdst が正の場合、元の値は代替タイムゾーンに基づいていると見なされます。代替タイムゾーンが計算されたカレンダー時間に対して有効でないことが判明すると、各メンバーはメイン タイムゾーンに調整されます。同様に、tm_isdst がゼロの場合、元の値はメイン タイムゾーンであると見なされ、メイン タイムゾーンが有効でなければ代替タイムゾーンに変換されます。tm_isdst が負の場合、正しいタイムゾーンが判断され、各メンバーは調整されません。

ローカル タイムゾーンの情報は、あたかも gp_mktime() が tzset() を呼び出したかのように使われます。

gp_mktime() は、特定のカレンダー時間を返します。カレンダー時間を表現できない場合、この関数は値 (time_t)-1 を返します。

マルチスレッドのアプリケーションのスレッドは、TPINVALIDCONTEXT を含むどんなコンテキスト状態でも、gp_mktime() を呼び出すことができます。

使用例

2001 年 7 月 4 日は何曜日か ?

  #include <stdio.h>
  #include <time.h>
 
  static char *const wday[] = {
  "Sunday", "Monday", "Tuesday", "Wednesday",
  "Thursday", "Friday", "Saturday", "-unknown-"  
  };
 
  struct tm time_str;
  /*...*/  
  time_str.tm_year        = 2001 - 1900;  
  time_str.tm_mon         = 7 - 1;
  time_str.tm_mday        = 4;
  time_str.tm_hour        = 0;
  time_str.tm_min         = 0;
  time_str.tm_sec         = 1;
  time_str.tm_isdst       = -1;
  if (gp_mktime(time_str) == -1)
     time_str.tm_wday=7;
  printf("%s\en", wday[time_str.tm_wday]);

注意事項

tm 構造体の tm_year は、1970 年以降でなければなりません。1970 年 1 月 1 日の 00:00:00 UTC より前、または 2038 年 1 月 19 日の 03:14:07 UTC より後のカレンダー時間を表現することはできません。

移植性

コンパイル システムが ANSI C の mktime() 関数をすでに提供しているシステムでは、gp_mktime() は mktime() を呼んで、変換を行うだけです。それ以外の場合、変換は直接 gp_mktime() の内部で行われます。

後者の場合、TZ 環境変数が設定されていなければなりません。多くのインストレーションでは、TZ は、ユーザがログオンする際にデフォルトで正しい値に設定されることに注意してください。TZ のデフォルト値は GMT0 です。TZ の形式は次の通りです。

stdoffset[dst[offset],[start[time],end[time]]]

std および dst

offset

start/time,end/time

Mm.n.d

start および end には、これらの省略可能なフィールドが与えられなかった場合、実装依存のデフォルトが使用されます。

time は、offset と同じ形式で、違いは先頭の符号 ("-" または "+") が許されることです。time が与えられなかった場合のデフォルトは 02:00:00 です。

関連項目

UNIX システムのリファレンス マニュアルの ctime(3c) と getenv(3c)、timezone(4)

nl_langinfo(3c)

名前

nl_langinfo() - 言語情報

形式

#include <nl_types.h>
#include <langinfo.h>

char *nl_langinfo (nl_item item);

機能説明

nl_langinfo() は、ある特定言語あるいはプログラム ロケールで定義されている文化圏に関連する情報を収めた NULL で終わる文字列を指すポインタを返します。item に入る定数名と値は langinfo.h に定義されています。

次に例を示します。

nl_langinfo (ABDAY_1);

指定された言語がフランス語で、フランス語のロケールが正しくインストールされていれば、文字列「Dim」を指すポインタを返します。また、指定された言語が英語であれば、「Sun」が返されます。

マルチスレッドのアプリケーション中のスレッドは、TPINVALIDCONTEXT を含め、どのコンテキスト状態で実行していても、nl_langinfo() の呼び出しを発行できます。

診断

setlocale() が正常に呼び出されなかった場合、あるいはサポートされている言語の langinf0() データが存在しないか、item が該当箇所に定義されていない場合には、nl_langinfo() は C ロケールの対応する文字列を指すポインタを返します。どのロケールの場合も、item に無効な文字列が指定されると、nl_langinfo() は空の文字列を指すポインタを返します。

注意事項

戻り値が指す配列は、プログラムで変更しないようにしてください。nl_langinfo() の次の呼び出しで、この配列の内容は変わってしまいます。

関連項目

setlocale(3c)、strftime(3c)、langinfo(5)、nl_types(5)

rpc_sm_allocate、rpc_ss_allocate(3c)

名前

rpc_sm_allocate()、rpc_ss_allocate()—RPC スタブ メモリ管理方式でのメモリの割り当て

形式

#include <rpc/rpc.h>

idl_void_p_t rpc_sm_allocate(unsigned32 size, unsigned32 *status)

idl_void_p_t rpc_ss_allocate(unsigned32 size)

機能説明

アプリケーションは rpc_sm_allocat3() を呼び出し、RPC スタブ メモリ管理方式でメモリを割り当てます。入力パラメータ size は、割り当てるメモリの大きさをバイト単位で指定します。このルーチンを呼び出す前に、スタブ メモリ管理環境が確立されていなければなりません。サーバ スタブから呼び出されるサービス コードでは通常、スタブ自身が必要な環境を確立します。スタブから呼び出されないコードで rpc_sm_allocate() を使用する場合には、アプリケーションが rpc_sm_enable_allocate() を呼び出し、必要なメモリ管理環境を確立しなければなりません。

サーバ スタブのパラメータ中に参照によるパラメータの転送に使用される以外のポインタが含まれている、あるいは [enable_allocate] 属性が ACS ファイル内の操作に指定されている場合には、環境は自動的に設定されます。そうでなければ、環境は rpc_sm_enable_allocate() を呼び出すことで、アプリケーションにより設定されなければなりません。

スタブがメモリ管理環境を確立する場合には、スタブ自身が rpc_sm_allocate() により割り当てられたメモリを解放します。アプリケーションは rpc_sm_free() を呼び出し、呼び出し側スタブに戻る前にメモリを解放することができます。

アプリケーションがメモリ管理環境を確立した場合には、アプリケーションは rpc_sm_free() または rpc_sm_disable_allocate() を呼び出し、割り当てられたすべてのメモリを解放しなければなりません。

出力パラメータ status には、このルーチンからのステータス コードが返されます。このステータス コードは、ルーチンが成功して完了したか、または失敗した場合はその理由を示します。次は、ステータス コードとその意味の一覧です。

rpc_s_ok

rpc_ss_allocate() は、この関数の例外復帰バージョンであり、出力パラメータ status を持ちません。例外は発生しません。

マルチスレッドのアプリケーション中のスレッドは、TPINVALIDCONTEXT を含め、どのコンテキスト状態で実行していても、rpc_sm_allocate() または rpc_ss_allocate() の呼び出しを発行できます。

戻り値

正常終了すると、このルーチンは割り当てられたメモリを指すポインタを返します。idl_void_p_t は、ISO 標準 C 環境では void * に、他の環境では char * に定義されていることに注意してください。

メモリ不足の場合、ルーチンは NULL ポインタを返します。

関連項目

rpc_sm_disable_allocate、rpc_ss_disable_allocate(3c)、rpc_sm_enable_allocate、rpc_ss_enable_allocate(3c)、rpc_sm_free、rpc_ss_free(3c)

『TxRPC を使用した Oracle Tuxedo アプリケーションのプログラミング』

rpc_sm_client_free、rpc_ss_client_free(3c)

名前

rpc_sm_client_free()、rpc_ss_client_free()—クライアント スタブから返されたメモリの解放