This tab of the Run Program action configures information about the program or command to be run.

 

Command: Specifies the command to invoke.  It can contain the executable name plus any parameters that should be passed to it (parameters that contain spaces must be surrounded in double quotes).  If an absolute path is not specified and the executable is not found in the current path, the Windows directory, the Windows System directory, or the PATH environment variable, Visual Build will also look for the executable in the App Paths registry key.

 

Note: To run batch files (.bat), command scripts (.cmd), or individual shell commands, use the Batch File action.  If using the Run Program action, the command should be prefixed with the DOSCMD system macro (i.e., %DOSCMD% call "C:\path\to\file.bat" arg1 "arg 2" or %DOSCMD% copy "%PROJDIR%\Test.exe" "\\server\deploy") so that the command is executed under a command shell/interpreter.  Also, if you wish to execute multiple commands (& [run both], && [run second command if first succeeds], or || [run second command if first fails]), redirect output (> or >>), or use piping (|) on the output of an executable, the command should also be prefixed with DOSCMD, since the command interpreter is what implements these capabilities.

 

Start In: The path that will be the starting directory for the process (optional).  Applications that use the working directory to locate files, such as NMAKE, require this parameter to be defined in order to work correctly.  This setting is equivalent to setting the current directory in a Command/DOS Prompt via the CD command.  Do not enclose the value in double-quotes.

 

Advanced: This field supports relative paths for nested steps: If the path is entered as a relative path, Visual Build will prefix the path of a "parent" step (one above it that has less indentation), and will do this recursively until there are no more parent steps or the path is no longer relative.  For example, if the first step (indented one level) has a Start In path of c:\, the second step (indented two levels) a Start In path of MyProject, and the third step (indented three levels) a Start In path of X, Visual Build will use a Start In path of c:\MyProject for step #2 and c:\MyProject\X for step #3 (in this case, the fully expanded path will be displayed in the field's tool tip).

 

Read Output From: Selects where to read the step's output from.  Most processes write their output to standard output.  Some (such as the Microsoft Visual Basic compiler) write their output to a file.  If A file is selected, an Output File to read from must be entered, and Visual Build can delete this file before building the step if desired.  Some processes may not have any output, and None can be chosen in this case, or if you do not want an application's output to be logged.

 

Hide application window: By default, the process window is hidden when building, but you can choose to show it with this field (Visual Build detects when Windows executables are called and always displays them with a window so that the user can respond if the application doesn't close as expected).  This may be necessary for applications that might display a dialog box or message box.  It can be useful when debugging a step that calls an application with a graphical interface.

 

Note: This option will be ignored for GUI applications if the Always show GUI applications option is checked.

 

Success Exit Codes: Visual Build determines the success of the process by examining the exit code of the process.  By default, a zero (0) exit code is considered successful, and any other code is a failure.  Sometimes, an application will return non-zero exit codes to indicate partial success or additional information, and multiple ranges of success exit codes can be specified in the format low1:hi1, low2:hi2, code3.  For instance, 0:5, 10 would cause the values 0 through 5 and 10 to be considered successful exit codes.

 

Note: Some applications do not return an exit code; Visual Build can still invoke them but cannot directly determine success or failure of the step.  In these situations, the system macro LASTSTEP_OUTPUT can be used in the following step or the vbld_StepDone step script event to determine failure (see the GetProjVer.bld sample for more details).