test

Sun WorkShop TeamWare 2.1 User's Guide

Chapter 7 TeamWare Configuring Workspace

As discussed in Chapter 3, Introduction to TeamWare Configuring," the workspace forms the basis of the Configuring system. The workspace provides isolation in which you (a developer) work in parallel with other developers programming in other workspaces. For an introduction to the Configuring workspace, refer to "Workspace".

This chapter discusses specific aspects of workspaces and the Configuring commands you use to configure, create, manipulate, and administer them, and contains the following sections:

The Workspace Metadata Directory

A Configuring workspace is a directory hierarchy that contains a directory named Codemgr_wsdata in its root directory. the Configuring program stores data (metadata) about that workspace in Codemgr_wsdata. Configuring commands use the presence or absence of this directory to determine whether a directory is a workspace.

TeamWare Configuring provides the tools necessary to maintain the information kept in the Codemgr_wsdata directory. Although not recommended, on rare occasions it may be necessary to modify certain files manually. However, great care must be taken to understand and preserve the format of each file being edited. Table 7-1 briefly describes each of the files and directories contained in the metadirectory. Information regarding the format of these files is available in the man(4) page for each file.

Table 7-1 Contents of the Codemgr_wsdata Metadata Directory

File/Dir Name 

Description 

access_control

The access_control file contains information that controls which users are allowed to execute Configuring transactions and commands for a given a workspace. When workspaces are created, a default access control file is also created. See "Controlling Access to Workspaces".

args

The args file is maintained by the Configuring Bringover and Putback transaction commands and contains a list of file, directory, and FLP arguments. Initially, the args file contains the arguments specified when the workspace was created. If you explicitly specify arguments during subsequent Bringover or Putback transactions, the commands determine if the new arguments are more encompassing than the arguments already in the args file; if they are, the new arguments replace the old.

backup/

The backup directory is used to store information that Configuring uses to "undo" a Bringover or Putback transaction. See "Reversing Bringover and Putback Transactions with Undo ".

children

The children file contains a list of the workspace's child workspaces. The names of child workspaces are entered into the workspace's children file during the Bringover Create transaction. Configuring consults this file to obtain the list of child workspaces. When you delete, move, or reparent a workspace, Configuring updates the children file in its parent.

conflicts

The conflicts file contains a list of files in that workspace that are currently in conflict. See Chapter 9, Resolving Conflicts," for more information about conflicts and how to resolve them.

history

The history file is a historical log of transactions and updated files that affect a workspace. See "Viewing Workspace Command History" for more information.

locks

To assure consistency, Configuring locks workspaces during Bringover, Putback and Undo transactions. Locks are recorded in the locks file in each workspace; Configuring consults that file before acting in a workspace. See "Ensuring Consistency Through Workspace Locking".

nametable

The nametable file contains a table of SCCS file names (path names relative to that workspace) and a unique number represented as four 32-bit hexadecimal words. Each entry in the table is terminated by a newline character. The nametable file is used by Configuring during Bringover and Putback to accelerate the processing of files that have been renamed. If this file is not available, Configuring rebuilds it automatically during the next Putback or Bringover transaction. See "Renaming, Moving, or Deleting Files".

notification

The notification file is edited by users to register notification requests. This facility permits Configuring to detect events that involve that workspace and to send electronic mail messages in response to the event. See "How to Notify Users of Changes to Workspaces".

parent

The parent file contains the path name of the workspace's parent workspace and is created by the Bringover Create transaction, or by the Reparent command if the workspace was originally created with the Create Workspace command (and thus had no parent). Configuring consults this file to determine a workspace's parent. When you delete, move, or reparent a workspace, Configuring updates the parent file in its children.

putback.cmt

The putback.cmt file is a cache of the text of the comment from the last blocked Putback transaction. When a Putback transaction is blocked, the comment is discarded. Configuring caches the comment in putback.cmt so that you can retrieve the original text when you reexecute the transaction.

Creating a Workspace

You can create a workspace in one of two ways:

Using Create Workspace

You can use File > Create Workspace to create new workspaces. Type the name of the new workspace's root (top-level) directory in the Workspace Directory text box and click OK.

If the workspace you are creating already exists as a directory hierarchy, Configuring converts it to a workspace by simply adding the Codemgr_wsdata subdirectory in the root directory and displaying its icon in the Workspace Graph pane.

If the directory does not already exist, Configuring creates both the root directory and the Codemgr_wsdata subdirectory.

Using the Bringover Create Transaction

Use the Bringover Create transaction (on the Transactions menu) to copy files from a parent workspace to a nonexistent child workspace; the child is automatically created as part of the transaction. See "Creating a New Child Workspace (Bringover Create)" for details.

