Sie sind auf Seite 1von 110

CM Synergy Learning Guide

Windows Client: Windows NT, Windows 98 Release 6.1 Part Number: LGD-W-061-010

Telelogic North America, Inc. 9401 Jeronimo Road Irvine, California 92618-1908 (949) 830-2022, Fax: (949) 830-2023

LICENSE AGREEMENT
No part of this publication may be reproduced, transmitted, stored in a retrieval system, nor translated into any human or computer language, in any form or by any means, electronic, mechanical, magnetic, optical, chemical, manual or otherwise, without the prior written permission of the copyright owner, Telelogic AB. Copyright infringement is a serious matter under the United States and foreign Copyright Laws. Telelogic AB reserves the right to revise this publication and to make changes from time to time without obligation to notify authorized users of such changes. Consult Telelogic AB to determine whether any such changes have been made. The terms and conditions governing the licensing of Telelogic software consist solely of those set forth in the written contracts between Telelogic AB and its customers.

RESTRICTED RIGHTS LEGEND/NOTICE


Use, duplication or disclosure by the government is subject to the Restricted Rights restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 or FAR 52.227-14, Alternate III, subparagraph (g)(3)(i), each clause of current date.

TRADEMARKS
Adobe, the Adobe logo, Acrobat, the Acrobat logo, FrameMaker, and PostScript are trademarks of Adobe Systems Incorporated or its subsidiaries and may be registered in certain jurisdictions. Telelogic AB, Telelogic, CM Synergy, ChangeSynergy, WebSynergy, and KnowledgeSynergy are registered trademarks of Telelogic AB. HP and HP-UX are registered trademarks of Hewlett-Packard Corporation. AIX is a registered trademark of IBM in the United States. INFORMIX is a registered trademark of Informix Software, Incorporated. Microsoft, Windows, Windows NT, Windows 95, Windows 98, Windows 2000, and/or other Microsoft products referenced herein are either trademarks or registered trademarks of Microsoft Corporation. Netscape and Netscape Enterprise Server are registered trademarks of Netscape Communications Corporation in the United States and other countries. Sun, Sun Microsystems, Solaris, and Java are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. Pentium is a trademark of Intel Corporation. All other products are trademarks or registered trademarks of their respective companies.

The Telelogic documentation was written using FrameMaker software and is controlled using CM Synergy.

NOTICE
The information in this document is subject to change without notice. TELOLOGIC AB MAKES NO WARRANTY OF ANY KIND WITH REGARD TO THIS MATERIAL, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. Telelogic AB shall not be liable for errors contained herein nor for incidental or consequential damages in connection with the furnishing, performance or use of this material. Copyright 2001 Telelogic AB All rights reserved.

ii

CM Synergy Learning Guide

Contents
Overview 1
Locating Information that Developers Need . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

CM Synergy Operations

Start CM Synergy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 How to Use the Project Views Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 How to Use Online Help. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 View File Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 View the History of an Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Change Your Personal Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Navigate through CM Synergy Using Icons. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Check Out a Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Update Your Project With the Latest Changes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Set the Default Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Use an Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 Check Out an Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 Modify Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Make Changes to Your Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 Work Disconnected From the CM Synergy Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Reconnect to the CM Synergy Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Create a New Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 Search the CM Synergy Database for an Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 Add an Object Already in the CM Synergy Database to Your Project . . . . . . . . . . . . . . . . . . . . . . 73 Unuse an Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Delete an Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 Reconfigure Your Project and Unit Test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Check In the Default Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Merge Two Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 Reuse Your Working Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 Work on a Patch Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 Migrate an Existing Project from Your File System into CM Synergy . . . . . . . . . . . . . . . . . . . . . . 93 Stop CM Synergy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

CM Synergy Learning Guide

iii

Appendix A: Unpack the Tutorial Database Index

99 103

iv

CM Synergy Learning Guide

Overview
Seeing is Believing
So many tutorials start with a hard sell of how great the product is instead of what a developer really wants: to strap in and drive. So instead of long paragraphs of Marketing talk, this section quickly describes the standards used in this guide so itll be as easy as possible for you to tour the CM Synergy tool. The goal of this document is to help developers smoothly navigate through the CM Synergy tool, and by using the tool, gain sufficient understanding to use CM Synergy in a production database right away.

Audience
This document is intended for the following users: Developers using the CM Synergy interface Build managers using the CM Synergy interface

Note that developers using CM Synergy for Developers can learn the interface by using the CM Synergy for Developers Tutorial. The tutorial is available on CD-ROM. See your CM administrator for a copy. Build managers who understand the terms and concepts in this document can find out detailed build management information by using the Build Managers Guide, available on the Documentation web site.

Expectations
The exercises in this guide only touch the surface of what you can do with the CM Synergy tools. For further exploration, read the next section, "Locating Information that Developers Need" on page 2 of this chapter.

How to Use This Guide


The operations in this guide are organized linearly, in an order that is typical of how users work with CM Synergy. Additionally, the order builds upon itself so, for example, when you arrive at the operation where you need to search the database, you have created files that youre searching for. Therefore, Telelogic strongly recommends that you perform the exercises in the order presented. Last, some instructions in this tutorial suggest that you use the CM Synergy Quick Card. The Quick Card is a three-fold cardboard card that is shipped with each copy of the CM Synergy Learning Guide. The card summarizes steps to complete operations from the GUI and the CLI.

CM Synergy Learning Guide

Overview

Locating Information that Developers Need


Youll use the Introduction to CM Synergy and the CM Synergy Learning Guide when first starting out with CM Synergy. Both are basic documents for new users. Introduction to CM Synergy Terms, concepts, and methodology

CM Synergy Learning Guide CM Synergy change management exercises that follow a scenario After you finish this guide, you might refer back to it for a while. Once you have the basics wired, use the following sources as references to help you become a CM Synergy power user. Documentation Web Site All documentation that supports the Telelogic change management products is available (with a user name and password) in HTML and PDF format at the Documentation web site. Access the web site by entering: http://www.continuus.com/customersonly/ docs/index.html.

Online Help Step-by-step procedures for performing the operations most commonly used by developers and build managers Dialog descriptions Command descriptions and examples Default settings

CM Synergy Learning Guide

Conventions

Conventions
The following sections describe the conventions used in this document.

Typefaces
Table 1 describes the typeface and symbol conventions used in this document. Table 1. Typeface and Symbol Conventions Typeface Times ALL CAPS Times Italic Times Bold Courier Description Represents explanatory text. Shows the status of an option: either ON or OFF. Designates names of roles (developer), states (working), groups (ccm_root), and users (laura). Used for menu names, dialog box titles, and emphasis. Represents command syntax to be entered verbatim. Also used to signify computer output that appears on-screen and the names of attributes (modify_time), commands (ccm start), functions (remote_type), types (csrc), and paths (c:\users\path). Represents values in a command string that you supply, for example, drive:\username\commands Description Indicates that, from the choices shown, you can specify only one option or argument. Indicates the different options available for a command. Indicates that you can specify more than one of an argument.

Courier Italic

Symbol Pipe ( | ) Brackets ( [...] ) Ellipses ( ... )

Note: A note contains important information about your CM Synergy software.

CM Synergy Learning Guide

Overview

Dialog Options
Table 2 describes how this document defines the options that are found in any dialog. Table 2. Dialog Options, Defined Dialog Box Element Button Drop-down list box Description A button enables you to initiate an action (e.g., clicking the Close button enables you to exit from a dialog). A drop-down list box first appears as a text box with a down arrow displaying the current selection. To view and choose from the list, click on the down arrow at the right of the box. If the list contains more choices than fit in the initial view of the box, use the scroll bar. A list box displays a list of choices. If the list contains more information than fits in the initial view of the box, scroll bars are provided. A check box is a square box that sets an option if it is selected or cleared. A text box is a space in a dialog where you need to enter information. Pop-up menus "pop up" when you place the cursor over an object, then hold down the Menu mouse button. A pop-up menu is context sensitive; the list of available actions is dependent on the object the cursor is on when you bring up the menu. Pull-down menus are at the top of a dialog. A pull-down menu displays submenus when you hold down the Select mouse button over a menu.

List box

Check box Text box Pop-up menu

Pull-down menu

CM Synergy Learning Guide

Conventions

Menu Paths
When you follow a procedure in an exercise, you will use menu paths to arrive at submenu destinations. For example, to bring up the Use dialog, you will see the following: Project View: foo.c pop-up menu > Use... The first dialog or view name in the menu path is the dialog or view in which you start the operation. Instructions follow the colon. The "greater than" symbol (>) prompts you to the next action.

Graphical User Interface


Figures showing the CM Synergy dialogs were created while running CM Synergy under the Microsoft Windows 95 operating system. If you run CM Synergy under Windows 98/NT, your dialogs may look slightly different. Additionally, the tutorial database is not initialized to use DCM. The DCM options will display, but they will be inactive. You can bring up CM Synergy dialogs in many different ways. Sometimes youll click a button, sometimes youll select an option from a pull-down menu, and other times youll select a file, then use the pop-up menu or the icons in the toolbar. This guide shows you several different ways to bring up dialogs so that you gain a basic level of familiarity to use as a jumping off point in deciding how youd like to bring up dialogs.

Command Line Interface


Telelogic supports the command line interface (CLI) under all Windows platforms. You can run any CM Synergy command from the DOS command prompt. Although this book shows you how to perform operations from the GUI only, the CM Synergy Quick Card gives you the commands.

Prompt
This document uses the > (greater than) character as the prompt.

Option Delimiter
The Windows client supports the slash ( / ) option delimiter.

Standards
Instructions for editing text files are given using Notepad commands. Notepad is the CM Synergy default text editor. If you use a different text editor, substitute the appropriate commands.

CM Synergy Learning Guide

Overview

CM Synergy Learning Guide

CM Synergy Operations

CM Synergy Learning Guide

CM Synergy Operations

Start CM Synergy
Bring up CM Synergy from the Windows Start menu. Before you start a CM Synergy session, youll need to know a few pieces of information. Gathering this information now will enable you to start a session easily and quickly. See your system administrator for answers to any of the following questions. Server Will you run CM Synergy from a UNIX server or from a Windows NT server? Engine Host What is the name of the machine that will run the engine processes? ________________________________________ Server Database Path What is the path to where your tutorial database resides? If youre connecting to a Windows server, check with your change management administrator (CM administrator) for the path. If youre connecting to a UNIX server, its most likely in your home directory. __________________________________________________ If youre connecting to a Windows NT server, you must enter the path by using a universal naming convention (UNC); for example, \\dbserver1\ccmdb\ccm_db. Home Directory Where should CM Synergy write the log file info? Typically, this is C:\temp. __________________________________________________ Client Database Path Where do you want your databases data to be copied on your PC? Enter a path to a temporary directory on a local drive, for example, C:\temp\ccm. __________________________________________________

CM Synergy Learning Guide

Start CM Synergy

Start Your CM Synergy Session 1. Bring up the Startup Info dialog by selecting Telelogic from the Start menu at the bottom of your Windows screen. A Startup Info dialog displays, similar to the one in Figure 1.
CM Synergy

Figure 1. Startup Info Dialog 2. Enter information in the Server Information group box. If youre not sure which server youll connect to, refer to "Server" on page 8. The Server Information group box contains four text boxes. The information in the text boxes relates to the server side of CM Synergy. You might or might not need to fill in the text boxes. Heres how to know if you need to enter information. a. User Name: By default, your user name displays. If you need to add it, be sure to do so in all lowercase letters. If youll connect to a UNIX server, you must enter your UNIX user name here. Connect to the
server

CM Synergy Learning Guide

CM Synergy Operations

b.

Password: Enter your password. If you dont know your password, see your System Administrator. If youll connect to a UNIX server, you must enter your UNIX password here. Engine Host: Fill in the name of the machine where the CM Synergy engine process will run. If you dont remember the machine name, look back at "Engine Host" on page 8.

c.

d.

Connect to the client

3.

Database Path: Fill in the path to where your tutorial database resides. If you dont remember the database path name, look back at "Server Database Path" on page 8. Enter information in the Client Information group box. Home Directory: By default, this box is empty. Enter the path to your home directory. If you dont remember this location, refer to "Home Directory" on page 8. Database Path: This field is optional if youre connecting to a Windows server. By default, this box is blank. If you need to specify a value, enter the path and name of the location on your PC where CM Synergy will copy your database information. If you dont remember this location, refer to "Client Database Path" on page 8.

a.

b.

4.

Start CM Synergy. Startup Info: click Continue The Splash screen displays the release and copyright information while the tool is starting, and a progress bar displays the percentage of the tool that has started. The session is ready to use when the Project View displays. The first time it opens for a new session, itll be empty.

10

CM Synergy Learning Guide

Start CM Synergy

Figure 2 shows the Project View, which you will see upon a successful startup.
This is the project name field. This is the tool bar.

CM Synergy

Figure 2. Project View: Open for the First Time

CM Synergy Learning Guide

11

CM Synergy Operations

How to Use the Project Views Features


