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:

p_rdb_RC_NORM
Command executed normally at the HiRDB server.
p_rdb_RC_ERRPARM
There was an invalid argument.
p_rdb_RC_PROTO
A communication error occurred.
p_rdb_RC_NOTF
No environment variable group was found.
p_rdb_RC_TIMEOUT
Timeout occurred.
p_rdb_RC_SQLERR
Some other error occurred.

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.

p_rdb_RC_NORM set in the return code receiving variable:
The results line (standard output and standard error output) of executing the command at the HiRDB server is set.
Anything other than p_rdb_RC_NORM set in the return code receiving variable:
A detailed message associated with the error code is set.

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.

UNIX version
Specify as an absolute path name the name (1-256 bytes, including NULL characters) of the normal file in which the client environment definition is defined.
Windows version
Specify a group name (1 to 31 bytes, including NULL characters) that was registered using the HiRDB client environment variable registration tool.

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

  1. All embedded variables that are used must be declared in the embedded variables declaration section.
  2. To use COMMAND EXECUTE, the following client environment definition statements must be specified:
    • PDASTHOST (host name of HiRDB Control Manager - Agent)
    • PDASTPORT (port number of HiRDB Control Manager - Agent)
    • PDSYSTEMID (HiRDB identifier of HiRDB Control Manager - Agent)
    • PDASTUSER (authorization identifier for executing commands on the HiRDB server)
    For details on client environment variable definitions, see the HiRDB Version 8 UAP Development Guide.
  3. COMMAND EXECUTE can be executed while the UAP is connected to HiRDB. However, because control does not return to the UAP until the command terminates, take care so that deadlock does not occur.
  4. Do not specify a command that requires a response. HiRDB Control Manager - Agent does not accept requests for entry of a response, so such a command terminates in an error.
  5. Any command input file to be executed should be set up at the HiRDB server in advance.
  6. Even if execution of the command takes a very long time, control does not return to the UAP until the command terminates. You can specify PDCMDWAITTIME in the client environment definition so that the HiRDB client does not have to wait for too long a time.
    If the client does time out, use the OS's kill command (pdkill command in the Windows version) to cancel the HiRDB Control Manager - Agent process or the command being executed.
  7. Note that if execution of the command takes a very long time during connection to the HiRDB server, specification of PDSWAITTIME and PDSWATCHTIME in the client environment definition can cause the HiRDB server to detect the timeout and terminate the connection.

Notes

  1. During execution of COMMAND EXECUTE, only the following client environment definition settings are in effect:
    PDCLTPATH, PDASTHOST, PDASTUSER, PDUSER, PDASTPORT, PDCMDWAITTIME, PDCMDTRACE, PDSYSTEMID, PDCLTAPNAME
  2. For the COBOL language, COMMAND EXECUTE cannot be executed.

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