The online help provides further assistance in creating new workspaces. To access the help, choose Help > Help Contents > Starting a Project.

Deleting a Workspace

You delete workspaces by selecting their icons in the Workspace Graph pane and then Edit > Delete.

The Delete submenu provides two items for deleting workspaces:

In either case Configuring automatically updates records in parent and child workspaces to reflect the deletion of the workspace.

Moving and Renaming a Workspace

Since a workspace is a directory, you move it by changing its path name. There are two ways that you can move and rename a workspace:

In addition to changing the workspace path name, both methods also update the appropriate data files in the parent and child workspaces to contain the new name. These data files are discussed in "The Workspace Metadata Directory ".

Caution - Caution -

Do not use the mv command to rename or move workspaces.

The Configuring Rename command updates files in the workspace's parent and children, as well as logging the event in the Codemgr_wsdata/history file.

If you inadvertently use the mv command to move and rename a workspace and discover that it has become "disconnected" from its parent and children, you can use the Rename command to reconnect it.

For example, if you used the mv command to rename a workspace from A to B:

  1. Use the Rename command to rename B to C.

    This causes Configuring to update the workspace's new name (C) in the parent and child workspaces. To save time, be sure to use a path name on the same device.

  2. Use the Rename command to change C back to B.

    Everything should be reconnected.

Reparenting a Workspace

As discussed in Chapter 3, Introduction to TeamWare Configuring, the parent/child relationship is the thread that connects the workspace hierarchy. Configuring provides the means for you to change this relationship at your discretion.

This section discusses how you can explicitly change a workspace's parent. It is also possible for you to implicitly change a workspace parent "on the fly" (for the duration of a single command) by specifying the new parent's path name as part of a Bringover Update or Putback transaction. See the descriptions of the Bringover Update and Putback transactions in Chapter 8, Copying Files between Workspaces" for more information.

Two Ways to Reparent Workspaces

This section describes two equivalent ways to reparent workspaces.

Drag and Drop Workspace Icons

You can change a workspace's parent by selecting its icon in the Workspace Graph Pane, pressing and holding the SHIFT key, and dragging it on top of its new parent's icon. The display is automatically adjusted to reflect the new relationship.

Note -

You are prompted to confirm the change.

You may also "orphan" a workspace by selecting its icon, pressing SHIFT, and dragging it to an open area on the Workspace Graph pane. The workspace no longer has a parent: the display is automatically adjusted to reflect its new status.

The Parent Command

You can change a workspace's parent by selecting its icon in the Workspace Graph pane and then choosing Edit > Parent.This opens the Parent dialog box.

When the window is initially opened, the New Parent Workspace Directory text box contains the name of the current parent. Edit that line so that it contains the name of the new parent file and click the Parent button. The Workspace Graph pane is automatically adjusted to reflect the new relationship.

If you do not specify a parent workspace in the New Parent Workspace Directory text box, the workspace is orphaned--it has no parent. The Workspace Graph pane is automatically adjusted to reflect its new status.

Reasons to Change a Workspace's Parent

You might want to permanently or temporarily change a workspace parent for any of these reasons:

A Reparenting Example

Often a bug is fixed in a version of a product and a patch release is made to distribute the fixed code. The code that was fixed must usually be incorporated into the next release of the product as well. If the product is developed using Configuring, the patch can be incorporated relatively simply by means of reparenting.

In the following example, a patch is developed to fix a bug in Release 1.0 of a product. The patch must be incorporated into Release 2.0, which has begun development.

  1. The workspace in which the patch was developed (or the workspace from which it is released) is cloned by means of the Bringover Create transaction. The reason the workspace is cloned is that it will be altered by its interaction with its new parent (Bringover transaction to synchronize it with its new parent).

  2. Either of the two reparenting methods are used to change the cloned workspace's parent from 1.0patch to 2.0. (see Figure 7-1).

    Figure 7-1 Patch Workspace Reparented to New Release

    Graphic

  3. The workspace is then updated from its new parent, and any new work is brought over from 2.0. (see Figure 7-2A).

  4. The fixes made for the patch are merged in patch with the files from 2.0 and are put back into the 2.0 workspace where they are now available to workspace 2.0child. (see Figure 7-2B).

    Figure 7-2 Files Brought Over, Merged, and Incorporated into the New Release

    Graphic

  5. Files are brought over to 2.0child, and patch is deleted by means of Edit > Delete > Sources and Codemgr_wsdata Directory. (Figure 7-3).

Figure 7-3 Patched Files Brought Over into 2.0child; patch Deleted

Graphic

