ATMI C関数リファレンス

     前  次    新規ウィンドウで目次を開く    PDFとして表示 - 新規ウィンドウ  Adobe Readerを入手 - 新規ウィンドウ
コンテンツはここから始まります

セクション3c - C関数

表1 Oracle Tuxedo ATMI C関数
名前
説明
C言語ATMIの概要を提供します。
アプリケーション固有のブロッキング・フック関数を確立します。
実行時にユーザー定義のバッファ・タイプをインストールまたは置換します。
進行中のブロッキング呼出しが存在するかどうかを確認します。
Oracle Tuxedo ATMI任意イベントに対するWindowsメッセージを掲示します。
tmtype_sw_tにおける要素の意味
プログラム・メッセージを読み取ります。
メッセージ・カタログをオープンまたはクローズします。
十進数変換および算術ルーチン
DTD、スキーマおよびエンティティ・ファイルがキャッシュされている場所の絶対パスを取得します。これは、特定のXercesパーサー・クラス・メソッドを指定します。
DTD、スキーマおよびエンティティ・ファイルのキャッシング・メカニズムを取得します。これは、特定のXercesパーサー・クラス・メソッドを指定します。
tm構造体をカレンダ時間に変換します。
言語情報
RPCスタブ内のメモリーを割り当てます。
クライアント・スタブから戻されたメモリーを解放します。
スタブのメモリー管理スキーム内のリソースおよび割り当てられたメモリーをリリースします。
スタブのメモリー管理環境を有効にします。
rpc_sm_allocate()ルーチンによって割り当てられたメモリーを解放します。
メモリー割当てとクライアント・スタブによって使用される解放メカニズムを設定します。
現在のメモリー割当てとクライアント・スタブによって使用される解放メカニズムを、クライアントによって提供されたものと交換します。
プログラムのロケールの修正および問合せを行います。
DTD、スキーマおよびエンティティ・ファイルがキャッシュされるディレクトリを設定します。これは、特定のXercesパーサー・クラス・メソッドを指定します。
DTD、スキーマおよびエンティティ・ファイルのキャッシングをデフォルトでオンまたはオフにします。これは、特定のXercesパーサー・クラス・メソッドを指定します。
エラー・メッセージ文字列を取得します。
日付および時間を文字列に変換します。
現在のトランザクションを中断するルーチン
サービス・リクエストを送信するルーチン
ブートされていないアプリケーションを管理します。
サービス名を通知するルーチン
型付きバッファの割当てを行うルーチン
アプリケーション生成のサーバー・スレッドで新しいTuxedoコンテキストを生成および初期化するルーチン
サーバー・プロセス内のアプリケーション生成のコンテキストを終了するルーチン
リソース・アクセスを制御します。
トランザクションを開始するルーチン
名前によって通知をブロードキャストするルーチン
サービス・リクエストを送信し、その応答を待つルーチン
未終了の応答に対する呼出し記述子を無効にするためのルーチン
アプリケーションへの参加に認証が必要かどうかをチェックするルーチン
任意通知型メッセージをチェックするルーチン
リソース・マネージャをクローズするルーチン
現在のトランザクションをコミットするルーチン
会話型サービスの接続を確立するルーチン
構造体を文字列表現に、または文字列表現を構造体に変換します。
入力バッファ内にある文字のエンコードをターゲットの名前付きのエンコードに変換します。
管理リクエスト内のアプリケーション・パスワードを暗号化します。
キューからメッセージを取り出すルーチン
会話型サービスの接続を切断するルーチン
メッセージをキューに登録するルーチン
型付きメッセージ・バッファに関連付けられたデジタル署名および暗号化情報にアクセスします。
最後のOracle Tuxedo ATMIシステム・コールで生成されたエラーに関する詳細を取得します。
型付きメッセージ・バッファを、デジタル署名と暗号化エンベロープを含むエクスポート可能なマシン独立型の文字列表現に変換します。
FML32バッファ・データをXMLバッファ・データに変換します。
FMLバッファ・データをXMLバッファ・データに変換します。
サービス・リクエストを他のサービス・ルーチンに転送するルーチン
型付きバッファを解放するルーチン
以前に設定された、1秒または1ミリ秒当たりの非トランザクション・ブロック時間値を戻すルーチン
管理認証キーを取得します。
呼出しパス・メッセージ・モニタリング属性を受信するルーチン
現在のアプリケーション関連のコンテキスト識別子を取り出す
トランザクション・モードかどうかチェックするルーチン
型付きバッファからコード・セットのエンコード名を取得します。
Tuxedoリポジトリ・ファイルからサービスおよびパラメータ情報を取得するルーチン
以前のリクエストからの応答を受信するルーチン
サービス・リクエストの優先度を取得するルーチン
エクスポートされた表現を型付きメッセージ・バッファに変換し戻します。
アプリケーションに参加します。
前にオープンされたキー・ハンドルをクローズ
キー・ハンドルに関連付する情報を獲得
デジタル署名生成、メッセージの暗号化、またはメッセージの復号化のためのキー・ハンドルをオープン
キー・ハンドルに関連付けられている省略可能な属性パラメータを設定
クライアント識別子によって通知を送信するルーチン
リソース・マネージャをオープンするルーチン
イベントを通知
型付きバッファのサイズを変更するルーチン
会話型接続でメッセージを受信するルーチン
グローバル・トランザクションを再開
サービス・ルーチンから戻るためのルーチン
複数のRMサーバー・グループで構成された特定のRMをクローズするルーチン
指定されたRMのトランザクション・ブランチのかわりに実行された現在の作業を終了するルーチン
複数のRMサーバー・グループに関連付けられている*RMSセクションで構成された特定のRMをオープンするルーチン
MRMサーバーの指定されたRMのトランザクション・ブランチのかわりに作業を開始するルーチン
次のサービス呼出しまたはコンテキストごとに使用されるすべてのサービス呼出しの非トランザクション・ブロック時間値を秒単位またはミリ秒単位で設定するルーチン
tpcommit()がいつ戻るかを設定するルーチン
暗号化のための型付きメッセージ・バッファをマークします。
会話型接続でメッセージを送信するルーチン
サービス・ルーチンのテンプレート
Tuxedoリクエストに帯域外情報を追加するルーチン
現在のアプリケーション関連にコンテキスト識別子を設定
型付きバッファのコード・セットのエンコード名を設定します。
Tuxedoサービス・メタデータ・リポジトリ・ファイルからのサービスおよびパラメータ情報を追加、編集または削除します。
任意通知型メッセージの処理方法を設定します。
デジタル署名のための型付きメッセージ・バッファをマークします。
サービス・リクエストの優先度を設定するルーチン
Oracle Tuxedo ATMIシステム・エラーのエラー・メッセージ文字列を取得します。
Oracle Tuxedo ATMIシステムのエラー詳細メッセージの文字列を取得します。
イベントにサブスクライブ
グローバル・トランザクションを一時停止
Oracle Tuxedo ATMIシステム・サーバーを終了します。
Oracle Tuxedo ATMIシステム・サーバーを初期化します。
Oracle Tuxedo ATMIサーバー・スレッドを終了します。
Oracle Tuxedo ATMIサーバー・スレッドを初期化します。
アプリケーションを分離
型付きバッファ情報を判別するルーチン
サービス名の通知を解除するルーチン
イベントへのサブスクライブを取り消す
トレース情報を提供するユーザー定義ルーチン
XMLバッファ・データをFML32バッファ・データに変換します。
XMLバッファ・データをFMLバッファ・データに変換します。
例外復帰インタフェース
環境名の値を戻します。
プロセス環境で環境変数TPMBACONVの値を取得します。
プロセス環境で環境変数TPMBENCのコード・セットのエンコード名を取得します。
環境に対して値を変更または追加します。
ファイルから環境に変数を追加します。
プロセス環境で環境変数TPMBACONVの値を設定します。
プロセス環境で環境変数TPMBENCのコード・セットのエンコード名を設定します。
現在のスレッドの環境変数を変更または追加します。
グローバル・トランザクションを開始
リソース・マネージャ・セットをクローズ
グローバル・トランザクションをコミットします。
グローバル・トランザクション情報を返す
リソース・マネージャ・セットをオープン
グローバル・トランザクションをロールバックします。
commit_return特性を設定
transaction_control特性を設定
transaction_timeout特性を設定
Oracle Tuxedo ATMIシステムの中央イベント・ログにメッセージを書き込みます。
Oracle Tuxedo ATMIシステム環境でのシグナル処理
UNIXシステム・コールのエラーを印刷します。

 


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

説明

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

通信パラダイム

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

メッセージ配信

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

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

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

メッセージの順序付け

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

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

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

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

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

ATMIトランザクション

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

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

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

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

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

TXトランザクション

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

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

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

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

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

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

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

クライアント・ルーチンとサービス・ルーチンは、tx_set_transaction_control()を呼び出すことによて連鎖モードを有効または無効にできます。連鎖モードと非連鎖モード間の移行は、次のtx_commit()またはtx_rollback()の呼出しに影響を与えます。tx_set_transaction_control()の呼出しによって、呼出し側がトランザクション・モードに入ったり、トランザクション・モードから抜けたりすることはありません。

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

トランザクション特性

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

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

エラー処理

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

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

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

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

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

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

タイムアウト

Oracle Tuxedo ATMIシステムには3種類のタイムアウトがあります。1つは、トランザクションの開始から終了までの時間に対応します。2つめは、呼出し元に制御が戻るまでブロッキング呼出しがブロック状態になる最長時間に対応します。3つめはサービスのタイムアウトです。これは呼出しの秒数が構成ファイルのSERVICESセクションにおけるSVCTIMEOUTパラメータで指定された秒数を越えた時に発生します。

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

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

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

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

