名前

userlog()−BEA Tuxedo ATMI システムの中央イベント・ログへのメッセージの書き込み

形式

#include “userlog.h” 
extern char *proc_name; 
 
int userlog (format [ ,arg] .. .) 
char *format;

機能説明

userlog() は、printf(3S) スタイルのフォーマット指定を受け付け、固定出力ファイル (BEA Tuxedo ATMI システムの中央イベント・ログ) を使用します。

中央のイベント・ログは通常の UNIX システムのファイルで、そのパス名は次のように構成されています。シェル変数 ULOGPFX が設定されている場合、その値がファイル名の接頭辞として使用されます。ULOGPFX が設定されていない場合は、ULOG が使用されます。この接頭辞は最初に userlog() が呼び出されたときに判別されます。userlog() が呼び出されるたびに、日付が判別され、月、日、年が mmddyy の形式で接頭辞に連結されてファイルの名前が設定されます。プロセスが初めてユーザ・ログに書き込む場合、対応する BEA Tuxedo ATMI システムのバージョンを示す追加のメッセージを書き込みます。

このあと、メッセージがそのファイルに追加されます。この方法の場合、それ以降の日に userlog() をプロセスが呼び出すと、メッセージは別のファイルに書き込まれます。

メッセージは、呼び出しプロセスの時刻 (hhmmss)、システム名、プロセス名、呼び出しプロセスのプロセス ID、スレッド ID、コンテキスト ID からなるタグと一緒にログ・ファイルに書き込まれます。このタグの末尾にはコロン (:) が付けられます。プロセスの名前は、外部変数 proc_name のパス名から取られます。proc_name の値が NULL であると、得られる名前は ?proc に設定されます。

BEA Tuxedo ATMI システムがログ・ファイルに出すエラー・メッセージの先頭には、一意の識別用文字列が次の形式で付けられます。

<catalog>:number>:

この文字列は、メッセージ文字列を収めている国際化されたメッセージ・カタログの名前にメッセージ番号を加えたものです。規則によれば、BEA Tuxedo ATMI システムのエラー・メッセージは一個所でのみ使用されるようになっているため、この文字列はソース・コード内の位置を一意に特定します。

format 指定の最後の文字が改行文字でない場合、userlog() は改行文字を 1 つ追加します。

シェル変数 ULOGDEBUG の先頭文字が 1 または y であると、userlog() に送られるメッセージは fprintf(3S) 関数により呼び出しプロセスの標準エラー出力にも書き出されます。

userlog() は、BEA Tuxedo ATMI システムが各種のイベントを記録するために使用します。

この userlog の機構は、BEA Tuxedo ATMI システムのトランザクション記録機構とは完全に独立しています。

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

移植性

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 に文字列 &dl“&dr”まれ、かつ変数 UID に整数 123 が指定されている場合、ログ・ファイルには次のような行が書き込まれます。

162214.m1!sec.23431:UNKNOWN USER 'sxx' (UID=123) 

プロセスがトランザクション・モードのときにメッセージが中央イベント・ログに送られた場合、ユーザ・ログ・エントリのタグに追加の要素が加わります。これらの要素は、リテラル gtrid と、それに続く 3 桁の long 型の 16 進整数で構成されます。これらの整数はグローバル・トランザクションを一意に示し、グローバル・トランザクション識別子と呼ばれます。この識別子は主に管理上の目的で使用されますが、中央イベント・ログでメッセージの先頭に付けられるタグの中に付けられます。前述のメッセージがトランザクション・モードで中央イベント・ログに書き出される場合、結果として得られるログ・エントリは次のようになります。

162214.logsys!security.23431:gtrid x2 x24e1b803 x239:UNKNOWN USER 'sxx' (UID=123) 

シェル変数 ULOGDEBUG の値が y であると、ログ・メッセージはプログラム security の標準エラー出力にも書き出されます。

エラー

userlog() は、送信されるメッセージが stdio.h で定義されている BUFSIZ より大きい場合にハングします。

診断

userlog() は、出力された文字数を返します。出力エラーがあった場合には、負の値を返します。出力エラーには、現在のログ・ファイルのオープンや書き込みができないといったエラーがあります。ULOGDEBUG が設定されている場合、標準エラー出力への書き込みができない場合は、エラーとは見なされません。

注意事項

アプリケーションで userlog() メッセージを使用する場合には、アプリケーション・エラーをデバッグするのに有用なものだけを使用するようにします。ログが情報であふれてしまうと、本来のエラーを検出するのが難しくなります。

関連項目

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