The Project View is the main view in CM Synergy. In it, you can view a project and all of the members of the project. Using the Project View is a little like using Windows Explorer in that it gives you a view of files in the database. However, Explorer shows you all files at a directory level, and the Project View shows you all objects that belong to a project. Heres How... You can view any project in the CM Synergy database from the Project View. When you bring a new project into view, youre looking at a new project in the same Project View. The Project View is like a clear glass that you fill with different contents. Later sections describe how to perform specific tasks from the GUI, such as check in a task, or view history. Here youll learn how to use the project browser, Open Project, and how to change your role. Youll need to view a project to perform the exercises in this guide, so first you should be familiar with Open Project, the CM Synergy project browser. The Open Project browser differs from file and directory browsers because it shows you projects that reside in a CM Synergy database only. Other CM Synergy file and directory browsers enable you to view files in your file system. Bring a Project into View in the Project View View a project 1. Find a project that exists in the database so that you can view it in the Project View. Project View: File pull-down menu > Open Project...

12

CM Synergy Learning Guide

How to Use the Project Views Features

An Open Project dialog similar to Figure 3 displays.


Shows a category of projects to list (All Lynns working Projects). Shows all projects in the category (user lynns projects in the working state). Shows information for the highlighted project (sandboxlynn).

Figure 3. Open Project Browser By default, the Open Project browser displays the All Users Working Projects scope. Although you havent checked out a project yet, the Project Name list box shows sandbox and the Project Version field shows your user name. If youre wondering why you own a working project, it was checked out for you automatically for purposes of this tutorial. 2. View all projects in the database. Open Project: click Scope list box > All Projects 3. Choose your version of the sandbox project. Open Project: Project Name list box > click sandbox Open Project: Project Version list box > click username 4. Click Open. The Open Project browser closes and the Project View displays the sandbox-username project. Figure 4 describes how you can use the different areas in the Project View.

CM Synergy Learning Guide

13

CM Synergy Operations

Displays the project name (sandbox) and version (lynn) you are viewing.

Project Stack: Displays project names and versions that you previously viewed.

Database name (lynn_tut)

Default Task: Displays the task that youre working on.

CM Synergy

Open state icon: Shows that the object contains members and is open, displaying its members.

Role: Displays your current role in the CM Synergy database.

Closed state icon: Shows that the object contains members and can be opened, but is now closed.

Type icon: Describes the object type pictorially.

First text column: Displays the name of an object in the CM Synergy database.

Figure 4. Project View: Description of Options

Change roles

Change Your Role in the Project View 1. Change your role from developer to build_mgr. The build_mgr role is used for configuring and building test areas and preparing software for release. Project View: click Role list box > select build_mgr The Role list box changes to display your current role, as shown in Figure 5.

14

CM Synergy Learning Guide

How to Use the Project Views Features

CM Synergy

Your role change displays here.

Figure 5. Project View: Where to View Your Current Role Your new role can only be a role to which you have access in a database. In this tutorial database, you have access to all roles. 2. Change your role back to developer. Project View: click Role list box > select developer

Notes... You can access a working project in your file system by looking at your CM Synergy "work area." A working project is a project that has been checked out from CM Synergy to your work area. Your work area contains the same files that you see listed in the Project View. To see your work area, look for the ccm_wa directory (usually under C:\users\<your username>) in Windows Explorer. CM Synergy work
area

CM Synergy Learning Guide

15

CM Synergy Operations

How to Use Online Help


Help on how to use CM Synergy is available from both the GUI and the CLI. GUI help is available by clicking on the Help button or by using the Help pull-down menu in a dialog or view. CLI help is available by executing a single help command. Heres How... 1. To bring up help for the Project View, click the Help pull-down menu. Note: If Help does not display, your CM Synergy manager may need to install and configure an HTML browser for you.

CM Synergy

Displays the help file for the view or dialog you are using. Displays the Contents page for the CM Synergy Online Help system. Displays the Index page for the CM Synergy Online Help system. Contains information to help you learn how to get CM Synergy up and running right away.

Telelogic on the Web About CM Synergy

Contains in-depth, advanced information on areas within CM Synergy.

Discusses licensing.

Displays three areas in the Telelogic web site you can access directly from CM Synergy: -Telelogic home page -Documentation Web Site -Customer Area See Notes on page 56 for more information about these three areas.

Figure 6. Getting Help in the Project View

16

CM Synergy Learning Guide

How to Use Online Help

2.

Read the help file for a dialog or view. In all dialogs and views with a Help pull-down, youll see several options, similar to those displayed in Figure 6. The first option is the one you want to choose to obtain help for the view or dialog you are using, for example: Project View: Help pull-down menu > Project View In dialogs that have a Help button, click the button to bring up the help file.

3.

Minimize your browser so that you can continue with this tutorial.

Notes... The Telelogic home page displays the home page on the Telelogic web site. The Documentation web site displays the home page on the Telelogic Documentation web site. This site resides under the Telelogic web sites Customers Only area. You will need a user name and password to access this site. The Customer Area displays the user name and password prompt. You must fill in this information to access the Customers Only area.

CM Synergy Learning Guide

17

CM Synergy Operations

View File Properties


The properties of a file (object) describe its characteristics. When you view the properties, youll see the name of the object, the owner, the status, the type of the object, creation and modification dates and times. Also, and equally important, youll see the comment entered by the last developer who worked on the object. If the object has a long history, you can read the comment for each object by bringing up a Properties dialog for each object version or by using the ccm properties command for each object version. This gives you a historical perspective regarding changes made to the object. Heres How... 1. Be sure youre viewing your sandbox project in the Project View. If youre not, either use the Open Project browser to find and display the project or type in sandbox-username in the Project Name field, then press Enter, to bring the project into view. (Be sure to substitute your user name for username.) 2.
1. In the Project View, place the cursor over an object. 2. Press the right mouse button to view a choice of operations (left-handed mouse users need to use the appropriate mouse button). 3. Select the correct feature for the operation you need to perform.

How To
Use a Pop-Up Menu...

Open the src directory by double-clicking on it. View the properties of ident.c-1. Project View: ident.c-1 pop-up menu > Properties If youre not sure how to bring up the pop-up menu, see the sidebar description.

3.

18

CM Synergy Learning Guide

View File Properties

A Properties dialog, similar to the one in Figure 7, displays.

Look here to find out why an object was changed.

Figure 7. Properties Dialog for an Object (File) Notice the Comment field. Here you can read why the object was checked out. You also know several things about the object by looking in this dialog, such as its status, owner, create time, the task number with which its associated, etc. 4. Close the Properties dialog. Properties: click Cancel Note: A property listed as <void> indicates that it is not yet defined for this object.

Notes... Besides viewing the properties belonging to objects, youll also want to view the properties for the project. Most developers use the Properties dialog to read about changes made to an object. When you want to know why the code changed, this dialog is handy. Read about changes
to an object

CM Synergy Learning Guide

19

CM Synergy Operations

You can view the properties of any number of objects at one time, because you can bring up as many Properties dialogs as you need and keep them open simultaneously. However, each Properties dialog can display the properties for a single object only. You can also read the entire history of changes made to an object by bringing up the History View, or by using the Show History Detail command. Youll do this next, in "View the History of an Object" on page 21.

20

CM Synergy Learning Guide

View the History of an Object

View the History of an Object


The history of an object shows you many things about an object, directory, or project. Most users look at an objects history to see if they are checking out from the most recent version of the object. Other users view the history to quickly look at the properties of several versions of an object, such as the Comment property to find what changes were made and why. You can also compare or merge the source of different object versions in the History View.

Heres How... You can view the history of any object in a CM Synergy database, whether or not you own the object. In this task, youll view the history of an object that you dont own, bufcolor.c-1. 1. Bring up the History View. Project View: bufcolor.c-1 pop-up menu > Show History The History View opens to reveal the change history of the object, which will look similar to the one in Figure 8.
CM Synergy

Figure 8. History of bufcolor.c 2. Read the comments for the history of bufcolor.c by bringing up a history detail list in Notepad. History View: bufcolor.c-3 pop-up menu > Show History Detail

CM Synergy Learning Guide

21

CM Synergy Operations

Find the state of an


object

Notice the Owner and State properties. If you were checking out or in a parallel version, this would be important information for you to consider. Who else had a version checked out? In what state is the object version? This information can help you decide whether or not you really need to check out a version of the object or if you will need to merge parallel versions. 3. 4. Close the history detail list. Close the History View. History View: File pull-down menu > Close

Find if parallel
versions exist for an object

Notes... View the history of


others objects

Youve viewed a history of the bufcolor.c object. The history detail list showed who created each version, when it was created, and why. Also, now you know that you can view the history of objects that you own as well as those that belong to others.

22

CM Synergy Learning Guide

Change Your Personal Environment

Change Your Personal Environment


Your ccm.ini file contains options that influence how your interface looks, the role in which it starts, the text editor it uses, and much more. When you set options in this file, they are set permanently (i.e., until you set them again). Note that if you manually change or set an option in your ccm.ini file, youll need to restart your CM Synergy session before you can use the option or gain the benefits of it. If you use the ccm set command to change an option, you can use the new setting immediately, but only for the current session. Note: Do not edit your ccm.ini file while you have a CM Synergy session running. If you do, the updates you make to the file will be overwritten when you exit your session. This is because CM Synergy always writes your current settings to your ccm.ini file before the session ends. Your ccm.ini file is typically in your Windows directory. If youre unable to find the file, talk with your CM administrator. Note: Changing your personal environment is optional. You dont need to change it to run CM Synergy. For a complete list of all options and suggestions for how to set the options, double-click CM Synergy Helps Default Settings section in the Contents page.

Change Object Colors in the Views


You can change the color in which an object displays in the Project and History Views to a wide range of colors. Using the colors can be fun! Most importantly though, colors can help you to ascertain how much work youll need to do after you update your project, and approximately what kind of shape your teams project is in (rapidly evolving, nearing completion, etc.). You dont need to have a project in focus in the Project View to change the colors, but it helps so that you can see how the colors youve chosen look. From the GUI 1. From the Project View, bring up the Object Color Options dialog. Project View: View pull-down menu > Color...

CM Synergy Learning Guide

23

CM Synergy Operations

The Object Color Options dialog displays, and initially its empty. The one shown in Figure 9 displays differently because the Object Color Scheme list box was changed from None (the default) to Attribute Driven Colors.
Set this option to "Attribute Driven Colors."

Keep this set to status.

Click Attribute_Value to bring up the table where you can change object colors based on their status.

Figure 9. Object Color Options Dialog 2. Change the object color scheme to match the object state. Object Color Options: Object Color Scheme list box > Attribute driven colors 3. 4. By default, the attribute that will drive the colors is set to status. Keep the default. Edit the Attribute Value Table. Object Color Options: Attribute driven colors text box > click first entry, Attribute_Value

24

CM Synergy Learning Guide

Change Your Personal Environment

The Attribute Value Table displays, as shown in Figure 10.


Select from a list of states here to change the state to "checkpoint." Select from a list of colors to change the background color. Select from a list of colors to change the foreground color.

Figure 10. Attribute Value Table 5. Set states to be represented by specific colors. a. Set the value. Attribute Value Table: Attribute Value list box > checkpoint b. Map the checkpoint state background color. Attribute Value Table: Background list box > Yellow c. Map the checkpoint state foreground color. Attribute Value Table: Foreground list box > Black d. Update the Attribute Value Table. Attribute Value Table: click Update The Attribute Value Table is updated. If you want to go with a "hot" colors (for objects that are being modified) to "cool" colors (for non-modifiable objects) look in the Project View, set the remaining states to the following colors by performing step a through step d for each state below: working state: background "Red," foreground "White" checkpoint state: background "Rust," foreground "White" integrate state: background "Yellow," foreground "Black" released state: background: "LightBlue," foreground: "Black"

CM Synergy Learning Guide

25

CM Synergy Operations

See "Notes" on page 27 for additional Project View and History View color suggestions. 6. Close the Attribute Value Table dialog. Attribute Value Table: click Close 7. Apply the changes. Object Color Options: click Apply Take a look. If you like the changes, keep them by saving the changes; otherwise, change them until youre happy with them, then apply your changes and save. The Apply button applies the changes you made in the Attribute Value Table to the Project View and History View. The Save button saves the changes you made to your ccm.ini file so they can be used the next time you start a CM Synergy session. Object Color Options: click Save 8. Close the Object Color Options dialog. Object Color Options: click Close 9. View an integrate state object in the History View. a. b. In the Project View, double-click the src directory, if you need to open it. Bring up the History View to view the colors you set for an integrate state object. Project View: bufcolor.c object pop-up menu > Show History Notice that the colors you set for object states in the Object Color Options dialog display in your Project View and in your History View. 10. Close out of the History View. History View: File pull-down menu > Close

26

CM Synergy Learning Guide

Change Your Personal Environment

Notes... The following is another color scheme that you can use. Choose a special color for working-state objects (usually your favorite color) and another color for objects in the other states. When you perform a reconfigure, you can see which objects stayed in the working state. These are the objects that you own and that you can change. Do this by setting states to the following colors (perform step 5 for each state below, then perform step 7). working state: background "Purple," foreground "White" checkpoint state: background "LightBlue," foreground "Black" integrate state: background "LightBlue," foreground "Black" released state: background: "LightBlue," foreground: "Black"

