How steps run

In a step definition, the command property contains operating system commands, dot commands, or a combination of both.

You can run more than one command in an individual step. Separate individual commands by placing them on separate lines.

Note: When you use the default Exit Code setting for the Result property of your step, the success or failure of the entire step is based on the exit code returned by the last command in the step. To detect failure in any of the commands, create a Log Filter and specify its use in the Result property.

Before the system runs a step, it constructs the step environment. Variables are set using values specified in the server environment, project environment, and step environment. See Environment inheritance. By default, the variables are parsed and then available to use in commands. See Interpretation of variables in steps.

Specifying a shell

You can use the #! directive to specify the shell to use to run the commands. This works on Windows^® as well as Linux^® and UNIX^® systems (the Windows agent handles passing the commands to the specified interpreter). To send the commands from your step to a copy of Perl in C:\perl\bin on Windows, use #!C:\perl\bin\perl.exe. If you use the Windows agent with Cygwin, but need to direct a command to the Windows shell cmd.exe, you can use the following line, which takes advantage of Windows implicit paths:

#!cmd.exe /C

Note that the /C option is required for cmd.exe as otherwise it waits for additional commands after your step commands are delivered to it. You might use the #!/bin/perl command on a UNIX or Linux computer.

Note: When you use the #! command on Linux or UNIX systems, the system does not change to the standard default directory (the path constructed from a combination of the server path, project, name, and step path field) because it cannot predict the required syntax; you must include your own directory-changing command. Use special environment variables created by the system, such as BF_SERVER_ROOT and BF_PROJECTNAME_PHYS, to do this.

How the system splits a step into parts

Rational^® Build Forge^® splits a step into parts, with each part formed by a set of operating system commands or a single dot command. For example, the following step has six parts.

cmd1        # Part 1
cmd2
.dot_cmd1   # Part 2
cmd3        # Part 3
cmd4
.dot_cmd2   # Part 4
.sleep 30   # Part 5
.dot_cmd3   # Part 6

The step parts run in sequence. The environment from each part is passed to the next part. When an error occurs in any part, the processing stops immediately.

Previous releases required each part from the step above to be a single step.

Note: Do not create references between parts. Do not create jumps between parts, such as using a GOTO in one part and its destination label in another part.