4.5.4 運用操作API群を使用する上での注意事項

本APIとコマンドで競合が発生した場合の振る舞いを以下に説明します。

ワークユニット定義の削除(tddeldef/isdelwudefコマンド)
ワークユニットの停止(tdstopwu/isstopwuコマンド)
ワークユニットの定義変更(tdadddef/isaddwudefコマンド)
ワークユニットの活性変更(tdmodifywuコマンド)
サーバアプリケーションの多重度を変更(tdmodifyprocnumコマンド)
ワークユニット定義の追加(tdadddef/isaddwudefコマンド)
ワークユニットの起動(tdstartwu/isstartwuコマンド)

操作対象システムの追加（iscreatesysコマンド）
操作対象システムの削除（isdeletesysコマンド）

Interstage停止（isstopコマンド）

それぞれのケースに関して運用操作API群は以下の動作となります。運用操作API群を使用する場合は上記で説明した状態を変更するコマンドと競合して運用しないことを推奨します。

ワークユニット定義の削除

ワークユニット定義が削除された場合は、ワークユニットを指定する機能がエラーの詳細情報にISOP_ENOWUを設定します。最新の状態を獲得する必要があれば、ワークユニット名通知およびオブジェクト名通知APIを発行して最新の情報を獲得してください。

ワークユニットの停止

起動したワークユニットが停止しているかどうかを確認する場合は、ワークユニット情報通知APIを使用してください。tdstopwuコマンドまたはisstopwuコマンドの投入による停止、または、異常停止した状態も獲得することができます。

ワークユニットの定義変更・ワークユニットの活性変更

ワークユニット名通知、オブジェクト名通知APIでは常に最新の定義が獲得されます。

サーバアプリケーションの多重度を変更

サーバアプリケーションの多重度を動的に変更した場合、オブジェクト名通知APIで復帰する多重度は動的に変更する前の多重度を通知しますが、オブジェクト情報通知APIで復帰する多重度は動的に変更した最新の多重度を通知します。多重度を動的に変更した場合は、オブジェクト情報通知APIを使用して獲得してください。

ワークユニット定義の追加

ワークユニット定義を追加した場合は、ワークユニット名通知APIで定義されているワークユニット名をすべて取り出してください。

ワークユニットの起動

ワークユニットがtdstartwuコマンドまたはisstartwuコマンドで起動されていた場合は、ワークユニット情報通知APIでワークユニットの停止理由は通知されません。

操作対象システムの追加

操作対象システムを追加した場合は、システム名一覧通知API機能で生成されているシステム名をすべて取り出してください。

操作対象システムの削除

操作対象システムが削除された場合は、削除されたシステム名を指定してAPIを発行するとエラーの詳細情報にISOP_ENOSYSTEMが通知されます。最新の状態を獲得する必要があれば、システム名一覧通知APIを発行して、最新の情報を獲得してください。

Interstageの停止

操作対象システムが停止された場合は、システム情報通知を除く全機能がエラー情報の詳細情報にISOP_ESTPISが通知されます。

4.5.4.2 ワークユニットの起動/停止

  本APIによるワークユニットの停止には通常停止、同期停止および強制停止があります。
  通常停止でワークユニットを停止した場合、ワークユニットが通信中（クライアントと連携中）であるとエラー復帰（ISOP_EREQREJECT）します。ワークユニットを必ず停止する必要がある場合は強制停止を指定してください。
  同期停止てワークユニットを停止した場合、処理中の要求を実行した後、ワークユニットを停止します。待ち状態となっている要求は、リジェクトされます。

ワークユニットの停止に関する以下の注意事項について説明します。

ワークユニット強制停止時の注意事項
ワークユニット情報獲得に関する注意事項

ワークユニット強制停止時の注意事項

ワークユニットを強制停止した場合でもAPIが異常終了すると、ワークユニットが停止していない場合が存在します。必ず停止したい場合はワークユニット情報通知機能で確認し、対処してください。

ワークユニット情報獲得に関する注意事項

ワークユニット情報通知機能の復帰情報statは停止状態として以下のステータスを返却します。必要がある場合はそれぞれの状態で対処してください。

ISOP_DWUSTOP
Interstage運用APIがワークユニットを停止しました。
ISOP_DWUSTOP_COM
Interstage運用APIで起動したワークユニットがtdstopwuコマンド、またはisstopwuコマンドで停止されました。
ISOP_DWUSTOP_ABEND
Interstage運用APIで起動したワークユニットが異常終了しました。

ISOP_DWUSTOP_AUTO
Interstage運用APIで起動したユーティリティワークユニットが自動停止しました。

4.5.4.3 クラスタシステムでの運用

クラスタシステムでInterstageを運用している環境で、Interstage運用APIを使用する場合には、以下のサービスを使用します。

INTERSTAGE APIサービス

本サービスはInterstageインストール時に、サービス登録が行われます。
具体的な運用方法については、“高信頼性システム運用ガイド”を参照してください。

なお、本サービスは、クラスタ構成でInterstageを運用する場合のみ、使用してください。クラスタ構成以外の構成でInterstageを運用する場合には、本サービスを起動しないでください。

4.5.4.4 Interstage運用APIの制御表のバージョン・レベルについて