Controlling Access to Workspaces

Configuring permits you to control the access that users have to your workspaces. Table 7-2 lists and describes the eight types of access over which you can exercise control.

Table 7-2 Operations Over Which You Have Access Control

Type of Access 

Description 

bringover-from 

Controls which users may bring over files from this workspace

bringover-to 

Controls which users may bring over files to this workspace

putback-from 

Controls which users may put back files from this workspace

putback-to 

Controls which users may put back files to this workspace

undo 

Controls which users may "undo" commands executed in this workspace 

workspace-delete 

Controls which users may delete this workspace 

workspace-move 

Controls which users may move this workspace 

workspace-reparent 

Controls which users may reparent this workspace 

workspace-reparent-to 

Controls which users may reparent other workspaces to this workspace 

Prior to taking any of the actions listed above, Configuring consults a file in the Codemgr_wsdata subdirectory named access_control to determine whether the user taking the action has access permission to the workspace for that purpose. The access_control file is a text file that contains a list of the eight operations and corresponding values that stipulate who is permitted to perform those operations. The access_control file is automatically created at the time the workspace is created and is owned by the creator of the workspace.

To view and change access permissions, choose Options > Workspace, then use the Category list box to choose the Access Control pane of the Workspace Properties dialog box (see "Viewing and Changing Access Control Values").

Table 7-3 shows the default contents of access_control after you create a workspace:

Table 7-3 Default Access Control Permissions

Operation 

Permissions 

bringover-from 

 

bringover-to 

creator 

putback-from 

 

putback-to 

 

undo 

 

workspace-delete 

creator 

workspace-move 

creator 

workspace-reparent 

creator 

workspace-reparent-to 

 

Note -

Creator permission indicates that Creator's login name appears.

You can express which users have or do not have access to a workspace in a number of ways. Table 7-4 shows all of the value types you can specify to control access to your workspaces and what the entries mean.

Table 7-4 Workspace Access Control Values

Value 

Meaning 

@engineering 

All users in the net group named engineering can execute this operation

-@engineering 

No users from the net group named engineering can execute this operation. Note that "-" denotes negation.

@special -user2 @engineering 

All users in the net groups special and engineering can execute the operation; user2 cannot (unless user2 is in the special netgroup). "-" denotes negation.

user1 user2 

The users user1 and user2 can execute the operation.

"-" 

No user can execute the operation. 

creator 

Only the user who created the workspace can execute the operation. Note that the creator's login name actually appears. 

(no entry)

Any user may execute the operation. 

Note -

If a user is listed as having both access permission and restriction, the first reference is used.

Note -

Performance may degrade when net groups are included in the access control file. The time required to look up group membership can add several seconds to the execution of a given operation.

Viewing and Changing Access Control Values

You can view and change the access control status of a workspace using the Workspace Properties dialog box.

Viewing Access Control Status

To view the access control status of a workspace:

  1. Select a workspace icon in the Workspace Graph pane.

  2. Choose Options > Workspace.

  3. Select Access Control from the Categories list box.

Changing Access Control Values

To change the access control status of a workspace:

  1. Select a workspace icon in the base window Workspace Graph pane.

  2. Choose Options > Workspace.

  3. Select Access Control from the Categories list box.

  4. Select an access line in the global Access Control list, then click Edit to open the Access Control Properties dialog box.

    The operation you selected before clicking Edit is automatically selected for you in the Operation list box.

    Or, use the Operation list box in the Access Control Properties dialog box to select an operation type.

  5. Select the radio button for the type of permission you wish to allow:

    • None--No users have permission

    • All--All users have permission

    • Specify--Use the Permissions list to construct a list of users and netgroups that are to be granted or denied permission

  6. If you choose to specify individual and/or group permissions, construct your entry using:

    • The Name text box to type the name of the user or netgroup

    • The Type radio buttons to specify whether the entry is a user or a netgroup

    • The Access buttons to specify whether the specified user/netgroup is granted or denied permission

  7. Click Insert Before or Insert After to add your entry into the Permissions list.

  8. Click Apply to enter your selection into the global Access Control list.

  9. In the Workspace Properties dialog box, click Apply to write the changes to the access_control file.

How to Notify Users of Changes to Workspaces

You can request Configuring to notify you (through an electronic mail message) when a variety of Configuring events occur in a workspace. Notification requests are entered in the file named notification in the Codemgr_wsdata directory.

A notification request consists of the following items:

The following is an example of a notification file that contains three requests: 

chip@mach1 bringover-to
BEGIN
dir1/foo.cc
dir2
END
biff@mach2 bringover-to putback-to
BEGIN
.
END
biff@mach2 workspace-move