トランザクションがタイムアウトになった場合、トランザクションが中断される前に有効な通信は、TPNOREPLYTPNOTRAN、およびTPNOBLOCKを設定したtpacall()の呼出しのみです。

リリース6.4以降、TPESVCERRエラー・コードの他に追加の詳細が提供されています。タイムアウトのしきい値を超えたことによってサービスが失敗した場合、イベント .SysServiceTimeoutが転記されます。

動的サービス通知

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

バッファ管理

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

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

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

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

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

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

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

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

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

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

type要素はNULL以外で、8文字長である必要があります。この要素がスイッチ内で一意でない場合は、subtype()がNULL以外である必要があります。

subtype()要素には、NULL、最大16文字の文字列、または* (ワイルドカード文字)を指定できます。type()subtype()の組合せによって、スイッチ内の要素が一意に識別される必要があります。

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

dfltsize()要素は、バッファの割り当てまたは再割当てを行うときに使用します。tpalloc()tprealloc()のセマンティクスでは、dfltsize()の値、またはtpalloc()関数とtprealloc()関数のsizeパラメータの値の大きい方が、バッファの作成または再割当てに使用されます。固定サイズのC構造体などの場合、バッファ・サイズはその構造体と同じにするべきです。dfltsize()がこの値に設定されると、呼出し側は、バッファが渡されるルーチンに対してバッファ長を指定する必要がありません。dfltsize()には0以下を指定できます。ただし、tpalloc()またはtprealloc()が呼び出され、呼び出される関数のsizeパラメータも0以下の場合、ルーチンは失敗します。dfltsize()を0よりも大きい値に設定することを推奨します。

Oracle Tuxedo ATMIシステムでは、5つの基本バッファ・タイプが提供されます。

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

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

非請求通知

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

表3 クライアント・スレッドのコンテキスト状態の変化
この関数が実行されるとき...
このコンテキスト状態のスレッドの結果は...
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

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

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

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

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

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

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

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

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

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

次の戻り値とフラグの定義は、ATMIルーチンによって使用されます。異なるトランザクション・モニターで変更または再コンパイルせずにアプリケーションを機能させるには、各システムで次のようにフラグと戻り値を定義する必要があります。

 /*
* 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;

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 */

ATMIの状態遷移

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

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

表4 使用可能な関数
関数
プロセス・タイプ
リクエスト/レスポンス型サーバー
会話型サーバー
クライアント
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()を使用する必要があります。

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

表5 スレッド初期化状態
関数
状態
非初期化
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

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

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

表6 リソース・マネージャの状態
関数
状態
クローズ
R0
オープン
R1
tpopen
R1
R1
tpclose
R0
R0
tpbegin
 
R1
tpcommit
 
R1
tpabort
 
R1
tpsuspend
 
R1
tpresume
 
R1
フラグTPTRANが設定されたtpservice
 
R1
ほかのすべてのATMI関数
R0
R1

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

表7 アプリケーションの関連付けのトランザクション状態
関数
状態
トランザクション内ではない
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

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

表8 非同期リクエスト記述子の状態
関数
状態
記述子なしA0
有効な記述子A1
tpacall
A1
 
tpgetrply
 
A0
tpcancel
 
A0 a
tpabort
A0
A0 b
tpcommit
A0
A0 b
tpsuspend
A0
A1 c
tpreturn
A0
A0
tpforward
A0
A0
tpterm
I0
I0
ほかのすべてのATMI関数
A0
A1

注: a この状態遷移は、記述子が呼出し側のトランザクションに関連付けられていない場合にのみ発生します。
注: b この状態遷移は、記述子が呼出し側のトランザクションに関連付けられている場合にのみ発生します。
注: c 記述子が呼出し側のトランザクションに関連付けられている場合、tpsuspend()はプロトコル・エラーを戻します。

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

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

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

TXの状態遷移

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

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

関連項目

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

 


AEMsetblockinghook(3c)

名前

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

形式

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

説明

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

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

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

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

戻り値

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

エラー

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

[TPEPROTO]

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

移植性

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

注意事項

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

 


AEOaddtypesw(3c)

名前

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

形式

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

int FAR PASCAL AEOaddtypesw(TMTYPESW *newtype)

説明

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

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

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

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

戻り値

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

エラー

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

[TPEINVAL]

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);
}

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

  ; EXAMPLE.DEF file

NAME EXAMPLE

DESCRIPTION 'EXAMPLE for OS/2'

EXETYPE OS/2


EXPORTS
Nfinit
Nfreinit
Nfuninit
....

関連項目

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

 


AEPisblocked(3c)

名前

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

形式

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

説明

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

戻り値

未終了のブロッキング関数が完了を待機している場合、AEPisblocked()は1を返します。それ以外の場合には、0を返します。

エラー

エラーは返されません。

移植性

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

備考

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

関連項目

AEMsetblockinghook(3c)

 


AEWsetunsol(3c)

名前

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

形式

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

説明

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

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

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

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

戻り値

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

エラー

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

[TPESYSTEM]

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

[TPEOS]

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

移植性

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

注意事項

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

関連項目

tpsetunsol(3c)

 


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を使用しなければなりません。typesubtypeの組合せは、スイッチ内でユニークに要素を指定するものでなければなりません。

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

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

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

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

_tmreinitbuf

_tmreinitbuf()はほとんど_tminitbuf()と同様に働きます。このルーチンは、バッファの再割当ての後、tprealloc()の中から呼び出されます。

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

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

_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()の呼出し側も異常終了を示すtperrnoTPESYSTEMに戻します。

_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()の呼出し側も異常終了を示すtperrnoTPESYSTEMに戻します。

_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のいずれかを指定します。

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

opTMDECODEを指定すると、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 (opTMENCODEと同じ)またはelen (opTMDECODEと同じ)を戻します。

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

_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()の呼出し側も異常終了を返します。これにより、tperrnoTPESYSTEMにセットされます。サーバーあるいはサービスが利用できないために_tmroute()が異常終了した場合は、tperrnoTPENOENTにセットされます。

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

_tmfilter()

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

exprlenが -1の場合、exprはNULLで終わる文字列とみなされます。それ以外の場合、exprexprlenバイトのバイナリ・データとみなされます。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()の呼出し側も異常終了を返してtperrnoTPESYSTEMに設定します。

_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()の呼出し側も異常終了を返してtperrnoTPESYSTEMに設定します。

関連項目

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

 


catgets(3c)

名前

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

形式

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

説明

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

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

診断

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

関連項目

catopen、catclose(3c)

 


catopen、catclose(3c)

名前

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

形式

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

説明

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

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

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

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

メタキャラクタ%は、置換フィールドを示します。この例で、%LLANG環境変数の現在の設定と置き替わります(下記の項を参照)。また、%Ncatopen()に渡される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()は使用されません。この引数は将来使用する予定であり、現在は必ずゼロを指定してください。このフィールドの値を別の値に変更した場合の動作は不定です。

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

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

診断

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

関連項目

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

 


decimal(3c)

名前

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

形式

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

説明

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

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

ネイティブの十進数表現

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

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

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

戻り値

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

 


getURLEntityCacheDir(3c)

名前

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

形式

char * getURLEntityCacheDir()

説明

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

 


getURLEntityCaching(3c)

名前

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

形式

bool getURLEntityCaching()

説明

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

 


gp_mktime(3c)

名前

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

形式

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

説明

gp_mktime()は、timeptrが指すtm構造体で表現される時間をカレンダ時間(世界協定時(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フィールドは、ローカル時間で、いつ変更が行われるかを示します。 startendの形式は次のうちのどれかです。

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)

 


nl_langinfo(3c)

名前

nl_langinfo() - 言語情報

形式

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

char *nl_langinfo (nl_item item);

説明

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

例:

nl_langinfo (ABDAY_1);

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

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

診断

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

注意事項

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

関連項目

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

 


rpc_sm_allocate、rpc_ss_allocate(3c)

名前

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

形式

#include <rpc/rpc.h>

idl_void_p_t rpc_sm_allocate(unsigned32 size, unsigned32 *status)

idl_void_p_t rpc_ss_allocate(unsigned32 size)

説明

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

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

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

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

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

rpc_s_ok

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

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

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

戻り値

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

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

関連項目

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

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

 


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

 


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

 


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

 


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

 


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

 


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

 


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)

 


setURLEntityCacheDir(3c)

名前

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

形式

void setURLEntityCacheDir (const char* cachedir)

説明

setURLEntityCacheDir()は、キャッシュが有効になっており、ユーザーがDTD、スキーマ、およびエンティティ・ファイルを特定のディレクトリにキャッシュする場合に呼び出します。cachedirには、ファイルの場所の絶対パスを指定します。

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

 


setURLEntityCaching(3c)

名前

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

形式

void setURLEntityCaching (bool UseCache)

説明

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

 


strerror(3c)

名前

strerror()—エラー・メッセージ文字列の取込み

形式

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

説明

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

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

関連項目

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

 


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
該当ロケールの午前または午後の表現
%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_TIMElocaleを設定することによって特定の言語に変更することができます。

タイム・ゾーン

タイム・ゾーンは環境変数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)

 


tpabort(3c)

名前

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

形式

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

説明

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

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

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

現時点では、tpabort()の唯一の引数flagsは将来使用する予定であり、現在は必ずゼロを指定してください。

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

戻り値

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

エラー

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

[TPEINVAL]

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)

 


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であったり、datatpalloc()で割り当てられた領域を指していなかったり、あるいはflagsが無効です)。

[TPENOENT]

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

[TPEITYPE]

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

[TPELIMIT]

