<execNative> Step

The <execNative> step executes a command native to the operating system on the target host. If the command produces an unexpected result, the step fails and execution stops.

The <execNative< step has the following child elements:

• <env> – An optional element that specifies environment variables for the child process. For each environment variable, specify one <env> element.

• <background> – An optional element that specifies that the command is to run as a background process. If you specify this element, it can only appear one time. If you specify the <background> element, you must also specify the <outputFile> and <errorFile> elements.

• <outputFile> – An optional element that is the name of the file in which to store standard output from the command. If you specify this element, it can only appear one time. This element is required if the <background> element is specified.

• <errorFile> – An optional element that is the name of the file in which to store standard error output from the command. If you specify this element, it can only appear one time. This element is required if the <background> element is specified.

• <inputText> – An optional element that is text to be used as standard input to the command. If you specify this element, it can only appear one time. This element is mutually exclusive with the <inputFile> element.

• <inputFile> – An optional element that is the name of the file to be used as standard input to the command. If you specify this element, it can only appear one time. This element is mutually exclusive with the <inputText> element.

• <exec> – A required element that specifies the name of the executable to run. This element is mutually exclusive with the <shell> element.

• <shell> – A required element that specifies a shell command to run. This element can only appear one time. This element is mutually exclusive with the <exec> element.

• <successCriteria> – An optional element that is the criteria used to determine whether this step succeeded or failed. If you specify this element, it can only appear one time.

Attributes for the <execNative> Step

The <execNative> step has the following attributes:

• userToRunAs – An optional attribute that is the name of the user to run this command. If this attribute is omitted, the command is run as the value of defaultUserToRunAs in the configuration file. The value can be either a string user name or a numeric user ID. The value should be a nonempty string. This attribute can reference simple substitution variables.

• dir – An optional attribute that is the absolute path to the working directory for the command. If this attribute is omitted, the value defaults to the agent-specific configurable directory. This value should be a nonempty string. This attribute can reference simple substitution variables.

• timeout – An optional attribute of type positiveInteger, which specifies the number of seconds to wait for the command to complete before timing out. If this attribute is omitted, the plan's <execNative> timeout period applies. The value should be greater than 0.

<env> Element

The <execNative> element can optionally have <env> elements to specify environment variables for the command. You can use <env> to supply new variables for the command's environment or to override existing variables.

The set of the command's environment variables is a union of the set of the remote agent's environment variables and the variables supplied by using the <env> elements.

Attributes for the <env> Element

The <env> element has the following attributes. They can reference simple substitution variables.

• name – A required attribute that is the name of the environment variable. The value should be a nonempty string.

