COMMAND EXECUTE (Execute commands from a UAP)
Function
COMMAND EXECUTE executes HiRDB and OS commands from within a UAP.
COMMAND EXECUTE cannot be executed if HiRDB Control Manager - Agent has not been installed in the HiRDB server. HiRDB Control Manager - Agent is required because it executes commands.
Format
COMMAND EXECUTE:command-line-variable,
:return-code-receiving-variable,
:execution-results-receiving-area-length-variable,
:execution-results-length-receiving-variable,
:execution-results-receiving-variable,
:executed-command-return-code-receiving-variable,
:environment-variable-group-name-variable
Operands
The command line containing the command to be executed at the HiRDB server is set in the command line variable.
Specify an embedded variable declared as a CHAR type (maximum area length is 30,000 bytes). The command line must end with a null character.
Multiple commands should not be specified in the command line variable. If multiple commands are specified, the integrity of the operation cannot be guaranteed.
A return code from execution of COMMAND EXECUTE is set in the return code receiving variable. Specify an embedded variable declared as an INT type.
Following are the values that can be set in the return code receiving variable; in the event of an error, detailed information is set in the execution results receiving variable:
The area length of the execution results receiving variable is set in the execution results receiving area length variable. Specify an embedded variable declared as an INT type.
The execution results receiving area length should not exceed 2 GB.
The output length for the execution results receiving variable is set in the execution results length receiving variable. Specify an embedded variable declared as an INT type.
The address of the area allocated for receiving execution results is set in the execution results receiving variable. Specify an embedded variable declared as a PDOUTBUF type.
After COMMAND EXECUTE has executed, the following value is assigned to the execution results receiving variable, with any additional trailing data (specified value of execution-results-receiving-area-length-variable - 1) being truncated. A one-byte null character is set at the end of the execution results.
The return code from the command line executed at the HiRDB server is set in the executed command return code receiving variable. Specify an embedded variable declared as an INT type.
A valid value is set in the executed command return code receiving variable only when COMMAND EXECUTE terminates normally (p_rdb_RC_NORM is set in the executed command return code receiving variable).
If the executed command does not output information to the standard output device or to the standard error output device, the value 0 is assigned to the execution command return code-receiving variable.
Specify an embedded variable declared as a CHAR type (maximum area length of 256 bytes).
If environment variable groups are not used, set the NULL character in the first byte.
For details on environment variable groups, see the HiRDB Version 8 UAP Development Guide.
Common rules
Notes
Example
Execute the pdls command from a UAP at a HiRDB/Single Server:
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("%sSuccessful execution\n",CmdLine) ;
printf("Execution results:%s\n", OutBuf) ;
}
else
{
printf("%sExecution failed\n",CmdLine) ;
printf("Execution results:%s\n", OutBuf) ;
}
}
else
{
printf("ReturnCode=%d\n",ReturnCode) ;
printf("Error details:%s\n",OutBuf) ;
}