未終了の非同期リクエストの数が、保持できる最大数に達したため、呼出し側のリクエストが送信できませんでした。
注: 以前のバージョンでは50だった最大数が、Oracle Tuxedo 12cリリース2 (12.1.3)から2048になりました。

[TPETRAN]

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

[TPETIME]

このエラー・コードは、タイムアウトが発生したか、または現在のトランザクションがすでに「ロールバックのみ」とマークされているにもかかわらずtpacall()が試行されたことを示します。
呼出し側がトランザクション・モードの場合、トランザクションはすでにロールバックのみであるか、またはトランザクション・タイムアウトが発生しました。このトランザクションは、中断のみとしてマークされます。呼出し側がトランザクション・モードでない場合、ブロッキング・タイムアウトが発生しています。(ブロッキング・タイムアウトは、TPNOBLOCKまたはTPNOTIMEが指定されている場合は発生しません。) トランザクション・タイムアウトが発生した場合、トランザクションが中断されない限り、新しいリクエストの送信や未処理の応答の受信はできず、TPETIMEが発生します。その例外とは、ブロックされず、応答を期待せず、かつ呼出し側のトランザクションのかわりに送信されない(つまり、TPNOTRANTPNOBLOCKおよび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)

 


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に入っています。

[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アプリケーション実行時の管理』

 


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)tpunadvertise(3c)

 


tpalloc(3c)

名前

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

形式

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

説明

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

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

なお、typeの最初の8バイトとsubtypeの最初の16バイトだけが有効です。

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

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

戻り値

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

エラー

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

[TPEINVAL]

無効な引数が与えられた場合(たとえば、typeがNULLである場合)。

[TPENOENT]

tmtype_swのどのエントリもtypeと一致しない場合。また、subtypeが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)

 


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のメンバーであるusrnamedata、およびdatalenが使用されます。SECURITYUSER_AUTH以上に設定されている場合、tpappthrinit()に渡されるTPINITバッファは、そのアプリケーションに対して構成された認証サービスに渡されます。TPINITバッファの特定のフィールドが認証サービスによって使用されるかどうかは、実装によって異なります。NONEおよびAPP_PWの各セキュリティ・レベルでは、tpthrinfoのメンバーであるcltnamegrpnameおよび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アプリケーションのプログラミング」

 


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

 


tpatz(3c)

名前

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

形式

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

説明

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

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

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

戻り値

エラー

[TPEINVAL]

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

注意事項

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

詳細は、認証キャッシュの設定に関する項を参照してください。

 


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)

 


tpbroadcast(3c)

名前

tpbroadcast() - 名前によって通知をブロードキャストするルーチン

形式

#include <atmi.h> 

int tpbroadcast(char *lmid, char *usrname, char *cltname,
char *data, long len, long flags)

説明

tpbroadcast()は、クライアント・プロセスやサーバー・プロセスがシステム内に登録されているクライアントに非請求メッセージを送ることができるようにします。ターゲットのクライアント・セットは、tpbroadcast()に渡されるワイルドカード以外の識別子すべてと一致するクライアントで構成されます。識別子の指定にワイルドカードを使用できます。

lmidusrnameおよびcltnameは、ターゲットのクライアント・セットの選択に使用する論理識別子です。引数のNULL値は、その引数のワイルドカードとなります。ワイルドカード引数は、そのフィールドの全クライアント識別子と一致します。長さ0の文字列の引数は、長さ0のクライアント識別子とのみ一致します。各識別子は、システムが有効とみなすよう定義されたサイズの制約事項を満たさなければなりません。つまり、各識別子の長さは0からMAXTIDENT文字まででなければなりません。

このリクエストのデータ部はdataによって示され、以前にtpalloc()によって割り当てられたバッファです。lenに送信するデータの大きさを指定します。ただし、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)

 


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のアドレスを指定してください。FMLFML32バッファは、通常最小サイズ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は、構成属性で、自動的にトランザクション・モードで呼び出されるようにすることができます。このフラグを設定するトランザクション・モードの呼出し側は、トランザクション・タイムアウトの影響を受けます。サービスが異常終了した場合でも、起動時にこのフラグが設定されていれば、呼出し側のトランザクションに影響は及びません。

TPNOCHANGE

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

TPNOBLOCK

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

TPNOTIME

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

TPNOCOPY

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

TPSIGRSTRT

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

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

戻り値

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

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

エラー

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

[TPEINVAL]

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

[TPENOENT]

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

[TPEITYPE]

idataのタイプとサブ・タイプは、svcが受け付けできるものでありません。

[TPEOTYPE]

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

[TPETRAN]

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

[TPETIME]

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

[TPESVCFAIL]

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

[TPESVCERR]

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

 


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)

 


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)

 


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)

 


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)

 


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)

 


tpconnect(3c)

名前

tpconnect() - 会話型サービス・ルーチンの接続を設定するルーチン

形式

#include <atmi.h> 

int tpconnect(char *svc, char *data, long len, long flags)

説明

tpconnect()により、プログラムは会話型サービスsvcとの半二重接続をセットアップすることができます。この名前は、会話型サーバーがポストした会話型サービス名の1つでなければなりません。

呼出し側は、接続セットアップ処理の一部として、アプリケーション定義データをリスニング・プログラムに渡すことができます。呼出し側がデータを渡す選択をした場合には、datatpalloc()が以前に割り当てたバッファを指していなければなりません。lenには送信バッファの大きさを指定します。ただし、dataが長さの指定を必要としないバッファを指している場合(FMLフィールド化バッファなど)、lenは無視されます(0でかまいません)。また、dataはNULLの場合もあります。この場合、lenは無視されます(アプリケーション・データは会話型サービスに渡されません)。dataのタイプとサブタイプは、svcが認識するタイプおよびサブタイプと一致しなければなりません。datalenは、該当サービスの呼出し時に使用する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またはTPRECVONLYflagsに指定されていない、あるいはflagsが無効であるなど)。

[TPEITYPE]

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

[TPELIMIT]

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

[TPENOENT]

svcが存在しないか、会話型サーバーでないか、または名前が"."で始まるため、svcへの接続を開始できません。

[TPEOS]

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

[TPEPROTO]

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

[TPESYSTEM]

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

[TPETIME]

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

[TPETRAN]

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

[TPGOTSIG]

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

関連項目

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

 


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文字の長さがなければなりません。

TPTRANIDXIDの値が異なる文字列バージョンをキー・フィールドとして許すTM_MIB(5)クラス(たとえばT_TRANSACTIONおよびT_ULOG)にアクセスする場合は、システムはこれらの値を等しいものとして扱うことに注意してください。したがって、アプリケーション・プログラムでは、これらのデータ・タイプの文字列の値を作ったり操作したりすべきではありません。これらの値のいずれかがキー・フィールドとして使用される場合、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)

 


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_encodinglen、またはbufpの値がNULLになっています。lenまたはtarget_encodingが無効です。

[TPEPROTO]

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

[TPESYSTEM]

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

[TPEOS]

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

関連項目

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

 


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アプリケーション実行時の管理』

 


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

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

TPNOTIME

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

TPNOCHANGE

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

TPSIGRSTRT

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

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

このフラグが設定されていると、キューが空の場合はエラーが戻されません。かわりに、メッセージを取り出せるようになるまで、プロセスは待機する必要があります。TPQWAITTPQGETBYMSGIDまたはTPQGETBYCORRIDとともに設定されている場合、指定されたメッセージ識別子または相関識別子を持つメッセージがキューに存在しないときは、エラーが戻されません。かわりに、基準を満たすメッセージを取り出せるようになるまで、プロセスは待機する必要があります。プロセスが呼出し側のトランザクション・タイムアウトに従っている場合、またはトランザクション・モードでない場合、プロセスは、TMQUEUEプロセスに-tオプションで指定されたタイムアウトの影響を受けます。
要求する基準を満たすメッセージがすぐには利用できず、設定されたアクションのリソースを使い尽くしてしまった場合には、tpdequeueは -1を返しtperrnoTPEDIAGNOSTICに設定し、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()の呼出しが成功し、メッセージがサービスの配信品質と共にキューに登録されていた場合、TPQQOSDEFAULTPERSISTTPQQOSPERSISTENT、またはTPQQOSNONPERSISTENTフラグがctl->delivery_qosに格納されます。メッセージがキューに登録されたときに配信サービスの品質が明示的に指定されていない場合は、ターゲットとなるキューのデフォルトの配信ポリシーによってメッセージ配信の品質が決まります。

TPQREPLYQOS

このフラグが設定され、tpdequeue()の呼出しが成功し、メッセージがサービスの応答品質と共にキューに登録されていた場合、TPQQOSDEFAULTPERSISTTPQQOSPERSISTENT、またはTPQQOSNONPERSISTENTフラグがctl->reply_qosに格納されます。メッセージがキューに登録されていたときに応答のサービス品質が明示的に指定されていない場合、ctl->replyqueueキューのデフォルトの配信ポリシーによって、すべての応答に対する配信サービスの品質が決まります。
デフォルトの配信ポリシーは、メッセージに対する応答がキューに登録されるときに決定される点に注意してください。つまり、元のメッセージがキューに登録されてからメッセージに対する応答が登録されるまでの間に、応答キューのデフォルトの配信ポリシーが変更された場合、応答が最後に登録される時点で有効なポリシーが使用されます。

TPQREPLYQ

このフラグが設定されていてtpdequeue()の呼出しが正常終了し、メッセージが応答キューによってエンキューされた場合、応答キューの名前がctl矢印記号replyqueueに格納されます。メッセージへの応答は、リクエスト・メッセージと同じキュー・スペース内の指定された応答キューに登録されます。

TPQFAILUREQ