CM Synergy Learning Guide

27

CM Synergy Operations

Navigate through CM Synergy Using Icons


The Project View and the History View each have a toolbar of icons that open the dialogs youll use the most. Each icon has a tooltip that appears when you move the cursor over the icon. If you havent used the icons before, try the exercise on page 30. If youre working exclusively from the CLI, you can skip this section and proceed to the next exercise, "Check Out a Project" on page 31. The Project View toolbar looks like this:

Heres what each icon in the Project View toolbar does: Open Project Icon Click this icon to bring up the Open Project dialog. This dialog is described in "Bring a Project into View in the Project View" on page 12. Check Out Icon Select the object you want to check out, then click this icon to bring up the Check Out dialog. This dialog is described in "Check Out an Object" on page 47. Check In Icon Select the object you want to check in, then click this icon to bring up the Check In dialog. This dialog is described in "Check In the Default Task" on page 83. Create Icon Click this icon to bring up the Create dialog. This dialog is described in "Create a New Object" on page 65. Properties Icon Click this icon to bring up the Properties dialog. This dialog is described in "Modify Properties" on page 52. Show History Icon Click this icon to bring up the Show History dialog. This dialog is described in "View the History of an Object" on page 21.

28

CM Synergy Learning Guide

Navigate through CM Synergy Using Icons

Reconfigure Icon Click this icon to bring up the Reconfigure dialog. This dialog is described in "Update Your Project With the Latest Changes" on page 34. Reconcile Icon Click this icon to bring up the Reconcile dialog. This dialog is described in "Reconnect to the CM Synergy Database" on page 60. Query Icon Click this icon to bring up the Query dialog. This dialog is described in "Search the CM Synergy Database for an Object" on page 68. Migrate Icon Click this icon to bring up the Migrate dialog. "Migrate an Existing Project from Your File System into CM Synergy" on page 93. The History View toolbar looks like this:

Heres what each icon in the History View toolbar does: Version Compare Icon Select the two objects you want to compare, then click this icon to compare all attributes of the objects. Compare Icon Select the two objects you want to compare, then click this icon to compare the source differences. Merge Icon Select the two objects you want to merge, then click this icon to bring up the Merge dialog. This dialog is described in "Merge Two Objects" on page 86.

CM Synergy Learning Guide

29

CM Synergy Operations

Add Link Icon Select the two objects you want to link, then click this icon to add a predecessor/successor relationship between them. Be sure to select the objects in the correct order. Del Link Icon Select two objects, then click this icon to remove a predecessor/ successor relationship from the two objects. Properties Icon Click this icon to bring up the Properties dialog. This dialog is described in "Modify Properties" on page 52. Query Icon Click this icon to bring up the Query dialog. This dialog is described in "Search the CM Synergy Database for an Object" on page 68. Heres How... 1. 2. Look in the Project View. Find the toolbar. Its located in the uppercenter part of the Project View. Place the cursor over the first icon, the Open Project icon. Its yellow and looks like a file folder opening towards you. Notice the little balloon with text in it that displays. It reads, "Open Project...." This is the name of both the icon and of the dialog it will bring up when you click the icon. All CM Synergy icons have tooltips. The tooltips make icon usage much easier; you dont have to memorize each icon and what it does! 3. 4. 5. 6. Place the cursor over a few more icons to become familiar with their location on the Project View toolbar. Find the Show History icon and click it to bring up the History View. Place the cursor over the icons to become familiar with the History View icons. Close out of the History View. History View: File pull-down menu > Close

30

CM Synergy Learning Guide

Check Out a Project

Check Out a Project


The CM Synergy work area is a directory that contains your checked-out projects. For example, right now your work area contains your checkedout sandbox project, which youve been using to view properties and histories of objects. Every CM Synergy user has a work area. The purpose of checking out a project is to keep your work insulated from changes made by other developers, yet not isolated. To see how this works, youll check out the toolkit-1.0 project, which is a released project. This project and its subprojects form a baseline for your work. Heres How... 1. Open the Open Project browser to bring the toolkit-1.0 project into view in the Project View. Refer to page 12 or see the sidebar for instructions on how to use the Open Project browser. 2. From the Project View, bring up the Check Out Project dialog. Project View: click toolkit-1.0 > Actions pull-down menu > Check Out...
Remember
To open a project... 1. In the Project View, bring up the Open Project browser. Project View: click File pull-down > Open Project 2. Change the Scope list to All Projects. 3. Click the toolkit project. 4. Click the 1.0 version. 5. Click Open.

CM Synergy Learning Guide

31

CM Synergy Operations

A Check Out Project dialog displays, similar to the one in Figure 11.
This shows the project that youre checking out from.

This lists the project with its subprojects and their versions.

Figure 11. Check Out Project Dialog: Default Settings Using the Check Out Project dialog, youll check out a new version of the toolkit-1.0 project and its subprojects. Notice that, by default, the Also Check Out Subprojects option is ON. Youll make changes to all of these projects to complete a task. 3. Change the release to reflect the new projects release number, 2.0. Check Out Project: click Release list box > 2.0 4. Check out from the baseline. Check Out Project: click OK The Check Out Project Status dialog displays and updates you on the progress of the check out. When CM Synergy finishes writing the toolkit project out to your work area, the Check Out Project Status dialog and the Check Out Project dialog close. Notice that the Project View displays your newly checked out project and the checked-out subprojects, too. The project name and version in the Project box will read toolkit-username. Your user name is the default version when a user in the developer role checks out a project.

32

CM Synergy Learning Guide

Check Out a Project

The project and all subprojects are checked out in the working state and owned by you. The remainder of the members are in the released state and owned by user jwark.

Notes... Usually, youll create a working-state project for a particular software application youre working on, and you can keep using that same working-state project for all subsequent changes. This is because checking in the project is unnecessary. You only need to check in the projects members. Perhaps youre wondering how you get newer versions of objects that other members of your team might be working on and checking in: good question! CM Synergy has an operation that enables you to update your project easily and quickly, and well talk about that more in "Update Your Project With the Latest Changes" on page 34. Working-state
projects

CM Synergy Learning Guide

33

CM Synergy Operations

Update Your Project With the Latest Changes


When you update your work area, you bring changes made by other developers into your project. The CM Synergy configuration update process is called "reconfigure." The reconfigure operation enables you to use or share the most recent versions of objects on demand. Your work area remains insulated from other users changes until you decide youre ready for the changes and reconfigure your project. For the purposes of this tutorial, your projects reconfigure properties were defined to automatically determine which objects will be selected when you reconfigure. See "Notes" on page 37 to learn more about the reconfigure properties that CM Synergy uses to update your project. Heres How... 1. Bring up the Reconfigure dialog from the toolkit-username project. Project View: toolkit-username pop-up menu > Reconfigure... A Reconfigure dialog displays, similar to the one in Figure 12.

Figure 12. Reconfigure Dialog 2. Update the


subprojects

Be sure to turn ON the Recurse Into Subprojects option. Reconfigure: Recurse Into Subprojects option > ON This option tells CM Synergy that you want the subprojects to be reconfigured too. The subprojects in toolkit are calculator, editor, and guilib.

3.

Be sure to turn ON the Show Messages option. Reconfigure: click Show Messages option > ON

34

CM Synergy Learning Guide

Update Your Project With the Latest Changes

This option causes the Message View to display, then prints a synopsis of the reconfigures progress in it. If you want to view detailed progress output about the reconfigure, you could turn ON the Verbose option, too, but you dont need to for this exercise. 4. Reconfigure your project to bring in the most recent versions of objects that have been tested by the build manager. Reconfigure: click Reconfigure Youll see some new objects reconfigured into your project. This is because your projects reconfigure properties were defined to select the new objects when you reconfigured. See "Notes" on page 37 to learn about reconfigure properties. While the reconfigure operation is in progress, the Reconfigure button changes to Stop so you can stop the operation if necessary. Note that if updates occur before you stop the reconfigure, the new versions will remain in your project. The Message View in Figure 13 shows where the reconfigure operation updated your project.
CM Synergy starts the reconfigure with the top-level project. Then moves on to the subprojects.
CM Synergy

When CM Synergy finishes reconfiguring each project, it gives a tally of the objects it replaced.

Figure 13. Message View: Output Showing Where Reconfigure Updated Object Versions

CM Synergy Learning Guide

35

CM Synergy Operations

5.

Close the Message View. Message View: File pull-down menu > Close Before you close out of the Reconfigure dialog, take a look at the reconfigure properties defined for your project. Reconfigure: click Details A Reconfigure Properties - Tasks dialog displays, similar to the one in Figure 14.

6.

7 8

Figure 14. Reconfigure Properties - Tasks This dialog shows the reconfigure properties CM Synergy uses to update your project: the baseline, tasks, and folders for the project. In this dialog, you can change the reconfigure properties by adding or removing a folder and task, and by selecting a new baseline. Typically, you wont need to change them because the build manager does it for you. See "Notes" on page 37 for more information. 7. Close the Reconfigure Properties - Tasks dialog. Reconfigure Properties - Tasks: click Cancel 8. Close the Reconfigure dialog. (Notice that the Cancel button changed to Close.) Reconfigure: click Close

36

CM Synergy Learning Guide

Update Your Project With the Latest Changes

Notes... Now you have completed the second of two steps that ensure your project is up-to-date. Whenever you start a new project, youll always do the following two steps: 1. 2. Create your work area by checking out a project Update your project with the latest changes

How the Build Manager Defines the Update The reconfigure operation replaces objects in your project with those that are most recent. It uses your projects reconfigure properties to select object versions. Luckily, you dont need to know everything about reconfigure properties. They are defined for your project automatically, based on reconfigure templates that the build manager sets up. See "Reconfigure Templates" on page 40 for more information. First though, lets learn some more about reconfigure properties. If you were to look at the reconfigure properties for your project, you would see that the properties define a baseline and a list of tasks and folders. The baseline is a different version of your project, usually the last released version. Its called a baseline because your projects members are based on that projects members, plus the objects from the list of tasks and folders. What is a Folder? A folder is a named grouping of tasks. (A task groups all of the objects needed to modify or fix a problem or make an enhancement.) A common grouping of tasks will be called something like Lynns Assigned or Completed Tasks for Release 2.0, which would gather tasks for a major release. In this example, the folder groups all of the tasks that were assigned to or completed by user lynn for release 2.0. Another common folder will have a name like All Completed Tasks for Release 2.0. In this example, the folder groups all of the tasks that were checked in to the completed state and that are ready for the build manager to build into either a product release or a patch. A folder can use a query to select the tasks it will group. This is convenient because it finds the tasks automatically, rather than having someone add and remove tasks manually.

CM Synergy Learning Guide

37

CM Synergy Operations

"Brain" of Task-Based CM The reconfigure properties creates the final link among the pieces of your work by telling your project which tasks to include and which object versions these tasks include. Reconfigure properties controls the tasks and all of their associated objects that are brought into your project configuration. Because of this control, the reconfigure properties are considered the "brain" of taskbased CM. The big picture looks like the one on the next page....

38

CM Synergy Learning Guide

Update Your Project With the Latest Changes

toolkit-1.0

1. This is the baseline project. When you reconfigure your working project, reconfigure builds a list of the baseline project members first. This is your working project. The baseline and folders are properties of your working project.

toolkit-lynn

Object task 4 folder Object task 4 task 7 task 11

task 7

Object

2. Each folder contains a list of tasks. Reconfigure goes through the folders to get the list of tasks.

Object

task 11

Object

Object 3. Each task contains a list of objects. Reconfigure goes through each of the tasks to get the list of objects. It adds to the list of objects from the baseline.

4. The objects contain attributes. Reconfigure compares the objects attributes with the projects, then selects the best match.

CM Synergy Learning Guide

39

CM Synergy Operations

Reconfigure Templates You don't need to know how to set up your reconfigure properties unless you want to. The build manager creates templates to define how your project's reconfigure properties will be set up for each release. A projects release and purpose are used to identify the reconfigure template that the project will use. Typically, a developer's project will be based on the last released version of the project, and will contain three task folders: user's Assigned or Completed Tasks for Release X This folder collects all of user's assigned and completed tasks, so that those objects will be included in the developers project. Miscellaneous Tasks for user for Release X This folder is usually empty. You can add tasks to this folder if you want to include their associated objects in your projects. For example, if you are working closely with another developer, you may want to include his task in your project even before it is tested; you could add his task to this folder, and then reconfigure. Integration Tested Tasks for Release X This folder contains all tasks that have passed integration testing. The build manager updates this folder after successful integration testing so that developers can use each others latest changes. Your projects reconfigure properties can vary, depending on how your build manager sets up the reconfigure templates for your site.

40

CM Synergy Learning Guide

Set the Default Task

Set the Default Task