Interstage運用APIのパラメタ構造体の制御表がバージョンアップした場合および、制御表のバージョンが古い場合の注意点について記述します。

  Interstage運用APIは、API呼び出しの際にパラメタとして設定された制御表バージョンの値を参照し、APIが動作する機能の範囲を決定します。
  API呼び出しの際にパラメタとして設定された制御表バージョンの値が本バージョンの値より古い場合、および本バージョンと同一の場合は、APIは設定されたバージョンまでにサポートされている機能の範囲で動作します。この場合、APIは復帰する際に、パラメタとして設定された制御表バージョンの値をそのまま通知します。
  API呼び出しの際にパラメタとして設定された制御表バージョンの値が本バージョンの値より新しい場合は、APIは本バージョンまでにサポートされている機能の範囲で動作し、本バージョンより新しいバージョンでサポートされた機能については動作しません。この場合、APIは復帰する際に、パラメタとして設定された制御表バージョンの領域に本バージョンの値を設定して復帰します。
  以下の表に、API呼び出し時に設定された制御表バージョンの値と、本バージョンにおけるAPIの動作および復帰する際の制御表バージョンの値について示します。

API呼び出しの際に設定される制御表バージョンの値	APIの動作	APIが復帰する際に設定する制御表バージョンの値
ISOP_001	ISOP_001でサポートされている機能の範囲で動作	ISOP_001
ISOP_002	ISOP_002でサポートされている機能の範囲で動作	ISOP_002
ISOP_003	ISOP_003でサポートされている機能の範囲で動作	ISOP_003
ISOP_005	ISOP_005でサポートされている機能の範囲で動作	ISOP_005
ISOP_006	ISOP_006でサポートされている機能の範囲で動作	ISOP_006
上記以外	各APIの最新制御表バージョンでサポートされている機能の範囲で動作	ISOP_006 システム名一覧通知：ISOP_001 システム名一覧解放：ISOP_001 上記以外：ISOP_006

4.5.4.5 Interstage運用APIで使用するパラメタ情報

Interstage運用APIで使用する構造体には、Interstageで定義されている情報があります。それらの定義を以下の表に示します。なお、文字列の終端には必ず’\0’を付けてください。

構造体に含まれるメンバ名	大きさ	設定できる値
ワークユニット名	36バイト	36バイト以内の英数字、ハイフン、アンダースコア、外字(ShiftJISコードのF040～F9FC) および半角カナを除く日本語。ただし、先頭と最終の文字にハイフン、アンダースコアの使用、漢字の空白文字（ShiftJISコードの8140）の使用は不可。半角英小文字の大文字と小文字、全角英文字の大文字と小文字は区別されません。 36バイト以内の英数字、ハイフン、アンダースコア、外字(日本語EUCコードの8FDDA1～8FFEFE) および半角カナを除く日本語。ただし、先頭と最終の文字にハイフン、アンダースコアの使用、漢字の空白文字（日本語EUCコードのA1A1）の使用は不可。
オブジェクト名	255バイト	ワークユニット種別がORBおよびWRAPPERの場合は、１つ以上のスラッシュを含む、255バイト以内の英字で始まる英数字、アンダースコア、スラッシュで構成された文字列です。先頭と最終文字のスラッシュ、２つ以上連続したスラッシュは指定できません。
システム名	8バイト	8バイト以内の英数字。

構造体に含まれるメンバ名

大きさ

設定できる値

ワークユニット名

36バイト

36バイト以内の英数字、ハイフン、アンダースコア、外字(ShiftJISコードのF040～F9FC) および半角カナを除く日本語。ただし、先頭と最終の文字にハイフン、アンダースコアの使用、漢字の空白文字（ShiftJISコードの8140）の使用は不可。半角英小文字の大文字と小文字、全角英文字の大文字と小文字は区別されません。

36バイト以内の英数字、ハイフン、アンダースコア、外字(日本語EUCコードの8FDDA1～8FFEFE) および半角カナを除く日本語。ただし、先頭と最終の文字にハイフン、アンダースコアの使用、漢字の空白文字（日本語EUCコードのA1A1）の使用は不可。

オブジェクト名

255バイト

ワークユニット種別がORBおよびWRAPPERの場合は、１つ以上のスラッシュを含む、255バイト以内の英字で始まる英数字、アンダースコア、スラッシュで構成された文字列です。先頭と最終文字のスラッシュ、２つ以上連続したスラッシュは指定できません。

システム名

8バイト

8バイト以内の英数字。

4.5.4.6 運用操作API群を使用するアプリケーションの作成方法

Interstage運用APIを使用するアプリケーションは、killコマンドまたはCtrl-Cで強制終了しないでください。強制終了した場合、Interstageが無応答になる場合があります。

以下のいずれかの方法でアプリケーションを作成することにより、強制終了した場合にInterstageが無応答になるのを回避することができます。

プロセスを強制終了させるシグナルを無視する処理をメイン関数に追加する。
プロセスを強制終了させるシグナルに対するシグナルハンドラを作成し、メイン関数にそのシグナルハンドラを登録する。

シグナルハンドラの作成時の注意

シグナルハンドラ内でプロセスを終了しないようにしてください。
以下に記述例を示します。

SIGTERMを受け付ける場合

#include <signal.h>
:
static void sig_term(); /* シグナルハンドラ（SIGTERM） */
int endflg; /* 終了フラグ */
main()
{
ISOP_LSTWU lstwu;
:
endflg=0; /* 終了フラグの初期化 */
signal( SIGTERM, sig_term); /* シグナルハンドラの登録 */
:
while(1) {
:
ISOPnotify( (char *)&lstwu); /* 運用APIの発行 */
:
if( endflg == 1) { /* 終了フラグがONの場合、プロセス終了 */
/* 終了処理 */
return;
}
}
}
static void sig_term()
{
endflg = 1; /* 終了フラグにONを設定 */
}