ATMI C関数リファレンス

セクション3c - C関数

表1 Oracle Tuxedo ATMI C関数
名前	説明
C言語アプリケーション・トランザクション・モニター・インタフェースの紹介	C言語ATMIの概要を提供します。
`AEMsetblockinghook(3c)`	アプリケーション固有のブロッキング・フック関数を確立します。
`AEOaddtypesw(3c)`	実行時にユーザー定義のバッファ・タイプをインストールまたは置換します。
`AEPisblocked(3c)`	進行中のブロッキング呼出しが存在するかどうかを確認します。
`AEWsetunsol(3c)`	Oracle Tuxedo ATMI任意イベントに対するWindowsメッセージを掲示します。
`buffer(3c)`	`tmtype_sw_t`における要素の意味
`catgets(3c)`	プログラム・メッセージを読み取ります。
`catopen、catclose(3c)`	メッセージ・カタログをオープンまたはクローズします。
`decimal(3c)`	十進数変換および算術ルーチン
`getURLEntityCacheDir(3c)`	DTD、スキーマおよびエンティティ・ファイルがキャッシュされている場所の絶対パスを取得します。これは、特定のXercesパーサー・クラス・メソッドを指定します。
`getURLEntityCaching(3c)`	DTD、スキーマおよびエンティティ・ファイルのキャッシング・メカニズムを取得します。これは、特定のXercesパーサー・クラス・メソッドを指定します。
`gp_mktime(3c)`	`tm`構造体をカレンダ時間に変換します。
`nl_langinfo(3c)`	言語情報
rpc_sm_allocate、rpc_ss_allocate(3c)	RPCスタブ内のメモリーを割り当てます。
rpc_sm_client_free、rpc_ss_client_free(3c)	クライアント・スタブから戻されたメモリーを解放します。
rpc_sm_disable_allocate、rpc_ss_disable_allocate(3c)	スタブのメモリー管理スキーム内のリソースおよび割り当てられたメモリーをリリースします。
rpc_sm_enable_allocate、rpc_ss_enable_allocate(3c)	スタブのメモリー管理環境を有効にします。
rpc_sm_free、rpc_ss_free(3c)	rpc_sm_allocate()ルーチンによって割り当てられたメモリーを解放します。
rpc_sm_set_client_alloc_free、rpc_ss_set_client_alloc_free(3c)	メモリー割当てとクライアント・スタブによって使用される解放メカニズムを設定します。
rpc_sm_swap_client_alloc_free、rpc_ss_swap_client_alloc_free(3c)	現在のメモリー割当てとクライアント・スタブによって使用される解放メカニズムを、クライアントによって提供されたものと交換します。
`setlocale(3c)`	プログラムのロケールの修正および問合せを行います。
`setURLEntityCacheDir(3c)`	DTD、スキーマおよびエンティティ・ファイルがキャッシュされるディレクトリを設定します。これは、特定のXercesパーサー・クラス・メソッドを指定します。
`setURLEntityCaching(3c)`	DTD、スキーマおよびエンティティ・ファイルのキャッシングをデフォルトでオンまたはオフにします。これは、特定のXercesパーサー・クラス・メソッドを指定します。
`strerror(3c)`	エラー・メッセージ文字列を取得します。
`strftime(3c)`	日付および時間を文字列に変換します。
`tpabort(3c)`	現在のトランザクションを中断するルーチン
`tpacall(3c)`	サービス・リクエストを送信するルーチン
`tpadmcall(3c)`	ブートされていないアプリケーションを管理します。
`tpadvertise(3c)`	サービス名を通知するルーチン
`tpalloc(3c)`	型付きバッファの割当てを行うルーチン
tpappthrinit(3c)	アプリケーション生成のサーバー・スレッドで新しいTuxedoコンテキストを生成および初期化するルーチン
tpappthrterm(3c)	サーバー・プロセス内のアプリケーション生成のコンテキストを終了するルーチン
`tpbegin(3c)`	トランザクションを開始するルーチン
`tpbroadcast(3c)`	名前によって通知をブロードキャストするルーチン
`tpcall(3c)`	サービス・リクエストを送信し、その応答を待つルーチン
`tpcancel(3c)`	未終了の応答に対する呼出し記述子を無効にするためのルーチン
`tpchkauth(3c)`	アプリケーションへの参加に認証が必要かどうかをチェックするルーチン
`tpchkunsol(3c)`	任意通知型メッセージをチェックするルーチン
`tpclose(3c)`	リソース・マネージャをクローズするルーチン
`tpcommit(3c)`	現在のトランザクションをコミットするルーチン
`tpconnect(3c)`	会話型サービスの接続を確立するルーチン
`tpconvert(3c)`	構造体を文字列表現に、または文字列表現を構造体に変換します。
`tpconvmb(3c)`	入力バッファ内にある文字のエンコードをターゲットの名前付きのエンコードに変換します。
`tpcryptpw(3c)`	管理リクエスト内のアプリケーション・パスワードを暗号化します。
`tpdequeue(3c)`	キューからメッセージを取り出すルーチン
`tpdiscon(3c)`	会話型サービスの接続を切断するルーチン
`tpenqueue(3c)`	メッセージをキューに登録するルーチン
`tpenvelope(3c)`	型付きメッセージ・バッファに関連付けられたデジタル署名および暗号化情報にアクセスします。
`tperrordetail(3c)`	最後のOracle Tuxedo ATMIシステム・コールで生成されたエラーに関する詳細を取得します。
`tpexport(3c)`	型付きメッセージ・バッファを、デジタル署名と暗号化エンベロープを含むエクスポート可能なマシン独立型の文字列表現に変換します。
tpfml32toxml(3c)	FML32バッファ・データをXMLバッファ・データに変換します。
tpfmltoxml(3c)	FMLバッファ・データをXMLバッファ・データに変換します。
`tpforward(3c)`	サービス・リクエストを他のサービス・ルーチンに転送するルーチン
`tpfree(3c)`	型付きバッファを解放するルーチン
`tpgblktime(3c)`	以前に設定された、1秒または1ミリ秒当たりの非トランザクション・ブロック時間値を戻すルーチン
`tpgetadmkey(3c)`	管理認証キーを取得します。
`tpgetctxt(3c)`	現在のアプリケーション関連のコンテキスト識別子を取り出す
`tpgetlev(3c)`	トランザクション・モードかどうかチェックするルーチン
`tpgetmbenc(3c)`	型付きバッファからコード・セットのエンコード名を取得します。
tpgetrepos(3c)	Tuxedoリポジトリ・ファイルからサービスおよびパラメータ情報を取得するルーチン
`tpgetrply(3c)`	以前のリクエストからの応答を受信するルーチン
`tpgprio(3c)`	サービス・リクエストの優先度を取得するルーチン
`tpimport(3c)`	エクスポートされた表現を型付きメッセージ・バッファに変換し戻します。
`tpinit(3c)`	アプリケーションに参加します。
`tpkey_close(3c)`	前にオープンされたキー・ハンドルをクローズ
`tpkey_getinfo(3c)`	キー・ハンドルに関連付する情報を獲得
`tpkey_open(3c)`	デジタル署名生成、メッセージの暗号化、またはメッセージの復号化のためのキー・ハンドルをオープン
`tpkey_setinfo(3c)`	キー・ハンドルに関連付けられている省略可能な属性パラメータを設定
`tpnotify(3c)`	クライアント識別子によって通知を送信するルーチン
`tpopen(3c)`	リソース・マネージャをオープンするルーチン
`tppost(3c)`	イベントを通知
`tprealloc(3c)`	型付きバッファのサイズを変更するルーチン
`tprecv(3c)`	会話型接続でメッセージを受信するルーチン
`tpresume(3c)`	グローバル・トランザクションを再開
`tpreturn(3c)`	サービス・ルーチンから戻るためのルーチン
tprmclose(3c)	複数のRMサーバー・グループで構成された特定のRMをクローズするルーチン
tprmend(3c)	指定されたRMのトランザクション・ブランチのかわりに実行された現在の作業を終了するルーチン
tprmopen(3c)	複数のRMサーバー・グループに関連付けられている*RMSセクションで構成された特定のRMをオープンするルーチン
tprmstart(3c)	MRMサーバーの指定されたRMのトランザクション・ブランチのかわりに作業を開始するルーチン
`tpsblktime(3c)`	次のサービス呼出しまたはコンテキストごとに使用されるすべてのサービス呼出しの非トランザクション・ブロック時間値を秒単位またはミリ秒単位で設定するルーチン
`tpscmt(3c)`	`tpcommit()`がいつ戻るかを設定するルーチン
`tpseal(3c)`	暗号化のための型付きメッセージ・バッファをマークします。
`tpsend(3c)`	会話型接続でメッセージを送信するルーチン
`tpservice(3c)`	サービス・ルーチンのテンプレート
`tpsetctxt(3c)`	現在のアプリケーション関連にコンテキスト識別子を設定
`tpsetmbenc(3c)`	型付きバッファのコード・セットのエンコード名を設定します。
tpsetrepos(3c)	Tuxedoサービス・メタデータ・リポジトリ・ファイルからのサービスおよびパラメータ情報を追加、編集または削除します。
`tpsetunsol(3c)`	任意通知型メッセージの処理方法を設定します。
`tpsign(3c)`	デジタル署名のための型付きメッセージ・バッファをマークします。
`tpsprio(3c)`	サービス・リクエストの優先度を設定するルーチン
`tpstrerror(3c)`	Oracle Tuxedo ATMIシステム・エラーのエラー・メッセージ文字列を取得します。
`tpstrerrordetail(3c)`	Oracle Tuxedo ATMIシステムのエラー詳細メッセージの文字列を取得します。
`tpsubscribe(3c)`	イベントにサブスクライブ
`tpsuspend(3c)`	グローバル・トランザクションを一時停止
`tpsvrdone(3c)`	Oracle Tuxedo ATMIシステム・サーバーを終了します。
`tpsvrinit(3c)`	Oracle Tuxedo ATMIシステム・サーバーを初期化します。
`tpsvrthrdone(3c)`	Oracle Tuxedo ATMIサーバー・スレッドを終了します。
`tpsvrthrinit(3c)`	Oracle Tuxedo ATMIサーバー・スレッドを初期化します。
`tpterm(3c)`	アプリケーションを分離
`tptypes(3c)`	型付きバッファ情報を判別するルーチン
`tpunadvertise(3c)`	サービス名の通知を取り消すルーチン
`tpunsubscribe(3c)`	イベントへのサブスクライブを取り消す
tputrace(3c)	トレース情報を提供するユーザー定義ルーチン
tpxmltofml32(3c)	XMLバッファ・データをFML32バッファ・データに変換します。
tpxmltofml(3c)	XMLバッファ・データをFMLバッファ・データに変換します。
`TRY(3c)`	例外復帰インタフェース
`tuxgetenv(3c)`	環境名の値を戻します。
`tuxgetmbaconv(3c)`	プロセス環境で環境変数`TPMBACONV`の値を取得します。
`tuxgetmbenc(3c)`	プロセス環境で環境変数`TPMBENC`のコード・セットのエンコード名を取得します。
`tuxputenv(3c)`	環境に対して値を変更または追加します。
`tuxreadenv(3c)`	ファイルから環境に変数を追加します。
`tuxsetmbaconv(3c)`	プロセス環境で環境変数`TPMBACONV`の値を設定します。
`tuxsetmbenc(3c)`	プロセス環境で環境変数`TPMBENC`のコード・セットのエンコード名を設定します。
tuxthrputenv(3c))	現在のスレッドの環境変数を変更または追加します。
`tx_begin(3c)`	グローバル・トランザクションを開始
`tx_close(3c)`	リソース・マネージャ・セットをクローズ
`tx_commit(3c)`	グローバル・トランザクションをコミットします。
`tx_info(3c)`	グローバル・トランザクション情報を返す
`tx_open(3c)`	リソース・マネージャ・セットをオープン
`tx_rollback(3c)`	グローバル・トランザクションをロールバックします。
`tx_set_commit_return(3c)`	`commit_return`特性を設定
`tx_set_transaction_control(3c)`	`transaction_control`特性を設定
`tx_set_transaction_timeout(3c)`	`transaction_timeout`特性を設定
`「userlog(3c)」`	Oracle Tuxedo ATMIシステムの中央イベント・ログにメッセージを書き込みます。
`Usignal(3c)`	Oracle Tuxedo ATMIシステム環境でのシグナル処理
`Uunix_err(3c)`	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システムは、現在のトランザクションの完了を調整し、制御を呼出し側に返す前に新しいトランザクションを開始します(異常終了の条件によっては、新しいトランザクションを開始できない場合もあります)。

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

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

トランザクション特性

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

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

エラー処理

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

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

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

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

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

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

タイムアウト

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

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

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

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

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

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

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

動的サービス公開

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

バッファ管理

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

非請求通知

前述のように定義されたクライアント/サーバー間でのやりとりの境界外からメッセージをアプリケーション・クライアントに送る方法は2通りあります。第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プロセスごとのコンテキスト・モード
関数	状態
関数	非初期化 S₀	初期化されたシングル・コンテキスト・モード S₁	初期化されたマルチコンテキスト・モード S₂
`TPMULTICONTEXTS`が設定されていない`tpinit`	S₁	S₁	S₂(エラー)
`TPMULTICONTEXTS`が設定された`tpinit`	S₂	S₁(エラー)	S₂
暗黙的な`tpinit`	S₁	S₁	S₂(エラー)
`tpterm` - 最後の関連付けでない			S₂
`tpterm` - 最後の関連付け		S₀	S₀
`tpterm` - 関連付けなし	S₀

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

マルチコンテキストのアプリケーションでは、いろいろな関数を呼び出すと、呼出し側スレッド、および呼出し側プロセスと同じコンテキストでアクティブなその他のスレッドのコンテキスト状態が変化します。次の図は、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`	シングル・コンテキスト	該当なし	該当なし	エラー
このスレッドでの`tpterm`	NULL	NULL	NULL	NULL
このコンテキストの異なるスレッドでの`tpterm`	該当なし	NULL	無効	該当なし

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

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

表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()を使用する必要があります。

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

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

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

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

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

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

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

表7 アプリケーションの関連付けのトランザクション状態
関数	状態
関数	トランザクション内ではない T₀	イニシエータ T₁	参加者 T₂
`tpbegin`
`tpabort`		T₀
`tpcommit`		T₀
`tpsuspend`		T₀
`tpresume`	T₁	T₀
フラグ`TPTRAN`が設定された`tpservice`	T₂
`tpservice` (トランザクション・モードでない)	T₀
`tpreturn`	T₀		T₀
`tpforward`	T₀		T₀
`tpclose`	R₀
`tpterm`	I₀	T₀
ほかのすべてのATMI関数	T₀	T₁	T₂

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

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

注意:

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

注意:

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

注意: ^c 記述子が呼出し側のトランザクションに関連付けられている場合、tpsuspend()はプロトコル・エラーを戻します。

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

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

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

表9 接続リクエスト記述子の状態
関数/イベント	状態
関数/イベント	C₀	C₁	C₂	C₃	C₄
`TPSENDONLY`が設定された`tpconnect`	C₁ ^a
`TPRECVONLY`が設定された`tpconnect`	C₂ ^a
フラグ`TPSENDONLY`が設定された`tpservice`	C₃ ^b
フラグ`TPRECVONLY`が設定された`tpservice`	C₄^b
`tprecv`/イベントなし			C₂		C₄
`tprecv`/`TPEV_SENDONLY`			C₁		C₃
`tprecv`/`TPEV_DISCONIMM`			C₀		C₀
`tprecv`/`TPEV_SVCERR`			C₀
`tprecv`/`TPEV_SVCFAIL`			C₀
`tprecv`/`TPEV_SVCSUCC`			C₀
`tpsend`/イベントなし		C₁		C₃
フラグ`TPRECVONLY`が設定された`tpsend`		C₂		C₄
`tpsend`/`TPEV_DISCONIMM`		C₀		C₀
`tpsend`/`TPEV_SVCERR`		C₀
`tpsend`/`TPEV_SVCFAIL`		C₀
`tpterm` (クライアントのみ)	C₀	C₀
`tpcommit` (オリジネータのみ)	C₀	C₀ ^c	C₀^c
`tpsuspend` (オリジネータのみ)	C₀	C₁^d	C₂^d
`tpabort` (オリジネータのみ)	C₀	C₀ ^c	C₀ ^c
`tpdiscon`		C₀	C₀
`tpreturn` (`CONV`サーバー)		C₀	C₀	C₀	C₀
`tpforward` (`CONV`サーバー)		C₀	C₀	C₀	C₀
ほかのすべてのATMI関数	C₀	C₁	C₂	C₃	C₄

注意: ^a プロセスがトランザクション・モードでTPNOTRANの指定がない場合、接続はトランザクション・モードになります。

注意: ^b TPTRANが設定されている場合、接続はトランザクション・モードになります。

注意:

^c接続がトランザクション・モードにない場合、状態は変化しません。

注意: ^d 接続がトランザクション・モードの場合、tpsuspend()はプロトコル・エラーを戻します。

TXの状態遷移

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

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

S₀: どのRMもオープンまたは初期化が行われていません。アプリケーションの関連付けは、tx_openを正常に呼び出すまで、グローバル・トランザクションを開始できません。
S₁: アプリケーションの関連付けはRMをオープンしましたが、トランザクションに入っていません。transaction_control特性はTX_UNCHAINEDです。
S₂: アプリケーションの関連付けはRMをオープンしましたが、トランザクションに入っていません。transaction_control特性はTX_CHAINEDです。
S₃: アプリケーションの関連付けはRMをオープンし、トランザクションに入っています。transaction_control特性はTX_UNCHAINEDです。
S₄: アプリケーションの関連付けはRMをオープンし、トランザクションに入っています。transaction_control特性はTX_CHAINEDです。

表10 TX関数の状態遷移
関数	状態
関数	S₀	S₁	S₂	S₃	S₄
`tx_begin`		S₃	S₄
`tx_close`	S₀	S₀	S₀
`tx_commit` `TX_SET1`				S₁	S₄
`tx_commit` `TX_SET2`					S₂
`tx_info`		S₁	S₂	S₃	S₄
`tx_open`	S₁	S₁	S₂	S₃	S₄
`tx_rollback` `TX_SET1`				S₁	S₄
`tx_rollback` `TX_SET2`					S₂
`tx_set_commit_return`		S₁	S₂	S₃	S₄
`tx_set_transaction_control control = TX_CHAINED`		S₂	S₂	S₄	S₄
`tx_set_transaction_control control = TX_UNCHAINED`		S₁	S₁	S₃	S₃
`tx_set_transaction_timeout`		S₁	S₂	S₃	S₄

TX_SET1は、TX_OK、TX_ROLLBACK、TX_MIXED、TX_HAZARD、TX_COMMITTEDのいずれかを表します。TX_ROLLBACKはtx_rollback()からは返されず、TX_COMMITTEDはtx_commit()からは返されません。
TX_SET2は、TX_NO_BEGIN、TX_ROLLBACK_NO_BEGIN、TX_MIXED_NO_BEGIN、TX_HAZARD_NO_BEGIN、またはTX_COMMITTED_NO_BEGINのいずれかを表します。TX_ROLLBACK_NO_BEGINはtx_rollback()では返されません。TX_COMMITTED_NO_BEGINはtx_commit()では返されません。
TX_FAILは、いずれかの呼出しから返された場合には、アプリケーション・プログラムの状態は、上記の表では未定義の状態になります。
tx_info()が、トランザクション状態情報にTX_ROLLBACK_ONLYまたはTX_TIMEOUT_ROLLBACK_ONLYを返した場合には、そのトランザクションは、「アボートのみ(ロールバックのみ)」とマークされ、アプリケーション・プログラムがtx_commit()を呼び出したかtx_rollback()を呼び出したかに関係なく、ロールバック(アボート)されます。

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
           ....

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つ以上存在することは禁止されていることに注意してください。

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()リクエストが、非請求メッセージを処理する方法を決定します。

buffer(3c)

名前

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

形式

int     /* Initialize a new data buffer */
_tminitbuf(char *ptr, long len)
int    /* Reinitialize a reallocated data buffer */
_tmreinitbuf(char *ptr, long len)
int    /* Uninitialize a data buffer to be freed */
_tmuninitbuf(char *ptr, long len)
long   /* Process buffer before sending */
_tmpresend(char *ptr, long dlen, long mdlen)
void   /* Process buffer after sending */
_tmpostsend(char *ptr, long dlen, long mdlen)
long   /* Process buffer after receiving */
_tmpostrecv(char *ptr, long dlen, long mdlen)
long   /* Encode/decode a buffer to/from a transmission format */
_tmencdec(int op, char *encobj, long elen, char *obj, long olen)
int    /* Determine server group for routing based on data */
_tmroute(char *routing_name, char *service, char *data, long \  len, char *group)
int    /* Evaluate boolean expression on buffer’s data */
_tmfilter(char *ptr, long dlen, char *expr, long exprlen)
int    /* Extract buffer’s data based on format string */
_tmformat(char *ptr, long dlen, char *fmt, char *result, long \  maxresult) 
long   /* Process buffer before sending, possibly generating copy */
_tmpresend2(char *iptr, long ilen, long mdlen, char *optr, long olen, long *flags )
long  /* Multibyte code-set encoding conversion */ 
_tmconvmb(char *ibufp, long ilen, char *enc_name, char *obufp, long olen, long 
    *flags)

説明

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

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

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

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

ルーチンの詳細

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

_tminitbuf()

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

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

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

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

_tmreinitbuf

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

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

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

_tmuninitbuf

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

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

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

_tmpresend

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

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

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

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

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

_tmpostsend()

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

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

_tmpostrecv

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

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

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

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

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

_tmencdec

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

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

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

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

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

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

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

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

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

_tmroute

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

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

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

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

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

_tmfilter()

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

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

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

_tmformat()

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

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

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

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

_tmpresend2

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

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

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

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

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

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

[`TMPARENT`]

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

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

[`TMUSEIPTR`]

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

[`TMUSEOPTR`]

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

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

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

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

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

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

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

_tmconvmb

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

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

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

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

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

[`TMUSEIPTR`]

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

[`TMUSEOPTR`]

_tmconvmb()が成功しました。処理されたデータはobufpが参照するバッファ内にあり、戻り値には変換されたデータの長さが含まれます。obufpバッファの割当てと、解放またはキャッシュは、呼出し側が行います。

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

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() - メッセージ・カタログをオープンまたはクローズします。

形式

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

説明

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

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

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

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

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

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

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

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

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

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

LANG=De_A.88591

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

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

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

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

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

診断

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

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オブジェクトと組み合せて排他的に使用されます。

XercesDOMParser
SAXparser

getURLEntityCaching(3c)

名前

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

形式

bool getURLEntityCaching()

説明

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

XercesDOMParser
SAXparser

gp_mktime(3c)

名前

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

形式

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

説明

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

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

struct tm {
  int tm_sec;     /* seconds after the minute [0, 61] */
  int tm_min;     /* minutes after the hour [0, 59] */
  int tm_hour;    /* hour since midnight [0, 23] */
  int tm_mday;    /* day of the month [1, 31] */
  int tm_mon;     /* months since January [0, 11] */
  int tm_year;    /* years since 1900 */
  int tm_wday;    /* days since Sunday [0, 6] */
  int tm_yday;    /* days since January 1 [0, 365] */
  int tm_isdst;   /* flag for daylight savings time */
};

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

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

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

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

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

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

例

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

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

注意事項

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

移植性

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

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

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

`std`および`dst`

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

`offset`

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

`start`/`time`,`end`/`time`

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

J`n`

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

`n`

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

M`m.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です。

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()の次の呼出しで、この配列が上書きされることがあります。

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_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コールにより返された動的に割り当てられたメモリーを解放することができます。

コードがサーバーの一部として実行している場合であっても、このルーチンは常にクライアント・コードから呼び出されます。

rpc_s_ok

正常終了

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

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

戻り値

なし。

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()を呼び出さずにこのルーチンを呼び出すと、予期しない動作が発生します。

rpc_s_ok

正常終了

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

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

戻り値

なし。

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()を呼び出す必要があります。

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_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()を呼び出した場合は、予期できない結果が生じます。

rpc_s_ok

正常終了

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

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

戻り値

なし。

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()になります。

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_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クライアントの場合は、その呼出し側が選択したメカニズムにかかわらず、どのメモリー割り当ておよび解放のルーチンが使用されたかを確認する必要があります。このルーチンを使用すれば、メモリー割り当ておよび解放のメカニズムを意図的に交換して、使用されたルーチンを確認することができます。

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

戻り値

なし。

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

説明

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

setURLEntityCacheDir(3c)

名前

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

形式

void setURLEntityCacheDir (const char* cachedir)

説明

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

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

XercesDOMParser
SAXparser

setURLEntityCaching(3c)

名前

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

形式

void setURLEntityCaching (bool UseCache)

説明

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

XercesDOMParser
SAXparser

strerror(3c)

名前

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

形式

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

説明

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

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

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_TIMEのlocaleを設定することによって特定の言語に変更することができます。

タイム・ゾーン

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

サンプル

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

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

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

ファイル

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

tpabort(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`]

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

注意事項

tpacall(3c)

名前

tpacall()—サービス・リクエストの送信を行うルーチン

形式

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

説明

tpacall()は、svcで指定されているサービスにリクエスト・メッセージを送ります。このリクエストは、以前のtpspri()で変更されていないかぎり、svcに対して定義されている優先度で送信されます。dataは、NULLでなければ、tpalloc()が以前に割り当てたバッファを指していなければなりません。lenには送信するバッファに入るデータの量を指定します。ただし、dataが長さの指定を必要としないバッファを指している場合(FMLフィールド化バッファなど)、lenは無視されます(0でかまいません)。dataがNULLであると、lenは無視され、リクエストはデータ部なしで送信されます。dataのタイプとサブタイプは、svcが認識するタイプおよびサブタイプと一致しなければなりません。トランザクション・モードにあるときに送信されるリクエストごとに、最終的には対応する応答が受信されなければならないことに注意してください。

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

`TPNOTRAN`

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

`TPNOREPLY`

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

`TPNOBLOCK`

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

`TPNOTIME`

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

`TPSIGRSTRT`

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

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

戻り値

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

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

エラー

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

[`TPEINVAL`]

無効な引数が与えられました(たとえば、svcがNULLであったり、dataがtpalloc()で割り当てられた領域を指していなかったり、あるいはflagsが無効です)。

[`TPENOENT`]

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

[`TPEITYPE`]

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

[`TPELIMIT`]

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

[`TPETRAN`]

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

[`TPETIME`]

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

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

[`TPEBLOCK`]

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

[`TPGOTSIG`]

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

[`TPEPROTO`]

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

[`TPESYSTEM`]

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

[`TPEOS`]

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

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を使用する必要があります。

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`]

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

tpalloc(3c)

名前

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

形式

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

説明

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

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

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

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

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

戻り値

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

エラー

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

[`TPEINVAL`]

無効な引数が与えられた場合(たとえば、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言語アプリケーション・トランザクション・モニター・インタフェースの紹介」を参照してください。

tpappthrinit(3c)

名前

tpappthrinit() - アプリケーション生成のサーバー・スレッドで新しいTuxedoコンテキストを生成および初期化するルーチン

形式

#include <atmi.h> 
int tpappthrinit(TPINIT *tpthrinfo);

説明

tpappthrinit()は、アプリケーション生成のサーバー・スレッドで新しいTuxedoコンテキストを生成します。tpappthrinit()によって生成されたコンテキストは、アプリケーション・サーバーが存在するドメインに接続します。また、現在のアプリケーション・スレッドのコンテキストを新たに作成されたコンテキストに設定します。

Tuxedoサーバー・プロセス内のアプリケーション生成スレッドがTuxedo ATMIシステムの通信ルーチンまたはトランザクション・ルーチンを使用するには、まずtpappthrinit()を呼び出すか、自身をtpsetctxt()を使用して有効なコンテキストに関連付ける必要があります。

tpappthrinit()が正常終了した後、アプリケーション生成のサーバー・スレッドはサービス・リクエストを開始し、トランザクションを定義できます。

注意: アプリケーション・スレッドは、tpreturn()およびtpforward()を呼び出すことはできません。アプリケーション・スレッドは、非請求メッセージを送信することはできますが、受信することはできません。

tpappthrinit()が正常に終了した後、アプリケーション生成のサーバー・スレッドはtpgetctxt()を呼び出して現在のコンテキストを取得し、そのコンテキストを、別のアプリケーション生成のサーバー・スレッドで呼び出したtpsetctxt()にパラメータとして渡すことで、自身を別のコンテキストに関連付けることができます。

注意: サービス・ルーチンでtpappthrinit()によって生成されたコンテキストを設定することはできません。

tpappthrinit()の引数tpthrinfoは、TPINITバッファ・タイプとNULLサブタイプのポインタです。TPINITは、atmi.hヘッダー・ファイルで定義されるバッファ・タイプです。このバッファは、tpappthrinit()を呼び出す前にtpalloc()で割り当てる必要があります。このバッファの解放は、tpappthrinit()の呼出しの後、tpfree()を使用して行います。

TPINIT構造体の説明については、tpinit()ルーチンを参照してください。tpappthrinit()に認証情報を渡す場合、tpthrinfoのメンバーであるusrname、data、およびdatalenが使用されます。tpthrinfoのメンバーであるcltname、grpname、およびpasswdは現在使用されないため、長さが0の文字列に設定する必要があります。TPINITのメンバーであるflagsも、tpappthrinit()では使用されません。

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

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

戻り値

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

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

エラー

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

`[TPEINVAL]`

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

`[TPEPROTO]`

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

`[TPENOENT]`

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

`[TPEPERM]`

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

`[TPESYSTEM]`

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

`[TPEOS]`

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

tpappthrterm(3c)

名前

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]`

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

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インタフェースを満たすリソース・マネージャをサーバーにリンクします。

tpbroadcast(3c)

名前

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

形式

#include <atmi.h> 
 
int tpbroadcast(char *lmid, char *usrname, char *cltname,
  char *data,  long len, long flags)

説明

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

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

このリクエストのデータ部はdataによって示され、以前にtpalloc()によって割り当てられたバッファです。lenに送信するデータの大きさを指定します。ただし、dataが長さの指定を必要としないタイプのバッファを指す場合(たとえば、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)」を参照してください。

tpcall(3c)

名前

tpcall() - サービス・リクエストを送信し、その応答を待つルーチン

形式

int tpcall(char *svc, char *idata, long ilen, char **odata, long \ 
   *olen, long flags)

説明

tpcall()は、リクエストを送り、それと同期してその応答を待ちます。この関数への呼出しは、tpacall()を呼び出した後、即座にtpgetrply()を呼び出すのと同じことです。tpcall()は、svcが指定するサービスにリクエストを送ります。このリクエストは、以前のtpspri()で変更されていないかぎり、svcに対して定義されている優先度で送信されます。このリクエストのデータ部はidataによって示され、以前にtpalloc()によって割り当てられたバッファです。ilenに送信するidataの大きさを指定します。なお、idataは、長さの指定を必要としないタイプのバッファを指している場合(たとえば、FMLのフィールド化バッファ)、ilenの値は無視(あるいは0に)されます。また、idataをNULLにすることもできますが、この場合には、ilenは無視されます。idataのタイプとサブタイプは、svcが認識するタイプおよびサブタイプのいずれかと一致しなければなりません。

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

odataは応答が読み込まれるバッファに対するポインタのアドレスです。olenはその応答の長さを指します。*odataは、最初にtpalloc()によって割り当てられたバッファを指す必要があります。送信と受信に同じバッファを使用する場合は、odataにはidataのアドレスを指定してください。FMLとFML32バッファは、通常最小サイズ4096バイトを確保します。応答が4096バイトより大きい場合には、バッファ・サイズは返されるデータを入れるのに十分な大きさに拡大します。また、tpcall()が呼び出されたときにidataと*odataが等しかった場合に、*odataが変更されると、idataは有効なアドレスを指さなくなります。古いアドレスを使用すると、データの破損やプロセス例外が発生する可能性があります。リリース6.4では、バッファに対するデフォルトの割当ては1024バイトです。また、最近使用したバッファの履歴情報が保持され、最適サイズのバッファをリターン・バッファとして再利用できます。

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

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

*olenが戻り時に0であると、応答にはデータ部がなく、*odataも、それが指すバッファも変更されていません。*odataまたは*olenがNULLであると、エラーになります。

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

`TPNOTRAN`

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

`TPNOCHANGE`

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

`TPNOBLOCK`

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

`TPNOTIME`

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

`TPNOCOPY`

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

`TPSIGRSTRT`

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

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

戻り値

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

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

エラー

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

[`TPEINVAL`]

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

[`TPENOENT`]

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

[`TPEITYPE`]

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

[`TPEOTYPE`]

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

[`TPETRAN`]

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

[`TPETIME`]

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

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

[`TPESVCFAIL`]

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

[`TPESVCERR`]

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

[`TPEBLOCK`]

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

[`TPGOTSIG`]

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

[`TPEPROTO`]

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

[`TPESYSTEM`]

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

[`TPEOS`]

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

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`]

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

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オペレーティング・システム上でサポートされています。

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`]

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

移植性

シグナル・ベースの通知方法を選択したクライアントは、シグナルに関する制約から、システムがシグナルで通知を制御することはできません。このような状態で通知がなされた場合、システムは、選択されたクライアントに対する通知方法をディップ・インに切り替えることを示すログ・メッセージを生成し、以後、クライアントにはディップ・イン方式で通知が行われることになります。通知方法の詳細は、UBBCONFIG(5)のRESOURCESセクションのNOTIFYパラメータの説明を参照してください。

ネイティブ・クライアントがアプリケーション管理者として実行している必要があります。
ワークステーション・クライアントは、アプリケーション管理者として実行している必要はありません。

アプリケーション管理者のIDは、アプリケーション構成の一部として識別されます。

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`]

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

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)」を参照してください。

