N1 Service Provisioning System 4.1 Reference Guide

execNative Step

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

execNative Step attributes

Name	Type	Required	Configurable	Description
userToRunAs	String	No	Yes	The user to run this command as. If specified, the command is executed as this user; otherwise it's run as the defaultUserToRunAs in the config file. The value can be either a string username or a numeric UID. It should be a non-empty string.
dir	String	No	Yes	The absolute path to the working directory for the command. If not specified defaults to agent-specific configurable directory. Should be a non-empty string
timeout	positive Integer	No	No	Specifies the number of seconds to wait for the command to complete before timing it out. If not specified the plan's exec native timeout period applies. Should be a value greater than 0.

execNative can have nested elements to specify the:

Environment variables
Background execution
Command standard output file
Command error output file
Command input
Command to execute
Step success criteria

execNative Element child elements

Name	How Many?	Description
env	0 or more	Environment variables for the child process
background	0 or 1	Specifies that the command should be executed as a background process
outputFile	0 or 1 1	The name of the file in which to store the command's standard output
errorFile	0 or 1 1	The name of the file in which to store the command's standard error output.
inputText	Only 1 of these elements may be specified 2	The text to feed to the command's standard input. This element cannot be specified if inputFile is specified.
inputFile	Only 1 of these elements may be specified 2	The name of the file from which to read command's standard input
exec	1 of these elements must be specified 3	Specifies the executable to execute
shell	1 of these elements must be specified 3	Specifies the shell command to execute
successCriteria	0 or 1	The criteria to evaluate if this step was successful or not.

1 Both <outputFile> and <errorFile> must be specified if <background> element is specified.

2 inputText and inputFile elements are optional. Only one of them may be specified at a time.

3 One of exec or shell elements must be specified. It is illegal to have both exec and shell elements in an execNative element.

The <inputText> and <inputFile> elements are optional. Only one of them may be specified at a time.

One of exec or shell elements must be specified. It is illegal to have both exec and shell elements in an execNative element.

The env Child Element

The <execNative> element may 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 over-ride existing variables.

The set of the command's environment variables will be a union of the set of Remote Agent's environment variables and the variables supplied using the <env> tags.

env Element attributes