このフラグが設定されていてtpdequeue()の呼出しが正常終了し、メッセージが失敗キューによってエンキューされた場合、失敗キューの名前がctl矢印記号failurequeueに格納されます。失敗メッセージは、リクエスト・メッセージと同じキュー・スペース内の指定された失敗キューに登録されます。

flagsパラメータの残りのビットは、tpdequeue()が呼び出されるとクリア(0に設定)されます。これには、TPQTOPTPQBEFOREMSGIDTPQTIME_ABSTPQTIME_RELTPQEXPTIME_ABSTPQEXPTIME_REL、およびTPQEXPTIME_NONEが含まれます。これらのビットは、tpenqueue()の入力情報を制御するflagsパラメータの有効なビットです。

tpdequeue()の呼出しが失敗してtperrnoTPEDIAGNOSTICが設定された場合は、失敗の原因を示す値が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]

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

[TPETIME]

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

[TPEBLOCK]

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

[TPGOTSIG]

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

[TPEPROTO]

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

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

 


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で失敗します。その例外とは、ブロックされず、応答を期待せず、かつ呼出し側のトランザクションのかわりに送信されない(つまり、TPNOTRANTPNOBLOCKおよび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)

 


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

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

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

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

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

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

TPNOTRAN

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

TPNOBLOCK

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

TPNOTIME

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

TPSIGRSTRT

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

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

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

制御パラメータ

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

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

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

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

TPNOFLAGS

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

TPQTOP

このフラグを設定すると、キューの順序付けは無効になり、メッセージはキューの先頭に登録されます。このリクエストは、順序付けを無効にするようにキューが設定されているかどうかによって、使用できない場合があります。TPQTOPTPQBEFOREMSGIDは、相互に排他的なフラグです。

TPQBEFOREMSGID

このフラグを設定すると、キューの順序はオーバーライドされ、メッセージはctl矢印記号msgidによって識別されるメッセージの前に登録されます。このリクエストは、順序付けを無効にするようにキューが設定されているかどうかによって、使用できない場合があります。TPQTOPTPQBEFOREMSGIDは、相互に排他的なフラグです。また、メッセージ識別子の値は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_ABSTPQTIME_RELは、相互に排他的なフラグです。絶対時間は、キュー・マネージャ・プロセスが存在するマシン・クロックによって決定されます。

TPQTIME_REL

このフラグを設定すると、メッセージは、キューへの登録操作が完了してからの相対時間経過後に使用可能になります。ctl矢印記号deq_timeは、キューの登録が完了した後、出されたリクエストが処理されるまでの遅延秒数を指定します。TPQTIME_ABSTPQTIME_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文字)。

TPQDELIVERYQOSTPQREPLYQOS

TPQDELIVERYQOSフラグが設定されていると、ctl->delivery_qosで指定されたフラグにより、メッセージの配信サービスの品質が制御されます。その場合、相互に排他的な3つのフラグTPQQOSDEFAULTPERSISTTPQQOSPERSISTENTTPQQOSNONPERSISTENTのいずれかをctl->delivery_qosに設定しなければなりません。TPQDELIVERYQOSフラグが設定されていない場合、ターゲットのキューのデフォルトの配信ポリシーがメッセージに対するサービスの配信品質を指定します。
TPQREPLYQOSフラグが設定されていると、ctl->reply_qosで指定されるフラグが、メッセージの応答に対するサービスの品質を制御します。その場合、相互に排他的な3つのフラグTPQQOSDEFAULTPERSISTTPQQOSPERSISTENTTPQQOSNONPERSISTENTのいずれかをctl->reply_qosに設定しなければなりません。TPQREPLYQOSフラグは、TMQFORWARDによって処理されるメッセージから応答が返されるときに使用されます。サービスを呼び出すときにTMQFORWARDを使用しないアプリケーションでは、自身の応答メカニズムのヒントとしてTPQREPLYQOSフラグを使用できます。 TPQREPLYQOSが設定されていない場合、ctl->replyqueueキューのデフォルトの配信ポリシーが応答に対するサービスの配信品質を指定します。デフォルトの配信ポリシーは、メッセージに対する応答がキューに登録されるときに決定される点に注意してください。つまり、元のメッセージがキューに登録されてからメッセージに対する応答が登録されるまでの間に、応答キューのデフォルトの配信ポリシーが変更された場合、応答が最後に登録される時点で有効なポリシーが使用されます。 次は、ctl->delivery_qosctl->reply_qosの有効なフラグです。

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_ABSTPQEXPTIME_REL、およびTPQEXPTIME_NONEは、相互に排他的なフラグです。この3つのどのフラグも設定されていない場合、ターゲットのキューに対応しているデフォルトの有効期限の時間がメッセージに適用されます。

TPQEXPTIME_REL

このフラグが設定されていると、メッセージに有効期限の相対時間が適用されます。これは、メッセージがキューに到達してから、キューから削除されるまでの秒数です。有効期限の時間は、ctl->exp_timeに格納された値で示されます。
有効期限の時間がメッセージの使用可能時間より前の場合、使用可能時間が有効期限の切れる時間より前になるようにいずれかの時間を変更しないかぎり、メッセージをキューから取り出すことはできません。また、これらのメッセージがキューからの取出しの対象になったことがなくても、有効期限が切れるとキューから削除されます。トランザクション中にメッセージの期限が切れても、トランザクションが異常終了することはありません。トランザクション内でキューへの登録、またはキューからの取出し中に有効期限が切れたメッセージは、トランザクションが終了した時点でキューから削除されます。メッセージの有効期限が切れたことの通知は行われません。 TPQEXPTIME_ABSTPQEXPTIME_REL、およびTPQEXPTIME_NONEは、相互に排他的なフラグです。この3つのどのフラグも設定されていない場合、ターゲットのキューに対応しているデフォルトの有効期限の時間がメッセージに適用されます。

TPQEXPTIME_NONE

このフラグが設定されると、メッセージの有効期限がないことを示します。このフラグは、ターゲットのキューに関連付けられているデフォルトの有効期限のポリシーをオーバーライドします。メッセージを削除する場合は、キューから取り出すか、管理インタフェースを介して削除します。
TPQEXPTIME_ABSTPQEXPTIME_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()の呼出しが失敗してtperrnoTPEDIAGNOSTICが設定された場合は、失敗の原因を示す値が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が発生します。その例外とは、ブロックされず、応答を期待せず、かつ呼出し側のトランザクションのかわりに送信されない(つまり、TPNOTRANTPNOBLOCKおよび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)

 


tpenvelope(3c)

名前

tpenvelope() - 型付きメッセージ・バッファに関連付けられているデジタル署名と暗号化情報へのアクセス

形式

#include <atmi.h> 
int tpenvelope(char *data, long len, int occurrence, TPKEY *outputkey, long *status, char *timestamp, long flags)

説明

tpenvelope()は、型付きメッセージ・バッファに関連付けられている以下のデジタル署名と暗号化情報へのアクセスを提供します。

署名および暗号化の情報は、送信プロセスと受信プロセスのどちらからも利用できます。送信プロセスでは、デジタル署名と暗号化の情報は普通は保留状態にあり、メッセージが送信されるまで待機しています。受信プロセスでは、デジタル署名が確認され、暗号化と復号化も既に行われています。復号化または署名の確認に失敗した場合、メッセージの配信が行われない可能性があります。この場合、受信プロセスはメッセージ・バッファを受け取ることができないため、メッセージ・バッファの情報が伝わりません。

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パラメータは、次のいずれかの値に設定できます。

戻り値

異常終了すると、この関数は-1を返し、tperrnoを設定してエラー条件を示します。

エラー

[TPEINVAL]

無効な引数が指定されました。たとえば、dataの値がNULLになっているか、またはflagsに割り当てられた値が認識されません。

[TPENOENT]

このoccurrenceは存在しません。

[TPESYSTEM]

エラーが発生しました。詳細は、システム・エラーのログ・ファイルを調べてください。

関連項目

tpkey_close(3c)tpkey_getinfo(3c)tpkey_open(3c)tpseal(3c)tpsign(3c)

 


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は将来の使用を考慮して予約されているため、ゼロを指定してください。

マルチスレッドのアプリケーション中のスレッドは、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呼出しから返され、tperrnoTPESYSTEMに設定されます。中間のATMI呼出しを省略して引き続きtperrordetail()を呼び出すと、TPED_INVALIDCONTEXTが返されます。

TPED_INVALID_XA_TRANSACTION

トランザクションの開始が試行されましたが、このドメインでNO_XAフラグが設定されました。

TPED_NOCLIENT

クライアントが存在しません。tpnotify()呼出しにTPACKフラグが指定されているのに、tpnotify()のターゲットがありません。tpnotify()が異常終了すると、tperrnoTPENOENTに設定されます。中間のATMI呼出しを省略して引き続きtperrordetail()呼び出すと、TPED_NOCLIENTが返されます。

TPED_NOUNSOLHANDLER

クライアントに非請求ハンドラ・セットがありません。tpnotify()呼出しにTPACKフラグが指定され、tpnotify()のターゲットがOracle Tuxedo ATMIセッション内にあるのに、ターゲットに非請求の通知ハンドラが設定されていません。tpnotify()が異常終了すると、tperrnoTPENOENTに設定されます。中間のATMI呼出しを省略して引き続きtperrordetail()を呼び出すと、TPED_NOUNSOLHANDLERが返されます。

TPED_RDMA_MSGQDAEMON

RDMA Msgq_daemonのエラー。RDMAが有効な場合、RDMAデーモン・プロセス(Msgq_daemon)で深刻な問題が検出されると、RDMAを介して送信されたリクエストが異常終了します。tperrnoではTPEOS/TPETIMEが返されます。中間ATMI呼出しを省略して引き続きtperrordetail()を呼び出すとTPED_RDMA_MSGQDAEMONが返されます。
リクエストの異常終了は次の呼出しによって検出されます。

