The Integrator Execrows output object allows Integrator scripts to execute command scripts based upon Integrator input. It takes a data flow as input; for each row of this data flow, it executes a series of commands, substituting parameters based on the data flow columns.
NOTE: Since the introduction of DI-Production, DI highly recommends using the Production Execute process node instead of the Integrator Execrows output object (see Execute Process Node).
On the OS/400, the commands are in the format of Q-shell commands rather than Command Line commands. This setup allows the use of Q-shell utility functions, such as "cat", "rm", etc. DI programs such as Builder and Integrator can be executed by giving the full Integrated File System pathname to the process object. For example:
/QSYS.LIB/ATLANTIS.LIB/INTEG.PGM sales.dsc
Command Line commands can be executed by using them as the argument to the "system" command. For example:
system "CRTLIB ATLANTIS"
Integrator uses the PATH environment variable (set using ADDENVVAR or CHGENVVAR) to locate commands that are not given by a full pathname. If no PATH variable is set, the PATH defaults to "/usr/bin:%LIB%".
Keep the following points in mind when using Execrow objects:
- Integrator parameter substitution only happens on parameter strings (defined using back quotes `), and the Integrator parameter substitution happens first.
- On Windows platforms, built-in DOS commands (COPY, DEL, DIR, ECHO, MKDIR, MOVE, RD, RENAME, and RMDIR) cannot be executed directly. Instead, they must be run within a command interpreter. Integrator detects references to these built-in commands and invokes the command interpreter on them.
For example, Integrator will convert the command "echo This is a test" to "cmd.exe /c echo This is a test".
Execrows Attributes
| Attribute | Type | Description |
|---|---|---|
| output_type (required) |
String | Identifies the object as an Execrows output object. The value of the string is "execrows". |
| input (required) |
String | Defines the object from which the data flow is arriving. |
| command | String | Defines a single command to execute for each row. Either command or commands is a required attribute. Before executing the command for a row, Integrator substitutes Execrows column parameters with the corresponding column values. An Execrows column parameter consists of a "$" followed by a column name consisting of alphanumeric characters and underscores. To accommodate non-alphanumeric column names and to allow alphanumeric strings to immediately follow the parameter, the column name can also be enclosed in parentheses following the "$". "$" can be included in the command strings by using two "$"'s ("$$"). For example: `echo The dollar sign is $$`. If a dash ("-") precedes a command, when the command is executed, any error from it is ignored. If a command begins with an ampersand ("&"), the command will be run as a background process, and the next command (regardless of row) will start running before the background process finishes. This allows commands to be run in parallel. To direct the output of the different commands to different files, the Execrows object supports the redirection (">") character present in UNIX and DOS shells. If a command contains an unquoted or unescaped ">", the output of the command will be directed to the file named following the ">". If the filename contains spaces, then the filename should be enclosed in double-quotes. When executing commands in Linux/UNIX via execrows, note that some characters (e.g., "$”) have special meanings. Enclose text containing the special character in single quotes to prevent the special character interpretation. The Execrows object will continue to process additional rows when there are background processes, but will not finish the task until all background processes end. On Windows and OS/ 400, only 64 processes can be run simultaneously. Examples:
|
| commands | Array of Strings | Defines multiple commands to execute for each row. Before executing a command for a row, Integrator substitutes Execrows column parameters with the corresponding column values, as defined in the command attribute description above.
Either commands or command is a required attribute. |
| output_file | String | Contains the filename of an output file to receive the output of the command(s). If specified, standard output and standard error output will be written to the given file. If not specified, standard output and standard error output will be included in the Integrator output. |
| append_output | Boolean | When "true", indicates that the output_file is not cleared before new output is added. |
| error_command | String | This optional attribute specifies a command that will be executed if an error occurs running the command or commands above. Execrows column parameter substitution will be performed as described for the command attribute. This error_command is not run for:
Example: error_command = "echo ERROR in EXECROWS object in Script XYZ", |
| echo | Boolean | Controls whether or not the commands are printed to the Integrator standard output as they are executed. By default, the commands are not echoed. |
| chdir | String | Defines the working directory to be set for commands that are run. If not defined, the commands are executed using the working directory for Integrator itself. |
| add_environment | Array of strings | Specifies new or updated environment variables to set before running the given commands. This attribute is an array of strings of the format "environment variable=environment value". Existing environment variables that are not listed are not changed and will be passed to the commands. (Available as of |
| trace_before | Sub-object | Traces data flows entering the specified object. This is equivalent to adding the Trace process object immediately before the current output object. See Embedded Trace Object. |