# SourceOffSite Tasks User Manual

by

- Jesse Stockall

Version 1.1 2002/01/23

## Contents

- Introduction
- The Tasks

## Introduction

These tasks provide an interface to the Microsoft Visual SourceSafe SCM via SourceGear's SourceOffSite product. SourceOffSite is an add-on to Microsoft's VSS, that allows remote development teams and tele-commuters that need fast and secure read/write access to a centralized SourceSafe database via any TCP/IP connection. SOS provides Linux, Solaris & Windows clients. The `org.apache.tools.ant.taskdefs.optional.sos` package consists of a simple framework to support SOS functionality as well as some Apache Ant tasks encapsulating frequently used SOS commands. Although it is possible to use these commands on the desktop, they were primarily intended to be used by automated build systems. These tasks have been tested with SourceOffSite version 3.5.1 connecting to VisualSourceSafe 6.0. The tasks have been tested with Linux, Solaris & Windows 2000.

## The Tasks

sosget | Retrieves a read-only copy of the specified project or file.
soslabel | Assigns a label to the specified project.
soscheckin | Updates VSS with changes made to a checked out file or project, and unlocks the VSS master copy.
soscheckout | Retrieves a read-write copy of the specified project or file, locking the VSS master copy

## Task Descriptions

## SOSGet

### Description

Task to perform Get commands with SOS

### Parameters

Attribute | Values | Required
--- | --- | ---
soscmd | Directory which contains `soscmd(.exe)` | No; by default, the executable must be in the path
vssserverpath | path to the `srcsafe.ini`—eg. `\\server\vss\srcsafe.ini` | Yes
sosserverpath | address & port of the SOS server—eg. `192.168.0.1:8888` | Yes
projectpath | SourceSafe project path—eg. `$/SourceRoot/Project1` | Yes
file | Filename to act upon | No; by default, act upon the project
username | SourceSafe username | Yes
password | SourceSafe password | No
localpath | Override the working directory and get to the specified path | No
soshome | The path to the SourceOffSite home directory | No
nocompress | true|false—disable compression | No
recursive | true|false—Only works with the GetProject command | No
version | a version number to get—Only works with the GetFile command | No
label | a label version to get—Only works with the GetProject command | No
nocache | true|false—Only needed if `SOSHOME` is set as an environment variable | No
verbose | true|false—Status messages are displayed | No

### Example

Connect to a SourceOffsite server on `192.168.10.6:8888` with build, build as the username & password. The SourceSafe database resides on the same box as the SOS server & the VSS database is at `d:\vss\srcsafe.ini`. Do a recursive GetProject on `$/SourceRoot/project1`, using `tmp` as the working directory.

    <sosget verbose="true"
            recursive="true"
            username="build"
            password="build"
            localpath="tmp"
            projectpath="$/SourceRoot/project1"
            sosserverpath="192.168.10.6:8888"
            vssserverpath="d:\vss\srcsafe.ini"/>

## SOSLabel

### Description

Task to perform Label commands with SOS

### Parameters

Attribute | Values | Required
--- | --- | ---
soscmd | Directory which contains `soscmd(.exe)` | No; by default, the executable must be in the path
vssserverpath | path to the `srcsafe.ini`—eg. `\\server\vss\srcsafe.ini` | Yes
sosserverpath | address and port of the SOS server—eg. `192.168.0.1:8888` | Yes
projectpath | SourceSafe project path—eg. `$/SourceRoot/Project1` | Yes
username | SourceSafe username | Yes
password | SourceSafe password | No
label | The label to apply to a project | Yes
comment | A comment to be applied to all files being labeled | No
verbose | true|false—Status messages are displayed | No

### Example

Connect to a SourceOffsite server on `192.168.10.6:8888` with build, build as the username & password. The SourceSafe database resides on the same box as the SOS server & the VSS database is at `d:\vss\srcsafe.ini`. Label the `$/SourceRoot/project1` project with test label.

    <soslabel username="build"
              password="build"
              label="test label"
              projectpath="$/SourceRoot/project1"
              sosserverpath="192.168.10.6:8888"
              vssserverpath="d:\vss\srcsafe.ini"/>

## SOSCheckIn

### Description

Task to perform CheckIn commands with SOS

### Parameters

Attribute | Values | Required
--- | --- | ---
soscmd | Directory which contains `soscmd(.exe)` | No; by default, the executable must be in the path
vssserverpath | path to the `srcsafe.ini`—eg. `\\server\vss\srcsafe.ini` | Yes
sosserverpath | address and port of the SOS server—eg. `192.168.0.1:8888` | Yes
projectpath | SourceSafe project path—eg. `$/SourceRoot/Project1` | Yes
file | Filename to act upon | No; by default, act upon the project
username | SourceSafe username | Yes
password | SourceSafe password | No
localpath | Override the working directory and get to the specified path | No
soshome | The path to the SourceOffSite home directory | No
nocompress | true|false—disable compression | No
recursive | true|false—Only works with the CheckOutProject command | No
nocache | true|false—Only needed if `SOSHOME` is set as an environment variable | No
verbose | true|false—Status messages are displayed | No
comment | A comment to be applied to all files being checked in | No

### Example

Connect to a SourceOffsite server on `server1:8888` with build, build as the username & password. The SourceSafe database resides on a different box (`server2`) & the VSS database is on a share called `vss`. Check-in only the `foobar.txt` file adding a comment of comment abc. Extra status messages will be displayed on screen.

    <soscheckin username="build"
                password="build"
                file="foobar.txt"
                verbose="true"
                comment="comment abc"
                projectpath="$/SourceRoot/project1"
                sosserverpath="server1:8888"
                vssserverpath="\\server2\vss\srcsafe.ini"/>

## SOSCheckOut

### Description

Task to perform CheckOut commands with SOS

### Parameters

Attribute | Values | Required
--- | --- | ---
soscmd | Directory which contains `soscmd(.exe)` | No; by default, the executable must be in the path
vssserverpath | path to the `srcsafe.ini`—eg. `\\server\vss\srcsafe.ini` | Yes
sosserverpath | address and port of the SOS server—eg. `192.168.0.1:8888` | Yes
projectpath | SourceSafe project path—eg. `$/SourceRoot/Project1` | Yes
file | Filename to act upon | No; by default, act upon the project
username | SourceSafe username | Yes
password | SourceSafe password | No
localpath | Override the working directory and get to the specified path | No
soshome | The path to the SourceOffSite home directory | No
nocompress | true|false—disable compression | No
recursive | true|false—Only works with the CheckOutProject command | No
nocache | true|false—Only needed if `SOSHOME` is set as an environment variable | No
verbose | true|false—Status messages are displayed | No

### Example

Connect to a SourceOffsite server on `server1:8888` with build, build as the username & password. The SourceSafe database resides on a different box (`server2`) & the VSS database is on a share called `vss`. Check-out project1, only the `project1` directory will be locked as the recursive option was not set. Extra status messages will be displayed on screen. The `soscmd(.exe)` file to be used resides in `/usr/local/bin`.

    <soscheckout soscmd="/usr/local/bin"
                 verbose="true"
                 username="build"
                 password="build"
                 projectpath="$/SourceRoot/project1"
                 sosserverpath="192.168.10.6:8888"
                 vssserverpath="\\server2\vss\srcsafe.ini"/>