TPED_RDMA_INVALIDQUEUE

無効な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_SVCTIMEOUTTM_MIB (5)に記載されています。このエラーよって呼出しが異常終了したときは、中間のATMI呼出しを省略して引き続きtperrordetail()を呼び出すと、TPED_SVCTIMEOUTが返されます。

TPED_TERM

ワークステーション・クライアントが、アプリケーションに接続していません。このエラーによって呼出しが異常終了したときは、中間のATMI呼出しを省略して引き続きtperrordetail()を呼び出すと、TPED_TERMが返されます。

エラー

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

TPEINVAL

flagsはゼロに設定されていません。

関連項目

「C言語アプリケーション・トランザクション・モニター・インタフェースの紹介」tpstrerrordetail(3c)tperrno(5)

 


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は、(1)以前tpalloc()を呼び出すプロセスによって割り当てられたメッセージ・バッファ、または(2)システムによって受信プロセスに渡されたメッセージ・バッファのうち、いずれかの有効な型付きメッセージ・バッファを指している必要があります。ilenは、エクスポートするibufの容量を指定します。ただし、ibufが長さの指定を必要としないタイプのバッファを指す場合(たとえば、FMLフィールド化バッファ)、ilenは無視されます(0を指定できます)。

ostrは、バッファの内容と関連プロパティの外部化された表現を保持する出力領域を指します。flagsTPEX_STRINGが設定されている場合、外部化の形式は文字列型になります。それ以外の場合、出力する長さは*olenによって指定され、NULLバイトを埋め込むことができます。

入力時には、*olenostrで使用できる最大記憶サイズを指定します。出力時には、*olenostrに書き込まれる実際のバイト数に設定されます。flagsTPEX_STRINGが設定されている場合は、終端のNULL文字を含みます。

出力バッファに文字列形式(base 64エンコード)が要求される場合、flags引数はTPEX_STRINGに設定します。それ以外の場合、出力はバイナリになります。

戻り値

異常終了すると、この関数は -1を返し、tperrnoを設定してエラー条件を示します。

エラー

[TPEINVAL]

無効な引数が指定されました。たとえば、ibufの値がNULL、またはflagsの値が正しく設定されていません。

[TPEPERM]

パーミッション異常終了。暗号サービスのプロバイダが、デジタル署名の生成に必要な秘密鍵にアクセスできませんでした。

[TPESYSTEM]

エラーが発生しました。詳細は、システム・エラーのログ・ファイルを調べてください。

[TPELIMIT]

十分な出力記憶域がありませんでした。*olenを必要な容量に設定します。

関連項目

tpimport(3c)

 


tpfml32toxml(3c)

名前

tpfml32toxml() - FML32バッファをXMLデータに変換

形式

#include <fml32.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)tpxmltofml(3c)tpfmltoxml(3c)

 


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]

fml32bufpまたはxmlbufpのどちらかが有効な型付きバッファではありません。

[TPESYSTEM]

Tuxedoシステムのエラーが発生しました。このエラーの正確な性質はuserlog(3)に書き込まれます。これは、XMLへの変換を実行できなかった時期も示します。そのインスタンスでは、エラーの詳細な情報がuserlogに追加されます。

[TPEOS]

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

関連項目

tpxmltofml32(3c)tpfml32toxml(3c)tpxmltofml(3c)

 


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を呼び出すサービス・セッション・ロールを構成する場合は、表11を参照してください。

表11 tpforwardのセッション・ロール
セッション・ロール
転送元サービス
転送先サービス
BEGIN
LIBTUX_CAT:6835: ERROR'がULOGに出力されます。セッションは開始しません。
アフィニティ・サーバーとアフィニティ・スコープは転送先サービスによって決定されます。アフィニティ・クライアントは、転送元サービスを呼び出すクライアントです。
END
LIBTUX_CAT:6836: ERROR'がULOGに出力されます。アフィニティ・クライアントとサーバー間のセッションは終了しません。
転送元サービスがセッションに関与していないかぎり、セッションは終了します。
なし
セッションが伝播されます。
セッションが伝播されます。

詳細は、 「Oracle Tuxedo ATMIのアーキテクチャ」の「クライアント/サーバー・アフィニティとは」を参照してください。

関連項目

tpalloc(3c)tpconnect(3c)tpreturn(3c)tpservice(3c)tpstrerrordetail(3c)

 


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)

 


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_NEXTTPBLK_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, or 0)が指定されました。

表12 SCANUNITとtpsblktimeのフラグの関係
UBBCONFIGのSCANUNIT
tpsblktimeのフラグ
結果
秒単位
TPBLK_SECOND
秒単位
TPBLK_MILLISECOND
ミリ秒単位
TPBLK_SECOND
不可
ミリ秒単位
TPBLK_MILLISECOND

[TPESYSTEM]

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

関連項目

tpcall(3c)tpcommit(3c)tprecv(3c)tpsblktime(3c)UBBCONFIG(5)

 


tpgetadmkey(3c)

名前

tpgetadmkey() - 管理用認証キーを取得するルーチン

形式

#include <atmi.h>  
long tpgetadmkey(TPINIT *tpinfo)

説明

tpgetadmkey()は、アプリケーションに特定の認証サーバーによって利用されます。このルーチンは、管理認証の目的のために指定ユーザーにふさわしいアプリケーション・セキュリティ・キーを返します。このルーチンは、tpsysadm()あるいはtpsysop()のクライアント名(つまりtpinfo矢印記号cltname)を指定して呼び出す必要があります。そうでなければ、有効な管理キーは返されません。

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

戻り値

tpgetadmkey()は、正常終了時には最上位ビットが設定(0x80000000)された0以外の値を戻し、異常終了時には0を戻します。tpinfoがNULLで、tpinfo矢印記号cltnametpsysadm()またはtpsysop()でないか、あるいはユーザーIDが構成されたアプリケーション管理者でない場合は、0が戻されます。

エラー

0が返されることで、有効な管理キーが割り当てられなかったことが分かります。

移植性

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

関連項目

tpaddusr(1)tpusradd(1)tpinit(3c)AUTHSVR(5)

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

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

 


tpgetcallinfo(3c)

名前

tpgetcallinfo()—コール・パス・メッセージ・モニタリング属性を受信するルーチン。

形式

int tpgetcallinfo(const char *msg, FBFR32 **obuf, long flags)

説明

tpgetcallinfo()は、呼出しパス・モニタリングにのみ使用されます。次のパラメータをサポートしています。

msg

測定に使用される型付きバッファ。

obuf

フィールドを使うために使用されるFML32バッファ。

flags

将来使用するために予約されたフィールド。

tpgetcallinfo()では、呼出しパス・モニタリングを有効にした場合、メッセージ・モニタリング属性が取得されます。

tpgetcallinfo()は、幅広い機能を実行するために様々なシナリオで使用できます。一般的な使用目的は、以下のとおりです。

アプリケーション・サーバーは、要求されたメッセージのモニタリング属性を確認するためにtpgetcallinfo()を呼び出します。これにより、次の情報を提供できます。

注: tpgetcallinfo()は、応答の受信後、いつでもコールして応答バッファを得ることができます。これは、tpacall/tpgetrplyの場合に特に有用です。

表13は、FMLモニター・メトリックス・フィールド名のリストです。

表13 モニター・イニシエータ・フィールド名
フィールド名
説明
サービス
モニタリング
イニシエータ
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

表14は、FMLカスタムHTTPヘッダー名のリストです。

表14 モニター・イニシエータ・フィールド名
フィールド名
説明
TA_HTTP_HEADER_NAME
string
HTTPヘッダー名部分
TA_HTTP_HEADER_VALUE
string
HTTPヘッダー値部分

戻り値

モニタリング属性を含む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 */
       ......
}

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)

 


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に設定されます。

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

エラー

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

[TPEINVAL]

無効な引数が指定されました。たとえば、contextの値がNULLか、またはflagsの値が0以外です。

[TPESYSTEM]

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

[TPEOS]

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

関連項目

「C言語アプリケーション・トランザクション・モニター・インタフェースの紹介」tpsetctxt(3c)tpterm(3c)

 


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)

 


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)

 


tpgetrepos(3c)

名前

tpgetrepos() - Tuxedoサービス・メタデータ・リポジトリ・ファイルからのサービス・パラメータ情報の取得

#include <atmi.h>

形式

int tpgetrepos(char *reposfile, FBFR32* idata, FBFR32** odata)

説明

tpgetrepos()は、TMMETADATA(5)によって提供される.TMMETAREPOSサービスに、代替リポジトリ・アクセス・インタフェースを提供します。これは、Tuxedoサービス・メタデータ・リポジトリ・ファイルからサービス・パラメータを取得します。tpgetrepos()を使用するには、メタデータ・リポジトリ・ファイルが、リクエスト元のネイティブ・クライアントまたはサーバーに存在している必要があります。このファイルにより、TMMETADATA(5)を開始していない場合でも、リポジトリ情報へのアクセスが可能になります。

注: tpgetrepos()は、Joltリポジトリ・ファイルの表示にも使用できます。既存のJoltリポジトリ・ファイルを変更したり、新しいJoltリポジトリ・ファイルを作成したりすることはできません。

tpgetrepos()では、以下のパラメータを使用できます。

reposfile

Tuxedoメタデータ・リポジトリがある現在のマシンでアクセス可能なファイルのパス名を指定します。呼出し側は、このファイルの読取りパーミッションを持っている必要があります。

idata

取得するサービス・パラメータ情報の種類を指定し、FML32バッファを指します。

*odata

出力に対して、取得するサービス・パラメータ情報とオペレーションのステータスを格納したFML32バッファを指します。