The default task tells CM Synergy which fix or enhancement you will work on. After you set it, CM Synergy will associate every object that you create or check out with the default task. Additionally, once you set the default task, its set for the entire CM Synergy session, not just the project youre currently looking at in the Project View. You can change the project as many times as youd like, but if you look at the Default Task list box, youll notice that the default task remains the same until you change it. You can also change the default task as many times as youd like per session, but each time you change it, it applies to the entire session. Note: Telelogic recommends that you work on one task at a time, whenever possible. If you work on more than one task at a time, youll have to remember to change the default task to correspond to the object youre checking out. If you forget to change the default task and check out an object (or several objects) with the wrong default task set, youll have to disassociate all of the incorrectly-associated objects, then associate them with the correct task. Forgetting to change the default task is very easy to do! This is why Telelogic recommends that you work on only one task at a time. Heres How... 1. Set the default task to a task assigned to you. In the Project View, click Select Task. Project View: click Select Task

CM Synergy Learning Guide

41

CM Synergy Operations

A Select Task dialog displays, similar to the one in Figure 15.


If you have a large number of tasks, you might want to sort by priority.

These are the tasks assigned to you. The task number displays first, followed by the task synopsis.

Figure 15. Select Task Dialog You might be thinking: Wait! Where did all of these tasks come from? Not to worry...this is a populated tutorial database. When the CM administrator ran the tutorial setup script, it populated the database with tasks for you to fix. In your production database, you will probably have tasks assigned to you by a project leader, quality assurance developer, or build manager. Task assignment
notifications through e-mail

You may have noticed task assignment notifications in your e-mail. CM Synergy sends a mail notification whenever someone assigns a task to you. For the tutorial, the setup script assigned all of these tasks to you and prompted the sending of the notifications. When you open a task assignment notification, it will read like this:
Task Assignment Notification ____________________________________________________ You have been assigned Task 33 by ccm_root in database /users/lynn/ccm_nt/db. PRIORITY: Medium SYNOPSIS: Fix scrolling problem in guilib

2.

Select the task that you will work on. Select Task: click 30: Go through the tutorial exercises

3.

Apply your choice. Select Task: click OK

42

CM Synergy Learning Guide

Set the Default Task

Notice that the Project View displays the default task in the Default Task list box, as shown in Figure 16.
The default task displays here.
CM Synergy

Figure 16. Project View Displaying a Default Task

CM Synergy Learning Guide

43

CM Synergy Operations

Notes... Daily work process Later in this guide, youll check in the default task. Default task check in occurs after you have finished all code changes needed to complete the task. Think of checking in the default task as part of your normal daily work process: Select the task youll work on. Set this task to be the default task. Make all code changes. Check in the default task.

Sometimes a task will take longer to complete than a day. This is fine! When you finish the task, use the items listed above to complete the next task. In the following exercises, youll complete several operations that wont necessarily need a completed task. Remember, the objective of this tutorial is to introduce you to the operations youre likely to use most often. Last, if you exit from the tutorial database, note that the sandbox project will be checked out again when you restart. This is because a script performs the check out whenever the tutorial database is started.

44

CM Synergy Learning Guide

Use an Object

Use an Object
When you "use" an object, you bring into your project a different version of an object that is already there. Most developers work with the use operation during unit testing, when they want to go back to a previous version of an object in their project. If you try to use an object in a project thats not writable by you, youll receive a warning message stating that you dont have write privilege to the project, and the use operation will fail. Youll need to check out the project. Heres How... 1. 2. 3. Be sure youre in your toolkit project. Double-click the misc directory to open it. Bring up the Use dialog for the readme object. Project View: readme pop-up menu > Use... The Use dialog displays as shown in Figure 17.

This is the name of the project in which the object you select will be used. This is the name of the directory in which the newly-used object will reside.

Figure 17. Use Dialog Look at the object versions that are available for your use. They include versions of readme that have been created in this particular project. But the Use dialog shows all readme object versions of the same instance only. (For a description of what an "instance" is, see "Notes" on page 46.)

CM Synergy Learning Guide

45

CM Synergy Operations

Notice the Recommend button at the bottom of the dialog. Clicking this button causes CM Synergy to recommend which object version to use. (The projects reconfigure properties determine the recommended version.) Also, notice the kind of information you receive about the object versions available for you to use. By default, the object name and version (%displayname), state (%status), owner (%owner), and task (%task) display in the Select Object to Use field. 4. Use version 1. Use: click readme-1 > click Use This version will bring in an object that will enable you to create a parallel object when you check it out in the next operation. This sets up a later merge exercise. The Use dialog closes when the operation is complete.

Notes... Whats an instance? An instance is an attribute that is automatically associated with objects, when the objects are created in the CM Synergy database. It distinguishes between multiple objects with the same name and type, but that are not versions of each other. Well talk about instances again in an upcoming exercise, after you have gained more experience with CM Synergy.

46

CM Synergy Learning Guide

Check Out an Object

Check Out an Object


Checking out an object with CM Synergy is similar to checking out an object using other source control systems. The object you check out receives a new version, and that version is unique. While youre working within a checked out file, no one else can make changes to your copy of the object. You must check out the project before checking out an object that is a member in that project. When you check out an object, the following happens: You check out a new version of the object from the existing version. In doing so, you copy all of that objects properties as well. CM Synergy automatically associates the checked-out object with the default task you set in your Project View. CM Synergy automatically updates your work area with the new file. CM Synergy automatically sets the state of the newly checked-out object to working. CM Synergy makes you the owner of the new object version. Only you can make changes to this object version. A working state object version is modifiable by the owner only.

In this operation, the object you check out will have a parallel version. (For a description of what a "parallel version" is, see "Notes" on page 50.) Whether or not youre checking out a parallel object version, the check out procedure is the same. Youll see messages during your parallel object version check out, but the messages are informational only. Also, if youre wondering about how to check out project, directory, and makefile objects, the "Notes" section on page 51 describes this. Heres How... 1. 2. In your toolkit project, double-click the misc directory if you need to open it. Check out the readme-1 object. Besides the obvious reason of checking out this object to learn how to perform this action, youre also setting up a later exercise that will show you how to merge parallel object versions. a. Bring up the Check Out dialog. Project View: readme pop-up menu > Check Out...

CM Synergy Learning Guide

47

CM Synergy Operations

The Check Out dialog displays. Figure 18 shows what it looks like.
This is the directory in which youll check out the object. A non-whole version number is your first clue that youre probably checking out a parallel version.

Add your comments here.

This shows the task you set as the default in your Project View.

Figure 18. Check Out Dialog b. Fill in comments Fill in the Comments field with the following comment: Add updates for release 2.0. From a historical perspective, this is a good habit to get into. Next time you or another developer checks out this file, you or he can read why the object was checked out last time and what you intended to do with it. c. Check out the object. Check Out: click OK

48

CM Synergy Learning Guide

Check Out an Object

Youll receive a Parallel Versions on Check Out warning message, which looks similar to the one in Figure 19.

This is the first version that was checked out from readme-1. By checking out another version from readme-1, youll create a parallel version.

Figure 19. Parallel Versions on Check Out Dialog If youre not sure what parallel versions are, the "Notes" section on page 50 discusses them further. d. Click Continue. The Check Out dialog closes when the operation is complete. 3. Look in the Project View. Notice that readmes version has changed to 1.1.1 and the status is working. Also, now you own it. If you bring up the Properties dialog, youll see that the task you set as the default task, task 30, was associated with the readme object version you just checked out. This occurred automatically because task 30 is the default task. 4. Bring up the History View for the readme object. If youve forgotten how, refer to "View the History of an Object" on page 21 or see the CM Synergy Quick Card.

CM Synergy Learning Guide

49

CM Synergy Operations

The History View in Figure 20 shows what a parallel version looks like.
CM Synergy

Figure 20. History View: Showing Parallel Versions 5. Close the History View. History View: File pull-down menu > Close

Notes... Parallel version


notification

When you checked out the object during this exercise, you saw a message stating that it had a parallel version. This means that you checked out a version from the same version that another developer used to check out his version. For example, lets say that developer jwark created an object version called readme, which would make him the owner of readme-1. Someone else checked out from readme-1, which created readme-2. Then you came along and checked out an object version from readme-1. You ended up with readme-1.1.1. This is exactly what happened and intentionally so. This tutorial database was populated with objects, and the object from which you checked out your version was the same object from which a developer at Telelogic had checked out her version. When you check out an object, many times youll check out a parallel version. But dont worry. You can merge the changes later, if youre the last one to check in the parallel object version. (More on this later in "Merge Two Objects" on page 86.)

50

CM Synergy Learning Guide

Check Out an Object

The parallel version notification is just a reminder that a parallel version of the object exists. It doesnt mean that you shouldnt check out another version. But it does disclose important information that you should seriously consider: who owns the other version. This feature can save you work. When you see the notification, you might choose to cancel the check out so that you can check out a more recent version or talk to the other developer about the change hes making. You might not need to make your change after all, or you might not need to create a parallel version. How To Know When to Check Out By now, youre probably wondering how youll know when to check out an object. You might also be wondering when to check out the other kinds of objects, projects and directories. Take a look at the following list to understand this better: When should you check out a project? Only check out a project to create a working environment for yourself when working on something new. When should you check out a directory? Never check out a directory. CM Synergy checks out the directory for you when you need to add or delete an object from the directory. When should you check out an object? Only check out an object when you need to change the contents or properties of the object. When to check out
an object

CM Synergy Learning Guide

51

CM Synergy Operations

Modify Properties
You can modify the properties of an object as long as youve checked out the object. Some reasons why youd want to modify an objects properties include: You neglected to fill in a comment and now want to. You want to change the objects version. You checked out the object, and it inherited a Release value that isnt right for the project youre working on now. You want to associate an object with the task that it fixes.

Heres How... Modify the properties of toolkit.ini by doing the following: add a comment and change the objects version. 1. In the misc directory, check out the object youre about to modify, toolkit.ini. Also check the Default Task field in the Project View to ensure that the task youre working on is set as the default. You must own a working state version of the object whose properties you want to modify. To check out an object, use the CM Synergy Quick Card instructions or refer to "Check Out an Object" on page 47. 2. Open the Properties dialog for toolkit.ini. Project View: toolkit.ini pop-up menu > Properties... The Properties dialog displays. 3. Change an object
version

Add a sentence to the objects comment. Properties: Comment text box > Need to add new options. Change the objects version from a number to a descriptive name. Note that versions can be alphanumeric. Properties: Version text box > mine

4.

52

CM Synergy Learning Guide

Modify Properties

Your Properties dialog will look similar to Figure 21.

Figure 21. Properties Dialog after Modifications 5. Apply your changes. Properties: click OK

CM Synergy Learning Guide

53

CM Synergy Operations

Make Changes to Your Source Code


At this point, in a production database, youd start checking out objects to make fixes or enhancements to code. Youd be working towards completing a task assigned to you. Sometimes youll assign tasks to yourself, other times the build manager or a project leader will assign a task to you, and sometimes youll already be fixing a bug and need to associate the object youre modifying with a task. All of these scenarios are acceptable ways of assigning a task. FYI... To edit an object from the GUI, double-click the object.

Build Your Product


During this phase of development, youd edit, compile, and debug your work. CM Synergy enables you to work in an insulated work area, which means you dont get other developers newly checked-in changes until youre ready for them. This makes it easy to isolate and fix problems in your code because you have control over when changes go into your work area. How Do You Want to Build Your Product? You have three choices: build with CM Synergys build tool, ObjectMake, or with one of the following: a third-party build tool, such as make an integrated development environment, such as PowerBuilder

Telelogic realizes that many other build tools exist, and your company might use one of them instead of the tools discussed here. If this is the case, youll want to read about building a product using a third-party make tool, which is discussed in the ObjectMake Guide. The instructions include how to control products built outside of CM Synergy. How to Build Products Whether your site builds products with ObjectMake, a third-party make tool, or both, each way is discussed in detail in the ObjectMake Guide.

54

CM Synergy Learning Guide

Make Changes to Your Source Code

Notes... When you build products in your work area using ObjectMake, the products are controlled by CM Synergy without any further work on your part. And since your work area is insulated against others changes until you request to incorporate those changes, you can continue with your edit, compile, debug cycle until youre confident enough of the integrity of your files to check them in so the build manager can build them. You can check in a product to the checkpoint state. This is a nonmodifiable state which enables you to keep a personal version of the product. Next time you build, ObjectMake will check out a new version of the product automatically so that the linker or compiler will have a working version in which to place additional changes. The checkpoint version will exist in case you need it. Later, you might choose to "collapse" the checkpoint version, which would remove it from the database permanently. The checkpoint and collapse operations enable you to temporarily save object versions without cluttering the database with lots of personal versions. FYI... For more info on the checkpoint and collapse operations, see the CM Synergy Online Help. If You Build Using a Third-Party Make Tool The files in your work area are stamped with the last time the file was modified. Because ObjectMake is integrated with CM Synergy, if you use an older version of a file, ObjectMake knows that the file has changed and needs to be rebuilt. However, if you use a third party make tool, the older file will not be rebuilt because its timestamp will be older than the file it replaced and older than the product. To ensure that your third-party make tool rebuilds replaced files, you should turn on the Use New Timestamps option in the Copy Options of your Work Area Properties. Then any time a file is replaced in your work area, its timestamp will be set to the current time rather than the files modification time, and this will cause the product to rebuild. Building products
using ObjectMake

Checkpoint-state
products

Collapse operation

CM Synergy Learning Guide

55

CM Synergy Operations

Work Disconnected From the CM Synergy Database


