Sun WorkShop TeamWare: User's Guide: 17 - Introduction to FreezePointing

# Introduction to FreezePointing | # 17 |

This chapter discusses how FreezePointing can help you preserve snapshots of your work, and the process of recreating those key points.

How FreezePointing Works | page 198
Starting FreezePointing | page 200
Creating a Freezepoint File | page 201
Recreating (Extracting) a Source Hierarchy | page 202

## Changing Names

The current release of TeamWare uses new command names, so Table 17-1 summarizes the correspondences for you. Note that the old commands still work, however this manual uses the new commands and GUI names.

#### Table 17-1 Matching New and Old TeamWare Commands

Old Command | New Command | Old Tool Name | New GUI Name
codemgrtool | twconfig, teamware | CodeManager | Configuring
vertool | twversion | VersionTool | Versioning
filemerge | twmerge | FileMerge | Merging
maketool | twbuild | MakeTool | Building
freezepttool | twfreeze | FreezePoint | Freezepointing

During the software development process it is often useful to create "freezepoints" of your work at key points. Those freezepoints serve as snapshots of a project that enable you to later recreate the state of the project at key development points.

One way to preserve the state of the project is to make a copy of the project hierarchy using the `tar` or `cpio` utilities. This method is very effective, but it requires a large amount of storage resources and time.

With FreezePointing, you preserve freezepoints quickly and simply, using a small amount of storage resource.

You can use FreezePointing through two functionally equivalent user interfaces. You can access the user interfaces with the following commands

- `twfreeze`--for the GUI
- `freezept`--for the CLI

> Note - FreezePointing is a companion tool to the TeamWare product. Therefore, FreezePointing assumes that you are creating freezepoints of Configuring workspace hierarchies. You can also use FreezePointing to preserve nonworkspace directories that contain SCCS files. If you specify a directory that is not a workspace, a cautionary warning is issued.

This chapter refers primarily to the GUI. For information about the CLI, see the `freezept`(1) `man` page. The GUI is documented online. You can access the online help from any TeamWare GUI, by opening the pull-down menu from the Help button, and clicking on Help Contents.

## How FreezePointing Works

FreezePointing enables you to create freezepoint files from Configuring workspaces.

> Note - Nonworkspace directory hierarchies that contain SCCS history files can also be preserved using FreezePointing. FreezePointing issues a warning if the directory is not a workspace.

At a later time you can use the freezepoint files to recreate the directory hierarchies contained in the workspaces.

> Note - The recreated hierarchy will not contain the original SCCS history files; only the g-files represented by the default deltas from the original hierarchy are recreated. The default delta is the delta that would be

The freezepoint file that FreezePointing creates is a text file that lists the default deltas in SCCS history files in the hierarchy. When you later recreate the hierarchy, FreezePointing uses those entries as pointers back to the original history files and to the delta that was the default at the time the freezepoint file was created.

When you create a freezepoint file, you specify directories and files to
FreezePointing in the Directories and Files pane. FreezePointing recursively descends the directory hierarchies and identifies the most recently checked-in deltas in each SCCS history file. FreezePointing then creates a freezepoint file that consists of a list of those files and unique numerical identifiers for each delta.

You can later use FreezePointing to recreate the source hierarchy. You specify the name of the freezepoint file, the path name of the directory hierarchy from which the deltas are to be extracted (if different from the hierarchy from which it was derived), and the directory where you want the source hierarchy recreated.

##### Terminology

#### Freezepoint File

A freezepoint file is a list of the default deltas from the SCCS history files contained in the workspace hierarchy being preserved. The freezepoint file also contains the following information:

- The login name of the user who created the freezepoint
- The date and time that the file was created
- The path name of the workspace from which the list of deltas was created
- An optional user-supplied comment

See "Details about the Freezepoint File" on page 204 for more information.

#### Extract

