2 C言語アプリケーション・トランザクション・モニター・インタフェースの紹介

この章では、次の項目について説明します。

• 説明
  
• 通信パラダイム
  
• クライアントおよびサーバーに対するOracle Tuxedo ATMIシステムのリクエスト/ レスポンス・パラダイム
  
• クライアントおよびサーバーに対するOracle Tuxedo ATMIシステムの会話パラダイム
  
• メッセージ配信
  
• メッセージの順序付け
  
• キュー式メッセージ・モデル
  
• ATMIトランザクション
  
• TXトランザクション
  
• 連鎖および非連鎖トランザクション
  
• トランザクション特性
  
• タイムアウト
  
• 動的サービス通知
  
• バッファ・タイプ・スイッチ
  
• 非請求通知
  
• プロセスごとのシングル・コンテキストとマルチコンテキスト
  
• クライアント・スレッドのコンテキスト状態の変化
  
• スレッド・プログラミングのサポート
  
• C言語ATMIの戻り値とその他の定義
  
• C言語TXの戻り値とその他の定義
  
• ATMIの状態遷移
  
• TXの状態遷移
  
• AEMsetblockinghook(3c)
  
• AEOaddtypesw(3c)
  
• AEPisblocked(3c)
  
• AEWsetunsol(3c)
  
• buffer(3c)
  
• catgets(3c)
  
• catopen、catclose(3c)
  
• decimal(3c)
  
• getURLEntityCacheDir(3c)
  
• getURLEntityCaching(3c)
  
• gp_mktime(3c)
  
• nl_langinfo(3c)
  
• rpc_sm_allocate、rpc_ss_allocate(3c)
  
• rpc_sm_client_free、rpc_ss_client_free(3c)
  
• 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)
  
• 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)
  
• setlocale(3c)
  
• setURLEntityCacheDir(3c)
  
• setURLEntityCaching(3c)
  
• strerror(3c)
  
• strftime(3c)
  
• tpacall(3c)
  
• tpabort(3c)
  
• tpadmcall(3c)
  
• tpadvertise(3c)
  
• tpadvertisex(3c)
  
• tpalloc(3c)
  
• tpappthrinit(3c)
  
• tpappthrterm(3c)
  
• tpatz(3c)
  
• tpbegin(3c)
  
• tpbroadcast(3c)
  
• tpcacheget(3c)
  
• tpcachemremove(3c)
  
• tpcacheput(3c)
  
• tpcacheremove(3c)
  
• tpcacheremoveall(3c)
  
• tpcall(3c)
  
• tpcancel(3c)
  
• tpchkauth(3c)
  
• tpchkunsol(3c)
  
• tpclose(3c)
  
• tpcommit(3c)
  
• tpconnect(3c)
  
• tpconvert(3c)
  
• tpconvmb(3c)
  
• tpcryptpw(3c)
  
• tpdequeue(3c)
  
• tpdiscon(3c)
  
• tpenqueue(3c)
  
• tpenvelope(3c)
  
• tperrordetail(3c)
  
• tpexport(3c)
  
• tpfml32toxml(3c)
  
• tpfmltoxml(3c)
  
• tpforward(3c)
  
• tpfree(3c)
  
• tpgblktime(3c)
  
• tpgetcache(3c)
  
• tpgetadmkey(3c)
  
• tpgetcallinfo(3c)
  
• tpgetctxt(3c)
  
• tpgetlev(3c)
  
• tpgetmbenc(3c)
  
• tpgetrepos(3c)
  
• tpgetrply(3c)
  
• tpgprio(3c)
  
• tpimport(3c)
  
• tpinit(3c)
  
• tpkey_close(3c)
  
• tpkey_getinfo(3c)
  
• tpkey_open(3c)
  
• tpkey_setinfo(3c)
  
• tpnotify(3c)
  
• tpopen(3c)
  
• tppost(3c)
  
• tprealloc(3c)
  
• tprecv(3c)
  
• tpresume(3c)
  
• tpreturn(3c)
  
• tprmclose(3c)
  
• tprmend(3c)
  
• tprmopen(3c)
  
• tprmstart(3c)
  
• tpsblktime(3c)
  
• tpscmt(3c)
  
• tpseal(3c)
  
• tpsend(3c)
  
• tpservice(3c)
  
• tpsetcallinfo(3c)
  
• tpsetctxt(3c)
  
• tpsetmbenc(3c)
  
• tpsetrepos(3c)
  
• tpsetunsol(3c)
  
• tpsign(3c)
  
• tpsprio(3c)
  
• tpstrerror(3c)
  
• tpstrerrordetail(3c)
  
• tpsubscribe(3c)
  
• tpsuspend(3c)
  
• tpsvrdone(3c)
  
• tpsvrinit(3c)
  
• tpsvrthrdone(3c)
  
• tpsvrthrinit(3c)
  
• tpterm(3c)
  
• tptypes(3c)
  
• tpunadvertise(3c)
  
• tpunsubscribe(3c)
  
• tputrace(3c)
  
• tpxmltofml32(3c)
  
• tpxmltofml(3c)
  
• TRY(3c)
  
• tuxgetenv(3c)
  
• tuxgetmbaconv(3c)
  
• tuxgetmbenc(3c)
  
• tuxputenv(3c)
  
• tuxreadenv(3c)
  
• tuxsetmbaconv(3c)
  
• tuxsetmbenc(3c)
  
• tuxthrputenv(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)
  
• userlog(3c)
  
• Usignal(3c)
  
• Uunix_err(3c)
  

2.1 説明

アプリケーション・トランザクション・モニター・インタフェース(ATMI)は、アプリケーションとトランザクション処理システムの間のインタフェースを提供します。このインタフェースは、ATMIインタフェースと呼ばれています。これは、リソースのオープンとクローズ、トランザクションの管理、型付きバッファの管理、リクエスト/レスポンス型および会話型サービスの呼出しなどを行う関数呼出しを提供します。

2.2 通信パラダイム

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

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

プロセスはリクエスト/レスポンス型と会話型のコミュニケーションのいずれも行うことができますが、両方のサービス・リクエストを受け付けることはできません。以下の項では、これら2種類の通信パラダイムの詳細を説明します。

ノート:

Oracle Tuxedoドキュメントでは、スレッドという用語が随所で使用されています。この用語がマルチスレッド・アプリケーションの説明で使用されている場合、その意味は明白です。ただし、場合によっては、シングルスレッド・アプリケーションとマルチスレッド・アプリケーションの両方に関連するトピックの説明でこの用語が使用されていることがあります。この場合、シングルスレッド・アプリケーションを実行している読者は、スレッドという用語はプロセス全体と表していると想定できます

2.3 クライアントおよびサーバーに対するOracle Tuxedo ATMIシステムのリクエスト/ レスポンス・パラダイム

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

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

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

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

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

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

2.4 クライアントおよびサーバーに対するOracle Tuxedo ATMIシステムの会話パラダイム

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

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

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

接続が確立すると、接続記述子により、参加リソースのアドレッシング情報に関して必要なコンテキストが示されます。メッセージは、アプリケーション側の規定に従って送受信することができます。リクエスト・メッセージと応答メッセージの間には本質的な相違はなく、またメッセージの優先度に関する規定もありません。

2.5 メッセージ配信

会話モードまたはリクエスト/レスポンス・モードのいずれにおいても、メッセージの送受信とは、2つのアプリケーション・ユニット間の通信を意味します。大部分のメッセージに対しては、応答または少なくとも確認が行われ、メッセージが受信されたことが確認されます。しかし、応答または確認を必要としないメッセージ(一部はシステムによって生成されたもので、その他はアプリケーションによって生成されたもの)があります。たとえば、システムはTPACK()フラグを設定せずにtpnotify()を使用することにより、任意通知型メッセージを送信でき、アプリケーションはTPNOREPLY()フラグを設定してtpacall()を使用することにより、メッセージを送信できます。受信プログラムのメッセージ・キューがいっぱいの場合、メッセージは破棄されます。

送信側と受信側が異なるマシン上にある場合、通信は、ネットワーク経由でメッセージを送受信するブリッジ・プロセス間で行われます。これにより、回線障害によって配信されなくなるという新たな可能性が生じます。これらの状況によってイベントまたはULOGメッセージが生成されても、イベントまたはULOGメッセージを特定のメッセージの非着信と関連付けることは容易ではありません。

Oracle Tuxedo ATMIシステムは、ブロード・ネットワーク間で大量のメッセージを処理するよう設計されているため、前の段落で説明したわずかなパーセントの配信の失敗を検出および修正するようにはプログラムされていません。このため、すべてのメッセージが配信されることを保証することはできません。

2.6 メッセージの順序付け

会話モデルでは、tpsend()およびtprecv()を使用して交換されるメッセージには、メッセージ・ヘッダーに順序番号が付けられ、メッセージは送信された順序で受信されます。サーバーまたはクライアントが順序を間違えてメッセージを受信した場合、会話が停止し、進行中のすべてのトランザクションがロールバックされ、LIBTUXのメッセージ1572 (Bad Conversational Sequence Number)が記録されます。

リクエスト/レスポンス・モデルでは、メッセージはシステムにより順序付けされません。アプリケーション・ロジックで順序が暗示される場合、順序のモニターと制御はアプリケーションの責任になります。ブリッジ・プロセスに対する複数のネットワーク・アドレスのサポートによって同時メッセージ伝送が可能になると、送信された順序でメッセージが受信されない可能性が高くなります。これを懸念するアプリケーションでは、各ブリッジ・プロセスに対して単一のネットワーク・アドレスを指定したり、メッセージに順序番号を追加したり、定期的な確認を必須にしたりすることが選択されます。

2.7 キュー式メッセージ・モデル

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

キュー式メッセージ機能は、XA準拠のリソース・マネージャで提供されます。永続的なメッセージはトランザクション内でエンキューまたはデキューされ、一度のみ処理されます。

2.8 ATMIトランザクション

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

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

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

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

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

2.9 TXトランザクション

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

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

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

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

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

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()を呼び出すには、非連鎖モードに切り替えて、現在のトランザクションを完了してから呼び出す必要があります。

2.11 トランザクション特性

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

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

エラー処理

ほとんどのATMI関数は、1つまたは複数の戻り値を返します。 エラーの条件は、エラーの他には考えられない戻り値で示されます。通常、エラーであれば-1、不正なフィールド識別子(BADFLDID)またはアドレスであれば0です。エラー・タイプは外部整数tperrnoで取得することもできます。tperrnoは、正常呼出しではクリアされないので、エラーが示された後でのみテストします。

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

tperrordetail()を3ステップの手順の最初のステップとして使用すると、現在のスレッドへのOracle Tuxedo ATMIシステムの最新の呼出しで発生したエラーの詳細を取得できます。tperrordetail()が返す整数値は、tpstrerrordetail()の引数として使用され、エラー・メッセージを表す文字列を指すポインタを取得します。このポインタは、userlogまたはfprintf()の引数として使用できます。

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

Fstrerror()、およびこれに対応するFstrerror32()を使用すると、FMLエラー・メッセージのテキストをメッセージ・カタログから取得できます。これは、userlogの引数として使用できるポインタを戻します。

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

2.12 タイムアウト

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がポストされます。

2.13 動的サービス通知

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

バッファ管理

当初、プロセスにはバッファがありません。メッセージの送信前に、tpalloc()を使用してバッファを割り当てる必要があります。その後、送信側のデータがバッファに入れられ、送信されます。このバッファには特殊な構造体があります。この特殊な構造体は、tpalloc()関数のtype引数によって表されます。いくつかの構造体はさらなる分類を必要とするため、サブタイプも指定できます(C構造体の特殊タイプなど)。

メッセージを受信するとき、アプリケーション・データを受信するためのバッファが必要です。このバッファは、最初はtpalloc()から取得する必要があります。Oracle Tuxedo ATMIシステム・サーバーは、mainでバッファを割り当てます。サービスを呼び出すときに、そのアドレスがリクエスト/レスポンス型または会話型サービスに渡されます。(このバッファの処理の詳細は、「tpservice(3c)」を参照してください。)

メッセージの受信に使用されるバッファを扱う方法は、送信に使用されるバッファとは少し異なります。通常、サイズとアドレスはメッセージを受信すると変わります。受信呼出しに渡されたバッファと、システムがバッファの処理に使用した内部バッファが内部で交換されるためです。バッファはデータを受信すると、サイズが大きくなるか小さくなります。大きくなるか小さくなるかは、送信者が送信したデータ容量と、送信者から受信者へのデータを取得するために必要な内部データ・フローによって異なります。圧縮、異なる種類のマシンからのメッセージの受信、使用中のバッファ・タイプに対するpostrecv()関数のアクションなど、多くの要因がバッファのサイズに影響します(「buffer(3c)」を参照)。通常、ワークステーション・クライアントのバッファ・サイズはネイティブ・クライアントのバッファ・サイズとは異なります。

受信バッファは、メッセージを受信する実際のコンテナではなく、プレースホルダーであるとみなすのが最善です。システムでは、ユーザーが渡すバッファのサイズをヒントとして使用することがあるため、このサイズが予想される応答を保持するために十分であると役立ちます。

送信側では、割り当てられた容量よりも少ない容量が書き込まれる可能性のあるバッファ・タイプ(FMLまたはSTRINGバッファなど)は、使用された量のみを送信します。1つの整数フィールドを含む100KのFML32バッファは、その整数のみを含む、非常に小さいバッファとして送信されます。

これは、受信者が、送信者の割り当てたバッファ・サイズより小さく、送信されたデータのサイズより大きいバッファを受け取ることを意味します。たとえば、10KBのSTRINGバッファが割り当てられ、文字列HELLOがバッファにコピーされた場合、6バイトのみが送信され、受信者が得るバッファはおそらく1KB - 4KBになります。(他の要因により、大きくなることも小さくなることもあります。)Oracle Tuxedo ATMIシステムで保証されるのは、送信されたすべてのデータが受信メッセージに含まれるということだけです。メッセージに本来含まれていたすべての空白が含まれることは保証されません。

応答を受け取るプロセスは、(tptypes()を使用して)バッファのサイズ変更を記録し、必要に応じてバッファの再割当てを行うことに責任を持ちます。すべてのOracle Tuxedo ATMI関数は、バッファ内のデータ量に関する受信側のバッファの戻り情報を変更するため、標準の手法として、応答を受け取るたびにバッファ・サイズをチェックする必要があります。

同じデータ・バッファを使用して、メッセージを送信および受信することができます。または、各メッセージに異なるデータ・バッファを割り当てることもできます。通常、tpfree()を呼び出してバッファを解放するのは、呼出し側プロセスの責任です。ただし、かぎられた状況では、Oracle Tuxedo ATMIシステムによって呼出し側のバッファが解放されます。バッファの使用方法の詳細は、tpfree()などの通信関数の説明を参照してください。

2.14 バッファ・タイプ・スイッチ

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つの基本バッファ・タイプが提供されます。

• CARRAY - 送信時にエンコードもデコードも行われない文字配列(多くの場合、NULL文字を含む)
• STRING - NULLで終わる文字配列
• FML - フィールド化バッファ(FMLまたはFML32)
• XML - XMLドキュメントまたはデータグラム・バッファ
• VIEW - 単純なC構造体(VIEWまたはVIEW32)。すべてのビューは同じルーチン・セットで処理され、特定のビューの名前はそのサブタイプの名前です。

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

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

2.15 非請求通知

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

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

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

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

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

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

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

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

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

表2-1 プロセスごとのコンテキスト・モード

関数	非初期化状態(S0 )	シングル・コンテキスト・モードで初期化された状態(S1)	マルチコンテキスト・モードで初期化された状態(S2)
TPMULTICONTEXTSが設定されていないtpinit	S1	S1	S2(error)
TPMULTICONTEXTSが設定されたtpinit	S2	S1(error)	S2
暗黙的なtpinit	S1	S1	S2(error)
tpterm - 最後の関連付けでない	-	-	S2
tpterm - 最後の関連付け	-	S0	S0
tpterm - 関連付けなし	S0	-	-

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

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

マルチコンテキスト状態の遷移

図2-1 クライアント・スレッドのコンテキスト状態の変化

ノート:

tpterm()がマルチコンテキスト状態(TPMULTICONTEXTS)で実行しているスレッドによって呼び出されると、呼出し側スレッドはNULLコンテキスト状態(TPNULLCONTEXT)になります。終了するコンテキストに関連するその他すべてのスレッドは、無効コンテキスト状態(TPINVALIDCONTEXT)に切り替わります。

次の表は、tpinit()、tpsetctxt()およびtpterm()の呼出しによって発生する可能性のある、すべてのコンテキスト状態の変化を示しています。これらの状態はスレッド固有であり、マルチコンテキスト・アプリケーションの一部である場合、スレッドごとに状態が異なる可能性があります。これに対し、前の表(表2-1)に示されている各コンテキスト状態は、プロセス全体に適用されます。

この関数が実行されるとき	NULL状態コンテキスト	シングル状態コンテキスト	マルチ状態コンテキスト	無効な状態コンテキスト
TPMULTICONTEXTSが設定されていないtpinit	シングル・コンテキスト	シングル・コンテキスト	エラー	エラー
TPMULTICONTEXTSが設定されたtpinit	マルチコンテキスト	エラー	マルチコンテキスト	エラー
TPNULLCONTEXTへのtpsetctxt	NULL	エラー	NULL	NULL
コンテキスト0へのtpsetctxt	エラー	シングル・コンテキスト	エラー	エラー
コンテキスト> 0へのtpsetctxt	マルチコンテキスト	エラー	マルチコンテキスト	マルチコンテキスト
暗黙的なtpinit	シングル・コンテキスト	N/A	N/A	エラー
このスレッドでのtpterm	NULL	NULL	NULL	NULL
このコンテキストの異なるスレッドでのtpterm	N/A	NULL	無効	N/A

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

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)
• tpfml32toxml(3c)
• tpfmltoxml(3c)
• tpfree(3c)
• tpgblktime(3c)
• tpgetctxt(3c)
• tpgetrepos(3c)
• tprealloc(3c)
• tpsblktime(3c)
• tpsetctxt(3c)
• tpsetrepos(3c)
• tpstrerror(3c)
• tpstrerrordetail(3c)
• tpstrerrordetail(3c)
• tpterm(3c)
• tptypes(3c)
• tpxmltofml32(3c)
• tpxmltofml(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)

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

次の戻り値とフラグの定義は、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;

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

次の戻り値とフラグの定義は、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 */

2.21 ATMIの状態遷移

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

ノート:

tpsvrinit()、tpsvrdone()、tpsvrthrinit()およびtpsvrthrdone()は、アプリケーションからは呼び出されないため、この表には示されていません(つまり、これらはアプリケーションが提供する関数ですが、Oracle Tuxedo ATMIシステムによって呼び出されます)。

表2-2 使用可能な関数

関数	リクエスト/レスポンス型サーバー(プロセス・タイプ)	会話型サーバー(プロセス・タイプ)	クライアント(プロセス・タイプ)
tpabort	Y	Y	Y
tpacall	Y	Y	Y
tpadvertise	Y	Y	N
tpalloc	Y	Y	Y
tpbegin	Y	Y	Y
tpbroadcast	Y	Y	Y
tpcall	Y	Y	Y
tpcancel	Y	Y	Y
tpchkauth	Y	Y	Y
tpchkunsol	N	N	Y
tpclose	Y	Y	Y
tpcommit	Y	Y	Y
tpconnect	Y	Y	Y
tpdequeue	Y	Y	Y
tpdiscon	Y	Y	Y
tpenqueue	Y	Y	Y
tpfmltoxml	Y	Y	Y
tpfml32toxml	Y	Y	Y
tpforward	Y	N	N
tpfree	Y	Y	Y
tpgblktime	Y	Y	Y
tpgetctxt	Y	Y	Y
tpgetlev	Y	Y	Y
tpgetrepos	Y	Y	N
tpgetrply	Y	Y	Y
tpgprio	Y	Y	Y
tpinit	N	N	Y
tpnotify	Y	Y	Y
tpopen	Y	Y	Y
tppost	Y	Y	Y
tprealloc	Y	Y	Y
tprecv	Y	Y	Y
tpresume	Y	Y	Y
tpreturn	Y	Y	N
tpsblktime	Y	Y	Y
tpscmt	Y	Y	Y
tpsend	Y	Y	Y
tpservice	Y	Y	N
tpsetctxt	Y (アプリケーション生成スレッドの場合)	Y (アプリケーション生成スレッドの場合)	Y
tpsetrepos	Y	Y	N
tpsetunsol	N	N	Y
tpsprio	Y	Y	Y
tpsubscribe	Y	Y	Y
tpsuspend	Y	Y	Y
tpterm	N	N	Y
tptypes	Y	Y	Y
tpunadvertise	Y	Y	N
tpunsubscribe	Y	Y	Y
tpxmltofml	Y	Y	Y
tpxmltofml32	Y	Y	Y

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

次の表は、クライアント・プロセスのスレッドがトランザクション・マネージャで初期化され登録されているかどうかを示しています。この表では、tpinit()を使用していると想定していますが、これは、シングル・コンテキスト・モードでは任意です。つまり、シングル・コンテキストのクライアントは、多数のATMI関数のどれか(たとえば、tpconnect()またはtpcall())を発行することによって、暗黙的にアプリケーションに参加することができます。次のいずれかに該当する場合、クライアントはtpinit()を使用する必要があります。

• アプリケーション認証が必須の場合(詳細は、「tpinit(3c)」およびUBBCONFIG(5)に関する項のSECURITYキーワードの説明を参照してください。)
• クライアントがXA準拠のリソース・マネージャに直接アクセスする場合(詳細は、「tpinit(3c)」を参照してください。)
• クライアントがXA準拠のリソース・マネージャに直接アクセスする場合(詳細は、「tpinit(3c)」を参照してください。)
• クライアントが複数のアプリケーション関連を作成する場合

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

関数	非初期化状態(I0)	初期化状態(I1)
tpalloc	I0	I1
tpchkauth	I0	I1
tpfree	I0	I1
tpgetctxt	I0	I1
tpinit	I1	I1
tprealloc	I0	I1
tpsetctxt (NULL以外のコンテキストに設定)	I1	I1
tpsetctxt (TPNULLCONTEXTコンテキストを設定)	I0	I0
tpsetunsol	I0	I1
tpterm (このスレッド内)	I0	I0
tpterm (このコンテキストの別のスレッド内)	I0	I0
tptypes	I0	I1
ほかのすべてのATMI関数	I1	I1

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

次の表は、プロセスに関連付けられているリソース・マネージャが初期化されているかどうかに関して、クライアントまたはサーバーの状態を示しています。

関数	クローズ状態(R0)	オープン状態(R1)
tpopen	R1	R1
tpclose	R0	R0
tpbegin	-	R1
tpcommit	-	R1
tpabort	-	R1
tpsuspend	-	R1
tpresume	-	R1
フラグTPTRANが設定されたtpservice	-	R1
ほかのすべてのATMI関数	R0	R1

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

関数	トランザクション状態ではない(T0)	イニシエータ状態(T1)	参加者状態(T2)
tpbegin	-	-	-
tpabort	-	T0	-
tpcommit	-	T0	-
tpsuspend	-	T0	-
tpresume	T1	T0	-
フラグTPTRANが設定されたtpservice	T2	-	-
tpservice (トランザクション・モードでない)	T0	-	-
tpreturn	T0	-	T0
tpforward	T0	-	T0
tpclose	R0	-	-
tpterm	I0	T0	-
ほかのすべてのATMI関数	T0	T1	T2

次の表は、tpacall()によって戻される1つのリクエスト記述子の状態を示しています。

関数	記述子なしの状態(A0)	有効な記述子の状態(A1)
tpacall	A1	-
tpgetrply	-	A0
tpcancel	-	A0 a
tpabort	A0	A0 b
tpcommit	A0	A0 b
tpsuspend	A0	A1c
tpreturn	A0	A0
tpforward	A0	A0
tpterm	I0	I0
ほかのすべてのATMI関数	A0	A1

ノート:

• ^a この状態遷移は、記述子が呼出し側のトランザクションに関連付けられていない場合にのみ発生します。
• ^b この状態遷移は、記述子が呼出し側のトランザクションに関連付けられている場合にのみ発生します。
• ^c この状態遷移は、記述子が呼出し側のトランザクションに関連付けられていない場合にのみ発生します。

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

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

• C₀ - 記述子なし
• C₁ - tpconnect()記述子送信専用
• C₂ - tpconnect()記述子受信専用
• C₃ - TPSVCINFO記述子送信専用
• C₄ - TPSVCINFO記述子受信専用

関数/イベント	状態(C0)	状態(C1)	状態(C2)	状態(C3)	状態(C4)
TPSENDONLYが設定されたtpconnect	C1a	-	-	-	-
TPRECVONLYが設定されたtpconnect	C2a	-	-	-	-
フラグTPSENDONLYが設定されたtpservice	C3b	-	-	-	-
フラグTPRECVONLYが設定されたtpservice	C4 b	-	-	-	-
tprecv/イベントなし	-	-	C2	-	C4
tprecv/TPEV_SENDONLY	-	-	C1	-	C3
tprecv/TPEV_DISCONIMM	-	-	C0	-	C0
tprecv/TPEV_SVCERR	-	-	C0	-	-
tprecv/TPEV_SVCFAIL	-	-	C0	-	-
tprecv/TPEV_SVCSUCC	-	-	C0	-	-
tpsend/イベントなし	-	C1	-	C3	-
フラグTPRECVONLYが設定されたtpsend	-	C2	-	C4	-
tpsend/TPEV_DISCONIMM	-	C0	-	C0	-
tpsend/TPEV_SVCERR	-	C0	-	-	-
tpsend/TPEV_SVCFAIL	-	C0	-	-	-
tpterm (クライアントのみ)	C0	C0	-	-	-
tpcommit (オリジネータのみ)	C0	C0c	C0c	-	-
tpsuspend (オリジネータのみ)	C0	C1d	C2 d	-	-
tpabort (オリジネータのみ)	C0	C0c	C0c	-	-
tpdiscon	-	C0	C0	-	-
tpreturn (CONVサーバー)	-	C0	C0	C0	C0
tpforward (CONVサーバー)	-	C0	C0	C0	C0
ほかのすべてのATMI関数	C0	C1	C2	C3	C4

ノート:

• ^a プロセスがトランザクション・モードでTPNOTRANの指定がない場合、接続はトランザクション・モードになります。
• ^b TPTRANフラグが設定されている場合、接続はトランザクション・モードになります。
• ^c接続がトランザクション・モードにない場合、状態は変化しません。
• ^d 接続がトランザクション・モードの場合、tpsuspend()はプロトコル・エラーを戻します。

2.22 TXの状態遷移

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

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

• S₀: どのRMもオープンまたは初期化が行われていません。アプリケーションの関連付けは、tx_openを正常に呼び出すまで、グローバル・トランザクションを開始できません。
• S₁: アプリケーションの関連付けはRMをオープンしましたが、トランザクションに入っていません。transaction_control特性はTX_UNCHAINEDです
• S₂: アプリケーションの関連付けはRMをオープンしましたが、トランザクションに入っていません。transaction_control特性はTX_CHAINEDです
• S₃: アプリケーションの関連付けはRMをオープンし、トランザクションに入っています。transaction_control特性はTX_UNCHAINEDです
• S₄: アプリケーションの関連付けはRMをオープンし、トランザクションに入っています。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_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()を呼び出したかに関係なく、ロールバック(中断)されます

表2-3 TX関数の状態遷移

関数	状態0	状態1	状態2	状態3	状態4
tx_begin	-	S3	S4	-	-
tx_close	S0	S0	S0	-	-
tx_commit −> TX_SET1	-	-	-	S1	S4
tx_commit −> TX_SET2	-	-	-	-	S2
tx_info	-	S1	S2	S3	S4
tx_open	S1	S1	S2	S3	S4
tx_rollback −> TX_SET1	-	-	-	S1	S4
tx_rollback −> TX_SET2	-	-	-	-	S2
tx_set_commit_return	-	S1	S2	S3	S4
tx_set_transaction_control control = TX_CHAINED	-	S2	S2	S4	S4
tx_set_transaction_control control = TX_UNCHAINED	-	S1	S1	S3	S3
tx_set_transaction_timeout	-	S1	S2	S3	S4

• 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)

2.23 AEMsetblockinghook(3c)

名前

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

形式

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

説明

AEMsetblockinghook()は、MacのタスクでATMIネットワーキング・ソフトウェアがブロッキングATMI呼出しを実装するための新しい関数をインストールできる、Mac用のATMI拡張機能です。この関数には、インストールするブロッキング関数の関数アドレスへのポインタが必要です。

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

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

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

戻り値

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

エラー

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

[TPEPROTO]

AEMsetblockinghook()が、ブロッキング操作の実行中に呼び出されました。

移植性

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

注意事項

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

2.24 AEOaddtypesw(3c)

名前

AEOaddtypesw() - 実行時にユーザー定義のバッファ・タイプをインストールまたは置換します。

形式

#include <atmi.h>
#include <tmtypes.h>

int FAR PASCAL AEOaddtypesw(TMTYPESW *newtype)

説明

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

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

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

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

戻り値

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

エラー

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

[TPEINVAL]

AEOaddtypesw()が呼び出され、typeパラメータはNULLでした。

[TPEINVAL]

AEOaddtypesw()が呼び出され、typeパラメータはNULLでした。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

移植性

このインタフェースは、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);
}
The application Module Definition File:
; EXAMPLE.DEF file

NAME EXAMPLE

DESCRIPTION 'EXAMPLE for OS/2'

EXETYPE OS/2


EXPORTS
Nfinit
Nfreinit
Nfuninit

関連項目:

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

2.25 AEPisblocked(3c)

名前

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つ以上存在することは禁止されています。

関連項目:

AEMsetblockinghook(3c)

2.26 AEWsetunsol(3c)

名前

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

形式

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

説明

Microsoft Windowsのプログラミング環境によっては、Oracle Tuxedo ATMIシステムの任意通知型メッセージをWindowsイベント・メッセージ・キューに送信するのが自然であり、便利なことがあります。

AEWsetunsol()は、通知するウィンドウ(hWnd)と、送信するWindowsメッセージ・タイプ(wMsg)を制御します。Oracle Tuxedo ATMI任意通知型メッセージが到着すると、Windowsメッセージが送信されます。lParam()は、Oracle Tuxedo ATMIシステム・バッファ・ポインタに設定されます(なしの場合はゼロに設定されます)。lParam()がゼロでなければ、アプリケーションはtpfree()を呼び出し、バッファを解放する必要があります。

wMsgがゼロであれば、その後の任意通知型メッセージはログに記録され、無視されます。

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

戻り値

異常終了時には、AEWsetunsol()は-1を返し、tperrnoを設定してエラー条件を示します。

エラー

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

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。

移植性

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

注意事項

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

関連項目:

tpsetunsol(3c)

2.27 buffer(3c)

名前

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

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

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

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

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

_tmreinitbuf

_tmreinitbuf()は、再割当てされたバッファの再初期化に使用される点を除いて、_tminitbuf()と同様に動作します。このルーチンは、バッファの再割当ての後、tprealloc()の中から呼び出されます。

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

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

_tmuninitbuf

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

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

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

_tmpresend

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

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

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

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

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

_tmpostsend

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

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

_tmpostrecv

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

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

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

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

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

_tmencdec

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

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

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

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

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

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

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

ネットワーク上に異種のマシンが存在する場合でもデータのエンコードまたはデコードを実行する必要がない場合は、NULL関数ポインタを指定します。デフォルト・ルーチンは、olen (opはTMENCODEと同じ)またはelen (opはTMDECODEと同じ)を戻します。

正常終了の場合、_tmencdec()は、前述のように負でないバッファ長を戻します。異常終了の場合、-1を返し、これにより_tmencdec()の呼出し側も異常終了を返してtperrnoをTPESYSTEMに設定します。

_tmroute

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

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

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

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

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

_tmfilter

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

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

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

_tmformat

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

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

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

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

_tmpresend2

_tmpresend2()は、tpcall()、tpacall()、tpconnect()、tpsend()、tpbroadcast()、tpnotify()、tpreturn()およびtpforward()でバッファが送信される前に呼び出されます。また、_tmroute()の後(ただし、_tmencdec()の前)にも呼び出されます。iptrがNULLでない場合、バッファの送信前にバッファに対して前処理が行われます。

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

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

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

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

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

[TMPARENT]

これは、親バッファ(送信先バッファ)です。

flagsで戻されるフラグは、_tmpresend2()の結果を示します。使用可能な値:

[TMUSEIPTR]

_tmpresend2()が成功しました。処理されたデータはiptrが参照するバッファ内にあり、戻り値には送信されたデータの長さが含まれます。

[TMUSEOPTR]

_tmpresend2()が成功しました。処理されたデータはoptrが参照するバッファ内にあり、戻り値には送信されたデータの長さが含まれます。

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

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

• 伝送処理で作成されるバッファは、入力バッファの最大長よりも長いこと。
• バッファの伝送準備を元に戻すのは非常に複雑な作業で、データを別のバッファにコピーする方が簡単であること。

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

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

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

_tmconvmb

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

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

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

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

flagsで返される値は、_tmconvmb()の結果を示します。使用可能な値:

[TMUSEIPTR]

_tmconvmb()が成功しました。処理されたデータはibufpが参照するバッファ内にあり、戻り値にはサービスに渡された変換済データの長さが含まれます。

[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)

2.28 catgets(3c)

名前

catgets() - プログラム・メッセージを読み取ります。

形式

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

説明

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

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

診断

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

関連項目:

catopen、catclose(3c)

2.29 catopen、catclose(3c)

名前

catopen()、catclose() - メッセージ・カタログをオープンまたはクローズします。

形式

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

説明

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

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

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

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

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

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

次の表は、メタ文字セットのリストです。

メタ文字	説明
%N	catopenに渡される名前パラメータの値
%L	LANGの値
%l	LANGの言語要素の値
%t	LANGの地域要素の値
%c	LANGのコードセット要素の値
%%	1文字の%。

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

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

LANG=De_A.88591

この設定により、ユーザーは関連するカタログが存在する場合、それらのカタログを見つけることができます。

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

oflag()は将来の用途のために予約されており、0に設定する必要があります。このフィールドの値を別の値に変更した場合の動作は不定です。

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

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

診断

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

関連項目:

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

2.30 decimal(3c)

名前

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

形式

#include “decimal.h”
int
lddecimal(cp, len, np) /* load a decimal */
char*cp; /* input: location of compacted format */
int
len; /* input: length of compacted format */
dec_t*np; /* output: location of dec_t format */
void
stdecimal(np, cp, len) /* store a decimal */
dec_t*np; /* input: location of dec_t format */
char*cp; /* output: location of compacted format */
int len; /* input: length of compacted format */
int
deccmp(n1, n2) /* compare two decimal numbers */
dec_t*n1; /* input: number to be compared */
dec_t*n2; /* input: number to be compared */
int
dectoasc(np, cp, len, right) /* convert dec_t to ascii */
dec_t*np; /* input: number to be converted */
char*cp; /* output: number after conversion */
int len; /* input: length of output string */
int right; /* input: number of places to right of decimal point */
int
deccvasc(cp, len, np) /* convert ascii to dec_t */
char*cp; /* input: number to be converted */
int len; /* input: maximum length of number to be converted */
dec_t*np; /* output: number after conversion */
int
dectoint(np, ip) /* convert int to dec_t */
dec_t*np; /* input: number to be converted */
int *ip; /* output: number after conversion */
int
deccvint(in, np) /* convert dec_t to int */
int in; /* input: number to be converted */
dec_t*np; /* output: number after conversion */
int
dectolong(np, lngp) /* convert dec_t to long */
dec_t*np; /* input: number to be converted */
long*lngp; /* output: number after conversion */
int
deccvlong(lng, np) /* convert long to dec_t */
longlng; /* input: number to be converted */
dec_t*np; /* output: number after conversion */
int
dectodbl(np, dblp) /* convert dec_t to double */
dec_t*np; /* input: number to be converted */
double *dblp; /* output: number after conversion */
int
deccvdbl(dbl, np) /* convert double to dec_t */
double *dbl; /* input: number to be converted */
dec_t*np; /* output: number after conversion */
int
dectoflt(np, fltp) /* convert dec_t to float */
dec_t*np; /* input: number to be converted */
float*fltp; /* output: number after conversion */
int
deccvflt(flt, np) /* convert float to dec_t */
double *flt; /* input: number to be converted */
dec_t*np; /* output: number after conversion */
int
decadd(*n1, *n2, *n3) /* add two decimal numbers */
dec_t*n1; /* input: addend */
dec_t*n2; /* input: addend */
dec_t*n3; /* output: sum */
int
decsub(*n1, *n2, *n3) /* subtract two decimal numbers */
dec_t*n1; /* input: minuend */
dec_t*n2; /* input: subtrahend */
dec_t*n3; /* output: difference */
int
decmul(*n1, *n2, *n3) /* multiply two decimal numbers */
dec_t*n1; /* input: multiplicand */
dec_t*n2; /* input: multiplicand */
dec_t*n3; /* output: product */
int
decdiv(*n1, *n2, *n3) /* divide two decimal numbers */
dec_t*n1; /* input: dividend */
dec_t*n2; /* input: divisor */
dec_t*n3; /* output: quotient */

説明

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

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

ネイティブの十進数表現

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

#define DECSIZE 16
struct decimal {
    short dec_exp; /* exponent base 100 */
    short dec_pos; /* sign: 1=pos, 0=neg, -1=null */
    short dec_ndgts; /* number of significant digits */
    char dec_dgts[DECSIZE]; /* actual digits base 100 */
};
typedef struct decimal dec_t;

プログラマがdec_t構造体に直接アクセスする必要はまったくありませんが、これによって基礎となるデータ構造を理解することができます。大容量の10進数データを格納する必要がある場合、stdecimal()関数とlddecimal()関数を使用すると形式を小さくすることができます。dectoasc()、dectoint()、dectolong()、dectodbl()およびdectoflt()を使用すると、10進数を他のデータ型に変換できます。deccvasc()、deccvint()、deccvlong()、deccvdbl()およびdeccvflt()を使用すると、他のデータ型を10進数データ型に変換できます。deccmp()は2つの10進数を比較する関数です。1つ目の10進数が2つ目の10進数よりも小さい場合は-1、等しい場合は0、1つ目が大きい場合は1が返されます。-1以外の負の値は、いずれかの引数が無効な場合に返されます。decadd()、decsub()、decmul()およびdecdiv()は、10進数の算術演算を行います。

戻り値

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

2.31 getURLEntityCacheDir(3c)

名前

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

形式

char * getURLEntityCacheDir()

説明

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

• XercesDOMParser
• SAXparser

2.32 getURLEntityCaching(3c)

名前

GetURLEntityCaching() - DTD、スキーマおよびエンティティ・ファイルのキャッシング・メカニズムを取得するXercesクラス・メソッドを指定します。

形式

bool getURLEntityCaching()

説明

GetURLEntityCaching()は、DTD、スキーマおよびエンティティ・ファイルのキャッシングがオンかオフかを判別するために呼び出されるメソッドです。キャッシングがオンの場合はtrue、オフの場合はfalseが返されます。このメソッドは、以下の2つのXercesオブジェクトと組み合せて排他的に使用されます。

• XercesDOMParser
• SAXparser

2.33 gp_mktime(3c)

名前

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

形式

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

説明

gp_mktime()は、timeptrが指すtm構造体で表現される時間をカレンダ時間(協定世界時(UTC) 1970年1月1日00:00:00から経過した秒数)に変換します。

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

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()を呼び出すことができます。

例

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

#include <stdio.h>
#include <time.h>

static char *const wday[] = {
"Sunday", "Monday", "Tuesday", "Wednesday",
"Thursday", "Friday", "Saturday", "-unknown-"
};

struct tm time_str;
/*...*/
time_str.tm_year = 2001 - 1900;
time_str.tm_mon = 7 - 1;
time_str.tm_mday = 4;
time_str.tm_hour = 0;
time_str.tm_min = 0;
time_str.tm_sec = 1;
time_str.tm_isdst = -1;
if (gp_mktime(time_str) == -1)
    time_str.tm_wday=7;
printf("%s\en", wday[time_str.tm_wday]);

注意事項

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

移植性

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

後者の場合、TZ環境変数が設定されていなければなりません。

ノート:

多くのインストレーションでは、TZは、ユーザーがログオンする際にデフォルトで正しい値に設定されます。

TZのデフォルト値はGMT0です

TZの形式は次の通りです。

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

stdおよびdst

標準(std)および夏時間(dst)のタイムゾーンを表す3バイト以上の文字です。stdのみが必須です。dstがない場合、このロケールには夏時間は適用されません。大文字と小文字をどちらでも使用できます。先頭のコロン(:)、数字、カンマ(,)、マイナス(-)、またはプラス(+)以外のすべての文字が使用できます。

offset

協定世界時に到達するためにローカル時間に加算しなければならない値を表します。offsetの形式はhh[:mm[:ss]]です。分(mm)と秒(ss)は省略可能です。時間(hh)は必須で、1つの数字でもかまいません。stdの次のoffsetは必須です。dstの次にoffsetがなければ、夏時間は標準時間の1時間先であるとみなされます。1桁または複数の桁を使用できます。値は常に10進数に解釈されます。時間は0から24の間でなければならず、分(および秒)は、もしあれば、0から59の間でなければなりません。範囲外の値は、予期できない動作を引き起こす場合があります。先頭に"-"がつくと、タイムゾーンはグリニッジ子午線の東にあります。それ以外の場合、タイムゾーンは西にあります(省略可能な"+"符号で示してもかまいません)。

start/time、end/time

いつ夏時間に変更し、いつ戻すかを示します。ここで、start/timeは、いつ標準時間から夏時間への変更が発生しするかを示し、end/timeは、逆の変更がいつ起こるかを示します。それぞれのtimeフィールドは、ローカル時間で、いつ変更が行われるかを示します。

startとendの形式は次のうちのどれかです:

Jn

ユリウス日n (1 n 365)。うるう日は含まれません。つまり、すべての年で2月28日が59日目で、3月1日が60日目です。2月29日があってもそれを指定することはできません。

n

ゼロ・ベースのユリウス日(0 n 365)。うるう日が含まれるので、2月29日を指定することができます。

Mm.n.d

その年(1 n 5、1 m 12)のm月のn週のd番目の日(0 d 6)です。ただし、週5は、4週目または5週目に発生する「m月の最後のd日」を意味します。週1は、d番目の日が発生する最初の週です。日0 (ゼロ)は、日曜日です。

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

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

関連項目:

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

2.34 nl_langinfo(3c)

名前

nl_langinfo() - 言語情報。

形式

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

char *nl_langinfo (nl_item item);

説明

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

例:

nl_langinfo (ABDAY_1);

指定された言語がフランス語で、フランス語のロケールが正しくインストールされている場合は、文字列Dimを指すポインタを戻します。指定された言語が英語の場合は、Sunを戻します。

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

診断

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

注意事項

戻り値が指す配列は、プログラムによって変更されないようにする必要があります。nl_langinfo()の次の呼出しで、この配列が上書きされることがあります。

関連項目:

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

2.35 rpc_sm_allocate、rpc_ss_allocate(3c)

名前

rpc_sm_allocate()、rpc_ss_allocate() - RPCスタブ・メモリー管理方式でメモリーを割り当てます。

形式

#include <rpc/rpc.h>
idl_void_p_t rpc_sm_allocate(unsigned32 size, unsigned32 *status)
idl_void_p_t rpc_ss_allocate(unsigned32 size)

説明

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

具体的には、サーバー・スタブのパラメータに、参照によってパラメータを渡すために使用される以外のポインタが含まれている場合、または[enable_allocate]属性がACSファイル内の操作に指定されている場合は、環境は自動的に設定されます。それ以外の場合は、環境はrpc_sm_enable_allocate()の呼出しによってアプリケーションにより設定される必要があります。

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

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

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

rpc_s_ok

常に戻されます。戻り値を使用して、障害が特定されます。

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

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

戻り値

正常終了すると、このルーチンは割り当てられたメモリーを指すポインタを返します。

ノート:

idl_void_p_tは、ISO標準C環境ではvoid *に、他の環境ではchar *に定義されています。

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

関連項目:

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

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

2.36 rpc_sm_client_free、rpc_ss_client_free(3c)

名前

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_s_ok

成功。

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 ATMIアプリケーションのプログラミング』

2.37 rpc_sm_disable_allocate、rpc_ss_disable_allocate(3c)

名前

rpc_sm_disable_allocate()、rpc_ss_disable_allocate() - スタブのメモリー管理スキーム内のリソースおよび割り当てられたメモリーをリリースします。

形式

#include <rpc/rpc.h>
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_s_ok

成功。

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 ATMIアプリケーションのプログラミング』

2.38 rpc_sm_enable_allocate、rpc_ss_enable_allocate(3c)

名前

rpc_sm_enable_allocate()、rpc_ss_enable_allocate() - スタブのメモリー管理環境を有効にします。

形式

#include <rpc/rpc.h>
void rpc_sm_enable_allocate(unsigned32 *status)
void rpc_ss_enable_allocate(void)

説明

アプリケーションからrpc_sm_enable_allocate()を呼び出して、スタブ自身によってメモリー管理環境が設定されていない場合に、スタブ・メモリー環境を設定できます。すべてのrpc_sm_allocate()の呼出しの前に、スタブ・メモリー環境を設定しなければなりません。サーバーのスタブから呼び出されるサービス・コードについては、通常、スタブ・メモリー環境はスタブ自身によって設定されます。他のコンテキストから呼び出すコードは、呼び出す前にrpc_sm_enable_allocate()を呼び出す必要があります(たとえば、サービス・コードをスタブからでなく直接呼び出す場合)。

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

rpc_s_ok

成功。

rpc_s_no_memory

必要なデータ構造体をセットアップするために十分なメモリーを割り当ることができません。

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

rpc_x_no_memory

必要なデータ構造体をセットアップするために十分なメモリーを割り当ることができません。

マルチスレッドのアプリケーション中のスレッドは、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 ATMIアプリケーションのプログラミング』

2.39 rpc_sm_free、rpc_ss_free(3c)

名前

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_s_ok

成功。

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

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

戻り値

なし。

関連項目:

rpc_sm_allocate、rpc_ss_allocate(3c)

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

2.40 rpc_sm_set_client_alloc_free、rpc_ss_set_client_alloc_free(3c)

名前

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_s_ok

成功。

rpc_s_no_memory

必要なデータ構造体をセットアップするために十分なメモリーを割り当ることができません。

rpc_ss_set_client_alloc_freeは、この関数の例外復帰バージョンであり、出力パラメータstatusを持ちません。このルーチンでは、次の例外が発生します。

rpc_x_no_memory

必要なデータ構造体をセットアップするために十分なメモリーを割り当ることができません。

マルチスレッドのアプリケーション中のスレッドは、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 ATMIアプリケーションのプログラミング』

2.41 rpc_sm_swap_client_alloc_free、rpc_ss_swap_client_alloc_free(3c)

名前

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アプリケーションのプログラミング』

2.42 setlocale(3c)

名前

setlocale() - プログラムのロケールの修正および問合せを行います。

形式

#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の値"C"はデフォルトの環境を指定します。

また、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

ノート:

複合ロケールはサポートされていません。複合ロケールは、“/"で始まり、各カテゴリのロケールを “/"で区切ってリストした文字列です。

関連項目:

mklanginfo(1)

UNIXシステムのリファレンス・マニュアルのctime(3c)、ctype(3c)、getdate(3c)、localeconv(3c)、strftime(3c)、strtod(3c)、printf(3S)、environ(5)

2.43 setURLEntityCacheDir(3c)

名前

setURLEntityCacheDir() - DTD、スキーマおよびエンティティ・ファイルがキャッシュされるディレクトリを設定するXercesクラス・メソッドを指定します。

形式

void setURLEntityCacheDir (const char* cachedir)

説明

setURLEntityCacheDir()は、キャッシュをオンにしてDTDが必要な場合に呼び出されるメソッドです。

このメソッドを呼び出さず、setURLEntityCaching()メソッドを呼び出すか、または環境変数を設定しないことによってキャッシュを有効にした場合、ファイルはカレント・ディレクトリにキャッシュされます。このメソッドは、以下の2つのXercesオブジェクトと組み合せて排他的に使用されます。

• XercesDOMParser
• SAXparser

2.44 setURLEntityCaching(3c)

名前

setURLEntityCaching() - XMLパーサー用にDTD、スキーマまたはエンティティ・ファイルのキャッシュを設定または設定解除するXercesクラス・メソッドを指定します。

形式

void setURLEntityCaching (bool UseCache)

説明

setURLEntityCaching()は、デフォルトでDTD、スキーマ、およびエンティティ・ファイルをキャッシュするメソッドです。このメソッドを使用して、ファイルのキャッシングをオンまたはオフにすることができます。UseCacheは、キャッシングをオフにする場合はfalseに設定され、キャッシングをオンにする場合はtrueに設定されます。このメソッドは、以下の2つのXercesオブジェクトと組み合せて排他的に使用されます。

• XercesDOMParser
• SAXparser

2.45 strerror(3c)

名前

strerror() - エラー・メッセージ文字列を取得します。

形式

#include <string.h> 
char *strerror (int errnum);

説明

strerrorはerrnumに指定されたエラー番号をエラー・メッセージ文字列にマッピングし、その文字列を指すポインタを返します。strerrorは、perrorと同じエラー・メッセージ・セットを使用します。返される文字列は上書きされないようにしてください。

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

関連項目:

UNIXシステムのリファレンス・マニュアルのperror(3)

2.46 strftime(3c)

名前

strftime() - 日付および時間を文字列に変換します。

形式

#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が指す構造体に格納されている値によって判別されます。

文字	説明
%%	%と同じ
%a	該当ロケールにおける曜日の略称
%A	該当ロケールにおける曜日の正式名
%b	該当ロケールの月の略称
%B	該当ロケールの月の正式名
%c	該当ロケールの日付/時刻表現
%C	date(1)によって出力される該当ロケールの日付/時刻表現
%d	月の日(01-31)
%D	%m/%d/%y書式の日付
%e	月の日(1-31; 1桁の数字には先頭に空白が付く)
%h	該当ロケールの月の略称
%H	時(00-23)
%I	時(01-12)
%j	年の通算日(001-366)
%m	月の番号(01-12)
%M	分(00-59)
%n	\と同じ
%p	ロケールのAMまたはPMのいずれかに相当
%r	%I:%M:%S 「AM」>「PM」形式の時刻表現
%R	%H:%Mと同じ
%S	秒(00-61)、うるう秒も可
%t	タブの挿入
%T	%H:%M:%S形式の時刻表現
%U	年間の週番号(00-53)、第1週の第1日目を日曜日とする
%w	曜日番号(0-6)、日曜日 = 0
%W	年間の週番号(00-53)、第1週の第1日目を月曜日とする
%x	該当ロケールの日付表現
%X	該当ロケールの時刻表現
%y	1世紀の年数(00-99)
%Y	ccyy形式の年表現(たとえば、1986)
%Z	タイム・ゾーン、またはタイム・ゾーンが存在しない場合は文字なし

%Uと%Wの相違点は、日にちを週の初日から数えるかどうかという点です。週番号01は、%Uの場合、日曜日から始まる1月の第1週、%Wの場合は月曜日から始まる1月の第1週を表します。また、週番号00には、%Uおよび%Wでそれぞれ最初の日曜日または月曜日の前の日にちを表します。

終端NULL文字を含む結果として得られた文字の合計数がmaxsizeを超えない場合、strftime()はsが指す配列に置かれた文字数(終端NULL文字を含まない)を返します。それ以外の場合は、ゼロが返され、配列の内容は不確定になります。

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

出力言語の選択

デフォルトの設定では、strftime()の出力はU.S. Englishで行われます。strftime()の出力は、setlocale()にカテゴリLC_TIMEのlocaleを設定することによって特定の言語に変更することができます。

タイム・ゾーン

タイム・ゾーンは環境変数TZから取得されます。TZの詳細は、「ctime(3c)」を参照してください。

例

strftime()の使用例を示します。この例は、tmptrが指す構造体に、ニュージャージー州における1986年8月28日木曜日の12時44分36秒に対応する値が入っている場合に、strの文字列がどのようになるかを示しています。

strftime (str, strsize, "%A %b %d %j", tmptr)

この結果、strには"Thursday Aug 28 240"の文字列が入ります。

ファイル

$TUXDIR/locale/ locale /LANGINFO - コンパイルされたロケール固有の日付/時刻情報を収めているファイル

関連項目:

mklanginfo(1)、setlocale(3c)

2.47 tpacall(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が認識するタイプおよびサブタイプのいずれかと一致しなければなりません。トランザクション・モードにあるときに送信されるリクエストごとに、最終的には対応する応答が受信されなければならないことに注意してください。

次に、有効なflagsの一覧を示します。

TPNOTRAN

呼出しプロセスがトランザクション・モードにあり、このフラグが設定されていると、svcが呼び出されたときに、このプロセスは呼出し側のトランザクションの一部として実行されません。svcがトランザクションをサポートしないサーバーに属している場合、呼出し側がトランザクション・モードのときに、このフラグを設定しなければなりません。svcが依然としてトランザクション・モードで起動される場合がありますが、それは同じトランザクションでないことに注意してください。svcは、構成属性で、自動的にトランザクション・モードで呼び出されるようにすることができます。このフラグを設定するトランザクション・モードの呼出し側は、トランザクション・タイムアウトの影響を受けます。サービスが異常終了した場合でも、起動時にこのフラグが設定されていれば、呼出し側のトランザクションに影響は及びません。

TPNOREPLY

応答を期待していないことをtpacall()に通知します。 TPNOREPLYが設定されると、正常終了時に関数は0を返します(0は無効な記述子)。呼出しプロセスがトランザクション・モードにあるとき、TPNOTRANが設定されないかぎりこの設定は使用できません。

TPNOBLOCK

このリクエストは、ブロッキング条件が存在する場合(たとえば、メッセージの送信先である内部バッファがいっぱいの場合など)には、送信されません。TPNOBLOCKが指定されていないときにブロッキング条件が存在すると、呼出し側は、その条件が解消されるか、またはタイムアウト(トランザクションまたはブロッキング)が発生するまではブロックされます。

TPNOTIME

このフラグは、呼出し側が無制限にブロックでき、ブロッキング・タイムアウトの対象にならないようにすることを指定します。ただし、トランザクション・タイムアウトは発生する可能性があります。

TPSIGRSTRT

ルーチン内部のシステム・コールがシグナルによって中断された場合、中断されたシステム・コールは再発行されます。

マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドは、tpacall()の呼出しを発行できません。

戻り値

正常終了の場合、tpacall()は、送信したリクエストの応答を受信するために使用できる記述子を返します。

異常終了すると、tpacall()は -1を返し、tperrnoを設定してエラー条件を示します。

エラー

異常終了時には、tpacall()はtperrnoを次のいずれかの値に設定します。(特に記述した場合を除いては、エラーが呼出し側のトランザクションに影響を及ぼすことはありません。)

[TPEINVAL]

無効な引数が指定されました(たとえば、svcがNULLである場合、dataがtpalloc()によって割り当てられた空間を指していない場合、flagsが無効である場合など)。

[TPENOENT]

svcが存在しないか、会話型サービスであるため、svcに送信できません。

[TPEITYPE]

dataのタイプおよびサブタイプは、svcが受け付けるタイプあるいはサブタイプの1つではありません。

[TPELIMIT]

未終了の非同期リクエストの数が、保持できる最大数に達したため、呼出し側のリクエストが送信できませんでした。

ノート:

以前のリリースでは50だった最大数が、Oracle Tuxedo 12cリリース2 (12.1.3)から2048になりました。

[TPETRAN]

svcが、トランザクションをサポートしていないサーバーに属しており、TPNOTRANが設定されていませんでした。

[TPETIME]

このエラー・コードは、タイムアウトが発生したか、または現在のトランザクションがすでに「ロールバックのみ」とマークされているにもかかわらずtpacall()が試行されたことを示します。

呼出し側がトランザクション・モードの場合、トランザクションはすでにロールバックのみであるか、またはトランザクション・タイムアウトが発生しました。このトランザクションは、「中断のみ」とマークされます。呼出し側がトランザクション・モードでない場合、ブロッキング・タイムアウトが発生しています。(ブロッキング・タイムアウトは、TPNOBLOCKまたはTPNOTIMEが指定されている場合は発生しません。)

トランザクション・タイムアウトが発生した場合、トランザクションが中断されないかぎり、新しいリクエストの送信や未処理の応答の受信はできず、TPETIMEが発生します。その例外とは、ブロックされず、応答を期待せず、かつ呼出し側のトランザクションのかわりに送信されない(つまり、TPNOTRAN、TPNOBLOCKおよびTPNOREPLYを設定してtpacall()を呼び出した場合の)リクエストです。

サービスがトランザクションの内部で失敗した場合、そのトランザクションはTX_ROLLBACK_ONLY状態に置かれます。ほとんどの場合、この状態はタイムアウトと同じものとして扱われます。このトランザクションの以降のATMI呼出しは、すべてTPETIMEで異常終了します(前の段落で説明した例外を除く)。

[TPEBLOCK]

ブロッキング状態のため、TPNOBLOCKが指定されました。

[TPGOTSIG]

シグナルを受け取りましたが、TPSIGRSTRTが指定されていません。

[TPEPROTO]

tpacall()が不正に呼び出されました。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。リモート・ロケーションにあるメッセージ・キューがいっぱいになった場合には、tpacall()が正常に復帰してもTPEOSが返されます。

関連項目:

tpalloc(3c)、tpcall(3c)、tpcancel(3c)、tpgetrply(3c)、tpgprio(3c)、tpsprio(3c)

2.48 tpabort(3c)

名前

tpabort() - 現在のトランザクションを中断するルーチン。

形式

#include <atmi.h> 
int tpabort(long flags)

説明

tpabort()は、トランザクションの中断を指定します。この関数が終了すると、そのトランザクションでなされたリソースへの変更内容はすべて取り消されます。tpcommit()と同様、この関数は、トランザクションのイニシエータからしか呼び出せません。参加リソース(つまり、サービス・ルーチン)は、トランザクションを中断させたい場合には、TPFAILを付けてtpreturn()を呼び出します。

未終了の応答に対する呼出し記述子が存在するときにtpabort()を呼び出すと、この関数の終了時に、トランザクションは中断し、呼出し側のトランザクションに関連するこれらの記述子は以後無効になります。呼出し側のトランザクションに関連付けられていない呼出し記述子の状態は、有効のままです。

トランザクション・モードの会話型サーバーに対してオープン接続がある場合、tpabort()はTPEV_DISCONIMMイベントをサーバーに送ります(そのサーバーが接続の制御権を有するかどうかに関係なく)。tpbegin()の前に、あるいはTPNOTRANフラグを付けて(つまり、トランザクション・モードでない状態で)オープンされた接続は、影響を受けません。

現時点では、tpabort()関数の唯一の引数flagsは将来の用途のために予約されており、0に設定する必要があります。

マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドはtpabort()の呼出しを発行できません。

戻り値

異常終了時には、tpabort()は-1を返し、tperrnoを設定してエラー条件を示します。

エラー

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

[TPEINVAL]

flagsが0ではありません。呼出し側のトランザクションは影響を受けません。

[TPEHEURISTIC]

ヒューリスティックな判断のため、トランザクションの一部としてなされた作業が一部はコミットされ、一部は中途終了しています。

[TPEHAZARD]

ある種の障害のため、トランザクションの一部としてなされた作業がヒューリスティックに完了している可能性があります。

[TPEPROTO]

tpabort()が(参加リソースに呼び出されるなど)不正に呼び出されました。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。

注意事項

Oracle Tuxedo ATMIシステムのトランザクションを記述するためにtpbegin()、tpcommit()、およびtpabort()を使用する場合、XAインタフェースに準拠した(呼出し側に妥当にリンクされている)リソース・マネージャが行う作業のみがトランザクションのプロパティを備えていることを記憶しておくことが重要です。トランザクションにおいて実行される他のすべての操作は、tpcommit()あるいはtpabort()のいずれにも影響されません。

関連項目:

tpbegin(3c)、tpcommit(3c)、tpgetlev(3c)

2.49 tpadmcall(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つのモードで呼び出すことができます。

モード1:ブートされていない、構成されていないアプリケーション

呼出し側は、アプリケーションの管理者であると考えられます。許される操作は、NEW T_DOMAINクラス・オブジェクトに対してSETを実行してアプリケーションの初期構成を定義すること、そしてAPPQ_MIB()で定義されているクラスのオブジェクトに対してGETおよびSETを実行することだけです。

モード2:ブートされていない、構成されたアプリケーション

呼出し側は、割り当てられた管理者であるか、ローカル・システムの管理者用の構成で定義された権限と自分のuid/gidを比較した結果に基づく他の権限を持っています。呼出し側は、TM_MIB()およびAPPQ_MIB()のあらゆるクラスのあらゆる属性に対して、これらに対して適切なパーミッションを持つ場合に、GETおよびSETを実行できます。クラスによっては、起動されていないアプリケーションからアクセスできない属性だけを持ち、これらのクラスへのアクセスが失敗する場合があることに注意してください。

モード3:ブートされたアプリケーション、アタッチされていないプロセス

呼出し側は、割り当てられた管理者であるか、ローカル・システムの管理者用の構成で定義された権限と自分のuid/gidを比較した結果に基づく他の権限を持っています。呼出し側は、TM_MIB()のあらゆるクラスのあらゆる属性に対して、これらに対して適切なパーミッションを持つ場合に、GETを実行できます。同様に呼出し側は、クラス固有の制限にもよりますが、APPQ_MIB()のあらゆるクラスのあらゆる属性に対してGETおよびSETを実行できます。ACTIVEであるときにのみアクセスできる属性は返されません。

モード4:ブートされたアプリケーション、アタッチされているプロセス

tpinit()の実行時に割り当てられた認証キーに従ってパーミッションが決められます。呼出し側は、TM_MIB()のあらゆるクラスのあらゆる属性に対して、これらに対して適切なパーミッションを持つ場合に、GETを実行できます。さらに呼出し側は、クラス固有の制限にもよりますが、APPQ_MIB()のあらゆるクラスのあらゆる属性に対してGETおよびSETを実行できます。

これらのインタフェース・ルーチンを使用したバイナリのOracle Tuxedo ATMIシステム・アプリケーション構成ファイルに対するアクセスおよび更新は、ディレクトリ名やファイル名に関するUNIXシステムのパーミッションによって制御されます。

マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドはtpadmcall()の呼出しを発行できません。

環境変数

このルーチンを呼び出す前に、次の環境変数を設定する必要があります。

TUXCONFIG

このアプリケーションに対するOracle Tuxedoシステムの構成ファイルを保存するファイルまたはデバイスの名前を指定します。

注意事項

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]

無効な引数が指定されました。flagsの値が無効であるか、inbufまたはoutbufは"FML32"タイプの型付きバッファへのポインタではありません。

[TPEMIB]

管理リクエストが失敗しました。outbufが更新され、「MIB(5)」および「TM_MIB(5)」で説明するエラーの原因を示すFML32のフィールドが設定され、呼出し側に返されました。

[TPEPROTO]

tpadmcall()が不正に呼び出されました。

[TPERELEASE]

環境変数TUXCONFIGに別のリリース・バージョンの構成ファイルが設定されて、tpadmcall()が呼び出されました。

[TPEOS]

オペレーティング・システムのエラーが発生しました。失敗したシステム・コールを示す数値がUunixerrに入っています

[TPEOS]

オペレーティング・システムのエラーが発生しました。失敗したシステム・コールを示す数値がUunixerrに入っています

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。このエラーの正確な性質はuserlog()に書き込まれます

相互運用性

このインタフェースは、ローカルな構成ファイルおよび掲示板に対するアクセスおよび更新しかサポートしていません。したがって、相互運用性の問題はありません。

移植性

このインタフェースは、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アプリケーション実行時の管理』

2.50 tpadvertise(3c)

名前

tpadvertise() - サービス名を通知するルーチン。

形式

#include <atmi.h> 
int tpadvertise(char *svcname, void (*func)(TPSVCINFO*))

説明

tpadvertise()を使用するとサーバーは提供するサービスを通知することができます。デフォルトの設定では、サーバーのサービスは、サーバーのブート時に通知され、サーバーの停止時にその通知が解除されます。

複数サーバー単一キュー(MSSQ)セットに属するすべてのサーバーは、同じサービス・セットを提供しなければなりません。これらのルーチンは、MSSQセットを共有する全サーバーを通知することによってこの規則を適用します。

tpadvertise()は、サーバー(あるいは、呼出し側のMSSQセットを共有するサーバーのセット)のsvcnameを通知します。svcnameにNULLあるいはNULL文字列("")を指定することはできません。また、長さは127文字までとしてください。(UBBCONFIG(5)に関する項の*SERVICESセクションを参照) funcはOracle Tuxedo ATMIシステムのサービス関数のアドレスです。この関数は、svcnameに対するリクエストをサーバーが受け取ったときに起動されます。funcにNULLを指定することはできません。明示的に指定された関数名( servopts(5)を参照)は、128文字までの長さを指定できます。127文字を超える名前は、受け取られてから127文字に切り詰められます。ユーザーは、切り詰められた名前が他のサービス名と同じにならないように注意する必要があります。

svcnameがすでにサーバーに対して通知されていて、funcがその現在の関数と一致する(すでに通知されている名前に一致する短縮された名前も含まれます)場合、tpadvertise()は正常に終了します。ただし、svcnameがすでにサーバーに対して通知されていても、funcが現在の関数と一致しない場合には(短縮された名前がすでに通知されている名前と同じ場合にも)、エラーが返されます。

'.'で始まるサービス名は、管理用サービスのために予約されています。アプリケーションがこれらのサービスの1つを通知しようとするとエラーが返されます。

戻り値

異常終了時には、tpadvertise()は-1を返し、tperrnoを設定してエラー条件を示します。

エラー

失敗すると、tpadvertise()はtperrnoを次のいずれかの値に設定します。

[TPEINVAL]

svcnameがNULLまたはNULL文字列("")であるか、ピリオド(".")で開始するか、またはfuncがNULLである場合。

[TPELIMIT]

領域に制限があるため、svcnameを通知できない場合。(UBBCONFIG(5)に関する項のRESOURCESセクションのMAXSERVICESを参照)

[TPEMATCH]

svcnameは、すでにこのサーバーについて通知されていますが、それは、func以外の関数で行われました。この関数は異常終了しても、svcnameはその現在の関数で通知されたまま変わりません(すなわち、funcは現在の関数と振り変わりません)。

[TPEPROTO]

tpadvertise()が不正なコンテキストで呼び出されました(たとえば、クライアントによって)。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。

関連項目:

tpservice(3c)、tpadvertisex(3c)、tpunadvertise(3c)

2.51 tpadvertisex(3c)

名前

tpadvertisex() - ドメイン内で一意のサービス名を持つサービスを通知するか、Tuxedoサーバーのセカンダリ・キューにサービスを通知するルーチン。

形式

#include <atmi.h> 
int tpadvertisex(char *svcname, void (*func)(TPSVCINFO *), long flags)

説明

tpadvertisex()により、サーバーは次のことが可能になります:

• サービスが現在のドメイン内の他のサーバーによって通知されていない場合にのみ通知します。
• Tuxedoサーバーのセカンダリ・キューにサービスを通知します。

戻り値

異常終了時には、tpadvertisex()は-1を返し、tperrnoを設定してエラー条件を示します。

エラー

失敗すると、tpadvertisex()はtperrnoを次のいずれかの値に設定します。

[TPENOSINGLETON]

svcnameが現在のドメイン内の他のサーバー・インスタンスに対してすでに通知されています。

[TPENOSECONDARYRQ]

svcnameがサーバーのセカンダリ・リクエスト・キューに通知されましたが、SECONDARYRQが設定されていないため、セカンダリ・リクエスト・キューは存在しません。

関連項目:

tpservice(3c)、 tpadvertise(3c)、tpunadvertise(3c)

2.52 tpalloc(3c)

名前

tpalloc() - 型付きバッファの割当てを行うルーチン。

形式

#include <atmi.h> 
char * tpalloc(char *type, char *subtype, long size)

説明

tpalloc()は、typeタイプのバッファを指すポインタを返します。バッファのタイプによっては、subtypeとsizeは両方とも省略することができます。Oracle Tuxedo ATMIシステムには、様々なタイプのバッファが提供されており、しかもアプリケーションは自由に独自のバッファ・タイプを追加することができます。詳細は、『Oracle Tuxedoファイル形式、データ記述、MIBおよびシステム・プロセス・リファレンス』のtuxtypes(5)に関する項を参照してください。

ある特定のバッファ・タイプのtmtype_swでsubtypeがNULLでない場合、tpalloc()を呼び出す際にsubtypeを指定しなければなりません。割り当てられるバッファは少なくともsizeおよびdfltsizeと同じ大きさになります。ここで、dfltsizeは特定のバッファ・タイプのtmtype_swに指定されたデフォルトのバッファ・サイズです。バッファ・タイプがSTRINGの場合、最小は512バイトです。バッファ・タイプがFMLあるいはVIEWの場合、最小は、1024バイトです。

ノート:

タイプの最初の8バイトとサブタイプの最初の16バイトのみが有効です。

あるバッファ・タイプは使用する前に初期化が必要です。tpalloc()は、バッファが割り当てられて返される前に(Oracle Tuxedo ATMIシステム固有の方法で)バッファを初期化します。このため、呼出し側から返されるバッファはすぐに使用できます。ただし、初期化ルーチンがバッファをクリアしないかぎり、そのバッファはtpalloc()によってゼロに初期化されません。

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

戻り値

正常終了の場合、tpalloc()はlongワードの適切なタイプのバッファを指すポインタを返します。それ以外の場合はNULLを返し、tperrnoを設定して条件を示します。

エラー

失敗すると、tpalloc()はtperrnoを次のいずれかの値に設定します。

[TPEINVAL]

無効な引数が指定されました(たとえば、typeがNULLである場合など)。

[TPENOENT]

tmtype_swのどのエントリもtypeと一致しない場合。また、NULLでなければsubtypeとも一致しない場合。

[TPEPROTO]

tpalloc()が不正に呼び出されました。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。

使用方法

バッファの初期化に失敗すると、割り当てられたバッファが解放され、tpalloc()がNULLを戻して失敗します。

この関数を、Cライブラリのmalloc()、realloc()、またはfree()と組み合せて使用するのは避けてください(tpalloc()で割り当てたバッファを、free()を使用して解放しないでください)。

Oracle Tuxedo ATMIシステムの拡張に準拠した実装は、すべて2つのバッファ・タイプをサポートしています。詳細は、「C言語アプリケーション・トランザクション・モニター・インタフェースの紹介」を参照してください。

関連項目:

tpfree(3c)、tprealloc(3c)、tptypes(3c)

2.53 tpappthrinit(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が使用されます。SECURITYがUSER_AUTH以上に設定されている場合、tpappthrinit()に渡されるTPINITバッファは、そのアプリケーションに対して構成された認証サービスに渡されます。TPINITバッファの特定のフィールドが認証サービスによって使用されるかどうかは、実装によって異なります。NONEおよびAPP_PWの各セキュリティ・レベルでは、tpthrinfoのメンバーであるcltname、grpnameおよびpasswdは現在使用されていないため、長さが0の文字列に設定する必要があります。TPINITのメンバーであるflagsも、tpappthrinit()では使用されません。

tpappthrinit()は、アプリケーション生成のサーバー・スレッドでのみ呼び出すことができます。サーバーをビルドする場合、buildserverで-tオプションを指定する必要があります。

ノート:

tpappthrinit()はサービス・ルーチンでは使用できません。

戻り値

Tuxedoコンテキストが正常に生成および初期化されると、tpappthrinit()が0を返します。

エラーが発生すると、この関数は、呼出し側スレッドがTPNULLCONTEXTの状態のままで-1を返し、tperrnoを設定してエラー条件を示します。

エラー

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

[TPEINVAL]

無効な引数が指定されました。たとえば、tpthrinfoはNULLではありませんが、TPINIT型付きバッファを指していません。

[TPEPROTO]

tpappthrinit()が不正に呼び出されました。たとえば、クライアント・プログラムまたはサーバー・ルーチンで呼び出されているか、buildserver -tオプションでサーバーがビルドされていません。

[TPENOENT]

十分な空き領域がないため、コンテキストを生成できません。

[TPEPERM]

認証エラーのため、コンテキストを生成できません。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。

関連項目:

tpappthrterm(3c)、tpinit(3c)、tpterm(3c)、tpgetctxt(3c)、tpsetctxt(3c)

マルチスレッドおよびマルチコンテキストATMIアプリケーションのプログラミング

2.54 tpappthrterm(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]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。

関連項目:

tpappthrinit(3c)、tpinit(3c)、tpgetctxt(3c)、tpsetctxt(3c)、tpterm(3c)

マルチスレッドおよびマルチコンテキストATMIアプリケーションのプログラミング

2.55 tpatz(3c)

名前

tpatz() - リソース・アクセス制御。

形式

#include <atmi.h>
int tpatz(char *restype, char *resname, char *action, long flag)

説明

tpatz()は、ユーザーに指定したリソースへのアクセスが許可されているかどうかをチェックします。この関数は、複数のスレッドを使用してサーバー側でのみ呼び出すことができます。このAPIは、認証のための認可サービスに要求を転送します。tpatz()は、XAUTHSVRやEAUTHSVTなどのサーバーとともに使用して認証を行うことができます。

restypeは、ユーザーまたはTuxedoシステムによって定義されるリソース・タイプです。resnameはリソース名を示す文字列のポインタです。actionはリソース操作です。flagは予約されています。

有効な文字列長は次のとおりです。

• restype: [1,15]
• resname: [1,127]
• action : [1,15]

戻り値

• 認証に成功すると、tpatz()は1を返します。
• 認証に失敗すると、tpatz()は0を返します。
• システムが異常終了すると、tpatz()は-1を返し、tperrnoを設定してエラー条件を示します。

エラー

[TPEINVAL]

無効な引数が指定されました(たとえば、文字列長が有効な長さを超えている場合など)。

注意事項

このAPIは、効率性向上のために各アプリケーション・サーバー内にキャッシュを構築します。次の環境変数は、ユーザー要件に適合するようにこのキャッシュを制御します。

• TMATZPRIVILEGEMAX
• TMATZRESOURCEMAX
• TMATZEXP

詳細は、「認証キャッシュの設定」を参照してください。

2.56 tpbegin(3c)

名前

tpbegin() - トランザクションを開始するルーチン。

形式

#include <atmi.h>
int tpbegin(unsigned long timeout, long flags)

説明

Oracle Tuxedo ATMIシステムにおけるトランザクションは、完全に成功する、あるいは何も影響を残さない1つの論理的な作業単位を定義するために使用されます。トランザクションにより、多くのプロセスで(そして、おそらく様々なサイトで)行われる作業を1つの分割できない単位として扱うことができます。トランザクションのイニシエータはtpbegin()とともに、tpcommit()またはtpabort()を使用して、トランザクション内での処理を記述します。いったんtpbegin()が呼び出されると、他のプロセスとの通信は、後のプロセス(つまりサーバー)をトランザクション・モードにすることができます(つまり、サーバーの作業はトランザクションの一部となります)。トランザクションに参加したプログラムを参加リソースと呼びます。トランザクションには、必ず1つの実行元があり、いくつかの参加リソースを持つことができます。tpcommit()またはtpabort()を呼び出せるのは、トランザクションの実行元だけです。参加リソースは、tpreturn()を呼び出したときに使用する戻り値(rvals)によって、トランザクションの結果に影響を与えることができます。トランザクション・モードに入ると、サーバーに出されたサービス・リクエストはすべて、トランザクションの一部として処理されます(リクエスタから明示的に別の指定がない場合)。

ノート:

会話型サーバーに対して確立されたオープン接続があるときにプログラムがトランザクションを起動しても、これらの接続はトランザクション・モードには変わりません。これは、tpconnect()の呼出し時にTPNOTRANフラグを指定したことと同じです。

tpbegin()の最初の引数timeoutは、トランザクションのタイムアウトまでの時間を最低timeout秒にすることを指定します。トランザクションはタイムアウト時間を経過した後は、中断のみとしてマークされます。timeoutの値が0であると、トランザクションにはシステムが許すかぎりの最大時間(秒単位)のタイムアウト値が与えられます(つまり、このときのタイムアウト値は、システムが定義している符号なしlong型の最大値になります)。

現在、tpbegin()の2番目の引数flagsは将来の用途のために予約されており、0に設定する必要があります。

マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドは、tpbegin()の呼出しを発行できません。

戻り値

異常終了すると、tpbegin()は -1を返し、tperrnoを設定してエラー条件を示します。

エラー

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

[TPEINVAL]

flagsが0ではありません。

[TPETRAN]

呼出し側は、トランザクション起動時にエラーが発生したため、トランザクション・モードになれません。

[TPEPROTO]

tpbegin()が不正なコンテキストで呼び出されました(たとえば、呼出し側がすでにトランザクション・モードであるなど)。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。

注意事項

Oracle Tuxedo ATMIシステムのトランザクションを記述するためにtpbegin()、tpcommit()、およびtpabort()を使用する場合、XAインタフェースに準拠した(呼出し側に妥当にリンクされている)リソース・マネージャが行う作業のみがトランザクションのプロパティを備えていることを記憶しておくことが重要です。トランザクションにおいて実行される他のすべての操作は、tpcommit()あるいはtpabort()のいずれにも影響されません。詳しくは、buildserver()を参照してください。リソース・マネージャによって実行される操作が、Oracle Tuxedo ATMIシステムのトランザクションの一部となるように、XAインタフェースを満たすリソース・マネージャをサーバーにリンクします。

関連項目:

tpabort(3c)、tpcommit(3c)、tpgetlev(3c)、tpscmt(3c)

2.57 tpbroadcast(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の大きさを指定します。ただし、dataが長さの指定を必要としないタイプのバッファを指す場合(FMLフィールド化バッファなど)、lenは無視されます(0でもかまいません)。また、dataはNULLであってもかまいません。この場合、lenは無視されます。このバッファは、他の送受信されるメッセージと同様、型付きバッファ・スイッチ・ルーチンで処理されます。たとえば、エンコード/デコードは自動的に行われます。

次に、有効なflagsの一覧を示します:

TPNOBLOCK

このリクエストは、ブロッキング条件が存在する場合(たとえば、メッセージの送信先である内部バッファがいっぱいの場合など)には、送信されません。

TPNOTIME

このフラグは、呼出し側が無制限にブロックでき、ブロッキング・タイムアウトの対象にならないようにすることを指定します。ただし、トランザクション・タイムアウトは発生する可能性があります。

TPSIGRSTRT

ルーチン内部のシステム・コールがシグナルによって中断された場合、中断されたシステム・コールは再発行されます。tpbroadcast()が正常終了した場合には、メッセージはシステムに渡され、選択されたクライアントに転送されます。tpbroadcast()は、選択された各クライアントにメッセージが送られるのを待機しません。マルチスレッドのアプリケーションでは、TPINVALIDCONTEXT状態のスレッドはtpbroadcast()の呼出しを発行できません。

戻り値

異常終了すると、tpbroadcast()は -1を返し、tperrnoを設定してエラー条件を示します。

エラー

異常終了には、tpbroadcast()はアプリケーション・クライアントにブロードキャスト・メッセージを送信せず、tperrnoを次のいずれかの値に設定します。

[TPEINVAL]

無効な引数が与えられました(たとえば、識別子が長すぎる、あるいはフラグが無効など)。無効なLMIDを使用すると、tpbroadcast()は正常に働かず、TPEINVALが返されます。ただし、存在しないユーザーやクライアントの名前の場合は、どこにもブロードキャストされないだけでこのルーチンは正常に終了します。

[TPETIME]

ブロッキング・タイムアウトが発生しました。(ブロッキング・タイムアウトは、TPNOBLOCKまたはTPNOTIMEが指定されている場合は発生しません。)

[TPEBLOCK]

呼出し時にブロッキング条件が検出されましたが、TPNOBLOCKが指定されました。

[TPGOTSIG]

シグナルを受け取りましたが、TPSIGRSTRTが指定されていません。

[TPEPROTO]

tpbroadcast()が不正に呼び出されました。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

[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)

2.58 tpcacheget(3c)

名前

tpcacheget - キーに関連付けられているOracle Tuxedo型付きバッファをキャッシュから取得します

形式

#include "atmi.h"
int tpcacheget(TCACHE* tc, char* key, char** odata, long* olen, long flags);

説明

tpcacheget(3c)は、キーに関連付けられているOracle Tuxedo型付きバッファをキャッシュから取得します。tcはtpgetcache(3c)によって返されます。odataは、キーのデータが読み込まれるバッファへのポインタのアドレスです。tpalloc(3c)によって最初に割り当てられたバッファを指している必要があります。olenはデータの長さを指します。flagsは予約されており、0Lである必要があります。

戻り値

成功すると、tpcacheget(3c)は0を返します。

失敗すると、tpcacheget(3c)は-1を返し、tperrnoを設定してエラー条件を示します。呼出しが失敗してtperrnoに特定の値が設定された場合は、続けて、中間のATMI呼出しを省略してtperrordetail(3c)を呼び出すと、エラーに関する詳細な情報が提供されます。詳細は、「tperrordetail(3c)」リファレンス・ページを参照してください。

エラー

[TPEINVAL]

無効な引数が指定されました。

[TPENOENT]

リクエストされたキャッシュは存在しません。

[TPETIME]

このエラー・コードは、タイムアウトが発生したことを示します。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な内容はULOGに追加されます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。

[TPESVCFAIL]

Oracle Tuxedoキャッシュ・サーバーはエラーを満たします。tpurcodeには正確なエラー値が含まれます。tpurcodeの想定される値を次に示します。

• TDC_ERR_CACHE_NOTEXIST

  このエラー・コードは、リクエストされたOracle Tuxedoキャッシュが存在しないことを示します。

• TDC_ERR_CACHE_UNAVAIL

  このエラー・コードは、リクエストされたOracle Tuxedoキャッシュが使用不可であることを示します。

• TDC_ERR_KEY_NOTEXIST

  このエラー・コードは、指定されたキーに基づいてリクエストされたエントリが存在しないことを示します。

2.59 tpcachemremove(3c)

名前

tpcachemremove - パラメータkeyarrayに関連付けられているキャッシュ・エントリをキャッシュから削除します

形式

#include "atmi.h"
int tpcachemremove(TCACHE* tc, char* keyarray[], int size, long flags);

説明

tpcachemremove(3c)は、パラメータkeyarrayに関連付けられているキャッシュ・エントリをキャッシュから削除します。tcはtpgetcache(3c)によって返されます。keyarrayは、削除されるキーの配列です。sizeはkeyarrayのサイズです。flagsは予約されており、0Lである必要があります。

戻り値

成功すると、tpcachemremove(3c)は0を返します。

失敗すると、tpcachemremove(3c)は-1を返し、tperrnoを設定してエラー条件を示します。呼出しが失敗してtperrnoに特定の値が設定された場合は、続けて、中間のATMI呼出しを省略してtperrordetail(3c)を呼び出すと、エラーに関する詳細な情報が提供されます。詳細は、「tperrordetail(3c)」リファレンス・ページを参照してください。

エラー

[TPEINVAL]

無効な引数が指定されました。

[TPENOENT]

リクエストされたキャッシュは存在しません。

[TPETIME]

このエラー・コードは、タイムアウトが発生したことを示します。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な内容はULOGに追加されます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。

[TPESVCFAIL]

Oracle Tuxedoキャッシュ・サーバーはエラーを満たします。tpurcodeには正確なエラー値が含まれます。tpurcodeの想定される値を次に示します。

• TDC_ERR_CACHE_NOTEXIST

  このエラー・コードは、リクエストされたOracle Tuxedoキャッシュが存在しないことを示します。

• TDC_ERR_CACHE_UNAVAIL

  このエラー・コードは、リクエストされたOracle Tuxedoキャッシュが使用不可であることを示します。

2.60 tpcacheput(3c)

名前

tpcacheput - Oracle Tuxedo型付きバッファをキーに関連付けてキャッシュに格納します

形式

#include "atmi.h"
int tpcacheput(TCACHE* tc, char* key, char* data, long len, long flags);

説明

tpcacheput(3c)は、Oracle Tuxedo型付きバッファをキーに関連付けてキャッシュに格納します。tcはtpgetcache(3c)によって返されます。dataは、tpalloc(3c)によって割り当てられたTuxedo型付きバッファを指します。lenはデータの長さです。データの型が長さの指定を必要としない場合(FMLフィールド化バッファなど)、lenは無視されます(0でもかまいません)。flagsは予約されており、0Lである必要があります。

戻り値

成功すると、tpcacheput(3c)は0を返します。

失敗すると、tpcacheput(3c)は-1を返し、tperrnoを設定してエラー条件を示します。呼出しが失敗してtperrnoに特定の値が設定された場合は、続けて、中間のATMI呼出しを省略してtperrordetail(3c)を呼び出すと、エラーに関する詳細な情報が提供されます。詳細は、「tperrordetail(3c)」リファレンス・ページを参照してください。

エラー

[TPEINVAL]

無効な引数が指定されました。

[TPENOENT]

リクエストされたキャッシュは存在しません。

[TPETIME]

このエラー・コードは、タイムアウトが発生したことを示します。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な内容はULOGに追加されます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。

[TPESVCFAIL]

Oracle Tuxedoキャッシュ・サーバーはエラーを満たします。tpurcodeには正確なエラー値が含まれます。tpurcodeの想定される値を次に示します。

• TDC_ERR_CACHE_NOTEXIST

  このエラー・コードは、リクエストされたOracle Tuxedoキャッシュが存在しないことを示します。

• TDC_ERR_CACHE_UNAVAIL

  このエラー・コードは、リクエストされたOracle Tuxedoキャッシュが使用不可であることを示します。

2.61 tpcacheremove(3c)

名前

tpcacheremove - パラメータkeyに関連付けられているキャッシュ・エントリをキャッシュから削除します

形式

#include "atmi.h"
int tpcacheremove(TCACHE* tc, char* key, long flags);

説明

tpcacheremove(3c)は、パラメータkeyに関連付けられているキャッシュ・エントリを削除します。tcはtpgetcache(3c)によって返されます。flagsは予約されており、0Lである必要があります。

戻り値

成功すると、tpcacheremove(3c)は0を返します。

失敗すると、tpcacheremove(3c)は-1を返し、tperrnoを設定してエラー条件を示します。呼出しが失敗してtperrnoに特定の値が設定された場合は、続けて、中間のATMI呼出しを省略してtperrordetail(3c)を呼び出すと、エラーに関する詳細な情報が提供されます。詳細は、「tperrordetail(3c)」リファレンス・ページを参照してください。

エラー

[TPEINVAL]

無効な引数が指定されました。

[TPENOENT]

リクエストされたキャッシュは存在しません。

[TPETIME]

このエラー・コードは、タイムアウトが発生したことを示します。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な内容はULOGに追加されます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。

[TPESVCFAIL]

Oracle Tuxedoキャッシュ・サーバーはエラーを満たします。tpurcodeには正確なエラー値が含まれます。tpurcodeの想定される値を次に示します。

• TDC_ERR_CACHE_NOTEXIST

  このエラー・コードは、リクエストされたOracle Tuxedoキャッシュが存在しないことを示します。

• TDC_ERR_CACHE_UNAVAIL

  このエラー・コードは、リクエストされたOracle Tuxedoキャッシュが存在しないことを示します。

2.62 tpcacheremoveall(3c)

名前

tpcacheremoveall - キャッシュからすべてのキャッシュ・エントリを削除します

形式

#include "atmi.h"
int tpcacheremoveall(TCACHE* tc, long flags);  

説明

tpcacheremoveall(3c)は、キャッシュからすべてのエントリを削除します。tcはtpgetcache(3c)によって返されます。flagsは予約されており、0Lである必要があります。

戻り値

成功すると、tpcacheremoveall(3c)は0を返します。

失敗すると、tpcacheremoveall(3c)は-1を返し、tperrnoを設定してエラー条件を示します。呼出しが失敗してtperrnoに特定の値が設定された場合は、続けて、中間のATMI呼出しを省略してtperrordetail(3c)を呼び出すと、エラーに関する詳細な情報が提供されます。詳細は、「tperrordetail(3c)」リファレンス・ページを参照してください。

エラー

[TPEINVAL]

無効な引数が指定されました。

[TPENOENT]

リクエストされたキャッシュは存在しません。

[TPETIME]

このエラー・コードは、タイムアウトが発生したことを示します。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な内容はULOGに追加されます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。

[TPESVCFAIL]

Oracle Tuxedoキャッシュ・サーバーはエラーを満たします。tpurcodeには正確なエラー値が含まれます。tpurcodeの想定される値を次に示します。

• TDC_ERR_CACHE_NOTEXIST

  このエラー・コードは、リクエストされたOracle Tuxedoキャッシュが存在しないことを示します。

• TDC_ERR_CACHE_UNAVAIL

  このエラー・コードは、リクエストされたOracle Tuxedoキャッシュが使用不可であることを示します。

2.63 tpcall(3c)

名前

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が認識するタイプおよびサブタイプのいずれかと一致しなければなりません。

ノート:

アプリケーションでtpcall()の送信バッファとしてXMLバッファを使用する必要がある場合、sendlenパラメータでその正確な長さ(XMLバッファの文字列長+1)を指定してください。

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であると、エラーになります。

次に、有効なflagsの一覧を示します。

TPNOTRAN

呼出しプロセスがトランザクション・モードにあり、このフラグが設定されていると、svcが呼び出されたときに、このプロセスは呼出し側のトランザクションの一部として実行されません。svcが依然としてトランザクション・モードで起動される場合がありますが、それは同じトランザクションでないことに注意してください。svcは、構成属性で、自動的にトランザクション・モードで呼び出されるようにすることができます。このフラグを設定するトランザクション・モードの呼出し側は、トランザクション・タイムアウトの影響を受けます。サービスが異常終了した場合でも、起動時にこのフラグが設定されていれば、呼出し側のトランザクションに影響は及びません。

TPNOTRAN

呼出しプロセスがトランザクション・モードにあり、このフラグが設定されていると、svcが呼び出されたときに、このプロセスは呼出し側のトランザクションの一部として実行されません。svcが依然としてトランザクション・モードで起動される場合がありますが、それは同じトランザクションでないことに注意してください。svcは、構成属性で、自動的にトランザクション・モードで呼び出されるようにすることができます。このフラグを設定するトランザクション・モードの呼出し側は、トランザクション・タイムアウトの影響を受けます。サービスが異常終了した場合でも、起動時にこのフラグが設定されていれば、呼出し側のトランザクションに影響は及びません。

TPNOCHANGE

デフォルトでは、*odataが指すバッファとは異なるタイプのバッファが受信されると、受信側が着信バッファのタイプを識別するかぎり、*odataのバッファ・タイプは、受信されたバッファのタイプに変更されます。このフラグが設定されていると、*odataが指すバッファのタイプを変更できません。つまり、受信されたバッファのタイプおよびサブタイプは、*odataが指すバッファのタイプおよびサブタイプと一致する必要があります。

TPNOBLOCK

このリクエストは、ブロッキング条件が存在する場合(たとえば、メッセージの送信先である内部バッファがいっぱいの場合など)には、送信されません。ただし、このフラグはtpcall()の送信部分にしか適用されません。この関数は応答を待ってブロックすることがあります。TPNOBLOCKが指定されていないときにブロッキング条件が存在すると、呼出し側は、その条件が解消されるか、またはタイムアウト(トランザクションまたはブロッキング)が発生するまではブロックされます。

TPNOTIME

このフラグは、呼出し側が無制限にブロックでき、ブロッキング・タイムアウトの対象にならないようにすることを指定します。ただし、呼出し側がトランザクション・モードの場合、このフラグの効果はありません。この場合、呼出し側はトランザクション・タイムアウトの制限に従います。ただし、トランザクション・タイムアウトは発生する可能性があります。

TPNOCOPY

このフラグはExalogicのみで使用でき、プロセス間通信での共有メモリーの使用の機能が有効になっている場合に使用します(UBBCONFIG(5)).のSHMQオプションに関する項を参照これは、Tuxedoがメッセージ送信プロセスでリクエスト・バッファの安全なコピーを作成しないように指定し、大容量のバッファをコピーするコストを低減します。ただし、tpcall()が失敗すると、呼出し元のアプリケーションがリクエスト・バッファにアクセスできなくなります。tpfree()を呼び出してリクエスト・バッファを解放することをお薦めします。プロセス間通信での共有メモリーの使用が有効ではない場合、このフラグには効果がありません。

TPSIGRSTRT

ルーチン内部のシステム・コールがシグナルによって中断された場合、中断されたシステム・コールは再発行されます。マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドはtpcall()の呼出しを発行できません。

戻り値

tpcall()が正常に終了した場合、あるいはtperrnoがTPESVCFAILに設定されて終了した場合、tpurcode()には、tpreturn()の一部として送信されたアプリケーションが定義した値が入ります。

異常終了すると、tpcall()は -1を返し、tperrnoを設定してエラー条件を示します。呼出しが異常終了してtperrnoに特定の値が設定されたときは、中間のATMI呼出しを省略して引き続きtperrordetail()を呼び出すと、エラーに関する詳細な情報が提供されます。詳細は、「tperrordetail(3c)」リファレンス・ページを参照してください。

エラー

異常終了時には、tpcall()はtperrnoを次のいずれかの値に設定します。(特に記述した場合を除いては、エラーが呼出し側のトランザクションに影響を及ぼすことはありません。)

[TPEINVAL]

無効な引数が指定されました(たとえば、svcがNULLである場合、flagsが無効である場合など)。

[TPENOENT]

svcが存在しないか、会話型サービスであるか、または名前が"."で始まるため、svcに送信できません。

[TPEITYPE]

idataのタイプおよびサブタイプは、svcが受け付けるタイプあるいはサブタイプの1つではありません。

[TPEOTYPE]

応答のタイプおよびサブタイプが呼出し側に認識されていないか、またはTPNOCHANGEがflagsに設定されており、*odataのタイプおよびサブタイプが、そのサービスから送信された応答のタイプおよびサブタイプと一致しません。*odataとその内容も、*olenも変更されません。サービス・リクエストが呼出し側の現在のトランザクションの一部として発行されると、応答が破棄されるので、そのトランザクションは中断のみとマークされます。

[TPETRAN]

svcが、トランザクションをサポートしていないサーバーに属しており、TPNOTRANが設定されていませんでした。

[TPETIME]

このエラー・コードは、タイムアウトが発生したか、または現在のトランザクションがすでに「ロールバックのみ」とマークされているにもかかわらずtpcall()が試行されたことを示します。呼出し側がトランザクション・モードの場合、トランザクションはすでにロールバックのみであるか、またはトランザクション・タイムアウトが発生しました。このトランザクションは、「中断のみ」とマークされます。呼出し側がトランザクション・モードでない場合、ブロッキング・タイムアウトが発生しています。(ブロッキング・タイムアウトは、TPNOBLOCKまたはTPNOTIMEが指定されている場合は発生しません。)いずれの場合でも、*odata、その内容、*olenはいずれも変更されません。トランザクション・タイムアウトが発生すると、1つの例外を除き、トランザクションが中断されないかぎり、新しいリクエストを送信したり、未処理の応答を受信しようとしても、TPETIMEで失敗します。その例外とは、ブロックされず、応答を期待せず、かつ呼出し側のトランザクションのかわりに送信されない(つまり、TPNOTRAN、TPNOBLOCKおよびTPNOREPLYを設定してtpacall()を呼び出した場合の)リクエストです。サービスがトランザクション内部で失敗すると、そのトランザクションはTX_ROLLBACK_ONLY状態になります。ほとんどの場合、この状態はタイムアウトと同じものとして扱われます。このトランザクションの以降のATMI呼出しは、すべてTPETIMEで異常終了します(前の段落で説明した例外を除く)。

[TPESVCFAIL]

呼出し側の応答を送信するサービス・ルーチンが、TPFAILでtpreturn()を呼び出しました。これは、アプリケーション・レベルの障害です。サービスの応答の内容(送信された場合)は、*odataが示すバッファに入ります。呼出し側のトランザクションの一部としてサービス・リクエストが出された場合、トランザクションは中断のみとしてマークされます。トランザクションがタイムアウトしたかどうかにかかわりなく、トランザクションが中断される前の通信で有効であるのは、TPNOREPLY、TPNOTRANおよびTPNOBLOCKを設定したtpacall()の呼出しのみです。

[TPESVCERR]

サービス・ルーチンがtpreturn(3c)またはtpforward(3c)のいずれかでエラーを検出しました(たとえば、誤った引数が渡された場合など)。このエラーが生じた場合には、応答データは返されません(つまり、*odataとその内容も、*olenも変更されません)。呼出し側のトランザクションの一部としてサービス・リクエストが出された場合(つまり、TPNOTRANが設定されていない場合)、このトランザクションは中断のみとしてマークされます。トランザクションがタイムアウトしたかどうかにかかわりなく、トランザクションが中断される前の通信で有効であるのは、TPNOREPLY、TPNOTRANおよびTPNOBLOCKを設定したtpacall()の呼出しのみです。UBBCONFIGファイル内のSVCTIMEOUTまたはTM_MIB内のTA_SVCTIMEOUTが0でない場合にサービスのタイムアウトが発生すると、TPESVCERRが戻されます。

[TPEBLOCK ]

送信呼出しでブロッキング条件が検出されましたが、TPNOBLOCKが指定されていました。

[TPGOTSIG]

シグナルを受け取りましたが、TPSIGRSTRTが指定されていません。

[TPEPROTO]

tpcall()が不正に呼び出されました。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。リモート・ロケーションにあるメッセージ・キューがいっぱいになった場合には、tpcall()が正常に復帰してもTPEOSが返されることがあります。

関連項目:

tpacall(3c)、tpalloc(3c)、tperrordetail(3c)、tpforward(3c)、tpfree(3c)、tpgprio(3c)、tprealloc(3c)、tpreturn(3c)、tpsprio(3c)、tpstrerrordetail(3c)、tptypes(3c)

2.64 tpcancel(3c)

名前

tpcancel() - 未終了の応答に対する呼出し記述子を無効にするためのルーチン。

形式

#include <atmi.h>
int tpcancel(int cd)

説明

tpcancel()は、tpacall()が返す呼出し記述子cdを取り消します。トランザクションに関連している呼出し記述子を無効にしようとするとエラーになります。

正常終了の場合、cdは以後無効になり、cdのために受信する応答はすべて、警告なしに破棄されます。

マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドはtpcancel()の呼出しを発行できません

戻り値

異常終了時には、tpcancel()は-1を返し、tperrnoを設定してエラー条件を示します。

エラー

失敗すると、tpcancel()はtperrnoを次のいずれかの値に設定します。

[TPEBADDESC]

cdは、無効な記述子です。

[TPETRAN]

cd()は、呼出し側のトランザクションに関連しています。cdはそのまま有効で、呼出し側の現在のトランザクションは影響を受けません。

[TPEPROTO]

tpcancel()が不正に呼び出されました。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。

関連項目:

tpacall(3c)

2.65 tpchkauth(3c)

名前

tpchkauth() - アプリケーションへの参加に認証が必要かどうかをチェックするルーチン。

形式

#include <atmi.h>

int tpchkauth(void)

説明

tpchkauth()は、アプリケーションの構成が認証を必要としているかどうかを調べます。これは一般に、tpinit()を呼び出す前にアプリケーション・クライアントが使用して、ユーザーからのパスワードの入力を必要とするかどうかを判別します。

マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドはtpchkauth()の呼出しを発行できません。

戻り値

tpchkauth()は、正常終了時に次のような負でない値を返します。

TPNOAUTH

認証が必要とされないことを示します。

TPSYSAUTH

システムの認証のみが必要とされることを示します。

TPAPPAUTH

システムの認証およびアプリケーション固有の認証の両方が必要であることを示します。

異常終了すると、tpchkauth()は -1を返し、tperrnoを設定してエラー条件を示します。

エラー

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

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。

相互運用性

tpchkauth()は、リリース4.2以降を使用しているサイトでしか使用できません。

移植性

tpchkauth(3c)に記述されているインタフェースは、UNIX、Windows、およびMS-DOSオペレーティング・システム上でサポートされています。

関連項目:

tpinit(3c)

2.66 tpchkunsol(3c)

名前

tpchkunsol() - 任意通知型メッセージをチェックするルーチン。

形式

#include <atmi.h>
int tpchkunsol(void)

説明

tpchkunsol()は、クライアントが任意通知型メッセージをチェックするときに使用します。クライアントでシグナル・ベースの通知を使用してこのルーチンを呼び出しても、何も行われず、ただちに終了します。この呼出しには、引数はありません。このルーチンを呼び出すと、アプリケーションで定義された任意通知型メッセージ処理ルーチンへの呼出しがOracle Tuxedo ATMIシステムのライブラリによって行われることがあります。

マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドはtpchkunsol()の呼出しを発行できません。

戻り値

正常終了の場合、tpchkunsol()は、ディスパッチされた非請求メッセージの番号を返します。異常終了すると、tpchkunsol()は -1を返し、tperrnoを設定してエラー条件を示します。

エラー

失敗すると、tpchkunsol()はtperrnoを次のいずれかの値に設定します。

[TPEPROTO]

tpchkunsol()が不正なコンテキストで呼び出されました(たとえば、サーバー内から)。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

[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)

2.67 tpclose(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]

tpclose()が不正なコンテキストで呼び出されました(たとえば、呼出し側がトランザクション・モードにあるとき)。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。

関連項目:

tpopen(3c)、tprmopen(3c)、tprmclose(3c)、tprmstart(3c)、tprmend(3c)

2.68 tpcommit(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]

flagsが0ではありません。呼出し側のトランザクションは影響を受けません。

[TPEOS]

オペレーティング・システムのエラーが発生しました。オペレーティング・システムのエラーが発生しました。

[TPEPROTO]

tpcommit()が不正なコンテキストで呼び出されました(たとえば、参加リソースにより呼び出されるなど)。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

[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)

2.69 tpconnect(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()を呼び出す必要はありません。

次に、有効なflagsの一覧を示します:

TPNOTRAN

呼出しプロセスがトランザクション・モードにあり、このフラグが設定されていると、svcが呼び出されたときに、このプロセスは呼出し側のトランザクションの一部として実行されません。svcが依然としてトランザクション・モードで起動される場合がありますが、それは同じトランザクションでないことに注意してください。svcは、構成属性で、自動的にトランザクション・モードで呼び出されるようにすることができます。このフラグを設定するトランザクション・モードの呼出し側は、トランザクション・タイムアウトの影響を受けます。サービスが異常終了した場合でも、起動時にこのフラグが設定されていれば、呼出し側のトランザクションに影響は及びません。

TPSENDONLY

呼出し側は、最初にそれがデータの送信のみを行え、呼び出されたサービスはデータの受信のみを行えるように(つまり、呼出し側が当初の接続の制御権を有するように)接続を設定します。TPSENDONLYまたはTPRECVONLYのいずれかを指定しなければなりません。

TPRECVONLY

呼出し側は、それがデータの受信のみを行え、呼び出されたサービスがデータの送信のみを行えるように(つまり、呼び出されるサービスが当初、接続の制御権を有するように)接続を設定します。TPSENDONLYまたはTPRECVONLYのいずれかを指定しなければなりません。

TPNOBLOCK

ブロッキング条件が存在する場合、接続が設定されておらず、データが送信されません(たとえば、メッセージが送信されるときに使用されるデータ・バッファがいっぱいである場合)。このフラグは、tpconnect()の送信部分にだけ適用されます。関数は、サーバーからの承認を待つ間ブロックする場合があります。TPNOBLOCKが指定されておらず、ブロッキング条件が存在する場合、条件の解除、またはブロッキング・タイムアウトあるいはトランザクション・タイムアウトが発生するまで呼出し側はブロックされます。

TPNOTIME

このフラグは、呼出し側が無制限にブロックでき、ブロッキング・タイムアウトの対象にならないようにすることを指定します。ただし、トランザクション・タイムアウトは引き続き有効です。

TPSIGRSTRT

ルーチン内部のシステム・コールがシグナルによって中断された場合、中断されたシステム・コールは再発行されます。

マルチスレッド・アプリケーションの場合、TPINVALIDCONTEXT状態のスレッドはtpconnect()の呼出しを発行できません。

戻り値

tpconnect()が正常に終了した場合、以後の呼出しでの接続を指すのに使用する記述子を返します。エラー時には、-1を返し、tperrnoを設定してエラー条件を示します。

エラー

異常終了時には、tpconnect()はtperrnoを次のいずれかの値に設定します。(特に記述した場合を除いては、エラーが呼出し側のトランザクションに影響を及ぼすことはありません。)

[TPEBLOCK]

ブロッキング状態のため、TPNOBLOCKが指定されました。

[TPEINVAL]

無効な引数が指定されました(たとえば、svcがNULLである場合、dataがNULLでなくtpalloc()で割り当てられたバッファを指していない場合、TPSENDONLYまたはTPRECVONLYがflagsに指定されていない場合、flagsが無効である場合など)。

[TPEITYPE]

dataのタイプおよびサブタイプは、svcが受け付けるタイプあるいはサブタイプの1つではありません。

[TPELIMIT]

未終了の接続の最大数に達したため、呼出し側のリクエストは送信されませんでした。

[TPENOENT]

svcが存在しないか、会話型サービスでないため、svcへの接続を開始できません。

[TPEOS]

オペレーティング・システムのエラーが発生しました。

[TPEPROTO]

tpconnect()が不正に呼び出されました。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

[TPETIME]

このエラー・コードは、タイムアウトが発生したか、または現在のトランザクションがすでに「ロールバックのみ」とマークされているにもかかわらずtpconnect()が試行されたことを示します。呼出し側がトランザクション・モードの場合、トランザクションはすでにロールバックのみであるか、またはトランザクション・タイムアウトが発生しました。このトランザクションは、「中断のみ」とマークされます。呼出し側がトランザクション・モードでない場合、ブロッキング・タイムアウトが発生しています。(ブロッキング・タイムアウトは、TPNOBLOCKまたはTPNOTIMEが指定されている場合は発生しません。)トランザクション・タイムアウトが発生すると、1つの例外を除き、トランザクションが中断されないかぎり、新しい会話を開始したり、新しいリクエストを送信したり、未処理の応答を受信しようとしても、TPETIMEで失敗します。その例外とは、ブロックされず、応答を期待せず、かつ呼出し側のトランザクションのかわりに送信されない(つまり、TPNOTRAN、TPNOBLOCKおよびTPNOREPLYを設定してtpacall()を呼び出した場合の)リクエストです。サービスがトランザクション内部で失敗すると、そのトランザクションはTX_ROLLBACK_ONLY状態になります。ほとんどの場合、この状態はタイムアウトと同じものとして扱われます。このトランザクションの以降のATMI呼出しは、TPETIMEで失敗します(前の段落で説明した例外を除く)。

[TPETRAN]

svcが、トランザクションをサポートしていないプログラムに属しており、TPNOTRANが設定されていませんでした。

[TPGOTSIG]

シグナルを受け取りましたが、TPSIGRSTRTが指定されていません。

関連項目:

tpalloc(3c)、tpdiscon(3c)、tprecv(3c)、tpsend(3c)、tpservice(3c)

2.70 tpconvert(3c)

名前

tpconvert() - 構造体を文字列表現に、または文字列表現を構造体に変換します。

形式

#include <atmi.h>
#include <xa.h>

int tpconvert(char *strrep, char *binrep, long flags)

説明

tpconvert()は、インタフェース構造体の文字列表現(strrep)とバイナリ表現(binrep)の間で変換を行います。

変換の方向およびインタフェース構造体のタイプは、どららもflags引数で指定します。バイナリ表現から文字列表現に構造体を変換するには、プログラマがTPTOSTRINGビットをflagsに設定する必要があります。文字列からバイナリに構造体を変換するには、プログラマがビットをクリアする必要があります。変換する構造体のタイプを示すフラグは次のように定義されており、同時に1つのフラグのみを指定できます。

[TPCONVCLTID]

CLIENTIDを変換します(atmi.hを参照)。

[TPCONVTRANID]

TPTRANIDを変換します(atmi.hを参照)。

[TPCONVXID]

XIDを変換します(xa.hを参照)。

バイナリ表現から文字列表現に変換する場合、strrepは最低でもTPCONVMAXSTR文字の長さがなければなりません。TPTRANIDとXIDの値が異なる文字列バージョンをキー・フィールドとして許すTM_MIB(5)クラス(たとえば、T_TRANSACTIONまたはT_ULOG)にアクセスする場合は、システムはこれらの値をequalとして扱うことに注意してください。したがって、アプリケーション・プログラムでは、これらのデータ・タイプの文字列の値を作ったり操作したりすべきではありません。これらの値のいずれかがキー・フィールドとして使用される場合、TM_MIB(5)は文字列で識別されるグローバル・トランザクションに一致するオブジェクトのみが返されることを保証します。

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

戻り値

異常終了すると、tpconvert()は -1を返し、tperrnoを設定してエラー条件を示します。

エラー

次の条件が発生すると、tpconvert()は失敗し、tperrnoを次のように設定します。

[TPEINVAL]

無効な引数が指定されました。strrepまたはbinrepがNULLポインタであるか、flagsが1つの構造タイプのみを示していません。

[TPEOS]

オペレーティング・システムのエラーが発生しました。失敗したシステム・コールを示す数値がUunixerrに入っています。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質はuserlog(3c).に書き込まれます

移植性

このインタフェースは、Oracle Tuxedo ATMIリリース5.0またはそれ以降でしか利用できません。このインタフェースは、ワークステーション・プラットフォームで利用できます。

関連項目:

tpresume(3c)、tpservice(3c)、tpsuspend(3c)、tx_info(3c)、TM_MIB(5)

2.71 tpconvmb(3c)

名前

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]

引数target_encoding、lenまたはbufpの値がNULLになっています。lenまたはtarget_encodingが無効です。

[TPEPROTO]

bufpは、バッファ・タイプ・スイッチ変換関数がないTuxedoバッファに変換します

[TPESYSTEM]

Tuxedoシステムのエラーが発生しました。(bufpが有効なTuxedoバッファに対応していない場合など)。

[TPEOS]

オペレーティング・システムのエラーが発生しました。失敗したシステム・コールを示す数値がUunixerrに入っています。

関連項目:

tpalloc(3c)、tpgetmbenc(3c)、tpsetmbenc(3c)

2.72 tpcryptpw(3c)

名前

tpcryptpw() - 管理リクエスト内のアプリケーション・パスワードを暗号化します。

形式

#include <atmi.h>
#include <fml32.h>

int tpcryptpw(FBFR32 *buf)

説明

tpcryptpw()は、サービスにリクエストを送る前に管理リクエスト・バッファ内のアプリケーション・パスワードを暗号化するために使用します。アプリケーション・パスワードは、FML32フィールド識別子TA_PASSWORDを用いて文字列値として保存されます。この暗号化は、テキスト・レベルのパスワードが危険にさらされず、すべてのアクティブなアプリケーション・サイトに適当なパスワードの更新が伝播することを保証するために必要です。付加的なシステム・フィールドが呼出し側のバッファに追加され、既存のフィールドがリクエストを満たすために変更されることがあります。

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

戻り値

異常終了すると、tpcryptpw()は -1を返し、tperrnoを設定してエラー条件を示します。

エラー

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

[TPEINVAL]

無効な引数が指定されました。bufの値がNULLで、FML32型付きバッファを指していないか、appdirが入力バッファもしくは環境から決定できませんでした。

[TPEPERM]

呼出し側プロセスが、リクエスト・タスクの実行に必要な適当なパーミッションを持っていませんでした。

[TPEOS]

オペレーティング・システムのエラーが発生しました。失敗したシステム・コールを示す数値がUunixerrに入っています。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質はuserlog(3c)に書き込まれます。

移植性

このインタフェースは、Oracle Tuxedo ATMIリリース5.0またはそれ以降が稼働するUNIX Systemのサイトでしか利用できません。このインタフェースはワークステーション・クライアントでは利用できません。

ファイル

${TUXDIR}/lib/libtmib.a、${TUXDIR}/lib/libtmib.so.rel

関連項目:

MIB(5)、TM_MIB(5)

Oracle Tuxedoアプリケーションの設定

Oracle Tuxedoアプリケーション実行時の管理

2.73 tpdequeue(3c)

名前

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フラグが設定されている場合は、メッセージはトランザクション・モードではキューから取り出されません。トランザクション・モードでない場合に通信エラーまたはタイムアウトが発生した場合、アプリケーションには、メッセージが正しくキューから取り出されたかどうかがわからず、メッセージが失われることがあります。

次に、有効なflagsの一覧を示します:

TPNOTRAN

呼出し側がトランザクション・モードにある場合に、このフラグが設定されていると、メッセージは呼出し側のトランザクション内ではキューから取り出されません。このフラグを設定するトランザクション・モードの呼出し側には、メッセージをキューから取り出すときにトランザクション・タイムアウトが適用され、それ以外は適用されません。キューからのメッセージの取出しが失敗した場合でも、呼出し側のトランザクションは影響されません。

TPNOBLOCK

ブロッキング状態が存在すると、メッセージはキューから取り出されません。このフラグが設定されていて、メッセージの転送先である内部バッファがいっぱいであるなどのブロッキング条件が存在する場合には、呼出しは異常終了し、tperrnoにTPEBLOCKが設定されます。このフラグが設定されていて、ターゲットのキューが別のアプリケーションによって排他的にオープンされているなどのブロッキング条件が存在する場合には、呼出しは異常終了してtperrnoにTPEDIAGNOSTICが設定され、TPQCTL構造体の診断フィールドはQMESHAREに設定されます。後者の場合、Oracle Tuxedo ATMIシステム以外のOracle製品をベースとするアプリケーションが、キューイング・サービスAPI (QSAPI)を使用した排他的な読取り/書込みのためのキューをオープンしています。

TPNOBLOCKが設定されていない場合に、ブロッキング状態が存在すると、その状態が解消されるかタイムアウト(トランザクション・タイムアウトまたはブロッキング・タイムアウト)が発生するまで、呼出し側はブロックされます。(TPQCTL構造体の) flagsにTPQWAITオプションが指定されている場合は、このブロッキング条件には、キュー自体のブロッキングは含まれません。

TPNOTIME

このフラグを設定すると、呼出し側は無制限にブロックでき、ブロッキング・タイムアウトが適用されなくなります。ただし、トランザクション・タイムアウトは発生する可能性があります。

TPNOCHANGE

このフラグが設定されていると、*dataが指すバッファのタイプを変更できません。デフォルトでは、*dataが指すバッファとは異なるタイプのバッファが受信されると、受信側が着信バッファのタイプを識別するかぎり、*dataのバッファ・タイプは、受信されたバッファのタイプに変更されます。つまり、キューから取り出されたメッセージのタイプおよびサブタイプは、*dataが指すバッファのタイプおよびサブタイプと一致する必要があります。

TPSIGRSTRT

このフラグが設定されていると、基底のシステム・コールがシグナルによって中断された場合、中断されたシステム・コールが再度呼び出されます。このフラグが設定されていないときにシグナルによってシステム・コールが中断されると、呼出しは異常終了し、tperrnoはTPGOTSIGに設定されます。

tpdequeue()が正常終了すると、アプリケーションは、ctlデータ構造体を使用してメッセージに関する追加情報を取得できます。この情報には、キューから取り出されたメッセージのメッセージ識別子、すべての応答または異常終了メッセージに付随して、発信元がメッセージと元のリクエストを結び付けることができるようにする相関識別子、メッセージが送られるサービスの品質、メッセージの応答が送られるサービスの品質、応答が要求された場合は応答キューの名前、およびメッセージをキューから取り出すときの失敗に関する情報をアプリケーションが登録できる異常終了キューの名前が含まれます。これらについて以下に説明します。

マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドは、tpdequeue()の呼出しを発行できません。

制御パラメータ

TPQCTL構造体は、アプリケーション・プログラムが、キューからのメッセージの取出しに関連するパラメータを渡したり、取得したりするために使用します。TPQCTLの要素flagsは、この構造体の他のどの要素が有効であるかを示すために使用されます。

tpdequeue()への入力時には、次の要素をTPQCTL構造体に設定できます。

long flags; /* indicates which of the values
                   * are set */
char msgid[32]; /* ID of message to dequeue */
char corrid[32]; /* correlation identifier of
                           * message to dequeue */

tpdequeue()の入力情報を制御するflagsパラメータの有効なビットの一覧を次に示します:

TPNOFLAGS

フラグは設定されません。制御構造体から情報は取得されません。

TPQGETBYMSGID

このフラグが設定されていると、ctl−>msgidで指定されたメッセージ識別子を持つメッセージを取り出すことがリクエストされます。メッセージ識別子は、事前のtpenqueue(3c)の呼出しによって取得できます。メッセージが別のキューに移動すると、メッセージ識別子が変わることに注意してください。メッセージ識別子の値は32バイト全体が意味を持つので、ctl−>msgidで指定される値は、たとえばNULL文字を埋め込むなどして、完全に初期化される必要があります。

TPQGETBYCORRID

このフラグが設定されていると、ctl−>corridで指定された相関識別子を持つメッセージを取り出すことがリクエストされます。相関識別子は、アプリケーションがtpenqueue()でメッセージをエンキューしたときに指定されます。相関識別子の値は32バイト全体が意味を持つので、ctl−>corridで指定される値は、たとえばNULL文字を埋め込むなどして、完全に初期化される必要があります。

TPQWAIT

このフラグが設定されていると、キューが空の場合はエラーが戻されません。かわりに、メッセージを取り出せるようになるまで、プロセスは待機する必要があります。TPQWAITがTPQGETBYMSGIDまたはTPQGETBYCORRIDとともに設定されている場合、指定されたメッセージ識別子または相関識別子を持つメッセージがキューに存在しないときは、エラーが戻されません。かわりに、基準を満たすメッセージを取り出せるようになるまで、プロセスは待機する必要があります。プロセスは、引き続き呼出し側のトランザクション・タイムアウトの影響を受けます。または、トランザクション・モードでない場合、プロセスは-tオプションによってTMQUEUEプロセスに指定されたタイムアウトの影響を受けます。必要な基準に一致するメッセージをすぐに利用できず、構成されたアクション・リソースがすべて使用されている場合、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以内の範囲内で、数値が高いほど優先度も高くなります。つまり、高い数値のメッセージが低い数値のメッセージよりも先にキューから取り出されます。優先度によって順序付けられていないキューの場合、値は情報にすぎません。

メッセージがキューに登録されるときに優先度が明示的に指定されずにtpdequeue()呼出しが正常に終了した場合、このメッセージの優先度は50になります。

TPQMSGID

このフラグが設定されている場合に、tpdequeue()の呼出しが成功すると、メッセージ識別子がctl−>msgidに格納されます。メッセージ識別子の値は、32バイト全体が意味を持ちます。

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]

無効な引数が指定されました(たとえば、qnameがNULLである場合、dataがtpalloc()によって割り当てられた空間を指していない場合、flagsが無効である場合など)。

[TPENOENT]

qspaceを使用できないので、これにアクセスできません(関連するTMQUEUE(5)サーバーは使用できません)。または、グローバル・トランザクション表(GTT)にエントリがないので、グローバル・トランザクションを開始できません。

[TPEOTYPE]

デキューされたメッセージのタイプおよびサブタイプが呼出し側に認識されていないか、またはTPNOCHANGEがflagsに設定されており、*dataのタイプおよびサブタイプが、デキューされたメッセージのタイプおよびサブタイプと一致しません。いずれの場合も、*data、その内容、および*lenは変更されません。 呼出しがトランザクション・モードで行われ、このエラーが発生すると、トランザクションは中断のみとマークされ、メッセージはキューに残ります。

[TPETIME]

このエラー・コードは、タイムアウトが発生したか、または現在のトランザクションがすでに「ロールバックのみ」とマークされているにもかかわらずtpdequeue()が試行されたことを示します。

呼出し側がトランザクション・モードの場合、トランザクションはすでにロールバックのみであるか、またはトランザクション・タイムアウトが発生しました。このトランザクションは、「中断のみ」とマークされます。呼出し側がトランザクション・モードでない場合、ブロッキング・タイムアウトが発生しています。(ブロッキング・タイムアウトは、TPNOBLOCKまたはTPNOTIMEが指定されている場合は発生しません。)いずれのケースでも、*data、その内容、*lenはいずれも変更されません。

トランザクション・タイムアウトが発生すると、1つの例外を除き、トランザクションが中断されないかぎり、会話を継続したり、新しいリクエストを送信したり、未処理の応答を受信しようとしても、TPETIMEで失敗します。その例外とは、ブロックされず、応答を期待せず、かつ呼出し側のトランザクションのかわりに送信されない(つまり、TPNOTRAN、TPNOBLOCKおよびTPNOREPLYを設定してtpacall()を呼び出した場合の)リクエストです。

サービスがトランザクションの内部で失敗した場合、そのトランザクションはTX_ROLLBACK_ONLY状態に置かれます。ほとんどの場合、この状態はタイムアウトと同じものとして扱われます。このトランザクションの以降のATMI呼出しは、すべてTPETIMEで異常終了します(前の段落で説明した例外を除く)。

[TPEBLOCK]

ブロッキング状態のため、TPNOBLOCKが指定されました。

[TPGOTSIG]

シグナルを受け取りましたが、TPSIGRSTRTが指定されていません。

[TPEPROTO]

tpdequeue()が不正に呼び出されました。キューまたはトランザクションには影響ありません。[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。キューには影響ありません。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。キューには影響ありません。

[TPEOS]

オペレーティング・システムのエラーが発生しました。キューには影響ありません。

[TPEDIAGNOSTIC]

指定されたキューからのメッセージの取出しが異常終了しました。異常終了の原因は、ctl構造体を介して返される診断値によって判別できます。

診断

次の診断値は、キューからのメッセージの取出し中に返されます。

[QMEINVAL]

無効なフラグ値が指定されています。

[QMEBADRMID]

無効なリソース・マネージャ識別子が指定されています

[QMENOTOPEN]

リソース・マネージャが現在オープンされていません。

[QMETRAN]

トランザクション・モードで呼出しが行われなかったため、またはTPNOTRANフラグを設定して呼び出したために、メッセージをキューから取り出すトランザクション開始のエラーが発生しました。この診断は、Oracle Tuxedoリリース7.1以降のキュー・マネージャからは返されません。

[QMEBADMSGID]

キューからの取出し用に、無効なメッセージ識別子が指定されました。

[QMESYSTEM]

システム・エラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

[QMEOS]

オペレーティング・システムのエラーが発生しました。

[QMEABORTED]

操作が中断されました。グローバル・トランザクション内で実行されている場合、グローバル・トランザクションがロールバックのみとしてマークされています。それ以外の場合、キュー・マネージャは操作を中断しました。

[QMEPROTO]

トランザクション状態がアクティブでないときに、キューからの取出しが行われました。

[QMEBADQUEUE]

無効または削除されたキューの名前が指定されています。

[QMENOMSG]

キューから取り出せるメッセージはありません。メッセージがキュー上に存在し、別のアプリケーション・プロセスがこのメッセージをキューから読み取った可能性があることに注意してください。この場合、その別のプロセスがトランザクションをロールバックしたときに、メッセージはキューに戻されます。

[QMEINUSE]

メッセージ識別子または相関識別子を使用してメッセージをキューから取り出す際に、指定されたメッセージが別のトランザクションによって使用されています。それ以外の場合、現在キューにあるすべてのメッセージは、ほかのトランザクションによって使用されています。この診断は、Oracle Tuxedoリリース7.1以降のキュー・マネージャからは返されません。

[QMESHARE]

指定されたキューからメッセージを取り出す際に、そのキューが別のアプリケーションによって排他的にオープンされています。Oracle Tuxedoシステム以外のOracle製品ベースのアプリケーションが、キューイング・サービスAPI (QSAPI)を使用して読取りおよび書込みを排他的に行うため、キューをオープンしています。

関連項目:

qmadmin(1)、tpalloc(3c)、tpenqueue(3c)、APPQ_MIB(5)、TMQUEUE(5)

2.74 tpdiscon(3c)

名前

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]

cdが無効であるか、会話型サービスの起動に使用された記述子です。

[TPETIME]

このエラー・コードは、タイムアウトが発生したか、または現在のトランザクションがすでに「ロールバックのみ」とマークされているにもかかわらずtpdiscon()が試行されたことを示します。

呼出し側がトランザクション・モードの場合、トランザクションはすでにロールバックのみであるか、またはトランザクション・タイムアウトが発生しました。このトランザクションは、「中断のみ」とマークされます。(呼出し側のトランザクションで接続時にtpdiscon()を呼び出すと、tpdiscon()が正常に呼び出されても、トランザクションが中断のみとしてマークされる可能性があります。)

呼出し側がトランザクション・モードでない場合、ブロッキング・タイムアウトが発生しています。

トランザクション・タイムアウトが発生すると、1つの例外を除き、トランザクションが中断されないかぎり、会話を継続したり、新しいリクエストを送信したり、未処理の応答を受信しようとしても、TPETIMEで失敗します。その例外とは、ブロックされず、応答を期待せず、かつ呼出し側のトランザクションのかわりに送信されない(つまり、TPNOTRAN、TPNOBLOCKおよびTPNOREPLYを設定してtpacall()を呼び出した場合の)リクエストです。

サービスがトランザクションの内部で失敗した場合、そのトランザクションはTX_ROLLBACK_ONLY状態に置かれます。ほとんどの場合、この状態はタイムアウトと同じものとして扱われます。このトランザクションの以降のATMI呼出しは、すべてTPETIMEで異常終了します(前の段落で説明した例外を除く)。

[TPEPROTO]

tpdiscon()が不正に呼び出されました。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。記述子は無効になります。

[TPEOS]

オペレーティング・システムのエラーが発生しました。記述子は無効になります。

関連項目:

tpabort(3c)、tpcommit(3c)、tpconnect(3c)、tprecv(3c)、tpreturn(3c)、tpsend(3c)

2.75 tpenqueue(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は、キューに登録されるバッファ内のデータの大きさを指定しなければなりません。ただし、dataが長さの指定を必要としないタイプのバッファを指す場合(FMLフィールド化バッファなど)、lenは無視されます。dataがNULLの場合、lenは無視され、メッセージはデータ部分なしでキューに登録されます。

メッセージは、qspace用に定義された優先度が事前のtpsprio()の呼出しによって無効化されていないかぎり、qspace用の優先度でキューに登録されます。

呼出し側がトランザクションにあり、TPNOTRANフラグが設定されていない場合は、メッセージは、トランザクション・モードでエンキューされます。この結果、tpenqueue()が正常終了して呼出し側のトランザクションが正常にコミットされると、メッセージは、トランザクションの完了後に処理されることが保証されます。呼出し側のトランザクションが、明示的に、またはトランザクション・タイムアウトあるいはなんらかの通信エラーの結果としてロールバックされると、メッセージはキューから削除されます(つまり、キューへのメッセージの登録もロールバックされます)。同じトランザクション内で同じメッセージの登録と取出しを行うことはできません。

呼出し側がトランザクション・モードにないか、またはTPNOTRANフラグが設定されている場合は、メッセージはトランザクション・モードではキューに登録されません。tpenqueue()が正常終了すれば、出されたメッセージが処理されることが保証されます。トランザクション・モードでないときに通信エラーまたはタイムアウトが発生した場合、アプリケーションには、メッセージが正しくキューに格納されたかどうかがわかりません。

メッセージがキューに配置される順序は、この後説明するように、ctlデータ構造体を介してアプリケーションによって制御されます。デフォルトのキューの順序は、キューの作成時に設定されます。

次に、有効なflagsの一覧を示します。

TPNOTRAN

呼出し側がトランザクション・モードにあり、このフラグが設定されていると、メッセージは呼出し側と同じトランザクション内ではキューに登録されません。このフラグを設定するトランザクション・モードの呼出し側は、メッセージをキューに登録するときに、やはりトランザクション・タイムアウトの影響を受けます(それ以外はなし)。キューへのメッセージの登録が失敗した場合、呼出し側のトランザクションは影響されません。

TPNOBLOCK

ブロッキング状態が存在する場合、メッセージはキューに登録されません。このフラグが設定されていて、メッセージの転送先である内部バッファがいっぱいであるなどのブロッキング条件が存在する場合には、呼出しは異常終了し、tperrnoにTPEBLOCKが設定されます。このフラグが設定されていて、ターゲットのキューが別のアプリケーションによって排他的にオープンされているなどのブロッキング条件が存在する場合には、呼出しは異常終了してtperrnoにTPEDIAGNOSTICが設定され、TPQCTL構造体の診断フィールドはQMESHAREに設定されます。後者の場合、Oracle Tuxedo ATMIシステム以外のOracle製品をベースとするアプリケーションが、キューイング・サービスAPI (QSAPI)を使った排他的な読み書きのためのキューをオープンしています。

TPNOBLOCKが設定されていない場合に、ブロッキング状態が存在すると、その状態が解消されるかタイムアウト(トランザクション・タイムアウトまたはブロッキング・タイムアウト)が発生するまで、呼出し側はブロックされます。タイムアウトが発生すると、呼出しは異常終了し、tperrnoはTPETIMEに設定されます。

TPNOTIME

このフラグを設定すると、呼出し側は無制限にブロックでき、ブロッキング・タイムアウトが適用されなくなります。ただし、トランザクション・タイムアウトは発生する可能性があります。

TPSIGRSTRT

このフラグが設定されていて、基本となるシステム・コールがシグナルによって中断された場合、中断されたシステム・コールは再発行されます。TPSIGRSTRTが指定されておらず、システム・コールがシグナルによって中断された場合、tpenqueue()は異常終了し、tperrnoにTPGOTSIGが設定されます。

キューへのメッセージ登録に関する追加情報は、ctlデータ構造体を介して指定できます。この情報には、デフォルトのキューの順序付けをオーバーライドしてキューの先頭または登録済のメッセージの前にメッセージを登録するための値、キューからメッセージを取り出すまでの絶対時間または相対時間、メッセージが期限切れになりキューから削除される絶対時間または相対時間、メッセージ配信サービスの品質、メッセージが応答する際のサービス品質、メッセージとそのメッセージに関連付けられた応答または失敗メッセージを結び付けるときに役立つ相関識別子、応答を登録するキューの名前、およびすべての失敗メッセージを登録するキューの名前が含まれます。

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

制御パラメータ

TPQCTL構造体は、アプリケーション・プログラムが、キューへのメッセージの登録に関連するパラメータを渡したり、取得したりする際に使用されます。TPQCTLの要素flagsは、この構造体の他のどの要素が有効であるかを示すために使用されます。

tpenqueue()への入力時には、次の要素をTPQCTL構造体に設定できます。

long flags; /* indicates which of the values
                         * are set */
long deq_time; /* absolute/relative for dequeuing */
long priority; /* enqueue priority */
long exp_time; /* expiration time */
long delivery_qos; /* delivery quality of service */
long reply_qos; /* reply quality of service */
long urcode; /* user-return code */
char msgid[32]; /* ID of message before which to queue
                         * request */
char corrid[32]; /* correlation identifier used to
                         * identify the msg */
char replyqueue[128]; /* queue name for reply message */
char failurequeue[128]; /* queue name for failure message */

tpenqueue()の入力情報を制御するflagsパラメータの有効なビットの一覧を次に示します。どのフラグ・ビットでも、tpdequeue()の呼出し時にオンになっていると、メッセージがエンキューされたときに提供された値が、構造体の関連する要素に格納され、そのビットは設定されたままになります。値が使用できない場合、またはtpdequeue()を呼び出したときにビットが設定されなかった場合、tpdequeue()はフラグがオフの状態で完了します。

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以下の範囲である必要があります。数値が高いほど優先度も高くなり、高い数値のメッセージが低い数値のメッセージより先にキューから取り出されます。優先度によって順序付けられていないキューでは、この値は参考として使用されます。

このフラグを設定しなかった場合、メッセージの優先度はデフォルトの50になります。

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の有効なflagsの一覧を示します:

TPQQOSDEFAULTPERSIST

このフラグは、ターゲットのキューで指定されているデフォルトの配信ポリシーを使用して、メッセージが配信されるように指定します。

TPQQOSPERSISTENT

このフラグは、メッセージがディスク・ベースの配信方法を使用して、永続的な記憶域に配信されることを指定します。このフラグの設定は、ターゲットのキューに指定されているデフォルトの配信ポリシーよりも優先されます。

TPQQOSNONPERSISTENT

このフラグは、メッセージがメモリー・ベースの配信方法を使用して、非永続的な記憶域に配信されることを指定します。特に、メッセージはキューから取り出されるまでメモリー内に登録されています。このフラグの設定は、ターゲットのキューに指定されているデフォルトの配信ポリシーよりも優先されます。呼出し側がトランザクション・モードの場合、非永続メッセージは呼出し側のトランザクション内でキューに登録されますが、システムがシャットダウンやクラッシュした場合、またはキュー・スペースとしてのIPC共有メモリーが削除された場合、非永続メッセージは失われます。

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つのどのフラグも設定されていない場合、ターゲットのキューに対応しているデフォルトの有効期限の時間がメッセージに適用されます。

TPQENQGETUSAGE

このフラグを設定すると、tpenque()関数が成功した場合に、tpenque()からキュー領域使用量を返す必要があることを示します。成功した場合は、tpenque()がctl->auxiliary[AUXIDX_QSPACEUSAGE]でキュー領域使用率を返します。たとえば、ctl->auxiliary[AUXIDX_QSPACEUSAGE]が50の場合は、現在のキュー領域使用率は50%です。

返されたキュー領域使用量は、メッセージ使用率とディスク使用率の最大値です。ディスク使用率は、現在使用されているディスク領域を有効なディスク領域で除算したものです。有効なディスク領域は、予約ディスク領域(キュー領域の制御領域によって使用される)と冗長領域(50ブロック)を、キュー領域が割り当てられているディスク領域全体から減算して算出します。

また、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]

無効な引数が指定されました(たとえば、qspaceがNULLである場合、dataがtpalloc()によって割り当てられた空間を指していない場合、flagsが無効である場合など)。

[TPENOENT]

qspaceを使用できないので、これにアクセスできません(関連するTMQUEUE(5)サーバーは使用できません)。または、グローバル・トランザクション表(GTT)にエントリがないので、グローバル・トランザクションを開始できません。

[TPETIME]

このエラー・コードは、タイムアウトが発生したか、または現在のトランザクションがすでに「ロールバックのみ」とマークされているにもかかわらずtpenqueue()が試行されたことを示します。

呼出し側がトランザクション・モードの場合、トランザクションはすでにロールバックのみであるか、またはトランザクション・タイムアウトが発生しました。このトランザクションは、「中断のみ」とマークされます。呼出し側がトランザクション・モードでない場合、ブロッキング・タイムアウトが発生しています。(ブロッキング・タイムアウトは、TPNOBLOCKまたはTPNOTIMEが指定されている場合は発生しません。)

トランザクション・タイムアウトが発生した場合、トランザクションが中断されないかぎり、新しいリクエストの送信や未処理の応答の受信はできず、TPETIMEが発生します。その例外とは、ブロックされず、応答を期待せず、かつ呼出し側のトランザクションのかわりに送信されない(つまり、TPNOTRAN、TPNOBLOCKおよびTPNOREPLYを設定してtpacall()を呼び出した場合の)リクエストです。

サービスがトランザクションの内部で失敗した場合、そのトランザクションはTX_ROLLBACK_ONLY状態に置かれます。ほとんどの場合、この状態はタイムアウトと同じものとして扱われます。このトランザクションの以降のATMI呼出しは、すべてTPETIMEで異常終了します(前の段落で説明した例外を除く)。

[TPEBLOCK]

ブロッキング状態のため、TPNOBLOCKが指定されました。

[TPGOTSIG]

シグナルを受け取りましたが、TPSIGRSTRTが指定されていません。

[TPEPROTO]

tpenqueue()が不正に呼び出されました。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。

[TPEDIAGNOSTIC]

指定されたキューへのメッセージの登録が異常終了しました。異常終了の原因は、ctlを介して返される診断値によって判別できます。

診断

次の診断値は、キューへのメッセージの登録中に返されます。

[QMEINVAL]

無効なフラグ値が指定されています。

[QMEBADRMID]

無効なリソース・マネージャ識別子が指定されています。

[QMENOTOPEN]

リソース・マネージャが現在オープンされていません。

[QMETRAN]

呼出しがトランザクション・モードで行われていないか、またはTPNOTRANフラグを設定して呼び出したときに、メッセージをキューに登録するトランザクションを開始してエラーが発生しました。この診断は、Oracle Tuxedoリリース7.1以降のキュー・マネージャからは返されません。

[QMEBADMSGID]

無効なメッセージ識別子が指定されています。

[QMESYSTEM]

システム・エラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

[QMEOS]

オペレーティング・システムのエラーが発生しました。

[QMEABORTED]

操作が中断されました。グローバル・トランザクション内で実行されている場合、グローバル・トランザクションがロールバックのみとしてマークされています。それ以外の場合、キュー・マネージャは操作を中断しました。

[QMEPROTO]

トランザクションの状態がアクティブではないときに、キューへの登録が行われました。

[QMEBADQUEUE]

無効または削除されたキューの名前が指定されています。

[QMENOSPACE]

キュー上に領域がないなどリソース不足が原因で、サービスの品質(永続的な記憶域または非永続的な記憶域)が指定されたメッセージがキューに登録されませんでした。次のいずれかのリソース設定を超えると、QMENOSPACEが返されます。(1)キュー・スペースに割り当てられたディスク容量(永続的)、(2)キュー・スペースに割り当てられたメモリー容量(非永続的)、(3)同時にアクティブ状態になるトランザクションの最大数(キュー・スペースで許容される数であることが必要です)、(4)キュー・スペースに一度に入れることができる最大メッセージ数、(5)キューイング・サービス・コンポーネントが処理できる並列アクションの最大数、または(6)キューイング・サービス・コンポーネントを同時に使用できる認証されたユーザーの最大数。

[QMERELEASE]

新機能がサポートされていないバージョンのOracle Tuxedoシステムのキュー・マネージャに対して、メッセージのキューへの登録が試みられました。

[QMESHARE]

指定されたキューのメッセージの登録時に、そのキューが別のアプリケーションによって排他的にオープンされています。Oracle Tuxedoシステム以外のOracle製品ベースのアプリケーションが、キューイング・サービスAPI (QSAPI)を使用して読取りおよび書込みを排他的に行うため、キューをオープンしています。

関連項目:

qmadmin(1)、gp_mktime(3c)、tpacall(3c)、tpalloc(3c)、tpdequeue(3c)、tpinit(3c)、tpsprio(3c)、APPQ_MIB(5)、TMQFORWARD(5)、TMQUEUE(5)

2.76 tpenvelope(3c)

名前

tpenvelope() - 型付きメッセージ・バッファに関連付けられたデジタル署名および暗号化情報にアクセスします。

形式

#include <atmi.h>
int tpenvelope(char *data, long len, int occurrence, TPKEY *outputkey, long *status, char *timestamp, long flags)

説明

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

署名者のデジタル証明書を発行した認証局(CA)で不明のため、デジタル署名が無効です。

TPSEAL_PENDING

対応する公開キーに関連付けられている受信者プリンシパルに対して暗号化(封印)がリクエストされており、このプロセスからメッセージ・バッファが伝送されるときに暗号化されます。

TPSEAL_OK

暗号化エンベロープは有効です。

TPSEAL_TAMPERED_CERT

受信者のデジタル証明書が変更されているため、暗号化エンベロープが無効です。

TPSEAL_REVOKED_CERT

受信者のデジタル証明書が取り消されたため、暗号化エンベロープが無効です。TPSEAL_EXPIRED_CERT

受信者のデジタル証明書の期限が切れたため、暗号化エンベロープが無効です。

TPSEAL_UNKNOWN

受信者のデジタル証明書を発行したCAが不明のため、暗号化エンベロープが無効です。

timestamp出力パラメータには、デジタル署名が生成されたマシンのローカル・クロックに従ったタイムスタンプが含まれています。この値の整合性は、関連付けられているデジタル署名によって保護されています。timestampによって示されるメモリー位置は、YYYYMMDDHHMMSS形式のNULLで終了する署名時間です。ここでYYYYは年、MMは月、DDは日、HHは時間、MMは分、SSは秒を表します。timestampはNULLでもかまいませんが、この場合値は返されません。暗号化(封印)にはタイムスタンプは含まれず、timestampによって示されるメモリー位置は変わりません。

flagsパラメータは、次のいずれかの値に設定できます:

• TPKEY_REMOVE - occurrenceの位置にある項目が削除されます(バッファとの関連付けがなくなります)。この項目に関連する出力パラメータoutputkey、statusおよびtimestampは、項目が削除される前に取り込まれます。その後の項目は1つずつ繰り下がるため、occurrenceの番号が不連続になることはありません
• TPKEY_REMOVEALL - メッセージ・バッファに関連付けられているすべての項目が削除されます。出力パラメータoutputkey、statusおよびtimestampは戻されません。
• TPKEY_VERIFY - メッセージ・バッファに関連付けられているすべてのデジタル署名が再確認されます。再確認後に署名のステータスが変わる場合があります。たとえば、受信プロセスによってメッセージ・バッファが修正された場合、発信者の署名のステータスはTPSIGN_OKからTPSIGN_TAMPERED_MESSAGEに変わります。
• TPKEY_VERIFY - メッセージ・バッファに関連付けられているすべてのデジタル署名が再確認されます。再確認後に署名のステータスが変わる場合があります。たとえば、受信プロセスによってメッセージ・バッファが修正された場合、発信者の署名のステータスはTPSIGN_OKからTPSIGN_TAMPERED_MESSAGEに変わります
• TPKEY_VERIFY - メッセージ・バッファに関連付けられているすべてのデジタル署名が再確認されます。再確認後に署名のステータスが変わる場合があります。たとえば、受信プロセスによってメッセージ・バッファが修正された場合、発信者の署名のステータスはTPSIGN_OKからTPSIGN_TAMPERED_MESSAGEに変わります

戻り値

異常終了すると、この関数は-1を返し、tperrnoを設定してエラー条件を示します。

エラー

[TPEINVAL]

無効な引数が指定されました。たとえば、dataの値がNULLになっているか、またはflagsに割り当てられた値が認識されません。

[TPENOENT]

このoccurrenceは存在しません。

[TPESYSTEM]

エラーが発生しました。詳細は、システム・エラーのログ・ファイルを調べてください。

関連項目:

tpkey_close(3c)、tpkey_getinfo(3c)、tpkey_open(3c)、tpseal(3c)、tpsign(3c)

2.77 tperrordetail(3c)

名前

tperrordetail() - 最後のOracle Tuxedo ATMIシステム・コールで生成されたエラーに関する詳細を取得します。

形式

#include <atmi.h>
int tperrordetail(long flags)

説明

tperrordetail()は、カレント・スレッドで呼び出された最後のOracle Tuxedo ATMIシステム・ルーチンにより発生したエラーに関する追加の詳細情報を返します。tperrordetail()は、数値を返します。その数値は、シンボリック名でも表されます。カレント・スレッドで呼び出された最後のOracle Tuxedo ATMIルーチンによりエラーが発生していない場合、tperrordetail()は、ゼロを返します。したがって、tperrordetail()はエラーが表示された後、つまりtperrnoが設定されたときに呼び出す必要があります。

現在、flagsは将来の用途のために予約されており、0に設定する必要があります。

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

戻り値

異常終了すると、tperrordetail()は-1を返し、tperrnoを設定してエラー条件を示します。

設定されるのは、tperrordetail()が返す各数値のシンボリック名および意味です。表示される順序は任意ではなく、優先順位を示すものではありません。

TPED_CLIENTDISCONNECTED

Joltクライアントは現在接続されていません。tpnotify()呼出しにTPACKフラグが使用され、tpnotify()のターゲットは現在Joltクライアントに接続していません。tpnotify()が異常終了したときは、中間のATMI呼出しを省略して引き続きtperrordetail()を呼び出すと、TPED_CLIENTDISCONNECTEDが返されます。

TPED_DECRYPTION_FAILURE

暗号化されたメッセージを受信するプロセスが、メッセージを復号化できません。このエラーが発生するのは、多くの場合、メッセージを復号化するための秘密キーにプロセスがアクセスできないためです。

このエラーで呼出しが異常終了した場合に、中間のATMI呼出しを省略して引き続きtperrordetail()を呼び出すとTPED_DECRYPTION_FAILUREが返されます。

TPED_DOMAINUNREACHABLE

ドメインに到達できません。つまり、リクエストの作成時に、ローカル・ドメインではサービスできないリクエストを満たすように構成されたドメインに到達できませんでした。リクエストが異常終了した後で、中間ATMI呼出しを省略して引き続きtperrordetail()を呼び出すと、TPED_DOMAINUNREACHABLEが返されます。

次の表は、ドメインに到達できないためにtpcall()、tpgetrply()、またはtprecv()呼出しが異常終了した場合にtperrnoが返す値を示します。引き続きtperrordetail()を呼び出すと、エラーの詳細としてTPED_DOMAINUNREACHABLE

ATMI呼出し	tperrno	エラーの詳細
tpcall	TPESVCERR	TPED_DOMAINUNREACHABLE
tpgetrply	TPESVCERR	TPED_DOMAINUNREACHABLE
tprecv	TPEEVENT TPEV_SVCERR	TPED_DOMAINUNREACHABLE

ノート:

TPED_DOMAINUNREACHABLE機能は、Oracle Tuxedo Domainsにのみ適用されます。Connect OSI TP DomainsやConnect SNA Domainsなど、他のドメインの製品には適用されません。

TPED_INVALID_CERTIFICATE

関連付けられたデジタル証明書が無効なため、デジタル署名付きのメッセージを受信するプロセスがデジタル署名を確認できません。このエラーが発生するのは、デジタル証明書の期限が切れている場合、デジタル証明書を発行しているのが未知の認証局(CA)である場合、デジタル証明書が変更されている場合などです。

このエラーによって呼出しが異常終了されたときに、中間のATMI呼出しを省略して引き続きtperrordetail()を呼び出すと、TPED_INVALID_CERTIFICATEが返されます。

TPED_INVALID_SIGNATURE

署名が無効なため、デジタル署名付きのメッセージを受信するプロセスがデジタル署名を確認できません。このエラーが発生するのは、メッセージが変更されている場合、デジタル署名のタイムスタンプが古すぎる場合、デジタル署名のタイムスタンプが極端に先のものである場合などです。

このエラーによって呼出しが異常終了したときに、中間のATMI呼出しを省略して引き続きtperrordetail()を呼び出すと、TPED_INVALID_SIGNATUREが返されます。

TPED_INVALIDCONTEXT

別のスレッドがコンテキストを終了すると、スレッドがATMI呼出し内でブロックされます。具体的には、別のスレッドがコンテキストを終了するときにATMI呼出し内でブロックされたスレッドは、異常終了とともにATMI呼出しから返され、tperrnoはTPESYSTEMに設定されます。中間のATMI呼出しを省略して引き続きtperrordetail()を呼び出すと、TPED_INVALIDCONTEXTが返されます。

TPED_INVALID_XA_TRANSACTION

トランザクションの開始が試行されましたが、このドメインでNO_XAフラグが設定されました。

TPED_NOCLIENT

クライアントが存在しません。tpnotify()呼出しにTPACKフラグが指定されているのに、tpnotify()のターゲットがありません。tpnotify()が異常終了すると、tperrnoはTPENOENTに設定されます。中間のATMI呼出しを省略して引き続きtperrordetail()呼び出すと、TPED_NOCLIENTが返されます。

TPED_NOUNSOLHANDLER

クライアントに非請求ハンドラ・セットがありません。tpnotify()呼出しにTPACKフラグが指定され、tpnotify()のターゲットがOracle Tuxedo ATMIセッション内にあるのに、ターゲットに非請求の通知ハンドラが設定されていません。tpnotify()が異常終了すると、tperrnoはTPENOENTに設定されます。中間のATMI呼出しを省略して引き続きtperrordetail()を呼び出すと、TPED_NOUNSOLHANDLERが返されます。

TPED_RDMA_MSGQDAEMON

RDMA Msgq_daemonのエラー。RDMAが有効な場合、RDMAデーモン・プロセス(Msgq_daemon)で深刻な問題が検出されると、RDMAを介して送信されたリクエストが異常終了します。tperrnoではTPEOS/TPETIMEが返されます。中間のATMI呼出しを省略して引き続きtperrordetail()を呼び出すと、TPED_RDMA_MSGQDAEMONが返されます。

リクエストの異常終了は次の呼出しによって検出されます。

• tpcall/tpacall/tpgetrply/tpadmcall/tpforward
• tpinit/tpappthrinit
• tpbegin/tpcommit/tpscmt/tpabort/tpsuspend/tpresume
• tpconnect/tpsend/tprecv/tpdiscon
• tpbroadcast/tpnotify
• tpenqueue/tpdequeue
• tpsubscribe/tpunsubscribe/tppost

TPED_RDMA_INVALIDQUEUE

無効なRDMAキュー。RDMAが有効な場合、Msgq_daemon共有メモリーによって内部エラーが発生することがあります。リクエストが異常終了した後で、tperrnoではTPEOSが返されます。中間ATMI呼出しを省略して引き続きtperrordetail()を呼び出すとTPED_RDMA_INVALIDQUEUEが返されます。この異常終了を検出できる呼出しは、「TPED_RDMA_MSGQDAEMON」を参照してください。

TPED_RDMA_NOMEMORY

RDMAリクエストを処理するために十分な共有メモリーがありません。RDMAが有効な場合に十分な共有メモリーなしでMsgq_daemonが開始すると、内部エラーが発生することがあります。tperrnoによってTPEOSが返されます。中間のATMI呼出しを省略して引き続きtperrordetail()を呼び出すと、TPED_RDMA_NOMEMORYが返されます。この異常終了を検出できる呼出しは、「TPED_RDMA_MSGQDAEMON」を参照してください。

TPED_SVCTIMEOUT

サーバーは、サービスのタイムアウトにより終了しました。サービスのタイムアウトは、UBBCONFIG中のSVCTIMEOUT値によって制御されます。T_SERVERおよびT_SERVICEクラスのTA_SVCTIMEOUTはTM_MIB (5)に記載されています。このエラーよって呼出しが異常終了したときは、中間のATMI呼出しを省略して引き続きtperrordetail()を呼び出すと、TPED_SVCTIMEOUTが返されます。

TPED_TERM

ワークステーション・クライアントが、アプリケーションに接続していません。このエラーによって呼出しが異常終了したときは、中間のATMI呼出しを省略して引き続きtperrordetail()を呼び出すと、TPED_TERMが返されます。

エラー

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

TPEINVAL

flagsはゼロに設定されていません

関連項目:

「C言語アプリケーション・トランザクション・モニター・インタフェースの紹介」、tpstrerrordetail(3c)、tperrno(5)

2.78 tpexport(3c)

名前

tpexport() - 型付きメッセージ・バッファを、デジタル署名と暗号化エンベロープを含むエクスポート可能なマシン独立型の文字列表現に変換します。

形式

#include <atmi.h>
int tpexport(char *ibuf, long ilen, char *ostr, long *olen,
long flags)

説明

tpexport()は、型付きメッセージ・バッファを外部化された表現に変換します。外部化された表現とは、通常は伝送直前にメッセージ・バッファに追加されるOracle Tuxedo ATMIヘッダー情報を含まないメッセージ・バッファです。

外部化された表現は、任意の通信メカニズムを介して、プロセス、マシン、Oracle Tuxedo ATMIアプリケーション間で伝送することができます。恒久的なストレージにアーカイブでき、システムの停止および再起動後も有効です。

外部化される表現には、次のものがあります。

• ibufに関連付けられているすべてのデジタル署名。これらの署名は、後で、バッファがインポートされたときに確認されます。
• ibufに関連付けられているすべての暗号化エンベロープ。バッファの内容は、暗号化によって保護されます。復号化のための有効な秘密キーにアクセスできる指定された受信者だけが、後でバッファをインポートできます。

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]

無効な引数が指定されました。たとえば、ibufの値がNULLであるか、またはflagsの値が正しく設定されていません。

[TPEPERM]

パーミッション異常終了。暗号サービスのプロバイダが、デジタル署名の生成に必要な秘密キーにアクセスできませんでした。

[TPESYSTEM]

エラーが発生しました。詳細は、システム・エラーのログ・ファイルを調べてください。

[TPELIMIT]

十分な出力ストレージがありませんでした。*olenを必要な容量に設定します。

関連項目:

tpimport(3c)

2.79 tpfml32toxml(3c)

名前

tpfml32toxml() - FML32バッファをXMLデータに変換します

形式

#include <fml.h>
int tpfml32toxml (FBFR32 *fml32bufp, char *vfile, char *rtag, char **xmlbufp, long flags)

説明

この関数は、FML32バッファをXMLデータに変換するために使用します。次の引数を使用できます。

fml32bufp

この引数は、FML32型付き入力バッファを指すポインタです。

vfile

この引数は、現時点ではFML32からXMLへの変換には使用されません。XML出力の検証機能がXercesでサポートされている場合、XML出力を検証するために使用するXMLスキーマ・ファイルの完全修飾パス名用に予約されています。

rtag

この引数は、出力XML文書の入力XMLルート要素名を指すポインタです。変換中に指定されたルート要素名は、そのルート要素名に追加されている省略可能なType属性で、XMLルート・タグとして使用するために識別および保存されます。入力ルート名を指定していない場合は、デフォルトの出力XMLルート・タグ<FML32>が使用されます。

xmlbufp

この引数は、FML32フィールド化バッファの記述用にあらかじめ定義されている形式で出力XML型付きバッファを指すポインタです。

flag

この引数は、現時点ではFML32からXMLへの変換には使用されず、0に設定する必要があります。

戻り値

正常終了の場合、tpfml32toxml()は0を返します。この関数は、エラー発生時に-1を返し、tperrnoを設定してエラー条件を示します。

エラー

失敗すると、tpfml32toxml()はtperrnoを次のいずれかの値に設定します。

[TPEINVAL]

fml32bufpまたはxmlbufpのどちらかが有効な型付きバッファではありません。

[TPESYSTEM]

Tuxedoシステムのエラーが発生しました。このエラーの正確な性質はuserlog(3)に書き込まれます。これは、XMLへの変換を実行できなかった時期も示します。そのインスタンスでは、エラーの詳細な情報がuserlogに追加されます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。失敗したシステム・コールを示す数値がUunixerrに入っています。

関連項目:

tpxmltofml32(3c)、tpfml32toxml(3c)、tpfmltoxml(3c)

2.80 tpfmltoxml(3c)

名前

tpfmltoxml() - FMLバッファをXMLデータに変換します

形式

#include <fml.h>
int tpfmltoxml (FBFR *fmlbufp, char *vfile, char *rtag, char **xmlbufp, long flags)

説明

この関数は、FMLバッファをXMLデータに変換するために使用します。次の引数を使用できます。

fmlbufp

この引数は、FML型付き入力バッファを指すポインタです。

vfile

この引数は、現時点ではFMLからXMLへの変換には使用されません。XML出力の検証機能がXercesでサポートされている場合、XML出力を検証するために使用するXMLスキーマ・ファイルの完全修飾パス名用に予約されています。

rtag

この引数は、出力XML文書の入力XMLルート要素名を指すポインタです。変換中に指定されたルート要素名は、そのルート要素名に追加されている省略可能なType属性で、XMLルート・タグとして使用するために識別および保存されます。入力ルート名を指定していない場合は、デフォルトの出力XMLルート・タグ<FML>が使用されます。

xmlbufp

この引数は、FMLフィールド化バッファの記述用にあらかじめ定義されている形式で出力XML型付きバッファを指すポインタです。

flag

この引数は、現時点ではFMLからXMLへの変換には使用されず、0に設定する必要があります。

戻り値

成功した場合、tpfmltoxml()は0を返します。この関数は、エラー発生時に-1を返し、tperrnoを設定してエラー条件を示します。

エラー

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

[TPEINVAL]

fmlbufpまたはxmlbufpのどちらかが有効な型付きバッファではありません。

[TPESYSTEM]

Tuxedoシステムのエラーが発生しました。このエラーの正確な性質はuserlog(3)に書き込まれます。これは、XMLへの変換を実行できなかった時期も示します。そのインスタンスでは、エラーの詳細な情報がuserlogに追加されます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。失敗したシステム・コールを示す数値がUunixerrに入っています。

関連項目:

tpxmltofml32(3c)、tpfml32toxml(3c)、tpxmltofml(3c)

2.81 tpforward(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を起動するサービス・セッション・ロールを示します。

セッション・ロール	転送元サービス	転送先サービス
BEGIN	LIBTUX_CAT:6835: ERROR'がULOGに出力されます。セッションは開始しません。	アフィニティ・サーバーとアフィニティ・スコープは転送先サービスによって決定されます。アフィニティ・クライアントは、転送元サービスを呼び出すクライアントです。
END	LIBTUX_CAT:6836: ERROR'がULOGに出力されます。アフィニティ・クライアントとサーバー間のセッションは終了しません。	転送元サービスがセッションに関与していないかぎり、セッションは終了します。
NONE	セッションが伝播されます。	セッションが伝播されます。

詳細は、「Oracle Tuxedo ATMIのアーキテクチャ」の「クライアント/サーバー・アフィニティとは」を参照してください。

関連項目:

tpalloc(3c)、tpconnect(3c)、tpreturn(3c)、tpservice(3c)、tpstrerrordetail(3c)

2.82 tpfree(3c)

名前

tpfree() - 型付きバッファを解放するルーチン。

形式

#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)

2.83 tpgblktime(3c)

名前

tpgblktime() - 以前に設定された、1秒または1ミリ秒当たりのブロック時間値を取得します

形式

#include <atmi.h>
int tpgblktime(long flags)

説明

tpgblktime()は、TPBLK_MILLISECONDフラグに基づいて、以前に設定された1秒当たりまたは1ミリ秒当たりのブロック時間値を取得します。tpgblktime()にブロック時間フラグ値を指定した場合、それに一致するflag値が設定されていないと戻り値0が返されます。ブロック時間フラグ値として0未満の値を指定すると、エラーが発生します。

次に、有効なflagsの一覧を示します:

TPBLK_MILLISECOND

このフラグは、戻りブロック時間値をミリ秒単位で設定します。SCANUNITの単位が、TUXCONFIGでミリ秒になっている場合、TPBLK_MILLISECONDフラグなしでtpgblktimeを呼び出すとエラーTPEINVALが返されます。

TPBLK_SECOND

このフラグは、戻りブロック時間値を秒単位で設定します。これはデフォルト動作です。

TPBLK_NEXT

このフラグは、あらかじめ設定されているtpsblktime(TPBLK_NEXT) 呼出しのブロック時間値を返します。

TPBLK_ALL

このフラグは、あらかじめ設定されているtpsblktime(TPBLK_ALL) 呼出しのブロック時間値を返します。

0

このフラグは、次のブロックしているATMIに設定されている適用可能なブロック時間値を返します。これは、前のtpsblktime()呼出しでTPBLK_NEXT、TPBLK_ALLの各フラグのブロック時間値、またはシステム全体のデフォルト・ブロック時間値が指定されていないためです。

ノート:

ワークステーション・クライアントがtpgblktime() 0を呼び出した場合は、システム全体のデフォルト・ブロック時間値を返すことはできません。この場合は、値0が返されます。

戻り値

成功すると、tpgblktime()は、対応するフラグ値で現在有効なブロッキング時間値を示す正数を戻します。戻り値0は、オーバーライドが有効なブロッキング時間値が現在ないことを示します。

この関数は、エラー発生時に-1を返し、tperrnoを設定してエラー条件を示します。エラーが既存のトランザクションに影響を及ぼすことはありません。

エラー

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

[TPEINVAL]

無効な引数が指定されました。たとえば、flags値が負数か、複数のブロック時間フラグ値(TPBLK_NEXT、TPBLK_ALL、TPBLK_NEXT |TPBLK_MILLISECOND、TPBLK_NEXT | TPBLK_SECOND、TPBLK_ALL | TPBLK_MILLISECOND、TPBLK_ALL | TPBLK_SECONDまたは0)が指定されました。

UBBCONFIGのSCANUNIT	tpsblktimeのフラグ	結果
秒単位	TPBLK_SECOND	成功
秒単位	TPBLK_MILLISECOND	成功
ミリ秒単位	TPBLK_SECOND	失敗
ミリ秒単位	TPBLK_MILLISECOND	成功

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

関連項目:

tpcall(3c)、tpcommit(3c)、tprecv(3c)、tpsblktime(3c)、UBBCONFIG(5)

2.84 tpgetcache(3c)

名前

tpgetcache - 構成に従ってOracle Tuxedoキャッシュ・ハンドルを取得します

形式

#include "atmi.h"
TCACHE* tpgetcache(const char* name);

説明

tpgetcache(3c)は、取得するOracle Tuxedoキャッシュの名前を示すOracle Tuxedoキャッシュ名に従ってOracle Tuxedoキャッシュ・ハンドルを取得します。名前の長さは78文字以内にする必要があります。tpgetcache(3c)はスレッド・レベルのAPIです。返されるハンドルTCACHEは、同じスレッド内でのみ使用できます。

戻り値

成功すると、tpgetcache(3c)は内部構造体であるハンドル型TCACHEを返します。

失敗すると、tpgetcache()はNULLを返し、tperrnoを設定してエラー条件を示します。呼出しが失敗してtperrnoに特定の値が設定された場合は、続けて、中間のATMI呼出しを省略してtperrordetail(3c)を呼び出すと、エラーに関する詳細な情報が提供されます。詳細は、「tperrordetail(3c)」リファレンス・ページを参照してください。

エラー

[TPEINVAL]

無効な引数(たとえば、confにNULL)が指定されました。

[TPENOENT]

リクエストされたキャッシュは存在しません。

[TPETIME]

このエラー・コードは、タイムアウトが発生したことを示します。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な内容はULOGに追加されます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。

[TPESVCFAIL]

Oracle Tuxedoキャッシュ・サーバーはエラーを満たします。tpurcodeには正確なエラー値が含まれます。tpurcodeの想定される値を次に示します。

• TDC_ERR_CACHE_NOTEXIST

  このエラー・コードは、リクエストされたOracle Tuxedoキャッシュが存在しないことを示します。

• TDC_ERR_CACHE_UNAVAIL

  このエラー・コードは、リクエストされたOracle Tuxedoキャッシュが使用不可であることを示します。

2.85 tpgetadmkey(3c)

名前

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)

Oracle Tuxedoアプリケーションの設定

Oracle Tuxedoアプリケーション実行時の管理

2.86 tpgetcallinfo(3c)

名前

tpgetcallinfo() - 呼出しパス・メッセージ・モニタリング属性を受信するルーチン。

形式

int tpgetcallinfo(const char *msg, FBFR32 **obuf, long flags)

説明

tpgetcallinfo()は、呼出しパス・モニタリングにのみ使用されます。次のパラメータをサポートしています。

• msg

  測定に使用される型付きバッファ。

• obuf

  フィールドを使うために使用されるFML32バッファ。

• flags

  将来の使用のために予約されています。

tpgetcallinfo()では、呼出しパス・モニタリングを有効にした場合、メッセージ・モニタリング属性が取得されます。

tpgetcallinfo()は、幅広い機能を実行するために様々なシナリオで使用できます。通常、次のように使用します。

アプリケーション・サーバーは、要求されたメッセージのモニタリング属性を確認するためにtpgetcallinfo()を呼び出します。これにより、次の情報を提供できます。

• リクエストの相関識別子。呼出し側によって生成されます。
• モニタリング・イニシエータを使用してコールを開始すると、タイム・スタンプが開始されます。
• モニターされた要求の、コール・パス・ツリー上の最後の終了タイム・スタンプ。通常、処理要求メッセージのサービスの待ち時間を測定するために使用されます。
• Tuxedoワークステーション・クライアント側からのリクエストの場合は、ワークステーション・クライアント・アドレス。
• リクエストがWebサービス(GWWS)のゲートウェイからカスタムHTTPまたはSOAPヘッダー・モードが有効な状態で送信された場合のカスタムHTTPまたはSOAPヘッダー
• モニタリング・イニシエータは、モニターされた呼出しの終了時間を取得するためにtpgetcallinfo()を呼び出します。

ノート:

tpgetcallinfo()は、応答の受信後、いつでもコールして応答バッファを得ることができます。これは、tpacall/tpgetrplyの場合に特に有用です

次の表に、FMLモニター・メトリック・フィールド名を示します。

フィールド名	タイプ	説明	サービス	モニタリング・イニシエータ
TA_MONCORRID	string	モニターされる呼出しの相関ID。重要な呼出しパス・モニタリング・メトリックです。	Y	Y
TA_MONLASTTIMESEC	long	呼出しパス・ツリーにおける最後の停止のタイムスタンプ。単位は秒です。	Y	Y
TA_MONLASTTIMEUSEC	long	呼出しパス・ツリーにおける最後の停止のタイムスタンプ。単位はマイクロ秒です。	Y	Y
TA_MONSTARTTTIMESEC	long	モニタリング・イニシエータが呼出しを開始したときのタイムスタンプ。単位は秒です。	Y	Y
TA_MONSTARTTIMEUSEC	long	モニタリング・イニシエータが呼出しを開始したときのタイムスタンプ。単位はマイクロ秒です。	Y	Y
TA_MONCLTADDR	string	ワークステーション・クライアントのアドレス	Y	N
TA_MONTOTALTIME	long	モニター対象の呼出しに対して使用されるエンド・ツー・エンド時間。単位は、ミリ秒です。	N	Y
TA_ECID	string	実行コンテキストID	Y	Y
TA_MSGTAG	string	Tuxedoメッセージ・タグ	Y	Y

次の表に、FMLカスタムHTTPヘッダー名を示します。

フィールド名	タイプ	説明
TA_HTTP_HEADER_NAME	string	HTTPヘッダー名部分
TA_HTTP_HEADER_VALUE	string	HTTPヘッダー値部分
TA_SOAP_HEADER	fml32	発信メッセージに追加されるSOAPヘッダー。このデータは、通常のSALTマッピング・ルールに従ってXMLにマップされます。詳細は、「Oracle SALTデータ型のマッピングとメッセージの変換」を参照してください。

戻り値

モニタリング属性を含むFML32バッファの取得に成功すると、0が返されます。

エラーが発生すると、tpgetcallinfo()は -1を返し、tperrnoを設定してエラー条件を示します。

エラー

エラーが発生すると、tpgetcallinfo()はtperrnoを次のいずれかの値に設定します。

[TPEINVAL]

無効な引数が指定されました(たとえば、msgがNULLである場合、あるいはobufが無効なFML32バッファである場合など)

[TPESYSTEM]

メッセージ入力にモニタリング属性が含まれていません。これは、メッセージに対して呼出しパス・モニタリングをオンにしていないためです。

[TPEOS]

オペレーティング・システムのエラーが発生しました。

使用例

サービス側tpgetcallinfoの例は、次のとおりです。

#include <stdio.h>
#include <atmi.h>
#include <userlog.h>
#include <fml32.h>
#include <tpadm.h>
#if defined(__STDC__) || defined(__cplusplus)
tpsvrinit(int argc, char *argv[])
#else
tpsvrinit(argc, argv)
int argc;
char **argv;
#endif
{

       /* tpsvrinit logic */
#ifdef __cplusplus
extern "C"
#endif
void
#if defined(__STDC__) || defined(__cplusplus)
APPSVC(TPSVCINFO *rqst)
#else
TOUPPER(rqst)
TPSVCINFO *rqst;
#endif
{
       FBFR32 *metainfo;
       int len = 0;
       /* Allocate the metainfo space */
       metainfo = tpalloc("FML32", NULL, 1024);
       if (metainfo == NULL ) {
              userlog("Memory allocation failed");
              tpreturn(TPFAIE, 0, 0, 0);
       }
       /* Get the monitoring attributes*/
       if ( tpgetcallinfo(rqst->data, &metainfo, 0) == 0 )
       {
              char *corrid;
char *msgtag;
              long laststopsec, starttimesec;
              if ((corrid = Ffind32(metainfo, TA_MONCORRID, 0, &len) ) {
                     userlog("Correlation ID = %s", corrid);
              }
if ((msgtag = Ffind32(metainfo, TA_MSGTAG, 0, &len) ) {
userlog("Tuxedo Message Tag = %s", corrid);
}
              len = sizeof(starttimesec);
              if (( Fget32(metainfo, TA_MONSTARTTIMESEC, &starttimesec, &len) == 0) {
                     userlog("Message beginning time = %ld", starttimesec);
              }
}
              len = sizeof(lasttimesec);
       if (( Fget32(metainfo, TA_MONLASTTIMESEC, &lasttimesec, &len) == 0) {
              userlog("Message entering my queue time = %ld", lasttimesec);
       }
       }
       tpfree(metainfo);
       /* rest of service processment */
       ......
}
The following is an example of retrieving custom HTTP headers attached to a request received by a Tuxedo service.
...
void
#if defined(__STDC__) || defined(__cplusplus)
APPSVC(TPSVCINFO *rqst)
#else
APPSVC(rqst)
TPSVCINFO *rqst;
#endif
{
FBFR32 *metainfo;
int len = 0;
/* Allocate the metainfo space */
metainfo = tpalloc("FML32", NULL, 1024);
if (metainfo == NULL ) {
userlog("Memory allocation failed");
tpreturn(TPFAIL, 0, 0, 0);
}
/* Get custom headers */
if ( tpgetcallinfo(rqst->data, &metainfo, 0) == 0 )
{
int ret;
FLDID32 fieldID = TA_HTTP_HEADER_NAME;
FLDOCC32 fieldOCC = 0;
ret = Fnext32(metainfo, &fieldID, &fieldOCC, NULL, NULL);
if (ret == 1) {
do {
char fldName[1024];
char fldValue[1024];
FLDLEN32 nameLen, valueLen;
nameLen = sizeof(fldName);
valueLen = sizeof(fldValue);
/* fieldOCC contains index of name/value pair */
/* check return values and ENOSPACE */
Fget32(metainfo, TA_HTTP_HEADER_NAME,
fieldOCC, (char *) &fldName, &nameLen);
/* always come in pairs */
Fget32(metainfo, TA_HTTP_HEADER_VALUE,
fieldOCC, (char *) &fldValue, &valueLen);
userlog("retrieved: %s: %s", fldName, fldValue);
/* move to next name-value pair */
} while (Fnext32(metainfo, &fieldID, &fieldOCC, NULL, NULL);
}
tpfree(metainfo);
/* rest of service processing */
...
}

Tuxedoサービスが受信したリクエストに付加されたカスタムHTTPヘッダーを検索する例は次のとおりです。

void
#if defined(__STDC__) || defined(__cplusplus)
APPSVC(TPSVCINFO *rqst)
#else
APPSVC(rqst)
TPSVCINFO *rqst;
#endif
{
  FBFR32 *metainfo;
  int len = 0;
  /* Allocate the metainfo space */
  metainfo = tpalloc("FML32", NULL, 1024);
  if (metainfo == NULL ) {
    userlog("Memory allocation failed");
    tpreturn(TPFAIL, 0, 0, 0);
  }
  /* Get custom headers */
  if ( tpgetcallinfo(rqst->data, &metainfo, 0) == 0 ) {
    int ret;
    FLDID32 fieldID = TA_HTTP_HEADER_NAME;
    FLDOCC32 fieldOCC = 0;
    ret = Fnext32(metainfo, &fieldID, &fieldOCC, NULL, NULL);
    if (ret == 1) {
      do {
        char fldName[1024];
        char fldValue[1024];
        FLDLEN32 nameLen, valueLen;
        nameLen = sizeof(fldName);
        valueLen = sizeof(fldValue);
        /* fieldOCC contains index of name/value pair */
        /* check return values and ENOSPACE */
        Fget32(metainfo, TA_HTTP_HEADER_NAME,
             fieldOCC, (char *) &fldName, &nameLen);
        /* always come in pairs */
        Fget32(metainfo, TA_HTTP_HEADER_VALUE,
             fieldOCC, (char *) &fldValue, &valueLen);
        userlog("retrieved: %s: %s", fldName, fldValue);
        /* move to next name-value pair */
      } while (Fnext32(metainfo, &fieldID, &fieldOCC, NULL, NULL);
    }
    tpfree(metainfo);
    /* rest of service processing */
    ...
  }
}

関連項目:

tpsetcallinfo(3c)

2.87 tpgetctxt(3c)

名前

tpgetctxt() - 現在のアプリケーションの関連付けのコンテキスト識別子を取得します。

形式

#include <atmi.h>
int tpgetctxt(TPCONTEXT_T *context, long flags)

説明

tpgetctxt()は、現在のアプリケーション・コンテキストを表す識別子を取得し、contextに入れます。この関数は、マルチスレッド環境ではスレッド単位で、非スレッド環境ではプロセス単位で動作します。

一般にスレッドは、次の動作を行います:

1. tpinit()を呼び出します
2. tpgetctxt()を呼び出します
3. contextの値を次のように処理します:
   • マルチスレッドのアプリケーションの場合、同じプロセス内の別のスレッドにcontextの値を渡し、そのスレッドがtpsetctxt()を呼び出せるようにします。
   • シングルスレッドまたはマルチスレッド・アプリケーションの場合 - 指定されたコンテキストに後から切り替えられるように、このコンテキスト識別子を自身で保存します。

2番目の引数flagsは現在使用されておらず、0に設定する必要があります。

tpgetctxt()は、マルチコンテキストのアプリケーションだけでなく、シングル・コンテキストのアプリケーションでも呼び出すことができます。

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

戻り値

正常終了時には、tpgetctxt()は負数でない値を返します。コンテキストは、以下のいずれかの形式で表される現在のコンテキストIDに設定されます。

• 0よりも大きいコンテキスト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]

無効な引数が指定されました。たとえば、contextの値がNULLであるか、またはflagsの値が0以外です。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質は、ログ・ファイルに書き込まれます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。

関連項目:

「C言語アプリケーション・トランザクション・モニター・インタフェースの紹介」、tpsetctxt(3c)、tpterm(3c)

2.88 tpgetlev(3c)

名前

tpgetlev() - トランザクション・モードかどうかチェックするルーチン。

形式

#include <atmi.h>
int tpgetlev()

説明

tpgetlev()は現在のトランザクション・レベルを呼出し側に返します。現時点では、定義されているレベルは0と1だけです。

マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドは、tpgetlev()の呼出しを発行できません。

戻り値

正常終了時tpgetlev()は、トランザクション・モードではないということを示す0、またはトランザクション・モードだということを示す1のどちらかを返します。

異常終了すると、tpgetlev()は -1を返し、tperrnoを設定してエラー条件を示します。

エラー

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

[TPEPROTO]

tpgetlev()が不正に呼び出されました。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。

注意事項

Oracle Tuxedo ATMIシステムのトランザクションを記述するためにtpbegin()、tpcommit()、およびtpabort()を使用する場合、XAインタフェースに準拠した(呼出し側に妥当にリンクされている)リソース・マネージャが行う作業のみがトランザクションのプロパティを備えていることを記憶しておくことが重要です。トランザクションにおいて実行される他のすべての操作は、tpcommit()あるいはtpabort()のいずれにも影響されません。そのリソース・マネージャが行った処理がOracle Tuxedo ATMIシステムのトランザクションの一部となるよう、XAインタフェースを満たすリソース・マネージャをサーバーにリンクする方法については、「buildserver(1)」を参照してください。

関連項目:

tpabort(3c)、tpbegin(3c)、tpcommit(3c)、tpscmt(3c)

2.89 tpgetmbenc(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型付きバッファは無効です。

引数flagsは現在使用されておらず、0に設定する必要があります。

戻り値

正常終了の場合、tpgetmbenc()は値0を返します。エラーの場合には-1を返し、次に説明するように各関数にtperrnoを設定します。この関数は、次の原因により異常終了する可能性があります。

[TPEINVAL]

引数enc_nameまたはbufpがNULLです。

[TPEPROTO]

このエラーは、bufpがエンコーディング名を提供できない場合に発生します。

[TPESYSTEM]

Tuxedoシステムのエラーが発生しました。(bufpが有効なTuxedoバッファに対応していない場合など)。

関連項目:

tpalloc(3c)、tpconvmb(3c)、tpsetmbenc(3c)

2.90 tpgetrepos(3c)

名前

tpgetrepos() - Tuxedoサービス・メタデータ・リポジトリ・ファイルからサービス・パラメータ情報を取得します。

形式

#include <atmi.h>
int tpgetrepos(char *reposfile, FBFR32* idata, FBFR32** odata)

説明

tpgetrepos()は、TMMETADATA(5)によって提供される.TMMETAREPOSサービスに、代替リポジトリ・アクセス・インタフェースを提供します。これは、Tuxedoサービス・メタデータ・リポジトリ・ファイルからサービス・パラメータを取得します。tpgetrepos()を使用するには、メタデータ・リポジトリ・ファイルが、リクエスト元のネイティブ・クライアントまたはサーバーに存在している必要があります。これにより、TMMETADATA(5) を開始していない場合でも、リポジトリ情報へのアクセスが可能になります。

tpgetrepos()では、次のパラメータを使用できます:

reposfile

Tuxedoメタデータ・リポジトリがある現在のマシンでアクセス可能なファイルのパス名を指定します。呼出し側は、このファイルの読取りパーミッションを持っている必要があります。

idata

取得するサービス・パラメータ情報の種類を指定し、FML32バッファを指します。

odata

出力に対して、取得するサービス・パラメータ情報とオペレーションのステータスを格納したFML32バッファを指します。

「METAREPOS(5)」 では、tpgetrepos() usesが使用するFML32バッファ形式について説明します。これは、Tuxedo MIBで使用する形式と同じです。

戻り値

tpgetrepos()は、成功した場合に0を返します。異常終了した場合は、tperrnoを設定し、-1を返します。ほとんどの異常終了では、Tuxedo MIBの場合と同様に、*odataのTA_ERRORフィールドに特定のエラーに関する情報が格納されています。

エラー

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

ノート:

TPEINVALの場合を除き、odataは、エラー条件についてさらに詳しい情報が得られるように、サービス・エントリごとにTA_ERROR、TA_STATUSを含める形で変更されます。

[TPEINVAL]

無効な引数が指定されました。reposfileの値が無効であるか、idataまたはodataはFML32型付きバッファへのポインタではありません。

[TPEMIB]

MIBと同種のリクエストが失敗しました。odataが更新され、MIB(5)で説明するエラーの原因を示すFML32のフィールドが設定され、呼出し側に返されました。

[TPEPROTO]

tpgetrepos()が不正に呼び出されました。指定したreposfileファイル引数は、有効なリポジトリ・ファイルではありません。

[TPEOS]

オペレーティング・システムのエラーが発生しました。失敗したシステム・コールを示す数値がUunixerrに入っています。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。このエラーの正確な性質はuserlog()で報告されます。

移植性

このインタフェースは、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サービス・メタデータ・リポジトリの管理」

2.91 tpgetrply(3c)

名前

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も、それが指すバッファも変更されていません。

*dataまたはlenがNULLであると、エラーになります。

マルチスレッド・プログラムの各コンテキストでは、次のことが当てはまります。

• 特定のハンドルに対してtpgetrply(TPGETANY)とtpgetrply()の呼出しを同時に発行することはできません。
• tpgetrply(TPGETANY)を同時に複数呼び出すこともできません。

これらの制限のどちらかに違反するtpgetrply()呼出しを発行した場合は、-1が返され、tperrnoはTPEPROTOに設定されます。

次のような呼出しの発行は受け付けられます。

• 異なるハンドルに対するtpgetrply()は、同時に呼び出すことができます。

• シングル・コンテキスト内でtpgetrply (TPGETANY)を呼び出すときに、同時に別のコンテキストでtpgetrply()を呼び出すことは、TPGETANYの指定の有無にかかわらず可能です。

次に、有効なflagsの一覧を示します:

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]

cdが無効な記述子を指しています。

[TPETIME]

このエラー・コードは、タイムアウトが発生したか、または現在のトランザクションがすでに「ロールバックのみ」とマークされているにもかかわらずtpgetrply()が試行されたことを示します。呼出し側がトランザクション・モードの場合、トランザクションはすでにロールバックのみであるか、またはトランザクション・タイムアウトが発生しました。このトランザクションは、「中断のみ」とマークされます。呼出し側がトランザクション・モードでない場合、ブロッキング・タイムアウトが発生しています。(ブロッキング・タイムアウトは、TPNOBLOCKまたはTPNOTIMEが指定されている場合は発生しません。)いずれの場合でも、*data、その内容、*lenはいずれも変更されません。*cdは、呼出し側がトランザクション・モードでなければ(そして、TPGETANYが設定されていない場合)そのまま有効です。

トランザクション・タイムアウトが発生した場合、トランザクションが中断されないかぎり、新しいリクエストの送信や未処理の応答の受信はできず、TPETIMEが発生します。その例外とは、ブロックされず、応答を期待せず、かつ呼出し側のトランザクションのかわりに送信されない(つまり、TPNOTRAN、TPNOBLOCKおよびTPNOREPLYを設定してtpacall()を呼び出した場合の)リクエストです。

サービスがトランザクションの内部で失敗した場合、そのトランザクションはTX_ROLLBACK_ONLY状態に置かれます。ほとんどの場合、この状態はタイムアウトと同じものとして扱われます。このトランザクションの以降のATMI呼出しは、すべてTPETIMEで異常終了します(前の段落で説明した例外を除く)。

[TPESVCFAIL]

呼出し側の応答を送信するサービス・ルーチンが、TPFAILでtpreturn()を呼び出しました。これは、アプリケーション・レベルの障害です。サービスの応答の内容(送信された場合)は、*dataが示すバッファに入ります。呼出し側のトランザクションのかわりにサービス・リクエストが発行された場合、トランザクションは中断のみとしてマークされます。トランザクションがタイムアウトしたかどうかにかかわりなく、トランザクションが中断される前の通信で有効であるのは、TPNOREPLY、TPNOTRANおよびTPNOBLOCKを設定したtpacall()の呼出しのみです。

[TPESVCERR]

サービス・ルーチンが、tpreturn()またはtpforward()でエラーを検出しました(たとえば、誤った引数が渡された場合など)。このエラーが生じた場合には、応答データは返されません(つまり、*dataとその内容も、*lenも変更されません)。呼出し側のトランザクションのかわりにサービス・リクエストが発行された場合、トランザクションは中断のみとしてマークされます。トランザクションがタイムアウトしたかどうかに関わりなく、トランザクションが中断される前の通信で有効であるのは、TPNOREPLY、TPNOTRANおよびTPNOBLOCKを設定したtpacall()の呼出しのみです。UBBCONFIGファイル内のSVCTIMEOUTまたはTM_MIB内のTA_SVCTIMEOUTが0でない場合にサービスのタイムアウトが発生すると、TPESVCERRが戻されます。

[TPEBLOCK]

ブロッキング状態のため、TPNOBLOCKが指定されました。*cdはそのまま有効です。

[TPGOTSIG]

シグナルを受け取りましたが、TPSIGRSTRTが指定されていません。

[TPEPROTO]

tpgetrply()が不正に呼び出されました。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。リモート・ロケーションにあるメッセージ・キューがいっぱいの場合には、TPEOSが返される場合もあります。

関連項目:

tpacall(3c)、tpalloc(3c)、tpcancel(3c)、tperrordetail(3c)、tprealloc(3c)、tpreturn(3c)、tpstrerrordetail(3c)、tptypes(3c)

2.92 tpgprio(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]

tpgprio()が呼び出されましたが、(tpcall()またはtpacall()を介して)リクエストが送信されなかったか、リクエストが送られなかった会話型サービス内から呼び出されました。

[TPEPROTO]

tpgprio()が不正に呼び出されました。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。

関連項目:

tpacall(3c)、tpcall(3c)、tpdequeue(3c)、tpenqueue(3c)、tpservice(3c)、tpsprio(3c)

2.93 tpimport(3c)

名前

tpimport() - メッセージ・バッファの外部化された表現を型付きメッセージ・バッファに変換します。

形式

#include <atmi.h>
int tpimport(char *istr, long ilen, char **obuf, long *olen,
long flags)

説明

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]

無効な引数が指定されました。たとえば、istrの値がNULLであるか、またはflagsパラメータが正しく設定されていません。

[TPEPERM]

パーミッション異常終了。暗号化サービス・プロバイダが、復号化に必要な秘密キーにアクセスできませんでした。

[TPEPROTO]

プロトコルの異常終了が発生しました。異常終了には、istrのデータ形式が無効な場合や、デジタル署名が確認できなかった場合があります。

[TPESYSTEM]

エラーが発生しました。詳細は、システム・エラーのログ・ファイルを調べてください。

関連項目:

tpenvelope(3c)、tpexport(3c)

2.94 tpinit(3c)

名前

tpinit() - アプリケーションに参加します。

形式

#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に設定すると、スレッドを使用しないアプリケーションでマルチスレッド処理が無効になります。

TPINFO構造体の説明

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()実行時にクライアントと関連付けられ、ブロードキャスト通知と管理統計情報の検索に使用されます。これらは、30として定義されているMAXTIDENTの文字数を超えてはなりません。passwdは、アプリケーション・パスワードに対する検証に使用される非暗号化形式のアプリケーション・パスワードです。passwdは30文字に制限されます。grpnameは、クライアントをリソース・マネージャ・グループ名と関連付けるときに使用します。grpnameが長さ0の文字列として設定されている場合、クライアントはリソース・マネージャに関連付けられず、デフォルトのクライアント・グループに属します。ワークステーション・クライアントの場合、grpnameの値にはNULL文字列(長さが0の文字列)を指定します。grpnameはACL GROUPSには関連しないことに注意してください。

シングル・コンテキスト・モードとマルチコンテキスト・モード

tpinit()には、シングル・コンテキスト・モードとマルチコンテキスト・モードの2つの動作モードがあります。シングル・コンテキスト・モードでは、プロセスは一度に1つのアプリケーションに参加できます。このアプリケーションには、複数のアプリケーション・スレッドがアクセスできます。シングル・コンテキスト・モードを指定するには、NULLのパラメータを指定したtpinit()を呼び出すか、TPINIT構造体のflagsフィールドにTPMULTICONTEXTSフラグを指定せずにtpinit()を呼び出します。また、tpinit()が別のATMI関数によって暗黙的に呼び出されたときも、シングル・コンテキスト・モードが指定されます。シングル・コンテキスト・モードで動作するプロセスのコンテキスト状態は、TPSINGLECONTEXTです。

ノート:

TMNOTHREADS環境変数を"yes"に設定しても、tpinitのTPMULTICONTEXTSモードは正しく機能します。

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

TPINIT構造体のflagsフィールドにTPMULTICONTEXTSフラグを設定してtpinit()を呼び出すと、マルチコンテキスト・モードに移行します。マルチコンテキスト・モードでは、tpinit()を呼び出すたびに別のアプリケーション関連が作成されます。

アプリケーションの関連とは、プロセスとOracle Tuxedo ATMIアプリケーションを関連付けるコンテキストです。クライアントは、複数のOracle Tuxedo ATMIアプリケーションと関連を持ったり、同じアプリケーションに対して複数の関連を持つことができます。クライアントの関連付けは、すべて同じリリースのOracle Tuxedo ATMIシステムを実行するアプリケーションに対する関連付けでなければなりません。また、すべての関連付けはネイティブ・クライアントかワークステーション・クライアントのいずれかでなければなりません。

ネイティブ・クライアントの場合、新しい関連の生成元になるアプリケーションは、TUXCONFIG環境変数の値で決まります。ワークステーション・クライアントの場合、新しい関連の生成元になるアプリケーションは、WSNADDRまたはWSENVFILE環境変数の値で決まります。カレント・スレッドのコンテキストは、新しい関連に設定されます。

マルチコンテキスト・モードでは、アプリケーションはtpgetctxt()を呼び出すことにより現在のコンテキストを表すハンドルを取得し、そのハンドルをパラメータとしてtpsetctxt()に渡して、特定のスレッドまたはプロセスが動作するコンテキストを設定できます。

シングル・コンテキスト・モードとマルチコンテキスト・モードの両方を使用することはできません。アプリケーションがどちらかのモードを選択した場合、すべてのアプリケーション関連でtpterm()が呼び出されるまで、他のモードでtpinit()を呼び出すことはできません。

TPINFO構造体フィールドの説明

マルチコンテキスト・モードとシングル・コンテキスト・モードを制御するほかに、flagsの設定により、クライアント固有の通知メカニズムとシステム・アクセスのモードの両方を示すことができます。この2つの設定で、アプリケーションのデフォルト設定をオーバーライドすることができます。これらの設定でアプリケーションのデフォルトをオーバーライドできない場合、tpinit()はログ・ファイルに警告メッセージを記録し、その設定を無視して、tpinit()からの戻り時にflagsフィールドの設定をアプリケーションのデフォルト設定に戻します。クライアントへの通知の場合、flagsの値として次のものがあります。

TPU_SIG

シグナルによる任意通知を選択します。このフラグは、シングル・スレッド、シングル・コンテキストのアプリケーション専用です。TPMULTICONTEXTSフラグが設定されている場合、このフラグは使用できません。

TPU_DIP

ディップ・インによる任意通知を選択します。

TPU_THREAD

Oracle Tuxedo ATMIシステムが管理する独立したスレッドで、THREAD通知を選択します。このフラグは、マルチスレッドをサポートするプラットフォーム専用です。マルチスレッドをサポートしていないプラットフォームでTPU_THREADが指定されると、無効な引数とみなされ、エラーが返されてtperrnoがTPEINVALに設定されます。

TPU_IGN

任意通知を無視します。

一度に上記の中から1つのフラグだけを使用できます。クライアントがフラグ・フィールドを使用して通知方法を選択しない場合、アプリケーションのデフォルトの方法が、tpinit()の終了時にフラグ・フィールドに設定されます。

システム・アクセス・モードの設定の場合、flagsの値として次のものがあります。

TPSA_FASTPATH

システム・アクセス・モードをfastpathに設定します。

TPSA_PROTECTED

システム・アクセス・モードを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]

無効な引数が指定されていました。tpinfoはNULLではなく、タイプTPINITの型付きバッファを指していません。

[TPENOENT]

領域制限のため、クライアントはアプリケーションに参加できません。

[TPEPERM]

クライアントは、許可を持たないため、または正しいアプリケーション・パスワードが与えられていないために、アプリケーションに参加できません。パーミッションが与えられない理由として、アプリケーション・パスワードが無効であった場合、アプリケーション固有の認証検査にパスできない場合、あるいは禁止されている名前を使用した場合などがあります。tpurcode()は、クライアントがアプリケーションに参加できない理由を説明するため、アプリケーション固有の認証サーバーによって設定される場合があります。

[TPEPROTO]

tpinit()が不正に呼び出されました。たとえば、(a)呼出し元がサーバーである、(b)シングル・コンテキスト・モードでTPMULTICONTEXTSフラグが指定されている、または(c)マルチコンテキスト・モードでTPMULTICONTEXTSフラグが指定されていない場合があります。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。[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()内で使用されます。これは、アプリケーションをアクセスするときに使用されるワークステーション・リスナー・プロセスのネットワーク・アドレスを示します。この変数はワークステーション・クライアントの場合は必須ですが、ネイティブ・クライアントの場合は無視されます。

TCP/IPアドレスは次の形式で指定します。

//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

Windows下で実行するためには、アドレス文字列は以下のように表します。

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文字列と解釈されます。

UNIXでソケット・ダイレクト・プロトコル(SDP)を使用するように/WSクライアントを構成する場合、アドレス文字列は次のようになります。

$ export WSNADDR=sdp://IB_IP:port

UNIXでIP over InfiniBand (IPoIB)を使用するように/WSクライアントを構成する場合、アドレス文字列は次のようになります。

$ export WSNADDR=//IB_IP:port

UNIXでIP over TCP/IPを使用するように/WSクライアントを構成する場合、アドレス文字列は次のようになります。

$ export WSNADDR=//ETH_IP:port

WSFADDR

ワークステーション・クライアントが呼び出すときにtpinit()内で使用されます。この変数は、ワークステーション・クライアントがワークステーション・リスナーまたはワークステーション・ハンドラに接続するときに使用するネットワーク・アドレスを指定します。この変数は、WSFRANGE変数とともに、ワークステーション・クライアントがアウトバウンド接続を行う前にバインドしようとするTCP/IPポートの範囲を決定します。このアドレスには、TCP/IPアドレスを指定する必要があります。TCP/IPアドレスのポート部分は、ワークステーション・クライアントによってバインドされる一連のTCP/IPポートのベース・アドレスを表します。WSFRANGE変数は、範囲の大きさを指定します。たとえば、このアドレスが//mymachine.oracle.com:30000でWSFRANGEが200の場合、このLMIDからアウトバウンド接続を試みるネイティブ・プロセスはすべて、mymachine.oracle.comの30000から30200までのポートをバインドします。この変数を設定しないと、空の文字列が使用され、オペレーティング・システムはローカル・ポートをランダムに選択します。

WSFRANGE

ワークステーション・クライアントが呼び出すときにtpinit()内で使用されます。この変数は、ワークステーション・クライアント・プロセスが、アウトバウンド接続を行う前にバインドを試みるTCP/IPポートの範囲を指定します。WSFADDRパラメータは、範囲のベース・アドレスを指定します。たとえば、WSFADDRパラメータが//mymachine.oracle.com:30000に設定され、WSFRANGEが200に設定されると、このLMIDからアウトバウンド接続を試みるネイティブ・プロセスはすべて、mymachine.oracle.comの30000から30200までのポートをバインドします。有効範囲は1から65535までです。デフォルトは1です。

WSDEVICE

ワークステーション・クライアントが呼び出すときにtpinit()内で使用されます。これは、ネットワークのアクセス時に使用するデバイス名を示します。この変数はワークステーション・クライアントが使用し、ネイティブ・クライアントの場合は無視されます。なお、ソケットやNetBIOSなどトランスポート・レベルのネットワーク・インタフェースはデバイス名を必要としません。このようなインタフェースによってサポートされているワークステーション・クライアントは、WSDEVICEを指定する必要はありません。

WSTYPE

ワークステーション・クライアントが呼び出すときにtpinit()内から使用され、ネイティブ・サイトとの間でエンコード/デコードの責任範囲について調整を行います。この変数はワークステーション・クライアントの場合は省略可能で、ネイティブ・クライアントの場合は無視されます。

WSRPLYMAX

tpinit()によって使用され、アプリケーションの応答をファイルに格納する前にバッファに入れるために使用するコア・メモリーの最大サイズを設定します。このパラメータのデフォルトは、256,000バイトです。詳細は、プログラミング・ドキュメントを参照してください。

TMMINENCRYPTBITS

Oracle Tuxedo ATMIシステムに接続するのに必要な暗号化の最小レベルを確立するときに使用されます。「0」は暗号化を行わないことを示します。「56」と「128」は暗号化キーの長さをビット単位で指定します。また後方互換のため、40ビットのリンク・レベルの暗号化も使用できます。ここで指定された最低レベルの暗号化が行われないと、リンクの確立は失敗します。デフォルトは0です。

TMMAXENCRYPTBITS

Oracle Tuxedo ATMIシステムに接続するときに、このレベルまで暗号化を調整するのに使用されます。「0」は暗号化を行わないことを示します。「56」と「128」は暗号化キーの長さをビット単位で指定します。また後方互換のため、40ビットのリンク・レベルの暗号化も使用できます。デフォルトは128です。

警告

シグナル・ベースの通知は、マルチコンテキスト・モードでは使用できません。また、シグナルの制約によって、クライアントがシグナル・ベースの通知を選択しても、システムがそれを使用できない場合があります。このような場合、システムは、選択されたクライアントに対する通知をディップ・インに切り替えることを示すログ・メッセージを生成し、クライアントはそれ以降ディップ・イン通知によって通知されます。(通知方法の詳細については、「UBBCONFIG(5)」のRESOURCESセクションのNOTIFYパラメータの説明を参照してください。)

クライアントのシグナル通知は、常にシステムによって行われるので、元の通知呼出しがどこで行われるかにかかわらず、通知の形態は一貫しています。したがって、シグナル・ベースの通知を使用するには次の条件が必要です。

• ネイティブ・クライアントは、アプリケーション管理者として実行しています。
• ワークステーション・クライアントはアプリケーション管理者として実行している必要はありません

アプリケーション管理者のIDは、アプリケーション構成の一部として識別されます。

クライアントにシグナル・ベースの通知を選択すると、ある種のATMI呼出しは正常に実行できないことがあります。このとき、TPSIGRSTRTの指定がない場合、非請求メッセージを受け取るため、TPGOTSIGが返されます。

関連項目:

「C言語アプリケーション・トランザクション・モニター・インタフェースの紹介」、tpgetctxt(3c)、tpterm(3c)。

2.95 tpkey_close(3c)

名前

tpkey_close() - 前にオープンされたキー・ハンドルをクローズします。

形式

#include <atmi.h>
int tpkey_close(TPKEY hKey, long flags)

説明

tpkey_close()は、以前にオープンしたキー・ハンドルと、それに関連付けられているすべてのリソースを解放します。プリンシパルの秘密キーなどの機密情報はすべて、メモリーから消去されます。

キー・ハンドルは、次のいずれかの方法でオープンできます。

• tpkey_open()の明示的呼出し
• tpenvelope()からの出力

tpkey_close()を呼び出してキー・リソースを解放するのは、アプリケーションの役目です。あるプロセスがキーをクローズすると、同じプロセスがそのキー・ハンドルを使用してデジタル署名や暗号化のメッセージ・バッファを登録することはできなくなります。プロセスがTPKEY_AUTOSIGNまたはTPKEY_AUTOENCRYPTフラグを指定したtpkey_open()でキーをオープンした場合、キーをクローズした後の通信操作にはそのキー・ハンドルは適用されません。

ただし、キーをクローズした後でも、そのキー・ハンドルは、クローズ前に登録された関連署名リクエストや暗号化リクエストに対しては有効です。クローズしたキーに関連付けられている最後のバッファが解放されるか上書きされると、そのキーに属していたリソースは解放されます。

引数flagsは将来の用途のために予約されており、0に設定する必要があります。

戻り値

異常終了すると、この関数は -1を返し、tperrnoを設定してエラー条件を示します。

エラー

[TPEINVAL]

無効な引数が指定されました。たとえば、hKeyの値が有効なキーではありません。

[TPESYSTEM]

エラーが発生しました。詳細は、システム・エラーのログ・ファイルを調べてください。

関連項目:

tpenvelope(3c)、tpkey_getinfo(3c)、tpkey_open(3c)、tpkey_setinfo(3c)

2.96 tpkey_getinfo(3c)

名前

tpkey_getinfo() - キー・ハンドルに関連付けられた情報を取得します。

形式

#include <atmi.h>
int tpkey_getinfo(TPKEY hKey, char *attribute_name, void *value, long *value_len, long flags)

説明

tpkey_getinfo()は、キー・ハンドルに関する情報を報告します。キー・ハンドルは、特定のプリンシパルのキーおよびそれに関連付けられている情報を表します。

調査対象のキーは、hKey入力パラメータによって識別されます。情報が要求されている属性は、attribute_name入力パラメータで識別されます。一部の属性は暗号サービス・プロバイダ固有のものですが、以下に示す属性は、すべてのプロバイダによってサポートされています。

属性	値
PRINCIPAL	キー(キー・ハンドル)と関連付けられているプリンシパルを識別する名前。NULLで終了する文字列で表されます。
PKENCRYPT_ALG	公開キー暗号化のキーによって使用される、公開キー・アルゴリズムのASN.1 DER (Distinguished Encoding Rules)形式のオブジェクト識別子。RSAのオブジェクト識別子は次の表で識別されます。
PKENCRYPT_BITS	公開キー・アルゴリズムのキー長(RSAのモジュロ・サイズ)。この値は、512 - 2048ビットの範囲でなければなりません。
SIGNATURE_ALG	デジタル署名のキーによって使用される、デジタル署名アルゴリズムのASN.1 DER形式のオブジェクト識別子。RSAおよびDSAのオブジェクト識別子は次の表で識別されます。
SIGNATURE_BITS	デジタル署名アルゴリズムのキー長(RSAのモジュロ・サイズ)。この値は、512 - 2048ビットの範囲でなければなりません。
ENCRYPT_ALG	バルク・データ暗号化のキーによって使用される、対称キー・アルゴリズムのASN.1 DER形式のオブジェクト識別子。AES、DES、3DESおよびRC2のオブジェクト識別子は次の表で識別されます。
ENCRYPT_BITS	対称キー・アルゴリズムのキー長。値は40ビット以上128ビット以下の範囲内にある必要があります。ENCRYPT_ALGで固定キー長によるアルゴリズムが設定されると、ENCRYPT_BITSの値は自動的にその固定キー長に設定されます。たとえば、ENCRYPT_ALGにDESが設定されると、ENCRYPT_BITSの値は自動的に56に設定されます。
DIGEST_ALG	デジタル署名のキーによって使用される、メッセージ・ダイジェスト・アルゴリズムのASN.1 DER形式のオブジェクト識別子。MD5およびSHA-1のオブジェクト識別子については、次の表を参照してください。
PROVIDER	暗号サービス・プロバイダの名前。
VERSION	暗号サービス・プロバイダのソフトウェアのバージョン番号。

次の表に、デフォルトの公開キー実装でサポートされるASN.1 DERアルゴリズム・オブジェクト識別子を示します。

ASN.1 DERアルゴリズム・オブジェクト識別子	アルゴリズム
{ 0x06, 0x08, 0x2a, 0x86, 0x48, 0x86, 0xf7, 0x0d, 0x02, 0x05 }	MD5
{ 0x06, 0x05, 0x2b, 0x0e, 0x03, 0x02, 0x1a }	SHA1
{ 0x06, 0x09, 0x2a, 0x86, 0x48, 0x86, 0xf7, 0x0d, 0x01, 0x01, 0x01 }	RSA
{ 0x06, 0x05, 0x2b, 0x0e, 0x03, 0x02, 0x0c }	DSA
{ 0x06, 0x09, 0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x01, 0x02 }	AES128-cbc
{ 0x06, 0x09, 0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x01, 0x2a }	AES256-cbc
{ 0x06, 0x05, 0x2b, 0x0e, 0x03, 0x02, 0x07 }	DES
{ 0x06, 0x08, 0x2a, 0x86, 0x48, 0x86, 0xf7, 0x0d, 0x03, 0x07 }	3DES
{ 0x06, 0x08, 0x2a, 0x86, 0x48, 0x86, 0xf7, 0x0d, 0x03, 0x02 }	RC2

指定されたattribute_nameパラメータに関連付けられている情報は、値によって示されるメモリー位置に格納されます。この位置に格納できる最大データ量は、呼出し側によってvalue_lenに指定されます。

tpkey_getinfo()が完了すると、value_lenは実際に返されたデータ・サイズに設定されます。この場合、string値の終端NULL値も含まれます。返されるバイト数がvalue_lenより大きい場合、tpkey_getinfo()は異常終了し(TPELIMITエラー・コードを返し)、value_lenを必要な大きさに設定します。

引数flagsは将来の用途のために予約されており、0に設定する必要があります。

戻り値

異常終了すると、この関数は -1を返し、tperrnoを設定してエラー条件を示します。

エラー

[TPEINVAL]

無効な引数が指定されました。たとえば、hKeyが有効なキーではありません。

[TPESYSTEM]

エラーが発生しました。詳細は、システム・エラーのログ・ファイルを調べてください。

[TPELIMIT]

リクエストされた属性値を保持するためのスペースが不足しています。

[TPENOENT]

リクエストされた属性は、このキーに関連付けらていません。

関連項目:

tpkey_close(3c)、tpkey_open(3c)、tpkey_setinfo(3c)

2.97 tpkey_open(3c)

名前

tpkey_open() - デジタル署名生成、メッセージの暗号化、またはメッセージの復号化のためのキー・ハンドルをオープンします。

形式

#include <atmi.h>
int tpkey_open(TPKEY *hKey, char *principal_name, char *location, char *identity_proof, long proof_len, long flags)

説明

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]

無効な引数が指定されました。たとえば、hKeyの値がNULLであるか、またはflagsパラメータが正しく設定されていません。

[TPEPERM]

パーミッション異常終了。暗号サービス・プロバイダは、指定された証明情報と現在の環境で、このプリンシパルの秘密キーにアクセスできませんでした。

[TPESYSTEM]

システム・エラーが発生しました。詳細は、システム・エラーのログ・ファイルを参照してください。

関連項目:

tpkey_close(3c)、tpkey_getinfo(3c)、tpkey_setinfo(3c)

2.98 tpkey_setinfo(3c)

名前

tpkey_setinfo() - キー・ハンドルに関連付けられている省略可能な属性パラメータを設定します。

形式

#include <atmi.h>
int tpkey_setinfo(TPKEY hKey, char *attribute_name, void *value, long value_len, long flags)

説明

tpkey_setinfo()は、キー・ハンドルのオプション属性パラメータを設定します。キー・ハンドルは、特定のプリンシパルのキーおよびそれに関連付けられている情報を表します。

情報が修正されるキーは、hKey入力パラメータで識別されます。情報が修正される属性は、attribute_name入力パラメータで識別されます。一部の属性は暗号サービス・プロバイダ固有のものですが、「tpkey_getinfo(3c)」リファレンス・ページで示す基本的属性は、すべてのプロバイダでサポートされる必要があります。

attribute_nameパラメータに関連付けられる情報は、valueによって示されるメモリー位置に格納されます。valueのデータ内容が自己記述型の場合、value_lenは無視されます(0でもかまいません)。それ以外の場合、value_lenにはvalue内のデータの長さが格納されている必要があります。

引数flagsは将来の用途のために予約されており、0に設定する必要があります。

戻り値

異常終了すると、この関数は -1を返し、tperrnoを設定してエラー条件を示します。

エラー

[TPEINVAL]

無効な引数が指定されました。たとえば、hKeyが有効なキーではない場合、attribute_nameが読取り専用の値を参照している場合などです。

[TPELIMIT]

指定されたvalueが大きすぎます。

[TPESYSTEM]

エラーが発生しました。詳細は、システム・エラーのログ・ファイルを調べてください。

[TPENOENT]

リクエストされた属性は、キーの暗号サービス・プロバイダによって認識されません。

関連項目:

tpkey_close(3c)、tpkey_getinfo(3c)、tpkey_open(3c)

2.99 tpnotify(3c)

名前

tpnotify() - クライアント識別子によって通知を送信するルーチン。

形式

#include <atmi.h>
int tpnotify(CLIENTID *clientid, char *data, long len, long flags)

説明

tpnotify()は、クライアントまたはサーバーが各クライアントに任意通知型メッセージを送信できるようにします。

clientidは、以前のあるいは現在のサービス呼出しのTPSVCINFO構造体から保存された、または、他のなんらかの通信機構によってクライアントに渡された(たとえば、管理インタフェースを介して検索された)クライアント識別子を指すポインタです。

このリクエストのデータ部はdataによって示され、以前にtpalloc()によって割り当てられたバッファです。lenには、送信するdataの大きさを指定します。ただし、dataが長さの指定を必要としないタイプのバッファを指す場合(FMLフィールド化バッファなど)、lenは無視されます(0でもかまいません)。また、dataはNULLであってもかまいません。この場合、lenは無視されます。

tpnotify()が正常終了した場合、メッセージはシステムに渡され、指定されたクライアントに送信されます。TPACKフラグが設定されている場合は、正常終了は、クライアントがメッセージを受信したことを意味します。さらに、クライアントが任意通知型メッセージ・ハンドラに登録している場合は、ハンドラが呼び出されます。

次に、有効なflagsの一覧を示します:

TPACK

リクエストは送信され、呼出し側は承認メッセージがターゲットのクライアントから受信されるまでブロックします。

TPNOBLOCK

このリクエストは、通知の送信中にブロッキング条件が存在する場合(たとえば、メッセージの送信先である内部バッファがいっぱいの場合など)には、送信されません。

TPNOTIME

このフラグは、呼出し側が無制限にブロックでき、ブロッキング・タイムアウトの対象にならないようにすることを指定します。ただし、トランザクション・タイムアウトは発生する可能性があります。

TPSIGRSTRT

ルーチン内部のシステム・コールがシグナルによって中断された場合、中断されたシステム・コールは再発行されます。

TPACKフラグを設定しないかぎり、tpnotify()は、メッセージがクライアントに送られるまで待機していません。

マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドはtpnotify()の呼出しを発行できません。

戻り値

異常終了すると、tpnotify()は -1を返し、tperrnoを設定してエラー条件を示します。呼出しが異常終了してtperrnoに特定の値が設定されたときは、中間のATMI呼出しを省略して引き続きtperrordetail()を呼び出すと、エラーに関する詳細な情報が提供されます。詳細は、「tperrordetail(3c)」リファレンス・ページを参照してください。

エラー

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

[TPEINVAL]

無効な引数が指定されました(たとえば、無効なフラグなど)。

[TPENOENT]

ターゲットのクライアントが存在せず、TPACKフラグが設定されました。

[TPETIME]

ブロッキング・タイムアウトが発生し、TPNOBLOCKとTPNOTIMEのいずれも指定されなかったか、TPACKは設定されたが承認が受信されず、TPNOTIMEが指定されませんでした。(ブロッキング・タイムアウトは、TPNOBLOCKまたはTPNOTIMEが指定されている場合は発生しません。)

[TPEBLOCK]

呼出し時にブロッキング条件が検出されましたが、TPNOBLOCKが指定されました。

[TPGOTSIG]

シグナルを受け取りましたが、TPSIGRSTRTが指定されていません。

[TPEPROTO]

tpnotify()が不正に呼び出されました。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。

[TPERELEASE]

TPACKが指定され、ターゲットは承認プロトコルをサポートしないOracle Tuxedoの前のリリースからのクライアントです。

関連項目:

「C言語アプリケーション・トランザクション・モニター・インタフェースの紹介」、tpalloc(3c)、tpbroadcast(3c)、tpchkunsol(3c)、tperrordetail(3c)、tpinit(3c)、tpsetunsol(3c)、tpterm(3c)

2.100 tpopen(3c)

名前

tpopen() - リソース・マネージャをオープンするルーチン。

形式

#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]

tpopen()が不正なコンテキストで呼び出されました(たとえば、Oracle Tuxedoシステム・サーバー・グループに結合していないクライアントにより)。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。

関連項目:

tpclose(3c)、tprmopen(3c)、tprmclose(3c)、tprmstart(3c)、tprmend(3c)

2.101 tppost(3c)

名前

tppost() - イベントをポストします。

形式

#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は、イベントでポストされるバッファ内のデータの大きさを指定しなければなりません。ただし、dataが長さの指定を必要としないタイプのバッファを指す場合(FMLフィールド化バッファなど)、lenは無視されます。dataがNULLの場合、lenは無視され、イベントはデータなしでポストされます。

tppost()をトランザクション内で使用する場合は、トランザクションの境界を拡大して、これらのサーバー上、およびイベント・ブローカが通知する安定ストレージ上のメッセージ・キューを含むようにすることができます。トランザクションによるポストでは、ポストされたイベントを受け取ったことがポスト元のトランザクションに通知される場合(サーバーやキューなど)と、通知されない場合(クライアントなど)があります。

ポスト元がトランザクション内にあり、TPNOTRANがセットされている場合は、ポストされたイベントはイベント・ブローカに渡されます。これは、イベント・ブローカがイベントをポスト元のトランザクションの一部として処理できるようにするためです。ブローカは、トランザクションによるイベント通知を、tpsubscribe()に渡されるctl−>flagsパラメータでTPEVTRANビットの設定を使用したサービス・ルーチンおよび安定ストレージ上のキューのサブスクリプションのみにディスパッチします。イベント・ブローカは、クライアントへの通知、およびtpsubscribe()に渡されるctl−>flagsパラメータでTPEVTRANビットの設定を使用しなかったサービス・ルーチンおよび安定ストレージ上のキューのサブスクリプションもディスパッチしますが、これはポスト元プロセスのトランザクションの一部としてではありません。

ポスト元がトランザクションの外部にある場合、イベントに関連付けられているサービスが失敗すると、tppost()は肯定応答のない一方向のポストになります。このような状況は、イベント用にTPEVTRANが設定されている場合でも起こります(この設定には、tpsubscribe()に渡されるctl−>flagsパラメータを使用します)。ポスト元がトランザクション内にある場合は、イベントに関連するサービスが失敗するとtppost()はTPESVCFAILを戻します。

次に、有効なflagsの一覧を示します:

TPNOTRAN

呼出し側がトランザクション・モードにあり、このフラグが設定されている場合は、イベントのポストは呼出し側のトランザクションのかわりに実行されません。トランザクション・モードにあるこのフラグを設定する呼出し側は、イベントのポストの際に、依然としてトランザクション・タイムアウトの対象となります。イベントのポストが正しく実行されなかった場合、呼出し側のトランザクションには影響はありません。

TPNOREPLY

tppost()に対し、イベント・ブローカがeventnameに対するすべてのサブスクリプションを処理するまで待ってから戻る必要はないことを知らせます。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]

無効な引数が指定されました(たとえば、eventnameがNULLである場合など)。

[TPENOENT]

Oracle Tuxedoのユーザー・イベント・ブローカにアクセスできません。

[TPETRAN]

呼出し側がトランザクション・モードにあり、TPNOTRANが設定されず、トランザクション伝達をサポートしないイベント・ブローカにtppost()がコンタクトしました。つまり、TMUSREVT(5)が、トランザクションをサポートするOracle Tuxedo ATMIグループで実行されていません。

[TPETIME]

このエラー・コードは、タイムアウトが発生したか、または現在のトランザクションがすでに「ロールバックのみ」とマークされているにもかかわらずtppost()が試行されたことを示します。

呼出し側がトランザクション・モードの場合、トランザクションはすでにロールバックのみであるか、またはトランザクション・タイムアウトが発生しました。このトランザクションは、「中断のみ」とマークされます。呼出し側がトランザクション・モードでない場合、ブロッキング・タイムアウトが発生しています。(ブロッキング・タイムアウトは、TPNOBLOCKまたはTPNOTIMEが指定されている場合は発生しません。)

トランザクション・タイムアウトが発生した場合、トランザクションが中断されないかぎり、新しいリクエストの送信や未処理の応答の受信はできず、TPETIMEが発生します。その例外とは、ブロックされず、応答を期待せず、かつ呼出し側のトランザクションのかわりに送信されない(つまり、TPNOTRAN、TPNOBLOCKおよびTPNOREPLYを設定してtpacall()を呼び出した場合の)リクエストです。

tppost()がトランザクション内部で失敗すると、そのトランザクションはTX_ROLLBACK_ONLY状態になります。ほとんどの場合、この状態はタイムアウトと同じものとして扱われます。このトランザクションの以降のATMI呼出しは、すべてTPETIMEで異常終了します(前の段落で説明した例外を除く)。

[TPESVCFAIL]

イベント・ブローカが呼出し側のトランザクションに関して、トランザクション・イベントをサービス・ルーチンまたは安定ストレージ上のキューに通知する際に、エラーが発生しました。呼出し側の現在のトランザクションは、中断のみとしてマークされます。このエラーが返された場合、tpurcode()には、eventnameのかわりにイベント・ブローカによってディスパッチされたトランザクション以外のイベント通知の数が設定されています。トランザクションによるポストは、トランザクションの完了とともにその効果がなくなるため、カウントされません。なお、トランザクションがタイムアウトしないかぎり、通信はトランザクションが異常終了するまで継続され、呼出し側のトランザクションのためになされた作業はトランザクションが完了する時点で異常終了されます(つまり、以降のやりとりで何らかの結果が得られる場合には、TPNOTRANを設定しておく必要があります)。

[TPEBLOCK]

ブロッキング状態のため、TPNOBLOCKが指定されました。

[TPGOTSIG]

シグナルを受け取りましたが、TPSIGRSTRTが指定されていません。

[TPEPROTO]

tppost()が不正に呼び出されました。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。

関連項目:

tpsubscribe(3c)、tpunsubscribe(3c)、EVENTS(5)、TMSYSEVT(5)、TMUSREVT(5)

2.102 tprealloc(3c)

名前

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]

無効な引数が指定されました(たとえば、ptrが、もともとtpalloc()によって割り当てられたバッファを指していない場合など)。

[TPEPROTO]

tprealloc()が不正に呼び出されました。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。

使用方法

バッファの再初期化が正常に実行できなかった場合、tprealloc()は異常終了してNULLを返し、ptrが指すバッファの内容は無効になってしまう可能性があります。この関数は、Cライブラリのmalloc()、realloc()、またはfree()とともに使用することはできません(たとえば、tprealloc()で割り当てたバッファはfree()で解放することはできません)。

関連項目:

tpalloc(3c)、tpfree(3c)、tptypes(3c)

2.103 tprecv(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はtprecv()が正常に受信したデータ量を設定するlong型の値を指すようにしてください。正常終了時には、*dataは、その応答を収めたバッファを指し、*lenには、そのバッファのサイズが入ります。FMLとFML32バッファは、通常最小サイズ4096バイトを確保します。したがって、応答が4096バイトより大きい場合は、バッファ・サイズは返されるデータを入れるのに十分な大きさに拡大します。

容量まで満たされていない送信側のバッファ(たとえば、FMLおよびSTRINGバッファ)は、送信に使用された大きさになります。システムは、受信データのサイズを任意の量で拡大します。これは、受信者が送信者の割り当てたバッファ・サイズより小さく、送信されたデータのサイズより大きいバッファを受け取ることを意味します。

受信バッファのサイズは、増加することも減少することもあります。また、アドレスもシステムがバッファを内部で交換するごとに常に変更されます。応答バッファのサイズが変わったかどうか(また変わったとしたらどれくらい変わったのか)を判別するには、tprecv()が発行される前の合計サイズを*lenと比較します。

バッファ管理の詳細については、「C言語アプリケーション・トランザクション・モニター・インタフェースの紹介」を参照してください。

I*lenが0であると、データは受け取られず、*dataも、それが指すバッファも変更されていません。data、*dataまたはlenがNULLであると、エラーになります。

tprecv()は、接続の制御を持たないプログラムによってのみ発行できます。

次に、有効なflagsの一覧を示します:

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]

無効な引数が指定されました(たとえば、dataがtpalloc()によって割り当てられたバッファを指すポインタのアドレスでない場合、flagsが無効である場合など)。

[TPEOTYPE]

受信バッファのタイプおよびサブタイプが呼出し側に認識されていないか、またはTPNOCHANGEがflagsに設定されており、*dataのタイプおよびサブタイプが、受信バッファのタイプおよびサブタイプと一致しません。*dataとその内容も、*lenも変更されません。会話が呼出し側の現在のトランザクションの一部になっている場合は、受け取るバッファが放棄されるため、トランザクションは中断のみとしてマークされます。

[TPEBADDESC]

cdが無効です。

[TPETIME]

このエラー・コードは、タイムアウトが発生したか、または現在のトランザクションがすでに「ロールバックのみ」とマークされているにもかかわらずtprecv()が試行されたことを示します。

呼出し側がトランザクション・モードの場合、トランザクションはすでにロールバックのみであるか、またはトランザクション・タイムアウトが発生しました。このトランザクションは、「中断のみ」とマークされます。呼出し側がトランザクション・モードでない場合、ブロッキング・タイムアウトが発生しています。(ブロッキング・タイムアウトは、TPNOBLOCKまたはTPNOTIMEが指定されている場合は発生しません。)いずれの場合でも、*dataもその内容も変更されません。

トランザクション・タイムアウトが発生した場合、トランザクションが中断されないかぎり、新しいリクエストの送信や未処理の応答の受信はできず、TPETIMEが発生します。その例外とは、ブロックされず、応答を期待せず、かつ呼出し側のトランザクションのかわりに送信されない(つまり、TPNOTRAN、TPNOBLOCKおよびTPNOREPLYを設定してtpacall()を呼び出した場合の)リクエストです。

ATMI呼出しがトランザクション内部で失敗すると、そのトランザクションはTX_ROLLBACK_ONLY状態になります。ほとんどの場合、この状態はタイムアウトと同じものとして扱われます。このトランザクションの以降のATMI呼出しは、すべてTPETIMEで異常終了します(前の段落で説明した例外を除く)。

[TPEEVENT]

イベントが発生し、そのタイプがreventに記録されます。[TPETIME]と[TPEEVENT]のリターン・コード間には関連があります。トランザクション・モードにおいては、会話の受信側がtprecvにブロックされていて、送信側がtpabort()を出した場合、受信側は[TPEVENT]リターン・コードをTPEV_DISCONIMMのイベントと共に取得します。ただし、受信側がtprecv()を呼び出す前に、送信側がtpabort()を呼び出した場合は、そのトランザクションはすでにGTTから削除されてしまっているため、tprecv()は異常終了し、[TPETIME]コードが返されます。

[TPEBLOCK]

ブロッキング状態のため、TPNOBLOCKが指定されました。

[TPGOTSIG]

シグナルを受け取りましたが、TPSIGRSTRTが指定されていません。

[TPEPROTO]

tprecv()が不正なコンテキストで呼び出されました(たとえば、呼出しプログラムがデータの送信のみを行えるよう接続が確立されている場合など)。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。

使用方法

サーバーは、tpreturn()を呼び出すとき、アプリケーション定義の戻りコードおよび型付きバッファを渡すことができます。戻り値はグローバル変数tpurcodeで使用され、バッファはdataで使用されます。

関連項目:

tpalloc(3c)、tpconnect(3c)、tpdiscon(3c)、tperrordetail(3c)、tpsend(3c)、tpservice(3c)、tpstrerrordetail(3c)

2.104 tpresume(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]

tranidが、別のプロセスがすでに再開したトランザクション識別子を指しています。トランザクションに関する呼出し側の状態は変化しません。

[TPETRAN]

呼出し側が少なくとも1つ以上のリソース・マネージャでグローバル・トランザクションの外部の作業に関与しているため、Oracle Tuxedoシステムがグローバル・トランザクションを再開できません。グローバル・トランザクションを再開するためには、あらかじめこれらの作業をすべて終了させる必要があります。ローカル・トランザクションについての呼出し側の状態は、変更されません。

[TPEPROTO]

tpresume()が不正なコンテキストで呼び出されました(たとえば、呼出し側がすでにトランザクション・モードであるなど)。トランザクションに関する呼出し側の状態は変化しません。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。

ノート

XA準拠のリソース・マネージャがグローバル・トランザクションに含まれるようにするには、そのリソース・マネージャが正常にオープンされている必要があります。(詳細は、「tpopen(3c)」を参照してください。)

中断したトランザクションを再開するプロセスは、トランザクションを中断したプロセスと同じ論理マシン(LMID)上に存在しなければなりません。ワークステーション・クライアントの場合、そのワークステーションが接続されているワークステーション・ハンドラ(WSH)は、そのトランザクションを停止させたワークステーション・クライアントのハンドラと同じ論理マシン上に存在している必要があります。

関連項目:

tpabort(3c)、tpcommit(3c)、tpopen(3c)、tpsuspend(3c)、tprmopen(3c)、tprmclose(3c)、tprmstart(3c)、tprmend(3c)

2.105 tpreturn(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つあります。

• 呼出しが行われたときに接続がすでに切断されていた場合(呼出し側がその接続上でTPEV_DISCONIMMを受け取っていた場合)、この呼出しは単にサービス・ルーチンを終了させ、現在のトランザクション(もしあれば)を中断させます。
• 呼出し側が接続の制御権をもたない場合、上記のように、TPEV_SVCFAILまたはTPEV_SVCERRが接続の要求元に送られます。発信元が受信したイベントの種類にかかわらず、データは送信されません。ただし、発信元がTPEV_SVCFAILイベントを受信した場合は、発信元のtpurcode()変数にリターン・コードが設定されます。

戻り値

サービス・ルーチンは呼出し側である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)

2.106 tprmclose(3c)

名前

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]

無効なパラメータが指定されました(たとえば、フラグの値が0でない、rmnameがNULLである、または複数のリソース・マネージャのサーバー・グループに関連付けられている現在の*RMSセクションで有効なリソース・マネージャ名が構成されていないなど)。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。

関連項目:

tpopen(3c)、tpclose(3c)、tprmopen(3c)

2.107 tprmend(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]

tprmend()が不正なコンテキストで呼び出されました(たとえば、buildserverの実行時に-Mオプションで指定されていないサーバーで呼び出された場合など)。

[TPETRAN]

tprmend()が非トランザクション・コンテキストで呼び出されました。

[TPEINVAL]

無効なパラメータが指定されました(たとえば、フラグの値が0でない、rmnameパラメータがNULLである、または現在の複数のリソース・マネージャのサーバー・グループに有効なリソース・マネージャ名が構成されていないなど)。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。

関連項目:

tprmstart(3c)

2.108 tprmopen(3c)

名前

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]

無効なパラメータが指定されました(たとえば、フラグの値が0でない、rmnameがNULLである、または複数のRMのサーバー・グループに関連付けられているUBBCONFIGの*RMSセクションに有効なリソース・マネージャ名が構成されていないなど)。

もう1つのケースとして、このRMがRMのCAE仕様でない場合があります。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。

関連項目:

tpopen(3c)、tpclose(3c)、tprmclose(3c)

2.109 tprmstart(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]

tprmstart()が非トランザクション・コンテキストで呼び出されました。

[TPEINVAL]

無効なパラメータが指定されました(たとえば、フラグの値が0でない、rmnameがNULLである、または複数のリソース・マネージャのサーバー・グループに関連付けられている*RMSセクションで有効なリソース・マネージャ名が構成されていないなど)。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。

関連項目:

tprmend(3c)

2.110 tpsblktime(3c)

名前

tpsblktime() - 次のサービス呼出しまたはすべてのサービス呼出しのブロック時間を秒単位またはミリ秒単位で設定するルーチン

形式

#include <atmi.h>
int tpsblktime(int blktime,long flags)

説明

tpsblktime()は、潜在的なブロッキングAPIのブロック時間値を秒単位またはミリ秒単位で設定するために使用します。潜在的なブロッキングAPIは、値としてフラグTBNOBLOCKを使用できるシステムAPIとして定義します。トランザクション・タイムアウト値には影響しません。

blktimeの値の範囲は0 - 32767です。フラグTPBLK_MILLISECONDが設定されると、範囲は0 - ら32767ミリ秒になります。フラグTPBLK_SECONDが設定されると、範囲は0から32767秒になります。次の例(ブロック時間)で示すように、有効なブロック時間値はSCANUNIT値の最も近い倍数に切り上げられます

ユーザーが設定したブロック時間値	Scanunit値	有効なブロック時間値
13	5	15
18	5	20

値0は、以前に設定されたブロック時間フラグ値が取り消されており、別のブロック時間フラグ値で設定されたブロック時間が優先されることを示します。tpsblktime()を呼び出さない場合は、UBBCONFIGファイルの*SERVICESセクションまたはデフォルトの*RESOURCESセクションのBLOCKTIME値が使用されます。

ノート:

tpsblktime()で設定したブロッキング・タイムアウトは、UBBCONFIGファイルの*SERVICESセクションおよび*RESOURCESセクションに設定されたBLOCKTIMEパラメータよりも優先されます。ブロック時間チェックの優先順位は次のとおりです: tpsblktime(TPBLK_NEXT)、tpsblktime(TPBLK_ALL)、*SERVICES、*RESOURCES

次に、有効なflagsの一覧を示します:

TPBLK_MILLISECOND

このフラグは、ブロック時間値をミリ秒単位で設定します。ミリ秒単位のブロック時間を設定するには、2つ目の引数フラグにTPBLK_MILLISECONDを指定する必要があります。そうしないと、最初の引数の単位が秒になります。SCANUNITの単位が、TUXCONFIGで秒になっている場合、TPBLK_MILLISECONDフラグを指定してtpsblktimeを呼び出すとエラーTPEINVALが返されます。

TPBLK_SECOND

このフラグは、ブロック時間値を秒単位で設定します。これはデフォルト動作です。

TPBLK_NEXT

このフラグは、次の潜在的なブロッキングAPIのブロック時間値を設定します。

呼び出されたAPIにTPNOBLOCKフラグが含まれている場合、tpsblktime (TPBLK_NEXT)は影響せず、ブロッキングなしの状態が継続します。

TPBLK_NEXTフラグ値は、その直後のAPI呼出しのTPBLK_ALLフラグ値をオーバーライドします。例:

tpsblktime(50,TPBLK_ALL)
tpcall(one)
tpsblktime(30,TPBLK_NEXT|TPBLK_MILLISECOND)
tpcall(two)
tpcall(three)

tpcall(two)には、tpsblktime (30,TPBLK_NEXT|TPBLK_MILLISECOND)を基に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]

無効な引数が指定されました。たとえば、blktimeの値が負数か、複数のブロック時間フラグ値(TPBLK_NEXT、TPBLK_ALL、TPBLK_NEXT|TPBLK_MILLISECOND、TPBLK_NEXT| TPBLK_SECOND、TPBLK_ALL|TPBLK_MILLISECOND、TPBLK_ALL|TPBLK_SECOND)が指定されました。

UBBCONFIGのSCANUNIT	tpsblktimeのフラグ	結果
秒単位	TPBLK_SECOND	成功
秒単位	TPBLK_MILLISECOND	失敗
ミリ秒単位	TPBLK_SECOND	成功
ミリ秒単位	TPBLK_MILLISECOND	成功

[TPERELEASE]

以前のリリースのTuxedoで実行されているワークステーション・ハンドラにアタッチされたクライアントでtpsblktime()が呼び出されました。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

関連項目:

tpcall(3c)、tpcommit(3c)、tprecv(3c)、tpgblktime(3c)、UBBCONFIG(5)

2.111 tpscmt(3c)

名前

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変数を参照)

flagsの有効な設定を次に示します:

TP_CMT_LOGGED

このフラグは、2フェーズ・コミット・プロトコルの第1フェーズによって第2フェーズの前にコミット決定が記録された後、tpcommit()から返ることを指定します。この設定は、tpcommit()の呼出し側に対するより速い反応を見込んでいます。だだし、第2フェーズの完了を待つ時間的な遅延のため、トランザクションの参加リソースが処理をヒューリスティックに完了する(すなわち、異常終了を示します)と決めるかもしれないという危険が存在します。この場合は、tpcommit()はすでに戻っているので、これを呼出し側に伝える方法はありません(ただし、リソース・マネージャがヒューリスティックな設定を行うと、Oracle Tuxedo ATMIシステムはメッセージをログ・ファイルに書き込みます)。正常な状態では、第1フェーズの間にコミットすることを約束している参加リソースは、第2フェーズでコミットします。一般に、ネットワークやサイトの障害が原因で問題が生じると、第2フェーズでヒューリスティックな判断がなされます。

TP_CMT_COMPLETE

このフラグは、2フェーズ・コミット・プロトコルが完全に終了してからtpcommit(3c)が終了することを指定します。この設定により、tpcommit()は第2フェーズのコミット中にヒューリスティックな判断がなされたことを示すことができます。

マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドは、tpscmt()の呼出しを発行できません。

戻り値

成功の場合、tpscmt()はTP_COMMIT_CONTROL特性の以前の値を返します。

異常終了すると、tpscmt()は -1を返し、tperrnoを設定してエラー条件を示します。

エラー

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

[TPEINVAL]

flagsは、TP_CMT_LOGGEDまたはTP_CMT_COMPLETEのいずれかではありません。

[TPEPROTO]

tpscmt()が不正に呼び出されました。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。

注意事項

Oracle Tuxedo ATMIシステムのトランザクションを記述するためにtpbegin()、tpcommit()、およびtpabort()を使用する場合、XAインタフェースに準拠した(呼出し側に妥当にリンクされている)リソース・マネージャが行う作業のみがトランザクションのプロパティを備えていることを記憶しておくことが重要です。トランザクションにおいて実行される他のすべての操作は、tpcommit()あるいはtpabort()のいずれにも影響されません。

そのリソース・マネージャが行った処理がOracle Tuxedo ATMIシステムのトランザクションの一部となるよう、XAインタフェースを満たすリソース・マネージャをサーバーにリンクする方法については、「buildserver(1)」を参照してください。

関連項目:

tpabort(3c)、tpbegin(3c)、tpcommit(3c)、tpgetlev(3c)

2.112 tpseal(3c)

名前

tpseal() - 暗号化のための型付きメッセージ・バッファをマークします。

形式

#include <atmi.h>
int tpseal(char *data, TPKEY hKey, long flags)

説明

tpseal()は、暗号化するメッセージ・バッファをマーク(登録)します。hKeyを所有するプリンシパルは、このバッファを復号化し、その内容にアクセスすることができます。tpseal()を何度か呼び出すことによって、複数の受信者のプリンシパルに1つのバッファを指定できます。

dataは、(1)以前tpalloc()を呼び出すプロセスによって割り当てられたメッセージ・バッファ、または(2)システムによって受信プロセスに渡されたメッセージ・バッファのうち、いずれかの有効な型付きメッセージ・バッファを指している必要があります。バッファの内容は、tpseal()を呼び出した後で修正することができます。

dataが指すメッセージ・バッファがプロセスから伝送されると、公開キー・ソフトウェアがメッセージ内容を暗号化し、各暗号化登録リクエストのメッセージ・バッファに暗号化エンベロープをアタッチします。暗号化エンベロープによって、受信プロセスはメッセージを復号化することができます。

引数flagsは使用されません。この引数は将来の用途のために予約されており、0に設定します。

戻り値

異常終了すると、この関数は-1を返し、tperrnoを設定してエラー条件を示します。

エラー

[TPEINVAL]

無効な引数が指定されました。たとえば、hKeyが暗号化に有効なキーでないか、またはdataがNULLです。

[TPESYSTEM]

エラーが発生したことを示す。詳細は、システム・エラーのログ・ファイルを調べてください。

関連項目:

tpkey_close(3c)、tpkey_open(3c)

2.113 tpsend(3c)

名前

tpsend() - 会話型接続でメッセージを送信するルーチン。

形式

#include <atmi.h>
int tpsend(int cd, 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のタイプとサブタイプは、接続の他方の側が認識するタイプおよびサブタイプのいずれかと一致しなければなりません。

次に、有効なflagsの一覧を示します:

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()の呼出しを発行できません。

戻り値

reventがTPEV_SVCSUCCまたはTPEV_SVCFAILのどちらかに設定されている場合に、tpsend()が終了した場合は、グローバル変数tpurcode()には、tpreturn()の一部として送信されるアプリケーション定義の値が含まれます。関数tpsend()はエラー時には -1を返し、tperrnoを設定してエラーの条件を示します。また、イベントが存在し、かつエラーが発生しなかった場合、tpsend()は-1を返し、tperrnoは[TPEEVENT]に設定されます。

エラー

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

[TPEINVAL]

無効な引数が指定されました(たとえば、dataがtpalloc()によって割り当てられたバッファを指していない場合、flagsが無効である場合など)。

[TPEBADDESC]

cdが無効です。

[TPETIME]

このエラー・コードは、タイムアウトが発生したか、または現在のトランザクションがすでに「ロールバックのみ」とマークされているにもかかわらずtpsend()が試行されたことを示します。

呼出し側がトランザクション・モードの場合、トランザクションはすでにロールバックのみであるか、またはトランザクション・タイムアウトが発生しました。このトランザクションは、「中断のみ」とマークされます。呼出し側がトランザクション・モードでない場合、ブロッキング・タイムアウトが発生しています。(ブロッキング・タイムアウトは、TPNOBLOCKまたはTPNOTIMEが指定されている場合は発生しません。)

トランザクション・タイムアウトが発生した場合、トランザクションが中断されないかぎり、新しいリクエストの送信や未処理の応答の受信はできず、TPETIMEが発生します。その例外とは、ブロックされず、応答を期待せず、かつ呼出し側のトランザクションのかわりに送信されない(つまり、TPNOTRAN、TPNOBLOCKおよびTPNOREPLYを設定してtpacall()を呼び出した場合の)リクエストです。

トランザクションATMI呼出しがトランザクション内部で失敗すると、そのトランザクションはTX_ROLLBACK_ONLY状態になります。ほとんどの場合、この状態はタイムアウトと同じものとして扱われます。このトランザクションの以降のATMI呼出しは、すべてTPETIMEで異常終了します(前の段落で説明した例外を除く)。

[TPEEVENT]

イベントが発生しました。このエラーが発生すると、dataは送信されません。イベントのタイプは、reventに戻されます。

[TPEBLOCK]

ブロッキング状態のため、TPNOBLOCKが指定されました。

[TPGOTSIG]

シグナルを受け取りましたが、TPSIGRSTRTが指定されていません。

[TPEPROTO]

tpsend()が不正なコンテキストで呼び出されました(たとえば、呼出しプログラムがデータの受信のみを行えるよう接続が確立されている場合など)。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。

関連項目:

tpalloc(3c)、tpconnect(3c)、tpdiscon(3c)、tprecv(3c)、tpservice(3c)

2.114 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

会話の接続リクエストが受け入れられており、会話の記述子がcdで使用できます。このフラグが設定されていなければ、これはリクエスト/レスポンス型サービスであり、cdは無効です。

TPTRAN

サービス・ルーチンはトランザクション・モードにあります。

TPNOREPLY

呼出し側は応答を期待していません。このオプションは、TPCONVが設定されている場合には設定されません。

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構造体には、次のようなメンバーが含まれます。

long clientdata[4];

ノート:

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)

2.115 tpsetcallinfo(3c)

名前

tpsetcallinfo() - Tuxedoリクエストに帯域外情報を追加するルーチン。

形式

int tpsetcallinfo(const char *msg, FBFR32 *obuf, long flags)

説明

tpsetcallinfo()は、既存のTuxedo型メッセージに帯域外データを追加するために使用されます。次のパラメータをサポートしています。

msg

型付きバッファは帯域外データを付加するために使用されます。このバッファは、tpalloc()をコールするプロセスによって割り当てられており、後続のtpcall()でidataとして使用されている必要があります。

obuf

フィールドを使うために使用されるFML32バッファ。

flags

将来の使用のために予約されています。

tpsetcallinfoは、次のユースケースで使用できます:

• ターゲット・サービスがGWWSゲートウェイを介してアクセスされたHTTP/RESTまたはSOAP Webサービスの場合に、送信HTTPまたはSOAPコールにカスタムHTTPまたはSOAPヘッダーを追加します。

ノート:

この機能は、HTTPプロトコル自体に影響を与える可能性のあるHTTPヘッダーを追加します。そのため、tpsetcallinfo() APIを使用する際は注意が必要です。カスタムHTTPヘッダーは、他のヘッダーの最後に追加され、多くの場合は問題は発生しません。ただし、関連するアプリケーション・サーバーによってはこれが保証されるものではありません。たとえば、Content-Length: nnnを設定すると、リクエストまたはレスポンスが拒絶されたり誤った操作が行われる場合があります。アプリケーション・プログラマは、他のパーティ(たとえば、アプリケーション・サーバー、HTTPサーバーまたはSOAPクライアント・プログラミング・キットなど)に影響する可能性のあるヘッダーを採用しないように注意する必要があります。

• ターゲット・サービスがGWWSゲートウェイを介してアクセスまたはコールされたSOAP Webサービスの場合に、送信SOAPメッセージ(リクエストまたは応答)にカスタムSOAPヘッダーを追加します。
• Tuxedoメッセージ・タグ(1024文字までのアウト・オブ・バンドの文字列情報)を追加します。その値は、tpgetcallinfo()を使用して取得できます。それは、リクエスト・メッセージに追加されるとコール・パス全体に伝播されます。複数のTuxedoメッセージ・タグ値を設定した場合、後のもので以前のものが上書きされます。

ノート:

会話型サーバーは、Tuxedoメッセージ・タグを自動的に伝播しません。

次の表に、FML名を示します:

フィールド	タイプ	説明
TA_HTTP_HEADER_NAME	string	HTTPヘッダー名部分
TA_HTTP_HEADER_VALUE	string	HTTPヘッダー値部分
TA_HTTP_CONNECT_URI	string	この値はアウトバウンド・サービスURIをオーバーライドします。
TA_SOAP_HEADER	fml32	発信メッセージに追加されるSOAPヘッダー。このデータは、通常のSALTマッピング・ルールに従ってXMLにマップされます。 詳細は、「Oracle SALTデータ型のマッピングとメッセージの変換」を参照してください。
TA_MSGTAG	string	Tuxedoメッセージ・タグ

戻り値

モニタリング属性を含むFML32バッファの取得に成功すると、0が返されます。

異常終了すると、tpsetcallinfo()は-1を返し、tperrnoを設定してエラー条件を示します。

エラー

失敗すると、tpsetcallinfo()はtperrnoを次のいずれかの値に設定します。

[TPEINVAL]

無効な引数が指定されました(たとえば、msgがNULLである場合、あるいはobufが無効なFML32バッファである場合など)

[TPESYSTEM]

メッセージ入力にモニタリング属性が含まれていません。これは、メッセージに対して呼出しパス・モニタリングをオンにしていないためです。

[TPEOS]

オペレーティング・システムのエラーが発生しました。

使用例

クライアント側tpsetcallinfoの例は、次のとおりです。

{
  FBFR32 *request;
  FBFR32 *metainfo;
  char name[50];
  char value[50];
  char msgtag[] = "0052kRkQAev9XbHpIsT4if0007zK000000";
  FLDLEN32 len;
  int len = 0;
  /* Allocate the metainfo space */
  metainfo = tpalloc("FML32", NULL, 1024);
  if (metainfo == NULL ) {
    userlog("Memory allocation failed");
    tpreturn(TPFAIL, 0, 0, 0);
  }
  request = tpalloc("STRING", NULL, 1024);
  /* Set custom headers */
  strcpy(name, "header_name");
  strcpy(value, "header_value");
  len = strlen(name);
  if (Fchg32(metainfo, TA_HTTP_HEADER_NAME, 0, name, len) < 0) {
    F_error32("program_name");
    tpfree(request);
    tpfree(metainfo);
    exit(1);
  }
  len = strlen(value);
  if (Fchg32(metainfo, TA_HTTP_HEADER_VALUE, 0, value, len) < 0) {

    tpfree(request);
    tpfree(metainfo);
    exit(1);
  }
  len = strlen(msgtag);
  if (Fchg32(metainfo, TA_MSGTAG, 0, msgtag, len) < 0) {
    F_error32("message tag");
    tpfree(request);
    tpfree(metainfo);
    exit(1);
  }
  if ( tpsetcallinfo(request, metainfo, 0) < 0 ) {
    userlog("an error occurred when attaching metainfo to the buffer");
    tpfree(request);
    tpfree(metainfo);
    exit(1);
  }
  strcpy(request, "this_is_the_request");
  response = tpalloc("STRING", NULL, 1024);
  rlen = 1024;
  if (tpcall(svc_name,(char *)request, 0, (char **)&response,(long *)&rlen, 0) == -1) {
    (void)fprintf (stderr, "%s service failed\n\n", svc_name);
    tpfree(response);
    tpfree(request);
    tpfree(metainfo);
    exit(1);
  }
}

関連項目:

tpgetcallinfo(3c)

2.116 tpsetctxt(3c)

名前

tpsetctxt() - 現在のアプリケーション関連にコンテキスト識別子を設定します。

形式

#include <atmi.h>
int tpsetctxt(TPCONTEXT_T context, long flags)

説明

tpsetctxt()は、現在のスレッドが動作するコンテキストを定義します。この関数は、マルチスレッド環境ではスレッド単位で、非スレッド環境ではプロセス単位で動作します。

次にこのスレッドでOracle Tuxedo ATMIが呼び出されると、コンテキストが示すアプリケーションが参照されます。コンテキストは、同一プロセス内のスレッドでtpgetctxt()の呼出しを発行することによって提供されます。contextの値がTPNULLCONTEXTの場合、現在のスレッドはどのOracle Tuxedo ATMIコンテキストにも関連付けられません。

マルチコンテキスト・モードで動作しているプロセスの各スレッドでは、次の呼出しを発行するによって、TPNULLCONTEXT状態にすることができます。

tpsetctxt(TPNULLCONTEXT, 0)

TPINVALIDCONTEXTは、contextに入力できる有効な値ではありません。

TPINVALIDCONTEXT状態のスレッドは、ほとんどのATMI関数に対する呼出しを発行できません。(呼び出せる関数と呼び出せない関数のリストについては、「C言語アプリケーション・トランザクション・モニター・インタフェースの紹介」を参照してください。)このため、必要に応じてスレッドのTPINVALIDCONTEXT状態を終了させる必要があります。それには、コンテキストをTPNULLCONTEXTか別の有効なコンテキストに設定してtpsetctxt()を呼び出します。(また、tpterm()関数を呼び出してTPINVALIDCONTEXT状態を終了させることもできます。)

2番目の引数flagsは現在使用されておらず、0に設定する必要があります。

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

戻り値

tpsetctxt()は、正常終了時には0以外の値を返します。

異常終了すると、呼出しプロセスを元のコンテキストに置いたまま-1を返し、tperrnoを設定してエラー条件を示します。

エラー

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

[TPEINVAL]

無効な引数が指定されました。たとえば、flagsが0以外の値に設定されたか、またはコンテキストがTPINVALIDCONTEXTです。

[TPENOENT]

contextの値が有効なコンテキストではありません。

[TPEPROTO]

tpsetctxt()が不正なコンテキストで呼び出されました。たとえば、(a)サーバーがディスパッチしたスレッドで呼び出された、(b) tpinit()を呼び出していないプロセスで呼び出された、(c) TPMULTICONTEXTSフラグを指定せずにtpinit()を呼び出したプロセスで呼び出された、または(d) TMNOTHREADS環境変数がオンになっているプロセスで複数のスレッドから呼び出された、などです。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質は、ログ・ファイルに書き込まれます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。

関連項目:

「C言語アプリケーション・トランザクション・モニター・インタフェースの紹介」、tpgetctxt(3c)

2.117 tpsetmbenc(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]

bufまたはenc_name引数の値がNULLです。あるいは、enc_nameに指定した名前が無効です。

[TPESYSTEM]

Tuxedoシステムのエラーが発生しました(たとえば、bufpが有効なTuxedoバッファに対応していないため、バッファのエンコード名を追加または削除できませんでした)

関連項目:

tpalloc(3c)、tpconvmb(3c)、tpgetmbenc(3c)、tpservice(3c)、tuxsetmbenc(3c)

2.118 tpsetrepos(3c)

名前

tpsetrepos() - Tuxedoサービス・メタデータ・リポジトリ・ファイルからのサービス・パラメータ情報を追加、編集または削除します

形式

int tpsetrepos(char *reposfile, FBFR32* idata, FBFR32** odata)

説明

tpsetrepos()は、TMMETADATA(5)によって提供される.TMMETAREPOSサービスに、代替リポジトリ・アクセス・インタフェースを提供します。Tuxedoサービス・メタデータ・リポジトリ・ファイルからのパラメータ情報を追加、編集または削除します。tpsetrepos()を使用するには、メタデータ・リポジトリ・ファイルが、要求元のネイティブ・クライアントまたはサーバーに存在している必要があります。これにより、TMMETADATA(5) を開始していない場合でも、リポジトリ情報へのアクセスが可能になります。

tpsetrepos()は、Oracle Tuxedoネイティブ・ライブラリにリンクされたプロセスで使用できますが、Oracle Tuxedoワークステーション・ライブラリにリンクされたプロセスでは使用できません。

reposfile

Tuxedoメタデータ・リポジトリがある現在のマシンでアクセス可能なファイルのパス名を指定します。ユーザーは、このファイルの読取り/書込みパーミッションを持っている必要があります。

idata

追加、編集、または削除するサービスの情報の種類を指定し、FML32バッファを指します。

*odata

出力に対して、取得するサービスの情報とオペレーションのステータスを格納したFML32バッファを指します。

「METAREPOS(5)」 では、tpsetrepos()usesが使用するFML32バッファ形式について説明します。これは、MIB(5)で使用する形式と同じです。

戻り値

tpsetrepos()は、成功した場合に0を返します。異常終了した場合は、tperrnoを設定し、-1を返します。ほとんどの異常終了では、Tuxedo MIBの場合と同様に、*odataのTA_ERRORフィールドに特定のエラーに関する情報が格納されています。

エラー

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

ノート:

TPEINVALの場合を除き、odataは、エラー条件についてさらに詳しい情報が得られるように、サービス・エントリごとにTA_ERROR、TA_STATUSを含める形で変更されます。

[TPEINVAL]

無効な引数が指定されました。reposfileの値が無効であるか、idataまたはodataはFML32型付きバッファへのポインタではありません。

[TPEMIB]

MIBと同種のリクエストが失敗しました。odataが更新され、MIB(5)で説明するエラーの原因を示すFML32のフィールドが設定され、呼出し側に返されました。

[TPEPROTO]

tpsetrepos()が不正に呼び出されました。指定したreposfileファイル引数は、有効なリポジトリ・ファイルではありません。

[TPEOS]

オペレーティング・システムのエラーが発生しました。失敗したシステム・コールを示す数値がUunixerrに入っています。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。このエラーの正確な性質はuserlog()で報告されます。

移植性

このインタフェースは、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)tpsetrepos(3c)、TMMETADATA(5)、『Oracle Tuxedoアプリケーションの設定』の「Oracle Tuxedoサービス・メタデータ・リポジトリの管理」

2.119 tpsetunsol(3c)

名前

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]

tpsetunsol()が不正なコンテキストで呼び出されました。たとえば、サーバー内部から呼び出されています。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。

移植性

tpnotify(3c)に記述されているインタフェースは、ネイティブ・サイトのUNIXベースのプロセッサおよびWindowsプロセッサ上でサポートされています。さらに、ルーチンtpbroadcast()とtpchkunsol(),は、関数tpsetunsol(),と共に、UNIXシステムおよびMS-DOSベースのプロセッサ上で利用することができます。

関連項目:

tpinit(3c)、tpterm(3c)

2.120 tpsign(3c)

名前

tpsign() - デジタル署名のための型付きメッセージ・バッファをマークします。

形式

#include <atmi.h>
int tpsign(char *data, TPKEY hKey, long flags)

説明

tpsign()は、hKeyに関連するプリンシパルにかわって、デジタル署名のためのメッセージ・バッファをマーク(登録)します。

dataは、(1)以前tpalloc()を呼び出すプロセスによって割り当てられたメッセージ・バッファ、または(2)システムによって受信プロセスに渡されたメッセージ・バッファのうち、いずれかの有効な型付きメッセージ・バッファを指している必要があります。バッファの内容は、tpsign()を起動してから修正することができます。

dataが指すバッファがプロセスから伝送されると、デジタル署名登録リクエストに対して、公開キー・ソフトウェアがデジタル署名を生成し、メッセージ・バッファにアタッチします。デジタル署名によって、受信プロセスはメッセージの署名者(発信者)を検証することができます。

引数flagsは将来の用途のために予約されており、0に設定する必要があります。

戻り値

異常終了時には、この関数は-1を返し、tperrnoを設定してエラー条件を示します。

エラー

[TPEINVAL]

無効な引数が指定されました。たとえば、hKeyが署名に有効なキーでないか、またはdataの値がNULLです。

[TPESYSTEM]

エラーが発生しました。詳細は、システム・エラーのログ・ファイルを調べてください。

関連項目:

tpkey_close(3c)、tpkey_open(3c)

2.121 tpsprio(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()はスレッド単位で動作します。

次に、有効なflagsの一覧を示します。

TPABSOLUTE

次のリクエストの優先度は、prioの絶対値で送信されます。prioの絶対値は、1以上100以下の範囲内にある必要があります(最も高い優先度は100です)。この範囲外の値を指定すると、デフォルトの値が使用されます。

マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドは、tpsprio()の呼出しを発行できません。

戻り値

異常終了すると、tpsprio()は -1を返し、tperrnoを設定してエラー条件を示します。

エラー

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

[TPEINVAL]

flagsが無効です。

[TPEPROTO]

tpsprio()が不正に呼び出されました。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。

関連項目:

tpacall(3c)、tpcall(3c)、tpdequeue(3c)、tpenqueue(3c)、tpgprio(3c)

2.122 tpstrerror(3c)

名前

tpstrerror() - Oracle Tuxedo ATMIシステム・エラーのエラー・メッセージ文字列を取得します。

形式

#include <atmi.h>
char *
tpstrerror(int err)

説明

tpstrerror()はLIBTUX_CATからエラー・メッセージのテキストを取得するために使用します。errは、Oracle Tuxedo ATMIシステムの関数呼出しが-1またはその他の異常終了値を返した場合にtperrnoに設定されるエラー・コードです。

tpstrerror()によって戻されたポインタをuserlog()またはUNIX関数fprintf()に対する引数として使用できます。

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

戻り値

正常終了すると、tpstrerror()はエラー・メッセージ・テキストを含む文字列を指すポインタを返します。

errが無効なエラー・コードであった場合は、tpstrerror()は、NULLを返します。

エラー

異常終了すると、tpstrerror()はNULLを返しますがtperrnoは設定しません。

例

if (tpbegin(10,0) == -1) {
  p = tpstrerror(tperrno);
  userlog(“%s”, p);
  (void)tpabort(0);
  (void)tpterm();
  exit(1);
}

関連項目:

userlog(3c)、Fstrerror、Fstrerror32(3fml)

2.123 tpstrerrordetail(3c)

名前

tpstrerrordetail() - Oracle Tuxedo ATMIシステム・エラーのエラー詳細メッセージの文字列を取得します。

形式

#include <atmi.h>
char * tpstrerrordetail(int err, long flags)

説明

tpstrerrordetail()は、Oracle Tuxedo ATMIシステム・エラーのエラー詳細テキストを取得するために使用します。errは、tperrordetail()によって戻される値です。

ユーザーは、tpstrerrordetail()が返したポインタをuserlog()またはUNIX関数fprintf()に対する引数として使用できます。

現在、flagsは将来の用途のために予約されており、0に設定する必要があります。

マルチスレッドのアプリケーション中のスレッドは、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)

2.124 tpsubscribe(3c)

名前

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と呼ばれるイベントは、どちらも登録の対象となります。正規表現の詳細は、268ページの「正規表現」を参照してください。

filterを指定する場合は、ブール値のフィルタ・ルールを含む文字列を指定します。このルールは、イベント・ブローカがイベントをポストする前に正しく評価しなければなりません。ポストするイベントを受け取ると、EventBrokerはそのイベントのデータにフィルタ規則(存在する場合)を適用します。データがフィルタ・ルールのチェックにパスした場合、イベント・ブローカは通知メソッドを呼び出します。データがフィルタ・ルールを通過しない場合は、イベント・ブローカは対応する通知メソッドを呼び出しません。呼出し側は、異なるフィルタ・ルールを利用して同じイベントを何度でもサブスクライブすることができます。

フィルタ・ルールは、それが適用される型付きバッファに固有なものです。FMLバッファおよびVIEWバッファの場合は、フィルタ・ルールはそれぞれのブール式コンパイラ(それぞれFboolco(3fml)およびFvboolco(3fml)を参照)に渡すことができて、ポストされたバッファ(Fboolev(3fml)およびFboolev(3fml)を参照)に対して評価することができる文字列です。STRINGバッファの場合は、フィルタ・ルールは正規表現です。他のすべてのタイプのバッファの場合、カスタマイズしたフィルタ評価機構が必要です(カスタマイズしたフィルタ評価機構を追加する方法の詳細は、「buffer(3c)」および「typesw(5)」を参照してください)。filterには、最大255文字のNULLで終了する文字列を指定します。

サブスクライバがOracle Tuxedo ATMIシステムのクライアント・プロセスで、ctlがNULLの場合は、サブスクライブしているイベントがポストされたときに、イベント・ブローカはサブスクライバに非請求メッセージを送ります。つまり、eventexprに対して評価が成功するイベント名がポストされると、イベント・ブローカは、eventexprに関連するフィルタ・ルールに対して、ポストされたデータをテストします。データがフィルタ・ルールによるチェックにパスした場合、あるいはそのイベントに対して適用すべきフィルタ・ルールが存在しない場合は、サブスクライバはイベントとそのデータ、および非請求メッセージを受け取ることになります。非請求メッセージを受け取るためには、クライアントは非請求通知処理ルーチンを(tpsetunsol()を利用して)登録しておく必要があります。Oracle Tuxedo ATMIシステムのサーバー・プロセスが、ctlパラメータをNULLにしてtpsubscribe()を呼び出した場合は、tpsubscribe()は異常終了してtperrnoをTPEPROTOに設定します。

非請求メッセージによってイベント通知を受け取るクライアントは、終了する前にイベント・ブローカのアクティブなサブスクリプションのリストから、そのサブスクリプションを削除する必要があります(詳細は、「tpunsubscribe(3c)」を参照してください)。クライアントは、tpunsubscribe()のワイルドカード・ハンドル、-1を使用することにより、非請求通知メソッドに関連するサブスクリプションを含むあらゆる「非永続的」サブスクリプションを削除することができます。プロセス終了後も存続するサブスクリプションおよびそれらに関連する通知メソッドについては、以下のTPEVPERSISTの説明を参照してください。クライアントが非持続型のサブスクリプションを削除せずに終了した場合は、イベント・ブローカはクライアントにアクセスできなくなったことを検出すると、そのクライアントのサブスクリプションを削除します。

サブスクライバが(プロセス・タイプにかかわらず)イベント通知をサービス・ルーチンまたは安定ストレージ内のキューに送りたい場合は、ctlパラメータは有効なTPEVCTL構造体を指さなければいけません。この構造体には次の要素が含まれます。

long flags;
char name1[128];
char name2[128];
TPQCTL qctl;

ノート:

サービス名の長さは127バイト以内に制限されています。サービス名の長さが127バイトを超える場合は、TPEINVALが戻されます。

次に、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は、相互に排他的なフラグです。

TPEVTRANも同時にctl−>flagsに設定し、またtppost()を呼び出すプロセスがトランザクション・モードにある場合は、イベント・ブローカは、ポストされたイベントとそのデータがポスト元のトランザクションの一部となるように、それらをキューに登録します。イベント・ブローカTMUSREVT(5)は、トランザクションをサポートするサーバー・グループに属している必要があります(詳細は、UBBCONFIG(5)に関する項を参照してください)。ctl−>flagsにTPEVTRANを設定していない場合は、イベント・ブローカは、ポストされたイベントとそのデータがポスト元のトランザクションの一部とならないように、それらをキューに登録します。

TPEVTRAN

このフラグを設定することは、このサブスクリプションのイベント通知が存在する場合に、サブスクライバがこれをポスト元のトランザクションに含めることを希望していることを示します。ポスト元がトランザクション以外の場合、このイベントを通知するためにトランザクションが開始されます。このフラグを設定しない場合は、このサブスクリプションに対してポストされたいかなるイベントも、ポスト元が参加しているどのトランザクションのかわりに実行させることはできません。このフラグは、TPEVSERVICEまたはTPEVQUEUEのどちらかと同時に指定できます。

TPEVPERSIST

デフォルトでは、Oracle Tuxedoのイベント・ブローカは、通知先のリソースが使用不可能である場合はサブスクリプションを削除します。たとえば、イベントのサブスクリプションに関連するサービス・ルーチン、またはキュー・スペースとキューにイベント・ブローカがアクセスできない場合などです。このフラグを設定することは、そのようなエラーが発生してもサブスクリプションが持続するように(多くの場合、リソースは後で利用できるようになるため)サブスクライバが求めることを示します。このフラグを設定しない場合、このサブスクリプションで指定されたサービス名またはキュー・スペース名/キュー名のいずれかへのアクセス時にエラーが発生すると、イベント・ブローカはこのサブスクリプションを削除します。

このフラグを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()の呼出しを発行できません。

正規表現

表17で説明する正規表現は、UNIXシステム・エディタ、ed(1)で使用されるパターンに似ています。一般的な正規表現のほか、代替演算子(|)も使用できます。ただし、全体的にほとんど変わりません。

正規表現(RE)は、次に示すいずれかの規則を1回以上適用して作成します。

ルール	一致するテキスト
文字	文字(文字とは、後述の特殊文字を除く任意のASCII文字)
\文字	それ自身(次に示すものを除く) \\ - 改行 \\t - タブ \\b - バックスペース \\r - 復帰 \\f - フォーム・フィード
\特殊文字	非特殊文字。特殊文字とは、.* + ? | ( ) [ {および\\です。 . - 行末文字(通常は改行文字またはNULL文字)以外の任意の文字 ^ - 行頭 $ - 行末文字。
[クラス]	一連の文字または範囲、あるいはその両方で表すクラス内の任意の文字。範囲は、character-characterという形式で指定されます。たとえば、文字クラス[a-zA-Z0-9_]は、英数字またはアンダースコア"_"と一致します。ハイフン("-")をクラスに含めるためには、"¥¥"の後のハイフンをエスケープするか、クラス内の先頭または終わりに指定する必要があります。リテラル"]"の場合は、エスケープするか、またはクラスの先頭に指定します。リテラル"^"がクラスの先頭にある場合は、エスケープする必要があります。
[^クラス]	行末文字を除く、クラスの補集合におけるASCII文字セットに関する文字
RE RE	正規表現のシーケンス。(連結)
RE | RE	左側のREまたは右側のRE (左右の二者択一)
RE *	REが0回以上発生
RE +	REが1回以上発生
RE ?	REが0回または1回発生
RE { n }	REがn回発生。nの範囲は0 - 255です。
RE { m, n }	REがm回以上n回以下発生。mが指定されない場合は0になります。nが指定されない場合は、REがm回以上発生することを示します。
( RE )	優先順位またはグループ化を明示的に示します。
( RE ) $ n	REと一致するテキストがn番目のユーザー・バッファにコピーされます。nは0から9までです。ユーザー・バッファは、照合が開始する前にクリアされ、パターン全体が一致した場合のみロードされます。

優先順位のレベルは3つあります。結合の強さの順に並べると、次のようになります。

• 連結閉包(*,+,?,{...})
• 連結
• 代替(|)

前述のとおり、かっこは優先順位が高いことを明示的に示すために使用します。

戻り値

tpsubscribe()は正常終了すると、イベント・ブローカのアクティブなサブスクリプションのリストからこのサブスクリプションを削除するために使用できるハンドルを戻します。サブスクライバやその他のプロセスは、いずれも戻されたハンドルを利用してこのサブスクリプションを削除することができます。

異常終了すると、tpsubscribe()は -1を返し、tperrnoを設定してエラー条件を示します。

エラー

異常終了時には、tpsubscribe()はtperrnoを次のいずれかの値に設定します。(特に記述した場合を除いては、エラーが呼出し側のトランザクションに影響を及ぼすことはありません。)

[TPEINVAL]

無効な引数が指定されました(たとえば、eventexprがNULLである場合など)。

[TPENOENT]

Oracle Tuxedoイベント・ブローカにアクセスできません。

[TPELIMIT]

イベント・ブローカの最大サブスクリプション数に達したため、サブスクリプションが失敗しました。

[TPEMATCH]

イベント・ブローカのリストにすでに存在するサブスクリプションと一致するため、サブスクリプションが異常終了しました。

[TPEPERM]

クライアントはtpsysadmとしてアタッチされず、サブスクリプションのアクションは、サービスの呼出しか、メッセージのキューへの登録になります。

[TPETIME]

このエラー・コードは、タイムアウトが発生したか、または現在のトランザクションがすでに「ロールバックのみ」とマークされているにもかかわらずtpsubscribe()が試行されたことを示します。

呼出し側がトランザクション・モードの場合、トランザクションはすでにロールバックのみであるか、またはトランザクション・タイムアウトが発生しました。このトランザクションは、「中断のみ」とマークされます。呼出し側がトランザクション・モードでない場合、ブロッキング・タイムアウトが発生しています。(ブロッキング・タイムアウトは、TPNOBLOCKまたはTPNOTIMEが指定されている場合は発生しません。)

トランザクション・タイムアウトが発生した場合、トランザクションが中断されないかぎり、新しいリクエストの送信や未処理の応答の受信はできず、TPETIMEが発生します。その例外とは、ブロックされず、応答を期待せず、かつ呼出し側のトランザクションのかわりに送信されない(つまり、TPNOTRAN、TPNOBLOCKおよびTPNOREPLYを設定してtpacall()を呼び出した場合の)リクエストです。

トランザクションATMI呼出しがトランザクション内部で失敗すると、そのトランザクションはTX_ROLLBACK_ONLY状態になります。ほとんどの場合、この状態はタイムアウトと同じものとして扱われます。このトランザクションの以降のATMI呼出しは、すべてTPETIMEで異常終了します(前の段落で説明した例外を除く)。

[TPEBLOCK]

ブロッキング状態のため、TPNOBLOCKが指定されました。

[TPGOTSIG]

シグナルを受け取りましたが、TPSIGRSTRTが指定されていません。

[TPEPROTO]

tpsubscribe()が不正に呼び出されました。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

[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)

2.125 tpsuspend(3c)

名前

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]

tranidがNULLポインタであるか、またはflagsが0ではありません。トランザクションに関する呼出し側の状態は変化しません。

[TPEABORT]

呼出し側のアクティブなトランザクションが中断されました。トランザクションに関連するすべてのコミュニケーション記述子は、有効ではなくなります。

[TPEPROTO]

tpsuspend()が不正なコンテキストで呼び出されました(たとえば、呼出し側がトランザクション・モードでないなど)。トランザクションに関する呼出し側の状態は変化しません。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。

関連項目:

tpacall(3c)、tpbegin(3c)、tprecv(3c)、tpresume(3c)、tprmopen(3c)、tprmclose(3c)、tprmstart(3c)、tprmend(3c)

2.126 tpsvrdone(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)

2.127 tpsvrinit(3c)

名前

tpsvrinit() - Oracle Tuxedoシステム・サーバーを初期化します。

形式

#include <atmi.h>
int tpsvrinit(int argc, 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)

2.128 tpsvrthrdone(3c)

名前

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)

2.129 tpsvrthrinit(3c)

名前

tpsvrthrinit() - Oracle Tuxedo ATMIサーバー・スレッドを初期化します。

形式

#include <atmi.h>
int tpsvrthrinit(int argc, char **argv)

説明

Oracle Tuxedo ATMIサーバーでは、ディスパッチされたサービス・リクエストを処理する各スレッドを初期化するときに、tpsvrthrinit()を呼び出します。このルーチンは、制御のスレッドがOracle Tuxedo ATMIサーバーの一部になった後、スレッドが何らかのサービス・リクエストを処理する前に呼び出されます。このため、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システムの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)

C言語リファレンス・マニュアルのgetopt(3)

2.130 tpterm(3c)

名前

tpterm() - アプリケーションから分離します。

形式

#include <atmi.h>
int tpterm(void)

説明

tpterm()は、Oracle Tuxedo ATMIシステム・アプリケーションからクライアントを削除します。クライアントがトランザクション・モードであると、トランザクションはロールバックされます。tpterm()が正常に終了すると、呼出し側はOracle Tuxedo ATMIクライアント操作を実行できません。未終了の会話はただちに切断されます。

tpterm()を2回以上呼び出した場合(すなわち、呼出し側がすでにアプリケーションから離れた後で呼び出した場合)、何も処理は行われず、正常終了を示す値が返されます。

マルチスレッド化およびマルチコンテキスト化の問題

適切なプログラミングでは、1つを残して他のすべてのスレッドがコンテキストを終了または切り替えると、最後のスレッドがtpterm()呼出しを発行します。このようにプログラミングされていないと、残りのスレッドはTPINVALIDCONTEXTコンテキスト状態になります。次に、このコンテキストのセマンティクスを説明します:

複数のスレッドが関連するコンテキストにおいて、1つのスレッドでtpterm()が呼び出されると、このtpterm()は以下のように動作します。

• 1つのプロセス内のすべてのコンテキストではなく、1つのコンテキスト内のすべてのスレッド上で動作します。
• 同じプロセスの他のスレッドとそのコンテキストがまだ関連している場合でも、すぐに動作を実行します。

別のスレッドがコンテキストを終了したときにATMI呼出し内でブロックされたスレッドがあると、そのスレッドはATMI呼出しから異常終了によって返され、tperrnoはTPESYSTEMに設定されます。また、このような異常終了の後でtperrordetail()が呼び出された場合、tperrordetail()はTPED_INVALIDCONTEXTを返します。

シングル・コンテキストのアプリケーションでは、単一のスレッドがtpterm()を呼び出すと、すべてのスレッドのコンテキスト状態がTPNULLCONTEXTに設定されます。

それに対して、マルチコンテキストのアプリケーションでは、tpterm()が1つのスレッドで呼び出されると、同じコンテキスト内の他のすべてのスレッドは、ほとんどのATMI関数を呼び出しても異常終了し、tperrnoがTPEPROTOに設定されるような状態になります。このような無効なコンテキスト状態で使用できる関数と使用できない関数のリストについては、「C言語アプリケーション・トランザクション・モニター・インタフェースの紹介」を参照してください。無効なコンテキスト状態(TPINVALIDCONTEXT)のスレッドがtpgetctxt()関数を呼び出した場合、tpgetctxt()によってコンテキストのパラメータがTPINVALIDCONTEXTに設定されます。

TPINVALIDCONTEXT状態を終了させるには、次の関数のどちらかを呼び出します。

• TPNULLCONTEXTコンテキストまたは別の有効なコンテキストを設定したtpsetctxt()
• tpterm()

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]

tpterm()が不正なコンテキストで呼び出されました(たとえば、呼出し側がサーバーであるなど)。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。

関連項目:

tpinit(3c)、tpgetctxt(3c)、tpsetctxt(3c)、tpsetunsol(3c)。

2.131 tptypes(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]

無効な引数が指定されました(たとえば、ptrが\% tpalloc()から取得されたバッファを指していない場合など)。

[TPEPROTO]

tptypes()が不正に呼び出されました。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。

関連項目:

tpalloc(3c)、tpfree(3c)、tprealloc(3c)

2.132 tpunadvertise(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]

svcnameがNULLまたはNULL文字列("")です。

[TPENOENT]

svcnameはサーバーによって現在通知されていません。

[TPEPROTO]

tpunadvertise()が不正なコンテキストで呼び出されました(たとえば、クライアントによって)。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。

関連項目:

tpadvertise(3c)

2.133 tpunsubscribe(3c)

名前

tpunsubscribe() - イベントのサブスクリプションを削除します。

形式

#include <atmi.h>
int tpunsubscribe(long subscription, long flags)

説明

呼出し側はtpunsubscribe()を使用して、Oracle Tuxedoイベント・ブローカのアクティブなサブスクリプションのリストからイベントのサブスクリプションまたはイベントのサブスクリプションの集合を削除します。subscriptionには、tpsubscribe()が返したイベントのサブスクリプションのハンドルを指定します。subscriptionをワイルドカード値-1に設定すると、呼出し側プロセスが以前に行った非永続的サブスクリプションをすべて削除するようtpunsubscribe()に指示されます。非永続的サブスクリプションとは、tpsubscribe()のctl−>flagsパラメータにTPEVPERSISTビットが設定されずに行われたサブスクリプションです。永続的サブスクリプションは、tpsubscribe()から返されたハンドルを使用することによってのみ削除できます。

ノート:

-1ハンドルでは、呼出し側プロセスで作成されたサブスクリプションのみが削除され、呼出し側の以前のインスタンス化によって作成されたサブスクリプションは削除されません(たとえば、停止してから再起動したサーバーは、元のサーバーによって作成されたサブスクリプションをワイルドカードを使用して削除できません)。

次に、有効なflagsの一覧を示します:

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]

無効な引数が指定されました(たとえば、subscriptionが無効なサブスクリプション・ハンドルである場合など)。

[TPENOENT]

Oracle Tuxedoイベント・ブローカにアクセスできません。

[TPETIME]

このエラー・コードは、タイムアウトが発生したか、または現在のトランザクションがすでに「ロールバックのみ」とマークされているにもかかわらずtpunsubscribe()が試行されたことを示します。

呼出し側がトランザクション・モードの場合、トランザクションはすでにロールバックのみであるか、またはトランザクション・タイムアウトが発生しました。このトランザクションは、「中断のみ」とマークされます。呼出し側がトランザクション・モードでない場合、ブロッキング・タイムアウトが発生しています。(ブロッキング・タイムアウトは、TPNOBLOCKまたはTPNOTIMEが指定されている場合は発生しません。)

トランザクション・タイムアウトが発生した場合、トランザクションが中断されないかぎり、新しいリクエストの送信や未処理の応答の受信はできず、TPETIMEが発生します。その例外とは、ブロックされず、応答を期待せず、かつ呼出し側のトランザクションのかわりに送信されない(つまり、TPNOTRAN、TPNOBLOCKおよびTPNOREPLYを設定してtpacall()を呼び出した場合の)リクエストです。

トランザクションATMI呼出しがトランザクション内部で失敗すると、そのトランザクションはTX_ROLLBACK_ONLY状態になります。ほとんどの場合、この状態はタイムアウトと同じものとして扱われます。このトランザクションの以降のATMI呼出しは、すべてTPETIMEで異常終了します(前の段落で説明した例外を除く)。

[TPEBLOCK]

ブロッキング状態のため、TPNOBLOCKが指定されました。

[TPGOTSIG]

シグナルを受け取りましたが、TPSIGRSTRTが指定されていません。

[TPEPROTO]

tpunsubscribe()が不正に呼び出されました。

[TPESYSTEM]

Oracle Tuxedoシステムのエラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。

関連項目:

tppost(3c)、tpsubscribe(3c)、EVENTS(5)、EVENT_MIB(5)、TMSYSEVT(5)、TMUSREVT(5)

2.134 tputrace(3c)

名前

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)に関する項を参照してください。

tputrace(3c)の有効な引数は次のとおりです。

trrec

ユーザーによって定義されるトレース情報のレコード。ttrecは、tputrace(3c)の最初の引数として必ず指定されます。trrecをuserlogに出力すると、tmtrace(5)と同じ結果になります。

nest

ネストのレベルを定義します。tputrace(3c)出力行にインデントを追加する場合に使用します。

category

ATMI関数のカテゴリを「atmi」、「iatmi」、「xa」などと定義します。

funcname

関数名を定義します。たとえば、「tpcall」または「tconnect」です。

utrtype

tputrace(3c)をATMI関数の開始時または終了時に呼び出すかどうかを示します。開始時に呼び出すときは0、終了時に呼び出すときは1と設定します。

args

tputrace(3c)出力関数に渡す引数を定義します。これには、ATMI関数に渡されるユーザー・データまたはフラグが含まれます。「使用例」のtputrace()の実装例で、各ATMI関数の引数の一覧を示します。引数のリストは、tmtrace(5)トレース情報出力でも参照できます。

Libutraceライブラリ

独立したTuxedoライブラリであるlibutraceは、tputrace()と組み合せて使用します。デフォルトのlibutraceは、Tuxedoシステム共有ライブラリ・ディレクトリ(UNIXの場合は$TUXDIR/lib、Windowsの場合は%TUXDIR%\bin)にインストールされます。

ユーザーは、独自のカスタムlibutraceライブラリを作成し、それを次のいずれかにインストールすることもできます。

• Tuxedoシステム共有ライブラリ・ディレクトリ
• Tuxedoアプリケーション・ディレクトリ(UNIXの場合は$APPDIR、Windowsの場合は%APPDIR%)

システム・ディレクトリにインストールされたカスタム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の出力を示しています。

ユーザー・レベル・トレース情報をカスタマイズして出力するには、以下の操作を行う必要があります。

1. tputrace()を変更します。
2. libutraceライブラリを再コンパイルしてTuxedoにリンクします。

この例では、TMTRACE=atmi:utraceを指定した場合、ATMI関数に渡されるユーザー・データの内容とフラグがTuxedo userlogに書き込まれます。

リスト1 Simpappサンプルによるユーザー・レベル・トレース情報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
q

戻り値

tmutrace(3c)は、正常に実行された場合に0、障害が発生した場合に-1を返します。

エラー

障害は、tputrace()ユーザー・レベルの実装/カスタマイズによって異なります。Tuxedo 9.0以上に付属のデフォルトtputrace()実装では、障害は発生しません。

関連項目:

• tmtrace(5)
• userlog(3c)
• 『Oracle Tuxedoアプリケーション実行時の管理』の「Oracle Tuxedoアプリケーションのモニタリング」の実行時およびユーザー・レベルのトレース・ユーティリティの使用に関する項

2.135 tpxmltofml32(3c)

名前

tpxmltofml32() - XMLデータをFML32バッファに変換します

形式

#include <fml32.h>
int tpxmltofml32 (char *xmlbufp, char *vfile, FBFR32 **fml32bufp, char **rtag, long flags)

説明

この関数は、XMLバッファをFML32バッファに変換するために使用します。次の引数を使用できます。

xmlbufp

この引数は、有効なXML型付きバッファ入力を指すポインタです。

vfile

この引数は、XML入力の検証に使用するXMLスキーマ・ファイルの完全修飾パス名です。この引数を使用するには、TPXPARSNSPACEフラグとTPXPARSDOSCHEフラグを設定する必要があります。TPXPARSNEVERフラグは設定しないでください。

fml32bufp

この引数は、入力XMLから作成されたFML32型付き出力バッファを指すポインタです。

rtag

この引数は、入力XMLドキュメントからルート要素名を格納するポインタです。

flags

この引数は、Xercesパーサー・クラスのTuxedo 9.xサブセットにマッピングするために、XMLからFML/FML32への変換に使用します(XercesParser 2.5ドキュメントを参照)。次に、Tuxedo 9.xで有効なXercesパーサーのflagsの一覧を示します。

TPXPARSNEVER

setValidationSchemeをVal_Neverに設定します。パーサーは、スキーマ検証エラーを報告しません。

TPXPARSALWAYS

setValidationSchemeをVal_Alwaysに設定します。パーサーは、スキーマ検証エラーを常に報告します。

同時に使用した場合、TPXPARSNEVERはTPXPARSALWAYSよりも優先されます。

TPXPARSSCHFULL

setValidationSchemaFullCheckingをtrueに設定します。このフラグを使用すると、完全なスキーマ制約チェックをオンまたはオフにできます。スキーマ検証が有効な場合にのみ機能します。オフにした場合は、部分的な制約チェックが実行されます。完全なスキーマ制約チェックには、多くの時間またはメモリーが必要なものもあります。現在、このオプションでは、微細な固有属性チェックと派生制約チェックを制御します。

TPXPARSCONFATAL

setValidationConstraintFatalをtrueに設定します。このフラグを使用すると、検証制約エラーが発生した場合のパーサーの動作を設定できます。trueに設定した場合、パーサーは、検証エラーを致命的として処理し、getExitOnFirstFatalErrorの状態に従って終了します。falseに設定した場合は、エラーを報告し、処理を続行します。

TPXPARSNSPACE

setDoNamespacesをtrueに設定します。このフラグを使用すると、パーサーによるネームスペースの処理を有効または無効にできます。trueに設定した場合、パーサーは、NameSpace仕様で指定したすべての制約とルールを適用します。

TPXPARSDOSCH

setDoSchemaをtrueに設定します。このフラグを使用すると、パーサーによるスキーマの処理を有効または無効にできます。falseに設定した場合、パーサーは、見つかったスキーマを処理しません。

ノート:

trueに設定した場合は、ネームスペースの処理もオンになっている必要があります

TPXPARSEREFN

setCreateEntityReferencNodesをfalseに設定します。このフラグを使用すると、生成中のDOMツリーでパーサーがエンティティ参照ノードを作成するかどうかを指定できます。createフラグがtrueの場合、パーサーは、DOMツリーにEntityReferenceノードを作成します。EntityReferenceノードとその子ノードは読取り専用です。createフラグがfalseの場合、EntityReferenceノードは作成されません。エンティティの代替テキストが、エンティティ参照ノードの子として追加されるか、所定の参照の位置に挿入されます。

TPXPARSNOEXIT

setExitOnFirstFatalErrorをfalseに設定します。このフラグを使用すると、最初に致命的なエラーが発生した場合のパーサーの動作を設定できます。trueに設定した場合、パーサーは最初の致命的なエラーで終了します。falseに設定した場合は、エラーを報告し、処理を続行します。

TPXPARSNOINCWS

setIncludeIgnorableWhitespaceをfalseに設定します。このフラグを使用すると、無視できる余白をテキスト・ノードとして検証パーサーに含めるかどうかを指定できます。非マークアップ・テキストを常に含む非検証パーサーには無効です。

falseに設定すると、無視可能な余白は破棄され、テキスト・ノードはDOMツリーに追加されません。

TPXPARSCACHESET

setcacheGrammarFromParseをtrueに設定します。このフラグを使用すると、XMLドキュメントを解析する際の文法のキャッシュを有効または無効にできます。trueに設定すると、パーサーは、結果の文法を以降の解析で使用するためにキャッシュします。フラグをtrueに設定した場合、キャッシュ済文法の使用フラグもtrueに設定されます。

TPXPARSCACHERESET

resetCachedGrammarPoolをリセットします。ドキュメントのベクトル・プールをリセットし、関連するすべてのメモリーをシステムに解放します。

DOMパーサーでドキュメントを解析する際に、DOMツリー用に割り当てられたすべてのメモリーがDOMドキュメントに関連付けられます。

同じDOMパーサー・インスタンスを使用して複数の解析を実行する場合、複数のDOMドキュメントが生成され、ベクトル・プールに保存されます。すべてのドキュメント(およびそれに付随するすべての割当て済メモリー)は、パーサー・インスタンスが破棄されるまで削除されません。

これらのDOMドキュメントが不要になったときにDOMパーサー・インスタンスをまだ破棄しない場合は、このメソッドを呼び出すと、ドキュメントのベクトル・プールをリセットして、割り当てられたすべてのメモリーをシステムに解放することができます。解析中に(たとえば、段階的な解析などで)このメソッドを呼び出すと、エラーになります。

戻り値

成功した場合、tpxmltofml32()は0を返します。この関数は、エラー発生時に-1を返し、tperrnoを設定してエラー条件を示します。

エラー

この関数は、次の原因により異常終了する可能性があります。

[TPEINVAL]

fml32bufpまたはxmlbufpのどちらかが有効な型付きバッファではありません。あるいは、パーサーが入力を認識できません。

[TPESYSTEM]

Tuxedoシステムのエラーが発生しました。このエラーの正確な性質はuserlog(3)に書き込まれます。これは、FML32への変換を実行できなかった時期も示します。そのインスタンスでは、エラーの詳細な情報がuserlogに追加されます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。失敗したシステム・コールを示す数値がUunixerrに入っています。

関連項目:

tpfml32toxml(3c)、tpxmltofml(3c)、tpfmltoxml(3c)

2.136 tpxmltofml(3c)

名前

tpxmltofml() - XMLデータをFMLバッファに変換します

形式

#include <fml.h>
int tpxmltofml (char *xmlbufp, char *vfile, FBFR **fmlbufp, char **rtag, long flags)

説明

この関数は、XMLデータをFMLバッファに変換するために使用します。次の引数を使用できます。

xmlbufp

この引数は、有効なXML型付きバッファ入力を指すポインタです。

vfile

この引数は、XML入力の検証に使用するXMLスキーマ・ファイルの完全修飾パス名です。この引数を使用するには、TPXPARSNSPACEフラグとTPXPARSDOSCHEフラグを設定する必要があります。TPXPARSNEVERフラグは設定しないでください。

fmlbufp

この引数は、入力XMLから作成されたFML型付き出力バッファを指すポインタです。

rtag

この引数は、入力XMLドキュメントからルート要素名を格納するポインタです。

flags

この引数は、Xercesパーサー・クラスのTuxedo 9.xサブセットにマッピングするために、XMLからFML/FM32Lへの変換に使用します(XercesParser 2.5ドキュメントを参照)。次に、Tuxedo 9.xで有効なXercesパーサーのflagsの一覧を示します。

• TPXPARSNEVER

  setValidationSchemeをVal_Neverに設定します。パーサーは、スキーマ検証エラーを報告しません。

• TPXPARSALWAYS

  setValidationSchemeをVal_Alwaysに設定します。パーサーは、スキーマ検証エラーを常に報告します。

  ノート:

  同時に使用した場合、TPXPARSNEVERはTPXPARSALWAYSよりも優先されます。

TPXPARSSCHFULL

setValidationSchemaFullCheckingをtrueに設定します。このフラグを使用すると、完全なスキーマ制約チェックをオンまたはオフにできます。スキーマ検証が有効な場合にのみ機能します。オフにした場合は、部分的な制約チェックが実行されます。完全なスキーマ制約チェックには、多くの時間またはメモリーが必要なものもあります。現在、このオプションでは、微細な固有属性チェックと派生制約チェックを制御します。

TPXPARSCONFATAL

setValidationConstraintFatalをtrueに設定します。このフラグを使用すると、検証制約エラーが発生した場合のパーサーの動作を設定できます。trueに設定した場合、パーサーは、検証エラーを致命的として処理し、getExitOnFirstFatalErrorの状態に従って終了します。falseに設定した場合は、エラーを報告し、処理を続行します。

TPXPARSNSPACE

setDoNamespacesをtrueに設定します。このフラグを使用すると、パーサーによるネームスペースの処理を有効または無効にできます。trueに設定した場合、パーサーは、NameSpace仕様で指定したすべての制約とルールを適用します。

TPXPARSDOSCH

setDoSchemaをtrueに設定します。このフラグを使用すると、パーサーによるスキーマの処理を有効または無効にできます。falseに設定した場合、パーサーは、見つかったスキーマを処理しません。

ノート:

trueに設定した場合は、ネームスペースの処理もオンになっている必要があります。

TPXPARSEREFN

setCreateEntityReferencNodesをfalseに設定します。このフラグを使用すると、生成中のDOMツリーでパーサーがエンティティ参照ノードを作成するかどうかを指定できます。このフラグがtrueの場合、パーサーは、DOMツリーにEntityReferenceノードを作成します。EntityReferenceノードとその子ノードは読取り専用です。createフラグがfalseの場合、EntityReferenceノードは作成されません。どちらの場合も、エンティティの代替テキストが、エンティティ参照ノードの子として追加されるか、所定の参照の位置に挿入されます。

TPXPARSNOEXIT

setExitOnFirstFatalErrorをfalseに設定します。このフラグを使用すると、最初に致命的なエラーが発生した場合のパーサーの動作を設定できます。trueに設定した場合、パーサーは最初の致命的なエラーで終了します。falseに設定した場合は、エラーを報告し、処理を続行します。

TPXPARSNOINCWS

setIncludeIgnorableWhitespaceをfalseに設定します。このフラグを使用すると、無視できる余白をテキスト・ノードとして検証パーサーに含めるかどうかを指定できます。非マークアップ・テキストを常に含む非検証パーサーには無効です。

falseに設定すると、無視可能な余白は破棄され、テキスト・ノードはDOMツリーに追加されません。

TPXPARSCACHESET

setcacheGrammarFromParseをtrueに設定します。このフラグを使用すると、XMLドキュメントを解析する際の文法のキャッシュを有効または無効にできます。trueに設定すると、パーサーは、結果の文法を以降の解析で使用するためにキャッシュします。フラグをtrueに設定した場合、キャッシュ済文法の使用フラグもtrueに設定されます。

TPXPARSCACHERESET

resetCachedGrammarPoolをリセットします。ドキュメントのベクトル・プールをリセットし、関連するすべてのメモリーをシステムに解放します。

DOMパーサーでドキュメントを解析する際に、DOMツリー用に割り当てられたすべてのメモリーがDOMドキュメントに関連付けられます。

同じDOMパーサー・インスタンスを使用して複数の解析を実行する場合、複数のDOMドキュメントが生成され、ベクトル・プールに保存されます。すべてのドキュメント(およびそれに付随するすべての割当て済メモリー)は、パーサー・インスタンスが破棄されるまで削除されません。

これらのDOMドキュメントが不要になったときにDOMパーサー・インスタンスをまだ破棄しない場合は、このメソッドを呼び出すと、ドキュメントのベクトル・プールをリセットして、割り当てられたすべてのメモリーをシステムに解放することができます。解析中に(たとえば、段階的な解析などで)このメソッドを呼び出すと、エラーになります。

戻り値

正常終了の場合、tpxmltofml()は0を返します。エラーが発生した場合は、-1を返し、tperrnoを設定してエラー条件を示します。

エラー

この関数は、次の原因により異常終了する可能性があります。

[TPEINVAL]

fml32bufpまたはxmlbufpのどちらかが有効な型付きバッファではありません。あるいは、パーサーが入力を認識できません。

[TPESYSTEM]

Tuxedoシステムのエラーが発生しました。エラーの正確な性質はuserlog(3c).に書き込まれますこれは、FMLへの変換を実行できなかった時期も示します。そのインスタンスでは、エラーの詳細な情報がuserlogに追加されます。

[TPEOS]

オペレーティング・システムのエラーが発生しました。失敗したシステム・コールを示す数値がUunixerrに入っています。

関連項目:

tpxmltofml32(3c)、tpfml32toxml(3c)、tpfmltoxml(3c)

『C言語を使用したOracle Tuxedo ATMIアプリケーションのプログラミング』の「XMLデータとFML/FML32バッファ間の変換」

2.137 TRY(3c)

名前

TRY() - 例外復帰インタフェース。

形式 exception_name;

/* initialize address (application) exception */

#include <texc.h>

TRY
try_block
[ CATCH(exception_name) handler_block] ...
[CATCH_ALL handler_block]
ENDTRY

TRY
try_block
FINALLY
finally_block
ENDTRY

RAISE(exception_name)
RERAISE

/* declare exception */
EXCEPTION exception_name;

/* initialize address (application) exception */
EXCEPTION_INIT(EXCEPTION exception_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種類の例外があります。どちらも同じ方法で宣言されますが、初期化の方法は異なります。

1種類の例外を使用してアプリケーション例外を定義します。EXCEPTION_INIT()マクロを呼び出して初期化します。例外のアドレスはaddress例外内の値として格納されます。この値は単一のアドレス空間内でのみ有効であり、例外が自動変数の場合には変更されることに注意してください。このためaddress例外は静的変数あるいは外部変数として宣言し、自動変数あるいはレジスタ変数として宣言すべきではありません。exc_get_status()マクロは、address例外では-1となります。この例外でexc_set_status()マクロを使用するとstatus例外となります。

exc_matchesマクロは、2つの例外を比較するのに使用します。同一であるためには、どちらの例外も同じタイプであり、同じ値を持たなければなりません(たとえば、status例外に対しては同じステータス値を持つか、address例外に対しては同じアドレスを持ちます)。この比較は、上記のCATCHクローズで使用されます。

ステータス例外が発生した場合の通常の処理は、ステータス値を表示するか、より好ましい方法としてはステータス値が何であるかを示す文字列を表示することです。文字列を標準エラー出力に表示するのであれば、文字列を1回の操作で表示できるようにstatus例外へのポインタを付加して関数exc_report()を呼び出します。

CATCH_ALL
{
exc_report(THIS_CATCH);
}
ENDTRY

文字列に対して他の処理を行う場合には(たとえば、エラーをユーザー・ログに出力する)、exc_get_status()をTHIS_CATCHで使用し、ステータス値を取得できます(THIS_CATCHはEXCEPTIONに対するポインタであり、EXCEPTION自体ではありません)。dce_error_inq_text()を使用して、ステータス値の文字列を取得することができます。

CATCH_ALL
{
unsigned long status_to_convert;
unsigned char error_text[200];
int status;

exc_get_status(THIS_CATCH,status_to_convert);
dce_error_inq_text(status_to_convert, error_text, status);
userlog(“%s”, (char *)error_text);
}
ENDTRY

ノート:

マルチスレッドのアプリケーション中のスレッドは、TPINVALIDCONTEXTを含め、どのコンテキスト状態で実行していても、TRY/CATCHインタフェースを呼び出すことができます

例外とステータス復帰をいつ使用するか

RPCオペレーションのステータスは、各オペレーションごとにステータス変数を定義することにより決定できます([comm_status]と[fault_status]パラメータは、属性構成ファイルで定義されます)。ステータス復帰インタフェースは、X/Open RPC仕様で提供される唯一のインタフェースです。fault_status属性は、不適切なパラメータ、リソース不足、コーディング・エラーなどによりサーバー上で発生したエラーが、補助的なステータス引数や戻り値でレポートされることを示しています。同様にcomm_status属性は、RPCコミュニケーション障害が補助的なステータス引数や戻り値でレポートされることを示します。ステータス値を利用する処理は、各コールごとに起こり得るエラーに対して指定されたリカバリを行う(コールごとの)きめ細かいエラー処理と、障害の時点での再試行が必要な場合にはうまく機能します。欠点としては、コールがローカルなものであってもリモートなものであっても、いずれの場合にも透過性がない点が挙げられます。リモート・コールには追加のステータス・パラメータ、あるいはvoidのかわりにステータスの戻り値が必要になります。従ってアプリケーションでは、ローカルと分散コード間で調整を行うプロシージャ宣言が必要です。

TRY/CATCH例外復帰インタフェースは、OSF/DCE環境からのアプリケーション移植性のためにも提供されています。このインタフェースは、すべての環境で利用できるものではありません。しかし、プロシージャ宣言をローカルと分散コード間で調整する必要がないという利点があり、既存のインタフェースを保持できます。各プロシージャ・コールは固有の障害チェックやリカバリ・コードを持つ必要がなく、エラー・チェッキングを簡素化できます。あるレベルでエラー処理が行えない場合には、プログラムは、「エラーが検出されたが修正可能である」などのシステム・エラー・メッセージを出力して終了します(メッセージを省略すると、エラー・チェッキングはより簡単になります)。例外は、大まかな例外処理を行う場合には有用です。

ビルトイン例外

表18に示す例外は、この例外インタフェースで使用するために組み込まれている例外です。最初のTRYクローズはシグナル・ハンドラを設定し、以下にリストされたシグナル(無視されることがなく、補足可能なもの)を補足します。その他の例外はDCE対応のプログラムでの移植性のためにのみ定義されたものです。

例外	説明
exc_e_SIGBUS	処理できないSIGBUSシグナルが発生しました。
exc_e_SIGEMT	処理できないSIGEMTシグナルが発生しました。
exc_e_SIGFPE	処理できないSIGFPEシグナルが発生しました。
exc_e_SIGILL	処理できないSIGILLシグナルが発生しました。
exc_e_SIGIOT	処理できないSIGIOTシグナルが発生しました。
exc_e_SIGPIPE	処理できないSIGPIPEシグナルが発生しました。
exc_e_SIGSEGV	処理できないSIGSEGVシグナルが発生しました。
exc_e_SIGSYS	処理できないSIGSYSシグナルが発生しました。
exc_e_SIGTRAP	処理できないSIGTRAPシグナルが発生しました。
exc_e_SIGXCPU	処理できないSIGXCPUシグナルが発生しました。
exc_e_SIGXFSZ	処理できないSIGXFSZシグナルが発生しました。
pthread_e_badparam	-
pthread_e_defer_q_full	-
pthread_e_existence	-
pthread_e_in_use	-
pthread_e_nostackmem	-
pthread_e_nostack	-
pthread_e_signal_q_full	-
pthread_e_stackovf	-
pthread_e_unimp	-
pthread_e_use_error	-
exc_e_decovf	-
exc_e_exquota	-
exc_e_fltdiv	-
exc_e_fltovf	-
exc_e_fltund	-
exc_e_illaddr	-
exc_e_insfmem	-
exc_e_intdiv	-
exc_e_intovf	-
exc_e_nopriv	-
exc_e_privinst	-
exc_e_resaddr	-
exc_e_resoper	-
exc_e_subrng	-
exc_e_uninitexc	-

名前の後に_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システムのいずれか一方でしか行えません。

例

例外を使用するC言語のソース・ファイルを以下に示します。

#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
}

関連項目:

userlog(3c)

UNIXシステムのリファレンス・マニュアルのabort(2)

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

2.138 tuxgetenv(3c)

名前

tuxgetenv() - 環境名の値を戻します。

形式

#include <atmi.h>
char *tuxgetenv(char *name)

説明

tuxgetenv()は、環境リストからname=valueという形式の文字列を探し、その文字列が見つかった場合に、現在の環境内のvalueを指すポインタを返します。文字列が見つからなかった場合は、NULLポインタを返します。

この関数は、Oracle Tuxedo ATMIがサポートされる、異なるプラットフォーム間で使用する環境変数に対して、移植可能なインタフェースを提供します。プラットフォームには、通常は環境変数を持たないプラットフォームも含まれます。

ノート:

tuxgetenvでは大文字と小文字が区別されます。

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

戻り値

文字列のポインタが存在する場合、tuxgetenv()はそのポインタを返します。ポインタが存在しない場合、tuxgetenv()はNULLポインタを返します。

移植性

MS Windowsでは、この関数によって、アプリケーションとダイナミック・リンク・ライブラリとの間で環境変数を共有できるようになります。Oracle Tuxedo ATMIワークステーションDLLは、付加された各アプリケーションの環境コピーを保持します。この関連付けられた環境およびコンテキスト情報は、tpterm()がWindowsアプリケーションから呼び出されると無効になります。環境変数の値は、アプリケーション・プログラムがtpterm()を呼び出した後で変更できます。

Windows環境では、大文字の変数名を使用することをお薦めします(tuxreadenv()はすべての環境変数名を大文字に変換します。)

関連項目:

tuxputenv(3c)、tuxreadenv(3c)

2.139 tuxgetmbaconv(3c)

名前

tuxgetmbaconv() - プロセス環境で環境変数TPMBACONVの値を取得します。

形式

#include <atmi.h>
extern int tperrno;

int
tuxgetmbaconv(long flags) /* Get TPMBACONV info */

説明

この関数は、TPMBACONVのステータスを取得するために使用します。tuxgetnombaconv()関数は、アプリケーション開発者が、型付きバッファ・スイッチの自動変換機能がオフになっているかどうかをチェックするために使用します。デフォルトでは、TPMBACONVは設定されず、自動変換機能が使用されます。

引数flagsは現在使用されておらず、0に設定する必要があります。

戻り値

tuxgetnombaconv()は、TPMBACONVが設定されている場合はMBAUTOCONVERSION_ONを戻し、TPMBACONVが設定されていない場合はMBAUTOCONVERSION_OFFを戻します。

関連項目:

tuxgetenv(3c)、tuxsetmbaconv(3c)

2.140 tuxgetmbenc(3c)

名前

tuxgetmbenc() - プロセス環境で環境変数TPMBENCのコード・セットのエンコード名を取得します。

形式

#include <atmi.h>
extern int tperrno;

int
tuxgetmbenc(char *enc_name, long flags)

説明

この関数は、環境変数TPMBENCに保持されているコードセットのエンコード名を取得するために使用します。この環境変数は、MBSTRING型付きバッファを作成する際に、デフォルトのコードセットのエンコード名として使用されます。新しいメッセージの取出しが可能になると、tpsetmbenc()関数を使用してデフォルトのエンコード名をリセットしたり設定解除したりできます。

引数enc_nameには、この関数の正常終了時に、環境変数TPMBENCの値が入ります。このポインタには、エンコード名のコピー先として十分な大きさを確保しておく必要があります。

引数flagsは現在使用されておらず、0に設定する必要があります。

戻り値

正常終了の場合、tuxgetmbenc()は0を返します。エラーが発生した場合は0以外の値を返します。

関連項目:

tpconvmb(3c)、tpgetmbenc(3c)、tpsetmbenc(3c)、tuxgetenv(3c)

2.141 tuxputenv(3c)

名前

tuxputenv() - 環境に対して値を変更または追加します。

形式

#include <atmi.h>
int tuxputenv(char *string)

説明

stringは、name=valueという形式の文字列を指します。tuxputenv()は、既存の環境変数を変更するか新しい環境変数を作成して、環境変数名の値がvalueと等しくなるようにします。どちらの場合も、stringによって指された文字列は環境変数の一部になります。

この関数は、Oracle Tuxedo ATMIがサポートされる、異なるプラットフォーム間で使用する環境変数に対して、移植可能なインタフェースを提供します。プラットフォームには、通常は環境変数を持たないプラットフォームも含まれます。

ノート:

tuxputenv()では大文字と小文字が区別されます

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

戻り値

tuxputenv()は、malloc()を介して拡張環境のための十分な領域を取得できなかった場合にゼロでない整数を返します。それ以外の場合は、0(ゼロ)を戻します。

移植性

MS Windowsでは、この関数によって、アプリケーションとダイナミック・リンク・ライブラリとの間で環境変数を共有できるようになります。Oracle Tuxedo ATMIシステムのワークスレーションDLLは、付加された各アプリケーションの環境コピーを保持します。この関連付けられた環境およびコンテキスト情報は、tpterm()がWindowsアプリケーションから呼び出されると無効になります。環境変数の値は、アプリケーション・プログラムがtpterm()を呼び出した後で変更できます。

DOS、Windows、およびOS/2環境では、大文字の変数名を使用することをお薦めします(tuxreadenv()はすべての環境変数名を大文字に変換します。)

関連項目:

tuxgetenv(3c)、tuxreadenv(3c)

2.142 tuxreadenv(3c)

名前

tuxreadenv() - ファイルから環境に変数を追加します。

形式

#include <atmi.h>
int tuxreadenv(char *file, char *label)

説明

tuxreadenv()は環境変数を含むファイルを読み込み、プラットフォームから独立して環境変数を環境に追加します。変数はtuxgetenv()を使用して利用でき、tuxputenv()を使用して再設定できます。

環境ファイルの形式は、次のとおりです。

• 各行の先頭のスペースまたはタブ文字は無視され、次の点では考慮されません。
• 環境に挿入する変数を含む行は次の形式です。

  variable=value

  または

  set variable=value

  ここで、variableは、先頭がアルファベット文字またはアンダースコア文字で、全体が英数字またはアンダースコア文字のみからなる文字列です。また、valueには改行文字を除くすべての文字を使用できます。

• value内で、${env}という形式の文字列は、環境内にすでにある変数を使用して展開されます。前方参照はサポートされておらず、値が設定されていない場合、変数は空の文字列に置き換えられます。円マーク(¥)を使用して、ドル記号およびそれ自体をエスケープすることができます。その他すべてのシェルの引用符およびエスケープのメカニズムは無視され、展開されたvalueが環境に配置されます。
• スラッシュ(/)、シャープ(#)、またはエクスクラメーション・マーク(!)で始まる行は、コメントとして扱われ、無視されます。これらのコメント文字、左角括弧、アルファベット文字またはアンダースコア文字以外の文字で始まる行は、将来の用途のため予約されています。使用法は未定義です
• ファイルは、ラベルとして動作する、左角カッコ(「)で始まる行によってセクションごとに区切られます。ラベルは、31文字を超えると切り詰められます。ラベルの形式は次のとおりです

  [label]

  labelは、前述のvariableと同じルール(無効なlabel値を持つ行は無視される)に従います

• ファイルの先頭と最初のラベルの間の変数行は、すべてのラベルの環境(つまりグローバル・セクション)に挿入されます。他の変数は、ラベルが、アプリケーション用に指定したラベルに一致する場合にのみ、その環境に挿入されます。ラベル[]はグローバル・セクションを示します。 )

fileがNULLの場合、デフォルトのファイル名が使用されます。固定のファイル名は次のとおりです。

DOS, Windows, OS2, NT: C:\TUXEDO\TUXEDO.ENV
MAC: TUXEDO.ENV in the system preferences directory
NETWARE: SYS:SYSTEM\TUXEDO.ENV
POSIX: /usr/tuxedo/TUXEDO.ENV or /var/opt/tuxedo/TUXEDO.ENV

labelがNULLの場合、グローバル・セクション内の変数だけが環境に挿入されます。labelが他の値の場合、グローバル・セクションの変数と、labelに一致するセクション内の変数が環境に入れられます。

エラー・メッセージは、メモリー障害が発生した場合、NULLでないファイル名が存在しない場合、またはNULLでないラベルがない場合は、userlog()に出力されます。

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

例

環境ファイルの例を次に示します。

TUXDIR=/usr/tuxedo
[application1]
;this is a comment
/* this is a comment */
#this is a comment
//this is a comment
FIELDTBLS=app1_flds
FLDTBLDIR=/usr/app1/udataobj
[application2]
FIELDTBLS=app2_flds
FLDTBLDIR=/usr/app2/udataobj

戻り値

tuxreadenv()は、malloc()を介して拡張環境のための十分な領域を取得できなかった場合か、NULLでない名前を持つファイルをオープンできず読み取ることができない場合に、ゼロ以外の整数を戻します。それ以外の場合、tuxreadenv()はゼロを戻します。

移植性

DOS、Windows、OS/2、およびNetWare環境では、tuxreadenv()がすべての環境変数名を大文字に変換します。

関連項目:

tuxgetenv(3c)、tuxputenv(3c)

2.143 tuxsetmbaconv(3c)

名前

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が設定され、型付きバッファでのコードセットのマルチバイト・データの自動変換が有効になります。

引数flagsは現在使用されておらず、0に設定する必要があります。

戻り値

正常終了の場合、tuxsetnombaconv()は0を返します。エラーが発生した場合は0以外の値を返します(たとえば、引数onoffが定義済の値のいずれかでない場合、-1を返します)。

関連項目:

tuxgetmbaconv(3c)、tuxputenv(3c)

2.144 tuxsetmbenc(3c)

名前

tuxsetmbenc() - プロセス環境で環境変数TPMBENCのコード・セットのエンコード名を設定します。

形式

#include <atmi.h>
extern int tperrno;

int
tuxsetmbenc(char *enc_name, long flags)

説明

この関数は、環境変数TPMBENCに保持されているコードセットのエンコード名を設定またはリセットするために使用します。この環境変数は、MBSTRING型付きバッファを作成する際に、デフォルトのコードセットのエンコード名として使用されます。新しいメッセージの取出しが可能になると、tpsetmbenc()関数を使用してデフォルトのエンコード名をリセットしたり設定解除したりできます。

引数enc_nameは、コードセットの識別に使用するエンコード名です。

引数flagsは現在使用されておらず、0に設定する必要があります。

戻り値

正常終了の場合、tuxsetmbenc()は0を返します。エラーが発生した場合は0以外の値を返します。

関連項目:

tpconvmb(3c)、tpgetmbenc(3c)、tpsetmbenc(3c)、tuxgetmbenc(3c)、tuxputenv(3c)

2.145 tuxthrputenv(3c)

名前

tuxthrputenv() - 現在のスレッドの環境変数を変更または追加します。

形式

#include <atmi.h>
int tuxthrputenv(char *string)

説明

stringは、name=valueという形式の文字列を指します。tuxthrputenv()は、既存の環境変数を変更するか新しい環境変数を作成して、環境変数名の値がvalueと等しくなるようにします。どちらの場合も、stringによって指された文字列は環境変数の一部になります。

この関数は、Oracle Tuxedo ATMIがサポートされる、異なるプラットフォーム間で使用する環境変数に対して、移植可能なインタフェースを提供します(プラットフォームには、通常は環境変数を持たないプラットフォームも含まれます)。これにより、マルチスレッド・アプリケーションのスレッドが独自の環境変数を使用できるようになります。

tuxthrputenvが機能するのは、tuxgetenv()によって読み取られる場合のみです。getenvが使用されると、tuxthrputenvは失敗します。

ノート:

tuxthrputenv()では大文字と小文字が区別されます。tuxputenvで設定された値をオーバーライドします。

戻り値

tuxthrputenv()は、malloc()を介して拡張環境のための十分な領域を取得できなかった場合にゼロでない整数を返します。それ以外の場合は、0(ゼロ)を戻します。

移植性

MS Windowsでは、tuxthrputenv()によって、アプリケーションとダイナミック・リンク・ライブラリとの間で環境変数を共有できるようになります。Oracle Tuxedo ATMIシステムのワークスレーションDLLは、付加された各アプリケーションの環境コピーを保持します。この関連付けられた環境およびコンテキスト情報は、tpterm()がWindowsアプリケーションから呼び出されると無効になります。環境変数の値は、アプリケーション・プログラムがtpterm()を呼び出した後で変更できます。

DOS、Windows、およびOS/2環境では、大文字の変数名を使用することをお薦めします(tuxreadenv()はすべての環境変数名を大文字に変換します。)

関連項目:

tuxgetenv(3c)、tuxreadenv(3c)、tuxputenv(3c)

2.146 tx_begin(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_set_transaction_timeout()

戻り値

tx_begin()は、正常終了時には、負数ではない戻り値TX_OKを返します。

エラー

次の条件の場合、tx_begin()は異常終了し、次のいずれかの負の値を返します。

[TX_OUTSIDE]

呼出し側の制御スレッドが、1つ以上のリソース・マネージャを利用して、グローバル・トランザクションの外部で現在作業中であるため、トランザクション・マネージャは、グローバル・トランザクションを開始できません。このような作業がすべて完了してからでなければ、グローバル・トランザクションは開始できません。ローカル・トランザクションについての呼出し側の状態は、変更されません。

[TX_PROTOCOL_ERROR]

この関数が不正なコンテキストで呼び出されました(たとえば、呼出し側がすでにトランザクション・モードにある場合)。トランザクション・モードに関する呼出し側の状態は変更されません。

[TX_ERROR]

トランザクション・マネージャまたは1つ以上のリソース・マネージャが、新しいトランザクションの開始において一時的エラーを検出しました。このエラーが返された場合は、呼出し側はトランザクション・モードにありません。エラーの正確な性質がログ・ファイルに書き込まれます。

[TX_FAIL]

トランザクション・マネージャまたは1つ以上のリソース・マネージャが、致命的エラーを検出しました。このエラーでは、トランザクション・マネージャまたは1つ以上のリソース・マネージャ、あるいはその両方は、アプリケーションのために作業を行うことができなくなります。このエラーが返された場合は、呼出し側はトランザクション・モードにありません。エラーの正確な性質がログ・ファイルに書き込まれます。

警告

XA準拠のリソース・マネージャがグローバル・トランザクションに含まれるようにするには、そのリソース・マネージャが正常にオープンされている必要があります。(詳細は、「tx_open(3c)」を参照してください。)X/Open TXインタフェースとX-Windowシステムは、いずれも型XIDを定義します。同一のファイルでX-WindowコールとTXコールの両方を使用することはできません。

関連項目:

tx_commit(3c)、tx_open(3c)、tx_rollback(3c)、tx_set_transaction_timeout(3c)

2.147 tx_close(3c)

名前

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]

トランザクション・マネージャまたは1つ以上のリソース・マネージャが、一時的エラーを検出しました。エラーの正確な性質がログ・ファイルに書き込まれます。クローズ可能なリソース・マネージャはすべてクローズされます。

[TX_FAIL]

トランザクション・マネージャまたは1つ以上のリソース・マネージャが、致命的エラーを検出しました。このエラーでは、トランザクション・マネージャまたは1つ以上のリソース・マネージャ、あるいはその両方は、アプリケーションのために作業を行うことができなくなります。エラーの正確な性質がログ・ファイルに書き込まれます。

警告

X/Open TXインタフェースとX-Windowシステムは、いずれも型XIDを定義します。同一のファイルでX-WindowコールとTXコールの両方を使用することはできません。

関連項目

tx_open(3c)

2.148 tx_commit(3c)

名前

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_set_commit_return()
• tx_set_transaction_control()
• tx_set_transaction_timeout()

戻り値

tx_commit()は、正常終了時には、負数でない戻り値TX_OKを返します。

エラー

次の条件の場合、tx_commit()は異常終了し、次のいずれかの負の値を返します。

[TX_NO_BEGIN]

現在のトランザクションは、正常にコミットされました。ただし、新しいトランザクションを開始できなかったので、呼出し側はトランザクション・モードではなくなりました。この戻り値はtransaction_control特性がTX_CHAINEDである場合のみ発生します。

[TX_ROLLBACK]

現在のトランザクションはコミットできず、ロールバックされました。また、transaction_control特性がTX_CHAINEDである場合には、新しいトランザクションが開始されます。

[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]

トランザクション・マネージャまたは1つ以上のリソース・マネージャが、致命的エラーを検出しました。このエラーでは、トランザクション・マネージャまたは1つ以上のリソース・マネージャ、あるいはその両方は、アプリケーションのために作業を行うことができなくなります。エラーの正確な性質がログ・ファイルに書き込まれます。トランザクションについての呼出し側の状態は、不明です。

警告

X/Open TXインタフェースとX-Windowシステムは、いずれも型XIDを定義します。同一のファイルでX-WindowコールとTXコールの両方を使用することはできません。

関連項目:

tx_begin(3c)、tx_set_commit_return(3c)、tx_set_transaction_control(3c)、tx_set_transaction_timeout(3c)

2.149 tx_info(3c)

名前

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_open()を呼び出していません)。

[TX_FAIL]

トランザクション・マネージャが致命的エラーを検出しました。このエラーでは、トランザクション・マネージャは、アプリケーションのために作業を行うことができなくなります。エラーの正確な性質がログ・ファイルに書き込まれます。

警告

同一のグローバル・トランザクション内では、後続のtx_info()呼出しは、XIDに同一のgtrid構成要素を示すことが保証されていますが、同一のbqual構成要素を示すことは必ずしも保証されません。X/Open TXインタフェースとX-Windowシステムは、いずれも型XIDを定義します。同一のファイルでX-WindowコールとTXコールの両方を使用することはできません。

関連項目:

tx_open(3c)、tx_set_commit_return(3c)、tx_set_transaction_control(3c)、tx_set_transaction_timeout(3c)

2.150 tx_open(3c)

名前

tx_open() - リソース・マネージャ・セットをオープンします。

形式

#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]

トランザクション・マネージャまたは1つ以上のリソース・マネージャが、一時的エラーを検出しました。リソース・マネージャは一切オープンされません。エラーの正確な性質がログ・ファイルに書き込まれます。

[TX_FAIL]

トランザクション・マネージャまたは1つ以上のリソース・マネージャが、致命的エラーを検出しました。tpinit()を呼び出さずにセキュリティの掛かったアプリケーション(SECURITY APP_PW)の中でtx_openを呼び出すと、TX_FAILが出されます。このエラーでは、トランザクション・マネージャまたは1つ以上のリソース・マネージャ、あるいはその両方は、アプリケーションのために作業を行うことができなくなります。エラーの正確な性質がログ・ファイルに書き込まれます。

警告

X/Open TXインタフェースとX-Windowシステムは、いずれも型XIDを定義します。同一のファイルでX-WindowコールとTXコールの両方を使用することはできません。

関連項目:

tx_close(3c)

2.151 tx_rollback(3c)

名前

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_set_transaction_control()
• tx_set_transaction_timeout()

戻り値

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_CHAINEである場合のみ発生します。

[TX_COMMITTED]

トランザクションのために行われた作業は、ヒューリスティックにコミットされました。また、transaction_control特性がTX_CHAINEDである場合には、新しいトランザクションが開始されます。

[TX_COMMITTED_NO_BEGIN]

トランザクションのために行われた作業は、ヒューリスティックにコミットされました。また、新しいトランザクションを開始できなかったので、呼出し側はトランザクション・モードではなくなりました。この戻り値はtransaction_control特性がTX_CHAINEDである場合のみ発生します。

[TX_PROTOCOL_ERROR]

この関数が不正なコンテキストで呼び出されました(たとえば、呼出し側がトランザクション・モードにない場合)。

[TX_FAIL]

トランザクション・マネージャまたは1つ以上のリソース・マネージャが、致命的エラーを検出しました。このエラーでは、トランザクション・マネージャまたは1つ以上のリソース・マネージャ、あるいはその両方は、アプリケーションのために作業を行うことができなくなります。エラーの正確な性質がログ・ファイルに書き込まれます。トランザクションについての呼出し側の状態は、不明です。

X/Open TXインタフェースとX-Windowシステムは、いずれも型XIDを定義します。同一のファイルでX-WindowコールとTXコールの両方を使用することはできません。

2.152 tx_set_commit_return(3c)

名前

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です。

when_returnの有効な設定を次に示します。

TX_COMMIT_DECISION_LOGGED

このフラグは、2フェーズ・コミット・プロトコルの第1フェーズによってコミットの決定が記録された後、第2フェーズが終了する前に、tx_commit()が終了することを示します。このフラグを設定すると、tx_commit()の呼出し側に高速で応答することができます。しかし、トランザクションがヒューリスティックな結果を得る危険があります。この場合、tx_commit()の戻りコードから呼出し側がこの状況を知ることはできません。正常な状態では、第1フェーズの間にコミットすることを約束している参加リソースは、第2フェーズでコミットします。ただし、特殊な状況(たとえば、長時間継続するネットワークまたはノードの障害)では、フェーズ2が完了できない可能性があり、ヒューリスティックな結果が生成されることがあります。

TX_COMMIT_COMPLETED

このフラグは、2フェーズのコミット・プロトコルが完全に終了した後、tx_commit()が返ることを示しています。この設定により、tx_commit()の呼出し側は、トランザクションにヒューリスティックな結果が発生したか、または発生した可能性があるかを示す戻り値を調べることができます。

マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドはtx_set_commit_return()の呼出しを発行できません。

戻り値

正常終了の場合、tx_set_commit_return()は、負でない戻り値TX_OKを返します。

エラー

次の条件の場合、tx_set_commit_return()は、commit_return特性の設定を変更することなく、次の負の値のうちの1つを返します:

[TX_EINVAL]

when_returnは、TX_COMMIT_DECISION_LOGGEDまたはTX_COMMIT_COMPLETEDのいずれかではありません。

[TX_PROTOCOL_ERROR]

この関数が不正なコンテキストで呼び出されました(たとえば、呼出し側がまだtx_open()を呼び出していません)。

[TX_FAIL]

トランザクション・マネージャが致命的エラーを検出しました。このエラーでは、トランザクション・マネージャは、アプリケーションのために作業を行うことができなくなります。エラーの正確な性質がログ・ファイルに書き込まれます。

警告

X/Open TXインタフェースとX-Windowシステムは、いずれも型XIDを定義します。同一のファイルでX-WindowコールとTXコールの両方を使用することはできません。

関連項目:

tx_commit(3c)、tx_info(3c)、tx_open(3c)

2.153 tx_set_transaction_control(3c)

名前

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です。

controlの有効な設定を次に示します:

TX_UNCHAINED

このフラグは、tx_commit()およびtx_rollback()が、これらの呼出し側に返る前に新しいトランザクションを開始してはならないことを示しています。呼出し側は新しいトランザクションを開始するためにtx_begin()を出さなければなりません。

TX_CHAINED

このフラグは、tx_commit()およびtx_rollback()が、これらの呼出し側に返る前に新しいトランザクションを開始することを示しています。

マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドはtx_set_transaction_control()の呼出しを発行できません。

戻り値

正常終了の場合、tx_set_transaction_control()は、負でない戻り値TX_OKを返します。

エラー

次の条件の場合、tx_set_transaction_control()は、transaction_control特性の設定を変更することなく、次の負の値のうちの1つを返します:

[TX_EINVAL]

controlは、TX_UNCHAINEDまたはTX_CHAINEDのいずれかではありません。

[TX_PROTOCOL_ERROR]

この関数が不正なコンテキストで呼び出されました(たとえば、呼出し側がまだtx_open()を呼び出していません)。

[TX_FAIL]

トランザクション・マネージャが致命的エラーを検出しました。このエラーでは、トランザクション・マネージャは、アプリケーションのために作業を行うことができなくなります。エラーの正確な性質がログ・ファイルに書き込まれます。

警告

X/Open TXインタフェースとX-Windowシステムは、いずれも型XIDを定義します。同一のファイルでX-WindowコールとTXコールの両方を使用することはできません。

関連項目:

tx_begin(3c)、tx_commit(3c)、tx_info(3c)、tx_open(3c)、tx_rollback(3c)

2.154 tx_set_transaction_timeout(3c)

名前

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値がゼロの場合、タイムアウト機能は無効になります。

マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT状態のスレッドはtx_set_transaction_timeout()の呼出しを発行できません。

戻り値

正常終了の場合、tx_set_transaction_timeout()は、負でない戻り値TX_OKを返します。

エラー

次の条件の場合、tx_set_transaction_timeout()は、transaction_timeout特性の設定を変更することなく、次の負の値のうちの1つを返します:

[TX_EINVAL]

指定したタイムアウト値が無効です。

[TX_PROTOCOL_ERROR]

関数の呼出し方法が不適切です。たとえば、呼出し側がtx_open()を呼び出す前に呼び出されました。

[TX_FAIL]

トランザクション・マネージャが致命的エラーを検出しました。このエラーでは、トランザクション・マネージャは、アプリケーションのために作業を行うことができなくなります。エラーの正確な性質がログ・ファイルに書き込まれます。

X/Open TXインタフェースとX-Windowシステムは、いずれも型XIDを定義します。同一のファイルでX-WindowコールとTXコールの両方を使用することはできません。

関連項目:

tx_begin(3c)、tx_commit(3c)、tx_info(3c)、tx_open(3c)、tx_rollback(3c)

2.155 userlog(3c)

名前

userlog() - Oracle Tuxedo ATMIシステムの中央イベント・ログにメッセージを書き込みます。

形式

#include “userlog.h”
extern char *proc_name;

int userlog (format [ ,arg] . . .)
char *format;

説明

userlog()は、printf(3S)スタイルのフォーマット指定を受け付け、固定出力ファイル(Oracle Tuxedo ATMIシステムの中央イベント・ログ)を使用します。

中央のイベント・ログは通常のUNIXファイルで、そのパス名は次のように構成されています。ネイティブTuxedoアプリケーションにアタッチされると、TUXCONFIGパラメータの値ULOGPFXがファイル名の接頭辞として使用されます。TUXCONFIGでULOGPFXが設定されていない場合は、$APPDIR/ULOGが使用されます。この接頭辞は、tpinit()の実行時またはサーバー起動時に決定されます。ネイティブTuxedoアプリケーションにアタッチされない場合は、環境変数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つ追加します。

userlog()は、Oracle Tuxedo ATMIシステムが各種のイベントを記録するために使用します。

このuserlogの機構は、いかなるデータベースのトランザクション記録機構からも完全に独立しています。

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

環境変数

ULOGPFX

この環境変数については、前述の「説明」に記載されています。

ULOGMILLISEC

タイムスタンプ・メッセージが秒ではなくミリ秒間隔でuserlogファイルに送るオン/オフ切替え環境変数。指定されない場合、デフォルトのタイムスタンプは秒です。ULOGMILLISECをオンまたはオフにするときは、サーバーを再起動する必要があります。

例: ULOGMILLISEC=Y

ULOGRTNSIZE

userlogローテーション・ファイル・サイズを指定するオン/オフ切替え環境変数。デフォルトのローテーション・ファイル・サイズは2GBです。ULOGRTNSIZEがオンの場合、サーバーは再起動します。

例: ULOGRTNSIZE=1000000 (ファイル・サイズが1MBの場合)

ローテーションされたファイルは、filename.nnという構文で保存されます。

例: ULOG.083103.1、ULOG.083103.2 ... ULOG.083103.10など。

ノート:

ULOGRTNSIZEを指定しなかった場合、ファイルのローテーションは行われません。

TUX_SIGNAL_ULOGPATTERN

ユーザー・ログ・メッセージが特定の正規表現と一致した場合に、プロセスがそれ自体に特定の信号を送信できるようにする環境変数。

有効な値の形式はTUX_SIGNAL_ULOGPATTERN=<var>signal_number</var>:<var>regular_expression</var>です。<var>signal_number</var>は正の整数で、<var>regular_expression</var>形式は、<code>tpsub scribe(3c)</code>マニュアル・ページに記載されているとおりです。

正規表現は、タイムスタンプ、マシン名、プロセスおよびトランザクション情報の追加後にユーザー・ログ・メッセージに対して照合されます。この照合は、userlog()自体で内部生成されたメッセージを除く、すべてのユーザー・ログ・メッセージに対して実行されます。

例:

TUX_SIGNAL_ULOGPATTERN=6:ERROR.*[Mm]emory.allocation

この設定を使用すると、メモリー割当てエラー・メッセージがユーザー・ログに記録された直後に、プロセスが自身に対して信号6 (SIGABRT)を送信します。デフォルトの信号処理は、コアをダンプして終了することです。これは、メモリー割当てエラーの発生原因のデバッグに役に立つ可能性があります。

ULOGDEBUG

環境変数ULOGDEBUGの最初の文字が1またはyの場合、userlog()に送信されたメッセージは、fprintf(3S)関数を使用して、呼出しプロセスの標準エラーにも書き込まれます。

例

変数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()メッセージを使用する場合には、アプリケーション・エラーをデバッグするのに有用なものだけを使用することをお薦めします。ログが情報であふれてしまうと、本来のエラーを検出するのが難しくなります。

関連項目:

• UNIXシステムのリファレンス・マニュアルのprintf(3S)
• 『Oracle Tuxedoアプリケーション実行時の管理』の「Oracle Tuxedoアプリケーションのモニタリング」のアクティビティをモニターするためのログ・ファイルの使用に関する項

2.156 Usignal(3c)

名前

Usignal() - Oracle Tuxedo ATMIシステム環境でのシグナル処理。

形式

#include “Usignal.h”

UDEFERSIGS()
UENSURESIGS()
UGDEFERLEVEL()
URESUMESIGS()
USDEFERLEVEL(level)

int (*Usignal(sig,func)()
int sig;
int (*func)();

void Usiginit()

説明

Oracle Tuxedo ATMIシステム・ソフトウェアが提供する多くの機能は、共有メモリー内のデータ構造に並行アクセスする必要があります。共有データ構造にアクセスするプログラムはユーザー・モードで走るため、シグナルを使用して中断することができます。共有データ構造の一貫性を維持するためには、それらの構造にアクセスする類の操作が、UNIXシステムのシグナルを受け取っても中断されないことが重要です。ここで説明する関数は、ほとんどの一般的なシグナルに対する保護機構を提供するもので、Oracle Tuxedo ATMIシステムのコードの多くがその内部で使用します。また、これらの関数は、アプリケーション側で使用して、不用意にシグナルを受け取らないようにします。

このOracle Tuxedo ATMIシステムのシグナル処理パッケージは、重要なコード部ではシグナルの発行を遅らせる、という発想から生まれたものです。このため、シグナルは、それが受信されてもすぐには処理されません。Oracle Tuxedo ATMIシステムのルーチンはまず最初に送信されたシグナルを捕捉します。そのシグナルを処理しても安全であれば、そのシグナルに指定された処理が実行されます。シグナルが安全でないということが判明した場合には、そのシグナルの到着が通知されるだけで、重要なコード部が終了したことをユーザーが示すまでは、そのシグナルの処理は行われません。

マルチスレッド・プログラムでシグナルを使用することは可能ですが、使用しないことをお薦めします。ただし、シグナルを使用した場合には、マルチスレッドのアプリケーション中のスレッドは、TPINVALIDCONTEXTを含め、どのコンテキスト状態で実行していてもUsignal()の呼出しを発行できます。

シグナルの捕捉

rmopen()またはtpinit()を使用するユーザー・コードは、Usignal()関数を使用してシグナルを捕捉するようにします。Usignal()はUNIXのsignal()システム・コールのように機能しますが、例外としてUsignal()では最初に、内部ルーチンがシグナルを捕捉してから、ユーザー・ルーチンをディスパッチするように調整します。

シグナルの遅延とリストア

ここで説明する呼出しは、アプリケーション・コードでシグナルを後回しにする必要がある場合にのみ使用します。一般に、これらのルーチンは、不適切な場面でシグナルが到着しないようにするためにOracle Tuxedo ATMIシステムのルーチンが自動的に呼び出します。

シグナルを遅延またはリストアする前に、メカニズムを初期化する必要があります。初期化は、Oracle Tuxedo ATMIシステム・クライアントがtpinit()を呼び出したときに、Oracle Tuxedo ATMIシステムのクライアントとサーバーのために自動的に行われます。また、初期化は、アプリケーションがはじめにUsignal()呼び出すときに行われます。初期化は、Usiginit()を呼び出すことで明示的に行うことができます。

UDEFERSIGS()マクロは、重要なコード部分に入るときに使用してください。UDEFERSIGS()が呼び出された後、シグナルは保留状態になります。また、URESUMESIGS()マクロは、その重要な部分が終わる時点で呼び出すようにします。シグナル遅延スタックに注意してください。このスタックは、最初にゼロに設定されるカウンタを通して実現されます。UDEFERSIGS()への呼出しによってシグナルが遅延されると、カウンタの値が1大きくなります。URESUMESIGS()の呼出しによりシグナルが再開されると、カウンタの値は1小さくなります。カウンタがゼロ以外の値のときにシグナルが到着すると、そのシグナルの処理は後回しになります。シグナルが到着したときにカウンタがゼロであれば、そのシグナルはただちに処理されます。シグナルの再開により、カウンタがゼロになると(すなわち、再開の前のカウンタ値が1のとき)、その据置期間に到着したシグナルが処理されます。一般に、UDEFERSIGS()の呼出しは、URESUMESIGS()の呼出しと対で使用するようにします。

UDEFERSIGS遅延カウンタの値をインクリメントしますが、返す値はそのインクリメント前の値です。マクロUENSURESIGS()は、遅延カウンタを明示的にゼロに設定する(そして、据え置かれたシグナルを強制的に処理させる)ときに使用できます。この場合、ユーザーはUDEFERSIGS()とURESUMESIGS()の不一致が生じないようにする必要があります。

関数UGDEFERLEVEL()は遅延カウンタの現在の設定値を返します。マクロUSDEFERLEVEL(level)を使用すると、特定の遅延レベルを設定することができます。UGDEFERLEVEL()とUSDEFERLEVEL()は、setjmp/longjmpの状況で適切にカウンタを設定するときに便利です。つまり、setjmp()が呼び出されたときに、UGDEFERLEVEl()の呼出しによってカウンタの値を保存し、longjmp()が実行されたときにUSDEFERLEVEL()の呼出しによりカウンタ値をリストアする、という考え方です。

注意事項

Usignalは、SIGHUP、SIGINT、SIGQUIT、SIGALRM、SIGTERM、SIGUSR1,およびSIGUSR2の各シグナルについて遅延処理を行います。その他すべてのシグナル番号に対する処理リクエストは、Usignal()により直接signaL()に渡されます。シグナルは非常に長い期間その処理が据え置かれることがあります。このため、シグナル遅延の間、シグナルの到着がすべてカウントされます。何回も到着する可能性のあるシグナルの処理が安全な場合、そのシグナルの処理ルーチンが繰り返し呼び出され、シグナルが到着した各シグナルが処理されます。各呼出しの前には、シグナルのデフォルト処理が行われます。つまり、安全なコードで連続して処理が行われる場合と同様に、据え置かれたシグナルが処理されるようにする、という考え方です。

一般に、ユーザーはsignal()とUsignal()の呼出しを同じシグナルに対して組み合せて使用するべきではありません。できれば、Usignal()を使用する方法をとることが推奨されます。これによって、常にシグナルの状態を知ることができるからです。それは、アプリケーションがOracle Tuxedo ATMIシステム・サービスでアラームを使用したい場合などには必要です。こうすることにより、Usiginit()は、シグナルの遅延メカニズムを初期化するために呼び出されなければなりません。次に、signal()を呼び出し、意図するシグナル用に、メカニズムを変更します。シグナルの遅延メカニズムをリストアするために、Usignal()をSIG_IGNで呼び出してから、再び、意図するシグナル処理関数で呼び出す必要があります。

シェル変数UIMMEDSIGSを使用すれば、シグナルの据置を変更することができます。この変数の値が次のように英字yで始まる場合、

UIMMEDSIGS=y

シグナルはUsignal()コードでインターセプトされません(したがって、据え置かれません)。このような場合、Usignal()の呼出しはただちにsignaL()に渡されます。

Usignalは、DOSオペレーティング・システムでは使用できません。

ファイル

Usignal.h

関連項目:

UNIXシステムのリファレンス・マニュアルのsignal(2)

2.157 Uunix_err(3c)

名前

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);
}