4.71 vopfmt（）関数

機能説明

vopfmt（）関数は、“ラベル:エラー種別:メッセージテキスト”の形式でメッセージを作成し、そのメッセージを指定したstreamに出力するとともに、システム監視エージェントへメッセージを通知します。

ラベルの指定は、opsetlabel（）関数によって行います。ラベルが指定されない場合、“エラー種別:メッセージテキスト”の形式でメッセージが作成されます。

システム監視エージェント未起動時は、メッセージ一時保存ファイルに保存され、システム監視エージェント起動時に読み込まれます。

呼び出し形式

#include <stdarg.h>
#include <opfmt.h>
int vopfmt(FILE *stream, long flags, char *format, va_list ap);

パラメタ

stream:: 出力先のファイルポインタを指定します。streamにNULLを指定した場合は、システム監視エージェントだけに通知されます。

flags:

作成するメッセージの形式、メッセージカタログへのアクセスの有無、およびエラー種別を指定します。
flagsは複数指定できますが、以下の各グループから1つずつしか指定できません。

メッセージ作成形式フラグ:

どのようなメッセージを作成するか指定します。

MM_NOSTD:: “ラベル:エラー種別:メッセージテキスト”形式ではなく、メッセージテキストだけがメッセージとして通知されます。MM_NOSTDが指定された場合、エラー種別フラグは無視されます。

MM_STD:: “ラベル:エラー種別:メッセージテキスト”形式でメッセージが作成されます。メッセージ作成形式フラグが指定されない場合、省略値はMM_STDです。

カタログアクセスフラグ:【UNIX】

メッセージカタログからメッセージテキストの取り出しを行うか行わないかの指定をします。

MM_NOGET:: メッセージカタログからメッセージテキストの取り出しを行いません。formatに指定された文字列がそのままメッセージテキストとして使用されます。

MM_GET:: メッセージカタログからメッセージテキストの取り出しを行います。カタログアクセスフラグが指定されない場合、省略値はMM_GETです。

エラー種別フラグ:

作成されるエラーメッセージのエラー種別(重要度)を指定します。エラー種別フラグが指定されていない場合、省略値はMM_ERRORです。指定される値により、エラー種別と重要度は以下のようになります。

Windows版
指定するエラー種別フラグ
エラー種別
重要度
MM_HALT
HALT
最重要
MM_ERROR
ERROR
重要
MM_WARNING
WARNING
警告
MM_NOTICE
INFO
通知
MM_INFO
INFO
一般
UNIX版
指定するエラー種別フラグ
エラー種別
重要度
MM_HALT
停止
最重要
MM_ERROR
エラー
重要
MM_WARNING
警告
警告
MM_NOTICE
情報
通知
MM_INFO
情報
一般

指定するエラー種別フラグ	エラー種別	重要度
MM_HALT	HALT	最重要
MM_ERROR	ERROR	重要
MM_WARNING	WARNING	警告
MM_NOTICE	INFO	通知
MM_INFO	INFO	一般

指定するエラー種別フラグ	エラー種別	重要度
MM_HALT	停止	最重要
MM_ERROR	エラー	重要
MM_WARNING	警告	警告
MM_NOTICE	情報	通知
MM_INFO	情報	一般

format:

メッセージテキストを指定します。

【Windowsの場合】

メッセージテキストは、printf（）関数と同じ形式で指定します。メッセージテキストが決定できない場合は、メッセージテキスト文字列として、“Message not found!!\n”が使用されます。

args:: formatで指定した、printf形式のメッセージテキストに対し、必要な引数を指定します。formatの指定に対して、argsの数が多い場合は、余分なargsは無視されます。formatの指定に対してargsの数が少ない場合は、その結果は不定です。

ap:: va_startで初期化された可変個数引数リストです。

【UNIXの場合】

メッセージカタログの指定、および初期値のメッセージテキストをシステムが提供している、printf（）関数と同じ形式で指定します。システムが提供している、printf（）関数についての詳細は、printf（3s）のマニュアルページを参照してください。
formatには、以下の形式のようにコロン（:）でつないだ1つの文字列で指定します。

メッセージカタログを指定する場合
```
catalog:msgnum:deftext
```
初期値のメッセージカタログを指定する場合
```
:msgnum:deftext
```