「METAREPOS(5)」では、tpgetrepos()が使用するFML32バッファ形式について説明します。これは、Tuxedo MIBで使用する形式と同じです。

戻り値

tpgetrepos()は、成功した場合に0を返します。異常終了した場合は、tperrnoを設定し、-1を返します。ほとんどの異常終了では、Tuxedo MIBの場合と同様に、*odataのTA_ERRORフィールドに特定のエラーに関する情報が格納されています。

エラー

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

注: TPEINVALの場合を除き、odataは、エラー条件についてさらに詳しい情報が得られるように、サービス・エントリごとにTA_ERRORTA_STATUSを含める形で変更されます。

[TPEINVAL]

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

[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サービス・メタデータ・リポジトリの管理」

 


tpgetrply(3c)

名前

tpgetrply() - 以前のリクエストに対する応答を受信するためのルーチン

形式

#include <atmi.h>
int tpgetrply(int *
cd, char **data, long *len, long flags)

説明

tpgetrply()は、以前に送信されたリクエストに対する応答を戻します。この関数の最初の引数cdは、tpacall()が戻す呼出し記述子を指します。デフォルトでは、この関数は、*cdと一致する応答が届くか、タイムアウトが発生するまで待機します。

dataは、以前にtpalloc()で割り当てたバッファを指すポインタのアドレスでなければならず、lentpgetrply()が正常に受信したデータ量を設定するlong型の値を指すようにしてください。正常終了時には、*dataは、その応答を収めたバッファを指し、*lenには、そのデータのサイズが入ります。FMLとFML32バッファは、通常最小サイズ4096バイトを確保します。応答が4096バイトより大きい場合には、バッファ・サイズは返されるデータを入れるのに十分な大きさに拡大します。リリース6.4では、バッファに対するデフォルトの割当ては1024バイトです。また、最近使用したバッファの履歴情報が保持され、最適サイズのバッファをリターン・バッファとして再利用できます。

容量まで満たされていないかもしれない送信者側のバッファ(たとえば、FMLまたはFML32バッファ)は、送信に使用されたサイズになります。システムは、受信データのサイズを任意の量で拡大します。これは、受信者が送信者の割り当てたバッファ・サイズより小さく、送信されたデータのサイズより大きいバッファを受け取ることを意味します。

受信バッファのサイズは、増加することも減少することもあります。また、アドレスもシステムがバッファを内部で交換するごとに常に変更されます。応答バッファのサイズが変わったどうか(また変わったとしたらどれくらい変わったのか)を決定するには、tpgetrply()が*lenとともに発行される前に、合計サイズを比べてください。バッファ管理の詳細については、「C言語アプリケーション・トランザクション・モニター・インタフェースの紹介」を参照してください。

返されたときに*lenが0の場合は、応答にはデータ部分がなく、*dataやそれが指示するバッファは変更されていません。

*dataまたはlenがNULLであるとエラーになります。

マルチスレッド・プログラムの各コンテキストでは、次のことが当てはまります。

これらの制限のどちらかに違反するtpgetrply()呼出しを発行した場合は、-1が返され、tperrnoTPEPROTOに設定されます。

次のような呼出しの発行は受け付けられます。

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

TPGETANY

このフラグは、tpgetrply()が、cdによって示される記述子を無視し、存在する応答があればそれらを返し、返された応答の呼出し記述子を指すようcdを設定します。応答が存在しなければ、tpgetrply()は1つの応答が届くまで待機します(デフォルトの設定の場合)。

TPNOCHANGE

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

TPNOBLOCK

tpgetrply()は、応答が送られてくるまで待機しません。応答がキューから取り出せる状態であれば、tpgetrply()はその応答を取り込み、終了します。このフラグの指定がなく、応答もキューから取り出せる状態にない場合、呼出し側は、応答が到着するまであるいはタイムアウト(トランザクション・タイムアウトまたはブロッキング・タイムアウト)が発生するまでブロックされます。

TPNOTIME

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

TPSIGRSTRT

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

後に示す場合以外は、*cdはその応答を受信した後は有効でなくなります。

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

戻り値

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

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

エラー

異常終了時には、tpgetrply()tperrnoに対して行う設定は、次のようになります。TPGETANYが設定されていない場合は、特に明記されていないかぎり、*cdは無効になります。TPGETANYが設定されている場合は、cdは異常が発生した応答の記述子を指します。応答が取り出せるようになる前にエラーが発生した場合には、cdは0を指します。また、特に明記しないかぎり、異常終了は呼出し側のトランザクションが存在していても、それには影響しません。呼出しが異常終了してtperrnoに特定の値が設定されたときは、中間のATMI呼出しを省略して引き続きtperrordetail()を呼び出すと、エラーに関する詳細な情報が提供されます。詳細は、「tperrordetail(3c)」リファレンス・ページを参照してください。

[TPEINVAL]

無効な引数が与えられました(たとえば、cddata、*dataまたはlenがNULL、あるいはflagsが無効など)。cdがNULLでない場合、エラーが発生した後もこの値は有効で、応答は未終了のまま残されます。

[TPEOTYPE]

応答のタイプとサブタイプが呼出し側が認識しているものでありません。あるいは、TPNOCHANGEflagsに設定されていて、*dataのタイプとサブタイプがそのサービスから送られた応答のタイプおよびサブタイプと一致しません。*dataの内容も*lenも変更されていません。呼出し側の現在のトランザクションのために応答が受信された場合は、応答が破棄されるので、そのトランザクションは中断のみとしてマークされます。

[TPEBADDESC]

cdが無効な記述子を指しています。

[TPETIME]

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

[TPESVCFAIL]

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

[TPESVCERR]

サービス・ルーチンが、tpreturn()またはtpforward()でエラーを検出しました(たとえば、誤った引数が渡された場合など)。このエラーが発生すると、応答データは戻されません(つまり、data、その内容、および*lenはいずれも変更されません)。呼出し側のトランザクションのかわりにサービス・リクエストが発行された場合、トランザクションは中断のみとしてマークされます。トランザクションがタイムアウトしたかどうかに関わりなく、トランザクションが中断される前の通信で有効であるのは、TPNOREPLYTPNOTRANおよび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)

 


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)

 


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バッファ表現が暗号化されている場合、インポート・プロセスは復号化に有効な秘密鍵にアクセスできる必要があります。復号化はインポート・プロセス中に自動的に実行されます。

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

 


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に設定しても、tpinitTPMULTICONTEXTSモードは正しく機能します。この環境変数を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;

usrnamecltnamegrpnameおよびpasswdの値はすべてNULL終了文字列です。usrnameは呼出し側を表す名前です。cltnameは、セマンティクスがアプリケーションで定義されたクライアント名です。値sysclientは、cltnameフィールド用にシステムによって予約されています。usrnamecltnameフィールドは、tpinit()実行時にクライアントと関連付けられ、ブロードキャスト通知と管理統計情報の検索に使用されます。これらの名前は、MAXTIDENTの文字数を超えてはなりません。passwdは、アプリケーション・パスワードとの認証に使用される非暗号化形式のアプリケーション・パスワードです。passwdは30文字に制限されます。grpnameは、クライアントをリソース・マネージャ・グループ名と関連付けるときに使用します。grpnameが長さ0の文字列として設定されている場合、クライアントはリソース・マネージャに関連付けられず、デフォルトのクライアント・グループに属します。ワークステーション・クライアントの場合、grpnameの値にはNULL文字列(長さが0の文字列)を指定します。grpnameはACL GROUPSには関連しないことに注意してください。

シングル・コンテキスト・モードとマルチコンテキスト・モード

tpinit()には、シングル・コンテキスト・モードとマルチコンテキスト・モードの2つの動作モードがあります。シングル・コンテキスト・モードでは、プロセスは一度に1つのアプリケーションに参加できます。このアプリケーションには、複数のアプリケーション・スレッドがアクセスできます。シングル・コンテキスト・モードを指定するには、NULLのパラメータを指定したtpinit()を呼び出すか、TPINIT構造体のflagsフィールドにTPMULTICONTEXTSフラグを指定せずにtpinit()を呼び出します。また、tpinit()が別のATMI関数によって暗黙的に呼び出されたときも、シングル・コンテキスト・モードが指定されます。シングル・コンテキスト・モードで動作するプロセスのコンテキスト状態は、TPSINGLECONTEXTです。

注: TMNOTHREADS環境変数を"yes"に設定しても、tpinitTPMULTICONTEXTSモードは正しく機能します。