tpconnect(3c)

名前

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

形式

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

説明

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

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

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

`TPNOTRAN`

`TPSENDONLY`

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

`TPRECVONLY`

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

`TPNOBLOCK`

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

`TPNOTIME`

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

`TPSIGRSTRT`

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

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

戻り値

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

エラー

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

[`TPEBLOCK`]

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

[`TPEINVAL`]

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

[`TPEITYPE`]

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

[`TPELIMIT`]

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

[`TPENOENT`]

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

[`TPEOS`]

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

[`TPEPROTO`]

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

[`TPESYSTEM`]

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

[`TPETIME`]

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

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

[`TPETRAN`]

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

[`TPGOTSIG`]

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

tpconvert(3c)

名前

tpconvert() - 構造体の文字列表現とバイナリ表現の間の変換

形式

#include <atmi.h>
#include <xa.h>
 
int tpconvert(char *strrep, char *binrep, long flags)

説明

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

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

`TPCONVCLTID`

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

`TPCONVTRANID`

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

`TPCONVXID`

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

バイナリ表現から文字列表現に変換する場合、strrepは最低でもTPCONVMAXSTR文字の長さがなければなりません。

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

tpconvmb(3c)

名前

tpconvmb() - 入力バッファ内にある文字のエンコードをターゲットの名前付きのエンコードに変換

形式

#include <atmi.h>
extern int tperrno;
int
tpconvmb (char **bufp, int *len, char *target_encoding, long flags)

説明

この関数は、入力バッファを目的のコードセットのエンコードに変換する場合に使用します。

この関数は、ユーザーの利便性を考慮して追加されたものであり、通常の自動によるコードセットのデータ変換では必須ではありません。

引数bufpは、MBSTRING型付きバッファのメッセージを指す有効なポインタです。バッファのサイズが変換済バッファの出力データの処理に不十分な場合、このポインタは内部的に再割り当てされます。

入力での引数lenには、変換に必要なバイト数が入ります。変換が正常に終了すると、bufpで使用されたバイト数が入ります。

引数target_encodingは、bufpメッセージで提供される型付きバッファの変換に使用するターゲットのコードセットのエンコード名です。

flags引数はTuxedo会話モードでは使用されません。これは、ユーザー定義の変換関数用のバッファ・タイプ・スイッチ関数に渡されます。

戻り値

正常終了の場合、tpconvmb()は0を返します。エラーの場合には-1を返し、次に説明するようにtperrnoを設定します。この関数は、次の原因により異常終了する可能性があります。

[`TPEINVAL`]

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

[`TPEPROTO`]

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

[`TPESYSTEM`]

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

[`TPEOS`]

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

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

tpdequeue(3c)

名前

tpdequeue() - キューからメッセージを取り出すルーチン

形式

#include <atmi.h> 
int tpdequeue(char *qspace, char *qname, TPQCTL *ctl, char **data, long *len, long flags)

説明

tpdequeue()は、キュー・スペースqspace内のqnameで指定されるキューから、処理するメッセージを取り出します。

省略時設定では、キューの先頭のメッセージが取り出されます。キュー上のメッセージの順序は、そのキューの作成時に定義されます。アプリケーションは、ctlパラメータでメッセージ識別子または相関識別子を指定することにより、特定のメッセージのキューからの取出しをリクエストできます。メッセージが現在利用できなかった場合にはアプリケーションはメッセージを待つということを示すために、ctlフラグを使用することもできます。ctlパラメータを使って、メッセージをキューから削除したりキューでのメッセージの相対位置を変更せずにメッセージを見ることができます。この後のこのパラメータについての説明を参照してください。

dataはメッセージが読み込まれるバッファに対するポインタのアドレスです。lenはそのメッセージの長さを指します。*dataは、最初にtpalloc()によって割り当てられたバッファを指す必要があります。メッセージがtpdequeueに渡されるバッファよりも大きい場合、バッファはメッセージが入れる大きさまで拡大されます。メッセージ・バッファのサイズに変化があるかどうかを判別するには、tpdequeue()が発行される前の(合計の)サイズを*lenと比較します。*lenのほうが大きい場合、バッファは大きくなっています。そうでない場合は、バッファのサイズは変更されていません。なお、*dataは、バッファのサイズが大きくなったこと以外の理由でも変化する可能性があるので注意してください。終了時に*lenが0である場合は、取り出されたメッセージにはデータ部がなく、*dataも*dataが指すバッファも変更されていません。*dataまたはlenがNULLであるとエラーになります。

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

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

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

`TPNOTRAN`

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

`TPNOBLOCK`

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

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

`TPNOTIME`

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

`TPNOCHANGE`

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

`TPSIGRSTRT`

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

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

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

制御パラメータ

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

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

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

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

`TPNOFLAGS`

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

`TPQGETBYMSGID`

このフラグを設定すると、ctl

msgidによって指定されたメッセージ識別子を持つメッセージのエキューをリクエストします。メッセージ識別子は、事前のtpenqueue(3c)の呼出しによって取得できます。メッセージが別のキューに移動すると、メッセージ識別子が変わることに注意してください。また、メッセージ識別子の値は32バイトすべてが意味を持つため、ctl

msgidによって指定された値を完全に初期化する必要があります(たとえば、NULL文字で埋めるなど)。

`TPQGETBYCORRID`

このフラグを設定すると、ctl

corridによって指定された相関識別子を持つメッセージのデキューをリクエストします。相関識別子は、アプリケーションがtpenqueue()でメッセージをエンキューしたときに指定されます。また、相関識別子の値は32バイト全体が意味を持つため、ctl

corridによって指定された値を完全に初期化する必要があります(たとえば、NULL文字で埋めるなど)。

`TPQWAIT`

このフラグが設定されていると、キューが空の場合はエラーが戻されません。かわりに、メッセージを取り出せるようになるまで、プロセスは待機する必要があります。TPQWAITがTPQGETBYMSGIDまたはTPQGETBYCORRIDとともに設定されている場合、指定されたメッセージ識別子または相関識別子を持つメッセージがキューに存在しないときは、エラーが戻されません。かわりに、基準を満たすメッセージを取り出せるようになるまで、プロセスは待機する必要があります。プロセスが呼出し側のトランザクション・タイムアウトに従っている場合、またはトランザクション・モードでない場合、プロセスは、TMQUEUEプロセスに-tオプションで指定されたタイムアウトの影響を受けます。

要求する基準を満たすメッセージがすぐには利用できず、設定されたアクションのリソースを使い尽くしてしまった場合には、tpdequeueは -1を返しtperrnoをTPEDIAGNOSTICに設定し、TPQCTL構造体の診断フィールドをQMESYSTEMに設定します。 TPQWAIT制御パラメータを指定するtpdequeue()の各リクエストでは、条件を満たすメッセージがすぐに利用できない場合、キュー・マネージャ(TMQUEUE)のアクション・オブジェクトを使用できる必要があります。アクション・オブジェクトが使用できない場合、tpdequeue()リクエストは失敗します。利用できるキュー・マネージャのアクション数は、キュー・スペースの作成時または変更時に指定されます。待機中のキューからの取出しリクエストが完了すると、対応するアクション・オブジェクトは別のリクエストに使用できるようになります。

`TPQPEEK`

このフラグが設定されていると、指定されたメッセージが読み取られてもキューから削除されません。このフラグは、tpdequeue()操作にTPNOTRANフラグが設定されていることを意味します。つまり、非破壊的なキューからの取出しはトランザクションに含まれません。トランザクション終了前のトランザクション内で、キューに登録されたメッセージまたはキューから取り出されたメッセージを読み取ることはできません。

あるスレッドがTPQPEEKを使用してメッセージを破棄せずにキューから取り出す場合、その取出しリクエストをシステムが処理している短時間の間、非ブロッキング状態の他のメッセージ取出し操作にメッセージが認識されないことがあります。たとえば、特定の選択基準(メッセージ識別子や相関識別子など)を使用してメッセージをキューから取り出す操作が、破棄せずに取出しが現在行われているメッセージを探している場合などがあります。

tpdequeue()からの出力時には、次の要素がTPQCTL構造体に設定されます。

long flags;            /* indicates which of the values 
                        * should be set */
 
long priority;         /* enqueue priority */ 
char msgid[32];        /* ID of message dequeued */ 
char corrid[32];       /* correlation identifier used to
                        * identify the message */
long delivery_qos;     /* delivery quality of service */
long reply_qos;        /* reply message quality of service */
char replyqueue[128];   /* queue name for reply */ 
char failurequeue[128]; /* queue name for failure */ 
long diagnostic;       /* reason for failure */ 
long appkey;           /* application authentication client 
                        * key */ 
long urcode;           /* user-return code */ 
CLIENTID cltid;        /* client identifier for originating 
                        * client */

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

`TPQPRIORITY`

このフラグが設定されていてtpdequeue()の呼出しが正常終了し、メッセージが明示的な優先度でキューに登録された場合、この優先度がctl

priorityに格納されます。優先度は1以上100以内の範囲内で、数値が高いほど優先度も高くなります。つまり、高い数値のメッセージが低い数値のメッセージよりも先にキューから取り出されます。優先度によって順序付けられていないキューの場合、値は情報にすぎません。

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

`TPQMSGID`

このフラグが設定されていてtpdequeue()の呼出しが正常終了した場合、メッセージ識別子がctl

msgidに格納されます。メッセージ識別子の値は、32バイト全体が意味を持ちます。

`TPQCORRID`

このフラグが設定されていてtpdequeue()の呼出しが正常終了し、メッセージが相関識別子によってエンキューされた場合、この相関識別子がctl

corridに格納されます。相関識別子の値は、32バイト全体が意味を持ちます。Oracle Tuxedo ATMI /Qが提供するメッセージの応答には、すべて元のリクエスト・メッセージの相関識別子が付いています。

`TPQDELIVERYQOS`

このフラグが設定され、tpdequeue()の呼出しが成功し、メッセージがサービスの配信品質と共にキューに登録されていた場合、TPQQOSDEFAULTPERSIST、TPQQOSPERSISTENT、またはTPQQOSNONPERSISTENTフラグがctl->delivery_qosに格納されます。メッセージがキューに登録されたときに配信サービスの品質が明示的に指定されていない場合は、ターゲットとなるキューのデフォルトの配信ポリシーによってメッセージ配信の品質が決まります。

`TPQREPLYQOS`

このフラグが設定され、tpdequeue()の呼出しが成功し、メッセージがサービスの応答品質と共にキューに登録されていた場合、TPQQOSDEFAULTPERSIST、TPQQOSPERSISTENT、またはTPQQOSNONPERSISTENTフラグがctl->reply_qosに格納されます。メッセージがキューに登録されていたときに応答のサービス品質が明示的に指定されていない場合、ctl->replyqueueキューのデフォルトの配信ポリシーによって、すべての応答に対する配信サービスの品質が決まります。

デフォルトの配信ポリシーは、メッセージに対する応答がキューに登録されるときに決定される点に注意してください。つまり、元のメッセージがキューに登録されてからメッセージに対する応答が登録されるまでの間に、応答キューのデフォルトの配信ポリシーが変更された場合、応答が最後に登録される時点で有効なポリシーが使用されます。

`TPQREPLYQ`

このフラグが設定されていてtpdequeue()の呼出しが正常終了し、メッセージが応答キューによってエンキューされた場合、応答キューの名前がctl

replyqueueに格納されます。メッセージへの応答は、リクエスト・メッセージと同じキュー・スペース内の指定された応答キューに登録されます。

`TPQFAILUREQ`

このフラグが設定されていてtpdequeue()の呼出しが正常終了し、メッセージが失敗キューによってエンキューされた場合、失敗キューの名前がctl

failurequeueに格納されます。失敗メッセージは、リクエスト・メッセージと同じキュー・スペース内の指定された失敗キューに登録されます。

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

tpdequeue()の呼出しが失敗してtperrnoにTPEDIAGNOSTICが設定された場合は、失敗の原因を示す値がctldiagnosticに戻されます。戻される可能性のある値は、この後の「診断」の項で定義しています。

また出力時には、tpdequeue()の呼出しが正常に終了すると、ctlappkeyにアプリケーション認証キーが設定され、ctlcltidにリクエストの発信元であるクライアントの識別子が設定され、ctlurcodeにメッセージ登録時に設定されたユーザー戻り値が設定されます。

ctlパラメータがNULLである場合、入力フラグはTPNOFLAGSとみなされ、アプリケーション・プログラムは出力情報を利用できません。

戻り値

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

エラー

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

[`TPEINVAL`]

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

[`TPENOENT`]

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

[`TPEOTYPE`]

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

[`TPETIME`]

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

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

[`TPEBLOCK`]

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

[`TPGOTSIG`]

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

[`TPEPROTO`]

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

[`TPESYSTEM`]

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

[`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)を使用して読取りおよび書込みを排他的に行うため、キューをオープンしています。

tpdiscon(3c)

名前

tpdiscon() - 会話型サービスの接続を切断するルーチン

形式

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

説明

tpdiscon()は、cdで指定された接続をただちに切断し、接続の他方の側でTPEV_DISCONIMMイベントを生成します。

tpdiscon()は、会話の起動側からしか呼び出せません。tpdiscon()は、呼出しに使用された記述子に対応する会話型サービス内からは呼び出せません。会話型サービスはtpreturn()を使用して、会話の該当部分が完了したことを通知しなければなりません。同様に、会話型サービスとのやりとりを行うプログラムがtpdiscon()を呼び出す場合でも、そのサービスにtpreturn()で接続を切断するようにしてください。これによって、正しい結果が得られます。

tpdiscon()を使用すると、接続はただちに切断されます(すなわち、正常終了ではなく、アボート)。したがって、宛先に届いていないデータは失われます。tpdiscon()は、接続の他方の側のプログラムが呼出し側のトランザクションに参加している場合でも発行されます。この場合、このトランザクションはアボートします。また、呼出し側は、tpdiscon()が呼び出されるときにその接続の制御権をもっている必要はありません。

戻り値

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

エラー

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

[`TPEBADDESC`]

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

[`TPETIME`]

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

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

[`TPEPROTO`]

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

[`TPESYSTEM`]

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

[`TPEOS`]

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

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`

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

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

`TPNOTIME`

`TPSIGRSTRT`

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

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

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

制御パラメータ

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

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

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

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

`TPNOFLAGS`

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

`TPQTOP`

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

`TPQBEFOREMSGID`

このフラグを設定すると、キューの順序はオーバーライドされ、メッセージはctl

msgidによって識別されるメッセージの前に登録されます。このリクエストは、順序付けを無効にするようにキューが設定されているかどうかによって、使用できない場合があります。TPQTOPとTPQBEFOREMSGIDは、相互に排他的なフラグです。また、メッセージ識別子の値は32バイト全体が意味を持つため、ctl

msgidによって指定された値を完全に初期化する必要があります(たとえば、NULL文字で埋めるなど)。

`TPQTIME_ABS`

このフラグが設定されると、メッセージはctl

deq_timeによって指定された時間の後で使用可能になります。deq_timeは、time(2)、mktime(3C)またはgp_mktime(3c)によって生成された絶対時間値です(UTC (協定世界時) 1970年1月1日00:00:00から経過した秒数)。TPQTIME_ABSとTPQTIME_RELは、相互に排他的なフラグです。絶対時間は、キュー・マネージャ・プロセスが存在するマシン・クロックによって決定されます。

`TPQTIME_REL`

このフラグを設定すると、メッセージは、キューへの登録操作が完了してからの相対時間経過後に使用可能になります。ctl

deq_timeは、キューの登録が完了した後、出されたリクエストが処理されるまでの遅延秒数を指定します。TPQTIME_ABSとTPQTIME_RELは、相互に排他的なフラグです。

`TPQPRIORITY`

このフラグを設定すると、メッセージがエンキューされる際の優先度がctl

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

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

`TPQCORRID`

このフラグが設定されている場合、ctl

corridで指定された相関識別子の値は、メッセージがtpdequeue()によってデキューされるときに使用できます。この識別子は、キューに登録されるすべての応答メッセージまたは失敗メッセージに付加されるので、アプリケーションは応答を特定のリクエストに結び付けることができます。また、相関識別子の値は32バイト全体が意味を持つため、ctl

corridで指定された値を完全に初期化する必要があります(たとえば、NULL文字で埋めるなど)。

`TPQREPLYQ`

このフラグが設定されると、ctl

replyqueueで指定された応答キューは、待機メッセージに関連付けられます。メッセージに対する応答はすべて、リクエスト・メッセージと同じキュー・スペース内の指定されたキューに登録されます。この文字列は、NULLで終了する必要があります(最大127文字)。

`TPQFAILUREQ`

このフラグが設定されると、ctl

failurequeueで指定された失敗キューは、待機メッセージに関連付けられます。(1)キューに登録されたメッセージがTMQFORWARD()によって処理され、(2) TMQFORWARDが-dオプションで開始され、さらに(3)サービスが失敗してNULL以外の応答を戻す場合は、その応答と関連するtpurcodeによって構成される失敗メッセージが、元のリクエスト・メッセージと同じキュー・スペース内で指定されたキューに登録されます。この文字列はNULLで終了する必要があります(長さは最大127文字)。

`TPQDELIVERYQOS`、`TPQREPLYQOS`

TPQDELIVERYQOSフラグが設定されていると、ctl->delivery_qosで指定されたフラグにより、メッセージの配信サービスの品質が制御されます。その場合、相互に排他的な3つのフラグTPQQOSDEFAULTPERSIST、TPQQOSPERSISTENT、TPQQOSNONPERSISTENTのいずれかをctl->delivery_qosに設定しなければなりません。TPQDELIVERYQOSフラグが設定されていない場合、ターゲットのキューのデフォルトの配信ポリシーがメッセージに対するサービスの配信品質を指定します。

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

`TPQQOSDEFAULTPERSIST`

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

`TPQQOSPERSISTENT`

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

`TPQQOSNONPERSISTENT`

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

`TPQEXPTIME_ABS`

このフラグが設定されていると、メッセージに有効期限の絶対時間が適用されます。これは、キューからメッセージが削除される絶対時間です。有効期限の絶対時間は、キュー・マネージャ・プロセスが存在するマシン・クロックによって決定されます。

有効期限の絶対時間は、ctl->exp_timeに格納された値で示されます。ctl->exp_timeの値は、time(2)、mktime(3C)、またはgp_mktime(3c)によって生成された絶対時間、つまり世界協定時(UTC) 1970年1月1日00:00:00から経過した秒数に設定されなければなりません。キューへの登録操作の時間より早い絶対時間が指定されると、操作は成功しますが、メッセージはしきい値の計算の対象になりません。有効期限の時間がメッセージの使用可能時間より前の場合、使用可能時間が有効期限の切れる時間より前になるようにいずれかの時間を変更しないかぎり、メッセージをキューから取り出すことはできません。また、これらのメッセージがキューからの取出しの対象になったことがなくても、有効期限が切れるとキューから削除されます。トランザクション内でメッセージの期限が切れた場合、それによってトランザクションが異常終了することはありません。トランザクション内でキューへの登録、またはキューからの取出し中に有効期限が切れたメッセージは、トランザクションが終了した時点でキューから削除されます。メッセージの有効期限が切れたことの通知は行われません。 TPQEXPTIME_ABS、TPQEXPTIME_REL、およびTPQEXPTIME_NONEは、相互に排他的なフラグです。この3つのどのフラグも設定されていない場合、ターゲットのキューに対応しているデフォルトの有効期限の時間がメッセージに適用されます。

`TPQEXPTIME_REL`

このフラグが設定されていると、メッセージに有効期限の相対時間が適用されます。これは、メッセージがキューに到達してから、キューから削除されるまでの秒数です。有効期限の時間は、ctl->exp_timeに格納された値で示されます。

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

`TPQEXPTIME_NONE`

このフラグが設定されると、メッセージの有効期限がないことを示します。このフラグは、ターゲットのキューに関連付けられているデフォルトの有効期限のポリシーをオーバーライドします。メッセージを削除する場合は、キューから取り出すか、管理インタフェースを介して削除します。

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

また、TPQCTLの要素urcodeにユーザー戻り値を設定することができます。この値は、メッセージをキューから取り出すアプリケーションに返されます。

tpenqueue()からの出力時には、次の要素がTPQCTL構造体に設定されます。

long flags;         /* indicates which of the values  
                                * are set */  
char msgid[32];                /* ID of enqueued message */  
long diagnostic;               /* indicates reason for failure */

tpenqueue()からの出力情報を制御するflagsパラメータの有効なビットの一覧を次に示します。tpenqueue()の呼出し時にこのフラグがオンになっていると、/QサーバーTMQUEUE(5)は、構造体の対応する要素にメッセージ識別子を挿入します。tpenqueue()の呼出し時にこのフラグ・ビットをオフにしていると、TMQUEUE()によって構造体の関連要素にメッセージ識別子は設定されません。

`TPQMSGID`

このフラグが設定されていてtpenqueue()の呼出しが正常終了した場合、メッセージ識別子がctl

msgidに格納されます。メッセージ識別子の値は32バイト全体が意味を持つため、ctl

msgidに格納される値は完全に初期化されます(たとえば、NULL文字で埋めるなど)。初期化に使用される実際の埋め文字は、Oracle Tuxedo ATMI /Qコンポーネントのリリースによって異なります。

制御構造体の残りのメンバーは、tpenqueue()への入力に使用されません。

tpenqueue()の呼出しが失敗してtperrnoにTPEDIAGNOSTICが設定された場合は、失敗の原因を示す値がctldiagnosticに戻されます。戻される可能性のある値は、この後の「診断」の項で定義しています。

このパラメータがNULLである場合、入力フラグは、TPNOFLAGSとみなされ、アプリケーション・プログラムは出力情報を利用できません。

戻り値

異常終了すると、tpenqueue()は -1を返し、tperrnoを設定してエラー条件を示します。エラーでないときは、メッセージは、tpenqueue()の終了時に正しくキューに登録されます。

エラー

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

[`TPEINVAL`]

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

[`TPENOENT`]

[`TPETIME`]

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

[`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)を使用して読取りおよび書込みを排他的に行うため、キューをオープンしています。

tpenvelope(3c)

名前

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

形式

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

説明

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

デジタル署名登録リクエスト

送信プロセスがメッセージ・バッファのデジタル署名リクエストを登録する場合は、tpsign()を呼び出して明示的に登録するか、TPKEY_AUTOSIGNフラグを指定したtpkey_open()を呼び出して暗黙的に登録します。

デジタル署名

メッセージ・バッファが送信される直前に、各暗号化登録リクエストに対して、公開鍵ソフトウェアがデジタル署名を生成し、メッセージ・バッファにアタッチします。デジタル署名によって、受信プロセスはメッセージの署名者(発信元)を確認することができます。

暗号化登録リクエスト

送信プロセスがメッセージ・バッファの暗号化(封印)リクエストを登録する場合、tpseal()を呼び出して明示的に登録するか、TPKEY_AUTOENCRYPTフラグを指定したtpkey_open()を呼び出して暗黙的に登録します。

暗号化エンベロープ

公開鍵ソフトウェアは、メッセージ・バッファが送信される直前に、各暗号化登録リクエストに対して、メッセージの内容を暗号化し、暗号化エンベロープをメッセージ・バッファに添付します。暗号化エンベロープにより、受信プロセスはメッセージを復号化することができます。

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

dataは、(1)以前tpalloc()を呼び出すプロセスによって割り当てられたメッセージ・バッファ、または(2)システムによって受信プロセスに渡されたメッセージ・バッファのうち、いずれかの有効な型付きメッセージ・バッファを指している必要があります。メッセージ・バッファが自己記述型の場合、lenは無視されます(0でかまいません)。それ以外の場合、lenにはdata内のデータの長さが含まれている必要があります。

デジタル署名登録リクエスト、デジタル署名、暗号化登録リクエスト、およびメッセージ・バッファに関連付けられている暗号化エンベロープの複数のオカレンスが同時に存在することがあります。これらのオカレンスは順番に格納され、最初の項目が0位置に、以降の項目は0に続く連続する位置に格納されます。occurrence入力パラメータは、リクエストされた項目を示します。occurrenceの値が最後の項目の位置を過ぎると、tpenvelope()はTPENOENTエラー状態で異常終了します。TPENOENTが返されるまで、tpenvelope()を繰り返し呼び出してすべての項目を調べることができます。

デジタル署名登録リクエスト、暗号化登録リクエスト、または暗号化エンベロープに関連付けられたキーのハンドルは、outputkeyを介して戻されます。戻されたキー・ハンドルは、tpkey_open()を呼び出してオープンされた元のキーの個別コピーです。PRINCIPAL属性パラメータなどのキーのプロパティは、tpkey_getinfo()を呼び出して取得します。キー・ハンドルoutputkeyは、呼出し側がtpkey_close()を呼び出して解放します。

注意: outputkeyがNULLの場合、キー・ハンドルは返されません。

status出力パラメータは、デジタル署名登録リクエスト、デジタル署名、暗号化登録リクエスト、または暗号化エンベロープの状態を報告します。ステータスの値がNULLでない場合、次のいずれかの状態に設定されます。

`TPSIGN_PENDING`

対応する秘密鍵に関連付けられている署名者プリンシパルのかわりにデジタル署名がリクエストされ、このプロセスからメッセージ・バッファが伝送される際にデジタル署名が生成されます。

`TPSIGN_OK`

デジタル署名が確認されました。

`TPSIGN_TAMPERED_MESSAGE`

メッセージ・バッファの内容が変更されたため、デジタル署名が無効です。

`TPSIGN_TAMPERED_CERT`

署名者のデジタル証明書が変更されたため、デジタル署名は無効です。

`TPSIGN_REVOKED_CERT`

署名者のデジタル証明書が取り消されたため、デジタル署名が無効です。

`TPSIGN_POSTDATED`

デジタル署名のタイムスタンプが極端に先であるため、デジタル署名が無効です。

`TPSIGN_EXPIRED_CERT`

署名者のデジタル証明書の期限が切れたため、デジタル署名が無効です。

`TPSIGN_EXPIRED`

デジタル署名のタイムスタンプが古すぎるため、デジタル署名が無効です。

`TPSIGN_UNKNOWN`

署名者のデジタル証明書を発行した認証局(CA)で不明のため、デジタル署名が無効です。

`TPSEAL_PENDING`

対応する公開鍵に関連付けられている受信者プリンシパルに対して暗号化(封印)がリクエストされており、このプロセスからメッセージ・バッファが伝送されるときに暗号化されます。

`TPSEAL_OK`

暗号化エンベロープは有効です。

`TPSEAL_TAMPERED_CERT`

受信者のデジタル証明書が変更されているため、暗号化エンベロープが無効です。

`TPSEAL_REVOKED_CERT`

受信者のデジタル証明書が取り消されたため、暗号化エンベロープが無効です。

`TPSEAL_EXPIRED_CERT`

受信者のデジタル証明書の期限が切れたため、暗号化エンベロープが無効です。

`TPSEAL_UNKNOWN`

受信者のデジタル証明書を発行したCAが不明のため、暗号化エンベロープが無効です。

timestamp出力パラメータには、デジタル署名が生成されたマシンのローカル・クロックに従ったタイムスタンプが含まれています。この値の整合性は、関連付けられているデジタル署名によって保護されています。timestampによって示されるメモリー位置は、YYYYMMDDHHMMSS形式のNULLで終了する署名時間です。ここでYYYYは年、MMは月、DDは日、HHは時間、MMは分、SSは秒を表します。timestampはNULLでもかまいませんが、この場合値は返されません。暗号化(封印)にはタイムスタンプは含まれず、timestampによって示されるメモリー位置は変わりません。

flagsパラメータは、次のいずれかの値に設定できます。

TPKEY_REMOVE - occurrenceの位置にある項目が削除されます(バッファとの関連付けがなくなります)。この項目に関連する出力パラメータoutputkey、statusおよびtimestampは、項目が削除される前に取り込まれます。その後の項目は1つずつ繰り下がるため、occurrenceの番号が不連続になることはありません。
TPKEY_REMOVEALL - メッセージ・バッファに関連付けられているすべての項目が削除されます。出力パラメータ、outputkey、statusおよびtimestampは戻されません。
TPKEY_VERIFY - メッセージ・バッファに関連付けられているすべてのデジタル署名が再確認されます。再確認後に署名のステータスが変わる場合があります。たとえば、受信プロセスによってメッセージ・バッファが修正された場合、発信者の署名のステータスはTPSIGN_OKからTPSIGN_TAMPERED_MESSAGEに変わります。

戻り値

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

エラー

[`TPEINVAL`]

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

[`TPENOENT`]

このoccurrenceは存在しません。

[`TPESYSTEM`]

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

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呼出しから返され、tperrnoはTPESYSTEMに設定されます。中間のATMI呼出しを省略して引き続きtperrordetail()を呼び出すと、TPED_INVALIDCONTEXTが返されます。

`TPED_INVALID_XA_TRANSACTION`

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

`TPED_NOCLIENT`

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

`TPED_NOUNSOLHANDLER`

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

`TPED_RDMA_MSGQDAEMON`

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

リクエストの異常終了は次の呼出しによって検出されます。

tpcall/tpacall/tpgetrply/tpadmcall/tpforward
tpinit/tpappthrinit
tpbegin/tpcommit/tpscmt/tpabort/tpsuspend/tpresume
tpconnect/tpsend/tprecv/tpdiscon
tpbroadcast/tpnotify
tpenqueue/tpdequeue
tpsubscribe/tpunsubscribe/tppost

`TPED_RDMA_INVALIDQUEUE`

無効なRDMAキュー。RDMAが有効な場合、Msgq_daemon共有メモリーによって内部エラーが発生することがあります。リクエストが異常終了した後で、tperrnoではTPEOSが返されます。中間ATMI呼出しを省略して引き続きtperrordetail()を呼び出すとTPED_RDMA_INVALIDQUEUEが返されます。この異常終了を検出できる呼出しは、「TPED_RDMA_MSGQDAEMON」を参照してください。

`TPED_RDMA_NOMEMORY`

RDMAリクエストを処理するために十分な共有メモリーがありません。RDMAが有効な場合に十分な共有メモリーなしでMsgq_daemonが開始すると、内部エラーが発生することがあります。tperrnoによってTPEOSが返されます。中間のATMI呼出しを省略して引き続きtperrordetail()を呼び出すと、TPED_RDMA_NOMEMORYが返されます。この異常終了を検出できる呼出しは、「TPED_RDMA_MSGQDAEMON」を参照してください。

`TPED_SVCTIMEOUT`

サーバーは、サービスのタイムアウトにより終了しました。サービスのタイムアウトは、UBBCONFIG中のSVCTIMEOUT値によって制御されます。T_SERVERおよびT_SERVICEクラスのTA_SVCTIMEOUTはTM_MIB (5)に記載されています。このエラーよって呼出しが異常終了したときは、中間のATMI呼出しを省略して引き続きtperrordetail()を呼び出すと、TPED_SVCTIMEOUTが返されます。

`TPED_TERM`

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

エラー

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

`TPEINVAL`

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

tpexport(3c)

名前

tpexport() - 型付きメッセージ・バッファを、デジタル署名と暗号化エンベロープを含むエクスポート可能なマシン独立型の文字列表現に変換

形式

#include <atmi.h>
int tpexport(char *ibuf, long ilen, char *ostr, long *olen, 
long flags)

説明

tpexport()は、型付きメッセージ・バッファを外部化された表現に変換します。外部化された表現とは、通常は伝送直前にメッセージ・バッファに追加されるOracle Tuxedo ATMIヘッダー情報を含まないメッセージ・バッファです。

外部化された表現は、任意の通信メカニズムを介して、プロセス、マシン、Oracle Tuxedo ATMIアプリケーション間で伝送することができます。恒久的なストレージにアーカイブでき、システムの停止および再起動後も有効です。

外部化される表現には、次のものがあります。

ibufに関連付けられているすべてのデジタル署名。これらの署名は、後で、バッファがインポートされたときに確認されます。
ibufに関連付けられているすべての暗号化エンベロープ。バッファの内容は、暗号化によって保護されます。復号化のための有効な秘密鍵にアクセスできる指定された受信者だけが、後でバッファをインポートできます。

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

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

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

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

戻り値

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

エラー

[`TPEINVAL`]

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

[`TPEPERM`]

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

[`TPESYSTEM`]

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

[`TPELIMIT`]

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

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

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`]

`[TPEOS]`

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

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のアーキテクチャ」の「クライアント/サーバー・アフィニティとは」を参照してください。

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で宣言されています。

使用方法

tpgblktime(3c)

名前

tpgblktime() - 以前に設定された、1秒当たりまたは1ミリ秒当たりのブロック時間値を取得します。

形式

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

説明

tpgblktime()は、TPBLK_MILLISECONDフラグに基づいて、以前に設定された1秒当たりまたは1ミリ秒当たりのブロック時間値を取得します。tpgblktime()にブロック時間フラグ値を指定した場合、それに一致するflag値が設定されていないと戻り値0が返されます。ブロック時間フラグ値として0未満の値を指定すると、エラーが発生します。

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

`TPBLK_MILLISECOND`

このフラグは、戻りブロック時間値をミリ秒単位で設定します。SCANUNITの単位が、TUXCONFIGでミリ秒になっている場合、TPBLK_MILLISECONDフラグなしでtpgblktimeを呼び出すとエラーTPEINVALが返されます。

`TPBLK_SECOND`

このフラグは、戻りブロック時間値を秒単位で設定します。これはデフォルト動作です。

`TPBLK_NEXT`

このフラグは、あらかじめ設定されているtpsblktime(TPBLK_NEXT)呼出しのブロック時間値を返します。

`TPBLK_ALL`

このフラグは、あらかじめ設定されているtpsblktime(TPBLK_ALL)呼出しのブロック時間値を返します。

`0`

このフラグは、次のブロックしているATMIに設定されている適用可能なブロック時間値を返します。これは、前のtpsblktime()呼出しでTPBLK_NEXT、TPBLK_ALLの各フラグのブロック時間値、またはシステム全体のデフォルト・ブロック時間値が指定されていないためです。

注意: ワークステーション・クライアントがtpgblktime() 0を呼び出した場合は、システム全体のデフォルト・ブロック時間値を返すことはできません。この場合は、値0が返されます。

戻り値

成功すると、tpgblktime()は、対応するフラグ値で現在有効なブロッキング時間値を示す正数を戻します。戻り値0は、オーバーライドが有効なブロッキング時間値が現在ないことを示します。

この関数は、エラー発生時に -1を返し、tperrnoを設定してエラー条件を示します。エラーが既存のトランザクションに影響を及ぼすことはありません。

エラー

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

[`TPEINVAL`]

無効な引数が指定されました。たとえば、flags値が負の数か、複数のブロック時間フラグ値(

TPBLK_NEXT, TPBLK_ALL, TPBLK_NEXT | TPBLK_MILLISECOND, TPBLK_NEXT | TPBLK_SECOND, TPBLK_ALL | TPBLK_MILLISECOND, TPBLK_ALL | TPBLK_SECOND, or 0)

が指定されました。

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

[`TPESYSTEM`]

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

tpgetadmkey(3c)

名前

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

形式

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

説明

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

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

戻り値

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

エラー

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

移植性

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

tpgetctxt(3c)

名前

tpgetctxt() - 現在のアプリケーションの関連付けのコンテキスト識別子を取得します。

形式

#include <atmi.h>
int tpgetctxt(TPCONTEXT_T *context, long flags)

説明

tpgetctxt()は、現在のアプリケーション・コンテキストを表す識別子を取り出し、contextに入れます。この関数は、マルチスレッド環境ではスレッド単位で、非スレッド環境ではプロセス単位で動作します。

一般にスレッドは、以下の動作を行います。

tpinit()を呼び出します。
tpgetctxt()を呼び出します。
contextの値を次のように処理します。

マルチスレッドのアプリケーションの場合 - 同じプロセス内の別のスレッドにcontextの値を渡し、そのスレッドがtpsetctxt()を呼び出せるようにします。
シングルスレッドまたはマルチスレッド・アプリケーションの場合 - 指定されたコンテキストに後から切り替えられるように、このコンテキスト識別子を自身で保存します。

2番目の引数flagsは現在使用されていないので、0に設定します。

tpgetctxt()は、マルチコンテキストのアプリケーションだけでなく、シングル・コンテキストのアプリケーションでも呼び出すことができます。

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

戻り値

正常終了時には、tpgetctxt()は負数でない値を返します。コンテキストは、以下のいずれかの形式で表される現在のコンテキストIDに設定されます。

0よりも大きいコンテキストID。マルチコンテキストのアプリケーション内のコンテキストを示します。
TPSINGLECONTEXT。カレント・スレッドがTPMULTICONTEXTSフラグの指定されていないtpinit()を正常に実行したこと、またはTPMULTICONTEXTSフラグが指定されていないtpinit()を正常に実行したプロセス内でカレント・スレッドが作成されたことを示します。TPSINGLECONTEXTの値は0です。
TPNULLCONTEXT。カレント・スレッドがコンテキストに関連付けられていないことを示します。
TPINVALIDCONTEXT。カレント・スレッドのコンテキスト状態が無効であることを示します。同じコンテキスト内で別のスレッドが作業している間に、マルチコンテキスト・クライアントのスレッドがtpterm()を呼び出すと、作業中のスレッドはTPINVALIDCONTEXTコンテキストになります。TPINVALIDCONTEXTの値は -1です。

TPINVALIDCONTEXT状態のスレッドは、ほとんどのATMI関数に対する呼出しを発行できません。呼び出せる関数、または呼び出せない関数のリストについては、「C言語アプリケーション・トランザクション・モニター・インタフェースの紹介」を参照してください。

TPINVALIDCONTEXTコンテキスト状態の詳細は、「tpterm(3c)」を参照してください。

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

エラー

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

[`TPEINVAL`]

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

[`TPESYSTEM`]

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

[`TPEOS`]

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

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)」を参照してください。

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バッファに対応していない場合など)。

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_ERROR、TA_STATUSを含める形で変更されます。