catalog:: メッセージカタログ名を指定します。catalogは、14バイト以内の文字列を指定してください。これらの文字列には、NULL（\0）、スラッシュ（/）、およびコロン（:）は使用できません。
catalogはopsetcat（）関数で初期値を指定することができます。opsetcat（）関数でメッセージカタログが指定されている場合、catalogは省略することができます。ただし、msgnumの直前につくコロン（:）は省略してはいけません。opsetcat（）関数についての詳細は、“opsetcat（）関数”を参照してください。

msgnum:: catalogで指定したメッセージカタログの取り出したいメッセージテキスト番号を指定します。

deftext:: catalogで指定したカタログから、メッセージテキストが取り出せない場合の初期値のメッセージテキストを指定します。
環境変数LC_MESSAGES、またはLANGに設定されたロケールに、catalogで指定したメッセージカタログが存在しない場合、またはmsgnumが範囲外の場合、opfmt（）関数は、Cロケールからテキストを取り出そうとします。これに失敗すると、opfmt（）関数は、deftextをメッセージテキストとして使用します。formatが正しい形式で指定されず、メッセージテキストが決定できない場合は、メッセージテキスト文字列として、“Message not found!!\n”が使用されます。

args:: formatで指定した、printf形式のメッセージテキストに対し、必要な引数を指定します。formatの指定に対して、argsの数が多い場合は、余分なargsは無視されます。formatの指定に対してargsの数が少ない場合は、その結果は不定です。

ap:: va_startで初期化された可変個数引数リストです。詳細はシステムが提供しているstdarg（5）のマニュアルページを参照してください。
注意
“%”をメッセージテキストとして使用する場合は、2つ連続させて（“%%”）記述します。

参照

以下のシステム監視のAPIを参照してください。

復帰値

0以上:: 正常終了。通知したメッセージのバイト数。

-1: 異常終了。

API格納場所

“メッセージ作成のAPI”を参照してください。

注意事項

運用管理サーバでクラスタ待機系の監視を行っている場合、待機系のシステムからvopfmt関数を使用してメッセージを出力しても運用系システムでのメッセージ監視はできません。なお、待機系時に実行したvopfmt関数の結果は、APIを使用したアプリケーションを実行したシステムが運用系になったときにメッセージが通知されます。

UNIXの場合は、以下の点にも注意が必要です。

環境変数LC_MESSAGES、またはLANGに指定されたロケールを有効にするために、本関数の前にシステムが提供しているsetlocale（）関数を呼び出す必要があります。詳細は、setlocale（3C）のマニュアルページを参照してください。
使用できるメッセージカタログの形式は、システムが提供しているmkmsgsコマンドでフォーマットされたメッセージカタログです。メッセージカタログの作成方法の詳細については、システムが提供しているgettxt（3C）、mkmsgs（1）のマニュアルページを参照してください。
各パラメタは、メッセージの長さ(以下に示す文字列の長さの合計)が2047バイト以内になるように指定してください。これを超える場合、メッセージは先頭からの2047バイト分のみがSystemwalker Centric Managerに通知されます。
- ラベル (注1)
- エラー種別 (注2)
- メッセージ (注3)
注1)
flagsにMM_NOSTDを指定した場合
0です。
上記以外の場合
opsetlabel()関数でラベルを指定した場合は指定したラベルの長さ+2です。未指定の場合は0です。
注2)
flagsにMM_NOSTDを指定した場合
0です。
上記以外の場合
flagsにエラー種別フラグを指定した場合はエラー種別フラグに対応するエラー種別の長さ+2です。未指定の場合は8(デフォルトのエラー種別"エラー"の長さ+2)です。
注3)
flagsのカタログアクセスフラグにMM_NOGETを指定する場合
formatの長さです。
※formatが%で始まる書式を含む場合、書式を引数で置換した文字列の長さです。
flagsのカタログアクセスフラグ未指定またはMM_GETを指定する場合
opsetcat()関数またはformat内のcatalogで指定したメッセージカタログの中の、msgnum(メッセージテキスト番号)で指定したメッセージの長さです。
※メッセージが%で始まる書式を含む場合、書式を引数で置換した文字列の長さです。
※opsetcat()関数またはformat内のcatalogで有効なメッセージカタログ名を指定していない場合、またはmsgnumに範囲外のメッセージテキスト番号を指定した場合、format内のdeftextの長さです。

使用例

使用例を以下に示します。

opsetlabel("LABEL");
vopfmt(stderr, MM_INFO, "test:23:test message 1 －－%s\n",ap);

実行結果/出力形式

通知メッセージ

LABEL: INFO: test message 1 －－No such file or directory