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} |
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
% 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]
EXEC SQL CALL COMMAND 'pdfbkup' WITH '/hirdb/ios/db0;/hirdb/ios/db0.backup' INPUT 'G';
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;
Notes
Table 5-2 Information to obtain and where it is stored if execution of the command or utility fails
Information to obtain | Where the information to obtain is stored |
---|---|
| embedded-variable-5 or ?-parameter-5 |
Exit code of the OS system function | embedded-variable-6 or ?-parameter-6 |
Examples
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;
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;
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;
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;