シングル・コンテキスト・モードでは、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が指定されると、無効な引数とみなされ、エラーが返されてtperrnoTPEINVALに設定されます。

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引数を使用するクライアント・プロセスは、usrnamecltname、および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の形式で指定できます。1つ目の形式では、ドメインがローカル名を解決する手法(通常はDNS)を使用してhostnameのアドレスを検索します。hostnameにはローカル・マシン名を指定し、ローカル名解決の機能でhostnameをローカル・マシンのアドレスに明確に解決する必要があります。 2つ目の形式の#.#.#.# は、ドットで区切られた10進数です。ドットで区切った10進数の形式では、各#は0から255までの数でなければなりません。このドットで区切った10進数は、ローカル・マシンのIPアドレスを表現します。 上記のどちらの形式でも、port_numberはドメイン・プロセスがリクエストの受信をリスニングするTCPポート番号です。port_numberには、0から65535までの数字または名前を指定できます。port_numberが名前の場合は、ローカル・マシンのネットワーク・サービス・データベースになければなりません。 アドレスは、文字0xを先頭に付けて16進数形式でも指定できます。先頭の0xに続く文字として、0 - 9までの数字か、またはAからFまでの文字(大文字と小文字は区別しない)を指定できます。16進数の形式は、IPX/SPXやTCP/IPのような任意のバイナリ・ネットワーク・アドレスに使うことができます。 アドレスはまた、任意の文字列として指定することもできます。値は、構成ファイル内のNETWORKセクションのNLSADDRパラメータに指定された値と同じでなければなりません。 必要に応じて複数のアドレスを指定できます。その場合は、WSNADDRのパス名のリストをカンマ区切りで指定します。接続が確立するまで順番にアドレス指定が試みられます。アドレス・リストのメンバーは、どれでもパイプで区切られたネットワーク・アドレスのかっこ付きのグループとして指定することができます。たとえば、WSNADDR=(//m1.acme.com:3050|//m2.acme.com:3050),//m3.acme.com:3050です。Windowsで実行しているユーザーの場合、アドレス文字列はset WSNADDR=(//m1.acme.com:3050^|//m2.acme.com:3050),//m3.acme.com:3050のようになります。パイプ記号(|)はWindowsでは特殊文字とみなされるため、コマンド行に指定する場合はWindows環境のエスケープ文字であるカレット(^)を前に付ける必要があります。ただし、envfileでWSNADDRが定義されている場合、Oracle Tuxedo ATMIシステムは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:30000WSFRANGEが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)tpsetctxt(3c)tpterm(3c)

 


tpkey_close(3c)

名前

tpkey_close() - 以前にオープンしたキー・ハンドルのクローズ

形式

#include <atmi.h>
int tpkey_close(TPKEY hKey, long flags)

説明

tpkey_close()は、以前にオープンしたキー・ハンドルと、それに関連付けられているすべてのリソースを解放します。プリンシパルの秘密鍵などの機密情報はすべて、メモリーから消去されます。

キー・ハンドルは、次のいずれかの方法でオープンできます。

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)

 


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によって示されるメモリー位置に格納されます。この位置に格納できる最大データ量は、呼出し側によって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)

 


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

 


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)

 


tpnotify(3c)

名前

tpnotify() - クライアント識別子によって通知を送信するルーチン

形式

#include <atmi.h> 
int tpnotify(CLIENTID *clientid, char *data, long len, long flags)

説明

tpnotify()は、各クライアントに非請求メッセージを送信できるようにします。

clientidは、以前のあるいは現在のサービス呼出しのTPSVCINFO構造体から保存された、または、他の何らかの通信機構によってクライアントに渡された(たとえば、管理インタフェースを使って検索された)クライアント識別子を指すポインタです。

このリクエストのデータ部はdataによって示され、以前にtpalloc()によって割り当てられたバッファです。lenに送信するデータの大きさを指定します。ただし、dataが長さの指定を必要としないタイプのバッファを指す場合(たとえば、FMLフィールド化バッファ)、lenは0でかまいません。また、dataはNULLであってもかまいません。この場合、lenは無視されます。

tpnotify()が正常終了した場合、メッセージはシステムに渡され、指定されたクライアントに送信されます。TPACKフラグが設定されている場合は、正常終了は、クライアントがメッセージを受信したことを意味します。さらに、クライアントが任意通知型メッセージ・ハンドラに登録している場合は、ハンドラが呼び出されます。

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

TPACK

リクエストは送信され、呼出し側は承認メッセージがターゲットのクライアントから受信されるまでブロックします。

TPNOBLOCK

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

TPNOTIME

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

TPSIGRSTRT

ルーチン内部のシステム・コールがシグナルによって中断された場合、中断されたシステム・コールは再発行されます。
TPACKフラグを設定しないかぎり、tpnotify()は、メッセージがクライアントに送られるまで待機していません。

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

戻り値

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

エラー

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

[TPEINVAL]

無効な引数が指定されました(たとえば、無効なフラグなど)。

[TPENOENT]

ターゲットのクライアントが存在せず、TPACKフラグが設定されました。

[TPETIME]

ブロッキング・タイムアウトが発生し、TPNOBLOCKTPNOTIMEのいずれも指定されなかったか、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)tpstrerrordetail(3c)tpterm(3c)

 


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のオープンが失敗すると、tpopenTPERMERRを戻します。

戻り値

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

エラー

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

[TPERMERR]

リソース・マネージャを正しくオープンできませんでした。より詳しい理由は、そのリソース・マネージャを独自の方法で調査することで得られます。エラーの正確な性質を判別するための呼出しを使用すると、移植性が損なわれることに注意してください。

[TPEPROTO]

tpopen()が不正なコンテキストで呼び出されました(たとえば、Oracle Tuxedoシステム・サーバー・グループに結合していないクライアントにより)。

[TPESYSTEM]

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

[TPEOS]

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

関連項目

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

 


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にはバッファ内のイベントと共にポストするバッファに入っているデータの長さを指定しなければなりません。長さを指定する必要のないタイプのバッファ(FMLフィールド化バッファなど)をdataが指す場合、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に対するすべてのサブスクリプションを処理するのを待たないように、tppostに通知します。TPNOREPLYがセットされると、tppost()が成功して戻ったかどうかにかかわらず、tpurcode()はゼロに設定されます。呼出しプロセスがトランザクション・モードにあるとき、TPNOTRANが設定されないかぎりこの設定は使用できません。

TPNOBLOCK

ブロッキング条件が存在する場合は、イベントはポストされません。このような条件が発生すると、呼出しは異常終了し、tperrnoにはTPEBLOCKが設定されます。TPNOBLOCKが指定されていないときにブロッキング条件が存在すると、呼出し側は、その条件が解消されるか、またはタイムアウト(トランザクションまたはブロッキング)が発生するまではブロックされます。

TPNOTIME

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

TPSIGRSTRT

ルーチン内部のシステム・コールがシグナルによって中断された場合、中断されたシステム・コールは再発行されます。TPSIGRSTRTが指定されていない場合にシグナルがシステム・コールを中断させると、tppost()は失敗し、tperrnoにはTPGOTSIGが設定されます。

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

戻り値

tppost()から成功して戻ると、tpurcode()にはeventnameのかわりにイベント・ブローカによってディスパッチされるイベント通知の数が設定されています(つまり、eventnameに対するイベント表現の評価が成功し、dataに対するフィルタ・ルールの評価が成功したサブスクリプションへのポストです)。tperrnoTPESVCFAILに設定されて戻った場合は、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が発生します。その例外とは、ブロックされず、応答を期待せず、かつ呼出し側のトランザクションのかわりに送信されない(つまり、TPNOTRANTPNOBLOCKおよび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)

 


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)

 


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はlong型(tprecv()が受信したデータのサイズに設定した)を指さなければなりません。*dataは応答を含んでいるバッファを指し、*len は、バッファのサイズを含みます。FMLFML32バッファは、通常最小サイズ4096バイトを確保します。したがって、応答が4096バイトより大きい場合は、バッファ・サイズは返されるデータを入れるのに十分な大きさに拡大します。

容量まで満たされていない送信側のバッファ(たとえば、FMLおよびSTRINGバッファ)は、送信に使用された大きさになります。システムは、受信データのサイズを任意の量で拡大します。これは、受信者が送信者の割り当てたバッファ・サイズより小さく、送信されたデータのサイズより大きいバッファを受け取ることを意味します。

受信バッファのサイズは、増加することも減少することもあります。また、アドレスもシステムがバッファを内部で交換するごとに常に変更されます。応答バッファのサイズが変わったどうか(また変わったとしたらどれくらい変わったのか)を決定するには、tprecv()*lenとともに発行される前に、合計サイズを比べてください。バッファ管理の詳細については、「C言語アプリケーション・トランザクション・モニター・インタフェースの紹介」を参照してください。

*lenが0の場合、データは受け取られず、*dataも、それが指すバッファも、変更されていません。data*dataまたはlenがNULLであると、エラーになります。

tprecv()は、接続の制御をもたないプログラムしか出せません。

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

TPNOCHANGE

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

TPNOBLOCK

tprecv()はデータが到着するまで待機しません。すでにデータが受信できる状態であると、tprecv()はデータを取り込んで終了します。このフラグが設定されておらず、かつ受信できるデータがない場合、呼出し側はデータが到着するまでブロックされます。

TPNOTIME

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

TPSIGRSTRT

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

記述子cdに対してイベントが存在すると、tprecv()は終了し、tperrnoTPEEVENTに設定します。イベントのタイプがreventで返されます。TPEV_SVCSUCCTPEV_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()の呼出しを発行できません。

戻り値

reventTPEV_SVCSUCCまたはTPEV_SVCFAILのどちらかに設定されている場合に、tprecv()が終了した場合は、グローバル変数tpurcodeには、tpreturn()の一部として送信されるアプリケーション定義の値が含まれます。

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

エラー

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

[TPEINVAL]

無効な引数が与えられました(たとえば、dataがtpalloc()によって割り当てられたバッファを指すポインタのアドレスでない、あるいはflagsが無効である場合など)。

[TPEOTYPE]

受け取るバッファのタイプおよびサブタイプのどちらも呼出し側に通知されていません。またはTPNOCHANGEflagsに設定されていて、*dataのタイプおよびサブタイプが受け取るバッファのタイプおよびサブタイプと合っていません。*dataの内容も*lenも変更されていません。会話が呼出し側の現在のトランザクションの一部になっている場合は、受け取るバッファが放棄されるため、トランザクションは中断のみとしてマークされます。

[TPEBADDESC]

cdが無効です。

[TPETIME]

