![]() ![]() ![]() ![]() ![]() ![]() |
アプリケーション・トランザクション・モニター・インタフェース(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()
を使用してリクエストを転送したりできます。サービスはその他の作業を行ったり、この時点以後別のプロセスとコミュニケートすることは許されません。そのため、サーバーが実行するサービスは、リクエストが受け取られたときに開始され、応答が送信あるいはリクエストが転送された時点で終了します。
リクエスト・メッセージと応答メッセージとの間には、本質的に異なる点があります。リクエストには、それが送信される以前には関連するコンテキストはありませんが、応答にはあるという点です。たとえば、あるリクエストを送信する際に、呼出し側はアドレッシング情報を与える必要がありますが、応答は常にそのリクエストの送信側であるプロセスに返されます。つまり、応答ではアドレッシング・コンテキストが維持され、応答の送信側はその宛先に手を加えることはできません。これら2つのメッセージ・タイプの相違点は、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()
はトランザクション情報を取り出すために使用されます。また、トランザクションにオプションを設定する3つのコールtx_set_commit_return()
、tx_set_transaction_control()
、およびtx_set_transaction_timeout()
があります。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 ATMIシステムは、現在のトランザクションの完了を調整し、制御を呼出し側に戻す前に新しいトランザクションを開始します(異常終了の条件によっては、新しいトランザクションを開始できない場合もあります)。
クライアント・ルーチンとサービス・ルーチンは、tx_set_transaction_control()
を呼び出すことによて連鎖モードを有効または無効にできます。連鎖モードと非連鎖モード間の移行は、次のtx_commit()
またはtx_rollback()
の呼出しに影響を与えます。tx_set_transaction_control()
の呼出しによって、呼出し側がトランザクション・モードに入ったり、トランザクション・モードから抜けたりすることはありません。
tx_close()
は、呼出し側がトランザクション・モードにあるときには呼び出すことができないため、連鎖モードで実行中の呼出し側がtx_close()
を呼び出すには、非連鎖モードに切り替えて、現在のトランザクションを完了してから呼び出す必要があります。
クライアント・ルーチンまたはサービス・ルーチンは、tx_info()
を呼び出すことによって、そのルーチンのトランザクション特性の現在の値を取得したり、そのルーチンがトランザクション・モードで実行中であるかどうかを判別したりすることができます。
アプリケーション・プロセスの状態には、いくつかのトランザクション特性があります。呼出し側は、tx_set_*()
関数の呼出しによってこれらの特性を指定します。クライアント・ルーチンまたはサービス・ルーチンが特性の値を設定している場合は、異なる値を呼出し側が指定するまでは、その値が有効のままです。呼出し側がtx_info()
を使用して特性の値を取得しても、これによって値が変更されることはありません。
ほとんどのATMI関数は、1つまたは複数の戻り値を返します。エラーの条件は、エラーの他には考えられない戻り値で示されます。通常、エラーであれば-1、不正なフィールド識別子(BADFLDID
)またはアドレスであれば0です。エラー・タイプは、外部整数tperrno
としても得られます。tperrno
は、正常な呼出しではクリアされないため、エラーが示された後でのみテストします。
標準エラー出力にメッセージを生成するために、tpstrerror()
関数があります。これは1つの引数と(tperrno
にある)1つの整数を取り、LIBTUX_CAT
のエラー・メッセージ・テキストへのポインタを戻します。このポインタは、userlog()
の引数として使用できます。
tperrordetail()
は、現在のスレッド上の最新のOracle Tuxedo ATMIシステム・コールでのエラーに関する詳細を取得するための3つの手順のうちの最初の手順として使用できます。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バッファは、その整数のみを含む、非常に小さいバッファとして送信されます。
つまり、受信側は、送信側によって当初に割り当てられたバッファよりも小さく、送信されたデータよりも大きいバッファを受け取ります。たとえば、10KバイトのSTRINGバッファが割り当てられ、このバッファに文字列"HELLO"がコピーされた場合、6バイトのみが送信され、受信側はおそらく1Kまたは4Kバイト位のバッファを受け取ります(これは、他の要因に応じてより大きい場合も小さい場合もあります)。Oracle Tuxedo ATMIシステムは、受信されたメッセージに送信されたすべてのデータが含まれていることのみを保証しており、メッセージに当初含まれていたすべての空き領域が含まれることは保証しません。
応答を受け取るプロセスは、(tptypes()
を使用して)バッファのサイズ変更を記録し、必要に応じてバッファの再割当てを行うことに責任を持ちます。すべてのOracle Tuxedo ATMI関数は、バッファ内のデータ量に関する受信側のバッファの戻り情報を変更するため、標準の手法として、応答を受け取るたびにバッファ・サイズをチェックする必要があります。
同じデータ・バッファを使用して、メッセージを送信および受信することができます。または、各メッセージに異なるデータ・バッファを割り当てることもできます。通常、tpfree()
を呼び出してバッファを解放するのは、呼出し側プロセスの責任です。ただし、かぎられた状況では、Oracle Tuxedo ATMIシステムによって呼出し側のバッファが解放されます。バッファの使用方法の詳細は、tpfree()
などの通信関数の説明を参照してください。
tmtype_sw_t
構造体は、プロセスに対するバッファ・タイプ・スイッチであるtm_typesw()
に新しいバッファ・タイプを追加する場合に必要な説明を提供します。スイッチ要素はtypesw(5)で定義されます。このエントリで使用される関数名は、Oracle Tuxedo ATMIシステムまたはカスタム・バッファ・タイプが作成されるアプリケーションによって定義された、実際の関数名のテンプレートです。これらの関数名は、スイッチ要素に容易にマップできます。テンプレート名を作成するには、単に関数ポインタの要素名に接頭辞_tm
を付けます。たとえば、要素initbuf
のテンプレート名は_tminitbuf
になります。
type
要素はNULL以外で、8文字長である必要があります。この要素がスイッチ内で一意でない場合は、subtype()
がNULL以外である必要があります。
subtype()
要素には、NULL、最大16文字の文字列、または* (ワイルドカード文字)を指定できます。type()
とsubtype()
の組合せによって、スイッチ内の要素が一意に識別される必要があります。
1つのタイプに対して、複数のサブタイプが存在してもかまいません。すべてのサブタイプを特定のタイプに対して同じように扱う場合には、ワイルドカード文字*を使用できます。ただし、サブタイプを区別する必要がある場合には、tptypes()
関数を使用して、バッファのタイプとサブタイプを特定できます。ある特定のタイプ内で一定のサブタイプのサブセットを個別に扱う必要があり、残りを同様に扱う場合には、特定の値でまとめるサブタイプはそのサブタイプをワイルドカードで指定する前にスイッチ内に指定しておく必要があります。このため、まずスイッチ内のタイプとサブタイプの検索が上から下の方向に行われ、ワイルドカードによるサブタイプのエントリは、残りの一致するタイプを受け付けることになります。
dfltsize()
要素は、バッファの割当てまたは再割当てを行うときに使用します。tpalloc()
とtprealloc()
は、dfltsize()
の値、またはtpalloc()
およびtprealloc()
関数のsize
パラメータの値のうち、大きいほうを使用してバッファの作成または再割当てを行うことを意味します。固定サイズのC構造体など、一部のタイプの構造体では、バッファ・サイズはその構造体のサイズと同じにする必要があります。dfltsize()
をこの値に設定すると、呼出し側はバッファが渡されるルーチンに対してそのバッファの長さを指定する必要はなくなります。dfltsize()
は0またはそれ以下にすることができます。ただし、tpalloc()
またはtprealloc()
を呼び出して、そのsize
パラメータも0またはそれ以下であると、このルーチンは失敗します。dfltsize()
は0より大きい値にすることをお薦めします。
Oracle Tuxedo ATMIシステムでは、5つの基本バッファ・タイプが提供されます。
これらのバッファ・タイプの中の2つには、同等のタイプのものがあります。X_OCTET
はCARRAY
と同じであり、X_C_TYPE
とX_COMMON
の両方はVIEW
と同じです。X_C_TYPE
は、VIEW
と同じ要素をすべてサポートしますが、X_COMMON
はlongs、shortsおよびcharactersのみをサポートします。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 (flags
TPCONV) 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()
の後で呼び出されます。_tmpresend()
で説明したように、_tmencdec()
に渡されるバッファには、そのバッファに隣接しないデータを指すポインタは含まれません。
受信側では、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
構造体に直接アクセスする必要はありません。基本的なデータ構造体を理解するためにこの構造体を提示します。 莫大な十進数データを格納する必要がある場合、より圧縮した形式を得るためにstdecimal()
、lddecimal()
関数を使用します。dectoasc()
、dectoint()
、dectolong()
、dectodbl()
およびdectoflt()
を使用すると、十進数から他のデータ・タイプへ変換することができます。deccvasc()
、deccvint()
、deccvlong()
、deccvdbl()
およびdeccvflt()
を使用すると、他のデータ・タイプから十進数のデータ・タイプに変換することができます。deccmp()
は、2つの十進数を比較する関数です。 1番目の十進数が2番目の十進数より小さい場合、-1を返します。2つの十進数が等しい場合、0を返します。1番目の十進数が2番目の十進数より大きい場合1を返します。 どちらかの引数が無効である場合、-1以外の負の値を返します。decadd()
、decsub()
、decmul()
およびdecdiv()
は、十進数の算術演算を行います。
特に指定がないかぎり、これらの関数は、正常終了時には0を返し、エラー時には負の数を返します。
getURLEntityCacheDir()
- 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
構造体で表現される時間をカレンダ時間(1970年1月1日から数えた秒数)に変換します。
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],e
nd[time]]]
std
およびdst
std
)および夏時間(dst
)のタイムゾーンを表す3バイト以上の文字です。 std
だけが必須です。 dst
が無い場合、このロケールには夏時間は適用されません。 大文字と小文字をどちらでも使用できます。 先頭のコロン(:)、数字、カンマ(,)、マイナース(-)、またはプラス(+)以外のすべての文字が使用できます。
offset
offset
の形式はhh
[:mm
[:ss
]]です。分(mm
)と秒(ss
)は省略可能です。時間(hh
)は必須で、1つの数字でもかまいません。std
の次のoffset
は必須です。dst
の次にoffset
がない場合、夏時間は標準時間の1時間先であるとみなされます。1つ以上の数字を使用でき、値は常に十進数として解釈されます。時間は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はm
月の最後のd
日を意味します。これは第4週または第5週に発生します。週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文字を含まない)を返します。 maxsizeを超えた場合には、ゼロが返され、配列の内容は不定になります。
マルチスレッドのアプリケーション中のスレッドは、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
がトランザクションをサポートしないサーバーに属している場合、呼出し側がトランザクション・モードのときに、このフラグを設定しなければなりません(そうでないと、TPETRANが返されます)。 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
が発生します。ただし、例外が1つあります。その例外とは、ブロックされず、応答を期待せず、かつ呼出し側のトランザクションのかわりに送信されない(つまり、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
は最大127文字にする必要があり、NULLまたはNULL文字列("")は指定できません(「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()
を呼び出したときに使用する戻り値(rval
s)によって、トランザクションの結果に影響を与えることができます。トランザクション・モードに入ると、サーバーに出されたサービス・リクエストはすべて、トランザクションの一部として処理されます(リクエスタから明示的に別の指定がない場合)。
また、会話型サーバーに対して確立されたオープン接続があるときにプログラムがトランザクションを起動しても、これらの接続はトランザクション・モードには変わりません。 これは、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()
のいずれにも影響されません。リソース・マネージャによって実行される操作が、Oracle Tuxedo ATMIシステムのトランザクションの一部となるように、XAインタフェースを満たすリソース・マネージャをサーバーにリンクします。詳しくは、buildserver()
を参照してください。
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
が発生します。ただし、例外が1つあります。その例外とは、ブロックされず、応答を期待せず、かつ呼出し側のトランザクションのかわりに送信されない(つまり、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
引数で指定します。 バイナリ表現から文字列表現へ変換する場合は、flags
のTPTOSTRING
ビットをセットし、 文字列からバイナリへ変換する場合は、このビットをリセットします。 変換する構造体のタイプを示すフラグは次のように定義されており、同時に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 Productsをベースとするアプリケーションが、キューイング・サービス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バイトすべてが意味を持つため、ctl
msgid
によって指定された値を完全に初期化する必要があります(たとえば、NULL文字で埋めるなど)。
TPQGETBYCORRID
ctl
corrid
によって指定された相関識別子を持つメッセージのデキューをリクエストします。相関識別子は、アプリケーションがtpenqueue()
でメッセージをエンキューしたときに指定されます。また、相関識別子の値は32バイト全体が意味を持つため、ctl
corrid
によって指定された値を完全に初期化する必要があります(たとえば、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()
の呼出しが正常終了し、メッセージが明示的な優先順位でエンキューされた場合、この優先順位がctl
priority
に格納されます。優先順位は1から100以内の範囲内で、数値が高いほど優先順位も高くなります。つまり、高い数値のメッセージが低い数値のメッセージよりも先にデキューされます。優先順位によって順序付けられていないキューの場合、値は情報にすぎません。
TPQMSGID
TPQCORRID
tpdequeue()
の呼出しが正常終了し、メッセージが相関識別子によってエンキューされた場合、この相関識別子がctl
corrid
に格納されます。相関識別子の値は、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()
の呼出しが正常終了し、メッセージが応答キューによってエンキューされた場合、応答キューの名前がctl
replyqueue
に格納されます。メッセージへの応答は、リクエスト・メッセージと同じキュー・スペース内の指定された応答キューに登録されます。
TPQFAILUREQ
tpdequeue()
の呼出しが正常終了し、メッセージが失敗キューによってエンキューされた場合、失敗キューの名前がctl
failurequeue
に格納されます。失敗メッセージは、リクエスト・メッセージと同じキュー・スペース内の指定された失敗キューに登録されます。
flags
パラメータの残りのビットは、tpdequeue()
が呼び出されるとクリア(0に設定)されます。これには、TPQTOP
、TPQBEFOREMSGID
、TPQTIME_ABS
、TPQTIME_REL
、TPQEXPTIME_ABS
、TPQEXPTIME_REL
、およびTPQEXPTIME_NONE
が含まれます。 これらのビットは、tpenqueue()
の入力情報を制御するflags
パラメータの有効なビットです。
tpdequeue()
の呼出しが失敗してtperrno
にTPEDIAGNOSTIC
が設定された場合は、失敗の原因を示す値がctl
diagnostic
に戻されます。戻される可能性のある値は、この後の「診断」の項で定義しています。
また出力時には、tpdequeue()
の呼出しが正常に終了すると、ctl
appkey
にアプリケーション認証キーが設定され、ctl
cltid
にリクエストの発信元であるクライアントの識別子が設定され、ctl
urcode
にメッセージ登録時に設定されたユーザー戻り値が設定されます。
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 Productsをベースとするアプリケーションが、キューイング・サービス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
ctl
msgid
によって識別されるメッセージの前に登録されます。このリクエストは、キューが順序を無効化できるように構成されているかどうかに応じて、受け入れられない場合があります。TPQTOP
とTPQBEFOREMSGID
は、相互に排他的なフラグです。また、メッセージ識別子の値は32バイト全体が意味を持つため、ctl
msgid
によって指定された値を完全に初期化する必要があります(たとえば、NULL文字で埋めるなど)。
TPQTIME_ABS
ctl
deq_time
によって指定された時間の後で使用可能になります。deq_time
は、time
(2)、mktime
(3C)またはgp_mktime(3c)
によって生成された絶対時間値です(UTC (協定世界時) 1970年1月1日00:00:00から経過した秒数)。TPQTIME_ABS
とTPQTIME_REL
は、相互に排他的なフラグです。絶対時間は、キュー・マネージャ・プロセスが存在するマシン・クロックによって決定されます。
TPQTIME_REL
ctl
deq_time
は、エンキューの完了後から発行されたメッセージが使用可能になるまでの遅延の秒数を指定します。TPQTIME_ABS
とTPQTIME_REL
は、相互に排他的なフラグです。
TPQPRIORITY
ctl
priority
に格納されます。優先順位は、1から100以下の範囲である必要があります。数値が高いほど優先順位も高くなり、高い数値のメッセージが低い数値のメッセージより先にキューから取り出されます。優先順位によって順序付けられていないキューでは、この値は参考として使用されます。
TPQCORRID
ctl
corrid
で指定された相関識別子の値は、メッセージがtpdequeue()
によってデキューされるときに使用できます。この識別子は、エンキューされるすべての応答メッセージまたは失敗メッセージに付加されるため、アプリケーションは応答を特定のリクエストに結び付けることができます。また、相関識別子の値は32バイト全体が意味を持つため、ctl
corrid
で指定された値を完全に初期化する必要があります(たとえば、NULL文字で埋めるなど)。
TPQREPLYQ
ctl
replyqueue
で指定された応答キューは、待機メッセージに関連付けられます。メッセージに対する応答はすべて、リクエスト・メッセージと同じキュー・スペース内の指定されたキューに登録されます。この文字列は、NULLで終了する必要があります(最大127文字)。
TPQFAILUREQ
ctl
failurequeue
で指定された失敗キューは、待機メッセージに関連付けられます。(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()
の呼出しが正常終了した場合、メッセージ識別子がctl
msgid
に格納されます。メッセージ識別子の値は32バイト全体が意味を持つため、ctl
msgid
に格納される値は完全に初期化されます(たとえば、NULL文字で埋めるなど)。初期化に使用される実際の埋め文字は、Oracle Tuxedo ATMI /Qコンポーネントのリリースによって異なります。
制御構造体の残りのメンバーは、tpenqueue()
への入力に使用されません。
tpenqueue()
の呼出しが失敗してtperrno
にTPEDIAGNOSTIC
が設定された場合は、失敗の原因を示す値がctl
diagnostic
に戻されます。戻される可能性のある値は、この後の「診断」の項で定義しています。
このパラメータがNULLである場合、入力フラグは、TPNOFLAGS
とみなされ、アプリケーション・プログラムは出力情報を利用できません。
異常終了すると、tpenqueue()
は -1を返し、tperrno
を設定してエラー条件を示します。 エラーでないときは、メッセージは、tpenqueue()
の終了時に正しくキューに登録されます。
失敗すると、tpenqueue()
はtperrno
を次のいずれかの値に設定します(特に記述されていないかぎり、エラーが呼出し側のトランザクションに影響を及ぼすことはありません)。
TPEINVAL
]
TPENOENT
]
qspace
を利用できないので、これにアクセスできません(関連するTMQUEUE(5)サーバーは利用できません)。または、グローバル・トランザクション表(GTT)にエントリがないので、グローバル・トランザクションを開始できません。
TPETIME
]
TPNOBLOCK
またはTPNOTIME
が指定されている場合は発生しません。 トランザクション・タイムアウトが発生した場合、トランザクションが停止されないかぎり、新しいリクエストの送信や未処理の応答の受信はできず、TPETIME
が発生します。ただし、例外が1つあります。その例外とは、ブロックされず、応答を期待せず、かつ呼出し側のトランザクションのかわりに送信されない(つまり、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_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_ALL
long 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()
のクライアント名(つまり、tpinfo
cltname
)を指定して呼び出す必要があります。そうでないと、有効な管理キーは戻されません。
マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT
状態のスレッドはtpgetadmkey()
の呼出しを発行できません。
tpgetadmkey()
は、正常終了時には最上位ビットが設定(0x80000000)された0以外の値を戻し、異常終了時には0を戻します。tpinfo
がNULLで、tpinfo
cltname
が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
サービスへの代替リポジトリ・アクセス・インタフェースを提供します。 tpgetrepos()は、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
が発生します。ただし、例外が1つあります。その例外とは、ブロックされず、応答を期待せず、かつ呼出し側のトランザクションのかわりに送信されない(つまり、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
の文字数を超えてはなりません。MAXTIDENTは30字に定義されています。passwd
は、アプリケーション・パスワードとの認証に使用される非暗号化形式のアプリケーション・パスワードです。 一方通行の暗号化方式に関するUNIXシステムの制限から、passwd
は8文字までしか意味をもちません。grpname
は、クライアントをリソース・マネージャ・グループ名と関連付けるときに使用します。 grpname
が長さ0の文字列として設定されている場合は、クライアントはリソース・マネージャに関連付けられず、デフォルトのクライアント・グループに含まれます。 ワークステーション・クライアントの場合、grpname
の値にはNULL文字列(長さが0の文字列)を指定します。 grpname
はACLグループとは関連がないことに注意してください。
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
最初の形式では、ドメインはローカル・ネーム解決機能(通常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
set WSNADDR=(//m1.acme.com:3050^|//m2.acme.com:3050),//m3.acme.com:3050
|
)はWindowsでは特殊文字と見みなされるため、コマンドラインで指定する際は、その前にWindows環境でのエスケープ文字のカレット(^)を前に付ける必要があります。ただし、envfileでWSNADDR
が定義されている場合、Oracle Tuxedo ATMIシステムはtuxgetenv(3c)
関数を介してWSNADDR
が定義する値を取得します。この場合、パイプ記号(|
)は特殊文字とみなされないので、カレット(^
)を使用する必要はありません。 Oracle Tuxedo ATMIシステムはかっこ付きアドレスを無作為に選択します。この方法は、一連のリスナー・プロセスに対してランダムに負荷分散します。接続が確立するまで順番にアドレス指定が試みられます。ワークステーション・リスナーを呼び出すには、アプリケーションの構成ファイルの値を使用してください。この値が、"0x
"で始まる文字列の場合は、16進値文字列と解釈され、それ以外の場合は、ASCII文字列と解釈されます。
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_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()
に渡されるctl
flags
パラメータでTPEVTRAN
ビットの設定を使用したサービス・ルーチンおよび安定ストレージ上のキューのサブスクリプションのみにディスパッチします。イベント・ブローカは、クライアントへの通知、およびtpsubscribe()
に渡されるctl
flags
パラメータでTPEVTRAN
ビットの設定を使用しなかったサービス・ルーチンおよび安定ストレージ上のキューにあるサブスクリプションのディスパッチも行いますが、これはポスト元プロセスのトランザクションの一部としてではありません。
ポスト元がトランザクションの外部にある場合、イベントに関連付けられているサービスが失敗すると、tppost()
は肯定応答のない一方向のポストになります。このような状況は、イベント用にTPEVTRAN
が設定されている場合でも起こります(この設定には、tpsubscribe()
に渡されるctl
flags
パラメータを使用します)。ポスト元がトランザクション内にある場合は、イベントに関連するサービスが失敗すると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
が発生します。ただし、例外が1つあります。その例外とは、ブロックされず、応答を期待せず、かつ呼出し側のトランザクションのかわりに送信されない(つまり、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
が発生します。ただし、例外が1つあります。その例外とは、ブロックされず、応答を期待せず、かつ呼出し側のトランザクションのかわりに送信されない(つまり、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
, long
len
, long
flags
, 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
が発生します。ただし、例外が1つあります。その例外とは、ブロックされず、応答を期待せず、かつ呼出し側のトランザクションのかわりに送信されない(つまり、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以外の値を返します。
異常終了すると、tpsetctxt()は呼出しプロセスを元のコンテキストに維持したまま -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)
tpsprio()
- サービス・リクエストの優先順位の設定
#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
の絶対値で送信されます。この絶対値は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
を指定する場合は、ブール値のフィルタ・ルールを含む文字列を指定します。このルールは、イベント・ブローカがイベントをポストする前に正しく評価しなければなりません。ポストするイベントを受け取ると、イベント・ブローカはそのイベントのデータにフィルタ・ルール(存在する場合)を適用します。データがフィルタ・ルールのチェックにパスした場合、イベント・ブローカは通知メソッドを呼び出します。データがフィルタ・ルールを通過しない場合は、イベント・ブローカは対応する通知メソッドを呼び出しません。呼出し側は、異なるフィルタ・ルールを利用して同じイベントを何度でもサブスクライブすることができます。
フィルタ・ルールは、それが適用される型付きバッファに固有なものです。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 が戻されます。 |
次に、ctl
flags
要素に指定する、イベントをサブスクライブするための制御オプションの有効なビットの一覧を示します。
TPEVSERVICE
ctl
name1
という名前のOracle Tuxedo ATMIシステムのサービス・ルーチンに送信したいことを示します。この場合、eventexpr
に対して評価が成功するイベント名がポストされると、イベント・ブローカはeventexpr
に対応したフィルタ・ルールに対してポストされたデータをテストします。データがフィルタ・ルールを通過する場合、またはイベントに対するフィルタ・ルールが存在しない場合は、サービス・リクエストはイベントとともにポストされたデータと合せてctl
name1
に送信されます。ctl
name1
のサービス名には、Oracle Tuxedo ATMIシステムの有効な任意のサービス名を指定することができ、このサービスはサブスクライブされたときにアクティブである場合もあれば、アクティブでない場合もあります。イベント・ブローカによって呼び出されたサービス・ルーチンは、応答データなしで戻ります。つまり、引数にNULLデータを指定してtpreturn()
を呼び出すはずです。tpreturn()
に渡されるデータはドロップされます。TPEVSERVICE
とTPEVQUEUE
を同時に指定することはできません。
TPEVTRAN
も同時にctl
flags
に設定し、またtppost()
を呼び出すプロセスがトランザクション・モードにある場合は、イベント・ブローカはサービス・ルーチンがポスト元のトランザクションの一部となるようにサブスクライブされたサービス・ルーチンを呼び出します。イベント・ブローカ(TMUSREVT(5))とサブスクライブされたサービス・ルーチンの両方が、トランザクションをサポートするサーバー・グループに属していなければなりません(詳細は、「UBBCONFIG(5)」を参照してください)。ctl
flags
にTPEVTRAN
を設定していない場合は、イベント・ブローカは、サービス・ルーチンがポスト元のトランザクションの一部とならないように、サブスクライブされたサービス・ルーチンを呼び出します。
TPEVQUEUE
ctl
name1
という名前のキュー・スペース、およびctl
name2
という名前のキューへ登録することを希望していることを示します。この場合、eventexpr
に対して評価が成功するイベント名がポストされると、イベント・ブローカはeventexpr
に対応したフィルタ・ルールに対してポストされたデータをテストします。データがフィルタ・ルールを通過した場合、またはイベントに対応したフィルタ・ルールが存在しない場合は、イベント・ブローカはメッセージをイベントとともにポストされたデータと合せて、ctl
name1
という名前のキュー・スペース、およびctl
name2
という名前のキューに登録します。キュー・スペースとキューの名前は、Oracle Tuxedo ATMIシステムの有効な任意のキュー・スペースおよびキューの名前で、サブスクリプションの実行時に存在している場合と存在していない場合があります。
ctl
qctl
には、ポストされたイベントをイベント・ブローカがキューに登録することに関するオプションをさらに指定することができます。オプションを何も指定しない場合は、ctl
qctl.flags
をTPNOFLAGS
に設定する必要があります。それ以外の場合は、「tpenqueue(3c)」
の「制御パラメータ」の項で説明しているようにオプションを設定できます(特に、tpenqueue(3c)
への入力情報を制御するフラグの有効なリストを説明している項を参照してください)。TPEVSERVICE
とTPEVQUEUE
を同時に指定することはできません。 ctl
flags
にTPEVTRAN
も同時に指定し、tppost()
を呼び出すプロセスがトランザクション・モードにある場合は、イベント・ブローカは、ポストされたイベントとそのデータがポスト元のトランザクションの一部となるように、それらをキューに登録します。イベント・ブローカ(TMUSREVT(5))はトランザクションをサポートするサーバー・グループに属している必要があります(詳細は、「UBBCONFIG(5)」を参照してください)。ctl
flags
にTPEVTRAN
を設定しない場合は、イベント・ブローカは、ポストされたイベントとそのデータがポスト元のトランザクションの一部とならないように、それらをキューに登録します。
TPEVTRAN
TPEVSERVICE
またはTPEVQUEUE
のどちらかと同時に指定できます。
TPEVPERSIST
TPEVTRAN
と同時に指定し、イベントの通知時にリソースが利用できない場合は、イベント・ブローカはポスト元に戻り、トランザクションが中止しなければならないようにします。つまり、サブスクリプションが保持されている場合でも、リソースが使用できなければポスト元のトランザクションは失敗します。
イベント・ブローカのアクティブなサブスクリプションのリストに、tpsubscribe()
がリクエストするサブスクリプションと一致するものがある場合は、この関数は失敗してtperrno
にTPEMATCH
を設定します。サブスクリプションが既存のサブスクリプションと一致するためには、eventexpr
とfilter
の両方が、イベント・ブローカのアクティブなサブスクリプションのリストにすでに存在するサブスクリプションのeventexprとfilterに一致する必要があります。また、通知メソッドによっては、サブスクリプションの一致を判断する際にこれ以外の基準も使用されます。
サブスクライバがOracle Tuxedo ATMIシステムのクライアント・プロセスで、(イベントがポストされたときに、呼出し側が任意通知を受け取るように) ctl
にNULLを設定した場合は、システム定義によるそのクライアント識別子(CLIENTID
と呼ばれています)も一致を調べるために使用されます。つまりtpsubscribe()
は、eventexpr
、filter
、および呼出し側のCLIENTID
が、イベント・ブローカにすでに知られているサブスクリプションが持つそれらの値と一致する場合に失敗します。
呼出し側がctl
flags
をTPEVSERVICE
に設定した場合、eventexpr
、filter
、およびctl
name1
で設定されるサービス名がイベント・ブローカのリストにすでに存在するサブスクリプションのそれらと一致すると、tpsubscribe()
は失敗します。
安定ストレージ内のキュー、キュー・スペース、およびキューの名前へのサブスクリプションの場合は、一致を調べる際にeventexpr
およびfilter
に加えて相関識別子が使用されます。相関識別子を利用することにより、同じ送信先の、同じイベント式やフィルタ・ルールに対する複数のサブスクリプションを区別することができます。したがって、呼出し側がctl
flags
にTPEVQUEUE
を設定し、ctl
qctl.flags
にTPQCOORID
が設定されなかった場合、eventexpr
、filter
、ctl
name1
に設定されたキュー・スペース名、およびctl
name2
に設定されたキュー名が、イベント・ブローカにすでに知られている(相関識別子が指定された)サブスクリプションが持つそれらの値と一致するとtpsubscribe()
は失敗します。さらに、ctl
qctl.flags
にTPQCOORID
が設定されている場合は、eventexpr
、filter
、ctl
name1
、ctl
name2
、およびctl
qctl.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
が発生します。ただし、例外が1つあります。その例外とは、ブロックされず、応答を期待せず、かつ呼出し側のトランザクションのかわりに送信されない(つまり、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のイベント・ブローカのアクティブなサブスクリプションのリストからイベントのサブスクリプションまたはイベントのサブスクリプションの集合を削除します。subscription
には、tpsubscribe()
が戻したイベントのサブスクリプションのハンドルを指定します。subscription
をワイルドカード値の-1に設定すると、tpunsubscribe()
が、呼出し側のプロセスが以前に行ったすべての非持続型のサブスクリプションを削除する指示になります。非持続型のサブスクリプションとは、tpsubscribe()
のctl
flags
パラメータに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
が発生します。ただし、例外が1つあります。その例外とは、ブロックされず、応答を期待せず、かつ呼出し側のトランザクションのかわりに送信されない(つまり、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
, long
status
)
/* 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種類の例外があります。 どちらも同じ方法で宣言されますが、初期化の方法は異なります。
一方の例外はアプリケーション例外を定義するのに使用され、 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
]パラメータは、ACF (Attribute Configuration File)で定義されます)。ステータス復帰インタフェースは、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/WS 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()
は、環境変数の名前を、既存の変数を変更するか、新しい変数を作成することで値と等しくします。どちらの場合も、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
set
variable
=
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
tuxputenv()
は、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)
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
]
transaction_control
特性がTX_CHAINED
の場合は、新しいトランザクションが開始されます。
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()
を使用する方法をとることが推奨されます。これによって、常にシグナルの状態を知ることができるからです。 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);
}
![]() ![]() ![]() |