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

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

コマンド構文の検査が終わると、コマンドは SRC 実行時サブルーチンを呼び出して、User Datagram Protocol (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 の『Reading Internet Datagrams Example Program』を参照してください。
  • サブシステムが複数のソケットをポーリングする場合は、select サブルーチンを使用して、読み取るものがあるソケットを決定してください。 この目的のために select サブルーチンを使用できる方法について詳しくは、Communications Programming Concepts の『Checking for Pending Connections Example Program』を参照してください。
  • 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 サブルーチンを使用できる方法について詳しくは、Communications Programming Concepts の『Checking for Pending Connections Example Program』を参照してください。
  • 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*/

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

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

parm1 と parm2 の各フィールドは、 それぞれのアクションによって別々に使用されます。

アクション parm1 parm2
STOP NORMAL または FORCE  
STATUS LONGSTAT または SHORTSTAT  
TRACE LONGTRACE または SHORT-TRACE TRACEON または TRACEOFF

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

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

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

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

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

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

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

SRC 状況要求の処理

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

注: サブシステムの短時間状況レポート作成は、srcmstr デーモン によって実行されます。 このタイプのレポートのための Statcode および応答状況値定数は、/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 サブルーチンを 使用します。

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

  1. サブシステムから状況 (短時間または長時間) を戻す場合は、statcode 構造体に srchdr 構造体を加えた配列を割り当てます。 srchdr 構造体は、状況要求への応答で送信するバッファーを開始する必要があります。 statcode 構造体は、/usr/include/spc.h ファイルに定義されています。 
    struct statcode
{
   short objtype;
   short status;
   char objtext [65];
   char objname [30];
};
  2. objtype フィールドに、SUBSYSTEM 定数を入力して 状況がサブシステムについてのものであることを示すか、またはサブサーバー・コード・ポイントを 入力して状況がサブサーバーについてのものであることを示します。
  3. status フィールドに、spc.h ファイルで定義されている SRC 状況定数の 1 つを入力します。
  4. objtext フィールドに、状況として表示したい NLS テキストを入力します。 このフィールドは、NULL 終了文字列でなければなりません。
  5. 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 サブルーチンを使用します。

応答の作成

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

  1. rtncode フィールドに、適用される SRC エラー・コードを入力します。 SRC_SUBMSG を rtncode フィールドとして使用して、サブシステム固有の NLS メッセージを戻します。
  2. objtype フィールドに、SUBSYSTEM 定数を入力して 応答がサブシステムに対するものであることを示すか、またはサブサーバー・コード・ポイントを入力して 応答がサブサーバーに対するものであることを示します。
  3. objname フィールドに、応答に適用されるサブシステム名、 サブサーバー・タイプ、またはサブサーバー・オブジェクトを入力します。
  4. rtnmsg フィールドに、サブシステム固有の NLS メッセージを入力します。
  5. 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 action フィールドが TRACE 定数に設定され、subreq object フィールドが SUBSYSTEM 定数に設定されます。 トレース・アクションは、parm1 を使用して LONGTRACE トレースまたは SHORTTRACE トレースを指示し、parm2 を使用して TRACEON または TRACEOFF を指示します。

サブシステムは、parm1 が SHORTTRACE に設定 され、parm2 が TRACEON に設定されたトレース・サブシステム・パケットを受け取ると、 ショート・トレースをオンに切り換える必要があります。 逆に、parm1 が LONGTRACE に設定され、parm2 が TRACEON に 設定されたトレース・サブシステム・パケットを受け取ると、サブシステムは ロング・トレースをオンに切り換える必要があります。 サブシステムは、parm2 が TRACEOFF に設定されたトレース・サブシステム・パケットを 受け取ると、サブシステムのトレースをオフに切り換える必要があります。

サブサーバー・トレース要求は、以下の形式で到着します。 サブサーバー・トレース要求では、subreq action フィールドが TRACE 定数に設定され、subreq object フィールドが、状況を送信するサブサーバーのサブサーバー・コード・ポイントに設定されます。 トレース・アクションは、parm1 を使用して LONGTRACE または SHORTTRACE を 指示し、parm2 を使用して TRACEON または TRACEOFF を指示します。

サブシステムは、parm1 が SHORTTRACE に設定 され、parm2 が TRACEON に設定されたトレース・サブサーバー・パケットを 受け取ると、サブサーバー・ショート・トレースをオンに切り換える必要があります。 逆に、parm1 が LONGTRACE に設定 され、parm2 が TRACEON に設定されたトレース・サブサーバー・パケットを 受け取ると、サブシステムはサブサーバー・ロング・トレースをオンに切り換える必要があります。 サブシステムは、parm2 が TRACEOFF に設定された トレース・サブサーバー・パケットを受け取ると、サブサーバーのトレースをオフに切り換える必要があります。

再表示要求への応答

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

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