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