In the first entry, the user chip@mach1 requests to be notified when the file dir1/foo.cc and any file in the directory dir2 (path names are relative to the workspace root directory) are brought over to the workspace.

Note -

File and directory entries for each event are bracketed by BEGIN/END statements. An empty list, a missing list, or a list that consists of only the "." character indicate that all files and directories in the workspace are registered for notification.

In the second entry, user biff@mach2 requests to be notified when any file in the workspace is brought over to, or put back to, the workspace. The "." character represents all files in the workspace.

In the third entry, biff@mach2 requests to be notified if the workspace is moved. Events that involve entire workspaces (delete, move, reparent) do not accept directory/file lists.

Table 7-5 lists the events for which you can register notification requests:

Table 7-5 Notification Events

Event Name 

Description 

bringover-from 

Send mail whenever files are brought over from the workspace in which the notification file is located.

bringover-to 

Send mail whenever files are brought over to the workspace in which the notification file is located.

putback-from 

Send mail whenever files are put back from the workspace in which the notification file is located.

putback-to 

Send mail whenever files are put back to the workspace in which the notification file is located.

undo 

Send mail whenever a transaction is "undone" in the workspace in which the notification file is located. 

workspace-delete 

Send mail if the workspace in which the notification file is located is deleted. 

workspace-move 

Send mail if the workspace in which the notification file is located is moved. 

workspace-reparent 

Send mail if the workspace in which the notification file is reparented. 

workspace-reparent-to 

Send mail if the workspace becomes the new parent of an existing workspace. 

Viewing and Changing Notification Entries

To view and change notification entries, select a workspace icon in the Workspace Graph pane and choose Options > Workspace. Select Notification from the Category list box. The requests contained in the notification file are similar to those displayed in the Workspace Properties dialog box.

Use the buttons to modify, create, and delete notification entries. Clicking Create Entry or Edit Entry opens the Notification Entry dialog box.

Creating a New Notification Entry

To create a new notification entry:

  1. Click Create Entry with no items selected.

  2. The Notifications Entry dialog box opens; use this dialog box to specify the following information:

    1. Type the mail address to which notification mail is to be sent in the Mail To text box.

      The mail address can be any valid mail address, including an alias.

    2. Select the appropriate radio button for the event about which notification mail is to be sent.

    3. Select the appropriate radio button for the files to which the notification event applies:

      - All for any file in the workspace

      - Specify for specific directories or files

  3. If you choose to specify files or directories, create the list of directories and files in the Files text pane.

    • To add files to the list, click Add to List and select files in the Add Notification Files dialog box

    • To delete files from the list, click Delete or Delete All.

  4. Click Apply to add the entry to the global Notification list.

  5. Click Apply in the Workspace Properties dialog box to apply changes to the notifications file.

Modifying a Existing Entry

To modify an existing entry:

  1. Select the entry in the Notification pane of the Workspace Properties dialog box and click Edit Entry.

  2. Use the Notification Entry dialog box to modify the entry.

  3. Click Apply to modify the entry in the global Notification list.

  4. Click Apply in the Workspace Properties dialog box to apply changes to the notifications file.

    Note -

    The following events involve entire workspaces and thus do not require a directory/file list:workspace-delete, workspace-move, workspace-reparent, workspace-reparent-to.

    Note -

    When a directory is specified in the list, all files hierarchically beneath it are automatically registered.

Viewing Workspace Command History

Configuring commands are logged in the text file Codemgr_wsdata/history. Commands that affect a single workspace are logged only in that workspace; interworkspace transactions are logged in both the source and destination workspaces.

Note -

Although command entries are logged in both the source and destination workspaces, the list of changed files is entered only in the destination directory.

You can view the contents of this file to track or reconstruct changes that have been made to a workspace over time. Log entries consist of the underlying command-line entries and do not correspond to GUI menu item names. If you have any questions about the meaning or syntax of a command, refer to its man page for details. Table 7-6 lists the GUI operations and the corresponding CLI command that is entered in the history log.

Table 7-6 Corresponding GUI and CLI Commands

GUI Menu Item 

Corresponding CLI Command 

Create Workspace 

workspace create

Rename 

workspace move

Parent  

workspace parent

Bringover Create 

bringover

Bringover Update  

bringover

Putback 

putback

Undo 

ws_undo

Resolve 

resolve

Note -

In active workspaces, the Codemgr_wsdata/history file can grow very quickly. You may want to periodically prune the file to reduce its size.

The following portion of a history file was generated during a Bringover Update transaction; entries are described in Table 7-7. This entry is taken from the history file in the child; the corresponding entry in the parent is identical except that file status messages are not included.