`[TPEINVAL]`

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

`[TPEMIB]`

MIBと同種のリクエストが失敗しました。odataが更新され、MIB(5)で説明するエラーの原因を示すFML32のフィールドが設定され、呼出し側に返されました。

`[TPEPROTO]`

tpgetrepos()が不正に呼び出されました。指定したreposfileファイル引数は、有効なリポジトリ・ファイルではありません。

`[TPEOS]`

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

`[TPESYSTEM]`

Oracle Tuxedoシステムのエラーが発生しました。このエラーの正確な性質はuserlog()で報告されます。

移植性

このインタフェースは、Oracle Tuxedoリリース9.0またはそれ以降でしか利用できません。

ファイル

次のライブラリ・ファイルが必要です。

${TUXDIR}/lib/libtrep.a ${TUXDIR}/lib/libtrep.so.<rel> ${TUXDIR}/lib/libtrep.lib

buildclientを使用する場合は、ライブラリを手動でリンクする必要があります。この場合、-L${TUXDIR}/lib -ltrepを指定します。

tpgetrply(3c)

名前

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

形式

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

説明

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

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

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

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

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

特定のハンドルに対してtpgetrply(TPGETANY)呼出しとtpgetrply()の呼出しを同時に発行することはできません。
tpgetrply(TPGETANY)を同時に複数呼び出すこともできません。

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

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

異なるハンドルに対するtpgetrply()は、同時に呼び出すことができます。
シングル・コンテキスト内でtpgetrply (TPGETANY)を呼び出すときに、同時に別のコンテキストでtpgetrply()を呼び出すことは、TPGETANYの指定の有無にかかわらず可能です。

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

`TPGETANY`

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

`TPNOCHANGE`

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

`TPNOBLOCK`

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

`TPNOTIME`

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

`TPSIGRSTRT`

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

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

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

戻り値

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

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

エラー

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

[`TPEINVAL`]

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

[`TPEOTYPE`]

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

[`TPEBADDESC`]

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

[`TPETIME`]

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

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

[`TPESVCFAIL`]

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

[`TPESVCERR`]

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

[`TPEBLOCK`]

ブロッキング状態のため、TPNOBLOCKが指定されました。*cdはそのまま有効です。

[`TPGOTSIG`]

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

[`TPEPROTO`]

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

[`TPESYSTEM`]

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

[`TPEOS`]

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

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`]

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

tpimport(3c)

名前

tpimport() - メッセージ・バッファの外部化された表現を型付きメッセージ・バッファに変換

形式

#include <atmi.h>
int tpimport(char *istr, long ilen, char **obuf, long *olen, 
long flags)

説明

tpimport()は、メッセージ・バッファの外部化された表現を、型付きメッセージ・バッファに変換します。外部化された表現とは、通常は伝送直前にメッセージ・バッファに追加されるOracle Tuxedo ATMIヘッダー情報を含まないメッセージ・バッファです。プロセスによってtpexport()関数が呼び出され、型付きメッセージ・バッファが外部化された表現に変換されます。

istrに関連付けられているデジタル署名は、バッファがインポートされるときに確認されますが、インポート後もtpenvelope()を介して確認できます。

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

flagsにTPEX_STRINGが設定されていない場合、istrに含まれるバイナリ・データの長さはilenに含まれます。ilenが0の場合は、istrはNULL終了文字列を指していると推定され、TPEX_STRINGフラグが指定されているものと考えられます。

*obufは、(1)以前tpalloc()を呼び出すプロセスによって割り当てられたメッセージ・バッファ、または(2)システムによって受信プロセスに渡されたメッセージ・バッファのうち、いずれかの有効な型付きメッセージ・バッファを指している必要があります。バッファは結果に応じて再度割り当てられ、バッファのタイプまたはサブタイプは変更される場合があります。

*olenは、出力バッファに含まれる有効なデータの量に設定されます。olenが入力時にNULLの場合は、無視されます。

入力する外部化表現が文字列形式(base 64エンコード)の場合は、flags引数はTPEX_STRINGに設定されています。それ以外の場合、入力はilenの長さのバイナリ形式です。

戻り値

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

エラー

[`TPEINVAL`]

無効な引数が指定されました。たとえば、istrの値がNULLか、またはflagsパラメータが正しく設定されていません。

[`TPEPERM`]

パーミッション異常終了。暗号化サービス・プロバイダが、復号化に必要な秘密鍵にアクセスできませんでした。

[`TPEPROTO`]

プロトコルの異常終了が発生しました。異常終了には、istrのデータ形式が無効な場合や、デジタル署名が確認できなかった場合があります。

[`TPESYSTEM`]

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

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()が正常に終了した場合は、クライアントはサービス・リクエストを開始し、トランザクションを定義できます。

マルチスレッド・クライアントの場合、TPINVALIDCONTEXT状態のスレッドはtpinit()の呼出しを発行できません。Oracle Tuxedo ATMIアプリケーションに参加するには、マルチスレッドのワークステーション・クライアントは、たとえシングル・コンテキスト・モードで動作している場合でも、必ずTPMULTICONTEXTSフラグを設定してtpinit()関数を呼び出さなければなりません。

注意: TMNOTHREADS環境変数をyesに設定しても、tpinitのTPMULTICONTEXTSモードは正しく機能します。この環境変数をyesに設定すると、スレッドを使用しないアプリケーションでマルチスレッド処理が無効になります。

TPINFO構造体の説明

tpinit()の引数tpinfoは、TPINITタイプおよびNULLサブタイプの型付きバッファを指すポインタです。TPINITは、atmi.hヘッダー・ファイルにtypedefで定義されているバッファ・タイプです。このバッファは、tpinit()を呼び出す前にtpalloc()で割り当てられる必要があります。このバッファの解放は、tpinit()の呼出しの後、tpfree()を使用して行います。TPINIT型付きバッファ構造体は次のようなメンバーで構成されています。

char      usrname[MAXTIDENT+2]; 
char      cltname[MAXTIDENT+2];
char      passwd[MAXTIDENT+2];
char      grpname[MAXTIDENT+2];
long      flags;
long      datalen;
long      data;

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

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

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

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

TPINIT構造体のflagsフィールドにTPMULTICONTEXTSフラグを設定してtpinit()を呼び出すと、マルチコンテキスト・モードに移行します。マルチコンテキスト・モードでは、tpinit()を呼び出すたびに別のアプリケーション関連が作成されます。

アプリケーションの関連とは、プロセスとOracle Tuxedo ATMIアプリケーションを関連付けるコンテキストです。クライアントは、複数のOracle Tuxedo ATMIアプリケーションと関連を持ったり、同じアプリケーションに対して複数の関連を持つことができます。クライアントの関連付けは、すべて同じリリースのOracle Tuxedo ATMIシステムを実行するアプリケーションに対する関連付けでなければなりません。また、すべての関連付けはネイティブ・クライアントかワークステーション・クライアントのいずれかでなければなりません。

ネイティブ・クライアントの場合、新しい関連の生成元になるアプリケーションは、TUXCONFIG環境変数の値で決まります。ワークステーション・クライアントの場合、新しい関連の生成元になるアプリケーションは、WSNADDRまたはWSENVFILE環境変数の値で決まります。カレント・スレッドのコンテキストは、新しい関連に設定されます。

マルチコンテキスト・モードでは、アプリケーションはtpgetctxt()を呼び出すことにより現在のコンテキストを表すハンドルを取得し、そのハンドルをパラメータとしてtpsetctxt()に渡して、特定のスレッドまたはプロセスが動作するコンテキストを設定できます。

シングル・コンテキスト・モードとマルチコンテキスト・モードの両方を使用することはできません。アプリケーションがどちらかのモードを選択した場合、すべてのアプリケーション関連でtpterm()が呼び出されるまで、他のモードでtpinit()を呼び出すことはできません。

TPINFO構造体フィールドの説明

マルチコンテキスト・モードとシングル・コンテキスト・モードを制御するほかに、flagsの設定により、クライアント固有の通知メカニズムとシステム・アクセスのモードの両方を示すことができます。この2つの設定で、アプリケーションのデフォルト設定をオーバーライドすることができます。これらの設定でアプリケーションのデフォルトをオーバーライドできない場合、tpinit()はログ・ファイルに警告メッセージを記録し、その設定を無視して、tpinit()からの戻り時にflagsフィールドの設定をアプリケーションのデフォルト設定に戻します。クライアントへの通知の場合、flagsの値として次のものがあります。

`TPU_SIG`

シグナルによる任意通知を選択します。このフラグは、シングル・スレッド、シングル・コンテキストのアプリケーション専用です。TPMULTICONTEXTSフラグが設定されている場合、このフラグは使用できません。

`TPU_DIP`

ディップ・インによる任意通知を選択します。

`TPU_THREAD`

Oracle Tuxedo ATMIシステムが管理する独立したスレッドで、THREAD通知を選択します。このフラグは、マルチスレッドをサポートするプラットフォーム専用です。マルチスレッドをサポートしていないプラットフォームでTPU_THREADが指定されると、無効な引数とみなされ、エラーが返されてtperrnoがTPEINVALに設定されます。

`TPU_IGN`

任意通知を無視します。

一度に上記の中から1つのフラグだけを使用できます。クライアントがフラグ・フィールドを使用して通知方法を選択しない場合、アプリケーションのデフォルトの方法が、tpinit()の終了時にフラグ・フィールドに設定されます。

システム・アクセス・モードの設定の場合、flagsの値として次のものがあります。

`TPSA_FASTPATH`

システム・アクセス・モードをfastpathに設定します。

`TPSA_PROTECTED`

システム・アクセス・モードをprotectedに設定します。

一度に上記の中から1つのフラグだけを使用できます。クライアントが通知方法あるいはシステム・アクセス・モードをフラグ・フィールドで選択しない場合、tpinit()の終了時にアプリケーションのデフォルトの方法がflagsフィールドに設定されます。クライアントの通知方法とシステム・アクセス・モードの詳細は、「UBBCONFIG(5)」を参照してください。

アプリケーションがマルチスレッドまたはマルチコンテキストを使用する場合は、次のフラグを設定する必要があります。

`TPMULTICONTEXTS`

「シングル・コンテキスト・モードとマルチコンテキスト・モード」を参照してください。

datalenは、それに続くアプリケーション固有のデータの長さです。TPINIT型付きバッファのバッファ・タイプ・スイッチ・エントリは、そのバッファに対して渡される合計サイズに基づいてこのフィールドを設定します(アプリケーション・データのサイズは、合計サイズからTPINIT構造体自体のサイズを差し引き、構造体に定義されているプレースホルダーのサイズを加えたものです)。dataは、アプリケーションで定義された認証サービスに転送される可変長データ用のプレースホルダーです。これは常に、この構造体の最後の要素となります。

マクロTPINITNEEDは、目的のアプリケーション固有のデータ長を収めるのに必要とされるTPINITのバッファのサイズを判別するときに使用できます。たとえば、アプリケーション固有のデータを8バイトにしたい場合、TPINITNEED(8)は必要とされるTPINITのバッファ・サイズを返します。

アプリケーションがOracle Tuxedo ATMIシステムの認証機能を使用しない場合には、tpinfoにNULL値を使用できます。NULL引数を使用するクライアント・プロセスは、usrname、cltname、およびpasswdについてはデフォルトの設定である長さ0の文字列を取得します。フラグは設定されず、アプリケーション・データも得られません。

戻り値

異常終了すると、tpinit()は呼出しプロセスを元のコンテキストに維持したまま-1を返し、tperrnoを設定してエラー条件を示します。またtpurcode()は、AUTHSVR(5)サーバーによって返される値に設定されます。

エラー

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

[`TPEINVAL`]

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

[`TPENOENT`]

領域制限のため、クライアントはアプリケーションに参加できません。

[`TPEPERM`]

クライアントは、許可を持たないため、または正しいアプリケーション・パスワードが与えられていないために、アプリケーションに参加できません。パーミッションが与えられない理由として、アプリケーション・パスワードが無効であった場合、アプリケーション固有の認証検査にパスできない場合、あるいは禁止されている名前を使用した場合などがあります。tpurcode()は、クライアントがアプリケーションに参加できない理由を説明するため、アプリケーション固有の認証サーバーによって設定される場合があります。

[`TPEPROTO`]

tpinit()が不正に呼び出されました。たとえば、(a)呼出し元がサーバーである、(b)シングル・コンテキスト・モードでTPMULTICONTEXTSフラグが指定されている、または(c)マルチコンテキスト・モードでTPMULTICONTEXTSフラグが指定されていない場合があります。

[`TPESYSTEM`]

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

[`TPEOS`]

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

相互運用性

tpchkauth()、およびtpinit()のTPINIT型付きバッファ引数に対するNULL以外の値は、リリース4.2以降を実行しているサイトでのみ使用できます。

移植性

tpinit(3c)に記述されているインタフェースは、UNIX、Windows、およびMS-DOSオペレーティング・システム上でサポートされています。ただし、シグナル・ベースの通知方法は、16ビットのWindowsおよびMS-DOSではサポートされていません。tpinit()の実行時にこの通知方法が選択されると、userlog()メッセージが生成され、通知方式は自動的にディップインに設定されます。

環境変数

`TUXCONFIG`

ネイティブ・クライアントによって起動されたときにtpinit()内で使用されます。この変数は、クライアントの接続先になるアプリケーションを示します。なお、この環境変数は、tpinit()が呼び出されたときのみ参照されます。これ以降の呼出しには、アプリケーション・コンテキストが使用されます。

`WSENVFILE`

ワークステーション・クライアントが呼び出すときにtpinit()内で使用されます。この変数には、環境変数の設定内容を含むファイルを指定しますが、この設定は呼出し側の環境で行うようにします。ワークステーション・クライアントに必要とされる環境変数の設定に関する詳細は、「compilation(5)」を参照してください。このファイルは、tpinit()が呼び出されるとき(その前ではなく)にのみ処理されます。

`WSNADDR`

ワークステーション・クライアントが呼び出すときにtpinit()内で使用されます。これは、アプリケーションをアクセスするときに使用されるワークステーション・リスナー・プロセスのネットワーク・アドレスを示します。この変数はワークステーション・クライアントの場合は必須ですが、ネイティブ・クライアントの場合は無視されます。

TCP/IPアドレスは、//host.name:port_number//#.#.#.#:port_numberの形式で指定できます。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:30000でWSFRANGEが200の場合、このLMIDからアウトバウンド接続を試みるネイティブ・プロセスはすべて、mymachine.oracle.com 30000から30200の間のポートをバインドします。この変数を設定しないと、空の文字列が使用され、オペレーティング・システムはローカル・ポートをランダムに選択します。

`WSFRANGE`

ワークステーション・クライアントが呼び出すときにtpinit()内で使用されます。この変数は、ワークステーション・クライアント・プロセスが、アウトバウンド接続を行う前にバインドを試みるTCP/IPポートの範囲を指定します。WSFADDRパラメータは、範囲のベース・アドレスを指定します。たとえば、WSFADDRパラメータが//mymachine.oracle.com:30000に設定され、WSFRANGEが200に設定されると、このLMIDからアウトバウンド接続を試みるネイティブ・プロセスはすべて、mymachine.oracle.com 30000から30200の間のポートにバインドします。有効範囲は1から65535までです。デフォルト値は1です。

`WSDEVICE`

ワークステーション・クライアントが呼び出すときにtpinit()内で使用されます。これは、ネットワークのアクセス時に使用するデバイス名を示します。この変数はワークステーション・クライアントが使用し、ネイティブ・クライアントの場合は無視されます。なお、ソケットやNetBIOSなどトランスポート・レベルのネットワーク・インタフェースはデバイス名を必要としません。このようなインタフェースによってサポートされているワークステーション・クライアントは、WSDEVICEを指定する必要はありません。

`WSTYPE`

ワークステーション・クライアントが呼び出すときにtpinit()内から使用され、ネイティブ・サイトとの間でエンコード/デコードの責任範囲について調整を行います。この変数はワークステーション・クライアントの場合は省略可能で、ネイティブ・クライアントの場合は無視されます。

`WSRPLYMAX`

tpinit()によって使用され、アプリケーションの応答をファイルに格納する前にバッファに入れるために使用するコア・メモリーの最大サイズを設定します。このパラメータのデフォルトは、256,000バイトです。詳細は、プログラミング・ドキュメントを参照してください。

`TMMINENCRYPTBITS`

Oracle Tuxedo ATMIシステムに接続するのに必要な暗号化の最小レベルを確立するときに使用されます。「0」は暗号化を行わないことを示します。「56」と「128」は暗号化キーの長さをビット単位で指定します。また後方互換のため、40ビットのリンク・レベルの暗号化も使用できます。ここで指定された最低レベルの暗号化が行われないと、リンクの確立は失敗します。デフォルト値は0です。

`TMMAXENCRYPTBITS`

Oracle Tuxedo ATMIシステムに接続するときに、このレベルまで暗号化を調整するのに使用されます。「0」は暗号化を行わないことを示します。「56」と「128」は暗号化キーの長さをビット単位で指定します。また後方互換のため、40ビットのリンク・レベルの暗号化も使用できます。デフォルト値は128です。

警告

シグナル・ベースの通知は、マルチコンテキスト・モードでは使用できません。また、シグナルの制約によって、クライアントがシグナル・ベースの通知を選択しても、システムがそれを使用できない場合があります。このような場合、システムは、選択されたクライアントに対する通知をディップ・インに切り替えることを示すログ・メッセージを生成し、クライアントはそれ以降ディップ・イン通知によって通知されます(通知方法の詳細については、「UBBCONFIG(5)」のRESOURCESセクションのNOTIFYパラメータの説明を参照してください)。

ネイティブ・クライアントは、アプリケーション管理者として実行しています。
ワークステーション・クライアントは、アプリケーション管理者として実行している必要はありません。

アプリケーション管理者のIDは、アプリケーション構成の一部として識別されます。

クライアントにシグナル・ベースの通知を選択すると、ある種のATMI呼出しは正常に実行できないことがあります。このとき、TPSIGRSTRTの指定がない場合、非請求メッセージを受け取るため、TPGOTSIGが返されます。

tpkey_close(3c)

名前

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

形式

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

説明

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

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

tpkey_open()の明示的呼出し
tpenvelope()からの出力

tpkey_close()を呼び出してキー・リソースを解放するのは、アプリケーションの役目です。あるプロセスがキーをクローズすると、同じプロセスがそのキー・ハンドルを使用してデジタル署名や暗号化のメッセージ・バッファを登録することはできなくなります。プロセスがTPKEY_AUTOSIGNまたはTPKEY_AUTOENCRYPTフラグを指定したtpkey_open()でキーをオープンした場合、キーをクローズした後の通信操作にはそのキー・ハンドルは適用されません。

ただし、キーをクローズした後でも、そのキー・ハンドルは、クローズ前に登録された関連署名リクエストや暗号化リクエストに対しては有効です。クローズしたキーに関連付けられている最後のバッファが解放されるか上書きされると、そのキーに属していたリソースは解放されます。

引数flagsは使用されません。この引数は将来の用途のために予約されており、0に設定します。

戻り値

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

エラー

[`TPEINVAL`]

無効な引数が指定されました。たとえば、値hKeyが無効です。

[`TPESYSTEM`]

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

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

名前

tpkey_open() - デジタル署名の生成、メッセージの暗号化、またはメッセージの復号化のためのキー・ハンドルのオープン

形式

#include <atmi.h>
int tpkey_open(TPKEY *hKey, char *principal_name, char *location, char *identity_proof, long proof_len, long flags)

説明

tpkey_open()は、呼出し側のプロセスからキー・ハンドルを使用できるようにします。キー・ハンドルは、特定のプリンシパルのキーおよびそれに関連付けられている情報を表します。

キーは、以下に示す目的のうち、1つまたは複数の目的に使用できます。

デジタル署名の生成。デジタル署名は、型付きメッセージ・バッファの内容を保護し、特定のプリンシパルがそのメッセージを発信したことを証明します。(プリンシパルは、個人またはプロセスのいずれの場合もあります)このタイプのキーは秘密鍵であり、キーの所有者のみが使用できます。

プリンシパル名とTPKEY_SIGNATUREまたはTPKEY_AUTOSIGNフラグを設定してtpkey_open()を呼び出すと、そのプリンシパルの秘密鍵とデジタル証明書に対するハンドルが戻されます。

デジタル署名の検証。これによって、型付きメッセージ・バッファの内容が変更されていないこと、また特定のプリンシパルによってメッセージが送信されたことが証明されます。

署名の検証にはtpkey_open()を呼び出す必要はありません。この確認プロセスでは、デジタル署名付きメッセージが添付されたデジタル証明書に指定されている公開鍵を使用して署名が検証されます。

特定のプリンシパルに宛てたメッセージ・バッファの暗号化。このタイプのキーは、プリンシパルの公開鍵およびデジタル証明書にアクセスするすべてのプロセスで使用できます。

プリンシパル名とTPKEY_ENCRYPTまたはTPKEY_AUTOENCRYPTフラグを設定してtpkey_open()を呼び出すと、プリンシパルのデジタル証明書を介して、プリンシパルの公開鍵に対するハンドルが戻されます。

特定のプリンシパルに送られたメッセージ・バッファの復号化。このタイプのキーは秘密鍵であり、キーの所有者のみが使用できます。

プリンシパルの名前とTPKEY_DECRYPTフラグを設定してtpkey_open()を呼び出すと、プリンシパルの秘密鍵とデジタル証明書に対するハンドルが戻されます。

tpkey_open()によって返されたキー・ハンドルは*hKeyに格納されますが、値にNULLを使用することはできません。

principal_name入力パラメータは、キーの所有者のIDを指定します。principal_nameの値がNULLポインタまたは空の文字列の場合、デフォルトIDが使用されます。デフォルトIDは、現在のログイン・セッション、現在のオペレーティング・システム・アカウント、またはローカル・ハードウェア・デバイスなどの別の属性に基づいて決定されます。

キーのファイル位置は、locationパラメータに渡されます。基本となるキー管理プロバイダが位置を示すパラメータを必要としない場合、このパラメータの値はNULLを使用できます。

principal_nameのIDを認証するには、パスワードやパス・フレーズなどの証明資料が必要になります。証明資料が必要な場合は、identity_proofによって資料を参照する必要があります。証明資料が不要な場合、このパラメータの値はNULLでかまいません。

証明資料の長さ(バイト)は、proof_lenで指定します。proof_lenが0の場合、identity_proofはNULLで終了する文字列とみなされます。

キーの操作モードに必要なキー・アクセスのタイプは、flagsパラメータで指定します。

`TPKEY_SIGNATURE`:

この秘密鍵はデジタル署名を生成します。

`TPKEY_AUTOSIGN`:

このプロセスがメッセージ・バッファを伝送すると、公開鍵ソフトウェアが署名者の秘密鍵を使用してデジタル署名を生成し、そのデジタル署名をバッファに添付します。TPKEY_SIGNATUREが暗黙的に指定されています。

`TPKEY_ENCRYPT`:

この公開鍵は、暗号化されたメッセージの受信者を識別します。

`TPKEY_AUTOENCRYPT`:

このプロセスによってメッセージ・バッファが伝送されると、公開鍵ソフトウェアがメッセージの内容を暗号化し、受信者の公開鍵を使用して暗号化エンベロープを生成し、その暗号化エンベロープをバッファに添付します。TPKEY_ENCRYPTが暗黙的に指定されています。

`TPKEY_DECRYPT`:

この秘密鍵は復号化に使用できます。

これらのフラグは1つまたは複数を組み合せて使用することができます。キーを暗号化のみに使用する場合(TPKEY_ENCRYPT)、identity_proofは必要ないのでNULLに設定できます。

戻り値

正常終了すると、*hKeyはこのキーを表す値に設定され、tpsign()やtpseal()などの関数で使用できるようになります。

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

エラー

[`TPEINVAL`]

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

[`TPEPERM`]

パーミッション異常終了。暗号サービス・プロバイダは、指定された証明情報と現在の環境で、このプリンシパルの秘密鍵にアクセスできませんでした。

[`TPESYSTEM`]

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

tpkey_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`]

リクエストされた属性は、キーの暗号サービス・プロバイダによって認識されません。

tpnotify(3c)

名前

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

形式

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

説明

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

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

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

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

