CALL COMMAND statement (Execute command or utility)

Function

Executes a HiRDB command or utility and obtains the execution results (standard output, standard error output, and the return value).

Privileges

Any user whose authorization identifier is specified in the system common definition pd_sql_command_exec_users operand.

Format

 CALL COMMAND {:embedded-variable-1|?-parameter-1|literal-1}
       [WITH {:embedded-variable-2|?-parameter-2|literal-2}[,  {:embedded-variable-2|?-parameter-2|literal-2}]...]
       [INPUT {:embedded-variable-3|?-parameter-3|literal-3}]
       [OUTPUT TO {:embedded-variable-4 :indicator-variable-1|?-parameter-4}]
       [ERROR TO {:embedded-variable-5 :indicator-variable-2|?-parameter-5}]
       [RETURN CODE TO {:embedded-variable-6|?-parameter-6}]
       [ENVIRONMENT {:embedded-variable-7|?-parameter-7|literal-4}]
       [SERVER {:embedded-variable-8|?-parameter-8|literal-5}]

Operands

Specifies the embedded variable, ? parameter, or literal containing the name of the command or utility to be executed. The name of the command or utility cannot be specified using an absolute or relative path name. The data type of the embedded variable or ? parameter must be a variable-length string with a maximum length of 30 bytes. Alternatively, if UTF16 is specified as the character set of the embedded variable or ? parameter, it must be a variable-length character string with a maximum length of 60 bytes. A literal must be no more than 30 bytes long.

Specifies embedded variables, ? parameters, or literals containing arguments to be passed to the command or utility. If there is a long list of arguments that cannot be specified in a single embedded variable, ? parameter, or literal, they can be specified using multiple embedded variables, ? parameters, or literals. In this case, the strings are concatenated in the order in which they are specified. To pass more than one argument, separate them with semicolons. If the argument itself is a semicolon, specify two consecutive semicolons. The data type of an embedded variable or ? parameter must be a variable-length string with a maximum length of 32,000 bytes. The length of a literal can be no more than 32,000 bytes. If an argument contains a path it must be an absolute path.

Specifies an embedded variable, ? parameter, or literal that contains the contents of the standard input to be passed to the command or utility to execute. The data type of an embedded variable or ? parameter must be a variable-length string with a maximum length of 32,000 bytes. The length of a literal can be no more than 32,000 bytes. For a command or utility that requires password input, the INPUT clause cannot be used to pass the password.

Specifies an embedded variable or a ? parameter to be used to store the contents of the standard output of the command or utility being executed. The data type of the embedded variable or ? parameter must be a binary data string (BLOB) with a maximum length of two gigabytes. If the standard output is longer than the maximum length of the embedded variable or ? parameter, the information from the beginning of the output up to the maximum length will be stored, and any further information will be truncated. In this case, an indicator variable will be used to store the length of the standard output, indicating that the output was truncated. Always make sure to specify an indicator variable whenever embedded variables are used.

Specifies an embedded variable or ? parameter to be used to store the contents of the standard error output of the command or utility being executed. The data type of the embedded variable and ? parameter must be a binary data string (BLOB) with a maximum length of two gigabytes. If the standard error output is longer than the maximum length of the embedded variable or ? parameter, the information from the beginning of the output up to the maximum length will be stored, and any further information will be truncated. In this case, an indicator variable will be used to store the length of the standard error, indicating that the output was truncated. Always make sure to specify an indicator variable whenever embedded variables are used.

Specifies the embedded variable or ? parameter to be used to store the return value of the command or utility being executed. The data type of the embedded variable or ? parameter must be an integer type.

Specifies the embedded variable, ? parameter, or literal that will contain the client environment definition when the command or utility is executed. The data type of an embedded variable or ? parameter must be a variable-length string with a maximum length of 32,000 bytes. The length of a literal can be no more than 32,000 bytes.

A client environment definition is specified in the format client-environment-definition-name = value. To specify multiple client environment definitions, separate them with semicolons. If the argument itself is a semicolon, specify two consecutive semicolons.

The default client environment definition for the environment in which the command or utility is to be executed inherits the client environment definition (PDDIR, PDCONFPATH, and so on) set when HiRDB was started. It also inherits the client environment definition that is set using the putenv format in the system definition. For details about the client environment definitions that you can specify, see the HiRDB Version 9 UAP Development Guide.

Specifies an embedded variable, ? parameter, or literal that contains the name of the server on which the command or utility is to be executed. The server name refers to the server name specified in the -s option of the pdstart operand in the system common definition. The data type of an embedded variable or ? parameter must be a variable-length string with a maximum length of eight bytes. However, if UTF16 is specified as the character set of the embedded variable or ? parameter, it must be a variable-length string with a maximum length of 16 bytes. The maximum length of a literal is eight bytes. To specify the System Manager Unit in a HiRDB/Parallel Server environment, specify MGR. If the SERVER clause is omitted, the MGR server name is assumed in a HiRDB/Parallel Server environment, and the SDS server name is assumed in HiRDB/Single Server environment.