このエラー・コードは、タイムアウトが発生したか、または現在のトランザクションがすでに「ロールバックのみ」とマークされているにもかかわらずtprecv()が試行されたことを示します。
呼出し側がトランザクション・モードの場合、トランザクションはすでにロールバックのみであるか、またはトランザクション・タイムアウトが発生しました。このトランザクションは、中断のみとしてマークされます。呼出し側がトランザクション・モードでない場合、ブロッキング・タイムアウトが発生しています。(ブロッキング・タイムアウトは、TPNOBLOCKまたはTPNOTIMEが指定されている場合は発生しません。)いずれの場合でも、*dataもその内容も変更されません。 トランザクション・タイムアウトが発生した場合、トランザクションが中断されない限り、新しいリクエストの送信や未処理の応答の受信はできず、TPETIMEが発生します。その例外とは、ブロックされず、応答を期待せず、かつ呼出し側のトランザクションのかわりに送信されない(つまり、TPNOTRANTPNOBLOCKおよび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)

 


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)

 


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イベントを受け取ります)。サービス・ルーチンの処理中になんらかの理由でトランザクションがロールバックのみとしてマークされると、rvalTPFAILに設定されます。TPSUCCESSが会話型サービスに対して指定されると、TPEV_SVCSUCCイベントが生成されます。

TPFAIL

アプリケーション上の問題でサービスが異常終了しました。応答を受け取ったプログラムにエラーが報告されます。つまり、応答を受け取る呼出しは失敗し、受信側はTPSVCFAIL指示あるいはTPEV_SVCFAILイベントを受け取ります。呼出し側がトランザクション・モードであると、tpreturn()はそのトランザクションをロールバックのみとしてマークします(ただし、そのトランザクションは、すでにロールバックのみとしてマークされている場合もあります)。戻り処理が失敗した場合を除き、呼出し側のデータが(存在する場合)送信されます。トランザクション・タイムアウトになって、呼出し側のデータが送信されない場合もあります。この場合、応答を待つプログラムはTPETIMEエラーを受け取ることになります。会話型サービスにTPFAILが指定された場合には、TPEV_SVCFAILイベントが生成されます。

TPEXIT

この値は、サービスの完了という点ではTPFAILと同じように動作しますが、TPEXITが戻されると、サーバーは、トランザクションがロールバックされて応答がリクエスタに戻された後に終了します。 マルチスレッド・プロセスにこの値が指定された場合、TPEXITは(そのプロセス内の単一のスレッドではなく)プロセス全体が強制終了されることを示します。 サーバーが再開可能な場合、サーバーは自動的に再開します。

rvalがこれら3つの値のいずれかに設定されていない場合、デフォルトの値としてTPFAILが使用されます。

アプリケーションが定義した戻りコードrcodeをサービスの応答を受け取るプログラムに送ることもできます。このコードは、応答を正常に送ることができさえすれば(つまり、受信呼出しが正常に行われる、あるいはTPESVCFAILが返されれば)、rvalの設定には関係なく送ることができます。さらに、会話型サービスでは、このコードは、サービス・ルーチンがtpreturn()を発行したときに接続の制御権を持っている場合のみ送信されます。rcodeの値は、受信側の変数tpurcode()に入ります。

dataは送信される応答のデータ部を指すポインタです。dataがNULLでなければ、以前にtpalloc()の呼出しによって得られたバッファを指していなければなりません。このバッファが、サービス・ルーチン起動時にサービス・ルーチンに渡されたバッファと同じバッファである場合、そのバッファの配置は、Oracle Tuxedo ATMIシステムのディスパッチャに一任されます。したがって、サービス・ルーチンをコーディングする人は、バッファが解放されているかどうかを気にする必要はありません。実際、ユーザーがこのバッファを解放しようとしてもできません。ただし、tpreturn()に渡されたバッファが、そのサービスが呼び出されたときのものと異なる場合には、tpreturn()でそのバッファを解放することができます。メイン・バッファが解放されても、そのバッファ内に埋め込まれたフィールドが参照するバッファは解放されません。lenは送信するデータ・バッファの大きさを指定します。dataが長さの指定を必要としないバッファを指すポインタである場合(FMLフィールド化バッファなど)、lenは0でもかまいません。

dataがNULLの場合、lenは無視されます。この場合、サービスを起動したプログラムが応答を待っている状態にあると、データなしの応答が返されます。応答を待たない状態にあると、tpreturn()は、必要に応じてdataを解放し、応答を送信しないで復帰します。

現在、flagsは将来の使用のために予約されており、0に設定する必要があります(0以外の値に設定すると、応答の受信者はTPESVCERR指示またはTPEV_SVCERRイベントを受信します)。

会話型サービスの場合、呼出し側の戻りコードとデータ部が転送されない場合が2つあります。

戻り値

サービス・ルーチンは呼出し側であるOracle Tuxedo ATMIシステムのディスパッチャに値を返しません。このため、このルーチンはvoidとして宣言されます。しかし、サービス・ルーチンはtpreturn()またはtpforward()を使用して終了させるようになっています。会話型サービス・ルーチンの場合、tpreturn()を使用しなければならず、tpforward()を使用することはできません。サービス・ルーチンをtpreturn()またはtpforward()のいずれも使用せずに終了させる場合(すなわち、このルーチンがC言語のreturn文を使用するか、ごく単純に関数の実行に失敗した場合)、あるいはtpforward()が会話型サーバーから呼び出された場合、そのサーバーはログに警告メッセージを出し、サービス・エラーをサービスのリクエスタに返します。従属側へのオープン接続はすべてただちに切断され、未終了の非同期応答は取り除かれます。障害時にサーバーがトランザクション・モードであった場合、このトランザクションには「ロールバックのみ」のマークが付けられます。tpreturn()tpforward()がサービス・ルーチンの外部から使用される場合(たとえば、クライアントやtpsvrinit()あるいはtpsvrdone()で)、これらのルーチンは単に終了するだけです。

エラー

tpreturn()はサービス・ルーチンを終了させるので、引数処理またはサービス処理の間に発生したエラーについて、関数の呼出し側に示すことはできません。このようなエラーが起こると、tpcall()またはtpgetrply()を使用してサービスの結果を受信するプログラムのためにtperrnoTPESVCERRに設定されます。またイベント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)

 


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)

 


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)

 


tprmopen(3c)

名前

tprmopen() - 複数のRMサーバー・グループに関連付けられているUBBCONFIGの*RMSセクションで構成された特定のRMをオープンするルーチン

形式

#include <atmi.h>
int tprmopen(char *rmname, long flags)

説明

tprmopen()は、UBBCONFIGの*RMSセクションに構成され、複数のリソース・マネージャのサーバー・グループに関連付けられている名前を使用して、特定のリソース・マネージャをオープンします。rmnameによって指定されたリソース・マネージャがすでにオープンしている場合(つまり、この rmname tprmopen()が複数回呼び出された場合、またはrmnametpopen()によってオープンされた場合)、何も実行されず、正常終了が戻されます。

現在の最初のパラメータ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)

 


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)

 


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)が指定されました。

表15 SCANUNITとtpsblktimeのフラグの関係
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)

 


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)

 


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)

 


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()の呼出しを発行できません。

戻り値

TPEV_SVCSUCCまたはTPEV_SVCFAILのどららかがreventに設定されてtpsend()が戻った場合、tpurcode()によってポイントされているグローバル変数には、tpreturn()の一部として送信された、アプリケーションで定義した値が入っています。関数tpsend()はエラー時には -1を返し、tperrnoを設定してエラーの条件を示します。またイベントが存在し、かつエラーが発生しない場合、tpsend()は -1を返し、tperrno[TPEEVENT]を設定します。

エラー

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

[TPEINVAL]

無効な引数が与えられました(たとえば、datatpalloc()によって割り当てられたバッファを指していないか、flagsが無効)。

[TPEBADDESC]

cdが無効です。

[TPETIME]

このエラー・コードは、タイムアウトが発生したか、または現在のトランザクションがすでに「ロールバックのみ」とマークされているにもかかわらずtpsend()が試行されたことを示します。
呼出し側がトランザクション・モードの場合、トランザクションはすでにロールバックのみであるか、またはトランザクション・タイムアウトが発生しました。このトランザクションは、中断のみとしてマークされます。呼出し側がトランザクション・モードでない場合、ブロッキング・タイムアウトが発生しています。(ブロッキング・タイムアウトは、TPNOBLOCKまたはTPNOTIMEが指定されている場合は発生しません。) トランザクション・タイムアウトが発生した場合、トランザクションが中断されない限り、新しいリクエストの送信や未処理の応答の受信はできず、TPETIMEが発生します。その例外とは、ブロックされず、応答を期待せず、かつ呼出し側のトランザクションのかわりに送信されない(つまり、TPNOTRANTPNOBLOCKおよび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)

 


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つだけ着信メッセージを受け取り(svcinfodata要素内に)、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になります。

TPCONVflagsに設定する場合、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()を使用してサービスの結果を受信するプログラムのためにtperrnoTPESVCERRに設定されます。またイベントTPEV_SVCERRが、tpsend()またはtprecv()を使用するプログラムに、会話を通して送信されます。

関連項目

tpalloc(3c)tpbegin(3c)tpcall(3c)tpconnect(3c)tpforward(3c)tpreturn(3c)servopts(5)

 


tpsetcallinfo(3c)

名前

tpsetcallinfo()-Tuxedoリクエストに帯域外情報を追加するルーチン。

形式

int tpsetcallinfo(const char *msg, FBFR32 *obuf, long flags)

説明

tpsetcallinfo()は、既存のTuxedo型メッセージに帯域外データを追加するために使用されます。次のパラメータをサポートしています。

msg

型付きバッファは帯域外データを付加するために使用されます。このバッファは、tpalloc()をコールするプロセスによって割り当てられており、後続のtpcall()でidataとして使用されている必要があります。

obuf

フィールドを使うために使用されるFML32バッファ。

flags

将来使用するために予約されたフィールド。

tpsetcallinfoは、次のユースケースで使用できま