`TPACK`

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

`TPNOBLOCK`

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

`TPNOTIME`

`TPSIGRSTRT`

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

TPACKフラグを設定しないかぎり、tpnotify()は、メッセージがクライアントに送られるまで待機していません。

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

戻り値

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

エラー

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

[`TPEINVAL`]

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

[`TPENOENT`]

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

[`TPETIME`]

ブロッキング・タイムアウトが発生し、TPNOBLOCKとTPNOTIMEのいずれも指定されなかったか、TPACKは設定されたが承認が受信されず、TPNOTIMEが指定されませんでした。ブロッキング・タイムアウトは、TPNOBLOCKまたはTPNOTIMEが指定されている場合は発生しません。

[`TPEBLOCK`]

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

[`TPGOTSIG`]

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

[`TPEPROTO`]

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

[`TPESYSTEM`]

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

[`TPEOS`]

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

[`TPERELEASE`]

TPACKが指定され、ターゲットは承認プロトコルをサポートしないOracle Tuxedoの前のリリースからのクライアントです。

tpopen(3c)

名前

tpopen() - リソース・マネージャを開くルーチン

形式

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

説明

tpopen()は、呼出し側がリンクされるリソース・マネージャをオープンします。呼出し側には、多くとも1つのリソース・マネージャしかリンクできません。この関数はリソース・マネージャ固有のopen()呼出しのかわりに使用するもので、これにより、移植性を損なう可能性のある呼出しをサービス・ルーチンからなくすことができます。リソース・マネージャは初期化の内容がそれぞれで異なるため、個々のリソース・マネージャをオープンするために必要な情報を構成ファイルに記述します。

リソース・マネージャがすでにオープンされている場合(すなわち、tpopen()を2回以上呼び出した場合)、何も処理は行われず、正常終了を示すコードが返されます。

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

現在のサーバーが-Mオプションを指定して構築されている場合、tpopenは、現在のサーバー・グループに関してAUTO=Yに設定されていて、対応するコンテキスト・フィールドが設定されている、UBBCONFIG (5)の*RMSセクションに記述されているすべてのRMをオープンします。

RMのオープンが失敗すると、tpopenはTPERMERRを戻します。

戻り値

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

エラー

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

[`TPERMERR`]

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

[`TPEPROTO`]

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

[`TPESYSTEM`]

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

[`TPEOS`]

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

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()に渡されるctlflagsパラメータでTPEVTRANビットの設定を使用したサービス・ルーチンおよび安定ストレージ上のキューのサブスクリプションだけにディスパッチします。イベント・ブローカは、クライアントへの通知、およびtpsubscribe()に渡されるctlflagsパラメータでTPEVTRANビットの設定を使用しなかったサービス・ルーチンおよび安定ストレージ上のキューにあるサブスクリプションのディスパッチも行いますが、これはポスト元プロセスのトランザクションの一部としてではありません。

ポスト元がトランザクションの外部にある場合、イベントに関連付けられているサービスが失敗すると、tppost()は肯定応答のない一方向のポストになります。このような状況は、イベント用にTPEVTRANが設定されている場合でも起こります(この設定には、tpsubscribe()に渡されるctlflagsパラメータを使用します)。ポスト元がトランザクション内にある場合は、イベントに関連するサービスが失敗すると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に対するフィルタ・ルールの評価が成功したサブスクリプションへのポストです)。tperrnoがTPESVCFAILに設定されて戻った場合は、tpurcode()には、eventnameのかわりにイベント・ブローカによってディスパッチされたトランザクション以外のイベント通知の数が設定されています。

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

エラー

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

[`TPEINVAL`]

無効な引数(たとえば、eventnameにNULL)が指定されました。

[`TPENOENT`]

Oracle Tuxedoのユーザー・イベント・ブローカにアクセスできません。

[`TPETRAN`]

呼出し側がトランザクション・モードにあり、TPNOTRANが設定されず、トランザクション伝達をサポートしないイベント・ブローカにtppost()がコンタクトしました。つまり、TMUSREVT(5)が、トランザクションをサポートするOracle Tuxedo ATMIグループで実行されていません。

[`TPETIME`]

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

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

[`TPESVCFAIL`]

イベント・ブローカが呼出し側のトランザクションに関して、トランザクション・イベントをサービス・ルーチンまたは安定ストレージ上のキューに通知する際に、エラーが発生しました。呼出し側の現在のトランザクションは、中断のみとしてマークされます。このエラーが返された場合、tpurcode()には、eventnameの代わりにイベント・ブローカがディスパッチするトランザクション以外のイベント通知の数が設定されています。トランザクションのポスティングは、トランザクションの完了と共にその効果がなくなるため、カウントされません。なお、トランザクションがタイムアウトしないかぎり、通信はトランザクションが異常終了するまで継続され、呼出し側のトランザクションのためになされた作業はトランザクションが完了する時点で異常終了されます(つまり、以降のやりとりで何らかの結果が得られる場合には、TPNOTRANを設定しておく必要があります)。

[`TPEBLOCK`]

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

[`TPGOTSIG`]

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

[`TPEPROTO`]

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

[`TPESYSTEM`]

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

[`TPEOS`]

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

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()で解放することはできません)。

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 は、バッファのサイズを含みます。FMLとFML32バッファは、通常最小サイズ4096バイトを確保します。したがって、応答が4096バイトより大きい場合は、バッファ・サイズは返されるデータを入れるのに十分な大きさに拡大します。

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

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

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

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

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

`TPNOCHANGE`

`TPNOBLOCK`

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

`TPNOTIME`

`TPSIGRSTRT`

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

記述子cdに対してイベントが存在すると、tprecv()は終了し、tperrnoをTPEEVENTに設定します。イベントのタイプがreventで返されます。TPEV_SVCSUCC、TPEV_SVCFAILおよびTPEV_SENDONLYイベントとともに、データを受け取ることができます。tprecv()の有効なイベントを次に示します。

`TPEV_DISCONIMM`

会話の従属側が受け取るこのイベントは、その会話の起動元がtpdiscon()により即時切断要求を出したこと、あるいは接続をオープンにしたままでtpreturn()、tpcommit()、またはtpabort()を出したことを示します。このイベントは、通信エラー(サーバー、マシン、ネットワークの障害など)により接続が切断されたときにも起動元またはその従属側に返されます。これは即時切断通知(つまり、正常ではなく中途の終了)であるため、処理途中のデータは失われます。2つのプログラムが同じトランザクションに参加していた場合、そのトランザクションは中断のみとしてマークされます。この接続に使用された記述子は無効になります。

`TPEV_SENDONLY`

接続の他方の側にあるプログラムは、接続の制御を放棄しました。このイベントの受信側はデータを送信することはできますが、制御権を放棄するまではデータを受信することはできません。

`TPEV_SVCERR`

このイベントは、会話の起動元が受け取るもので、会話の従属側がtpreturn()を出したことを示します。tpreturn()に、サービスが正しく応答を返すことができないようなエラーが発生しています。たとえば、不正な引数がtpreturn()に渡されていたり、tpreturn()が、そのサービスが別の従属側にオープン接続を持っている最中に呼び出されている可能性があります。このイベントの性質上、アプリケーションが定義したデータや戻りコードは返されません。この接続は切断され、記述子は無効になります。このイベントがcd受信側のトランザクションの一部として発生した場合は、トランザクションは中断のみとしてマークされます。

`TPEV_SVCFAIL`

このイベントは、接続の起動元が受け取るもので、会話の他方の側の従属サービスが、アプリケーションで定義されているように正常に終了しなかったことを示します(つまり、TPFAILまたはTPEXITとともにtpreturn()が呼び出されています)。従属サービスは、tpreturn()が呼び出されたときにこの接続の制御下にあった場合は、アプリケーション定義の戻りコードおよび型付きバッファを接続の起動元に渡すことができます。サービス・ルーチンの終了処理の一部として、サーバーはこの接続を切断しています。このため、cdは無効な記述子となります。このイベントが、受信側のトランザクションの一部として発生すると、そのトランザクションは中断のみとしてマークされます。

`TPEV_SVCSUCC`

このイベントは、会話の起動元が受け取るもので、接続の他方の側の従属サービスがアプリケーションで定義されているように正常に終了したことを示します(すなわち、TPSUCCESSとともにtpreturn()が呼び出されています)。サービス・ルーチンの終了処理の一部として、サーバーはこの接続を切断しています。このため、cdは無効な記述子となります。受信側がトランザクション・モードにいる場合、そのトランザクションをコミットする(それが起動元でもある場合)か、中途終了して、サーバーが行った作業内容(トランザクション・モードである場合)をコミットあるいは中途終了させます。

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

戻り値

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

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

エラー

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

[`TPEINVAL`]

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

[`TPEOTYPE`]

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

[`TPEBADDESC`]

cdが無効です。

[`TPETIME`]

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

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

[`TPEEVENT`]

イベントが発生し、そのタイプがreventに記録されます。[TPETIME]と、[TPEEVENT]リターン・コードには関連があります。トランザクション・モードにおいては、会話の受信側がtprecvにブロックされていて、送信側がtpabort()を出した場合、受信側は[TPEVENT]リターン・コードをTPEV_DISCONIMMのイベントと共に取得します。ただし、受信側がtprecv()を呼び出す前に、送信側がtpabort()を出した場合は、そのトランザクションはすでにGTTから削除されてしまっているので、tprecv()は異常終了し、[TPETIME]コードが返されます。

[`TPEBLOCK`]

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

[`TPGOTSIG`]

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

[`TPEPROTO`]

tprecv()が不正なコンテキストで呼び出されました(たとえば、呼出しプログラムがデータの送信のみを行えるよう接続が確立されている場合など)。

[`TPESYSTEM`]

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

[`TPEOS`]

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

使用方法

サーバーは、tpreturn()を呼び出すとき、アプリケーション定義の戻りコードおよび型付きバッファを渡すことができます。戻りコードはグローバル変数tpurcodeで使用され、バッファはdataで使用されます。

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)は、そのトランザクションを停止させたワークステーション・クライアントのハンドラと同じ論理マシン上に存在している必要があります。

tpreturn(3c)

名前

tpreturn() - Oracle Tuxedo ATMIシステム・サービス・ルーチンからの復帰

形式

void tpreturn(int rval, long rcode, char *data, long len, long \flags)

説明

tpreturn()は、サービス・ルーチンが完了したことを示します。tpreturn()は、C言語のreturn文と同様に機能します(つまり、tpreturn()が呼び出されると、サービス・ルーチンはOracle Tuxedo ATMIシステム・ディスパッチャに戻ります)。Oracle Tuxedo ATMIシステム・ディスパッチャに制御を適切に戻すためには、ディスパッチされたサービス・ルーチン内からtpreturn()を呼び出すことを推奨します。

tpreturn()はサービスの応答メッセージを送信するときに使用します。応答を受け取るプログラムがtpcall()、tpgetrply()またはtprecv()で待機している場合、tpreturn()の呼出しが成功した時点で、受信側のバッファに応答が入ります。

会話型サービスの場合、tpreturn()は接続自体も切断します。したがって、サービス・ルーチンは、tpdiscon()を直接呼び出すことができません。正常な結果を保証するためには、会話型サービスに接続しているプログラムはtpdiscon()を呼び出してはなりません。そのようなプログラムは、会話型サービスが完了したという通知を待たなければなりません(たとえば、そのプログラムは、tpreturn()によって送信されるTPEV_SVCSUCCまたはTPEV_SVCFAILなどのイベントのちの1つを待つ必要があります)。

また、サービス・ルーチンがトランザクション・モードにあった場合には、tpreturn()はトランザクションのサービス部分を、そのトランザクションの完了時点でコミットまたは中断できる状態にします。サービスは同じトランザクションの一部として複数回呼び出すことができるため、tpcommit()またはtpabort()がそのトランザクションの開始プロセスによって呼び出されるまでは、完全にコミットあるいは中断させる必要は必ずしもありません。

tpreturn()は、該当サービス・ルーチンが出したサービス・リクエストから期待されるすべての応答を受け取った後、呼び出すようにしてください。そうしない場合は、サービスの性質によって決まりますが、TPESVCERRステータスまたはTPEV_SVCERRイベントのいずれかが、サービス・ルーチンとの接続を開始したプログラムに返ります。受け取られなかった応答は、受信処理の後、通信マネージャによって自動的に取り除かれます。また、これらの応答に対応する記述子は無効になります。

tpreturn()は、サービスが出したすべての接続をクローズした後、呼び出される必要があります。そうしない場合はサービスの性質によって決まりますが、TPESVCERRまたはTPEV_SVCERRイベントのいずれかが、サービス・ルーチンとの通信を開始したプログラムに返されます。また、即時切断イベント(つまり、TPEV_DISCONIMM)が、オープンしているすべての接続を通して従属側に送信されます。

会話型サービスは、自分で開始しなかったオープン接続を1つだけ備えているため、通信マネージャは、送信すべき記述子データ(およびイベント)を認識しています。このため、記述子は、tpreturn()に渡されません。

次に、tpreturn()の引数について説明します。rvalは次のいずれかに設定できます。

`TPSUCCESS`

サービスは正常に終了しました。データが存在する場合、そのデータは送信されます(戻り処理の失敗の場合を除く)。呼出し側がトランザクション・モードにある場合には、tpreturn()は、そのトランザクションの呼出し側の部分を、トランザクションが最終的にコミットすべき時点でコミットできるような状態にします。tpreturn()を呼び出しても、必ずしもトランザクション全体が終了することにはつながりません。また、呼出し側が正常終了を示したとしても、未終了の応答またはオープン接続がある場合、該当サービス内で行われた作業が原因でトランザクションがロールバックのみとしてマークされた場合、失敗メッセージが送信されます(つまり、応答の受信側はTPESVCERR指示あるいはTPEV_SVCERRイベントを受け取ります)。サービス・ルーチンの処理中になんらかの理由でトランザクションがロールバックのみとしてマークされると、rvalがTPFAILに設定されます。TPSUCCESSが会話型サービスに対して指定されると、TPEV_SVCSUCCイベントが生成されます。

`TPFAIL`

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

`TPEXIT`

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

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

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

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

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

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

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

呼出しが行われたときに接続がすでに切断されていた場合(呼出し側がその接続上でTPEV_DISCONIMMを受け取っていた場合)、この呼出しは単にサービス・ルーチンを終了させ、現在のトランザクション(もしあれば)をアボートさせます。
呼出し側が接続の制御権をもたない場合、上記のように、TPEV_SVCFAILまたはTPEV_SVCERRが接続の要求元に送られます。発信元が受信したイベントの種類にかかわらず、データは送信されません。ただし、発信元がTPEV_SVCFAILイベントを受信した場合は、発信元のtpurcode()変数にリターン・コードが設定されます。

戻り値

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

エラー

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

UBBCONFIGファイル中のSVCTIMEOUTか、TM_MIB中のTA_SVCTIMEOUTが0でない場合にサービスのタイムアウトが発生すると、TPEV_SVCERRが返されます。

tperrordetail()とtpstrerrordetail()を使用すると、現在のスレッドの中で呼び出された最新のOracle Tuxedo ATMIシステムのルーチンが出したエラーに関して、追加的な情報を取得できます。エラーが起きると、tperrordetail()は数値を返しますが、この数値をtrstrerrordetail()への引数として利用することで、エラーの詳細に関するテキストを受け取ることができます。

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]`

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

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]`

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

tprmopen(3c)

名前

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

形式

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

説明

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

現在の最初のパラメータrmnameは、このリソース・マネージャ・グループのUBBCONFIGに構成されている値である必要があります。flagsは0である必要があります。

戻り値

失敗すると、tprmopen()は-1を戻し、tperrnoを設定してエラー条件を示します。

エラー

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

`[TPERMERR]`

`[TPEPROTO]`

tprmopen()が不正なコンテキストで呼び出されました(たとえば、buildserverによって-Mオプションを使用して構築されていないサーバーによって呼び出された場合や、クライアント・プロセスによって呼び出された場合)。

`[TPEINVAL]`

無効なパラメータが指定されました(たとえば、フラグの値が0でない、rmnameがNULLである、または複数のRMのサーバー・グループに関連付けられているUBBCONFIGの*RMSセクションに有効なリソース・マネージャ名が構成されていないなど)。

もう1つのケースとして、このRMがRMのCAE仕様でない場合があります。

`[TPESYSTEM]`

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

`[TPEOS]`

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

tprmstart(3c)

名前

tprmstart() - MRMサーバーの指定されたRMのトランザクション・ブランチのかわりに作業を開始するルーチン

形式

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

説明

