Adding triggers to run executables

You can run scripts and compiled programs from pre- and post-event triggers. Surround SCM accepts any command line call.

The executable must be located on the Surround SCM Server computer. The administrator needs to make sure the executable has appropriate directory access permissions and the same run privileges as the server.

If the executable is not found when the trigger runs, an error is returned to Surround SCM and the event does not complete. If multiple triggers are associated with a file and one trigger fails, the remaining triggers do not run.

Use environment variables in scripts and programs to retrieve data about the file that caused a trigger to run and pass data back to the executable. See Environment variables.

Pre-event triggers

Pre-event triggers can run server scripts that perform additional checks on files before an event completes. For example, you can create scripts to verify that text is included in specific files before they are checked in.

Pre-event triggers that run scripts can cause performance issues because the Surround SCM Server waits for the script to complete before moving to the next file. Post-event triggers should always be used to run scripts unless the trigger is used for validation. Even a one second pre-event script will significantly slow down the server because it takes an additional second per file that the trigger runs on.

Scripts that run from pre-event triggers must return a value that tells the server if an event should be allowed to complete. A return value of zero indicates the event can continue. A non-zero return value indicates the event should be not be performed. If a non-zero value is returned, any messages output by the executable (output to stdout) are sent back to Surround SCM with the error. The error is truncated to 1024 characters.

Following are some examples of how to return a value from an executable:

C program—Specify the value in the return( ) statement in the main( ) routine. You can also use a parameter in the exit statement.
Windows/DOS batch file—Set the ERRORLEVEL value. In Windows 2000/XP batch scripts the command “exit /B #” can be used.
Windows application—Use the CWinApp::ExitInstance( ) function.

Post-event triggers

Post-event triggers can run server scripts that perform additional actions after the event is successfully completed on the server. For example, you can create scripts for custom logging of Surround SCM file activity, to synchronize two separate servers, or start your build process on a server computer.

1. Choose Tools > Administration > Triggers.

The Triggers dialog box opens.

2. Click Add.

The Add Trigger dialog box opens.

3. Enter a Trigger Name, select the Trigger When events, and select the Preconditions. See Adding triggers.

4. Click the Actions tab and click Add to add an action.

5. Select Run [executable] from the Action list.

6. Enter the full path to the Executable location and click OK.

7. Select Disable trigger after it runs once if you only want the trigger to run once.

8. Click OK to add the trigger.