Using Environment Variables With Scripts

From Seapine Labs

Surround SCM gives users the option to set up triggers. These triggers can be used to send emails when certain events occur, prevent certain actions from occurring or to run a script. This article focuses on the use of scripts. Specifically, this article focuses on how to get Surround SCM environment variables dynamically when the script is run by the trigger.

Surround SCM environment variables offer a great way to get information at run-time for scripts used with triggers. Instead of creating multiple scripts with hard coded Surround SCM information, only a few scripts need to be created using the environment variables.

Surround SCM environment variables that can be used in email templates and with scripts that are run by triggers. These variables are listed in the Surround SCM User Guide.

The following table includes the available Surround SCM version 5 system variables. This is just meant to be used as a quick reference. It is recommended that you first read the user guide section on environment variables.

Surround SCM Environment Variables
Variable	Definition
SSCM_TRIGGERDESC	Trigger description
SSCM_EVENT	Event that fired the trigger
SSCM_BEFOREAFTER	Indicates if trigger fired before or after the event
SSCM_DATE	Date the trigger fired
SSCM_TIME	Time the trigger fired
SSCM_USER	User that caused the event to occur
SSCM_CLIENTIP	User’s IP address
SSCM_CLIENTMACHINE	User’s computer name
SSCM_MAINLINE	Mainline branch the specified file is in
SSCM_BRANCH	Branch the specified file is in
SSCM_BRANCHTYPE	Type of branch the specified file is in
SSCM_REPOSITORY	Full repository path for the specified file
SSCM_FILE	File name
SSCM_LABEL	File label
SSCM_FILEVERSION	Post-event file version
SSCM_LOCALFILE	Full path of the local file (used with Check In or Add events only)
SSCM_COMMENT	File event comments
SSCM_SOURCEBRANCH	Source branch used for an add/promote/rebase event
SSCM_DEFECTNUMBER	Defect number the file is attached to
SSCM_SHAREREPOSITORY	Source repository the share was created from
SSCM_OLDFILENAME	File’s original name, used with rename event
SSCM_PERMREMOVE	File was permanently removed (yes/no)
SSCM_NUMFILES	Number of files user is being notified about, used with email triggers
SSCM_FILELIST	List of files for the event (used with email triggers)
SSCM_CHANGELISTNAME	Changelist name
SSCM_CHANGELISTID	Changelist ID number
SSCM_FILELINK	File hyperlink in sscm:// format
CF_<field name>	Custom field code*

*To view the field code for a custom field, choose Tools > Administration > Custom Fields and look at the value for the desired field in the Field Code column.

These environment variables are especially useful to get information that is only available when the script runs.

[edit] DOS Example

An administrator wants to keep track of files that are renamed in a specific branch in Surround SCM. The administrator creates a batch file with the following content:

echo File Renamed on %SSCM_DATE% >>C:\testfile.txt

echo Old Name: %SSCM_OLDFILENAME% >>C:\testfile.txt

echo New Name: %SSCM_FILE% >>C:\testfile.txt

The administrator saves the file and names it "base.bat" and then creates the following trigger:

Trigger applies to files in branch [<all branches>] and in repository [Test] [recursively] -- before an event on a [Rename file] -- Run script located at "C:\base.bat"

Note: The path of the script file is on C:\ drive of the computer where the Surround SCM Server is running, not the computer where the Surround SCM client is running.

A user later takes the file named "test.cpp" and renames it to "testing.cpp". The output file ("testfile.txt") has the following content after the trigger runs the batch file:

File Renamed on 4/11/2007

Old Name: test.cpp

New Name: testing.cpp

Note: The path of the output file is also the C:\ drive on the computer the Surround SCM Server is running on, not the computer the Surround SCM client is running on.

[edit] C# Example

You can also get Surround SCM variables using a programming language. C# can get any system variable by using:

System.Environment.GetEnvironmentVariable(variable name);

So you can retrieve the file name that triggered the script like this:

System.Environment.GetEnvironmentVariable("SSCM_FILE");

The following example copies a file before it is checked in:

//First we check to make sure there are environment variables
if ((!(System.Environment.GetEnvironmentVariable("SSCM_LOCALFILE") == null))&&(!(System.Environment.GetEnvironmentVariable("SSCM_FILE") == null)))

{
   surroundLocalFile = System.Environment.GetEnvironmentVariable("SSCM_LOCALFILE");

   surroundFileName = System.Environment.GetEnvironmentVariable("SSCM_FILE");
    
   FileInfo scmFile = new FileInfo(surroundLocalFile);//File that surround is about to check in

   FileInfo copyFile = new FileInfo(@"d:\" +  surroundFileName);//destination and file name of copy

//if the file already exists in the destination location, delete it. 
  
   if (copyFile.Exists)    
   {  
 
      copyFile.Delete();

   }

   scmFile.CopyTo(@"d:\" + surroundFileName);
}

One thing to note is that the "SSCM_LOCALFILE" variable does not return the file in the working directory about to be checked in. It returns the .tmp file that Surround actually uses for the check in. This is why we need to get the "SSCM_FILE", so we can use it as file name for the copy.

[edit] C++ Example

Several examples of how to use Surround SCM environment variables using C++ are available from the Surround SCM add-ons page:

http://www.seapine.com/scmresources.php#trigger

Following is one line of code that illustrates how to get a Surround SCM environment variable using C++:

getenvcheck("SSCM_FILE");

Note: Seapine does not provide support for sample triggers and scripts.