tprmstart()は、トランザクション・ブランチのかわりにこのトランザクション作業単位に参加することをオープンされたRMに通知します。現在のRMがすでに開始状態にある場合、このルーチンは操作をスキップします。現在のRMがまだオープンしていない場合は、tprmstart()は何も実行せず、呼出し側にエラーを戻します。

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]`

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

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

)が指定されました。

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

[`TPERELEASE`]

以前のリリースのTuxedoで実行されているワークステーション・ハンドラにアタッチされたクライアントでtpsblktime()が呼び出されました。

[`TPESYSTEM`]

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

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)」を参照してください。

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`]

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

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`]

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

[`TPEBADDESC`]

cdが無効です。

[`TPETIME`]

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

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

[`TPEEVENT`]

イベントが発生しました。このエラーが発生すると、dataは送られません。イベントのタイプは、reventに戻されます。

[`TPEBLOCK`]

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

[`TPGOTSIG`]

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

[`TPEPROTO`]

tpsend()が不正なコンテキストで呼び出されました(たとえば、呼出し側がデータの受信しかできないように、接続が確立された場合など)。

[`TPESYSTEM`]

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

[`TPEOS`]

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

tpservice(3c)

名前

tpservice() - サービス・ルーチンのテンプレート

形式

#include <atmi.h>                   /* C interface */  
void tpservice(TPSVCINFO *svcinfo)  /* C++ interface - must have
                                     * C linkage */  
extern “C” void tpservice(TPSVCINFO *svcinfo)

説明

tpservice()は、サービス・ルーチン作成時のテンプレートです。このテンプレートは、ルーチンtpcall()、tpacall()、またはtpforward()を介してリクエストを受け取るサービス、およびルーチンtpconnect()、tpsend()、またはtprecv()を介して通信を行うサービスに使用できます。

tpcall()またはtpacall()を介して行われるリクエストを処理するサービス・ルーチンは、1つだけ着信メッセージを受け取り(svcinfoのdata要素内に)、1つだけ応答を送る(tpreturn()を使用してサービス・ルーチンを終了するとき)ことができます。

一方、会話サービスは、最大1つの着信メッセージとオープン接続の参照手段とともに、接続リクエストにより呼び出されます。会話型サービス・ルーチンが呼び出されると、接続元プログラムあるいは会話型サービスはアプリケーション側で定義されたようにデータの送信および受信を行うことができます。この接続は半二重方式で確立されます。つまり、接続の一方の側は、他方から明示的に制御を渡されるまで、会話を制御することはできません(データを送信できません)。

トランザクションとの関連で言えば、サービス・ルーチンはトランザクション・モードで呼び出されると、1つのトランザクションにしか参加できません。サービス・ルーチン作成者側から見るかぎり、トランザクションはサービス・ルーチンから返った時点で終了します。サービス・ルーチンは、トランザクション・モードで呼び出されなかった場合、tpbegin()、tpcommit()およびtpabort()を使用して必要な回数だけトランザクションを起動できます。ただし、トランザクションの終了にはtpreturn()を使用しません。したがって、サービス・ルーチン内から起動された未終了のトランザクションについて、tpreturn()を呼び出すと、エラーになります。

サービス・ルーチンは、1つの引数、つまりsvcinfoを使用して呼び出します。この引数は、サービス情報が定義された構造体を指すポインタです。この構造体には、次のメンバーが含まれます。

char        name[128];
char        *data;
long        len;  
long        flags;  
int         cd;  
long        appkey;  
CLIENTID     cltid;

nameには、リクエスタがサービスの呼出しに使用したサービス名を指定します。

サービス・ルーチンに入った時点で設定されるflagsは、サービス・ルーチンが注目する必要のある属性を示します。flagsに指定できる値は、次のとおりです。

`TPCONV`

会話型の接続リクエストが受け入れられたときに、その接続記述子がcdに設定されることを示します。このフラグが設定されていなければ、これはリクエスト/レスポンス型サービスであり、cdは無効です。

`TPTRAN`

サービス・ルーチンはトランザクション・モードにあります。

`TPNOREPLY`

呼出し側は応答を期待していません。このオプションは、TPCONVが設定されている場合には設定されません。

`TPSENDONLY`

サービスは、接続を介してデータの送信のみ可能で、接続の他方の側のプロセスはデータの受信しかできないよう呼び出されます。このフラグはTPRECVONLYと相互に排他的で、TPCONVが設定されているときにしか設定できません。

`TPRECVONLY`

サービスは、接続を介してデータの受信のみ可能で、接続の他方の側のプロセスはデータの送信しかできないよう呼び出されます。このフラグはTPSENDONLYと相互に排他的で、TPCONVが設定されているときにしか設定できません。

dataはリクエスト・メッセージのデータ部を指し、lenはデータの長さです。dataによって指されたバッファは、通信マネージャでtpalloc()により割り当てられたものです。このバッファのサイズは、ユーザーがtprealloc()を使用して大きくすることができます。ただし、これをユーザーが解放することはできません。このバッファは、サービス終了時にtpreturn()またはtpforward()に渡すようにしてください。異なるバッファをこれらのルーチンに渡すと、そのバッファはそれらによって解放されてしまいます。なお、dataによって指されるバッファは、このバッファがtpreturn()またはtpforward()に渡されない場合でも、次に出されたサービス・リクエストによって変更されてしまいます。dataは、リクエストとともにデータが渡されなかった場合にはNULLになります。この場合、lenは0になります。

TPCONVをflagsに設定する場合、cdに接続記述子を指定しますが、これはこの会話を開始したプログラムとのコミュニケーションを行うためにtpsend()およびtprecv()とともに使用します。

appkeyは、アプリケーション側で定義した認証サービスが要求クライアントに割り当てるアプリケーション・キーに設定します。このキー値は、このサービス・ルーチンのこの呼出し中になされたあらゆるサービス・リクエストとともに渡されます。アプリケーション認証サービスを通らないクライアントを起動する場合には、appkeyの値は -1になります。

cltidは、このサービス要求に対応する元のクライアントを示すユニークなクライアント識別子です。この構造体はatmi.hにのみ、アプリケーションが利用できるよう定義されているので、必要によりアプリケーション・サーバー間でクライアント識別子をやりとりすることができます。このため、以下に定義されているフィールドの意味は明記されていません。アプリケーション側ではCLIENTID構造体の内容を操作しないようにしてください。内容を操作してしまうと、この構造体自体が無効になってしまいます。CLIENTID構造体には、次のようなメンバーが含まれます。

long clientdata[4];

C++では、サービス関数にCリンケージが必要なことに注意してください。これは、関数を'extern "C"'と宣言することで行うことができます。

戻り値

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

エラー

tpsetctxt(3c)

名前

tpsetctxt() - 現在のアプリケーション関連に対するコンテキスト識別子の設定

形式

#include <atmi.h>
int tpsetctxt(TPCONTEXT_T context, long flags)

説明

tpsetctxt()は、現在のスレッドが動作するコンテキストを定義します。この関数は、マルチスレッド環境ではスレッド単位で、非スレッド環境ではプロセス単位で動作します。

次にこのスレッドでOracle Tuxedo ATMIが呼び出されると、コンテキストが示すアプリケーションが参照されます。コンテキストは、同一プロセス内のスレッドでtpgetctxt()の呼出しを発行することによって提供されます。contextの値がTPNULLCONTEXTの場合、現在のスレッドはどのOracle Tuxedo ATMIコンテキストにも関連付けられません。

マルチコンテキスト・モードで動作しているプロセスの各スレッドでは、次の呼出しを発行するによって、TPNULLCONTEXT状態にすることができます。

tpsetctxt(TPNULLCONTEXT, 0)

TPINVALIDCONTEXTは、contextに入力できる有効な値ではありません。

TPINVALIDCONTEXT状態のスレッドは、ほとんどのATMI関数に対する呼出しを発行できません。(呼び出せる関数と呼び出せない関数のリストについては、「C言語アプリケーション・トランザクション・モニター・インタフェースの紹介」を参照してください)。このため、必要に応じてスレッドのTPINVALIDCONTEXT状態を終了させる必要があります。それには、コンテキストをTPNULLCONTEXTか別の有効なコンテキストに設定してtpsetctxt()を呼び出します。また、tpterm()関数を呼び出してTPINVALIDCONTEXT状態を終了させることもできます。

2番目の引数flagsは現在使用されていないので、0に設定します。

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

戻り値

tpsetctxt()は、正常終了時には0以外の値を返します。

異常終了すると、呼出しプロセスを元のコンテキストに置いたまま-1を返し、tperrnoを設定してエラー条件を示します。

エラー

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

[`TPEINVAL`]

無効な引数が指定されました。たとえば、flagsが0以外の値に設定された、またはコンテキストがTPINVALIDCONTEXTです。

[`TPENOENT`]

contextの値が有効なコンテキストではありません。

[`TPEPROTO`]

tpsetctxt()が不正なコンテキストで呼び出されました。たとえば、(a)サーバーがディスパッチしたスレッドで呼び出された、(b) tpinit()を呼び出していないプロセスで呼び出された、(c) TPMULTICONTEXTSフラグを指定せずにtpinit()を呼び出したプロセスで呼び出された、または (d) TMNOTHREADS環境変数がオンになっているプロセスで複数のスレッドから呼び出された、などです。

[`TPESYSTEM`]

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

[`TPEOS`]

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

tpsetmbenc(3c)

名前

tpsetmbenc() - 型付きバッファにコード・セットのエンコード名を設定

形式

#include <atmi.h>
extern int tperrno;

int
tpsetmbenc(char *bufp, char *enc_name, long flags)

説明

この関数は、コードセットのエンコーディング名を設定またはリセットするために使用します。エンコーディング名は、入力型付きバッファとともに送信されます。これらのメッセージを受け取るプロセスは、tpgetmbenc()を使用してこのエンコーディング名を取得できます。

tpsetmbenc()は、Tuxedoシステム・リクエストに含めるコードセットのエンコード名を設定します。この関数で呼出し側のバッファにNULL以外のエンコード名を設定すると、その設定をリセットまたは解除するまで、(tpcall()、tpsend()によって)送信されるすべてのメッセージに、この文字列が入ります。tpalloc()の実行時に、TPMBENC環境変数で初期コードセットのエンコード名がMBSTRINGバッファに適用されます。エンコード名が未定義のMBSTRINGバッファは無効です。

引数bufpは、エンコード名で型付きバッファを指す有効なポインタです。

引数enc_nameは、コードセットのエンコードの識別に使用するエンコード名です。

引数flagsには、0またはRM_ENCを指定します。RM_ENCの場合、エンコード名がMBSTRINGバッファから削除され、引数enc_nameは無視されます。MBSTRINGバッファにエンコード名を設定しないと、_tmconvmb()による変換は失敗します。

戻り値

正常終了の場合、tpsetmbenc()は値0を返します。エラーが発生した場合は、ゼロ以外の値を返し、tperrnoを設定してエラー条件を示します。この関数は、次の原因により異常終了する可能性があります。

[`TPEINVAL`]

bufまたはenc_name引数の値がNULLです。あるいは、enc_nameに指定した名前が無効です。

[`TPESYSTEM`]

Tuxedoシステムのエラーが発生しました。 bufpが有効なTuxedoバッファに対応していないため、バッファへのエンコード名の追加、またはバッファからのエンコード名の削除ができない可能性があります。

tpsetrepos(3c)

名前

tpsetrepos() - Tuxedoサービス・メタデータ・リポジトリ・ファイルからのサービス・パラメータ情報を追加、編集または削除します。

形式

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

説明

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

tpsetrepos()は、Oracle Tuxedoネイティブ・ライブラリにリンクされたプロセスで使用できますが、Oracle Tuxedoワークステーション・ライブラリにリンクされたプロセスでは使用できません。

注意:

tpsetrepos()を使用して、JOLTリポジトリ・ファイルのサービス・パラメータ情報を追加、編集、または削除することはできません。

`reposfile`

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

`idata`

追加、編集、または削除するサービスの情報の種類を指定し、FML32バッファを指します。

*`odata`

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

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

戻り値

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

エラー

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

`[TPEINVAL]`

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

`[TPEMIB]`

`[TPEPROTO]`

tpsetrepos()が不正に呼び出されました。指定したreposfileファイル引数は、有効なリポジトリ・ファイルではありません。

`[TPEPERM]`

Joltリポジトリ・ファイルが指定されています。tpsetrepos()をJoltリポジトリ・ファイルに適用することはできません。

`[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を指定します。

tpsetunsol(3c)

名前

tpsetunsol() - 非請求メッセージの処理方式の設定

形式

#include <atmi.h> void (*tpsetunsol (void (_TMDLLENTRY *)(*disp) (char *data, long len, long flags))) (char *data, long len, long flags)

説明

tpsetunsol()は、非請求メッセージがOracle Tuxedo ATMIシステムのライブラリによって受け取られる際に呼び出すルーチンをクライアントが指定できるようにします。tpsetunsol()の最初の呼出しの前に、Oracle Tuxedo ATMIシステムのライブラリがクライアントのために受け取った非請求メッセージは記録されますが、無視されます。NULL関数ポインタを使用するtpsetunsol()を呼び出した場合も、同じ結果になります。システムが通知や検出のために使用する方法は、アプリケーションのデフォルトの設定で決まります。このデフォルトは、クライアントごとに変更できます(「tpinit(3c)」を参照)。

tpsetunsol()の呼出し時に渡される関数ポインタは、所定のパラメータ定義に準拠している必要があります。Tuxedoライブラリと使用中のコードの間の適切な呼出し規約を取得するために、Windowsベースのオペレーティング・システムでは_TMDLLENTRYマクロが必要になります。UnixシステムではNULL文字列に拡張されるため、_TMDLLENTRYマクロは必要ありません。

dataは受け取った型付きバッファを指し、lenはそのデータの長さを指定します。flagsは現時点では使用されていません。dataは、通知と一緒にデータが渡されない場合にはNULLになります。dataは、クライアントが認識しないタイプ/サブタイプのバッファであることがありますが、その場合、メッセージ・データは不明瞭になります。

dataはアプリケーション・コードで解放することはできません。ただし、システムはこれを解放し、終了後、データ領域を無効にします。

アプリケーションの任意通知型メッセージ処理ルーチン内での処理は、Oracle Tuxedo ATMI関数tpalloc()、tpfree()、tpgetctxt()、tpgetlev()、tprealloc()およびtptypes()に限定されています。

マルチスレッド・プログラミング環境では、非請求メッセージ処理ルーチンがtpgetctxt()を呼び出して、別のスレッドを作成し、そのスレッドに適切なコンテキストのtpsetctxt()を呼び出し、新しいスレッドに、クライアントが使用できるATMI関数をすべて使用させることができます。

tpsetunsol()がコンテキストに関連していないスレッドから呼び出されると、新しく生成されるすべてのtpinit()コンテキストに対して、プロセスごとのデフォルトの非請求メッセージ・ハンドラが作成されます。これは、すでにシステムに関連付けられているコンテキストには影響しません。特定のコンテキストは、コンテキストがアクティブのときにtpsetunsol()を再度呼び出して、そのコンテキストの非請求メッセージ・ハンドラを変更することができます。プロセス単位のデフォルトの非請求メッセージ・ハンドラは、コンテキストに現在関連付けされていないスレッドでtpsetunsol()を再度呼び出すと、変更できます。

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

戻り値

tpsetunsol()は、正常終了時には、非請求メッセージ処理ルーチンの以前の設定条件を返します(NULLも正常な戻り値の1つであり、メッセージ処理関数を事前に設定していなかったことを示します)。

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

エラー

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

[`TPEPROTO`]

tpsetunsol()が正しくないコンテキストで呼び出されました。たとえば、サーバー内部から呼び出されています。

[`TPESYSTEM`]

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

[`TPEOS`]

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

移植性

tpnotify(3c)で説明したインタフェースはすべて、ネイティブ・サイトのUNIXシステム・ベースのプロセッサおよびWindowsプロセッサ上で利用できます。さらに、ルーチンtpbroadcast()とtpchkunsol()は、関数tpsetunsol()ともとに、UNIXシステムおよびMS-DOSベースのプロセッサ上で利用することができます。

tpsign(3c)

名前

tpsign() - デジタル署名のための型付きメッセージ・バッファのマーク

形式

#include <atmi.h>
int tpsign(char *data, TPKEY hKey, long flags)

説明

tpsign()は、hKeyに関連するプリンシパルにかわって、デジタル署名のためのメッセージ・バッファをマーク(登録)します。

dataは、(1)以前tpalloc()を呼び出すプロセスによって割り当てられたメッセージ・バッファ、または(2)システムによって受信プロセスに渡されたメッセージ・バッファのうち、いずれかの有効な型付きメッセージ・バッファを指している必要があります。バッファの内容は、tpsign()を起動してから修正することができます。

dataが指すバッファがプロセスから伝送されると、デジタル署名登録リクエストに対して、公開鍵ソフトウェアがデジタル署名を生成し、メッセージ・バッファにアタッチします。デジタル署名によって、受信プロセスはメッセージの署名者(発信者)を検証することができます。

引数flagsは使用されません。この引数は将来の用途のために予約されており、0に設定します。

戻り値

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

エラー

[`TPEINVAL`]

無効な引数が指定されました。たとえば、hKeyが署名に有効なキーでない、またはdataの値がNULLです。

[`TPESYSTEM`]

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

tpsprio(3c)

名前

tpsprio() - サービス・リクエストの優先度の設定

形式

#include <atmi.h> 
int tpsprio(prio, flags)

説明

tpsprio()は、カレント・コンテキストのカレント・スレッドが、次に送信または転送するリクエストの優先度を設定します。設定された優先度は、次に送信されるリクエストに対してのみ有効です。メッセージのキュー登録機能がインストールされている場合、優先度をtpenqueue()やtpdequeue()によってキューへ登録、または削除されたメッセージに対しても設定することができます。デフォルトでは、prioに正または負の値を設定することにより、サービスの優先度が、そのデフォルト値を基準として設定値の分だけ上下します。上限は100、下限は1で、100が最も高い優先度を表します。リクエストのデフォルトの優先度は、そのリクエストの送信先となるサービスによって決まります。このデフォルトの設定は、管理時に指定してもよいですし(「UBBCONFIG(5)」を参照)、システムの省略時値50を使用してもかまいません。tpsprio()は、tpconnect()またはtpsend()を介して送られるメッセージには影響しません。

メッセージは、10回に1回はFIFO方式に基づいて取り出されるため、優先度の低いメッセージがキューにいつまでも残されることはありません。優先度の低いインタフェースやサービスでは、レスポンス時間を問題にすべきではありません。

マルチスレッドのアプリケーションでは、tpsprio()はスレッド単位で動作します。

次に、有効なフラグの一覧を示します。

`TPABSOLUTE`

次のリクエストの優先度は、prioの絶対値で送信されます。prioの絶対値は1から100までの範囲内の数値とします(最も高い優先度は100です)。この範囲外の値を指定すると、デフォルトの値が使用されます。

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

戻り値

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

エラー

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

[`TPEINVAL`]

flagsが無効です。

[`TPEPROTO`]

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

[`TPESYSTEM`]

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

[`TPEOS`]

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

tpstrerror(3c)

名前

tpstrerror() - Oracle Tuxedo ATMIシステムのエラー・メッセージ文字列の取得

形式

#include <atmi.h> 
char *  
tpstrerror(int err)

説明

tpstrerror()はLIBTUX_CATからエラー・メッセージのテキストを取得するために使用します。errは、Oracle Tuxedo ATMIシステムの関数呼出しが -1またはその他の異常終了値を返した場合にtperrnoに設定されるエラー・コードです。

tpstrerror()によって戻されたポインタをuserlog()またはUNIX関数fprintf()に対する引数として使用できます。

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

戻り値

正常終了すると、tpstrerror()はエラー・メッセージ・テキストを含む文字列を指すポインタを返します。

errが無効なエラー・コードであった場合は、tpstrerror()は、NULLを返します。

エラー

異常終了すると、tpstrerror()はNULLを返しますがtperrnoは設定しません。

例

#include <atmi.h>
.
.
.
  char *p;
  if (tpbegin(10,0) == -1) {
    p = tpstrerror(tperrno); 
    userlog(“%s”, p); 
    (void)tpabort(0); 
    (void)tpterm(); 
    exit(1);
  }

tpstrerrordetail(3c)

名前

tpstrerrordetail() - Oracle Tuxedo ATMIのエラーに関する詳細なメッセージ文字列の取得

形式

#include <atmi.h> 
char * tpstrerrordetail(int err, long flags)

説明

tpstrerrordetail()は、Oracle Tuxedo ATMIシステム・エラーのエラー詳細テキストを取得するために使用します。errは、tperrordetail()によって戻される値です。

ユーザーは、tpstrerrordetail()が返したポインタをuserlog()またはfprintf()に対する引数として使用できます。

flagsは将来の使用を考慮して予約されているため、ゼロを指定してください。

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

戻り値

正常終了すると、この関数はエラー詳細メッセージ・テキストを含む文字列を指すポインタを戻します。

異常終了時(すなわちerrが無効なエラー・コードの場合)、tpstrerrordetail()はNULLを返します。

エラー

異常終了すると、tpstrerrordetail()はNULLを返し、tperrnoは設定しません。

例

#include <atmi.h> .  .  .  
int ret;
char *p;

if (tpbegin(10,0) == -1) {
       ret = tperrordetail(0);
       if (ret == -1) {
              (void) fprintf(stderr, “tperrordetail() failed!\n”);
              (void) fprintf(stderr, “tperrno = %d, %s\n”,
                     tperrno, tpstrerror(tperrno));
       }


       else if (ret != 0) {
              (void) fprintf(stderr, “errordetail:%s\n”,
                             tpstrerrordetail(ret, 0));
       }
       .
       .
       .
}

tpsubscribe(3c)

名前

tpsubscribe() - イベントをサブスクライブする

形式

#include <atmi.h> 
long tpsubscribe(char *eventexpr, char *filter, TPEVCTL *ctl, long flags)

説明

呼出し側はtpsubscribe()を使用して、eventexprで示されるイベントまたはイベントの集合をサブスクライブします。サブスクリプションは、Oracle Tuxedo ATMIのイベント・ブローカ、TMUSREVT(5)によって保持され、イベントがポストされたときにサブスクライバに通知するために、tppost()によって使用されます。それぞれのサブスクリプションには、通知メソッドを指定します。通知メソッドは、クライアント通知、サービス呼び出し、または安定ストレージ内のキューへのメッセージ登録の3つの内いずれかの形式をとります。通知メソッドはサブスクライバのプロセスのタイプとtpsubscribe()に渡された引数によって決まります。

サブスクライブするイベントまたはイベントの集合は、eventexprで指定します。eventexprには、最大で255文字の正規表現が入ったNULLで終了する文字列を指定します。たとえば、eventexprが「¥e¥e..*」であれば、呼出し側はシステムで生成されたすべてのイベントをサブスクライブします。eventexprが「¥e¥e.SysServer.*」であれば、呼出し側はシステムで生成されたサーバーに関連するすべてのイベントをサブスクライブします。eventexprが「[A-Z].*」であれば、呼出し側は先頭にA-Zを持つすべてのユーザー・イベント文字列をサブスクライブします。eventexprが「.*(ERR|err).*」である場合、呼出し側はサブストリングERRまたはerrのいずれかを含むすべてのユーザー・イベントを登録しています。たとえば、account_errorおよびERROR_STATEと呼ばれるイベントは、どちらも登録の対象となります。正規表現の詳細については、「正規表現」を参照してください。

filterを指定する場合は、ブール値のフィルタ・ルールを含む文字列を指定します。このルールは、イベント・ブローカがイベントをポストする前に正しく評価しなければなりません。ポストするイベントを受け取ると、EventBrokerはそのイベントのデータにフィルタ規則(存在する場合)を適用します。データがフィルタ・ルールのチェックにパスした場合、イベント・ブローカは通知メソッドを呼び出します。データがフィルタ・ルールを通過しない場合は、イベント・ブローカは対応する通知メソッドを呼び出しません。呼出し側は、異なるフィルタ・ルールを利用して同じイベントを何度でもサブスクライブすることができます。

フィルタ・ルールは、それが適用される型付きバッファに固有なものです。FMLバッファおよびVIEWバッファの場合は、フィルタ・ルールはそれぞれのブール式コンパイラ(それぞれFboolco(3fml)およびFvboolco(3fml)を参照)に渡すことができて、ポストされたバッファ(Fboolev(3fml)およびFboolev(3fml)を参照)に対して評価することができる文字列です。STRINGバッファの場合は、フィルタ・ルールは正規表現です。他のすべてのタイプのバッファの場合、カスタマイズしたフィルタ評価機構が必要です(カスタマイズしたフィルタ評価機構を追加する方法についての詳細は、buffer(3c)およびtypesw(5)を参照してください)。filterには、最大255文字のNULLで終了する文字列を指定します。

サブスクライバがOracle Tuxedo ATMIのクライアント・プロセスで、ctlがNULLの場合は、サブスクライブしているイベントがポストされたときに、イベント・ブローカはサブスクライバに非請求メッセージを送ります。この場合、eventexprに対して評価が成功するイベント名がポストされると、イベント・ブローカはeventexprに対応したフィルタ・ルールに対してポストされたデータをテストします。データがフィルタ・ルールによるチェックにパスした場合、あるいはそのイベントに対して適用すべきフィルタ・ルールが存在しない場合は、サブスクライバはイベントとそのデータ、および非請求メッセージを受け取ることになります。非請求メッセージを受け取るためには、クライアントは非請求通知処理ルーチンを(tpsetunsol()を利用して)登録しておく必要があります。Oracle Tuxedo ATMIシステムのサーバー・プロセスが、ctlパラメータをNULLにしてtpsubscribe()を呼び出した場合は、tpsubscribe()は異常終了してtperrnoをTPEPROTOに設定します。

非請求メッセージによってイベント通知を受け取るクライアントは、終了する前にイベント・ブローカのアクティブなサブスクリプションのリストから、そのサブスクリプションを削除する必要があります(詳細は、「tpunsubscribe(3c)」を参照してください)。クライアントは、tpunsubscribe()のワイルドカード・ハンドル、-1を使用することにより、非請求通知メソッドに関連するサブスクリプションを含むあらゆる「非永続的」サブスクリプションを削除することができます。プロセス終了後も存続するサブスクリプションおよびそれらに関連する通知メソッドについては、以下のTPEVPERSISTの説明を参照してください。クライアントが非持続型のサブスクリプションを削除せずに終了した場合は、イベント・ブローカはクライアントにアクセスできなくなったことを検出すると、そのクライアントのサブスクリプションを削除します。

サブスクライバが(プロセス・タイプにかかわらず)イベント通知をサービス・ルーチンまたは安定ストレージ内のキューに送りたい場合は、ctlパラメータは有効なTPEVCTL構造体を指さなければいけません。この構造体には次の要素が含まれます。

long    flags;  
char    name1[128];  
char    name2[128];  
TPQCTL  qctl;

注意: サービス名の長さは127バイト以内に制限されています。サービス名の長さが127バイトを超える場合は、TPEINVALが戻されます。

次に、ctlflags要素に指定する、イベントをサブスクライブするための制御オプションの有効なビットの一覧を示します。

`TPEVSERVICE`

このフラグは、サブスクライバがイベント通知をctl

name1という名前のOracle Tuxedo ATMIシステムのサービス・ルーチンに送信したいことを示します。この場合、eventexprに対して評価が成功するイベント名がポストされると、イベント・ブローカはeventexprに対応したフィルタ・ルールに対してポストされたデータをテストします。データがフィルタ・ルールを通過する場合、またはイベントに対するフィルタ・ルールが存在しない場合は、サービス・リクエストはイベントとともにポストされたデータと合せてctl

name1に送信されます。ctl

name1のサービス名には、Oracle Tuxedo ATMIシステムの有効な任意のサービス名を指定することができ、このサービスはサブスクライブされたときにアクティブである場合もあれば、アクティブでない場合もあります。イベント・ブローカによって呼び出されたサービス・ルーチンは、応答データなしで戻ります。つまり、引数にNULLデータを指定してtpreturn()を呼び出すはずです。tpreturn()に渡されるデータはドロップされます。TPEVSERVICEとTPEVQUEUEを同時に指定することはできません。

TPEVTRANも同時にctl

flagsに設定し、またtppost()を呼び出すプロセスがトランザクション・モードにある場合は、イベント・ブローカはサービス・ルーチンがポスト元のトランザクションの一部となるようにサブスクライブされたサービス・ルーチンを呼び出します。イベント・ブローカ(TMUSREVT(5))とサブスクライブされたサービス・ルーチンの両方が、トランザクションをサポートするサーバー・グループに属していなければなりません(詳細は、「UBBCONFIG(5)」を参照してください)。ctl

flagsにTPEVTRANを設定していない場合は、イベント・ブローカは、サービス・ルーチンがポスト元のトランザクションの一部とならないように、サブスクライブされたサービス・ルーチンを呼び出します。

`TPEVQUEUE`

このフラグを設定することは、サブスクライバがイベント通知をctl

name1という名前のキュー・スペース、およびctl

name2という名前のキューへ登録することを希望していることを示します。この場合、eventexprに対して評価が成功するイベント名がポストされると、イベント・ブローカはeventexprに対応したフィルタ・ルールに対してポストされたデータをテストします。データがフィルタ・ルールを通過した場合、またはイベントに対応したフィルタ・ルールが存在しない場合は、イベント・ブローカはメッセージをイベントとともにポストされたデータと合せて、ctl

name1という名前のキュー・スペース、およびctl

name2という名前のキューに登録します。キュー・スペースとキューの名前は、Oracle Tuxedo ATMIシステムの有効な任意のキュー・スペースおよびキューの名前で、サブスクリプションの実行時に存在している場合と存在していない場合があります。

ctl

qctlには、ポストされたイベントをイベント・ブローカがキューに登録することに関するオプションをさらに指定することができます。オプションを何も指定しない場合は、ctl

qctl.flagsをTPNOFLAGSに設定する必要があります。それ以外の場合は、「tpenqueue(3c)」の「制御パラメータ」の項で説明しているようにオプションを設定できます(特に、tpenqueue(3c)への入力情報を制御するフラグの有効なリストを説明している項を参照してください)。TPEVSERVICEとTPEVQUEUEを同時に指定することはできません。 ctl

flagsにTPEVTRANも同時に指定し、tppost()を呼び出すプロセスがトランザクション・モードにある場合は、イベント・ブローカは、ポストされたイベントとそのデータがポスト元のトランザクションの一部となるように、それらをキューに登録します。イベント・ブローカ(TMUSREVT(5))はトランザクションをサポートするサーバー・グループに属している必要があります(詳細は、「UBBCONFIG(5)」を参照してください)。ctl

flagsにTPEVTRANを設定しない場合は、イベント・ブローカは、ポストされたイベントとそのデータがポスト元のトランザクションの一部とならないように、それらをキューに登録します。

`TPEVTRAN`

このフラグを設定することは、このサブスクリプションのイベント通知が存在する場合に、サブスクライバがこれをポスト元のトランザクションに含めることを希望していることを示します。ポスト元がトランザクション以外の場合、このイベントを通知するためにトランザクションが開始されます。このフラグを設定しない場合は、このサブスクリプションに対してポストされたいかなるイベントも、ポスト元が参加しているどのトランザクションのかわりに実行させることはできません。このフラグは、TPEVSERVICEまたはTPEVQUEUEのどちらかと同時に指定できます。

`TPEVPERSIST`

デフォルトでは、Oracle Tuxedoのイベント・ブローカは、通知先のリソースが使用不可能である場合はサブスクリプションを削除します。たとえば、イベントのサブスクリプションに関連するサービス・ルーチン、またはキュー・スペースとキューにイベント・ブローカがアクセスできない場合などです。このフラグを設定することは、そのようなエラーが発生してもサブスクリプションが持続するように(多くの場合、リソースは後で利用できるようになるため)サブスクライバが求めることを示します。このフラグを設定しない場合、このサブスクリプションで指定されたサービス名またはキュー・スペース名/キュー名のいずれかへのアクセス時にエラーが発生すると、イベント・ブローカはこのサブスクリプションを削除します。

このフラグをTPEVTRANと同時に指定し、イベントの通知時にリソースが利用できない場合は、イベント・ブローカはポスト元に戻り、トランザクションが中止しなければならないようにします。つまり、サブスクリプションが保持されている場合でも、リソースが使用できなければポスト元のトランザクションは失敗します。

イベント・ブローカのアクティブなサブスクリプションのリストに、tpsubscribe()がリクエストするサブスクリプションと一致するものがある場合は、この関数は失敗してtperrnoにTPEMATCHを設定します。サブスクリプションが既存のサブスクリプションと一致するためには、eventexprとfilterの両方が、イベント・ブローカのアクティブなサブスクリプションのリストにすでに存在するサブスクリプションのeventexprとfilterに一致する必要があります。また、通知メソッドによっては、サブスクリプションの一致を判断する際にこれ以外の基準も使用されます。

サブスクライバがOracle Tuxedo ATMIシステムのクライアント・プロセスで、(イベントがポストされたときに、呼出し側が任意通知を受け取るように) ctlにNULLを設定した場合は、システム定義によるそのクライアント識別子(CLIENTIDと呼ばれています)も一致を調べるために使用されます。つまりtpsubscribe()は、eventexpr、filter、および呼出し側のCLIENTIDが、イベント・ブローカにすでに知られているサブスクリプションが持つそれらの値と一致する場合に失敗します。

呼出し側がctlflagsをTPEVSERVICEに設定した場合、eventexpr、filter、およびctlname1で設定されるサービス名がイベント・ブローカのリストにすでに存在するサブスクリプションのそれらと一致すると、tpsubscribe()は失敗します。

安定ストレージ内のキュー、キュー・スペース、およびキューの名前へのサブスクリプションの場合は、一致を調べる際にeventexprおよびfilterに加えて相関識別子が使用されます。相関識別子を利用することにより、同じ送信先の、同じイベント式やフィルタ・ルールに対する複数のサブスクリプションを区別することができます。したがって、呼出し側がctlflagsにTPEVQUEUEを設定し、ctlqctl.flagsにTPQCOORIDが設定されなかった場合、eventexpr、filter、ctlname1に設定されたキュー・スペース名、およびctlname2に設定されたキュー名が、イベント・ブローカにすでに知られている(相関識別子が指定された)サブスクリプションが持つそれらの値と一致するとtpsubscribe()は失敗します。さらに、ctlqctl.flagsにTPQCOORIDが設定されている場合は、eventexpr、filter、ctlname1、ctlname2、およびctlqctl.corridがイベント・ブローカにすでに知られている(同じ相関識別子が指定された)サブスクリプションのデータと一致すると、tpsubscribe()は失敗します。

次に、tpsubscribe()に対して有効なflagsの一覧を示します。

`TPNOBLOCK`

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

`TPNOTIME`

`TPSIGRSTRT`

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

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

正規表現

表14で説明する正規表現は、UNIXシステム・エディタ、ed(1)で使用されるパターンに似ています。一般的な正規表現のほか、代替演算子(|)も使用できます。ただし、全体的にほとんど変わりません。

正規表現(RE: Regular Expressions)は、次に示すいずれかの規則を1回以上適用して作成します。

表14 正規表現
規則	一致するテキスト
文字	文字(文字とは、後述の特殊文字を除く任意のASCII文字)
`¥文字`	それ自身(次に示すものを除く) ¥¥ - 改行 ¥¥t - タブ ¥¥b - バックスペース ¥¥r - キャリッジ・リターン ¥¥f - フォーム・フィード
`¥特殊文字`	非特殊文字。特殊文字には、 * + ? ピリオド(.)、*、+、?、\|、(、)、「、{、¥¥、があります。 . - 行末文字(通常は改行文字またはNULL文字)以外の任意の文字 ^ - 行頭 $ - 行末文字



`[class]`	一連の文字または範囲、あるいはその両方で表すクラス内の任意の文字。範囲は、character-characterという形式で指定されます。たとえば、文字クラス[a-zA-Z0-9_]は、英数字またはアンダースコア"_"と一致します。ハイフン("-")をクラスに含めるためには、"¥¥"の後のハイフンをエスケープするか、クラス内の先頭または終わりに指定する必要があります。リテラル"]"の場合は、エスケープするか、またはクラスの先頭に指定します。リテラル"^"がクラスの先頭にある場合は、エスケープする必要があります。
[`^ class` ]	行末文字を除く、クラスの補集合におけるASCII文字セットに関する文字
`RE RE`	正規表現のシーケンス(連結)
`RE \| RE`	左側のREまたは右側のRE (左右の二者択一)
`RE *`	REが0回以上発生
`RE +`	REが1回以上発生
`RE ?`	REが0回または1回発生
`RE { n }`	REが`n`回発生。`n`の範囲は0 - 255です。
`RE { m, n }`	REが`m` - `n`の範囲の回数発生。`m`が指定されない場合は0になります。`n`が指定されない場合は、`RE`が`m`回以上発生することを示します。
`( RE )`	優先順位またはグループ化を明示的に示します。
`( RE ) $ n`	`RE`と一致するテキストがnthユーザー・バッファにコピーされます。`n`は0 - 9です。ユーザー・バッファは、照合が開始する前にクリアされ、パターン全体が一致した場合のみロードされます。

優先順位のレベルは3つあります。結合の強さの順に並べると、次のようになります。

catenation closure (*,+,?,{...})
連結
二者択一(|)

上記のとおり、かっこは優先順位が高いことを明示的に示すために使用します。

戻り値

tpsubscribe()は正常終了すると、イベント・ブローカのアクティブなサブスクリプションのリストからこのサブスクリプションを削除するために使用できるハンドルを戻します。サブスクライバやその他のプロセスは、いずれも戻されたハンドルを利用してこのサブスクリプションを削除することができます。

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

エラー

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

[`TPEINVAL`]

無効な引数(たとえば、eventexprにNULL)が指定されました。

[`TPENOENT`]

Oracle Tuxedoイベント・ブローカにアクセスできません。

[`TPELIMIT`]

イベント・ブローカの最大サブスクリプション数に達したため、サブスクリプションが失敗しました。

[`TPEMATCH`]

イベント・ブローカのリストにすでに存在するサブスクリプションと一致するため、サブスクリプションが異常終了しました。

[`TPEPERM`]

クライアントはtpsysadmとしてアタッチされず、サブスクリプションのアクションは、サービスの呼出しか、メッセージのキューへの登録になります。

[`TPETIME`]

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

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

[`TPEBLOCK`]

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

[`TPGOTSIG`]

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

[`TPEPROTO`]

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

[`TPESYSTEM`]

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

[`TPEOS`]

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

tpsuspend(3c)

名前

tpsuspend() - グローバル・トランザクションの中断

形式

#include <atmi.h> 
int tpsuspend(TPTRANID *tranid, long flags)

説明

tpsuspend()を使用して、呼出し側のプロセス内でアクティブなトランザクションを中断します。tpbegin()により開始したトランザクションは、tpsuspend()で中断できます。中断を行ったプロセスまたは他のプロセスのいずれかがtpresume()を使用して、中断されたトランザクション上の作業を再開できます。tpsuspend()が復帰すると、呼出し側はトランザクション・モードではなくなります。ただし、トランザクションが中断されている間は、そのトランザクションに関係のあるリソース(データベース・ロックなど)はすべてアクティブな状態に保たれます。アクティブなトランザクションと同様、中断されたトランザクションにもトランザクションを最初にスタートする際に割り当てたトランザクション・タイムアウトの値が適用されます。

トランザクションを別のプロセスで再開するには、tpsuspend()の呼出し側が明示的にtpbegin()を呼び出すことによってトランザクションを起動している必要があります。tpsuspend()は、トランザクションの開始元以外のプロセスから呼び出すこともできます(たとえば、トランザクション・モードでリクエストを受信するサーバー)。後者の場合、tpsuspend()の呼出し側のみtpresume()を呼び出してトランザクションを再開することができます。このような方法が認められているのは、プロセスがトランザクションのスタートを一時中断し、そのトランザクションを終了する前に別のトランザクションをスタートさせ、作業を行えるようにするためです(エラーを記録するトランザクションを実行してから最初のトランザクションをロールバックする場合など)。

tpsuspend()は、中断されているトランザクションの識別子を、tranidで指される領域に返します。呼出し側はtranidが指す空間を割り当てなければなりません。tranidがNULLの場合はエラーです。

正常終了するためには、呼出し側はtpsuspend()を実行する前に、サーバーとの未終了のコミュニケーションをすべて完了している必要があります。つまり、呼出し側は、呼出し側のトランザクションに関連付けられていたtpacall()で送信したリクエストに対する応答を、すべて受け取っている必要があります。また、呼出し側は、呼出し側のトランザクションに関連のある会話型サービスとの接続を、すべてクローズしている必要があります(つまり、tprecv()はTPEV-SVCSUCCイベントを戻している必要があります)。この規則のいずれかが守られない場合には、tpsuspend()は失敗し、呼出し側の現在のトランザクションは中断されず、トランザクション・コミュニケーションの記述子は有効なままです。呼出し側のトランザクションに関連付けられていないコミュニケーション記述子は、tpsuspend()の結果に関係なく有効なままです。

flagsは将来使用するために予約されており、0に設定されます。

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

tpsuspend()は、グローバル・トランザクション内の複数のリソース・マネージャを含め、すべての参加リソース・マネージャに対して影響を与えることができます。

戻り値

tpsuspend()はエラーの場合は -1を返し、tperrnoを設定してエラー条件を示します。

エラー

次の条件の場合、tpsuspend()は異常終了し、tperrnoを次の値に設定します。

[`TPEINVAL`]

tranidがNULLポインタであるか、またはflagsが0ではありません。トランザクションに関する呼出し側の状態は変化しません。

[`TPEABORT`]

呼出し側のアクティブなトランザクションが中断されました。トランザクションに関連するすべてのコミュニケーション記述子は、有効ではなくなります。

[`TPEPROTO`]

tpsuspend()が不正なコンテキストで呼び出されました(たとえば、呼出し側がトランザクション・モードでないなど)。トランザクションに関する呼出し側の状態は変化しません。

[`TPESYSTEM`]

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

[`TPEOS`]

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

tpsvrdone(3c)

名前

tpsvrdone() - Oracle Tuxedo ATMIシステム・サーバーの終了

形式

#include <atmi.h>
void tpsvrdone(void)

説明

Oracle Tuxedo ATMIシステムのサーバー用ルーチンは、サービス・リクエストの処理完了後、ルーチンを終了する前にtpsvrdone()を呼び出します。このルーチンを呼び出した時点では、サーバーはまだシステムの一部のままですが、それ独自のサービスは公開から外されています。このため、このルーチンで、Oracle Tuxedo ATMIシステムとのコミュニケーションとトランザクションの定義を行うことができます。ただし、接続がオープン状態にある場合、保留中の非同期応答がある場合、あるいはまだトランザクション・モードにある場合にtpsvrdone()が終了すると、Oracle Tuxedo ATMIシステムはその接続をクローズし、保留中の応答を無視し、サーバーが終了する前にトランザクションを中断させます。

サーバーがtmshutdown -yを呼び出して停止された場合、サービスは中断され、tpsvrdone()で通信したりトランザクションを開始する機能は制限されます。

アプリケーションがこのルーチンをサーバーで提供していない場合、Oracle Tuxedo ATMIシステムが提供するデフォルトのバージョンがかわりに呼び出されます。サーバーがシングル・スレッド・サーバーとして定義されている場合、デフォルトのtpsvrdone()はtpsvrthrdone()を呼び出し、デフォルト・バージョンのtpsvrthrdone()はtx_close()を呼び出します。サーバーがマルチスレッド・サーバーとして定義されている場合、各サーバーのディスパッチ・スレッドでtpsvrthrdone()が呼び出され、tpsvrdone()からは呼び出されません。サーバーがマルチスレッドかどうかに関わらず、デフォルトのtpsvrdone()はuserlogを呼び出し、サーバーが終了することを示します。

使用方法

tpsvrdone()で呼び出された場合、tpreturn()とtpforward()は何も行わずただちに戻ります。

tpsvrinit(3c)

名前

tpsvrinit() - Oracle Tuxedoシステム・サーバーの初期化

形式

#include <atmi.h> 
int tpsvrinit(int argc, char **argv)

説明

Oracle Tuxedo ATMIシステムのサーバー用ルーチンは、その初期化処理中にtpsvrinit()を呼び出します。このルーチンは、サーバーに制御が移った後、サービス・リクエストを処理する前に呼び出されます。このため、Oracle Tuxedo ATMIシステムとのコミュニケーションとトランザクションの定義をこのルーチンで行うことができます。ただし、接続がオープン状態にあるとき、保留中の非同期応答があるとき、あるいはまだトランザクション・モードにあるときにtpsvrinit()が戻った場合、Oracle Tuxedo ATMIシステムはその接続をクローズし、保留中の応答を無視し、サーバーが終了する前にトランザクションをアボートします。

アプリケーションがこのルーチンをサーバーで提供していない場合、Oracle Tuxedo ATMIシステムが提供するデフォルトのバージョンがかわりに呼び出されます。

サーバーがシングル・スレッド・サーバーとして定義されている場合、デフォルトのtpsvrinit()はtpsvrthrinit()を呼び出し、デフォルト・バージョンのtpsvrthrinit()はtx_open()を呼び出します。サーバーがマルチスレッド・サーバーとして定義されている場合、tpsvrthrinit()は各サーバーのディスパッチ・スレッドで呼び出されますが、tpsvrinit()からは呼び出されません。サーバーがシングル・スレッドかマルチスレッドかに関わらず、デフォルト・バージョンのtpsvrinit()はuserlog()を呼び出してサーバーが正常に開始したことを示します。

アプリケーション固有のオプションをサーバーに渡し、tpsvrinit()で処理させることができます(「servopts(5)」を参照)。このオプションはargcとargvを使用して渡します。getopt()がOracle Tuxedo ATMIシステムのサーバー用ルーチンで使用されているため、optarg()、optind()およびopterr()を使用してオプションの解析やエラー検出をtpsvrinit()で制御できます。

注意:

プログラムでtpsvrinit()を呼び出す場合は、ロング・ブロッキングを行わないでください。ロング・ブロッキングを行った場合、MP構成内の1つのリモート・サーバーがtpsvrinit()処理を行うと、tmbootを実行しても、同じノード上のほかのサーバーを起動できません。

tpsvrinit()でエラーが生じた場合、アプリケーションから -1を返して明示的にサーバーを終了させることができます(サービス・リクエストをとらずに)。アプリケーション自体ではexit()を呼び出さないようにしてください。

tpsvrinit()が-1を戻した場合、サーバーはシステムによって再起動されません。かわりに、管理者がtmbootを実行してサーバーを再起動する必要があります。

戻り値

負の戻り値は、サーバーを適切に終了させます。

使用方法

tpreturn()やtpforward()がサービス・ルーチンの外部(たとえば、クライアントやtpsvrinit()、あるいはtpsvrdone()で)使用された場合、tpreturn()およびtpforward()は何も行わずただちに戻ります。

tpsvrthrdone(3c)

名前

tpsvrthrdone() - Oracle Tuxedo ATMIサーバーのスレッドの終了

形式

#include <atmi.h>
void tpsvrthrdone(void)

説明

Oracle Tuxedo ATMIのサーバーでは、ディスパッチされたサービス・リクエストを処理するために開始された各スレッドを終了するときに、tpsvrthrdone()を呼び出します。つまり、スレッドがリクエストを処理する前に終了された場合でも、tpsvrdone()関数が呼び出されます。このルーチンが呼び出されたとき、対象のスレッドはまだOracle Tuxedo ATMIサーバーの一部ですが、すべてのサービス・リクエストの処理を終了しています。このため、Oracle Tuxedo ATMIとのコミュニケーションとトランザクションの定義をこのルーチンで行うことができます。ただし、接続がオープン状態にある場合や保留中の非同期応答がある場合、あるいはまだトランザクション・モードにある場合にtpsvrthrdone()が終了すると、Oracle Tuxedo ATMIシステムはその接続をクローズし、保留中の応答を無視し、サーバーが終了する前にトランザクションを異常終了させます。

アプリケーションがサーバー中にこのルーチンを記述していない場合、Oracle Tuxedo ATMIシステムによって提供されるデフォルト・バージョンのtpsvrthrdone()がかわりに呼び出されます。デフォルト・バージョンのtpsvrthrdone()では、tx_close()が呼び出されます。

tpsvrthrdone()は、シングルスレッド・サーバーでも呼び出されます。シングルスレッド・サーバーでは、tpsvrthrdone()はデフォルト・バージョンのtpsvrdone()から呼び出されます。複数のディスパッチ・スレッドが予測されるサーバーでは、tpsvrdone()はtpsvrthrdone()を呼び出しません。

使用方法

tpsvrthrdone()から呼び出された場合、tpreturn()とtpforward()関数は単純に返るだけで影響はありません。

tpsvrthrinit(3c)

名前

tpsvrthrinit() - Oracle Tuxedo ATMIサーバーのスレッドの初期化

形式

#include <atmi.h>
int tpsvrthrinit(int argc, char **argv)

説明

Oracle Tuxedo ATMIのサーバーでは、ディスパッチされたサービス・リクエストを処理する各スレッドを初期化するときに、tpsvrthrinit()を呼び出します。このルーチンは、サーバーに制御が移った後、サービス・リクエストを処理する前に呼び出されます。このため、Oracle Tuxedo ATMIとのコミュニケーションとトランザクションの定義をこのルーチンで行うことができます。ただし、接続がオープン状態にある場合や保留中の非同期応答がある場合、あるいはまだトランザクション・モードにある場合にtpsvrthrinit()が終了すると、Oracle Tuxedo ATMIシステムはその接続をクローズし、保留中の応答を無視し、サーバーが終了する前にトランザクションを異常終了させます。

アプリケーションがサーバーにこのルーチンを提供していない場合、Oracle Tuxedo ATMIシステムによって提供されたデフォルト・バージョンのtpsvrthrinit()がかわりに呼び出されます。デフォルト・バージョンのtpsvrthrinit()はtx_open()を呼び出します。

tpsvrthrinit()は、シングル・スレッド・サーバーでも呼び出されます。シングル・スレッド・サーバーでは、tpsvrthrinit()はデフォルト・バージョンのtpsvrinit()から呼び出されます。複数のディスパッチ・スレッドが予測されるサーバーでは、tpsvrinit()はtpsvrthrinit()を呼び出しません。

アプリケーション固有のオプションをサーバーに渡し、tpsvrthrinit()で処理させることができます。オプションの詳細は、「servopts(5)」を参照してください。オプションはargcとargvを使用して渡します。getopt()がOracle Tuxedo ATMIシステムのサーバー用ルーチンで使用されているため、optarg()、optind()およびopterr()を使用してオプションの解析やエラー検出をtpsvrthrinit()で制御できます。

tpsvrthrinit()でエラーが生じた場合、アプリケーションから -1を返して正常に(サービス・リクエストをとらずに)サーバーのディスパッチ・スレッドを終了させることができます。アプリケーションが、exit()やその他オペレーティング・システムのスレッド終了関数を呼び出してはいけません。

戻り値

負の戻り値によって、サーバーのディスパッチ・スレッドは正常に終了します。

使用方法

サービス・ルーチンの外側で使用された場合(たとえば、クライアントまたはtpsvrinit()、tpsvrdone()、tpsvrthrinit()、tpsvrthrdone()で使用された場合)、tpreturn()とtpforward()関数は単純に返るだけで影響はありません。

tpterm(3c)

名前

tpterm() - アプリケーションからの分離

形式

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

説明

tpterm()は、Oracle Tuxedo ATMIシステム・アプリケーションからクライアントを削除します。クライアントがトランザクション・モードであると、トランザクションはロールバックされます。tpterm()が正常に終了すると、呼出し側はOracle Tuxedo ATMIクライアント操作を実行できません。未終了の会話はただちに切断されます。

tpterm()を2回以上呼び出した場合(すなわち、呼出し側がすでにアプリケーションから離れた後で呼び出した場合)、何も処理は行われず、正常終了を示す値が返されます。

マルチスレッド化およびマルチコンテキスト化の問題

適切なプログラミングでは、1つを残して他のすべてのスレッドがコンテキストを終了または切り替えると、最後のスレッドがtpterm()呼出しを発行します。このようにプログラミングされていないと、残りのスレッドはTPINVALIDCONTEXTコンテキスト状態になります。次に、このコンテキストのセマンティクスを説明します。

複数のスレッドが関連するコンテキストにおいて、1つのスレッドでtpterm()が呼び出されると、このtpterm()は以下のように動作します。

1つのプロセス内のすべてのコンテキストではなく、1つのコンテキスト内のすべてのスレッド上で動作します。
同じプロセスの他のスレッドとそのコンテキストがまだ関連している場合でも、すぐに動作を実行します。

別のスレッドがコンテキストを終了したときにATMI呼出し内でブロックされたスレッドがあると、そのスレッドはATMI呼出しから異常終了によって返され、tperrnoはTPESYSTEMに設定されます。また、このような異常終了の後でtperrordetail()が呼び出された場合、tperrordetail()はTPED_INVALIDCONTEXTを返します。

シングル・コンテキストのアプリケーションでは、単一のスレッドがtpterm()を呼び出すと、すべてのスレッドのコンテキスト状態がTPNULLCONTEXTに設定されます。

それに対して、マルチコンテキストのアプリケーションでは、tpterm()が1つのスレッドで呼び出されると、同じコンテキスト内の他のすべてのスレッドは、ほとんどのATMI関数を呼び出しても異常終了し、tperrnoがTPEPROTOに設定されるような状態になります。このような無効なコンテキスト状態で使用できる関数と使用できない関数のリストについては、「C言語アプリケーション・トランザクション・モニター・インタフェースの紹介」を参照してください。無効なコンテキスト状態(TPINVALIDCONTEXT)のスレッドがtpgetctxt()関数を呼び出した場合、tpgetctxt()によってコンテキストのパラメータがTPINVALIDCONTEXTに設定されます。

TPINVALIDCONTEXT状態を終了させるには、次の関数のどちらかを呼び出します。

TPNULLCONTEXTコンテキストまたは別の有効なコンテキストを設定したtpsetctxt()
tpterm()

TPINVALIDCONTEXTコンテキストを設定してtpsetctxt()を呼び出すことはできません。このような場合は、異常終了してtperrnoがTPEPROTOに設定されます。呼出し側とアプリケーションを関連させる必要がないtpsetunsol()以外のATMI関数をスレッドが呼び出すと、ATMI関数はNULLコンテキストで呼び出されたときと同じように動作します。非請求のスレッド通知を使用するクライアント・アプリーションは、tpterm()を明示的に呼び出して、非請求スレッドを終了する必要があります。

tpterm()呼出し後、スレッドはTPNULLCONTEXTコンテキスト状態になります。TPNULLCONTEXTコンテキストのスレッドで呼び出されるATMI関数の多くは、暗黙的なtpinit()を実行します。tpinit()の呼出しが成功するかどうかは、コンテキスト固有の問題やスレッド固有の問題ではなく、通常の要因によって決まります。

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

戻り値

シングルコンテキスト・アプリケーションで正常に終了すると、現在のコンテキストがTPNULLCONTEXT状態になります。

マルチコンテキストのアプリケーションで正常終了すると、呼出し側のスレッドはTPNULLCONTEXT状態になり、呼出し側のスレッドと同じコンテキスト内の他のスレッドはすべてTPINVALIDCONTEXT状態になります。後者のスレッドのコンテキスト状態は、引数contextをTPNULLCONTEXTか別の有効なコンテキストに設定してtpsetctxt()を実行すれば変更できます。

異常終了すると、tpterm()は呼出し側のプロセスを元のコンテキスト状態のままで -1を返し、tperrnoを設定してエラー条件を示します。

エラー

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

[`TPEPROTO`]

tpterm()が不正なコンテキストで呼び出されました(たとえば、呼出し側がサーバーであるなど)。

[`TPESYSTEM`]

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

[`TPEOS`]

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

tptypes(3c)

名前

tptypes() - 型付きバッファ情報を判別するルーチン

形式

#include <atmi.h> long tptypes(char *ptr, char *type, char *subtype)

説明

tptypes()は、その第1引数として、データ・バッファを指すポインタをとり、2番目と3番目の引数でそれぞれタイプとサブタイプを返します。ptrは、tpalloc()から得たバッファを指していなければなりません。typeとsubtypeがNULLでない場合、この関数は、そのバッファのタイプとサブタイプの名前をそれぞれ該当する文字配列に入れます。これらの名前が最大長であると(typeの場合は8、subtypeの場合は16)、この文字配列はNULLで終了しません。また、サブタイプが存在しない場合は、subtypeが指す配列にはNULL文字列が入ります。

なお、typeの場合は最初の8バイト、subtypeの場合は最初の16バイトが格納されます。

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

戻り値

正常終了の場合、tptypes()はバッファのサイズを返します。

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

エラー

エラーが発生すると、tptypes()はtperrnoを次のいずれかの値に設定します。

[`TPEINVAL`]

無効な引数が与えられた(たとえば、ptrがもともと\% tpalloc()から得たバッファを指していない場合など)。

[`TPEPROTO`]

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

[`TPESYSTEM`]

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

[`TPEOS`]

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

tpunadvertise(3c)

名前

tpunadvertise() - サービス名の公開解除を行うルーチン

形式

#include <atmi.h> 
int tpunadvertise(char *svcname)

説明

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

tpunadvertise()は、該当サーバー(または、呼出し側のMSSQセットを共有するサーバー・セット)に対して通知されたサービスとしてsvcnameを削除します。svcnameにはNULLまたはNULL文字列("")は指定できません。また、svcnameは127文字以下で指定する必要があります。(「UBBCONFIG(5)」の*SERVICESの項を参照)。これ以上の長さの名前でも受け付けられますが、127文字に切り詰められます。このため、切り詰められた名前が他のサービス名と同じにならないよう、注意が必要です。

戻り値

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

エラー

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

[`TPEINVAL`]

svcnameがNULLまたはNULL文字列("")である場合。

[`TPENOENT`]

svcnameがサーバーによって公開されていない場合。

[`TPEPROTO`]

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

[`TPESYSTEM`]

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

[`TPEOS`]

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

tpunsubscribe(3c)

名前

TPUNSUBSCRIBE() - イベントのサブスクリプションを削除します。

形式

#include <atmi.h> 
int tpunsubscribe(long subscription, long flags)

説明

呼出し側はtpunsubscribe()を使用して、Oracle Tuxedo EventBrokerのアクティブなサブスクリプションのリストからイベントのサブスクリプションまたはイベントのサブスクリプションの集合を削除します。subscriptionには、tpsubscribe()が返したイベントのサブスクリプションのハンドルを指定します。subscriptionをワイルドカード値の -1に設定すると、tpunsubscribe()が、呼出し側のプロセスが以前に行ったすべての非持続型のサブスクリプションを削除する指示になります。非持続型のサブスクリプションとは、tpsubscribe()のctlflagsパラメータにTPEVPERSISTビットを設定せずに行われたサブスクリプションのことです。持続タイプのサブスクリプションは、tpsubscribe()から返されたハンドルを使用することによってのみ削除できます。

ハンドル -1を指定すると、呼出し側のプロセスが行ったサブスクリプションのみを削除し、呼出し側が以前に起動されたときに行ったサブスクリプションは削除しないことに注意してください(たとえば、異常終了した後で再起動したサーバーでは、ワイルドカードを使用して以前のサーバーが行ったサブスクリプションを削除することはできません)。

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

`TPNOBLOCK`

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

`TPNOTIME`

`TPSIGRSTRT`

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

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

戻り値

tpunsubscribe()が成功して戻ると、tpurcode()にはイベント・ブローカのアクティブなサブスクリプションのリストから削除されたサブスクリプションの数(0または1以上)が指定されます。tpurcode()に1より大きな数が設定されるのは、ワイルドカードのハンドルを-1に指定した場合のみです。また、tpunsubscribe()が失敗して終了した場合にも、tpurcode()に1より大きな数が設定されることがあります(つまり、ワイルドカードのハンドルを指定して、イベント・ブローカがいくつかのサブスクリプションの削除に成功した後で、他のサブスクリプションを削除する際にエラーが発生したような場合です)。

失敗すると、tpunsubscribe()は-1を戻し、tperrnoを設定してエラー条件を示します。

エラー

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

[`TPEINVAL`]

無効な引数(たとえば、subscriptionに無効なサブスクリプションのハンドル)が指定されました。

[`TPENOENT`]

Oracle Tuxedoイベント・ブローカにアクセスできません。

[`TPETIME`]

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

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

[`TPEBLOCK`]

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

[`TPGOTSIG`]

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

[`TPEPROTO`]

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

[`TPESYSTEM`]

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

[`TPEOS`]

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

tputrace(3c)

名前

tputrace() - ユーザー定義のトレース情報のアプリケーション

形式

#include <atmi.h> int tputrace (char *trrec, int nest, char *category, char *funcname, int utrtype, va_list args)

説明

tputrace(3c)は、詳細なトレース出力情報(ATMI関数との間でやり取りする完全なユーザー・データの内容など)のモニターおよび取得方法を柔軟に設定できるユーザー定義のAPIで、この情報をどのように、またどこに出力するかを定義します。デフォルトでは、更新したり別にものに変更したりしないかぎり、tputrace()は、トレース・レコード情報をuserlog(3c)に出力します。

tputrace(3c)は、TMTRACEを指定した受信側utraceを指定することで排他的に呼び出されます。たとえば、TMTRACE=atmi:utraceです。utraceの受信側を指定すると、atmiトレース・カテゴリ・レコードに対してのみtputrace(3c)が自動的に呼び出されて出力されます。TMTRACEおよびutrace受信側の詳細は、『ファイル形式、データ記述、MIBおよびシステム・プロセス・リファレンス』の「tmtrace(5)」を参照してください。

tputrace(3c)の有効な引数は次のとおりです。

`trrec`

ユーザーによって定義されるトレース情報のレコード。ttrecは、tputrace(3c)の最初の引数として必ず指定されます。trrecをuserlogに出力すると、tmtrace(5)と同じ結果になります。

`nest`

ネストのレベルを定義します。tputrace(3c)出力行にインデントを追加する場合に使用します。

`category`

ATMI関数のカテゴリを「atmi」、「iatmi」、「xa」などと定義します。

`funcname`

関数名を定義します。たとえば、「tpcall」または「tconnect」です。

`utrtype`

tputrace(3c)をATMI関数の開始時または終了時に呼び出すかどうかを示します。開始時に呼び出すときは0、終了時に呼び出すときは1と設定します。

`args`

tputrace(3c)出力関数に渡す引数を定義します。これには、ATMI関数に渡されるユーザー・データまたはフラグが含まれます。「使用例」のtputrace()の実装例で、各ATMI関数の引数の一覧を示します。引数の一覧は、tmtrace(5)トレース情報出力でも参照できます。

Libutraceライブラリ

独立したTuxedoライブラリであるlibutraceは、tputrace()と組み合せて使用します。デフォルトのlibutraceは、Tuxedoシステム共有ライブラリ・ディレクトリ(UNIXの場合は$TUXDIR/lib、Windowsの場合は%TUXDIR%\bin)にインストールされます。

ユーザーは、独自のカスタムlibutraceライブラリを作成し、それを次のいずれかにインストールすることもできます。

Tuxedoシステム共有ライブラリ・ディレクトリ
Tuxedoアプリケーション・ディレクトリ(UNIXの場合は$APPDIR、Windowsの場合は%APPDIR%)

システム・ディレクトリにインストールされたカスタムlibutraceライブラリは、デフォルトlibutraceにかわって、マシン上のすべてのTuxedoクライアントおよびサーバーで使用されます。アプリケーション・ディレクトリにインストールされたカスタムlibutraceライブラリは、そのアプリケーションのクライアントおよびサーバーにのみ使用されます。

tputrace()を変更した場合には、libutraceライブラリを必ず再コンパイルしてTuxedo 9.0以上にリンクする必要があります。サンプルのtputrace()ソース・ファイルは、$TUXDIR/samples/atmi/libutraceディレクトリにあります。

「使用例」では、詳細なtputrace()のカスタマイズ方法を示します。

警告: デフォルトまたはカスタムのlibutraceライブラリは、BBLまたはWSLなどのシステム・サーバーを含むすべてのTuxedoアプリケーション・プロセスにロードされます。そのため、すべてのTuxedoシステム・サーバーは、libutraceのロードに多少のメモリーを消費します。デフォルトのlibutraceライブラリは非常に小さいため、メモリー消費は無視することができます。ただし、カスタムのlibutraceは、ユーザーが追加する機能の数によっては、多くのメモリー容量を消費する可能性があります。

例

この例は、Tuxedo simpappサンプル・プログラムのsimpclの実行に対する、ユーザー・レベルのトレース情報userlogの出力を示しています。

ユーザー・レベル・トレース情報をカスタマイズして出力するには、以下の操作を行う必要があります。

tputrace()を変更します。
libutraceライブラリを再コンパイルしてTuxedoにリンクします。

この例では、`TMTRACE=atmi:utrace`を指定した場合、ATMI関数に渡されるユーザー・データの内容とフラグがTuxedo userlogに書き込まれます。

リスト1 Simpappサンプルによるユーザー・レベル・トレース情報Userlogの出力

091206.HOST1!?proc.1560.1520.0: UTRAC:at:  } tpinit = 1
091206.HOST1!?proc.1560.1520.0: UTRAC:at:  { tpalloc("STRING", "", 7)
091206.HOST1!?proc.1560.1520.0: UTRAC:at:  } tpalloc = 0x86a8e8
091206.HOST1!?proc.1560.1520.0: UTRAC:at:  { tpalloc("STRING", "", 7)
091206.HOST1!?proc.1560.1520.0: UTRAC:at:  } tpalloc = 0x87fa20
091206.HOST1!?proc.1560.1520.0: UTRAC:at:  { tpcall(
091206.HOST1!?proc.1560.1520.0: UTRAC:at:      svc="TOUPPER"
091206.HOST1!?proc.1560.1520.0: UTRAC:at:      idata=(0x86a8e8){
091206.HOST1!?proc.1560.1520.0: UTRAC:at:        len=0
091206.HOST1!?proc.1560.1520.0: UTRAC:at:        type="STRING"
091206.HOST1!?proc.1560.1520.0: UTRAC:at:        value="abcdef"
091206.HOST1!?proc.1560.1520.0: UTRAC:at:      }
091206.HOST1!?proc.1560.1520.0: UTRAC:at:      odata=(0x12ff48){
091206.HOST1!?proc.1560.1520.0: UTRAC:at:        data=(0x87fa20){
091206.HOST1!?proc.1560.1520.0: UTRAC:at:          len=0
091206.HOST1!?proc.1560.1520.0: UTRAC:at:          type="STRING"
091207.HOST1!?proc.1560.1520.0: UTRAC:at:        }
091207.HOST1!?proc.1560.1520.0: UTRAC:at:        len=(0x12ff44)0
091207.HOST1!?proc.1560.1520.0: UTRAC:at:      }
091207.HOST1!?proc.1560.1520.0: UTRAC:at:      flags=<none>
091207.HOST1!?proc.1560.1520.0: UTRAC:at:    )
091207.HOST1!simpserv.760.2188.0: UTRAC:at:  { tpservice(
091207.HOST1!simpserv.760.2188.0: UTRAC:at:      svcinfo=(0x5e1518){
091207.HOST1!simpserv.760.2188.0: UTRAC:at:        name="TOUPPER"
091207.HOST1!simpserv.760.2188.0: UTRAC:at:        flags=<none>
091207.HOST1!simpserv.760.2188.0: UTRAC:at:        data=(0x602820){
091207.HOST1!simpserv.760.2188.0: UTRAC:at:          len=7
091207.HOST1!simpserv.760.2188.0: UTRAC:at:          type="STRING"
091207.HOST1!simpserv.760.2188.0: UTRAC:at:          value="abcdef"
091207.HOST1!simpserv.760.2188.0: UTRAC:at:        }
091207.HOST1!simpserv.760.2188.0: UTRAC:at:        cd=0
091207.HOST1!simpserv.760.2188.0: UTRAC:at:        appkey=0
091207.HOST1!simpserv.760.2188.0: UTRAC:at: cltid=(0x5e154c){1095811926,0,12,0}
091207.HOST1!simpserv.760.2188.0: UTRAC:at:      }
091207.HOST1!simpserv.760.2188.0: UTRAC:at:    )
091207.HOST1!simpserv.760.2188.0: UTRAC:at:    { tpreturn(
091207.HOST1!simpserv.760.2188.0: UTRAC:at:        rval=TPSUCCESS
091207.HOST1!simpserv.760.2188.0: UTRAC:at:        rcode=0
091207.HOST1!simpserv.760.2188.0: UTRAC:at:        data=(0x602820){
091207.HOST1!simpserv.760.2188.0: UTRAC:at:          len=0
091207.HOST1!simpserv.760.2188.0: UTRAC:at:          type="STRING"
091207.HOST1!simpserv.760.2188.0: UTRAC:at:          value="ABCDEF"
091207.HOST1!simpserv.760.2188.0: UTRAC:at:        }
091207.HOST1!simpserv.760.2188.0: UTRAC:at:        flags=<none>
091207.HOST1!simpserv.760.2188.0: UTRAC:at:      )
091207.HOST1!?proc.1560.1520.0: UTRAC:at:  } tpcall(
091207.HOST1!?proc.1560.1520.0: UTRAC:at:      ret=0
091207.HOST1!?proc.1560.1520.0: UTRAC:at:      odata=(0x12ff48){
091207.HOST1!?proc.1560.1520.0: UTRAC:at:        data=(0x881690){
091207.HOST1!?proc.1560.1520.0: UTRAC:at:          len=7
|091207.HOST1!?proc.1560.1520.0: UTRAC:at:          type="STRING"
091207.HOST1!?proc.1560.1520.0: UTRAC:at:          value="ABCDEF"
091207.HOST1!?proc.1560.1520.0: UTRAC:at:        }
091207.HOST1!?proc.1560.1520.0: UTRAC:at:        len=(0x12ff44)7
091207.HOST1!simpserv.760.2188.0: UTRAC:at:    } tpreturn [long jump]
091207.HOST1!?proc.1560.1520.0: UTRAC:at:      }
091207.HOST1!?proc.1560.1520.0: UTRAC:at:    )
091207.HOST1!?proc.1560.1520.0: UTRAC:at:  { tpfree(0x86a8e8)
091207.HOST1!?proc.1560.1520.0: UTRAC:at:  } tpfree
091207.HOST1!?proc.1560.1520.0: UTRAC:at:  { tpfree(0x881690)
091207.HOST1!?proc.1560.1520.0: UTRAC:at:  } tpfree
091207.HOST1!simpserv.760.2188.0: UTRAC:at:  } tpservice
091207.HOST1!?proc.1560.1520.0: UTRAC:at:  { tpterm()
091207.HOST1!?proc.1560.1520.0: UTRAC:at:  } tpterm = 1
091207.HOST1!?proc.1560.1520.-2: UTRAC:at:  { tpterm()
091207.HOST1!?proc.1560.1520.-2: UTRAC:at:  } tpterm = 1

戻り値

tmutrace(3c)は、正常に実行された場合に0、障害が発生した場合に-1を返します。

エラー

障害は、tputrace()ユーザー・レベルの実装/カスタマイズによって異なります。Tuxedo 9.0以上に付属のデフォルトtputrace()実装では、障害は発生しません。

tpxmltofml32(3c)

名前

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

形式

#include <fml32.h>
int tpxmltofml32 (char *xmlbufp, char *vfile, FBFR32 **fml32bufp, char **rtag, long flags)

説明

この関数は、XMLバッファをFML32バッファに変換するために使用します。次の引数を使用できます。

`xmlbufp`

この引数は、有効なXML型付きバッファ入力を指すポインタです。

`vfile`

この引数は、XML入力の検証に使用するXMLスキーマ・ファイルの完全修飾パス名です。この引数を使用するには、TPXPARSNSPACEフラグとTPXPARSDOSCHEフラグを設定する必要があります。TPXPARSNEVERフラグは設定しないでください。

`fml32bufp`

この引数は、入力XMLから作成されたFML32型付き出力バッファを指すポインタです。

`rtag`

この引数は、入力XMLドキュメントからルート要素名を格納するポインタです。

`flags`

この引数は、Xercesパーサー・クラスのTuxedo 9.xサブセットにマッピングするために、XMLからFML/FML32への変換に使用します(XercesParser 2.5ドキュメントを参照)。次に、Tuxedo 9.xで有効なXercesパーサーのflagsの一覧を示します。

`TPXPARSNEVER`

setValidationSchemeをVal_Neverに設定します。パーサーは、スキーマ検証エラーを報告しません。

`TPXPARSALWAYS`

setValidationSchemeをVal_Alwaysに設定します。パーサーは、スキーマ検証エラーを常に報告します。

注意: 同時に使用した場合、TPXPARSNEVERはTPXPARSALWAYSよりも優先されます。

`TPXPARSSCHFULL`

setValidationSchemaFullCheckingをtrueに設定します。このフラグを使用すると、完全なスキーマ制約チェックをオンまたはオフにできます。スキーマ検証が有効な場合にのみ機能します。オフにした場合は、部分的な制約チェックが実行されます。完全なスキーマ制約チェックには、多くの時間またはメモリーが必要なものもあります。現在、このオプションでは、微細な固有属性チェックと派生制約チェックを制御します。

`TPXPARSCONFATAL`

setValidationConstraintFatalをtrueに設定します。このフラグを使用すると、検証制約エラーが発生した場合のパーサーの動作を設定できます。trueに設定した場合、パーサーは、検証エラーを致命的として処理し、getExitOnFirstFatalErrorの状態に従って終了します。falseに設定した場合は、エラーを報告し、処理を続行します。

`TPXPARSNSPACE`

setDoNamespacesをtrueに設定します。このフラグを使用すると、パーサーによるネームスペースの処理を有効または無効にできます。trueに設定した場合、パーサーは、NameSpace仕様で指定したすべての制約とルールを適用します。

`TPXPARSDOSCH`

setDoSchemaをtrueに設定します。このフラグを使用すると、パーサーによるスキーマの処理を有効または無効にできます。falseに設定した場合、パーサーは、見つかったスキーマを処理しません。

注意:

trueに設定した場合は、ネームスペースの処理もオンになっている必要があります。

`TPXPARSEREFN`

setCreateEntityReferencNodesをfalseに設定します。このフラグを使用すると、生成中のDOMツリーでパーサーがエンティティ参照ノードを作成するかどうかを指定できます。このフラグがtrueの場合、パーサーは、DOMツリーにEntityReferenceノードを作成します。EntityReferenceノードとその子ノードは読取り専用です。このフラグがfalseの場合、EntityReferenceノードは作成されません。エンティティの代替テキストが、エンティティ参照ノードの子として追加されるか、所定の参照の位置に挿入されます。

`TPXPARSNOEXIT`

setExitOnFirstFatalErrorをfalseに設定します。このフラグを使用すると、最初に致命的なエラーが発生した場合のパーサーの動作を設定できます。trueに設定した場合、パーサーは最初の致命的なエラーで終了します。falseに設定した場合は、エラーを報告し、処理を続行します。

`TPXPARSNOINCWS`

setIncludeIgnorableWhitespaceをfalseに設定します。このフラグを使用すると、無視できる余白をテキスト・ノードとして検証パーサーに含めるかどうかを指定できます。非マークアップ・テキストを常に含む非検証パーサーには無効です。

falseに設定すると、無視可能な余白は破棄され、テキスト・ノードはDOMツリーに追加されません。

`TPXPARSCACHESET`

setcacheGrammarFromParseをtrueに設定します。このフラグを使用すると、XMLドキュメントを解析する際の文法のキャッシュを有効または無効にできます。trueに設定すると、パーサーは、結果の文法を以降の解析で使用するためにキャッシュします。フラグをtrueに設定した場合、Useキャッシュ文法フラグもtrueに設定されます。

`TPXPARSCACHERESET`

resetCachedGrammarPoolをリセットします。ドキュメントのベクトル・プールをリセットし、関連するすべてのメモリーをシステムに解放します。

DOMパーサーでドキュメントを解析する際に、DOMツリー用に割り当てられたすべてのメモリーがDOMドキュメントに関連付けられます。

同じDOMパーサー・インスタンスを使用して複数の解析を実行する場合、複数のDOMドキュメントが生成され、ベクトル・プールに保存されます。すべてのドキュメント(およびそれに付随するすべての割当て済メモリー)は、パーサー・インスタンスが破棄されるまで削除されません。

これらのDOMドキュメントが不要になったときにDOMパーサー・インスタンスをまだ破棄しない場合は、このメソッドを呼び出すと、ドキュメントのベクトル・プールをリセットして、割り当てられたすべてのメモリーをシステムに解放することができます。解析中に(たとえば、段階的な解析などで)このメソッドを呼び出すと、エラーになります。

戻り値

成功した場合、tpxmltofml32()は0を返します。この関数は、エラー発生時に-1を返し、tperrnoを設定してエラー条件を示します。

エラー

この関数は、次の原因により異常終了する可能性があります。

[`TPEINVAL`]

fml32bufpまたはxmlbufpのどちらかが有効な型付きバッファではありません。あるいは、パーサーが入力を認識できません。

[`TPESYSTEM`]

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

[`TPEOS`]

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

tpxmltofml(3c)

名前

tpxmltofml() - XMLデータをFMLバッファに変換

形式

#include <fml.h>
int tpxmltofml (char *xmlbufp, char *vfile, FBFR **fmlbufp, char **rtag, long flags)

説明

この関数は、XMLデータをFMLバッファに変換するために使用します。次の引数を使用できます。

`xmlbufp`

この引数は、有効なXML型付きバッファ入力を指すポインタです。

`vfile`

`fmlbufp`

この引数は、入力XMLから作成されたFML型付き出力バッファを指すポインタです。

`rtag`

この引数は、入力XMLドキュメントからルート要素名を格納するポインタです。

`flags`

`TPXPARSNEVER`

setValidationSchemeをVal_Neverに設定します。パーサーは、スキーマ検証エラーを報告しません。

`TPXPARSALWAYS`

setValidationSchemeをVal_Alwaysに設定します。パーサーは、スキーマ検証エラーを常に報告します。

注意: 同時に使用した場合、TPXPARSNEVERはTPXPARSALWAYSよりも優先されます。

`TPXPARSSCHFULL`

`TPXPARSCONFATAL`

`TPXPARSNSPACE`

`TPXPARSDOSCH`

注意:

trueに設定した場合は、ネームスペースの処理もオンになっている必要があります。

`TPXPARSEREFN`

`TPXPARSNOEXIT`

`TPXPARSNOINCWS`

falseに設定すると、無視可能な余白は破棄され、テキスト・ノードはDOMツリーに追加されません。

`TPXPARSCACHESET`

`TPXPARSCACHERESET`

resetCachedGrammarPoolをリセットします。ドキュメントのベクトル・プールをリセットし、関連するすべてのメモリーをシステムに解放します。

DOMパーサーでドキュメントを解析する際に、DOMツリー用に割り当てられたすべてのメモリーがDOMドキュメントに関連付けられます。

戻り値

正常終了の場合、tpxmltofml()は値0を返します。エラーが発生した場合は、-1を返し、tperrnoを設定してエラー条件を示します。

エラー

この関数は、次の原因により異常終了する可能性があります。

`[TPEINVAL]`

fml32bufpまたはxmlbufpのどちらかが有効な型付きバッファではありません。あるいは、パーサーが入力を認識できません。

[`TPESYSTEM`]

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

[`TPEOS`]

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

TRY(3c)

名前

TRY() - 例外復帰インタフェース

形式

#include <texc.h>
 
TRY
try_block 
[  CATCH(exception_name) handler_block] ...  
[CATCH_ALL handler_block] 
ENDTRY  
 
TRY 
try_block 
FINALLY 
finally_block 
ENDTRY  
 
RAISE(exception_name)  
RERAISE  
 
/* declare exception */ 
EXCEPTION exception_name;  
 
/* initialize address (application) exception */
EXCEPTION_INIT(EXCEPTION exception_name)  
 
/* intialize status exception (map status to exception */ 
exc_set_status(EXCEPTION *exception_name, long status)  
 
/* map status exception to status */ 
exc_get_status(EXCEPTION *exception_name, long *status)  
 
/* compare exceptions */ 
exc_matches(EXCEPTION *e1, EXCEPTION *e2)  
 
/* print error to stderr */ 
void exc_report(EXCEPTION *exception)

説明

TRY/CATCHインタフェースは、ステータス変数(たとえば、errnoやRPCオペレーションで返されるステータス変数)を使用せずに例外を処理する機能を提供します。これらのマクロはtexc.hに定義されています。

TRYのtry_blockはCまたはC++の宣言文とステートメントのブロックであり、このブロック内で例外が発生します(例外の発生と関係のないコードはtry_blockの前、あるいは後に配置します)。TRY/ENDTRYの対により、例外のスコープ、つまり例外を検出するコード・リージョンが構成されます(C言語のスコーピングとは異なります)。これらのスコープはネストすることができます。例外が発生すると、例外を処理するためのアクション(CATCHまたはCATCH_ALLクローズ)、あるいはスコープを完結するためのアクション(FINALLYクローズ)に対応するアクティブなスコープを検索することにより、エラーがアプリケーションにレポートされます。スコープが例外処理を行えない場合には、そのスコープは終了し次の上位レベルで例外が生成されます(例外スコープのスタックをアンワインドします)。実行は、処理が行われた箇所の後から再開します。エラーが発生した箇所から実行を再開することはありません。いずれのスコープでも例外が処理されない場合には、プログラムは終了します(userlog(3c)とabort(3)を呼び出すことにより、メッセージがログに書き込まれます)。

CATCH (exception_name) handler_blockは、存在しなくても複数回記述してもかまいません。各handler_blockはCまたはC++の宣言文またはステートメントであり、対応する例外(exception_name)の処理を行います(通常、障害からリカバリするためのアクションが指定されます)。例外がtry_block内のステートメントで発生した場合には、その例外に対応する最初のCATCHクローズが実行されます。

CATCHまたはCATCH_ALL handler_block内では、現レベルの例外はEXCEPTIONポインタTHIS_CATCHにより参照できます(たとえば、例外値に基づくロジックや、例外値の出力など)。

例外がいずれのCATCHクローズでも処理できない場合には、CATCH_ALLクローズが実行されます。デフォルトではCATCHまたはCATCH_ALLクローズで処理される例外に対しては、それ以上のアクションは取られません。CATCH_ALLクローズが存在しない場合には、try_blockが他のtry_blockにネストされているものと想定し、次の上位のtry_blockで例外が発生します。ANSI Cコンパイラを使用した場合には、ハンドラ・ブロック内で使用されるレジスタと自動変数にvolatile属性を付加して宣言しなければなりません(setjmp/longjmpを使用するブロックの場合も同様です)。また、例外を発生する関数からの出力パラメータと戻り値は、不明であることに注意してください。

CATCHまたはCATCH_ALL handler_block内では、現レベルの例外はRERAISE文により、次の上位のレベルに伝播されます(例外が再度発生します)。RERAISE文は、handler_blockのスコープ内(つまりhandler_blockにより呼び出された関数内ではありません)になければなりません。検出はできますが、完全には処理できない例外はすべて出し直さなければなりません。ほとんどの場合、ハンドラはすべての例外を処理するようには書かれていないため、CATCH_ALLハンドラは例外を再度発生させる必要があります。アプリケーションは、例外が該当するスコープで発生し、ハンドラ・ブロックが適切な処理を行って該当するステータスを変更するように書かれなければなりません(たとえば、ファイルのオープン中に例外が発生した場合には、そのレベルの例外関数は、オープンされていないファイルをクローズしてはいけません)。

例外は、RAISE (exception_name)ステートメントを使用してどこででも発生させることができます。このステートメントにより、例外は現在のtry_blockから伝播を開始して、処理が行われる上位レベルに到達するまで出し直されます。

FINALLYクローズは、例外の発生に関係なく、try_blockの後で実行されるコードの終局ブロックを指定するのに使用します。例外はtry_block内で発生した場合には、finally_blockが実行された後で出し直されます。このクローズは、終局コードを重複して使用しないように、つまりCATCH_ALLクローズ内とENDTRYの後で二度繰り返して使用しないようにするためのものです。このクローズは通常、クリーンアップ作業を行い、例外の発生に関係なく(つまりブロックでの正常終了と異常終了の両方で)スコープがアンワインドする際にインバリアント(たとえば、共有データ、ロック)をリストアするのに使用します。FINALLYクローズは、同じtry_blockに対してはCATCHやCATCH_ALLクローズと一緒に使用することはできません。try_blockをネストして使用します(「形式」の項を参照)。

TRYブロックを終了するには、ENDTRYステートメントを使用しなければなりません。このステートメントは、例外が処理されコンテキストがクリーンアップされたことを確かめるために実行するコードを含んでいます。try_blockやhandler_block、finally_blockには、return、ローカルではないjump、あるいはENDTRYに到達せずにブロックを出る手法(goto()、break()、continue()、longjmp()など)を含めてはいけません。

このインタフェースは、RPCオペレーションからの例外を処理するために提供されています。ただしこのインタフェースは、すべてのアプリケーションで使用することのできる汎用のインタフェースです。例外は、EXCEPTIONの形式で宣言されます(これは複雑なデータ・タイプで、long integerのようには使用できません)。2種類の例外があります。どちらも同じ方法で宣言されますが、初期化の方法は異なります。

1種類の例外を使用してアプリケーション例外を定義します。EXCEPTION_INIT()マクロを呼び出して初期化します。例外のアドレスはaddress例外内の値として格納されます。この値は単一のアドレス空間内でのみ有効であり、例外が自動変数の場合には変更されることに注意してください。このためaddress例外は静的変数あるいは外部変数として宣言し、自動変数あるいはレジスタ変数として宣言すべきではありません。exc_get_status()マクロは、address例外では -1となります。この例外でexc_set_status()マクロを使用するとstatus例外となります。

exc_matchesマクロは、2つの例外を比較するのに使用します。同一であるためには、どちらの例外も同じタイプであり、同じ値を持たなければなりません(つまり、status例外に対しては同じステータス値を持つか、address例外に対しては同じアドレスを持ちます)。この比較は、上記のCATCHクローズで使用されます。

ステータス例外が発生した場合の通常の処理は、ステータス値を表示するか、より好ましい方法としてはステータス値が何であるかを示す文字列を表示することです。文字列を標準エラー出力に表示するのであれば、文字列を1回の操作で表示できるようにstatus例外へのポインタを付加して関数exc_report()を呼び出します。

CATCH_ALL 
{
 exc_report(THIS_CATCH);
}
ENDTRY

文字列に対して他の処理を行う場合には(たとえば、エラーをユーザー・ログに出力する)、exc_get_status()をTHIS_CATCHで使用し、ステータス値を取得できます(THIS_CATCHはEXCEPTIONに対するポインタであり、EXCEPTION自体ではありません)。dce_error_inq_text()を使用して、ステータス値の文字列を取得することができます。

CATCH_ALL 
{
  unsigned long status_to_convert;  
  unsigned char error_text[200];
  int status;  
 
  exc_get_status(THIS_CATCH,status_to_convert); 
  dce_error_inq_text(status_to_convert, error_text, status); 
  userlog(“%s”, (char *)error_text);  
}
ENDTRY

注意: マルチスレッドのアプリケーション中のスレッドは、TPINVALIDCONTEXTを含め、どのコンテキスト状態で実行していても、TRY/CATCHインタフェースを呼び出すことができます。

例外とステータス復帰をいつ使用するか

RPCオペレーションのステータスは、各オペレーションごとにステータス変数を定義することにより決定できます([comm_status]と[fault_status]パラメータは、属性構成ファイルで定義されます)。ステータス復帰インタフェースは、X/Open RPC仕様で提供される唯一のインタフェースです。fault_status属性は、不適切なパラメータ、リソース不足、コーディング・エラーなどによりサーバー上で発生したエラーが、補助的なステータス引数や戻り値でレポートされることを示しています。同様にcomm_status属性は、RPCコミュニケーション障害が補助的なステータス引数や戻り値でレポートされることを示します。ステータス値を利用する処理は、各コールごとに起こり得るエラーに対して指定されたリカバリを行う(コールごとの)きめ細かいエラー処理と、障害の時点での再試行が必要な場合にはうまく機能します。欠点としては、コールがローカルなものであってもリモートなものであっても、いずれの場合にも透過性がない点が挙げられます。リモート・コールには追加のステータス・パラメータ、あるいはvoidのかわりにステータスの戻り値が必要になります。従ってアプリケーションでは、ローカルと分散コード間で調整を行うプロシージャ宣言が必要です。

TRY/CATCH例外復帰インタフェースは、OSF/DCE環境からのアプリケーション移植性のためにも提供されています。このインタフェースは、すべての環境で利用できるものではありません。しかし、プロシージャ宣言をローカルと分散コード間で調整する必要がないという利点があり、既存のインタフェースを保持できます。各プロシージャ・コールは固有の障害チェックやリカバリ・コードを持つ必要がなく、エラー・チェッキングを簡素化できます。あるレベルでエラー処理が行えない場合には、プログラムは、「エラーが検出されたが修正可能である」などのシステム・エラー・メッセージを出力して終了します(メッセージを省略すると、エラー・チェッキングはより簡単になります)。例外は、大まかな例外処理を行う場合には有用です。

組込み例外

表15に示す例外は、この例外インタフェースで使用するために組み込まれている例外です。最初のTRYクローズはシグナル・ハンドラを設定し、以下にリストされたシグナル(無視されることがなく、補足可能なもの)を補足します。その他の例外はDCE対応のプログラムでの移植性のためにのみ定義されたものです。

表15 組込み例外
例外	説明
`exc_e_SIGBUS`	処理できない`SIGBUS`シグナルが発生しました。
`exc_e_SIGEMT`	処理できない`SIGEMT`シグナルが発生しました。
`exc_e_SIGFPE`	処理できない`SIGFPE`シグナルが発生しました。
`exc_e_SIGILL`	処理できない`SIGILL`シグナルが発生しました。
`exc_e_SIGIOT`	処理できない`SIGIOT`シグナルが発生しました。
`exc_e_SIGPIPE`	処理できない`SIGPIPE`シグナルが発生しました。
`exc_e_SIGSEGV`	処理できない`SIGSEGV`シグナルが発生しました。
`exc_e_SIGSYS`	処理できない`SIGSYS`シグナルが発生しました。
`exc_e_SIGTRAP`	処理できない`SIGTRAP`シグナルが発生しました。
`exc_e_SIGXCPU`	処理できない`SIGXCPU`シグナルが発生しました。
`exc_e_SIGXFSZ`	処理できない`SIGXFSZ`シグナルが発生しました。
`pthread_e_badparam`
`pthread_e_defer_q_full`
`pthread_e_existence`
`pthread_e_in_use`
`pthread_e_nostackmem`
`pthread_e_nostack`
`pthread_e_signal_q_full`
`pthread_e_stackovf`
`pthread_e_unimp`
`pthread_e_use_error`
`exc_e_decovf`
`exc_e_exquota`
`exc_e_fltdiv`
`exc_e_fltovf`
`exc_e_fltund`
`exc_e_illaddr`
`exc_e_insfmem`
`exc_e_intdiv`
`exc_e_intovf`
`exc_e_nopriv`
`exc_e_privinst`
`exc_e_resaddr`
`exc_e_resoper`
`exc_e_subrng`
`exc_e_uninitexc`

名前の後に_eが付加された同じ例外コードが定義されています(たとえば、exc_e_SIGBUSはexc_SIGBUS_eとも定義されています)。同等のステータス・コードが同様な名前で定義されていますが、_e_は_s_に変更されています(たとえば、exc_e_SIGBUSはexc_s_SIGBUSステータス・コードと同等です)。

注意事項

OSF/DCEでは、ヘッダー・ファイルはexc_handling.hと命名されますが、Oracle Tuxedo ATMIシステムのヘッダー・ファイルはtexc.hです。同じソース・ファイルでDCEとOracle Tuxedo ATMIシステムの例外処理を両方使用することはできません。また1つのプログラム内では、シグナル例外の処理はDCEかOracle Tuxedo ATMIシステムのいずれか一方でしか行えません。

サンプル

例外を使用するC言語のソース・ファイルを以下に示します。

#include <texc.h>  
 
EXCEPTION badopen_e;                      /* declare exception for bad open() */
 
doit(char *filename)  
{
  EXCEPTION_INIT(badopen_e);              /* initialize exception */
  TRY  get_and_update_data(filename);     /* do the operation */
  CATCH(badopen_e)                        /* exception - open() failed */
     fprintf(stderr, “Cannot open %s\en”, filename); 
  CATCH_ALL                               /* handle other errors */
     /* handle rpc service not available, ... */
     exc_report(THIS_CATCH)  
   ENDTRY
}
/*
 * Open output file
 * Get the remote data item 
 * Write out to file 
 */
get_and_update_data(char *filename)
{
  FILE *fp;
  if ((fp == fopen(filename)) == NULL) /* open output file */
    RAISE(badopen_e);                  /* raise exception */
  TRY
    /* in this block, file is opened successfully -
     * use associated FINALLY to close file  
     */
      long data;
      /*  
       * Execute RPC call - exceptions are raised to the calling
       * function, doit()
       */
      data = remote_get_data();
      fprintf(fp, “%ld\en”, data);
  FINALLY
    /* Whether or not exceptions are raised, close the file */
     fclose(fp);
  ENDTRY
}

tuxgetenv(3c)

名前

tuxgetenv() - 環境名に対して値を返す

形式

#include <atmi.h>  
char *tuxgetenv(char *name)

説明

tuxgetenv()は、環境リストからname=valueという形式の文字列を探し、その文字列が見つかった場合に、現在の環境内のvalueを指すポインタを返します。文字列が見つからなかった場合は、NULLポインタを返します。

この関数は、Oracle Tuxedo ATMIがサポートされる、異なるプラットフォーム間で使用する環境変数に対して、移植可能なインタフェースを提供します。プラットフォームには、通常は環境変数を持たないプラットフォームも含まれます。

tuxgetenvは大文字と小文字を区別することに注意してください。

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

戻り値

文字列のポインタが存在する場合、tuxgetenv()はそのポインタを返します。ポインタが存在しない場合、tuxgetenv()はNULLポインタを返します。

移植性

MS Windowsでは、この関数によって、アプリケーションとダイナミック・リンク・ライブラリとの間で環境変数を共有できるようになります。Oracle Tuxedo ATMIワークステーションDLLは、付加された各アプリケーションの環境コピーを保持します。この関連付けられた環境およびコンテキスト情報は、tpterm()がWindowsアプリケーションから呼び出されると無効になります。環境変数の値は、アプリケーション・プログラムがtpterm()を呼び出した後で変更できます。

Windows環境では、大文字の変数名を使用することをお薦めします(tuxreadenv()はすべての環境変数名を大文字に変換します)。

tuxgetmbaconv(3c)

名前

tuxgetmbaconv() - プロセス環境で環境変数TPMBACONVの値を取得

形式

#include <atmi.h>
extern int tperrno;

int
tuxgetmbaconv(long flags)     /* Get TPMBACONV info */

説明

この関数は、TPMBACONVのステータスを取得するために使用します。tuxgetnombaconv()関数は、アプリケーション開発者が、型付きバッファ・スイッチの自動変換機能がオフになっているかどうかをチェックするために使用します。デフォルトでは、TPMBACONVは設定されず、自動変換機能が使用されます。

引数flagsは現在使用されていないため、0に設定します。

戻り値

tuxgetnombaconv()は、TPMBACONVが設定されている場合はMBAUTOCONVERSION_ONを戻し、TPMBACONVが設定されていない場合はMBAUTOCONVERSION_OFFを戻します。

tuxgetmbenc(3c)

名前

tuxgetmbenc() - プロセス環境で環境変数TPMBENCのコード・セットのエンコード名を取得

形式

#include <atmi.h>
extern int tperrno;

int
tuxgetmbenc(char *enc_name, long flags)

説明

この関数は、環境変数TPMBENCに保持されているコードセットのエンコード名を取得するために使用します。この環境変数は、MBSTRING型付きバッファを作成する際に、デフォルトのコードセットのエンコード名として使用されます。新しいメッセージの取出しが可能になると、tpsetmbenc()関数を使用してデフォルトのエンコード名をリセットしたり設定解除したりできます。

引数enc_nameには、この関数の正常終了時に、環境変数TPMBENCの値が入ります。このポインタには、エンコード名のコピー先として十分な大きさを確保しておく必要があります。

引数flagsは現在使用されていないため、0に設定します。

戻り値

正常終了の場合、tuxgetmbenc()は0を返します。エラーが発生した場合は0以外の値を返します。

tuxputenv(3c)

名前

tuxputenv() - 環境の値を変更、または値を環境に追加する

形式

#include <atmi.h> int tuxputenv(char *string)

説明

stringは、name=valueという形式の文字列を指します。tuxputenv()は、既存の環境変数を変更するか新しい環境変数を作成して、環境変数名の値がvalueと等しくなるようにします。どちらの場合も、stringによって指された文字列は環境変数の一部になります。

注意: tuxputenv()では大文字と小文字が区別されます。

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

戻り値

tuxputenv()は、malloc()を介して拡張環境のための十分な領域を取得できなかった場合にゼロでない整数を返します。領域を取得できた場合はゼロを返します。

移植性

MS Windowsでは、この関数によって、アプリケーションとダイナミック・リンク・ライブラリとの間で環境変数を共有できるようになります。Oracle Tuxedo ATMIシステムのワークスレーションDLLは、付加された各アプリケーションの環境コピーを保持します。この関連付けられた環境およびコンテキスト情報は、tpterm()がWindowsアプリケーションから呼び出されると無効になります。環境変数の値は、アプリケーション・プログラムがtpterm()を呼び出した後で変更できます。

DOS、Windows、およびOS/2環境では、大文字の変数名を使用することをお薦めします(tuxreadenv()はすべての環境変数名を大文字に変換します)。

tuxreadenv(3c)

名前

tuxreadenv() - ファイルから環境へ変数を追加する

形式

#include <atmi.h> 
int tuxreadenv(char *file, char *label)

説明

tuxreadenv()は環境変数を含むファイルを読み込み、プラットフォームから独立して環境変数を環境に追加します。変数はtuxgetenv()を使用して利用でき、tuxputenv()を使用して再設定できます。

環境ファイルの形式は、次のとおりです。

各行の先頭のスペースまたはタブ文字は無視され、次の点では考慮されません。
環境に挿入する変数を含む行は次の形式です。

variable=value

または

set variable=value

ここで、variableは、先頭がアルファベット文字またはアンダースコア文字で、全体が英数字またはアンダースコア文字のみからなる文字列です。また、valueには改行文字を除くすべての文字を使用できます。

value内で、${env}という形式の文字列は、環境内にすでにある変数を使用して展開されます。前方参照はサポートされておらず、値が設定されていない場合、変数は空の文字列に置き換えられます。円マーク(¥)を使用して、ドル記号およびそれ自体をエスケープすることができます。その他すべてのシェルのクォートおよびエスケープのメカニズムは無視され、展開されたvalueがそのまま環境に入れられます。
スラッシュ(/)、シャープ(#)、またはエクスクラメーション・マーク(!)で始まる行は、コメントとして扱われ、無視されます。これらのコメント文字、左角括弧、アルファベット文字またはアンダースコア文字以外の文字で始まる行は、将来の用途のため予約されています。使用法は未定義です。
ファイルは、ラベルとして動作する、左角カッコ(「)で始まる行によってセクションごとに区切られます。ラベルは、31文字を超えると切り詰められます。ラベルの形式は次のとおりです。

[label]

labelは、上記のvariableと同じ規則(無効なlabel値を持つ行は無視される)に従います。

ファイルの先頭と最初のラベルの間の変数行は、すべてのラベルの環境(つまりグローバル・セクション)に挿入されます。他の変数は、ラベルが、アプリケーション用に指定したラベルに一致する場合にのみ、その環境に挿入されます。ラベル[]はグローバル・セクションを示します。

fileがNULLの場合、デフォルトのファイル名が使用されます。固定のファイル名は次のとおりです。

DOS、Windows、OS2、NT: C:\TUXEDO\TUXEDO.ENV MAC:システム環境設定ディレクトリのTUXEDO.ENV NETWARE: SYS:SYSTEM\TUXEDO.ENV POSIX: /usr/tuxedo/TUXEDO.ENVまたは/var/opt/tuxedo/TUXEDO.ENV

labelがNULLの場合、グローバル・セクション内の変数だけが環境に挿入されます。labelが他の値の場合、グローバル・セクションの変数と、labelに一致するセクション内の変数が環境に入れられます。

エラー・メッセージは、メモリー障害が発生した場合、NULLでないファイル名が存在しない場合、またはNULLでないラベルがない場合は、userlog()に出力されます。

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

例

環境ファイルの例を次に示します。

TUXDIR=/usr/tuxedo [application1] ;これはコメントです /*これはコメントです*/ #これはコメントです //これはコメントです FIELDTBLS=app1_flds FLDTBLDIR=/usr/app1/udataobj [application2] FIELDTBLS=app2_flds FLDTBLDIR=/usr/app2/udataobj

戻り値

tuxreadenv()は、malloc()を介して拡張環境のための十分な領域を取得できなかった場合か、NULLでない名前を持つファイルをオープンできず読み取ることができない場合に、ゼロ以外の整数を戻します。それ以外の場合、tuxreadenv()はゼロを戻します。

移植性

DOS、Windows、OS/2、およびNetWare環境では、tuxreadenv()がすべての環境変数名を大文字に変換します。

tuxsetmbaconv(3c)

名前

tuxsetmbaconv() - プロセス環境で環境変数TPMBACONVの値を設定

形式

#include <atmi.h>
extern int tperrno;

int
tuxsetmbaconv(int onoff, long flags)     /* Set TPMBACONV */

説明

この関数は、環境変数TPMBACONVの設定またはリセットに使用します。デフォルトでは、TPMBACONVは設定されず、自動変換機能が使用されます。

引数onoffがMBAUTOCONVERSION_OFFの場合、TPMBACONVが設定解除され、自動変換が無効になります。MBAUTOCONVERSION_ONの場合、TPMBACONVが設定され、型付きバッファでのコードセットのマルチバイト・データの自動変換が有効になります。

引数flagsは現在使用されていないため、0に設定します。

戻り値

正常終了の場合、tuxsetnombaconv()は0を返します。エラーが発生した場合は0以外の値を返します(たとえば、引数onoffが定義済の値のいずれかでない場合、-1を返します)。

tuxsetmbenc(3c)

名前

tuxsetmbenc() - プロセス環境で環境変数TPMBENCのコード・セットのエンコード名を設定

形式

#include <atmi.h>
extern int tperrno;

int
tuxsetmbenc(char *enc_name, long flags)

説明

この関数は、環境変数TPMBENCに保持されているコードセットのエンコード名を設定またはリセットするために使用します。この環境変数は、MBSTRING型付きバッファを作成する際に、デフォルトのコードセットのエンコード名として使用されます。新しいメッセージの取出しが可能になると、tpsetmbenc()関数を使用してデフォルトのエンコード名をリセットしたり設定解除したりできます。

引数enc_nameは、コードセットの識別に使用するエンコード名です。

引数flagsは現在使用されていないため、0に設定します。

戻り値

正常終了の場合、tuxsetmbenc()は0を返します。エラーが発生した場合は0以外の値を返します。

tuxthrputenv(3c)

名前

tuxthrputenv() - 現在のスレッドの環境変数を変更または追加します。

形式

#include <atmi.h> int tuxthrputenv(char *string)

説明

stringは、name=valueという形式の文字列を指します。tuxthrputenv()は、既存の環境変数を変更するか新しい環境変数を作成して、環境変数名の値がvalueと等しくなるようにします。どちらの場合も、stringによって指された文字列は環境変数の一部になります。

この関数は、Oracle Tuxedo ATMIがサポートされる、異なるプラットフォーム間で使用する環境変数に対して、移植可能なインタフェースを提供します(プラットフォームには、通常は環境変数を持たないプラットフォームも含まれます)。これにより、マルチスレッド・アプリケーションのスレッドが独自の環境変数を使用できるようになります。

tuxthrputenvが機能するのは、tuxgetenv()によって読み取られる場合のみです。getenvが使用されると、tuxthrputenvは失敗します。

注意: tuxthrputenv()では大文字と小文字が区別されます。tuxputenvで設定された値をオーバーライドします。

戻り値

tuxthrputenv()は、malloc()を介して拡張環境のための十分な領域を取得できなかった場合にゼロでない整数を返します。領域を取得できた場合はゼロを返します。

移植性

MS Windowsでは、tuxthrputenv()によって、アプリケーションとダイナミック・リンク・ライブラリとの間で環境変数を共有できるようになります。Oracle Tuxedo ATMIシステムのワークスレーションDLLは、付加された各アプリケーションの環境コピーを保持します。この関連付けられた環境およびコンテキスト情報は、tpterm()がWindowsアプリケーションから呼び出されると無効になります。環境変数の値は、アプリケーション・プログラムがtpterm()を呼び出した後で変更できます。

DOS、Windows、およびOS/2環境では、大文字の変数名を使用することをお薦めします(tuxreadenv()はすべての環境変数名を大文字に変換します)。

tx_begin(3c)

名前

tx_begin() - グローバル・トランザクションを開始します。

形式

#include <tx.h> 
int tx_begin(void)

説明

tx_begin()は、呼出し側の制御スレッドをトランザクション・モードにする際に使用します。呼出し側のスレッドは、トランザクションを開始する前に、リンクされているリソース・マネージャがオープンしている(tx_open()を介して)ことを、まず第1に確実にしなければなりません。呼出し側がすでにトランザクション・モードにある場合、またはtx_open()が呼び出されていない場合には、tx_begin()は([TX_PROTOCOL_ERROR]を返して)異常終了します。

トランザクション・モードに入ると、呼出し側のスレッドは、現在のトランザクションを完了させるために、tx_commit()またはtx_rollback()を呼び出さなければなりません。トランザクションの連鎖に関連する条件によっては、トランザクションの開始に明示的にtx_begin()を呼び出す必要がないこともあります。詳細は、tx_commit()およびtx_rollback()を参照してください。

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

選択可能なセットアップ

tx_set_transaction_timeout()

戻り値

tx_begin()は、正常終了時には、負数ではない戻り値TX_OKを返します。

エラー

次の条件の場合、tx_begin()は異常終了し、次のいずれかの負の値を返します。

[`TX_OUTSIDE`]

呼出し側の制御スレッドが、1つ以上のリソース・マネージャを利用して、グローバル・トランザクションの外部で現在作業中であるため、トランザクション・マネージャは、グローバル・トランザクションを開始できません。このような作業がすべて完了してからでなければ、グローバル・トランザクションは開始できません。ローカル・トランザクションについての呼出し側の状態は、変更されません。

[`TX_PROTOCOL_ERROR`]

この関数が不正なコンテキストで呼び出されました(たとえば、呼出し側がすでにトランザクション・モードにある場合)。トランザクション・モードに関する呼出し側の状態は変更されません。

[`TX_ERROR`]

トランザクション・マネージャまたは1つ以上のリソース・マネージャが、新しいトランザクションの開始において一時的エラーを検出しました。このエラーが返された場合は、呼出し側はトランザクション・モードにありません。エラーの正確な性質がログ・ファイルに書き込まれます。

[`TX_FAIL`]

トランザクション・マネージャまたは1つ以上のリソース・マネージャが、致命的エラーを検出しました。このエラーでは、トランザクション・マネージャまたは1つ以上のリソース・マネージャ、あるいはその両方は、アプリケーションのために作業を行うことができなくなります。このエラーが返された場合は、呼出し側はトランザクション・モードにありません。エラーの正確な性質がログ・ファイルに書き込まれます。

警告

XA準拠のリソース・マネージャがグローバル・トランザクションに含まれるようにするには、そのリソース・マネージャが正常にオープンされている必要があります(詳細については、「tx_open(3c)」を参照してください)。X/Open TXインタフェースとX-Windowシステムは、いずれも型XIDを定義します。同一のファイルでX-WindowコールとTXコールの両方を使用することはできません。

tx_close(3c)

名前

tx_close() - リソース・マネージャ・セットをクローズする

形式

#include <tx.h> 
int tx_close(void)

説明

tx_close()は、移植性の高い方法でリソース・マネージャ・セットをクローズします。これにより、トランザクション・マネージャが呼び出されて、リソース・マネージャ固有の情報がトランザクション・マネージャ固有の方法で読み取られ、この情報が呼出し側にリンクされているリソース・マネージャに渡されます。

tx_close()は、呼出し側がリンクしているリソース・マネージャをすべてクローズします。この関数は、リソース・マネージャ固有のクローズ呼出しのかわりに使用されるため、アプリケーション・プログラムは、移植性を損う危険性のある呼出しを使用することがなくなります。リソース・マネージャは終了の内容がそれぞれで異なるため、個々のリソース・マネージャをクローズするために必要な情報をリソース・マネージャごとに通知する必要があります。

tx_close()は、アプリケーションの制御スレッドがグローバル・トランザクションに関与する必要がなくなったときに呼び出してください。呼出し側がトランザクション・モードにあると、tx_close()は([TX_PROTOCOL_ERROR]を返して)異常終了します。したがって、現在のトランザクションに関与しない制御スレッドがあっても、リソース・マネージャは一切クローズされません。

tx_close()が正常に終了すると(TX_OK)、呼出し側のスレッドにリンクしているリソース・マネージャはすべてクローズされます。

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

戻り値

tx_close()は、正常終了時には、負数でない戻り値TX_OKを返します。

エラー

次の条件の場合、tx_close()は異常終了し、次のいずれかの負の値を返します。

[`TX_PROTOCOL_ERROR`]

この関数が不正なコンテキストで呼び出されました(たとえば、呼出し側がトランザクション・モードにある場合)。リソース・マネージャは一切クローズされません。

[`TX_ERROR`]

トランザクション・マネージャまたは1つ以上のリソース・マネージャが、一時的エラーを検出しました。エラーの正確な性質がログ・ファイルに書き込まれます。クローズ可能なリソース・マネージャはすべてクローズされます。

[`TX_FAIL`]

トランザクション・マネージャまたは1つ以上のリソース・マネージャが、致命的エラーを検出しました。このエラーでは、トランザクション・マネージャまたは1つ以上のリソース・マネージャ、あるいはその両方は、アプリケーションのために作業を行うことができなくなります。エラーの正確な性質がログ・ファイルに書き込まれます。

警告

X/Open TXインタフェースとX-Windowシステムは、いずれも型XIDを定義します。同一のファイルでX-WindowコールとTXコールの両方を使用することはできません。

tx_commit(3c)

名前

tx_commit() - グローバル・トランザクションをコミットします。

形式

#include <tx.h> 
int tx_commit(void)

説明

tx_commit()は、呼出し側の制御スレッドでアクティブなトランザクションの作業をコミットするために使用します。

transaction_control特性(「tx_set_transaction_control(3c)」を参照)がTX_UNCHAINEDである場合は、tx_commit()が終了すると、呼出し側はトランザクション・モードではなくなります。一方、transaction_control特性がTX_CHAINEDである場合は、tx_commit()が終了すると、呼出し側は、新しいトランザクションのためにトランザクション・モードのままになります(このページの「戻り値」および「エラー」の項を参照してください)。

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

選択可能なセットアップ

tx_set_commit_return()
tx_set_transaction_control()
tx_set_transaction_timeout()

戻り値

tx_commit()は、正常終了時には、負数でない戻り値TX_OKを返します。

エラー

次の条件の場合、tx_commit()は異常終了し、次のいずれかの負の値を返します。

[`TX_NO_BEGIN`]

現在のトランザクションは、正常にコミットされました。ただし、新しいトランザクションを開始できなかったので、呼出し側はトランザクション・モードではなくなりました。この戻り値はtransaction_control特性がTX_CHAINEDである場合のみ発生します。

[`TX_ROLLBACK`]

現在のトランザクションはコミットできず、ロールバックされました。また、transaction_control特性がTX_CHAINEDである場合には、新しいトランザクションが開始されます。

[`TX_ROLLBACK_NO_BEGIN`]

現在のトランザクションはコミットできず、ロールバックされました。また、新しいトランザクションを開始できなかったので、呼出し側はトランザクション・モードではなくなりました。この戻り値はtransaction_control特性がTX_CHAINEDである場合のみ発生します。

[`TX_MIXED`]

トランザクションのために行われた作業は、部分的にコミットされ、部分的にロールバックされました。また、transaction_control特性がTX_CHAINEDである場合には、新しいトランザクションが開始されます。

[`TX_MIXED_NO_BEGIN`]

トランザクションのために行われた作業は、部分的にコミットされ、部分的にロールバックされました。また、新しいトランザクションを開始できなかったので、呼出し側はトランザクション・モードではなくなりました。この戻り値はtransaction_control特性がTX_CHAINEDである場合のみ発生します。

[`TX_HAZARD`]

障害が原因で、トランザクションのために行われた作業は、部分的にコミットされ、部分的にロールバックされた可能性があります。また、transaction_control特性がTX_CHAINEDである場合には、新しいトランザクションが開始されます。

[`TX_HAZARD_NO_BEGIN`]

障害が原因で、トランザクションのために行われた作業は、部分的にコミットされ、部分的にロールバックされた可能性があります。また、新しいトランザクションを開始できなかったので、呼出し側はトランザクション・モードではなくなりました。この戻り値はtransaction_control特性がTX_CHAINEDである場合のみ発生します。

[`TX_PROTOCOL_ERROR`]

この関数が不正なコンテキストで呼び出されました(たとえば、呼出し側がトランザクション・モードにない場合)。トランザクション・モードについての呼出し側の状態は、変更されません。

[`TX_FAIL`]

警告

tx_info(3c)

名前

tx_info() - グローバル・トランザクション情報を返す

形式

#include <tx.h> int tx_info(TXINFO *info)

説明

tx_info()は、グローバル・トランザクション情報を、infoが指す構造体に返します。また、この関数は、呼出し側が現在トランザクション・モードにあるかどうかを示す値も返します。infoがNULL以外の値であれば、tx_info()は、infoが指すTXINFO構造体にグローバル・トランザクション情報を入れます。TXINFO構造体には次の要素があります。

XID                 xid;  
COMMIT_RETURN       when_return;
TRANSACTION_CONTROL transaction_control;
TRANSACTION_TIMEOUT transaction_timeout;  
TRANSACTION_STATE    transaction_state;

tx_info()がトランザクション・モードにおいて呼び出されると、xidに現在のトランザクションのブランチ識別子が、transaction_stateに現在のトランザクションの状態が入ります。呼出し側がトランザクション・モードにない場合は、xidにNULLのXIDが入ります(詳細はtx.hファイルを参照)。また、呼出し側がトランザクション・モードにあるかどうかに関係なく、when_return、transaction_controlおよびtransaction_timeoutに、commit_returnおよびtransaction_control特性の現在の設定、および秒単位のトランザクション・タイムアウト値が入ります。

返されるトランザクション・タイムアウト値は、次のトランザクション開始時に使用される設定を反映しています。したがって、この値は、呼出し側の現在のグローバル・トランザクションのタイムアウト値を反映しているわけではありません。現在のトランザクション開始後に行われたtx_set_transaction_timeout()の呼出しによって、この値が変更されていることがあるからです。

infoがNULLである場合は、TXINFO構造体は返されません。

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

戻り値

呼出し側がトランザクション・モードにある場合は、1を返します。呼出し側がトランザクション・モードにない場合は、0を返します。

エラー

次の条件の場合、tx_info()は異常終了し、次のいずれかの負の値を返します。

[`TX_PROTOCOL_ERROR`]

この関数が不正なコンテキストで呼び出されました(たとえば、呼出し側がまだtx_open()を呼び出していません)。

[`TX_FAIL`]

トランザクション・マネージャが致命的エラーを検出しました。このエラーでは、トランザクション・マネージャは、アプリケーションのために作業を行うことができなくなります。エラーの正確な性質がログ・ファイルに書き込まれます。

警告

同一のグローバル・トランザクション内では、後続のtx_info()呼出しは、XIDに同一のgtrid構成要素を示すことが保証されていますが、同一のbqual構成要素を示すことは必ずしも保証されません。X/Open TXインタフェースとX-Windowシステムは、いずれも型XIDを定義します。同一のファイルでX-WindowコールとTXコールの両方を使用することはできません。

tx_open(3c)

名前

tx_open() - リソース・マネージャ・セットを開く

形式

#include <tx.h> 
int tx_open(void)

説明

tx_open()は、移植性の高い方法でリソース・マネージャ・セットをオープンします。これにより、トランザクション・マネージャが呼び出されて、リソース・マネージャ固有の情報がトランザクション・マネージャ固有の方法で読み取られ、この情報が呼出し側にリンクされているリソース・マネージャに渡されます。

tx_open()はアプリケーションにリンクされているすべてのリソース・マネージャのオープンを試行します。この関数は、リソース・マネージャ固有のオープン呼出しのかわりに使用されるため、アプリケーション・プログラムは、移植性を損なう可能性のある呼出しを使用することがなくなります。リソース・マネージャは開始の内容がそれぞれで異なるため、個々のリソース・マネージャをオープンするために必要な情報をリソース・マネージャごとに通知する必要があります。

tx_open()がTX_ERRORを返した場合は、リソース・マネージャは一切オープンされません。tx_open()がTX_OKを返した場合は、いくつかまたはすべてのリソース・マネージャがオープンされています。オープンされなかったリソース・マネージャは、アプリケーションによってアクセスされるときに、リソース・マネージャ固有のエラーを返します。tx_open()は、制御スレッドがグローバル・トランザクションに関与する前に、正常に終了していなければなりません。

tx_open()が正常に終了した後で(tx_close()を呼び出す前に)、tx_open()を呼び出すことができます。このような後続の呼出しは、正常終了しますが、トランザクション・マネージャは、リソース・マネージャの再オープンは一切行いません。

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

戻り値

tx_open()は、正常終了時には、負数でない戻り値TX_OKを返します。

エラー

次の条件の場合、tx_open()は異常終了し、次のいずれかの負の値を返します。

[`TX_ERROR`]

トランザクション・マネージャまたは1つ以上のリソース・マネージャが、一時的エラーを検出しました。リソース・マネージャは一切オープンされません。エラーの正確な性質がログ・ファイルに書き込まれます。

[`TX_FAIL`]

トランザクション・マネージャまたは1つ以上のリソース・マネージャが、致命的エラーを検出しました。tpinit()を呼び出さずにセキュリティの掛かったアプリケーション(SECURITY APP_PW)の中でtx_openを呼び出すと、TX_FAILが出されます。このエラーでは、トランザクション・マネージャまたは1つ以上のリソース・マネージャ、あるいはその両方は、アプリケーションのために作業を行うことができなくなります。エラーの正確な性質がログ・ファイルに書き込まれます。

警告

tx_rollback(3c)

名前

tx_rollback() - グローバル・トランザクションのロールバック

形式

#include <tx.h> 
int tx_rollback(void)

説明

tx_rollback()は、呼出し側の制御スレッドでアクティブなトランザクションの作業をロールバックします。

transaction_control特性(「tx_set_transaction_control(3c)」を参照)がTX_UNCHAINEDである場合は、tx_rollback()が終了すると、呼出し側はトランザクション・モードではなくなります。一方、transaction_control特性がTX_CHAINEDである場合は、tx_rollback()が終了すると、呼出し側は新しいトランザクションのためにトランザクション・モードのままになります(このページの「戻り値」および「エラー」の項を参照してください)。

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

選択可能なセットアップ

tx_set_transaction_control()
tx_set_transaction_timeout()

戻り値

tx_rollback()は、正常終了時には、負数ではない戻り値TX_OKを返します。

エラー

次の条件の場合、tx_rollback()は異常終了し、次のいずれかの負の値を返します。

[`TX_NO_BEGIN`]

現在のトランザクションはロールバックしました。ただし、新しいトランザクションを開始できなかったので、呼出し側はトランザクション・モードではなくなりました。この戻り値はtransaction_control特性がTX_CHAINEDである場合のみ発生します。

[`TX_MIXED`]

[`TX_MIXED_NO_BEGIN`]

[`TX_HAZARD`]

[`TX_HAZARD_NO_BEGIN`]

[`TX_COMMITTED`]

トランザクションのために行われた作業は、ヒューリスティックにコミットされました。また、transaction_control特性がTX_CHAINEDである場合には、新しいトランザクションが開始されます。

[`TX_COMMITTED_NO_BEGIN`]

トランザクションのために行われた作業は、ヒューリスティックにコミットされました。また、新しいトランザクションを開始できなかったので、呼出し側はトランザクション・モードではなくなりました。この戻り値はtransaction_control特性がTX_CHAINEDである場合のみ発生します。

[`TX_PROTOCOL_ERROR`]

この関数が不正なコンテキストで呼び出されました(たとえば、呼出し側がトランザクション・モードにない場合)。

[`TX_FAIL`]

警告

tx_set_commit_return(3c)

名前

tx_set_commit_return() - commit_return特性の設定

形式

#include <tx.h> 
int tx_set_commit_return(COMMIT_RETURN when_return)

説明

tx_set_commit_return()は、when_returnで指定されている値にcommit_return特性を設定します。この特性は、呼出し側に制御を返すことに関するtx_commit()の動作に影響します。tx_set_commit_return()は、その呼出し側がトランザクション・モードかどうかにかかわらず呼び出されます。この設定は、引き続き呼び出されるtx_set_commit_return()で変更されるまで有効です。

この特性の初期設定は、TX_COMMIT_COMPLETEDです。

when_returnの有効な設定を次に示します。

`TX_COMMIT_DECISION_LOGGED`

このフラグは、2フェーズ・コミット・プロトコルの第1フェーズによってコミットの決定が記録された後、第2フェーズが終了する前に、tx_commit()が終了することを示します。このフラグを設定すると、tx_commit()の呼出し側に高速で応答することができます。しかし、トランザクションがヒューリスティックな結果を得る危険があります。この場合、tx_commit()の戻りコードから呼出し側がこの状況を知ることはできません。正常な状態では、第1フェーズの間にコミットすることを約束している参加リソースは、第2フェーズでコミットします。ただし、特殊な状況(たとえば、長時間継続するネットワークまたはノードの障害)では、フェーズ2が完了できない可能性があり、ヒューリスティックな結果が生成されることがあります。

`TX_COMMIT_COMPLETED`

このフラグは、2フェーズのコミット・プロトコルが完全に終了した後、tx_commit()が返ることを示しています。この設定により、tx_commit()の呼出し側は、トランザクションにヒューリスティックな結果が発生したか、または発生した可能性があるかを示す戻り値を調べることができます。

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

戻り値

正常終了の場合、tx_set_commit_return()は、負でない戻り値TX_OKを返します。

エラー

次の条件の場合、commit_returnは、commit_return特性の設定を変更することなく、次の3つの負の値のうちの1つを返します。

[`TX_EINVAL`]

when_returnが、TX_COMMIT_DECISION_LOGGEDまたはTX_COMMIT_COMPLETEDのいずれでもありません。

[`TX_PROTOCOL_ERROR`]

この関数が不正なコンテキストで呼び出されました(たとえば、呼出し側がまだtx_open()を呼び出していません)。

[`TX_FAIL`]

警告

tx_set_transaction_control(3c)

名前

tx_set_transaction_control() - transaction_control特性を設定する

形式

#include <tx.h> 
int tx_set_transaction_control(TRANSACTION_CONTROL control)

説明

tx_set_transaction_control()は、controlで指定されている値にtransaction_control特性を設定します。この特性は、tx_commit()およびtx_rollback()のどちらかが、これらの呼出し側に返る前に、新しいトランザクションを開始するかどうかを決めます。tx_set_transaction_control()は、アプリケーション・プログラムがトランザクション・モードかどうかにかかわらず呼び出すことができます。この設定は、引き続き後に呼び出されるtx_set_transaction_control()で変更されるまで有効です。

この特性の初期設定は、TX_UNCHAINEDです。

controlの有効な設定を次に示します。

`TX_UNCHAINED`

このフラグは、tx_commit()およびtx_rollback()が、これらの呼出し側に返る前に新しいトランザクションを開始してはならないことを示しています。呼出し側は新しいトランザクションを開始するためにtx_begin()を出さなければなりません。

TX_CHAINED

このフラグは、tx_commit()およびtx_rollback()が、これらの呼出し側に返る前に新しいトランザクションを開始することを示しています。

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

戻り値

正常終了の場合、tx_set_transaction_control()は、負でない戻り値TX_OKを返します。

エラー

次の条件の場合、tx_set_transaction_control()は、transaction_control特性の設定を変更することなく、次に示す3つの負の値のうちの1つを返します。

[`TX_EINVAL`]

controlが、TX_UNCHAINEDまたはTX_CHAINEDのいずれでもありません。

[`TX_PROTOCOL_ERROR`]

この関数が不正なコンテキストで呼び出されました(たとえば、呼出し側がまだtx_open()を呼び出していません)。

[`TX_FAIL`]

警告

tx_set_transaction_timeout(3c)

名前

tx_set_transaction_timeout() - transaction_timeout特性を設定する

形式

#include <tx.h> 
int tx_set_transaction_timeout(TRANSACTION_TIMEOUT timeout)

説明

tx_set_transaction_timeout()は、timeoutで指定されている値にtransaction_timeout特性を設定します。この値は、トランザクションが、トランザクション・タイムアウトになる前に終了しなければならない時間間隔、すなわちアプリケーションが、tx_begin()を呼び出してからtx_commit()またはtx_rollback()を呼び出すまでの時間間隔を指定します。tx_set_transaction_timeout()は、呼出し側がトランザクション・モードかどうかにかかわらず呼び出すことができます。tx_set_transaction_timeout()が、トランザクション・モードで呼び出される場合、新しいタイムアウト値は、次のトランザクションが開始されないと有効になりません。

transaction_timeoutの初期値は0 (タイムアウトなし)です。

timeoutは、トランザクションが、トランザクション・タイムアウトを受けないでいられる秒数を指定します。この値は、最大値、すなわちシステムによって定義されているlongまでの任意の値に設定されます。timeout値が0の場合、タイムアウト機能は働きません。

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

戻り値

正常終了の場合、tx_set_transaction_timeout()は、負でない戻り値TX_OKを返します。

エラー

次の条件の場合、tx_set_transaction_timeout()は、transaction_timeout特性の設定を変更することなく、次に示す3つの負の値のうちの1つを返します。

[`TX_EINVAL`]

指定したタイムアウト値が無効です。

[`TX_PROTOCOL_ERROR`]

関数の呼出し方法が不適切です。たとえば、呼出し側がtx_open()を呼び出す前に呼び出されました。

[`TX_FAIL`]

警告

userlog(3c)

名前

userlog() - Oracle Tuxedo ATMIシステムの中央イベント・ログへのメッセージの書込み

形式

#include “userlog.h” 
extern char *proc_name; 
 
int userlog (format [ ,arg] . . .) 
char *format;

説明

userlog()は、printf(3S)スタイルのフォーマット指定を受け付け、固定出力ファイル(Oracle Tuxedo ATMIシステムの中央イベント・ログ)を使用します。

中央イベント・ログは通常のUNIXファイルです(パス名は次のように構成されます)。シェル変数ULOGPFXが設定されると、その値がファイル名の接頭辞として使用されます。ULOGPFXが設定されていない場合は、ULOGが使用されます。この接頭辞は最初にuserlog()が呼び出されたときに判別されます。userlog()が呼び出されるたびに、日付が判別され、月、日、年がmmddyyの形式で接頭辞に連結されてファイルの名前が設定されます。プロセスが初めてユーザー・ログに書き込む場合、対応するOracle Tuxedo ATMIシステムのバージョンを示す追加のメッセージを書き込みます。

このあと、メッセージがそのファイルに追加されます。この方法の場合、それ以降の日にuserlog()をプロセスが呼び出すと、メッセージは別のファイルに書き込まれます。

メッセージは、呼出しプロセスの時刻(hhmmss)、システム名、プロセス名、呼出しプロセスのプロセスID、スレッドID、コンテキストIDからなるタグと一緒にログ・ファイルに書き込まれます。このタグの末尾にはコロン(:)が付けられます。プロセスの名前は、外部変数proc_nameのパス名から取られます。proc_nameの値がNULLであると、得られる名前は?procに設定されます。

Oracle Tuxedo ATMIシステムがログ・ファイルに出すエラー・メッセージの先頭には、ユニークな識別用文字列が次の形式で付けられます。

<catalog>:number>:

この文字列は、メッセージ文字列を含む国際版カタログの名前にメッセージ番号を加えたものです。規則によれば、Oracle Tuxedo ATMIシステムのエラー・メッセージは1度のみ使用されるようになっているため、この文字列はソース・コード内の位置を一意に識別します。

format指定の最後の文字が改行文字でない場合、userlog()は改行文字を1つ追加します。

シェル変数ULOGDEBUGの先頭文字が1またはyであると、userlog()に送られるメッセージはfprintf(3S)関数により呼出しプロセスの標準エラー出力にも書き出されます。

userlog()は、Oracle Tuxedo ATMIシステムが各種のイベントを記録するために使用します。

このuserlogの機構は、いかなるデータベースのトランザクション記録機構からも完全に独立しています。

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

環境変数

`ULOGMILLISEC`

タイムスタンプ・メッセージが秒ではなくミリ秒間隔でuserlogファイルに送るオン/オフ切替え環境変数。指定されない場合、デフォルトのタイムスタンプは秒です。ULOGMILLISECがオンの場合、サーバーは再起動します。
例: ULOGMILLISEC=Y

`ULOGRTNSIZE`

userlogローテーション・ファイル・サイズを指定するオン/オフ切替え環境変数。デフォルトのローテーション・ファイル・サイズは2GBです。ULOGRTNSIZEがオンの場合、サーバーは再起動します。
例: ULOGRTNSIZE=1000000 (ファイル・サイズが1MBの場合)

ローテーションされたファイルは、filename.nnという構文で保存されます。
例: ULOG.083103.1、ULOG.083103.2 ... ULOG.083103.10など

注意: ULOGRTNSIZEを指定しなかった場合、ファイルのローテーションは行われません。

移植性

userlog()インタフェースは、UNIXシステムおよびMS-DOSオペレーティング・システムで利用できます。ログ・メッセージの一部として生成されるシステム名は、MS-DOSシステムでは利用できません。このため、MS-DOSシステムのシステム名としては、値PCを使用します。

サンプル

変数ULOGPFXが/application/logs/logに設定されている場合、およびuserlog()の最初の呼出しが1990年9月7日に行われた場合、作成されるログ・ファイルには/application/logs/log.090790という名前が付けられます。たとえば、

userlog(“UNKNOWN USER '%s' (UID=%d)”, usrname, UID);

上記のような呼出しが、プロセスIDが23431であるプログラムsecによりUNIXシステムが指定したm1上で4:22:14pmに出され、変数usrnameに文字列“sxx”,が含まれ、かつ変数UIDに整数123が指定されている場合、ログ・ファイルには次のような行が書き込まれます。

162214.m1!sec.23431: UNKNOWN USER 'sxx' (UID=123)

プロセスがトランザクション・モードのときにメッセージが中央イベント・ログに送られた場合、ユーザー・ログ・エントリのタグに追加の要素が加わります。これらの要素は、リテラルgtridと、それに続く3桁のlong型の16進整数で構成されます。これらの整数はグローバル・トランザクションをユニークに識別し、グローバル・トランザクション識別子と呼ばれます。この識別子は主に管理上の目的で使用されますが、中央イベント・ログでメッセージの先頭に付けられるタグの中に付けられます。前述のメッセージがトランザクション・モードで中央イベント・ログに書き出される場合、結果として得られるログ・エントリは次のようになります。

162214.logsys!security.23431: gtrid x2 x24e1b803 x239: UNKNOWN USER 'sxx' (UID=123)

シェル変数ULOGDEBUGの値がyであると、ログ・メッセージはプログラムsecurityの標準エラー出力にも書き出されます。

エラー

userlog()は、送信されるメッセージがstdio.hで定義されているBUFSIZより大きい場合にハングします。

診断

userlog()は、出力された文字数を返します。出力エラーがあった場合には、負の値を返します。出力エラーには、現在のログ・ファイルのオープンや書込みができないといったエラーがあります。ULOGDEBUGが設定されている場合、標準エラー出力への書込みができない場合は、エラーとはみなされません。

注意事項

アプリケーションでuserlog()メッセージを使用する場合には、アプリケーション・エラーをデバッグするのに有用なものだけを使用することをお薦めします。ログが情報であふれてしまうと、本来のエラーを検出するのが難しくなります。

Usignal(3c)

名前

Usignal() - Oracle Tuxedo ATMIシステム環境でのシグナル処理

形式

#include “Usignal.h” 
 
UDEFERSIGS() 
UENSURESIGS() 
UGDEFERLEVEL() 
URESUMESIGS() 
USDEFERLEVEL(level) 
 
int (*Usignal(sig,func)() 
int sig; 
int (*func)(); 
 
void Usiginit()

説明

Oracle Tuxedo ATMIシステム・ソフトウェアが提供する多くの機能は、共有メモリー内のデータ構造に並行アクセスする必要があります。共有データ構造にアクセスするプログラムはユーザー・モードで走るため、シグナルを使用して中断することができます。共有データ構造の一貫性を維持するためには、それらの構造にアクセスする類の操作が、UNIXシステムのシグナルを受け取っても中断されないことが重要です。ここで説明する関数は、ほとんどの一般的なシグナルに対する保護機構を提供するもので、Oracle Tuxedo ATMIシステムのコードの多くがその内部で使用します。また、これらの関数は、アプリケーション側で使用して、不用意にシグナルを受け取らないようにします。

このOracle Tuxedo ATMIシステムのシグナル処理パッケージは、重要なコード部ではシグナルの発行を遅らせる、という発想から生まれたものです。このため、シグナルは、それが受信されてもすぐには処理されません。Oracle Tuxedo ATMIシステムのルーチンはまず最初に送信されたシグナルを捕捉します。そのシグナルを処理しても安全であれば、そのシグナルに指定された処理が実行されます。シグナルが安全でないということが判明した場合には、そのシグナルの到着が通知されるだけで、重要なコード部が終了したことをユーザーが示すまでは、そのシグナルの処理は行われません。

マルチスレッド・プログラムでシグナルを使用することは可能ですが、使用しないことをお薦めします。ただし、シグナルを使用した場合には、マルチスレッドのアプリケーション中のスレッドは、TPINVALIDCONTEXTを含め、どのコンテキスト状態で実行していてもUsignal()の呼出しを発行できます。

シグナルの捕捉

rmopen()またはtpinit()を使用するユーザー・コードは、Usignal()関数を使用してシグナルを捕捉するようにします。Usignal()はUNIXのsignal()システム・コールのように機能しますが、例外としてUsignal()では最初に、内部ルーチンがシグナルを捕捉してから、ユーザー・ルーチンをディスパッチするように調整します。

シグナルの遅延とリストア

ここで説明する呼出しは、アプリケーション・コードでシグナルを後回しにする必要がある場合にのみ使用します。一般に、これらのルーチンは、不適切な場面でシグナルが到着しないようにするためにOracle Tuxedo ATMIシステムのルーチンが自動的に呼び出します。

シグナルを遅延またはリストアする前に、メカニズムを初期化する必要があります。初期化は、Oracle Tuxedo ATMIシステム・クライアントがtpinit()を呼び出したときに、Oracle Tuxedo ATMIシステムのクライアントとサーバーのために自動的に行われます。また、初期化は、アプリケーションがはじめにUsignal()呼び出すときに行われます。初期化は、Usiginit()を呼び出すことで明示的に行うことができます。

UDEFERSIGS()マクロは、重要なコード部分に入るときに使用してください。UDEFERSIGS()が呼び出された後、シグナルは保留状態になります。また、URESUMESIGS()マクロは、その重要な部分が終わる時点で呼び出すようにします。シグナル遅延スタックに注意してください。このスタックは、最初にゼロに設定されるカウンタを通して実現されます。UDEFERSIGS()への呼出しによってシグナルが遅延されると、カウンタの値が1大きくなります。URESUMESIGS()の呼出しによりシグナルが再開されると、カウンタの値は1小さくなります。カウンタがゼロ以外の値のときにシグナルが到着すると、そのシグナルの処理は後回しになります。シグナルが到着したときにカウンタがゼロであれば、そのシグナルはただちに処理されます。シグナルの再開により、カウンタがゼロになると(すなわち、再開の前のカウンタ値が1のとき)、その据置期間に到着したシグナルが処理されます。一般に、UDEFERSIGS()の呼出しは、URESUMESIGS()の呼出しと対で使用するようにします。

UDEFERSIGS遅延カウンタの値をインクリメントしますが、返す値はそのインクリメント前の値です。マクロUENSURESIGS()は、遅延カウンタを明示的にゼロに設定する(そして、据え置かれたシグナルを強制的に処理させる)ときに使用できます。この場合、ユーザーはUDEFERSIGS()とURESUMESIGS()の不一致が生じないようにする必要があります。

関数UGDEFERLEVEL()は遅延カウンタの現在の設定値を返します。マクロUSDEFERLEVEL(level)を使用すると、特定の遅延レベルを設定することができます。UGDEFERLEVEL()とUSDEFERLEVEL()は、setjmp/longjmpの状況で適切にカウンタを設定するときに便利です。つまり、setjmp()が呼び出されたときに、UGDEFERLEVEl()の呼出しによってカウンタの値を保存し、longjmp()が実行されたときにUSDEFERLEVEL()の呼出しによりカウンタ値をリストアする、という考え方です。

注意事項

Usignalは、SIGHUP、SIGINT、SIGQUIT、SIGALRM、SIGTERM、SIGUSR1およびSIGUSR2の各シグナルについて遅延処理を行います。その他すべてのシグナル番号に対する処理リクエストは、Usignal()により直接signaL()に渡されます。シグナルは非常に長い期間その処理が据え置かれることがあります。このため、シグナル遅延の間、シグナルの到着がすべてカウントされます。何回も到着する可能性のあるシグナルの処理が安全な場合、そのシグナルの処理ルーチンが繰り返し呼び出され、シグナルが到着した各シグナルが処理されます。各呼出しの前には、シグナルのデフォルト処理が行われます。つまり、安全なコードで連続して処理が行われる場合と同様に、据え置かれたシグナルが処理されるようにする、という考え方です。

一般に、ユーザーはsignal()とUsignal()の呼出しを同じシグナルに対して組み合せて使用するべきではありません。できれば、Usignal()を使用する方法をとることが推奨されます。これによって、常にシグナルの状態を知ることができるからです。それは、アプリケーションがOracle Tuxedo ATMIシステム・サービスでアラームを使用したい場合などには必要です。こうすることにより、Usiginit()は、シグナルの遅延メカニズムを初期化するために呼び出されなければなりません。次に、signal()を呼び出し、意図するシグナル用に、メカニズムを変更します。シグナルの遅延メカニズムをリストアするために、Usignal()をSIG_IGNで呼び出してから、再び、意図するシグナル処理関数で呼び出す必要があります。

シェル変数UIMMEDSIGSを使用すれば、シグナルの据置を変更することができます。この変数の値が次のように英字yで始まる場合、

UIMMEDSIGS=y

シグナルはUsignal()コードでインターセプトされません(したがって、据え置かれません)。このような場合、Usignal()の呼出しはただちにsignaL()に渡されます。

また、UsignalはDOSオペレーティング・システムの配下では役に立ちません。

ファイル

Usignal.h

Uunix_err(3c)

名前

Uunix_err() - UNIXシステム・コール・エラーの出力

形式

#include Uunix.h 
 
void Uunix_err(s) 
char *s;

説明

Oracle Tuxedo ATMIシステムの関数がUNIXシステム・コールを呼び出したときに、そのシステム・コールがエラーを検出すると、エラーが返されます。外部整数Uunixerr()が、そのエラーを返したシステム・コールを示す値(Uunix.hに定義されています)に設定されます。さらに、このシステム・コールは、errno()を失敗した理由を示す値(errno.hに定義されています)に設定します。

Uunix_err()関数は、Oracle Tuxedo ATMIシステムの関数の呼出し中に最後に検出したシステム・コールを示すメッセージを標準エラー出力に書き出します。この関数は引数(文字列)を1つとります。この関数はこの引数文字列に続いて、コロンと空白、失敗したシステム・コールの名前、失敗の理由、そして改行文字を書き出します。様々な利用形態を考慮して、この引数文字列には、エラーを起こしたプログラム名を入れます。システム・コールのエラー番号は外部変数Uunixerr()からとられ、そのエラーの理由はerrno()から取り込まれます。どちらの変数も、エラーが発生した時点で設定されます。これらの変数はエラーのない呼出しが行われたときにクリアされます。

メッセージの多彩な形式を単純化するため、次のようなメッセージ文字列の配列

extern char *Uunixmsg[];

が提供されます。Uunixerr()は、この表への索引として使用し、失敗したシステム・コールの名前を(改行文字なしで)取り込むことができます。

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

サンプル

#include Uunix.h 
extern int Uunixerr, errno;
 
  ..........  
   if((fd=open(“myfile”, 3, 0660)) == -1)

       { 
       Uunixerr = UOPEN;  
       Uunix_err(“myprog”);  
       exit(1); 
       }

ATMI C関数リファレンス

セクション3c - C関数

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

説明

通信パラダイム

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

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

メッセージ配信

メッセージの順序付け

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

ATMIトランザクション

TXトランザクション

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

トランザクション特性

エラー処理

タイムアウト

動的サービス公開

バッファ管理

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

非請求通知

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

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

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

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

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

ATMIの状態遷移

TXの状態遷移

関連項目

AEMsetblockinghook(3c)

名前

形式

説明

戻り値

エラー

[TPEPROTO]

移植性

注意事項

AEOaddtypesw(3c)

名前

形式

説明

戻り値

エラー

[TPEINVAL]

[TPESYSTEM]

移植性

注意事項

サンプル

関連項目

AEPisblocked(3c)

名前

形式

説明

戻り値

エラー

移植性

備考

関連項目

AEWsetunsol(3c)

名前

形式

説明

戻り値

エラー

[TPESYSTEM]

[TPEOS]

移植性

注意事項

関連項目

buffer(3c)

名前

形式

説明

ルーチンの詳細

_tminitbuf()

_tmreinitbuf

_tmuninitbuf

_tmpresend

_tmpostsend()

_tmpostrecv

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

[`TPEPROTO`]

[`TPEINVAL`]

[`TPESYSTEM`]

`[TPESYSTEM]`

`[TPEOS]`

[`TMPARENT`]

[`TMUSEIPTR`]

[`TMUSEOPTR`]

[`TMUSEIPTR`]

[`TMUSEOPTR`]

`std`および`dst`

`offset`

`start`/`time`,`end`/`time`

J`n`

`n`

M`m.n.d`