SRC とのサブシステム通信のプログラミング

システム・リソース・コントローラー (SRC) コマンドは、コマンド・ラインからオプションを採用する実行可能プログラムです。

コマンド構文が検査された後、コマンドは SRC ランタイム・サブルーチンを呼び出して、ユーザー・データグラム・プロトコル (UDP) データグラムを構成し、それを srcmstr デーモンに送信します。

以下の節では、SRC サブルーチン、およびサブシステムがそれらをどのように使用して、SRC メイン・プロセスと通信するのかについて詳しく説明しています。

SRC 要求を受信するサブシステムのプログラミング

SRC 要求の受信に関連するプログラミング・タスクは、サブシステムに対して指定されている通信タイプによって異なります。 srcmstr デーモンは、ソケットを使用してコマンド・プロセスから作業要求を受け取り、必要なソケットまたはメッセージ・キューを作成して、作業要求を転送します。各サブシステムは、そのソケットまたはメッセージ・キューの作成を確認する必要があります。 SRC 要求パケットを受信するサブシステムのプログラミングに関する通信タイプ固有の指針については、以下の節をお読みください。

注: 通信タイプに関係なく、すべてのサブシステムが、SIGTERM 要求を操作するためのシグナル・キャッチャー・ルーチンを定義する必要があります。

SRC シグナルの受信

通信タイプとしてシグナルを使用するサブシステムは、SIGNORM および SIGFORCE の各シグナルをキャッチするためのシグナル・キャッチャーを定義する必要があります。使用するシグナル・キャッチ・メソッドは、サブシステムによって決まります。この目的のために使用できるサブルーチンの 2 例を、以下に示します。

サブルーチン	説明
sigaction、 sigvec、または signal サブルーチン	シグナルのデリバリー時に行うアクションを指定します。
sigset、 sighold、 sigrelse、または sigignore サブルーチン	シグナル機能を拡張子、アプリケーション・プロセスに対するシグナル管理を行います。

ソケットを使用した SRC 要求パケットの受信

SRC 要求パケットを受信するソケット・サブシステムのプログラミング時に、以下の指針を使用してください。

/usr/include/spc.h ファイルを指定して、SRC サブシステム構造をサブシステム・コードに組み込みます。このファイルには、サブシステムが SRC コマンドに応答する際に使用する構造体が入っています。さらに、spc.h ファイルには、srcerrno.h ファイルが組み込まれているため、別個に組み込む必要はありません。 srcerrno.h ファイルには、デーモンをサポートするためのエラー・コード定義が入っています。
ソケット・サブシステムが開始されると、そのサブシステムが SRC 要求パケットを受信するソケットは、ファイル記述子 0として設定されます。サブシステムは、 getsockname サブルーチンを呼び出して、サブシステムのソケットのアドレスを戻すことによって、これを検証する必要があります。ファイル・ディスクリプター 0 がソケットでない場合、サブシステムはエラーをログに記録してから終了します。 getsockname サブルーチンを使用してサブシステム・ソケットのアドレスを戻す方法については、「 Communications Programming Concepts 」の「 Internet Datagrams Example Program の読み取り」を参照してください。
サブシステムが複数のソケットをポーリングする場合は、 select サブルーチンを使用して、読み取るものがあるソケットを判別します。 select サブルーチンをこの目的で使用する方法について詳しくは、「 通信プログラミングの概念 」の「保留中の接続の例プログラムの検査」を参照してください。
recvfrom サブルーチンを使用して、ソケットから要求パケットを取得します。
注: サブシステム応答パケットの戻りアドレスは、受け取った SRC 要求パケット内に入っています。このアドレスと、recvfrom サブルーチンがパラメーターの 1 つとして戻すアドレスとを混同しないようにしてください。

