Creating all C-language header files as elements of type hdr_file allows flexibility in configuring views. Suppose that one developer has been reorganizing

all of the project's header files, working on a branch named header_reorg to avoid destabilizing others' work. To compile with the new header files, another developer can use a view reconfigured with one additional rule:

element * CHECKEDOUT
element -eltype hdr_file * /main/header_reorg/LATEST
element * /main/LATEST

Suppose that a coding-standards program named check_var_names is to be executed on each C-language source file. If all such files have element type c_src, then a single cleartool command does the job:

%  cleartool find -avobs -visible -element 'eltype(c_src)' \	        -exec 'check_var_names $CLEARCASE_PN'

The create_version method is invoked when a checkin command is entered. The create_version method of the z_whole_copy type manager:

File /usr/atria/lib/mgrs/mgr_info.h shows what arguments will be passed to the method from the calling program (usually cleartool or xclearcase):

/****************************************************************************
 * create_version
 * Store the data for a new version.
 * Store the version's data in the supplied new container, combining it
 * with the predecessor's data if desired (e.g for incremental deltas).
 *
 * Command line:
 *  create_version create_time new_branch_oid new_ver_oid new_ver_num
 *                new_container_pname pred_branch_oid pred_ver_oid
 *                pred_ver_num pred_container_pname data_pname

The only arguments that require special attention are new_container_pname (5th argument), which specifies the pathname of the new data container, and data_pname (10th argument), which specifies the pathname of the checked-out file.

File /usr/atria/lib/mgrs/mgr_info.sh lists the appropriate exit statuses and provides a symbolic name for the create_version method:

# Any unexpected value is treated as failure
MGR_FAILED=1
# Return Values for store operations
MGR_STORE_KEEP_NEITHER=101
MGR_STORE_KEEP_JUST_OLD=102
MGR_STORE_KEEP_JUST_NEW=103
MGR_STORE_KEEP_BOTH=104
 .
 .
MGR_OP_CREATE_VERSION="create_version"

Figure 19-3 shows the code that implements the create_version method.

Figure 19-3. 'create_version' Method

The Bourne shell allows only nine command-line arguments. The shift 1 in Line 1 discards the first argument (create_time), which is unneeded. Thus, the

pathname of the checked-out version (data_pname), originally the 10th argument, becomes $9.

In Line 6, the contents of data_pname are compressed, then appended to the new, empty data container: new_container_pname, originally the 5th argument, but shifted to become $4. (Lines 2-5 verify that the new data container is, indeed, empty.)

Finally, the exit status of the compress command is checked, and the appropriate value is returned (Lines 7–11). The exit status of the create_version method indicates that both the old data container (which contains the predecessor version) and the new data container (which contains the new version) should be kept.

An element's construct_version method is invoked when standard UNIX software reads a particular version of the element (unless the contents are already cached in a cleartext storage pool). For example, the construct_version method of element monet_admin.1 is invoked by the view_server when a user enters these commands:

% cp monet_admin.1 /usr/tmp   (read version selected by view)
% cat monet_admin.1@@/main/4       (read a specified version)

It is also invoked during a checkout command, which makes a view-private copy of the most recent version on a branch. The construct_version method of the z_whole_copy type manager:

File /usr/lib/lib/mgrs/mgr_info.h shows what arguments will be passed to the method:

/****************************************************************************
 * construct_version
 * Fetch the data for a version.
 * Extract the data for the requested version into the supplied pathname, or
 * return a value indicating that the source container can be used as the
 * cleartext data for the version.
 *
 * Command line:
 *  construct_version source_container_pname data_pname version_oid

File /usr/atria/lib/mgrs/mgr_info.sh lists the appropriate exit statuses and provides a symbolic name for the construct_version method:

# Any unexpected value is treated as failure
MGR_FAILED=1
# Return Values for construct operations
MGR_CONSTRUCT_USE_SRC_CONTAINER=101
MGR_CONSTRUCT_USE_NEW_FILE=102
 .
 .
MGR_OP_CONSTRUCT_VERSION="construct_version"

Figure 19-4 shows the code that implements the construct_version method.

Figure 19-4. 'construct_version' Method

In Line 1, the contents of source_container_pname are uncompressed, then stored in the cleartext container, data_pname. The remaining lines return the appropriate value to the calling process, depending on the success or failure of the uncompress command.

A new type manager can be tested only by actually using it on some ClearCase host. This process need not be obtrusive. Since the type manager has a new name, no existing element type — and hence, no existing element — uses it automatically. To place the type manager in service, create a new element type, create some test elements of that type, and run some tests.

The following testing sequence continues the mp_mgr example.

Creating a Test Element Type. To make sure that an untested type manager is not used accidentally, associate it with a new element type, manpage_test, whose use is restricted to yourself.

% cleartool mkeltype -nc -supertype compressed_file \ 
         -manager mp_mgr manpage_test 
% cleartool lock -nusers $USER -eltype manpage_test 

Creating and Using a Test Element. These commands create a test element that uses the new type manager, and tests the various data-manipulation methods:

% cd directory-in-test-VOB 
% cleartool checkout -nc .
                              (tests `create_element' method)
% cleartool mkelem -eltype manpage_test -nc -nco test.1
% cleartool checkout -nc test.1
                           (tests `construct_version' method)
% vi test.1                        (edit checked-out version)
% cleartool checkin -c "first" test.1
                             (tests `create_ version' method)
% cleartool checkout -nc test.1
                          (tests `construct_ version' method)
% vi test.1
                                   (edit checked-out version)
% cleartool checkin -c "second" test.1
                             (tests `create_ version' method)
% cleartool diff test.1@@/main/1 test.1@@/main/2
                                     (tests `compare' method)

After a type manager has been fully tested, you can “make it official” with the following procedure.

Installation. A VOB is a network-wide resource — it can be mounted on any ClearCase host. But a type manager is only a host-wide resource — a separate copy must be installed on each host where ClearCase client programs execute. (It need not be installed on hosts that serve only as repositories for VOBs and/or views.)

To install the type manager on a particular host, create a subdirectory in /usr/atria/lib/mgrs, then populate it with the programs that implement the methods. You might create across-the-network symbolic links to a “master copy” on a server host.

Creation of Element Types. Create one or more element types that use the type manager, just as you did in <Emphasis>Testing the Type Manager (but don't include “test” in the name of the element type!). For example, you might name the element type named manpage or nroff_src.

Conversion of Existing Elements. It is likely that you'll want to have at least a few existing elements use the new type manager. The chtype command does the job:

% cleartool chtype -force manpage pathname(s) 

Permission to change an element's type is restricted to the element's owner, the VOB owner, and the root user.

Revision of Magic Files. If you want the new element type(s) to be used automatically for certain newly created elements, create (or update) a local.magic file in each host's /usr/atria/config/magic directory:

manpage src_file text_file file: -name "*.[1-9]" ;

Public Relations. Advertise the new element type(s) to all ClearCase users, describing the features and benefits of the new type manager. Be sure to include directions on how to gain access to the new functionality automatically (through filenames that match `magic' file rules) and explicitly (with mkelem -eltype).