COMMAND bringover -w /home/sponge3/larryh/ws/man_pages -p 

/home/sponge3/larryh/ws/manpages man trans/man  

update: man/Makefile 

update: man/man5/access_control.5 

create: man/man5/notification.5 

create: man/man1/codemgr.1 

rename from: man/man1/def.dir.flg.1 

to: man/man1/def.dir.flp.1 

update: man/man1/def.dir.flp.1 

create: man/man1/codemgrtool.1 

rename from: man/man1/fileresolve.1 

to: deleted_files/man/man1/fileresolve.1 

update children's name history: 

deleted_files/man/man1/fileresolve.1 

rename from: man/man1/resolve_tty.1 

to: deleted_files/man/man1/resolve_tty.1 

update: deleted_files/man/man1/resolve_tty.1 

create: trans/man/man1/codemgr_acquire.1 

create: trans/man/man1/codemgr_prepare.1 

CWD /tmp_mnt/home/sponge3/larryh/temp 

RELEASE Beta 1.0  

HOST croak 

USER larryh 

PARENT_WORKSPACE (/home/sponge3/larryh/ws/manpages) (sponge:/export/home/sponge3/larryh/ws/manpages) 

CHILD_WORKSPACE (/home/sponge3/larryh/ws/man_pages) (sponge:/export/home/sponge3/larryh/ws/man_pages) 

START (Mon Jul 13 13:31:16 1992 PDT) (Mon Jul 13 20:31:16 1992 GMT) 

END (Mon Jul 13 13:32:08 1992 PDT) (Mon Jul 13 20:32:08 1992 GMT) 

STATUS 0 

Table 7-7 History File Entry Descriptions

Entry 

Description 
COMMAND

Underlying command line issued for the operation. File status messages as displayed in the Transaction Output window are included only in the destination workspace history file. 
CWD

Name of the current working directory when the command was executed. 
RELEASE

Release number of the TeamWare software 
HOST

Name of the system from which the command was executed. 
USER

Login name of the user who executed the command. 
PARENT_WORKSPACE

The path name of the parent workspace specified in two formats: host-specific and machine:pathname.
CHILD_WORKSPACE

The path name of the child workspace specified in two formats: host-specific and machine:pathname.
START

Time the command started execution, both locally and as measured by Greenwich Mean Time (GMT). 
END

Time the command completed execution, both locally and as measured by Greenwich Mean Time (GMT). 
STATUS

Exit status of the command: 0 = Normal completion, any other value indicates an error condition, warning, or other status. 

Ensuring Consistency Through Workspace Locking

To assure consistency, the Configuring transactions--Bringover, Undo, and Putback--lock workspaces while they are working in them. These locks only affect Configuring transactions; other commands such as SCCS programs, are not affected. Locks are recorded in the Codemgr_wsdata/locks file in each workspace; the Configuring transaction commands consult that file before acting in a workspace. Two types of locks are used:

If a Configuring command is unable to remove its lock after completion (for example, the system crashes), you must remove the lock yourself before Configuring commands will again be able to read and/or write in the workspace. You can use the Configuring GUI to view and delete active locks for a workspace, or you can edit the file directly.

To view and delete locks using the Configuring GUI, select a workspace icon from the Workspace Graph pane and choose the Workspace item from the main Props menu. Use the Category menu to choose the Locks pane.

To delete locks, select the line that contains the lock and click on the Delete button. To apply the deletion to the locks file, click on the Set Default button.

Configuring Environment Variables

Configuring consults environment variables to direct some of its actions. Configuring uses the CODEMGR_WS and CODEMGR_WSPATH environment variables.

The CODEMGR_WS Environment Variable

If you do not explicitly specify a workspace as the focus of a Configuring command, many of the commands will consult the shell environment variable CODEMGR_WS to determine a default workspace as the focus of their action. If you have a workspace that is the primary focus of your work, using the CODEMGR_WS environment variable allows you to execute the commands without specifying the workspace argument.

The CODEMGR_WSPATH Environment Variable

When it is started, Configuring automatically loads workspaces from directory path names specified in the CODEMGR_WSPATH environment variable. You can set the CODEMGR_WSPATH environment variable to one or more directories that contain workspace directories. For example, to set CODEMGR_WSPATH to the directories /export/home/ws and ~/projects/ws, you would use the following command:

% setenv CODEMGR_WSPATH "/export/home/ws ~/projects/ws"

Note -

The CODEMGR_WS environment variable overrides the CODEMGR_WSPATH. environment variable. That is, the commands that you execute in Configuring use the default workspaces defined in the CODEMGR_WS environment variable.