clearexport_ssafe

Converts SourceSafe files to elements

Applicability

Product

Command type

ClearCase®

command

Platform

Windows

Synopsis

clearexport_ssafe [ –r ]
[ [ –s date-time ] [ –p date-time ] | –I { now | date-time } ]

[ –V ] [ –b target-branch [ –v version-id ] ] [ –T translation-file ]

[ –o datafile-pname] [ source-name]

Description

clearexport_ssafe and clearimport allow you to copy SourceSafe files to a VOB. You can copy a single file, multiple files, or an entire project tree.

Note:

Before using clearexport_ssafe, run analyze.exe. Resolve any problems that analyze.exe detects before proceeding with the export operation.

During the export stage, you invoke clearexport_ssafe while connected to any SourceSafe project. clearexport_ssafe creates a datafile (by default, cvt_data), and places in it the descriptions of elements and versions.

In the import stage, you invoke clearimport on the datafile. clearimport reads the descriptions in the datafile and imports the information into the VOB.

clearexport_ssafe converts each SourceSafe label into a ClearCase version label. clearexport_ssafe creates separate elements for each SourceSafe file. You can specify a translation file to control naming of labels, enforcing consistency over multiple invocations of the command. You can use the –V option to preserve SourceSafe version numbers as attributes of the corresponding ClearCase versions.

Note:
  • clearexport_ssafe and clearimport use magic files to determine which element type to use for each element that clearimport creates. For more information about magic files and file typing, see the cc.magic reference page.
  • clearexport_ssafe uses the value of the TMP environment variable as the directory for temporary files.

SourceSafe checked-out files

clearexport_ssafe issues warning messages when it encounters checked-out SourceSafe files, but still processes the files.

SourceSafe executable in PATH

For clearexport_ssafe to work, the SourceSafe command-line executable ss.exe must be in your PATH environment variable. ss.exe must work without prompting you for a user name and password. To prevent prompting, you may need to use a SourceSafe user name that matches your domain login user name, or you may need to set the SSUSER environment variable and set the corresponding password to blank, or no password.

Special characters in file names

During import, clearimport invokes a shell to extract data from the datafile. clearimport can handle some, but not all, characters that are special to shells. The import fails for any file name that includes any of these characters:

‘   '   “   <Tab>   [   ]   ?   *  %

For example:

Succeeds

Fails

foo&bar foo?bar
$MY_LIB yellow‘sunset

Before running clearexport_ssafe, rename any file whose name contains these characters.

Translation file

Renaming SourceSafe labels can introduce inconsistencies over multiple runs of clearexport_ssafe. The same label may be renamed during processing of some SourceSafe files, but remain unchanged during processing of other files. You can enforce consistency by using the same translation file in multiple invocations of clearexport_ssafe. If you name such a file (using the –T option), clearexport_ssafe uses it as follows:

  • To look up each SourceSafe label to determine how to translate it to a ClearCase label type. If a match is found, clearexport_ssafe translates the label the same way.
  • To record each translation of a new SourceSafe label for use in future lookups.

The first time you use clearexport_ssafe, use –T to create a new translation file. On subsequent invocations of clearexport_ssafe, use –T again and specify the same translation file, for consistent name translation.

Syntax of translation file

The translation file consists of one or more lines in the following form:

label old-name new-name

For example, to rename the label BL1.7 to IMPORT_BASE and the label BL2 to IMPORT_BASE2, the translation file would be:

label BL1.7 IMPORT_BASE
label BL2 IMPORT_BASE2

No blank lines are allowed in the file.

Shares

clearexport_ssafe does not preserve shares as hard links during conversion. Instead, shares become separate elements.

Labels

clearexport_ssafe converts a SourceSafe label into a ClearCase label with the same name.

Note:

Labels on SourceSafe directories are not exported.

Branches

clearexport_ssafe does not convert SourceSafe branches to ClearCase branches. Instead, clearexport_ssafe creates separate elements.

Pins

clearexport_ssafe translates SourceSafe pins to ClearCase version labels named PINNED.

No deltas

SourceSafe lets you assign the NO DELTAS attribute to elements, which directs SourceSafe to keep only the current version of the element. SourceSafe keeps a history of all versions, but the contents of only the current version. clearexport_ssafe creates an empty version for each of the previous versions of the element and a version with contents for the current version. Because ClearCase does not include a feature comparable to NODELTAS, when you create new versions of the element, the previous versions and their contents are stored. You can, however, use the rmver –data command to remove a version's contents.

Handling of objects that cannot be exported

When clearexport_ssafe encounters a file or directory that cannot be exported (for example, a file with format problems, or a broken symbolic link), it prints an error and continues. After creating the data file, the command prints a summary of the files and directories that could not be exported.

Guidelines for handling data

After you export data, do not move the data to another location before importing it.

It is not a good practice to move data between different operating systems or between operating systems with different architectures.

Restrictions

None.

Options and arguments

Handling of directory arguments

clearexport_ssafe processes the files in your SourceSafe current project. You cannot specify a pathname with the source-name argument.

–r
clearexport_ssafe descends recursively into all subprojects of your current project.
Note:

