|
|
アプリケーション・トランザクション・モニター・インタフェース(ATMI)は、アプリケーションとトランザクション処理システムの間のインタフェースを提供します。このインタフェースは、ATMIインタフェースと呼ばれています。これは、リソースのオープンとクローズ、トランザクションの管理、型付きバッファの管理、リクエスト/レスポンス型および会話型サービスの呼出しなどを行う関数呼出しを提供します。
ATMIマニュアル・ページに記述されている関数コールは、特定のコミュニケーション・モデルを表しています。このモデルは、クライアント・プロセスとサーバー・プロセスがリクエストおよび応答の各メッセージを使用して、どのようにコミュニケートできるかという観点から表現されています。
コミュニケーションの基本的パラダイムとして、リクエスト/レスポンス型と会話型の2つがあります。リクエスト/レスポンス・サービスは、サービス・リクエストとそれに関わるデータによって呼び出されます。リクエスト/レスポンス・サービスは、リクエストを1つだけ受け取ることができ(該当サービス・ルーチンに入った時点で)、かつレスポンスも1つだけ送信することができます(該当サービス・ルーチンから戻った時点で)。一方、会話サービスは接続リクエストによって呼び出されます。このとき、オープンされた接続を参照する手段(つまり、以後の接続ルーチンを呼び出す際に使用される記述子)が必要です。接続が確立され、サービス・ルーチンが呼び出されると、以降、接続プログラムあるいは会話型サービスは、その接続が解除されるまでアプリケーションで定義されたようにデータの送受信を行えるようになります。
プロセスはリクエスト/レスポンス型と会話型のコミュニケーションのいずれも行うことができますが、両方のサービス・リクエストを受け付けることはできません。以下の項では、これら2種類の通信パラダイムの詳細を説明します。
| 注意: | Oracle Tuxedoドキュメントでは、スレッドという用語が随所で使用されています。この用語がマルチスレッド・アプリケーションの説明で使用されている場合、その意味は明白です。ただし、場合によっては、シングルスレッド・アプリケーションとマルチスレッド・アプリケーションの両方に関連するトピックの説明でこの用語が使用されていることがあります。この場合、シングルスレッド・アプリケーションを実行している読者は、スレッドという用語はプロセス全体と表していると想定できます。 |
リクエスト/レスポンスによるコミュニケーションの場合、クライアントはリクエストを送り、応答を受け取ることができる1つのプロセスと定義されています。定義によれば、クライアントはリクエストを受け取ったり、応答を送ったりすることはできません。その代わり、クライアントはいくつでもリクエストを送ることができ、またそれと同時に応答を待ったり、あるいは適宜ある一定数の応答を受け取ったりすることができます。特定のケースで、クライアントは応答のないリクエストを送信できます。tpinit()とtpterm()を使用すると、クライアントがOracle Tuxedo ATMIシステム・アプリケーションに参加したりアプリケーションから分離したりすることができます。
一方、リクエスト/レスポンス型サーバーは一度に1つのサービス・リクエストを受け取り、そのリクエストに対して1つの応答を返すことができるプロセスと定義されています。(ただしサーバーがマルチスレッドの場合は、一度に複数のリクエストを受け取って、一度に複数の応答を送信できます。)サーバーは特定のリクエストを処理しながら、一方でリクエスト/レスポンス型リクエストあるいは会話型リクエストを出し、それらのレスポンスを受け取ることにより、クライアントのように働くこともできます。サーバーはこうした能力の故に、リクエスタと呼ばれることもあります。ただし、クライアント・プロセスとサーバー・プロセスはどちらもリクエスタになることができます(実際、クライアントはリクエスタ以外の何物でもありません)。
リクエスト/レスポンス型サーバーは別のリクエスト/レスポンス型サーバーにリクエストを送る(転送する)ことができます。この場合、最初のサーバーは受け取ったリクエストを別のサーバーに渡すだけで、応答を受け取ることは期待しません。この連鎖の中の最後のサーバーがそのリクエストに対する応答を元のリクエスタに送ります。この転送ルーチンの利用によって、元のリクエスタは最終的にその応答を受け取ることができるのです。
サーバーとサービス・ルーチンの利用により、Oracle Tuxedo ATMIシステムのアプリケーションの作成に構造化手法をとることが可能になります。サーバーでは、アプリケーション作成者は、リクエストの受信や応答の送信といったコミュニケーションの詳細ではなく、サービスによって実行される作業に専念できます。コミュニケーション上の詳細の多くはOracle Tuxedo ATMIシステムのmainによって処理されるため、サービス・ルーチンを作成するときにはある一定の規則に従う必要があります。サーバーは、そのサービス・ルーチンを終了する時点で、tpreturn()を使用して応答を送信したり、tpforward()を使用してリクエストを転送したりできます。サービスはその他の作業を行ったり、この時点以後別のプロセスとコミュニケートすることは許されません。そのため、サーバーが実行するサービスは、リクエストが受け取られたときに開始され、応答が送信あるいはリクエストが転送された時点で終了します。
リクエスト・メッセージと応答メッセージとの間には、本質的に異なる点があります。リクエストにはそれが送信される以前には関連するコンテキストはありませんが、応答にはあるという点です。たとえば、あるリクエストを送る際に、呼出し側はアドレッシング情報を与えなければなりませんが、応答は常にそのリクエストを出したプロセスに返されます。つまり、応答の場合には、リクエストが出されるときに与えられたアドレッシング情報が維持されていて、応答の送信側はその宛先になんら手を加えることはできません。この両者の相違点については、tpcall()のルーチンのパラメータと説明で明らかにされています。
リクエスト・メッセージはその送信時に特定の優先度が付与されます。この優先度にしたがって、リクエストはキューから取り出されます。つまり、サーバーはキューの中で最も優先度の高いリクエストから順に取り出すのです。ただし、リクエストがいつまでもキューの中に残されてしまうのを防ぐために、優先度に関係なく、最も長くキューに入っているリクエストが一定間隔で取り出されます。デフォルト設定では、リクエストの優先度はそのリクエストが送られるサービス名に対応させて付けられます。サービス名にはシステムの構成時に優先度を与えることができます(「UBBCONFIG(5)」参照)。特に定義されていない場合には、デフォルトの優先度が使用されます。この優先度は、ルーチンtpsprio()を使用して実行時に設定することができます。呼出し側はこの方法により、メッセージ送信時に構成またはデフォルトの優先度を変更できます。
会話型のコミュニケーションの場合、クライアントは、会話接続を行うことはできるが、接続リクエストを受け付けることはできないプロセスと定義されています。
一方、会話サーバーは、接続リクエストを受け取ることができるプロセスです。接続が確立され、サービス・ルーチンが呼び出されると、以降、接続プログラムあるいは会話型サービスは、その接続が解除されるまでアプリケーションで定義されたようにデータの送受信を行えるようになります。会話は半二重方式で行われます。つまり、接続の一方の側が制御権をもってデータを送信し、他方の側は制御権を渡されるまではデータを送信できません。単一スレッド・サーバーでは、接続が確立されている間、サーバーは「予約状態」になり、ほかのプロセスがそのサーバーとの間で接続を確立することはできません。ただし、マルチスレッド・サーバーへの接続が確立しても、1つのプロセスによる排他的な使用のためにそのサーバーが予約されることはありません。かわりに複数のクライアント・スレッドからリクエストを受け取ることができます。
リクエスト/レスポンス型サーバーの場合と同様、会話型サーバーは他のリクエストを出したり、他のサーバーとの接続を行うことによりリクエスタとして機能できます。一方、リクエスト/レスポンス型サーバーと異なり、会話サーバーはリクエストを別のサーバーに転送することはできません。このため、会話サーバーによって実行される会話サービスは、リクエストを受け取った時点で開始され、tpreturn()を介して最終的な応答が送信された時点で終了します。
接続が確立すると、接続記述子により、参加リソースのアドレッシング情報に関して必要なコンテキストが示されます。メッセージは、アプリケーション側の規定に従って送受信することができます。リクエスト・メッセージと応答メッセージの間には本質的な相違はなく、またメッセージの優先度に関する規定もありません。
会話モードまたはリクエスト/レスポンス・モードのいずれにおいても、メッセージの送受信とは、2つのアプリケーション・ユニット間の通信を意味します。大部分のメッセージに対しては、応答または少なくとも確認が行われ、メッセージが受信されたことが確認されます。しかし、応答または確認を必要としないメッセージ(一部はシステムによって生成されたもので、その他はアプリケーションによって生成されたもの)があります。たとえば、システムはTPACK()フラグを設定せずにtpnotify()を使用することにより、任意通知型メッセージを送信でき、アプリケーションはTPNOREPLY()フラグを設定してtpacall()を使用することにより、メッセージを送信できます。受信プログラムのメッセージ・キューがいっぱいの場合、メッセージは破棄されます。
送信側と受信側が異なるマシン上にある場合、通信は、ネットワーク経由でメッセージを送受信するブリッジ・プロセス間で行われます。これにより、サーキット障害によって配信されなくなるという新たな可能性が生じます。これらの状況によってイベントまたはULOGメッセージが生成されても、イベントまたはULOGメッセージを特定のメッセージの非着信と関連付けることは容易ではありません。
Oracle Tuxedo ATMIシステムは、ブロード・ネットワーク間で大量のメッセージを処理するよう設計されているため、前の段落で説明したわずかなパーセントの配信の失敗を検出および修正するようにはプログラムされていません。このため、すべてのメッセージが配信されることを保証することはできません。
会話モデルでは、tpsend()およびtprecv()を使用して交換されるメッセージには、メッセージ・ヘッダーに順序番号が付けられ、メッセージは送信された順序で受信されます。サーバーまたはクライアントが順序を間違えてメッセージを受信した場合、会話が停止し、進行中のすべてのトランザクションがロールバックされ、LIBTUXのメッセージ1572(Bad Conversational Sequence Number)が記録されます。
リクエスト/レスポンス・モデルでは、メッセージはシステムにより順序付けされません。アプリケーション・ロジックで順序が暗示される場合、順序の監視と制御はアプリケーションの責任になります。ブリッジ・プロセスに対する複数のネットワーク・アドレスのサポートによって同時メッセージ伝送が可能になると、送信された順序でメッセージが受信されない可能性が高くなります。これを懸念するアプリケーションでは、各ブリッジ・プロセスに対して単一のネットワーク・アドレスを指定したり、メッセージに順序番号を追加したり、定期的な確認を必須にしたりすることが選択されます。
Oracle Tuxedo ATMIシステムのキュー・メッセージ・モデルは、リクエスト・メッセージの完了を待たず、そのメッセージが後で処理されるようにキューに登録し、またオプションとしてキューに入れられたレスポンス・メッセージを介して応答が得られるようにします。メッセージをキューに登録したりレスポンスをキューから取り出したりすためのATMI関数は、tpenqueue()とtpdequeue()です。これらの関数は、Oracle Tuxedo ATMIシステムのすべてのタイプのアプリケーション・プロセス(クライアント、サーバー、会話型)から呼び出すことができます。関数tpenqueue()およびtpdequeue()は、エンキュー・アプリケーションとデキュー・アプリケーションのいずれもサーバーまたはクライアントとして指定されていないピアツーピア通信にも使用されます。
キュー・メッセージ機能は、XA準拠のリソース・マネージャで提供されます。永続的なメッセージはトランザクション内でエンキューまたはデキューされ、一度のみ処理されます。
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インタフェースによって定義されるトランザクションは、ATMI関数によって定義されるトランザクションと実質的に同じです。アプリケーション開発者は、クライアント・ルーチンおよびサービス・ルーチンを作成する際にどちらの関数も使用できますが、単一プロセス内で2つの関数を混在させることはできません(つまり、プロセスではtpbegin()を呼び出した後にtx_commit()を呼び出すことはできません)。
TXインタフェースには、移植性の高い方法でリソース・マネージャのオープンとクローズを行う2つのコール、tx_open()およびtx_close()があります。トランザクションはtx_begin()で開始し、tx_commit()またはtx_rollback()で終了します。tx_info()は、トランザクション情報を取得するために使用されます。トランザクションのオプションを設定するために、tx_set_commit_return()、tx_set_transaction_control()およびtx_set_transaction_timeout()の3つの呼出しがあります。TXインタフェースには、ATMIのtpsuspend()とtpresume()に相当するものはありません。
TXインタフェースには、ATMIトランザクションについて定義されているセマンティクスおよび規則の他にも、ここで説明しておくべきセマンティクスがいくつかあります。まず、TXインタフェースを使用するサービス・ルーチン開発者は、tx_open()を呼び出す独自のtpsvrinit()ルーチンを使用する必要があります。省略時にOracle Tuxedo ATMIシステムが提供するtpsvrinit()は、tpopen()を呼び出します。tpsvrdone()についても同じことがあてはまります。TXインタフェースを使用している場合は、サービス・ルーチン開発者は、tx_close()を呼び出す独自のtpsvrdone()を使用しなければなりません。
次に、TXインタフェースには、ATMIにはない別のセマンティクスが2つあります。それは、連鎖および非連鎖トランザクションと、トランザクション特性です。
TXインタフェースは、トランザクション実行の連鎖モードおよび非連鎖モードをサポートしています。省略時には、クライアント・ルーチンおよびサービス・ルーチンは、非連鎖モードで実行されます。この場合、アクティブなトランザクションが完了した際、新しいトランザクションはtx_begin()が呼び出されるまで実行されません。
連鎖モードでは、新しいトランザクションは、現在のトランザクションが完了すると、暗黙に開始されます。つまり、tx_commit()またはtx_rollback()が呼び出されると、Oracle Tuxedoシステムは、現在のトランザクションの完了を調整し、制御を呼出し側に返す前に新しいトランザクションを開始します(異常終了の条件によっては、新しいトランザクションを開始できない場合もあります)。
クライアント・ルーチンとサービス・ルーチンは、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にある)1つの整数を取り、LIBTUX_CATのエラー・メッセージ・テキストへのポインタを戻します。このポインタは、userlog()の引数として使用できます。
tperrordetail()を3ステップの手順の最初のステップとして使用すると、現在のスレッドへのOracle Tuxedo ATMIシステムの最新の呼出しで発生したエラーの詳細を取得できます。tperrordetail()が返す整数値は、tpstrerrordetail()の引数として使用され、エラー・メッセージを表す文字列を指すポインタを取得します。このポインタは、userlogまたはfprintf()の引数として使用できます。
エラー・コードのうち、ATMI機能で生成できるものについては、マニュアルのATMIの項目で説明しています。F_error()とF_error32()関数は、FMLエラーの標準エラー出力にメッセージを出力します。 これらは1つのパラメータ(文字列)を取り、引数の文字列にコロンと空白を付けて出力し、改行文字の後にエラー・メッセージを出力します。表示されるエラー・メッセージは、エラー発生時に設定されたFerror()またはFerror32()内の現在のエラー番号に対して定義されているメッセージです。
Fstrerror()、およびこれに対応するFstrerror32()を使用すると、FMLエラー・メッセージのテキストをメッセージ・カタログから取得できます。これは、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バッファなど)は、使用された量のみを送信します。1つの整数フィールドを含む100KのFML32バッファは、その整数のみを含む、非常に小さいバッファとして送信されます。
これは、受信者が、送信者の割り当てたバッファ・サイズより小さく、送信されたデータのサイズより大きいバッファを受け取ることを意味します。たとえば、10KBのSTRINGバッファが割り当てられ、文字列HELLOがバッファにコピーされた場合、6バイトのみが送信され、受信者が得るバッファはおそらく1KB - 4KBになります。(他の要因により、大きくなることも小さくなることもあります。)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()関数を呼び出しても、コンテキスト状態は変化しません。
| 注意: | tpterm()がマルチコンテキスト状態(TPMULTICONTEXTS)で実行しているスレッドによって呼び出されると、呼出し側スレッドはNULLコンテキスト状態(TPNULLCONTEXT)になります。終了するコンテキストに関連するその他すべてのスレッドは、無効コンテキスト状態(TPINVALIDCONTEXT)に切り替わります。 |
表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状態で動作するスレッドは次の関数を呼び出すことができます。
catgets(3c)catopen、catclose(3c)decimal(3c)gp_mktime(3c)nl_langinfo(3c)setlocale(3c)strerror(3c)strftime(3c)tpalloc(3c)tpconvert(3c)tpcryptpw(3c)tperrordetail(3c)tpfree(3c)tpgetctxt(3c)tpgetrepos(3c)tprealloc(3c)tpsetctxt(3c)tpstrerror(3c)tpstrerrordetail(3c)tpterm(3c)tptypes(3c)TRY(3c)tuxgetenv(3c)tuxputenv(3c)tuxreadenv(3c)「userlog(3c)」Usignal(3c)Uunix_err(3c) Oracle Tuxedo ATMIシステムでは、TPINVALIDCONTEXT状態で動作するスレッドは、次の関数を呼び出すことはできません。
AEWsetunsol(3c)tpabort(3c)tpacall(3c)tpadmcall(3c)tpbegin(3c)tpbroadcast(3c)tpcall(3c)tpcancel(3c)tpchkauth(3c)tpchkunsol(3c)tpclose(3c)tpcommit(3c)tpconnect(3c)tpdequeue(3c)tpenqueue(3c)tpgetadmkey(3c)tpgetlev(3c)tpgetrply(3c)tpgprio(3c)tpinit(3c)tpnotify(3c)tpopen(3c)tppost(3c)tprecv(3c)tpresume(3c)tpscmt(3c)tpsend(3c)tpsetunsol(3c)tpsprio(3c)tpsubscribe(3c)tpsuspend(3c)tpunsubscribe(3c)tx_begin(3c)tx_close(3c)tx_commit(3c)tx_info(3c)tx_open(3c)tx_rollback(3c)tx_set_commit_return(3c)tx_set_transaction_control(3c)tx_set_transaction_timeout(3c)次の戻り値とフラグの定義は、ATMIルーチンによって使用されます。異なるトランザクション・モニターで変更または再コンパイルせずにアプリケーションを機能させるには、各システムで次のようにフラグと戻り値を定義する必要があります。
/*
* The following definitions must be included in atmi.h
*/
/* Flags to service routines */
#define TPNOBLOCK 0x00000001 /* non-blocking send/rcv */
#define TPSIGRSTRT 0x00000002 /* restart rcv on interrupt */
#define TPNOREPLY 0x00000004 /* no reply expected */
#define TPNOTRAN 0x00000008 /* not sent in transaction mode */
#define TPTRAN 0x00000010 /* sent in transaction mode */
#define TPNOTIME 0x00000020 /* no timeout */
#define TPABSOLUTE 0x00000040 /* absolute value on tmsetprio */
#define TPGETANY 0x00000080 /* get any valid reply */
#define TPNOCHANGE 0x00000100 /* force incoming buffer to match */
#define RESERVED_BIT1 0x00000200 /* reserved for future use */
#define TPCONV 0x00000400 /* conversational service */
#define TPSENDONLY 0x00000800 /* send-only mode */
#define TPRECVONLY 0x00001000 /* recv-only mode */
#define TPACK 0x00002000 /* */
/* Flags to tpreturn - also defined in xa.h */
#define TPFAIL 0x20000000 /* service FAILURE for tpreturn */
#define TPEXIT 0x08000000 /* service FAILURE with server exit */
#define TPSUCCESS 0x04000000 /* service SUCCESS for tpreturn */
/* Flags to tpscmt - Valid TP_COMMIT_CONTROL
* characteristic values
*/
#define TP_CMT_LOGGED 0x01 /* return after commit
* decision is logged */
#define TP_CMT_COMPLETE 0x02 /* return after commit has
* completed */
/* client identifier structure */
struct clientid_t {
long clientdata[4]; /* reserved for internal use */
}
typedef struct clientid_t CLIENTID;
/* context identifier structure */
typedef long TPCONTEXT_T;
/* interface to service routines */
struct tpsvcinfo {
name[128];
long flags; /* describes service attributes */
char *data; /* pointer to data */
long len; /* request data length */
int cd; /* connection descriptor
* if (flagsTPCONV) true */
long appkey; /* application authentication client
* key */
CLIENTID cltid; /* client identifier for originating
* client */
};
typedef struct tpsvcinfo TPSVCINFO;
/* tpinit(3c) interface structure */
#define MAXTIDENT 30
struct tpinfo_t {
char usrname[MAXTIDENT+2]; /* client user name */
char cltname[MAXTIDENT+2]; /* app client name */
char passwd[MAXTIDENT+2]; /* application password */
long flags; /* initialization flags */
long datalen; /* length of app specific data */
long data; /* placeholder for app data */
};
typedef struct tpinfo_t TPINIT;
/* The transactionID structure passed to tpsuspend(3c) and tpresume(3c) */
struct tp_tranid_t {
long info[6]; /* Internally defined */
};
typedef struct tp_tranid_t TPTRANID;
/* Flags for TPINIT */
#define TPU_MASK 0x00000007 /* unsolicited notification
* mask */
#define TPU_SIG 0x00000001 /* signal based
* notification */
#define TPU_DIP 0x00000002 /* dip-in based
* notification */
#define TPU_IGN 0x00000004 /* ignore unsolicited
* messages */
#define TPU_THREAD 0x00000040 /* THREAD notification */
#define TPSA_FASTPATH 0x00000008 /* System access ==
* fastpath */
#define TPSA_PROTECTED 0x00000010 /* System access ==
* protected */
#define TPMULTICONTEXTS 0x00000020 /* multiple context associa-
* tions per process */
/* /Q tpqctl_t data structure */
#define TMQNAMELEN 127
#define TMMSGIDLEN 32
#define TMCORRIDLEN 32
struct tpqctl_t { /* control parameters to queue primitives */
long flags; /* indicates which values are set */
long deq_time; /* absolute/relative time for dequeuing */
long priority; /* enqueue priority */
long diagnostic; /* indicates reason for failure */
char msgid[TMMSGIDLEN]; /* ID of message before which to queue */
char corrid[TMCORRIDLEN]; /* correlation ID used to identify message */
char replyqueue[TMQNAMELEN+1]; /* queue name for reply message */
char failurequeue[TMQNAMELEN+1]; /* queue name for failure message */
CLIENTID cltid; /* client identifier for */
/* originating client */
long urcode; /* application user-return code */
long appkey; /* application authentication client key */
long delivery_qos; /* delivery quality of service */
long reply_qos; /* reply message quality of service */
long exp_time /* expiration time */
};
typedef struct tpqctl_t TPQCTL;
/* /Q structure elements that are valid - set in flags */
#ifndef TPNOFLAGS
#define TPNOFLAGS 0x00000 /* no flags set -- no get */
#endif
#define TPQCORRID 0x00001 /* set/get correlation ID */
#define TPQFAILUREQ 0x00002 /* set/get failure queue */
#define TPQBEFOREMSGID 0x00004 /* enqueue before message ID */
#define TPQGETBYMSGIDOLD 0x00008 /* deprecated */
#define TPQMSGID 0x00010 /* get msgid of enq/deq message */
#define TPQPRIORITY 0x00020 /* set/get message priority */
#define TPQTOP 0x00040 /* enqueue at queue top */
#define TPQWAIT 0x00080 /* wait for dequeuing */
#define TPQREPLYQ 0x00100 /* set/get reply queue */
#define TPQTIME_ABS 0x00200 /* set absolute time */
#define TPQTIME_REL 0x00400 /* set relative time */
#define TPQGETBYCORRIDOLD 0x00800 /* deprecated */
#define TPQPEEK 0x01000 /* non-destructive dequeue */
#define TPQDELIVERYQOS 0x02000 /* delivery quality of service */
#define TPQREPLYQOS 0x04000 /* reply msg quality of service*/
#define TPQEXPTIME_ABS 0x08000 /* absolute expiration time */
#define TPQEXPTIME_REL 0x10000 /* relative expiration time */
#define TPQEXPTIME_NONE 0x20000 /* never expire */
#define TPQGETBYMSGID 0x40008 /* dequeue by msgid */
#define TPQGETBYCORRID 0x80800 /* dequeue by corrid */
/* Valid flags for the quality of service fields in the TPQCTL structure */
#define TPQQOSDEFAULTPERSIST 0x00001 /* queue's default persistence */
/* policy */
#define TPQQOSPERSISTENT 0x00002 /* disk message */
#define TPQQOSNONPERSISTENT 0x00004 /* memory message */
/* error return codes */
extern int tperrno;
extern long tpurcode;
/* tperrno values - error codes */
* The reference pages explain the context in which the following
* error codes can return.
*/
#define TPMINVAL 0 /* minimum error message */
#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 /* maximum error message */
/* conversations - events */
#define TPEV_DISCONIMM 0x0001
#define TPEV_SVCERR 0x0002
#define TPEV_SVCFAIL 0x0004
#define TPEV_SVCSUCC 0x0008
#define TPEV_SENDONLY 0x0020
/* /Q diagnostic codes */
#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
/* EventBroker Messages */
#define TPEVSERVICE 0x00000001
#define TPEVQUEUE 0x00000002
#define TPEVTRAN 0x00000004
#define TPEVPERSIST 0x00000008
/* Subscription Control Structure */
struct tpevctl_t {
long flags;
char name1[XATMI_SERVICE_NAME_LENGTH];
char name2[XATMI_SERVICE_NAME_LENGTH];
TPQCTL qctl;
};
typedef struct tpevctl_t TPEVCTL;
次の戻り値とフラグの定義は、TXルーチンによって使用されます。異なるトランザクション・モニターで変更または再コンパイルせずにアプリケーションを機能させるには、各システムで次のようにフラグと戻り値を定義する必要があります。
#define TX_H_VERSION 0 /* current version of this
* header file */
/*
* Transaction identifier
*/
#define XIDDATASIZE 128 /* size in bytes */
struct xid_t {
long formatID; /* format identifier */
long gtrid_length; /* value not to exceed 64 */
long bqual_length; /* value not to exceed 64 */
char data[XIDDATASIZE];
};
typedef struct xid_t XID;
/*
* A value of -1 in formatID means that the XID is null.
*/
/*
* Definitions for tx_ routines
*/
/* commit return values */
typedef long COMMIT_RETURN;
#define TX_COMMIT_COMPLETED 0
#define TX_COMMIT_DECISION_LOGGED 1
/* transaction control values */
typedef long TRANSACTION_CONTROL;
#define TX_UNCHAINED 0
#define TX_CHAINED 1
/* type of transaction timeouts */
typedef long TRANSACTION_TIMEOUT;
/* transaction state values */
typedef long TRANSACTION_STATE;
#define TX_ACTIVE 0
#define TX_TIMEOUT_ROLLBACK_ONLY 1
#define TX_ROLLBACK_ONLY 2
/* structure populated by 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_ return codes
* (transaction manager reports to application)
*/
#define TX_NOT_SUPPORTED 1 /* option not supported */
#define TX_OK 0 /* normal execution */
#define TX_OUTSIDE -1 /* application is in an RM
* local transaction */
#define TX_ROLLBACK -2 /* transaction was rolled
* back */
#define TX_MIXED -3 /* transaction was
* partially committed and
* partially rolled back */
#define TX_HAZARD -4 /* transaction may have been
* partially committed and
* partially rolled back */
#define TX_PROTOCOL_ERROR -5 /* routine invoked in an
* improper context */
#define TX_ERROR -6 /* transient error */
#define TX_FAIL -7 /* fatal error */
#define TX_EINVAL -8 /* invalid arguments were given */
#define TX_COMMITTED -9 /* transaction has
* heuristically committed */
#define TX_NO_BEGIN -100 /* transaction committed plus
* new transaction could not
* be started */
#define TX_ROLLBACK_NO_BEGIN (TX_ROLLBACK+TX_NO_BEGIN)
/* transaction rollback plus
* new transaction could not
* be started */
#define TX_MIXED_NO_BEGIN (TX_MIXED+TX_NO_BEGIN)
/* mixed plus new transaction
* could not be started */
#define TX_HAZARD_NO_BEGIN (TX_HAZARD+TX_NO_BEGIN)
/* hazard plus new transaction
* could not be started */
#define TX_COMMITTED_NO_BEGIN (TX_COMMITTED+TX_NO_BEGIN)
/* heuristically committed plus
* new transaction could not
* be started */
Oracle Tuxedo ATMIシステムは、各プロセスの状態を記録し、各種の関数呼出しやオプションごとに正当な状態遷移が行われているかどうかを検証します。この状態情報には、プロセス・タイプ(リクエスト/レスポンス型サーバー、会話サーバーまたはクライアント)、初期化状態(非初期化または初期化済)、リソースの管理状態(クローズまたはオープン)、プロセスのトランザクション状態、およびすべての非同期リクエストと接続記述子の状態などがあります。不当な状態遷移が行われようとすると、呼び出された関数は異常終了し、tperrnoがTPEPROTOに設定されます。この情報に関する正当な状態と遷移を次の表に示します。
表4は、リクエスト/レスポンス型サーバー、会話型サーバーおよびクライアントがどの関数を呼び出すことができるかを示しています。ただし、tpsvrinit()、tpsvrdone()、tpsvrthrinit()およびtpsvrthrdone()は、アプリケーションからは呼び出されないため、この表には示されていません(つまり、これらはアプリケーションが提供する関数ですが、Oracle Tuxedo ATMIシステムによって呼び出されます)。
次の各表は、特に明記されていないかぎり、クライアントとサーバー両方に適用されます。なお、関数によってはクライアントとサーバーの両方が呼び出せるわけではないため(たとえばtpinit())、以下の状態遷移のなかには、両方のプロセス・タイプには適用できないものもあります。前述の表を参照して、目的のプロセスから特定の関数を呼び出すことができるかどうかを判断してください。
次の表は、クライアント・プロセスのスレッドがトランザクション・マネージャで初期化され登録されているかどうかを示しています。この表では、tpinit()を使用していると想定していますが、これは、シングル・コンテキスト・モードでは任意です。つまり、シングル・コンテキストのクライアントは、多数のATMI関数のどれか(たとえば、tpconnect()またはtpcall())を発行することによって、暗黙的にアプリケーションに参加することができます。次のいずれかに該当する場合、クライアントはtpinit()を使用する必要があります。
tpinit(3c)」およびUBBCONFIG(5)に関する項のSECURITYキーワードの説明を参照してください。)tpinit(3c)」を参照してください。) サーバーはtpsvrinit()関数が呼び出される前にOracle Tuxedo ATMIシステムのmain()によって初期化状態になり、tpsvrdone()関数が返された後、Oracle Tuxedo ATMIシステムのmain()によって非初期化状態になります。次に示されているすべての表において、関数からエラーが戻された場合、特に明記されていないかぎり、スレッドの状態は変わりません。
次の状態の表は、前提条件として状態がI1であると想定しています(tpinit()、tpsetctxt()、またはOracle Tuxedo ATMIシステムのmain()を介してこの状態でプロセスが到着したかどうかに関わりなく)。
表6は、プロセスに関連付けられているリソース・マネージャが初期化されているかどうかに関して、クライアントまたはサーバーの状態を示しています。
表7は、プロセスがトランザクションに関連付けられているかどうかに関して、プログラムの状態を示したものです。サーバーの場合、状態T1とT2への遷移は、前提条件として状態R1を想定しています(たとえば、tpopen()はそれ以降tpclose()またはtpterm()の呼出しがないものとして呼び出されています)。
表8は、tpacall()によって戻される1つのリクエスト記述子の状態を示しています。
| 注意: | a この状態遷移は、記述子が呼出し側のトランザクションに関連付けられていない場合にのみ発生します。 |
| 注意: | b この状態遷移は、記述子が呼出し側のトランザクションに関連付けられている場合にのみ発生します。 |
| 注意: | c 記述子が呼出し側のトランザクションに関連付けられている場合、tpsuspend()はプロトコル・エラーを戻します。 |
表9は、tpconnect()によって戻される接続記述子またはTPSVCINFO構造体でサービス呼出しを行うことによって提供される接続記述子の状態を示しています。接続記述子をとらないプリミティブの場合、特に明記されていないかぎり、状態の変化はすべての接続記述子に適用されます。
| 注意: | a プロセスがトランザクション・モードでTPNOTRANの指定がない場合、接続はトランザクション・モードになります。 |
| 注意: | b TPTRANが設定されている場合、接続はトランザクション・モードになります。 |
| 注意: | c接続がトランザクション・モードにない場合、状態は変化しません。 |
| 注意: | d 接続がトランザクション・モードの場合、tpsuspend()はプロトコル・エラーを戻します。 |
The Oracle Tuxedo ATMIシステムでは、プロセスが必ずTX関数を正しい順序で呼び出すことが確認されます。不正の状態遷移が試行される(つまり、ブランクの遷移エントリの状態から呼出しを行う)と、呼び出された関数はTX_PROTOCOL_ERRORを戻します。TX関数の正当な状態および遷移を表10に示します。異常終了を戻す呼出しの場合、この表で特に明記されていないかぎり、状態遷移は行われません。Oracle Tuxedo ATMIシステムのすべてのクライアントまたはサーバーは、TX関数を使用できます。
tx_openを正常に呼び出すまで、グローバル・トランザクションを開始できません。transaction_control特性はTX_UNCHAINEDです。transaction_control特性はTX_CHAINEDです。transaction_control特性はTX_UNCHAINEDです。transaction_control特性はTX_CHAINEDです。TX_SET1は、TX_OK、TX_ROLLBACK、TX_MIXED、TX_HAZARD、TX_COMMITTEDのいずれかを表します。TX_ROLLBACKはtx_rollback()からは返されず、TX_COMMITTEDはtx_commit()からは返されません。TX_SET2は、TX_NO_BEGIN、TX_ROLLBACK_NO_BEGIN、TX_MIXED_NO_BEGIN、TX_HAZARD_NO_BEGIN、またはTX_COMMITTED_NO_BEGINのいずれかを表します。TX_ROLLBACK_NO_BEGINはtx_rollback()では返されません。TX_COMMITTED_NO_BEGINはtx_commit()では返されません。TX_FAILは、いずれかの呼出しから返された場合には、アプリケーション・プログラムの状態は、上記の表では未定義の状態になります。tx_info()が、トランザクション状態情報にTX_ROLLBACK_ONLYまたはTX_TIMEOUT_ROLLBACK_ONLYを返した場合には、そのトランザクションは、「アボートのみ(ロールバックのみ)」とマークされ、アプリケーション・プログラムがtx_commit()を呼び出したかtx_rollback()を呼び出したかに関係なく、ロールバック(アボート)されます。 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() - アプリケーション固有のブロッキング・フック関数を確立
#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() - 実行時にユーザー定義のバッファ・タイプをインストールまたはリプレース
#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() - 進行中のブロッキング呼出しが存在するかどうかの確認
#include <atmi.h>
int far pascal AEPisblocked(void)
AEPisblocked()は、OS/2プレゼンテーション・マネージャ用のATMI拡張機能です。これを使用することにより、OS/2プレゼンテーション・マネージャのタスクは、タスクの実行が前のブロッキング呼出しの完了を待っている最中にあるかどうかを判断できます。
未終了のブロッキング関数が完了を待機している場合、AEPisblocked()は1を返します。それ以外の場合には、0を返します。
このインタフェースは、OS/2プレゼンテーション・マネージャのクライアントにおいてのみサポートされます。
ATMIブロッキング呼出しは、アプリケーションから見るとブロックしているように見えますが、OS/2 PM ATMI DLLは、プロセッサの制御権を放棄して他のアプリケーションが実行できるようにしなければなりません。このことは、ブロッキング呼出しを発行したアプリケーションが、受信メッセージによって再入する可能性があることを意味します。このような場合は、AEPisblocked()関数を使用すると、タスクが再入したのが未終了のブロッキング呼出しの完了を待っている最中だったかどうかを確認できます。ATMIでは、未終了の呼出しが単一スレッド内に2つ以上存在することは禁止されていることに注意してください。
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()リクエストが、非請求メッセージを処理する方法を決定します。
buffer() - tmtype_sw_tにおける要素の意味
int /* Initialize a new data buffer */
_tminitbuf(char *ptr, long len)
int /* Reinitialize a reallocated data buffer */
_tmreinitbuf(char *ptr, long len)
int /* Uninitialize a data buffer to be freed */
_tmuninitbuf(char *ptr, long len)
long /* Process buffer before sending */
_tmpresend(char *ptr, long dlen, long mdlen)
void /* Process buffer after sending */
_tmpostsend(char *ptr, long dlen, long mdlen)
long /* Process buffer after receiving */
_tmpostrecv(char *ptr, long dlen, long mdlen)
long /* Encode/decode a buffer to/from a transmission format */
_tmencdec(int op, char *encobj, long elen, char *obj, long olen)
int /* Determine server group for routing based on data */
_tmroute(char *routing_name, char *service, char *data, long \ len, char *group)
int /* Evaluate boolean expression on buffer’s data */
_tmfilter(char *ptr, long dlen, char *expr, long exprlen)
int /* Extract buffer’s data based on format string */
_tmformat(char *ptr, long dlen, char *fmt, char *result, long \ maxresult)
long /* Process buffer before sending, possibly generating copy */
_tmpresend2(char *iptr, long ilen, long mdlen, char *optr, long olen, long *flags )
long /* Multibyte code-set encoding conversion */
_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()は、バッファの割り当てまたは再割当てを行うときに使用します。dfltsize()およびこれらのルーチンのsizeパラメータのうち大きい方を使用して、バッファの作成または再割当てが行われます。固定サイズのC構造体などの場合、バッファ・サイズはその構造体と同じにするべきです。dfltsize()をこの値に設定すると、呼出し側はバッファが渡されるルーチンに対してそのバッファの長さを指定する必要はなくなります。dfltsize()は0あるいはそれ以下にすることができます。ただし、tpalloc()やtprealloc()を呼び出して、そのsizeパラメータも0もしくはそれ以下であると、このルーチンは異常終了します。このため、dfltsize()を0以下の値に設定することはお勧めできません。
以下に指定する関数の名前は、Oracle Tuxedo ATMIシステム内で使用されるテンプレート名です。新しいルーチンをバッファ・タイプ・スイッチに追加するアプリケーションは、そのアプリケーションあるいはライブラリ・ルーチンが提供する実際の関数に対応する名前を使用しなければなりません。NULL関数ポインタがバッファ・タイプ・スイッチ・エントリに格納されている場合、Oracle Tuxedo ATMIシステムは正しい数と引数タイプをとり、デフォルトの値を返すデフォルト関数を呼び出します。
_tminitbuf()は、バッファの割当て後、tpalloc()の中から呼び出されます。これは新しいバッファを指すポインタptrとそのサイズを渡されるので、適切にバッファを初期化することができます。lenはtpalloc()に渡されるより大きな長さであり、かつそのタイプのスイッチ・エントリにdfltsize()で指定されるデフォルト値です。なお、ptrは、tpalloc()とtprealloc()の意味合いからNULLには決してなりません。正常終了すると、ptrがtpalloc()の呼出し側に返されます。
複数のサブタイプの処理に1つのスイッチ・エントリを使用する場合、_tminitbuf()の作成者はtptypes()を使用してそのサブタイプを特定することができます。
バッファを初期化しなおす必要がない場合には、NULL関数ポインタを使用します。
正常終了の場合、_tminitbuf()は1を返します。異常終了の場合には、-1を返し、これによってtpalloc()も異常終了を示すtperrnoをTPESYSTEMに返します。
_tmreinitbuf()はほとんど_tminitbuf()と同様に働きます。このルーチンは、バッファの再割当ての後、tprealloc()の中から呼び出されます。
バッファを初期化しなおす必要がない場合には、NULL関数ポインタを使用します。
正常終了の場合、_tmreinitbuf()は1を返します。異常終了の場合には、-1を返し、これによりtprealloc()も異常終了を示すtperrnoをTPESYSTEMに返します。
_tmuninitbuf()は、データ・バッファが解放される前にtpfree()によって呼び出されます。_tmuninitbuf()は、データ・バッファのアプリケーション部分を指すポインタにそのサイズと一緒に渡され、構造体またはそのバッファに関連する状態情報をクリーンアップするために使用できます。ptrは、tpfree()のセマンティクスのため決してNULLにはなりません。_tmuninitbuf()でバッファそのものを解放してはならないことに注意してください。tpfree()関数は、データ・バッファのすべてのFLD_PTRフィールドについて自動的に呼び出されます。
バッファを解放する前に何も処理が必要とされない場合には、NULL関数ポインタを使用してください。
正常終了の場合、_tmuninitbuf()は1を返します。異常終了の場合には、-1が返され、tpfree()はログ・メッセージを出力します。
_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()は、tpcall()、tpbroadcast()、tpnotify()、tpacall()、tpconnect()またはtpsend()でバッファが送信された後に呼び出されます。このルーチンにより、バッファの送信後、関数が戻る前にバッファに対して後処理を行うことができます。送信呼出しに渡されるバッファは戻り時に異なっていてはならないため、_tmpostsend()を呼び出して、_tmpresend()によって行われたバッファへの変更を修復します。この関数の最初の引数ptrは、_tmpresend()の実行結果として送信されたデータを指すポインタです。2番目の引数dlenは、_tmpresend()から戻されるデータの長さです。3番目の引数mdlenは、データが含まれているバッファの実際の長さです。このルーチンは、ptrがNULL以外の場合にのみ呼び出されます。
後処理が必要ない場合には、NULL関数ポインタを指定します。
_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()は、異なるデータ表現を使用するマシン間でネットワークを介してバッファを送受信するときにエンコード/デコードを行うために使用します。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に戻します。
メッセージは、デフォルトの設定では、要求されたサービスを提供する任意のサーバー・グループにルーティングされます。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()は、tppost()によってポストされたバッファの内容を分析するためにイベント・ブローカ・サーバーによって呼び出されます。サブスクライバ(tpsubscribe())が提供した式がバッファの内容を基に評価されます。式が真の場合、_tmfilter()は1を戻し、イベント・ブローカはサブスクライバへの通知処理を実行します。_tmfilter()が0を戻した場合は、イベント・ブローカはこのポストをサブスクリプションの一致とみなしません。
exprlenが -1の場合、exprはNULLで終わる文字列とみなされます。それ以外の場合、exprはexprlenバイトのバイナリ・データとみなされます。exprlenが0の場合は、式がないことを示します。
フィルタリングがこのバッファ・タイプに適用しない場合は、NULL関数ポインタを指定します。デフォルトのルーチンは、式がないか、exprが空のNULLで終わる文字列の場合は1を返します。それ以外の場合、デフォルトのルーチンは0を返します。
_tmformat()は、fmtという形式指定に従って、バッファのデータを表示可能な文字列に変換するためにイベント・ブローカ・サーバーによって呼び出されます。イベント・ブローカは、userlogまたはsystem通知処理の入力のためにポストされたバッファを文字列に変換します。
出力は、resultが指すメモリーの位置に文字列として格納されます。resultには、終端NULL文字を含めて最大maxresultバイト書き込まれます。resultの大きさが十分でない場合は、_tmformat()は出力を切り詰めます。出力文字列は、必ずNULLで終わります。
正常終了の場合、_tmformat()は負でない整数を返します。 1は正常終了、2は出力文字列が切り詰められたことを示します。異常終了の場合、-1を返し、resultに空の文字列を格納します。
形式設定がこのバッファ・タイプに適用しない場合は、NULL関数ポインタを指定します。デフォルトのルーチンが後を引き継ぎ、resultに空の文字列を返します。
_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を返し、バッファに対して何もしません。
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()は、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()が成功しました。処理されたデータはobufpが参照するバッファ内にあり、戻り値には変換されたデータの長さが含まれます。obufpバッファの割当てと、解放またはキャッシュは、呼出し側が行います。
正常終了時には、_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)
#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() - メッセージ・カタログをオープンまたはクローズします。
#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)
#include “decimal.h”
int
lddecimal(cp, len, np) /* load a decimal */
char*cp; /* input: location of compacted format */
int
len; /* input: length of compacted format */
dec_t*np; /* output: location of dec_t format */
void
stdecimal(np, cp, len) /* store a decimal */
dec_t*np; /* input: location of dec_t format */
char*cp; /* output: location of compacted format */
int len; /* input: length of compacted format */
int
deccmp(n1, n2) /* compare two decimal numbers */
dec_t*n1; /* input: number to be compared */
dec_t*n2; /* input: number to be compared */
int
dectoasc(np, cp, len, right) /* convert dec_t to ascii */
dec_t*np; /* input: number to be converted */
char*cp; /* output: number after conversion */
int len; /* input: length of output string */
int right; /* input: number of places to right of decimal point */
int
deccvasc(cp, len, np) /* convert ascii to dec_t */
char*cp; /* input: number to be converted */
int len; /* input: maximum length of number to be converted */
dec_t*np; /* output: number after conversion */
int
dectoint(np, ip) /* convert int to dec_t */
dec_t*np; /* input: number to be converted */
int *ip; /* output: number after conversion */
int
deccvint(in, np) /* convert dec_t to int */
int in; /* input: number to be converted */
dec_t*np; /* output: number after conversion */
int
dectolong(np, lngp) /* convert dec_t to long */
dec_t*np; /* input: number to be converted */
long*lngp; /* output: number after conversion */
int
deccvlong(lng, np) /* convert long to dec_t */
longlng; /* input: number to be converted */
dec_t*np; /* output: number after conversion */
int
dectodbl(np, dblp) /* convert dec_t to double */
dec_t*np; /* input: number to be converted */
double *dblp; /* output: number after conversion */
int
deccvdbl(dbl, np) /* convert double to dec_t */
double *dbl; /* input: number to be converted */
dec_t*np; /* output: number after conversion */
int
dectoflt(np, fltp) /* convert dec_t to float */
dec_t*np; /* input: number to be converted */
float*fltp; /* output: number after conversion */
int
deccvflt(flt, np) /* convert float to dec_t */
double *flt; /* input: number to be converted */
dec_t*np; /* output: number after conversion */
int
decadd(*n1, *n2, *n3) /* add two decimal numbers */
dec_t*n1; /* input: addend */
dec_t*n2; /* input: addend */
dec_t*n3; /* output: sum */
int
decsub(*n1, *n2, *n3) /* subtract two decimal numbers */
dec_t*n1; /* input: minuend */
dec_t*n2; /* input: subtrahend */
dec_t*n3; /* output: difference */
int
decmul(*n1, *n2, *n3) /* multiply two decimal numbers */
dec_t*n1; /* input: multiplicand */
dec_t*n2; /* input: multiplicand */
dec_t*n3; /* output: product */
int
decdiv(*n1, *n2, *n3) /* divide two decimal numbers */
dec_t*n1; /* input: dividend */
dec_t*n2; /* input: divisor */
dec_t*n3; /* output: quotient */
これらの関数を使用するとOracle Tuxedo ATMIシステムにおいてパック十進データを格納、変換、および操作することができます。Oracle Tuxedo ATMIシステムにおいて表現される十進数のデータ型の形式は、CICSでのその表現とは異なることに注意してください。
マルチスレッドのアプリケーションのスレッドは、TPINVALIDCONTEXTを含むどんなコンテキスト状態でも、10進数の変換関数を呼び出すことができます。
十進数は、Oracle Tuxedo ATMIシステム上ではdec_t構造体を使用して表現されます。この構造体の定義を次に示します。
#define DECSIZE 16
struct decimal {
short dec_exp; /* exponent base 100 */
short dec_pos; /* sign: 1=pos, 0=neg, -1=null */
short dec_ndgts; /* number of significant digits */
char dec_dgts[DECSIZE]; /* actual digits base 100 */
};
typedef struct decimal dec_t;
プログラマがdec_t構造体に直接アクセスする必要はまったくありませんが、これによって基礎となるデータ構造を理解することができます。大容量の10進数データを格納する必要がある場合、stdecimal()関数とlddecimal()関数を使用すると形式を小さくすることができます。dectoasc()、dectoint()、dectolong()、dectodbl()およびdectoflt()を使用すると、10進数を他のデータ型に変換できます。deccvasc()、deccvint()、deccvlong()、deccvdbl()およびdeccvflt()を使用すると、他のデータ型を10進数データ型に変換できます。deccmp()は2つの10進数を比較する関数です。1つ目の10進数が2つ目の10進数よりも小さい場合は-1、等しい場合は0、1つ目が大きい場合は1が返されます。decadd()、decsub()、decmul()およびdecdiv()は、十進数の算術演算を行います。
特に指定がないかぎり、これらの関数は、正常終了時には0を返し、エラー時には負の数を返します。
getURLEntityCacheDir() - DTD、スキーマおよびエンティティ・ファイルがキャッシュされている場所の絶対パスを取得するXercesクラス・メソッドを指定します。
char * getURLEntityCacheDir()
getURLEntityCacheDir()は、DTD、スキーマおよびエンティティ・ファイルがキャッシュされている場所を探すために呼び出されるメソッドです。キャッシュされたファイルの場所の絶対パスが返されます。このメソッドは、以下の2つのXercesオブジェクトと組み合せて排他的に使用されます。
GetURLEntityCaching() - DTD、スキーマ、およびエンティティ・ファイルのキャッシュ機構の取得するXercesクラス・メソッドの指定
bool getURLEntityCaching()
GetURLEntityCaching()は、DTD、スキーマおよびエンティティ・ファイルのキャッシングがオンかオフかを判別するために呼び出されるメソッドです。キャッシングがオンの場合はtrue、オフの場合はfalseが返されます。このメソッドは、以下の2つのXercesオブジェクトと組み合せて排他的に使用されます。
gp_mktime() - tm構造体をカレンダ時間に変換します。
#include <time.h>
time_t gp_mktime (struct tm *timeptr);
gp_mktime()は、timeptrが指すtm構造体で表現される時間をカレンダ時間(世界協定時(UTC) 1970年1月1日00:00:00から経過した秒数)に変換します。
struct tm {
int tm_sec; /* seconds after the minute [0, 61] */
int tm_min; /* minutes after the hour [0, 59] */
int tm_hour; /* hour since midnight [0, 23] */
int tm_mday; /* day of the month [1, 31] */
int tm_mon; /* months since January [0, 11] */
int tm_year; /* years since 1900 */
int tm_wday; /* days since Sunday [0, 6] */
int tm_yday; /* days since January 1 [0, 365] */
int tm_isdst; /* flag for daylight savings time */
}; 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()を呼び出すことができます。
#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
std)および夏時間(dst)のタイムゾーンを表す3バイト以上の文字です。stdだけが必須です。dstが無い場合、このロケールには夏時間は適用されません。大文字と小文字をどちらでも使用できます。先頭のコロン(:)、数字、カンマ(,)、マイナス(-)、またはプラス(+)以外のすべての文字が使用できます。
offset
offsetの形式はhh[:mm[:ss]]です。分(mm)と秒(ss)は省略可能です。時間(hh)は必須で、1つの数字でもかまいません。stdの次のoffsetは必須です。dstの次にoffsetが無ければ、夏時間は標準時間の1時間先であると見なされます。1桁または複数の桁を使用できます。値は常に10進数に解釈されます。時間は0から24の間でなければならず、分(および秒)は、もしあれば、0から59の間でなければなりません。範囲外の値は、予期できない動作を引き起こす場合があります。先頭に"-"がつくと、タイムゾーンはグリニッジ子午線の東にあります。それ以外の場合、タイムゾーンは西にあります(省略可能な"+"符号で示してもかまいません)。
start/time,end/time
start/timeは、いつ標準時間から夏時間への変更が発生しするかを示し、end/timeは、逆の変更がいつ起こるかを示します。それぞれのtimeフィールドは、ローカル時間で、いつ変更が行われるかを示します。 startとendの形式は次のうちのどれかです。
m.n.d
n 5、1 m 12)のm月のn週のd番目の日(0 d 6)です。ただし、週5は、4週目または5週目に発生する「m月の最後のd日」を意味します。週1は、d番目の日が発生する最初の週です。日0 (ゼロ)は、日曜日です。
startおよびendには、これらの省略可能なフィールドが与えられなかった場合、実装依存のデフォルトが使用されます。
timeは、offsetと同じ形式で、違いは先頭の符号(-または+)が許可されることです。timeが指定されなかった場合のデフォルトは、02:00:00です。
UNIXシステムのリファレンス・マニュアルのctime(3c)、getenv(3c)、timezone(4)
#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()—RPCスタブ・メモリー管理方式でのメモリーの割当て
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_ss_allocate()は、この関数の例外復帰バージョンであり、出力パラメータstatusを持ちません。例外は発生しません。
マルチスレッドのアプリケーション中のスレッドは、TPINVALIDCONTEXTを含め、どのコンテキスト状態で実行していても、rpc_sm_allocate()またはrpc_ss_allocate()の呼出しを発行できます。
正常終了すると、このルーチンは割り当てられたメモリーを指すポインタを返します。idl_void_p_tは、ISO標準C環境ではvoid *に、他の環境ではchar *に定義されていることに注意してください。
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()—クライアント・スタブから返されたメモリーの解放
#include <rpc/rpc.h>
void rpc_sm_client_free (idl_void_p_t node_to_free, unsigned32 *status)
void rpc_ss_client_free (idl_void_p_t node_to_free)
ルーチンrpc_sm_client_free()は、クライアント・スタブに割り当てられ、そのスタブから返されたメモリーを解放します。入力パラメータnode_to_freeは、クライアント・スタブから返されたメモリーを指すポインタを指定します。ISO標準のC環境では、idl_void_p_tはvoid *と定義され、他の環境ではchar *と定義されます。
このルーチンにより、他のルーチンはそれが呼び出されたメモリー管理環境を意識せずに、RPCコールにより返された動的に割り当てられたメモリーを解放することができます。
コードがサーバーの一部として実行している場合であっても、このルーチンは常にクライアント・コードから呼び出されます。
出力パラメータstatusには、このルーチンからのステータス・コードが返されます。このステータス・コードは、ルーチンが成功して完了したか、または失敗した場合はその理由を示します。次は、ステータス・コードとその意味の一覧です。
rpc_ss_client_free()は、この関数の例外復帰バージョンであり、出力パラメータstatusを持ちません。例外は発生しません。
マルチスレッドのアプリケーション中のスレッドは、TPINVALIDCONTEXTを含め、どのコンテキスト状態で実行していても、rpc_sm_client_free()またはrpc_ss_client_free()の呼出しを発行できます。
rpc_sm_free、rpc_ss_free(3c)、rpc_sm_set_client_alloc_free、rpc_ss_set_client_alloc_free(3c)、rpc_sm_swap_client_alloc_free、rpc_ss_swap_client_alloc_free(3c)
『TxRPCを使用したOracle Tuxedoアプリケーションのプログラミング』
rpc_sm_disable_allocate(), rpc_ss_disable_allocate()—資源とスタブ・メモリー管理方式で割り当てられたメモリーの解放
void rpc_sm_disable_allocate(unsigned32 *status);
void rpc_ss_disable_allocate(void);
rpc_sm_disable_allocate()ルーチンは、rpc_sm_enable_allocate()を呼び出して取得したすべての資源と、rpc_sm_allocate()の呼出し後にrpc_sm_enable_allocate()を呼び出すことで割り当てられたすべてのメモリーを解放します。
rpc_sm_enable_allocate()ルーチンとrpc_sm_disable_allocate()ルーチンは、一対として使用する必要があります。rpc_sm_enable_allocate()を呼び出さずにこのルーチンを呼び出すと、予期しない動作が発生します。
出力パラメータstatusには、このルーチンからのステータス・コードが返されます。このステータス・コードは、ルーチンが成功して完了したか、または失敗した場合はその理由を示します。次は、ステータス・コードとその意味の一覧です。
rpc_ss_disable_allocate()は、この関数の例外復帰バージョンであり、出力パラメータstatusを持ちません。例外は発生しません。
マルチスレッドのアプリケーション中のスレッドは、TPINVALIDCONTEXTを含め、どのコンテキスト状態で実行していても、rpc_sm_disable_allocate()またはrpc_ss_disable_allocate()の呼出しを発行できます。
rpc_sm_allocate、rpc_ss_allocate(3c)、rpc_sm_enable_allocate、rpc_ss_enable_allocate(3c)
『TxRPCを使用したOracle Tuxedoアプリケーションのプログラミング』
rpc_sm_enable_allocate(), rpc_ss_enable_allocate()—スタブ・メモリー管理環境を有効にする
void rpc_sm_enable_allocate(unsigned32 *status)
void rpc_ss_enable_allocate(void)
アプリケーションからrpc_sm_enable_allocate()を呼び出して、スタブ自身によってメモリー管理環境が設定されていない場合に、スタブ・メモリー環境を設定できます。すべてのrpc_sm_allocate()の呼出しの前に、スタブ・メモリー環境を設定しなければなりません。サーバーのスタブから呼び出されるサービス・コードについては、通常、スタブ・メモリー環境はスタブ自身によって設定されます。他のコンテキストから呼び出すコード(たとえば、サービス・コードをスタブからでなく直接呼び出す場合)では、rpc_sm_allocate()を呼び出す前にrpc_sm_enable_allocate()を呼び出す必要があります。
出力パラメータstatusには、このルーチンからのステータス・コードが返されます。このステータス・コードは、ルーチンが成功して完了したか、または失敗した場合はその理由を示します。次は、ステータス・コードとその意味の一覧です。
rpc_ss_enable_allocate()は、この関数の例外復帰バージョンで、出力パラメータstatusを持ちません。このルーチンでは、次の例外が発生します。
マルチスレッドのアプリケーション中のスレッドは、TPINVALIDCONTEXTを含め、どのコンテキスト状態で実行していても、rpc_sm_enable_allocate()またはrpc_ss_enable_allocate()の呼出しを発行できます。
rpc_sm_allocate、rpc_ss_allocate(3c)、rpc_sm_disable_allocate、rpc_ss_disable_allocate(3c)
『TxRPCを使用したOracle Tuxedoアプリケーションのプログラミング』
rpc_sm_free, rpc_ss_free()rpc_sm_allocate()ルーチンによって割り当てたメモリーを解放する
#include <rpc/rpc.h>
void rpc_sm_free(idl_void_p_t node_to_free, unsigned32 *status)
void rpc_ss_free(idl_void_p_t node_to_free)
アプリケーションからrpc_sm_free()を呼び出して、rpc_sm_allocate()を使用して割り当てたメモリーを解放します。入力パラメータnode_to_freeには、rpc_sm_allocate()を使用して割り当てたメモリーへのポインタを指定します。ISO標準のC環境では、idl_void_p_tはvoid *と定義され、他の環境ではchar *と定義されます。
スタブ・メモリー管理環境でスタブがメモリーを割り当てると、スタブから呼び出されるサービス・コードは、rpc_sm_free()を使用してスタブが割り当てたメモリーを解放することができます。
rpc_sm_allocate()によって割り当てたのではないメモリーへのポインタ、またはrpc_sm_allocate()によって割り当てたメモリーでも先頭以外の場所へのポインタでrpc_ss_free()を呼び出した場合は、予期できない結果が生じます。
出力パラメータstatusには、このルーチンからのステータス・コードが返されます。このステータス・コードは、ルーチンが成功して完了したか、または失敗した場合はその理由を示します。次は、ステータス・コードとその意味の一覧です。
rpc_ss_freeは、この関数の例外復帰バージョンであり、出力パラメータstatusを持ちません。例外は発生しません。
マルチスレッドのアプリケーション中のスレッドは、TPINVALIDCONTEXTを含め、どのコンテキスト状態で実行していても、rpc_sm_free()またはrpc_ss_free()の呼出しを実行できます。
rpc_sm_allocate、rpc_ss_allocate(3c)
『TxRPCを使用したOracle Tuxedoアプリケーションのプログラミング』
rpc_sm_set_client_alloc_free()、rpc_ss_set_client_alloc_free()—クライアントのスタブが使用するメモリー管理および解放のメカニズムを設定する
#include <rpc/rpc.h>
void rpc_sm_set_client_alloc_free(idl_void_p_t (*p_allocate)(unsigned long size), void (*p_free) (idl_void_p_t ptr), unsigned32 *status)
void rpc_ss_set_client_alloc_free(idl_void_p_t (*p_allocate)(unsigned long size), void (*p_free) (idl_void_p_t ptr))
rpc_sm_set_client_alloc_free()は、クライアントのスタブがメモリー管理に使用するデフォルトのルーチンよりも優先されます。入力パラメータp_allocateおよびp_freeには、メモリーの割り当ておよび解放のルーチンを指定します。サーバーのコード中でリモート・コールが発生する場合(この場合、メモリー管理ルーチンはrpc_ss_allocate(3)およびrpc_ss_free(3)でなければなりません)を除いて、デフォルトのメモリー管理ルーチンはISO Cのmalloc()およびfree()になります。
出力パラメータstatusには、このルーチンからのステータス・コードが返されます。このステータス・コードは、ルーチンが成功して完了したか、または失敗した場合はその理由を示します。次は、ステータス・コードとその意味の一覧です。
rpc_ss_set_client_alloc_freeは、この関数の例外復帰バージョンで、出力パラメータstatusを持ちません。このルーチンでは、次の例外が発生します。
マルチスレッドのアプリケーション中のスレッドは、TPINVALIDCONTEXTを含め、どのコンテキスト状態で実行していても、rpc_sm_set_client_alloc_free()またはrpc_ss_set_client_alloc_free()の呼出しを発行できます。
rpc_sm_allocate、rpc_ss_allocate(3c)、rpc_sm_free、rpc_ss_free(3c)
『TxRPCを使用したOracle Tuxedoアプリケーションのプログラミング』
rpc_sm_swap_client_alloc_free(), rpc_ss_swap_client_alloc_free()—クライアントのスタブが使用するメモリー管理および解放のメカニズムを、クライアントが提供するメカニズムに交換する
#include <rpc/rpc.h>
void rpc_sm_swap_client_alloc_free(idl_void_p_t (*p_allocate)(unsigned long size),
void (*p_free) (idl_void_p_t ptr), idl_void_p_t (**p_p_old_allocate)(unsigned long size),
void (**p_p_old_free)( idl_void_p_t ptr), unsigned32 *status)
void rpc_ss_swap_client_alloc_free(idl_void_p_t (*p_allocate)(unsigned long size),
void (*p_free) (idl_void_p_t ptr), idl_void_p_t (**p_p_old_allocate)(unsigned long size),
void (**p_p_old_free)( idl_void_p_t ptr))
rpc_sm_swap_client_alloc_free()ルーチンは、クライアントのスタブが使用する現在のメモリー管理および解放のメカニズムを、呼出し側が提供するルーチンに交換します。入力パラメータp_allocateおよびp_freeには、新しいメモリー割り当ておよび解放のルーチンを指定します。出力パラメータp_p_old_allocateおよびp_p_old_freeには、このルーチンを呼び出す前に使用されていたメモリーの割り当ておよび解放のルーチンが返されます。
呼出し可能なルーチンがRPCクライアントの場合は、その呼出し側が選択したメカニズムにかかわらず、どのメモリー割り当ておよび解放のルーチンが使用されたかを確認する必要があります。このルーチンを使用すれば、メモリー割り当ておよび解放のメカニズムを意図的に交換して、使用されたルーチンを確認することができます。
出力パラメータstatusには、このルーチンからのステータス・コードが返されます。このステータス・コードは、ルーチンが成功して完了したか、または失敗した場合はその理由を示します。次は、ステータス・コードとその意味の一覧です。
rpc_s_ok
rpc_s_no_memory
rpc_ss_swap_client_alloc_freeは、この関数の例外復帰バージョンで、出力パラメータstatusを持ちません。このルーチンでは、次の例外が発生します。
rpc_x_no_memory
マルチスレッド・アプリケーションのスレッドは、TPINVALIDCONTEXTを含め、どのコンテキスト状態で実行していても、rpc_sm_swap_client_alloc_free()またはrpc_ss_swap_client_alloc_free()の呼出しを発行できます。
rpc_sm_allocate、rpc_ss_allocate(3c)、rpc_sm_free、rpc_ss_free(3c)、rpc_sm_set_client_alloc_free、rpc_ss_set_client_alloc_free(3c)
TxRPCを使用したOracle Tuxedo ATMIアプリケーションのプログラミング。
#include <locale.h>
char *setlocale (int category, const char *locale);
setlocale()は、プログラムのロケールの該当部分を、categoryおよびlocale引数の指定に従って選択します。category引数には、次のいずれかの値を指定することができます。
LC_CTYPE
LC_NUMERIC
LC_TIME
LC_COLLATE
LC_MONETARY
LC_MESSAGES
LC_ALL
これらの名前は、ヘッダー・ファイルlocale.hに定義されています。Oracle Tuxedo ATMIシステムとの互換関数の場合、setlocale()によりすべてのカテゴリにつき1つだけlocaleを使用できます。どのカテゴリを設定しても、LC_ALL (プログラムのロケール全体を表す)と同じに扱われます。
また、localeの値""は、そのロケールを環境変数から取り出すことを表します。環境変数LANGからロケールが判別されます。
setlocale(LC_ALL, "C")が実行されます。これにより、各カテゴリが、環境"C"に指定されるロケールに初期化されます。
ある文字列を指すポインタがlocaleに対して指定されると、setlocale()はすべてのカテゴリのロケールをlocaleに設定しようとします。localeは1つのロケールからなる単純なロケールでなければなりません。setlocale()がカテゴリに対するロケールの設定に失敗すると、NULLポインタが返され、すべてのカテゴリに対するプログラムのロケールは変更されません。正常に設定されれば、設定されたロケールが返されます。
localeにNULLポインタが設定されると、setlocale()はcategoryに対応する現在のロケールを返します。プログラムのロケールは変更されません。
マルチスレッドのアプリケーション中のスレッドは、TPINVALIDCONTEXTを含め、どのコンテキスト状態で実行していても、setlocale()の呼出しを発行できます。
$TUXDIR/locale/C/LANGINFO - time and money database for the C locale
$TUXDIR/locale/locale/* - locale specific information for each
locale $TUXDIR/locale/C/*_CAT - text messages for the C locale
複合ロケールはサポートされていません。複合ロケールは、“/"で始まり、各カテゴリのロケールを “/"で区切ってリストした文字列です。
UNIXシステムのリファレンス・マニュアルのctime(3c)、ctype(3c)、getdate(3c)、localeconv(3c)、strftime(3c)、strtod(3c)、printf(3S)、environ(5)
setURLEntityCacheDir() - DTD、スキーマおよびエンティティ・ファイルがキャッシュされるディレクトリを設定する、Xercesクラス・メソッドを指定します。
void setURLEntityCacheDir (const char* cachedir)
setURLEntityCacheDir()は、キャッシュが有効になっており、ユーザーがDTD、スキーマ、およびエンティティ・ファイルを特定のディレクトリにキャッシュする場合に呼び出します。cachedirには、ファイルの場所の絶対パスを指定します。
このメソッドを呼び出さず、setURLEntityCaching()メソッドを呼び出すか、または環境変数を設定しないことによってキャッシュを有効にした場合、ファイルはカレント・ディレクトリにキャッシュされます。このメソッドは、以下の2つのXercesオブジェクトと組み合せて排他的に使用されます。
setURLEntityCaching() - XMLパーサー用にDTD、スキーマ、またはエンティティ・ファイルのキャッシュの設定または設定解除を行うXercesクラス・メソッドの指定
void setURLEntityCaching (bool UseCache)
setURLEntityCaching()は、デフォルトでDTD、スキーマ、およびエンティティ・ファイルをキャッシュするメソッドです。このメソッドを使用して、ファイルのキャッシングをオンまたはオフにすることができます。UseCacheは、キャッシングをオフにする場合はfalseに設定され、キャッシングをオンにする場合はtrueに設定されます。このメソッドは、以下の2つのXercesオブジェクトと組み合せて排他的に使用されます。
#include <string.h>
char *strerror (int errnum);
strerrorはerrnumに指定されたエラー番号をエラー・メッセージ文字列にマッピングし、その文字列を指すポインタを返します。strerrorは、perrorと同じエラー・メッセージ・セットを使用します。返される文字列は上書きされないようにしてください。
マルチスレッドのアプリケーション中のスレッドは、TPINVALIDCONTEXTを含め、どのコンテキスト状態で実行していても、strerror()の呼出しを発行できます。
UNIXシステムのリファレンス・マニュアルのperror(3)
#include <time.h>
size_t *strftime (char *s, size_t maxsize, const char *format, const struct tm *timeptr);
strftime()は、formatが指す文字列の制御に従って、sが指す配列に文字を入れます。format文字列は、ゼロ個以上のディレクティブと通常文字で構成します。すべての通常文字(文字列の最後を表すNULL文字列を含む)は、そのまま配列に複写されます。strftime()の場合、maxsize個以上の文字は配列には入りません。
formatが(char *)0である場合、ロケールのデフォルトの形式が使用されます。デフォルトの形式は"%c"と同じです。
各ディレクティブは、次のリストの記述に従って該当する文字と置き換えられます。該当文字はプログラムのロケールのLC_TIMEカテゴリおよびtimeptrが指す構造体に格納されている値によって判別されます。
%Uと%Wの相違点は、日にちを週の初日から数えるかどうかという点です。週番号01は、%Uの場合、日曜日から始まる1月の第1週、%Wの場合は月曜日から始まる1月の第1週を表します。また、週番号00には、%Uおよび%Wでそれぞれ最初の日曜日または月曜日の前の日にちを表します。
終端NULL文字を含む結果として得られた文字の合計数がmaxsizeを超えない場合、strftime()はsが指す配列に置かれた文字数(終端NULL文字を含まない)を返します。それ以外の場合は、ゼロが返され、配列の内容は不確定になります。
マルチスレッドのアプリケーション中のスレッドは、TPINVALIDCONTEXTを含め、どのコンテキスト状態で実行していても、strftime()の呼出しを発行できます。
デフォルトの設定では、strftime()の出力はU.S. Englishで行われます。strftime()の出力は、setlocale()にカテゴリLC_TIMEのlocaleを設定することによって特定の言語に変更することができます。
タイム・ゾーンは環境変数TZから取得されます。TZの詳細は、「ctime(3c)」を参照してください。
strftime()の使用例を示します。この例は、tmptrが指す構造体に、ニュージャージー州における1986年8月28日木曜日の12時44分36秒に対応する値が入っている場合に、strの文字列がどのようになるかを示しています。
strftime (str, strsize, "%A %b %d %j", tmptr)
この結果、strには"Thursday Aug 28 240"の文字列が入ります。
$TUXDIR/locale/locale/LANGINFO—コンパイルされたロケール固有の日付/時刻情報を収めているファイル
tpabort()—現在のトランザクションを中断するルーチン
#include <atmi.h>
int tpabort(long flags)
tpabort()は、トランザクションの中断を指定します。この関数が終了すると、そのトランザクションでなされたリソースへの変更内容はすべて取り消されます。tpcommit()と同様、この関数は、トランザクションのイニシエータからしか呼び出せません。参加リソース(つまり、サービス・ルーチン)は、トランザクションを中断させたい場合には、TPFAILを付けてtpreturn()を呼び出します。
未終了の応答に対する呼出し記述子が存在するときにtpabort()を呼び出すと、この関数の終了時に、トランザクションは中断し、呼出し側のトランザクションに関連するこれらの記述子は以後無効になります。呼出し側のトランザクションに関連がない呼出し記述子の状態は有効のままです。
トランザクション・モードの会話型サーバーに対してオープン接続がある場合、tpabort()はTPEV_DISCONIMMイベントをサーバーに送ります(そのサーバーが接続の制御権を有するかどうかに関係なく)。tpbegin()の前に、あるいはTPNOTRANフラグを付けて(つまり、トランザクション・モードでない状態で)オープンされた接続は、影響を受けません。
現時点では、tpabort()の唯一の引数flagsは将来使用する予定であり、現在は必ずゼロを指定してください。
マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドはtpabort()の呼出しを発行できません。
異常終了すると、tpabort()は -1を返し、tperrnoを設定してエラー条件を示します。
異常終了すると、tpabort()はtperrnoを次のいずれかの値に設定します。
TPEINVAL]
TPEHEURISTIC]
TPEHAZARD]
TPEPROTO]
TPESYSTEM]
TPEOS]
Oracle Tuxedo ATMIシステムのトランザクションを記述するためにtpbegin()、tpcommit()、およびtpabort()を使用する場合、XAインタフェースに準拠した(呼出し側に妥当にリンクされている)リソース・マネージャが行う作業のみがトランザクションのプロパティを備えていることを記憶しておくことが重要です。トランザクションにおいて実行される他のすべての操作は、tpcommit()あるいはtpabort()のいずれにも影響されません。
tpbegin(3c)、tpcommit(3c)、tpgetlev(3c)
tpacall()—サービス・リクエストの送信を行うルーチン
#include <atmi.h>
int tpacall(char *svc, char *data, long len, long flags)
tpacall()は、svcで指定されているサービスにリクエスト・メッセージを送ります。このリクエストは、以前のtpspri()で変更されていないかぎり、svcに対して定義されている優先度で送信されます。dataは、NULLでなければ、tpalloc()が以前に割り当てたバッファを指していなければなりません。lenには送信するバッファに入るデータの量を指定します。ただし、dataが長さの指定を必要としないバッファを指している場合(FMLフィールド化バッファなど)、lenは無視されます(0でかまいません)。dataがNULLであると、lenは無視され、リクエストはデータ部なしで送信されます。dataのタイプとサブタイプは、svcが認識するタイプおよびサブタイプと一致しなければなりません。トランザクション・モードにあるときに送信されるリクエストごとに、最終的には対応する応答が受信されなければならないことに注意してください。
TPNOTRAN
svcが呼び出されたときに、このプロセスは呼出し側のトランザクションの一部として実行されません。svcがトランザクションをサポートしないサーバーに属している場合、呼出し側がトランザクション・モードのときに、このフラグを設定しなければなりません。svcが依然としてトランザクション・モードで起動される場合がありますが、それは同じトランザクションでないことに注意してください。svcは、構成属性で、自動的にトランザクション・モードで呼び出されるようにすることができます。このフラグを設定するトランザクション・モードの呼出し側は、トランザクション・タイムアウトの影響を受けます。サービスが異常終了した場合でも、起動時にこのフラグが設定されていれば、呼出し側のトランザクションに影響は及びません。
TPNOREPLY
tpacall()に通知します。 TPNOREPLYが設定されると、正常終了時に関数は0を返します(0は無効な記述子)。呼出しプロセスがトランザクション・モードにあるとき、TPNOTRANが設定されないかぎりこの設定は使用できません。
TPNOBLOCK
TPNOBLOCKが指定されていないときにブロッキング条件が存在すると、呼出し側は、その条件が解消されるか、またはタイムアウト(トランザクションまたはブロッキング)が発生するまではブロックされます。
TPNOTIME
TPSIGRSTRT
マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドは、tpacall()の呼出しを発行できません。
正常終了の場合、tpacall()は、送信したリクエストの応答を受信するために使用できる記述子を返します。
異常終了すると、tpacall()は -1を返し、tperrnoを設定してエラー条件を示します。
異常終了時には、tpacall()はtperrnoを次のいずれかの値に設定します(特に記述した場合を除いては、エラーが呼出し側のトランザクションに影響を及ぼすことはありません)。
TPEINVAL]
TPENOENT]
TPEITYPE]
TPELIMIT]
TPETRAN]
TPETIME]
TPNOBLOCKまたはTPNOTIMEが指定されている場合は発生しません。 トランザクション・タイムアウトが発生した場合、トランザクションがアボートされない限り、新しいリクエストの送信や未処理の応答の受信はできず、TPETIMEが発生します。その例外とは、ブロックされず、応答を期待せず、かつ呼出し側のトランザクションのかわりに送信されない(つまり、TPNOTRAN、TPNOBLOCKおよびTPNOREPLYを設定してtpacall()を呼び出した場合の)リクエストです。 サービスがトランザクションの内部で失敗した場合、そのトランザクションはTX_ROLLBACK_ONLY状態に置かれます。ほとんどの場合、この状態はタイムアウトと同じものとして扱われます。このトランザクションの以降のATMI呼出しは、TPETIMEで失敗します(前の段落で説明した例外を除きます)。
TPEBLOCK]
TPGOTSIG]
TPEPROTO]
TPESYSTEM]
TPEOS]
tpalloc(3c)、tpcall(3c)、tpcancel(3c)、tpgetrply(3c)、tpgprio(3c)、tpsprio(3c)
tpadmcall()—ブートされていないアプリケーションの管理
#include <atmi.h>
#include <fml32.h>
#include <tpadm.h>
int tpadmcall(FBFR32 *inbuf, FBFR32 **outbuf, long flags)
tpadmcall()は、ブートされていないアプリケーションの属性の検索と更新に使用します。また、アクティブなアプリケーションで、限られた属性の集合を直接検索することもできます。この場合、外部プロセスとの通信は必要ありません。この関数は、システム提供のインタフェース・ルーチンを使用してシステムの構成と管理が完全に行えるような十分な機能を提供します。
inbufには、tpalloc()によって以前に割り当てた、希望する管理操作とそのパラメータが入っているFML32バッファへのポインタを指定します。
outbufには、結果を入れるFML32バッファへのポインタのアドレスを指定します。outbufは、元々tpalloc()によって割り当てられたFML32バッファを指していなければなりません。送信と受信に同じバッファを使用する場合は、outbufにはinbufのアドレスを指定してください。
現在tpadmcall()の最後の引数のflagsは将来の使用のために予約されているため、0に設定しなければなりません。
MIB(5)を調べて、管理リクエストの構築に関する一般情報を得る必要があります。TM_MIB(5)およびAPPQ_MIB(5)を調べて、tpadmcall()を介してアクセスできるクラスに関する情報を得る必要があります。
tpadmcall()は次の4つのモードで呼び出すことができます。
APPQ_MIB()で定義されているクラスのオブジェクトに対してGETおよびSETを実行することだけです。
TM_MIB()およびAPPQ_MIB()のあらゆるクラスのあらゆる属性に対して、これらに対して適切なパーミッションを持つ場合に、GETおよびSETを実行できます。クラスによっては、起動されていないアプリケーションからアクセスできない属性だけを持ち、これらのクラスへのアクセスが失敗する場合があることに注意してください。
TM_MIB()のあらゆるクラスのあらゆる属性に対して、これらに対して適切なパーミッションを持つ場合に、GETを実行できます。同様に呼出し側は、クラス固有の制限にもよりますが、APPQ_MIB()のあらゆるクラスのあらゆる属性に対してGETおよびSETを実行できます。ACTIVEであるときにのみアクセスできる属性は返されません。
tpinit()の実行時に割り当てられた認証キーに従ってパーミッションが決められます。呼出し側は、TM_MIB()のあらゆるクラスのあらゆる属性に対して、これらに対して適切なパーミッションを持つ場合に、GETを実行できます。さらに呼出し側は、クラス固有の制限にもよりますが、APPQ_MIB()のあらゆるクラスのあらゆる属性に対してGETおよびSETを実行できます。
これらのインタフェース・ルーチンを使用したバイナリのOracle Tuxedo ATMIシステム・アプリケーション構成ファイルに対するアクセスおよび更新は、ディレクトリ名やファイル名に関するUNIXシステムのパーミッションによって制御されます。
マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドはtpadmcall()の呼出しを発行できません。
このルーチンを呼び出す前に、次の環境変数を設定する必要があります。
TUXCONFIG
tpadmcall()を使用する場合、GETリクエストにおけるTA_OCCURS属性の使用はサポートされていません。tpadmcall()を使用する場合、GETNEXTリクエストはサポートされていません。
tpadmcall()は成功すると0を、失敗すると -1を返します。
異常終了時には、tpadmcall()はtperrnoを次のいずれかの値に設定します。
| 注意: | TPEINVALの場合を除き、呼出し側の出力バッファoutbufは、TA_ERROR属性とTA_STATUS属性、および場合によってはTA_BADFLD属性を含むように変更され、エラー条件の詳細が取得されます。これによって戻されるエラー・コードの詳細は、「MIB(5)」、「TM_MIB(5)」および「APPQ_MIB(5)」を参照してください。 |
TPEINVAL]
TPEMIB]
TPEPROTO]
TPERELEASE]
TPEOS]
TPESYSTEM]
このインタフェースは、ローカルな構成ファイルおよび掲示板に対するアクセスおよび更新しかサポートしていません。したがって、相互運用性の問題はありません。
このインタフェースは、Oracle Tuxedo ATMIリリース5.0またはそれ以降が稼働するUNIX Systemのサイトでしか利用できません。
${TUXDIR}/lib/libtmib.a、${TUXDIR}/lib/libqm.a、${TUXDIR}/lib/libtmib.so.<rel>、${TUXDIR}/lib/libqm.so.<rel>、${TUXDIR}/lib/libtmib.lib、${TUXDIR}/lib/libqm.lib
buildclientを使用する場合は、ライブラリを手動でリンクする必要があります。この場合、ユーザーは-L${TUXDIR}/lib -ltmid -lqmを使用する必要があります。
ACL_MIB(5)、APPQ_MIB(5)、EVENT_MIB(5)、MIB(5)、TM_MIB(5)、WS_MIB(5)
『Oracle Tuxedoアプリケーションの設定』
『Oracle Tuxedoアプリケーション実行時の管理』
#include <atmi.h>
int tpadvertise(char *svcname, void (*func)(TPSVCINFO *))
tpadvertise()使用するとサーバーは提供するサービスを公開することができます。デフォルトの設定では、サーバーのサービスは、サーバーのブート時に公開され、サーバーの停止時にその公開が解除されます。
複数サーバー単一キュー(MSSQ)セットに属するすべてのサーバーは、同じサービス・セットを提供しなければなりません。これらのルーチンは、MSSQセットを共有する全サーバーを公開することによってこの規則を適用します。
tpadvertise()は、サーバー(あるいは、呼出し側のMSSQセットを共有するサーバーのセット)のsvcnameを宣言します。svcnameにNULLあるいはNULL文字列(“")を指定することはできません。また、長さは127文字までとしてください(UBBCONFIG(5)のSERVICESセクションを参照)。funcはOracle Tuxedo ATMIシステムのサービス関数のアドレスです。この関数は、svcnameに対するリクエストをサーバーが受け取ったときに起動されます。funcにNULLを指定することはできません。明示的に指定された関数名(servopts(5)を参照)は、128文字までの長さを指定できます。127文字を超える名前は、受け取られてから127文字に切り詰められます。ユーザーは、切り詰められた名前が他のサービス名と同じにならないように注意する必要があります。
svcnameがすでにサーバーに対して公開されていて、funcがその現在の関数と一致する(すでに公開されている名前に一致する短縮された名前も含まれます)場合、tpadvertise()は正常に終了します。ただし、svcnameがすでにサーバーに対して公開されていても、funcが現在の関数と一致しない場合には(短縮された名前がすでに公開されている名前と同じ場合にも)、エラーが返されます。
'.'で始まるサービス名は、管理用サービスのために予約されています。アプリケーションがこれらのサービスの1つを公開しようとするとエラーが返されます。
異常終了すると、tpadvertise()は -1を返し、tperrnoを設定してエラー条件を示します。
失敗すると、tpadvertise()はtperrnoを次のいずれかの値に設定します。
TPEINVAL]
TPELIMIT]
TPEMATCH]
svcnameは、すでにこのサーバーについて公開されていますが、それは、func以外の関数で行われました。この関数は異常終了しても、svcnameはその現在の関数で公開されたまま変わりません(すなわち、funcは現在の関数と振り変わりません)。
TPEPROTO]
TPESYSTEM]
TPEOS]
tpservice(3c)、tpunadvertise(3c)
#include <atmi.h>
char * tpalloc(char *type, char *subtype, long size)
tpalloc()は、typeタイプのバッファを指すポインタを返します。バッファのタイプによっては、subtypeとsizeは両方とも省略することができます。Oracle Tuxedo ATMIシステムには、様々なタイプのバッファが提供されており、しかもアプリケーションは自由に独自のバッファ・タイプを追加することができます。詳細は、tuxtypes(5)を参照してください。
ある特定のバッファ・タイプのtmtype_swでsubtypeがNULLでない場合、tpalloc()を呼び出す際にsubtypeを指定しなければなりません。割り当てるバッファは少なくともsizeおよびdfltsizeと同じ大きさにします。ここで、dfltsizeは特定のバッファ・タイプのtmtype_swに指定するデフォルトのバッファ・サイズです。バッファ・タイプがSTRINGの場合、最小は512バイトです。バッファ・タイプがFMLあるいはVIEWの場合、最小は、1024バイトです。
なお、typeの最初の8バイトとsubtypeの最初の16バイトだけが有効です。
あるバッファ・タイプは使用する前に初期化が必要です。tpalloc()は、バッファが割り当てられて返される前に(Oracle Tuxedo ATMIシステム固有の方法で)バッファを初期化します。このため、呼出し側から返されるバッファはすぐに使用できます。ただし、初期化ルーチンがバッファをクリアしないかぎり、そのバッファはtpalloc()によってゼロに初期化されません。
マルチスレッドのアプリケーション中のスレッドは、TPINVALIDCONTEXTを含め、どのコンテキスト状態で実行していても、tpalloc()の呼出しを発行できます。
正常終了の場合、tpalloc()はlongワードの適切なタイプのバッファを指すポインタを返します。それ以外の場合はNULLを返し、tperrnoを設定して条件を示します。
失敗すると、tpalloc()はtperrnoを次のいずれかの値に設定します。
TPEINVAL]
TPENOENT]
TPEPROTO]
TPESYSTEM]
TPEOS]
バッファの初期化に失敗すると、割り当てられたバッファが解放され、tpalloc()がNULLを戻して失敗します。
この関数を、Cライブラリのmalloc()、realloc()、またはfree()と組み合せて使用するのは避けてください(tpalloc()で割り当てたバッファを、free()を使用して解放しないでください)。
Oracle Tuxedo ATMIシステムの拡張に準拠した実装は、すべて2つのバッファ・タイプをサポートしています。詳細は、「C言語アプリケーション・トランザクション・モニター・インタフェースについて」を参照してください。
tpfree(3c)、tprealloc(3c)、tptypes(3c)
tpappthrinit() - アプリケーション生成のサーバー・スレッドで新しいTuxedoコンテキストを生成および初期化するルーチン
#include <atmi.h>
int tpappthrinit(TPINIT *tpthrinfo); tpappthrinit()は、アプリケーション生成のサーバー・スレッドで新しいTuxedoコンテキストを生成します。tpappthrinit()によって生成されたコンテキストは、アプリケーション・サーバーが存在するドメインに接続します。また、現在のアプリケーション・スレッドのコンテキストを新たに作成されたコンテキストに設定します。
Tuxedoサーバー・プロセス内のアプリケーション生成スレッドがTuxedo ATMIシステムの通信ルーチンまたはトランザクション・ルーチンを使用するには、まずtpappthrinit()を呼び出すか、自身をtpsetctxt()を使用して有効なコンテキストに関連付ける必要があります。
tpappthrinit()が正常終了した後、アプリケーション生成のサーバー・スレッドはサービス・リクエストを開始し、トランザクションを定義できます。
| 注意: | アプリケーション・スレッドは、tpreturn()およびtpforward()を呼び出すことはできません。アプリケーション・スレッドは、非請求メッセージを送信することはできますが、受信することはできません。 |
tpappthrinit()が正常に終了した後、アプリケーション生成のサーバー・スレッドはtpgetctxt()を呼び出して現在のコンテキストを取得し、そのコンテキストを、別のアプリケーション生成のサーバー・スレッドで呼び出したtpsetctxt()にパラメータとして渡すことで、自身を別のコンテキストに関連付けることができます。
| 注意: | サービス・ルーチンでtpappthrinit()によって生成されたコンテキストを設定することはできません。 |
tpappthrinit()の引数tpthrinfoは、TPINITバッファ・タイプとNULLサブタイプのポインタです。TPINITは、atmi.hヘッダー・ファイルで定義されるバッファ・タイプです。このバッファは、tpappthrinit()を呼び出す前にtpalloc()で割り当てる必要があります。このバッファの解放は、tpappthrinit()の呼出しの後、tpfree()を使用して行います。
TPINIT構造体の説明については、tpinit()ルーチンを参照してください。tpappthrinit()に認証情報を渡す場合、tpthrinfoのメンバーであるusrname、data、およびdatalenが使用されます。tpthrinfoのメンバーであるcltname、grpname、およびpasswdは現在使用されないため、長さが0の文字列に設定する必要があります。TPINITのメンバーであるflagsも、tpappthrinit()では使用されません。
tpappthrinit()は、アプリケーション生成のサーバー・スレッドでのみ呼び出すことができます。サーバーをビルドする場合、buildserverで-tオプションを指定する必要があります。
| 注意: | tpappthrinit()はサービス・ルーチンでは使用できません。 |
Tuxedoコンテキストが正常に生成および初期化されると、tpappthrinit()が0を返します。
エラーが発生すると、この関数は、呼出し側スレッドがTPNULLCONTEXTの状態のままで -1を返し、tperrnoを設定してエラー条件を示します。
異常終了時には、tpappthrinit()はtperrnoを次のいずれかの値に設定します。
[TPEINVAL]
[TPEPROTO]
tpappthrinit()が不正に呼び出されました。たとえば、クライアント・プログラムまたはサーバー・ルーチンで呼び出されているか、buildserver -tオプションでサーバーがビルドされていません。
[TPENOENT]
[TPEPERM]
[TPESYSTEM]
[TPEOS]
tpappthrterm(3c)、 tpinit(3c)、 tpterm(3c)、 tpgetctxt(3c)、 tpsetctxt(3c)
「マルチスレッドおよびマルチコンテキスト・アプリケーションのプログラミング」
tpappthrterm() - アプリケーション生成のサーバー・スレッドのtpappthrinit()によって生成されたTuxedoコンテキストを終了するルーチン
#include<atmi.h>
int tpappthrterm(void); tpappthrterm()は、現在のTuxedoコンテキストを削除し、現在のアプリケーション生成のサーバー・スレッドのコンテキストにTPNULLCONTEXTを設定します。アプリケーション・スレッドがトランザクション・モードであると、トランザクションはロールバックします。tpappthrterm()が正常に終了すると、呼出し側はほとんどのTuxedo ATMIクライアントの操作を行えなくなります。未終了の会話はただちに切断されます。
tpappthrterm()はtpappthrinit(),によって生成されたコンテキストを終了する場合にのみ使用できます。この関数はアプリケーション生成のサーバー・スレッドでのみ呼び出すことができます。サーバーをビルドする場合、 buildserverで -tオプションを指定する必要があります。
| 注意: | tpappthrterm()は、サービス・ルーチンや、サーバー・ディスパッチ・コンテキストに現在関連付けられているアプリケーション生成のサーバー・スレッドで使用することはできません。 |
アプリケーション生成のサーバー・スレッドのコンテキストでほかのアプリケーション生成のサーバー・スレッドがまだ処理を行っている場合は、そのコンテキストでtpappthrterm()を呼び出さないようにする必要があります。
Tuxedoコンテキストが正常に終了すると、tpappthrterm()が0を返し、現在のコンテキストにTPNULLCONTEXTが設定されます。
異常終了すると、tpappthrterm()は-1を返し、tperrnoを設定してエラー条件を示します。
異常終了時には、tpappthrterm()はtperrnoを次のいずれかの値に設定します。
[TPEPROTO]
tpappthrterm()が不正に呼び出されました。たとえば、クライアント・プログラムまたはサービス・ルーチンで呼び出されているか、サーバー・ディスパッチ・コンテキストに現在関連付けられているアプリケーション生成のサーバー・スレッドで呼び出されています。
[TPESYSTEM]
[TPEOS]
tpappthrinit(3c)、tpinit(3c)、tpgetctxt(3c)、tpsetctxt(3c)、tpterm(3c)
「マルチスレッドおよびマルチコンテキスト・アプリケーションのプログラミング」
tpbegin()—トランザクションを開始するためのルーチン
#include <atmi.h>
int tpbegin(unsigned long timeout, long flags) Oracle Tuxedo ATMIシステムにおけるトランザクションは、完全に成功する、あるいは何も影響を残さない1つの論理的な作業単位を定義するために使用されます。トランザクションにより、多くのプロセスで(そして、おそらく様々なサイトで)行われる作業を1つの分割できない単位として扱うことができます。トランザクションの開始プロセスはtpbegin()とともに、tpcommit()またはtpabort()を使用して、トランザクション内での処理を記述します。いったんtpbegin()が呼び出されると、他のプロセスとの通信は、後のプロセス(つまりサーバー)をトランザクション・モードにすることができます(つまり、サーバーの作業はトランザクションの一部となります)。トランザクションに参加したプログラムを参加リソースと呼びます。トランザクションには、必ず1つの実行元があり、いくつかの参加リソースを持つことができます。tpcommit()またはtpabort()を呼び出せるのは、トランザクションの実行元だけです。参加リソースは、tpreturn()を呼び出したときに使用する戻り値(rvals)によって、トランザクションの結果に影響を与えることができます。トランザクション・モードに入ると、サーバーに出されたサービス・リクエストはすべて、トランザクションの一部として処理されます(リクエスタから明示的に別の指定がない場合)。
また、会話型サーバーに対して確立されたオープン接続があるときにプログラムがトランザクションを起動しても、これらの接続はトランザクション・モードには変わりません。これは、tpconnect()の呼出し時にTPNOTRANフラグを指定したことと同じです。
tpbegin()の最初の引数timeoutは、トランザクションのタイムアウトまでの時間を最低timeout秒にすることを指定します。トランザクションはタイムアウト時間を経過した後は、中断のみとしてマークされます。timeoutの値が0であると、トランザクションにはシステムが許すかぎりの最大時間(秒単位)のタイムアウト値が与えられます(つまり、このときのタイムアウト値は、システムが定義している符号なしlong型の最大値になります)。
現時点では、tpbegin()の2番目の引数のflagsは将来の使用のために予約されているため、0に設定する必要があります。
マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドは、tpbegin()の呼出しを発行できません。
異常終了すると、tpbegin()は -1を返し、tperrnoを設定してエラー条件を示します。
異常終了時には、tpbegin()はtperrnoを次のいずれかの値に設定します。
TPEINVAL]
TPETRAN]
TPEPROTO]
TPESYSTEM]
TPEOS]
Oracle Tuxedo ATMIシステムのトランザクションを記述するためにtpbegin()、tpcommit()、およびtpabort()を使用する場合、XAインタフェースに準拠した(呼出し側に妥当にリンクされている)リソース・マネージャが行う作業のみがトランザクションのプロパティを備えていることを記憶しておくことが重要です。トランザクションにおいて実行される他のすべての操作は、tpcommit()あるいはtpabort()のいずれにも影響されません。詳しくは、buildserver()を参照してください。リソース・マネージャによって実行される操作が、Oracle Tuxedo ATMIシステムのトランザクションの一部となるように、XAインタフェースを満たすリソース・マネージャをサーバーにリンクします。
tpabort(3c)、tpcommit(3c)、tpgetlev(3c)、tpscmt(3c)
tpbroadcast() - 名前によって通知をブロードキャストするルーチン
#include <atmi.h>
int tpbroadcast(char *lmid, char *usrname, char *cltname,
char *data, long len, long flags)
tpbroadcast()は、クライアント・プロセスやサーバー・プロセスがシステム内に登録されているクライアントに非請求メッセージを送ることができるようにします。ターゲットのクライアント・セットは、tpbroadcast()に渡されるワイルドカード以外の識別子すべてと一致するクライアントで構成されます。識別子の指定にワイルドカードを使用できます。
lmid、usrnameおよびcltnameは、ターゲットのクライアント・セットの選択に使用する論理識別子です。引数のNULL値は、その引数のワイルドカードとなります。ワイルドカード引数は、そのフィールドの全クライアント識別子と一致します。長さ0の文字列の引数は、長さ0のクライアント識別子とのみ一致します。各識別子は、システムが有効とみなすよう定義されたサイズの制約事項を満たさなければなりません。つまり、各識別子の長さは0からMAXTIDENT文字まででなければなりません。
このリクエストのデータ部はdataによって示され、以前にtpalloc()によって割り当てられたバッファです。lenに送信するデータの大きさを指定します。ただし、dataが長さの指定を必要としないタイプのバッファを指す場合(たとえば、FMLフィールド化バッファ)、lenは0でかまいません。また、dataはNULLであってもかまいません。この場合、lenは無視されます。このバッファは、他の送受信されるメッセージと同様、型付きバッファ・スイッチ・ルーチンで処理されます。たとえば、エンコード/デコードは自動的に行われます。
TPNOBLOCK
TPNOTIME
TPSIGRSTRT
tpbroadcast()が正常終了した場合には、メッセージはシステムに渡され、選択されたクライアントに転送されます。tpbroadcast()は、選択された各クライアントにメッセージが送られるのを待機しません。
異常終了すると、tpbroadcast()は -1を返し、tperrnoを設定してエラー条件を示します。
異常終了には、tpbroadcast()はアプリケーション・クライアントにブロードキャスト・メッセージを送信せず、tperrnoを次のいずれかの値に設定します。
TPEINVAL]
LMIDを使用すると、tpbroadcast()は正常に働かず、TPEINVALが返されます。ただし、存在しないユーザーやクライアントの名前の場合は、どこにもブロードキャストされないだけでこのルーチンは正常に終了します。
TPETIME]
TPEBLOCK]
TPGOTSIG]
TPEPROTO]
TPESYSTEM]
TPEOS]
tpnotify(3c)で説明したインタフェースはすべて、ネイティブ・サイトのUNIXシステム・ベースのプロセッサ上で利用できます。さらに、ルーチンtpbroadcast()とtpchkunsol()は、関数tpsetunsol()と共に、UNIXシステムおよびMS-DOSベースのプロセッサ上で利用することができます。
シグナル・ベースの通知方法を選択したクライアントは、シグナルに関する制約から、システムがシグナルで通知を制御することはできません。このような状態で通知がなされた場合、システムは、選択されたクライアントに対する通知方法をディップ・インに切り替えることを示すログ・メッセージを生成し、以後、クライアントにはディップ・イン方式で通知が行われることになります。(通知方法の詳細については、UBBCONFIG()のRESOURCESセクションのNOTIFYパラメータの説明を参照してください)。
クライアントのシグナル通知は、常にシステムによって行われるので、元の通知呼出しがどこで行われるかにかかわらず、通知の形態は一貫しています。したがって、シグナル・ベースの通知を使用するには次の条件が必要です。
アプリケーション管理者のIDは、アプリケーション構成の一部として識別されます。
あるクライアントに対してシグナル・ベースの通知方法を選択すると、いくつかのATMI呼出しは異常終了します。TPSIGRSTRTの指定がなければ非請求メッセージを受け取るため、TPGOTSIGを返します。通知方法の選択については、「UBBCONFIG(5)」および「tpinit(3c)」を参照してください。
tpalloc(3c)、tpinit(3c)、tpnotify(3c)、tpterm(3c)、UBBCONFIG(5)
tpcall() - サービス・リクエストを送信し、その応答を待つルーチン
int tpcall(char *svc, char *idata, long ilen, char **odata, long \
*olen, long flags)
tpcall()は、リクエストを送り、それと同期してその応答を待ちます。この関数への呼出しは、tpacall()を呼び出した後、即座にtpgetrply()を呼び出すのと同じことです。tpcall()は、svcが指定するサービスにリクエストを送ります。このリクエストは、以前のtpspri()で変更されていないかぎり、svcに対して定義されている優先度で送信されます。このリクエストのデータ部はidataによって示され、以前にtpalloc()によって割り当てられたバッファです。ilenに送信するidataの大きさを指定します。なお、idataは、長さの指定を必要としないタイプのバッファを指している場合(たとえば、FMLのフィールド化バッファ)、ilenの値は無視(あるいは0に)されます。また、idataをNULLにすることもできますが、この場合には、ilenは無視されます。idataのタイプとサブタイプは、svcが認識するタイプおよびサブタイプのいずれかと一致しなければなりません。
odataは応答が読み込まれるバッファに対するポインタのアドレスです。olenはその応答の長さを指します。*odataは、最初にtpalloc()によって割り当てられたバッファを指す必要があります。送信と受信に同じバッファを使用する場合は、odataにはidataのアドレスを指定してください。FMLとFML32バッファは、通常最小サイズ4096バイトを確保します。応答が4096バイトより大きい場合には、バッファ・サイズは返されるデータを入れるのに十分な大きさに拡大します。また、tpcall()が呼び出されたときにidataと*odataが等しかった場合に、*odataが変更されると、idataは有効なアドレスを指さなくなります。古いアドレスを使用すると、データの破損やプロセス例外が発生する可能性があります。リリース6.4では、バッファに対するデフォルトの割当ては1024バイトです。また、最近使用したバッファの履歴情報が保持され、最適サイズのバッファをリターン・バッファとして再利用できます。
容量まで満たされていないかもしれない送信者側のバッファ(たとえば、FMLまたはFML32バッファ)は、送信に使用されたサイズになります。システムは、受信データのサイズを任意の量で拡大します。これは、受信者が送信者の割り当てたバッファ・サイズより小さく、送信されたデータのサイズより大きいバッファを受け取ることを意味します。
受信バッファのサイズは、増加することも減少することもあります。また、アドレスもシステムがバッファを内部で交換するごとに常に変更されます。応答バッファのサイズが変わったどうか(また変わったとしたらどれくらい変わったのか)を決定するには、tpgetrply()が*lenとともに発行される前に、合計サイズを比べてください。バッファ管理の詳細については、「C言語アプリケーション・トランザクション・モニター・インタフェースについて」を参照してください。
*olenが戻り時に0であると、応答にはデータ部がなく、*odataも、それが指すバッファも変更されていません。*odataまたは*olenがNULLであると、エラーになります。
TPNOTRAN
svcが呼び出されたときに、このプロセスは呼出し側のトランザクションの一部として実行されません。svcが依然としてトランザクション・モードで起動される場合がありますが、それは同じトランザクションでないことに注意してください。svcは、構成属性で、自動的にトランザクション・モードで呼び出されるようにすることができます。このフラグを設定するトランザクション・モードの呼出し側は、トランザクション・タイムアウトの影響を受けます。サービスが異常終了した場合でも、起動時にこのフラグが設定されていれば、呼出し側のトランザクションに影響は及びません。
TPNOCHANGE
odataが指すバッファとは異なるタイプのバッファが受信されると、受信側が着信バッファのタイプを識別するかぎり、*odataのバッファ・タイプは、受信されたバッファのタイプに変更されます。このフラグを設定すると、*odataが指すバッファのタイプは変更されません。つまり、受信されたバッファのタイプとサブタイプは、*odataが指すバッファのタイプとサブタイプと一致する必要があります。
TPNOBLOCK
tpcall()の送信部分にしか適用されません。この関数は応答を待ってブロックすることがあります。TPNOBLOCKが指定されていないときにブロッキング条件が存在すると、呼出し側は、その条件が解消されるか、またはタイムアウト(トランザクションまたはブロッキング)が発生するまではブロックされます。
TPNOTIME
TPSIGRSTRT
マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドはtpcall()の呼出しを発行できません。
tpcall()が正常に終了した場合、あるいはtperrnoがTPESVCFAILに設定されて終了した場合、tpurcode()には、tpreturn()の一部として送信されたアプリケーションが定義した値が入ります。
異常終了すると、tpcall()は -1を返し、tperrnoを設定してエラー条件を示します。呼出しが異常終了してtperrnoに特定の値が設定されたときは、中間のATMI呼出しを省略して引き続きtperrordetail()を呼び出すと、エラーに関する詳細な情報が提供されます。詳細は、「tperrordetail(3c)」リファレンス・ページを参照してください。
異常終了時には、tpcall()はtperrnoを次のいずれかの値に設定します(特に記述した場合を除いては、エラーが呼出し側のトランザクションに影響を及ぼすことはありません)。
TPEINVAL]
TPENOENT]
TPEITYPE]
TPEOTYPE]
TPNOCHANGEがflagsに設定されているか、*odataのタイプとサブタイプがそのサービスから送られた応答のタイプおよびサブタイプと一致しません。*odata、その内容、そして*olenはいずれも変更されません。サービス・リクエストが呼出し側の現在のトランザクションの一部として発行されると、応答が破棄されるので、そのトランザクションは中断のみとマークされます。
TPETRAN]
TPETIME]
TPNOBLOCKまたはTPNOTIMEが指定されている場合は発生しません。いずれの場合も、*odata、その内容、*olenはどれも変更されません。 トランザクション・タイムアウトが発生した場合、トランザクションがアボートされない限り、新しいリクエストの送信や未処理の応答の受信はできず、TPETIMEが発生します。その例外とは、ブロックされず、応答を期待せず、かつ呼出し側のトランザクションのかわりに送信されない(つまり、TPNOTRAN、TPNOBLOCKおよびTPNOREPLYを設定してtpacall()を呼び出した場合の)リクエストです。 サービスがトランザクションの内部で失敗した場合、そのトランザクションはTX_ROLLBACK_ONLY状態に置かれます。ほとんどの場合、この状態はタイムアウトと同じものとして扱われます。このトランザクションの以降のATMI呼出しは、TPETIMEで失敗します(前の段落で説明した例外を除きます)。
TPESVCFAIL]
TPFAILでtpreturn()を呼び出しました。これは、アプリケーション・レベルの障害です。サービスの応答の内容(送信された場合)は、*odataが示すバッファに入ります。呼出し側のトランザクションの一部としてサービス・リクエストが出された場合、トランザクションは中断のみとしてマークされます。トランザクションがタイムアウトしたかどうかに関わりなく、トランザクションが中断される前の通信で有効であるのは、TPNOREPLY、TPNOTRAN、およびTPNOBLOCKを設定したtpacall()の呼出しのみです。
TPESVCERR]
tpreturn(3c)またはtpforward(3c)のいずれかでエラーを検出しました(たとえば、誤った引数が渡された場合など)。このエラーが生じた場合には、応答データは返されません(つまり、*odata、その内容、*olenはいずれも変更されません)。呼出し側のトランザクションの一部としてサービス・リクエストが出された場合(つまり、TPNOTRANが設定されていない場合)、このトランザクションは中断のみとしてマークされます。トランザクションがタイムアウトしたかどうかに関わりなく、トランザクションが中断される前の通信で有効であるのは、TPNOREPLY、TPNOTRAN、およびTPNOBLOCKを設定したtpacall()の呼出しのみです。UBBCONFIGファイル内のSVCTIMEOUTまたはTM_MIB内のTA_SVCTIMEOUTが0でない場合にサービスのタイムアウトが発生すると、TPESVCERRが戻されます。
TPEBLOCK]
TPGOTSIG]
TPEPROTO]
TPESYSTEM]
TPEOS]
tpacall(3c)、tpalloc(3c)、tperrordetail(3c)、tpforward(3c)、tpfree(3c)、tpgprio(3c)、tprealloc(3c)、tpreturn(3c)、tpsprio(3c)、tpstrerrordetail(3c)、tptypes(3c)
tpcancel() - 未終了の応答に対する呼出し記述子を無効にするためのルーチン
#include <atmi.h>
int tpcancel(int cd)
tpcancel()は、tpacall()が返す呼出し記述子cdを取り消します。トランザクションに関連している呼出し記述子を無効にしようとするとエラーになります。
正常終了の場合、cdは以後無効になり、cdのために受信する応答はすべて、何の警告もなく捨てられてしまいます。
マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドはtpcancel()の呼出しを発行できません。
異常終了すると、tpcancel()は -1を返し、tperrnoを設定してエラー条件を示します。
失敗すると、tpcancel()はtperrnoを次のいずれかの値に設定します。
TPEBADDESC]
TPETRAN]
TPEPROTO]
TPESYSTEM]
TPEOS]
tpchkauth() - アプリケーションへの参加に認証が必要かどうかをチェックするルーチン
#include <atmi.h>
int tpchkauth(void)
tpchkauth()は、アプリケーションの構成が認証を必要としているかどうかを調べます。これは一般に、tpinit()を呼び出す前にアプリケーション・クライアントが使用して、ユーザーからのパスワードの入力を必要とするかどうかを判別します。
マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドはtpchkauth()の呼出しを発行できません。
tpchkauth()は、正常終了時に次のような負でない値を返します。
TPNOAUTH
TPSYSAUTH
TPAPPAUTH
異常終了すると、tpchkauth()は -1を返し、tperrnoを設定してエラー条件を示します。
異常終了時には、tpchkauth()はtperrnoを次のいずれかの値に設定します。
TPESYSTEM]
TPEOS]
tpchkauth()は、リリース4.2以降を使用しているサイトでしか使用できません。
tpchkauth(3c)に記述されているインタフェースは、UNIX、Windows、およびMS-DOSオペレーティング・システム上でサポートされています。
tpchkunsol() - 非請求メッセージを検査するルーチン
#include <atmi.h>
int tpchkunsol(void)
tpchkunsol()は、クライアントが任意通知型メッセージをチェックするときに使用します。クライアントでシグナル・ベースの通知を使用してこのルーチンを呼び出しても、何も行われず、ただちに終了します。この呼出しには、引数はありません。このルーチンを呼び出すと、アプリケーションで定義された任意通知型メッセージ処理ルーチンへの呼出しがOracle Tuxedo ATMIシステムのライブラリによって行われることがあります。
マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドはtpchkunsol()の呼出しを発行できません。
正常終了の場合、tpchkunsol()は、ディスパッチされた非請求メッセージの番号を返します。異常終了すると、tpchkunsol()は -1を返し、tperrnoを設定してエラー条件を示します。
失敗すると、tpchkunsol()はtperrnoを次のいずれかの値に設定します。
TPEPROTO]
TPESYSTEM]
TPEOS]
tpnotify(3c)で説明したインタフェースはすべて、ネイティブ・サイトのUNIXシステム・ベースのプロセッサ上で利用できます。さらに、ルーチンtpbroadcast()とtpchkunsol()は、関数tpsetunsol()と共に、UNIXシステムおよびMS-DOSベースのプロセッサ上で利用することができます。
シグナル・ベースの通知方法を選択したクライアントは、シグナルに関する制約から、システムがシグナルで通知を制御することはできません。このような状態で通知がなされた場合、システムは、選択されたクライアントに対する通知方法をディップ・インに切り替えることを示すログ・メッセージを生成し、以後、クライアントにはディップ・イン方式で通知が行われることになります。通知方法の詳細は、UBBCONFIG(5)のRESOURCESセクションのNOTIFYパラメータの説明を参照してください。
クライアントのシグナル通知は、常にシステムによって行われるので、元の通知呼出しがどこで行われるかにかかわらず、通知の形態は一貫しています。したがって、シグナル・ベースの通知を使用するには次の条件が必要です。
アプリケーション管理者のIDは、アプリケーション構成の一部として識別されます。
あるクライアントに対してシグナル・ベースの通知方法を選択すると、いくつかのATMI呼出しは異常終了します。TPSIGRSTRTの指定がなければ非請求メッセージを受け取るため、TPGOTSIGを返します。通知方法の選択については、「UBBCONFIG(5)」および「tpinit(3c)」を参照してください。
tpbroadcast(3c)、tpinit(3c)、tpnotify(3c)、tpsetunsol(3c)
tpclose() - リソース・マネージャをクローズするルーチン
#include <atmi.h>
int tpclose(void)
tpclose()は、呼出し側とそれにリンクされたリソース・マネージャとの関係を絶ちます。リソース・マネージャはクローズの内容がそれぞれで異なるため、個々のリソース・マネージャをクローズするために必要な情報を構成ファイルに記述します。
リソース・マネージャがすでにクローズしている場合(すなわち、tpclose()が1回以上呼び出された)、何も処理は行われず、正常終了を示すコードが返されます。
マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドは、tpclose()の呼出しを発行できません。
現在のサーバーが-Mオプションを指定して構築されている場合、tpcloseは、実行時段階でtprmopen(3c)ルーチンによってオープンされたRMを含め、オープンしているすべてのRMのクローズを試行します。
異常終了すると、tpclose()は -1を返し、tperrnoを設定してエラー条件を示します。
異常終了時には、tpclose()はtperrnoを次のいずれかの値に設定します。
TPERMERR]
TPEPROTO]
TPESYSTEM]
TPEOS]
tpopen(3c)、tprmopen(3c)、tprmclose(3c)、tprmstart(3c)、tprmend(3c)
tpcommit() - 現在のトランザクションをコミットするルーチン
#include <atmi.h>
int tpcommit(long flags)
tpcommit()はトランザクションの終了(コミット)を示します。tpcommit()は2フェーズ・コミット・プロトコルを使用して、参加リソース間の調整をとります。tpcommit()は、トランザクションの開始プロセスからのみ呼び出されます。いずれかの参加リソースがトランザクションをコミットできない場合(たとえば、それらがtpreturn()を呼び出したときにTPFAILが返された場合など)、そのトランザクション全体がアボートし、tpcommit()は異常終了します。つまり、そのトランザクションに関連して各プロセスが行ったすべての作業は取り消されます。すべての参加リソースがトランザクションの中のそれぞれが担当する部分のコミットを決定した場合、この決定は安定したストレージに記録された後、すべての参加リソースに対して作業のコミットが要求されます。
コミットの決定が記録された後、あるいは2フェーズ・コミット・プロトコルが完了した後、TP_COMMIT_CONTROL特性の設定条件に従って(tpscmt(3c)を参照)、tpcommit()は正常に終了することができます。コミットの決定が記録された後、第2フェーズが完了する前(TP_CMT_LOGGED)にtpcommit()が終了する場合、すべての参加リソースはトランザクションにかわって行った作業内容をコミットすることに同意しているとみなし、第2フェーズでトランザクションをコミットする約束を果たすようにする必要があります。ただし、tpcommit()は第2フェーズが完了する前に終了してしまうので、参加リソースの中には、この関数が正常終了した場合でもトランザクションの担当部分をヒューリスティックに(コミットの決定とは矛盾するような方法で)完了するといった状況が発生してしまいます。
TP_COMMIT_CONTROL特性が、2フェーズ・コミット・プロトコルの完了(TP_CMT_COMPLETE)後にtpcommit()が終了するように設定されている場合、その戻り値には、トランザクションの正確なステータスが反映されます(つまり、トランザクションがヒューリスティックに完了するかどうか)。
なお、トランザクションに1つのリソース・マネージャしか関与していない場合には、1フェーズ・コミットが行われます(つまり、リソース・マネージャには、コミットできるかどうかの確認はされず、単にコミットの指示が出されます)。そして、この場合、TP_COMMIT_CONTROL特性はコミットには関係せず、tpcommit()はヒューリスティックに得られた結果(もしあれば)を返します。
未終了の応答に対する呼出し記述子が存在するときにtpcommit()を呼び出すと、この関数の終了時に、トランザクションは中断し、呼出し側のトランザクションに関連付けられているこれらの記述子は、それ以後無効になります。呼出し側のトランザクションに関連付けられていない呼出し記述子の状態は、有効のままです。
tpcommit()は、呼出し側のトランザクションに関連付けられているすべての接続をクローズした後に呼び出される必要があります(そうでないと、TPEABORTが戻され、トランザクションは中断、これらの接続は、TPEV_DISCONIMMイベントを使用して不規則に切断されます)。tpbegin()の前またはTPNOTRANフラグを指定してオープンされた接続(つまり、トランザクション・モードでない状態での接続)は、tpcommit()またはtpabort()の影響を受けません。
現時点では、tpcommit()の唯一の引数flagsは、将来の使用のために予約されており、0に設定する必要があります。
マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドはtpcommit()の呼出しを発行できません。
異常終了すると、tpcommit()は -1を返し、tperrnoを設定してエラー条件を示します。
異常終了時には、tpcommit()はtperrnoを次のいずれかの値に設定します。
TPEABORT]
tpcommit()が未終了の応答が残っているか、会話型接続をオープンしたまま呼び出された場合にも返されます。
TPEHAZARD]
TPEHEURISTIC]
TPEINVAL]
TPEOS]
TPEPROTO]
TPESYSTEM]
TPETIME]
TPEABORTが返されます。
Oracle Tuxedo ATMIシステムのトランザクションを記述するためにtpbegin()、tpcommit()、およびtpabort()を使用する場合、XAインタフェースに準拠した(呼出し側に妥当にリンクされている)リソース・マネージャが行う作業のみがトランザクションのプロパティを備えていることを記憶しておくことが重要です。トランザクションにおいて実行される他のすべての操作は、tpcommit()あるいはtpabort()のいずれにも影響されません。そのリソース・マネージャが行った処理がOracle Tuxedo ATMIシステムのトランザクションの一部となるよう、XAインタフェースを満たすリソース・マネージャをサーバーにリンクする方法については、「buildserver(1)」を参照してください。
tpabort(3c)、tpbegin(3c)、tpconnect(3c)、tpgetlev(3c)、tpreturn(3c)、tpscmt(3c)
tpconnect() - 会話型サービス・ルーチンの接続を設定するルーチン
#include <atmi.h>
int tpconnect(char *svc, char *data, long len, long flags) tpconnect()により、プログラムは会話型サービスsvcとの半二重接続をセットアップすることができます。この名前は、会話型サーバーがポストした会話型サービス名の1つでなければなりません。
呼出し側は、接続セットアップ処理の一部として、アプリケーション定義データをリスニング・プログラムに渡すことができます。呼出し側がデータを渡す選択をした場合には、dataはtpalloc()が以前に割り当てたバッファを指していなければなりません。lenには送信バッファの大きさを指定します。ただし、dataが長さの指定を必要としないバッファを指している場合(FMLフィールド化バッファなど)、lenは無視されます(0でかまいません)。また、dataはNULLの場合もあります。この場合、lenは無視されます(アプリケーション・データは会話型サービスに渡されません)。dataのタイプとサブタイプは、svcが認識するタイプおよびサブタイプと一致しなければなりません。dataとlenは、該当サービスの呼出し時に使用するTPSVCINFO構造体を介して会話型サービスに渡されます。また、サービスはこのデータの取得にtprecv()を呼び出す必要はありません。
TPNOTRAN
svcが呼び出されたときに、このプロセスは呼出し側のトランザクションの一部として実行されません。svcが依然としてトランザクション・モードで起動される場合がありますが、それは同じトランザクションでないことに注意してください。svcは、構成属性で、自動的にトランザクション・モードで呼び出されるようにすることができます。このフラグを設定するトランザクション・モードの呼出し側は、トランザクション・タイムアウトの影響を受けます。サービスが異常終了した場合でも、起動時にこのフラグが設定されていれば、呼出し側のトランザクションに影響は及びません。
TPSENDONLY
TPSENDONLYまたはTPRECVONLYのいずれかを指定しなければなりません。
TPRECVONLY
TPSENDONLYまたはTPRECVONLYのいずれかを指定しなければなりません。
TPNOBLOCK
tpconnect()の送信部分にだけ適用されます。関数は、サーバーからの承認を待つ間ブロックする場合があります。TPNOBLOCKが指定されておらず、ブロッキング条件が存在する場合、条件の解除、またはブロッキング・タイムアウトあるいはトランザクション・タイムアウトが発生するまで呼出し側はブロックされます。
TPNOTIME
TPSIGRSTRT
マルチスレッド・アプリケーションの場合、TPINVALIDCONTEXT状態のスレッドはtpconnect()の呼出しを発行できません。
tpconnect()が正常に終了した場合、以後の呼出しでの接続を指すのに使用する記述子を返します。エラー時には、-1を返し、tperrnoを設定してエラー条件を示します。
異常終了時には、tpconnect()はtperrnoを次のいずれかの値に設定します(特に記述した場合を除いては、エラーが呼出し側のトランザクションに影響を及ぼすことはありません)。
TPEBLOCK]
TPEINVAL]
svcがNULL、dataがNULLでなくtpalloc()で割り当てられたバッファを指していない、TPSENDONLYまたはTPRECVONLYがflagsに指定されていない、あるいはflagsが無効であるなど)。
TPEITYPE]
TPELIMIT]
TPENOENT]
TPEOS]
TPEPROTO]
TPESYSTEM]
TPETIME]
TPNOBLOCKまたはTPNOTIMEが指定されている場合は発生しません。 トランザクション・タイムアウトが発生すると、1つの例外を除き、トランザクションが中断されないかぎり、新しい会話を開始したり、新しいリクエストを送信したり、未処理の応答を受信しようとしても、TPETIMEで失敗します。その例外とは、ブロックされず、応答を期待せず、かつ呼出し側のトランザクションのかわりに送信されない(つまり、TPNOTRAN、TPNOBLOCKおよびTPNOREPLYを設定してtpacall()を呼び出した場合の)リクエストです。 サービスがトランザクションの内部で失敗した場合、そのトランザクションはTX_ROLLBACK_ONLY状態に置かれます。ほとんどの場合、この状態はタイムアウトと同じものとして扱われます。このトランザクションの以降のATMI呼出しは、TPETIMEで失敗します(前の段落で説明した例外を除きます)。
TPETRAN]
TPGOTSIG]
tpalloc(3c)、tpdiscon(3c)、tprecv(3c)、tpsend(3c)、tpservice(3c)
tpconvert() - 構造体の文字列表現とバイナリ表現の間の変換
#include <atmi.h>
#include <xa.h>
int tpconvert(char *strrep, char *binrep, long flags)
tpconvert()は、インタフェース構造体の文字列表現(strrep)とバイナリ表現(binrep)の間で変換を行います。
変換の方向およびインタフェース構造体のタイプは、どららもflags引数で指定します。バイナリ表現から文字列表現に構造体を変換するには、プログラマがTPTOSTRINGビットをflagsに設定する必要があります。文字列からバイナリに構造体を変換するには、プログラマがビットをクリアする必要があります。変換する構造体のタイプを示すフラグは次のように定義されており、同時に1つのフラグのみを指定できます。
TPCONVCLTID
TPCONVTRANID
TPCONVXID
バイナリ表現から文字列表現に変換する場合、strrepは最低でもTPCONVMAXSTR文字の長さがなければなりません。
TPTRANIDとXIDの値が異なる文字列バージョンをキー・フィールドとして許すTM_MIB(5)クラス(たとえばT_TRANSACTIONおよびT_ULOG)にアクセスする場合は、システムはこれらの値を等しいものとして扱うことに注意してください。したがって、アプリケーション・プログラムでは、これらのデータ・タイプの文字列の値を作ったり操作したりすべきではありません。これらの値のいずれかがキー・フィールドとして使用される場合、TM_MIB(5)は文字列で識別されるグローバル・トランザクションに一致するオブジェクトのみが返されることを保証します。
マルチスレッドのアプリケーション中のスレッドは、TPINVALIDCONTEXTを含め、どのコンテキスト状態で実行していても、tpconvert()の呼出しを発行できます。
異常終了すると、tpconvert()は -1を返し、tperrnoを設定してエラー条件を示します。
次の条件が発生すると、tpconvert()は失敗し、tperrnoを次のように設定します。
TPEINVAL]
TPEOS]
TPESYSTEM]
userlog(3c)に書き込まれます。
このインタフェースは、Oracle Tuxedo ATMIリリース5.0またはそれ以降でしか利用できません。このインタフェースは、ワークステーション・プラットフォームで利用できます。
tpresume(3c)、tpservice(3c)、tpsuspend(3c)、tx_info(3c)、TM_MIB(5)
tpconvmb() - 入力バッファ内にある文字のエンコードをターゲットの名前付きのエンコードに変換
#include <atmi.h>
extern int tperrno;
int
tpconvmb (char **bufp, int *len, char *target_encoding, long flags)
この関数は、入力バッファを目的のコードセットのエンコードに変換する場合に使用します。
この関数は、ユーザーの利便性を考慮して追加されたものであり、通常の自動によるコードセットのデータ変換では必須ではありません。
引数bufpは、MBSTRING型付きバッファのメッセージを指す有効なポインタです。バッファのサイズが変換済みバッファの出力データの処理に不十分な場合、このポインタは内部的に再割り当てされます。
入力での引数lenには、変換に必要なバイト数が入ります。変換が正常に終了すると、bufpで使用されたバイト数が入ります。
引数target_encodingは、bufpメッセージで提供される型付きバッファの変換に使用するターゲットのコードセットのエンコード名です。
flags引数はTuxedo会話モードでは使用されません。これは、ユーザー定義の変換関数用のバッファ・タイプ・スイッチ関数に渡されます。
正常終了の場合、tpconvmb()は0を返します。エラーの場合には-1を返し、次に説明するようにtperrnoを設定します。この関数は、次の原因により異常終了する可能性があります。
TPEINVAL]
TPEPROTO]
TPESYSTEM]
TPEOS]
tpalloc(3c)、tpgetmbenc(3c)、tpsetmbenc(3c)
tpcryptpw() - 管理リクエスト内のアプリケーション・パスワードを暗号化
#include <atmi.h>
#include <fml32.h>
int tpcryptpw(FBFR32 *buf)
tpcryptpw()は、サービスにリクエストを送る前に管理リクエスト・バッファ内のアプリケーション・パスワードを暗号化するために使用します。アプリケーション・パスワードは、FML32フィールド識別子TA_PASSWORDを用いて文字列値として保存されます。この暗号化は、テキスト・レベルのパスワードが危険にさらされず、すべてのアクティブなアプリケーション・サイトに適当なパスワードの更新が伝播することを保証するために必要です。付加的なシステム・フィールドが呼出し側のバッファに追加され、既存のフィールドがリクエストを満たすために変更されることがあります。
マルチスレッドのアプリケーション中のスレッドは、TPINVALIDCONTEXTを含め、どのコンテキスト状態で実行していても、tpcryptpw()の呼出しを発行できます。
異常終了すると、tpcryptpw()は -1を返し、tperrnoを設定してエラー条件を示します。
異常終了時には、tpcryptpw()はtperrnoを次のいずれかの値に設定します。
TPEINVAL]
TPEPERM]
TPEOS]
TPESYSTEM]
userlog(3c)に書き込まれます。
このインタフェースは、Oracle Tuxedo ATMIリリース5.0またはそれ以降が稼働するUNIX Systemのサイトでしか利用できません。このインタフェースはワークステーション・クライアントでは利用できません。
${TUXDIR}/lib/libtmib.a、${TUXDIR}/lib/libtmib.so.rel
tpdequeue() - キューからメッセージを取り出すルーチン
#include <atmi.h>
int tpdequeue(char *qspace, char *qname, TPQCTL *ctl, char **data, long *len, long flags)
tpdequeue()は、キュー・スペースqspace内のqnameで指定されるキューから、処理するメッセージを取り出します。
省略時設定では、キューの先頭のメッセージが取り出されます。キュー上のメッセージの順序は、そのキューの作成時に定義されます。アプリケーションは、ctlパラメータでメッセージ識別子または相関識別子を指定することにより、特定のメッセージのキューからの取出しをリクエストできます。メッセージが現在利用できなかった場合にはアプリケーションはメッセージを待つということを示すために、ctlフラグを使用することもできます。ctlパラメータを使って、メッセージをキューから削除したりキューでのメッセージの相対位置を変更せずにメッセージを見ることができます。この後のこのパラメータについての説明を参照してください。
dataはメッセージが読み込まれるバッファに対するポインタのアドレスです。lenはそのメッセージの長さを指します。*dataは、最初にtpalloc()によって割り当てられたバッファを指す必要があります。メッセージがtpdequeueに渡されるバッファよりも大きい場合、バッファはメッセージが入れる大きさまで拡大されます。メッセージ・バッファのサイズに変化があるかどうかを判別するには、tpdequeue()が発行される前の(合計の)サイズを*lenと比較します。*lenのほうが大きい場合、バッファは大きくなっています。そうでない場合は、バッファのサイズは変更されていません。なお、*dataは、バッファのサイズが大きくなったこと以外の理由でも変化する可能性があるので注意してください。終了時に*lenが0である場合は、取り出されたメッセージにはデータ部がなく、*dataも*dataが指すバッファも変更されていません。*dataまたはlenがNULLであるとエラーになります。
呼出し側がトランザクション・モードにあり、TPNOTRANフラグが設定されていない場合は、メッセージはトランザクション・モードでキューから取り出されます。この結果、tpdequeue()が正常終了して呼出し側のトランザクションが正常にコミットされると、リクエストはキューから削除されます。呼出し側のトランザクションが、明示的に、またはトランザクション・タイムアウトあるいは何らかの通信エラーの結果としてロールバックされると、メッセージはキュー上に残されます。つまり、キューからのメッセージの削除もロールバックされます。同じトランザクション内で、同じメッセージの登録と取出しを行うことはできません。
呼出し側がトランザクション・モードにないか、またはTPNOTRANフラグが設定されている場合は、メッセージはトランザクション・モードではキューから取り出されません。トランザクション・モードでない場合に通信エラーまたはタイムアウトが発生した場合、アプリケーションには、メッセージが正しくキューから取り出されたかどうかがわからず、メッセージが失われることがあります。
TPNOTRAN
TPNOBLOCK
tperrnoにTPEBLOCKが設定されます。このフラグが設定されていて、ターゲットのキューが別のアプリケーションによって排他的にオープンされているなどのブロッキング条件が存在する場合には、呼出しは失敗してtperrnoにTPEDIAGNOSTICが設定され、TPQCTL構造体の診断フィールドはQMESHAREに設定されます。後者の場合、Oracle Tuxedo ATMIシステム以外のOracle製品をベースとするアプリケーションが、キューイング・サービスAPI (QSAPI)を使用した排他的な読取り/書込みのためのキューをオープンしています。
TPNOBLOCKが設定されていない場合に、ブロッキング状態が存在すると、その状態が解消されるかタイムアウト(トランザクション・タイムアウトまたはブロッキング・タイムアウト)が発生するまで、呼出し側はブロックされます。(TPQCTL構造体の) flagsにTPQWAITオプションが指定されている場合は、このブロッキング条件には、キュー自体のブロッキングは含まれません。
TPNOTIME
TPNOCHANGE
dataが指すバッファのタイプは変更されません。デフォルトでは、*dataが指すバッファとは異なるタイプのバッファが受信されると、受信側が着信バッファのタイプを識別するかぎり、*dataのバッファ・タイプは、受信されたバッファのタイプに変更されます。つまり、受信されたバッファのタイプおよびサブタイプは、*dataが指すバッファのタイプおよびサブタイプと一致する必要があります。
TPSIGRSTRT
tperrnoはTPGOTSIGに設定されます。
tpdequeue()が正常終了すると、アプリケーションは、ctlデータ構造体を使用してメッセージに関する追加情報を取得できます。この情報には、キューから取り出されたメッセージのメッセージ識別子、すべての応答または異常終了メッセージに付随して、発信元がメッセージと元のリクエストを結び付けることができるようにする相関識別子、メッセージが送られるサービスの品質、メッセージの応答が送られるサービスの品質、応答が要求された場合は応答キューの名前、およびメッセージをキューから取り出すときの失敗に関する情報をアプリケーションが登録できる異常終了キューの名前が含まれます。これらについて以下に説明します。
マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドは、tpdequeue()の呼出しを発行できません。
TPQCTL構造体は、アプリケーション・プログラムが、キューからのメッセージの取出しに関連するパラメータを渡したり、取得したりするために使用します。TPQCTLの要素flagsは、この構造体の他のどの要素が有効であるかを示すために使用されます。
tpdequeue()への入力時には、次の要素をTPQCTL構造体に設定できます。
long flags; /* indicates which of the values
* are set */
char msgid[32]; /* ID of message to dequeue */
char corrid[32]; /* correlation identifier of
* message to dequeue */
tpdequeue()の入力情報を制御するflagsパラメータの有効なビットの一覧を次に示します。
TPNOFLAGS
TPQGETBYMSGID
ctl
msgidによって指定されたメッセージ識別子を持つメッセージのエキューをリクエストします。メッセージ識別子は、事前のtpenqueue(3c)の呼出しによって取得できます。メッセージが別のキューに移動すると、メッセージ識別子が変わることに注意してください。また、メッセージ識別子の値は32バイトすべてが意味を持つため、ctlmsgidによって指定された値を完全に初期化する必要があります(たとえば、NULL文字で埋めるなど)。
TPQGETBYCORRID
ctlcorridによって指定された相関識別子を持つメッセージのデキューをリクエストします。相関識別子は、アプリケーションがtpenqueue()でメッセージをエンキューしたときに指定されます。また、相関識別子の値は32バイト全体が意味を持つため、ctlcorridによって指定された値を完全に初期化する必要があります(たとえば、NULL文字で埋めるなど)。
TPQWAIT
TPQWAITがTPQGETBYMSGIDまたはTPQGETBYCORRIDとともに設定されている場合、指定されたメッセージ識別子または相関識別子を持つメッセージがキューに存在しないときは、エラーが戻されません。かわりに、基準を満たすメッセージを取り出せるようになるまで、プロセスは待機する必要があります。プロセスが呼出し側のトランザクション・タイムアウトに従っている場合、またはトランザクション・モードでない場合、プロセスは、TMQUEUEプロセスに-tオプションで指定されたタイムアウトの影響を受けます。
tpdequeueは -1を返しtperrnoをTPEDIAGNOSTICに設定し、TPQCTL構造体の診断フィールドをQMESYSTEMに設定します。 TPQWAIT制御パラメータを指定するtpdequeue()の各リクエストでは、条件を満たすメッセージがすぐに利用できない場合、キュー・マネージャ(TMQUEUE)のアクション・オブジェクトを使用できる必要があります。アクション・オブジェクトが使用できない場合、tpdequeue()リクエストは失敗します。利用できるキュー・マネージャのアクション数は、キュー・スペースの作成時または変更時に指定されます。待機中のキューからの取出しリクエストが完了すると、対応するアクション・オブジェクトは別のリクエストに使用できるようになります。
TPQPEEK
tpdequeue()操作にTPNOTRANフラグが設定されていることを意味します。つまり、非破壊的なキューからの取出しはトランザクションに含まれません。トランザクション終了前のトランザクション内で、キューに登録されたメッセージまたはキューから取り出されたメッセージを読み取ることはできません。
TPQPEEKを使用してメッセージを破棄せずにキューから取り出す場合、その取出しリクエストをシステムが処理している短時間の間、非ブロッキング状態のほかのメッセージ取出し操作にメッセージが認識されないことがあります。たとえば、メッセージ識別子や相関識別子などの特定の選択基準を使用してメッセージをキューから取り出す操作で、現在、非破壊的なキューから取出し中のメッセージを検索する場合などです。
tpdequeue()からの出力時には、次の要素がTPQCTL構造体に設定されます。
long flags; /* indicates which of the values
* should be set */
long priority; /* enqueue priority */
char msgid[32]; /* ID of message dequeued */
char corrid[32]; /* correlation identifier used to
* identify the message */
long delivery_qos; /* delivery quality of service */
long reply_qos; /* reply message quality of service */
char replyqueue[128]; /* queue name for reply */
char failurequeue[128]; /* queue name for failure */
long diagnostic; /* reason for failure */
long appkey; /* application authentication client
* key */
long urcode; /* user-return code */
CLIENTID cltid; /* client identifier for originating
* client */
次は、tpdequeue()からの出力情報を制御するflagsパラメータの有効なビットです。どのフラグ・ビットでも、tpdequeue()の呼出し時にオンになっていると、メッセージがエンキューされたときに提供された値が、構造体の関連する要素に格納され、そのビットは設定されたままになります。値が使用できない場合、またはtpdequeue()を呼び出したときにビットが設定されなかった場合、tpdequeue()はフラグがオフの状態で完了します。
TPQPRIORITY
tpdequeue()の呼出しが正常終了し、メッセージが明示的な優先度でキューに登録された場合、この優先度がctlpriorityに格納されます。優先度は1以上100以内の範囲内で、数値が高いほど優先度も高くなります。つまり、高い数値のメッセージが低い数値のメッセージよりも先にキューから取り出されます。優先度によって順序付けられていないキューの場合、値は情報にすぎません。
TPQMSGID
TPQCORRID
tpdequeue()の呼出しが正常終了し、メッセージが相関識別子によってエンキューされた場合、この相関識別子がctlcorridに格納されます。相関識別子の値は、32バイト全体が意味を持ちます。Oracle Tuxedo ATMI /Qが提供するメッセージの応答には、すべて元のリクエスト・メッセージの相関識別子が付いています。
TPQDELIVERYQOS
tpdequeue()の呼出しが成功し、メッセージがサービスの配信品質と共にキューに登録されていた場合、TPQQOSDEFAULTPERSIST、TPQQOSPERSISTENT、またはTPQQOSNONPERSISTENTフラグがctl->delivery_qosに格納されます。メッセージがキューに登録されたときに配信サービスの品質が明示的に指定されていない場合は、ターゲットとなるキューのデフォルトの配信ポリシーによってメッセージ配信の品質が決まります。
TPQREPLYQOS
tpdequeue()の呼出しが成功し、メッセージがサービスの応答品質と共にキューに登録されていた場合、TPQQOSDEFAULTPERSIST、TPQQOSPERSISTENT、またはTPQQOSNONPERSISTENTフラグがctl->reply_qosに格納されます。メッセージがキューに登録されていたときに応答のサービス品質が明示的に指定されていない場合、ctl->replyqueueキューのデフォルトの配信ポリシーによって、すべての応答に対する配信サービスの品質が決まります。
TPQREPLYQ
tpdequeue()の呼出しが正常終了し、メッセージが応答キューによってエンキューされた場合、応答キューの名前がctlreplyqueueに格納されます。メッセージへの応答は、リクエスト・メッセージと同じキュー・スペース内の指定された応答キューに登録されます。
TPQFAILUREQ
tpdequeue()の呼出しが正常終了し、メッセージが失敗キューによってエンキューされた場合、失敗キューの名前がctlfailurequeueに格納されます。失敗メッセージは、リクエスト・メッセージと同じキュー・スペース内の指定された失敗キューに登録されます。
flagsパラメータの残りのビットは、tpdequeue()が呼び出されるとクリア(0に設定)されます。これには、TPQTOP、TPQBEFOREMSGID、TPQTIME_ABS、TPQTIME_REL、TPQEXPTIME_ABS、TPQEXPTIME_REL、およびTPQEXPTIME_NONEが含まれます。これらのビットは、tpenqueue()の入力情報を制御するflagsパラメータの有効なビットです。
tpdequeue()の呼出しが失敗してtperrnoにTPEDIAGNOSTICが設定された場合は、失敗の原因を示す値がctldiagnosticに戻されます。戻される可能性のある値は、この後の「診断」の項で定義しています。
また出力時には、tpdequeue()の呼出しが正常に終了すると、ctlappkeyにアプリケーション認証キーが設定され、ctlcltidにリクエストの発信元であるクライアントの識別子が設定され、ctlurcodeにメッセージ登録時に設定されたユーザー戻り値が設定されます。
ctlパラメータがNULLである場合、入力フラグはTPNOFLAGSとみなされ、アプリケーション・プログラムは出力情報を利用できません。
異常終了すると、tpdequeue()は -1を返し、tperrnoを設定してエラー条件を示します。
異常終了時には、tpdequeue()はtperrnoを次のいずれかの値に設定します(特に記述した場合を除いては、エラーが呼出し側のトランザクションに影響を及ぼすことはありません)。
TPEINVAL]
TPENOENT]
qspaceを利用できないので、これにアクセスできません(関連するTMQUEUE(5)サーバーは利用できません)。または、グローバル・トランザクション表(GTT)にエントリがないので、グローバル・トランザクションを開始できません。
TPEOTYPE]
TPNOCHANGEがflagsに設定されていますが、*dataのタイプおよびサブタイプが、サービスによって送信された応答のタイプおよびサブタイプと一致しません。いずれの場合も、*data、その内容、および*lenはいずれも変更されません。 呼出しがトランザクション・モードで行われ、このエラーが発生すると、トランザクションはアボートのみになり、メッセージはキューに残ります。
TPETIME]
TPNOBLOCKまたはTPNOTIMEが指定されている場合は発生しません。いずれのケースでも、*data、その内容、*lenはいずれも変更されません。 トランザクション・タイムアウトが発生すると、1つの例外を除き、トランザクションが中断されないかぎり、会話を継続したり、新しいリクエストを送信したり、未処理の応答を受信しようとしても、TPETIMEで失敗します。その例外とは、ブロックされず、応答を期待せず、かつ呼出し側のトランザクションのかわりに送信されない(つまり、TPNOTRAN、TPNOBLOCKおよびTPNOREPLYを設定してtpacall()を呼び出した場合の)リクエストです。 サービスがトランザクションの内部で失敗した場合、そのトランザクションはTX_ROLLBACK_ONLY状態に置かれます。ほとんどの場合、この状態はタイムアウトと同じものとして扱われます。このトランザクションの以降のATMI呼出しは、TPETIMEで失敗します(前の段落で説明した例外を除きます)。
TPEBLOCK]
TPGOTSIG]
TPEPROTO]
TPESYSTEM]
TPEOS]
TPEDIAGNOSTIC]
次の診断値は、キューからのメッセージの取出し中に返されます。
QMEINVAL]
QMEBADRMID]
QMENOTOPEN]
QMETRAN]
TPNOTRANフラグを設定して呼び出したために、メッセージをキューから取り出すトランザクション開始のエラーが発生しました。この診断は、Oracle Tuxedoリリース7.1以降のキュー・マネージャからは返されません。
QMEBADMSGID]
QMESYSTEM]
QMEOS]
QMEABORTED]
QMEPROTO]
QMEBADQUEUE]
QMENOMSG]
QMEINUSE]
QMESHARE]
qmadmin(1)、tpalloc(3c)、tpenqueue(3c)、APPQ_MIB(5)、TMQUEUE(5)
tpdiscon() - 会話型サービスの接続を切断するルーチン
#include <atmi.h>
int tpdiscon(int cd)
tpdiscon()は、cdで指定された接続をただちに切断し、接続の他方の側でTPEV_DISCONIMMイベントを生成します。
tpdiscon()は、会話の起動側からしか呼び出せません。tpdiscon()は、呼出しに使用された記述子に対応する会話型サービス内からは呼び出せません。会話型サービスはtpreturn()を使用して、会話の該当部分が完了したことを通知しなければなりません。同様に、会話型サービスとのやりとりを行うプログラムがtpdiscon()を呼び出す場合でも、そのサービスにtpreturn()で接続を切断するようにしてください。これによって、正しい結果が得られます。
tpdiscon()を使用すると、接続はただちに切断されます(すなわち、正常終了ではなく、アボート)。したがって、宛先に届いていないデータは失われます。tpdiscon()は、接続の他方の側のプログラムが呼出し側のトランザクションに参加している場合でも発行されます。この場合、このトランザクションはアボートします。また、呼出し側は、tpdiscon()が呼び出されるときにその接続の制御権をもっている必要はありません。
異常終了すると、tpdiscon()は -1を返し、tperrnoを設定してエラー条件を示します。
異常終了時には、tpdiscon()はtperrnoを次のいずれかの値に設定します。
TPEBADDESC]
TPETIME]
tpdiscon()を呼び出すと、tpdiscon()が正常に呼び出されても、トランザクションが中断のみとしてマークされる可能性があります。 呼出し側がトランザクション・モードでない場合、ブロッキング・タイムアウトが発生しています。 トランザクション・タイムアウトが発生すると、1つの例外を除き、トランザクションが中断されないかぎり、会話を継続したり、新しいリクエストを送信したり、未処理の応答を受信しようとしても、TPETIMEで失敗します。その例外とは、ブロックされず、応答を期待せず、かつ呼出し側のトランザクションのかわりに送信されない(つまり、TPNOTRAN、TPNOBLOCKおよびTPNOREPLYを設定してtpacall()を呼び出した場合の)リクエストです。 サービスがトランザクションの内部で失敗した場合、そのトランザクションはTX_ROLLBACK_ONLY状態に置かれます。ほとんどの場合、この状態はタイムアウトと同じものとして扱われます。このトランザクションの以降のATMI呼出しは、TPETIMEで失敗します(前の段落で説明した例外を除きます)。
TPEPROTO]
TPESYSTEM]
TPEOS]
tpabort(3c)、tpcommit(3c)、tpconnect(3c)、tprecv(3c)、tpreturn(3c)、tpsend(3c)
tpenqueue() - メッセージをキューに登録するルーチン
#include <atmi.h>
int tpenqueue(char *qspace, char *qname, TPQCTL *ctl, char *data, long len, long flags)
tpenqueue()は、キュー・スペースqspace内のqnameで指定されるキューに、メッセージを格納します。キュー・スペースは、キューを集めたもので、そのうちの1つのキューがqnameでなければなりません。
メッセージがOracle Tuxedo ATMIシステムのサーバーを対象としている場合、qnameは、サーバーによって提供されるサービスの名前に一致します。システムが提供するサーバーであるTMQFORWARD(5)は、メッセージをキューから取り出し、キューと同じ名前のサービスを提供するサーバーにそのメッセージを転送するデフォルトのメカニズムを提供します。発信元が応答を期待していた場合は、転送されたサービス・リクエストへの応答は、特に指定されている場合を除き、発信元のキューに格納されます。発信元は、後で応答メッセージをキューから取り出します。キューは、任意の2つのOracle Tuxedo ATMIシステムのプロセス間(クライアントやサーバー)における信頼性の高いメッセージ転送メカニズム用としても使用できます。この場合、キューの名前はサービス名とは一致せず、メッセージ転送のための名前に関連します。
dataがNULL以外である場合、これは事前にtpalloc()によって割り当てられたバッファを指さなければならず、lenは、キューに登録されるバッファ内のデータの大きさを指定しなければなりません。長さを指定する必要のないタイプのバッファ(FMLフィールド化バッファなど)をdataが指す場合、lenは無視されます。dataがNULLの場合、lenは無視され、データ部分なしでメッセージはキューに登録されます。
メッセージは、qspace用に定義された優先度が事前のtpsprio()の呼出しによって無効化されていないかぎり、qspace用の優先度でキューに登録されます。
呼出し側がトランザクションにあり、TPNOTRANフラグが設定されていない場合は、メッセージは、トランザクション・モードでエンキューされます。この結果、tpenqueue()が正常終了して呼出し側のトランザクションが正常にコミットされると、メッセージは、トランザクションの完了後に処理されることが保証されます。呼出し側のトランザクションが、明示的に、またはトランザクション・タイムアウトあるいはなんらかの通信エラーの結果としてロールバックされると、メッセージはキューから削除されます(つまり、キューへのメッセージの登録もロールバックされます)。同じトランザクション内で同じメッセージのエンキューとデキューを行うことはできません。
呼出し側がトランザクション・モードにないか、またはTPNOTRANフラグが設定されている場合は、メッセージはトランザクション・モードではキューに登録されません。tpenqueue()が正常終了すれば、出されたメッセージが処理されることが保証されます。トランザクション・モードでないときに通信エラーまたはタイムアウトが発生した場合、アプリケーションには、メッセージが正しくキューに格納されたかどうかがわかりません。
メッセージが処理される順序は、この後説明するように、ctlデータ構造体を介してアプリケーションによって制御されます。デフォルトのキューの順序は、キューの作成時に設定されます。
TPNOTRAN
TPNOBLOCK
tperrnoにTPEBLOCKが設定されます。このフラグが設定されていて、ターゲットのキューが別のアプリケーションによって排他的にオープンされているなどのブロッキング条件が存在する場合には、呼出しは失敗してtperrnoにTPEDIAGNOSTICが設定され、TPQCTL構造体の診断フィールドはQMESHAREに設定されます。後者の場合、Oracle Tuxedo ATMIシステム以外のOracle製品をベースとするアプリケーションが、キューイング・サービスAPI (QSAPI)を使った排他的な読み書きのためのキューをオープンしています。
TPNOBLOCKが設定されていない場合に、ブロッキング状態が存在すると、その状態が解消されるかタイムアウト(トランザクション・タイムアウトまたはブロッキング・タイムアウト)が発生するまで、呼出し側はブロックされます。タイムアウトが発生すると、呼出しは異常終了し、tperrnoはTPETIMEに設定されます。
TPNOTIME
TPSIGRSTRT
TPSIGRSTRTが指定されておらず、システム・コールがシグナルによって中断された場合、tpenqueue()は異常終了し、tperrnoにTPGOTSIGが設定されます。
キューへのメッセージ登録に関する追加情報は、ctlデータ構造体を介して指定できます。この情報には、デフォルトのキューの順序付けを無効にしてキューの先頭または登録済みのメッセージの前にメッセージを登録するための値、キューからメッセージを取り出すまでの絶対時間または相対時間、メッセージが期限切れになりキューから削除される絶対時間または相対時間、メッセージ配信サービスの品質、メッセージが応答する際のサービス品質、メッセージとそのメッセージに関連付けられた応答または異常終了メッセージを結び付けるときに役立つ相関識別子、応答を登録するキューの名前、およびすべての異常終了メッセージを登録するキューの名前が含まれます。
マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドはtpenqueue()を呼び出すことはできません。
TPQCTL構造体は、アプリケーション・プログラムが、キューへのメッセージの登録に関連するパラメータを渡したり、取得したりする際に使用されます。TPQCTLの要素flagsは、この構造体の他のどの要素が有効であるかを示すために使用されます。
tpenqueue()への入力時には、次の要素をTPQCTL構造体に設定できます。
long flags; /* indicates which of the values
* are set */
long deq_time; /* absolute/relative for dequeuing */
long priority; /* enqueue priority */
long exp_time /* expiration time */
long delivery_qos /* delivery quality of service */
long reply_qos /* reply quality of service */
long urcode; /* user-return code */
char msgid[32]; /* ID of message before which to queue
* request */
char corrid[32]; /* correlation identifier used to
* identify the msg */
char replyqueue[128]; /* queue name for reply message */
char failurequeue[128]; /* queue name for failure message */
tpenqueue()の入力情報を制御するflagsパラメータの有効なビットの一覧を次に示します。
TPNOFLAGS
TPQTOP
TPQTOPとTPQBEFOREMSGIDは、相互に排他的なフラグです。
TPQBEFOREMSGID
ctlmsgidによって識別されるメッセージの前に登録されます。このリクエストは、キューが順序を無効化できるように構成されているかどうかに応じて、受け入れられない場合があります。TPQTOPとTPQBEFOREMSGIDは、相互に排他的なフラグです。また、メッセージ識別子の値は32バイト全体が意味を持つため、ctlmsgidによって指定された値を完全に初期化する必要があります(たとえば、NULL文字で埋めるなど)。
TPQTIME_ABS
ctldeq_timeによって指定された時間の後で使用可能になります。deq_timeは、time(2)、mktime(3C)またはgp_mktime(3c)によって生成された絶対時間値です(UTC (協定世界時) 1970年1月1日00:00:00から経過した秒数)。TPQTIME_ABSとTPQTIME_RELは、相互に排他的なフラグです。絶対時間は、キュー・マネージャ・プロセスが存在するマシン・クロックによって決定されます。
TPQTIME_REL
ctldeq_timeは、キューの登録が完了した後、出されたリクエストが処理されるまでの遅延秒数を指定します。TPQTIME_ABSとTPQTIME_RELは、相互に排他的なフラグです。
TPQPRIORITY
ctlpriorityに格納されます。優先度は、1から100以下の範囲である必要があります。数値が高いほど優先度も高くなり、高い数値のメッセージが低い数値のメッセージより先にキューから取り出されます。優先度によって順序付けられていないキューでは、この値は参考として使用されます。
TPQCORRID
ctlcorridで指定された相関識別子の値は、メッセージがtpdequeue()によってデキューされるときに使用できます。この識別子は、エンキューされるすべての応答メッセージまたは失敗メッセージに付加されるため、アプリケーションは応答を特定のリクエストに結び付けることができます。また、相関識別子の値は32バイト全体が意味を持つため、ctlcorridで指定された値を完全に初期化する必要があります(たとえば、NULL文字で埋めるなど)。
TPQREPLYQ
ctlreplyqueueで指定された応答キューは、待機メッセージに関連付けられます。メッセージに対する応答はすべて、リクエスト・メッセージと同じキュー・スペース内の指定されたキューに登録されます。この文字列は、NULLで終了する必要があります(最大127文字)。
TPQFAILUREQ
ctlfailurequeueで指定された失敗キューは、待機メッセージに関連付けられます。(1)キューに登録されたメッセージがTMQFORWARD()によって処理され、(2) TMQFORWARDが-dオプションで開始され、さらに(3)サービスが失敗してNULL以外の応答を戻す場合は、その応答と関連するtpurcodeによって構成される失敗メッセージが、元のリクエスト・メッセージと同じキュー・スペース内で指定されたキューに登録されます。この文字列はNULLで終了する必要があります(長さは最大127文字)。
TPQDELIVERYQOS、TPQREPLYQOS
TPQDELIVERYQOSフラグが設定されていると、ctl->delivery_qosで指定されたフラグにより、メッセージの配信サービスの品質が制御されます。その場合、相互に排他的な3つのフラグTPQQOSDEFAULTPERSIST、TPQQOSPERSISTENT、TPQQOSNONPERSISTENTのいずれかをctl->delivery_qosに設定しなければなりません。TPQDELIVERYQOSフラグが設定されていない場合、ターゲットのキューのデフォルトの配信ポリシーがメッセージに対するサービスの配信品質を指定します。
TPQREPLYQOSフラグが設定されていると、ctl->reply_qosで指定されるフラグが、メッセージの応答に対するサービスの品質を制御します。その場合、相互に排他的な3つのフラグTPQQOSDEFAULTPERSIST、TPQQOSPERSISTENT、TPQQOSNONPERSISTENTのいずれかをctl->reply_qosに設定しなければなりません。TPQREPLYQOSフラグは、TMQFORWARDによって処理されるメッセージから応答が返されるときに使用されます。サービスを呼び出すときにTMQFORWARDを使用しないアプリケーションでは、自身の応答メカニズムのヒントとしてTPQREPLYQOSフラグを使用できます。 TPQREPLYQOSが設定されていない場合、ctl->replyqueueキューのデフォルトの配信ポリシーが応答に対するサービスの配信品質を指定します。デフォルトの配信ポリシーは、メッセージに対する応答がキューに登録されるときに決定される点に注意してください。つまり、元のメッセージがキューに登録されてから応答が登録されるまでの間に、応答キューのデフォルトの配信ポリシーが変更された場合、応答が最後に登録される時点で有効なポリシーが使用されます。 次は、ctl->delivery_qosとctl->reply_qosの有効なフラグです。
TPQEXPTIME_ABS
ctl->exp_timeに格納された値で示されます。ctl->exp_timeの値は、time(2)、mktime(3C)、またはgp_mktime(3c)によって生成された絶対時間、つまり世界協定時(UTC) 1970年1月1日00:00:00から経過した秒数に設定されなければなりません。 キューへの登録操作の時間より早い絶対時間が指定されると、操作は正常終了しますが、メッセージはしきい値の計算の対象になりません。期限切れ時間がメッセージの使用可能時間より早い時間の場合、使用可能時間が期限切れ時間より早い時間になるようにいずれかの時間を変更しないかぎり、メッセージをキューから取り出すことはできません。また、これらのメッセージがキューからの取出しの対象になったことがなくても、期限切れ時間になるとキューから削除されます。トランザクション内でメッセージの期限が切れた場合、それによってトランザクションが異常終了することはありません。トランザクション内でキューへの登録中、またはキューからの取出し中に期限切れになったメッセージは、トランザクションが終了した時点でキューから削除されます。メッセージの有効期限が切れたことの通知は行われません。 TPQEXPTIME_ABS、TPQEXPTIME_REL、およびTPQEXPTIME_NONEは、相互に排他的なフラグです。この3つのどのフラグも設定されていない場合、ターゲットのキューに対応しているデフォルトの有効期限の時間がメッセージに適用されます。
TPQEXPTIME_REL
ctl->exp_timeに格納された値で示されます。
TPQEXPTIME_ABS、TPQEXPTIME_REL、およびTPQEXPTIME_NONEは、相互に排他的なフラグです。この3つのどのフラグも設定されていない場合、ターゲットのキューに対応しているデフォルトの有効期限の時間がメッセージに適用されます。
TPQEXPTIME_NONE
TPQEXPTIME_ABS、TPQEXPTIME_REL、およびTPQEXPTIME_NONEは、相互に排他的なフラグです。この3つのどのフラグも設定されていない場合、ターゲットのキューに対応しているデフォルトの有効期限の時間がメッセージに適用されます。
また、TPQCTLの要素urcodeにユーザー戻り値を設定することができます。この値は、メッセージをキューから取り出すアプリケーションに返されます。
tpenqueue()からの出力時には、次の要素がTPQCTL構造体に設定されます。
long flags; /* indicates which of the values
* are set */
char msgid[32]; /* ID of enqueued message */
long diagnostic; /* indicates reason for failure */
tpenqueue()からの出力情報を制御するflagsパラメータの有効なビットの一覧を次に示します。tpenqueue()の呼出し時にこのフラグがオンになっていると、/QサーバーTMQUEUE(5)は、構造体の対応する要素にメッセージ識別子を挿入します。tpenqueue()の呼出し時にこのフラグ・ビットをオフにしていると、TMQUEUE()によって構造体の関連要素にメッセージ識別子は設定されません。
TPQMSGID
tpenqueue()の呼出しが正常終了した場合、メッセージ識別子がctlmsgidに格納されます。メッセージ識別子の値は32バイト全体が意味を持つため、ctlmsgidに格納される値は完全に初期化されます(たとえば、NULL文字で埋めるなど)。初期化に使用される実際の埋め文字は、Oracle Tuxedo ATMI /Qコンポーネントのリリースによって異なります。
制御構造体の残りのメンバーは、tpenqueue()への入力に使用されません。
tpenqueue()の呼出しが失敗してtperrnoにTPEDIAGNOSTICが設定された場合は、失敗の原因を示す値がctldiagnosticに戻されます。戻される可能性のある値は、この後の「診断」の項で定義しています。
このパラメータがNULLである場合、入力フラグは、TPNOFLAGSとみなされ、アプリケーション・プログラムは出力情報を利用できません。
異常終了すると、tpenqueue()は -1を返し、tperrnoを設定してエラー条件を示します。エラーでないときは、メッセージは、tpenqueue()の終了時に正しくキューに登録されます。
異常終了時には、tpenqueue()はtperrnoを次のいずれかの値に設定します。(特に記述した場合を除いては、エラーが呼出し側のトランザクションに影響を及ぼすことはありません)。
TPEINVAL]
TPENOENT]
qspaceを利用できないので、これにアクセスできません(関連するTMQUEUE(5)サーバーは利用できません)。または、グローバル・トランザクション表(GTT)にエントリがないので、グローバル・トランザクションを開始できません。
TPETIME]
TPNOBLOCKまたはTPNOTIMEが指定されている場合は発生しません。 トランザクション・タイムアウトが発生した場合、トランザクションがアボートされない限り、新しいリクエストの送信や未処理の応答の受信はできず、TPETIMEが発生します。その例外とは、ブロックされず、応答を期待せず、かつ呼出し側のトランザクションのかわりに送信されない(つまり、TPNOTRAN、TPNOBLOCKおよびTPNOREPLYを設定してtpacall()を呼び出した場合の)リクエストです。 サービスがトランザクションの内部で失敗した場合、そのトランザクションはTX_ROLLBACK_ONLY状態に置かれます。ほとんどの場合、この状態はタイムアウトと同じものとして扱われます。このトランザクションの以降のATMI呼出しは、TPETIMEで失敗します(前の段落で説明した例外を除きます)。
TPEBLOCK]
TPGOTSIG]
TPEPROTO]
TPESYSTEM]
TPEOS]
TPEDIAGNOSTIC]
QMEINVAL]
QMEBADRMID]
QMENOTOPEN]
QMETRAN]
TPNOTRANフラグを設定して呼び出したときに、メッセージをキューに登録するトランザクションを開始してエラーが発生しました。この診断は、Oracle Tuxedoリリース7.1以降のキュー・マネージャからは返されません。
QMEBADMSGID]
QMESYSTEM]
QMEOS]
QMEABORTED]
QMEPROTO]
QMEBADQUEUE]
QMENOSPACE]
QMENOSPACEが返されます。(1)キュー・スペースに割り当てられたディスク容量(永続的)、(2)キュー・スペースに割り当てられたメモリー容量(非永続的)、(3)同時にアクティブ状態になるトランザクションの最大数(キュー・スペースで許容される数であることが必要です)、(4)キュー・スペースに一度に入れることができる最大メッセージ数、(5)キューイング・サービス・コンポーネントが処理できる並列アクションの最大数、または(6)キューイング・サービス・コンポーネントを同時に使用できる認証されたユーザーの最大数。
QMERELEASE]
QMESHARE]
qmadmin(1)、gp_mktime(3c)、tpacall(3c)、tpalloc(3c)、tpdequeue(3c)、tpinit(3c)、tpsprio(3c)、APPQ_MIB(5)、TMQFORWARD(5)、TMQUEUE(5)
tpenvelope() - 型付きメッセージ・バッファに関連付けられているデジタル署名と暗号化情報へのアクセス
#include <atmi.h>
int tpenvelope(char *data, longlen, intoccurrence, TPKEY *outputkey, long *status, char *timestamp, longflags)
tpenvelope()は、型付きメッセージ・バッファに関連付けられている以下のデジタル署名と暗号化情報へのアクセスを提供します。
送信プロセスがメッセージ・バッファのデジタル署名リクエストを登録する場合は、tpsign()を呼び出して明示的に登録するか、TPKEY_AUTOSIGNフラグを指定したtpkey_open()を呼び出して暗黙的に登録します。
メッセージ・バッファが送信される直前に、各暗号化登録リクエストに対して、公開鍵ソフトウェアがデジタル署名を生成し、メッセージ・バッファにアタッチします。デジタル署名によって、受信プロセスはメッセージの署名者(発信元)を確認することができます。
送信プロセスがメッセージ・バッファの暗号化(封印)リクエストを登録する場合、tpseal()を呼び出して明示的に登録するか、TPKEY_AUTOENCRYPTフラグを指定したtpkey_open()を呼び出して暗黙的に登録します。
公開鍵ソフトウェアは、メッセージ・バッファが送信される直前に、各暗号化登録リクエストに対して、メッセージの内容を暗号化し、暗号化エンベロープをメッセージ・バッファに添付します。暗号化エンベロープにより、受信プロセスはメッセージを復号化することができます。
署名および暗号化の情報は、送信プロセスと受信プロセスのどちらからも利用できます。送信プロセスでは、デジタル署名と暗号化の情報は普通は保留状態にあり、メッセージが送信されるまで待機しています。受信プロセスでは、デジタル署名が確認され、暗号化と復号化も既に行われています。復号化または署名の確認に失敗した場合、メッセージの配信が行われない可能性があります。この場合、受信プロセスはメッセージ・バッファを受け取ることができないため、メッセージ・バッファの情報が伝わりません。
dataは、(1)以前tpalloc()を呼び出すプロセスによって割り当てられたメッセージ・バッファ、または(2)システムによって受信プロセスに渡されたメッセージ・バッファのうち、いずれかの有効な型付きメッセージ・バッファを指している必要があります。メッセージ・バッファが自己記述型の場合、lenは無視されます(0でかまいません)。それ以外の場合、lenにはdata内のデータの長さが含まれている必要があります。
デジタル署名登録リクエスト、デジタル署名、暗号化登録リクエスト、およびメッセージ・バッファに関連付けられている暗号化エンベロープの複数のオカレンスが同時に存在することがあります。これらのオカレンスは順番に格納され、最初の項目が0位置に、以降の項目は0に続く連続する位置に格納されます。occurrence入力パラメータは、リクエストされた項目を示します。occurrenceの値が最後の項目の位置を過ぎると、tpenvelope()はTPENOENTエラー状態で異常終了します。TPENOENTが返されるまで、tpenvelope()を繰り返し呼び出してすべての項目を調べることができます。
デジタル署名登録リクエスト、暗号化登録リクエスト、または暗号化エンベロープに関連付けられたキーのハンドルは、outputkeyを介して戻されます。戻されたキー・ハンドルは、tpkey_open()を呼び出してオープンされた元のキーの個別コピーです。PRINCIPAL属性パラメータなどのキーのプロパティは、tpkey_getinfo()を呼び出して取得します。キー・ハンドルoutputkeyは、呼出し側がtpkey_close()を呼び出して解放します。
| 注意: | outputkeyがNULLの場合、キー・ハンドルは返されません。 |
status出力パラメータは、デジタル署名登録リクエスト、デジタル署名、暗号化登録リクエスト、または暗号化エンベロープの状態を報告します。ステータスの値がNULLでない場合、次のいずれかの状態に設定されます。
TPSIGN_PENDING
TPSIGN_OK
TPSIGN_TAMPERED_MESSAGE
TPSIGN_TAMPERED_CERT
TPSIGN_REVOKED_CERT
TPSIGN_POSTDATED
TPSIGN_EXPIRED_CERT
TPSIGN_EXPIRED
TPSIGN_UNKNOWN
TPSEAL_PENDING
TPSEAL_OK
TPSEAL_TAMPERED_CERT
TPSEAL_REVOKED_CERT
TPSEAL_EXPIRED_CERT
TPSEAL_UNKNOWN
timestamp出力パラメータには、デジタル署名が生成されたマシンのローカル・クロックに従ったタイムスタンプが含まれています。この値の整合性は、関連付けられているデジタル署名によって保護されています。timestampによって示されるメモリー位置は、YYYYMMDDHHMMSS形式のNULLで終了する署名時間です。ここでYYYYは年、MMは月、DDは日、HHは時間、MMは分、SSは秒を表します。timestampはNULLでもかまいませんが、この場合値は返されません。暗号化(封印)にはタイムスタンプは含まれず、timestampによって示されるメモリー位置は変わりません。
TPKEY_REMOVE - occurrenceの位置にある項目が削除されます(バッファとの関連付けがなくなります)。この項目に関連する出力パラメータoutputkey、statusおよびtimestampは、項目が削除される前に取り込まれます。その後の項目は1つずつ繰り下がるため、occurrenceの番号が不連続になることはありません。TPKEY_REMOVEALL - メッセージ・バッファに関連付けられているすべての項目が削除されます。出力パラメータ、outputkey、statusおよびtimestampは戻されません。TPKEY_VERIFY - メッセージ・バッファに関連付けられているすべてのデジタル署名が再確認されます。再確認後に署名のステータスが変わる場合があります。たとえば、受信プロセスによってメッセージ・バッファが修正された場合、発信者の署名のステータスはTPSIGN_OKからTPSIGN_TAMPERED_MESSAGEに変わります。 異常終了すると、この関数は-1を返し、tperrnoを設定してエラー条件を示します。
TPEINVAL]
TPENOENT]
TPESYSTEM]
tpkey_close(3c)、tpkey_getinfo(3c)、tpkey_open(3c)、tpseal(3c)、tpsign(3c)
tperrordetail() - 最後のOracle Tuxedo ATMIシステム呼出しから生じるエラーに関する詳細の取得
#include <atmi.h>
int tperrordetail(long flags)
tperrordetail()は、カレント・スレッドで呼び出された最後のOracle Tuxedo ATMIルーチンにより発生したエラーに関する追加の詳細情報を返します。tperrordetail()は、数値を返します。その数値は、シンボリック名でも表わされます。カレント・スレッドで呼び出された最後のOracle Tuxedo ATMIルーチンによりエラーが発生していない場合、tperrordetail()は、ゼロを返します。したがって、tperrordetail()はエラーが表示された後、つまりtperrnoが設定されたときに呼び出す必要があります。
flagsは将来の使用を考慮して予約されているため、ゼロを指定してください。
マルチスレッドのアプリケーション中のスレッドは、TPINVALIDCONTEXTを含め、どのコンテキスト状態で実行していても、tperrordetail()の呼出しを発行できます。
異常終了すると、tperrordetail()は-1を返し、tperrnoを設定してエラー条件を示します。
設定されるのは、tperrordetail()が返す各数値のシンボリック名および意味です。表示される順序は任意ではなく、優先順位を示すものではありません。
TPED_CLIENTDISCONNECTED
tpnotify()呼出しにTPACKフラグが使用され、tpnotify()のターゲットは現在Joltクライアントに接続していません。tpnotify()が異常終了したときは、中間のATMI呼出しを省略して引き続きtperrordetail()を呼び出すと、TPED_CLIENTDISCONNECTEDが返されます。
TPED_DECRYPTION_FAILURE
TPED_DOMAINUNREACHABLE
tperrordetail()を呼び出すと、TPED_DOMAINUNREACHABLEが返されます。
tpcall()、tpgetrply()、またはtprecv()呼出しが異常終了した場合にtperrnoが返す値を示します。引き続きtperrordetail()を呼び出すと、エラーの詳細としてTPED_DOMAINUNREACHABLE
TPED_DOMAINUNREACHABLE機能は、Oracle Tuxedo Domainsにのみ適用されます。Connect OSI TP DomainsやConnect SNA Domainsなど、他のドメインの製品には適用されません。
TPED_INVALID_CERTIFICATE
TPED_INVALID_SIGNATURE
TPED_INVALIDCONTEXT
tperrnoはTPESYSTEMに設定されます。中間のATMI呼出しを省略して引き続きtperrordetail()を呼び出すと、TPED_INVALIDCONTEXTが返されます。
TPED_INVALID_XA_TRANSACTION
TPED_NOCLIENT
tpnotify()呼出しにTPACKフラグが指定されているのに、tpnotify()のターゲットがありません。tpnotify()が異常終了すると、tperrnoはTPENOENTに設定されます。中間のATMI呼出しを省略して引き続きtperrordetail()呼び出すと、TPED_NOCLIENTが返されます。
TPED_NOUNSOLHANDLER
tpnotify()呼出しにTPACKフラグが指定され、tpnotify()のターゲットがOracle Tuxedo ATMIセッション内にあるのに、ターゲットに非請求の通知ハンドラが設定されていません。tpnotify()が異常終了すると、tperrnoはTPENOENTに設定されます。中間のATMI呼出しを省略して引き続きtperrordetail()を呼び出すと、TPED_NOUNSOLHANDLERが返されます。
TPED_RDMA_MSGQDAEMON
RDMA Msgq_daemonのエラー。RDMAが有効な場合、RDMAデーモン・プロセス(Msgq_daemon)で深刻な問題が検出されると、RDMAを介して送信されたリクエストが異常終了します。tperrnoではTPEOS/TPETIMEが返されます。中間ATMI呼出しを省略して引き続きtperrordetail()を呼び出すとTPED_RDMA_MSGQDAEMONが返されます。
TPED_RDMA_INVALIDQUEUE
Msgq_daemon共有メモリーによって内部エラーが発生することがあります。リクエストが異常終了した後で、tperrnoではTPEOSが返されます。中間ATMI呼出しを省略して引き続きtperrordetail()を呼び出すとTPED_RDMA_INVALIDQUEUEが返されます。この異常終了を検出できる呼出しは、「TPED_RDMA_MSGQDAEMON」を参照してください。
TPED_RDMA_NOMEMORY
Msgq_daemonが開始すると、内部エラーが発生することがあります。tperrnoによってTPEOSが返されます。中間のATMI呼出しを省略して引き続きtperrordetail()を呼び出すと、TPED_RDMA_NOMEMORYが返されます。この異常終了を検出できる呼出しは、「TPED_RDMA_MSGQDAEMON」を参照してください。
TPED_SVCTIMEOUT
UBBCONFIG中のSVCTIMEOUT値によって制御されます。T_SERVERおよびT_SERVICEクラスのTA_SVCTIMEOUTはTM_MIB(5)に記載されています。このエラーよって呼出しが異常終了したときは、中間のATMI呼出しを省略して引き続きtperrordetail()を呼び出すと、TPED_SVCTIMEOUTが返されます。
TPED_TERM
tperrordetail()を呼び出すと、TPED_TERMが返されます。
異常終了時には、tperrordetail()はtperrnoを次のいずれかの値に設定します。
TPEINVAL
「C言語アプリケーション・トランザクション・モニター・インタフェースについて」、tpstrerrordetail(3c)、tperrno(5)
tpexport() - 型付きメッセージ・バッファを、デジタル署名と暗号化エンベロープを含むエクスポート可能なマシン独立型の文字列表現に変換
#include <atmi.h>
int tpexport(char *ibuf, longilen, char *ostr, long *olen,
longflags)
tpexport()は、型付きメッセージ・バッファを外部化された表現に変換します。外部化された表現とは、通常は伝送直前にメッセージ・バッファに追加されるOracle Tuxedo ATMIヘッダー情報を含まないメッセージ・バッファです。
外部化された表現は、任意の通信メカニズムを介して、プロセス、マシン、Oracle Tuxedo ATMIアプリケーション間で伝送することができます。恒久的なストレージにアーカイブでき、システムの停止および再起動後も有効です。
ibufは、(1)以前tpalloc()を呼び出すプロセスによって割り当てられたメッセージ・バッファ、または(2)システムによって受信プロセスに渡されたメッセージ・バッファのうち、いずれかの有効な型付きメッセージ・バッファを指している必要があります。ilenは、エクスポートするibufの容量を指定します。ただし、ibufが長さの指定を必要としないタイプのバッファを指す場合(たとえば、FMLフィールド化バッファ)、ilenは無視されます(0を指定できます)。
ostrは、バッファの内容と関連プロパティの外部化された表現を保持する出力領域を指します。flagsにTPEX_STRINGが設定されている場合、外部化の形式は文字列型になります。それ以外の場合、出力する長さは*olenによって指定され、NULLバイトを埋め込むことができます。
入力時には、*olenはostrで使用できる最大記憶サイズを指定します。出力時には、*olenはostrに書き込まれる実際のバイト数に設定されます。flagsにTPEX_STRINGが設定されている場合は、終端のNULL文字を含みます。
出力バッファに文字列形式(base 64エンコード)が要求される場合、flags引数はTPEX_STRINGに設定します。それ以外の場合、出力はバイナリになります。
異常終了すると、この関数は -1を返し、tperrnoを設定してエラー条件を示します。
TPEINVAL]
TPEPERM]
TPESYSTEM]
TPELIMIT]
tpfml32toxml() - FML32バッファをXMLデータに変換
#include <fml32.h>
int tpfml32toxml (FBFR32 *fml32bufp, char *vfile, char *rtag, char **xmlbufp, long flags)
この関数は、FML32バッファをXMLデータに変換するために使用します。以下の引数を使用できます。
fml32bufp
vfile
rtag
Type属性で、XMLルート・タグとして使用するために識別および保存されます。入力ルート名を指定していない場合は、デフォルトの出力XMLルート・タグ<FML32>が使用されます。
xmlbufp
flag
成功した場合、tpfml32toxml()は0を返します。この関数は、エラー発生時に-1を返し、tperrnoを設定してエラー条件を示します。
失敗すると、tpfml32toxml()はtperrnoを次のいずれかの値に設定します。
TPEINVAL]
TPESYSTEM]
userlog(3)に書き込まれます。これは、XMLへの変換を実行できなかった時期も示します。そのインスタンスでは、エラーの詳細な情報がuserlogに追加されます。
TPEOS]
tpxmltofml32(3c)、tpxmltofml(3c)、tpfmltoxml(3c)
tpfmltoxml() - FMLバッファをXMLデータに変換
#include <fml.h>
int tpfmltoxml (FBFR *fmlbufp, char *vfile, char *rtag, char **xmlbufp, long flags)
この関数は、FMLバッファをXMLデータに変換するために使用します。以下の引数を使用できます。
fmlbufp
Type属性で、XMLルート・タグとして使用するために識別および保存されます。入力ルート名を指定していない場合は、デフォルトの出力XMLルート・タグ<FML>が使用されます。
xmlbufp
flag
成功した場合、tpfmltoxml()は0を返します。この関数は、エラー発生時に-1を返し、tperrnoを設定してエラー条件を示します。
異常終了時には、tpfmltoxml()はtperrnoを次のいずれかの値に設定します。
TPEINVAL]
TPESYSTEM]
userlog(3)に書き込まれます。これは、XMLへの変換を実行できなかった時期も示します。そのインスタンスでは、エラーの詳細な情報がuserlogに追加されます。
[TPEOS]
tpxmltofml32(3c)、tpfml32toxml(3c)、tpxmltofml(3c)
tpforward() - サービス・リクエストを他のサービス・ルーチンに転送するルーチン
#include <atmi.h>
void tpforward(char *svc, char *data, long len, long flags)
tpforward()を使用すると、サービス・ルーチンはクライアントのリクエストを別のサービス・ルーチンに転送して処理させることができます。tpforward()はtpreturn()と同様、サービス・ルーチンの中で最後に呼び出されます。tpreturn()のように、tpforward()は、Oracle Tuxedo ATMIシステムのディスパッチャに制御を正常に返すことを保証するために、ディスパッチされるサービス・ルーチン内から呼び出されます。tpforward()は会話型サービス内から呼び出すことはできません。
この関数は、dataが指すデータを使用してsvcによって指定されるサービスにリクエストを転送します。サービス名の先頭に"."を付けてはいけません。リクエストを転送するサービス・ルーチンは応答を受け取りません。リクエストの転送が終わると、サービス・ルーチンは、通信マネージャ・ディスパッチャに戻り、他の作業を行える状態になります。なお、転送されたリクエストからの応答は期待しないため、このリクエストは、そのリクエストを転送するサービスと同じ実行形式内の任意のサービス・ルーチンに、エラーなして転送することができます。
サービス・ルーチンがトランザクション・モードであると、tpforward()はトランザクションの呼出し側の部分を、そのトランザクションの開始プロセスがtpcommit()またはtpabort()のいずれかを発行したときに完了できるような状態にします。トランザクションがサービス・ルーチンの実行中にtpbegin()により明示的に開始された場合、このトランザクションをtpcommit()またはtpabort()で終了させてから、tpforward()を呼び出す必要があります。このため、転送チェーンに関与するすべてのサービスは、トランザクション・モードで起動するか、あるいはいずれもトランザクション・モードでは起動しないようにします。
転送チェーンの最後のサーバーは、tpreturn()を使用してリクエストの発信元に応答を返します。要約して言えば、tpforward()は待機しているリクエスタに応答を返す役割を別のサーバーに転送するわけです。
tpforward()は、サービス・ルーチンが出したサービス・リクエストから期待されるすべての応答を受け取った後、呼び出すようにします。受信されていない未終了の応答は、受信後、通信マネージャ・ディスパッチャによって自動的に取り除かれます。さらに、以後、これらの応答の記述子は無効になり、リクエストはsvcに転送されません。
dataは送信される応答のデータ部を指すポインタです。dataがNULLでなければ、以前にtpalloc()の呼出しによって得られたバッファを指していなければなりません。このバッファが、サービス・ルーチン起動時にサービス・ルーチンに渡されたバッファと同じバッファである場合、そのバッファの配置は、Oracle Tuxedo ATMIシステムのディスパッチャに一任されます。したがって、サービス・ルーチンをコーディングする人は、バッファが解放されているかどうかを気にする必要はありません。実際、ユーザーがこのバッファを解放しようとしてもできません。しかし、tpforward()に渡されるバッファが、サービスが起動したものに等しいものでない場合は、tpforward()はそのバッファを解放します。lenには送信するデータ・バッファの大きさを指定します。dataが長さの指定を必要としないバッファを指すポインタである場合(FMLフィールド化バッファなど)、lenは0でもかまいません。dataがNULLの場合、lenは無視され、長さ0のデータのリクエストが送信されます。
引数flagsは使用されません。この引数は将来の用途のために予約されており、必ず0に設定します。
サービス・ルーチンは、呼出し側である通信マネージャ・ディスパッチャには何も返しません。したがって、tpforward()はvoidで定義されています。詳細は、「tpreturn(3c)」を参照してください。
関数に渡すパラメータの処理あるいはその関数のいずれかでなんらかのエラーが発生した場合は、(応答が送信されないかぎり)失敗メッセージが元のリクエスタに戻されます。未終了の応答または従属接続がある場合、または呼出し側のトランザクションが中断のみとしてマークされた場合、これらは失敗メッセージの原因となる障害であるとみなされます。
UBBCONFIGファイル中のSVCTIMEOUTか、TM_MIB中のTA_SVCTIMEOUTが0でない場合にサービスのタイムアウトが発生すると、TPEV_SVCERRが返されます。
リクエスタは、エラーを示すTPESVCERRエラーによって、失敗メッセージを検出します。このようなエラーが発生した場合、呼出し側のデータは送信されません。また、このエラーが原因で、呼出し側の現在のトランザクションが中断のみとしてマークされます。
サービス・ルーチンの処理中あるいはリクエストの転送中にトランザクション・タイムアウトになると、tpcall()またはtpgetrply()で応答を待つリクエスタはTPETIMEエラーを受け取ります。サービスがトランザクション内部で失敗すると、そのトランザクションはタイムアウトになり、TX_ROLLBACK_ONLY状態になります。また、そのトランザクションの後続のATMI呼出しは、すべてTPETIMEで失敗します。待ち状態にあるリクエスタは、どのようなデータも受信しません。しかし、サービス・ルーチンはtpreturn()またはtpforward()を使用して終了させるようになっています。会話型サービス・ルーチンの場合、tpreturn()を使用しなければならず、tpforward()を使用することはできません。
サービス・ルーチンが、tpreturn()またはtpforward()のいずれも使用せずに戻る場合、(つまり、サービス・ルーチンがC言語のreturn文を使用するか、または単に関数の終わりで終了する場合)、あるいはtpforward()が会話型サーバーから呼び出される場合、サーバーは、ログ・ファイルに警告メッセージを出力し、サービス・エラーを元のリクエスタに戻します。また、従属接続に対するオープン接続はすべて、ただちに切断され、未終了の非同期応答は無効とマークされます。サーバーが異常終了時にトランザクション・モードにあった場合は、そのトランザクションは中断のみとしてマークされます。tpreturn()またはtpforward()がサービス・ルーチンの外部から使用される場合(たとえば、クライアント、またはtpsvrinit()あるいはtpsvrdone()で)、これらのルーチンは単に終了するだけです。
tpforwardを呼び出すサービス・セッション・ロールを構成する場合は、表11を参照してください。
詳細は、 「Oracle Tuxedo ATMIのアーキテクチャ」の「クライアント/サーバー・アフィニティとは」を参照してください。
tpalloc(3c)、tpconnect(3c)、tpreturn(3c)、tpservice(3c)、tpstrerrordetail(3c)
#include <atmi.h>
void tpfree(char *ptr)
tpfree()の引数は、以前にtpalloc()またはtprealloc()によって得られたバッファを指すポインタです。ptrがNULLの場合は、動作は行われません。ptrが型付きバッファを指していない場合(または、その前にtpfree()を使用して解放した領域を指している場合)、不定の結果が発生します。サービス・ルーチン内では、ptrがサービス・ルーチンに渡されたバッファを指している場合、tpfree()は単に終了し、そのバッファを解放しません。
ある種のバッファ・タイプは、バッファの解放処理の一環として、状態情報あるいは関連するデータを削除する必要があります。tpfree()は、バッファを解放する前にこうした関連情報を(通信マネージャ固有の方法に従って)削除します。
tpfree()が終了した後は、ptrをOracle Tuxedo ATMIシステムのルーチンの引数として使用したり、その他の方法で使用したりしないようにしてください。
マルチスレッドのアプリケーション中のスレッドは、TPINVALIDCONTEXTを含め、どのコンテキスト状態で実行していても、tpfree()の呼出しを発行できます。
tpfree()を使用してFML32バッファを解放するとき、ルーチンは埋め込まれたバッファをすべて再帰的に解放して、メモリー・リークの発生を防ぎます。埋め込まれたバッファが解放されないようにするには、対応するポインタにNULLを指定してからtpfree()コマンドを発行します。上記で説明したように、ptrがNULLの場合アクションは発生しません。
tpfree()は、呼出し側に値を返しません。したがって、この関数は、voidで宣言されています。
この関数を、Cライブラリのmalloc()、realloc()、またはfree()と組み合せて使用するのは避けてください(tpalloc()で割り当てたバッファを、free()を使用して解放しないでください)。
「C言語アプリケーション・トランザクション・モニター・インタフェースについて」、tpalloc(3c)、tprealloc(3c)
tpgblktime() - 以前に設定された、1秒当たりのブロック時間値を取得します。
#include <atmi.h>
inttpgblktime(TPBLK_NEXT,TPBLK_ALLlong flags)
tpgblktime()は、以前に設定された1秒あたりのブロック時間値を取得します。tpgblktime()にブロック時間フラグ値を指定した場合、それに一致するflag値が設定されていないと、戻り値0が返されます。ブロック時間フラグ値として0未満の値を指定すると、エラーが発生します。
TPBLK_NEXT
TPBLK_ALL
0
TPBLK_NEXTを指定した前のtpsblktime()呼出しがあるために設定された次のブロックATMIセットの適用可能なブロック時間値、またはTPBLK_ALLフラグのブロック時間値(システム全体のデフォルト・ブロック時間値)を返します。
| 注意: | ワークステーション・クライアントがtpgblktime() 0を呼び出した場合は、システム全体のデフォルト・ブロック時間値を返すことはできません。この場合は、値0が返されます。 |
成功すると、tpgblktime()は、対応するフラグ値で現在有効なブロッキング時間値を示す正数を戻します。戻り値0は、オーバーライドが有効なブロッキング時間値が現在ないことを示します。
この関数は、エラー発生時に -1を返し、tperrnoを設定してエラー条件を示します。エラーが既存のトランザクションに影響を及ぼすことはありません。
異常終了時には、tpgblktime()はtperrnoを次のいずれかの値に設定します。
TPEINVAL]
TPESYSTEM]
tpcall(3c)、tpcommit(3c)、tprecv(3c)、tpsblktime(3c)、UBBCONFIG(5)
tpgetadmkey() - 管理用認証キーを取得するルーチン
#include <atmi.h>
long tpgetadmkey(TPINIT *tpinfo)
tpgetadmkey()は、アプリケーションに特定の認証サーバーによって利用されます。このルーチンは、管理認証の目的のために指定ユーザーにふさわしいアプリケーション・セキュリティ・キーを返します。このルーチンは、tpsysadm()あるいはtpsysop()のクライアント名(つまりtpinfocltname)を指定して呼び出す必要があります。そうでなければ、有効な管理キーは返されません。
マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドはtpgetadmkey()の呼出しを発行できません。
tpgetadmkey()は、正常終了時には最上位ビットが設定(0x80000000)された0以外の値を戻し、異常終了時には0を戻します。tpinfoがNULLで、tpinfocltnameがtpsysadm()またはtpsysop()でないか、あるいはユーザーIDが構成されたアプリケーション管理者でない場合は、0が戻されます。
0が返されることで、有効な管理キーが割り当てられなかったことが分かります。
このインタフェースは、Oracle Tuxedoリリース5.0またはそれ以降が稼働するUNIX Systemのサイトでしか利用できません。
tpaddusr(1)、tpusradd(1)、tpinit(3c)、AUTHSVR(5)
tpgetctxt() - 現在のアプリケーションの関連付けのコンテキスト識別子を取得します。
#include <atmi.h>
int tpgetctxt(TPCONTEXT_T *context, longflags)
tpgetctxt()は、現在のアプリケーション・コンテキストを表す識別子を取り出し、contextに入れます。この関数は、マルチスレッド環境ではスレッド単位で、非スレッド環境ではプロセス単位で動作します。
2番目の引数flagsは現在使用されていないので、0に設定します。
tpgetctxt()は、マルチコンテキストのアプリケーションだけでなく、シングル・コンテキストのアプリケーションでも呼び出すことができます。
マルチスレッドのアプリケーションのスレッドは、TPINVALIDCONTEXTを含め、どのコンテキスト状態で実行していてもtpgetctxt()の呼出しを発行できます。
正常終了時には、tpgetctxt()は負数でない値を返します。コンテキストは、以下のいずれかの形式で表される現在のコンテキストIDに設定されます。
TPSINGLECONTEXT。カレント・スレッドがTPMULTICONTEXTSフラグの指定されていないtpinit()を正常に実行したこと、またはTPMULTICONTEXTSフラグが指定されていないtpinit()を正常に実行したプロセス内でカレント・スレッドが作成されたことを示します。TPSINGLECONTEXTの値は0です。TPNULLCONTEXT。カレント・スレッドがコンテキストに関連付けられていないことを示します。 TPINVALIDCONTEXT。カレント・スレッドのコンテキスト状態が無効であることを示します。同じコンテキスト内で別のスレッドが作業している間に、マルチコンテキスト・クライアントのスレッドがtpterm()を呼び出すと、作業中のスレッドはTPINVALIDCONTEXTコンテキストになります。TPINVALIDCONTEXTの値は -1です。 TPINVALIDCONTEXT状態のスレッドは、ほとんどのATMI関数に対する呼出しを発行できません。呼び出せる関数、または呼び出せない関数のリストについては、「C言語アプリケーション・トランザクション・モニター・インタフェースについて」を参照してください。
TPINVALIDCONTEXTコンテキスト状態の詳細は、「tpterm(3c)」を参照してください。
異常終了すると、tpgetctxt()は -1を返し、tperrnoを設定してエラー条件を示します。
異常終了時には、tpgetctxt()はtperrnoを次のいずれかの値に設定します。
TPEINVAL]
TPESYSTEM]
TPEOS]
「C言語アプリケーション・トランザクション・モニター・インタフェースについて」、tpsetctxt(3c)、tpterm(3c)
tpgetlev() - トランザクション・モードかどうかチェックするルーチン
#include <atmi.h>
int tpgetlev()
tpgetlev()は現在のトランザクション・レベルを呼出し側に返します。現時点では、定義されているレベルは0と1だけです。
マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドは、tpgetlev()の呼出しを発行できません。
正常終了時tpgetlev()は、トランザクション・モードではないということを示す0、またはトランザクション・モードだということを示す1のどちらかを返します。
異常終了すると、tpgetlev()は -1を返し、tperrnoを設定してエラー条件を示します。
異常終了時には、tpgetlev()はtperrnoを次のいずれかの値に設定します。
TPEPROTO]
TPESYSTEM]
TPEOS]
Oracle Tuxedo ATMIシステムのトランザクションを記述するためにtpbegin()、tpcommit()、およびtpabort()を使用する場合、XAインタフェースに準拠した(呼出し側に妥当にリンクされている)リソース・マネージャが行う作業のみがトランザクションのプロパティを備えていることを記憶しておくことが重要です。トランザクションにおいて実行される他のすべての操作は、tpcommit()あるいはtpabort()のいずれにも影響されません。そのリソース・マネージャが行った処理がOracle Tuxedo ATMIシステムのトランザクションの一部となるよう、XAインタフェースを満たすリソース・マネージャをサーバーにリンクする方法については、「buildserver(1)」を参照してください。
tpabort(3c)、tpbegin(3c)、tpcommit(3c)、tpscmt(3c)
tpgetmbenc() - 型付きバッファからコード・セットのエンコード名を取得
#include <atmi.h>
extern int tperrno;
int
tpgetmbenc (char *bufp, char *enc_name, long flags)
この関数は、型付きバッファで送信されたコードセットのエンコード名を取得するために使用します。この名前は、変換が必要な場合にターゲットのコードセットと比較することができます(「tpconvmb(3c)」を参照)。
引数bufpは、型付きバッファのメッセージを指す有効なポインタです。
この関数が正常に実行されると、enc_name引数がbufpに指定されているエンコーディング名に設定されます。戻される文字列はNULLで終わります。ユーザーは、エンコーディング名とNULL終了文字を足した長さを保持するのに十分な大きさのバッファを割り当てるよう注意する必要があります(「<limits.h>」の「NL_LANGMAX」を参照してください)。エンコーディング名が設定されていないMBSTRING型付きバッファは無効です。
正常終了の場合、tpgetmbenc()は値0を返します。エラーの場合には-1を返し、次に説明するように各関数にtperrnoを設定します。この関数は、次の原因により異常終了する可能性があります。
TPEINVAL]
TPEPROTO]
TPESYSTEM]
tpalloc(3c)、tpconvmb(3c)、tpsetmbenc(3c)
tpgetrepos() - Tuxedoサービス・メタデータ・リポジトリ・ファイルからのサービス・パラメータ情報の取得
#include <atmi.h>
int tpgetrepos(char *reposfile, FBFR32* idata, FBFR32** odata)
tpgetrepos()は、TMMETADATA(5)によって提供される.TMMETAREPOSサービスに、代替リポジトリ・アクセス・インタフェースを提供します。これは、Tuxedoサービス・メタデータ・リポジトリ・ファイルからサービス・パラメータを取得します。tpgetrepos()を使用するには、メタデータ・リポジトリ・ファイルが、リクエスト元のネイティブ・クライアントまたはサーバーに存在している必要があります。このファイルにより、TMMETADATA(5)を開始していない場合でも、リポジトリ情報へのアクセスが可能になります。
| 注意: | tpgetrepos()は、Joltリポジトリ・ファイルの表示にも使用できます。既存のJoltリポジトリ・ファイルを変更したり、新しいJoltリポジトリ・ファイルを作成したりすることはできません。 |
tpgetrepos()では、以下のパラメータを使用できます。
reposfile
idata
odata
「METAREPOS(5)」では、tpgetrepos()が使用するFML32バッファ形式について説明します。これは、Tuxedo MIBで使用する形式と同じです。
tpgetrepos()は、成功した場合に0を返します。異常終了した場合は、tperrnoを設定し、-1を返します。ほとんどの異常終了では、Tuxedo MIBの場合と同様に、*odataのTA_ERRORフィールドに特定のエラーに関する情報が格納されています。
異常終了時には、tpgetrepos()はtperrnoを次のいずれかの値に設定します。
| 注意: | TPEINVALの場合を除き、odataは、エラー条件についてさらに詳しい情報が得られるように、サービス・エントリごとにTA_ERROR、TA_STATUSを含める形で変更されます。 |
[TPEINVAL]
[TPEMIB]
[TPEPROTO]
[TPEOS]
[TPESYSTEM]
このインタフェースは、Oracle Tuxedoリリース9.0またはそれ以降でしか利用できません。
${TUXDIR}/lib/libtrep.a
${TUXDIR}/lib/libtrep.so.<rel>
${TUXDIR}/lib/libtrep.lib
buildclientを使用する場合は、ライブラリを手動でリンクする必要があります。この場合、-L${TUXDIR}/lib -ltrepを指定します。
tpsetrepos(3c)、tmloadrepos(1)、tmunloadrepos(1)、TMMETADATA(5)、『Oracle Tuxedoアプリケーションの設定』の「Tuxedoサービス・メタデータ・リポジトリの管理」
tpgetrply() - 以前のリクエストに対する応答を受信するためのルーチン
#include <atmi.h>
int tpgetrply(int *cd, char **data, long *len, long flags)
tpgetrply()は、以前に送信されたリクエストに対する応答を戻します。この関数の最初の引数cdは、tpacall()が戻す呼出し記述子を指します。デフォルトでは、この関数は、*cdと一致する応答が届くか、タイムアウトが発生するまで待機します。
dataは、以前にtpalloc()で割り当てたバッファを指すポインタのアドレスでなければならず、lenはtpgetrply()が正常に受信したデータ量を設定するlong型の値を指すようにしてください。正常終了時には、*dataは、その応答を収めたバッファを指し、*lenには、そのデータのサイズが入ります。FMLとFML32バッファは、通常最小サイズ4096バイトを確保します。応答が4096バイトより大きい場合には、バッファ・サイズは返されるデータを入れるのに十分な大きさに拡大します。リリース6.4では、バッファに対するデフォルトの割当ては1024バイトです。また、最近使用したバッファの履歴情報が保持され、最適サイズのバッファをリターン・バッファとして再利用できます。
容量まで満たされていないかもしれない送信者側のバッファ(たとえば、FMLまたはFML32バッファ)は、送信に使用されたサイズになります。システムは、受信データのサイズを任意の量で拡大します。これは、受信者が送信者の割り当てたバッファ・サイズより小さく、送信されたデータのサイズより大きいバッファを受け取ることを意味します。
受信バッファのサイズは、増加することも減少することもあります。また、アドレスもシステムがバッファを内部で交換するごとに常に変更されます。応答バッファのサイズが変わったどうか(また変わったとしたらどれくらい変わったのか)を決定するには、tpgetrply()が*lenとともに発行される前に、合計サイズを比べてください。バッファ管理の詳細については、「C言語アプリケーション・トランザクション・モニター・インタフェースについて」を参照してください。
返されたときに*lenが0の場合は、応答にはデータ部分がなく、*dataやそれが指示するバッファは変更されていません。
マルチスレッド・プログラムの各コンテキストでは、次のことが当てはまります。
これらの制限のどちらかに違反するtpgetrply()呼出しを発行した場合は、-1が返され、tperrnoはTPEPROTOに設定されます。
TPGETANY
tpgetrply()が、cdによって示される記述子を無視し、存在する応答があればそれらを返し、返された応答の呼出し記述子を指すようcdを設定します。応答が存在しなければ、tpgetrply()は1つの応答が届くまで待機します(デフォルトの設定の場合)。
TPNOCHANGE
dataが指すバッファとは異なるタイプのバッファが受信されると、受信側が着信バッファのタイプを識別するかぎり、*dataのバッファ・タイプは、受信されたバッファのタイプに変更されます。このフラグが設定されていると、*dataが指すバッファのタイプは変更されません。つまり、受信されたバッファのタイプとサブタイプは、*dataが指すバッファのタイプとサブタイプと一致する必要があります。
TPNOBLOCK
tpgetrply()は、応答が送られてくるまで待機しません。応答がキューから取り出せる状態であれば、tpgetrply()はその応答を取り込み、終了します。このフラグの指定がなく、応答もキューから取り出せる状態にない場合、呼出し側は、応答が到着するまであるいはタイムアウト(トランザクション・タイムアウトまたはブロッキング・タイムアウト)が発生するまでブロックされます。
TPNOTIME
TPSIGRSTRT
後に示す場合以外は、*cdはその応答を受信した後は有効でなくなります。
マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドはtpgetrply()の呼出しを発行できません。
tpgetrply()が正常に終了した場合、あるいはtperrnoがTPESVCFAILに設定されて終了した場合、tpurcode()には、tpreturn()の一部として送信されたアプリケーションが定義した値が入ります。
異常終了すると、tpgetrply()は -1を返し、tperrnoを設定してエラー条件を示します。
異常終了時には、tpgetrply()がtperrnoに対して行う設定は、次のようになります。TPGETANYが設定されていない場合は、特に明記されていないかぎり、*cdは無効になります。TPGETANYが設定されている場合は、cdは異常が発生した応答の記述子を指します。応答が取り出せるようになる前にエラーが発生した場合には、cdは0を指します。また、特に明記しないかぎり、異常終了は呼出し側のトランザクションが存在していても、それには影響しません。呼出しが異常終了してtperrnoに特定の値が設定されたときは、中間のATMI呼出しを省略して引き続きtperrordetail()を呼び出すと、エラーに関する詳細な情報が提供されます。詳細は、「tperrordetail(3c)」リファレンス・ページを参照してください。
TPEINVAL]
cd、data、*dataまたはlenがNULL、あるいはflagsが無効など)。cdがNULLでない場合、エラーが発生した後もこの値は有効で、応答は未終了のまま残されます。
TPEOTYPE]
TPNOCHANGEがflagsに設定されていて、*dataのタイプとサブタイプがそのサービスから送られた応答のタイプおよびサブタイプと一致しません。*dataの内容も*lenも変更されていません。呼出し側の現在のトランザクションのために応答が受信された場合は、応答が破棄されるので、そのトランザクションは中断のみとしてマークされます。
TPEBADDESC]
TPETIME]
TPNOBLOCKまたはTPNOTIMEが指定されている場合は発生しません。いずれのケースでも、*data、その内容、*lenはどれも変更されません。 *cdは、呼出し側がトランザクション・モードでなければ(そして、TPGETANYが設定されていない場合)そのまま有効です。 トランザクション・タイムアウトが発生した場合、トランザクションがアボートされない限り、新しいリクエストの送信や未処理の応答の受信はできず、TPETIMEが発生します。その例外とは、ブロックされず、応答を期待せず、かつ呼出し側のトランザクションの代わりに送信されない(つまり、TPNOTRAN、TPNOBLOCKおよびTPNOREPLYを設定してtpacall()を呼び出した場合の)リクエストです。 サービスがトランザクション内部で失敗すると、そのトランザクションはTX_ROLLBACK_ONLY状態になります。ほとんどの場合、この状態はタイムアウトと同じものとして扱われます。このトランザクションの以降のATMI呼出しは、TPETIMEで異常終了します(前の段落で説明した例外を除く)。
TPESVCFAIL]
TPFAILでtpreturn()を呼び出しました。これは、アプリケーション・レベルの障害です。サービスの応答の内容は(送信された場合)は、*dataが指すバッファに入ります。呼出し側のトランザクションのかわりにサービス・リクエストが発行された場合、トランザクションは中断のみとしてマークされます。トランザクションがタイムアウトしたかどうかに関わりなく、トランザクションが中断される前の通信で有効であるのは、TPNOREPLY、TPNOTRANおよびTPNOBLOCKを設定したtpacall()の呼出しのみです。
TPESVCERR]
tpreturn()またはtpforward()でエラーを検出しました(たとえば、誤った引数が渡された場合など)。このエラーが発生すると、応答データは戻されません(つまり、data、その内容、および*lenはいずれも変更されません)。呼出し側のトランザクションのかわりにサービス・リクエストが発行された場合、トランザクションは中断のみとしてマークされます。トランザクションがタイムアウトしたかどうかに関わりなく、トランザクションが中断される前の通信で有効であるのは、TPNOREPLY、TPNOTRANおよびTPNOBLOCKを設定したtpacall()の呼出しのみです。UBBCONFIGファイル内のSVCTIMEOUTまたはTM_MIB内のTA_SVCTIMEOUTが0でない場合にサービスのタイムアウトが発生すると、TPESVCERRが戻されます。
TPEBLOCK]
TPGOTSIG]
TPEPROTO]
TPESYSTEM]
TPEOS]
tpacall(3c)、tpalloc(3c)、tpcancel(3c)、tperrordetail(3c)、tprealloc(3c)、tpreturn(3c)、tpstrerrordetail(3c)、tptypes(3c)
tpgprio() - サービス・リクエストの優先度を受け取るルーチン
#include <atmi.h>
int tpgprio(void)
tpgprio()は、カレント・スレッドがカレント・コンテキストで最後に送信または受信したリクエストの優先度を返します。優先度の範囲は1から100までです。最高優先度は100です。tpgprio()はtpcall()またはtpacall() (キュー管理機能がインストールされている場合には、tpenqueue()またはtpdequeue())の後に呼び出すことができ、返される優先度は送信されたリクエストのものです。また、tpgprio()はサービス・ルーチン内から呼び出して、呼び出されたサービスがどの優先度で送られたかを明らかにします。tpgprio()は何回でも呼び出すことができ、次のリクエストが送られるまでは同じ値を返します。
マルチスレッドのアプリケーションでは、tpgprio()はスレッド単位で動作します。
会話プリミティブは優先度とは関連付けられていないので、tpsend()やtprecv()を出しても、tpgprio()が返す優先度には影響しません。また、会話型サービス・ルーチンの場合も、tpcall()やtpacall()がそのサービス内から出されないかぎり、優先度は関連付けられません。
マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドはtpgprio()の呼出しを発行できません。
正常終了時には、tpgprio()はリクエストの優先度を戻します。
異常終了すると、tpgprio()は -1を返し、tperrnoを設定してエラー条件を示します。
異常終了時には、tpgprio()はtperrnoを次のいずれかの値に設定します。
TPENOENT]
TPEPROTO]
TPESYSTEM]
TPEOS]
tpacall(3c)、tpcall(3c)、tpdequeue(3c)、tpenqueue(3c)、tpservice(3c)、tpsprio(3c)
tpimport() - メッセージ・バッファの外部化された表現を型付きメッセージ・バッファに変換
#include <atmi.h>
int tpimport(char *istr, longilen, char **obuf, long *olen,
longflags)
tpimport()は、メッセージ・バッファの外部化された表現を、型付きメッセージ・バッファに変換します。外部化された表現とは、通常は伝送直前にメッセージ・バッファに追加されるOracle Tuxedo ATMIヘッダー情報を含まないメッセージ・バッファです。プロセスによってtpexport()関数が呼び出され、型付きメッセージ・バッファが外部化された表現に変換されます。
istrに関連付けられているデジタル署名は、バッファがインポートされるときに確認されますが、インポート後もtpenvelope()を介して確認できます。
istrバッファ表現が暗号化されている場合、インポート・プロセスは復号化に有効な秘密鍵にアクセスできる必要があります。復号化はインポート・プロセス中に自動的に実行されます。
flagsにTPEX_STRINGが設定されていない場合、istrに含まれるバイナリ・データの長さはilenに含まれます。ilenが0の場合は、istrはNULL終了文字列を指していると推定され、TPEX_STRINGフラグが指定されているものと考えられます。
*obufは、(1)以前tpalloc()を呼び出すプロセスによって割り当てられたメッセージ・バッファ、または(2)システムによって受信プロセスに渡されたメッセージ・バッファのうち、いずれかの有効な型付きメッセージ・バッファを指している必要があります。バッファは結果に応じて再度割り当てられ、バッファのタイプまたはサブタイプは変更される場合があります。
*olenは、出力バッファに含まれる有効なデータの量に設定されます。olenが入力時にNULLの場合は、無視されます。
入力する外部化表現が文字列形式(base 64エンコード)の場合は、flags引数はTPEX_STRINGに設定されています。それ以外の場合、入力はilenの長さのバイナリ形式です。
異常終了すると、この関数は -1を返し、tperrnoを設定してエラー条件を示します。
TPEINVAL]
TPEPERM]
TPEPROTO]
TPESYSTEM]
#include <atmi.h>
int tpinit(TPINIT *tpinfo) tpinit()は、クライアントがOracle Tuxedo ATMIシステムのアプリケーションに参加するときに使用します。Oracle Tuxedo ATMIシステムのコミュニケーションあるいはトランザクション・ルーチンをクライアントが使用する前には、あらかじめクライアントはOracle Tuxedo ATMIシステムのアプリケーションに参加しなければなりません。
tpinit()には、シングル・コンテキスト・モードとマルチコンテキスト・モードの2つの動作モードがあります。これについては、後で詳しく説明します。シングル・コンテキスト・モードではtpinit()の呼出しはオプションのため、シングル・コンテキストのクライアントは、tpinfoをNULLに設定してtpinit()を透過的に呼び出す多くのATMIルーチン(たとえば、tpcall())を呼び出すことによって、アプリケーションに参加することもできます。クライアントは、tpinit()を直接呼び出して、後に示すパラメータを設定する必要がある場合があります。また、マルチコンテキスト・モードが必要な場合、アプリケーションの認証が必要な場合(「UBBCONFIG(5)」のSECURITYキーワードの説明を参照)、またはアプリケーションが独自のバッファ・タイプ・スイッチを提供する場合(「typesw(5)」を参照)は、tpinit()を使用しなければなりません。tpinit()が正常に終了した場合は、クライアントはサービス・リクエストを開始し、トランザクションを定義できます。
シングル・コンテキスト・モードでは、tpinit()を2回以上呼び出す場合(つまり、クライアントがすでにアプリケーションに参加した後に呼び出す場合)は、何もアクションは実行されず、成功を示す戻り値が返されます。
マルチスレッド・クライアントの場合、TPINVALIDCONTEXT状態のスレッドはtpinit()の呼出しを発行できません。Oracle Tuxedo ATMIアプリケーションに参加するには、マルチスレッドのワークステーション・クライアントは、たとえシングル・コンテキスト・モードで動作している場合でも、必ずTPMULTICONTEXTSフラグを設定してtpinit()関数を呼び出さなければなりません。
| 注意: | TMNOTHREADS環境変数をyesに設定しても、tpinitのTPMULTICONTEXTSモードは正しく機能します。この環境変数をyesに設定すると、スレッドを使用しないアプリケーションでマルチスレッド処理が無効になります。 |
tpinit()の引数tpinfoは、TPINITタイプおよびNULLサブタイプの型付きバッファを指すポインタです。TPINITは、atmi.hヘッダー・ファイルにtypedefで定義されているバッファ・タイプです。このバッファは、tpinit()を呼び出す前にtpalloc()で割り当てられる必要があります。このバッファの解放は、tpinit()の呼出しの後、tpfree()を使用して行います。TPINIT型付きバッファ構造体は次のようなメンバーで構成されています。
char usrname[MAXTIDENT+2];
char cltname[MAXTIDENT+2];
char passwd[MAXTIDENT+2];
char grpname[MAXTIDENT+2];
long flags;
long datalen;
long data; usrname、cltname、grpnameおよびpasswdの値はすべてNULL終了文字列です。usrnameは呼出し側を表す名前です。cltnameは、セマンティクスがアプリケーションで定義されたクライアント名です。値sysclientは、cltnameフィールド用にシステムによって予約されています。usrnameとcltnameフィールドは、tpinit()実行時にクライアントと関連付けられ、ブロードキャスト通知と管理統計情報の検索に使用されます。これらの名前は、MAXTIDENTの文字数を超えてはなりません。passwdは、アプリケーション・パスワードとの認証に使用される非暗号化形式のアプリケーション・パスワードです。passwdは30文字に制限されます。grpnameは、クライアントをリソース・マネージャ・グループ名と関連付けるときに使用します。grpnameが長さ0の文字列として設定されている場合、クライアントはリソース・マネージャに関連付けられず、デフォルトのクライアント・グループに属します。ワークステーション・クライアントの場合、grpnameの値にはNULL文字列(長さが0の文字列)を指定します。grpnameはACL GROUPSには関連しないことに注意してください。
tpinit()には、シングル・コンテキスト・モードとマルチコンテキスト・モードの2つの動作モードがあります。シングル・コンテキスト・モードでは、プロセスは一度に1つのアプリケーションに参加できます。このアプリケーションには、複数のアプリケーション・スレッドがアクセスできます。シングル・コンテキスト・モードを指定するには、NULLのパラメータを指定したtpinit()を呼び出すか、TPINIT構造体のflagsフィールドにTPMULTICONTEXTSフラグを指定せずにtpinit()を呼び出します。また、tpinit()が別のATMI関数によって暗黙的に呼び出されたときも、シングル・コンテキスト・モードが指定されます。シングル・コンテキスト・モードで動作するプロセスのコンテキスト状態は、TPSINGLECONTEXTです。
| 注意: | TMNOTHREADS環境変数を"yes"に設定しても、tpinitのTPMULTICONTEXTSモードは正しく機能します。 |
シングル・コンテキスト・モードでは、tpinit()を2回以上呼び出す場合(つまり、クライアントがすでにアプリケーションに参加した後に呼び出す場合)は、何もアクションは実行されず、成功を示す戻り値が返されます。
TPINIT構造体のflagsフィールドにTPMULTICONTEXTSフラグを設定してtpinit()を呼び出すと、マルチコンテキスト・モードに移行します。マルチコンテキスト・モードでは、tpinit()を呼び出すたびに別のアプリケーション関連が作成されます。
アプリケーションの関連とは、プロセスとOracle Tuxedo ATMIアプリケーションを関連付けるコンテキストです。クライアントは、複数のOracle Tuxedo ATMIアプリケーションと関連を持ったり、同じアプリケーションに対して複数の関連を持つことができます。クライアントの関連付けは、すべて同じリリースのOracle Tuxedo ATMIシステムを実行するアプリケーションに対する関連付けでなければなりません。また、すべての関連付けはネイティブ・クライアントかワークステーション・クライアントのいずれかでなければなりません。
ネイティブ・クライアントの場合、新しい関連の生成元になるアプリケーションは、TUXCONFIG環境変数の値で決まります。ワークステーション・クライアントの場合、新しい関連の生成元になるアプリケーションは、WSNADDRまたはWSENVFILE環境変数の値で決まります。カレント・スレッドのコンテキストは、新しい関連に設定されます。
マルチコンテキスト・モードでは、アプリケーションはtpgetctxt()を呼び出すことにより現在のコンテキストを表すハンドルを取得し、そのハンドルをパラメータとしてtpsetctxt()に渡して、特定のスレッドまたはプロセスが動作するコンテキストを設定できます。
シングル・コンテキスト・モードとマルチコンテキスト・モードの両方を使用することはできません。アプリケーションがどちらかのモードを選択した場合、すべてのアプリケーション関連でtpterm()が呼び出されるまで、他のモードでtpinit()を呼び出すことはできません。
マルチコンテキスト・モードとシングル・コンテキスト・モードを制御するほかに、flagsの設定により、クライアント固有の通知メカニズムとシステム・アクセスのモードの両方を示すことができます。この2つの設定で、アプリケーションのデフォルト設定をオーバーライドすることができます。これらの設定でアプリケーションのデフォルトをオーバーライドできない場合、tpinit()はログ・ファイルに警告メッセージを記録し、その設定を無視して、tpinit()からの戻り時にflagsフィールドの設定をアプリケーションのデフォルト設定に戻します。クライアントへの通知の場合、flagsの値として次のものがあります。
TPU_SIG
TPMULTICONTEXTSフラグが設定されている場合、このフラグは使用できません。
TPU_DIP
TPU_THREAD
THREAD通知を選択します。このフラグは、マルチスレッドをサポートするプラットフォーム専用です。マルチスレッドをサポートしていないプラットフォームでTPU_THREADが指定されると、無効な引数とみなされ、エラーが返されてtperrnoがTPEINVALに設定されます。
TPU_IGN
一度に上記の中から1つのフラグだけを使用できます。クライアントがフラグ・フィールドを使用して通知方法を選択しない場合、アプリケーションのデフォルトの方法が、tpinit()の終了時にフラグ・フィールドに設定されます。
システム・アクセス・モードの設定の場合、flagsの値として次のものがあります。
TPSA_FASTPATH
TPSA_PROTECTED
一度に上記の中から1つのフラグだけを使用できます。クライアントが通知方法あるいはシステム・アクセス・モードをフラグ・フィールドで選択しない場合、tpinit()の終了時にアプリケーションのデフォルトの方法がflagsフィールドに設定されます。クライアントの通知方法とシステム・アクセス・モードの詳細は、「UBBCONFIG(5)」を参照してください。
アプリケーションがマルチスレッドまたはマルチコンテキストを使用する場合は、次のフラグを設定する必要があります。
TPMULTICONTEXTS
datalenは、それに続くアプリケーション固有のデータの長さです。TPINIT型付きバッファのバッファ・タイプ・スイッチ・エントリは、そのバッファに対して渡される合計サイズに基づいてこのフィールドを設定します(アプリケーション・データのサイズは、合計サイズからTPINIT構造体自体のサイズを差し引き、構造体に定義されているプレースホルダーのサイズを加えたものです)。dataは、アプリケーションで定義された認証サービスに転送される可変長データ用のプレースホルダーです。これは常に、この構造体の最後の要素となります。
マクロTPINITNEEDは、目的のアプリケーション固有のデータ長を収めるのに必要とされるTPINITのバッファのサイズを判別するときに使用できます。たとえば、アプリケーション固有のデータを8バイトにしたい場合、TPINITNEED(8)は必要とされるTPINITのバッファ・サイズを返します。
アプリケーションがOracle Tuxedo ATMIシステムの認証機能を使用しない場合には、tpinfoにNULL値を使用できます。NULL引数を使用するクライアント・プロセスは、usrname、cltname、およびpasswdについてはデフォルトの設定である長さ0の文字列を取得します。フラグは設定されず、アプリケーション・データも得られません。
異常終了すると、tpinit()は呼出しプロセスを元のコンテキストに維持したまま-1を返し、tperrnoを設定してエラー条件を示します。またtpurcode()は、AUTHSVR(5)サーバーによって返される値に設定されます。
異常終了時には、tpinit()はtperrnoを次のいずれかの値に設定します。
TPEINVAL]
TPENOENT]
TPEPERM]
tpurcode()は、クライアントがアプリケーションに参加できない理由を説明するため、アプリケーション固有の認証サーバーによって設定される場合があります。
TPEPROTO]
tpinit()が不正に呼び出されました。たとえば、(a)呼出し元がサーバーである、(b)シングル・コンテキスト・モードでTPMULTICONTEXTSフラグが指定されている、または(c)マルチコンテキスト・モードでTPMULTICONTEXTSフラグが指定されていない場合があります。
TPESYSTEM]
TPEOS]
tpchkauth()、およびtpinit()のTPINIT型付きバッファ引数に対するNULL以外の値は、リリース4.2以降を実行しているサイトでのみ使用できます。
tpinit(3c)に記述されているインタフェースは、UNIX、Windows、およびMS-DOSオペレーティング・システム上でサポートされています。ただし、シグナル・ベースの通知方法は、16ビットのWindowsおよびMS-DOSではサポートされていません。tpinit()の実行時にこの通知方法が選択されると、userlog()メッセージが生成され、通知方式は自動的にディップインに設定されます。
TUXCONFIG
tpinit()内で使用されます。この変数は、クライアントの接続先になるアプリケーションを示します。なお、この環境変数は、tpinit()が呼び出されたときのみ参照されます。これ以降の呼出しには、アプリケーション・コンテキストが使用されます。
WSENVFILE
tpinit()内で使用されます。この変数には、環境変数の設定を含むファイルを指定しますが、この設定は呼出し側の環境で行うようにします。ワークステーション・クライアントに必要とされる環境変数の設定に関する詳細は、「compilation(5)」を参照してください。このファイルは、tpinit()が呼び出されるとき(その前ではなく)にのみ処理されます。
WSNADDR
tpinit()内で使用されます。これは、アプリケーションをアクセスするときに使用されるワークステーション・リスナー・プロセスのネットワーク・アドレスを示します。この変数はワークステーション・クライアントの場合は必須ですが、ネイティブ・クライアントの場合は無視されます。
//host.name:port_number//#.#.#.#:port_numberの形式で指定できます。1つ目の形式では、ドメインがローカル名を解決する手法(通常はDNS)を使用してhostnameのアドレスを検索します。hostnameにはローカル・マシン名を指定し、ローカル名解決の機能でhostnameをローカル・マシンのアドレスに明確に解決する必要があります。 2つ目の形式の#.#.#.# は、ドットで区切られた10進数です。ドットで区切った10進数の形式では、各#は0から255までの数でなければなりません。このドットで区切った10進数は、ローカル・マシンのIPアドレスを表現します。 上記のどちらの形式でも、port_numberはドメイン・プロセスがリクエストの受信をリスニングするTCPポート番号です。port_numberには、0から65535までの数字または名前を指定できます。port_numberが名前の場合は、ローカル・マシンのネットワーク・サービス・データベースになければなりません。 アドレスは、文字0xを先頭に付けて16進数形式でも指定できます。先頭の0xに続く文字として、0 - 9までの数字か、またはAからFまでの文字(大文字と小文字は区別しない)を指定できます。16進数の形式は、IPX/SPXやTCP/IPのような任意のバイナリ・ネットワーク・アドレスに使うことができます。 アドレスはまた、任意の文字列として指定することもできます。値は、構成ファイル内のNETWORKセクションのNLSADDRパラメータに指定された値と同じでなければなりません。 必要に応じて複数のアドレスを指定できます。その場合は、WSNADDRのパス名のリストをカンマ区切りで指定します。接続が確立するまで順番にアドレス指定が試みられます。アドレス・リストのメンバーは、どれでもパイプで区切られたネットワーク・アドレスのかっこ付きのグループとして指定することができます。たとえば、WSNADDR=(//m1.acme.com:3050|//m2.acme.com:3050),//m3.acme.com:3050です。Windowsで実行しているユーザーの場合、アドレス文字列はset WSNADDR=(//m1.acme.com:3050^|//m2.acme.com:3050),//m3.acme.com:3050のようになります。パイプ記号(|)はWindowsでは特殊文字とみなされるため、コマンドラインに指定する場合はWindows環境のエスケープ文字であるカレット(^)を前に付ける必要があります。ただし、envfileでWSNADDRが定義されている場合、Oracle Tuxedo ATMIシステムは関数を介してWSNADDRが定義する値を取得します。この場合、パイプ記号(|)は特殊文字とみなされないので、カレット(^)を使用する必要はありません。 Oracle Tuxedo ATMIシステムはかっこ付きアドレスを無作為に選択します。この方法は、一連のリスナー・プロセスに対してランダムに負荷分散します。接続が確立するまで順番にアドレス指定が試みられます。ワークステーション・リスナーを呼び出すには、アプリケーションの構成ファイルの値を使用してください。この値が、"0x"で始まる文字列の場合は、16進値文字列と解釈され、それ以外の場合は、ASCII文字列と解釈されます。 UNIXでソケット・ダイレクト・プロトコル(SDP)を使用するように/WSクライアントを構成する場合、アドレス文字列は$ export WSNADDR=sdp://IB_IP:portのようになります。UNIXでIP over InfiniBand (IPoIB)を使用するように/WSクライアントを構成する場合、アドレス文字列は $ export WSNADDR=//IB_IP:portのようになります。UNIXでIP over TCP/IPを使用するように/WSクライアントを構成する場合、アドレス文字列は$ export WSNADDR=//ETH_IP:portのようになります。
WSFADDR
tpinit()内で使用されます。この変数は、ワークステーション・クライアントがワークステーション・リスナーまたはワークステーション・ハンドラに接続するときに使用するネットワーク・アドレスを指定します。この変数は、WSFRANGE変数とともに、ワークステーション・クライアントがアウトバウンド接続を行う前にバインドしようとするTCP/IPポートの範囲を決定します。このアドレスには、TCP/IPアドレスを指定する必要があります。TCP/IPアドレスのポート部分は、ワークステーション・クライアントによってバインドされる一連のTCP/IPポートのベース・アドレスを表します。WSFRANGE変数は、範囲の大きさを指定します。たとえば、このアドレスが//mymachine.oracle.com:30000でWSFRANGEが200の場合、このLMIDからアウトバウンド接続を試みるネイティブ・プロセスはすべて、mymachine.oracle.com 30000から30200の間のポートをバインドします。この変数を設定しないと、空の文字列が使用され、オペレーティング・システムはローカル・ポートをランダムに選択します。
WSFRANGE
tpinit()内で使用されます。この変数は、ワークステーション・クライアント・プロセスが、アウトバウンド接続を行う前にバインドを試みるTCP/IPポートの範囲を指定します。WSFADDRパラメータは、範囲のベース・アドレスを指定します。たとえば、WSFADDRパラメータが//mymachine.oracle.com:30000に設定され、WSFRANGEが200に設定されると、このLMIDからアウトバウンド接続を試みるネイティブ・プロセスはすべて、mymachine.oracle.com 30000から30200の間のポートにバインドします。有効範囲は1から65535までです。デフォルト値は1です。
WSDEVICE
tpinit()内で使用されます。これは、ネットワークのアクセス時に使用するデバイス名を示します。この変数はワークステーション・クライアントが使用し、ネイティブ・クライアントの場合は無視されます。なお、ソケットやNetBIOSなどトランスポート・レベルのネットワーク・インタフェースはデバイス名を必要としません。このようなインタフェースによってサポートされているワークステーション・クライアントは、WSDEVICEを指定する必要はありません。
WSTYPE
tpinit()内から使用され、ネイティブ・サイトとの間でエンコード/デコードの責任範囲について調整を行います。この変数はワークステーション・クライアントの場合は省略可能で、ネイティブ・クライアントの場合は無視されます。
WSRPLYMAX
tpinit()によって使用され、アプリケーションの応答をファイルに格納する前にバッファに入れるために使用するコア・メモリーの最大サイズを設定します。このパラメータのデフォルトは、256,000バイトです。詳細は、プログラミング・ドキュメントを参照してください。
TMMINENCRYPTBITS
TMMAXENCRYPTBITS
シグナル・ベースの通知は、マルチコンテキスト・モードでは使用できません。また、シグナルの制約によって、クライアントがシグナル・ベースの通知を選択しても、システムがそれを使用できない場合があります。このような場合、システムは、選択されたクライアントに対する通知をディップ・インに切り替えることを示すログ・メッセージを生成し、クライアントはそれ以降ディップ・イン通知によって通知されます(通知方法の詳細については、「UBBCONFIG(5)」のRESOURCESセクションのNOTIFYパラメータの説明を参照してください)。
クライアントのシグナル通知は、常にシステムによって行われるので、元の通知呼出しがどこで行われるかにかかわらず、通知の形態は一貫しています。したがって、シグナル・ベースの通知を使用するには次の条件が必要です。
アプリケーション管理者のIDは、アプリケーション構成の一部として識別されます。
クライアントにシグナル・ベースの通知を選択すると、ある種のATMI呼出しは正常に実行できないことがあります。このとき、TPSIGRSTRTの指定がない場合、非請求メッセージを受け取るため、TPGOTSIGが返されます。
「C言語アプリケーション・トランザクション・モニター・インタフェースについて」、tpgetctxt(3c)、tpsetctxt(3c)、tpterm(3c)
tpkey_close() - 以前にオープンしたキー・ハンドルのクローズ
#include <atmi.h>
int tpkey_close(TPKEYhKey, longflags)
tpkey_close()は、以前にオープンしたキー・ハンドルと、それに関連付けられているすべてのリソースを解放します。プリンシパルの秘密鍵などの機密情報はすべて、メモリーから消去されます。
tpkey_close()を呼び出してキー・リソースを解放するのは、アプリケーションの役目です。あるプロセスがキーをクローズすると、同じプロセスがそのキー・ハンドルを使用してデジタル署名や暗号化のメッセージ・バッファを登録することはできなくなります。プロセスがTPKEY_AUTOSIGNまたはTPKEY_AUTOENCRYPTフラグを指定したtpkey_open()でキーをオープンした場合、キーをクローズした後の通信操作にはそのキー・ハンドルは適用されません。
ただし、キーをクローズした後でも、そのキー・ハンドルは、クローズ前に登録された関連署名リクエストや暗号化リクエストに対しては有効です。クローズしたキーに関連付けられている最後のバッファが解放されるか上書きされると、そのキーに属していたリソースは解放されます。
引数flagsは使用されません。この引数は将来の用途のために予約されており、0に設定します。
異常終了すると、この関数は -1を返し、tperrnoを設定してエラー条件を示します。
TPEINVAL]
TPESYSTEM]
tpenvelope(3c)、tpkey_getinfo(3c)、tpkey_open(3c)、tpkey_setinfo(3c)
tpkey_getinfo() - キー・ハンドルに関連付けられた情報の取得
#include <atmi.h>
int tpkey_getinfo(TPKEYhKey, char *attribute_name, void *value, long *value_len, longflags)
tpkey_getinfo()は、キー・ハンドルに関する情報を報告します。キー・ハンドルは、特定のプリンシパルのキーおよびそれに関連付けられている情報を表します。
調査対象のキーは、hKey入力パラメータによって識別されます。情報が要求されている属性は、attribute_name入力パラメータによって識別されます。一部の属性は暗号サービス・プロバイダ固有のものですが、以下に示す属性は、すべてのプロバイダによってサポートされています。
次の表に、デフォルトの公開鍵実装でサポートされるASN.1 DERアルゴリズム・オブジェクト識別子を示します。
指定されたattribute_nameパラメータに関連付けられている情報は、valueによって示されるメモリー位置に格納されます。この位置に格納できる最大データ量は、呼出し側によってvalue_lenに指定されます。
tpkey_getinfo()が完了すると、value_lenは実際に返されたデータ・サイズに設定されます。この場合、string値の終了NULL値も含まれます。返されるバイト数がvalue_lenより大きい場合、tpkey_getinfo()は異常終了し(TPELIMITエラー・コードを返し)、value_lenを必要な大きさに設定します。
引数flagsは使用されません。この引数は将来の用途のために予約されており、0に設定します。
異常終了すると、この関数は -1を返し、tperrnoを設定してエラー条件を示します。
TPEINVAL]
TPESYSTEM]
TPELIMIT]
TPENOENT]
tpkey_close(3c)、tpkey_open(3c)、tpkey_setinfo(3c)
tpkey_open() - デジタル署名の生成、メッセージの暗号化、またはメッセージの復号化のためのキー・ハンドルのオープン
#include <atmi.h>
int tpkey_open(TPKEY *hKey, char *principal_name, char *location, char *identity_proof, longproof_len, longflags)
tpkey_open()は、呼出し側のプロセスからキー・ハンドルを使用できるようにします。キー・ハンドルは、特定のプリンシパルのキーおよびそれに関連付けられている情報を表します。
キーは、以下に示す目的のうち、1つまたは複数の目的に使用できます。
プリンシパル名とTPKEY_SIGNATUREまたはTPKEY_AUTOSIGNフラグを設定してtpkey_open()を呼び出すと、そのプリンシパルの秘密鍵とデジタル証明書に対するハンドルが戻されます。
署名の検証にはtpkey_open()を呼び出す必要はありません。この確認プロセスでは、デジタル署名付きメッセージが添付されたデジタル証明書に指定されている公開鍵を使用して署名が検証されます。
プリンシパル名とTPKEY_ENCRYPTまたはTPKEY_AUTOENCRYPTフラグを設定してtpkey_open()を呼び出すと、プリンシパルのデジタル証明書を介して、プリンシパルの公開鍵に対するハンドルが戻されます。
プリンシパルの名前とTPKEY_DECRYPTフラグを設定してtpkey_open()を呼び出すと、プリンシパルの秘密鍵とデジタル証明書に対するハンドルが戻されます。
tpkey_open()によって返されたキー・ハンドルは*hKeyに格納されますが、値にNULLを使用することはできません。
principal_name入力パラメータは、キーの所有者のIDを指定します。principal_nameの値がNULLポインタまたは空の文字列の場合、デフォルトIDが使用されます。デフォルトIDは、現在のログイン・セッション、現在のオペレーティング・システム・アカウント、またはローカル・ハードウェア・デバイスなどの別の属性に基づいて決定されます。
キーのファイル位置は、locationパラメータに渡されます。基本となるキー管理プロバイダが位置を示すパラメータを必要としない場合、このパラメータの値はNULLを使用できます。
principal_nameのIDを認証するには、パスワードやパス・フレーズなどの証明資料が必要になります。証明資料が必要な場合は、identity_proofによって資料を参照する必要があります。証明資料が不要な場合、このパラメータの値はNULLでかまいません。
証明資料の長さ(バイト)は、proof_lenで指定します。proof_lenが0の場合、identity_proofはNULLで終了する文字列とみなされます。
キーの操作モードに必要なキー・アクセスのタイプは、flagsパラメータで指定します。
TPKEY_SIGNATURE:
TPKEY_AUTOSIGN:
TPKEY_SIGNATUREが暗黙的に指定されています。
TPKEY_ENCRYPT:
TPKEY_AUTOENCRYPT:
TPKEY_ENCRYPTが暗黙的に指定されています。
TPKEY_DECRYPT:
これらのフラグは1つまたは複数を組み合せて使用することができます。キーを暗号化のみに使用する場合(TPKEY_ENCRYPT)、identity_proofは必要ないのでNULLに設定できます。
正常終了すると、*hKeyはこのキーを表す値に設定され、tpsign()やtpseal()などの関数で使用できるようになります。
異常終了すると、この関数は -1を返し、tperrnoを設定してエラー条件を示します。
TPEINVAL]
TPEPERM]
TPESYSTEM]
tpkey_close(3c)、tpkey_getinfo(3c)、tpkey_setinfo(3c)
tpkey_setinfo() - キー・ハンドルに関連するオプション属性パラメータの設定
#include <atmi.h>
int tpkey_setinfo(TPKEYhKey, char *attribute_name, void *value, longvalue_len, longflags)
tpkey_setinfo()は、キー・ハンドルのオプション属性パラメータを設定します。キー・ハンドルは、特定のプリンシパルのキーおよびそれに関連付けられている情報を表します。
情報が修正されるキーは、hKey入力パラメータで識別されます。情報が修正される属性は、attribute_name入力パラメータで識別されます。一部の属性は暗号サービス・プロバイダ固有のものですが、「tpkey_getinfo(3c)」リファレンス・ページで示す基本的属性は、すべてのプロバイダでサポートされる必要があります。
attribute_nameパラメータに関連付けられた情報は、valueによって示されるメモリー位置に格納されます。valueのデータ内容が自己記述型の場合、value_lenは無視されます(0でかまいません)。それ以外の場合、value_lenにはvalue内のデータの長さが格納されている必要があります。
引数flagsは使用されません。この引数は将来の用途のために予約されており、0に設定します。
異常終了すると、この関数は -1を返し、tperrnoを設定してエラー条件を示します。
TPEINVAL]
TPELIMIT]
TPESYSTEM]
TPENOENT]
tpkey_close(3c)、tpkey_getinfo(3c)、tpkey_open(3c)
tpnotify() - クライアント識別子によって通知を送信するルーチン
#include <atmi.h>
int tpnotify(CLIENTID *clientid, char *data, long len, long flags)
tpnotify()は、各クライアントに非請求メッセージを送信できるようにします。
clientidは、以前のあるいは現在のサービス呼出しのTPSVCINFO構造体から保存された、または、他の何らかの通信機構によってクライアントに渡された(たとえば、管理インタフェースを使って検索された)クライアント識別子を指すポインタです。
このリクエストのデータ部はdataによって示され、以前にtpalloc()によって割り当てられたバッファです。lenに送信するデータの大きさを指定します。ただし、dataが長さの指定を必要としないタイプのバッファを指す場合(たとえば、FMLフィールド化バッファ)、lenは0でかまいません。また、dataはNULLであってもかまいません。この場合、lenは無視されます。
tpnotify()が正常終了した場合、メッセージはシステムに渡され、指定されたクライアントに送信されます。TPACKフラグが設定されている場合は、正常終了は、クライアントがメッセージを受信したことを意味します。さらに、クライアントが非請求のメッセージ・ハンドラに登録している場合は、ハンドラが呼び出されます。
TPACK
TPNOBLOCK
TPNOTIME
TPSIGRSTRT
マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドはtpnotify()の呼出しを発行できません。
異常終了すると、tpnotify()は -1を返し、tperrnoを設定してエラー条件を示します。呼出しが異常終了してtperrnoに特定の値が設定されたときは、中間のATMI呼出しを省略して引き続きtperrordetail()を呼び出すと、エラーに関する詳細な情報が提供されます。詳細は、「tperrordetail(3c)」リファレンス・ページを参照してください。
異常終了時には、tpnotify()はtperrnoを次のいずれかの値に設定します。
TPEINVAL]
TPENOENT]
TPETIME]
TPNOBLOCKとTPNOTIMEのいずれも指定されなかったか、TPACKは設定されたが承認が受信されず、TPNOTIMEが指定されませんでした。ブロッキング・タイムアウトは、TPNOBLOCKまたはTPNOTIMEが指定されている場合は発生しません。
TPEBLOCK]
TPGOTSIG]
TPEPROTO]
TPESYSTEM]
TPEOS]
TPERELEASE]
「C言語アプリケーション・トランザクション・モニター・インタフェースについて」、tpalloc(3c)、tpbroadcast(3c)、tpchkunsol(3c)、tperrordetail(3c)、tpinit(3c)、tpsetunsol(3c)、tpstrerrordetail(3c)、tpterm(3c)
#include <atmi.h>
int tpopen(void)
tpopen()は、呼出し側がリンクされるリソース・マネージャをオープンします。呼出し側には、多くとも1つのリソース・マネージャしかリンクできません。この関数はリソース・マネージャ固有のopen()呼出しのかわりに使用するもので、これにより、移植性を損なう可能性のある呼出しをサービス・ルーチンからなくすことができます。リソース・マネージャは初期化の内容がそれぞれで異なるため、個々のリソース・マネージャを開くために必要な情報を構成ファイルに記述します。
リソース・マネージャがすでにオープンされている場合(すなわち、tpopen()を2回以上呼び出した場合)、何も処理は行われず、正常終了を示すコードが返されます。
マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXTのスレッドはtpopen()の呼出しを発行できません。
現在のサーバーが-Mオプションを指定して構築されている場合、tpopenは、現在のサーバー・グループに関してAUTO=Yに設定されていて、対応するコンテキスト・フィールドが設定されている、UBBCONFIG (5)の*RMSセクションに記述されているすべてのRMをオープンします。
RMのオープンが失敗すると、tpopenはTPERMERRを戻します。
異常終了すると、tpopen()は -1を返し、tperrnoを設定してエラー条件を示します。
異常終了時には、tpopen()はtperrnoを次のいずれかの値に設定します。
TPERMERR]
TPEPROTO]
TPESYSTEM]
TPEOS]
tpclose(3c)、tprmopen(3c)、tprmclose(3c)、tprmstart(3c)、tprmend(3c)
#include <atmi.h>
int tppost(char *eventname, char *data, long len, long flags)
呼出し側はtppost()を使用して、イベントとそれに伴うすべてのデータをポストします。イベント名はeventnameに指定し、dataは、NULL以外の場合はデータを指すようにします。ポストされたイベントとそのデータは、Oracle Tuxedo ATMIのイベント・ブローカによって、eventnameに対して評価が成功するサブスクリプションを持ち、dataに対して評価が成功するオプションのフィルタ・ルールを持つすべてのサブスクライバにディスパッチされます。
eventnameには、最大31文字のNULLで終了する文字列を指定します。eventnameの最初の文字にドット(.)は使用できません。これは、Oracle Tuxedo ATMIシステム自体が定義するすべてのイベントの最初の文字として、ドットが予約されているためです。
dataには、NULL以外の場合は、tpalloc()によって以前に割り当てたバッファを指定し、lenにはバッファ内のイベントと共にポストするバッファに入っているデータの長さを指定しなければなりません。長さを指定する必要のないタイプのバッファ(FMLフィールド化バッファなど)をdataが指す場合、lenは無視されます。dataがNULLの場合、lenは無視され、イベントはデータなしでポストされます。
tppost()をトランザクション内で使用する場合は、トランザクションの境界を拡大して、これらのサーバー上、およびイベント・ブローカが通知する安定ストレージ上のメッセージ・キューを含むようにすることができます。トランザクションによるポストでは、ポストされたイベントを受け取ったことがポスト元のトランザクションに通知される場合(サーバーやキューなど)と、通知されない場合(クライアントなど)があります。
ポスト元がトランザクション内にあり、TPNOTRANがセットされている場合は、ポストされたイベントはイベント・ブローカに渡されます。これは、イベント・ブローカがイベントをポスト元のトランザクションの一部として処理できるようにするためです。イベント・ブローカはトランザクションによるイベント通知を、tpsubscribe()に渡されるctlflagsパラメータでTPEVTRANビットの設定を使用したサービス・ルーチンおよび安定ストレージ上のキューのサブスクリプションだけにディスパッチします。イベント・ブローカは、クライアントへの通知、およびtpsubscribe()に渡されるctlflagsパラメータでTPEVTRANビットの設定を使用しなかったサービス・ルーチンおよび安定ストレージ上のキューにあるサブスクリプションのディスパッチも行いますが、これはポスト元プロセスのトランザクションの一部としてではありません。
ポスト元がトランザクションの外部にある場合、イベントに関連付けられているサービスが失敗すると、tppost()は肯定応答のない一方向のポストになります。このような状況は、イベント用にTPEVTRANが設定されている場合でも起こります(この設定には、tpsubscribe()に渡されるctlflagsパラメータを使用します)。ポスト元がトランザクション内にある場合は、イベントに関連するサービスが失敗するとtppost()はTPESVCFAILを戻します。
TPNOTRAN
TPNOREPLY
tppost()が戻る前にイベント・ブローカがeventnameに対するすべてのサブスクリプションを処理するのを待たないように、tppostに通知します。TPNOREPLYがセットされると、tppost()が成功して戻ったかどうかにかかわらず、tpurcode()はゼロに設定されます。呼出しプロセスがトランザクション・モードにあるとき、TPNOTRANが設定されないかぎりこの設定は使用できません。
TPNOBLOCK
tperrnoにはTPEBLOCKが設定されます。TPNOBLOCKが指定されていないときにブロッキング条件が存在すると、呼出し側は、その条件が解消されるか、またはタイムアウト(トランザクションまたはブロッキング)が発生するまではブロックされます。
TPNOTIME
TPSIGRSTRT
TPSIGRSTRTが指定されていない場合にシグナルがシステム・コールを中断させると、tppost()は失敗し、tperrnoにはTPGOTSIGが設定されます。
マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドはtppost()の呼出しを発行できません。
tppost()から成功して戻ると、tpurcode()にはeventnameのかわりにイベント・ブローカによってディスパッチされるイベント通知の数が設定されています(つまり、eventnameに対するイベント表現の評価が成功し、dataに対するフィルタ・ルールの評価が成功したサブスクリプションへのポストです)。tperrnoがTPESVCFAILに設定されて戻った場合は、tpurcode()には、eventnameのかわりにイベント・ブローカによってディスパッチされたトランザクション以外のイベント通知の数が設定されています。
異常終了すると、tppost()は -1を返し、tperrnoを設定してエラー条件を示します。
異常終了時には、tppost()はtperrnoを次のいずれかの値に設定します(特に記述した場合を除いては、エラーが呼出し側のトランザクションに影響を及ぼすことはありません)。
TPEINVAL]
TPENOENT]
TPETRAN]
TPNOTRANが設定されず、トランザクション伝達をサポートしないイベント・ブローカにtppost()がコンタクトしました。つまり、TMUSREVT(5)が、トランザクションをサポートするOracle Tuxedo ATMIグループで実行されていません。
TPETIME]
TPNOBLOCKまたはTPNOTIMEが指定されている場合は発生しません。 トランザクション・タイムアウトが発生した場合、トランザクションがアボートされない限り、新しいリクエストの送信や未処理の応答の受信はできず、TPETIMEが発生します。その例外とは、ブロックされず、応答を期待せず、かつ呼出し側のトランザクションのかわりに送信されない(つまり、TPNOTRAN、TPNOBLOCKおよびTPNOREPLYを設定してtpacall()を呼び出した場合の)リクエストです。 tppost()がトランザクション内部で失敗すると、そのトランザクションはTX_ROLLBACK_ONLY状態になります。ほとんどの場合、この状態はタイムアウトと同じものとして扱われます。このトランザクションの以降のATMI呼出しは、TPETIMEで失敗します(前の段落で説明した例外を除きます)。
TPESVCFAIL]
tpurcode()には、eventnameの代わりにイベント・ブローカがディスパッチするトランザクション以外のイベント通知の数が設定されています。トランザクションのポスティングは、トランザクションの完了と共にその効果がなくなるため、カウントされません。なお、トランザクションがタイムアウトしないかぎり、通信はトランザクションが異常終了するまで継続され、呼出し側のトランザクションのためになされた作業はトランザクションが完了する時点で異常終了されます(つまり、以降のやりとりで何らかの結果が得られる場合には、TPNOTRANを設定しておく必要があります)。
TPEBLOCK]
TPGOTSIG]
TPEPROTO]
TPESYSTEM]
TPEOS]
tpsubscribe(3c)、tpunsubscribe(3c)、EVENTS(5)、TMSYSEVT(5)、TMUSREVT(5)
tprealloc() - 型付きバッファのサイズを変更するルーチン
#include <atmi.h>
char * tprealloc(char *ptr, long size)
tprealloc()は、ptrが指すバッファのサイズをsizeバイトに変更し、新しい(おそらく移動した)バッファを指すポインタを返します。tpalloc()と同様、割り当てるバッファは少なくともsizeおよびdfltsizeと同じ大きさになります。ここで、dfltsizeは特定のバッファ・タイプのtmtype_swに指定されたデフォルトのバッファ・サイズです。この2つの値の大きい方のサイズが0またはそれ以下であると、このバッファは変更されず、NULLが返されます。バッファの型は、再割当ての後も変わりません。この関数が正常に終了した場合、返されたポインタは、バッファを参照するために使用します。以後、バッファの参照にptrを使用しないようにしてください。バッファの内容は、新しいサイズと古いサイズのうち短い方の長さまでは変更されません。
ある種のバッファ・タイプは、使用する前に初期化を行っておく必要があります。tprealloc()は、バッファを再割り当てした後、(通信マネージャ固有の方法で)バッファを再度初期化します。このため、呼出し側から返されるバッファはすぐに使用できます。
マルチスレッドのアプリケーション中のスレッドは、TPINVALIDCONTEXTを含め、どのコンテキスト状態で実行していても、tprealloc()の呼出しを発行できます。
tprealloc()は正常終了すると、longワードに境界を合わせた、適切なタイプのバッファへのポインタを返します。
異常終了すると、tprealloc()はNULLを返し、tperrnoを設定してエラー条件を示します。
再初期化関数が正常に実行できなかった場合、tprealloc()は異常終了してNULLを返し、ptrが指すバッファの内容は無効になってしまう可能性があります。異常終了時には、tprealloc()はtperrnoを次のいずれかの値に設定します。
TPEINVAL]
TPEPROTO]
TPESYSTEM]
TPEOS]
バッファの再初期化が正常に実行できなかった場合、tprealloc()は異常終了して、NULLを返し、ptrが指すバッファの内容は無効になってしまう可能性があります。この関数は、Cライブラリのmalloc()、realloc()、またはfree()とともに使用することはできません(たとえば、tprealloc()で割り当てたバッファはfree()で解放することはできません)。
tpalloc(3c)、tpfree(3c)、tptypes(3c)
tprecv() - 会話型接続でメッセージを受信するルーチン
#include <atmi.h>
int tprecv(int cd, char **data, long *len, long flags, long \
*revent)
tprecv()は、別のプログラムからオープン接続を介してデータを受け取るときに使用します。tprecv()の最初の引数cdは、データを受け取るオープン接続を指定します。cdには、tpconnect()から返される記述子、あるいは会話型サービスに渡されるTPSVCINFOパラメータに含まれる記述子のいずれかを指定します。2番目の引数dataは、tpalloc()によって以前に割り当てられたバッファを指すポインタのアドレスです。
dataは、前にtpalloc()が割り当てたバッファへのポインタのアドレスでなければなりません。また、lenはlong型(tprecv()が受信したデータのサイズに設定した)を指さなければなりません。*dataは応答を含んでいるバッファを指し、*len は、バッファのサイズを含みます。FMLとFML32バッファは、通常最小サイズ4096バイトを確保します。したがって、応答が4096バイトより大きい場合は、バッファ・サイズは返されるデータを入れるのに十分な大きさに拡大します。
容量まで満たされていない送信側のバッファ(たとえば、FMLおよびSTRINGバッファ)は、送信に使用された大きさになります。システムは、受信データのサイズを任意の量で拡大します。これは、受信者が送信者の割り当てたバッファ・サイズより小さく、送信されたデータのサイズより大きいバッファを受け取ることを意味します。
受信バッファのサイズは、増加することも減少することもあります。また、アドレスもシステムがバッファを内部で交換するごとに常に変更されます。応答バッファのサイズが変わったどうか(また変わったとしたらどれくらい変わったのか)を決定するには、tprecv()が*lenとともに発行される前に、合計サイズを比べてください。バッファ管理の詳細については、「C言語アプリケーション・トランザクション・モニター・インタフェースについて」を参照してください。
*lenが0の場合、データは受け取られず、*dataも、それが指すバッファも、変更されていません。data、*dataまたはlenがNULLであると、エラーになります。
tprecv()は、接続の制御をもたないプログラムしか出せません。
TPNOCHANGE
dataが指すバッファとは異なるタイプのバッファが受信されると、受信側が着信バッファのタイプを識別するかぎり、*dataのバッファ・タイプは、受信されたバッファのタイプに変更されます。このフラグが設定されていると、*dataが指すバッファのタイプは変更されません。つまり、受信されたバッファのタイプとサブタイプは、*dataが指すバッファのタイプとサブタイプと一致する必要があります。
TPNOBLOCK
tprecv()はデータが到着するまで待機しません。すでにデータが受信できる状態であると、tprecv()はデータを取り込んで終了します。このフラグが設定されておらず、かつ受信できるデータがない場合、呼出し側はデータが到着するまでブロックされます。
TPNOTIME
TPSIGRSTRT
記述子cdに対してイベントが存在すると、tprecv()は終了し、tperrnoをTPEEVENTに設定します。イベントのタイプがreventで返されます。TPEV_SVCSUCC、TPEV_SVCFAILおよびTPEV_SENDONLYイベントとともに、データを受け取ることができます。tprecv()の有効なイベントを次に示します。
TPEV_DISCONIMM
tpdiscon()により即時切断要求を出したこと、あるいは接続をオープンにしたままでtpreturn()、tpcommit()、またはtpabort()を出したことを示します。このイベントは、通信エラー(サーバー、マシン、ネットワークの障害など)により接続が切断されたときにも起動元またはその従属側に返されます。これは即時切断通知(つまり、正常ではなく中途の終了)であるため、処理途中のデータは失われます。2つのプログラムが同じトランザクションに参加していた場合、そのトランザクションは中途終了マークが付けられます。この接続に使用された記述子は無効になります。
TPEV_SENDONLY
TPEV_SVCERR
tpreturn()を出したことを示します。tpreturn()に、サービスが正しく応答を返すことができないようなエラーが発生しています。たとえば、不正な引数がtpreturn()に渡されていたり、tpreturn()が、そのサービスが別の従属側にオープン接続を持っている最中に呼び出されている可能性があります。このイベントの性質上、アプリケーションが定義したデータや戻りコードは返されません。この接続は切断され、記述子は無効になります。このイベントがcd受信側のトランザクションの一部として発生した場合は、トランザクションは中断のみとしてマークされます。
TPEV_SVCFAIL
TPFAILまたはTPEXITとともにtpreturn()が呼び出されています)。従属サービスは、tpreturn()が呼び出されたときにこの接続の制御下にあった場合は、アプリケーション定義の戻りコードおよび型付きバッファを接続の起動元に渡すことができます。サービス・ルーチンの終了処理の一部として、サーバーはこの接続を切断しています。このため、cdは無効な記述子となります。このイベントが、受信側のトランザクションの一部として発生すると、そのトランザクションは中断のみとしてマークされます。
TPEV_SVCSUCC
TPSUCCESSとともにtpreturn()が呼び出されています)。サービス・ルーチンの終了処理の一部として、サーバーはこの接続を切断しています。このため、cdは無効な記述子となります。受信側がトランザクション・モードにいる場合、そのトランザクションをコミットする(それが起動元でもある場合)か、中途終了して、サーバーが行った作業内容(トランザクション・モードである場合)をコミットあるいは中途終了させます。
マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドはtprecv()の呼出しを発行できません。
reventがTPEV_SVCSUCCまたはTPEV_SVCFAILのどちらかに設定されている場合に、tprecv()が終了した場合は、グローバル変数tpurcodeには、tpreturn()の一部として送信されるアプリケーション定義の値が含まれます。
異常終了すると、tprecv()は -1を返し、tperrnoを設定してエラーの条件を示します。呼出しが異常終了してtperrnoに特定の値が設定されたときは、中間のATMI呼出しを省略して引き続きtperrordetail()を呼び出すと、エラーに関する詳細な情報が提供されます。詳細は、「tperrordetail(3c)」リファレンス・ページを参照してください。
異常終了時には、tprecv()はtperrnoを次のいずれかの値に設定します。
TPEINVAL]
TPEOTYPE]
TPNOCHANGEがflagsに設定されていて、*dataのタイプおよびサブタイプが受け取るバッファのタイプおよびサブタイプと合っていません。*dataの内容も*lenも変更されていません。会話が呼出し側の現在のトランザクションの一部になっている場合は、受け取るバッファが放棄されるため、トランザクションは中断のみとしてマークされます。
TPEBADDESC]
TPETIME]
TPNOBLOCKまたはTPNOTIMEが指定されている場合は発生しません。)いずれの場合でも、*dataもその内容も変更されません。 トランザクション・タイムアウトが発生した場合、トランザクションがアボートされない限り、新しいリクエストの送信や未処理の応答の受信はできず、TPETIMEが発生します。その例外とは、ブロックされず、応答を期待せず、かつ呼出し側のトランザクションのかわりに送信されない(つまり、TPNOTRAN、TPNOBLOCKおよびTPNOREPLYを設定してtpacall()を呼び出した場合の)リクエストです。 ATMI呼出しがトランザクション内部で失敗すると、そのトランザクションはTX_ROLLBACK_ONLY状態になります。ほとんどの場合、この状態はタイムアウトと同じものとして扱われます。このトランザクションの以降のATMI呼出しは、TPETIMEで失敗します(前の段落で説明した例外を除きます)。
TPEEVENT]
TPETIME]と、[TPEEVENT]リターン・コードには関連があります。トランザクション・モードにおいては、会話の受信側がtprecvにブロックされていて、送信側がtpabort()を出した場合、受信側は[TPEVENT]リターン・コードをTPEV_DISCONIMMのイベントと共に取得します。ただし、受信側がtprecv()を呼び出す前に、送信側がtpabort()を出した場合は、そのトランザクションはすでにGTTから削除されてしまっているので、tprecv()は異常終了し、[TPETIME]コードが返されます。
TPEBLOCK]
TPGOTSIG]
TPEPROTO]
TPESYSTEM]
TPEOS]
サーバーは、tpreturn()を呼び出すとき、アプリケーション定義の戻りコードおよび型付きバッファを渡すことができます。戻りコードはグローバル変数tpurcodeで使用され、バッファはdataで使用されます。
tpalloc(3c)、tpconnect(3c)、tpdiscon(3c)、tperrordetail(3c)、tpsend(3c)、tpservice(3c)、tpstrerrordetail(3c)
tpresume() - グローバル・トランザクションを再開します。
#include <atmi.h>
int tpresume(TPTRANID *tranid, long flags)
tpresume()を使用して、中断されているトランザクションでの作業を再開します。呼出し側がトランザクションの作業を再開した場合、その作業はtpsuspend()で再度中断させるか、あるいはあとでtpcommit()またはtpabort()を利用して完了させる必要があります。
トランザクションの作業を再開する際には、呼出し側はリンクされたリソース・マネージャが(tpopen()を利用して)オープンされていることを確認する必要があります。
tpresume()は、tranidでポイントされるグローバル・トランザクション識別子により呼出し側をトランザクション・モードにします。tranidがNULLの場合はエラーです。
flagsは将来使用するために予約されており、0に設定されます。
マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドはtpresume()の呼出しを発行できません。
tpresume()は、グローバル・トランザクション内の複数のリソース・マネージャを含め、すべての参加リソース・マネージャに対して影響を与えることができます。
tpresume()は、エラーが発生すると -1を返し、tperrnoを設定してエラー条件を示します。
次の条件の場合、tpresume()は異常終了し、tperrnoを次の値に設定します。
TPEINVAL]
TRANID()がNULLポインタであるか、存在しないトランザクション識別子(以前に終了したトランザクションまたはタイムアウトになったトランザクションであるか、または呼出し側が再開することを認められていないトランザクション識別子です。トランザクションに関する呼出し側の状態は変化しません。
TPEMATCH]
TPETRAN]
TPEPROTO]
TPESYSTEM]
TPEOS]
XA準拠のリソース・マネージャがグローバル・トランザクションに含まれるようにするには、そのリソース・マネージャが正常にオープンされている必要があります(詳細については、「tpopen(3c)」を参照)。
中断したトランザクションを再開するプロセスは、トランザクションを中断したプロセスと同じ論理マシン(LMID)上に存在しなければなりません。ワークステーション・クライアントの場合、そのワークステーションが接続されているワークステーション・ハンドラ(WSH)は、そのトランザクションを停止させたワークステーション・クライアントのハンドラと同じ論理マシン上に存在している必要があります。
tpabort(3c)、tpcommit(3c)、tpopen(3c)、tpsuspend(3c)、tprmopen(3c)、tprmclose(3c)、tprmstart(3c)、tprmend(3c)
tpreturn() - Oracle Tuxedo ATMIシステム・サービス・ルーチンからの復帰
void tpreturn(int rval, long rcode, char *data, long len, long \
flags)
tpreturn()は、サービス・ルーチンが完了したことを示します。tpreturn()は、C言語のreturn文と同様に機能します(つまり、tpreturn()が呼び出されると、サービス・ルーチンはOracle Tuxedo ATMIシステム・ディスパッチャに戻ります)。Oracle Tuxedo ATMIシステム・ディスパッチャに制御を適切に戻すためには、ディスパッチされたサービス・ルーチン内からtpreturn()を呼び出すことを推奨します。
tpreturn()はサービスの応答メッセージを送信するときに使用します。応答を受け取るプログラムがtpcall()、tpgetrply()またはtprecv()で待機している場合、tpreturn()の呼出しが成功した時点で、受信側のバッファに応答が入ります。
会話型サービスの場合、tpreturn()は接続自体も切断します。したがって、サービス・ルーチンは、tpdiscon()を直接呼び出すことができません。正常な結果を保証するためには、会話型サービスに接続しているプログラムはtpdiscon()を呼び出してはなりません。そのようなプログラムは、会話型サービスが完了したという通知を待たなければなりません(たとえば、そのプログラムは、tpreturn()によって送信されるTPEV_SVCSUCCまたはTPEV_SVCFAILなどのイベントのちの1つを待つ必要があります)。
また、サービス・ルーチンがトランザクション・モードにあった場合には、tpreturn()はトランザクションのサービス部分を、そのトランザクションの完了時点でコミットまたは中断できる状態にします。サービスは同じトランザクションの一部として複数回呼び出すことができるため、tpcommit()またはtpabort()がそのトランザクションの開始プロセスによって呼び出されるまでは、完全にコミットあるいは中断させる必要は必ずしもありません。
tpreturn()は、該当サービス・ルーチンが出したサービス・リクエストから期待されるすべての応答を受け取った後、呼び出すようにしてください。そうしない場合は、サービスの性質によって決まりますが、TPESVCERRステータスまたはTPEV_SVCERRイベントのいずれかが、サービス・ルーチンとの接続を開始したプログラムに返ります。受け取られなかった応答は、受信処理の後、通信マネージャによって自動的に取り除かれます。また、これらの応答に対応する記述子は無効になります。
tpreturn()は、サービスが出したすべての接続をクローズした後、呼び出される必要があります。そうしない場合はサービスの性質によって決まりますが、TPESVCERRまたはTPEV_SVCERRイベントのいずれかが、サービス・ルーチンとの通信を開始したプログラムに返されます。また、即時切断イベント(つまり、TPEV_DISCONIMM)が、オープンしているすべての接続を通して従属側に送信されます。
会話型サービスは、自分で開始しなかったオープン接続を1つだけ備えているため、通信マネージャは、送信すべき記述子データ(およびイベント)を認識しています。このため、記述子は、tpreturn()に渡されません。
次に、tpreturn()の引数について説明します。rvalは次のいずれかに設定できます。
TPSUCCESS
tpreturn()は、そのトランザクションの呼出し側の部分を、トランザクションが最終的にコミットすべき時点でコミットできるような状態にします。tpreturn()を呼び出しても、必ずしもトランザクション全体が終了することにはつながりません。また、呼出し側が正常終了を示したとしても、未終了の応答またはオープン接続がある場合、該当サービス内で行われた作業が原因でトランザクションがロールバックのみとしてマークされた場合、失敗メッセージが送信されます(つまり、応答の受信側はTPESVCERR指示あるいはTPEV_SVCERRイベントを受け取ります)。サービス・ルーチンの処理中になんらかの理由でトランザクションがロールバックのみとしてマークされると、rvalがTPFAILに設定されます。TPSUCCESSが会話型サービスに対して指定されると、TPEV_SVCSUCCイベントが生成されます。
TPFAIL
TPSVCFAIL指示あるいはTPEV_SVCFAILイベントを受け取ります。呼出し側がトランザクション・モードであると、tpreturn()はそのトランザクションをロールバックのみとしてマークします(ただし、そのトランザクションは、すでにロールバックのみとしてマークされている場合もあります)。戻り処理が失敗した場合を除き、呼出し側のデータが(存在する場合)送信されます。トランザクション・タイムアウトになって、呼出し側のデータが送信されない場合もあります。この場合、応答を待つプログラムはTPETIMEエラーを受け取ることになります。会話型サービスにTPFAILが指定された場合には、TPEV_SVCFAILイベントが生成されます。
TPEXIT
TPFAILと同じように動作しますが、TPEXITが戻されると、サーバーは、トランザクションがロールバックされて応答がリクエスタに戻された後に終了します。 マルチスレッド・プロセスにこの値が指定された場合、TPEXITは(そのプロセス内の単一のスレッドではなく)プロセス全体が強制終了されることを示します。 サーバーが再開可能な場合、サーバーは自動的に再開します。
rvalがこれら3つの値のいずれかに設定されていない場合、デフォルトの値としてTPFAILが使用されます。
アプリケーションが定義した戻りコードrcodeをサービスの応答を受け取るプログラムに送ることもできます。このコードは、応答を正常に送ることができさえすれば(つまり、受信呼出しが正常に行われる、あるいはTPESVCFAILが返されれば)、rvalの設定には関係なく送ることができます。さらに、会話型サービスでは、このコードは、サービス・ルーチンがtpreturn()を発行したときに接続の制御権を持っている場合のみ送信されます。rcodeの値は、受信側の変数tpurcode()に入ります。
dataは送信される応答のデータ部を指すポインタです。dataがNULLでなければ、以前にtpalloc()の呼出しによって得られたバッファを指していなければなりません。このバッファが、サービス・ルーチン起動時にサービス・ルーチンに渡されたバッファと同じバッファである場合、そのバッファの配置は、Oracle Tuxedo ATMIシステムのディスパッチャに一任されます。したがって、サービス・ルーチンをコーディングする人は、バッファが解放されているかどうかを気にする必要はありません。実際、ユーザーがこのバッファを解放しようとしてもできません。ただし、tpreturn()に渡されたバッファが、そのサービスが呼び出されたときのものと異なる場合には、tpreturn()でそのバッファを解放することができます。メイン・バッファが解放されても、そのバッファ内に埋め込まれたフィールドが参照するバッファは解放されません。lenは送信するデータ・バッファの大きさを指定します。dataが長さの指定を必要としないバッファを指すポインタである場合(FMLフィールド化バッファなど)、lenは0でもかまいません。
dataがNULLの場合、lenは無視されます。この場合、サービスを起動したプログラムが応答を待っている状態にあると、データなしの応答が返されます。応答を待たない状態にあると、tpreturn()は、必要に応じてdataを解放し、応答を送信しないで復帰します。
現在、flagsは将来の使用のために予約されており、0に設定する必要があります(0以外の値に設定すると、応答の受信者はTPESVCERR指示またはTPEV_SVCERRイベントを受信します)。
会話型サービスの場合、呼出し側の戻りコードとデータ部が転送されない場合が2つあります。
サービス・ルーチンは呼出し側であるOracle Tuxedo ATMIシステムのディスパッチャに値を返しません。このため、このルーチンはvoidとして宣言されます。しかし、サービス・ルーチンはtpreturn()またはtpforward()を使用して終了させるようになっています。会話型サービス・ルーチンの場合、tpreturn()を使用しなければならず、tpforward()を使用することはできません。サービス・ルーチンをtpreturn()またはtpforward()のいずれも使用せずに終了させる場合(すなわち、このルーチンがC言語のreturn文を使用するか、ごく単純に関数の実行に失敗した場合)、あるいはtpforward()が会話型サーバーから呼び出された場合、そのサーバーはログに警告メッセージを出し、サービス・エラーをサービスのリクエスタに返します。従属側へのオープン接続はすべてただちに切断され、未終了の非同期応答は取り除かれます。障害時にサーバーがトランザクション・モードであった場合、このトランザクションには「ロールバックのみ」のマークが付けられます。tpreturn()やtpforward()がサービス・ルーチンの外部から使用される場合(たとえば、クライアントやtpsvrinit()あるいはtpsvrdone()で)、これらのルーチンは単に終了するだけです。
tpreturn()はサービス・ルーチンを終了させるので、引数処理またはサービス処理の間に発生したエラーについて、関数の呼出し側に示すことはできません。このようなエラーが起こると、tpcall()またはtpgetrply()を使用してサービスの結果を受信するプログラムのためにtperrnoがTPESVCERRに設定されます。またイベントTPEV_SVCERRが、tpsend()またはtprecv()を使用するプログラムに、会話を通して送信されます。
UBBCONFIGファイル中のSVCTIMEOUTか、TM_MIB中のTA_SVCTIMEOUTが0でない場合にサービスのタイムアウトが発生すると、TPEV_SVCERRが返されます。
tperrordetail()とtpstrerrordetail()を使用すると、現在のスレッドの中で呼び出された最新のOracle Tuxedo ATMIシステムのルーチンが出したエラーに関して、追加的な情報を取得できます。エラーが起きると、tperrordetail()は数値を返しますが、この数値をtrstrerrordetail()への引数として利用することで、エラーの詳細に関するテキストを受け取ることができます。
tpalloc(3c)、tpcall(3c)、tpconnect(3c)、tpforward(3c)、tprecv(3c)、tpsend(3c)、tpservice(3c)、tprmopen(3c)、tprmclose(3c)、tprmstart(3c)、tprmend(3c)
tpsblktime() - 次のサービス呼び出しまたはすべてのサービス呼出しのブロック・タイムを秒単位で設定するルーチン
#include <atmi.h>
inttpsblktime(int blktime,long flags)
tpsblktime()は、潜在的なブロッキングAPIのブロック時間値を秒単位で設定するために使用します。潜在的なブロッキングAPIは、値としてフラグTBNOBLOCKを使用できるシステムAPIとして定義します。トランザクション・タイムアウト値には影響しません。
blktimeの値の範囲は0 - 32767です。次の例で示すように、有効なブロック時間値はSCANUNIT値の最も近い倍数に切り上げられます。
値0は、以前に設定されたブロック時間フラグ値が取り消されており、別のブロック時間フラグ値で設定されたブロック時間が優先されることを示します。tpsblktime()を呼び出さない場合は、UBBCONFIGファイルの*SERVICESセクションまたはデフォルトの*RESOURCESセクションのBLOCKTIME値が使用されます。
| 注意: | tpsblktime()で設定したブロッキング・タイムアウトは、UBBCONFIGファイルの*SERVICESセクションおよび*RESOURCESセクションに設定されたBLOCKTIMEパラメータよりも優先されます。ブロック時間チェックの優先順位は次のとおりです。tpsblktime(TPBLK_NEXT)、tpsblktime(TPBLK_ALL)、*SERVICES、*RESOURCES |
TPBLK_NEXT
TPNOBLOCKフラグが含まれている場合、tpsblktime (TPBLK_NEXT)は影響せず、ブロッキングなしの状態が継続します。
TPBLK_NEXTフラグ値は、その直後のAPI呼出しのTPBLK_ALLフラグ値をオーバーライドします。次に例を示します。 tpsblktime(50,TPBLK_ALL)
tpcall(one)
tpsblktime(30,TPBLK_NEXT)
tpcall(two)
tpcall(three)tpcall(two)には、tpsblktime(30,TPBLK_NEXT)を基に30秒のブロッキング・タイムアウトアウト値が入ります。tpcall(one)およびtpcall(three)には、tpsblktime(50,TPBLK_ALL)を基に50秒のタイムアウト値が入ります。 tpsblktime(TPBLK_NEXT)はスレッド単位で動作します。したがって、アプリケーションでtpsblktime(TPBLK_NEXT)呼び出しや後続のAPI呼出しの周囲にミューテックスを使用する必要はありません。
TPBLK_ALL
tpsblktime()が呼び出されるまでの間、後続のすべての潜在的なブロッキングAPIのブロック時間値(秒)を設定します。呼び出されたAPIにTPNOBLOCKフラグが含まれている場合、tpsblktime(TPBLK_ALL)は影響せず、ブロッキングなしの状態が継続します。
tpsblktime(TPBLK_ALL)はコンテキスト単位で動作します。したがって、tpsblktime(TPBLK_ALL)は、複数のスレッドで使用されるコンテキストのいずれか1つのスレッドで呼び出す必要があります。 tpsblktime(TPBLK_ALL)は、tpterm(3c)が呼び出された後のコンテキストには影響しません。 | 注意: | スレッド・タイミングの依存関係に影響されないブロック時間値を実行するためには、tpinit(3c)の直後、tpgetctxt(3c)の戻り値がほかのスレッドで使用できるようになる前に、TPMULTICONTEXTSフラグを使用してマルチスレッド・コンテキストでtpsblktime(TPBLK_ALL)を呼び出すのが最適な方法です。 |
| 注意: | マルチスレッド・サーバー上のサービスでtpsblktime(TPBLK_ALL)を呼び出した場合は、その時点で実行されているスレッドにのみ影響します。すべてのサービスのブロック時間値を設定するには、tpsvrinit(3c)またはtpsvrthrinit(3c)と一緒にtpsblktime(TPBLK_ALL)を使用するのが最適な方法です。 |
tpsblktime()は、エラーが発生すると -1を返し、tperrnoを設定してエラー条件を示します。
異常終了時には、tpsblktime()はtperrnoを次のいずれかの値に設定します。
TPEINVAL]
TPERELEASE]
TPESYSTEM]
tpcall(3c)、tpcommit(3c)、tprecv(3c)、tpgblktime(3c)、UBBCONFIG(5)
tprmclose() - 複数のRMサーバー・グループに構成された特定のRMをクローズするルーチン
#include <atmi.h>
int tprmclose(char *rmname, long flags)
tprmclose()は、引数rmnameで指定されたリソース・マネージャをクローズします。現在のコンテキストがトランザクション・コンテキストにある場合、このルーチンは何も行わず、呼出し側にエラーを戻します。現在のRMがまだオープンしていない場合、またはすでにクローズしている場合(つまり、tprmclose() が複数回呼び出された場合)、何も実行されず、正常終了が戻されます。
tprmclose() は、tprmopen()ルーチンによってオープンされたリソース・マネージャのみをクローズできます。
現在の最初のパラメータrmnameは、UBBCONFIGの*RMSセクションで構成された値である必要があります。flagsは0である必要があります。
失敗すると、tprmclose()は-1を戻し、tperrnoを設定してエラー条件を示します。
失敗すると、tprmclose()はtperrnoを次のいずれかの値に設定します。
[TPERMERR]
[TPEPROTO]
tprmclose()が不正なコンテキストで呼び出されました。たとえば、buildserverの実行時に-Mオプションを使用して指定されていないサーバーによって呼び出された場合や、進行中のトランザクション・コンテキストで実行された場合などがあります。
[TPEINVAL]
rmnameがNULLである、または複数のリソース・マネージャのサーバー・グループに関連付けられている現在の*RMSセクションで有効なリソース・マネージャ名が構成されていないなど)。
[TPESYSTEM]
[TPEOS]
tpopen(3c)、tpclose(3c))、tprmopen(3c)
tprmend() - 指定されたRMのトランザクション・ブランチのかわりに実行された現在の作業を終了するルーチン
#include <atmi.h>
int tprmend (char *rmname, long flags);
tprmend()は、指定されたRMのトランザクション・ブランチのかわりに実行された現在の作業を終了します。このルーチンは、トランザクション・ブランチとの関連付けを解除するようリソース・マネージャに通知します。現在のRMがまだオープンしていない場合、または現在のコンテキストがトランザクション状態にない場合、tprmend()は何も実行せず、正常終了を呼出し側に戻します。
現在の最初のパラメータrmidは、このリソース・マネージャ・グループのUBBCONFIGに構成されている値である必要があります。flagsは0である必要があります。
失敗すると、tprmend()は-1を戻し、tperrnoを設定してエラー条件を示します。
失敗すると、tprmend()はtperrnoを次のいずれかの値に設定します。
[TPERMERR]
[TPEPROTO]
[TPETRAN]
[TPEINVAL]
rmnameパラメータがNULLである、または現在の複数のリソース・マネージャのサーバー・グループに有効なリソース・マネージャ名が構成されていないなど)。
TPESYSTEM]
[TPEOS]
tprmopen() - 複数のRMサーバー・グループに関連付けられているUBBCONFIGの*RMSセクションで構成された特定のRMをオープンするルーチン
#include <atmi.h>
int tprmopen(char *rmname, long flags)
tprmopen()は、UBBCONFIGの*RMSセクションに構成され、複数のリソース・マネージャのサーバー・グループに関連付けられている名前を使用して、特定のリソース・マネージャをオープンします。rmnameによって指定されたリソース・マネージャがすでにオープンしている場合(つまり、この rmname でtprmopen()が複数回呼び出された場合、またはrmnameがtpopen()によってオープンされた場合)、何も実行されず、正常終了が戻されます。
現在の最初のパラメータrmnameは、このリソース・マネージャ・グループのUBBCONFIGに構成されている値である必要があります。flagsは0である必要があります。
失敗すると、tprmopen()は-1を戻し、tperrnoを設定してエラー条件を示します。
失敗すると、 tprmopen()はtperrnoを次のいずれかの値に設定します。
[TPERMERR]
[TPEPROTO]
tprmopen()が不正なコンテキストで呼び出されました(たとえば、buildserverによって-Mオプションを使用して構築されていないサーバーによって呼び出された場合や、クライアント・プロセスによって呼び出された場合)。
[TPEINVAL]
rmnameがNULLである、または複数のRMのサーバー・グループに関連付けられているUBBCONFIGの*RMSセクションに有効なリソース・マネージャ名が構成されていないなど)。
[TPESYSTEM]
[TPEOS]
tpopen(3c)、tpclose(3c)、tprmclose(3c)
tprmstart() - MRMサーバーの指定されたRMのトランザクション・ブランチのかわりに作業を開始するルーチン
#include <atmi.h>
int tprmstart (char *rmname, long flags)
tprmstart()は、トランザクション・ブランチのかわりにこのトランザクション作業単位に参加することをオープンされたRMに通知します。現在のRMがすでに開始済状態である場合、このルーチンは操作を省略します。現在のRMがまだオープンしていない場合は、tprmstart()は何も実行せず、呼出し側にエラーを戻します。
現在の最初のパラメータrmnameは、このリソース・マネージャ・グループのUBBCONFIGに構成されている値である必要があります。flagsは0である必要があります。
tprmstart()は、古い仮仕様タイプのRMはサポートしていません。
失敗すると、tprmstart()は-1を戻し、tperrnoを設定してエラー条件を示します。
失敗すると、 tprmopen()はtperrnoを次のいずれかの値に設定します。
[TPERMERR]
[TPEPROTO]
tprmstart()が不正なコンテキストで呼び出されました(たとえば、複数のRMのサーバー・グループに含まれていないサーバーによって呼び出された場合、現在のプロセスがbuildserverに-Mオプションを指定して構築されていない場合、または現在のRMがまだオープンしていない場合など)。
[TPETRAN]
[TPEINVAL]
rmnameがNULLである、または複数のリソース・マネージャのサーバー・グループに関連付けられている*RMSセクションで有効なリソース・マネージャ名が構成されていないなど)。
[TPESYSTEM]
[TPEOS]
tpscmt() - tpcommit()がいつ戻るかを設定するルーチン
#include <atmi.h>
int tpscmt(long flags)
tpscmt()は、flagsで指定した値をTP_COMMIT_CONTROL特性に設定します。TP_COMMIT_CONTROL特性は、tpcommit()の呼出し側に制御を戻すことに関して、tpcommit()の動作に影響を与えます。プログラムがトランザクション・モードにあるかどうかに関係なく、プログラムからtpscmt()を呼び出すことができます。他のプログラムがコミットしなければならないトランザクションに呼出し側が参加している場合は、tpscmt()を呼び出してもそのトランザクションに影響を与えないことに注意してください。むしろ、呼出し側がコミットするその後のトランザクションに影響を与えます。
ほとんどの場合、Oracle Tuxedo ATMIシステムのスレッドの制御がtpcommit()を呼び出す場合にのみ、トランザクションがコミットされます。ただし、例外が1つあります。UBBCONFIGファイルのSERVICESセクションでAUTOTRAN変数が使用可能になっているために、サービスがトランザクション・モードでディスパッチされる場合は、そのトランザクションはtpreturn()の呼出し時点で完了します。tpforward()が呼び出されると、最終的にサーバーがtpreturn()を呼び出すことでトランザクションが完了します。このように、tpreturn()を呼び出すサービスのTP_COMMIT_CONTROL属性の設定によって、サーバー中でtpcommit()からいつ制御が戻るかが決まります。tpcommit()がヒューリスティックなエラー・コードを返した場合、サーバーはメッセージをログ・ファイルに書き込みます。
クライアントがOracle Tuxedo ATMIシステムのアプリケーションに参加する場合は、この特性の初期設定は構成ファイルから取られます(「UBBCONFIG(5)」のRESOURCESセクションのCMTRET変数を参照)。
TP_CMT_LOGGED
tpcommit()から返ることを指定します。この設定は、tpcommit()の呼出し側に対するより速い反応を見込んでいます。だだし、第2フェーズの完了を待つ時間的な遅延のため、トランザクションの参加リソースが処理をヒューリスティックに完了する(すなわち、異常終了を示します)と決めるかもしれないという危険が存在します。この場合は、tpcommit()はすでに戻っているので、これを呼出し側に伝える方法はありません(ただし、リソース・マネージャがヒューリスティックな設定を行うと、Oracle Tuxedo ATMIシステムはメッセージをログ・ファイルに書き込みます)。正常な状態では、第1フェーズの間にコミットすることを約束している参加リソースは、第2フェーズでコミットします。一般に、ネットワークやサイトの障害が原因で問題が生じると、第2フェーズでヒューリスティックな判断がなされます。
TP_CMT_COMPLETE
tpcommit(3c)が終了することを指定します。この設定により、tpcommit()は第2フェーズのコミット中にヒューリスティックな判断がなされたことを示すことができます。
マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドは、tpscmt()の呼出しを発行できません。
成功の場合、tpscmt()はTP_COMMIT_CONTROL特性の以前の値を返します。
異常終了すると、tpscmt()は -1を返し、tperrnoを設定してエラー条件を示します。
異常終了時には、tpscmt()はtperrnoを次のいずれかの値に設定します。
TPEINVAL]
TPEPROTO]
TPESYSTEM]
TPEOS]
Oracle Tuxedo ATMIシステムのトランザクションを記述するためにtpbegin()、tpcommit()、およびtpabort()を使用する場合、XAインタフェースに準拠した(呼出し側に妥当にリンクされている)リソース・マネージャが行う作業のみがトランザクションのプロパティを備えていることを記憶しておくことが重要です。トランザクションにおいて実行される他のすべての操作は、tpcommit()あるいはtpabort()のいずれにも影響されません。そのリソース・マネージャが行った処理がOracle Tuxedo ATMIシステムのトランザクションの一部となるよう、XAインタフェースを満たすリソース・マネージャをサーバーにリンクする方法については、「buildserver(1)」を参照してください。
tpabort(3c)、tpbegin(3c)、tpcommit(3c)、tpgetlev(3c)
tpseal() - 暗号化する型付きメッセージ・バッファのマーク
#include <atmi.h>
int tpseal(char *data, TPKEYhKey, longflags)
tpseal()は、暗号化するメッセージ・バッファをマーク(登録)します。hKeyを所有するプリンシパルは、このバッファを復号化し、その内容にアクセスすることができます。tpseal()を何度か呼び出すことによって、複数の受信者のプリンシパルに1つのバッファを指定できます。
dataは、(1)以前tpalloc()を呼び出すプロセスによって割り当てられたメッセージ・バッファ、または(2)システムによって受信プロセスに渡されたメッセージ・バッファのうち、いずれかの有効な型付きメッセージ・バッファを指している必要があります。バッファの内容は、tpseal()を呼び出した後で修正することができます。
dataが指すメッセージ・バッファがプロセスから伝送されると、公開鍵ソフトウェアがメッセージ内容を暗号化し、各暗号化登録リクエストのメッセージ・バッファに暗号化エンベロープをアタッチします。暗号化エンベロープによって、受信プロセスはメッセージを復号化することができます。
引数flagsは使用されません。この引数は将来の用途のために予約されており、0に設定します。
異常終了すると、この関数は -1を返し、tperrnoを設定してエラー条件を示します。
TPEINVAL]
TPESYSTEM]
tpkey_close(3c)、tpkey_open(3c)
tpsend() - 会話型接続でメッセージを送信するルーチン
#include <atmi.h>
int tpsend(intcd, char *data, longlen, longflags, long *revent)
tpsend()は、別のプログラムにオープン接続を介してデータを送信するときに使用します。このとき、呼出し側がこの接続を制御できなければなりません。tpsend()の最初の引数cdは、データを送信するオープン接続を指定するものです。cdには、tpconnect()から返される記述子、あるいは会話型サービスに渡されるTPSVCINFOパラメータに含まれる記述子のいずれかを指定します。
2番目の引数dataは、tpalloc()によって以前に割り当てられたバッファを指していなければなりません。lenには送信バッファの大きさを指定します。ただし、dataが長さの指定を必要としないバッファを指している場合(FMLフィールド化バッファなど)、lenは無視されます(0でかまいません)。また、dataはNULLでもかまいません。この場合、lenは無視されます(アプリケーション・データは送信されません。これはデータを送信せず、たとえば接続の制御だけを与えるときに使用されます)。dataのタイプとサブタイプは、接続の他方の側が認識するタイプおよびサブタイプと一致していなければなりません。
TPRECVONLY
tpsend()呼出しを発行できなくなります)。接続の他方の側の受取り側がtpsend()から送信されたデータを受け取る場合、接続の制御権を得たことを示すイベント(TPEV_SENDONLY)も受け取ります(そして、それ以上、tprecv()を呼び出すことができなくなります)。
TPNOBLOCK
TPNOBLOCKが指定されていないときにブロッキング条件が存在すると、呼出し側は、その条件が解消されるか、またはタイムアウト(トランザクションまたはブロッキング)が発生するまではブロックされます。
TPNOTIME
TPSIGRSTRT
記述子cdに対してイベントが存在する場合、tpsend()は呼出し側のデータを送信せずに失敗します。イベントのタイプは、reventに戻されます。tpsend()の有効なイベントを次に示します。
TPEV_DISCONIMM
tpdiscon()により即時切断要求を出したことを、または接続をオープンにしたままでtpreturn()か、tpcommit()か、もしくはtpabort()を出したことを示します。このイベントは、通信エラー(サーバー、マシン、ネットワークの障害など)により接続が切断されたときにも起動元またはその従属側に返されます。
TPEV_SVCERR
tpreturn()を出したことを示します。さらに、tpreturn()は、TPEV_SVCFAILについて後述している方法とは異なる方法で出されました。このイベントはACLパーミッション違反によっても発生します。つまり、呼出し側が受け取り先プロセスに接続するためのパーミッションをもっていないことを示します。このイベントは、tpconnect()が出されるのと同時にではなく、最初のtpsend()と共に(フラグTPSENDONLYをもったtpconnect()に続いて)返されるか、または最初のtprecv()と共に(フラグTPRECVONLYをもったtpconnect()に続いて)返されます。また、システム・イベントとログ・メッセージも生成されます。
TPEV_SVCFAIL
tpreturn()を出したことを示します。さらに、tpreturn()は、rvalとしてTPFAILまたはTPEXITを設定し、dataとしてNULLを設定した状態で出されました。
これらのイベントはそれぞれ、即時切断通知(つまり、正常ではなく中途で終了)を示すので、処理途中のデータは失われます。この接続に使用された記述子は無効になります。2つのプログラムが同じトランザクションに参加していた場合には、そのトランザクションに中途終了マークが付けられます。
UBBCONFIGファイル中のSVCTIMEOUTか、TM_MIB中のTA_SVCTIMEOUTのどちらか一方が0でない場合にサービスのタイムアウトが発生すると、TPESVCERRが返されます。
マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドは、tpsend()の呼出しを発行できません。
TPEV_SVCSUCCまたはTPEV_SVCFAILのどららかがreventに設定されてtpsend()が戻った場合、tpurcode()によってポイントされているグローバル変数には、tpreturn()の一部として送信された、アプリケーションで定義した値が入っています。関数tpsend()はエラー時には -1を返し、tperrnoを設定してエラーの条件を示します。またイベントが存在し、かつエラーが発生しない場合、tpsend()は -1を返し、tperrnoに[TPEEVENT]を設定します。
異常終了時には、tpsend()はtperrnoを次のいずれかの値に設定します。
TPEINVAL]
TPEBADDESC]
TPETIME]
TPNOBLOCKまたはTPNOTIMEが指定されている場合は発生しません。 トランザクション・タイムアウトが発生した場合、トランザクションがアボートされない限り、新しいリクエストの送信や未処理の応答の受信はできず、TPETIMEが発生します。その例外とは、ブロックされず、応答を期待せず、かつ呼出し側のトランザクションのかわりに送信されない(つまり、TPNOTRAN、TPNOBLOCKおよびTPNOREPLYを設定してtpacall()を呼び出した場合の)リクエストです。 トランザクションATMI呼出しがトランザクション内部で失敗すると、そのトランザクションはTX_ROLLBACK_ONLY状態になります。ほとんどの場合、この状態はタイムアウトと同じものとして扱われます。このトランザクションの以降のATMI呼出しは、TPETIMEで失敗します(前の段落で説明した例外を除きます)。
TPEEVENT]
TPEBLOCK]
TPGOTSIG]
TPEPROTO]
TPESYSTEM]
TPEOS]
tpalloc(3c)、tpconnect(3c)、tpdiscon(3c)、tprecv(3c)、tpservice(3c)
tpservice() - サービス・ルーチンのテンプレート
#include <atmi.h> /* C interface */
void tpservice(TPSVCINFO *svcinfo) /* C++ interface - must have
* C linkage */
extern “C” void tpservice(TPSVCINFO *svcinfo)
tpservice()は、サービス・ルーチン作成時のテンプレートです。このテンプレートは、ルーチンtpcall()、tpacall()、またはtpforward()を介してリクエストを受け取るサービス、およびルーチンtpconnect()、tpsend()、またはtprecv()を介して通信を行うサービスに使用できます。
tpcall()またはtpacall()を介して行われるリクエストを処理するサービス・ルーチンは、1つだけ着信メッセージを受け取り(svcinfoのdata要素内に)、1つだけ応答を送る(tpreturn()を使用してサービス・ルーチンを終了するとき)ことができます。
一方、会話サービスは、最大1つの着信メッセージとオープン接続の参照手段とともに、接続リクエストにより呼び出されます。会話型サービス・ルーチンが呼び出されると、接続元プログラムあるいは会話型サービスはアプリケーション側で定義されたようにデータの送信および受信を行うことができます。この接続は半二重方式で確立されます。つまり、接続の一方の側は、他方から明示的に制御を渡されるまで、会話を制御することはできません(データを送信できません)。
トランザクションとの関連で言えば、サービス・ルーチンはトランザクション・モードで呼び出されると、1つのトランザクションにしか参加できません。サービス・ルーチン作成者側から見るかぎり、トランザクションはサービス・ルーチンから返った時点で終了します。サービス・ルーチンは、トランザクション・モードで呼び出されなかった場合、tpbegin()、tpcommit()およびtpabort()を使用して必要な回数だけトランザクションを起動できます。ただし、トランザクションの終了にはtpreturn()を使用しません。したがって、サービス・ルーチン内から起動された未終了のトランザクションについて、tpreturn()を呼び出すと、エラーになります。
サービス・ルーチンは、1つの引数、つまりsvcinfoを使用して呼び出します。この引数は、サービス情報が定義された構造体を指すポインタです。この構造体には、次のメンバーが含まれます。
char name[128];
char *data;
long len;
long flags;
int cd;
long appkey;
CLIENTID cltid;
nameには、リクエスタがサービスの呼出しに使用したサービス名を指定します。
サービス・ルーチンに入った時点で設定されるflagsは、サービス・ルーチンが注目する必要のある属性を示します。flagsに指定できる値は、次のとおりです。
TPCONV
TPTRAN
TPNOREPLY
TPSENDONLY
TPRECVONLYと相互に排他的で、TPCONVが設定されているときにしか設定できません。
TPRECVONLY
TPSENDONLYと相互に排他的で、TPCONVが設定されているときにしか設定できません。
dataはリクエスト・メッセージのデータ部を指し、lenはデータの長さです。dataによって指されたバッファは、通信マネージャでtpalloc()により割り当てられたものです。このバッファのサイズは、ユーザーがtprealloc()を使用して大きくすることができます。ただし、これをユーザーが解放することはできません。このバッファは、サービス終了時にtpreturn()またはtpforward()に渡すようにしてください。異なるバッファをこれらのルーチンに渡すと、そのバッファはそれらによって解放されてしまいます。なお、dataによって指されるバッファは、このバッファがtpreturn()またはtpforward()に渡されない場合でも、次に出されたサービス・リクエストによって変更されてしまいます。dataは、リクエストとともにデータが渡されなかった場合にはNULLになります。この場合、lenは0になります。
TPCONVをflagsに設定する場合、cdに接続記述子を指定しますが、これはこの会話を開始したプログラムとのコミュニケーションを行うためにtpsend()およびtprecv()とともに使用します。
appkeyは、アプリケーション側で定義した認証サービスが要求クライアントに割り当てるアプリケーション・キーに設定します。このキー値は、このサービス・ルーチンのこの呼出し中になされたあらゆるサービス・リクエストとともに渡されます。アプリケーション認証サービスを通らないクライアントを起動する場合には、appkeyの値は -1になります。
cltidは、このサービス要求に対応する元のクライアントを示すユニークなクライアント識別子です。この構造体はatmi.hにのみ、アプリケーションが利用できるよう定義されているので、必要によりアプリケーション・サーバー間でクライアント識別子をやりとりすることができます。このため、以下に定義されているフィールドの意味は明記されていません。アプリケーション側ではCLIENTID構造体の内容を操作しないようにしてください。内容を操作してしまうと、この構造体自体が無効になってしまいます。CLIENTID構造体には、次のようなメンバーが含まれます。
C++では、サービス関数にCリンケージが必要なことに注意してください。これは、関数を'extern "C"'と宣言することで行うことができます。
サービス・ルーチンは呼出し側である通信マネージャのディスパッチャに値を返しません。このため、このルーチンはvoidとして宣言されます。しかし、サービス・ルーチンはtpreturn()またはtpforward()を使用して終了させるようになっています。会話型サービス・ルーチンの場合、tpreturn()を使用しなければならず、tpforward()を使用することはできません。サービス・ルーチンをtpreturn()またはtpforward()のいずれも使用せずに終了させる場合(すなわち、このルーチンがC言語のreturn文を使用するか、ごく単純に関数の実行に失敗した場合)、あるいはtpforward()が会話型サーバーから呼び出された場合、そのサーバーはログ・ファイルに警告メッセージを出し、サービス・エラーを発信元すなわちリクエスタに返します。また、従属接続に対するオープン接続はすべて、ただちに切断され、未終了の非同期応答は無効とマークされます。サーバーが異常終了時にトランザクション・モードにあった場合は、そのトランザクションは中断のみとしてマークされます。tpreturn()やtpforward()がサービス・ルーチンの外部から使用される場合(たとえば、クライアントやtpsvrinit()あるいはtpsvrdone()で)、これらのルーチンは単に終了するだけです。
tpreturn()はサービス・ルーチンを終了させるので、引数処理またはサービス処理の間に発生したエラーについて、関数の呼出し側に示すことはできません。このようなエラーが起こると、tpcall()またはtpgetrply()を使用してサービスの結果を受信するプログラムのためにtperrnoがTPESVCERRに設定されます。またイベントTPEV_SVCERRが、tpsend()またはtprecv()を使用するプログラムに、会話を通して送信されます。
tpalloc(3c)、tpbegin(3c)、tpcall(3c)、tpconnect(3c)、tpforward(3c)、tpreturn(3c)、servopts(5)
tpsetctxt() - 現在のアプリケーション関連に対するコンテキスト識別子の設定
#include <atmi.h>
int tpsetctxt(TPCONTEXT_Tcontext, longflags)
tpsetctxt()は、現在のスレッドが動作するコンテキストを定義します。この関数は、マルチスレッド環境ではスレッド単位で、非スレッド環境ではプロセス単位で動作します。
次にこのスレッドでOracle Tuxedo ATMIが呼び出されると、コンテキストが示すアプリケーションが参照されます。コンテキストは、同一プロセス内のスレッドでtpgetctxt()の呼出しを発行することによって提供されます。contextの値がTPNULLCONTEXTの場合、現在のスレッドはどのOracle Tuxedo ATMIコンテキストにも関連付けられません。
マルチコンテキスト・モードで動作しているプロセスの各スレッドでは、次の呼出しを発行するによって、TPNULLCONTEXT状態にすることができます。
tpsetctxt(TPNULLCONTEXT, 0)
TPINVALIDCONTEXTは、contextに入力できる有効な値ではありません。
TPINVALIDCONTEXT状態のスレッドは、ほとんどのATMI関数に対する呼出しを発行できません。(呼び出せる関数と呼び出せない関数のリストについては、「C言語アプリケーション・トランザクション・モニター・インタフェースについて」を参照してください)。このため、必要に応じてスレッドのTPINVALIDCONTEXT状態を終了させる必要があります。それには、コンテキストをTPNULLCONTEXTか別の有効なコンテキストに設定してtpsetctxt()を呼び出します。また、tpterm()関数を呼び出してTPINVALIDCONTEXT状態を終了させることもできます。
2番目の引数flagsは現在使用されていないので、0に設定します。
マルチスレッドのアプリケーション中のスレッドは、TPINVALIDCONTEXTを含め、どのコンテキスト状態で実行していても、tpsetctxt()の呼出しを発行できます。
tpsetctxt()は、正常終了時には0以外の値を返します。
異常終了すると、呼出しプロセスを元のコンテキストに置いたまま-1を返し、tperrnoを設定してエラー条件を示します。
異常終了時には、tpsetctxt()はtperrnoを次のいずれかの値に設定します。
TPEINVAL]
TPENOENT]
TPEPROTO]
tpsetctxt()が不正なコンテキストで呼び出されました。たとえば、(a)サーバーがディスパッチしたスレッドで呼び出された、(b) tpinit()を呼び出していないプロセスで呼び出された、(c) TPMULTICONTEXTSフラグを指定せずにtpinit()を呼び出したプロセスで呼び出された、または (d) TMNOTHREADS環境変数がオンになっているプロセスで複数のスレッドから呼び出された、などです。
TPESYSTEM]
TPEOS]
「C言語アプリケーション・トランザクション・モニター・インタフェースについて」、tpgetctxt(3c)
tpsetmbenc() - 型付きバッファにコード・セットのエンコード名を設定
#include <atmi.h>
extern int tperrno;
int
tpsetmbenc(char *bufp, char *enc_name, long flags)
この関数は、コードセットのエンコーディング名を設定またはリセットするために使用します。エンコーディング名は、入力型付きバッファとともに送信されます。これらのメッセージを受け取るプロセスは、tpgetmbenc()を使用してこのエンコーディング名を取得できます。
tpsetmbenc()は、Tuxedoシステム・リクエストに含めるコードセットのエンコード名を設定します。この関数で呼出し側のバッファにNULL以外のエンコード名を設定すると、その設定をリセットまたは解除するまで、(tpcall()、tpsend()によって)送信されるすべてのメッセージに、この文字列が入ります。tpalloc()の実行時に、TPMBENC環境変数で初期コードセットのエンコード名がMBSTRINGバッファに適用されます。エンコード名が未定義のMBSTRINGバッファは無効です。
引数bufpは、エンコード名で型付きバッファを指す有効なポインタです。
引数enc_nameは、コードセットのエンコードの識別に使用するエンコード名です。
引数flagsには、0またはRM_ENCを指定します。RM_ENCの場合、エンコード名がMBSTRINGバッファから削除され、引数enc_nameは無視されます。MBSTRINGバッファにエンコード名を設定しないと、_tmconvmb()による変換は失敗します。
正常終了の場合、tpsetmbenc()は値0を返します。エラーが発生した場合は、ゼロ以外の値を返し、tperrnoを設定してエラー条件を示します。この関数は、次の原因により異常終了する可能性があります。
TPEINVAL]
TPESYSTEM]
tpalloc(3c)、tpconvmb(3c)、tpgetmbenc(3c)、tpservice(3c)、tuxsetmbenc(3c)
tpsetrepos() - Tuxedoサービス・メタデータ・リポジトリ・ファイルからのサービス・パラメータ情報を追加、編集または削除します。
int tpsetrepos(char *reposfile, FBFR32* idata, FBFR32** odata)
tpsetrepos()は、TMMETADATA(5)によって提供される.TMMETAREPOSサービスに、代替リポジトリ・アクセス・インタフェースを提供します。これは、Tuxedoサービス・メタデータ・リポジトリ・ファイルのパラメータ情報を追加、編集または削除します。tpsetrepos()を使用するには、メタデータ・リポジトリ・ファイルが、要求元のネイティブ・クライアントまたはサーバーに存在している必要があります。このファイルにより、TMMETADATA(5)を開始していない場合でも、リポジトリ情報へのアクセスが可能になります。
tpsetrepos()は、Oracle Tuxedoネイティブ・ライブラリにリンクされたプロセスで使用できますが、Oracle Tuxedoワークステーション・ライブラリにリンクされたプロセスでは使用できません。
| 注意: | tpsetrepos()を使用して、JOLTリポジトリ・ファイルのサービス・パラメータ情報を追加、編集、または削除することはできません。 |
reposfile
idata
odata
「METAREPOS(5)」では、tpsetrepos()が使用するFML32バッファ形式について説明します。これは、MIB(5)で使用する形式と同じです。
tpsetrepos()は、成功した場合に0を返します。異常終了した場合は、tperrnoを設定し、-1を返します。ほとんどの異常終了では、Tuxedo MIBの場合と同様に、*odataのTA_ERRORフィールドに特定のエラーに関する情報が格納されています。
異常終了時には、tpsetrepos()はtperrnoを次のいずれかの値に設定します。
| 注意: | TPEINVALの場合を除き、odataは、エラー条件についてさらに詳しい情報が得られるように、サービス・エントリごとにTA_ERROR、TA_STATUSを含める形で変更されます。 |
[TPEINVAL]
[TPEMIB]
[TPEPROTO]
[TPEPERM]
[TPEOS]
[TPESYSTEM]
このインタフェースは、Oracle Tuxedoリリース9.0またはそれ以降でしか利用できません。
${TUXDIR}/lib/libtrep.a
${TUXDIR}/lib/libtrep.so.<rel>
${TUXDIR}/lib/libtrep.lib
buildclientを使用する場合は、ライブラリを手動でリンクする必要があります。この場合、-L${TUXDIR}/lib -ltrepを指定します。
tpgetrepos(3c)、tmloadrepos(1)、tmunloadrepos(1)、TMMETADATA(5)、『Oracle Tuxedoアプリケーションの設定』の「Tuxedoサービス・メタデータ・リポジトリの管理」
tpsetunsol() - 非請求メッセージの処理方式の設定
#include <atmi.h>
void (*tpsetunsol (void (_TMDLLENTRY *)(*disp) (char *data, long len, long flags))) (char *data, long len, long flags)
tpsetunsol()は、非請求メッセージがOracle Tuxedo ATMIシステムのライブラリによって受け取られる際に呼び出すルーチンをクライアントが指定できるようにします。tpsetunsol()の最初の呼出しの前に、Oracle Tuxedo ATMIシステムのライブラリがクライアントのために受け取った非請求メッセージは記録されますが、無視されます。NULL関数ポインタを使用するtpsetunsol()を呼び出した場合も、同じ結果になります。システムが通知や検出のために使用する方法は、アプリケーションのデフォルトの設定で決まります。このデフォルトは、クライアントごとに変更できます(「tpinit(3c)」を参照)。
tpsetunsol()の呼出し時に渡される関数ポインタは、所定のパラメータ定義に準拠している必要があります。Tuxedoライブラリと使用中のコードの間の適切な呼出し規約を取得するために、Windowsベースのオペレーティング・システムでは_TMDLLENTRYマクロが必要になります。UnixシステムではNULL文字列に拡張されるため、_TMDLLENTRYマクロは必要ありません。
dataは受け取った型付きバッファを指し、lenはそのデータの長さを指定します。flagsは現時点では使用されていません。dataは、通知と一緒にデータが渡されない場合にはNULLになります。dataは、クライアントが認識しないタイプ/サブタイプのバッファであることがありますが、その場合、メッセージ・データは不明瞭になります。
dataはアプリケーション・コードで解放することはできません。ただし、システムはこれを解放し、終了後、データ領域を無効にします。
アプリケーションの任意通知型メッセージ処理ルーチン内での処理は、Oracle Tuxedo ATMI関数tpalloc()、tpfree()、tpgetctxt()、tpgetlev()、tprealloc()およびtptypes()に限定されています。
マルチスレッド・プログラミング環境では、非請求メッセージ処理ルーチンがtpgetctxt()を呼び出して、別のスレッドを作成し、そのスレッドに適切なコンテキストのtpsetctxt()を呼び出し、新しいスレッドに、クライアントが使用できるATMI関数をすべて使用させることができます。
tpsetunsol()がコンテキストに関連していないスレッドから呼び出されると、新しく生成されるすべてのtpinit()コンテキストに対して、プロセスごとのデフォルトの非請求メッセージ・ハンドラが作成されます。これは、すでにシステムに関連付けられているコンテキストには影響しません。特定のコンテキストは、コンテキストがアクティブのときにtpsetunsol()を再度呼び出して、そのコンテキストの非請求メッセージ・ハンドラを変更することができます。プロセス単位のデフォルトの非請求メッセージ・ハンドラは、コンテキストに現在関連付けされていないスレッドでtpsetunsol()を再度呼び出すと、変更できます。
マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドはtpsetunsol()の呼出しを発行できません。
tpsetunsol()は、正常終了時には、非請求メッセージ処理ルーチンの以前の設定条件を返します(NULLも正常な戻り値の1つであり、メッセージ処理関数を事前に設定していなかったことを示します)。
異常終了すると、この関数はTPUNSOLERRを返し、tperrnoを設定してエラー条件を示します。
異常終了時には、tpsetunsol()はtperrnoを次のいずれかの値に設定します。
TPEPROTO]
TPESYSTEM]
TPEOS]
tpnotify(3c)で説明したインタフェースはすべて、ネイティブ・サイトのUNIXシステム・ベースのプロセッサおよびWindowsプロセッサ上で利用できます。さらに、ルーチンtpbroadcast()とtpchkunsol()は、関数tpsetunsol()ともとに、UNIXシステムおよびMS-DOSベースのプロセッサ上で利用することができます。
tpsign() - デジタル署名のための型付きメッセージ・バッファのマーク
#include <atmi.h>
int tpsign(char *data, TPKEYhKey, longflags)
tpsign()は、hKeyに関連するプリンシパルにかわって、デジタル署名のためのメッセージ・バッファをマーク(登録)します。
dataは、(1)以前tpalloc()を呼び出すプロセスによって割り当てられたメッセージ・バッファ、または(2)システムによって受信プロセスに渡されたメッセージ・バッファのうち、いずれかの有効な型付きメッセージ・バッファを指している必要があります。バッファの内容は、tpsign()を起動してから修正することができます。
dataが指すバッファがプロセスから伝送されると、デジタル署名登録リクエストに対して、公開鍵ソフトウェアがデジタル署名を生成し、メッセージ・バッファにアタッチします。デジタル署名によって、受信プロセスはメッセージの署名者(発信者)を検証することができます。
引数flagsは使用されません。この引数は将来の用途のために予約されており、0に設定します。
異常終了すると、この関数は -1を返し、tperrnoを設定してエラー条件を示します。
TPEINVAL]
TPESYSTEM]
tpkey_close(3c)、tpkey_open(3c)
#include <atmi.h>
int tpsprio(prio, flags)
tpsprio()は、カレント・コンテキストのカレント・スレッドが、次に送信または転送するリクエストの優先度を設定します。設定された優先度は、次に送信されるリクエストに対してのみ有効です。メッセージのキュー登録機能がインストールされている場合、優先度をtpenqueue()やtpdequeue()によってキューへ登録、または削除されたメッセージに対しても設定することができます。デフォルトでは、prioに正または負の値を設定することにより、サービスの優先度が、そのデフォルト値を基準として設定値の分だけ上下します。上限は100、下限は1で、100が最も高い優先度を表します。リクエストのデフォルトの優先度は、そのリクエストの送信先となるサービスによって決まります。このデフォルトの設定は、管理時に指定してもよいですし(「UBBCONFIG(5)」を参照)、システムの省略時値50を使用してもかまいません。tpsprio()は、tpconnect()またはtpsend()を介して送られるメッセージには影響しません。
メッセージは、10回に1回はFIFO方式に基づいて取り出されるため、優先度の低いメッセージがキューにいつまでも残されることはありません。優先度の低いインタフェースやサービスでは、レスポンス時間を問題にすべきではありません。
マルチスレッドのアプリケーションでは、tpsprio()はスレッド単位で動作します。
TPABSOLUTE
prioの絶対値で送信されます。prioの絶対値は1から100までの範囲内の数値とします(最も高い優先度は100です)。この範囲外の値を指定すると、デフォルトの値が使用されます。
マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドは、tpsprio()の呼出しを発行できません。
異常終了すると、tpsprio()は -1を返し、tperrnoを設定してエラー条件を示します。
異常終了時には、tpsprio()はtperrnoを次のいずれかの値に設定します。
TPEINVAL]
TPEPROTO]
TPESYSTEM]
TPEOS]
tpacall(3c)、tpcall(3c)、tpdequeue(3c)、tpenqueue(3c)、tpgprio(3c)
tpstrerror() - Oracle Tuxedo ATMIシステムのエラー・メッセージ文字列の取得
#include <atmi.h>
char *
tpstrerror(interr)
tpstrerror()はLIBTUX_CATからエラー・メッセージのテキストを取得するために使用します。errは、Oracle Tuxedo ATMIシステムの関数呼出しが -1またはその他の異常終了値を返した場合にtperrnoに設定されるエラー・コードです。
tpstrerror()によって戻されたポインタをuserlog()またはUNIX関数fprintf()に対する引数として使用できます。
マルチスレッドのアプリケーション中のスレッドは、TPINVALIDCONTEXTを含め、どのコンテキスト状態で実行していてもtpstrerror()の呼出しを発行できます。
正常終了すると、tpstrerror()はエラー・メッセージ・テキストを含む文字列を指すポインタを返します。
errが無効なエラー・コードであった場合は、tpstrerror()は、NULLを返します。
異常終了すると、tpstrerror()はNULLを返しますがtperrnoは設定しません。
#include <atmi.h>
.
.
.
char *p;
if (tpbegin(10,0) == -1) {
p = tpstrerror(tperrno);
userlog(“%s”, p);
(void)tpabort(0);
(void)tpterm();
exit(1);
}
userlog(3c)、Fstrerror、Fstrerror32(3fml)
tpstrerrordetail() - Oracle Tuxedo ATMIのエラーに関する詳細なメッセージ文字列の取得
#include <atmi.h>
char * tpstrerrordetail(interr, longflags)
tpstrerrordetail()は、Oracle Tuxedo ATMIシステム・エラーのエラー詳細テキストを取得するために使用します。errは、tperrordetail()によって戻される値です。
ユーザーは、tpstrerrordetail()が返したポインタをuserlog()またはfprintf()に対する引数として使用できます。
flagsは将来の使用を考慮して予約されているため、ゼロを指定してください。
マルチスレッドのアプリケーション中のスレッドは、TPINVALIDCONTEXTを含め、どのコンテキスト状態で実行していても、tpstrerrordetail()の呼出しを発行できます。
正常終了すると、この関数はエラー詳細メッセージ・テキストを含む文字列を指すポインタを戻します。
異常終了時(すなわちerrが無効なエラー・コードの場合)、tpstrerrordetail()はNULLを返します。
異常終了すると、tpstrerrordetail()はNULLを返し、tperrnoは設定しません。
#include <atmi.h> . . .
int ret;
char *p;
if (tpbegin(10,0) == -1) {
ret = tperrordetail(0);
if (ret == -1) {
(void) fprintf(stderr, “tperrordetail() failed!\n”);
(void) fprintf(stderr, “tperrno = %d, %s\n”,
tperrno, tpstrerror(tperrno));
}
else if (ret != 0) {
(void) fprintf(stderr, “errordetail:%s\n”,
tpstrerrordetail(ret, 0));
}
.
.
.
}
「C言語アプリケーション・トランザクション・モニター・インタフェースについて」、tperrordetail(3c)、tpstrerror(3c)、userlog(3c)、tperrno(5)
tpsubscribe() - イベントをサブスクライブする
#include <atmi.h>
long tpsubscribe(char *eventexpr, char *filter, TPEVCTL *ctl, long flags)
呼出し側はtpsubscribe()を使用して、eventexprで示されるイベントまたはイベントの集合をサブスクライブします。サブスクリプションは、Oracle Tuxedo ATMIのイベント・ブローカ、TMUSREVT(5)によって保持され、イベントがポストされたときにサブスクライバに通知するために、tppost()によって使用されます。それぞれのサブスクリプションには、通知メソッドを指定します。通知メソッドは、クライアント通知、サービス呼び出し、または安定ストレージ内のキューへのメッセージ登録の3つの内いずれかの形式をとります。通知メソッドはサブスクライバのプロセスのタイプとtpsubscribe()に渡された引数によって決まります。
サブスクライブするイベントまたはイベントの集合は、eventexprで指定します。eventexprには、最大で255文字の正規表現が入ったNULLで終了する文字列を指定します。たとえば、eventexprが「¥e¥e..*」であれば、呼出し側はシステムで生成されたすべてのイベントをサブスクライブします。eventexprが「¥e¥e.SysServer.*」であれば、呼出し側はシステムで生成されたサーバーに関連するすべてのイベントをサブスクライブします。eventexprが「[A-Z].*」であれば、呼出し側は先頭にA-Zを持つすべてのユーザー・イベント文字列をサブスクライブします。eventexprが「.*(ERR|err).*」である場合、呼出し側はサブストリングERRまたはerrのいずれかを含むすべてのユーザー・イベントを登録しています。たとえば、account_errorおよびERROR_STATEと呼ばれるイベントは、どちらも登録の対象となります。正規表現の詳細については、「正規表現」を参照してください。
filterを指定する場合は、ブール値のフィルタ・ルールを含む文字列を指定します。このルールは、イベント・ブローカがイベントをポストする前に正しく評価しなければなりません。ポストするイベントを受け取ると、EventBrokerはそのイベントのデータにフィルタ規則(存在する場合)を適用します。データがフィルタ・ルールのチェックにパスした場合、イベント・ブローカは通知メソッドを呼び出します。データがフィルタ・ルールを通過しない場合は、イベント・ブローカは対応する通知メソッドを呼び出しません。呼出し側は、異なるフィルタ・ルールを利用して同じイベントを何度でもサブスクライブすることができます。
フィルタ・ルールは、それが適用される型付きバッファに固有なものです。FMLバッファおよびVIEWバッファの場合は、フィルタ・ルールはそれぞれのブール式コンパイラ(それぞれFboolco(3fml)およびFvboolco(3fml)を参照)に渡すことができて、ポストされたバッファ(Fboolev(3fml)およびFboolev(3fml)を参照)に対して評価することができる文字列です。STRINGバッファの場合は、フィルタ・ルールは正規表現です。他のすべてのタイプのバッファの場合、カスタマイズしたフィルタ評価機構が必要です(カスタマイズしたフィルタ評価機構を追加する方法についての詳細は、buffer(3c)およびtypesw(5)を参照してください)。filterには、最大255文字のNULLで終了する文字列を指定します。
サブスクライバがOracle Tuxedo ATMIのクライアント・プロセスで、ctlがNULLの場合は、サブスクライブしているイベントがポストされたときに、イベント・ブローカはサブスクライバに非請求メッセージを送ります。この場合、eventexprに対して評価が成功するイベント名がポストされると、イベント・ブローカはeventexprに対応したフィルタ・ルールに対してポストされたデータをテストします。データがフィルタ・ルールによるチェックにパスした場合、あるいはそのイベントに対して適用すべきフィルタ・ルールが存在しない場合は、サブスクライバはイベントとそのデータ、および非請求メッセージを受け取ることになります。非請求メッセージを受け取るためには、クライアントは非請求通知処理ルーチンを(tpsetunsol()を利用して)登録しておく必要があります。Oracle Tuxedo ATMIシステムのサーバー・プロセスが、ctlパラメータをNULLにしてtpsubscribe()を呼び出した場合は、tpsubscribe()は異常終了してtperrnoをTPEPROTOに設定します。
非請求メッセージによってイベント通知を受け取るクライアントは、終了する前にイベント・ブローカのアクティブなサブスクリプションのリストから、そのサブスクリプションを削除する必要があります(詳細は、「tpunsubscribe(3c)」を参照してください)。クライアントは、tpunsubscribe()のワイルドカード・ハンドル、-1を使用することにより、非請求通知メソッドに関連するサブスクリプションを含むあらゆる「非永続的」サブスクリプションを削除することができます。プロセス終了後も存続するサブスクリプションおよびそれらに関連する通知メソッドについては、以下のTPEVPERSISTの説明を参照してください。クライアントが非持続型のサブスクリプションを削除せずに終了した場合は、イベント・ブローカはクライアントにアクセスできなくなったことを検出すると、そのクライアントのサブスクリプションを削除します。
サブスクライバが(プロセス・タイプにかかわらず)イベント通知をサービス・ルーチンまたは安定ストレージ内のキューに送りたい場合は、ctlパラメータは有効なTPEVCTL構造体を指さなければいけません。この構造体には次の要素が含まれます。
long flags;
char name1[128];
char name2[128];
TPQCTL qctl;
| 注意: | サービス名の長さは127バイト以内に制限されています。サービス名の長さが127バイトを超える場合は、TPEINVALが戻されます。 |
次に、ctlflags要素に指定する、イベントをサブスクライブするための制御オプションの有効なビットの一覧を示します。
TPEVSERVICE
ctlname1という名前のOracle Tuxedo ATMIシステムのサービス・ルーチンに送信したいことを示します。この場合、eventexprに対して評価が成功するイベント名がポストされると、イベント・ブローカはeventexprに対応したフィルタ・ルールに対してポストされたデータをテストします。データがフィルタ・ルールを通過する場合、またはイベントに対するフィルタ・ルールが存在しない場合は、サービス・リクエストはイベントとともにポストされたデータと合せてctlname1に送信されます。ctlname1のサービス名には、Oracle Tuxedo ATMIシステムの有効な任意のサービス名を指定することができ、このサービスはサブスクライブされたときにアクティブである場合もあれば、アクティブでない場合もあります。イベント・ブローカによって呼び出されたサービス・ルーチンは、応答データなしで戻ります。つまり、引数にNULLデータを指定してtpreturn()を呼び出すはずです。tpreturn()に渡されるデータはドロップされます。TPEVSERVICEとTPEVQUEUEを同時に指定することはできません。
TPEVTRANも同時にctlflagsに設定し、またtppost()を呼び出すプロセスがトランザクション・モードにある場合は、イベント・ブローカはサービス・ルーチンがポスト元のトランザクションの一部となるようにサブスクライブされたサービス・ルーチンを呼び出します。イベント・ブローカ(TMUSREVT(5))とサブスクライブされたサービス・ルーチンの両方が、トランザクションをサポートするサーバー・グループに属していなければなりません(詳細は、「UBBCONFIG(5)」を参照してください)。ctlflagsにTPEVTRANを設定していない場合は、イベント・ブローカは、サービス・ルーチンがポスト元のトランザクションの一部とならないように、サブスクライブされたサービス・ルーチンを呼び出します。
TPEVQUEUE
ctlname1という名前のキュー・スペース、およびctlname2という名前のキューへ登録することを希望していることを示します。この場合、eventexprに対して評価が成功するイベント名がポストされると、イベント・ブローカはeventexprに対応したフィルタ・ルールに対してポストされたデータをテストします。データがフィルタ・ルールを通過した場合、またはイベントに対応したフィルタ・ルールが存在しない場合は、イベント・ブローカはメッセージをイベントとともにポストされたデータと合せて、ctlname1という名前のキュー・スペース、およびctlname2という名前のキューに登録します。キュー・スペースとキューの名前は、Oracle Tuxedo ATMIシステムの有効な任意のキュー・スペースおよびキューの名前で、サブスクリプションの実行時に存在している場合と存在していない場合があります。
ctlqctlには、ポストされたイベントをイベント・ブローカがキューに登録することに関するオプションをさらに指定することができます。オプションを何も指定しない場合は、ctlqctl.flagsをTPNOFLAGSに設定する必要があります。それ以外の場合は、「tpenqueue(3c)」の「制御パラメータ」の項で説明しているようにオプションを設定できます(特に、tpenqueue(3c)への入力情報を制御するフラグの有効なリストを説明している項を参照してください)。TPEVSERVICEとTPEVQUEUEを同時に指定することはできません。 ctlflagsにTPEVTRANも同時に指定し、tppost()を呼び出すプロセスがトランザクション・モードにある場合は、イベント・ブローカは、ポストされたイベントとそのデータがポスト元のトランザクションの一部となるように、それらをキューに登録します。イベント・ブローカ(TMUSREVT(5))はトランザクションをサポートするサーバー・グループに属している必要があります(詳細は、「UBBCONFIG(5)」を参照してください)。ctlflagsにTPEVTRANを設定しない場合は、イベント・ブローカは、ポストされたイベントとそのデータがポスト元のトランザクションの一部とならないように、それらをキューに登録します。
TPEVTRAN
TPEVSERVICEまたはTPEVQUEUEのどちらかと同時に指定できます。
TPEVPERSIST
TPEVTRANと同時に指定し、イベントの通知時にリソースが利用できない場合は、イベント・ブローカはポスト元に戻り、トランザクションが中止しなければならないようにします。つまり、サブスクリプションが保持されている場合でも、リソースが使用できなければポスト元のトランザクションは失敗します。
イベント・ブローカのアクティブなサブスクリプションのリストに、tpsubscribe()がリクエストするサブスクリプションと一致するものがある場合は、この関数は失敗してtperrnoにTPEMATCHを設定します。サブスクリプションが既存のサブスクリプションと一致するためには、eventexprとfilterの両方が、イベント・ブローカのアクティブなサブスクリプションのリストにすでに存在するサブスクリプションのeventexprとfilterに一致する必要があります。また、通知メソッドによっては、サブスクリプションの一致を判断する際にこれ以外の基準も使用されます。
サブスクライバがOracle Tuxedo ATMIシステムのクライアント・プロセスで、(イベントがポストされたときに、呼出し側が任意通知を受け取るように) ctlにNULLを設定した場合は、システム定義によるそのクライアント識別子(CLIENTIDと呼ばれています)も一致を調べるために使用されます。つまりtpsubscribe()は、eventexpr、filter、および呼出し側のCLIENTIDが、イベント・ブローカにすでに知られているサブスクリプションが持つそれらの値と一致する場合に失敗します。
呼出し側がctlflagsをTPEVSERVICEに設定した場合、eventexpr、filter、およびctlname1で設定されるサービス名がイベント・ブローカのリストにすでに存在するサブスクリプションのそれらと一致すると、tpsubscribe()は失敗します。
安定ストレージ内のキュー、キュー・スペース、およびキューの名前へのサブスクリプションの場合は、一致を調べる際にeventexprおよびfilterに加えて相関識別子が使用されます。相関識別子を利用することにより、同じ送信先の、同じイベント式やフィルタ・ルールに対する複数のサブスクリプションを区別することができます。したがって、呼出し側がctlflagsにTPEVQUEUEを設定し、ctlqctl.flagsにTPQCOORIDが設定されなかった場合、eventexpr、filter、ctlname1に設定されたキュー・スペース名、およびctlname2に設定されたキュー名が、イベント・ブローカにすでに知られている(相関識別子が指定された)サブスクリプションが持つそれらの値と一致するとtpsubscribe()は失敗します。さらに、ctlqctl.flagsにTPQCOORIDが設定されている場合は、eventexpr、filter、ctlname1、ctlname2、およびctlqctl.corridがイベント・ブローカにすでに知られている(同じ相関識別子が指定された)サブスクリプションのデータと一致すると、tpsubscribe()は失敗します。
次に、tpsubscribe()に対して有効なflagsの一覧を示します。
TPNOBLOCK
tperrnoにはTPEBLOCKが設定されます。TPNOBLOCKが指定されていないときにブロッキング条件が存在すると、呼出し側は、その条件が解消されるか、またはタイムアウト(トランザクションまたはブロッキング)が発生するまではブロックされます。
TPNOTIME
TPSIGRSTRT
TPSIGRSTRTが指定されていない場合にシグナルがシステム・コールを中断させると、tpsubscribe()は異常終了し、tperrnoにはTPGOTSIGが設定されます。
マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドは、tpsubscribe()の呼出しを発行できません。
表12で説明する正規表現は、UNIXシステム・エディタ、ed(1)で使用されるパターンに似ています。一般的な正規表現のほか、代替演算子(|)も使用できます。ただし、全体的にほとんど変わりません。
正規表現(RE: Regular Expressions)は、次に示すいずれかの規則を1回以上適用して作成します。
優先順位のレベルは3つあります。結合の強さの順に並べると、次のようになります。
上記のとおり、かっこは優先順位が高いことを明示的に示すために使用します。
tpsubscribe()は正常終了すると、イベント・ブローカのアクティブなサブスクリプションのリストからこのサブスクリプションを削除するために使用できるハンドルを戻します。サブスクライバやその他のプロセスは、いずれも戻されたハンドルを利用してこのサブスクリプションを削除することができます。
異常終了すると、tpsubscribe()は -1を返し、tperrnoを設定してエラー条件を示します。
異常終了時には、tpsubscribe()はtperrnoを次のいずれかの値に設定します(特に記述した場合を除いては、エラーが呼出し側のトランザクションに影響を及ぼすことはありません)。
TPEINVAL]
TPENOENT]
TPELIMIT]
TPEMATCH]
TPEPERM]
TPETIME]
TPNOBLOCKまたはTPNOTIMEが指定されている場合は発生しません。 トランザクション・タイムアウトが発生した場合、トランザクションがアボートされない限り、新しいリクエストの送信や未処理の応答の受信はできず、TPETIMEが発生します。その例外とは、ブロックされず、応答を期待せず、かつ呼出し側のトランザクションのかわりに送信されない(つまり、TPNOTRAN、TPNOBLOCKおよびTPNOREPLYを設定してtpacall()を呼び出した場合の)リクエストです。 トランザクションATMI呼出しがトランザクション内部で失敗すると、そのトランザクションはTX_ROLLBACK_ONLY状態になります。ほとんどの場合、この状態はタイムアウトと同じものとして扱われます。このトランザクションの以降のATMI呼出しは、TPETIMEで失敗します(前の段落で説明した例外を除きます)。
TPEBLOCK]
TPGOTSIG]
TPEPROTO]
TPESYSTEM]
TPEOS]
buffer(3c)、tpenqueue(3c)、tppost(3c)、tpsetunsol(3c)、tpunsubscribe(3c)、Fboolco、Fboolco32、Fvboolco、Fvboolco32(3fml)、Fboolev、Fboolev32、Fvboolev、Fvboolev32(3fml)、EVENTS(5)、EVENT_MIB(5)、TMSYSEVT(5)、TMUSREVT(5)、tuxtypes(5)、typesw(5)、UBBCONFIG(5)
tpsuspend() - グローバル・トランザクションの中断
#include <atmi.h>
int tpsuspend(TPTRANID *tranid, long flags)
tpsuspend()を使用して、呼出し側のプロセス内でアクティブなトランザクションを中断します。tpbegin()により開始したトランザクションは、tpsuspend()で中断できます。中断を行ったプロセスまたは他のプロセスのいずれかがtpresume()を使用して、中断されたトランザクション上の作業を再開できます。tpsuspend()が復帰すると、呼出し側はトランザクション・モードではなくなります。ただし、トランザクションが中断されている間は、そのトランザクションに関係のあるリソース(データベース・ロックなど)はすべてアクティブな状態に保たれます。アクティブなトランザクションと同様、中断されたトランザクションにもトランザクションを最初にスタートする際に割り当てたトランザクション・タイムアウトの値が適用されます。
トランザクションを別のプロセスで再開するには、tpsuspend()の呼出し側が明示的にtpbegin()を呼び出すことによってトランザクションを起動している必要があります。tpsuspend()は、トランザクションの開始元以外のプロセスから呼び出すこともできます(たとえば、トランザクション・モードでリクエストを受信するサーバー)。後者の場合、tpsuspend()の呼出し側のみtpresume()を呼び出してトランザクションを再開することができます。このような方法が認められているのは、プロセスがトランザクションのスタートを一時中断し、そのトランザクションを終了する前に別のトランザクションをスタートさせ、作業を行えるようにするためです(エラーを記録するトランザクションを実行してから最初のトランザクションをロールバックする場合など)。
tpsuspend()は、中断されているトランザクションの識別子を、tranidで指される領域に返します。呼出し側はtranidが指す空間を割り当てなければなりません。tranidがNULLの場合はエラーです。
正常終了するためには、呼出し側はtpsuspend()を実行する前に、サーバーとの未終了のコミュニケーションをすべて完了している必要があります。つまり、呼出し側は、呼出し側のトランザクションに関連付けられていたtpacall()で送信したリクエストに対する応答を、すべて受け取っている必要があります。また、呼出し側は、呼出し側のトランザクションに関連のある会話型サービスとの接続を、すべてクローズしている必要があります(つまり、tprecv()はTPEV-SVCSUCCイベントを戻している必要があります)。この規則のいずれかが守られない場合には、tpsuspend()は失敗し、呼出し側の現在のトランザクションは中断されず、トランザクション・コミュニケーションの記述子は有効なままです。呼出し側のトランザクションに関連付けられていないコミュニケーション記述子は、tpsuspend()の結果に関係なく有効なままです。
flagsは将来使用するために予約されており、0に設定されます。
マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドは、tpsuspend()の呼出しを発行できません。
tpsuspend()は、グローバル・トランザクション内の複数のリソース・マネージャを含め、すべての参加リソース・マネージャに対して影響を与えることができます。
tpsuspend()はエラーの場合は -1を返し、tperrnoを設定してエラー条件を示します。
次の条件の場合、tpsuspend()は異常終了し、tperrnoを次の値に設定します。
TPEINVAL]
TPEABORT]
TPEPROTO]
TPESYSTEM]
TPEOS]
tpacall(3c)、tpbegin(3c)、tprecv(3c)、tpresume(3c)、tprmopen(3c)、tprmclose(3c)、tprmstart(3c)、tprmend(3c)
tpsvrdone() - Oracle Tuxedo ATMIシステム・サーバーの終了
#include <atmi.h>
void tpsvrdone(void)
Oracle Tuxedo ATMIシステムのサーバー用ルーチンは、サービス・リクエストの処理完了後、ルーチンを終了する前にtpsvrdone()を呼び出します。このルーチンを呼び出した時点では、サーバーはまだシステムの一部のままですが、それ独自のサービスは公開から外されています。このため、このルーチンで、Oracle Tuxedo ATMIシステムとのコミュニケーションとトランザクションの定義を行うことができます。ただし、接続がオープン状態にある場合、保留中の非同期応答がある場合、あるいはまだトランザクション・モードにある場合にtpsvrdone()が終了すると、Oracle Tuxedo ATMIシステムはその接続をクローズし、保留中の応答を無視し、サーバーが終了する前にトランザクションを中断させます。
サーバーがtmshutdown -yを呼び出して停止された場合、サービスは中断され、tpsvrdone()で通信したりトランザクションを開始する機能は制限されます。
アプリケーションがこのルーチンをサーバーで提供していない場合、Oracle Tuxedo ATMIシステムが提供するデフォルトのバージョンがかわりに呼び出されます。サーバーがシングル・スレッド・サーバーとして定義されている場合、デフォルトのtpsvrdone()はtpsvrthrdone()を呼び出し、デフォルト・バージョンのtpsvrthrdone()はtx_close()を呼び出します。サーバーがマルチスレッド・サーバーとして定義されている場合、各サーバーのディスパッチ・スレッドでtpsvrthrdone()が呼び出され、tpsvrdone()からは呼び出されません。サーバーがマルチスレッドかどうかに関わらず、デフォルトのtpsvrdone()はuserlogを呼び出し、サーバーが終了することを示します。
tpsvrdone()で呼び出された場合、tpreturn()とtpforward()は何も行わずただちに戻ります。
tpsvrthrdone(3c)、tpsvrthrinit(3c)、servopts(5)
tpsvrinit() - Oracle Tuxedoシステム・サーバーの初期化
#include <atmi.h>
int tpsvrinit(intargc, char **argv)
Oracle Tuxedo ATMIシステムのサーバー用ルーチンは、その初期化処理中にtpsvrinit()を呼び出します。このルーチンは、サーバーに制御が移った後、サービス・リクエストを処理する前に呼び出されます。このため、Oracle Tuxedo ATMIシステムとのコミュニケーションとトランザクションの定義をこのルーチンで行うことができます。ただし、接続がオープン状態にあるとき、保留中の非同期応答があるとき、あるいはまだトランザクション・モードにあるときにtpsvrinit()が戻った場合、Oracle Tuxedo ATMIシステムはその接続をクローズし、保留中の応答を無視し、サーバーが終了する前にトランザクションをアボートします。
アプリケーションがこのルーチンをサーバーで提供していない場合、Oracle Tuxedo ATMIシステムが提供するデフォルトのバージョンがかわりに呼び出されます。
サーバーがシングル・スレッド・サーバーとして定義されている場合、デフォルトのtpsvrinit()はtpsvrthrinit()を呼び出し、デフォルト・バージョンのtpsvrthrinit()はtx_open()を呼び出します。サーバーがマルチスレッド・サーバーとして定義されている場合、tpsvrthrinit()は各サーバーのディスパッチ・スレッドで呼び出されますが、tpsvrinit()からは呼び出されません。サーバーがシングル・スレッドかマルチスレッドかに関わらず、デフォルト・バージョンのtpsvrinit()はuserlog()を呼び出してサーバーが正常に開始したことを示します。
アプリケーション固有のオプションをサーバーに渡し、tpsvrinit()で処理させることができます(「servopts(5)」を参照)。このオプションはargcとargvを使用して渡します。getopt()がOracle Tuxedo ATMIシステムのサーバー用ルーチンで使用されているため、optarg()、optind()およびopterr()を使用してオプションの解析やエラー検出をtpsvrinit()で制御できます。
| 注意: | プログラムでtpsvrinit()を呼び出す場合は、ロング・ブロッキングを行わないでください。ロング・ブロッキングを行った場合、MP構成内の1つのリモート・サーバーがtpsvrinit()処理を行うと、tmbootを実行しても、同じノード上のほかのサーバーを起動できません。 |
tpsvrinit()でエラーが生じた場合、アプリケーションから -1を返して明示的にサーバーを終了させることができます(サービス・リクエストをとらずに)。アプリケーション自体ではexit()を呼び出さないようにしてください。
tpsvrinit()が-1を戻した場合、サーバーはシステムによって再起動されません。かわりに、管理者がtmbootを実行してサーバーを再起動する必要があります。
tpreturn()やtpforward()がサービス・ルーチンの外部(たとえば、クライアントやtpsvrinit()、あるいはtpsvrdone()で)使用された場合、tpreturn()およびtpforward()は何も行わずただちに戻ります。
tpopen(3c)、tpsvrdone(3c)、tpsvrthrinit(3c)、servopts(5)
C言語リファレンス・マニュアルのgetopt(3)
tpsvrthrdone() - Oracle Tuxedo ATMIサーバーのスレッドの終了
#include <atmi.h>
void tpsvrthrdone(void)
Oracle Tuxedo ATMIのサーバーでは、ディスパッチされたサービス・リクエストを処理するために開始された各スレッドを終了するときに、tpsvrthrdone()を呼び出します。つまり、スレッドがリクエストを処理する前に終了された場合でも、tpsvrdone()関数が呼び出されます。このルーチンが呼び出されたとき、対象のスレッドはまだOracle Tuxedo ATMIサーバーの一部ですが、すべてのサービス・リクエストの処理を終了しています。このため、Oracle Tuxedo ATMIとのコミュニケーションとトランザクションの定義をこのルーチンで行うことができます。ただし、接続がオープン状態にある場合や保留中の非同期応答がある場合、あるいはまだトランザクション・モードにある場合にtpsvrthrdone()が終了すると、Oracle Tuxedo ATMIシステムはその接続をクローズし、保留中の応答を無視し、サーバーが終了する前にトランザクションを異常終了させます。
アプリケーションがサーバー中にこのルーチンを記述していない場合、Oracle Tuxedo ATMIシステムによって提供されるデフォルト・バージョンのtpsvrthrdone()がかわりに呼び出されます。デフォルト・バージョンのtpsvrthrdone()では、tx_close()が呼び出されます。
tpsvrthrdone()は、シングルスレッド・サーバーでも呼び出されます。シングルスレッド・サーバーでは、tpsvrthrdone()はデフォルト・バージョンのtpsvrdone()から呼び出されます。複数のディスパッチ・スレッドが予測されるサーバーでは、tpsvrdone()はtpsvrthrdone()を呼び出しません。
tpsvrthrdone()から呼び出された場合、tpreturn()とtpforward()関数は単純に返るだけで影響はありません。
tpforward(3c)、tpreturn(3c)、tpsvrdone(3c)、tpsvrthrinit(3c)、tx_close(3c)、servopts(5)
tpsvrthrinit() - Oracle Tuxedo ATMIサーバーのスレッドの初期化
#include <atmi.h>
int tpsvrthrinit(intargc, char **argv)
Oracle Tuxedo ATMIのサーバーでは、ディスパッチされたサービス・リクエストを処理する各スレッドを初期化するときに、tpsvrthrinit()を呼び出します。このルーチンは、サーバーに制御が移った後、サービス・リクエストを処理する前に呼び出されます。このため、Oracle Tuxedo ATMIとのコミュニケーションとトランザクションの定義をこのルーチンで行うことができます。ただし、接続がオープン状態にある場合や保留中の非同期応答がある場合、あるいはまだトランザクション・モードにある場合にtpsvrthrinit()が終了すると、Oracle Tuxedo ATMIシステムはその接続をクローズし、保留中の応答を無視し、サーバーが終了する前にトランザクションを異常終了させます。
アプリケーションがサーバーにこのルーチンを提供していない場合、Oracle Tuxedo ATMIシステムによって提供されたデフォルト・バージョンのtpsvrthrinit()がかわりに呼び出されます。デフォルト・バージョンのtpsvrthrinit()はtx_open()を呼び出します。
tpsvrthrinit()は、シングル・スレッド・サーバーでも呼び出されます。シングル・スレッド・サーバーでは、tpsvrthrinit()はデフォルト・バージョンのtpsvrinit()から呼び出されます。複数のディスパッチ・スレッドが予測されるサーバーでは、tpsvrinit()はtpsvrthrinit()を呼び出しません。
アプリケーション固有のオプションをサーバーに渡し、tpsvrthrinit()で処理させることができます。オプションの詳細は、「servopts(5)」を参照してください。オプションはargcとargvを使用して渡します。getopt()がOracle Tuxedo ATMIシステムのサーバー用ルーチンで使用されているため、optarg()、optind()およびopterr()を使用してオプションの解析やエラー検出をtpsvrthrinit()で制御できます。
tpsvrthrinit()でエラーが生じた場合、アプリケーションから -1を返して正常に(サービス・リクエストをとらずに)サーバーのディスパッチ・スレッドを終了させることができます。アプリケーションが、exit()やその他オペレーティング・システムのスレッド終了関数を呼び出してはいけません。
負の戻り値によって、サーバーのディスパッチ・スレッドは正常に終了します。
サービス・ルーチンの外側で使用された場合(たとえば、クライアントまたはtpsvrinit()、tpsvrdone()、tpsvrthrinit()、tpsvrthrdone()で使用された場合)、tpreturn()とtpforward()関数は単純に返るだけで影響はありません。
tpforward(3c)、tpreturn(3c)、tpsvrthrdone(3c)、tpsvrthrinit(3c)、tx_open(3c)、servopts(5)
#include <atmi.h>
int tpterm(void)
tpterm()は、Oracle Tuxedo ATMIシステム・アプリケーションからクライアントを削除します。クライアントがトランザクション・モードであると、トランザクションはロールバックされます。tpterm()が正常に終了すると、呼出し側はOracle Tuxedo ATMIクライアント操作を実行できません。未終了の会話はただちに切断されます。
tpterm()を2回以上呼び出した場合(すなわち、呼出し側がすでにアプリケーションから離れた後で呼び出した場合)、何も処理は行われず、正常終了を示す値が返されます。
適切なプログラミングでは、1つを残して他のすべてのスレッドがコンテキストを終了または切り替えると、最後のスレッドがtpterm()呼出しを発行します。このようにプログラミングされていないと、残りのスレッドはTPINVALIDCONTEXTコンテキスト状態になります。次に、このコンテキストのセマンティクスを説明します。
複数のスレッドが関連するコンテキストにおいて、1つのスレッドでtpterm()が呼び出されると、このtpterm()は以下のように動作します。
別のスレッドがコンテキストを終了したときにATMI呼出し内でブロックされたスレッドがあると、そのスレッドはATMI呼出しから異常終了によって返され、tperrnoはTPESYSTEMに設定されます。また、このような異常終了の後でtperrordetail()が呼び出された場合、tperrordetail()はTPED_INVALIDCONTEXTを返します。
シングル・コンテキストのアプリケーションでは、単一のスレッドがtpterm()を呼び出すと、すべてのスレッドのコンテキスト状態がTPNULLCONTEXTに設定されます。
それに対して、マルチコンテキストのアプリケーションでは、tpterm()が1つのスレッドで呼び出されると、同じコンテキスト内の他のすべてのスレッドは、ほとんどのATMI関数を呼び出しても異常終了し、tperrnoがTPEPROTOに設定されるような状態になります。このような無効なコンテキスト状態で使用できる関数と使用できない関数のリストについては、「C言語アプリケーション・トランザクション・モニター・インタフェースについて」を参照してください。無効なコンテキスト状態(TPINVALIDCONTEXT)のスレッドがtpgetctxt()関数を呼び出した場合、tpgetctxt()によってコンテキストのパラメータがTPINVALIDCONTEXTに設定されます。
TPINVALIDCONTEXT状態を終了させるには、次の関数のどちらかを呼び出します。
TPINVALIDCONTEXTコンテキストを設定してtpsetctxt()を呼び出すことはできません。このような場合は、異常終了してtperrnoがTPEPROTOに設定されます。呼出し側とアプリケーションを関連させる必要がないtpsetunsol()以外のATMI関数をスレッドが呼び出すと、ATMI関数はNULLコンテキストで呼び出されたときと同じように動作します。非請求のスレッド通知を使用するクライアント・アプリーションは、tpterm()を明示的に呼び出して、非請求スレッドを終了する必要があります。
tpterm()呼出し後、スレッドはTPNULLCONTEXTコンテキスト状態になります。TPNULLCONTEXTコンテキストのスレッドで呼び出されるATMI関数の多くは、暗黙的なtpinit()を実行します。tpinit()の呼出しが成功するかどうかは、コンテキスト固有の問題やスレッド固有の問題ではなく、通常の要因によって決まります。
マルチスレッドのアプリケーション中のスレッドは、TPINVALIDCONTEXTを含め、どのコンテキスト状態で実行していても、tpterm()の呼出しを発行できます。
シングルコンテキスト・アプリケーションで正常に終了すると、現在のコンテキストがTPNULLCONTEXT状態になります。
マルチコンテキストのアプリケーションで正常終了すると、呼出し側のスレッドはTPNULLCONTEXT状態になり、呼出し側のスレッドと同じコンテキスト内の他のスレッドはすべてTPINVALIDCONTEXT状態になります。後者のスレッドのコンテキスト状態は、引数contextをTPNULLCONTEXTか別の有効なコンテキストに設定してtpsetctxt()を実行すれば変更できます。
異常終了すると、tpterm()は呼出し側のプロセスを元のコンテキスト状態のままで -1を返し、tperrnoを設定してエラー条件を示します。
異常終了時には、tpterm()はtperrnoを次のいずれかの値に設定します。
TPEPROTO]
TPESYSTEM]
TPEOS]
tpinit(3c)、tpgetctxt(3c)、tpsetctxt(3c)、tpsetunsol(3c)
tptypes() - 型付きバッファ情報を判別するルーチン
#include <atmi.h>
long tptypes(char *ptr, char *type, char *subtype)
tptypes()は、その第1引数として、データ・バッファを指すポインタをとり、2番目と3番目の引数でそれぞれタイプとサブタイプを返します。ptrは、tpalloc()から得たバッファを指していなければなりません。typeとsubtypeがNULLでない場合、この関数は、そのバッファのタイプとサブタイプの名前をそれぞれ該当する文字配列に入れます。これらの名前が最大長であると(typeの場合は8、subtypeの場合は16)、この文字配列はNULLで終了しません。また、サブタイプが存在しない場合は、subtypeが指す配列にはNULL文字列が入ります。
なお、typeの場合は最初の8バイト、subtypeの場合は最初の16バイトが格納されます。
マルチスレッドのアプリケーション中のスレッドは、TPINVALIDCONTEXTを含め、どのコンテキスト状態で実行していても、tptypes()の呼出しを発行できます。
正常終了の場合、tptypes()はバッファのサイズを返します。
異常終了すると、この関数は -1を返し、tperrnoを設定してエラー条件を示します。
エラーが発生すると、tptypes()はtperrnoを次のいずれかの値に設定します。
TPEINVAL]
TPEPROTO]
TPESYSTEM]
TPEOS]
tpalloc(3c)、tpfree(3c)、tprealloc(3c)
tpunadvertise() - サービス名の公開解除を行うルーチン
#include <atmi.h>
int tpunadvertise(char *svcname)
tpunadvertise()を使用すると、サーバーは、提供するサービスの通知を取り消すことができます。デフォルトでは、サーバーのサービスは、サーバーのブート時に通知され、サーバーの停止時にその通知が取り消されます。
複数サーバー単一キュー(MSSQ)セットに属するすべてのサーバーは、同じサービス・セットを提供しなければなりません。これらのルーチンは、MSSQセットを共有する全サーバーを公開することによってこの規則を適用します。
tpunadvertise()は、該当サーバー(または、呼出し側のMSSQセットを共有するサーバー・セット)に対して通知されたサービスとしてsvcnameを削除します。svcnameにはNULLまたはNULL文字列("")は指定できません。また、svcnameは127文字以下で指定する必要があります。(「UBBCONFIG(5)」の*SERVICESの項を参照)。これ以上の長さの名前でも受け付けられますが、127文字に切り詰められます。このため、切り詰められた名前が他のサービス名と同じにならないよう、注意が必要です。
異常終了すると、tpunadvertise()は -1を返し、tperrnoを設定してエラー条件を示します。
失敗すると、tpunadvertise()はtperrnoを次のいずれかの値に設定します。
TPEINVAL]
TPENOENT]
TPEPROTO]
TPESYSTEM]
TPEOS]
TPUNSUBSCRIBE() - イベントのサブスクリプションを削除します。
#include <atmi.h>
int tpunsubscribe(long subscription, long flags)
呼出し側はtpunsubscribe()を使用して、Oracle Tuxedo EventBrokerのアクティブなサブスクリプションのリストからイベントのサブスクリプションまたはイベントのサブスクリプションの集合を削除します。subscriptionには、tpsubscribe()が返したイベントのサブスクリプションのハンドルを指定します。subscriptionをワイルドカード値の -1に設定すると、tpunsubscribe()が、呼出し側のプロセスが以前に行ったすべての非持続型のサブスクリプションを削除する指示になります。非持続型のサブスクリプションとは、tpsubscribe()のctlflagsパラメータにTPEVPERSISTビットを設定せずに行われたサブスクリプションのことです。持続タイプのサブスクリプションは、tpsubscribe()から返されたハンドルを使用することによってのみ削除できます。
ハンドル -1を指定すると、呼出し側のプロセスが行ったサブスクリプションのみを削除し、呼出し側が以前に起動されたときに行ったサブスクリプションは削除しないことに注意してください(たとえば、異常終了した後で再起動したサーバーでは、ワイルドカードを使用して以前のサーバーが行ったサブスクリプションを削除することはできません)。
TPNOBLOCK
tperrnoにはTPEBLOCKが設定されます。TPNOBLOCKが指定されていないときにブロッキング条件が存在すると、呼出し側は、その条件が解消されるか、またはタイムアウト(トランザクションまたはブロッキング)が発生するまではブロックされます。
TPNOTIME
TPSIGRSTRT
TPSIGRSTRTが指定されていない場合にシグナルがシステム・コールを中断させると、tpunsubscribe()は異常終了し、tperrnoにはTPGOTSIGが設定されます。
マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドは、tpunsubscribe()の呼出しを発行できません。
tpunsubscribe()が成功して戻ると、tpurcode()にはイベント・ブローカのアクティブなサブスクリプションのリストから削除されたサブスクリプションの数(0または1以上)が指定されます。tpurcode()に1より大きな数が設定されるのは、ワイルドカードのハンドルを-1に指定した場合のみです。また、tpunsubscribe()が失敗して終了した場合にも、tpurcode()に1より大きな数が設定されることがあります(つまり、ワイルドカードのハンドルを指定して、イベント・ブローカがいくつかのサブスクリプションの削除に成功した後で、他のサブスクリプションを削除する際にエラーが発生したような場合です)。
失敗すると、tpunsubscribe()は-1を戻し、tperrnoを設定してエラー条件を示します。
異常終了時には、tpunsubscribe()はtperrnoを次のいずれかの値に設定します(特に記述した場合を除いては、エラーが呼出し側のトランザクションに影響を及ぼすことはありません)。
TPEINVAL]
TPENOENT]
TPETIME]
TPNOBLOCKまたはTPNOTIMEが指定されている場合は発生しません。) トランザクション・タイムアウトが発生した場合、トランザクションがアボートされない限り、新しいリクエストの送信や未処理の応答の受信はできず、TPETIMEが発生します。その例外とは、ブロックされず、応答を期待せず、かつ呼出し側のトランザクションのかわりに送信されない(つまり、TPNOTRAN、TPNOBLOCKおよびTPNOREPLYを設定してtpacall()を呼び出した場合の)リクエストです。 トランザクションATMI呼出しがトランザクション内部で失敗すると、そのトランザクションはTX_ROLLBACK_ONLY状態になります。ほとんどの場合、この状態はタイムアウトと同じものとして扱われます。このトランザクションの以降のATMI呼出しは、TPETIMEで失敗します(前の段落で説明した例外を除きます)。
TPEBLOCK]
TPGOTSIG]
TPEPROTO]
TPESYSTEM]
TPEOS]
tppost(3c)、tpsubscribe(3c)、EVENTS(5)、EVENT_MIB(5)、TMSYSEVT(5)、TMUSREVT(5)
tputrace() - ユーザー定義のトレース情報のアプリケーション
#include <atmi.h>
int tputrace (char *trrec, int nest, char *category, char *funcname, int utrtype, va_list args)
tputrace(3c)は、詳細なトレース出力情報(ATMI関数との間でやり取りする完全なユーザー・データの内容など)のモニターおよび取得方法を柔軟に設定できるユーザー定義のAPIで、この情報をどのように、またどこに出力するかを定義します。デフォルトでは、更新したり別にものに変更したりしないかぎり、tputrace()は、トレース・レコード情報をuserlog(3c)に出力します。
tputrace(3c)は、TMTRACEを指定した受信側utraceを指定することで排他的に呼び出されます。たとえば、TMTRACE=atmi:utraceです。utraceの受信側を指定すると、atmiトレース・カテゴリ・レコードに対してのみtputrace(3c)が自動的に呼び出されて出力されます。TMTRACEおよびutrace受信側の詳細は、『ファイル形式、データ記述、MIBおよびシステム・プロセス・リファレンス』の「tmtrace(5)」を参照してください。
trrec
ttrecは、tputrace(3c)の最初の引数として必ず指定されます。trrecをuserlogに出力すると、tmtrace(5)と同じ結果になります。
nest
category
funcname
utrtype
args
tputrace(3c)出力関数に渡す引数を定義します。これには、ATMI関数に渡されるユーザー・データまたはフラグが含まれます。「使用例」のtputrace()の実装例で、各ATMI関数の引数の一覧を示します。引数の一覧は、tmtrace(5)トレース情報出力でも参照できます。
独立したTuxedoライブラリであるlibutraceは、tputrace()と組み合せて使用します。デフォルトのlibutraceは、Tuxedoシステム共有ライブラリ・ディレクトリ(UNIXの場合は$TUXDIR/lib、Windowsの場合は%TUXDIR%\bin)にインストールされます。
ユーザーは、独自のカスタムlibutraceライブラリを作成し、それを次のいずれかにインストールすることもできます。
システム・ディレクトリにインストールされたカスタムlibutraceライブラリは、デフォルトlibutraceにかわって、マシン上のすべてのTuxedoクライアントおよびサーバーで使用されます。アプリケーション・ディレクトリにインストールされたカスタムlibutraceライブラリは、そのアプリケーションのクライアントおよびサーバーにのみ使用されます。
tputrace()を変更した場合には、libutraceライブラリを必ず再コンパイルしてTuxedo 9.0以上にリンクする必要があります。サンプルのtputrace()ソース・ファイルは、$TUXDIR/samples/atmi/libutraceディレクトリにあります。
「使用例」では、詳細なtputrace()のカスタマイズ方法を示します。
| 警告: | デフォルトまたはカスタムのlibutraceライブラリは、BBLまたはWSLなどのシステム・サーバーを含むすべてのTuxedoアプリケーション・プロセスにロードされます。そのため、すべてのTuxedoシステム・サーバーは、libutraceのロードに多少のメモリーを消費します。デフォルトのlibutraceライブラリは非常に小さいため、メモリー消費は無視することができます。ただし、カスタムのlibutraceは、ユーザーが追加する機能の数によっては、多くのメモリー容量を消費する可能性があります。 |
この例は、Tuxedo simpappサンプル・プログラムのsimpclの実行に対する、ユーザー・レベルのトレース情報userlogの出力を示しています。
ユーザー・レベル・トレース情報をカスタマイズして出力するには、以下の操作を行う必要があります。
TMTRACE=atmi:utraceを指定した場合、ATMI関数に渡されるユーザー・データの内容とフラグがTuxedo userlogに書き込まれます。
091206.HOST1!?proc.1560.1520.0: UTRAC:at: } tpinit = 1
091206.HOST1!?proc.1560.1520.0: UTRAC:at: { tpalloc("STRING", "", 7)
091206.HOST1!?proc.1560.1520.0: UTRAC:at: } tpalloc = 0x86a8e8
091206.HOST1!?proc.1560.1520.0: UTRAC:at: { tpalloc("STRING", "", 7)
091206.HOST1!?proc.1560.1520.0: UTRAC:at: } tpalloc = 0x87fa20
091206.HOST1!?proc.1560.1520.0: UTRAC:at: { tpcall(
091206.HOST1!?proc.1560.1520.0: UTRAC:at: svc="TOUPPER"
091206.HOST1!?proc.1560.1520.0: UTRAC:at: idata=(0x86a8e8){
091206.HOST1!?proc.1560.1520.0: UTRAC:at: len=0
091206.HOST1!?proc.1560.1520.0: UTRAC:at: type="STRING"
091206.HOST1!?proc.1560.1520.0: UTRAC:at: value="abcdef"
091206.HOST1!?proc.1560.1520.0: UTRAC:at: }
091206.HOST1!?proc.1560.1520.0: UTRAC:at: odata=(0x12ff48){
091206.HOST1!?proc.1560.1520.0: UTRAC:at: data=(0x87fa20){
091206.HOST1!?proc.1560.1520.0: UTRAC:at: len=0
091206.HOST1!?proc.1560.1520.0: UTRAC:at: type="STRING"
091207.HOST1!?proc.1560.1520.0: UTRAC:at: }
091207.HOST1!?proc.1560.1520.0: UTRAC:at: len=(0x12ff44)0
091207.HOST1!?proc.1560.1520.0: UTRAC:at: }
091207.HOST1!?proc.1560.1520.0: UTRAC:at: flags=<none>
091207.HOST1!?proc.1560.1520.0: UTRAC:at: )
091207.HOST1!simpserv.760.2188.0: UTRAC:at: { tpservice(
091207.HOST1!simpserv.760.2188.0: UTRAC:at: svcinfo=(0x5e1518){
091207.HOST1!simpserv.760.2188.0: UTRAC:at: name="TOUPPER"
091207.HOST1!simpserv.760.2188.0: UTRAC:at: flags=<none>
091207.HOST1!simpserv.760.2188.0: UTRAC:at: data=(0x602820){
091207.HOST1!simpserv.760.2188.0: UTRAC:at: len=7
091207.HOST1!simpserv.760.2188.0: UTRAC:at: type="STRING"
091207.HOST1!simpserv.760.2188.0: UTRAC:at: value="abcdef"
091207.HOST1!simpserv.760.2188.0: UTRAC:at: }
091207.HOST1!simpserv.760.2188.0: UTRAC:at: cd=0
091207.HOST1!simpserv.760.2188.0: UTRAC:at: appkey=0
091207.HOST1!simpserv.760.2188.0: UTRAC:at: cltid=(0x5e154c){1095811926,0,12,0}
091207.HOST1!simpserv.760.2188.0: UTRAC:at: }
091207.HOST1!simpserv.760.2188.0: UTRAC:at: )
091207.HOST1!simpserv.760.2188.0: UTRAC:at: { tpreturn(
091207.HOST1!simpserv.760.2188.0: UTRAC:at: rval=TPSUCCESS
091207.HOST1!simpserv.760.2188.0: UTRAC:at: rcode=0
091207.HOST1!simpserv.760.2188.0: UTRAC:at: data=(0x602820){
091207.HOST1!simpserv.760.2188.0: UTRAC:at: len=0
091207.HOST1!simpserv.760.2188.0: UTRAC:at: type="STRING"
091207.HOST1!simpserv.760.2188.0: UTRAC:at: value="ABCDEF"
091207.HOST1!simpserv.760.2188.0: UTRAC:at: }
091207.HOST1!simpserv.760.2188.0: UTRAC:at: flags=<none>
091207.HOST1!simpserv.760.2188.0: UTRAC:at: )
091207.HOST1!?proc.1560.1520.0: UTRAC:at: } tpcall(
091207.HOST1!?proc.1560.1520.0: UTRAC:at: ret=0
091207.HOST1!?proc.1560.1520.0: UTRAC:at: odata=(0x12ff48){
091207.HOST1!?proc.1560.1520.0: UTRAC:at: data=(0x881690){
091207.HOST1!?proc.1560.1520.0: UTRAC:at: len=7
|091207.HOST1!?proc.1560.1520.0: UTRAC:at: type="STRING"
091207.HOST1!?proc.1560.1520.0: UTRAC:at: value="ABCDEF"
091207.HOST1!?proc.1560.1520.0: UTRAC:at: }
091207.HOST1!?proc.1560.1520.0: UTRAC:at: len=(0x12ff44)7
091207.HOST1!simpserv.760.2188.0: UTRAC:at: } tpreturn [long jump]
091207.HOST1!?proc.1560.1520.0: UTRAC:at: }
091207.HOST1!?proc.1560.1520.0: UTRAC:at: )
091207.HOST1!?proc.1560.1520.0: UTRAC:at: { tpfree(0x86a8e8)
091207.HOST1!?proc.1560.1520.0: UTRAC:at: } tpfree
091207.HOST1!?proc.1560.1520.0: UTRAC:at: { tpfree(0x881690)
091207.HOST1!?proc.1560.1520.0: UTRAC:at: } tpfree
091207.HOST1!simpserv.760.2188.0: UTRAC:at: } tpservice
091207.HOST1!?proc.1560.1520.0: UTRAC:at: { tpterm()
091207.HOST1!?proc.1560.1520.0: UTRAC:at: } tpterm = 1
091207.HOST1!?proc.1560.1520.-2: UTRAC:at: { tpterm()
091207.HOST1!?proc.1560.1520.-2: UTRAC:at: } tpterm = 1
tmutrace(3c)は、正常に実行された場合に0、障害が発生した場合に-1を返します。
障害は、tputrace()ユーザー・レベルの実装/カスタマイズによって異なります。Tuxedo 9.0以上に付属のデフォルトtputrace()実装では、障害は発生しません。
「userlog(3c)」
tpxmltofml32() - XMLデータをFML32バッファに変換
#include <fml32.h>
int tpxmltofml32 (char *xmlbufp, char *vfile, FBFR32 **fml32bufp, char **rtag, long flags)
この関数は、XMLバッファをFML32バッファに変換するために使用します。次の引数を使用できます。
xmlbufp
vfile
TPXPARSNSPACEフラグとTPXPARSDOSCHEフラグを設定する必要があります。TPXPARSNEVERフラグは設定しないでください。
fml32bufp
rtag
flags
flagsの一覧を示します。
| 注意: | 同時に使用した場合、TPXPARSNEVERはTPXPARSALWAYSよりも優先されます。 |
setValidationSchemaFullCheckingをtrueに設定します。このフラグを使用すると、完全なスキーマ制約チェックをオンまたはオフにできます。スキーマ検証が有効な場合にのみ機能します。オフにした場合は、部分的な制約チェックが実行されます。完全なスキーマ制約チェックには、多くの時間またはメモリーが必要なものもあります。現在、このオプションでは、微細な固有属性チェックと派生制約チェックを制御します。
setValidationConstraintFatalをtrueに設定します。このフラグを使用すると、検証制約エラーが発生した場合のパーサーの動作を設定できます。trueに設定した場合、パーサーは、検証エラーを致命的として処理し、getExitOnFirstFatalErrorの状態に従って終了します。falseに設定した場合は、エラーを報告し、処理を続行します。
setDoNamespacesをtrueに設定します。このフラグを使用すると、パーサーによるネームスペースの処理を有効または無効にできます。trueに設定した場合、パーサーは、NameSpace仕様で指定したすべての制約とルールを適用します。
| 注意: | trueに設定した場合は、ネームスペースの処理もオンになっている必要があります。 |
setCreateEntityReferencNodesをfalseに設定します。このフラグを使用すると、生成中のDOMツリーでパーサーがエンティティ参照ノードを作成するかどうかを指定できます。このフラグがtrueの場合、パーサーは、DOMツリーにEntityReferenceノードを作成します。EntityReferenceノードとその子ノードは読取り専用です。このフラグがfalseの場合、EntityReferenceノードは作成されません。エンティティの代替テキストが、エンティティ参照ノードの子として追加されるか、所定の参照の位置に挿入されます。
setExitOnFirstFatalErrorをfalseに設定します。このフラグを使用すると、最初に致命的なエラーが発生した場合のパーサーの動作を設定できます。trueに設定した場合、パーサーは最初の致命的なエラーで終了します。falseに設定した場合は、エラーを報告し、処理を続行します。
setIncludeIgnorableWhitespaceをfalseに設定します。このフラグを使用すると、無視できる余白をテキスト・ノードとして検証パーサーに含めるかどうかを指定できます。非マークアップ・テキストを常に含む非検証パーサーには無効です。
setcacheGrammarFromParseをtrueに設定します。このフラグを使用すると、XMLドキュメントを解析する際の文法のキャッシュを有効または無効にできます。trueに設定すると、パーサーは、結果の文法を以降の解析で使用するためにキャッシュします。フラグをtrueに設定した場合、Useキャッシュ文法フラグもtrueに設定されます。
成功した場合、tpxmltofml32()は0を返します。この関数は、エラー発生時に-1を返し、tperrnoを設定してエラー条件を示します。
TPEINVAL]
TPESYSTEM]
userlog(3)に書き込まれます。これは、FML32への変換を実行できなかった時期も示します。そのインスタンスでは、エラーの詳細な情報がuserlogに追加されます。
TPEOS]
tpfml32toxml(3c)、tpxmltofml(3c)、tpfmltoxml(3c)
tpxmltofml() - XMLデータをFMLバッファに変換
#include <fml.h>
int tpxmltofml (char *xmlbufp, char *vfile, FBFR **fmlbufp, char **rtag, long flags)
この関数は、XMLデータをFMLバッファに変換するために使用します。以下の引数を使用できます。
xmlbufp
vfile
TPXPARSNSPACEフラグとTPXPARSDOSCHEフラグを設定する必要があります。TPXPARSNEVERフラグは設定しないでください。
fmlbufp
rtag
flags
flagsの一覧を示します。
| 注意: | 同時に使用した場合、TPXPARSNEVERはTPXPARSALWAYSよりも優先されます。 |
setValidationSchemaFullCheckingをtrueに設定します。このフラグを使用すると、完全なスキーマ制約チェックをオンまたはオフにできます。スキーマ検証が有効な場合にのみ機能します。オフにした場合は、部分的な制約チェックが実行されます。完全なスキーマ制約チェックには、多くの時間またはメモリーが必要なものもあります。現在、このオプションでは、微細な固有属性チェックと派生制約チェックを制御します。
setValidationConstraintFatalをtrueに設定します。このフラグを使用すると、検証制約エラーが発生した場合のパーサーの動作を設定できます。trueに設定した場合、パーサーは、検証エラーを致命的として処理し、getExitOnFirstFatalErrorの状態に従って終了します。falseに設定した場合は、エラーを報告し、処理を続行します。
setDoNamespacesをtrueに設定します。このフラグを使用すると、パーサーによるネームスペースの処理を有効または無効にできます。trueに設定した場合、パーサーは、NameSpace仕様で指定したすべての制約とルールを適用します。
| 注意: | trueに設定した場合は、ネームスペースの処理もオンになっている必要があります。 |
setCreateEntityReferencNodesをfalseに設定します。このフラグを使用すると、生成中のDOMツリーでパーサーがエンティティ参照ノードを作成するかどうかを指定できます。このフラグがtrueの場合、パーサーは、DOMツリーにEntityReferenceノードを作成します。EntityReferenceノードとその子ノードは読取り専用です。このフラグがfalseの場合、EntityReferenceノードは作成されません。エンティティの代替テキストが、エンティティ参照ノードの子として追加されるか、所定の参照の位置に挿入されます。
setExitOnFirstFatalErrorをfalseに設定します。このフラグを使用すると、最初に致命的なエラーが発生した場合のパーサーの動作を設定できます。trueに設定した場合、パーサーは最初の致命的なエラーで終了します。falseに設定した場合は、エラーを報告し、処理を続行します。
setIncludeIgnorableWhitespaceをfalseに設定します。このフラグを使用すると、無視できる余白をテキスト・ノードとして検証パーサーに含めるかどうかを指定できます。非マークアップ・テキストを常に含む非検証パーサーには無効です。
setcacheGrammarFromParseをtrueに設定します。このフラグを使用すると、XMLドキュメントを解析する際の文法のキャッシュを有効または無効にできます。trueに設定すると、パーサーは、結果の文法を以降の解析で使用するためにキャッシュします。フラグをtrueに設定した場合、Useキャッシュ文法フラグもtrueに設定されます。
正常終了の場合、tpxmltofml()は値0を返します。エラーが発生した場合は、-1を返し、tperrnoを設定してエラー条件を示します。
[TPEINVAL]
TPESYSTEM]
userlog(3c)に書き込まれます。これは、FMLへの変換を実行できなかった時期も示します。そのインスタンスでは、エラーの詳細な情報がuserlogに追加されます。
TPEOS]
tpxmltofml32(3c)、tpfml32toxml(3c)、tpfmltoxml(3c)
#include <texc.h>
TRYtry_block
[ CATCH(exception_name)handler_block] ...
[CATCH_ALLhandler_block]
ENDTRY
TRYtry_block
FINALLYfinally_block
ENDTRY
RAISE(exception_name)
RERAISE
/* declare exception */
EXCEPTIONexception_name;
/* initialize address (application) exception */
EXCEPTION_INIT(EXCEPTIONexception_name)
/* intialize status exception (map status to exception */
exc_set_status(EXCEPTION *exception_name, longstatus)
/* map status exception to status */
exc_get_status(EXCEPTION *exception_name, long *status)
/* compare exceptions */
exc_matches(EXCEPTION *e1, EXCEPTION *e2)
/* print error to stderr */
void exc_report(EXCEPTION *exception)
TRY/CATCHインタフェースは、ステータス変数(たとえば、errnoやRPCオペレーションで返されるステータス変数)を使用せずに例外を処理する機能を提供します。これらのマクロはtexc.hに定義されています。
TRYのtry_blockはCまたはC++の宣言文とステートメントのブロックであり、このブロック内で例外が発生します(例外の発生と関係のないコードはtry_blockの前、あるいは後に配置します)。TRY/ENDTRYの対により、例外のスコープ、つまり例外を検出するコード・リージョンが構成されます(C言語のスコーピングとは異なります)。これらのスコープはネストすることができます。例外が発生すると、例外を処理するためのアクション(CATCHまたはCATCH_ALLクローズ)、あるいはスコープを完結するためのアクション(FINALLYクローズ)に対応するアクティブなスコープを検索することにより、エラーがアプリケーションにレポートされます。スコープが例外処理を行えない場合には、そのスコープは終了し次の上位レベルで例外が生成されます(例外スコープのスタックをアンワインドします)。実行は、処理が行われた箇所の後から再開します。エラーが発生した箇所から実行を再開することはありません。いずれのスコープでも例外が処理されない場合には、プログラムは終了します(userlog(3c)とabort(3)を呼び出すことにより、メッセージがログに書き込まれます)。
CATCH (exception_name) handler_blockは、存在しなくても複数回記述してもかまいません。各handler_blockはCまたはC++の宣言文またはステートメントであり、対応する例外(exception_name)の処理を行います(通常、障害からリカバリするためのアクションが指定されます)。例外がtry_block内のステートメントで発生した場合には、その例外に対応する最初のCATCHクローズが実行されます。
CATCHまたはCATCH_ALL handler_block内では、現レベルの例外はEXCEPTIONポインタTHIS_CATCHにより参照できます(たとえば、例外値に基づくロジックや、例外値の出力など)。
例外がいずれのCATCHクローズでも処理できない場合には、CATCH_ALLクローズが実行されます。デフォルトではCATCHまたはCATCH_ALLクローズで処理される例外に対しては、それ以上のアクションは取られません。CATCH_ALLクローズが存在しない場合には、try_blockが他のtry_blockにネストされているものと想定し、次の上位のtry_blockで例外が発生します。ANSI Cコンパイラを使用した場合には、ハンドラ・ブロック内で使用されるレジスタと自動変数にvolatile属性を付加して宣言しなければなりません(setjmp/longjmpを使用するブロックの場合も同様です)。また、例外を発生する関数からの出力パラメータと戻り値は、不明であることに注意してください。
CATCHまたはCATCH_ALL handler_block内では、現レベルの例外はRERAISE文により、次の上位のレベルに伝播されます(例外が再度発生します)。RERAISE文は、handler_blockのスコープ内(つまりhandler_blockにより呼び出された関数内ではありません)になければなりません。検出はできますが、完全には処理できない例外はすべて出し直さなければなりません。ほとんどの場合、ハンドラはすべての例外を処理するようには書かれていないため、CATCH_ALLハンドラは例外を再度発生させる必要があります。アプリケーションは、例外が該当するスコープで発生し、ハンドラ・ブロックが適切な処理を行って該当するステータスを変更するように書かれなければなりません(たとえば、ファイルのオープン中に例外が発生した場合には、そのレベルの例外関数は、オープンされていないファイルをクローズしてはいけません)。
例外は、RAISE (exception_name)ステートメントを使用してどこででも発生させることができます。このステートメントにより、例外は現在のtry_blockから伝播を開始して、処理が行われる上位レベルに到達するまで出し直されます。
FINALLYクローズは、例外の発生に関係なく、try_blockの後で実行されるコードの終局ブロックを指定するのに使用します。例外はtry_block内で発生した場合には、finally_blockが実行された後で出し直されます。このクローズは、終局コードを重複して使用しないように、つまりCATCH_ALLクローズ内とENDTRYの後で二度繰り返して使用しないようにするためのものです。このクローズは通常、クリーンアップ作業を行い、例外の発生に関係なく(つまりブロックでの正常終了と異常終了の両方で)スコープがアンワインドする際にインバリアント(たとえば、共有データ、ロック)をリストアするのに使用します。FINALLYクローズは、同じtry_blockに対してはCATCHやCATCH_ALLクローズと一緒に使用することはできません。try_blockをネストして使用します(「概要」の項)。
TRYブロックを終了するには、ENDTRYステートメントを使用しなければなりません。このステートメントは、例外が処理されコンテキストがクリーンアップされたことを確かめるために実行するコードを含んでいます。try_blockやhandler_block、finally_blockには、return、ローカルではないjump、あるいはENDTRYに到達せずにブロックを出る手法(goto()、break()、continue()、longjmp()など)を含めてはいけません。
このインタフェースは、RPCオペレーションからの例外を処理するために提供されています。ただしこのインタフェースは、すべてのアプリケーションで使用することのできる汎用のインタフェースです。例外は、EXCEPTIONの形式で宣言されます(これは複雑なデータ・タイプで、long integerのようには使用できません)。2種類の例外があります。どちらも同じ方法で宣言されますが、初期化の方法は異なります。
1種類の例外を使用してアプリケーション例外を定義します。EXCEPTION_INIT()マクロを呼び出して初期化します。例外のアドレスはaddress例外内の値として格納されます。この値は単一のアドレス空間内でのみ有効であり、例外が自動変数の場合には変更されることに注意してください。このためaddress例外は静的変数あるいは外部変数として宣言し、自動変数あるいはレジスタ変数として宣言すべきではありません。exc_get_status()マクロは、address例外では -1となります。この例外でexc_set_status()マクロを使用するとstatus例外となります。
exc_matchesマクロは、2つの例外を比較するのに使用します。同一であるためには、どちらの例外も同じタイプであり、同じ値を持たなければなりません(つまり、status例外に対しては同じステータス値を持つか、address例外に対しては同じアドレスを持ちます)。この比較は、上記のCATCHクローズで使用されます。
ステータス例外が発生した場合の通常の処理は、ステータス値を表示するか、より好ましい方法としてはステータス値が何であるかを示す文字列を表示することです。文字列を標準エラー出力に表示するのであれば、文字列を1回の操作で表示できるようにstatus例外へのポインタを付加して関数exc_report()を呼び出します。
CATCH_ALL
{
exc_report(THIS_CATCH);
}
ENDTRY
文字列に対して他の処理を行う場合には(たとえば、エラーをユーザー・ログに出力する)、exc_get_status()をTHIS_CATCHで使用し、ステータス値を取得できます(THIS_CATCHはEXCEPTIONに対するポインタであり、EXCEPTION自体ではありません)。dce_error_inq_text()を使用して、ステータス値の文字列を取得することができます。
CATCH_ALL
{
unsigned long status_to_convert;
unsigned char error_text[200];
int status;
exc_get_status(THIS_CATCH,status_to_convert);
dce_error_inq_text(status_to_convert, error_text, status);
userlog(“%s”, (char *)error_text);
}
ENDTRY| 注意: | マルチスレッドのアプリケーション中のスレッドは、TPINVALIDCONTEXTを含め、どのコンテキスト状態で実行していても、TRY/CATCHインタフェースを呼び出すことができます。 |
RPCオペレーションのステータスは、各オペレーションごとにステータス変数を定義することにより決定できます([comm_status}と[fault_status]パラメータは、属性構成ファイルで定義されます)。ステータス復帰インタフェースは、X/Open RPC仕様で提供される唯一のインタフェースです。fault_status属性は、不適切なパラメータ、リソース不足、コーディング・エラー等によりサーバー上で発生したエラーが、補助的なステータス引数や戻り値でレポートされることを示しています。同様にcomm_status属性は、RPCコミュニケーション障害が補助的なステータス引数や戻り値でレポートされることを示します。ステータス値を利用する処理は、各コールごとに起こり得るエラーに対して指定されたリカバリを行う(コールごとの)きめ細かいエラー処理と、障害の時点での再試行が必要な場合にはうまく機能します。欠点としては、コールがローカルなものであってもリモートなものであっても、いずれの場合にも透過性がない点が挙げられます。リモート・コールには追加のステータス・パラメータ、あるいはvoidのかわりにステータスの戻り値が必要になります。従ってアプリケーションでは、ローカルと分散コード間で調整を行うプロシージャ宣言が必要です。
TRY/CATCH例外復帰インタフェースは、OSF/DCE環境からのアプリケーション移植性のためにも提供されています。このインタフェースは、すべての環境で利用できるものではありません。しかし、プロシージャ宣言をローカルと分散コード間で調整する必要がないという利点があり、既存のインタフェースを保持できます。各プロシージャ・コールは固有の障害チェックやリカバリ・コードを持つ必要がなく、エラー・チェッキングを簡素化できます。あるレベルでエラー処理が行えない場合には、プログラムは、「エラーが検出されたが修正可能である」などのシステム・エラー・メッセージを出力して終了します(メッセージを省略すると、エラー・チェッキングはより簡単になります)。例外は、大まかな例外処理を行う場合には有用です。
表 13に示す例外は、この例外インタフェースで使用するために組み込まれている例外です。最初のTRYクローズはシグナル・ハンドラを設定し、以下にリストされたシグナル(無視されることがなく、補足可能なもの)を補足します。その他の例外はDCE対応のプログラムでの移植性のためにのみ定義されたものです。
名前の後に_eが付加された同じ例外コードが定義されています(たとえば、exc_e_SIGBUSはexc_SIGBUS_eとも定義されています)。同等のステータス・コードが同様な名前で定義されていますが、_e_は_s_に変更されています(たとえば、exc_e_SIGBUSはexc_s_SIGBUSステータス・コードと同等です)。
OSF/DCEでは、ヘッダー・ファイルはexc_handling.hと命名されますが、Oracle Tuxedo ATMIシステムのヘッダー・ファイルはtexc.hです。同じソース・ファイルでDCEとOracle Tuxedo ATMIシステムの例外処理を両方使用することはできません。また1つのプログラム内では、シグナル例外の処理はDCEかOracle Tuxedo ATMIシステムのいずれか一方でしか行えません。
#include <texc.h>
EXCEPTION badopen_e; /* declare exception for bad open() */
doit(char *filename)
{
EXCEPTION_INIT(badopen_e); /* initialize exception */
TRY get_and_update_data(filename); /* do the operation */
CATCH(badopen_e) /* exception - open() failed */
fprintf(stderr, “Cannot open %s\en”, filename);
CATCH_ALL /* handle other errors */
/* handle rpc service not available, ... */
exc_report(THIS_CATCH)
ENDTRY
}
/*
* Open output file
* Get the remote data item
* Write out to file
*/
get_and_update_data(char *filename)
{
FILE *fp;
if ((fp == fopen(filename)) == NULL) /* open output file */
RAISE(badopen_e); /* raise exception */
TRY
/* in this block, file is opened successfully -
* use associated FINALLY to close file
*/
long data;
/*
* Execute RPC call - exceptions are raised to the calling
* function, doit()
*/
data = remote_get_data();
fprintf(fp, “%ld\en”, data);
FINALLY
/* Whether or not exceptions are raised, close the file */
fclose(fp);
ENDTRY
}
UNIXシステムのリファレンス・マニュアルのabort(2)
『TxRPCを使用したOracle Tuxedoアプリケーションのプログラミング』
#include <atmi.h>
char *tuxgetenv(char *name)
tuxgetenv()は、環境リストからname=valueという形式の文字列を探し、その文字列が見つかった場合に、現在の環境内のvalueを指すポインタを返します。文字列が見つからなかった場合は、NULLポインタを返します。
この関数は、Oracle Tuxedo ATMIがサポートされる、異なるプラットフォーム間で使用する環境変数に対して、移植可能なインタフェースを提供します。プラットフォームには、通常は環境変数を持たないプラットフォームも含まれます。
tuxgetenvは大文字と小文字を区別することに注意してください。
マルチスレッドのアプリケーション中のスレッドは、TPINVALIDCONTEXTを含め、どのコンテキスト状態で実行していても、tuxgetenv()の呼出しを発行できます。
文字列のポインタが存在する場合、tuxgetenv()はそのポインタを返します。ポインタが存在しない場合、tuxgetenv()はNULLポインタを返します。
MS Windowsでは、この関数によって、アプリケーションとダイナミック・リンク・ライブラリとの間で環境変数を共有できるようになります。Oracle Tuxedo ATMIワークステーションDLLは、付加された各アプリケーションの環境コピーを保持します。この関連付けられた環境およびコンテキスト情報は、tpterm()がWindowsアプリケーションから呼び出されると無効になります。環境変数の値は、アプリケーション・プログラムがtpterm()を呼び出した後で変更できます。
Windows環境では、大文字の変数名を使用することをお薦めします(tuxreadenv()はすべての環境変数名を大文字に変換します)。
tuxgetmbaconv() - プロセス環境で環境変数TPMBACONVの値を取得
#include <atmi.h>
extern int tperrno;
int
tuxgetmbaconv(long flags) /* Get TPMBACONV info */
この関数は、TPMBACONVのステータスを取得するために使用します。tuxgetnombaconv()関数は、アプリケーション開発者が、型付きバッファ・スイッチの自動変換機能がオフになっているかどうかをチェックするために使用します。デフォルトでは、TPMBACONVは設定されず、自動変換機能が使用されます。
tuxgetnombaconv()は、TPMBACONVが設定されている場合はMBAUTOCONVERSION_ONを戻し、TPMBACONVが設定されていない場合はMBAUTOCONVERSION_OFFを戻します。
tuxgetenv(3c)、tuxsetmbaconv(3c)
tuxgetmbenc() - プロセス環境で環境変数TPMBENCのコード・セットのエンコード名を取得
#include <atmi.h>
extern int tperrno;
int
tuxgetmbenc(char *enc_name, long flags)
この関数は、環境変数TPMBENCに保持されているコードセットのエンコード名を取得するために使用します。この環境変数は、MBSTRING型付きバッファを作成する際に、デフォルトのコードセットのエンコード名として使用されます。新しいメッセージの取出しが可能になると、tpsetmbenc()関数を使用してデフォルトのエンコード名をリセットしたり設定解除したりできます。
引数enc_nameには、この関数の正常終了時に、環境変数TPMBENCの値が入ります。このポインタには、エンコード名のコピー先として十分な大きさを確保しておく必要があります。
正常終了の場合、tuxgetmbenc()は0を返します。エラーが発生した場合は0以外の値を返します。
tpconvmb(3c)、tpgetmbenc(3c)、tpsetmbenc(3c)、tuxgetenv(3c)、tuxsetmbenc(3c)
tuxputenv() - 環境の値を変更、または値を環境に追加する
#include <atmi.h>
int tuxputenv(char *string)
stringは、name=valueという形式の文字列を指します。tuxputenv()は、既存の環境変数を変更するか新しい環境変数を作成して、環境変数名の値がvalueと等しくなるようにします。どちらの場合も、stringによって指された文字列は環境変数の一部になります。
この関数は、Oracle Tuxedo ATMIがサポートされる、異なるプラットフォーム間で使用する環境変数に対して、移植可能なインタフェースを提供します。プラットフォームには、通常は環境変数を持たないプラットフォームも含まれます。
| 注意: | tuxputenv()では大文字と小文字が区別されます。 |
マルチスレッドのアプリケーション中のスレッドは、TPINVALIDCONTEXTを含め、どのコンテキスト状態で実行していてもtuxputenv()の呼出しを発行できます。
tuxputenv()は、malloc()を介して拡張環境のための十分な領域を取得できなかった場合にゼロでない整数を返します。領域を取得できた場合はゼロを返します。
MS Windowsでは、この関数によって、アプリケーションとダイナミック・リンク・ライブラリとの間で環境変数を共有できるようになります。Oracle Tuxedo ATMIシステムのワークスレーションDLLは、付加された各アプリケーションの環境コピーを保持します。この関連付けられた環境およびコンテキスト情報は、tpterm()がWindowsアプリケーションから呼び出されると無効になります。環境変数の値は、アプリケーション・プログラムがtpterm()を呼び出した後で変更できます。
DOS、Windows、およびOS/2環境では、大文字の変数名を使用することをお薦めします(tuxreadenv()はすべての環境変数名を大文字に変換します)。
tuxreadenv() - ファイルから環境へ変数を追加する
#include <atmi.h>
int tuxreadenv(char *file, char *label)
tuxreadenv()は環境変数を含むファイルを読み込み、プラットフォームから独立して環境変数を環境に追加します。変数はtuxgetenv()を使用して利用でき、tuxputenv()を使用して再設定できます。
variable=value
setvariable=value
ここで、variableは、先頭がアルファベット文字またはアンダースコア文字で、全体が英数字またはアンダースコア文字のみからなる文字列です。また、valueには改行文字を除くすべての文字を使用できます。
value内で、${env}という形式の文字列は、環境内にすでにある変数を使用して展開されます。前方参照はサポートされておらず、値が設定されていない場合、変数は空の文字列に置き換えられます。円マーク(¥)を使用して、ドル記号およびそれ自体をエスケープすることができます。その他すべてのシェルのクォートおよびエスケープのメカニズムは無視され、展開されたvalueがそのまま環境に入れられます。[label]
labelは、上記のvariableと同じ規則(無効なlabel値を持つ行は無視される)に従います。
fileがNULLの場合、デフォルトのファイル名が使用されます。固定のファイル名は次のとおりです。
DOS、Windows、OS2、NT: C:\TUXEDO\TUXEDO.ENVまたは
MAC:システム環境設定ディレクトリのTUXEDO.ENV
NETWARE: SYS:SYSTEM\TUXEDO.ENV
POSIX: /usr/tuxedo/TUXEDO.ENV/var/opt/tuxedo/TUXEDO.ENV
labelがNULLの場合、グローバル・セクション内の変数だけが環境に挿入されます。labelが他の値の場合、グローバル・セクションの変数と、labelに一致するセクション内の変数が環境に入れられます。
エラー・メッセージは、メモリー障害が発生した場合、NULLでないファイル名が存在しない場合、またはNULLでないラベルがない場合は、userlog()に出力されます。
マルチスレッドのアプリケーション中のスレッドは、TPINVALIDCONTEXTを含め、どのコンテキスト状態で実行していても、tuxreadenv()の呼出しを発行できます。
TUXDIR=/usr/tuxedo
[application1]
;これはコメントです
/*これはコメントです*/
#これはコメントです
//これはコメントです
FIELDTBLS=app1_flds
FLDTBLDIR=/usr/app1/udataobj
[application2]
FIELDTBLS=app2_flds
FLDTBLDIR=/usr/app2/udataobj
tuxreadenv()は、malloc()を介して拡張環境のための十分な領域を取得できなかった場合か、NULLでない名前を持つファイルをオープンできず読み取ることができない場合に、ゼロ以外の整数を戻します。それ以外の場合、tuxreadenv()はゼロを戻します。
DOS、Windows、OS/2、およびNetWare環境では、tuxreadenv()がすべての環境変数名を大文字に変換します。
tuxsetmbaconv() - プロセス環境で環境変数TPMBACONVの値を設定
#include <atmi.h>
extern int tperrno;
int
tuxsetmbaconv(int onoff, long flags) /* Set TPMBACONV */
この関数は、環境変数TPMBACONVの設定またはリセットに使用します。デフォルトでは、TPMBACONVは設定されず、自動変換機能が使用されます。
引数onoffがMBAUTOCONVERSION_OFFの場合、TPMBACONVが設定解除され、自動変換が無効になります。MBAUTOCONVERSION_ONの場合、TPMBACONVが設定され、型付きバッファでのコードセットのマルチバイト・データの自動変換が有効になります。
正常終了の場合、tuxsetnombaconv()は0を返します。エラーが発生した場合は0以外の値を返します(たとえば、引数onoffが定義済みの値のいずれかでない場合、-1を返します)。
tuxgetmbaconv(3c)、tuxputenv(3c)
tuxsetmbenc() - プロセス環境で環境変数TPMBENCのコード・セットのエンコード名を設定
#include <atmi.h>
extern int tperrno;
int
tuxsetmbenc(char *enc_name, long flags)
この関数は、環境変数TPMBENCに保持されているコードセットのエンコード名を設定またはリセットするために使用します。この環境変数は、MBSTRING型付きバッファを作成する際に、デフォルトのコードセットのエンコード名として使用されます。新しいメッセージの取出しが可能になると、tpsetmbenc()関数を使用してデフォルトのエンコード名をリセットしたり設定解除したりできます。
引数enc_nameは、コードセットの識別に使用するエンコード名です。
正常終了の場合、tuxsetmbenc()は0を返します。エラーが発生した場合は0以外の値を返します。
tpconvmb(3c)、tpgetmbenc(3c)、tpsetmbenc(3c)、tuxgetmbenc(3c)、tuxputenv(3c)
tuxthrputenv() - 現在のスレッドの環境変数を変更または追加します。
#include <atmi.h> )
int tuxthrputenv(char *string
stringは、name=valueという形式の文字列を指します。tuxthrputenv()は、既存の環境変数を変更するか新しい環境変数を作成して、環境変数名の値がvalueと等しくなるようにします。どちらの場合も、stringによって指された文字列は環境変数の一部になります。
この関数は、Oracle Tuxedo ATMIがサポートされる、異なるプラットフォーム間で使用する環境変数に対して、移植可能なインタフェースを提供します(プラットフォームには、通常は環境変数を持たないプラットフォームも含まれます)。これにより、マルチスレッド・アプリケーションのスレッドが独自の環境変数を使用できるようになります。
tuxthrputenvが機能するのは、tuxgetenv()によって読み取られる場合のみです。getenvが使用されると、tuxthrputenvは失敗します。
| 注意: | tuxthrputenv()では大文字と小文字が区別されます。tuxputenvで設定された値をオーバーライドします。 |
tuxthrputenv()は、malloc()を介して拡張環境のための十分な領域を取得できなかった場合にゼロでない整数を返します。領域を取得できた場合はゼロを返します。
MS Windowsでは、tuxthrputenv()によって、アプリケーションとダイナミック・リンク・ライブラリとの間で環境変数を共有できるようになります。Oracle Tuxedo ATMIシステムのワークスレーションDLLは、付加された各アプリケーションの環境コピーを保持します。この関連付けられた環境およびコンテキスト情報は、tpterm()がWindowsアプリケーションから呼び出されると無効になります。環境変数の値は、アプリケーション・プログラムがtpterm()を呼び出した後で変更できます。
DOS、Windows、およびOS/2環境では、大文字の変数名を使用することをお薦めします(tuxreadenv()はすべての環境変数名を大文字に変換します)。
tuxgetenv(3c)、tuxreadenv(3c)、tuxputenv(3c)
tx_begin() - グローバル・トランザクションを開始します。
#include <tx.h>
int tx_begin(void)
tx_begin()は、呼出し側の制御スレッドをトランザクション・モードにする際に使用します。呼出し側のスレッドは、トランザクションを開始する前に、リンクされているリソース・マネージャがオープンしている(tx_open()を介して)ことを、まず第1に確実にしなければなりません。呼出し側がすでにトランザクション・モードにある場合、またはtx_open()が呼び出されていない場合には、tx_begin()は([TX_PROTOCOL_ERROR]を返して)異常終了します。
トランザクション・モードに入ると、呼出し側のスレッドは、現在のトランザクションを完了させるために、tx_commit()またはtx_rollback()を呼び出さなければなりません。トランザクションの連鎖に関連する条件によっては、トランザクションの開始に明示的にtx_begin()を呼び出す必要がないこともあります。詳細は、tx_commit()およびtx_rollback()を参照してください。
マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドは、tx_begin()の呼出しを発行できません。
tx_begin()は、正常終了時には、負数ではない戻り値TX_OKを返します。
次の条件の場合、tx_begin()は異常終了し、次のいずれかの負の値を返します。
TX_OUTSIDE]
TX_PROTOCOL_ERROR]
TX_ERROR]
TX_FAIL]
tx_commit(3c)、tx_open(3c)、tx_rollback(3c)、tx_set_transaction_timeout(3c)
XA準拠のリソース・マネージャがグローバル・トランザクションに含まれるようにするには、そのリソース・マネージャが正常にオープンされている必要があります(詳細については、「tx_open(3c)」を参照してください)。X/Open TXインタフェースとX-Windowシステムは、いずれも型XIDを定義します。同一のファイルでX-WindowコールとTXコールの両方を使用することはできません。
tx_close() - リソース・マネージャ・セットをクローズする
#include <tx.h>
int tx_close(void)
tx_close()は、移植性の高い方法でリソース・マネージャ・セットをクローズします。これにより、トランザクション・マネージャが呼び出されて、リソース・マネージャ固有の情報がトランザクション・マネージャ固有の方法で読み取られ、この情報が呼出し側にリンクされているリソース・マネージャに渡されます。
tx_close()は、呼出し側がリンクしているリソース・マネージャをすべてクローズします。この関数は、リソース・マネージャ固有のクローズ呼出しのかわりに使用されるため、アプリケーション・プログラムは、移植性を損なう危険性のある呼出しを使用することがなくなります。リソース・マネージャは終了の内容がそれぞれで異なるため、個々のリソース・マネージャをクローズするために必要な情報をリソース・マネージャごとに通知する必要があります。
tx_close()は、アプリケーションの制御スレッドがグローバル・トランザクションに関与する必要がなくなったときに呼び出してください。呼出し側がトランザクション・モードにあると、tx_close()は([TX_PROTOCOL_ERROR]を返して)異常終了します。したがって、現在のトランザクションに関与しない制御スレッドがあっても、リソース・マネージャは一切クローズされません。
tx_close()が正常に終了すると(TX_OK)、呼出し側のスレッドにリンクしているリソース・マネージャはすべてクローズされます。
マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドはtx_close()の呼出しを発行できません。
tx_close()は、正常終了時には、負数でない戻り値TX_OKを返します。
次の条件の場合、tx_close()は異常終了し、次のいずれかの負の値を返します。
TX_PROTOCOL_ERROR]
TX_ERROR]
TX_FAIL]
X/Open TXインタフェースとX-Windowシステムは、いずれも型XIDを定義します。同一のファイルでX-WindowコールとTXコールの両方を使用することはできません。
tx_commit() - グローバル・トランザクションをコミットします。
#include <tx.h>
int tx_commit(void)
tx_commit()は、呼出し側の制御スレッドでアクティブなトランザクションの作業をコミットするために使用します。
transaction_control特性(「tx_set_transaction_control(3c)」を参照)がTX_UNCHAINEDである場合は、tx_commit()が終了すると、呼出し側はトランザクション・モードではなくなります。一方、transaction_control特性がTX_CHAINEDである場合は、tx_commit()が終了すると、呼出し側は、新しいトランザクションのためにトランザクション・モードのままになります(このページの「戻り値」および「エラー」の項を参照してください)。
マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドはtx_commit()の呼出しを発行できません。
tx_commit()は、正常終了時には、負数でない戻り値TX_OKを返します。
次の条件の場合、tx_commit()は異常終了し、次のいずれかの負の値を返します。
TX_NO_BEGIN]
transaction_control特性がTX_CHAINEDである場合のみ発生します。
TX_ROLLBACK]
TX_ROLLBACK_NO_BEGIN]
transaction_control特性がTX_CHAINEDである場合のみ発生します。
TX_MIXED]
transaction_control特性がTX_CHAINEDの場合は、新しいトランザクションが開始されます。
TX_MIXED_NO_BEGIN]
transaction_control特性がTX_CHAINEDである場合のみ発生します。
TX_HAZARD]
transaction_control特性がTX_CHAINEDの場合は、新しいトランザクションが開始されます。
TX_HAZARD_NO_BEGIN]
transaction_control特性がTX_CHAINEDである場合のみ発生します。
TX_PROTOCOL_ERROR]
TX_FAIL]
tx_begin(3c)、tx_set_commit_return(3c)、tx_set_transaction_control(3c)、tx_set_transaction_timeout(3c)
X/Open TXインタフェースとX-Windowシステムは、いずれも型XIDを定義します。同一のファイルでX-WindowコールとTXコールの両方を使用することはできません。
tx_info() - グローバル・トランザクション情報を返す
#include <tx.h>
int tx_info(TXINFO *info)
tx_info()は、グローバル・トランザクション情報を、infoが指す構造体に返します。また、この関数は、呼出し側が現在トランザクション・モードにあるかどうかを示す値も返します。infoがNULL以外の値であれば、tx_info()は、infoが指すTXINFO構造体にグローバル・トランザクション情報を入れます。TXINFO構造体には次の要素があります。
XID xid;
COMMIT_RETURN when_return;
TRANSACTION_CONTROL transaction_control;
TRANSACTION_TIMEOUT transaction_timeout;
TRANSACTION_STATE transaction_state;
tx_info()がトランザクション・モードにおいて呼び出されると、xidに現在のトランザクションのブランチ識別子が、transaction_stateに現在のトランザクションの状態が入ります。呼出し側がトランザクション・モードにない場合は、xidにNULLのXIDが入ります(詳細はtx.hファイルを参照)。また、呼出し側がトランザクション・モードにあるかどうかに関係なく、when_return、transaction_controlおよびtransaction_timeoutに、commit_returnおよびtransaction_control特性の現在の設定、および秒単位のトランザクション・タイムアウト値が入ります。
返されるトランザクション・タイムアウト値は、次のトランザクション開始時に使用される設定を反映しています。したがって、この値は、呼出し側の現在のグローバル・トランザクションのタイムアウト値を反映しているわけではありません。現在のトランザクション開始後に行われたtx_set_transaction_timeout()の呼出しによって、この値が変更されていることがあるからです。
infoがNULLである場合は、TXINFO構造体は返されません。
マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドはtx_info()の呼出しを発行できません。
呼出し側がトランザクション・モードにある場合は、1を返します。呼出し側がトランザクション・モードにない場合は、0を返します。
次の条件の場合、tx_info()は異常終了し、次のいずれかの負の値を返します。
TX_PROTOCOL_ERROR]
TX_FAIL]
tx_open(3c)、tx_set_commit_return(3c)、tx_set_transaction_control(3c)、tx_set_transaction_timeout(3c)
同一のグローバル・トランザクション内では、後続のtx_info()呼出しは、XIDに同一のgtrid構成要素を示すことが保証されていますが、同一のbqual構成要素を示すことは必ずしも保証されません。X/Open TXインタフェースとX-Windowシステムは、いずれも型XIDを定義します。同一のファイルでX-WindowコールとTXコールの両方を使用することはできません。
#include <tx.h>
int tx_open(void)
tx_open()は、移植性の高い方法でリソース・マネージャ・セットをオープンします。これにより、トランザクション・マネージャが呼び出されて、リソース・マネージャ固有の情報がトランザクション・マネージャ固有の方法で読み取られ、この情報が呼出し側にリンクされているリソース・マネージャに渡されます。
tx_open()はアプリケーションにリンクされているすべてのリソース・マネージャのオープンを試行します。この関数は、リソース・マネージャ固有のオープン呼出しのかわりに使用されるため、アプリケーション・プログラムは、移植性を損なう可能性のある呼出しを使用することがなくなります。リソース・マネージャは開始の内容がそれぞれで異なるため、個々のリソース・マネージャをオープンするために必要な情報をリソース・マネージャごとに通知する必要があります。
tx_open()がTX_ERRORを返した場合は、リソース・マネージャは一切オープンされません。tx_open()がTX_OKを返した場合は、いくつかまたはすべてのリソース・マネージャがオープンされています。オープンされなかったリソース・マネージャは、アプリケーションによってアクセスされるときに、リソース・マネージャ固有のエラーを返します。tx_open()は、制御スレッドがグローバル・トランザクションに関与する前に、正常に終了していなければなりません。
tx_open()が正常に終了した後で(tx_close()を呼び出す前に)、tx_open()を呼び出すことができます。このような後続の呼出しは、正常終了しますが、トランザクション・マネージャは、リソース・マネージャの再オープンは一切行いません。
マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドはtx_open()の呼出しを発行できません。
tx_open()は、正常終了時には、負数でない戻り値TX_OKを返します。
次の条件の場合、tx_open()は異常終了し、次のいずれかの負の値を返します。
TX_ERROR]
TX_FAIL]
tpinit()を呼び出さずにセキュリティの掛かったアプリケーション(SECURITY APP_PW)の中でtx_openを呼び出すと、TX_FAILが出されます。このエラーでは、トランザクション・マネージャまたは1つ以上のリソース・マネージャ、あるいはその両方は、アプリケーションのために作業を行うことができなくなります。エラーの正確な性質がログ・ファイルに書き込まれます。
X/Open TXインタフェースとX-Windowシステムは、いずれも型XIDを定義します。同一のファイルでX-WindowコールとTXコールの両方を使用することはできません。
tx_rollback() - グローバル・トランザクションのロールバック
#include <tx.h>
int tx_rollback(void)
tx_rollback()は、呼出し側の制御スレッドでアクティブなトランザクションの作業をロールバックします。
transaction_control特性(「tx_set_transaction_control(3c)」を参照)がTX_UNCHAINEDである場合は、tx_rollback()が終了すると、呼出し側はトランザクション・モードではなくなります。一方、transaction_control特性がTX_CHAINEDである場合は、tx_rollback()が終了すると、呼出し側は新しいトランザクションのためにトランザクション・モードのままになります(このページの「戻り値」および「エラー」の項を参照してください)。
マルチスレッド・アプリケーションの場合、TPINVALIDCONTEXT状態のスレッドはtx_rollback()の呼出しを発行できません。
tx_rollback()は、正常終了時には、負数ではない戻り値TX_OKを返します。
次の条件の場合、tx_rollback()は異常終了し、次のいずれかの負の値を返します。
TX_NO_BEGIN]
transaction_control特性がTX_CHAINEDである場合のみ発生します。
TX_MIXED]
transaction_control特性がTX_CHAINEDの場合は、新しいトランザクションが開始されます。
TX_MIXED_NO_BEGIN]
transaction_control特性がTX_CHAINEDである場合のみ発生します。
TX_HAZARD]
transaction_control特性がTX_CHAINEDの場合は、新しいトランザクションが開始されます。
TX_HAZARD_NO_BEGIN]
transaction_control特性がTX_CHAINEDである場合のみ発生します。
TX_COMMITTED]
TX_COMMITTED_NO_BEGIN]
transaction_control特性がTX_CHAINEDである場合のみ発生します。
TX_PROTOCOL_ERROR]
TX_FAIL]
tx_begin(3c)、tx_set_transaction_control(3c)、tx_set_transaction_timeout(3c)
X/Open TXインタフェースとX-Windowシステムは、いずれも型XIDを定義します。同一のファイルでX-WindowコールとTXコールの両方を使用することはできません。
tx_set_commit_return() - commit_return特性の設定
#include <tx.h>
int tx_set_commit_return(COMMIT_RETURN when_return)
tx_set_commit_return()は、when_returnで指定されている値にcommit_return特性を設定します。この特性は、呼出し側に制御を返すことに関するtx_commit()の動作に影響します。tx_set_commit_return()は、その呼出し側がトランザクション・モードかどうかにかかわらず呼び出されます。この設定は、引き続き呼び出されるtx_set_commit_return()で変更されるまで有効です。
この特性の初期設定は、TX_COMMIT_COMPLETEDです。
TX_COMMIT_DECISION_LOGGED
tx_commit()が終了することを示します。このフラグを設定すると、tx_commit()の呼出し側に高速で応答することができます。しかし、トランザクションがヒューリスティックな結果を得る危険があります。この場合、tx_commit()の戻りコードから呼出し側がこの状況を知ることはできません。正常な状態では、第1フェーズの間にコミットすることを約束している参加リソースは、第2フェーズでコミットします。ただし、特殊な状況(たとえば、長時間継続するネットワークまたはノードの障害)では、フェーズ2が完了できない可能性があり、ヒューリスティックな結果が生成されることがあります。
TX_COMMIT_COMPLETED
tx_commit()が返ることを示しています。この設定により、tx_commit()の呼出し側は、トランザクションにヒューリスティックな結果が発生したか、または発生した可能性があるかを示す戻り値を調べることができます。
マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドはtx_set_commit_return()の呼出しを発行できません。
正常終了の場合、tx_set_commit_return()は、負でない戻り値TX_OKを返します。
次の条件の場合、commit_returnは、commit_return特性の設定を変更することなく、次の3つの負の値のうちの1つを返します。
TX_EINVAL]
TX_PROTOCOL_ERROR]
TX_FAIL]
tx_commit(3c)、tx_info(3c)、tx_open(3c)
X/Open TXインタフェースとX-Windowシステムは、いずれも型XIDを定義します。同一のファイルでX-WindowコールとTXコールの両方を使用することはできません。
tx_set_transaction_control() - transaction_control特性を設定する
#include <tx.h>
int tx_set_transaction_control(TRANSACTION_CONTROL control)
tx_set_transaction_control()は、controlで指定されている値にtransaction_control特性を設定します。この特性は、tx_commit()およびtx_rollback()のどちらかが、これらの呼出し側に返る前に、新しいトランザクションを開始するかどうかを決めます。tx_set_transaction_control()は、アプリケーション・プログラムがトランザクション・モードかどうかにかかわらず呼び出すことができます。この設定は、引き続き後に呼び出されるtx_set_transaction_control()で変更されるまで有効です。
TX_UNCHAINED
tx_commit()およびtx_rollback()が、これらの呼出し側に返る前に新しいトランザクションを開始してはならないことを示しています。呼出し側は新しいトランザクションを開始するためにtx_begin()を出さなければなりません。
マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドはtx_set_transaction_control()の呼出しを発行できません。
正常終了の場合、tx_set_transaction_control()は、負でない戻り値TX_OKを返します。
次の条件の場合、tx_set_transaction_control()は、transaction_control特性の設定を変更することなく、次に示す3つの負の値のうちの1つを返します。
TX_EINVAL]
TX_PROTOCOL_ERROR]
TX_FAIL]
tx_begin(3c)、tx_commit(3c)、tx_info(3c)、tx_open(3c)、tx_rollback(3c)
X/Open TXインタフェースとX-Windowシステムは、いずれも型XIDを定義します。同一のファイルでX-WindowコールとTXコールの両方を使用することはできません。
tx_set_transaction_timeout() - transaction_timeout特性を設定する
#include <tx.h>
int tx_set_transaction_timeout(TRANSACTION_TIMEOUT timeout)
tx_set_transaction_timeout()は、timeoutで指定されている値にtransaction_timeout特性を設定します。この値は、トランザクションが、トランザクション・タイムアウトになる前に終了しなければならない時間間隔、すなわちアプリケーションが、tx_begin()を呼び出してからtx_commit()またはtx_rollback()を呼び出すまでの時間間隔を指定します。tx_set_transaction_timeout()は、呼出し側がトランザクション・モードかどうかにかかわらず呼び出すことができます。tx_set_transaction_timeout()が、トランザクション・モードで呼び出される場合、新しいタイムアウト値は、次のトランザクションが開始されないと有効になりません。
transaction_timeoutの初期値は0 (タイムアウトなし)です。
timeoutは、トランザクションが、トランザクション・タイムアウトを受けないでいられる秒数を指定します。この値は、最大値、すなわちシステムによって定義されているlongまでの任意の値に設定されます。timeout値が0の場合、タイムアウト機能は働きません。
マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドはtx_set_transaction_timeout()の呼出しを発行できません。
正常終了の場合、tx_set_transaction_timeout()は、負でない戻り値TX_OKを返します。
次の条件の場合、tx_set_transaction_timeout()は、transaction_timeout特性の設定を変更することなく、次に示す3つの負の値のうちの1つを返します。
TX_EINVAL]
TX_PROTOCOL_ERROR]
TX_FAIL]
tx_begin(3c)、tx_commit(3c)、tx_info(3c)、tx_open(3c)、tx_rollback(3c)
X/Open TXインタフェースとX-Windowシステムは、いずれも型XIDを定義します。同一のファイルでX-WindowコールとTXコールの両方を使用することはできません。
userlog() - Oracle Tuxedo ATMIシステムの中央イベント・ログへのメッセージの書込み
#include “userlog.h”
extern char *proc_name;
int userlog (format [ ,arg] . . .)
char *format;
userlog()は、printf(3S)スタイルのフォーマット指定を受け付け、固定出力ファイル(Oracle Tuxedo ATMIシステムの中央イベント・ログ)を使用します。
中央イベント・ログは通常のUNIXファイルです(パス名は次のように構成されます)。シェル変数ULOGPFXが設定されると、その値がファイル名の接頭辞として使用されます。ULOGPFXが設定されていない場合は、ULOGが使用されます。この接頭辞は最初にuserlog()が呼び出されたときに判別されます。userlog()が呼び出されるたびに、日付が判別され、月、日、年がmmddyyの形式で接頭辞に連結されてファイルの名前が設定されます。プロセスが初めてユーザー・ログに書き込む場合、対応するOracle Tuxedo ATMIシステムのバージョンを示す追加のメッセージを書き込みます。
このあと、メッセージがそのファイルに追加されます。この方法の場合、それ以降の日にuserlog()をプロセスが呼び出すと、メッセージは別のファイルに書き込まれます。
メッセージは、呼出しプロセスの時刻(hhmmss)、システム名、プロセス名、呼出しプロセスのプロセスID、スレッドID、コンテキストIDからなるタグと一緒にログ・ファイルに書き込まれます。このタグの末尾にはコロン(:)が付けられます。プロセスの名前は、外部変数proc_nameのパス名から取られます。proc_nameの値がNULLであると、得られる名前は?procに設定されます。
Oracle Tuxedo ATMIシステムがログ・ファイルに出すエラー・メッセージの先頭には、ユニークな識別用文字列が次の形式で付けられます。
<catalog>:number>:
この文字列は、メッセージ文字列を含む国際版カタログの名前にメッセージ番号を加えたものです。規則によれば、Oracle Tuxedo ATMIシステムのエラー・メッセージは1度のみ使用されるようになっているため、この文字列はソース・コード内の位置を一意に識別します。
format指定の最後の文字が改行文字でない場合、userlog()は改行文字を1つ追加します。
シェル変数ULOGDEBUGの先頭文字が1またはyであると、userlog()に送られるメッセージはfprintf(3S)関数により呼出しプロセスの標準エラー出力にも書き出されます。
userlog()は、Oracle Tuxedo ATMIシステムが各種のイベントを記録するために使用します。
このuserlogの機構は、いかなるデータベースのトランザクション記録機構からも完全に独立しています。
マルチスレッドのアプリケーション中のスレッドは、TPINVALIDCONTEXTを含め、どのコンテキスト状態で実行していてもuserlog()の呼出しを発行できます。
ULOGMILLISEC
ULOGMILLISECがオンの場合、サーバーは再起動します。ULOGMILLISEC=Y
ULOGRTNSIZE
ULOGRTNSIZEがオンの場合、サーバーは再起動します。ULOGRTNSIZE=1000000 (ファイル・サイズが1MBの場合)
ULOG.083103.1、ULOG.083103.2 ... ULOG.083103.10など | 注意: | ULOGRTNSIZEを指定しなかった場合、ファイルのローテーションは行われません。 |
userlog()インタフェースは、UNIXシステムおよびMS-DOSオペレーティング・システムで利用できます。ログ・メッセージの一部として生成されるシステム名は、MS-DOSシステムでは利用できません。このため、MS-DOSシステムのシステム名としては、値PCを使用します。
変数ULOGPFXが/application/logs/logに設定されている場合、およびuserlog()の最初の呼出しが1990年9月7日に行われた場合、作成されるログ・ファイルには/application/logs/log.090790という名前が付けられます。たとえば、
userlog(“UNKNOWN USER '%s' (UID=%d)”, usrname, UID);
上記のような呼出しが、プロセスIDが23431であるプログラムsecによりUNIXシステムが指定したm1上で4:22:14pmに出され、変数usrnameに文字列“sxx”,が含まれ、かつ変数UIDに整数123が指定されている場合、ログ・ファイルには次のような行が書き込まれます。
162214.m1!sec.23431: UNKNOWN USER 'sxx' (UID=123)
プロセスがトランザクション・モードのときにメッセージが中央イベント・ログに送られた場合、ユーザー・ログ・エントリのタグに追加の要素が加わります。これらの要素は、リテラルgtridと、それに続く3桁のlong型の16進整数で構成されます。これらの整数はグローバル・トランザクションをユニークに識別し、グローバル・トランザクション識別子と呼ばれます。この識別子は主に管理上の目的で使用されますが、中央イベント・ログでメッセージの先頭に付けられるタグの中に付けられます。前述のメッセージがトランザクション・モードで中央イベント・ログに書き出される場合、結果として得られるログ・エントリは次のようになります。
162214.logsys!security.23431: gtrid x2 x24e1b803 x239: UNKNOWN USER 'sxx' (UID=123)
シェル変数ULOGDEBUGの値がyであると、ログ・メッセージはプログラムsecurityの標準エラー出力にも書き出されます。
userlog()は、送信されるメッセージがstdio.hで定義されているBUFSIZより大きい場合にハングします。
userlog()は、出力された文字数を返します。出力エラーがあった場合には、負の値を返します。出力エラーには、現在のログ・ファイルのオープンや書込みができないといったエラーがあります。ULOGDEBUGが設定されている場合、標準エラー出力への書込みができない場合は、エラーとは見なされません。
アプリケーションでuserlog()メッセージを使用する場合には、アプリケーション・エラーをデバッグするのに有用なものだけを使用することをお薦めします。ログが情報であふれてしまうと、本来のエラーを検出するのが難しくなります。
printf(3S)
Usignal() - Oracle Tuxedo ATMIシステム環境でのシグナル処理
#include “Usignal.h”
UDEFERSIGS()
UENSURESIGS()
UGDEFERLEVEL()
URESUMESIGS()
USDEFERLEVEL(level)
int (*Usignal(sig,func)()
int sig;
int (*func)();
void Usiginit()
Oracle Tuxedo ATMIシステム・ソフトウェアが提供する多くの機能は、共有メモリー内のデータ構造に並行アクセスする必要があります。共有データ構造にアクセスするプログラムはユーザー・モードで走るため、シグナルを使用して中断することができます。共有データ構造の一貫性を維持するためには、それらの構造にアクセスする類の操作が、UNIXシステムのシグナルを受け取っても中断されないことが重要です。ここで説明する関数は、ほとんどの一般的なシグナルに対する保護機構を提供するもので、Oracle Tuxedo ATMIシステムのコードの多くがその内部で使用します。また、これらの関数は、アプリケーション側で使用して、不用意にシグナルを受け取らないようにします。
このOracle Tuxedo ATMIシステムのシグナル処理パッケージは、重要なコード部ではシグナルの発行を遅らせる、という発想から生まれたものです。このため、シグナルは、それが受信されてもすぐには処理されません。Oracle Tuxedo ATMIシステムのルーチンはまず最初に送信されたシグナルを捕捉します。そのシグナルを処理しても安全であれば、そのシグナルに指定された処理が実行されます。シグナルが安全でないということが判明した場合には、そのシグナルの到着が通知されるだけで、重要なコード部が終了したことをユーザーが示すまでは、そのシグナルの処理は行われません。
マルチスレッド・プログラムでシグナルを使用することは可能ですが、使用しないことをお薦めします。ただし、シグナルを使用した場合には、マルチスレッドのアプリケーション中のスレッドは、TPINVALIDCONTEXTを含め、どのコンテキスト状態で実行していてもUsignal()の呼出しを発行できます。
rmopen()またはtpinit()を使用するユーザー・コードは、Usignal()関数を使用してシグナルを捕捉するようにします。Usignal()はUNIXのsignal()システム・コールのように機能しますが、例外としてUsignal()では最初に、内部ルーチンがシグナルを捕捉してから、ユーザー・ルーチンをディスパッチするように調整します。
ここで説明する呼出しは、アプリケーション・コードでシグナルを後回しにする必要がある場合にのみ使用します。一般に、これらのルーチンは、不適切な場面でシグナルが到着しないようにするためにOracle Tuxedo ATMIシステムのルーチンが自動的に呼び出します。
シグナルを遅延またはリストアする前に、メカニズムを初期化する必要があります。初期化は、Oracle Tuxedo ATMIシステム・クライアントがtpinit()を呼び出したときに、Oracle Tuxedo ATMIシステムのクライアントとサーバーのために自動的に行われます。また、初期化は、アプリケーションがはじめにUsignal()呼び出すときに行われます。初期化は、Usiginit()を呼び出すことで明示的に行うことができます。
UDEFERSIGS()マクロは、重要なコード部分に入るときに使用してください。UDEFERSIGS()が呼び出された後、シグナルは保留状態になります。また、URESUMESIGS()マクロは、その重要な部分が終わる時点で呼び出すようにします。シグナル遅延スタックに注意してください。このスタックは、最初にゼロに設定されるカウンタを通して実現されます。UDEFERSIGS()への呼出しによってシグナルが遅延されると、カウンタの値が1大きくなります。URESUMESIGS()の呼出しによりシグナルが再開されると、カウンタの値は1小さくなります。カウンタがゼロ以外の値のときにシグナルが到着すると、そのシグナルの処理は後回しになります。シグナルが到着したときにカウンタがゼロであれば、そのシグナルはただちに処理されます。シグナルの再開により、カウンタがゼロになると(すなわち、再開の前のカウンタ値が1のとき)、その据置期間に到着したシグナルが処理されます。一般に、UDEFERSIGS()の呼出しは、URESUMESIGS()の呼出しと対で使用するようにします。
UDEFERSIGS遅延カウンタの値をインクリメントしますが、返す値はそのインクリメント前の値です。マクロUENSURESIGS()は、遅延カウンタを明示的にゼロに設定する(そして、据え置かれたシグナルを強制的に処理させる)ときに使用できます。この場合、ユーザーはUDEFERSIGS()とURESUMESIGS()の不一致が生じないようにする必要があります。
関数UGDEFERLEVEL()は遅延カウンタの現在の設定値を返します。マクロUSDEFERLEVEL(level)を使用すると、特定の遅延レベルを設定することができます。UGDEFERLEVEL()とUSDEFERLEVEL()は、setjmp/longjmpの状況で適切にカウンタを設定するときに便利です。つまり、setjmp()が呼び出されたときに、UGDEFERLEVEl()の呼出しによってカウンタの値を保存し、longjmp()が実行されたときにUSDEFERLEVEL()の呼出しによりカウンタ値をリストアする、という考え方です。
Usignalは、SIGHUP、SIGINT、SIGQUIT、SIGALRM、SIGTERM、SIGUSR1およびSIGUSR2の各シグナルについて遅延処理を行います。その他すべてのシグナル番号に対する処理リクエストは、Usignal()により直接signaL()に渡されます。シグナルは非常に長い期間その処理が据え置かれることがあります。このため、シグナル遅延の間、シグナルの到着がすべてカウントされます。何回も到着する可能性のあるシグナルの処理が安全な場合、そのシグナルの処理ルーチンが繰り返し呼び出され、シグナルが到着した各シグナルが処理されます。各呼出しの前には、シグナルのデフォルト処理が行われます。つまり、安全なコードで連続して処理が行われる場合と同様に、据え置かれたシグナルが処理されるようにする、という考え方です。
一般に、ユーザーはsignal()とUsignal()の呼出しを同じシグナルに対して組み合わせて使用するべきではありません。できれば、Usignal()を使用する方法をとることが推奨されます。これによって、常にシグナルの状態を知ることができるからです。それは、アプリケーションがOracle Tuxedo ATMIシステム・サービスでアラームを使用したい場合などには必要です。こうすることにより、Usiginit()は、シグナルの遅延メカニズムを初期化するために呼び出されなければなりません。次に、signal()を呼び出し、意図するシグナル用に、メカニズムを変更します。シグナルの遅延メカニズムをリストアするために、Usignal()をSIG_IGNで呼び出してから、再び、意図するシグナル処理関数で呼び出す必要があります。
シェル変数UIMMEDSIGSを使用すれば、シグナルの据置を変更することができます。この変数の値が次のように英字yで始まる場合、
UIMMEDSIGS=y
シグナルはUsignal()コードでインターセプトされません(したがって、据え置かれません)。このような場合、Usignal()の呼出しはただちにsignaL()に渡されます。
また、UsignalはDOSオペレーティング・システムの配下では役に立ちません。
UNIXシステムのリファレンス・マニュアルのsignal(2)
Uunix_err() - UNIXシステム・コール・エラーの出力
#include Uunix.h
void Uunix_err(s)
char *s;
Oracle Tuxedo ATMIシステムの関数がUNIXシステム・コールを呼び出したときに、そのシステム・コールがエラーを検出すると、エラーが返されます。外部整数Uunixerr()が、そのエラーを返したシステム・コールを示す値(Uunix.hに定義されています)に設定されます。さらに、このシステム・コールは、errno()を失敗した理由を示す値(errno.hに定義されています)に設定します。
Uunix_err()関数は、Oracle Tuxedo ATMIシステムの関数の呼出し中に最後に検出したシステム・コールを示すメッセージを標準エラー出力に書き出します。この関数は引数(文字列)を1つとります。この関数はこの引数文字列に続いて、コロンと空白、失敗したシステム・コールの名前、失敗の理由、そして改行文字を書き出します。様々な利用形態を考慮して、この引数文字列には、エラーを起こしたプログラム名を入れます。システム・コールのエラー番号は外部変数Uunixerr()からとられ、そのエラーの理由はerrno()から取り込まれます。どちらの変数も、エラーが発生した時点で設定されます。これらの変数はエラーのない呼出しが行われたときにクリアされます。
メッセージの多彩な形式を単純化するため、次のようなメッセージ文字列の配列
extern char *Uunixmsg[];
が提供されます。Uunixerr()は、この表への索引として使用し、失敗したシステム・コールの名前を(改行文字なしで)取り込むことができます。
マルチスレッドのアプリケーション中のスレッドは、TPINVALIDCONTEXTを含め、どのコンテキスト状態で実行していても、Uunix_err()の呼出しを発行できます。
#include Uunix.h
extern int Uunixerr, errno;
..........
if((fd=open(“myfile”, 3, 0660)) == -1)
{
Uunixerr = UOPEN;
Uunix_err(“myprog”);
exit(1);
}
  
|