recvfrom サブルーチンが完了し、パケットが受信されたら、 srcrrqs サブルーチンを使用して、静的 srchdr 構造体へのポインターを戻します。このポインターには、サブシステムの応答用の戻りアドレスが入っています。この構造体は srcrrqs サブルーチンがコールされるたびに上書きされるため、その内容が srcrrqs サブルーチンの次のコール後に必要となる場合は、どこかに保管しておく必要があります。

メッセージ・キューを使用した SRC 要求パケットの受信

SRC 要求パケットを受信するメッセージ・キュー・サブシステムのプログラミング時に、以下の指針を使用してください。

/usr/include/spc.h ファイルを指定して、SRC サブシステム構造をサブシステム・コードに組み込みます。このファイルには、サブシステムが SRC コマンドに応答する際に使用する構造体が入っています。さらに、spc.h ファイルには srcerrno.h ファイルが組み込まれているため、別個に組み込む必要はありません。 srcerrno.h ファイルには、デーモンをサポートするためのエラー・コード定義が入っています。
コンパイル・オプションとして -DSRCBYQUEUE を指定します。これにより、メッセージ・タイプ (mtype) フィールドは、 srcreq 構造体の最初のフィールドです。 SRC パケット受信時は、必ずこの構造体を使用してください。
サブシステムが開始されたら、 msgget サブルーチンを使用して、システム始動時にメッセージ・キューが作成されたことを確認します。メッセージ・キューが作成されていなかった場合、サブシステムはエラーをログに記録して終了する必要があります。
サブシステムが複数のメッセージ待ち行列をポーリングする場合は、 select サブルーチンを使用して、読み取るものがあるメッセージ待ち行列を判別します。 select サブルーチンをこの目的で使用する方法については、「 通信プログラミングの概念 」の「保留中の接続の例プログラムの検査」を参照してください。
msgrcv または msgxrcv サブルーチンを使用して、メッセージ・キューからパケットを取得します。サブシステム応答パケットの戻りアドレスは、受け取ったパケット内に入っています。
msgrcv または msgxrcv サブルーチンが完了し、パケットが受信されると、 srcrrqs サブルーチンを呼び出して、受信プロセスを終了します。 srcrrqs サブルーチンは、srcrrqs サブルーチンがコールされるたびに上書きされる静的 srchdr 構造体を指すポインターを戻します。このポインターには、サブシステムの応答用の戻りアドレスが入っています。

SRC 要求パケットを処理するサブシステムのプログラミング

サブシステムは、停止要求を処理できなければなりません。オプショナルで、サブシステムは始動、状況、トレース、および再表示の各要求をサポートすることもできます。

要求パケットの処理には、次の 2 ステップから成るプロセスが関与します。

『SRC 要求パケットの読み取り』

SRC 要求パケットは、/usr/include/spc.h ファイルで定義されているように、srcreq 構造体の形式でサブシステムに受け取られます。サブシステム要求は、srcreq 構造体の subreq 構造体の中に常駐します。

struct subreq
   short object;         /*object to act on*/
   short action;         /*action START, STOP, STATUS, TRACE,\
                           REFRESH*/
   short parm1;          /*reserved for variables*/
   short parm2;          /*reserved for variables*/
   char objname;         /*object name*/

このobjectsubreq 構造体のフィールドは、要求が適用されるオブジェクトを示します。要求がサブシステムに適用されると、objectフィールドは SUBSYSTEM 定数に設定されます。それ以外の場合は、objectフィールドがサブサーバー・コード・ポイントまたはobjnameフィールドは、サブサーバー PID に文字ストリングとして設定されます。要求が適用されるオブジェクトの決定は、サブシステムの責任で行います。

このactionフィールドは、サブシステムに要求されたアクションを指定します。サブシステムは、 START、 STOP、および STATUS アクション・コードを理解している必要があります。 TRACE と REFRESH のアクション・コードは、オプショナルです。

このparm1およびparm2フィールドは、アクションごとに異なる方法で使用されます。

