tpinit(3c)

名前

tpinit()-アプリケーションへの参加

形式

#include <atmi.h>
int tpinit(TPINIT *tpinfo)

機能説明

tpinit() は、クライアントが BEA Tuxedo ATMI システムのアプリケーションに参加するときに使用します。BEA Tuxedo ATMI システムのコミュニケーションあるいはトランザクション・ルーチンをクライアントが使用する前には、あらかじめクライアントは BEA Tuxedo ATMI システムのアプリケーションに参加しなければなりません。

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

マルチスレッド・クライアントの場合、TPINVALIDCONTEXT 状態のスレッドは tpinit() の呼び出しを発行できません。BEA 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 の文字数を超えてはなりません。MAXTIDENT は 30 字に定義されています。passwd は、アプリケーション・パスワードとの認証に使用される非暗号化形式のアプリケーション・パスワードです。一方通行の暗号化方式に関する UNIX システムの制限から、passwd は８文字までしか意味をもちません。grpname は、クライアントをリソース・マネージャ・グループ名と関連付けるときに使用します。grpname が長さ 0 の文字列として設定されている場合は、クライアントはリソース・マネージャに関連付けられず、デフォルトのクライアント・グループに含まれます。ワークステーション・クライアントの場合、この値は NULL 文字列 (長さが 0 の文字列) でなければなりません。grpname は ACL グループとは関連がないことに注意してください。

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

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

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

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

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

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

ネイティブ・クライアントの場合、新しい関連を作成するときに TUXCONFIG 環境変数の値を使ってアプリケーションを識別します。ワークステーション・クライアントの場合、新しい関連を作成するときに WSNADDR または WSENVFILE 環境変数の値を使ってアプリケーションを識別します。カレント・スレッドのコンテキストは、新しい関連に設定されます。

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

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

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

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

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

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

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

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

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

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

戻り値

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

エラー

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

相互運用性

tpchkauth() および、tpinit() の TPINIT タイプのバッファ引数に対する NULL 以外の値は、リリース 4.2 またはそれ以降を使用しているサイトでしか使用できません。

移植性

環境変数

警告

クライアントのシグナル通知は、必ずシステムによって行われるので、通知呼び出しの起動元がどこであっても、通知の動作は一貫しています。したがって、シグナル・ベースの通知を使用するには次の条件が必要です。

アプリケーション管理者の ID は、アプリケーション・コンフィギュレーションの一部として識別されます。

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

関連項目