The extract operation consists of creating a new directory hierarchy based on the information contained in the freezepoint file. The new hierarchy is comprised of g-files defined by the default deltas in the original SCCS history files; the history files themselves are not recreated. Deltas are extracted from SCCS history files located in the original source workspace.

#### Source Workspace

The source workspace is the directory hierarchy that contains the SCCS history files from which the freezepoint file is created. Usually, the source workspace is also the directory hierarchy from which g-files are later extracted to recreate the hierarchy.

> Note - You can specify an alternate source directory at the time you perform the extract operation.

#### Destination Directory

The destination directory is the top-level directory into which the files listed in the freezepoint file are extracted. You specify the path name of this directory in the Extract pane of the FreezePointing base window.

## Starting FreezePointing

| To start the FreezePointing GUI, type the following:

  After a moment, the FreezePointing GUI appears.

      demo% twfreeze &
      demo%

## Creating a Freezepoint File

  1. To create a Freezepoint file, use the Category menu to choose the Create pane.

    The pane below the Control area is used for both creating and extracting freezepoints. You switch between the Create pane and the Extract pane by choosing the appropriate item from the Category menu. The Create pane is the default and is displayed when you start FreezePointing.

  2. Enter the name of a freezepoint file.

  - When FreezePointing initially appears, the FreezePointing File text field is automatically set to contain the file `freezepoint.out` appended to the path name of the directory from which freezepoint.

- Delete `freezepoint.out` and type the path name of your freezepoint file in the FreezePointing File text field.

  Note that path names that are not absolute are assumed to be relative to the directory in which FreezePointing is started.

  3. Enter the name of the source workspace.

    When you start FreezePointing, the Workspace text field is automatically set to be the workspace you have specified through the CODEMGR_WS environment variable. If the variable is not set, and the directory from which FreezePointing is started is hierarchically within a workspace, the Workspace field is initialized with the path name of that workspace.

  4. In the Directories and Files text window, compose a list of directories and/or files that you wish to preserve.

    The list of directories and files that you create in the Directories and Files text window are those that will be preserved in the freezepoint file.

  You add directory and file entries to the Directories and Files window using the two items in the File menu:

- Load Entire Directory

- Add File to List

  The Load Entire Directory inserts the "./" characters into the Directories and Files window; this indicates that the entire workspace hierarchy be recursively preserved.

  The Add Files to List item activates a point-and-click chooser window with which you can search for and select files and directories to add to the list.

  - Click SELECT on a directory icon to select it, and then select the chooser's Add to List button to add the choice to the list.

  - Double click SELECT on a directory icon to descend in the file system hierarchy, double-click SELECT on a previous icon to ascend. (Alternatively, you can select a directory icon and click on the Load Directory button to hierarchically descend.)

> Note - You can also type the path name of a directory or file into the chooser Directory field and then click SELECT on the Add to List button.

  5. Enter an optional comment in the Comments text pane.

    The comment is stored in the freezepoint file for future reference.

  6. Select the Create button to create the freezepoint file.

    A counter on the bottom right corner of the base window footer displays the progress of the freezepoint operation.

## Viewing or Modifying a Freezepoint File

Freezepoint files are text files. You can view and edit their contents using standard text editors.

## Recreating (Extracting) a Source Hierarchy

To extract a new source hierarchy described by a freezepoint file, follow these basic steps:

  1. Use the Category menu to choose the Extract pane

    The pane below the Control area is used for both creating and extracting freezepoints. You switch between the Create pane and the Extract pane by choosing the appropriate item from the Category menu. Choose the Extract item to display the Extract pane.

  2. Type the name of an existing freezepoint file.

    Type the path name of your freezepoint file in the FreezePointing File text field.

  Note that path names that are not absolute are assumed to be relative to the directory in which FreezePointing is started.

  3. Use the Extract From menu to choose how you will specify the source workspace.

    By default, FreezePointing extracts files from the source workspace path name stored in the freezepoint file when it was created. (You can edit the freezepoint file and change the path name of the source workspace.) By default, FreezePointing uses this path name as the source workspace from which to extract files. If you choose the Show Default menu item from the Extract From menu, FreezePointing displays the path name of the source workspace in the Workspace text field.