アクション	parm1	parm2
中止	NORMAL または FORCE
状況	LONGSTAT または SHORTSTAT
TRACE	LONGTRACE または SHORT-TRACE	TRACEON または TRACEOFF

START サブサーバーおよび REFRESH アクションは、以下のものを使用しません。parm1およびparm2フィールド

SRC 要求に対するサブシステム応答のプログラミング

大多数の SRC 要求に対する適切なサブシステム・アクションは、SRC に対してサブシステム・オブジェクトが定義されるときに、プログラミングされています。サブシステムが SRC 要求に応答するために使用する構造体は、 /usr/include/spc.h ファイルに定義されています。サブシステムは、以下の SRC 実行時サブルーチンを使用して、コマンド処理要件に適合させることができます。

サブルーチン	説明
SRCRQS	サブシステムが要求からヘッダーを保管できるようになります。
srcsrpy (srcsrpy)	サブシステムが要求に対して応答を送り返せるようになります。

状況要求処理では、タスクとサブルーチンのマージが必要です。

サブシステムが、処理できない要求あるいは無効な要求を受け取った場合は、不明または無効な要求への応答で、SRC_SUBICMD というエラー・コードを持ったエラー・パケットを送信しなければなりません。 SRC では、SRC 内部使用として 0 から 255 のアクション・コードを予約しています。サブシステムは、無効なアクション・コードの入った要求を受け取った場合、SRC_SUBICMD というエラー・コードを戻す必要があります。 SRC がサポートしている有効なアクション・コードは、spc.h ファイルに定義されています。また、サブシステム固有のアクション・コードを定義することもできます。 SRC またはサブシステムによって定義されていないアクション・コードは、無効です。

注: アクション・コード 0 から 255 は、SRC が使用するものとして予約されています。

SRC 状況要求の処理

サブシステムは、サブシステムの長時間状況、サブサーバーの短時間状況、およびサブサーバーの長時間状況という 3 つのタイプの状況レポートの提供を要求される場合があります。

注: サブシステムの短時間状況レポート作成は、srcmstr デーモンによって実行されます。このタイプのレポートのための statcode 定数と reply-status 値定数は、 /usr/include/spc.h ファイルに定義されています。状況値定数の表は、必須および推奨する応答状況値コードをリストしたものです。

応答状況値コード

値	意味	サブシステム	サブサーバー
SRCWARN	停止する要求を受信しました。 (20 秒以内に停止されます。)	X	X
SRCACT	開始済みで、アクティブです。	X	X
SRCINAC	アクティブではありません。
SRCINOP	作動不能です。	X	X
SRCLOSD	クローズされました。
SRCLSPN	クローズの処理中です。
SRCNOSTAT	活動停止中です。
SRCOBIN	オープンされていますが、アクティブではありません。
SRCOPND	オープン。
SRCOPPN	オープンの処理中です。
SRCSTAR	始動中です。		X
SRCSTPG	停止中です。	X	X
SRCTST	TEST アクティブです。
SRCTSTPN	TEST 保留中です。

SRC lssrc コマンドは、受信した情報を標準出力に表示します。サブシステムによって、長時間状況要求に対する応答で戻される情報は、サブシステムに一任されています。希望に応じて、サブサーバーの状態変更のトラッキングとレポート作成は、そのサブサーバーを所有するサブシステムの責任で行います。 srcstathdr サブルーチンを使用して、状況データの先頭に戻す標準状況ヘッダーを検索します。

状況要求の処理では、以下のステップをお勧めします。