Working disconnected means that you can workedit, debug, compile, and add objects to a projectoutside of a CM Synergy session. Note: To edit or add a file while working disconnected from CM Synergy, the project in which the corresponding database object is a member must be checked out. Youll complete the following tasks from within your file system work area, using the text editor of your choice. You dont need to log out of CM Synergy to complete these exercises. Youll be prompted to minimize the Project View.
How To
Find a work area path... 1. Open the Work Area Properties dialog. Project View: project pop-up menu > click Work Area Properties 2. The Directory box in the Work Area Path group box shows the path to your work area.

Edit Files Offline


In this operation, youll edit two files in your work area as if you were working at home, or at work but unable to run CM Synergy. One of the files youll edit will be checked out, which makes it writable. The other file will not be checked out, and will need its read-only permission removed so that it can be edited. The corresponding database object for the checked out object will be in the working state. The corresponding database object for the object that is not checked out will be in the released state. Heres How... 1. 2. Be sure that youre in the calculator project. Check out one of the files youre going to update, clear.c, which resides in the sources directory. After checking out, notice in the Project View that clear.c is checked out and main.c is not checked out. Locate your work area path. Use the sidebar instructions. Your work area path: _________________________________ 4. If youre working in the CM Synergy GUI, close out of all CM Synergy dialogs that are open, except the Project View. Minimize the Project View. When you work outside of CM Synergy, you wont have a session up. You could close out of your session now, but then youd just have to start it up again, so thats why youre minimizing it.

3.

56

CM Synergy Learning Guide

Work Disconnected From the CM Synergy Database

5.

From Windows Explorer, change directories to the calculator-username\calculator\sources subdirectory under your work area path, where the files to be edited reside. For the work area path, refer back to step 3 of this exercise. Use the text editor of your choice to edit clear.c, then save and exit out of it. Turn off the read-only attribute on main.c. Because you did not check out main.c, it is unwritable. For instructions on how to turn off the read-only attribute, see the Windows Explorer online help. Turn off the readonly attribute

6. 7.

8.

Once youve turned off the read-only attribute for main.c, go ahead and edit the file, save and exit out of it.

To Add a File
Now youre on the road, and need to add the file test.c to the calculator project in your work area. Your work area is on your laptop.

CM Synergy Learning Guide

57

CM Synergy Operations

Heres How... 1. From within the Explorer, create the new test.c file by copying an existing file. a. b. Copy main.c, then call it test.c. Open test.c and add the following line at the top of the file:
/* This is a test of the emergency broadcast system. */

c.

Save and exit from test.c. This file exists in your work area, but until you create it in the CM Synergy database, it doesnt exist in CM Synergy. In "Reconnect to the CM Synergy Database" youll create this object.

2.

Read the "Notes" section below to understand the state of the database files and directories versus the state of the file system files and directories.

Notes... Presently, all of your changes exist in your work area only. They arent in the database yet. CM Synergy has no idea that youve changed your work area. The first thing to do in letting the database know that you made changes to the work area is to reconcile. Changes are in the
work area only

One important point to remember is that all changes you make to files in the work area must be made to the corresponding database objects. In other words, the work area files you changed are not additional versions of database objects. When you reconnect to CM Synergy, youll need to ensure that the work area files and database objects match. The work area files must be saved in the database, either by updating the database objects with the work area files or by creating new objects in the database from the new work area files. CM Synergy has a quick way for you to do this, and well talk about it in "Reconnect to the CM Synergy Database" on page 60. If you dont save changes made in work area files to the database, the work area files are just like files that reside on your PC. Theyre subject to the reliability of your system. In the next exercise, youll save the changes you made to the files in your work area to the CM Synergy database. This is called "reconcile." Once

58

CM Synergy Learning Guide

Work Disconnected From the CM Synergy Database

youre in the database again, CM Synergy can use decisions you make in the Reconcile Work Area dialog to do the reconcile legwork for you.

CM Synergy Learning Guide

59

CM Synergy Operations

Reconnect to the CM Synergy Database


In the previous operation, "Work Disconnected From the CM Synergy Database", you edited files and created a file in your work area while working outside of CM Synergy. Now youll reconnect to the CM Synergy database to bring your work area files and your database objects back into sync. This process is called "reconcile." Heres How... 1. If you minimized the Project View in "Work Disconnected From the CM Synergy Database" on page 56, restore it now. If you exited your CM Synergy session, restart it now (refer to "Start CM Synergy" on page 8 for instructions). 2. 3. 4. Reconcile work area
and database files

Check the Default Task field in the Project View to ensure that the task youre working on is set as the default. Be sure your calculator project is in view in the Project View. Bring up the Reconcile Work Area dialog. Project View: calculator-username pop-up menu > Reconcile... A Reconcile Work Area dialog displays. In the Conflict Handling group box, be sure to turn ON the Select option. Reconcile Work Area: Conflict Handling group box > click Select > ON The Conflict Handling group box contains options that you can turn ON to tell CM Synergy how you want to resolve the conflicts in work area files with database objects.

FYI... ...Normally, youll want to use the Select option so that you can choose the files that will be reconciled. If you select the Update Database from Work Area option, all work area changes will be copied into your CM Synergy project. If youve deleted a file in the work area, it will be deleted from your project. Extra files that youve created in your work area will be created in the project, even if you didnt want the files there. 5. Turn on the Advanced Conflict Resolution option. Reconcile Work Area: Conflict Handling group box > click Advanced Conflict Resolution > ON By choosing the Select and Advanced Conflict Resolution options, youve told CM Synergy to display the conflicts it finds and to allow you to decide how to resolve them.

60

CM Synergy Learning Guide

Reconnect to the CM Synergy Database

6.

Turn OFF the Check for Missing Work Area Files option. Reconcile Work Area: Options group box > click Check for Missing Work Area Files > OFF

7.

Turn ON the Check for Uncontrolled Files option. Reconcile Work Area: Options group box > click Check for Uncontrolled Files > ON Use this option when you have created new files in your work area and you want to add them to CM Synergy.

8.

Turn ON the Message View. Your Reconcile Work Area dialog will look similar to the one in Figure 22. Reconcile Work Area: Options group box > click Show Messages > ON

Figure 22. Reconcile Work Area Dialog 9. Start the reconcile. Reconcile Work Area: click Reconcile

CM Synergy Learning Guide

61

CM Synergy Operations

The Resolve Work Area Conflict dialog displays, showing three conflicts, one each for clear.c, main.c and test.c. The conflicts for clear.c and main.c show that the files has changed. Recall that you edited main.c even though it was not checked out to you. The conflict for test.c is that it is not under source control, i.e., an uncontrolled file. Your Reconcile Work Area dialog will look similar to the one in Figure 23.

Figure 23. Advanced Work Area Conflict Resolution Dialog The Advanced Work Area Conflict Resolution dialog allows you to resolve conflicts detected during the reconcile process. You have the option to gather additional information about selected files before resolving the conflicts. For this tutorial, well skip ahead and resolve the conflicts by updating the database from the work area. 10. Select all three conflicts to resolve. Advanced Work Area Conflict Resolution: Files in conflict text box > select clear.c, main.c, and test.c

62

CM Synergy Learning Guide

Reconnect to the CM Synergy Database

Note: In this dialog, you can resolve up to five files at a time, as long as they have the same conflict resolution requirements. 11. Select how the conflicts will be resolved. Advanced Work Area Conflict Resolution: Resolution group box > click Database from Work Area 12. Resolve the conflicts. Advanced Work Area Conflict Resolution: click Update When the reconcile is complete, the Reconcile Work Area dialog closes automatically. Look at the Message View to see which database objects were updated. Notice that clear.c was updated in the database, test.c was added to your project, and a new version of main.c was checked out. 13. Exit from the dialog and close the Message View. Advanced Work Area Conflict Resolution: click Close Message View: File pull-down menu > click Close

Notes... Now for some exciting information! If youve changed a file in your work area but not in your database, or if youve changed an object version in your database but not in your work area (i.e., the timestamps are different), then completing any of the following CM Synergy operations will automatically update the old file with the new. In all situations: check in, resync, sync On new working state versions: reconfigure, use, unuse When a conflict exists between the file system file and the database object version: check out If you created a file in the file system or the database: create Before the text editor starts: edit When building certain types of files: ObjectMake Automatic update

Automatic update means that you dont need to reconcile the changes between the database and file system. This is helpful because it automatically brings your work area and database files into sync when you perform an operation such as check in.

CM Synergy Learning Guide

63

CM Synergy Operations

Telelogic strongly recommends that you reconcile at least once a day, at the end of the day. Even if you have a reliable nightly backup, you must reconcile your work area changes with your database objects. Reconcile Handles Synchronization Conflicts Part of reconcile involves synchronization. As you might recall reading in the Introduction to CM Synergy, synchronization is the process CM Synergy uses to make the file system files and the database objects contain the same data. The reconcile process deals with how to handle the conflicts that occur when CM Synergy tries to sync the file system and the database, and finds that those files contain differences. For more information, read the "Reconcile" section in the Introduction to CM Synergy.

64

CM Synergy Learning Guide

Create a New Object

Create a New Object


You can create a new object in your CM Synergy database in two ways: in your work area first, or in the database first. Each way has its advantages. If youre working disconnected from the database and you create a new object, its easy to bring it under CM Synergy when you reconnect as you saw in the last exercise. If youre in the database and you create a new object, its written out to your work area as soon as its created. In this exercise, youll create the new.h object in the calculator project. Heres How... 1. Be sure your calculator project is open in the Project View. Also check the Default Task field in the Project View to ensure that the task youre working on is set as the default. Bring up the Create dialog to create a new incl file that is a member of the includes directory. Project View: includes-1 pop-up menu > Create... A Create dialog displays, similar to the one in Figure 24.
When you create the object, it will be a member of this project, and of this root directory and subdirectory.

2.

If you enter an extension here when you name the object, then you wont need to make changes here.

Figure 24. Create Dialog 3. Give the new object a name and extension. Create: Name text box > new.h Sometimes youll need to change the Type list, but only if youre creating an object that doesnt have an extension such as a directory (more on this later in "Notes" on page 67). For all other type creation,

CM Synergy Learning Guide

65

CM Synergy Operations

you can leave the Type list set to default and CM Synergy will fill in the type according to the extension you enter in the Name box, as long as the extension maps to a predefined CM Synergy type. 4. 5. Automatic directory
checkout and default task association

Enter a comment. Create the incl object. Create: click Create The dialog automatically closes when the operation completes. Since you created an object (new.h) in a directory (includes) that was non-writable (integrate or above), CM Synergy checked out the directory for you when it created the new object. This occurs with root directories as well. Also, CM Synergy automatically associated the default task with the newly checked-out directory.

6.

View the contents of new.h by double-clicking it.

Look at your includes directory in the Project View. The new incl object displays, and both the object and the directory are in the working state.

Notes... Earlier in this exercise, two points to consider came up: where the newlycreated object should reside, and how to bring up the Create dialog. These are important, related items. For example, if youre creating an object called color.c to enhance functionality, and all of the other code for this part of the product resides in the rainbow directory, then youll create color.c as a member of the rainbow directory as well. Youll bring up the Create dialog from the rainbow directory. Create More Objects As with all types of creation, many variations exist. The following section describes more ways to create new objects. Do these additional create exercises if you have the time, otherwise make a note of where they are so you can come back and try them later. 1. Create a new project 2. Create a New Project Bring up the Create dialog. Project View: Actions pull-down menu > Create Project... Type the project name, for example gizmo, in the Name text box.

66

CM Synergy Learning Guide

Create a New Object

3. 4. 5.

Type your username in the Version text box. Select release 2.0 in the Release list box. Create the project by clicking on the Create button. The new project automatically displays in the Project View. Additionally, the new project is written out to your work area upon creation.

1.

Create a new dir object In the Project View, place the cursor over an existing directory in which you want the new directory to be a member. Project View: directory pop-up menu > Create Create a new
directory

2.

Select the dir type to display in the Type list box. A directory does not have a file extension, so always select the dir type when you create a directory.

3. 4.

Enter a name for the new directory. Create the directory by clicking Create.

CM Synergy Learning Guide

67

CM Synergy Operations

Search the CM Synergy Database for an Object


After youve used CM Synergy for a while and own several projects in the database, there will be times when you need to look at a certain object, but wont remember the exact name of the object. The Query dialog enables you to search the database for existing objects based on the information you know about them, such as who owns the object, the objects state, or the objects version. Heres How... 1. Bring up the Query dialog. Project View: Actions pull-down menu > Query... A Query dialog, similar to the one in Figure 25, displays.

Slim down this field as much as possible for faster queries.

Turn off this option when sorting is unnecessary for faster queries.

Figure 25. Query Dialog 2. Find all csrc objects called main.c in the released state that are owned by user jwark. a. Enter main.c in the Name text box. Query: Name text box > type main.c

68

CM Synergy Learning Guide

Search the CM Synergy Database for an Object

b.

Enter jwark in the Owner text box. Query: Owner text box > type jwark Select released from the Status list box. Query: Status list box > released Select csrc from the Type list box. Query: Type list box > csrc

c.

d.

e.