Do not specify the RECURSIVE variable in your SourceSafe initialization file (.ini).

Selective conversion of files

Default
clearexport_ssafe processes all files it encounters.
–s date-time
clearexport_ssafe processes only files that have been modified since the specified time. Use this option for regular, incremental updating of an element from a SourceSafe file that is still under development. Be sure to specify a date-time that covers the entire period since the preceding update. In other situations, it is better to use –I instead of –s.

clearexport_ssafe determines whether to process a SourceSafe file by using the last-modified date/time of the file. If this date/time is before the date-time you specified with –s, clearexport_ssafe does not process any of the versions of the file. If the date/time is after the date-time you specified, clearexport_ssafe processes the following versions:

  • All versions created since the specified date-time
  • All versions that have labels
Note:

For an incremental update, if you remove a label from a SourceSafe file, clearimport does not remove the label from the ClearCase element.

–p date-time
Like -s, but processes only versions modified with new metadata (labels, branches, attributes, and so on) or created before the specified time.
–I { now | date-time }
Processes important versions only, but includes all versions created since the specified time. A version is important if either of these conditions is true:
  • It is the most recent version.
  • It has a label.

To export only important versions, use –I now. The time is specified in one of the following formats:

date.time | date | time | now where:

date

:=

day-of-week | long-date

time

:=

h[h]:m[m][:s[s]] [UTC [ [ + | - ]h[h][:m[m] ] ] ]

day-of-week

:=

today |yesterday |Sunday | ... |Saturday |Sun | ... |Sat

long-date

:=

d[d]–month[ – [yy]yy]

month

:=

January |... |December |Jan |... |Dec

Specify the time in 24-hour format, relative to the local time zone. If you omit the time, the default value is 00:00:00. If you omit the date, the default value is today. If you omit the century, year, or a specific date, the most recent one is used. Specify UTC if you want to resolve the time to the same moment in time regardless of time zone. Use the plus (+) or minus (-) operator to specify a positive or negative offset to the UTC time. If you specify UTC without hour or minute offsets, the default is Greenwich Mean Time (GMT). (Dates before January 1, 1970 Universal Coordinated Time (UTC) are invalid.)

Preserving SourceSafe information as attributes

Default
clearexport_ssafe does not attach attributes to versions exported from SourceSafe versions.
–V
Attaches an attribute of type SSAFE_VERSION to each newly created version. The string value of the attribute is the SourceSafe version number of the processed version. (clearimport creates attribute type SSAFE_VERSION, if necessary.)

If you use the –s option with this option, clearimport attaches SSAFE_VERSION attributes only to versions created after the date-time you specified.

Each attribute requires about 1 KB of storage in the VOB database.

Creating new versions on a branch

Default
clearimport creates new versions of a file or directory element on the element's main branch.
–b target-branch [ –v version-id ]
Converts each file to a version on branch target-branch of the new or existing element. Whenever clearimport creates a new element in the target VOB, it also revises the parent directory element on branch target-branch. To prevent directory branching, you can check out all directories on any branch before importing. clearimport then uses the checked-out directories.

If branch type target-branch does not already exist in the target VOB, clearimport creates it. If an existing element already has a branch of this type, the new version extends this branch; otherwise, clearimport sprouts target-branch from version \main\LATEST (\main\0 for new elements). To specify another version from which the branch should sprout, use the –v option.

Translation of labels

Default
clearexport_ssafe may rename a label type to avoid naming conflicts.
–T translation-file
Uses the specified translation file to control and record the conversion of SourceSafe label names to ClearCase version labels.

Storage location of datafile

Default
clearexport_ssafe creates the datafile cvt_data in the current working directory.
–o datafile-pname
Stores the datafile at the specified location. An error occurs if the datafile already exists.
Note:

Do not specify the OUTPUT variable in your SourceSafe initialization file (.ini).

Specifying files to be exported

Default
The SourceSafe current project (equivalent to specifying a dot (.)) as the source-name argument). clearexport_ssafe processes each SourceSafe file in the current project and creates a directory element for each subproject of the current project.
source-name
The name of the SourceSafe current project, or a file or subproject in that project:
  • For each SourceSafe file, clearexport_ssafe places a description in the datafile.
  • For the current project, clearexport_ssafe places a description in the datafile for all the elements it catalogs. clearimport creates a directory element for the specified project itself, and for its subprojects.

Each source-name must be a SourceSafe file or project in the SourceSafe current project, or a wildcard as described in wildcards_ccase. clearexport_ssafe processes files and subprojects only from your SourceSafe current project. You cannot use source-name to specify a pathname that is not in your SourceSafe current project.

Examples

  • Create entries in the datafile for the elements in the current project, processing important versions created before 1999 and all versions created since the beginning of 1999.

    c:\> clearexport_ssafe –r –I 1-Jan-1999

  • Create entries in the datafile for the elements in the current project, but not in any subprojects; store the datafile in a file named newcvt.

    c:\> clearexport_ssafe –o newcvt .

  • In SourceSafe, display your SourceSafe current project.

    c:\> ss cp

  • In SourceSafe, list the contents of your SourceSafe current project.

    c:\> ss dir