Systemwalker Centric Manager API・スクリプトガイド - UNIX/Windows(R)共通 -

4.70 ORMRequest（）関数【UNIX版】

■機能説明

任意の文字列を返答結果とする返答要求メッセージを運用管理サーバに通知します。

■呼び出し形式

  
#include "ORMessage.h"
int  ORMRequest (char *apname, char *msg, 
                 struct ORM_REP_DAT_TAG *rep_dat, 
                 int rep_len, int time_out)

■パラメタ

char *apname:

要求元名(任意の文字列)を示す文字列。最終文字のNULL文字を含め、最大文字数は32バイトです。指定可能な文字は半角英数字のみです。なお、要求元名には、1バイト以上の文字列を、必ず設定する必要があります。

char *msg:

NULLで終わるメッセージ文字列。最大文字数はNULL文字を含めて1024バイトです。なお、返答要求メッセージ文字列には、1バイト以上の文字列を必ず設定する必要があります。

struct ORM_REP_DAT_TAG *rep_dat:

返答結果を受け取る構造体の参照アドレス。
本領域はサーバプログラムにて以下に記述する"ORM_REP_DAT_TAG"構造体型の変数領域を指定してください。構造体定義は"ORMessage.h"に定義されています。

int rep_len:

返答文字列の入力最大バイト長を設定します。指定可能範囲は1〜320(単位：バイト)です。

int time_out:

タイムアウト時間を個別に変更したい場合にタイムアウト時間の指定を行います。指定可能範囲は1〜1440(単位：分)または0です。0を指定すると通常のタイムアウト時間1440分として扱います。

■構造体の説明

  
struct ORM_REP_DAT_TAG {
  int resno;                // 返答識別番号
  int len;                  // 返答バイト長
  char str[321];            // 返答結果文字列格納領域
};

int resno:

返答識別番号を格納します。

int len:

返答結果の返答バイト長を格納します。

char str[321]:

返答結果は末尾にNULL文字を付加された文字列として指定された参照変数に格納されます。オペレータからの返答で、返答文字列が省略された場合は、領域の先頭にNULLが設定されます。

■復帰値

PR_OK(0):

正常終了しました。

PR_ERR_PARAM(-1):

パラメタエラーが発生しました。

PR_TIMEOUT(-2):

タイムアウトが発生しました。

PR_STOP(-3):

Open ReplyMessageサービスがユーザ要求により停止しました。

PR_ERR_CONECT(-11):

Open ReplyMessageサービスと接続できません

PR_ERR_SEND(-12):

Open ReplyMessageサービスへの返答要求は送信できませんでした。

PR_ERR_RCV(-13):

Open ReplyMessageサービスからの返答を受信できませんでした。

PR_ERR_CONNECTOVER(-21):

返答要求実行可能の最大数を超過しました。

PR_ERR_ORM_STOP(-26):

Open ReplyMessageサービスの緩和停止中に返答要求が発行されました。

PR_ERR_LENGTHOVER(-31):

入力最大バイト長を超える返答入力が行われました。

PR_ERR_UEXPCT(-99):

予期せぬエラーが発生しました。

補足：

戻り値がエラー(-1以下)の場合、構造体rep_datの値は以下のようになります。

• PR_ERR_LENGTHOVER(-31) の場合

  構造体rep_datのメンバstrには、パラメタrep_lenに指定された長さまでの返答結果が設定されます。

  構造体rep_datのメンバlenには、GUIまたは返答コマンドにより返答されたバイト長(NULL除く)が設定されます。メンバstrに設定された文字列の長さではありません。

  構造体rep_datのメンバresnoには、返答番号が設定されます。

• PR_TIMEOUT(-2)およびPR_STOP(-3)の場合

  構造体rep_datのメンバstrには、領域の先頭にNULLが設定されます。

  構造体rep_datのメンバlenには、0が設定されます。

  構造体rep_datのメンバresnoには、返答番号が設定されます。

• 上記以外の場合

  構造体rep_datのメンバstrには、領域の先頭にNULLが設定されます。

  構造体rep_datのメンバlenには、0が設定されます。

  構造体rep_datのメンバresnoには、0が設定されます。

■参照

以下のメッセージ返答要求・返答APIを参照してください。

• ORMMessage（）関数

■API格納場所

Solaris	/usr/lib
Linux	/usr/lib

■INCLUDEファイル格納場所

Solaris	/usr/include
Linux	/usr/include

■実行に必要な権限/実行環境

• 環境: 運用管理サーバ/部門管理サーバ/業務サーバで実行可能です。

■注意事項