サブシステム (short または long) から状況を戻すには、 statcode 構造体の配列と srchdr 構造体を割り振ります。 srchdr 構造体は、状況要求への応答で送信するバッファーを開始する必要があります。 statcode 構造体は、/usr/include/spc.h ファイルに定義されています。
```
struct statcode
{
   short objtype;
   short status;
   char objtext [65];
   char objname [30];
};
```
以下を入力してください:objtype状況がサブシステムに関するものであることを示す SUBSYSTEM 定数、または状況がサブサーバーに関するものであることを示すサブサーバー・コード・ポイントを持つフィールド。
以下を入力してください:statusspc.h ファイルに定義されている SRC 状況定数の 1 つを含むフィールド。
以下を入力してください:objtext状況として表示したい NLS テキストを含むフィールド。このフィールドは、NULL 終了文字列でなければなりません。
以下を入力してください:objnameフィールドには, そのサブシステムまたはサブサーバーの名前が入ります。objtext適用されます。このフィールドは、NULL 終了文字列でなければなりません。
注: サブシステムおよびリクエスターは、他のサブシステムが定義した情報をリクエスターに送り返すことに同意することができます。

応答パケットを送信するサブシステムのプログラミング

サブシステムが SRC に戻すパケットは、/usr/include/spc.h ファイルで定義されているように、srcrep 構造体の形式になっている必要があります。 srcrep 構造体の一部である svrreply 構造体には、サブシステムの応答が入っています。

struct svrreply
{
   short rtncode;        /*return code from the subsystem*/
   short objtype;        /*SUBSYSTEM or SUBSERVER*/
   char objtext[65];     /*object description*/
   char objname[20];     /*object name*/
   char rtnmsg[256];     /*returned message*/
};

srcsrpy サブルーチンを使用して、パケットをリクエスターに戻します。

応答の作成

サブシステムの応答のプログラムを作成する場合は、以下の手順を使用してください。

以下を入力してください: rtncode該当する SRC エラー・コードを持つフィールド。 SRC_SUBMSG を以下のように使用します。rtncodeサブシステム固有の NLS メッセージを戻すためのフィールド。
以下を入力してください:objtype応答がサブシステムに対するものであることを示す SUBSYSTEM 定数、または応答がサブサーバーに対するものであることを示すサブサーバー・コード・ポイントを含むフィールド。
以下を入力してください:objname応答に適用されるサブシステム名、サブサーバー・タイプ、またはサブサーバー・オブジェクトを含むフィールド。
以下を入力してください:rtnmsgフィールドには、サブシステム固有の NLS メッセージが表示されます。
srcsrpy Continued パラメーター内の適切なエントリーにキーを付けます。詳細については、srcsrpy 継続パケットを参照してください。
注記： サブシステムからの最後のパケットには、srcsrpy サブルーチンの Continuedパラメーターで常にENDを指定する必要があります。

srcsrpy 継続パケット

SRC 要求に対するサブシステムの応答は、継続パケットの形式で作成されます。通知メッセージと応答パケットという、2 つのタイプの継続パケットを指定することができます。

通知メッセージは、クライアントには戻されません。その代わりに、クライアントの標準出力に印刷されます。メッセージは、NLS テキストと、送信側サブシステムによって入力されたメッセージ・トークンで構成しなければなりません。このタイプの継続パケットを送信する場合は、srcsrpy サブルーチンの Continued パラメーターに、CONTINUED を指定します。

注: STOP サブシステム・アクションでは、いかなる種類の継続も認められていません。ただし、SRC からサブシステムが受け取ったその他のアクション要求は、すべて通知メッセージを送信することができます。

応答パケットは、さらに処理を進めるためにクライアントに戻されます。そのため、パケットはサブシステムとリクエスターに同意されている必要があります。このタイプの継続の一例として、状況要求があります。サブシステム状況要求に対して応答するときは、srcsrpy の Continued パラメーターに STATCONTINUED を指定します。状況レポート作成が完了、またはサブシステムが定義したすべての応答パケットの送信が完了すると、srcsrpy Continued パラメーターに END を指定します。これでパケットはクライアントに渡され、応答の終わりが指示されます。

SRC エラー・パケットを戻すサブシステムのプログラミング