Name	Type	Required	Configurable	Description
name	String	Yes	Yes	The name of environment variable. Should be a non-empty string
value	String	Yes	Yes	The value of the environment variable. The value may contain ${var_name} strings to refer to the values of RA's environment variables. If var_name refers to a variable over-ridden using the env tag, its substituted value the one defined in RA's environment, not the over-ridden one. If ${ needs to appear literally ${{ may be used. All instances of ${{ will be replaced by ${.

background element

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

For an <execNative> with a <background> element, the following constraints apply.

<successCriteria> need not be specified. The step will succeed if there were no issues starting off 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 error output will be captured for the executed command. Clicking on details will show exist status as 0 and the empty output and error output. However in case there were problems starting the native command in background, you will see a different exit status, depending on the nature of the error and diagnostic output.
The <outputFile> and <errorFile> elements must be specified. If the specified files already exist, they will be overwritten.

outputFile element

The outputFile element is used to specify the path to a local file on the agent in which the standard output of the command being executed should be stored. The path to the local file is specified through the name attribute in the outputFile element. Relative paths are interpreted relative to the command"s working directory.

The outputFile element must be specified if the background element is specified.

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

outputFile Attributes

Name	Type	Required	Configurable	Description
name	String	Yes	Yes	The file to write the standard output of the command to. Should be a non-empty string.

errorFile element

The errorFile element is used to specify the path to a local file on the agent in which the error output of the command being executed should be stored. The path to the local file is specified through the name attribute in the errorFile element. Relative paths are interpreted relative to the command"s working directory.

The errorFile element must be specified if the background element is specified.

If errorFile is not specified and the successCriteria element doesn"t specify an errorMatches, the respective output of the command will not be stored and will be lost. If errorMatches is specified, the error output will be stored in a temporary file and that will be deleted after command is done executing.

errorFile Attributes

Name	Type	Required	Configurable	Description
name	String	Yes	Yes	The file to write the error output of the command to. Should be a non-empty string.

The inputText Child Element

The <inputText> element is a child element of <execNative>. The <inputText> element specifies any arbitrary text that should be fed into the command's standard input. The text is specified as contents of this element.

You can use <inputText> to enclose input in CDATA sections, preserving the formatting of the input and avoiding parse errors that might be caused by input containing the characters `& and `<'.

For example:

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

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

The contents of <inputText> are config-generated.

The <inputText> element has no attributes.

inputFile Child Element

The <inputFile> element is a child element of <execNative>. The <inputFile> element specifies the path to a local file on the Remote Agent whose contents should be fed into the standard input of the command being executed. The path to the local file is specified through the name attribute in the <inputFile> element.

Note –

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

inputFile Element attributes

Name	Type	Required	Configurable	Description
name	String	Yes	Yes	The file to read the input of the command from. Should be a non-empty string. If relative path is specified, it is taken relative to the command's working directory.

The exec Child Element

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

The <exec> element contains:

an attribute, cmd, that specifies the name of the command to execute
a set of nested arg elements that specify each of the arguments for the command specified with cmd.

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

For example, the <execNative> step below:

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

will execute the command: ps –fu sps.

exec Element attributes

Name	Type	Required	Configurable	Description
cmd	String	Yes	Yes	The path of the command to execute. If the specified path is not absolute the command is looked up using the platform specified PATH environment variable setting for the RA. Should be a non-empty string

exec Element child elements

Name	How Many?	Description
arg	0 or more	The arguments to the command being executed. Each arg element defines one positional parameter to the command.

arg Child Element attributes

Name	Type	Required	Configurable	Description
value	String	Yes	Yes	The argument value. This argument will be supplied as the nth argument to the command where arg is the nth child of the command element.

The shell Child Element

The <shell> element is a child element of <execNative>. The <shell> element specifies the command to be executed as its content. The command to be executed is interpreted using an interpreter specified using the cmd attribute. The command thus specified is executed using sh –c `command' syntax for the platform. In this form the cmd attribute has to 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>

This code executes the 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 will always be enclosed within a CDATA element when generating XML representation from the <execNative> step.

It is illegal for command string to be empty or have only white space characters. The command string is supplied exactly as it is specified (with surrounding white space) to the shell.

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

Attributes of the shell Element

Name	Type	Required	Configurable	Description
cmd	String	Yes	Yes	The shell command in the `sh –c' syntax. The string should not contain any embedded quote characters. The string will be parsed to retrieve the shell name and the arguments using white space a delimiters. For example `/usr/bin/bash –c' should be a non-empty string

The successCriteria Element

The <successCriteria> element is a child element of <execNative>. The <successCriteria> element specifies the criteria to be used to evaluate whether or not an <execNative> step executed successfully. If this element is not specified, the default value is:

<successCriteria status=”0”/>

The successCriteria is ignored if an empty successCriteria is specified. If you specify the tag:

<successCriteria/>

The step will always succeed no matter what output or exit code the command generated.

successCriteria Element attributes

Name	Type	Required	Configurable	Description
status	integer	No (If more than one is specified, then these conditions are AND-ed together.)	No	The desired exit status of the command. Should be a positive integer.
outputMatches	String		Yes	The regular expression to match with the standard output generated by the command. Should be a non-empty string
errorMatches	String		Yes	The regular expression to match the standard error generated by the command. Should be a non-empty string
inverse	Boolean	No	No	If set to true the conditional expressed by echo element of success criteria is negated. The default value is false. That is the step succeeds only if the conditions specified through each attribute of successCriteria are not met

If the inverse attribute is set to true, it negates each of the conditions specified within <successCriteria>.

For example, an <execNative> step with the following successCriteria

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

will succeed if status is not 1 and output does not match `bin' and error does notmatch `none'.

<successCriteria> element that contains only the inverse attribute will be saved without the inverse attribute. That is if you specify

<successCriteria inverse=”true”/>

It will be stored as:

<successCriteria/>

The result will be that <successCriteria> is ignored.