Common rules

  1. If a transaction is initiated by the command or utility that was executed, it will be independent from the transaction that executed the SQL.
  2. A lock-release wait or deadlock may occur between the transaction that executed the SQL and the transaction initiated by the command or utility that was executed.
  3. When a command or utility that requests a response is executed, passing the contents of standard input may cause the system to become unresponsive if the command or utility cannot be properly terminated.
    Example:
    Execute a backup (pdfbkup) of the HiRDB file system (/hirdb/ios/db0):
    When the pdfbkup command is run from the command line, it requests user input of G to continue the backup or T to confirm its termination, followed by a carriage return (CR).

     % pdfbkup /hirdb/ios/db0 /hirdb/ios/db0.backup
     1605756 19:27:29 SQA2          KFPI21514-Q HiRDB file system area
     /hirdb/ios/db0 backup to /hirdb/ios/db0.backup. [G:continue, T:terminate]

    In the following CALL COMMAND statement, the system becomes unresponsive when the standard input, which does not contain a carriage return, is passed to the pdfbkup command.

     EXEC SQL CALL COMMAND 'pdfbkup' WITH '/hirdb/ios/db0;/hirdb/ios/db0.backup' INPUT 'G';

    In order to execute the pkfbkup command correctly, the standard input must include a newline in the INPUT clause as follows:

     EXEC SQL BEGIN DECLARE SECTION;
             char input_data[10];
     EXEC SQL END DECLARE SECTION;
     sprintf(input_data, "G\n");
     EXEC SQL CALL COMMAND 'pdfbkup' WITH '/hirdb/ios/db0;
     /hirdb/ios/db0.backup' INPUT :input_data;

    If the system becomes unresponsive, use the pdcancel command to terminate the HiRDB process (FES for HiRDB/Parallel Server and SDS for HiRDB/Single Server) and the command or utility process.

Notes

  1. If a timeout of the command or utility is required, specify the PDCALCMDWAITTIME operand in the client environment definition. If the operand times out during the execution of the command or utility, terminate the control command (pdcmdexec) process, and the executing command or utility process using the pdkill command (or the OS kill command in UNIX).
  2. The command or utility may fail to execute depending on the limitations of the execution platform. The following table lists the information to obtain and where that information is stored if the execution of the command or utility fails.

    Table 5-2 Information to obtain and where it is stored if execution of the command or utility fails

    Information to obtainWhere the information to obtain is stored
    • System function name where the error occurred#
    • Error code#
    embedded-variable-5 or ?-parameter-5
    Exit code of the OS system functionembedded-variable-6 or ?-parameter-6
    #
    The error code and the system function where the error occurred are output in the format func=aa....aa,errno=bb....bb (where errno indicates an external integer variable representing the error state).
    aa....aa: System function where the error occurred
    bb....bb: Error code (empty if the error code cannot be obtained)
    Corrective action
    Investigate the error code in errno.h or in the appropriate OS user documentation, eliminate the cause of the error, and execute again.
    One likely reason for an OS system function to fail to execute is that the arguments specified for the command or utility exceed the command line argument length limit defined in the OS. To resolve this issue, adjust the OS to increase the command line argument length limit.

Examples

  1. Use the HiRDB system status display (pdfls) to obtain a list of HiRDB files in the HiRDB file system area (/hirdb/ios/rdfiles). Assign the execution result to the embedded variable (:OUTPUT) specified in the OUTPUT TO clause. This yields the same result as running pdfls -H /hirdb/ios/rdfiles from the command line.

     EXEC SQL BEGIN DECLARE SECTION;
             SQL TYPE IS BLOB(1M) OUTPUT;
     EXEC SQL END DECLARE SECTION;
     EXEC SQL CALL COMMAND 'pdfls' WITH '-H;/hirdb/ios/rdfiles' OUTPUT TO :OUTPUT;

  2. Use the RDAREA hold command (pdhold) to hold the RDAREAs (RU01, RU02, and RU03). Assign the execution result to the embedded variable (:OUTPUT) specified in the OUTPUT TO clause. This yields the same result as running pdhold -r RU01,RU02,RU03 from the command line.

     EXEC SQL BEGIN DECLARE SECTION;
             SQL TYPE IS BLOB(1M) OUTPUT;
     EXEC SQL END DECLARE SECTION;
     EXEC SQL CALL COMMAND 'pdhold' WITH '-r;RU01,RU02,RU03' OUTPUT TO :OUTPUT;

    More than one literal can be specified in the WITH clause, as follows:

     EXEC SQL BEGIN DECLARE SECTION;
             SQL TYPE IS BLOB(1M) OUTPUT;
     EXEC SQL END DECLARE SECTION;
     EXEC SQL CALL COMMAND 'pdhold' WITH '-r;RU01',',RU02,RU03' OUTPUT TO :OUTPUT;

    A literal and an embedded variable can be specified in the WITH clause, as follows:

     EXEC SQL BEGIN DECLARE SECTION;
             SQL TYPE IS BLOB(1M) OUTPUT;
             char RDAREAS[100];
     EXEC SQL END DECLARE SECTION;
     sprintf(RDAREAS, "RU01,RU02,RU03");
     EXEC SQL CALL COMMAND 'pdhold' WITH '-r;',:RDAREAS OUTPUT TO :OUTPUT;