May 2, 2007

Using Environment Variables With Scripts

Surround SCM
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
VariableDefinition
SSCM_TRIGGERDESCTrigger description
SSCM_EVENTEvent that fired the trigger
SSCM_BEFOREAFTERIndicates if trigger fired before or after the event
SSCM_DATEDate the trigger fired
SSCM_TIMETime the trigger fired
SSCM_USERUser that caused the event to occur
SSCM_CLIENTIPUser’s IP address
SSCM_CLIENTMACHINEUser’s computer name
SSCM_MAINLINEMainline branch the specified file is in
SSCM_BRANCHBranch the specified file is in
SSCM_BRANCHTYPEType of branch the specified file is in
SSCM_REPOSITORYFull repository path for the specified file
SSCM_FILEFile name
SSCM_LABELFile label
SSCM_FILEVERSIONPost-event file version
SSCM_LOCALFILEFull path of the local file (used with Check In or Add events only)
SSCM_COMMENTFile event comments
SSCM_SOURCEBRANCHSource branch used for an add/promote/rebase event
SSCM_DEFECTNUMBERDefect number the file is attached to
SSCM_SHAREREPOSITORYSource repository the share was created from
SSCM_OLDFILENAMEFile’s original name, used with rename event
SSCM_PERMREMOVEFile was permanently removed (yes/no)
SSCM_NUMFILESNumber of files user is being notified about, used with email triggers
SSCM_FILELISTList of files for the event (used with email triggers)
SSCM_CHANGELISTNAMEChangelist name
SSCM_CHANGELISTIDChangelist ID number
SSCM_FILELINKFile hyperlink in sscm:// format
CF_<field name>Custom field code*
Table 1 - Surround SCM Environment Variables
*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.

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.

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.

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.