> Note - Show Default displays the default source workspace in the Workspace text field

  If you wish to specify a source workspace hierarchy other than the one contained in the freezepoint file, choose the You Specify item from the Extract From menu and enter the path name of the alternate source workspace in the Workspace text field.

  4. Specify the Destination Directory.

    Enter in the Destination Directory text field the path name of the directory in which you want the new (extracted) hierarchy to be located.

  Note that path names that are not absolute are assumed to be relative to the directory in which FreezePointing is started. The destination directory that you specify must be new or empty.

  5. Select the Extract button to begin the extraction.

    Selecting the Extract button causes a series of `sccs` `get` operations to be performed on the source files listed in the freezepoint file. The version of each file extracted is the version specified by the SMID in the freezepoint file. The extracted g-files are written to destination directory.

  A counter on the bottom right corner of the base window footer displays the progress of the extract operation.

### Notes about Using FreezePointing

- Use the Edit menu on the Create pane to delete selections from the Directories and Files text window. Select and deselect files using the SELECT mouse button and then use the Delete item from the Edit menu to delete selected directories/files. Use the Select All, Deselect All, Delete All items to edit large numbers of directories/files.

- Helpful status messages are displayed in the main window footer.

- If during an extraction, FreezePointing cannot locate a file that has been renamed or deleted, the extraction is aborted and the offending entry is named. You must edit the freezepoint file to remove the entry. Refer to the `freezepointfile`(5) `man` page for information that enables you to determine the new name of a renamed file.

- You can use the Tools menu to launch other TeamWare tools directly from FreezePointing.

## Details about the Freezepoint File

A freezepoint file contains:

- A list of source files

- A group of hex digits that identifies the most recent SCCS deltas found in each file's corresponding SCCS history file

- A group of hex digits that identifies the root delta in each file's corresponding SCCS history file

      filemerge.1 (previously 1.5) 92/03/19 14:09:08 jon a6f4fe81 89b4632b 418e7950 5510740e cf9ab4e1 95627c33 2287acc3 b9e0877e
      putback.1 (previously 1.40)92/06/02 16:36:16 george 5b791c60 2b827cfd f0cc9a73 46ac975 24d9b3ec f87d1975 9ea59e0d 72ce2a4d
      resolve.1 (previously 1.19) 92/06/10 16:38:07 paul f21fa6e6 668bf818 e4964f36 240d825c f1d3f57 8cc4c31c 9f53029f 8aaf3db1

##### Figure 17-1 Three Entries From a Freezepoint File

The deltas are not identified as you might imagine, by their standard SCCS delta ID (SID). Instead, a new means of identification called an SCCS Mergeable ID (SMID) is used. Use of the SMID enables FreezePointing to work properly with files in which SIDS have been renumbered as part of a Configuring Bringover Update transaction. For more information see Section , "Why are SMIDs Necessary?".

### What is a SMID?

The use of SMIDs ensures that every delta is uniquely identifiable, even if its SID is changed. A SMID is a number generated using the Xerox Secure Hash Function. When you use FreezePointing to create a freezepoint file, it calculates the SMID for both the current delta and the root delta in the SCCS history file. Using both of these values, FreezePointing can identify a delta in a file even if its SID has been changed.

### Why are SMIDs Necessary?

> Note - This section briefly discusses how Configuring merges SCCS history files. For more information, see Chapter 11, "How the Configuring Program Merges SCCS Files.

When Configuring encounters a file conflict during a Bringover Update transaction (file is changed in both the parent and child workspaces), it merges the new deltas from the parent workspace into the SCCS history file in the child. When this merge occurs, the deltas that were created in the child are moved to an SCCS branch off of the delta that both deltas have in common (common ancestor).