Start the query. Query: Query button

The results that display in the Results box match the information you requested, as pointed out in Figure 26.

Figure 26. View the Results of Your Query The following are queries used daily by developers at Telelogic. You can perform them for more practice with the query operation.

CM Synergy Learning Guide

69

CM Synergy Operations

3.

Perform more queries by using the following information: Query for all occurrences of clear.c, but turn OFF sorting. Query: click Clear Name box > type clear.c Type box > csrc Sorted option > OFF click Query Query for all projects that you own and sort the results of the query using the display name only. Query: click Clear Owner box > type username Type box > project Format list box > %displayname Sorted option > ON click Query Query for all instances of the main.c object that you currently have checked out. Format the query to return the display name and instance. Query: click Clear Name box > type main.c Owner box > type username Status box > working Type box > csrc Format list box > %displayname %instance click Query Query for the products that you just checked in. Format the query to return the display name and type. (This is a useful query to know. If you try it now, youll receive no match because you havent checked in a product yet.) Query: click Clear Owner box > type username Status box > checkpoint Query box > type is_product=TRUE Format list box > %displayname %type click Query

70

CM Synergy Learning Guide

Search the CM Synergy Database for an Object

Query for the changes that user jwark checked in after 6/14/99. Format the query to return the display name, type, instance, and task. Query: click Clear Owner box > type jwark Status box > released Query box > type modify_time > time(1999/06/14) Format list box > %displayname %type %instance %task Query click

From the Query dialog, you can also do the following: Find out in which project an object is being used. Click an entry in the Results box, then click Find Use. View the history of an object in the History View. Click an entry in the Results box, then click Show History. Display a project that you queried. Click a project in the Results box, then click Show Project. 4. Close the Query dialog. Query: click Close

Notes... The following items are tips to help you search the database from the GUI faster and more easily. Wildcards are allowed You can enter any portion of an object name in the Name and Within Project text boxes as long as you use the asterisk to denote the unknown parts of the name. For example, lets say youre looking for an object that you think has the word "sample" in it. But lets say you cant recall whether "sample" is capitalized or not, and you dont know if other characters came before or after. Youd enter *ample* in the Name text box. Non-sorted queries are faster than sorted queries A query is sorted by default. Sorting is done in the order which CM Synergy displays object names. Names beginning with numbers

CM Synergy Learning Guide

71

CM Synergy Operations

display first, names written in all capital letters display next, then initially-capitalized names, and last all lowercase names. When you turn OFF Sorted, the names are ordered according to when theyre found in the database. Non-formatted query results return faster than formatted query results The Format text box tells CM Synergy what kind of information about an object to display and the order to display it. The more information you want to view, the longer the query will take. Take a few seconds to look at the information in the Format text box. You might not need all of it, or you might need to designate different keywords. Save queries that you use often to file If you find yourself using the same queries, or if you set up very detailed queries, you can save them to a query file. Next time you want to use one, bring up the Load Query String browser to select it, then load it into the Query dialog. Note: See the CM Synergy Online Help for more information about queries.

72

CM Synergy Learning Guide

Add an Object Already in the CM Synergy Database to Your Project

Add an Object Already in the CM Synergy Database to Your Project


When an object that isnt a member of your project already exists in the CM Synergy database and you want to use its contents, then add the object to your project. You can add any object to your project whether or not you own the object. Note: The project that youre adding an object to must be modifiable or the operation will not work. When you add an object to a project that is writable by you but the directory is in a non-modifiable state, CM Synergy will check out a new version of the directory and then add the object version to it that you want to use. Heres How... 1. Bring your editor project into view in the Project View. Also check the Default Task field in the Project View to ensure that the task youre working on is set as the default. Add user connors bufcolor.c-2, instance 2, to your sources directory. Project View: sources directory pop-up menu > Add Object... An Add Object dialog displays, similar to the one in Figure 27.

2.

Figure 27. Add Object Dialog 3. Enter the object name. a. Click the Query icon. The Query dialog displays.

CM Synergy Learning Guide

73

CM Synergy Operations

b.

Query for bufcolor.c. Query: click Clear Name box > bufcolor.c Type box> csrc Format field > %displayname %project %owner %instance Query click Highlight the object you want to add, bufcolor.c-2, instance 2, owned by user connor. Close the Query dialog. Query: click Close Place the highlighted query info in the Add Object dialog by clicking Get Query Result.

c. d.

e.

Now the Object text box will contain the object reference form, bufcolor.c-2:csrc:2. (For a description of what the "object reference form" is, read about it in "Notes" on page 75.) 4. Click Add. Add Object: click Add Notice that the Cancel button changed to Close when the operation completed. 5. Close out of the Add Object dialog. Add Object: click Close Look in your Project View. Notice that the sources directory has a new member, bufcolor.c-2. Also, notice that the sources directory, which was in the released state, now is in the working state. This change occurred because you changed the sources directory entry list when you added bufcolor.c. CM Synergy checked out sources for you automatically, and also associated task 30, the default task, with the new directory version. If you mapped objects in different states to unique colors, the bufcolor.c object, which is in the integrate state, should be obvious within the sources directory. Take a look!

74

CM Synergy Learning Guide

Add an Object Already in the CM Synergy Database to Your Project

Notes... Recall that an instance is an attribute that is automatically associated with objects when the objects are created in the CM Synergy database. The instance distinguishes between multiple objects that have the same name and type but that are not versions of a single object. For example, a project could contain twenty C source files named main.c, each in different directories and each with several versions. If you wanted to use main.c-4, the query of that object might yield six objects named main.c-4. The instance attribute would distinguish which main.c-4 object is the one you want to use. For example, bring up the History View. Project View: File pull-down menu > click Show History In the Object text box field, enter bufcolor.c. Notice the different instances of this object. The instance attribute is included in the Query dialogs format field by default. Each time you query, CM Synergy will return the instance of the specified object. You can also use the Properties dialog to view the instance of an object. The CM Synergy object reference form is also known as the four-part name. It looks like this: objectname-version:type:instance For example, in the previous exercise, you needed to add bufcolor.c-2 to your project. By looking at the object, you know its name is bufcolor.c, its version is 2, and its type is csrc. All you need to find out is its instance. As you learned in the above paragraphs, you can do this in the Properties dialog. So, the object reference form or four-part name is: bufcolor.c-2:csrc:2 Object reference
form

Distinguish between
multiple objects of the same name and type

CM Synergy Learning Guide

75

CM Synergy Operations

Unuse an Object
When you unuse an object version, you remove the object version from your project configuration. Most developers work with the unuse operation when moving source code to a different project or when removing obsolete code. This operation enables you to unuse an object version in the following three ways: Unuse Removes an object version from your project. Additionally, you can unuse a checked-in object from your project configuration. Unuse and Delete Removes an object version from your project and permanently deletes it from the database. Delete and Replace Deletes the object version permanently from the database, then replaces it with the version that CM Synergy finds to be the next best candidate. Note: The "Unuse and Delete" and the "Delete and Replace" options permanently delete objects from the CM Synergy database. You can only delete an object version if it is writable and owned by you. Additionally, when you unuse or unuse and delete an object version from your project, you change the directory objects list of entries. If the directory object is not checked out, CM Synergy will check it out and associate it with the default task (if one is set). If you delete and replace an object version, the directory object wont be checked out (since the directory entry list doesnt change). Heres How... 1. 2. Bring your calculator project into view in the Project View, then open the sources directory. Bring up the Unuse dialog for the math.c object version in your calculator project. Project View: math.c pop-up menu > Unuse...

76

CM Synergy Learning Guide

Unuse an Object

The Unuse dialog displays, as shown in Figure 28.

Figure 28. Unuse Dialog 3. Tell CM Synergy that you no longer want math.c in your project, but that you still want it in your database. Project View: click Unuse option > ON 4. Unuse the object version. Unuse: click Unuse Note: When you unuse an object, you change the directory entries. CM Synergy will check out the directory if its nonmodifiable. Your sources directory was checked out during a previous operation, so you wont see a change. FYI... The "Unuse and Delete" option and the "Delete and Replace" option are two ways of deleting an object that you no longer want in your project configuration or in the CM Synergy database. You also can use the Delete dialog, which contains additional options to help you delete object versions. Youll use the Delete dialog in the next exercise.

CM Synergy Learning Guide

77

CM Synergy Operations

Delete an Object
When you no longer want an object to exist in the CM Synergy database, you can delete it. If you dont want the object in your project, but you still want it to exist in the CM Synergy database, you should unuse it. This distinction is very important to understand. When you delete an object, its gone permanently. When you unuse an object, its no longer a member of your project configuration, but if you need it again later you can add the object back in. You can only delete your objects that are in the working state, and then only if they arent used in other projects. You might need to delete objects for the following reasons: You created the object for your own testing or prototyping, but you dont need it anymore. You created the object early in the project, but you dont need it anymore because the project changed direction. You made a change in an object, but the change didnt work, so you want to start over.

In this exercise, youll delete an object you no longer need. Heres How... 1. 2. Be sure youre still in your calculator projects sources directory. Bring up the Delete dialog for test.c. (This is the object that you created in "Work Disconnected From the CM Synergy Database" on page 56, and brought into CM Synergy in "Reconnect to the CM Synergy Database" on page 60. Since you own this object and its writable by you, youll be able to delete it.) Project View: test.c pop-up menu > Delete...

78

CM Synergy Learning Guide

Delete an Object

The Delete dialog displays, as shown in Figure 29.

Figure 29. Delete Dialog 3. 4. You only want CM Synergy to delete the one object, so leave the Scope set to Object Version Only. Delete the object. Delete: click Delete The object version you deleted no longer exists in the database or in your work area. If you wanted to delete a directory or a project object, you would place the cursor over the directory or project object, bring up the object popup menu, then select Delete. By bringing up the Delete dialog in this way, you would see the Scope options for either the directory object or the project object. The scopes available for each object are different. For more information on valid scopes when deleting objects, refer to the CM Synergy Online Help. Note: If any object you want to delete is being used in another projectany other projectyou cannot delete the object until it has been unused from the other project(s).

CM Synergy Learning Guide

79

CM Synergy Operations

Notes... Find the use of an


object before deleting

A useful feature in the Delete dialog is the Find Use button, which is located in the lower left portion of the dialog. When you click an object in the Selection field, then on the Find Use button, the Find Use dialog displays. Use the Find Use dialog to see where an object you want to delete is being used. Sometimes developers will use the Find Use operation before they attempt to delete an object to see if performing the delete is worthwhile. Other times developers perform the delete, then, if it fails, they use the Find Use operation to see where the object is being used. The object could be in use only in a couple of working projects that you own, and you might decide that you dont need it in those projects. In this case, you could proceed with the delete by first performing an unuse of the object in all but one of the working projects, then performing a delete in the last working project in which the object is being used.

80

CM Synergy Learning Guide

Reconfigure Your Project and Unit Test

Reconfigure Your Project and Unit Test


You might be thinking that youve already reconfigured your project once and maybe you dont need to reconfigure again. You do need to reconfigure again. This time when you reconfigure, youll bring in the most recent tested tasks that were built by the build manager. This will occur because there is a tested tasks folder in your projects reconfigure properties. See "Notes" on page 37 for an explanation of how reconfigure works. Why do you need the most recent tested tasks that were built by the build manager? The answer is...UNIT TESTING! Right now, your project is running great. Youve debugged it, and within your insulated world, it builds perfectly. Now youre ready to introduce objects from other team members into your project, then build and test again to ensure that your code works with all of their changes, all of which have passed the build managers tests. If you check in your task without a final reconfigure and unit testing cycle, the build manager will pick up your checked-in task and attempt to build the code anyway. Your code could break the build and hold up the team while you go back, reconfigure, unit test, debug, rebuild, etc. A final reconfigure and unit test cycle is really important to complete to keep the build process running smoothly. Normally, in a production database, you would perform a reconfigure now. But since you reconfigured earlier, and youre the only one working in this database, if you were to reconfigure now, nothing new would be reconfigured into your project.

Notes... The reconfigure operation updates your work area automatically. It selects the latest versions of files that were checked in by other users, as well as your own working versions. However, sometimes youll want to bring in a newer object to your project with the use operation rather than reconfigure the entire project. For example, in a very large project where many developers are working on the same project, a reconfigure might replace "old" object versions that you want to keep with more recent object versions. If you need only one or two of the latest object versions available, you could use those object versions into your project. Alternatively, if you Bring latest object
versions into your project

CM Synergy Learning Guide

81

CM Synergy Operations

wanted all the latest object versions except for two, you could use the objects differentlyyou could reconfigure your project, then use the two older object versions back into your project.

82

CM Synergy Learning Guide

Check In the Default Task

Check In the Default Task


