Integrating InterSystems IRIS with Source Control Systems

InterSystems IRIS Documents

On this page, the term document refers to any discrete item that you place within a source control system; this includes class definitions, routines, and data transformations. InterSystems IRIS records information such as whether a document has changed since the last compilation. Your source control system treats each document as a separate unit.

Each document has two names:

• An internal name.

• An external name, which is the fully qualified path to the file in the file system.

Deciding How to Map Internal and External Names

Creating a bidirectional mapping between internal and external names may be one of the most challenging parts of implementing a source control system. Your code will need to define this mapping, which means that it must do the following:

• Given the name of an internal item, determine the corresponding filename.

• Given a changed file, determine the corresponding internal item and update it by importing the changed file.

For example, you could use a directory structure like this:

• Class files are in the cls subdirectory, which contains subdirectories corresponding to the package hierarchy of the classes.

• .INT routines are in the int subdirectory.

• .MAC routines are in the mac subdirectory.

So that multiple developers in different environments can use your custom source control class, your code must also provide a way to configure the basic location of the files (rather than simply hardcoding the mapping completely).

Tools for Managing Documents and Files

InterSystems IRIS provides the following tools for managing documents and external files:

• To export InterSystems IRIS documents, use one of the following, depending on the file format you want to use:

  • For UDL files, use $system.OBJ.ExportUDL().

  • For XML files, use $system.OBJ.Export().

  UDL files more closely resemble the code as seen in an IDE.

• To import files (of either format), use $system.OBJ.Load().

• To obtain the timestamp and compile time for an InterSystems IRIS document, use the %RoutineMgr.TS class method.

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 callout interface.)

Also, this CheckOut() method calls the OnBeforeLoad() method, which ensures that the InterSystems IRIS document and the external XML file are synchronized.