When Configuring relocates the child deltas to a branch, it changes their SID. If SIDS were used in freezepoint files to identify deltas, this relocation would invalidate the information contained in the freezepoint file. For that reason, SIDs cannot be used to identify deltas after conflicting SCCS histories have been merged.

## SMID/SID Translation

In release 2.0 of TeamWare, SMID/SID translation is available only through the FreezePointing CLI.

The `freezept` command `sid` and `smid` subcommands enable you to translate specified SIDs into SMIDs, and to translate specified SMIDs into SIDs. The ability to make these translations is useful if you wish to write your own scripts or programs to track deltas.

### Translating SIDs to SMIDs

Use the `freezept` `smid` command to translate SIDs to SMIDs. The syntax is:

`freezept` `smid` [`-w` workspace] [`-r` SID] [`-a`] file

- Use the `-r` option to specify the SID (in file file) for which you wish to calculate a SMID.

- Use the `-a` option to calculate a SMID for all of the SIDS in file.

- For convenience you can use the `-s` option to specify a directory from which file is relative.

#### Examples

    example% freezept smid -r 1.38 module.c
    SID 1.38 = SMID "f5b67794 705f0768 a89b1f4 588de104"

    example% freezept smid -a bringover.1
    SID 1.1 = SMID "b05b0a2f 1db5246e 1a466014 707e38f5"
    SID 1.2 = SMID "d6a5c61f 5634f0ef 9847a080 d0d7b212"
    SID 1.2 = SMID "e31acdd5 6c1232e2 9e81c287 1edb2f41"
    SID 1.3 = SMID "c34c91b4 a818622a 2457356a 489b2728"
    SID 1.4 = SMID "98c0fd8d 889563fb cf722c2b 6afc9636"
    SID 1.5 = SMID "b1e24be3 752fec3e df2d2717 a9b3f1fa"
    SID 1.6 = SMID "2b93d39 1ea2f6ba 9814320c bc609acb"
    SID 1.7 = SMID "1db7d640 42b0f009 35c60d7b b230bd85"
    SID 1.8 = SMID "906dfe9a ca7e2d6c a64da5be 4baef254"

### Translating SMIDS to SIDS

Use the `freezept` `sid` command to translate SMIDs to SIDs. The syntax is:

`freezept` `sid` [`-w` workspace] [`-m` "SMID"] [`-a`] file

- Use the `-m` option to specify the SMID (in file file) for which you wish to calculate a SID.

- Use the `-a` option to calculate a SID for all of the deltas in file.

- For convenience you can use the `-s` option to specify a directory from which file is relative.

> Note - Because the SMID contains white space, you must enclose it within quotation marks.

#### Examples

    example% freezept sid -m "64fdd0df de9d7dd de75812 23da96aa"
    module.c
    SMID "64fdd0df de9d7dd de75812 23da96aa" = SID 1.36

    example% freezept sid -a bringover.1
    SMID "b05b0a2f 1db5246e 1a466014 707e38f5" = SID 1.1
    SMID "d6a5c61f 5634f0ef 9847a080 d0d7b212" = SID 1.2
    SMID "e31acdd5 6c1232e2 9e81c287 1edb2f41" = SID 1.2
    SMID "c34c91b4 a818622a 2457356a 489b2728" = SID 1.3
    SMID "98c0fd8d 889563fb cf722c2b 6afc9636" = SID 1.4
    SMID "b1e24be3 752fec3e df2d2717 a9b3f1fa" = SID 1.5
    SMID "2b93d39 1ea2f6ba 9814320c bc609acb" = SID 1.6
    SMID "1db7d640 42b0f009 35c60d7b b230bd85" = SID 1.7
    SMID "906dfe9a ca7e2d6c a64da5be 4baef254" = SID 1.8
    SMID "77481e8a 61542339 cc28f532 e5fc6389" = SID 1.9
    SMID "cb97c9a6 d0342cf6 19b7b743 2436ca1c" = SID 1.10
    SMID "46de4131 b95b9973 93958a07 b960074c" = SID 1.11