• 返答結果は、半角英数字で124文字以内になるようにプログラムを作成してください。日本語を使用する場合は、日本語61文字以内になるようにプログラムを作成してください。
• メッセージのエラー種別は、エラーとなります。以下にメッセージフォーマットとメッセージの形式を示します。
  • メッセージフォーマット

      
    返答番号  要求元 メッセージ

    
    
  • メッセージの形式

      
    ラベル：なし
    重要度：重要
    エラー種別：エラー
    監視イベント種別：システム

• メッセージ、および応答内容の文字コードはシステムに設定されているロケールの文字コードを使用します。
• COBOLからのCALL命令を用いたAPI呼び出しはCOBOL97仕様以降のCOBOLに対応しています。

■使用例

◆C言語によるプログラム例

App1.c(サーバプログラム)は、オペレータに『ディレクトリを入力してください。』という返答要求メッセージをApp1というサーバプログラムから発行し、最大320バイトの返答内容を120分間待ちます。

返答メッセージはdirdat構造体のstrに保存されます。

返答メッセージの長さはdirdat構造体のlenに保存されます。

返答メッセージの返答番号はdirdat構造体のresnoに保存されます。

  
//App1.c（サーバプログラム）
#include "ORMessage.h"
#define DIRNAME_LENGTH 320                   /* DIR文字列長        */

int main(int argc, char **argv){
  struct ORM_REP_DAT_TAG dirdat;             /* 返答結果構造体     */

  ret = ORMRequest
       ( "App1",                             /* 要求元名           */
        "ディレクトリを入力してください。",   /* 返答要求メッセージ */
        &dirdat,                             /* 返答内容格納領域   */
        DIRNAME_LENGTH,                      /* 入力最大バイト長   */
        120 );                               /* タイムアウト時間   */
}

◆COBOLによるプログラム例

APP1.cob（サーバプログラム）は、返答要求メッセージをAPP1というサーバプログラムから発行し、最大320バイトの返答内容を120分間待ちます。
返答メッセージはSTRに保存されます。
返答メッセージの長さはLENに保存されます。
返答メッセージの返答番号はRESNOに保存されます。

  
*APP1.cob（サーバプログラム）
000010 IDENTIFICATION   DIVISION.
000020 PROGRAM-ID.      APP1.
000030 ENVIRONMENT      DIVISION.
000040 DATA             DIVISION.
000050 WORKING-STORAGE  SECTION.
000060 01  CALLINFO.
000070     03  SUB-PG       PIC X(256).　　　　            *API名
000080     03  APNAME       PIC X(32).                     *呼び出し元AP名
000090     03  MSG          PIC X(1024).                   *表示メッセージ
000100     03  REP-DAT.                                    *返答結果格納構造体
000110         05  RESNO    PIC S9(09) COMP-5 VALUE 0.　　 *返答番号
000120         05  LEN      PIC S9(09) COMP-5 VALUE 0.     *返答バイト長
000130         05  STR      PIC X(321).                    *返答内容
000140     03  REP-LEN      PIC S9(09) COMP-5 VALUE 320.   *入力最大バイト長
000150     03  TIME-OUT     PIC S9(09) COMP-5 VALUE 120.   *タイムアウト
000160     03  RETURNVALUE  PIC S9(09) COMP-5 VALUE 0.     *API復帰値
000170 PROCEDURE        DIVISION.
000180*初期化部
000190     INITIALIZE CALLINFO.
000200     MOVE "ORMRequest"    TO SUB-PG.　　　　　       *API名のセット
000210     MOVE LOW-VALUE       TO SUB-PG(11:).            *終端文字のセット
000220     MOVE "APP1"          TO APNAME.                 *呼び出し元AP名のセット
000230     MOVE LOW-VALUE       TO APNAME(5:).             *終端文字のセット
000240     MOVE "ディレクトリを入力してください。" TO MSG. *メッセージのセット
000250     MOVE LOW-VALUE       TO MSG(33:).               *終端文字のセット
000260*API呼び出し
000270     CALL SUB-PG                                     *API呼び出し
000280         USING
000290             BY  REFERENCE   APNAME
000300             BY  REFERENCE   MSG
000310             BY  REFERENCE   REP-DAT
000320             BY  VALUE       REP-LEN
000330             BY  VALUE       TIME-OUT
000340         RETURNING RETURNVALUE
000350     END-CALL.
000360*結果表示
000370     DISPLAY              RESNO.                     *応答番号を表示
000380     DISPLAY              LEN.                       *応答長を表示
000390     DISPLAY              STR.                       *応答内容を表示
000400     DISPLAY              RETURNVALUE.               *API復帰値を表示
000410     STOP RUN.