Now that your work is done, youre ready to check in the task youve been working on. Whether your task has three objects or a hundred objects associated with it, CM Synergy checks in all of the objects first, then the task itself. Once the task is checked in, its available for the build manager to build. How does the build manager get your task? The build manager will have a folder set up to query for all objects that were completed for release 2.0. Since youve just completed a task for release 2.0, your task will be gathered by the query and added to the build managers folder. Note: Before you check in your task, look at the objects associated with it. If any objects that should be in the list are missing, at that point you would want to associate them with the task. If any objects are in the list but shouldnt be, at that point you would want to disassociate them. Once a task is completed, you cannot change it back to assigned. Heres How... Check in task 30 (the default task). 1. Bring up the Check In Task dialog. Project View: Tools menu > Task submenu > Check In Default Task... A Check In Task dialog displays, as shown in Figure 30.
This is the default task youve been working on.
bufcolor.c-2 clear.c-2 includes-2 main.c-2 new.h-1 readme-1.1.1 sources-2 toolkit.ini-mine

These are the objects that youve checked out while working on your task.

Figure 30. Check In Task Dialog

CM Synergy Learning Guide

83

CM Synergy Operations

Notice that the objects you checked out and added to your project are listed in this dialogs Objects field. Your list of objects may differ, depending on whether youve tried some additional operations. Even though you worked within at least four different projects and many directories, CM Synergy kept track of every object you checked out or added because you set the default task before you began work on the task. Every object you worked on after you set the default task was associated with it. This is good because now you will check in the default task, and all objects associated with the default task will be checked in at the same time. 2. Check in the default task. Check In Task: click OK During the check in process, youll receive a Warning dialog with the following message:
Parallel versions were detected for 1 of the objects checked in. See the Message View for details.

Dismiss the warning dialog. Youll merge this parallel version in the next exercise. Look in the Project View. Notice that after the default task is checked in, the Default Task field displays "None." This is because the task that was the default now is checked in and non-writable, so you can no longer associate objects with it.

84

CM Synergy Learning Guide

Check In the Default Task

Notes... Once youve completed your task, normally, youd set a new default task and start on your next task. But since this is a tutorial database, you can take a little break before moving into the last set of operations. In this exercise, you saw how easy task-based CM makes it for developers to check in objects. Besides making your work easier, the automatic features for directories in CM Synergy can also help avoid potential embarrassment. How? In a previous exercise, you added an object to a checked-in directory. When you added the bufcolor.c object, you added a new directory entry, which means that the sources directory needed to be checked out. So CM Synergy checked out the directory for you, associated the new directory version with the default task, then added the bufcolor.c object. When you checked in the default task, the directory, which was associated with the default task, was checked in as well. Whenever you change a directory entry list by adding or deleting members, you must check in the directory or the objects will not be available for the build manager to build. Since the directory was associated with the default task, and since you already checked in the default task, the directory was checked in. Correcting Completed Tasks That Contain Errors Sometimes errors are found after a task has been checked in. For a completed task that contains errors, a fix task may be created to remedy the errors. The fix task is a new task or an existing task that is associated with the old task. Although it looks exactly like the old task when you create it, the fix task contains only the objects required for the fix. In emergency situations, a task may be excluded from a project. See CM Synergy Online Help for information about fixing and excluding tasks. Automatic directory
checkin

CM Synergy Learning Guide

85

CM Synergy Operations

Merge Two Objects


The Merge tool enables you to blend information from two parallel versions of a file. In this exercise, youll merge your integrate state readme-1.1.1 with user darcys integrate state readme-2. Recall that when you checked in your default task in the previous exercise, you received a Warning dialog informing you that a parallel version existed. You couldve merged the parallel version before checking in the default task, but lets say that youre a busy person with a lot on your mind, and you forgot that you had a parallel version. No problem! You can merge the parallel versions now. One advantage to merging the parallel version after checking in the default task is that you narrow the scope of your testing. For example, lets say that you already tested your code for the rounding error problem in calculator. You integrated it with your teams latest and greatest changes. You know your codes good. After you merge parallel versions, youll build using the new object, do any debugging, fixes, etc. If you have problems, you can be pretty sure that the problem is with the new merged object. Your search is narrowed, enabling you to identify the fix more quickly. Heres How... 1. Open the toolkit-username project in your Project View. This is not necessary to merge two objects, but in step 9 you will see in the Project View some of the things CM Synergy merge does to make your life easier. Query the database to find your parallel version. The version is 1.1.1, the status is integrate, and you are the owner. If youve forgotten how to query, refer to "Search the CM Synergy Database for an Object" on page 68, or see the CM Synergy Quick Card. Be sure to click the Clear button before you enter anything in the Query dialog. 3. View history of
parallel versions

2.

Bring up the History View for the object to be merged, readme-1.1.1. Query: Results > highlight readme-1.1.1 > click Show History The History View displays. In the History View, click the readme-2 object first, then shift-click readme-1.1.1 to select it.

4.

86

CM Synergy Learning Guide

Merge Two Objects

When you merge two object versions, CM Synergy takes the data in each file, then creates a third object version. The third object gets its version from the first object version you choose in the History View. Therefore, this new version will be called readme-3. If youd chosen readme-1.1.1 first, then the merged object version would be called readme-1.1.2. The merged object will contain all the likenesses and differences between the two readme objects youre about to merge. 5. Bring up the Merge dialog. History View: Actions pull-down menu > Merge A Merge dialog displays, similar to the one in Figure 31.
In the History View, you chose this object first. You chose this object second.

Bring up the Merge


dialog

This comment is added automatically by CM Synergy. These options are default settings.

Figure 31. Merge Dialog Notice that the Create New Task option is ON. This is the default, if you dont have a default task set. Remember, you checked in your default task in a previous exercise. If you did have a default task set, the Merge dialog would display with the Create New Task option OFF by default. 6. Merge the files. CM Synergy brings up the automated merge option because the changes youre merging are minimal and none of them conflict. CM Synergy performs an automatic merge unless conflicts exist. In this case, youll perform an interactive merge. Merge: click OK Create a new task for
the merge

CM Synergy Learning Guide

87

CM Synergy Operations

The files merge and the Merge dialog closes. If you havent configured your mail tool, youll receive a message asking if youd like to do this. You can press the No button because you dont need to send and receive mail from the tutorial database. 7. The History View automatically displays so that you can see the new history for readme-3. Figure 32 displays the new history.
CM Synergy

This is the name of the object whose history youre viewing.

This is the new (merged) object version.

Figure 32. History View: Example of Merge History 8. Exit from the History View. History View: File pull-down menu > Close Close the Query dialog. 9. Look in the Project View to see the new (merged) version, readme3, in your project. CM Synergy brings it into your project automatically. Also, notice that CM Synergy set the new default task in the Project Views Default Task pull-down menu. At this point, in a production database, you would edit, compile, and debug the merged object version, but you wont in this tutorial database. Check in the new
default task

10. Check in the new default task, 40. (Your default task number might be different if you practiced creating additional tasks.)

88

CM Synergy Learning Guide

Merge Two Objects

Refer to "Check In the Default Task" on page 83 or see the CM Synergy Quick Card. Perhaps youre wondering how the build manager will know to bring your merged object into his project. Thats a good question! Well discuss it in "How Does the Build Manager Build a Merged Object Version?" on page 90.

Notes... Merge Multiple Parallel Versions To understand how to merge multiple parallel versions, consider the following example: A team of four developers works on a new international editor. They each check out a version from main.c-1. In the database are main.c-2, main.c1.1.1, main.c-1.2.1, and main.c-1.3.1. Lulu owns main.c-2, and she finishes her changes first, so she checks in her default task. Since the other object versions are in the working state, she cant merge versions, so shes off the hook. Next Conchita finishes her work and checks in her default task. During the check in, she receives the Warning dialog, which states that a parallel version was detected. Right after the task check in, Conchita merges main.c-1.1.1 with main.c-2. The merged version, main.c-3, contains changes from main.c-2 and main.c1.1.1, in that order. Hildegard finishes her changes and goes to check in her default task. She receives the Warning dialog, too. She merges main.c-3 and main.c-1.2.1, in that order. The newly-merged object version is called main.c-4. Thor finishes testing main.c-1.3.1. Thor dislikes using the GUI, so he only works from the CLI. He issues the ccm checkin /task command and receives the message about parallel versions existing. After the check in completes, he uses the ccm merge command to merge his changes with main.c-4. Thor doesnt notice that hes chosen main.c-1.3.1 before main.c-4, but realizes it when he sees the resulting object version, which is main.c-1.3.2. Youll commonly see whole and non-whole version numbers as a result of merges. Dont worry about non-whole numbers when you see them. They just mean that whoever chose the objects to be merged selected the nonwhole numbered object before the whole numbered object.

CM Synergy Learning Guide

89

CM Synergy Operations

Areas in Conflict During Merge When CM Synergy creates the new (merged) object version, it first compares the versions against the most recent common ancestor version, then checks out a new object in which to place the merged data, and gives the new object a name and version based on the first parallel object version you select in the History View. This is why merges using CM Synergy are commonly called three-way merges. If conflicts do not exist in the files (i.e., the same line or lines of code were not changed), the new object version is ready to use, otherwise you must edit the new (merged) source file and choose which of the conflicting code you want to use. How Does the Build Manager Build a Merged Object Version? In the merge exercise you just completed, if you had set a default task and then merged parallel versions before checking in the default task, CM Synergy would not have automatically created a task for you . But since you didnt have a default task set when you merged parallel versions, CM Synergy created a task for the newly created object (the object that was created by the merged objects), then associated the new task with the newly created object. Lets say that the task CM Synergy created was task 40. Right after CM Synergy created it, it became the new default task. Even though you didnt manually create the task or the association, readme-3 was associated with task 40. The synopsis of the new task is: 40: Merge readme-2 (associated with task 6) with readme-1.1.1 (associated with task 30) Task 6 is the task associated with readme-2, which was the object with which you merged your parallel version. Task 30 is the task associated with readme-1.1.1, which was your parallel version. Task 40 is the new task that CM Synergy created automatically when you merged the two parallel versions. The default task states this in its name: 40: Merge readme-2 (associated with....) The build manager now can pick up task 40 because youve checked it in. Remember, when you check in the default task, all of the objects you checked out to make any fixes will be checked in too.

90

CM Synergy Learning Guide

Reuse Your Working Project

Reuse Your Working Project


Now your project is done. You checked in all the tasks that you needed to complete. Everything passed testing by the build manager and quality assurance, and your company built and shipped the software application. Youre ready to start on the next release. Telelogic recommends that you reuse your working project because this methodology represents a clean way to work. It wont leave old projects to clutter the CM Synergy database. To reuse your working project, take the following steps: 1. 2. Find the name of the new release from your build manager. Update the release value on each of your working projects: a. b. c. Bring up the Properties dialog on the top-level project, then set the Release attribute to the new release. Select the Apply Release to Subprojects option to copy the release attribute to all subprojects. Click OK to save your changes. Note: These instructions assume that your build manager has set up templates for the new release.

CM Synergy Learning Guide

91

CM Synergy Operations

Work on a Patch Release


Occasionally when youre working on a regular release, you may have to stop to work on a patch release. If you need to work on more than one release at a time, Telelogic recommends that you check out projects for each release. A patch is really a different release. It requires a different release number and different reconfigure properties. Working in a separate project is much easier than switching the projects reconfigure properties back and forth between a release project and a patch project, and then reconfiguring every time you need to work on the other release. Complete the following steps to reuse your working project for a patch release: 1. 2. Find out two things from the build manager: the patch baseline and the patch release name. From the patch baseline, check out the project you need to patch. Be sure to set the patch release name on your new project when you check out. The patch release cycle will be the same as the regular release cycle. Youll set the default task, then check out objects required to complete the task. Youll test until youre confident that your code is ready for the final reconfigure, then youll unit test. After your code passes this final cycle, youll check in the default task, making it available for the build manager to include in his next build. Note: These instructions assume that your build manager has set up templates for the new release.

3.

92

CM Synergy Learning Guide

Migrate an Existing Project from Your File System into CM Synergy

Migrate an Existing Project from Your File System into CM Synergy


The CM Synergy Project Migration Facility enables you to load an existing directory hierarchy into CM Synergy. This facility (also called the Migrate dialog) enables you to inspect the files to be migrated by providing a Preview feature. While previewing a migration, you can ignore any unnecessary files and change the types of the files youre about to migrate. During initial project setup, the project leader typically migrates the project into CM Synergy. This is because the project leader should possess the knowledge for how to structure the projects in CM Synergy for maximum speed during the migration and afterwards, and for operations such as synchronization and reconfiguration. However, after the initial project setup, you might migrate additional data. Heres How... Load any simple directory structure from your file system to the CM Synergy database, and give the new project a meaningful name and version. 1. From the Project View, bring up the Migrate dialog. Project View: Tools pull-down menu > Migrate...

CM Synergy Learning Guide

93

CM Synergy Operations

The Migrate dialog displays, as shown in Figure 33.

Figure 33. Project Migration Facility 2.


Remember
Migrate from the browser...

Enter the migration information. a. Enter the path from which CM Synergy should migrate the directory. Migrate: From Directory text box > enter drive:\db_name\path If you dont remember the path or name of the directory to be migrated, click the Browse button to bring up the Migrate From browser. This browser provides a view into your file system. Select a path and directory, then load it into the From Directory text box by clicking OK. (See the sidebar if youre not sure how to use the browser.) b. Enter a meaningful project name and version for the objects youre migrating. Migrate: Project text box > enter project_name-version c. Enter a task that you wish to associate with the objects. Migrate: Task text box > enter task_number To see a list of tasks, click the Select Task button.

