COMMAND EXECUTEUAPからのコマンド実行

機能

UAP中から,HiRDBのコマンド,及びOSのコマンドを実行します。

COMMAND EXECUTEを実行する場合,HiRDBサーバにHiRDB Control Manager - Agentをインストールしておく必要があります。これは,HiRDB Control Manager - Agentがコマンドを実行するためです。

形式

 COMMAND EXECUTE :コマンドライン変数,
            :リターンコード受け取り変数,
            :実行結果受け取り領域長変数,
            :実行結果長受け取り変数,
            :実行結果受け取り変数,
            :実行コマンドリターンコード受け取り変数,
            :環境変数グループ名変数

オペランド

コマンドライン変数には,HiRDBサーバで実行するコマンドのコマンドラインを設定します。

CHAR型(領域長30,000バイト以内)として宣言した埋込み変数を指定してください。また,コマンドラインの最後には,必ずナル文字を指定してください。

既定文字集合以外の文字集合は指定できません。

コマンドライン変数に複数のコマンドは指定しないでください。指定した場合,動作は保証されません。

リターンコード受け取り変数には,COMMAND EXECUTE実行時のリターンコードが設定されます。INT型として宣言した埋込み変数を指定してください。

リターンコード受け取り変数には,次の値が設定されます。なお,エラーの場合には,実行結果受け取り変数に詳細情報が設定されます。

p_rdb_RC_NORM:
HiRDBサーバで正常にコマンドが実行された場合
p_rdb_RC_ERRPARM:
引数が不正な場合
p_rdb_PROTO:
通信エラーの場合
p_rdb_RC_NOTF:
環境変数グループがない場合
p_rdb_RC_TIMEOUT:
タイムアウトした場合
p_rdb_RC_SQLERR:
そのほかのエラーの場合

実行結果受け取り領域長変数には,実行結果受け取り変数の領域長を設定します。INT型として宣言した埋込み変数を指定してください。

実行結果受け取り領域長は,2ギガバイト以内で設定してください。

実行結果長受け取り変数には,実行結果受け取り変数への出力長が設定されます。INT型として宣言した埋込み変数を指定してください。

実行結果受け取り変数には,実行結果受け取り用に確保した領域のアドレスを設定します。PDOUTBUF型として宣言した埋込み変数を指定してください。

COMMAND EXECUTE実行後,実行結果受け取り変数には,次の値が設定されます。ただし,(実行結果受け取り領域長変数の指定値-1)以降のデータは切り捨てられます。また,実行結果の最後には,1バイトのナル文字が設定されます。

リターンコード受け取り変数にp_rdb_RC_NORMが設定されている場合:
HiRDBサーバで実行したコマンドラインの実行結果(標準出力と標準エラー出力)が設定されます。
リターンコード受け取り変数にp_rdb_RC_NORM以外が設定されている場合:
障害コードに対応する詳細メッセージが設定されます。

実行コマンドリターンコード受け取り変数には,HiRDBサーバで実行したコマンドラインのリターンコードが設定されます。INT型として宣言した埋込み変数を指定してください。

COMMAND EXECUTEが正常終了(リターンコード受け取り変数にp_rdb_RC_NORMが設定されている場合)したときだけ,実行コマンドリターンコード受け取り変数に有効な値が設定されます。

なお,実行したコマンドが標準出力又は標準エラー出力に情報を出力しない場合は,実行コマンドリターンコード受け取り変数には0が設定されます。

環境変数グループ名変数には,次の値を指定します。

UNIX版の場合:
クライアント環境定義を記述した通常ファイルの名称(ナル文字を含めて256バイト以内)を,絶対パス名で指定します。
Windows版の場合:
HiRDBクライアント環境変数登録ツールで登録したグループ名(ナル文字を含めて31バイト以内)を指定します。

CHAR型(領域長256バイト以内)として宣言した埋込み変数を指定してください。

既定文字集合以外の文字集合は指定できません。

