Beruflich Dokumente
Kultur Dokumente
INTEGRATION
Release 4.1 and later
UNIX Edition
ClearCase/FrameMaker Integration
August 2000
Rational Software Corporation 20 Maguire Road Lexington, Massachusetts 02421
IMPORTANT NOTICE
Copyright Notice
Copyright © 1992, 2000 Rational Software Corporation. All rights reserved.
Copyright 1989, 1991 The Regents of the University of California
Copyright 1984–1991 by Raima Corporation
Copyright 1992 Purdue Research Foundation, West Lafayette, Indiana 47907
Trademarks
Rational, the Rational logo, Atria, ClearCase, ClearCase MultiSite, ClearCase Attache, ClearDDTS,
ClearQuest, ClearGuide, PureCoverage, Purify, Quantify, Rational Rose, and SoDA are trademarks or
registered trademarks of Rational Software Corporation in the United States and in other countries. All other
names are used for identification purposes only and are trademarks or registered trademarks of their
respective companies.
Microsoft, MS, ActiveX, BackOffice, Developer Studio, Visual Basic, Visual C++, Visual InterDev, Visual J++,
Visual Studio, Win32, Windows, and Windows NT are trademarks or registered trademarks of Microsoft
Corporation.
Sun, Solaris, and Java are trademarks or registered trademarks of Sun Microsystems, Inc.
Oracle and Oracle7 are trademarks or registered trademarks of Oracle Corporation.
Sybase and SQL Anywhere are trademarks or registered trademarks of Sybase Corporation.
U.S. Government Rights
Use, duplication, or disclosure by the U.S. Government is subject to restrictions set forth in the applicable
Rational License Agreement and in DFARS 227.7202-1(a) and 227.7202-3(a) (1995),
DFARS 252.227-7013(c)(1)(ii) (Oct 1988), FAR 12.212(a) 1995, FAR 52.227-19, or FAR 52.227-14, as applicable.
Patent
U.S. Patent Nos. 5,574,898 and 5,649,200 and 5,675,802. Additional patents pending.
Warranty Disclaimer
This document and its associated software may be used as stated in the underlying license agreement, and,
except as explicitly stated otherwise in such license agreement, Rational Software Corporation expressly
disclaims all other warranties, express or implied, with respect to the media and software product and its
documentation, including without limitation, the warranties of merchantability or fitness for a particular
purpose or arising from a course of dealing, usage or trade practice.
Technical Acknowledgments
This software and documentation is based in part on BSD Networking Software Release 2, licensed from the
Regents of the University of California. We acknowledge the role of the Computer Systems Research Group
and the Electrical Engineering and Computer Sciences Department of the University of California at Berkeley
and the Other Contributors in its development.
This software and documentation is based in part on software written by Victor A. Abell while at Purdue
University. We acknowledge his role in its development.
This product includes software developed by Greg Stein <gstein@lyra.org> for use in the mod_dav module
for Apache (http://www.webdav.org/mod_dav/).
Preface ........................................................................................................................................ix
About This Manual ...........................................................................................ix
ClearCase Documentation Roadmap ..............................................................x
Typographical Conventions ............................................................................xi
Technical Support ............................................................................................xii
1. Introduction ........................................................................................................................... 1
1.1 Version Control Overview................................................................................ 1
1.2 Accessing Files Under Version Control .......................................................... 2
Contents iii
iv ClearCase/FrameMaker Integration
Figures v
Tables vii
This manual describes the ClearCase/FrameMaker Integration. The Integration enables users of
the FrameMaker® publishing system to take advantage of the version-control features in
Rational ClearCase®.
The Integration and this manual are intended for FrameMaker users who are familiar with basic
version-control concepts.
Preface ix
ClearCase Documentation Roadmap
Orientation
Introduction to ClearCase
ClearCase and MultiSite Release Notes
ClearCase Tutorials
Project
Development Management
More Information
ClearCase Reference Manual
ClearCase Online Help
clearcase.rational.com
Build ClearCase
Management Administration
x ClearCase/FrameMaker Integration
Typographical Conventions
➤ ccase-home-dir represents the directory into which the ClearCase Product Family has been
installed. By default, this directory is /usr/atria on UNIX and
C:\Program Files\Rational\ClearCase on Windows.
➤ attache-home-dir represents the directory into which ClearCase Attache has been installed.
By default, this directory is C:\Program Files\Rational\Attache, except on Windows 3.x,
where it is C:\RATIONAL\ATTACHE.
➤ Bold is used for names the user can enter; for example, all command names, file names, and
branch names.
➤ Italic is used for variables, document titles, glossary terms, and emphasis.
➤ A monospaced font is used for examples. Where user input needs to be distinguished
from program output, bold is used for user input.
➤ Nonprinting characters are in small caps and appear as follows: <EOF>, <NL>.
➤ Key names and key combinations are capitalized and appear as follows: SHIFT, CTRL+G.
➤ {} Braces enclose a list from which you must choose an item in format and syntax
descriptions.
➤ ... In a syntax description, an ellipsis indicates you can repeat the preceding item or line
one or more times. Otherwise, it can indicate omitted information.
NOTE: In certain contexts, ClearCase recognizes “...” within a pathname as a wildcard, similar
to “*” or “?”. See the wildcards_ccase reference page for more information.
➤ If a command or option name has a short form, a “medial dot” ( ⋅ ) character indicates the
shortest legal abbreviation. For example:
lsc·heckout
This means that you can truncate the command name to lsc or any of its intermediate
spellings (lsch, lsche, lschec, and so on).
Preface xi
Technical Support
If you have any problems with the software or documentation, please contact Rational Technical
Support via telephone, fax, or electronic mail as described below. For information regarding
support hours, languages spoken, or other support information, click the Technical Support link
on the Rational Web site at www.rational.com.
1
The ClearCase/FrameMaker Integration enables users of the FrameMaker® publishing system
to take advantage of the version-control features available in Rational ClearCase®. The
Integration operates completely within the FrameMaker environment; users do not need to enter
ClearCase version-control commands to use it.
The remaining sections of this chapter provide a brief summary of ClearCase version-control
concepts that are relevant for FrameMaker users. For more information on version control and
ClearCase capabilities, see Introduction to ClearCase and Developing Software with ClearCase.
Informally, you may think of each Save command as creating a new version of the document file.
Formal version-control systems (including ClearCase) use this term differently, however. When
it is under version control in ClearCase, a document file evolves as follows:
➤ A previously created version of the document file is maintained in a read-only state; any user
can open and browse through the document, but no one can modify it.
➤ When you want to modify a document file, you enter a checkout command. The Integration
adds the command File➔ClearCase➔Checkout to the FrameMaker File menu. This makes
the file writable; it is termed the checked-out version.
1 - Introduction 1
➤ You edit the file with FrameMaker, invoking File➔Save as often as you want. Each time you
do so, you update the checked-out version.
➤ At any time, you can check in a new version of the document file, using
File➔ClearCase➔Checkin. At this point, the file becomes read-only again, until the next
checkout, by you or by another user.
A checked-in version is permanent; regardless of changes you make in the document file, you
can always see the old version (and, if you want, compare it with the current version).
Over time, each document file “grows” its own version tree (Figure 1).
NOTE: This figure shows a version tree with a single main branch. In general, version trees can
have any number of subbranches, nested to any level. The Integration works perfectly well with
such document files, but we do not include any specific discussion of branching in this manual.
The following procedure describes the most convenient way to access files under version control:
2 ClearCase/FrameMaker Integration
1. Establish a view context.
% cd /vobs/docgrp/my_project
3. Start FrameMaker.
% maker
Alternatively, you can use view-extended pathnames to access document files that are already
under ClearCase version control:
1. Start the view. This step is not necessary if the view is already active.
2. Start FrameMaker.
% maker
3. Click Open and enter a view-extended pathname to access the directory containing the files;
for example:
/view/my_view/vobs/docgrp/my_project
1 - Introduction 3
4 ClearCase/FrameMaker Integration
2 Installing and Configuring the
ClearCase/FrameMaker Integration
2
This chapter describes how to install the Integration.
The ClearCase/FrameMaker Integration is a layered product; you cannot install it until you
install FrameMaker. We assume that you are familiar with the ClearCase installation model
described in the ClearCase Product Family Installation Notes.
➤ If you have installed FrameMaker on a server and users run it from that server, you install
the ClearCase/FrameMaker Integration on the server. To use the Integration, users must
install ClearCase on their client hosts and run FrameMaker from the server. Users who do
not have ClearCase installed on their hosts cannot use the Integration.
➤ If FrameMaker has been installed on each user’s host, you install ClearCase and the
ClearCase/FrameMaker Integration on each host.
The ClearCase FrameMaker Integration is included on the ClearCase CD-ROM and uses the
ClearCase Product Family installation as described in ClearCase Product Family Installation Notes.
The only way this installation differs from the description in ClearCase Product Family Installation
Notes is in the form of an additional option on the install_release command (see Step #1).
1. Following the instructions in ClearCase Product Family Installation Notes, run install_release
–level 3 on the host where the FrameMaker installation directory (FMHOME) is located. Run
the installation program specifically for the architecture where FMHOME is located.
You may or may not want to install other ClearCase components at the same time as the
ClearCase FrameMaker Integration. It is not a requirement that ClearCase be installed on the
same host as FrameMaker. Installing the ClearCase FrameMaker Integration adds files only
to the FMHOME directory.
4. Follow the remaining installation steps as described in ClearCase Product Family Installation
Notes.
For example, if you are a C shell user, you can put this line in your .cshrc or .login file:
6 ClearCase/FrameMaker Integration
This setting configures the Integration as follows:
The details of setting up your environment vary among UNIX shell programs (C shell, Bourne
shell, and so on), and also among the UNIX variants supported by the Integration. See your
system administrator if you need help setting the CCASE_FRAME_OPTS variable in your
environment.
–off Disables the Integration By default, the Integration is enabled for all FrameMaker
sessions running on a host, if ClearCase is also installed on
that host.
-co_unreserved Performs all checkouts with By default, all checkouts are reserved.
the –unreserved option
-ci_identical Allows creation of document By default, the Integration cancels a checkout rather than
versions that are identical to creating a new, identical successor version.
their predecessors NOTE: The –ci_identical functionality does not
correspond exactly to native ClearCase functionality. For
many kinds of files, it is not necessary to specify the
ClearCase checkin –identical command to enable creation
of identical successor versions. With the Integration, you
must use –ci_identical in your CCASE_FRAME_OPTS
variable to enable creation of identical successor versions.
-unco_keep Retains .keep file as copy of These options are mutually exclusive.
each document that you
uncheckout
-unco_rm Does not retain .keep file
8 ClearCase/FrameMaker Integration
3 Using the Integration on Individual
Document Files
3
This chapter describes the Integration’s version-control capabilities for individual FrameMaker
document files. Facilities for book files are described in Chapter 4.
2. Click File➔ClearCase➔Checkout.
The comment can span multiple lines. Click OK when you’re finished; pressing RETURN is
not enough.
The comment is a character string that is stored in the ClearCase VOB database that tracks the
evolution of the document file. You can view comments using ClearCase informational
commands, such as lscheckout and lshistory. (These commands are not accessible through the
Integration.)
In standard FrameMaker, you can open and edit a document that is stored in a read-only disk
file. You can make any number of modification, but when you attempt to save the file,
FrameMaker displays this error message: cannot open for writing.
The Integration changes this situation. The first time you attempt to modify a document that you
have not checked out, the Integration intervenes. You may notice a slight delay and the words
API: ClearCase in the status bar at the lower-left corner of the document window.
The message box that appears asks whether you want to check out the file. If you click Yes, the
checkout operation proceeds, as if you had clicked File➔ClearCase➔Checkout (see Checking Out
a Document File on page 9).
If you click No, no checkout occurs. You can edit the document, but a cannot open for writing
error message appears when you click File➔Save. At that point, do the following:
1. Click File➔ClearCase➔Checkout. This does not change the contents of the document
window.
Alternatively, you can click File➔Save As to create a view-private file with your edits.
1. Click File➔ClearCase➔Checkin.
If you entered a comment when you checked out the file (Step #3 on page 9), it appears in
this window. You can accept this comment, edit it, delete it, and so on. Click OK when you’re
finished; pressing RETURN is not enough.
NOTE: In some cases, you may find that a comment window does not appear. Instead, the
Integration displays a popup window announcing that the checkout has been canceled. This
10 ClearCase/FrameMaker Integration
indicates that the Integration has determined that a new version would be identical to its
predecessor. Instead of creating a new, redundant version in this case, the Integration reverts to
the existing version. You can override this feature; see the description of the –ci_identical
keyword in Table 1 on page 7.
You can use File➔ClearCase➔Checkin on a file that is not under ClearCase version control—for
example, on a newly created document file. This feature applies only to view-private files, which
are document files you’ve created in VOB directories but have not yet placed under version
control. It does not work in non-ClearCase locations, for example, in your home directory.
When you attempt to check in a view-private file, the Integration invites you to place the file
under version control, as a new element. If you click Yes, the following sequence occurs:
1. The Integration checks out the directory in which the document is stored. (ClearCase
version-controls directories as well as files.)
2. The Integration prompts for a creation comment for the document file.
3. The Integration offers to check in the directory to create a new version. Click Yes, unless you
intend to place additional files under version control at the same time.
NOTE: Be sure to click Yes after placing the last file under version control. Forgetting to check
in a directory element is a common error and can cause confusion.
NOTE: The Integration does not prompt for comments when performing the checkout/checkin
operations to create a new version of the document directory. ClearCase generates a checkin
comment that lists the new file elements you just created in the directory.
➤ Remove your working copy of the file that you checked out. If you’ve made changes to the
document, this removal may irretrievably destroy useful data.
➤ Preserve your working copy in a view-private file. For example, chap1.doc would be
renamed to the view-private file chap1.doc.keep.)
NOTE:You can configure the Integration to perform one of these actions automatically, thus
bypassing the prompt. See –unco_rm and –unco_keep in Table 1 on page 7.
In either case, the version of the file that was current when you checked it out becomes current
again. This version is read-only; to modify the document, you must check it out again.
The Integration asks whether you want to revert the document window (in-memory copy of the
document), as well. We suggest that you answer Yes, to avoid possible confusion.
CAUTION: If you do not revert the document window, your in-memory version of the document
will be out of sync with your current on-disk version. This may cause confusion. (On the other
hand, you won’t be able to save the in-memory version, because the file becomes read-only after
an uncheckout operation.)
12 ClearCase/FrameMaker Integration
3.4 Comparing Document Versions
The Integration includes an interface to FrameMaker’s document comparison facility. You can
also use this facility manually to compare versions of a document file.
As shown in Figure 1 on page 2, the versions of a document file are organized into a version tree.
This means that each version has an immediate predecessor. There are actually two cases to
consider:
➤ You have not checked out the file — If you are viewing version 6 of a document, its
predecessor is version 5. In this case, document comparison helps you identify the changes
made in this particular version.
➤ You have checked out the file — You are viewing the checked-out version; its predecessor
is the version from which you checked it out. In this case, document comparison helps you
identify the changes you have made so far.
This command creates two files, in the standard FrameMaker manner: a Document Comparison
Summary and a CMP file with the changes indicated with conditional text.
In ClearCase, all versions of a file are accessible to FrameMaker (and any other program),
through special version-extended pathnames. For example, version 5 of file intro.doc can be
accessed with the following pathname, no matter what the number of the current version of this
document:
intro.doc@@/main/5
Note that double at-signs follow the file name; this extended naming symbol precedes the first
slash.
3. The old version of the document appears as 5 in the list of open documents. (This integer is
the version number, which is the final component of the version-extended pathname.) Select
this as the document to be used in the comparison.
14 ClearCase/FrameMaker Integration
4 Using the Integration on Book Files
4
This chapter describes the Integration’s version-control capabilities for FrameMaker book files.
Facilities for individual document files are described in Chapter 3.
The ClearCase submenu that appears on the FrameMaker File menu for a book file includes two
sets of version-control commands: one that operates on the book file itself, and one that operates
on the document files in the book file. These commands are described in the following sections.
➤ Attempt the modification, at which point the Integration intervenes, initiating the checkout
process by prompting for a comment (as described in section Automatic Checkout When You
Modify a File on page 10).
The checkin and uncheckout operations work on a book file as described in Chapter 3.
Command Description
File➔ClearCase➔Entire Book Checkout Initiates a sequence of checkout operations on the files listed in
the book. You are prompted for a comment string, which
becomes the checkout comment for each file. Any file that is not
under ClearCase version control (is not an element) is ignored.
After processing all the files, the Integration displays status information for the work it has done.
16 ClearCase/FrameMaker Integration