SRC エラーと SRC 以外のエラーの両方のエラー・パケットを戻すためには、サブシステムが不可欠です。

SRC エラーを戻す場合、サブシステムが戻す応答パケットは、 srcrep 構造体の svrreply 構造体の形式でなければなりません。objnameフィールドには、エラーのあるサブシステム名、サブサーバー・タイプ、またはサブサーバー・オブジェクトが入ります。 SRC エラー番号に関連付けられている NLS メッセージにトークンが組み込まれていない場合、エラー・パケットは短形式で戻されます。これは、エラー・パケットには SRC エラー番号しか入っていないということです。ただし、エラー番号にトークンが関連付けられている場合は、メッセージ・カタログに入っている標準 NLS メッセージ・テキストを戻す必要があります。

非 SRC エラーを戻す場合、応答パケットは、以下のような svrreply 構造でなければなりません。rtncodeフィールドが SRC_SUBMSG 定数に設定され,rtnmsgフィールドは、サブシステム固有の NLS メッセージに設定されます。このrtnmsgフィールドはクライアントの標準出力に出力されます。

トレース要求への応答

traceson および tracesoff コマンドのサポートは、サブシステムに依存します。これらのコマンドをサポートすることを選択した場合は、サブシステムおよびサブサーバーに対してトレース・アクションを指定することができます。

サブシステム・トレース要求は、以下の形式で到着します。サブシステム・トレース要求は、 subreq actionTRACE 定数および subreq に設定されるフィールド objectフィールドは SUBSYSTEM 定数に設定されます。トレース・アクションは以下を使用しますparm1LONGTRACE または SHORTTRACE トレースを指示するparm2TRACEON または TRACEOFF を示します。

サブシステムがトレース・サブシステム・パケットを受信したときparm1SHORTTRACE に設定され、parm2TRACEON に設定すると、サブシステムは短時間トレースをオンにする必要があります。逆に、サブシステムがトレース・サブシステム・パケットを受信すると、以下のようになります。parm1LONGTRACE に設定され、かつparm2TRACEON に設定すると、サブシステムは長いトレースをオンにする必要があります。サブシステムがトレース・サブシステム・パケットを受信したときparm2TRACEOFF に設定すると、サブシステムはサブシステム・トレースをオフにします。

サブサーバー・トレース要求は、以下の形式で到着します。サブサーバー・トレース要求は、 subreq actionTRACE 定数および subreq に設定されるフィールド object状況を送信するサブサーバーのサブサーバー・コード・ポイントに設定されるフィールド。トレース・アクションは以下を使用しますparm1LONGTRACE または SHORTTRACE を示し、かつ、parm2TRACEON または TRACEOFF を示します。

サブシステムがトレース・サブサーバー・パケットを受信したときparm1SHORTTRACE に設定され、parm2TRACEON に設定すると、サブシステムはサブサーバーの簡略トレースをオンにする必要があります。反対に、サブシステムがトレース・サブサーバー・パケットを受信すると、以下のようになります。parm1LONGTRACE に設定され、かつparm2TRACEON に設定すると、サブシステムはサブサーバーの長時間トレースをオンにする必要があります。サブシステムがトレース・サブサーバー・パケットを受信したときparm2TRACEOFF に設定すると、サブシステムはサブサーバーのトレースをオフにします。

再表示要求への応答

サブシステム再表示要求のサポートは、サブシステムによって異なります。 refresh コマンドをサポートすることを選択したサブシステム・プログラマーは、以下の方法で SRC と対話するようにサブシステムをプログラムする必要があります。

サブシステムのリフレッシュ要求には、 subreq 構造体があります。actionREFRESH 定数および subreq 構造体に設定されるフィールドobjectフィールドは SUBSYSTEM 定数に設定されます。サブシステムのリフレッシュ・アクションは、以下を使用しません。parm1またはparm2.
サブシステムは、再表示要求を受け取ったら、自身を再構成する必要があります。