• value – A required attribute that is the value of an environment variable. The value can contain ${var-name} strings to refer to the values of the remote agent's environment variables. If var-name refers to a variable that is overridden by an <env> element, the substituted value is the one that is defined in the remote agent's environment, not the overridden one. If the string ${ must appear in the value, escape this string by using ${{. All instances of ${{ are replaced by ${.

<background> Element

The <background> element is a child of the <execNative> element. When present, this element specifies that the command should be executed as a background process. This element has no attributes or child elements.

An <execNative> with a <background> element has the following constraints:

• <successCriteria> need not be specified. The step succeeds if no issues arise when starting the background process. If specified, the <successCriteria> is tested against the script that is used to run the command as a background process.

• No standard output or standard error output is captured for the executed command.

  By viewing the details in the browser interface, you see an exit status of 0 and the empty standard output and standard error output. However, if problems occurred when starting the native command in the background, a different exit status is shown. The value depends on the nature of the error and diagnostic output.

• The <outputFile> and <errorFile> elements must be specified. If the specified files already exist, they are overwritten.

<outputFile> Element

The <outputFile> element is a child of the <execNative> element. The <outputFile> element specifies the path to a local file on the agent in which to store the standard output of the command that is being executed. Specify the path to the local file by using the <outputFile> name attribute. Relative paths are interpreted as being relative to the command's working directory.

You must specify the <outputFile> element if you specify the <background> element.

If <outputFile> is not specified and the <successCriteria> element does not specify outputMatches, the command output is not stored and will be lost. If outputMatches is specified, the standard output is stored in a temporary file that is deleted after the command finishes executing.

Attributes for the <outputFile> Element

The <outputFile> element has one required attribute, name, which is the name of the file to which the standard output of the command is written. This value should be a nonempty string. This attribute can reference simple substitution variables.

<errorFile> Element

The <errorFile> element specifies the path to a local file on the agent in which to store the error output of the command that is being executed. The path to the local file is specified by using the <errorFile> name attribute. Relative paths are interpreted as being relative to the command's working directory.

You must specify the <errorFile> element if you specify the <background> element.

If <errorFile> is not specified and the <successCriteria> element does not specify errorMatches, the command output is not stored and will be lost. If errorMatches is specified, the error output is stored in a temporary file that is deleted after the command finishes executing.

Attributes for the <errorFile> Element

The <errorFile> element has one required attribute, name, which is the name of the file to which the standard error output of the command is written. This value should be a nonempty string. This attribute can reference simple substitution variables.

<inputText> Element

The <inputText> element is a child element of the <execNative> element. This child element specifies the arbitrary text that should be used as standard input to the command. The text is specified as the contents of this element.

<execNative>
    <inputText>
        ls -l | fgrep `*test*' | sort -u > file.out
    </inputText>
    <command exec=”sh”/>
</execNative>

The body of the <inputText> element can be enclosed in a CDATA section to preserve the formatting of the input and to avoid parsing errors that might be caused by input that contains the & and < characters.

If the <inputText> is specified, it is always enclosed within a CDATA section when generating XML for the <execNative> step. All of the characters within <inputText> are passed as standard input to the command that is being executed. If <inputText> contains only white spaces, those white spaces are passed, exactly as specified, to the command that is being executed.

The contents of <inputText> are config-generated.

The <inputText> element has no attributes.

<inputFile> Element

The <inputFile> element is a child element of <execNative>. This child element specifies the path to a local file on the remote agent whose contents are used as standard input to the command being executed. The path to the local file is specified by using the <inputFile> name attribute.

The <inputFile> element cannot be used with the <inputText> element in an <execNative> command.

Attributes for the <inputFile> Element

The <inputFile> element as one required attribute, name, which is the file to act as standard input to the command. This value should be a nonempty string. If a relative path is specified, it is relative to the command's working directory. This attribute can reference simple substitution variables.

<exec> Element

An <execNative> step can contain only one <exec> element. The <exec> element specifies the details of the native command to be executed.

The <exec> element contains the following attributes:

• A cmd attribute that specifies the name of the command to execute

• A set of nested <arg> elements for each of the arguments of the cmd command

<execNative> executes the command specified by cmd with the arguments in the order in which they are specified.

For example, the following <execNative> step executes the ps -fu sps command:

<execNative>
    <exec cmd=”ps”>
        <arg value=”-fu”/>
        <arg value=”sps”/>
    </exec>
</execNative>

The <exec> element has an optional child element, <arg>. Specify one <arg> element for each argument to the command that you want to execute.

The <arg> element has one required attribute, value, which is the argument value. This argument is supplied as the nth argument to the command, where <arg> is the nth child of the command element. This attribute can reference simple substitution variables.

Attributes for the <exec> Element

The <exec> element has one required attribute, cmd, which is the path of the command to execute. If the specified path is not absolute, the command is found by using the platform-specified PATH environment variable set for the remote agent. This value should be a nonempty string. This attribute can reference simple substitution variables.

<shell> Element

The <shell> element is a child element of <execNative>. The contents of the <shell> element specifies the command to be executed. The command to be executed is interpreted using an interpreter, which is specified by the cmd attribute. The command is executed by using sh -c “command” syntax for the platform. In this form, the cmd attribute must be specified to indicate the shell command to use to execute the command.

For example:

<execNative>
    <shell cmd=”/usr/bin/bash -c”>
        ls -l | fgrep `*test*' | sort -u > file.out
    </shell>
</execNative>

The previous <execNative> example executes the following command:

/usr/bin/bash -c `ls -l | fgrep `*test*' | sort -u > file.out'

To preserve formatting and to avoid XML parsing problems, the text contents of the command is always enclosed within a CDATA element when the XML representation is generated from the <execNative> step.

A command string cannot be empty or contain only white space characters. The command string is supplied exactly as it is specified, including surrounding white space, to the shell.

The contents of the <shell> element are config-generated.

Attributes for the <shell> Element

The <shell> element has one required attribute, cmd, which is the shell command in the sh -c syntax. The string should not contain any embedded quote characters. The string is parsed to retrieve the shell name and the arguments by using white space as delimiters. For example, /usr/bin/bash -c should be a nonempty string. This attribute can reference simple substitution variables.

<successCriteria> Element

The <successCriteria> element is a child element of <execNative>. This child element specifies the criteria to be used to evaluate whether an <execNative> step executed successfully. If this element is not specified, the default value is <successCriteria status=”0”/>.

If the specified <successCriteria> is empty, it is ignored.

If you specify <successCriteria/>, the step always succeeds no matter what output or exit code the command generated.

Attributes for the <successCriteria> Element

The <successCriteria> element has the following optional attributes. If more than one of the status, outputMatches, and errorMatches attributes are specified, they are ANDed together.

• status – An optional attribute of type integer, which is the desired exit status of the command. This value should be a positive integer.

• outputMatches – An optional attribute that is a regular expression to match the standard output that is generated by the command. This value should be a nonempty string. This attribute can reference simple substitution variables.

• errorMatches – An optional attribute that is a regular expression to match the standard error output that is generated by the command. This value should be a nonempty string. This attribute can reference simple substitution variables.

• inverse – An optional attribute of type Boolean, which, if set to true, negates each of the conditionals specified in <successCriteria>. The default value is false. The step succeeds only if the conditions that are specified through each attribute of <successCriteria> are not met.

  For example, an <execNative> step with the following <successCriteria> succeeds if status is not 1, the standard output does not match bin, and standard error does not match none.

  <successCriteria status=”1” outputMatches=”bin” errorMatches=”none” inverse=”true”/>

  A <successCriteria> element that contains only the inverse attribute is saved without the inverse attribute. So, if you specify the following statement, the element is stored as <successCriteria/>, and the <successCriteria> element is ignored.

  <successCriteria inverse=”true”/>