環境変数グループを使用しない場合は,1バイト目にナル文字を設定してください。

環境変数グループについては,マニュアル「HiRDB Version 8 UAP開発ガイド」を参照してください。

共通規則

  1. 使用する埋込み変数は,埋込み変数宣言節で宣言してください。
  2. COMMAND EXECUTEを実行する場合,次のクライアント環境定義を設定しておく必要があります。
    • PDASTHOST(HiRDB Control Manager - Agentのホスト名)
    • PDASTPORT(HiRDB Control Manager - Agentのポート番号)
    • PDSYSTEMID(HiRDB Control Manager - AgentのHiRDB識別子)
    • PDASTUSER(HiRDBサーバでコマンドを実行する認可識別子)
    クライアント環境定義については,マニュアル「HiRDB Version 8 UAP開発ガイド」を参照してください。
  3. UAPがHiRDBと接続中でもCOMMAND EXECUTEは実行できます。ただし,コマンドが終了するまでUAP側に制御は戻ってこないので,デッドロックが発生しないように注意してください。
  4. 応答要求があるコマンドは指定しないでください。HiRDB Control Manager - Agentでは,応答の入力要求は受け付けないため,コマンドがエラーで終了します。
  5. 実行するコマンドの入力ファイルは,あらかじめHiRDBサーバに用意しておいてください。
  6. コマンドの実行が長時間になる場合,コマンドが終了するまでUAPに制御は戻ってきません。この場合,クライアント環境定義PDCMDWAITTIMEを指定しておくと,HiRDBクライアント側の長時間待ちを回避できます。
    なお,クライアント側がタイムアウトとなった場合,HiRDB Control Manager - Agentのプロセス,又は実行中のコマンドを,OSのkillコマンド(Windows版の場合はpdkillコマンド)で取り消してください。
  7. HiRDBサーバ接続中に,コマンドの実行が長時間になる場合,クライアント環境定義PDSWAITTIME及びPDSWATCHTIMEによってHiRDBサーバ側でタイムアウトを検知して,接続が終了することがあるので注意してください。

留意事項

  1. COMMAND EXECUTE実行時は,次のクライアント環境定義だけ有効となり,それ以外のものについては無効となります。
    PDCLTPATH,PDASTHOST,PDASTUSER,PDUSER,PDASTPORT,PDCMDWAITTIME,PDCMDTRACE,PDSYSTEMID,PDCLTAPNAME
  2. COBOL言語の場合,COMMAND EXECUTEは実行できません。

使用例

UAP中から,pdlsコマンドを実行します。なお,HiRDB/シングルサーバで実行しているものとします。

EXEC SQL BEGIN DECLARE SECTION;
   char         CmdLine[30000];
   int          ReturnCode;
   int          OutBufLen;
   int          OutDataLen;
   int          DataLength;
   PDOUTBUF     OutBuf ;
   int          CmdRetCode;
   char         EnvGroup[256];
EXEC SQL END DECLARE SECTION;

strcpy(CmdLine,"c:¥HiRDB_S¥bin¥pdls -d trn");
OutBuf = malloc(30000) ;
OutBufLen = 30000 ;
EnvGroup[0] = '¥0';

EXEC SQL COMMAND EXECUTE    :CmdLine,
                           :ReturnCode,
                           :OutBufLen,
                           :DataLength,
                           :OutBuf,
                           :CmdRetCode,
                           :EnvGroup ;

if (ReturnCode == p_rdb_RC_NORM)
{
     if (CmdRetCode == 0)
     {
         printf("%s実行成功¥n",CmdLine) ;
         printf("実行結果:%s¥n",OutBuf) ;
     }
     else
     {
         printf("%s実行失敗¥n",CmdLine) ;
         printf("実行結果:%s¥n",OutBuf) ;
     }
}
else
{
         printf("ReturnCode=%d¥n",ReturnCode) ;
         printf("エラー詳細情報:%s¥n",OutBuf) ;
}