Set the right drive here. Click here to find the right directory Click OK to load the directory of choice into the Migrate dialog.

94

CM Synergy Learning Guide

Migrate an Existing Project from Your File System into CM Synergy

d.

Enter a release value for the objects youre migrating. Migrate: Release list box > click release_value

3.

Preview the project data you want to migrate. Migrate: click Preview Notice that the Preview button changed and became the Stop button. You have the option to stop the preview at any time. The Preview operation analyzes the directory tree you want to migrate, but does not load it. After this operation completes, the total number of files scanned displays in the lower left portion of the dialog, as shown in Figure 34.

This is where CM Synergy retrieved the info to preview.

This will be the name of the project and version once its migrated.

Figure 34. Preview of Migrated Project and Members a. Use the scroll bar to examine the Preview Results field. If you find files in this directory that you dont want to load, click the file name, then click the Ignore option ON. Youll see a dash to the far left of the file name. When you migrate the directory, the files you marked to be ignored will not be migrated.

CM Synergy Learning Guide

95

CM Synergy Operations

b.

Check that each type CM Synergy has assigned to your objects is correct. If you find that youve migrated an object that doesnt map to a predefined CM Synergy type, assign it an ascii or binary type. If this had occurred in your production database, you would go to the user with type_developer or ccm_admin role and ask him to create a new type in the database.

4.

Load the previewed project data into CM Synergy. Migrate: click Load Notice that the Load button changed and became the Stop button. You can stop loading the project at any point during the load. Understand, however, that whatever objects were created before you stopped the load will remain in the database. If you decide to reload the same directory structure later, by default, CM Synergy will skip identical files. A progress dialog, Migrate Status, displays and reports on the load progress.

Number of objects
migrated

When the migration completes, the total number of objects migrated into CM Synergy displays in place of the load time. The number is always one larger than the previewed total. This is because during the preview, the project does not exist; when you tell CM Synergy to load the objects, it first creates the project under which the other objects will reside, then it migrates the objects under the project. 5. After the project data successfully migrates into CM Synergy, the new project displays in the Project View. Look at the state of the project in your Project View. By default, the project migrates in the working state, but the members are in integrate. 6. Bring the Migrate dialog to the foreground, then close it. Migrate: File pull-down menu > Close

96

CM Synergy Learning Guide

Migrate an Existing Project from Your File System into CM Synergy

Notes... You have previewed an existing directory hierarchy using the Migrate dialog and loaded data into CM Synergy to create a project. Although you didnt use the migration rules in this exercise, you can use them to ignore certain types of files or to map a file with a specific name or suffix to a particular type. For more information on understanding and setting migration rules, see "Advanced Topics" in the CM Synergy Online Help. Read the section called "Migration Rules." Now that the project is under CM Synergy control, you can use all of the tools features to manage your objects. If youd like more practice using CM Synergy in a non-production database, you can go through the tutorial using your "real world" data.

CM Synergy Learning Guide

97

CM Synergy Operations

Stop CM Synergy
When youre ready to exit from your CM Synergy session, you can exit from the Project View. Heres How... 1. Exit from your CM Synergy session. Project View: File pull-down menu > Exit The Exit Confirmation dialog displays. 2. Confirm that you want to exit from the session. Exit Confirmation: click Yes Congratulations on completing the tutorial! Now youre ready to work in your production database. If you forget how to perform an operation, use this guide to refresh your memory. This guide includes only a subset of operations that can be performed in CM Synergy. If you have any comments for improvement on the material you just read, wed like to hear from you, so please send us an e-mail: U.S. and non-European customers: cmsupport.us@telelogic.com European customers: cmsupport.eu@telelogic.com Asia/Pacific customers: support.australia@telelogic.com

98

CM Synergy Learning Guide

Appendix A: Unpack the Tutorial Database


Note: Be sure to run the shipped tutorial setup script so that users can go through the exercises in this guide. If users tell you that their database doesnt match the exercises, check to be sure that you have the latest tutorial database and that you ran the shipped tutorial setup script. Instructions for where to find the latest of each are in this appendix. The following information is for the CM administrator only. If you want to set up the tutorial database and youre not the CM administrator, youll need to have ccm_root privilege. The CM Synergy Learning Guide enables users to learn about CM Synergy by using objects in a populated tutorial database. Youll need to create a tutorial database for each new user by using the tutorial setup script. The script creates a personal tutorial database for the specified user and sets up the environment and permissions needed to run the tutorial. The tutorial setup script does the following: Unpacks a tutorial database. For Windows server users, the database is called: db_prefix_t. For UNIX server users, the database is called: db_prefix_tut. db_prefix is the prefix that you give the database when you unpack it. The prefix can be a maximum of four characters, and is usually the users name or initials. For example, a typical Windows tutorial database is called: lynn_t. For UNIX, the tutorial database usually is called lynn_tut. Adds the user to the database and adds all of the CM Synergy roles that the user will need. Note: You must know the users log-in name and the database prefix. You can obtain both pieces of information from the person who will use the tutorial database. Windows Server Users 1. Log in as user ccm_root on the database server machine (i.e., where the Main Server or an Additional Server is running).

CM Synergy Learning Guide

99

Appendix A: Unpack the Tutorial Database

2. 3. 4. 5.

Bring up the DOS command shell. Set CCM_HOME to your CM Synergy installation area. ccm_root> set CCM_HOME=CCM_install_area Set PATH to the CM Synergy installation area. ccm_root> set PATH=%CCM_HOME%\bin;%path% Run the tutorial setup script. ccm_root> tutsetup username db_prefix unc_dbpath username is the users log in. db_prefix is the database prefix that can be up to four characters long. unc_dbpath is the path of an existing directory to where you want the setup script to place the users tutorial database. You must enter the path in the universal naming convention (UNC) format, and the existing directory must be writable by user ccm_root. The Startup Info dialog displays.

6.

Start a session by entering the user name and password for user ccm_root. After the session starts, the Project View will display, but you dont need to do anything with it. The script needs the tool to be running. When the script finishes, it will exit from the session. During setup, several tasks will be created for the user. When tasks are created, a mail message is sent to the user to inform him that hes been assigned a task. The first time CM Synergy tries to send the user a mail message, you will receive a message stating the following.
A CM Synergy operation that requires mail to be sent was performed for the first time. You must configure ccm_mail by selecting the type of mail protocol to use. Do you want to configure ccm_mail now? Y N

Click N (No) because you dont need to send mail to or receive mail from the tutorial database. A completion message displays when the setup is finished. If the tutorial fails for any reason, a message will be written to the tutsetup.log file describing the required changes. When complete, the tutorial setup script creates the tutorial database and places it in the location you specified in step 5. Users will need to know where this is so that they can designate the area in their Telelogic Startup Info dialog. (Theyve been prompted to go to you for this info.) Enter it here:

100

CM Synergy Learning Guide

____________________________________________ 7. 8. Exit from user ccm_root. Tell the user the name and location of his tutorial database.

UNIX Server Users 1. 2. 3. Log in as user root or as the user whose home directory you need to change. Change to the users home directory. Set permissions on the users UNIX home and pt directories so that ccm_root has write permission.
$ chmod 777 . $ mkdir pt $ chmod 777 pt

4. 5. 6. 7.

Exit from user root. Log in as user ccm_root.


$ su - ccm_root

Perform a remote log-in to the database server machine.


$ rlogin db_server_machine

Set your CCM_HOME and PATH environment variables.


$ CCM_HOME=ccm_dir; export CCM_HOME $ PATH=$CCM_HOME/bin:$PATH; export PATH

The ccm_dir variable is the CM Synergy installation directory. 8. Run the tutorial setup script.
ccm_root$ tut_setup username db_prefix

username is the users log in. db_prefix is the database prefix. A completion message displays when the setup is finished. If the tutorial fails, a message will display describing the required changes. When complete, the tutorial setup script creates the tutorial database and places it in the users home directory. Users will need to know where this is so that they can designate the area in their ccm start command. (Theyve been prompted to go to you for this info.) Enter it here: ____________________________________________ 9. Exit from the database server machine.

10. Exit from user ccm_root.

CM Synergy Learning Guide

101

Appendix A: Unpack the Tutorial Database

11. Tell the user the name and location of the database. 12. Log in as user root or as the user whose home directory you need to change back. 13. Change to the users UNIX home directory. 14. Restore permissions to the users UNIX home directory to the previous settings.
$ chmod 755 .

15. Exit from user root.

102

CM Synergy Learning Guide

Index

Index
A
assigning tasks 54

conventions menu paths 5 typeface and symbol 3 creating new directory 67 new object 65 new project 66

B
browsing projects 12 building your product 55

D
database add object to project from 73 check out object from 48, 54 reconnect to 60 remove objects from 76 search for objects in 68 update project from 34 use object from 45 default task associate object before checkin 83 associate object with 52 check in 44, 83 check out 47 in Project View 43 new, created by merge 87 set 41 deleting objects Find Use operation 80 from database 78 delimiter for options (CLI) 5 directory, project 45 add object to 73 check in 85 create 67 states of 74 unuse objects from 76 disconnected, see working disconnected

C
ccm_root tutsetup 99 ccminit file options 23 checking in default task 44, 83 errors 85 project directory 85 checking out add comment 48 directory during unuse 76 during migrate 96 object 47 similar to RCS 47 similar to SCCS 47 subprojects 32 view properties 22 working state 33 checkpoint state 25, 55 color change settings 23 in project directory 74 comments add to object 52 create objects 65 enter in Properties dialog 19 connecting enter database path 10 enter engine host name 10 worksheet 8

E
editor, text 5 exit from CM Synergy 98

CM Synergy Learning Guide

103

Index

F
Find Use operation 71, 80 folders 37 four-part name for objects 75

N
naming objects 75

O
objects add comment to 65 associate with default task 52 create new 65 delete 78 find projects that use 71 merge two 86 reference form 75 remove 76 search for 68 types 65 unuse 76 use 45 Open Project browser, how to use 12 option delimiter,(CLI) 5

H
help menu (GUI) 16 History View from Query dialog 71 how to use 21 merge objects in 86 toolbar 29 history, view object 21 how to Migrate From browser 94 open project 31 use pop-up menu 18

I
icons, how to use 28 instances in History View 75 object 46 view in Properties dialog 75 integrate state 74, 86, 96

P
parallel versions merge 86 merge multiple 89 on check out 47 task checkin 84 pop-up menu 18 Project View color settings 23 default task in 43 find project name in 11 how to use 12 toolbar 11, 28

M
mail, task assignment 42 menu paths, guide 5 menu, pop-up 18 merging objects 86 Message View for reconcile 60 for reconfigure 34 migrating object type 96 preview project 95 projects into CM Synergy 93 role required for 93 rules for 97

104

CM Synergy Learning Guide

Index

projects add object to 73 browse 12 find in Project View 11 open from Query dialog 71 reconcile 60 reconfigure 34 reuse 91 search for 68 states of checkpoint 25, 55 integrate 74, 86, 96 released 74 working 33, 47, 52, 55, 74, 78, 89, 91, 96 update with latest changes 34 up-to-date projects 37 prompt in CLI 5 properties enter comments in 19 modify object 52 view from History View 22 view object (file) 18 view project 19 Properties dialog how to use 19 modify 52 view object instance in 75

reconcile disconnected work 58 from work area 60 reconfigure folders 37 for unit testing 81 how to use 34 project, subprojects 34 properties 38, 91 templates 40 the big picture 38, 39 update properties to reuse project 91 view properties of 36 reconnect to CM Synergy, see reconcile release change for object 52 query for 68 released state 74 role change in Project View 14

S
SCCS, CM Synergy check out similar to 47 script, tutorial setup 99 search database, see queries Select Task button 41 starting CM Synergy Startup Info dialog 9 states add object to project 73 checkpoint 25, 55 integrate 74, 86, 96 project directory 74 released 74 working 33, 47, 52, 55, 74, 78, 89, 91, 96 subprojects check out 32 update 34

Q
queries format 71 save to file 71 sort 71 using objects 68 Query dialog from other dialogs 71 using objects 68

R
RCS, CM Synergy check out similar to 47

CM Synergy Learning Guide

105

Index

T
tasks assign 54 check in 83 default 43 folders 37 templates, reconfigure 40 text editor 5 toolbar in History View 29 in Project View 11, 28 tutorial setup script 99 type new object 65 object, in migrate 96 query object 68

V
versions change object 52 check most recent 21 decimal numbering in 48 parallel 48 unuse object 76 use object 45 viewing history of objects 21 object (file) properties 18 object versions 50 projects 12, 71 reconcile messages 60 reconfigure messages 34

U
unit testing 45, 81, 86 unusing objects object versions 76 unused objects at task checkin 84 updating build manager 37 for unit testing 81 on checkout 47 project 60 the big picture 39 your project 34 using objects object versions 45 Recommend operation 46 vs. reconfigure 81

W
work area find path of 56 update 34 working disconnected create the object in database 65 edit file offline 56 working state 33, 47, 52, 55, 74, 78, 89, 91, 96

106

CM Synergy Learning Guide