From RTSC-Pedia

[printable version]  [offline version]

offline version generated on 04-Aug-2010 21:08 UTC

XDCscript - xdc.exec

Execute external command

Synopsis

var exitCode = xdc.exec(command, attrs, status);

Parameters

command 

command line to execute. The program name and arguments can be given either as a single string with whitespace delimiters, or else as an array of strings. The array variant is useful in the case that either the program name or the arguments might contain spaces.

attrs 

optional set of attributes used to control the environment of the command

• envs - array of environment variable settings; e.g., ["foo=bar", "toto=baz"].
• useEnv - if false environment of the calling process is not copied into the environment of the invoked command, only variables in envs are available to the command; if true the environment of the calling process is copied, but if envs contains variables already present in the environment, the values from envs are used. The default is false.
• cwd - the command's current working directory (defaults to ".")
• outName - if defined, the name of the output file to create; if the file exists, output is appended to the end of the file.
• filter - if defined, filter is a string representation of a regular expression used to filter command output. Only the stdout lines that match the Java regular expression are included in the output; the command's stderr output is unaffected by this filter.
• merge - if false the stdout and stderr output streams are not merged into a single output stream. The default value of merge is true.

status 

optional output parameter. If status is non-null, the following fields are set:

• output - string containing all output from command, unless attrs.outName is defined. If attrs.outName is defined the output normally placed in this string is written to the file named by attrs.outName. In addition, if attrs.merge is undefined or true, output contains both the stderr and stdout output of the command.
• errors - if attrs.merge is false, a string containing only the stderr output; output will then contain only the command's stdout output.
• exitStatus - exit status of the command

Description

Execute an arbitrary shell command and optionally put output into a file. Both stderr and stdout are combined into a single output stream.

Locating the Command

The search algorithm used to find command along the search path is similar to the algorithm used in xdc.findFile(). If the specified command is not an absolute path, the value of the PATH environment variable, as specified in the attrs.envs array, will be used to locate the command. If attrs.envs is not specified, the search path is formed as described below for the variable PATH in the command environment. Unlike "normal" shell command path searches, if the command is a relative path, the PATH is still searched: each directory in the PATH is perpended to the command in left-to-right order and the first command file that is found to exist is executed. This allows commands in packages to be executed using the same pattern as that used to find files in packages.

Command Environment

All commands are run with the environment variables specified by attrs.envs and attrs.useEnv. However, the following variables are treated specially in cases when attrs.useEnv is set to false:

• HOME - if not explicitly set in the attrs.envs array or if attrs.envs is undefined, the value of HOME is set to the value of HOME in the caller's environment. If HOME is not set in the callers environment, HOME will not be set in the command's environment.
• SYSTEMROOT - if not explicitly set in the attrs.envs array or if attrs.envs is undefined, the value of SYSTEMROOT is set to the value of SYSTEMROOT in the caller's environment. If SYSTEMROOT is not set in the callers environment, SYSTEMROOT will not be set in the command's environment.
• PATH - if the attrs.envs array is undefined, the value of PATH is set to ".;$XDCROOT;$PATH", where $XDCROOT is the installation directory of the XDCtools and $PATH is the value of the PATH variable in the caller's environment. If attrs.envs is not empty, the value of PATH in the command's environment is the value supplied in attrs.envs. If PATH is not specified in attrs.envs, PATH is not set in the caller's environment.

Command Working Directory

The working directory of all commands is specifed by attrs.cwd. If attrs.cwd is not defined, the command's working directory is set to the current working directory of the caller (".").

Return Value

xdc.exec returns the numeric exit code of the command run. If for any reason the command could not be run, the return value is -1. In addition to the exit code, the optional output parameter status is set as follows:

• output - string containing all output from command, unless attrs.outName is defined. If attrs.outName is defined the output normally placed in this string is written to the file named by attrs.outName. In addition, if attrs.merge is undefined or true, output contains both the stderr and stdout output of the command.
• errors - if attrs.merge is false, a string containing only the command's stderr output, output will then contain only the command's stdout output.
• exitStatus - the numeric exit code from the command

[printable version]  [offline version]

offline version generated on 04-Aug-2010 21:08 UTC