Hitachi

ノンストップデータベース HiRDB Version 10 SQLリファレンス


6.11.1 COMMAND EXECUTEの形式と規則

〈この項の構成〉

(1) 機能

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

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

(2) 形式

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

(3) オペランド

(a) :コマンドライン変数

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

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

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

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

(b) :リターンコード受け取り変数

リターンコード受け取り変数には,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:

そのほかのエラーの場合

(c) :実行結果受け取り領域長変数

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

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

(d) :実行結果長受け取り変数

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

(e) :実行結果受け取り変数

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

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

リターンコード受け取り変数にp_rdb_RC_NORMが設定されている場合:

HiRDBサーバで実行したコマンドラインの実行結果(標準出力と標準エラー出力)が設定されます。

リターンコード受け取り変数にp_rdb_RC_NORM以外が設定されている場合:

障害コードに対応する詳細メッセージが設定されます。

(f) :実行コマンドリターンコード受け取り変数

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

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

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

(g) :環境変数グループ名変数

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

UNIX版の場合:

クライアント環境定義を記述した通常ファイルの名称(ナル文字を含めて256バイト以内)を,絶対パス名で指定します。

Windows版の場合:

HiRDBクライアント環境変数登録ツールで登録したグループ名(ナル文字を含めて31バイト以内)を指定します。

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

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

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

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

(4) 共通規則

  1. 使用する埋込み変数は,埋込み変数宣言節で宣言してください。

  2. COMMAND EXECUTEを実行する場合,次のクライアント環境定義を設定しておく必要があります。

    • PDASTHOST(HiRDB Control Manager - Agentのホスト名)

    • PDASTPORT(HiRDB Control Manager - Agentのポート番号)

    • PDSYSTEMID(HiRDB Control Manager - AgentのHiRDB識別子)

    • PDASTUSER(HiRDBサーバでコマンドを実行する認可識別子)

    クライアント環境定義については,マニュアル「HiRDB 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サーバ側でタイムアウトを検知して,接続が終了することがあるので注意してください。

(5) 留意事項

  1. COMMAND EXECUTE実行時は,次のクライアント環境定義だけ有効となり,それ以外のものについては無効となります。

    PDCLTPATH,PDASTHOST,PDASTUSER,PDUSER,PDASTPORT,PDCMDWAITTIME,PDCMDTRACE,PDSYSTEMID,PDCLTAPNAME

  2. COBOL言語の場合,COMMAND EXECUTEは実行できません。

(6) 使用例

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) ;
}