docs.intersystems.com
Home  /  Application Development: Additional Options  /  Using Studio  /  Using Studio Source Control Hooks


Using Studio
Using Studio Source Control Hooks
[Back]  [Next] 
InterSystems: The power behind what matters   
Search:  


To place InterSystems IRIS code under source control, you need to connect Studio to a third-party source control system. This appendix describes how to do this. It discusses the following topics:
Overview
To place an InterSystems IRIS development project under source control, do the following:
InterSystems IRIS Documents
An InterSystems IRIS document is a class definition, a routine, or an include file. InterSystems IRIS records information about each InterSystems IRIS document, such as whether it has changed since the last compilation. Your source control system treats each InterSystems IRIS document as a separate unit. The state of a document is shown by an icon in the document window.
In InterSystems IRIS, you work within one namespace at a time. The same is true for your source control system.
Tools for Managing Documents and Files
InterSystems IRIS provides the following tools for managing InterSystems IRIS documents and external files:
Deciding How to Map Internal and External Names
Each document has two names:
You will set up a bidirectional mapping between the internal names and the external names. In practice, deciding how to do this may be one of the most challenging parts of creating a source control interface. This mapping is customer-specific and should be considered carefully.
You want the source control tool to group similar items. For example, the sample uses the following directory structure:
For example, the external name for the class MyApp.Addresses.HomeAddress is C:\sources\cls\MyApp\Addresses\HomeAddress.xml.
This approach might be problematic if you had large numbers of routines. In such a case, you might prefer to group routines into subdirectories in some manner, perhaps by function.
Creating and Activating a Source Control Class
This section describes the basic requirements for creating and activating a source control class.
Extending Studio
InterSystems IRIS provides classes that you can use to add menu items to Studio. To add a source control menu to Studio, you would use either %Studio.Extension.Base or %Studio.SourceControl.Base.
Note:
Limit on how many menus you can add to Studio: You can add up two menus with 19 menu items each.
The %Studio.Extension.Base class provides the following methods, which all use the internal name of the InterSystems IRIS document:
Note:
Studio class compilation can use multiple processes. Therefore, don't use properties of %Studio.Extension.Base to pass information from MenuItem to OnBeforeCompile. Instead, use a temporary global.
The %Studio.SourceControl.Base class is a subclass of the preceding class. %Studio.SourceControl.Base provides the following additional elements:
To extend Studio, you define a new class that extends one of these classes. As you see in Activating a Source Control Class,” the Management Portal provides a way to indicate which extension class is currently active in a given namespace. If an extension class is active in a given namespace, and if that class defines an XDATA menu block, those menu items are added to Studio.
Creating a Source Control Class
To create a source control class, do the following:
  1. If you started with %Studio.Extension.Base, create an XDATA block named Menu in your subclass. (Copy and paste from %Studio.SourceControl.Base to start this.)
  2. Implement the methods of this class as needed: AddToSourceControl, CheckIn, CheckOut, and so on. These methods would typically do the following, at a minimum:
    The details depend upon the source control system.
  3. Implement the GetStatus method of your source control class. This is required. You might also need to implement the IsInSourceControl method, if the default implementation is not suitable.
Activating a Source Control Class
To activate a source control class for a given namespace, do the following:
  1. Use the Management Portal to specify which extension class, if any, Studio should use for a given namespace. To specify the class to use:
    1. Navigate to the [System] > [Configuration] > [Source Control Settings] page of the Management Portal. (Select System Administration > Configuration > Additional Settings > Source Control.)
    2. On the left, select the namespace to which this setting should apply.
    3. Select the name of the extension class to use (or select NONE) and select OK.
      This list includes all compiled subclasses of %Studio.Extension.Base.
  2. If Studio is currently open, close it and reopen it, or switch to another namespace and then switch back.
Accessing Your Source Control System
The API for your source control system provides methods or functions to perform source control activities such as checking files out. Your source control class will need to make the appropriate calls to this API, and the InterSystems IRIS server will need to be able to locate the shared library or other file that defines the API itself.
Also, it is important to remember that InterSystems IRIS will execute the source control commands on the InterSystems IRIS server. This means that your XML files will be on the InterSystems IRIS server, and your file mapping must work on the operating system used on that server.
Example 1
For the following fragment, we have created wrapper methods for the API for VSS. Then we can include code like the following within the source control methods:
 do ..VSSFile.CheckIn(..VSSFile.LocalSpec,Description)
The details depend on the source control software, its API, and your needs.
Example 2
The following fragment uses a Windows command-line interface to check out a file. In this example, the source control system is Perforce:
/// Check this routine/class out of source control.
Method CheckOut(IntName As %String, Description As %String) As %Status
{
  Set file=..ExternalName(IntName)
  If file="" Quit $$$OK
  //...
 Set cmd="p4 edit """_file_""""


  #; execute the actual command
  Set sc=..RunCmd(cmd)
  If $$$ISERR(sc) Quit sc

  #; If the file still does not exist or
  #; if it is not writable then checkout failed
  If '##class(%File).Exists(file)||(##class(%File).ReadOnly(file)) {
    Quit $$$ERROR($$$GeneralError,
                  "Failure: '"_IntName_"' not writeable in file sys")
  }

  #; make sure we have latest version
  Set sc=..OnBeforeLoad(IntName)
  If $$$ISERR(sc) Quit sc

  //...
  Quit sc
}
In this example, RunCmd is another method, which executes the given command and does some generic error checking. (RunCmd issues the OS command via the $ZF(-1) interface.)
Also, this CheckOut method calls the OnBeforeLoad method, which ensures that the InterSystems IRIS document and the external XML file are synchronized.