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 Pro 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 (&), 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 Pro 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 Pro 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 Pro 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.

 

Wait for Completion: When checked, Visual Build Pro waits for the step to finish before continuing and it displays any step output in the Output pane.  Uncheck this item to immediately start the next step without waiting for the current step to complete.  No output from that step will be shown in Visual Build Pro and if the process is successfully started, it will be treated as a successful.

 

Notes:

 

Hide application window: By default, the process window is hidden when building, but you can choose to show it with this field (Visual Build Pro 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.

 

Success Exit Codes: Visual Build Pro 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 Pro 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 Analyze.bld and GetProjVer.bld samples for more details).