serena changeman ds user guide

Serena® ChangeMan® DS

User’s Guide

Copyright © 2001–2005 Serena Software, Inc. All rights reserved.This document, as well as the software described in it, is furnished under license and may be used or copied only in accordance with the terms of such license. Except as permitted by such license, no part of this publication may be reproduced, photocopied, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, recording, or otherwise, without the prior written permission of Serena. Any reproduction of such software product user documentation, regardless of whether the documentation is reproduced in whole or in part, must be accompanied by this copyright statement in its entirety, without modification.The content of this document is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Serena. Serena assumes no responsibility or liability for any errors or inaccuracies that may appear in this document.

TrademarksSerena, TeamTrack, StarTool, and ChangeMan are registered trademarks of Serena Software, Inc. The Serena logo is a trademark of Serena Software, Inc.Merant, PVCS, and Collage are registered trademarks of Merant Inc. Dimensions, Professional, Tracker, Version Manager, Builder, Meritage, and Mover are trademarks of Merant, Inc.All other products or company names are used for identification purposes only, and may be trademarks of their respective owners.

U.S. Government RightsAny Software product acquired by Licensee under this Agreement for or on behalf of the U.S. Government, its agencies and instrumentalities is "commercial software" as defined by the FAR. Use, duplication, and disclosure by the U.S. Government is subject to the restrictions set forth in the license under which the Software was acquired. The manufacturer is Serena Software, Inc., 2755 Campus Drive, San Mateo, CA 94403.

Part number: MA-DSINST-003

Publication date: 6/28/05

CONTENTS

About This BookObjective 17Audience 17Manual Organization 17Related Documents 20

Accessing the Documentation 20Using the Online Manuals 21

Online Help 22Section 508 Compliant Help 22

Chapter 1: IntroductionChangeMan DS Overview 23

Multi-Site Development Environments 23Process Definition and Enforcement 24

Serena ChangeMan Product Compatibility 24Support for Serena Enterprise Change Packages 24

Chapter 2: Product OverviewArea Management 28Process Flow Control 28Software Change Control 29Security and Approvals 30

About User Permissions 30Projects and Subprojects 31Package-Oriented Approach 31Build and Release Management 32Reporting 32Terminology Concepts 32Architecture 33

3

4

Contents

Conversion Utilities 36System Requirements 36

Chapter 3: Getting StartedAbout ChangeMan DS Clients 37Accessing ChangeMan DS with the Windows Client 38Accessing ChangeMan DS with the Web Browser Client 38Accessing ChangeMan DS with the Java Client 39Reconnecting to ChangeMan DS 40Changing your ChangeMan DS Password 40Exiting ChangeMan DS 41Overview of ChangeMan DS Interface 42

Navigating the Main Window 43

Chapter 4: Adding Files To ChangeMan DS ControlAdding to Control Using DS Control Option 48Adding to Control Using Promote Options 49Removing Files from Control 50Troubleshooting Adding Files To Source Control 51

Chapter 5: Working With FilesEditing the Contents of a File 53Viewing the Contents of a File 54Setting the Editor 55Editing a File with ChangeMan Edit 56Viewing File Properties 57

Chapter 6: Using ProjectsPromoting Projects 63Viewing Projects—Project Filter Screen 64Creating or Editing Projects in the Windows Client 65Creating Projects in the Web Browser and Java Clients 66Editing Projects in the Web Browser and Java Clients 67

Serena® ChangeMan® DS 5.7.1 User’s Guide

Deleting a ChangeMan DS Project 68Copying Project Properties to Another Project 68Defining Projects 70Project Properties 73

Project Type 74Project Status 75Project Priority 75

Project Authorization 76Adding Users or Groups to the Project Authorization List 77Deleting Users or Groups from the Project Authorization List 77Configuring User Permissions for a Project 78

Attaching Files 81Attaching Files to a Project during Configuration 83Attaching Files from the Content Window 84Attaching Files using Drag-and-Drop 84Removing Files from a Project During Configuration 85Removing Files from a Project Through ExplorerView 86Viewing Status of Attached Files 86

Working Location 87Setting Project Working Location 88Project Working Location View 88

Relative Path 90Setting Relative Path 90

Subprojects 91Attachment Rules for Subprojects 92Subproject Promotion Behavior 92Example Subproject Schemes 92

Chapter 7: Transferring Files and ProjectsCompleting the Transfer Request Dialog 96

Scheduling On-line or Off-line Transfers 97Adding a Description to a Transfer 98Associating a Project with Transferred Files 98Associating Source Control Operations with TeamTrack Items 98

5

6

Contents

Modifying the List of Files Being Transferred 98Transfer Process 99File Transfer Request Status Dialog 104Checking Out 105

Checking Out Files 106Checking Out Files by Choosing a Folder 106Checking Out Files Using a File List 107Issuing a Second Check Out Request for a File 108Checking Out a Previous Version of a File 109Canceling a Check Out Transaction for a File 110Checking Out a Project 110Issuing a Second Check Out Request for a Project 112Canceling a Check Out Transaction for a Project 113

Checking In 114Checking In Files 115Checking In New Files 116Checking In the Same Version of a File 116Checking In a Project 117

Promoting 119Promoting Files 120Promoting a Project 121

Distributing 123Interactive Distribution of Files 124Interactive Distribution of a Project 125Automatic Distribution by Implementation Script 126Automatic Distribution by Post Compile Option 127Automatic Distribution by Command Line Interface 128

Permissions Required to Transfer Files 128Troubleshooting File and Project Transfers 128

Chapter 8: BranchingCreating a Branch of a File During Check Out 135Creating a Branch of a File During Check In 137Creating a Branch of a Project 139


Creating a Branch of a Release 140

Chapter 9: Comparing FilesComparing Files with the Show Differences Command 144Comparing Files from the File Tree 144Comparing Files from an Audit Trail Report 145Text-Based Comparisons 147Text-Based and Binary Files 148

Locale Setting 149Microsoft® Word Document Comparisons 149

Changing Display Colors 150Closing the ChangeMan Word Diff Utility 150Merging Files during ChangeMan Word Diff Comparison 150Navigating Changes 151

Chapter 10: MergingMerging from the File Tree 154Merging as Part of Check In 155Merging as Part of Synchronization 156Completing the ChangeMan DS Merge Dialog 157Target Rules for Merging 159Interactive Merges with Text-Based Files 160Interactive Merges with Microsoft® Word Documents 162

Accepting/Rejecting Changes in ChangeMan Word Diff 163Saving and Exiting from ChangeMan Word Diff After Merging 163

Automatic Merge Rules 163Canceling a Merge 164

Chapter 11: Synchronizing

Chapter 12: Managing BuildsMake Procedures 170Build Options 171

7

8

Contents

Creating a New Make Procedure 173Modifying Existing Make Procedures 174

Defining Make Procedure Properties 175Defining Make Procedure Pre Compile Script 177Defining Make Procedure Global Compile Script 178Defining Make Procedure Post Compile Script 180Make Procedure Targets 181Make Procedure Dependencies 184Examples of Build Scripts 187

Initiating the Build Process 189User Login Information for the Build Host 191

Build History 192Reviewing Build History 192Understanding the Build History 193Sending the Build History to a Log File 194Locating Build Information Storage 194Deleting the Build History 195

Importing a Make File 196Exporting Make Procedures 200Troubleshooting Builds 201

Chapter 13: Managing ReleasesCreating Frozen Releases 203Promoting a Release 206Rolling Back a Release 206Modifying a Release 207

Detaching a File from an Existing Release 207Attaching New Files to an Existing Release 208Changing Properties of a Frozen Release 208

Maintaining (Branching) a Release 209Changing the Properties for a Frozen File 209Troubleshooting Releases 210


Chapter 14: ReportingViewing File Information from the File Tree 211Audit Trail 213

Running Audit Trail Reports 213Viewing the Audit Trail for One File 214Creating an Audit Trail Report with a Query 215Saving a Query 216Creating an Audit Trail Report Using a Saved Query 217Viewing an Audit Trail from an IDE 217Query Criteria for an Audit Trail 217Working with Audit Trail Reports 222Troubleshooting Audit Trail 226

Impact Analysis 227Performing Impact Analysis 228Alphabetical Impact Analysis 228Itemized Impact Analysis 229Working with Impact Analysis Results 230Troubleshooting Impact Analysis 233

Chapter 15: Approving File TransfersApproving a Pending Transaction from ExplorerView 238Approving a Pending Transaction from an Audit Trail Report 239Rejecting a Pending File Transfer 240Viewing the Sign-off History of a File 241

Chapter 16: Package-Oriented ApproachUsing the Package-Oriented Approach 244Accessing Package-Oriented Functionality 247Applications 248

Creating an Application 250Adding Specifications to an Application 250Attaching Projects to an Application 251Attaching an Area to an Application 252Creating a Default Area Configuration 254

9

10

Contents

Working with an Application’s Projects 255Packages 255

Package Configuration Screen 255Creating a Package 261Adding Specifications to a Package 262Attaching Projects to a Package 263Attaching an Area to a Package 264Linking Packages 266Adding Files to a Change Set 267Adding a Contact (or Requester) to a Package 269Establishing a Hierarchy for Packages 270Dependencies between Packages 271Promoting a Package 276Promotion Types for Packages 278Editing Files in a Package 279Freezing Files of a Package 282Life Cycle States for Packages 284Creating Scripts for Package Installation 286Viewing Installation History of a Package 289Searching for Packages 290Saving a Package Search 292

Setting Security Permissions for POA 292Approvals in POA 295

Creating an Approval Process 295Approving Packages 296Creating an Approval Group in POA 298Adding and Removing Users from an Approval Group 298Setting the Approval Order for Packages 299Specifying a Password for Approvals in POA 299Configuring Notifications for Approvals 300

Data Sources 306Approval Data Sources 308

Notifications 311Creating a Notification 312Activity/Event Drop-Down List for Notifications 314


Notification Data Source 314

Chapter 17: Host ViewInformation Displayed in Host View 323

Viewing the List of Commands Available on the File Level 324Exploring a UNIX Host 324

Configuring the Host View 325Adding a Host 326Removing a Host 327

Managing Heterogeneous Hosts 327Managing Properties for Files and Directories 327

Managing File Properties on a UNIX Host 328Modifying Directory Properties on the UNIX Host 329

Chapter 18: OS/400 EnvironmentsUsing the AS/400 Communication Agent 331Make Behaviors for AS/400 332Transfers in AS/400 333Scripting Behavior for the AS/400 334Scripting Examples for AS/400 335

Copying a File Between Directories in "/QSYS.LIB" System 335Compiling a Member in "/QSYS.LIB" System 336Distributing a Member in "/QSYS.LIB" System 336Sending a Message in "/QSYS.LIB" System 337Copying a File Between Directories on Root File System 337Forcing Native Area Script Execution 337

VCS Variables for AS/400 338 339

Appendix A: TroubleshootingInstallation 341Determining Software Versions 343Connecting to ChangeMan DS 344Web Browser Client 344

11

12

Contents

345

Appendix B: User Interface ReferenceContent Window 347

Selecting Areas or Projects Node in Explorer 348Selecting an Area Type in Explorer View 348Selecting a User-Created Area or Project in ExplorerView 348Selecting a Directory Node in ExplorerView 349Selecting a Project Type Node in ExplorerView 350Selecting a Frozen Release Node in ExplorerView 350Selecting a Make Procedure Node in ExplorerView 351Selecting the Attachments Node in ExplorerView 351Status Icons 353

Windows Client UI 357Main Window Menus—Windows Client 357Main Window Toolbars—Windows Client 365System Configuration Dialog 374ChangeMan DS Project Configuration Dialog 376ChangeMan DS Area Configuration Dialog 377Impact Analysis Module 377

ChangeMan DS Java Client and Web Browser Client UI 380ChangeMan DS Web Client 383Display Permissions for Web Browser and Java Clients 384Changing Status Options 385Toolbar Buttons 385Right-Click Menus 393

Performance Monitor 397File Tree UI 400ChangeMan Diff Menus and Toolbar 402

File Menu—ChangeMan Diff 403Edit Menu—ChangeMan Diff 404Merge Menu—ChangeMan Diff 405Tools Menu—ChangeMan Diff 406View Menu—ChangeMan Diff 407View Options—ChangeMan Diff 408


Diff Menu—ChangeMan Diff 409ChangeMan Edit Menus and Toolbars 410

See “ChangeMan Edit Module” on page 437 for more information on ChangeMan Edit.File Menu—ChangeMan Edit 411Edit Menu—ChangeMan Edit 411Find Toolbar—ChangeMan Edit 412View Menu—ChangeMan Edit 413Window Menu—ChangeMan Edit 413Tools Menu—ChangeMan Edit 414

Appendix C: ChangeMan Diff ModuleAccepting/Rejecting Changed Lines during a Merge 430Accepting/Rejecting Inserted Lines during a Merge 430Altering the Display Mode 430Changing Display Options 431Changing Text Background Colors in ChangeMan Diff 431Editing the Merged File in ChangeMan Diff 432Merging the Files from a Comparison 432Navigating Changes during Merge in ChangeMan Diff 433Performing a Comparison while Merging Files 433Redoing a Comparison in ChangeMan Diff 433Redoing a Merge in ChangeMan Diff 433Selecting Templates 433Saving and Exiting the Merge 434Selecting Templates for ChangeMan Diff 434Synchronizing Displayed Lines in ChangeMan Diff 434Toggling Display of Map and Status Bar 435

Appendix D: ChangeMan Edit ModuleEditing Text in a Code Window 438

Copying a Selection Using Commands 439Copying a Selection Using the Drag-and-Drop Method 440Finding Text 440Moving a Selection Using Commands 441Moving a Selection Using the Drag-and-Drop Method 441

13

14

Contents

Navigating the Text in Code Window 441Replacing Text 443Undo and Redo Commands 443

Using Bookmarks 444Placing a Bookmark 444Removing a Bookmark 445Navigating to Bookmarks 445

Impact Analysis from ChangeMan Edit 445Running a Remote Command 446Compiling a File 447Compile Result Script 448

Configuring Compile Result Script 449Viewing Next Error or Warning 450Clearing Compile Command Results 450

Saving a File 451Saving File with Original Name 451Saving a File Under a Different Name 451

Creating a New File 451Toggling Display Items 452

Displaying Line Numbers 453Displaying Marker Bar 453Displaying the Ruler 454Displaying the Status Bar 454

ChangeMan Edit Variables 455Template Manager 456

Opening the Template Manager 456Creating a New Template 457Copying a Template 458Deleting a Template 458Modifying a List of Keywords 458Configuring Auto Line Numbering 459Changing Colors 460Template Manager Tabs 460

TroubleshootingChangeMan Edit 465


Glossary 467

Index 477

15

16

Contents

ABOUT THIS BOOK

This document describes 5.7.1 of Serena® ChangeMan® DS, a product of Serena® Software, Inc. The product may also be referred to as Software Change Manager for Distributed Systems, or ChangeMan DS.

ChangeMan DS is a process-oriented software change management (SCM) tool that lets you control software development, maintenance, and distribution activities across multiple platforms and locations.

By automating the software development life cycle, ChangeMan DS prevents overlays in parallel development, manages source code, manages builds across platforms, manages distribution, and maintains comprehensive audit trails.

OBJECTIVEThis document describes how to use ChangeMan DS for your SCM-related tasks. Refer to “Related Documents” on page 20 for documents that describe the installation, configuration, and administration of the product.

AUDIENCEThis document is intended for ChangeMan DS users, including system administrators, software developers, system engineers, and customer support staff.

MANUAL ORGANIZATIONThis document is organized as follows:

Chapter Description

1. Introduction to ChangeMan DS.

2. Overview of ChangeMan DS functionality.

17

18

About This Book

3. Logging in to ChangeMan DS and an overview of the ChangeMan DS main window.

4. Adding files to control.

5. Working with files in ChangeMan DS.

6. Using and maintaining projects in ChangeMan DS.

7. Checking in, checking out, promoting and archiving files and projects.

8. Branching files and projects.

9. Comparing files within ChangeMan DS.

10. Merging files with ChangeMan DS.

11. Synchronizing files within ChangeMan DS.

12. Describes build functionality.

13. Describes release-related functions such as build, freeze, and rollback.

14. Using reporting functionality in ChangeMan DS such as Filer Tree, Audit Trail, and Impact Analysis.

15. Approving file transfers.

16. Using the ChangeMan DS Package Oriented Approach.

17. Using Host View, an easy-to-use GUI-based file manager for UNIX platforms.

18. Using ChangeMan DS on AS/400 hosts.

Appendix A

Some common troubleshooting issues.

Appendix B

Reference of the ChangeMan DS User Interface including items such as toolbar buttons and menu items.

Appendix C

Using ChangeMan Diff.

Chapter Description


Note

While every effort has been made to updates screenshots and icons to match the new icons in ChangeMan DS, some graphics may still show legacy images.

Appendix D

Using ChangeMan Edit.

Glossary Glossary of ChangeMan DS terms.

Index Index of ChangeMan DS subjects.

Chapter Description

19

20

About This Book

RELATED DOCUMENTS

Accessing the DocumentationAll documentation is included on the software distribution CD in Adobe Portable Document Format (PDF) format.

To access the documentation on the CD, open the Documentation folder.

The documentation is also available from support.serena.com.

Title Description

Serena® ChangeMan® DS Administrator’s Guide

Configuration information on Serena® ChangeMan® DS, the Software Change Manager for Distributed Systems.

Serena® ChangeMan® DS Command Line Interface Guide

Guide to using the Serena® ChangeMan® DS command line interface.

Serena® ChangeMan® Conversion Guide

Guide to converting from other source control applications to Serena® ChangeMan® DS.

Serena® ChangeMan® DS Installation Guide

Installation information on Serena® ChangeMan® DS.

Serena® ChangeMan® DS Integration Guide for Microsoft® Visual Studio® .NET™

Guide to integrating Microsoft Visual Studio .NET with ChangeMan DS.

Serena® ChangeMan® DS Integration Guide for Sybase® PowerBuilder®

Guide to integrating Sybase PowerBuilder with ChangeMan DS.

Serena® ChangeMan® DS Integration Guide for Eclipse and IBM® WebSphere® Studio

Guide to integrating Eclipse and IBM WebSphere Studio with ChangeMan DS.

Serena® ChangeMan® DS Integration Guide for Borland® JBuilder®

Guide to integrating Borland JBuilder with ChangeMan DS.


Using the Online ManualsThe Serena online manuals use the Adobe Portable Document Format (PDF). To view PDF files, use Adobe® Reader®, which is freely available from www.adobe.com.

Tip

Be sure to download the full version of Reader. The more basic version does not include the search feature.

This section highlights some of the main Reader features. For more detailed information, see the Adobe Reader online help system.

The online manuals include the following features:

• Bookmarks. All of the online manuals contain predefined bookmarks that make it easy for you to quickly jump to a specific topic. By default, the bookmarks appear to the left of each online manual.

• Links. Cross-reference links within an online manual enable you to jump to other sections within the manual and to other manuals with a single mouse click. These links appear in blue.

• Printing. While viewing a manual, you can print the current page, a range of pages, or the entire manual.

• Advanced search. Starting with version 6, Adobe Reader includes an advanced search feature that enables you to search across multiple PDF files in a specified directory. (This is in addition to using any search index created by Adobe Catalog—see step 3 below.)

To search within multiple PDF documents at once, perform the following steps (requires Adobe Reader version 6 or higher):

1. In Adobe Reader, select Edit > Search (or press CTRL+F).

2. In the text box, enter the word or phrase for which you want to search.

3. Select the All PDF Documents in option, and browse to select the folder in which you want to search. (If you have a document open that has an Adobe Catalog index attached, you can leave the In the index named... option selected to search across all the manuals in the index.)

4. Optionally, select one or more of the additional search options, such as Whole words only and Case-Sensitive.

5. Click the Search button.

21

22

About This Book

Note

Optionally, you can click the Use Advanced Search Options link near the lower right corner of the application window to enable additional, more powerful search options. (If this link says Use Basic Search Options instead, the advanced options are already enabled.) For details, see Adobe Reader's online help.

ONLINE HELPThe online Help is the primary source of information about ChangeMan DS. The online Help includes:

• Overviews of key elements within the application

• Detailed procedures for completing tasks.

You can open the online Help by

• Pressing F1.

• Holding down the left-mouse button on a menu command or toolbar icon, and then pressing F1 (Windows client).

• Choosing Index from the Help menu.

• To view command-level help, click on the toolbar, then click the menu command or button about which you want information (when available).

Section 508 Compliant HelpSection 508 is part of the Rehabilitation Act of 1973 that requires Federal agencies to use software that provides access for people with disabilities. A version of the Help system is available with Section 508 compliant navigation.

To enable the Section 508 compliant navigation in your online help:

1. Open the ChangeMan DS online help (Help > Index)

2. Find the topic Making Your Help Accessible. The topic is located in the Welcome to ChangeMan DS section.

3. Click the link and follow the instructions.

INTRODUCTION
1 This chapter introduces you to Serena® ChangeMan® DS, compatible Serena® ChangeMan® DS products, and new features available in this release.
CHANGEMAN DS OVERVIEWChangeMan DS addresses critical issues throughout the software development life cycle across Windows®, Web, UNIX®, Linux®, and OS/400® environments, from a single point of control.

ChangeMan DS provides version control and cross-platform build management. It manages specific projects and lets you reuse components, repeat builds, and maintain development standards and application quality. It is an infrastructure tool that regardless of project size or complexity, brings order, audit ability, and automation to all your development projects.

ChangeMan DS gives a comprehensive approach to controlling and tracking changes to software components. It supports the development life cycle as changed components move from one stage in the process to another.

A graphical user interface facilitates project creation, check-out and check-in, source code changes, multiple version merging, impact analysis, rollbacks, approvals, promoting to QA, build and release management, software distribution and audit trails. It adapts to your existing processes, yet lets you create and enforce your desired development strategies. IDE integration allows developers to work in their IDE of choice with a minimum of additional training.

Multi-Site Development EnvironmentsChangeMan DS lets you create a multi-site development environment in which your developers access and manage source components across multiple platforms. From any supported platform or IDE, developers are able to:

• Check in and check out source code.

• Manage approvals.

23

24

Chapter 1: Introduction

• Conduct pre-change impact analysis.

• Describe and maintain a migration path for earlier versions of components.

• Manage builds.

Project leaders track versions of source code, maintain an audit trail of code changes, automate promotion across the life cycle, and set user and project workflows and guidelines.

Using ChangeMan DS, developers can automate releases, builds, and software distribution. Based on how ChangeMan DS is implemented, developers can work concurrently on the same source code by branching and merging, and maintain source-code-to-executable links.

The ChangeMan DS architecture allows all software assets to remain on their original platforms and in their original formats and file systems – close to the people who are using them. The central administrative server is attached to a metadata repository, which contains information on process flow, configuration, impact analysis, audit, and administration information only. This scheme minimizes space requirements and allows efficient, real-time access to files and information across platforms, so changes can be managed as they occur.

Process Definition and Enforcement ChangeMan DS lets you define your business processes through a graphical interface. By dragging icons and drawing arrows across a workspace, project management can determine how files will be handled at the global (product), application (group or version) and individual project level. The resulting processes are implemented as a set of rules which impose permissions for user interaction and govern code movement from the baseline repository to development work areas, QA test and eventually end-user production environments.

SERENA CHANGEMAN PRODUCT COMPATIBILITYThis section describes other Serena ChangeMan products that ChangeMan DS integrates with.

Support for Serena Enterprise Change PackagesThe Enterprise Change Packages capability is a result of integration between ChangeMan DS and Serena® ChangeMan® ZMF. The solution enables centralized management of software assets across all major platforms, from mainframe to Web,


by programmatically linking distributed and mainframe development environments from a central management point. This minimizes reliance on lengthy meetings, e-mails and other cumbersome, manual, error-prone methods of managing enterprise change. Using Enterprise Change Packages increases software quality and achieves unmatched flexibility in resource deployment, maximizing IT investments. Enterprise Change Packages are the most recent step in Serena's ongoing execution of its vision of a truly seamless Enterprise Change Management solution that manages code and content from mainframe to Web.

25

26

Chapter 1: Introduction

PRODUCT OVERVIEW
2 This chapter introduces you to the main concepts of Serena® ChangeMan® DS, and it explains how it is used to provide Software Change Management (SCM) to your software development environment.
Serena® ChangeMan® DS addresses SCM concerns with the following functionality:

• Area Management, which lets you specify locations where files are stored and what purposes the locations serve.

• Process Flow Control, which controls the flow of files or projects from one area to another. You can design your process flow to verify that the desired work is done to the software components before it advances to the next phase in the development life cycle.

• Software Change Control, which manages with software components with features such as versioning your Production area files, notifications of file tampering, and team development procedures.

• Security and Approvals, which lets you set permissions on which files, projects and areas users have access. Approvals require that certain users sign off on a file transfer before the transfer can occur.

• Projects and Subprojects, which lets you group related files so that they can promoted and frozen as a unit.

• Package-Oriented Approach, which adds more granularity to the grouping of related files and lets you define a specific change set. You can then promote that change set through a life cycle.

• Build and Release Management, which lets you automatically build applications across distributed hosts and heterogeneous platforms and allows all components of a project at a given point in time to be labelled as a single entity.

• Reporting, which lets you create informational reports such as an audit trail report which tells you what actions were performed on a file and who performed the actions.

27

28

Chapter 2: Product Overview

AREA MANAGEMENTChangeMan DS manages the location of files by using areas. Areas define physical repositories of source code. An area can reference any directory or directory structure as long as the required Communication Agent is running on the host.

ChangeMan DS combines area management and version control functions that enable you to transfer files between source and target areas in the software development life cycle, and maintain copies of previous versions of files as they are checked into Production areas.

ChangeMan DS allows four different types of areas: Production, Development, Quality Assurance, and End User. Each type of area has different properties and serves a specific purpose. For example, users can’t edit files in a Production area.

Each file that is placed under ChangeMan DS control needs a Home (Production) area. This area is where the baseline file will be stored, and the ChangeMan DS versioning takes place. The file’s Home area determines the reference point for whether you are checking in (replacing a file in its Home (Production) area) or checking out (copying file to a Development area).

The areas that you have access to can be displayed by expanding the subnodes under the Areas node in ExplorerView.

See “Areas” in the Serena® ChangeMan® DS Administrator’s Guide for more information on areas and area types.

PROCESS FLOW CONTROLChangeMan DS lets you define controls and workflows to manage development policies and procedures throughout the software development life cycle.

Software components are packaged and moved through process workflows that support user roles and responsibilities and maintain the appropriate approvals process. On a global, application, or project basis, ChangeMan DS gives you the ability to define workflows to support the policies and practices that are appropriate for your organization.

For example, you may require that all edited files be transferred to QA area before being allowed to be placed back into the Production area.

Embedded policies also define how components are promoted, including when promotion is permissible, and where components get promoted.


If you have the appropriate permissions, you can view and edit process flows on the Process Configuration dialog.

See “Process Flow” in the Serena® ChangeMan® DS Administrator’s Guide for more information on process flow.

SOFTWARE CHANGE CONTROLChangeMan DS helps you manage your software changes with features such as file versioning, file tampering recognition, and team development utilities.

Software change management starts with controlling your source control.

Begin your SCM activities by placing your files under ChangeMan DS control. When you place a file under control, its original Production area is called its Home area. These files can be associated with a project to group to the related files. Users cannot edit files while they are located in the Production areas.

The controlled files are checked out, promoted between Development and QA areas in the development life cycle, then checked back in to Production. At this point, ChangeMan DS increments the file versions and stores the archives. Finally, the executable files are distributed to End User areas.

In ChangeMan DS, “promote” refers to all transfer activities: check in, check out, transfer, and distribute. Each type of promotion invokes the transfer request process, but the results of the request depend on the specific promote type, and the origin and target areas involved in the request.

You can perform these actions either at the file level or the project level. To do project level promote activities, you must be authorized to perform both file and project level SCM activities at either the user or group level via the user configuration module.

ChangeMan DS notifies you if someone tampers with a Production area file outside of ChangeMan DS by changing the file’s status icon changes to red.

ChangeMan DS supports team development processes such as allowing multiple users to check out the same file (concurrent check outs) or creating a second line of development (branching). When you have different versions of the same file from a branch or concurrent check out, you can use the ChangeMan Diff module to compare or merge the versions into one file. Then, the merged file can be placed back into production.

You embed policies to define who can see, who can work upon, and who can promote components.

29

30


SECURITY AND APPROVALSChangeMan DS has many layers of security. For example, ChangeMan DS lets you transfer files and projects between only those source and target areas for which you have permissions to carry out file transfer activities.

Administrators control who can access ChangeMan DS by assigning ChangeMan DS user IDs, and they define what permissions that user has in ChangeMan DS such as access to ChangeMan DS areas and projects. See “About User Permissions” on page 30.

On a global, application, or project basis, ChangeMan DS gives you the ability to define user, area, and project permissions to support the practices that are appropriate for your organization.

ChangeMan DS lets you require certain people to approve a transfer before the files are allowed to be transferred to the target region. Files will not be transferred to the target area until all of the required approvals are given. You establish the sequence in which the sign-off process should take place. When one person approves the request, ChangeMan DS sends e-mail to the next group of people, letting them know that it is now their turn to sign off the request.

About User PermissionsEvery ChangeMan DS user must have a ChangeMan DS user account created for them by the ChangeMan DS administrator. The administrator controls a user’s access by granting and denying rights to user accounts.

ChangeMan DS lets administrators grant individual rights to the user, or group rights (by making the individual into a member of a group).

In general, three groups of users exist (which can be modified for your environment):

• Administrators, who initially configure and manage ongoing configuration of ChangeMan DS.

• Power Users, such as Project Managers, who perform some administrative duties and manage projects, builds, and releases.

• End Users, such as Developers, Technical Communicators, QA Testers, who carry out development life cycle tasks within the control of ChangeMan DS.


PROJECTS AND SUBPROJECTSChangeMan DS lets you manage logical relationships in real-life projects through its project/subproject structure. Projects are collections of related files; subprojects are projects within projects. A parent project can contain multiple child subprojects, and a child subproject can be the parent of additional child subprojects.

Using the project/subproject divisions simplifies the organization and management of a large project shared by several developers whose work must come together to form the finished release.

You can use the project/subproject structure to:

• Control the overall view of files.

• Promote groups of related files.

• Freeze a release of related files.

• Perform a build of related files.

Configure your project/subproject structure to produce whatever view you want. Following consistent rules for attaching files to projects across your company helps increase your overall efficiency.

The projects that you have access to can be displayed by expanding the subnodes under the Projects node in ExplorerView.

See “Using Projects” on page 63 for more information.

PACKAGE-ORIENTED APPROACHChangeMan DS offers two levels of file organization, projects and packages.

Introduced in ChangeMan DS Version 5.4.1, the Package-Oriented Approach (POA) provides a way to manage change packages for your software throughout the change life cycle, so that the work being done at each phase is visible and approved before going forward.

POA enhances the project-level behavior of ChangeMan DS, taking change management to a higher level of organization.

POA is available through the Web and Java client, and it can be used in solely ChangeMan DS, or in conjunction with other Serena SCM products, such as ChangeMan ECP.

See “Package-Oriented Approach” on page 243 for more information.

31

32


BUILD AND RELEASE MANAGEMENTBuild Management provides distributed build functionality with UNIX and Microsoft-style make files. A typical build compiles and links executables, and generates other intermediate or final interpretable components. ChangeMan DS Build Management helps you to perform consistent builds.

Release Management lets you operate on a “release” level, and treat all components of the release as a single entity. You can use ChangeMan DS to freeze an entire release, promote a release, or perform a rollback to the previous version of a release.

REPORTINGChangeMan DS has the following reporting features to help you manage and track your software files and components:

• File Tree is a graphical depiction of the history of a file. It includes information such as branches and merges that have occurred to the file.

• Audit Trails show you what actions have been performed on a file, and who performed the action. It also shows you the current state of the file and if it requires any approvals.

• Impact Analysis determines which of your software components will be affected when you make a change to your software code.

TERMINOLOGY CONCEPTSThe following terms should be understood to comprehend ChangeMan DS:

Term Definition

software change management (SCM)

A process for controlling and tracking software components.SCM enables a software development team to identify those components of data, documents, and programs that will undergo change; establishes a strict procedure for specifying, evaluating, and approving changes; reports changes; audits changes that are made to ensure that quality has been maintained; and reconstructs the software to accommodate the changes that were implemented.


ARCHITECTUREThe multi-tier, cross-platform ChangeMan DS architecture includes a central Main Server, a central metadata repository, distributed Communication Agents which interface with various source repositories and a choice of user-interface clients. No reconfiguration of processes, network architecture or file locations are required; all activity is managed through the central server.

ChangeMan DS’s unique low-bandwidth architecture and Communication Agents give you the power to:

• Employ geographically dispersed development teams

area A logical name for a physical location in which the software components reside.

process flow Rules in ChangeMan DS that control the transfer of components from area to area. This enforces defined routes that files must follow during the development life cycle.

lifecycle The phases software goes through from when it is conceived, until when it is retired. A lifecycle consists of a number of states, along with transitions between those states: A state is a place where a specific type of activity occurs; a transition is the path between states.

project A logical grouping of software components that are tracked and manipulated during the SCM promotion, build, and release processes.

application Defines a logical grouping of software components that represents a complete entity, such as a software product or a software system. Applications are the highest level of organization of a set of software changes.

package A logical grouping of software components in an application. Multiple packages can be associated with an application. A package is part of only one application, and may be linked to other packages in the same application.Packages are sometimes referred to as change packages or change sets.

Term Definition

33

34


• Team-build and deploy applications across multiple platforms

• Perform impact analysis across platforms

• Execute cross-platform builds

ChangeMan DS creates a ‘virtual single repository’ using Communication Agents. Communication Agents direct builds, transfers, and other activity, and allow components to reside in their existing directories on the machines and platforms of your choice. The network connections are maintained only for the life of the transaction between the nodes, with minimal impact on bandwidth. You can store code anywhere, in non-proprietary formats.

Integration with a wide range of popular IDE tools allows developers to continue working in a familiar environment, with a minimum of additional training. A Web browser client is available to keep developers and management involved in the development life cycle from anywhere on the globe. Security features supplement network security, assuring that software assets are well protected from unauthorized changes. Intermediate Application Layers such as NFS, FTP, or Telnet are not required.


The multi-tier TCP/IP architecture appears as follows:

The major ChangeMan DS components are:

• Main Server - A UNIX or Windows host machine that coordinates SCM activities, including user authentication and transfer request authorizations. The server does not store files; they remain in their native format and in the original directories.

• Metadata Repository - Stores metadata, such as configurations, impact analysis, and detailed audit trail information.

• Communication Agent - A small process running on a host that allows you to your ChangeMan DS areas, which contain your software assets.

• Client - The code that provides the user interface to ChangeMan DS from anywhere in your enterprise, including the Internet. ChangeMan DS clients include:

• Windows

• Web browser

35

36


• Java

• Command line (for use in scripts)

• Supported Integrated Development Environments

About Supported Integrated Development EnvironmentsChangeMan DS integrates with many of the most popular development environments. It enforces all transactions, process flow models, and code change audits without actually launching the ChangeMan DS client when the developers work in their Integrated Development Environment (IDE). This lets developers perform all their day-to-day development activities directly from their favorite IDE.

Integration in ChangeMan DS uses the Microsoft Source Code Control (SCC) interface to seamlessly integrate with other SCC-compliant IDEs. Some of the supported include Visual Basic®, Visual C++®, and Borland® JBuilder™.

Refer to the Serena® ChangeMan® Integrated Products Guide for a complete list of supported IDEs, and details on integrating ChangeMan DS with other development environments, project management tools, and QA test management products.

CONVERSION UTILITIESChangeMan DS includes automated conversion utilities for most version control systems, including:

• SCCS

• RCS

• PVCS Version Manager

• Visual SourceSafe

See the Serena® ChangeMan® Conversion Guide for more details.

SYSTEM REQUIREMENTS For specific platform requirements for the database, server, and client, see the Serena® ChangeMan® Installation Guide.

GETTING STARTED
3 This chapter describes how to get started using ChangeMan DS. It includes information on logging in to ChangeMan DS through the available clients, and it describes the layout and navigation of the main window.
You can also access ChangeMan DS functionality through a supported IDE or through the ChangeMan DS Command Line Interface.

See the Serena® ChangeMan® DS Integrated Products Guide and the Serena® ChangeMan® DS Command Line Interface Guide for more information.

ABOUT CHANGEMAN DS CLIENTSChangeMan DS includes three graphical interfaces; Windows client, Java client, and the Web browser client. All three clients allow you to perform common SCM functions such as promotion activities, Impact Analysis, and Audit Trails.

Each of the clients has certain advantages:

• The ChangeMan DS Windows client lets you perform all administrative activities such as configuring users and groups.

• The ChangeMan DS Web Browser client can accessed by any local machine which has with a supported Internet browser and TCP/IP access to the ChangeMan DS Main Server. The local machine doesn’t need a client installed on the machine. In addition to all the common SCM activities, the Web browser client lets you perform all activities related to the package-oriented approach.

• The ChangeMan DS Java client, constructed completely in Java, can be installed and run on a variety of platforms such as UNIX. In addition to all the common SCM activities, the Java client lets you perform all activities related to the package-oriented approach.

Note that you cannot access ChangeMan DS until your have a user account created. Contact your ChangeMan DS administrator to create an account for you.

37

38

Chapter 3: Getting Started

ACCESSING CHANGEMAN DS WITH THE WINDOWS CLIENT

ACCESSING CHANGEMAN DS WITH THE WEB BROWSER CLIENT

To access ChangeMan DS from the Web browser client, your browser should be Internet Explorer 5.0 (or higher), or Netscape Navigator 6.1 or 6.2.

Step Action

1. Either:• Double-click the ChangeMan DS icon, or• Choose Programs > Serena > Serena ChangeMan DS.

2. Sign on as an authorized user.


To initiate the ChangeMan DS Web browser client:

ACCESSING CHANGEMAN DS WITH THE JAVA CLIENT

Use the following procedures to initiate the ChangeMan DS Java client on UNIX and Windows:

Initiating the Java Client on UNIX

Step Action

1. Launch your Web browser.

2. Enter either:• http://123.123.123.123:8040

where 123.123.123.123 is the IP address of your ChangeMan DS Main Server.

• http://hostname:8040

where hostname is the name of the machine on which your ChangeMan DS Main Server is located.

If your host name includes non-USASCII7 characters (for example, ñ) use the IP address.The Serena Web Client service and the VCS_Server service must be running on the Main Server.

3. Enter your ChangeMan DS User Name and Password, then click Login.

Step Action

1. Run Client.sh.Its default client path is: /usr/serena/changeman/DS/client.

2. Enter your ChangeMan DS User Name, and Password.

3. Enter the Host Name of the server that you want to access.

4. Click OK.

39

40


Initiating the Java Client on Windows Platforms

RECONNECTING TO CHANGEMAN DSTo reconnect to ChangeMan DS as a different user or to acquire new permissions that may have changed from your last login:

CHANGING YOUR CHANGEMAN DS PASSWORDTo change your personal password:

• In the Windows client, select Change Password on the log in dialog box (it appears when you start ChangeMan DS). You will be prompted for your new password. To verify that you typed the password correctly, you must type the new password in both fields of the ChangeMan DS Password Change dialog, and then click OK.

Step Action

1. Run Client.bat which can be found in the <program files>\Serena\ChangeMan\DS\Client.

2. Enter your ChangeMan DS User Name, and Password.

3. Enter the Host Name of the server that you want to access.

4. Click OK.

Step Action

1. From the ChangeMan DS Windows client, choose Connect from the File menu.In the Web Browser and Java clients, choose ChangeMan DS >

Relogin, or click

2. Fill out the login dialog.


• In the Java and Web Browser clients, select ChangeMan DS > Change Password or click .

Type your current password and your new password (you need to type the password again in the Confirm Password field), and then click Save. You will receive a confirmation prompt that your password has been changed successfully.

If you are a ChangeMan DS administrator, you can change the password for other ChangeMan DS users on the User Properties tab. See “Users and Groups” in the Serena® ChangeMan® DS Administrator’s Guide for more information.

EXITING CHANGEMAN DSTo quit the main ChangeMan DS module:

• Click the Close button in the upper-right corner of the window (Windows client).

• Choose Exit from the File menu (Windows client).

• Click in the upper-right corner (Web browser and Java client).

41

42


OVERVIEW OF CHANGEMAN DS INTERFACEThe main ChangeMan DS window is what users see first when they log in to ChangeMan DS. The nodes displayed in the tree are controlled by the access permissions granted to the user.

The main ChangeMan DS window contains a menu bar, toolbars, status bar, tree, and a content window that provides information on the selected module.

The tree is the area on left in the ExplorerView. Expand the nodes to display the different areas and projects that you have access to. Particular areas are displayed under their area type node. When you select a node, specific information displays in the content window.

In the Windows client, change views by clicking the following tabs on the tree section of the screen (lower left side):

• ExplorerView displays ChangeMan DS items and modules in a tree format, and is used for many ChangeMan DS functions.

• Host View displays an explorer-level view for UNIX and HP e3000 users .

To change the tree view, click the corresponding tab.

The content window is the area on the right in ExplorerView. The column headings change according to what is selected in the ExplorerView tree.


Note On the ChangeMan DS Windows client, you can receive context sensitive help either for a screen by pressing F1, or for a particular toolbar button by holding the left-click on a button and pressing F1.

From the Main window you can:

• Define new and manage existing, projects.

• Perform Impact Analysis to identify files affected by a project.

• Attach files to a project

• Promote or demote files and projects according to your process flow model.

• View and report the Audit Trail information.

• Maintain and invoke build projects.

• Manage files and directories or accounts on various hosts.

Navigating the Main WindowThe following tips will help you navigate through the ChangeMan DS main window:

• Right-click the file or tree node to display a list of commands available for this item.

• Find a particular project or area by clicking the plus signs to expand to the particular node.

• Display the files attached to a project by selecting the Attachments node under a project.

• Collapse nodes by clicking the minus sign.

• Bring the mouse pointer to a toolbar button to display the ToolTip.

• Drag the screen edge or corner to change the screen size and shape.

Note that ChangeMan DS records screen parameters (size, position, and shape) as they were before exiting from the system. ChangeMan DS automatically retains these parameters for future sessions. (Windows client)

• Toggle the toolbars or status bar by choosing Toolbar and Status Bar from the View menu. The toolbars and the status bar appear on the screen by default.

• Click and hold a toolbar button, and press F1 to access context-sensitive help for the a toolbar button. (Windows client only)

• Choose the Host View tab for the Explorer-level view of the HP e3000 and UNIX environments. (Windows client only)

43

44



45

46


ADDING FILES TO CHANGEMAN DS CONTROL
4
Before applying ChangeMan DS operations on files at any level, you must add the files to ChangeMan DS control.

Place the files under initial control:

• During creation of a Production area. See “Area Configuration” in Serena™ ChangeMan® DS Administrator Guide.

• By using the Add to DS Control option.

• By using Promote options.

• By using the Command Line Interface. See Serena® ChangeMan® DS Command Line Interface for more information.

• By using the appropriate option in an SCC-integrated IDE. See Serena® ChangeMan® Integrated Products Guide for more information.

ChangeMan DS assigns a home location to each file added to control. The home location is the Production area and path of a file after its initial load into ChangeMan DS (add to source control).

Note When considering adding files to control, you need to be aware of what characters your metadata database and participating operating systems support as some limit the use of non-alphanumeric characters.

47

48

Chapter 4: Adding Files To ChangeMan DS Control

ADDING TO CONTROL USING DS CONTROL OPTION

Use this procedure to add files with the Add to DS Control option. This technique is used when new files can be directly checked in from Development to Production.

Step Action

1. Place the file that you want to put under control in a directory pointed to by a ChangeMan DS area. This is typically a Development area, since other area locations are not authorized for write access by most users outside of ChangeMan DS.

2. Expand the area node, then select the file to put under control.

Files with status shown as are in uncontrolled status. If a file is in controlled status and a non-checked out copy resides in the selected

area, it has a status shown as .

To select multiple files, hold down the Shift or Control key and select the files.

3. Use one of the following options:

• Click (Add to DS Control) on the Files toolbar.• Choose Add to DS Control from the Files menu.• Choose Add to DS Control from the file’s right-click menu.

4. If the file you are adding to control is in either a Development or QA area, ChangeMan DS prompts you to choose a Production area and path to assign as its home.If the file you are adding to control resides in a Production area location, ChangeMan DS assigns that Production area path as its home, and puts the file under control, assigning Version 1 to the file. The following steps do not apply in this situation.


ADDING TO CONTROL USING PROMOTE OPTIONS

Use the following procedure to add files to ChangeMan DS control using the Promote options. This technique is used when new development must follow a process flow that does not allow direct check in from Development to Production, or if you want to assign a file to a home location other than the one to which it currently belongs.

5. Complete the Transfer Request dialog, as needed.See “Completing the Transfer Request Dialog” on page 96.

6. Click:• Transfer to initiate the file transfer process.

Provide passwords for source and target area, if required. See “Transfer Process” on page 99 for additional steps that ChangeMan DS performs in the transfer process.

• Cancel to exit from the Transfer Request screen and return to ChangeMan DS main module.

Step Action

1. Place the file that you want to put under control in a directory pointed to by a ChangeMan DS area. This is typically a Development area, since other area locations are not authorized for write access by most users outside of ChangeMan DS.

2. Expand the area node, then select the file to put under control.

Files with status shown as are in an uncontrolled state.

If a file is in a controlled state and a non-checked out copy resides in the

selected area, it has a status shown as .

Select multiple files by holding down the Shift or Control key.

3. Use one of the “Ways to Initiate the Promote Process” on page 119, depending on the current source area location and the target location:

For example, click (Promote to QA) from the Promote toolbar.

Step Action

49

50


REMOVING FILES FROM CONTROL

This procedure describes how to remove files from ChangeMan DS control.

Note The file is not physically deleted from its area location. The file can be deleted only by a person authorized to access that area from outside ChangeMan DS.

4. If the target area to which you are promoting is a Development or QA area, ChangeMan DS prompts you to choose a Production area and path to assign as the file’s home, even though the file is not yet transferred to its home location.If the target area to which you are promoting is a Production area, and you are not using the drag-and-drop method, ChangeMan DS displays a list of possible target Production areas for which you are authorized.

5. Verify the information in the Transfer Request dialog.See “Completing the Transfer Request Dialog” on page 96.



• Cancel to exit from the Transfer screen and return to ChangeMan DS main module.

Step Action


!!Caution!! This procedure removes all of the metadata information about this file from the ChangeMan DS database, including the Audit Trail records.

TROUBLESHOOTING ADDING FILES TO SOURCE CONTROL

Why can’t a file be placed under ChangeMan DS control?

Many reasons exist for not being able to place the file under control. A common problem is that you cannot place a file under source control if the file name contains an apostrophe character.

Step Action

1. Expand the area node, then select the file to remove from control.You can select multiple files by holding down the Shift or Control key.


• Click (Remove from source control) on the Files toolbar.

• Choose Remove from DS Control on the Files menu.• Choose Remove from DS Control from the file’s right-click menu.

3. You are prompted to verify the removal.Click:• OK to remove the file from control.• Cancel to abort the request.When you click OK, ChangeMan DS removes the file from control.

51

52


WORKING WITH FILES
5 This chapter describes working with the contents and properties of a file.
For information on transferring a file (such as checking in) or putting a file under source control, see “Transferring Files and Projects” on page 95. For information on merging or comparing multiple files, see “Merging” on page 153 and “Comparing Files” on page 143.

From the ChangeMan DS interface, you can:

• Edit a version of a file in a working area (page 53)

• Open a read-only version of a file for viewing (page 54).

• View a file’s status and source control properties (page 57).

• View a file’s history in graphical format through the File Tree (page 211).

EDITING THE CONTENTS OF A FILE You can edit text-based files from ChangeMan DS, from supported IDEs, or from outside ChangeMan DS.

From ChangeMan DSWhen you are in ChangeMan DS, you can edit files that reside in working areas that you have permission to access.

The editor invoked depends on your client:

• The Web browser client launches ChangeMan Edit when you edit a file.

See“ChangeMan Edit Module” on page 437 for more information on ChangeMan Edit.

• The Windows and Java clients launch the editor that is specified in your settings.

See “Setting the Editor” on page 55 for more information on configuring to choose your editor.

53

54

Chapter 5: Working With Files

To invoke the editor:

• From ExplorerView, select a file, and choose Files > Edit. (Windows client)

• From ExplorerView, right-click on a file, and choose Edit.• From ExplorerView, select a file, and click on the Files toolbar. (Windows

client)

• From the File Tree, select a version icon, and click Edit File .

Note If you select several versions in the File Tree, then click Edit File, only the most recently-selected file opens.

From Supported IDEsSee the integration guide for your particular IDE for specific information on editing files from a supported IDE.

From Outside ChangeMan DSWhen you edit files from outside ChangeMan DS, you must check out the file to your working area, and then open the file in your working area with your desired editor.

!!Caution!! Do not edit files that are located in Production areas or that have not been checked out. Doing so circumvents ChangeMan DS file management capabilities, and you may lose your file and all previous versions.

VIEWING THE CONTENTS OF A FILEChangeMan DS allows users to view contents of the file without authority to make changes (Read-Only).

To view the contents of a file:

• From ExplorerView, select a file, and choose Files > View.• From ExplorerView, right-click on a file, and choose View.

Note You can choose to view the Production version or the Working version (in Development and QA areas).

• From ExplorerView, select a file, and click on the Files toolbar.

• From the File Tree, select a version icon, and click View File


If you select several versions in the File Tree, then click View File, only the most recently-selected file is opened. This is standard Windows behavior.

See “Setting the Editor” on page 55 for choosing which application ChangeMan DS launches when viewing a file.

SETTING THE EDITORWhen you view or edit a file, the editor that is launched depends on the Use ChangeMan Edit setting.

In the Windows client:

• Select from the Tools toolbar

• Select Use ChangeMan Edit from the Tools menu

In the Java client:

• Select Use ChangeMan DS Editor from the View Options on the ChangeMan DS menu (Java client)

• Click and select Use ChangeMan DS Editor on the View Options dialog (Java client)

If the Use ChangeMan Edit option is not selected, the editor invoked is the program associated with the selected file's extension (type).

Note ChangeMan Edit is launched in the Web browser client even if the Use ChangeMan DS Editor option is deselected.

In a Windows environment, a program must be registered with Windows for the specific file type to open with the appropriate application when you view or edit it. If you select a file with an extension for a file type that has not been registered, Windows displays a prompt, allowing you to select the appropriate utility for viewing this type of file. Select the Always use this program to open this file check box to register the utility with Microsoft Windows.

Double-clicking on the file invokes either the ChangeMan Edit in view mode or the program associated with the file's extension (type), depending on the setting of the Use ChangeMan Edit option.

Note You cannot use ChangeMan Edit to edit Microsoft Word documents.

See “ChangeMan Edit Module” on page 437 for more information on ChangeMan Edit.

55

56


EDITING A FILE WITH CHANGEMAN EDITNote ChangeMan Edit must be specified as your editor for the following

procedure. See “Setting the Editor” on page 55 specifying ChangeMan Edit as your editor.

To open a file for editing in a Development area:

Step Action

1. In the ChangeMan DS main window, select the file to modify.You can invoke the Edit module from the Production area only if the selected file has been checked out.

2.Click Edit from the Files toolbar, or right-click, then select Edit from the right-click menu.

3. ChangeMan DS prompts you for the host login information to verify your security access.• If the selected file is located on a

Windows or UNIX host, this screen prompts you for the host login information.


See “ChangeMan Edit Module” on page 437 for more information on ChangeMan Edit.

VIEWING FILE PROPERTIESThe File Properties option gives comprehensive file status information.

To view the properties of files under control, either:

• Right-click on a selected file and choose Properties.

• Select the file and click (Windows client only).

The Source Control Properties dialog displays with four tabs. From any tab:

• Click Refresh to update the file information.

• Click Tree to see the File tree for the selected file.

4. Enter the appropriate host login information, then click OK.ChangeMan Edit uses a template to control the content editing, syntax highlighting, line numbering, and formatting.If the file has a defined type extension such as g.ch or g.txth, ChangeMan DS attempts to select the template that is defined for that file type.If only one template exists, the editor opens the file using that template.If there are several templates found for the file type, ChangeMan DS prompts you for the appropriate template.

5. If necessary, select a template, then click OK.ChangeMan Edit opens the file and displays it on your screen.ChangeMan Edit lets you open several files simultaneously, allowing you to copy text between the opened files.

Step Action

57

58


An example of the File Properties dialog from the Web browser client follows:


File Properties

Feature Description

File Name The name of the file.

Current Area The current location of the file.

Version The version of the file in its current location.

Current Path The path to the file in its current location.

Production Area The home Production area for this file.

Version The version of the file in the Production area.

Production Path The path to the file's Production area.

Current Project The project to which the file is attached, if any.

Relative Path The relative path for the project, if created.

Status

Shared by multiple projects

Whether or not the file is attached to multiple projects.

File in pending state Whether or not the file is waiting to be approved to move either to or from this area.

File in requested state Whether or not the file is awaiting transfer, usually if the transfer is scheduled to occur later.

Current file differs from production

Whether or not the file has changed from the version in the Production area.

Checked out to current user

Whether or not the file is checked out to the current user.

Checked out to other users

Whether or not the file is checked out by another user.

59

60


Concurrent Check Out InfoThe window at the top of this tab provides information on the concurrently checked out copies of the file including:

You may also perform the following functions:

Concurrently checked out Whether or not the file is checked out by multiple users.

Checked out to current location

Whether or not the file is checked out to the area from which the file was selected and the properties viewed.

Feature Description

Local Status Indicates the current status of the file

Area The current location of the file.

Path The path to the current area.

User The user who checked out the file.

Project The project to which the file is attached if any.

Version The version number of the file.

Time When the file was checked into its current area.

Feature Description

Edit Opens the file for editing.

Compare to Current File Compares a selected file to the file currently under the user's control.

Synchronize Current File Merge or overwrite two versions of the file in the same area.

Cancel Check Out Cancels the check out of the file.

Feature Description


Sharing InfoFrom this tab you can see projects to which the file is attached.

Pending and Scheduling InfoFrom this tab you can see what file transfers are awaiting approval, and can approve them if you have permission.

Select the file and click Approve or Reject to display the ChangeMan DS Approval dialog.

Compare to Production Compares the file to its Production copy.

Promote Promotes the file to any area to which the Process Flow allows.

Check In Promotes the file to its home Production area provided the Process Flows permit transfer from its current area.

Compare Compares two selected versions of the file.

Feature Description

Attach Attach the current file to a project.

Detach Detach the current file from a project.

Relative Path Set the relative path for a project.

Feature Description

61

62


USING PROJECTS
6 In the development process, files are rarely changed by themselves; most files are logically related to other files, such as components of a software application. ChangeMan DS projects help to manage these logically-related files.
ChangeMan DS lets you group reported problems or change requests as projects. You can attach multiple files or objects to a project and treat the project and its components as a single entity. This feature lets you monitor the changes made to the files or objects and relate them to the reported problems.

Some advantages of using projects include:

• Project Management - Displays and tracks the related components in a project; manages them between promotions, maintaining comprehensive information about reported problems or enhancement requests.

• Project Build Management - Automates and standardizes software. executables.

• Project Release Management - Enables the freezing of projects to capture the version of components and make procedure information that went into a release at a specific time.

PROMOTING PROJECTSProjects are promoted from area to area using the promote options. Each user sees only the projects and areas that they are authorized to see.

Refer to “Transferring Files and Projects” on page 95 for additional information on different project promotion actions.

63

64

Chapter 6: Using Projects

Enforced Project-level PromotionSome companies choose to enforce project-level transfer activities. Upon transfer, the file must be attached to a project (if it is not already attached to one). This also forces the entire project to be moved as a unit, and after the initial Check Out and attach to a project, all promote requests must be done by selecting the project, not the individual files.

To enforce project-level transfers, the Transfer Mandatory Fields Project check box in the user/group properties should be checked.

Refer to “Users and Groups” in Serena™ ChangeMan® DS Administrator Guide for information on setting user properties.

VIEWING PROJECTS—PROJECT FILTER SCREEN ChangeMan DS lets you view the projects that have common criteria. For example, you may view all Open projects or all projects assigned a certain status.

• Click the Filter by status and priority button on the ChangeMan DS Project Configuration dialog.

This feature lets you view projects with the specified status or priority.

You can view specific projects by selecting the button associated with the project’s status and/or priority. All other projects will be excluded from the list.

Note If you don’t select any of the filters, or you select them all, ChangeMan DS displays all projects.


CREATING OR EDITING PROJECTS IN THE WINDOWS CLIENT

The Web browser and Java clients allow new projects to be created. All other project configuration functions should be carried out using the Windows client.

To access and utilize the project configuration, you need to have the following permissions:

• Setup Process Projects and ExplorerView Projects permissions on the Layout tab. Select Project Frozen Releases, Make Procedures, or Attachments if you will be working with any of those items.

• Create, Edit, Delete for Projects on the Administrative Permissions tab

To create or edit a project in the Windows Client:

Step Action

1. Either:• Choose System Configuration from the Tools menu.

• Click on the Tools toolbar.

2. In the Global Process Flow window, choose Projects from the Edit

menu or click .

The Projects Configuration window displays the following tabs:• New displays names and descriptions of New Projects.• Bug Fix tab displays names and descriptions of Bug Fix Projects.• Custom displays names and descriptions of Custom Projects.• Enhancements displays names and descriptions of Enhancement

projects.Whichever type you select causes the Type to be pre-selected in the New Project dialog. If All is selected, New Project is pre-selected by default.

3. In the ChangeMan DS Project Configuration window, either:• Click New to define a new project. • Click Edit to modify a selected existing project.

65

66


CREATING PROJECTS IN THE WEB BROWSER AND JAVA CLIENTS

The Web browser and Java clients allow new projects to be created. All other project configuration functions should be carried out using the Windows client.

To access and utilize the project configuration, you need to have the following permissions:

• Setup Process Projects and ExplorerView Projects permissions on the Layout tab. Select Project Frozen Releases, Make Procedures, or Attachments if you will be working with any of those items.

• Create, Edit, Delete for Projects on the Administrative Permissions tab

4. Input all necessary information under the following tabs:• Properties• Authorization• AttachmentsSee “Project Properties” on page 73, “Project Authorization” on page 76, and “Attaching Files” on page 81 for more information.

5. Click OK.

Step Action


To create a new project in the Web browser and Java clients:

EDITING PROJECTS IN THE WEB BROWSER AND JAVA CLIENTS

To edit an existing project in the Web browser and Java clients:

Step Action

1. Either:• Click New Project button on the toolbar. • Select the Projects node in the ExplorerView and choose Create

New Project from the right-click menu.


3. Click OK.

Step Action

1. Right-click on the node of the specific project that you want to edit, and choose Edit.


3. Click OK.

67

68


DELETING A CHANGEMAN DS PROJECTTo delete an existing project:

COPYING PROJECT PROPERTIES TO ANOTHER PROJECT

To copy the properties from one project to another:

Step Action

1. Select a project name displayed in the ChangeMan DS Project Configuration dialog.

2. Click Delete.

Step Action

1. Select a project name displayed in the ChangeMan DS Project Configuration dialog.

2. Click Copy.ChangeMan DS displays the following dialog.


3. Select the properties for copying.

Select... To...

Authorization Copy the user authorization from one project to another.

Files Copy the file attachment list from one project to another.

Method

• Replace Replace the target profile with the selected source profile.

• Append Add the target project profile to the existing profile of the source project.

4. Click OK. ChangeMan DS displays the list of target projects.

5. Select the target project and click OK.

Step Action

69

70


DEFINING PROJECTS

Note The Project Configuration dialog is titled Add Project when first creating a project, but is titled Edit Project when you go back to edit the project.

Step Action

1. In the Name field, type a name for the project.Allowed characters are alphanumeric or embedded underscores.See “Project Properties” on page 73 for more information.

2. Type a brief description, such as “Sample project for Payroll application,” in the Description field.See “Project Properties” on page 73 for more information.

3. To define a ChangeMan DS project, you must designate Type, Status, and Priority.See “Project Type” on page 74, “Project Status” on page 75, and “Project Priority” on page 75 for more information.


4. Select the Authorization tab.

5. Select the users and/or groups who are authorized to work with the project from the List of configured users and click Add.Note: If all users need access to this project, do not add anyone to the

Authorization list. By default, all users have access to a project until specific users are granted access, leaving any user not on the Authorization list without access.

See “Project Authorization” on page 76 for more information.

Step Action

71

72


6.Optional

Double-click the users/groups or select them and click Properties to specify their permissions for this project.

7. Select the appropriate options for the user/group for this project and click OK. See “Configuring User Permissions for a Project” on page 78 for more information.

8. Select the Attachments tab to attach files to the project.

Step Action


PROJECT PROPERTIESThe project Properties tab is used to either create a new ChangeMan DS project or change the profile of an existing project.

The following categories define each ChangeMan DS project.

• Project Type

• Project Status

• Project Priority

The Properties tab contains the following input fields.

9.Expand the Production area, select the files, and click to attach

the selected files to the project.See “Attaching Files” on page 81 for more information.

10. Complete project configuration by clicking OK.

Field Description

NameRequired.

Contains a unique name identifying the project (up to 10 characters).Allowed characters are alphanumeric or embedded underscores.

DescriptionOptional.

Contains a brief description of the project.

OwnerRequired.

Contains the name of the ChangeMan DS user who created the project.Note: A project owner can delegate the responsibility for this

project to another user.

Step Action

73

74


Project Type

Project type lets you classify your projects by the purpose of the project. Projects are organized by type under the Projects node in ExplorerView. Select one of the following icons to define the type of project.

ParentOptional.

Contains the name of the Parent project if the current new project is created as a sub-project of the existing one. You can use the drop-down menu to select the Parent project from the list.

NotesOptional.

Contains narrative notes related to this project.

Icon Description

New projects.

Bug Fix projects.

Custom projects.

Enhancement projects.

Field Description


Project StatusProject status lets you classify your project by the stage of development that it is in. This is purely informational and is displayed in the Content Area when the item is selected. Select one of the following icons to define the Status of the project.

Project PriorityProject priority lets you prioritize your project. This is purely informational and is displayed in the Content Area when the item is selected. Select one of the following icons to define the Priority of the project:

Icon Description

Open projects.

Development projects.

Quality Assurance projects.

Completed projects.

Icon Description

Low Priority projects.

Medium Priority projects.

75

76


PROJECT AUTHORIZATIONThe Project Authorization process lets you permit certain users to perform various operations involving selected projects.

Note If a project doesn’t have an Authorization list defined, then all users can work with this project

Select the Authorization tab from the project setup screen. The following screen lets you maintain the user authorization list for this project.

The left portion of the screen displays the Authorization list column. This column contains a list of ChangeMan DS users and groups that have been authorized to work on this project.

• Select All to view the list of all ChangeMan DS users and groups authorized to perform SCM operations involving this project.

High Priority projects.

ASAP Priority projects.

Icon Description


• Select Users to view all ChangeMan DS users authorized to perform SCM operations involving this project.

• Select Groups to view all ChangeMan DS groups authorized to perform SCM operations involving this project.

Note The owner of a project is able to access the project, even if the owner is not on the authorization list.

Adding Users or Groups to the Project Authorization ListTo add users or groups to a project authorization list:

Note The next time anyone in the authorization list opens ChangeMan DS, they will be able to access the subset of SCM functionality you specified for the project.

Project-level permissions are separate from those specified under user/group configuration, and they further limit permissions specified in the user/group configuration. See “Configuring User Permissions for a Project” on page 78 for more information about changing project-level permissions.

Deleting Users or Groups from the Project Authorization List

To delete users or groups from a project authorization list:

Step Action

1. Select the user or group names from the List of configured users/groups column.

2. Click Add to add the selected name to the Authorization list.

Step Action

1. Select the user or group names from the Authorization list column.

2. Click Delete to remove the selected name from the Authorization list.

77

78


Configuring User Permissions for a ProjectTo configure permission on the Global Projects Configuration window, double-click on the name of a user or group in the Authorization list or select the name and click Properties.

You can define special sets of permissions for the users and groups displayed in the Authorization list column.

Project-level permissions allow you to further restrict what actions a user or group can perform in the area. You can’t add additional permissions at the project-level. If you select a permission that is not allowed at the global level, the selection won't override the global permissions.

For example, a user can be allowed to check out on the global level but the permission can be removed for a specific project. However, if the user is not allowed to check out at the global level, adding it at the area level won’t let the user check out for that project.

The project-level permissions default to the corresponding settings defined during user setup. You can further restrict these permissions by disabling the appropriate checkboxes.

Once a user or group has been added to a project authorization list, the project-level permissions are no longer directly linked to the global permissions. Therefore, if the permissions for a user or group are changed, the permissions set at the project level are not updated, even if none of the permissions for the user or group have been overridden at the project level. This is to maintain the restrictive nature of the project-level permissions.

To reset the permissions to the global settings for the user or group in the Authorization List, simply delete them from the Authorization List and re-add them.

Note The permission defined for the group affects all ChangeMan DS users that are members of this group.

See “Default User Templates for Project Authorization” on page 80 for the templates that are included to help you select permissions.


Clear the following options from the Permissions dialog to restrict user permissions on specific activities related to projects.

Option Permission

View Only Open files for viewing.Note: If this option is not selected, the user can still see the list

of files within an area, but can not open any of them for viewing.

Check out Check out this project.

Second Check out

Get a copy of the project that was previously checked out by another user.

Cancel Check out Cancel a check out.

Check in Check in the project.

Promote to QA Promote this project to QA.

Demote from QA Demote this project from QA.

Check in overwrite: Binary

Check in a project that contains binary files and has not been originally checked out by this user.

Check in overwrite: Text

Check in a project that contains text files and has not been originally checked out by this user.

Check in merge Merge files attached to this project during the check in process.

Create release Create a release based on this project.

Delete release Delete a release based on this project.

Rollback release Restore a previous release of this project.

Remove from source control

Remove files from source control.

Add target/ dependency

Add externally created targets and dependencies to the make procedure.

Modify target/ dependency

Modify the target and dependencies in the make procedure.

79

80


Default User Templates for Project Authorization

ChangeMan DS offers the following templates designed to simplify the configuration process:

• Administrator

• PowerUser

• End User

Each template has a set of permissions. The following table shows which operations will be permitted under each template provided by ChangeMan DS.

Selected indicates access to the functionality is provided, while a Cleared indicates access to the functionality is denied.

Delete target/ dependency

Delete the target and dependencies in the make procedure.

Create target/ dependency

Create targets and dependencies in the make procedure.

Project Administration: Properties

Modify properties for this project.

Project Administration: Authorization

Modify the Authorization list for this project.

Project Administration: Attach files

Attach files to this project.

Project Administration: Detach files

Remove files from this project.

Option Administrator PowerUser End User

Check out Selected Selected Selected

Check in Selected Selected Selected

Option Permission


ATTACHING FILESFiles are logically associated with a project by attaching them to the project. By so doing, you can treat the grouped files or objects as a single entity during all of your SCM activities. Because it is a logical grouping, a project can consist of files or objects that reside throughout your network.

Promote to QA Selected Selected Selected

Demote from QA Selected Selected Selected

Second check out Selected Selected Cleared

Check in overwrite - Binary

Selected Selected Cleared

Check in overwrite - Text


Check in merge Selected Selected Cleared

Create release Selected Selected Cleared

Delete release Selected Selected Cleared

Rollback release Selected Selected Cleared

Attach files Selected Selected Selected

Remove files Selected Selected Cleared

Add target / dependency

Selected Selected Selected

Modify target / dependency

Selected Selected Selected

Delete target / dependency


Create new target / dependency


Option Administrator PowerUser End User

81

82


You can attach files to projects using any of several methods:

• During project creation.

• From the content window (either from ExplorerView or an Impact Analysis report).

• By dragging and dropping a file in ExplorerView.

• As a part of the promote process by typing the project name in the Transfer Request dialog.

• From the Command Line Interface. See the Serena® ChangeMan® Command Line Interface Guide.

• From your IDE.

Once the selected files are attached to a project, you can use the project (along with its components) to perform various version control tasks.

You can attach files at the child and the corresponding parent level so that the subproject contains a logical subset of the project files. With this organization, you can:

• View all files in the child subproject from the parent project view.

• View subproject files separately to see the logical configuration of the project.

• Set permissions for each project and subproject, so that users have views appropriate to their roles.

• Control the project at the parent level, with build and freeze rippling down through the associated child levels.

Also, you can attach files at the lowest subproject level only, so that you view files only on the subproject. In this configuration, you:

• Promote files between areas at the subproject level.

• Perform build and freeze at the subproject level to maintain project integrity and ensure that only specific subproject files are included.


Attaching Files to a Project during ConfigurationUse this procedure to attach files to a project on the Attachments tab while creating or editing a project:

Once the selected files are attached to a project, you can use the project (along with its components) to perform various version control tasks. See “Transferring Files and Projects” on page 95 for information on promoting the attached files as one entity.

Step Action

1. Select the Attachments tab from the ChangeMan DS Project Configuration screen. This tab lets you maintain a list of files attached to this project.The right section of the window displays a list of Production areas currently configured in ChangeMan DS.The left portion of the screen displays a list of files already attached to this project.See “Creating or Editing Projects in the Windows Client” on page 65 for information on accessing the ChangeMan DS Project Configuration screen.

2. Double-click on the name of the Production area that contains the file to attach to a project. ChangeMan DS displays the names of directories in the selected area.

3. Select a directory name. ChangeMan DS displays the names of files in the selected directory.

4. Select the files to attach. You can select multiple, individual files by holding down the Control key, or you can select multiple contiguous files by holding down the Shift key.

5.Click to attach the selected files to the project.

83

84


Attaching Files from the Content WindowFrom ExplorerView or an Impact Analysis report, use this procedure to attach files to a project:

Attaching Files using Drag-and-Drop

From the content window in ExplorerView, drag-and-drop a file into the appropriate project under the project’s node.

Step Action

1. Select a file.

2. Either:• Right-click and choose Attach.

• Click Attach from the File toolbar

• Click Attach from the Impact Analysis toolbar.

ChangeMan DS displays the Projects dialog.

3. Either:• Attach the file to a current

project by selecting a project, then clicking OK.

• Attach the file to a new project by clicking New to create the project as described in “Creating or Editing Projects in the Win-dows Client” on page 65.

The file displays in the attachment list of the chosen project.Note: If you attached the file from a Production area, the relative path is

set automatically for the file.If you attached the file from a working area, the relative path is not set.


Removing Files from a Project During Configuration

To remove files from the Attachments tab:

Step Action

1. Select the Attachments tab from the ChangeMan DS Project Configuration screen. This tab lets you maintain a list of files attached to this project.The right section of the window displays a list of Production areas currently configured in ChangeMan DS.The left portion of the screen displays a list of files already attached to this project.See “Creating or Editing Projects in the Windows Client” on page 65 for information on accessing the ChangeMan DS Project Configuration screen.

2. Double-click on a Production Area name from the list displayed in the Files attached to project column. ChangeMan DS displays the names of directories located in the selected area.

3. Select a directory name. ChangeMan DS displays the names of files located in the selected directory.

4. Select the files. You can select multiple, individual files by holding down the Control key, or you can select multiple contiguous files by holding down the Shift key.

5.Click the button to remove the selected files from the

project.

85

86


Removing Files from a Project Through ExplorerViewUse this procedure to remove files from a project through ExplorerView:

Viewing Status of Attached FilesFrom the ExplorerView, use this procedure to view the status of project components:

Step Action

1. Expand the Projects node, then select the appropriate project.

2. Expand the Attachments node, then select the appropriate file.You can select multiple, individual files by holding down the Control key, or you can select multiple contiguous files by holding down the Shift key.

3. Select Files > Detach from Project.The ChangeMan DS verification dialog displays.

4. Click Yes to detach the file.The ChangeMan DS dialog reports the Detach Operation Complete message.

Step Action

1. Expand the Projects node to display the four project types.

2. Expand the project type node; a list of configured projects of this type displays.

The project in Development icon indicates that this project has been checked out.


WORKING LOCATIONA working location for a project serves any of these primary purposes:

• To define a default Development or QA area into which files are checked out.

• To allow a working view of project attachments (set by toggling the Show Project Work Location View button on the Tools toolbar).

• To maintain a directory structure for a project as it is promoted from one area to another (used in conjunction with Set Relative Path).

The working location consists of a working area and a working path defined when checking out a project for the first time, or by setting the project's properties. See “Setting Project Working Location” on page 88.

The working location works in conjunction with the project's relative path structure. The working area path is the relative "root", and the relative path structure is created or searched for under that directory.

The working location is specific to each user, so different users can have unique working locations for the same project.

3. Expand the project name to display the project structure.Each project in ChangeMan DS has the following structure:• Frozen Releases - contain information on the project’s structure as of

a certain release.• Make Procedures - contain target and dependency structure of the

Build process.• Attachments - contain information regarding files attached to the

project.

4. Expand the Attachments node to display a list of files attached to the project. If those files belong to multiple Production areas, a list of the corresponding areas displays.The display of the content window can be toggled between project working location view and Production area view, see “Project Working Location View” on page 88 for more information.

Step Action

87

88


In addition, the working location is stored on the client machine for Java or Windows clients; therefore, if you access ChangeMan DS from different client machines, you need to set the working location on each machine.

Setting Project Working LocationNote that you can either set the project working location explicitly, or ChangeMan DS prompts you to set it when you promote the project.

To set the project working location:

Project Working Location ViewYou can view the attached files of a project in either Production view or project working location view. The views differ as follows:

• Production view shows the files as they appear if you selected the home Production area file list.

• Project working location view displays the files as if you selected the assigned project working location area file list.

Step Action

1. Select the project, then choose Properties from the right-click menu.The Project Working Location dialog displays with the Project tab selected.

2. Click the browse button, then choose a working area, expanding to the level of subdirectory you want to maintain as your relative root directory for this project. The Working Area field is populated with the area name chosen, and the Working Path is populated with the full path selected.


The project working location view is primarily for developers. It allows them to view files attached to a project as they appear in the project working location (generally a Development area). With the project working location view, a developer edits files in that project working location. When working from the Production view, a developer may mistakenly edit another developer’s concurrently checked out file.

All other users should use the Production view.

To toggle the project working location view, either:

• Click in the list, then click on the Tools toolbar. (Windows client)

• Click and select or deselect Set Project Work Location View. (Java and Web browser clients)

Toggling the project working location view has no effect unless a work area has been assigned for the project.

Choose Refresh after changing this indicator to update the display.

When you select the Attachments node and the Production area view (deselect the icon), each file appears with a checked out icon.

The Status icon indicates that the corresponding file is checked out.

The Owner column contains the name of the user who initiated the last transaction for this file.

If you select the Attachments node and project working location view (select the icon) after checking out a project, the project icon is overlaid with the developer icon, thus indicating that the project has some checked out attachments. In this case, all of the attachments are checked out, because the entire project was checked out.

Note If you don’t have an assigned project working location, you will always see the Production view.

Once you have promoted your project to the next level in the development process (usually QA), remember to set the Show Project Work Location View back to the Production view (deselect it) so that the view you see will properly reflect the current status of the files.

89

90


RELATIVE PATHA relative path maintains the directory structure relationships between files that exist in an original area. The relative path designates a sub-level directory that is to be maintained as the project is promoted from area to area. This allows different projects in an area to have different relative directory structures, and allows higher-level paths in differing areas to have different directory names.

The relative path defines the desired directory structure that is retained when a project is promoted. The directory structure is relative to the Working Path designated in the Project Working Location for the project. The relative path overrides the Same preference for an area.

Attached files with a relative path appear in folders labeled with relative path under the Attachments node for a project.

If directory structure is not important to the project, then it is not necessary to set a relative path. Files without a relative path are contained in a folder labeled Unassigned below the Attachments node.

If a relative path is not used, and if the Same option is set for the areas involved in the process flow, then the directory structure of the origin area will be maintained for project-level promotes.

If you attach files to a project by using the right-click menu in the file list for a Production area, the relative path is automatically set for those files, relative to the Production area root path. The relative path is also automatically set if the files are attached to the project from an IDE. If you attach files in any other way, they are assigned a relative path of Unassigned. See “Attaching Files from the Content Window” on page 84.

You can change a relative path for a file with the Set Relative Path option (see “Setting Relative Path”).

Setting Relative PathUse this procedure to set the relative path option:

Step Action

1. Expand the attachments of the project so that the files are displayed on the right side of the screen. You can sort the files by clicking on the Home Path column heading to help select groups of files that fall in the same subdirectory.


SUBPROJECTSProjects may be subdivided into subprojects. Some advantages of using project/subproject divisions are:

• Controls the view of files on a large project on which the work is subdivided between several contributors.

• Simplifies the build management of a release that has multiple contributors.

• Simplifies the freeze of a release that has multiple contributors.

2. Select a group of files based on their subdirectory location, then right-click.

3. Choose Set Relative Path from the right-click menu to set the relative path on the selected group of files.The Set Relative Path dialog displays.

4. Type your relative path.For UNIX, '/' (forward slash) is used.For Windows NT, '\' (backward slash) is used in the path. The relative path name will be entered as '.\' if the file is to be placed just under the directory pointed to by the Working Location Work Path. If the file is to be placed in a subdirectory under the Work Path, the relative path is entered as '.\subdir\subdir2\…', where 'subdir\subdir2\…' represents the subdirectory path.The attachments are assigned to a specific directory structure; now, as the project is promoted from area to area, this sub-level directory structure will be maintained.

5. Repeat the process to create different relative paths for different files in the same project.

Step Action

91

92


Subprojects are displayed in the ExplorerView under their parent project’s attachments, and also shown in the same level view.The parent of a project is assigned using Tools > System Configuration > Project Manager, or it can done by attaching a project to another project to make it a subproject of the target project.

Attachment Rules for SubprojectsSubprojects are an extended kind of attachment to a project; therefore, files are attached to subprojects in the same way they are attached to regular projects. However, it is important to consider the relationship of the parent and child projects when attaching files to them. The direct attachments of a project are promoted, frozen, or otherwise acted upon when action is taken on the project, regardless of whether the project is a parent or child project. Subproject attachments are not automatically part of the parent project's direct attachments; if you want them to be, you must specify that explicitly.

When attaching files to a subproject, ChangeMan DS prompts for whether or not the operation should affect parent projects (be populated to the hierarchy above it). A window lists choices of all higher levels (parent, grandparent) that may be selected or deselected.

Projects and subprojects can be thought of as sets of files, in which the parent and child point to distinct sets of files, or in which they may be supersets or subsets of each other.

Subproject Promotion BehaviorFor parent-level promotes, only the direct attachments of the parent will be transferred. Any attachments of subprojects that are not also direct attachments of the parent are not transferred.

For child-level promotes, only the direct attachments of the subproject will be transferred. Any attachments of the parent project that are not also direct attachments of the subproject will not be transferred.

Example Subproject Schemes

Project Scheme AA parent project may have the same file attachments as its subprojects have, with the subprojects themselves having different sets of attachments.


In this scheme, the parent project is considered to be the whole project, and the subprojects are considered to be the separate components of the project that are assigned to different programmers, or that represent different portions of the project (for example, Subproject1 could be source files, Subproject2 could be executables, and Subproject3 could be objects).

This lets you view each subproject's distinct files, and operate on the subprojects separately, while also letting you view and operate on the files at the larger (parent) project level.

Project Scheme BParent and child attachments may all be distinct, so that only the parent-child relationship is a common factor.

93

94


This scheme could be used in a situation in which you want the operations to be done at the subproject level, but want to show that the subprojects are related to each other, and that they are all logically part of a common larger project.

Project Scheme CA parent project may have all the same attachments as its subprojects, with each subproject also having the same attachments as its subprojects, and so on.

This scheme could be used in the situation where you have a more complex relationship between levels of work, and you want to maintain that view of the project.

TRANSFERRING FILES AND PROJECTS
7
You transfer files whenever you check in, check out, promote, or distribute files or projects.

In ChangeMan DS, “promote” refers to all transfer activities. Each type of promote invokes the transfer request process, but the results of the request depend on the specific promote type, and the origin and target areas involved in the request.

For example, the assignment of a new version number for a file takes place upon promotion to the Production area with a check in transaction.

The transfer process includes three steps:

1. Invoking a specific transfer process. The following table lists the transfer types.

This process… Performs this task…

Check Out Retrieves a production version of a file and creates an identical copy in a Development (or QA) area.See “Checking Out” on page 105.

Check In Introduces a new version of a file to a Production area and stores file changes in the archives. Also referred to as Bring Home.See “Checking In” on page 114.

Promotion/ Demotion

Advances files or projects to the next logical stage in a software development process flow or rejects files or projects to a previous stage in a software development process flow.See “Promoting” on page 119.

Distribution Forwards files or projects to the locations accessible to, and used by, the application’s end users, such as a Web server.See “Distributing” on page 123.

95

96

Chapter 7: Transferring Files and Projects

2. Completing the Transfer Request dialog.

See “Completing the Transfer Request Dialog” on page 96.

3. Performing the transfer process based on your area configurations.

See “Transfer Process” on page 99.

You can check out, check in, and promote files and projects to the next logical stage of development as defined in the process flow by:

• Using the Promote menu or toolbar commands.

• Using the right-click menu Promote commands.

• Using the Copy and Paste commands.

• Dragging and dropping.

Binary Versus Text-Based TransfersChangeMan DS examines the files to determine whether they are binary or text-based. Binary files are treated differently than the text-based:

• Binary files are not converted during Windows to UNIX (or UNIX to Windows) transfers.

• Binary files are stored as zip archives.

ChangeMan DS uses the following default criteria to determine if a file is binary

• A “special” character refers to a nonprintable(binary) character for a locale. For an English locale, characters such as “ä” are “special” to it. Such characters force the file to be determined as binary on the locale for which they are “special.” See “Locale Setting” on page 149.

• PDF files are considered binary.

• Any text-based file that has lines longer than 512 characters is considered binary.

Configure ChangeMan DS to treat certain types of files as binary when they are transferred. To force the a file type as binary, you need to change the variable bintransforce in vcs_serv.ins (Windows machines) or vcs_serv.cfg (UNIX machines). See “vcs_serv.ins” in the Serena® ChangeMan® DS Administrator’s Guide for more information.

COMPLETING THE TRANSFER REQUEST DIALOGThe Transfer Request dialog appears during promotion activities, and is modified as needed.


Select from the following options:

• Choose a real-time (On-line transfer) or schedule an Off-line transfer. See “Scheduling On-line or Off-line Transfers” on page 97.

• Add a description to the transfer in the Description field. See “Adding a Description to a Transfer” on page 98.

• Associate a project with the files being transferred by clicking . See “Associating a Project with Transferred Files” on page 98.

• Mark the file as read only in the target area by selecting Read Only.

• Associate a check in with a related TeamTrack item by clicking TeamTrack. See “Associating Source Control Operations with TeamTrack Items” on page 98.

• Check out a previous version of the file or to create a branch by clicking Advanced. See “Checking Out a Previous Version of a File” on page 109 and “Branching” on page 133.

• Modify the list of files being transferred in the Files list on the left. See “Modifying the List of Files Being Transferred” on page 98.

After modifying the dialog, continue with your promotion activity by clicking Transfer.

ChangeMan DS performs the transfer process as described in “Transfer Process” on page 99.

Scheduling On-line or Off-line TransfersThe default transfer mode is On-line on the Transfer Request dialog (box is checked). This mode allows the transfers to take place in real time. You see updated status on the requests from the ExplorerView window.

In on-line mode, you can select Execute implementation scripts on project level to force implementation scripts to run at the project-level instead of the file-level. This option causes scripts to be run once when the project is transferred, and not multiple times for each individual file.

If the On-line option is not checked on the Transfer Request dialog (off-line mode), the transfers are put into a queue and picked up by the server in off-line mode.

In off-line mode, you can schedule date and time for the transfer to occur by entering the date and time by selecting Schedule and inserting the date and time on the Transfer Request dialog.

In off-line mode, the status updates for the ExplorerView window are not automatic; you must do a manual refresh to see the current status of the file transfer.

97

98


Adding a Description to a TransferEnter a description associated with the request in the Description field.

If promoting multiple files, use the same comment for all files by selecting Use this comment for all files.

If dictated by the user configuration, certain users can be forced to enter a description if their user or group configuration has Description selected under Transfer Mandatory Fields on the Properties tab.

Associating a Project with Transferred Files

To associate the files in the check out request with a certain project, click on the Transfer Request dialog, and select from the list of configured ChangeMan DS projects (or create a new project).

You must enter a project name if your user or group configuration has Project selected under Transfer Mandatory Fields on the Properties tab.

If you are promoting a project, the project field is automatically populated.

Associating Source Control Operations with TeamTrack Items

Use the Associate Source Control Operations with TeamTrack Items dialog to find TeamTrack items and associate them with your source control operations.

The source control information is recorded in the TeamTrack database, and displayed in the Version Control History section of your TeamTrack browser interface.

Access this dialog by clicking TeamTrack on the Transfer Request dialog. Note that this button is disabled if you have neither Mandatory nor Optional permissions set at the user or group level.

For detailed information on installing, configuring, and using the TeamTrack integration with ChangeMan DS, see the Serena TeamTrack VersionBridge for Serena® ChangeMan® DS Guide.

Modifying the List of Files Being TransferredAdd or remove files from the transfer list on the Transfer Request dialog.


Reasons to modify the list include if you want to promote only a few of a project’s files after selecting the entire project for check out.

It is easier to select the files you want to promote from the project’s attachments view rather than typing in the list of file names. However, if you want to use the project’s relative path settings, select the entire project and type the project’s files that you want to promote in the File list.

You can modify the list using the following commands:

TRANSFER PROCESSAfter you have invoked the transfer process by clicking Transfer on the Transfer Request dialog, ChangeMan DS performs the following steps:

Click… To perform this task…

Edit the file name on the selected line.

Add a new line to the list of files.

Delete the selected line.

Move the selected line up the list.

Move the selected line down the list.

Step Action

1. Prompts you to provide passwords associated with the source and target areas, if required. In and Out passwords are defined for some implementations of ChangeMan DS. See “Area Configuration” in Serena™ ChangeMan® DS Administrator Guide.

99

10


2. Analyzes the transfer request, addressing, and permissions on all levels. Each file transfer request is evaluated against the Global, Application, and Project Process Flow rules.If the request fails in any respect, ChangeMan DS reports why the request failed.

3. If the request is valid, one promote request is created.

4. The request is either immediately initiated (on-line mode) or put in a queue to be picked up by the server agent (off-line mode).The following Request Status icon show the transfer status of the files:

Icon Means

Requested. This item is in the process of being transferred. Refresh the screen to remove this icon after transfer.

5. If the Pending option is enabled for the target area, the request goes into pending status. The request is put in the pending queue and awaits approval. The file being transferred remains in the source area until the pending transaction is approved. Pending files have the following Request Status icon:

Icon Means

Pending. This item is awaiting approval before it can be transferred into this area.

To approve the pending file, see “Approving File Transfers” on page 237.If the Pending option is not set for that area, the transfer process continues.

Step Action

0


6. For project promotions when the relative path is set and the directory does not exist in the target working area, ChangeMan DS prompts to verify that you want this directory created under your working area path.

See “Relative Path” on page 90 for more information.

7. For promotions other than check in:• If an uncontrolled copy of the same-named component exists in the tar-

get area, ChangeMan DS asks if you want to overwrite the existing file. If you choose to overwrite, the file in the target area will be replaced with the new file.

• If a controlled (already checked out) copy of the file exists in the target area, a message indicating that the file is already checked out displays.

See “Synchronizing” on page 165 for information on how this conflict is resolved using the Synchronize option.

Step Action

101

10


8. For check in promotions, if a checked in copy of the same version of the file exists in the target Production area (upon check in of a file that has been checked out by multiple users), you are given a prompt to merge or overwrite. Depending on the file type, you have the following options. See “Text-Based and Binary Files” on page 148 for information on determining if a file is text-based or binary.

File Type Options Available

Text file • Overwrite the existing file. This is possible only if you have the Check in overwrite – Text permission (defined in the user configuration process). Note that a new version of the file is created when overwriting into production, and the old version is archived.

• Merge two versions of the file. This is possible only if you have the Check in merge permission (defined in the user configuration process). See the detailed description of the merge procedure under “Merging as Part of Check In” on page 155.

• Cancel this transaction.

Binary file • Overwrite the existing file. This is possible only if you have the Check in overwrite – Binary permission (defined in the user configuration process). Note that a new version of the file is created when overwriting into production, and the old version is archived.

• Cancel this transaction.

Step Action

2


9. ChangeMan DS places your file in a subdirectory depending on your area configuration:• If a target Development area has the Same preference selected, trans-

fers of individual files and folders from a Production area to a Develop-ment area recreates the subdirectory structure from the Production area.

• If a target Development area has the Same preference selected and a project transfer request has been made from a Production area to a Development area, then the files will be placed in the Development area according to their relative path.

If no relative path has been specified for a particular file, then the file is placed in the appropriate Development area subdirectory as recreated from the Production area.

• If a target Development area has the None preference selected, then transfers of individual files from a Production area to a Development area is placed in the target folder with no directory recreation.

Transfers of folders should recreate the directory structure from that folder on down, recursively, in the Development area.

• If a target Development Areas has the None preference selected, then project transfers use the relative path to set the target location of each file.

If no relative path is set, then files are transferred to the target area with no directory recreation.

Areas must be configured with the Search Tree option enabled for you to use subdirectory level operations.Note: If the subdirectory does not exist in the target area, you are

prompted to let ChangeMan DS create the target subdirectory for you, or cancel the transfer.

See “Area Configuration” in Serena™ ChangeMan® DS Administrator Guide for more information about defining properties for the source and target areas.

10. ChangeMan DS reports the output in the Transfer Request log.See “File Transfer Request Status Dialog” on page 104.

Step Action

103

10


FILE TRANSFER REQUEST STATUS DIALOGThe File Transfer Request Status dialog contains details of what occurred during the transfer process.

By default, the File Transfer Request Status dialog flashes by very fast. To read the detailed information displayed on the screen, either modify the ChangeMan.ini file to read AutoHide=0 or deselect Auto hide on the dialog (if possible).

The end of the output contains a summary of the transfer. The following is a an example summary and an explanation of the outfields:

2 file(s) transferred0 file(s) merged0 request transactions created0 file(s) failed to transfer0 pending transaction(s) created0 file(s) skipped0 warning message(s)2 halted check in transsaction(s) created0 project file(s) are not under source control

The output fields mean the following:

This output field... Means...

file(s) transferred Number of files transferred successfully. The Audit Trail shows the completed transactions.

file(s) merged Number of files merged, when the merge utility is used.

request transaction(s) created

Number of transfer transactions requested on an area where pending or scheduling is used.

file(s) failed to transfer Number of files that failed to transfer because of communication error or permission denial.

pending transaction(s) created

Number of transactions in pending status, when transferring to an area where pending is enabled.

file(s) skipped Number of files skipped because of the user clicking skip or permission denial.

warning message(s) Number of warning messages generated during transfer. For example, Implementation Script failures.

4


CHECKING OUTWhen you invoke a check out, ChangeMan DS retrieves a production version of a file and creates an identical copy in a Development (or QA) area.

Ways to Initiate the Check Out ProcessYou can initiate the check out process in variety of ways, including:

• Click (Check Out) on the Promote toolbar. (Windows client only)

• Choose Promote > Check Out from the menu. (Windows client only)

• Choose Promote > Check Out from a right-click menu for a file, folder, project, or area.

• Choose Edit > Copy for a chosen files, then Edit > Paste with the target area selected. (Windows client only)

• Choose Copy from the right-click menu, then Paste from the target area folder’s right-click menu. (Windows client only)

• Drag-and-drop the selected files to the target Development area on the left side of the ExplorerView. When you drag the mouse pointer outside of the visible part of the screen, the window is scrolled automatically. (Windows client only)

halted check in transaction(s) created

Number of transactions in which no changes were made to the files that were being checked in. This occurs when files in the Production area do not need to be updated and their version numbers remain the same; however, the transfer is complete.

project file(s) not under source control

Number of files that were not placed under control during transfer. For example, external components.

This output field... Means...

105

10


Checking Out Files

Use this procedure to check out files:

Checking Out Files by Choosing a Folder

You can check out an entire folder by selecting it, then choosing the check out option. This checks out all files in the folder and all of its subfolders.

Step Action

1. Expand the Production area node, then select the file to check out.

Files with status shown as , , or are currently checked out. You can check out files concurrently only if you have second check out permission. Select multiple files by holding down the Shift or Control key.

2. Use one of the “Ways to Initiate the Check Out Process” on page 105.

For example, click (Check Out) on the Promote toolbar.

For all check out options (except for drag-and-drop and copy/paste), ChangeMan DS displays a list of target areas for which you are authorized.

3. Select the target area and path if prompted.

4. Complete the Transfer Request dialog as needed.See “Completing the Transfer Request Dialog” on page 96.


Provide passwords for source and target area, if required. See “Transfer Process” on page 99 for the additional steps that ChangeMan DS performs in the transfer process.

• Cancel to exit from the Transfer Request screen and return to the ChangeMan DS main module.

6


Use this procedure to check out the files in a folder:

Checking Out Files Using a File List

The File List toolbar and File List option from a file’s right-click menu are valid only if used on a file that contains a list of file names to be promoted. The list of files embedded in the selected file must be in the appropriate status in ChangeMan DS for the selected promote option to complete successfully.

Step Action

1. Expand the Production area node, then select the folder to check out.

2. Use one of the “Ways to Initiate the Check Out Process” on page 105.


For all check out options (except for drag-and-drop and copy/paste), ChangeMan DS displays a list of target areas for which you are authorized.

3. Select the target area and path, if prompted.





107

10


Use this procedure to check out the file in a file list:

Issuing a Second Check Out Request for a File

You can check out a copy of a file that is currently checked out by another user if you have second check out permission. This permission is given during the user setup process.

Use the standard check out procedure described previously for a second (or subsequent) check out. See “Checking Out Files” on page 106 for more information.

Step Action

1. Expand the Production area node, then select the file to check out.Select multiple files by holding down the Shift or Control key.The selected files must contain the names of the files you want to check out.

2. Choose from one of the following check out options:

• Click Check Out on the File List toolbar.• Choose Edit > File List > Check Out from the menu. • Choose File List > Check Out from the file’s right-click menu.ChangeMan DS displays a list of target areas.

3. Select the target area, then click OK.ChangeMan DS verifies the list of files in the selected area.

4. Select the target Development area, then click OK.





8


ChangeMan DS notifies you when a file is currently checked out, and asks you if you want to continue with the check out.

Checking Out a Previous Version of a File

You can check out any version of a file if an archive path is specified for the Production area. Where appropriate, ChangeMan DS rebuilds that version of the file on demand, using reverse delta archives applied to the current version. See “Binary Versus Text-Based Transfers” on page 96 for information on how ChangeMan DS stores deltas for different files.

For true text-based files, only the differences between the current and prior versions are stored in the archives. For binary files, the entire prior version is stored in the archives.

See “Area Configuration” in Serena™ ChangeMan® DS Administrator Guide for more information about defining an area archive path.

To check out a previous version of a file:

Step Action

1. Initiate the transfer process by using the drag-and-drop method or commands.

2. Click Advanced in the Transfer Request dialog window (if Branching permissions are not allowed for the user or group, the Advanced option is not available).

3. Select the data row, then click Edit.

4. Select the version to check out, then click OK.The ChangeMan DS Advanced Check Out dialog displays the current version (Source Version) and the version to be checked out (Target Version)

5. Click OK to complete the ChangeMan DS Advanced Check Out dialog.

6. Continue to the transfer process as described in “Transfer Process” on page 99.

109

11


Canceling a Check Out Transaction for a File

If you decide not to keep a file checked out, you can cancel the check out at any point in the process before it is checked back in (you must have been granted permission to cancel your own check out).

To cancel a check out transaction:

Checking Out a ProjectTo check out at the project level, select the project name node on the ExplorerView.

You initiate a file level check out if you select the Attachments node or folders under the Attachments node, then select files from the files listed on the right side of the display.

Step Action

1. Expand the area node, then select the file for which the check out record is to be removed.You can select multiple files by holding down the Shift or Control key.


• Click Cancel check out from the Promote toolbar.• Choose Promote > Cancel Check Out from the menu.• Choose Promote > Cancel Check Out from the file’s right-click

menu.Note: You can cancel the check out transaction by deleting the

corresponding check out record from the Audit Trail report; however, deleting a record from the Audit Trail is unwise in case you choose the wrong record.

3. You are prompted to verify the selection.Click:• OK to cancel (delete) the check out request.• Cancel to abort the request.When you click OK, the check out record is removed from the metadata database.

0


To check out a project:

Step Action

1. Select the project to check out:

Projects with status shown as have one or more files checked out. You can check out project files concurrently only if you have second check out permission.

2. Use one of the “Ways to Initiate the Check Out Process” on page 105:


For all check out options (except for drag-and-drop and copy/paste), ChangeMan DS displays a list of possible target areas for which you are authorized.

3. You are prompted to define a project working location if you have not already assigned one.

Click to select from the list of Development areas for which you are authorized. Expand the area folders to choose the path. For drag-and-drop and copy/paste check outs, ChangeMan DS does not prompt for a working area path.

4. Complete the Transfer Request dialog.The left side of the dialog is blank because projects can span multiple areas. The project name is pre-filled in the Project field.To check out only a select number of files in this project, type the list of files in the File field. See “Completing the Transfer Request Dialog” on page 96.

111

11


Issuing a Second Check Out Request for a Project

You can check out a project that already belongs to another user by following the regular check out procedure.

ChangeMan DS detects the status of each file in the project and gives appropriate warnings and prompts:

• File checked out to the same location.

ChangeMan DS warns you that it cannot create a second check out record, and asks if you want to skip the file and continue.

• File checked out to a different location.

ChangeMan DS warns you that the file is checked out already, and asks if you want to perform a second check out.



• Cancel to exit from the Transfer Request screen and return to the ChangeMan DS main module.

6.Click Refresh on the main ChangeMan DS window (or choose Refresh from the project right-click menu) to see the change in the status of the transferred project.ChangeMan DS refreshes the screen by section, so make sure you select a node at or below the Projects node on the left side view before choosing Refresh.The detailed history of this transfer is available through the Audit Trail report.See for “Audit Trail” on page 213 more information.

Step Action

2


Canceling a Check Out Transaction for a Project

If you decide that you no longer want to keep a project checked out, you can cancel the check out at any point in the process before it is checked back in again. This cancels the check out for each checked out file in the project.

You must have permission to cancel your own check out. The user or group permission setting for this is Audit Permissions, Delete transactions, Check out.

See “Users and Groups” in Serena™ ChangeMan® DS Administrator Guide.

The procedure for canceling a project check out is:

Step Action

1. Select the project from which to remove the check out record.


• Click Cancel check out from the Promote toolbar.• Choose Promote > Cancel Check Out from the menu.• Choose Promote > Cancel Check Out from the project’s right-click

menu.Note: You can cancel the check out transaction by deleting the

corresponding check out record from the Audit Trail report; however, deleting a record from the Audit Trail is unwise in case you choose the wrong record.

3. You are prompted to verify the action.Click:• OK to cancel (delete) the check out request.• Cancel to abort the request.When you click OK, ChangeMan DS removes the check out record from the metadata database.

113

11


CHECKING INAfter you successfully completed the check in (Bring Home) transaction, ChangeMan DS automatically:

• Introduces a new version of the file into its Production area and assigns a new version number to it.

• Saves the old version of the file as an archive (if an archive path was indicated for the Home area).

• Executes any user-defined Implementation Scripts for the area such as build or distribution procedures. See “Implementation Scripts” in Serena™ ChangeMan® DS Administrator Guide.

• Deletes the copy of the file from the source area after the transfer request completes, if the Delete From option was selected for the source area. See “Area Configuration” in Serena™ ChangeMan® DS Administrator Guide.

Ways to Initiate the Check In ProcessYou can initiate the check in process in variety of ways, including:

• Click (Check In) on the Promote toolbar. (Windows client only)

• Choose Promote > Check In from the menu. (Windows client only)

• Choose Promote, then Check In from the file’s right-click menu.

• Click (Bring File(s) Home) on the Promote toolbar. (Windows client only)

• Choose Promote > Bring Home from the menu.(Windows client only)

• Choose Promote > Bring Home from the file’s right-click menu.

• Choose Edit > Copy from the menu for the chosen files, then Edit > Paste for the chosen target area. (Windows client only)

• Choose Copy from the file right-click menu, then Paste from the target area folder’s right-click menu. (Windows client only)

• Drag-and-drop the selected files to the target Development area on the left side of the ExplorerView. When you drag the mouse pointer outside of the visible part of the screen, the window scrolls automatically. (Windows client only)

Note Bring Home is enabled only in Production area views.

4


Checking In Files

This procedure describes how to introduce a new version of a file to a Production area:

Step Action

1. Expand an area node, then select the file you want to check in. You cannot check in from an End User area.

In Development or QA area views, files with status shown as or

are currently checked out and reside in the selected area. Make sure you choose a file with one of these status icons if you are promoting from a Development or QA area view.

In Production area views, files with status shown as , ,

or are checked out. Make sure you choose a file with one of these status icons if you are promoting from a Production area view.Select multiple files by holding down the Shift or Control key.

2. Use one of the “Ways to Initiate the Check In Process” on page 114:

For example, click (Check In) on the Promote toolbar.





115

11


Checking In New Files

Introduce a new file that has not been loaded into ChangeMan DS by checking in the file.

Use the Promote > Check In option as described in “Adding to Control Using Promote Options” on page 49.

Checking In the Same Version of a File

If multiple copies of a file are checked out, and if ChangeMan DS detects a second (or subsequent) check in of a file, ChangeMan DS prevents the second copy from inadvertently overlaying the prior checked in copy. ChangeMan DS prompts you with several choices to resolve the parallel development situation.

When you overwrite into the Production area, ChangeMan DS assigns the next version number to the newer file and replaces the older file with the newer file. The older file is archived, and is made accessible through the File Tree and Audit Trail.

You can also use this procedure to check in a file that has not been checked out (perhaps in an emergency situation in which you want to overwrite the existing version without moving through the normal process flow).

Use this procedure to do a second (or subsequent) check in of the same version of a file:

Step Action

1. Expand an area node, then select the file to check in. You cannot check in from an End User area.


are currently checked out and reside in the selected area. Make sure you choose a file with one of these status icons if you are promoting from a Development or QA area view.

In Production area views, files with status shown as , ,

or are checked out. Make sure you choose a file with one of these status icons if you are promoting from a Production area view.Select multiple files by holding down the Shift or Control key.

6


Checking In a Project

Projects point to Production-level versions of files and checked out (Development-level) versions of files. Therefore, you must tell ChangeMan DS from where to promote the files.

Both QA and Development are considered to be Development areas in this context.

Use this procedure to check in a project:





Provide passwords for source and target area, if required. See “Transfer Process” on page 99 for the additional steps that ChangeMan DS performs in the transfer process.


Step Action

1. Select the project to check in.

Projects with status shown as have one or more of their files checked out.




Step Action

117

11


4. Click:• Transfer to initiate the file transfer process.• Cancel to exit from the Transfer screen and return to ChangeMan

DS main module.If you select Transfer, the Select source file location dialog displays.

5. Choose one of the following options:

Choose… To…

Production All

Transfer all of the checked out files from their Production areas.

Production Transfer the designated file from its Production area.

Area Preference

Transfer all checked out files from your currently-assigned project working location. See “Using Projects” on page 63 for more information on project working location.

User Preference

Transfer all of your checked out files from the locations in which you are the assigned owner of the files.

Skip All Disregard the transfer request for all remaining files in the request.

Skip Disregard the transfer request for the designated file.

Select Transfer the selected checked out files from their current location.

Cancel Terminate the transfer request.

6. See “Transfer Process” on page 99 for additional steps that ChangeMan DS performs in the transfer process.

Step Action

8


PROMOTINGWhen you promote files, you either advance the files to an area, which represents the next stage in a software development process flow, or return files to a previous area, which represents a rejection that the proper items were completed in the previous stage.

You cannot promote a file to a working target area where a controlled file of the same name already exists. You will receive the following message: “The destination file is already checked out.” If this occurs, cancel your promotion request.

The action is prohibited to prevent you from overlaying another team member’s work. If you are authorized to merge/overwrite in the target area, you can use the Synchronize option instead to merge/overwrite the target file. See “Synchronizing” on page 165 for more information on synchronizing files.

You can promote from a Production area, usually for the purpose of transferring from one Production area to another. However, this section focuses on promotion from Development or QA areas.

You cannot promote from an End User area.

Ways to Initiate the Promote ProcessYou can initiate the promote process in variety of ways, including:

• Click (Promote to QA) from the Promote toolbar. (Windows client only)

• Click (Promote to Development) from the Promote toolbar. (Windows client only)

• Click (Promote to Production) from the Promote toolbar. (Windows client only)

• Choose Promote > Promote to QA from the menu. (Windows client only)

• Choose Promote > Promote to Development. (Windows client only)

• Choose Promote > Promote to Production. (Windows client only)

• Choose Promote > Promote to QA from the right-click menu.

• Choose Promote > Promote to Development from the right-click menu.

• Choose Promote > Promote to Production from the right-click menu.

• Choose Edit > Copy from the menu for the chosen files, then Edit > Paste for the chosen target area. (Windows client only)

• Choose Copy from the project’s right-click menu, then Paste from the target area folder’s right-click menu. (Windows client only)

119

12


• Drag-and-drop the selected project to the target Development area on the left side of the ExplorerView. When you drag the mouse pointer outside of the visible part of the screen, the window is scrolled automatically. (Windows client only)

Promoting Files

You can promote from a Production area, usually for the purpose of transferring from one Production area to another.

This procedure, however, assumes that you are promoting from Development or QA areas.

To promote a file:

Step Action

1. Expand the source area (Development or QA) node, then select the file to promote.


are currently checked out and reside in the selected area. Make sure you choose a file with one of these status icons if you are promoting from a Development or QA area view.Select multiple files by holding down the Shift or Control key.

2. Use one of the “Ways to Initiate the Promote Process” on page 119, depending on the current source area location and the desired target location.

For example, click (Promote to QA) on the Promote toolbar.

For all of the promote methods (except for drag-and-drop and copy/paste), a list displays the target areas for which you are authorized.


0


Promoting a Project

You can promote a project that is not checked out (is in Production status), usually for the purpose of transferring a set of files from one Production area to another.

This procedure, however, focuses on promotion of projects checked out to Development or QA areas.




• Cancel to exit from the Transfer screen and return to the ChangeMan DS main screen.

Step Action

1. Select the project to promote.

Projects with a status shown as have one or more of their files checked out.

2. Use one of the “Ways to Initiate the Promote Process” on page 119, depending on the current source area location and the target location.

For example, click (Promote to QA) on the Promote toolbar.

For all of the promote methods (except for drag-and-drop and copy/paste), a list displays of possible target areas for which you are authorized.


Step Action

121

12


4. Complete the Transfer Request dialog.To check out only some of files in this project, type a list of files in the File field. See “Completing the Transfer Request Dialog” on page 96.

5. Click:• Transfer to initiate the file transfer process.• Cancel to exit from the Transfer screen and return to ChangeMan

DS main module.Upon transfer, the Select source file location dialog displays.

6. Projects point to Production level versions of files and checked out (Development level) versions of files; therefore, you must indicate the files source. Note that both QA and Development are considered to be Development areas in this context.Choose from the following file sources:

Choose… To…

Production All Transfer all of the checked out files from their Production areas.

Production Transfer the designated file from its Production area.

Area Preference Transfer all checked out files from your currently-assigned project working location. See “Using Projects” on page 63 for more information on project working location.

User Preference Transfer all of your checked out files from the locations in which you are the assigned owner of the files.

Step Action

2


DISTRIBUTINGDistribution is the process of forwarding files or projects to locations for end users. Usually, executables and files needed for the application to run are distributed. For example, if the application is a Web application, all files needed for the Web application are distributed.

ChangeMan DS Software Distribution provides you with the following features:

• Distributing all types of custom and commercial software.

• Packaging files into projects and distributing them to heterogeneous platforms as a complete change package.

• Scheduling the push/pull distribution for a specific date and time.

• Supporting both text and binary files.

• Maintaining comprehensive audit trail information about distribution activities.

You can initiate distribution interactively with the ChangeMan DS Promote options, or automatically through ChangeMan DS scripting capabilities.

Skip All Disregard the transfer request for all remaining files in the request.

Skip Disregard the transfer request for the designated file.

Select Transfer the selected checked out files from their current location.

Cancel Terminate the transfer request.

7. Provide passwords associated with the source and target areas if required. See “Transfer Process” on page 99 for information on the ChangeMan DS transfer process.

Step Action

123

12


Interactive Ways to Initiate the Distribution Process

To initiate the distribution process for either files or projects:

• Click Distribute to end users on the Promote toolbar. (Windows client only)

• Choose Promote > Distribute to End Users from the menu. (Windows client only)

• Choose Promote > Distribute to End Users from the file’s right-click menu.

• Choose Edit > Copy for the chosen files, then Edit > Paste for the chosen target area. (Windows client only)

• Choose Copy from the file right-click menu, then Paste from the target area folder’s right-click menu. (Windows client only)

• Drag-and-drop the selected files to the target End User area on the left side of the ExplorerView. When you drag the mouse pointer outside of the visible part of the screen, the window is scrolled automatically. (Windows client only)

See “Interactive Distribution of Files” on page 124 and “Interactive Distribution of a Project” on page 125 for more information on interactive distribution.

Automated Ways to Initiate the Distribution Process

• Automatic Distribution by Implementation Script on an area

• Automatic Distribution by Post Compile Option during builds

• Automatic Distribution by Command Line Interface with a batch job (.bat or shell script).

Interactive Distribution of Files

ChangeMan DS lets you distribute files from a Production area to End User areas. This process makes a copy of the files in the designated area, without updating the location and owner status of the file. A record of the distribution transaction is placed in the Audit Trail.

4


To distribute files with the ChangeMan DS ExplorerView screen:

Interactive Distribution of a Project

ChangeMan DS lets you distribute a project to an End User area. This makes a copy of the project files in the designated area, without updating the location and owner status of the files. A record of each distribution transaction is placed in the Audit Trail.

Although distribution is typically done from a Production area, you can distribute to End User areas from other area types, if the process flow allows it.

Step Action

1. Expand a Production area, then select the file to distribute.Select multiple files by holding down the Shift or Control key.Distribute files to End User areas from area types other than Production areas, if allowed by your process flow.

2. Use one of the “Interactive Ways to Initiate the Distribution Process” on page 124:

For example, click Distribute to end users on the Promote toolbar.For all of the distribute methods (except for drag-and-drop and copy/paste), ChangeMan DS displays a list of possible target End User areas for which you are authorized.






125

12


To distribute a project with the ChangeMan DS ExplorerView screen:

Automatic Distribution by Implementation ScriptEach area may have one script associated with it. When ChangeMan DS transfers a file into an area, the system automatically identifies and executes the area's script.

The ChangeMan DS command line interface lets you execute the distribute promote option from an implementation script. From the script, you can execute the command directly, or you can save the command in a batch file (DOS) or a script file (UNIX), and run the batch file or script from the implementation script.

Save the commands in batch or script files when you want to version control your scripts. Batch or script files let you test your distribution in the native operating system before running it from your implementation script.

Step Action

1. Select the project to distribute.

2. Use one of the “Interactive Ways to Initiate the Distribution Process” on page 124:

For example, click Distribute to end users on the Promote toolbar.For all of the distribute methods (except for drag-and-drop and copy/paste), ChangeMan DS displays a list of target End User areas for which you are authorized.






6


This Windows script conditionally executes PRS_Distribute.bat for all files ending in “.exe” (executables):

if %vcs_suffix%==.exe call "d:\scripts\PRS_Distribute"

The command in the batch file looks like this:

REM Distribute to PRS End User area upon check in to production area"d:\program files\serena\changeman\ds\cmnxfer" -h:%main_node% -r -u:user -ps:pswd -f:"%vcsfile%" -fa:PrsProdMain -fp:"D:\dsareas\PrsProdMain" -ta:PrsEU -tp:"D:\dsareas\PrsEULoc\Test" -d:"PRSEU distribute" -v

where "d:\program files\ through -v are all on one line of text. This example distributes any file with a .exe extension to the End User area (PRSEU) from the Production area (PrsProdMain) upon check in of that file to the Production area where the Implementation Script is defined.

See “Areas” in the ChangeMan DS Administrator’s Guide for more information on attaching Implementation Scripts to areas.

Automatic Distribution by Post Compile OptionYou can execute the command line interface from a Post Compile script in the ChangeMan DS Make Configuration dialog. The following is a post compile script that executes a batch file containing a command:

call “D:\scripts\Build_Distribute.bat”

The command in the batch file looks like this:

REM Distribute executables to End User area upon generation by build"d:\program files\serena\changeman\ds\client\cmnxfer" -h:host -r -u:user -ps:pswd -f:"%VCS_TARGET_FILE%" -fa:VCProd -fp:"D:\dsareas\VCProd\ClassVC" -ta:VCEU -tp:"D:\dsareas\VCEU\ClassVC" -d:"VCEU distribute" -v

where "d:\program files\ through -v are all on one line of text. This example distributes any file with a .exe extension to the End User area (VCEU) from the Production area (VCProd) upon generation of the build.

See “Defining Make Procedure Post Compile Script” on page 180 for information on accessing the Post Compile tab.

127

12


Automatic Distribution by Command Line InterfaceExecute the Serena ChangeMan Command Line Interface directly from the operating system command prompt to distribute files. Enter the commands directly at the command line, or save them in a batch file (DOS) or a script file (UNIX) to be executed when the batch file or script is run.

See the Serena® ChangeMan® DS Command Line Interface Guide for more information.

PERMISSIONS REQUIRED TO TRANSFER FILESChangeMan DS lets you transfer files and projects between only those source and target areas for which you have permission to carry out file transfer activities.

Your system administrator must give you the necessary permission to perform the transfer operations at all of these levels:

• User or Group Level (called the global level) - The correct permissions need to be set for the transfer that you are performing such as check out, check in, and create branch. These may need to be set at both the project and file level.

For information on setting these permissions, see “Users and Groups” in the Serena™ ChangeMan® DS Administrator Guide.

• Area Level (object level) - Transfer permissions can be overridden at the area level using the Authorization List for an area. This means that although a user has the ability to check out at the global level, he may not be allowed to check out from a particular area.

See “Area Authorization” in Serena™ ChangeMan® DS Administrator Guide.

• Project Level (object level) - Transfer permissions can be overridden at the project level using the Authorization List for a project. This means that certain permissions can be prohibited to the user for certain projects.

See “Project Authorization” in Serena™ ChangeMan® DS Administrator Guide.

TROUBLESHOOTING FILE AND PROJECT TRANSFERS

Why doesn’t a file (or a series of files) get promoted?

8


ChangeMan DS verifies that transactions, especially batch transactions, complete successfully. Often, system or network problems can interrupt large transactions. If this occurs, ChangeMan DS keeps all files in the source area.

You can see transactions that did not complete in an Audit Trail report, especially if you filter by Aborted status. Transactions that did not complete show an error message in the Description field instead of a user description.

What does the “File filename failed process control rule” message mean?

This message indicates that the transfer request violates at least one process flow rule.

For example, you try to check in the file directly to Production from Development, but your process flow rules let you promote this file to a QA area only.

ChangeMan DS allows the transfer to take place only if it is permitted by Global, Application, and Project level Process Flow rules.

You must change the Process Control rule and re-initiate the transfer request, or issue a transfer request that follows a different path to complete the transaction.

What does the “You are not authorized to check out file filename from area” message mean?

This message displays when the requester violates security permissions defined during the system configuration process.

To complete the transfer you must check the following security levels:

User Setup:

File Permissions The administrator allows certain users to check out, check in, merge, and branch individual files.

Project Permission The administrator allows certain users to check in or check out entire projects, attach files to projects, or create a release.

Area Setup:

Authorization List The administrator allows certain users to have access to specific areas. Each member of the Authorization List can have a unique set of permissions.

129

13


See "Security” in the Serena® ChangeMan® DS Administrator’s Guide for more information.

What does the “No requests were created for project projectname” message mean?

ChangeMan DS displays this message when you attempt to transfer a project that has no files attached to it.

How can I view the File Transfer Request Status dialog?

By default, the File Transfer Request Status dialog flashes by very fast. To read the detailed information displayed on the screen, modify the ChangeMan.ini file to read AutoHide=0 (or deselect Auto hide on the dialog) and set DetailState=1.

Project Setup:

Authorization List The administrator allows certain users to have access to specific projects. Each member of Authorization List can have a unique set of permissions.

0


131

13


2

BRANCHING
8 A branch creates a separate line of development that diverges from a baseline, or another branch. This allows variations of the same file to be in development at the same time without affecting the baseline copy. Branching creates a copy of the file and maintains the relationship in the file’s history.
For example, developer A is ready to make a special modification to the software application for a specific customer; however, there is another project already in motion for that application, and Developer A doesn't want her customer-specific changes to affect the work going in that project. Therefore, developer A creates a branch upon check out. The branch begins a second development path, separate from the baseline version, allowing the main product to continue along the main development path. If, in the future, product management decides that the changes made by developer A should be applied to the main product for general distribution, the changes (branch) can be merged into the main development path.

In the File Tree, a branch appears as parallel lines of development. The branched file (copy) restarts the versioning at one, and appears with a solid outline:

133

13

Chapter 8: Branching

A branch differs from multiple concurrent check outs. You use multiple concurrent check outs when the component follows one main path. For example, multiple developers can work on different parts of a shared component that is handed over at the same time. Instead of using a branch, each developer checks out the file, makes the changes, then the changed files are merged and checked in to production.

Concurrent check outs appear like this on the File Tree:

Whenever a second user checks out a file, ChangeMan DS notifies the user that the file is already checked out, and asks whether to perform a second check out.

Some typical reasons for creating branches are:

• Maintaining program changes (patches) without affecting the main development process.

• Implementing custom enhancements without affecting the main baseline version.

• Keeping new versions separate from the current line of development when starting to work on a new release of a software application.

You can branch files individually, or you can branch an entire project or release. ChangeMan DS lets you assign a new file name to the branch, or it creates a new name automatically. You can place the new branch in the same area as the original file, or put it in another location. If you assign the branch to a different location from where the original file resides, you can assign the branch the same name as the original.

The record of the created branch displays in the Audit Trail report and File Tree. See “Viewing the Audit Trail for One File” on page 214 and “Viewing File Information from the File Tree” on page 211.

4


Only users with the required permissions can create branches:

• Production Branch permission allows branching upon check in and is required for Release branches because a check in is invoked automatically during that process.

• Development Branch permissions allow branch upon check out.

See “Users and Groups” in Serena® ChangeMan® DS Administrator’s Guide for more information.

CREATING A BRANCH OF A FILE DURING CHECK OUT

You can create a branch during the check out process if you want to initiate the branch before you start working on the file.

Use this procedure to create a branch during check out:

Step Action

1. Select a file.

2. Initiate the check out process using the drag-and-drop method or file commands (Promote > Checkout).See “Ways to Initiate the Check Out Process” on page 105 for more information.

3. In the Transfer Request dialog window, click Advanced. ChangeMan DS displays the ChangeMan DS Advanced Checkout screen.

135

13


4. Select the data row, then click Edit.

The ChangeMan DS Checkout Version dialog displays.

5. Select Create Branch.ChangeMan DS automatically selects a name for the new branch. You can either:• Change the suggested

name by clicking inside the Name field.

• Use the original file name for the branch name by choosing the corresponding option.

6. Click OK to close the ChangeMan DS Checkout Version dialog.

7. Click OK to close the ChangeMan DS Advanced Checkout dialog.

8. Add any additional information to the Transfer Request dialog, then click Transfer.See “Completing the Transfer Request Dialog” on page 96 for information on other fields in this dialog.

Step Action

6


CREATING A BRANCH OF A FILE DURING CHECK IN

You can create a branch during the check in process if you want to initiate the branch after you finish working on the file.

To create a branch during check in:

9. If you selected to use the same name, select the new physical location to which to branch.

Step Action

1. Select a file.

2. Initiate the check in process using the file commands.See “Ways to Initiate the Check In Process” on page 114 for more information.

3. Click Advanced in the Transfer Request dialog window. ChangeMan DS displays the ChangeMan DS Branch screen.

Step Action

137

13


Note If branching when checking in and you do not give the branch a new name, the branch will be checked in, but the original file will remain checked out. This allows you to continue working on the original file. If you give the branch a new name, then both files will be checked in.

4. Select the Create Branch box.You can let ChangeMan DS automatically select a name for the new branch, or you can use the original file name for the branch name by choosing the corresponding option.

5. Click OK to close the ChangeMan DS Branch dialog.

6. Add any additional information to the Transfer Request dialog (if necessary), then click Transfer.See “Completing the Transfer Request Dialog” on page 96 for information on other fields in this dialog.

7. If you elected to use the same name, select the new physical location to which to branch.

Step Action

8


CREATING A BRANCH OF A PROJECTYou can create a branch during the check in or check out process for a project. This causes a branch to be created for each file attached to the project.

Create the branch on check out if you want to initiate the branch before you begin working on the project files. Create the branch on check in if you want to initiate the branch after you finish working on the project files.

The status of the current project does not reflect the checked out or checked in status upon completion of the branch because the current attachments of the project are not affected. You can get a list of the branched files for the project by running an Audit Trail report. See “Audit Trail” on page 213.

Use this procedure to create a project branch during check out or check in:

Step Action

1. Select a project.

2. Initiate a check in or check out process for a project using the file commands.See “Checking In a Project” on page 117 or “Checking Out a Project” on page 110 for more information.

3. Click Advanced in the Transfer Request dialog window. ChangeMan DS displays the ChangeMan DS Branch screen.

4. Check the Create Branch box.You can let ChangeMan DS automatically select names for the branches of the project’s files, or you can use the original file names for the branch names by choosing the corresponding option.If you use the same names, ChangeMan DS prompts you during the transfer for a new Home area to which to branch.

5. Click OK.

139

14


CREATING A BRANCH OF A RELEASEYou can create a branch of a release if you want to maintain a separate line of development on a particular version of a project.

The Maintain function branches the release to a new location.

This function requires permissions to branch to Production because it copies the old release to a designated Production area. It also requires permissions to create a project, because it automatically creates a new project for the branched release.

See “Users and Groups” in the Serena® ChangeMan® DS Administrator’s Guide for more information.

Use this procedure to branch a release:

6. Finish the check in or check out request as described in “Checking In a Project” on page 117 or “Checking Out a Project” on page 110.After completing the request, each file in the project is branched.

Step Action

1. Select the release.

2. Right-click and choose the Maintain option from the menu.The ChangeMan DS Maintain frozen release window displays.

3. Specify a project name in the New field.This is the project to which the branched files will be attached. The new project will be created automatically and the branched files attached to it during the Maintain operation.

Step Action

0


4. Select each From Area in the list, then click Edit to specify the target area for the branch.The From Area column lists the Production areas where the release’s attachments reside. The From Base Path column displays the highest common directory path for the attachments from each area. Note that more than one area displays only if the release's attachments span more than one Production area.

5. Select the target location by expanding the nodes shown in the ChangeMan DS Tree of Areas window, then click OK.After you select a target location for all of the From Areas, click OK. The ChangeMan DS Tree of Areas closes, and the ChangeMan DS Maintain frozen release dialog displays.

Step Action

141

14


6. Click OK on the ChangeMan DS Maintain frozen release dialog.

7. If necessary, select a list entry and click Edit to specify a different target location for a specific file of the release.

8. Click OK.

9. Click Transfer to finish the branch request, answering the prompts to place the new files under source control.

Step Action

2

COMPARING FILES
9 The comparison utility compares two files ,or two different versions of a file, allowing you to see the changes made to the file.
When you perform a compare, ChangeMan DS invokes a comparison utility specific to your client (Windows, Web browser, and Java).

The comparison results depend on the type of files that are being compared and their differences:

• For text-based files that have differences, ChangeMan DS invokes the ChangeMan Diff utility and displays a side-by-side comparison.

See “Text-Based Comparisons” on page 147 for an example screenshot.

• For text-based files that have no differences, a message displays indicating that the files are identical.

• For Microsoft® Word documents, ChangeMan DS invokes the ChangeMan Word Diff utility. Microsoft Word must be installed on the client machine for this to complete successfully.

In the Web client, ChangeMan Word Diff is not invoked for Word documents, rather the ChangeMan Diff utility is invoked.

See “Microsoft® Word Document Comparisons” on page 149.

• For binary files:

— In the Java and Web browser clients, a message displays indicating that the files are identical or different.

— In the Windows client, if the binary files are identical, a message displays to that effect.

If the files are different and they are OLE registered on the system, ChangeMan DS launches the ChangeMan DIFF View utility, which shows the files side by side. For example, graphic files (JPEGs or GIFs) launch the ChangeMan DIFF View utility.

See “Text-Based and Binary Files” on page 148 for rules on how ChangeMan DS determines if a file is text-based or binary.

143

14

Chapter 9: Comparing Files

You can compare versions through the File Tree module, the Audit Trail window, the Show Differences command, or launching ChangeMan Diff directly:

• The File Tree lets you to select any two versions of a file, including branched files. See “Comparing Files from the File Tree” on page 144.

• To compare a file with its immediately-preceding production version, use the Audit Trail window or Show Differences command.

For example, if a file is checked out, and the check out transaction for that version (say version 3) is selected in the Audit Trail, the checked out version is compared to the latest production version, even if that is the same version number at the time. If the check in transaction for version 3 is selected for compare, then version 3 is compared to version 2 in production.

• Launching the ChangeMan Diff directly allows you to compare any two files. To launch ChangeMan Diff, run eChangeDiff from within the \Client directory.

See“Comparing Files with the Show Differences Command” on page 144 and “Comparing Files from an Audit Trail Report” on page 145 for more information.

COMPARING FILES WITH THE SHOW DIFFERENCES COMMAND

The Show Differences command lets you compare a file with its previous version.

The Show Differences command is available only when the file has a previous version. It is found on the file’s right-click menu, the Files toolbar, and the Files menu.

To use the Show Differences command, select a file, then choose the Show Differences command.

COMPARING FILES FROM THE FILE TREEThrough the File Tree, you can compare any two versions of the file that share the same ancestry, including file branches.

4


Use this procedure to compare two files from the File Tree:

COMPARING FILES FROM AN AUDIT TRAIL REPORT

From a report in the Audit Trail window, you can compare a file with its immediately-preceding version. For example, you can compare version 5 of a file to its version 4, but not to earlier versions. You can compare files that have been checked in, or files that have been checked out if changes were made to the checked out files.

Step Action

1. Access the File Tree by selecting a file and either:• right-clicking and choosing File Tree.

• clicking from the Files toolbar.

2. Select an icon representing one version of the file.

3. Hold the Shift key, then select a second version icon.The order in which files are selected determines if lines are considered added or deleted. If you select the files so that the newest file is File 2, then the added lines appear color-coded as added. Otherwise, they appears as deleted.

4.Click Compare versions from the File Tree toolbar.

If you compared two text-based files, the ChangeMan Diff utility appears in Diff mode. See “Text-Based Comparisons” on page 147 for more information on this screen.If you compared two Microsoft Word document files, the ChangeMan Word Diff utility appears. See “Microsoft® Word Document Comparisons” on page 149 for more information on this screen.Note: The ChangeMan Word Diff utility doesn’t appear in the Web

client.

5. Exit the comparison utility by choosing File > Exit (or using other standard Windows exit methods).

145

14


The comparison results depend on the transaction type selected. Selecting different transaction types for the same version of a file can cause different results, because a transaction can point to either checked in or checked out versions of the files.

The check in transaction points to the Production version so that the current and previous versions of Production will be compared, whereas the check out transaction points to the working area version so that the working area and current Production version are compared.

If the working area version was deleted, ChangeMan DS issues an error message that the file was not found in the system.

To compare non-consecutive versions of a file, you must use the File Tree.

Use this procedure to compare files from an audit report:

Step Action

1. Open the ChangeMan DS Audit Trail dialog for a file.

2. Select a transaction from the list.Note: Select only Check Out or Check In transactions. If you select

another transaction type and choose the compare option, ChangeMan DS issues a message that the transaction is not valid for this operation.

3.Click (or choose Compare from the right-click menu).

In the Web client Audit Trail, choose Show Differences from the right-click menu.If you compared two text-based files, the ChangeMan Diff utility appears in Diff mode. See “Text-Based Comparisons” on page 147 for more information on this screen.If you have compared two Microsoft Word document files, the ChangeMan Word Diff utility appears. See “Microsoft® Word Document Comparisons” on page 149 for more information on this screen.Note: The ChangeMan Word Diff utility doesn’t appear in the Web

client.

4. Exit the comparison utility by choosing File > Exit (or using other standard Windows exit methods).

6


TEXT-BASED COMPARISONSWhen you compare differing text-based files, you see the ChangeMan Diff screen in Diff mode.

The exact appearance of the ChangeMan Diff utility depends on the client that you are using (Windows, Java, or Web browser).

The main screen appears as follows (Windows client screenshot):

The right two windows display the compared files; their title bars show the current file name, location, and version. Line numbers for the text display on the left side of each window.

The Map provides a micro view of the entire file, with arrows indicating the current positioning of the file, and colors indicating positions of differences. Toggle the Map display by choosing the View > Show/Hide Map option.

The map and the text lines in the right two windows are highlighted in different colors to represent different types of changes. When you place the cursor in the text of a file, the legend displays in the status bar. If you want to change the default background colors, see “Changing Text Background Colors in ChangeMan Diff” on page 431.

The order in which files are selected determines if lines are considered added or deleted. If you select the files so that the newest file is File 2, then the added lines appear color-coded as added. Otherwise, they appear as deleted.

File 2File 1Map Status Bar

147

14


The following sections describe the functionality available in the ChangeMan Diff module:

• “Altering the Display Mode” on page 430

• “Changing Display Options” on page 431

• “Changing Text Background Colors in ChangeMan Diff” on page 431

• “Merging the Files from a Comparison” on page 432

• “Selecting Templates” on page 433

• “Synchronizing Displayed Lines in ChangeMan Diff” on page 434

• “Toggling Display of Map and Status Bar” on page 435


• “Using Bookmarks” on page 444

TEXT-BASED AND BINARY FILESChangeMan DS decides whether a file is binary or text-based by examining the file, and the result affects how ChangeMan DS compares the file, displays the file, and stores archived versions of the file.

The Communication agent on the Production area machine is responsible for storing the new file and archiving the old version. It uses functions that depend on the current locale to determine if the file is text or binary. So if the locale says that for example the character “ä” is to be considered text because it is part of the local language, then ChangeMan DS considers it text as well.

Depending on the file type (Text-based or Binary), the file is stored as either text or a zip archive. It is important to find out what type the file is because the text file’s delta depends on the correct file type assessment to work properly.

Rules that ChangeMan DS uses to determine if a file is binary

• ChangeMan DS considers a file to be binary for a locale if it contains “special characters” for that locale. A “special” character refers to a nonprintable(binary) character for a locale. For an English locale, characters such as “ä” are “special” to it. See “Locale Setting” on page 149.

• PDF files are considered binary.

• Any text-based file that has a line longer than 512 characters is considered binary.

8


You can force a file to be transferred as binary by ChangeMan DS, which means that the file is transferred as a zip archive. See the description for the bintransforce variable in “vcs_serv.ins” in the Serena® ChangeMan® DS Administrator’s Guide for more information.

The Comparison utility executes on the requester's machine; therefore, the comparison result depends on the locale of the requester.

Example of Comparing Text-Based Files on Multiple ServersFor example:

File1 resides on Machine1 handled by Agent1. File1 is written by a German programmer with embedded German comments. Machine1 and Agent1 have a German locale.

File2 resides on Machine2 handled by Agent2. File2 was written by a Russian programmer putting comments in Cyrillic. Machine2 and Agent2 have a Russian locale.

When their manager in the United States performs a comparison (or merge), both files are binary because the manager has an English locale.

Locale SettingThe locale setting consists of "LanguageCode_CountryCode.Encoding." The encoding decides what characters are in the locale. The first two parameters tell the locale handling routines which characters (from the character set) should be treated as text and which are binary.

In the case of “de_DE.ISO8859-1” what is considered as text depends on which characters in the ISO8859-1 character set are used by the Germans in Germany (de_DE).

For example, the Cyrillic based languages generally use ISO8859-5; however, the Ukrainians have additional characters which are missing from Bulgarian or Macedonian alphabets. Therefore, in one locale (Ukrainian) they (the missing characters) would be text and in other (Macedonian, Bulgarian), they are binary.

MICROSOFT® WORD DOCUMENT COMPARISONS When you compare (or merge) two Microsoft Word Documents, ChangeMan DS invokes the ChangeMan Word Diff utility. Microsoft Word must be installed on the client machine for this to complete successfully.

149

15


Note You cannot compare Microsoft Word documents from the Web browser or Java clients.

The ChangeMan Word Diff utility displays only one file. The changes between the files are color-coded according to the color-coding defined under Track Changes in Microsoft Word.

By default, lines that are in File 2 but not in File 1 appear underlined, and lines that are in File 1 but not in File 2 have a strike through them. File 1 and File 2 are determined by the order in which you selected the files.

ChangeMan Word Diff supports the following versions of Microsoft Word:

• Microsoft Word 97 (v 8.0)


• Microsoft Word XP (v 10.0)

The following topics describe actions available in the ChangeMan Word Diff utility:

• “Changing Display Colors” on page 150

• “Closing the ChangeMan Word Diff Utility” on page 150

• “Merging Files during ChangeMan Word Diff Comparison” on page 150

• “Navigating Changes” on page 151

Changing Display ColorsTo define a different color for your changes, exit the ChangeMan Word Diff utility, and open Microsoft Word. Choose Tools > Track Changes > Highlight Changes, then click the Options button. Refer to the Microsoft Word documentation from Microsoft for more information.

Closing the ChangeMan Word Diff UtilityYou can close the utility by choosing Close or Exit on the File menu.

Merging Files during ChangeMan Word Diff ComparisonYou can merge the two files by accepting or rejecting the changes as described in “Interactive Merges with Microsoft® Word Documents” on page 162, then choosing File > Save as. Note that unless your Save As overlays one of the controlled documents that you are comparing, the merged file will not be not under ChangeMan DS control.

0


You can merge two different Word files by choosing File > Merge Word Documents. You are prompted for the files and the common ancestor, then ChangeMan Word Diff will display the merged files for you to accept or reject changes as described in “Interactive Merges with Microsoft® Word Documents” on page 162.

Navigating ChangesStep through the changes either manually by scrolling, or by choosing Changes > Prev Change or Changes > Next Change.

151

15


2

MERGING 1
0 Merging files lets you choose added, deleted, or changed lines from two file versions and then places the chosen composite information in one of the file versions. This lets you reconcile disparate changes in files being changed concurrently. The Merge module merges any two files that have a common ancestor. The common ancestor is the file version from which the two files were derived.
You can initiate two types of merges:

• Interactive, which lets you select which changes are incorporated.

For text-based files, see “Interactive Merges with Text-Based Files” on page 160.

For Microsoft Word documents, see “Interactive Merges with Microsoft® Word Documents” on page 162.

For example:

If a user created a branch of a source file, and now, he wants to combine the branch with its baseline version. ChangeMan DS allows this merge to take place because the two files share a common ancestor, the version of the main tree from which the branch was originally made.

The file’s history would appear similar to that shown in the File Tree on the right. The main development line is at the left, the branch is at the right, and the merged file is at the center-bottom.

153

15

Chapter 10: Merging

• Automatic, which selects changes based on default rules.

See “Automatic Merge Rules” on page 163 for an explanation of the default merging rules.

The origins of the files to be merged determine where the resulting merged file is placed. For example, if you are merging one Development file (checked out) and one Production file, ChangeMan DS places the result of the merge into the Development file. See “Target Rules for Merging” on page 159 for resulting targets for the different combinations of first and second file origins.

You can initiate the merge through the File Tree module, as a part of the Check In request, or as part of the Synchronize process.

Only authorized users can initiate merges.

See “Text-Based and Binary Files” on page 148 for information on how ChangeMan DS determines if a file is text-based or binary.

MERGING FROM THE FILE TREETo merge two file versions from the File Tree:

Step Action

1. Select an icon representing one version of the file.

2. Shift-Click to select an icon for a second version of the file.

3.Click .

The ChangeMan DS Merge dialog displays.

4. Complete the ChangeMan DS Merge dialog.See “Completing the ChangeMan DS Merge Dialog” on page 157 for details on the fields.If you want to reverse which file is considered the first file and which is considered the second file, cancel the merge dialog, and select the icons in the reverse order.

4


MERGING AS PART OF CHECK INTo merge during the check in process for a file that is concurrently checked out:

5. Either:• Click Interactive Merge to choose how the changes are imple-

mented.For text-based files, see “Interactive Merges with Text-Based Files” on page 160.For Microsoft Word documents, see “Interactive Merges with Microsoft® Word Documents” on page 162.

• Click Auto Merge to have ChangeMan DS merge the files automati-cally. See “Automatic Merge Rules” on page 163 for the rules that ChangeMan DS uses to merge the files.

Step Action

1. When checking in a text-based file that already exists in the target area (for example, a file that was a concurrent check out and the second to be checked in), click the Merge to production, Interactive or the Merge to development, Interactive button.See “Checking In the Same Version of a File” on page 116.

2. Complete the ChangeMan DS Merge dialog.See “Completing the ChangeMan DS Merge Dialog” on page 157 for details on the fields.

3. Either:• Click Interactive Merge to choose how the changes are implemented.

For text-based files, see “Interactive Merges with Text-Based Files” on page 160.For Microsoft Word documents, see “Interactive Merges with Microsoft® Word Documents” on page 162.


Step Action

155

15

Chapter 10: Merging

MERGING AS PART OF SYNCHRONIZATIONTo merge as part of the synchronization process (when a conflicting version of a file exists in the target location):

Step Action

1. When synchronizing two areas and the same text-based file already exists in the target area, click the Merge to production, Interactive button or the Merge to development, Interactive button.

2. Complete the ChangeMan DS Merge dialog.See “Completing the ChangeMan DS Merge Dialog” on page 157 for details on the fields.

3. Either:• Click Interactive Merge to choose how the changes are implemented.

For text-based files, see “Interactive Merges with Text-Based Files” on page 160.For Microsoft Word documents, see “Interactive Merges with Microsoft® Word Documents” on page 162.


6


COMPLETING THE CHANGEMAN DS MERGE DIALOG

After selecting one of the interactive merge options using any of the previously described methods, the ChangeMan DS Merge Dialog displays as follows:

157

15

Chapter 10: Merging

The following table describes the fields on the Merge screen. Some of the fields require user input to complete the merge process:

Field Description

First File

File The name of the file used as the first source in the merge process.

V The version number of the first file.

Area The ChangeMan DS area ID where the first source file is located.

Password Optional. Enter the “transfer out” password associated with this area. This password is defined during area configuration.

Second File

File The name of the second file.

V The version number of the second file.

Area The ChangeMan DS area ID where the second source file is located.

Password Optional. Enter the “transfer out” password associated with this area. This password is defined during area configuration.

8


TARGET RULES FOR MERGINGThe target rules for merging determine the target destination of the merged file, based on the origins of the first and second files. The rules also depend on how you invoked the merge.

Selecting Merge from the File TreeIf both files are from the Production area, you can:

• Replace the contents of one production file with the merged file by choosing the name of that Production file. The production file must be latest version.

• Place the merged file into a branch by choosing a new name and a new Production area (if desired).

Target Files

File The name of the target file.See “Target Rules for Merging” on page 159 for possible combinations of first and second file origins, and their resulting target file destinations.

Area The target file area ID.

Click to browse for an area from a list of Production areas.

Project The project that the merged file will be associated with.

Click to browse for a list of ChangeMan DS projects.

Path The directory path in the target area.

Description Optional. Type a brief description of the merge process, such as a reason for performing it.This description appears in the Audit Trail record of the merge transaction.

Password Optional. Enter the “transfer in” password associated with this area. This password is defined during area configuration.

Field Description

159

16

Chapter 10: Merging

If both files are from Development or QA areas, you can:

• Replace the contents of the First File with the merged file. Select files in the reverse order to change which file is first and which file is second.

If one file is from Development or QA, and one file is from a Production area, you can:

• Replace the contents of the production file with the merged file by choosing the name of that production file. The production file must be latest version.

• Replace the contents of the development or QA file with the merged file. It must be selected as the First File.

• Place the merged file into a branch by choosing a new name and a new Production area (if desired).

Selecting Merge from Second Check InIf you select to merge when checking in a file from a Development or QA area, choose from the following options for where to place the merged file:

• Replace the contents of the production file with the merged file by choosing Merge to Production.

• Replace the contents of the development or QA file with the merged file by choosing Merge to Development. The file remains in the Development or QA area.

Selecting Merge during SynchronizationIf you are synchronizing a development or QA file, you can replace the contents of the Target Synchronization file with the merged file.

INTERACTIVE MERGES WITH TEXT-BASED FILESThe interactive merge lets you reconcile disparate changes in the two files by choosing added, deleted, or changed lines from the two versions. After you reconcile the differences and exit, the merged information is placed into the First File or other target location as described in “Target Rules for Merging” on page 159.

Note This section assumes that you have initiated the merge process. For information on initiating the merge process, see:

• “Merging from the File Tree” on page 154

• “Merging as Part of Check In” on page 155

0


• “Merging as Part of Synchronization” on page 156

When you initiate an interactive merge for a text-based file, the ChangeMan Diff utility displays in Merge mode. The screen shows the following:

The Map provides a micro view of each file, with arrows indicating the current positioning of the file, and colors indicating positions of differences. The different columns correspond to the different files: Left is the First File, the middle column is the Second File, and the right column is the Ancestor File. To display (or hide) the Map, choose View > Show Map (or View > Hide Map).

The displayed merge file color-codes the text background to help you discern which lines came from which file. Place your cursor in a file, and the Status Bar displays the meaning of the colors for that file. To display (or hide) the Status Bar, choose View > Show Status Bar (or View > Hide Status Bar). See “Changing Text Background Colors in ChangeMan Diff” on page 431 for an explanation of the different colors.

The following sections describe actions available during the merge:

• “Accepting/Rejecting Changed Lines during a Merge” on page 430

Map

Common AncestorFile 1 File 2

Merged File Status Bar

161

16

Chapter 10: Merging

• “Editing the Merged File in ChangeMan Diff” on page 432


• “Changing Display Options” on page 431

• “Changing Text Background Colors in ChangeMan Diff” on page 431

• “Performing a Comparison while Merging Files” on page 433

• “Merging the Files from a Comparison” on page 432

• “Editing the Merged File in ChangeMan Diff” on page 432

• “Performing a Comparison while Merging Files” on page 433

• “Saving and Exiting the Merge” on page 434

• “Synchronizing Displayed Lines in ChangeMan Diff” on page 434

• “Toggling Display of Map and Status Bar” on page 435

• “Using Bookmarks” on page 444

INTERACTIVE MERGES WITH MICROSOFT® WORD DOCUMENTS

Interactive merge lets you control the merge process between two files as the merge is being performed by ChangeMan DS. You navigate through the merged file, accepting or rejecting the changes from each file.

Note You cannot merge Microsoft Word documents from the Web browser or Java clients.

When you merge two Microsoft Word documents, ChangeMan DS invokes the ChangeMan Word Diff utility. Microsoft Word must be installed on the client machine for this to complete successfully.

The ChangeMan Word Diff utility displays only the merged file. Changes are color coded, according to the color-coding that you defined under Track Changes in Microsoft Word. By default, inserted lines are underlined and deleted lines have a strike through them.

For information on initiating the merge process, see:

• “Merging from the File Tree” on page 154

• “Merging as Part of Check In” on page 155

• “Merging as Part of Synchronization” on page 156

2


ChangeMan Word Diff supports the following versions of Microsoft Word:



• Microsoft Word XP (v 10.0)

The following topics describe actions available in the ChangeMan Word Diff utility:

• “Accepting/Rejecting Changes in ChangeMan Word Diff” on page 163

• “Changing Display Colors” on page 150

• “Closing the ChangeMan Word Diff Utility” on page 150

• “Merging Files during ChangeMan Word Diff Comparison” on page 150

• “Navigating Changes” on page 151

Accepting/Rejecting Changes in ChangeMan Word DiffYou can accept or reject the changes by right-clicking on the change, or placing your cursor on the change and choosing Changes > Accept Change/Reject Change.

Saving and Exiting from ChangeMan Word Diff After Merging

After you completed viewing your changes either save and exit or exit without saving by choosing the appropriate option from the File Menu. If you choose Close, the file will be saved.

AUTOMATIC MERGE RULESThe automatic merge reconciles the differences between two files according to a set of defined rules without giving you the opportunity to intervene and select the changes that you want.

Use caution when selecting automatic merge, since the resulting merge could overwrite your files with unintended code. For files that are documentary, automatic merge can be useful if the default rules are acceptable to you.

Depending on the type of change, the reconciliation is handled in different ways:

• In the case of conflicting changes in the two versions of the file, ChangeMan DS accepts the change from the first file.

163

16

Chapter 10: Merging

• In the case of inserted lines, ChangeMan DS accepts all inserted lines from both files.

• In the case of deleted lines, ChangeMan DS omits all deleted lines from all files.

CANCELING A MERGEWhen you cancel a merge, the dialog you should act upon is sent to the back. You need to bring that window to the front and cancel there. If you cancel from the other dialog, the merge may go through as originated.

4

SYNCHRONIZING 1
1 Synchronizing lets you update files to match versions of the files that are currently in another area.
There are two choices given during synchronization:

• Merging, which lets you combine the two files from different areas.

• Overwriting, which replaces your file with another one. (You lose your changes.)

To synchronize copies of the files in working areas, use the Synchronize option. The alternative is to wait until the versions of the files in that area have been promoted to the next stage of the development life cycle.

Use this procedure to initiate synchronization:

Step Action

1. Display a list of files in the area to which you want the files refreshed.The files can be in the Development, QA or End User areas.

2. Select the files you want to synchronize.You can also select a list of files from the Attachments node under a project, or you can choose all files related to the project by selecting the project node.

3. Either:• Right-click and choose Promote > Synchronize• Choose Get Latest from the Promote menu

• Click on the Promote toolbar

The Get Files From dialog prompts for the location of the files with which you want to synchronize.

165

16


4. Select where to retrieve the files for synchronization on the Get Files From dialog:If you choose the Checked out to user,

either click to browse for a user or fill in the user’s name in the entry field.This step lets you pinpoint which version of the file you are looking for if several people are concurrently working on the same file.

5. Click OK.The ChangeMan DS Transfer Request dialog displays.

6.Optional.

To synchronize to a previous version of a production file:

a) Click Advanced on the ChangeMan DS Transfer Request dialog to display the ChangeMan DS Advanced Check Out dialog.

b) Select the list entry, and click Edit.The ChangeMan DS Check Out Version dialog displays.

c) Select the version number on the Check out version field.

d) Click OK to accept the change and close the ChangeMan DS Check Out Version dialog.

e) Click OK to accept the change and close the ChangeMan DS Advanced Check Out dialog.

Step Action

6


7. Click Transfer.The ChangeMan DS Prompt dialog displays for the First File. The file name appears in the message of the dialog.

8. For files that changed, click one of the following:• Interactive initiates Interactive Merge for the mentioned file and

the retrieved file. See “Merging” on page 153.• Automatic performs an Automatic Merge for the mentioned file

and the retrieved file based on rules. See “Merging” on page 153.• Automatic All performs an Automatic Merge for all selected files

and its copy based on rules. See “Merging” on page 153.• Overwrite overwrites the selected file with the retrieved file. No

merge is performed. • Automatic All overwrites all selected files with the retrieved files.

No merge is performed.

Step Action

167

16


8

MANAGING BUILDS 1
2 Build Management provides distributed build functionality with UNIX and Microsoft-style make files. A typical build compiles and links executables, and generates other intermediate or final interpretable components.
ChangeMan DS Build Management also provides the following features:

• Unlimited number of dependencies for each target file.

• History of the build process.

• Ability of developers across applications to share objects.

• Parallel and distributed builds across heterogeneous platforms.

• Unlimited number of named make procedures for executing builds on multiple hosts.

ChangeMan DS lets you automatically build files across distributed hosts and heterogeneous platforms with:

Single Point Of Control

You can designate any host on the LAN, WAN, or Internet as the “assembly” host responsible for compiling and linking your software applications.

Multiple Operating Systems

You can instruct ChangeMan DS to build executable files for multiple operating systems by specifying multiple hosts using the New Make option.

Projects The ChangeMan DS build process is based on projects; that is, the components that make up all or part of a software application. Each project can consist of multiple executables, and each executable can have any number of dependencies.

169

17

Chapter 12: Managing Builds

MAKE PROCEDURESYou can configure each project with information to build the application. This is called a Make Procedure.

You can create target-level properties for the Make Procedure that override the project-level information.

The build process for a project in ChangeMan DS is entered under a project's Make Procedures node. Every project in ChangeMan DS can have Make Procedures associated with it.

To work with make procedures for a specific project, you must have permission to access and work with make procedures. See “Users and Groups” in Serena® ChangeMan® DS Administrator’s Guide for information on setting permissions.

Before you can execute the build, you must enter all of the information needed for the build.

To do a typical build, you must:

E-mail Notification

ChangeMan DS automatically sends an e-mail message containing the results of the build process to a specified workstation or user.

History ChangeMan DS maintains a complete history of build activities that occur anywhere on the network. You can obtain a comprehensive history about all ChangeMan DS Build events under Make Procedures History in the ExplorerView.

1. Create a new make procedure. See “Creating a New Make Procedure” on page 173.

2. Add at least one target for the make procedure. See “Make Procedure Targets” on page 181.

3. Add required dependencies for the target or targets. See “Make Procedure Dependencies” on page 184.

4. Use the Build command to execute the make procedures. See “Initiating the Build Process” on page 189.

0


To create or execute a build for a project, expand the project node and right-click the Make Procedures node of that project to display the available Build Options.

BUILD OPTIONSExpand the project node and right-click the Make Procedures node of that project to display the available build options.

171

17


There are several options under the Make Procedures node. The options are:

This option… Allows you to…

New Make Create a named make procedure. You must define properties defined for named make procedures.

New Target Define a target or targets to be generated during the make procedure. You must define a target and dependency tree to tell ChangeMan DS which files to use and which commands to execute in the build procedure.New Target is available when you right-click on a named make.

New Dependency Define dependencies to be used during the make procedure to generate the targets. You must define a target and dependency tree to tell ChangeMan DS which files to use and which commands to execute in the build procedure.New Dependency is available when you right-click on a target.

Build Execute the build commands included in the named make procedures and their associated target and dependency trees.

Delete Delete make procedures for the selected project.

Export Export ChangeMan DS make procedures to a designated external make file.

Properties View and modify the properties of the make file, target, or dependency.

Print Print the make configuration.

Print Preview Preview the print setup of the make configuration.

2


CREATING A NEW MAKE PROCEDURE

Use this procedure to create a new make file:

Step Action

1. Expand the project to which you want to add a make file.

2. Select the Make Procedures node, then right-click to view the list of options available for this procedure. When you select the Make Procedures node, ChangeMan DS displays the existing project properties in the right section of the screen.

3. Choose New Make. ChangeMan DS displays the ChangeMan DS Make Configuration window.

4. Type the necessary information on the Properties tab as described in “Defining Make Procedure Properties” on page 175.

5. Enter the necessary information in the Pre Compile tab as described in “Defining Make Procedure Pre Compile Script” on page 177.

6. Enter the necessary information in the Global Compile tab as described in “Defining Make Procedure Global Compile Script” on page 178.

7. Enter the necessary information in the Post Compile tab as described in “Defining Make Procedure Post Compile Script” on page 180.

8. Click OK.A named make file now exists under the Make Procedures node for the selected project.

173

17


MODIFYING EXISTING MAKE PROCEDURES

Use this procedure to modify a make procedure:

Step Action

1. Select the named make file.

2. Do one of the following:• Right-click, then choose Properties.

• Click on the Project toolbar• Choose Properties from the Project menu.The ChangeMan DS Make Configuration window displays.

3. Enter the necessary information on the Properties tab as described in “Defining Make Procedure Properties” on page 175.

4. Enter the necessary information in the Pre Compile tab as described in “Defining Make Procedure Pre Compile Script” on page 177.

5. Enter the necessary information in the Global Compile tab as described in “Defining Make Procedure Global Compile Script” on page 178.

6. Enter the necessary information in the Post Compile tab as described in “Defining Make Procedure Post Compile Script” on page 180.

7. Click OK to save the changes.

4


Defining Make Procedure PropertiesSelect the Properties tab to enter the required information for the make procedure.

The Properties tab contains the following input fields:

In this field… Enter…

Make Name A unique name for each make procedure to be associated with the project. There can be an unlimited number of named make procedures for executing builds on multiple hosts.The Make Name cannot have a space.

Assembly User

The operating system user ID for login on the host that the build process is to be executed. The user ID must have permission to execute scripts. The environment variables available to this user ID are available from the script.

Assembly Host

The host name where the build process is to be executed.

175

17


Assembly Path

The subdirectory path where the build process is to be executed. Click the browse button to select the path with the Remote Directories Browser.During the build process, ChangeMan DS copies necessary files into the Assembly Path and deletes them when the process is complete. The Project Assembly Path cannot point to any of the existing ChangeMan DS areas. ChangeMan DS aborts the build and issues an error message if it finds that an Assembly Path points to an area.

Default dependency location

Designate the location from which to copy the dependency files. Dependency files may simultaneously exist in multiple areas, such as Production, Development, and QA. The build process can use any of the versions.

Production Select this option to use a Production copy of the dependency file, although a Development or QA copy may also exist.

Development Select this option to use a Development copy of the dependency file, although a Production or QA copy may also exist.

Initiator Development

When some project components are currently checked out by other people, use this option to instruct the build process to use a Development copy of the file, but only if the initiator of the build is the owner of the file. All other project components will be taken from Production. This feature allows developers to test their own changes.

Q/A Select this option to use a copy of a dependency file that exists in a QA area, even though Development or Production copies may also exist.


6


Defining Make Procedure Pre Compile ScriptSelect the Pre Compile tab to enter commands that execute before executing other make procedure commands.

The Pre Compile tab allows you to enter the script commands that run before the target build commands. These commands are executed first in the build process, and are generally used to set the environment variables that are used in the build procedure.

Default dependency location (continued)

Initiator Q/A If some of the project attachments currently reside in QA areas and are owned by various users, select this option and the build process will take a QA copy of the file only if the initiator of the build is the owner of the file. All other project components will be taken from Production. This feature allows a quality assurance person to test the changes.

Use production if development version doesn't exist.

Select this option to force the build process to use the Production version of the dependency file if its Development or QA copy does not exist.


177

17


Use the following buttons to edit the Make commands:

Defining Make Procedure Global Compile ScriptSelect the Global Compile tab to enter commands to be executed if no target-specific commands exist. These commands are executed after any pre-compile commands.

The Global Compile tab lets you enter commands to invoke the compiler. If the target-specific compile rules don't exist, then the build process uses the global compile commands.

This button… Performs this function…

Starts editing the selected line.

Creates a new line.

Deletes a selected line.

Moves a selected line up.

Moves a selected line down.

8


Global Compile commands allow the following ChangeMan DS variables:

• $VCS_SOURCE_FILE (containing dependency file name)

• $VCS_TARGET_FILE (containing target file name for the dependency)

See “Scripting” in Serena™ ChangeMan® DS Administrator Guide for more information about the ChangeMan DS variables.

Use the following buttons to edit the Make commands:


Start editing the selected line.

Create a new line.

Delete a selected line.

Move a selected line up.

Move a selected line down.

179

18


Defining Make Procedure Post Compile ScriptSelect the Post Compile tab to enter commands that execute after the other make procedure commands are executed.

The Post Compile tab lets you enter commands that run after the target build commands. These commands execute as a last step in the build process. Use this feature to remove temporary files, or to copy the build results to other locations.

Use the following set of buttons to edit the Make commands:


Start editing the selected line.

Create a new line.

Delete a selected line.

Move a selected line up.

Move a selected line down.

0


Make Procedure TargetsChangeMan DS lets you configure build information (properties) for the named Make Procedure or for individual targets.

The Make Procedure level properties apply to all targets and dependencies in the Make Procedure. Note, however, that if a target or dependency has its own set of properties, then these properties override the Make Procedure level information.

The following topics describe how to define a target file for a build project. Add targets only after you create a named make procedure:

• Creating a New Target

• Adding Target Information from a Project

• Modifying Target Properties

Creating a New TargetNote that you can add targets only after a you create a named make procedure for a project.

To create a new target file:

Step Action

1. Select the Make Procedures node.

2. Do one of the following:

• Click from the Project toolbar.

• Choose New Target / Dependency from the Project menu.• Right-click, then choose New Target from the right-click menu.ChangeMan DS displays the Target /Dep Configuration screen.

181

18


Adding Target Information from a ProjectInstead of manually typing the Target name and properties as described in the preceding section, you can drag-and-drop the information from an existing project.

3. Fill out all input fields as follows:

File Type the name of the file to add.

Area Type the area name (or browse through the list of existing areas and select one).

Path When you select the area name, expand the folders beneath it to choose the path. The Path field is completed automatically with the chosen path.For non-Production areas, you cannot set the path to a subdirectory of the area path.

Version Select the version of the target file. The default is the latest version.

Dependency location

If this option is disabled, the build process uses the dependency location defined during the project Make Configuration process. If you enable this option, other options are made available to identify the dependency file to use.

Build Directory

Type a subdirectory where this target is to be built. This subdirectory is relative to the assembly path that is defined in the Make properties of the project.

Build Command(s)

Type commands that are used to generate this target.

4. Click OK to finish the target configuration process.You can define multiple levels of subdependencies.

Step Action

2


To add target files to a make procedure:

Modifying Target Properties

Use this procedure to modify target file properties:

Step Action

1. Expand the project.

2. Select the filet from the area in which you want to re-create it (whether Production, Development, or QA) or from your project’s attachments.

3. Drag the selected file to the Make Procedures node, or use the Copy and Paste commands from the File menu.

4. Repeat this procedure as many times as needed.

Step Action

1. Select the target file.When you select a target or dependency file, ChangeMan DS displays its properties in the Item Window.


• Click on the Project toolbar

Choose Properties from the Project menu.

3. Make the changes, then click OK.

183

18


Make Procedure DependenciesThe following procedure describes how to define a dependency file for a build project. This option is available only after a target is created under a named make procedure. Dependencies can exist under targets or other dependencies.

• Creating a New Dependency• Adding a Dependency• Modifying Dependency Properties

Creating a New Dependency

Use this procedure to create a new dependency file:

Step Action

1. Select the target file node under the Project Make Procedures.

4



• Click from the Project toolbar.

• Choose New Target / Dependency from the Project menu.• Right-click, then choose New Dependency.ChangeMan DS displays the Target /Dep Configuration screen.

Step Action

185

18


Adding a DependencyYou can create a dependency after a target is created under a named make procedure. Dependencies can exist under targets or other dependencies.

3. Fill out all input fields as follows:

File Type the name of the file to add.

Area Type the area name (or browse through the list of existing areas and select one).

Path When you select the area name, expand the folders beneath it to choose the path. The Path field is completed automatically with the chosen path.Note that for non-Production areas, you cannot set the path to a subdirectory of the area path.

Version Select the version of the target file to be used. The default is the latest version.

Dependency location

If this option is disabled, the build process uses the dependency location defined at the Make Procedure level. If you enable this option, other options are made available to identify the dependency file to be used.

Build Directory

Type a subdirectory where this target is to be built. This subdirectory is relative to the assembly path that is defined in the Make properties of the project.

Build Command(s)

Type commands to generate this target.

4. Click OK to finish the target configuration process.You can define multiple levels of subdependencies by repeating this procedure.

Step Action

6


To add a dependency to the project, expand the <named make> node under the project, select the node (target or dependency) to which you want to add the dependency, and either:

• Right-click the node, and choose New Dependency. Complete the fields as described in “Creating a New Dependency” on page 184.

• Select a file from the content window and drag it to the node.

• Use Copy and Paste commands from the File menu to copy the file to the node.

If you add a file that is attached to the project, the relative path is set according to how it is defined in the project.

Modifying Dependency Properties

Use this procedure to modify dependency properties:

Examples of Build ScriptsThe following scripts are examples that you can use for builds.

See “Scripting” in the Serena® ChangeMan® DS Administrator’s Guide for more information about the ChangeMan DS scripts.

Step Action

1. Select the target file.ChangeMan DS displays the file’s properties in the Content Window.



• Choose Properties from the Project menu.

3. Make any necessary changes, then click OK.

187

18


Visual Basic Script Example for BuildsIn this Visual Basic Script example, ChangeMan DS compiles "Demo.exe" and places the file in the "Release" directory:

"C:\Program Files\Microsoft Visual Studio\VB98\VB6.EXE" /make .\Source\Demo.vbp /out DemoLog.txt /outdir .\Release

Note the following:

• Quote marks are included because the path has spaces.

• The build directory has 2 subdirectories: "Source" and "Release". The source files are in the "Source" subdirectory.

• "outdir" sends the compiled file to the .\Release directory, relative to the Build directory.

• The Relative Build Directory field of the Target Configuration dialog contains the "outdir" values. In this example, the Relative Build Directory field contains ".\Release".

• The Assembly Path field on the Properties Tab for the project has: "C:\ds\assembly\vb\Demo."

• The "C:\ds\assembly\vb\Demo\Source" and "C:\ds\assembly\vb\Demo\Release" subdirectories exist.

Java Build Script ExampleThis example is for a basic Java project that creates a single .jar file as its deliverable output.

The example assumes the following:

• All source code starts at relative path .\src

• The jar file is stored at .\lib\myJar.jar

8


INITIATING THE BUILD PROCESSInvoke the Build process from the Make Procedures node for a project, or through ChangeMan DS scripts.

Step Action

1. Create a new make procedure with the following information in each of the tabs:Pre Compile TabSET JAVA_HOME=D:\jdk1.3 (Path to your jdk if it is not already a system variable)SET PATH=%PATH%;D:\jdk1.3\bin (This adds the javac.exe file to your path statement if it is not in your system PATH)SET CLASSPATH=%CLASSPATH%;JAVA_HOME\lib\tools.jar;D:\myDependencies\dependency.jar (Here is where you would add any libraries that are required by your Java source files such as XML parsers and JDBC drivers)Global Compile Tabjavac -sourcepath .\src\*.java -d .\classes (This compiles everything under .\src and puts the class files in .\classes.)Post Compile Tabjar -cvf .\lib\myJar.jar .\classes\ (This will put all files under .\classes into a jar file called myJar.jar at relative path .\lib)

2. Create a new target by dragging the myJar.jar file from your project attachments onto the make procedure.

3. Drag all the dependencies of this file (the source files .java) from your project attachments onto this target.

4. Run the make by choosing the Build command.ChangeMan DS updates the version number of myJar.jar if it changes after the make.

189

19


When you initiate the from a project that has subprojects, the Initiate Build Procedures dialog suggests the Make Procedures to build. If a parent project does not have maker procedures of its own, those of the child projects display.

For detailed information on how to invoke the Build process through scripts, see “Make Utility” in Serena™ ChangeMan® DS Administrator Guide.

Use this procedure to initiate the build process from ExplorerView:

Step Action


2. Select the Make Procedures node.


• Click on the Project toolbar.

• Choose Build from the Project menu.• Right-click, then choose Build from the right-click menu.

4. If the assembly host is UNIX or Microsoft Windows, then ChangeMan DS prompts you to provide the user password.

5. Log in with your host user ID. See “User Login Information for the Build Host” on page 191 for more information about user IDs for the host.A notification message displays the results of the build process.Use a similar procedure to initiate the build process for individual targets.

0


User Login Information for the Build HostSupply the following user login information:

Host Configure

Windows NT For the user ID for the Communication Agent or Main Server:• In the NT User Manager, select Policies, then

User rights and check Show Advanced User Rights.

• Add the user ID from the startup of the Change-Man DS agent or server service to the list of users with the right Act as part of the operat-ing system and Log on as a service.

For the user ID for executing builds:• In the NT User Manager, select Policies, then

User rights and check Show Advanced User Rights.

• Add the build user ID to the list of users with the right Log on as a service.

Windows 9x Add the following lines to the vcs_serv.ins file in your ChangeMan DS \Client directory:

ValidateMakePassword=1MakeUser=abcMakePassword=xyz

where xyz is the password for the user ID abc.If you intend to run Implementation Scripts on this same machine, also add:

ValidatePassword=xyzValidateUser=abcValidateAreaPassword=1

Stop and restart the ChangeMan DS Communication Agent service on the target machine for the changes to take effect.

UNIX The user must be given read, write, and execute rights for the build on the assembly host or build directory.

191

19


BUILD HISTORYAt the end of the build process, ChangeMan DS saves the build execution history. ChangeMan DS lets you review all the build history for the specific project.

See the following topics for details:

• Reviewing Build History

• Understanding the Build History

• Sending the Build History to a Log File

• Locating Build Information Storage

• Deleting the Build History

Reviewing Build HistoryUse this procedure to review build history:

Step Action


2. Expand the Make Procedure node to see the History node.

2


Understanding the Build HistoryTarget and dependency files display one of the following icons:

3. Expand the History node to see separate date nodes for each time the Build process was initiated.

4. Select the Date node. Project properties and build results are displayed in the Item Window.

ChangeMan DS also shows the target and dependency structure for each time the Build process took place.

This icon… Indicates…

A successfully built target.

An unsuccessfully built target.

Step Action

193

19


On Windows NT or UNIX systems, the amount of information displayed depends on the type of commands run during the build. Some commands yield more results than others.

If you receive a message stating only that the target file was not transferred (and no error messages), this usually means that the error messages are being logged elsewhere by the compiler, or that the make command is not in the Environment Variable Path for root.

On Windows 9x, a DOS session is opened to execute the build. If your build failed and you need more information, enter a Pause command in the Pre Compile tab on the make procedures Properties to pause processing after the SET commands are executed. Once the processing has paused, you can view the information displayed so far in the DOS window. Press Enter to continue the build execution. Quickly press Pause when an error message displays.

Sending the Build History to a Log FileAlthough the build results are automatically saved under the History node of the Make Procedures, some make procedures do not output all of the details in the case of a failed build. Visual Basic is one example. However, a Visual Basic make can be used in conjunction with a /out parameter to specify output to a log file for errors. Depending on the type of make procedure, there may be additional commands or parameters you can use to log the errors.

Locating Build Information StorageBy default, the make procedures information entered in the ChangeMan DS ExplorerView is stored in three folders in your ChangeMan DS server directory, rather than in the ChangeMan DS database. The following code shows the folder names, the naming structure, and content of the files.

makes.config (folder)projectname.newmakename.0

A target that hasn't been built due to the fact that all of its dependencies are current.

A pseudo target. The pseudo files in the make procedures will show up as the pseudo files in the build history. The nature of pseudo files is explained in “Importing a Make File” on page 196.

This icon… Indicates…

4


contains pre-compile commandsprojectname.newmakename.1

contains global compile commandsprojectname.newmakename.2

contains post-compile commandsmakes.depend (folder)

projectname.newmakename.#(where # = number from 0 to n)contains target/dependency commands

makes.history (folder)projectname.newmakename.#

(where # = number from 0 to n)contains make results

makes.config (subfolder)projectname.newmakename.0

contains pre-compile command historyprojectname.newmakename.1

contains global compile command historyprojectname.newmakename.2

contains post-compile command historymakes.depend (subfolder)

projectname.newmakename.# (where # = number from 0 to n)contains target / dependency command history

It is important that you backup the content of these three folders and their subfolders in synchronization with your ChangeMan DS database and Production area backups.

You may designate a different path for the makes.config, makes.depend, and makes.history folders in the vcs_serv.ins file by modifying the values for variables MakeConfigPath, MakeDependConfig, and MakeResultPath.

Deleting the Build HistoryIf you no longer need a build record, you can delete it with the following procedure:

Step Action

1. Expand the Make Procedure node.

195

19


IMPORTING A MAKE FILEYou can automatically populate a project’s build procedures by importing an existing make file.

Use this procedure to import a make file:

2. Select the History node.

3. Right-click, then choose Delete from the right-click menu. You can use a similar procedure to delete individual build records, rather than the entire build project.

Step Action

1. Expand the area node containing the existing make file.

2. Select an existing make file from the displayed list of files.

Step Action

6



• Click on the Files toolbar.

• Choose Import Make File on the Files menu.• Right-click, then choose Import Make File from the right-click

menu.If there are any conditional expressions inside the make file, ChangeMan DS prompts user to define “True” or “False” answers for those expressions.After responses to the conditionals are completed, the Import Make File dialog displays.

4. Click the Project browse box.The Projects dialog displays.

5. Select the appropriate project, then click Make New.The ChangeMan DS Make Configuration dialog displays (see “Defining Make Procedure Properties” on page 175).

Step Action

197

19


6. When the make configuration is complete, click OK. The Projects dialog displays.

7. Click OK on the Import Make File dialog; the selected files are listed.

8. Click Continue to import the information, then click OK when the import is complete.

9. Select the make node, then click OK. The make configuration information is added to the Import Make File dialog.

Step Action

8


10. Complete the Import Make File dialog; the items are:

Project Click the browse button to select the project and make file.

Make Select the appropriate make file.

Assembly User

Accept the default, or enter the name of the user who is initiating the build.

Assembly Host

Type the name of the host where the build is to occur.

Assembly Path

Use the browser button to select the location.

Reuse makefile…

Execute the make command against the indicated make file, rather than importing all of the make information into the make procedures.

Case insensitive…

Ignore case in target names (“abc” = “ABC”), instead of generating separate target names. Recommended for Windows systems.

Omit targets…

Do not import targets that do not have associated build commands in the make file.

Omit directory…

Do not maintain directory structure information.

Append to existing…

Add imported information to existing make procedures (instead of replacing them).

11. When all items have been completed, click OK.

Step Action

199

20


EXPORTING MAKE PROCEDURESYou can export existing ChangeMan DS make procedures into an external make file.

To export the make procedures:

12. Expand the project make procedures in ExplorerView, then do the following:

a) Delete unnecessary targets or dependencies.

b) Add necessary targets or dependencies.See “Adding Target Information from a Project” on page 182 or “Adding a Dependency” on page 186.

c) Modify properties as required.See “Modifying Existing Make Procedures” on page 174.

d) Execute the build.

Step Action

1. Expand the project node.

2. Select the Make Procedure node.



• Choose Export Make Procedures from the Project menu• Right-click, then choose Export from the right-click menu.You are prompted for a name for the make file.

4. Enter the name of an external make file.

Step Action

0


TROUBLESHOOTING BUILDSUNIX: When trying to do a build, why do I get the “Unable to transfer file... (The specified file was not found in the system)” message and no output is created in the history?

Verify that root’s environment variable path includes a make, and any compilers or executables called in the make procedure.

This can also be caused by the umask settings for root in .profile. When you start a build, the assembly user does not have permission to write into the log files created in the /tmp directory by the ChangeMan DS Communication Agent.

This can be addressed for the ChangeMan DS Main Server on UNIX by:

— Logging on as root.

— Stopping the ChangeMan DS Communication Agent.

— Running umask +w to create the default mask for root that allows write access.

— Starting the ChangeMan DS Communication Agent.

— Logging off.

Windows: When trying to do a build, why do I get the “Unable to transfer file... (The specified file was not found in the system)” message and no output is created in the history?

The amount of information displayed in the build results depends on the type of commands run during the build. Some commands yield more results than others. If you simply get a message that the target file was not transferred, with no error messages displayed, this usually means the error messages are being logged elsewhere by the compiler.

5. Click OK.A confirmation message displays.

6. Click OK to finish.Following this procedure, a new make file can be found in the assembly directory.

Step Action

201

20


For example, the Visual Basic make command logs the error messages in a file designated after the /out parameter. Check your compiler options and add any options needed to output detailed error messages during the build.

2

MANAGING RELEASES 1
3 ChangeMan DS gives you the option to operate on a “release” level, and treat all components of the release as a single entity.
You can perform the following procedures at the release level:

• Creating Frozen Releases

• Promoting a Release

• Rolling Back a Release

• Modifying a Release

• Maintaining (Branching) a Release

CREATING FROZEN RELEASESFreezing a project is essentially versioning at the project level. It lets you fully track not only the versions of the files that went into the release, but also track the exact target/dependency structure and commands that were used in the build process.

A freeze records the Production version of the project attachments along with the make procedures information associated with the project at that time, and assigns the freeze a release label.

Although a make procedure can point to versions of the dependencies not in Production, ChangeMan DS always freezes the Production versions of those files when creating a frozen release.

203

20

Chapter 13: Managing Releases

Use this procedure to freeze a project:

A new release node is created for your project.

Step Action

1. Select a project.Note that you can freeze multiple projects of the same category by selecting them in the content window.

2. Either:• click Freeze on the Project toolbar.• choose Freeze a project release from the Project menu.• right-click, then choose the Freeze from the right-click menu.ChangeMan DS displays the Initiate Freeze Procedures dialog.

3. Supply the following information:

Release Label used to identify this release.

Description Brief description of this release.

4. Click OK to freeze the release.

4


If a freeze is initiated from a parent project, the Freeze Procedures dialog will suggest the projects to freeze, including the parent and all its subprojects. For example, the following dialog shows the prompt received upon initiating a freeze at a parent project that has two subprojects.

When the Freeze node is selected, ChangeMan DS displays the information regarding this release in the right pane.

When you right-click on the release label, ChangeMan DS displays a list of commands. You can create an unlimited number of frozen releases for the project.

205

20


A frozen release contains the project attachments list and build structure at the time of freeze. If the properties for a target or dependency are configured to use the latest version of a file, then during the freeze process ChangeMan DS updates the corresponding entry to include the actual latest version number.

The version of the files in the attachment list for the frozen project only changes when you modify the release, as described in “Modifying a Release” on page 207.

PROMOTING A RELEASEOnce a release has been created, you may choose the promote options to promote the release as an entity. This will promote all of the versions of the files that are in that release. This can be used for actions such as to distribute a release, or to Check Out a release to continue development.

Use this procedure to promote a release:

ROLLING BACK A RELEASEThe Rollback functionality lets you replace the current version of selected files with the corresponding frozen versions.

Use this procedure to roll back a release:

Step Action

1. Highlight the release name.

2. Choose a promote option from the right-click menu or from the Promote menu.

3. Follow prompts for transfer.

Step Action

1. Expand the project node.

2. Expand the Frozen node.


4. Right-click, then choose Rollback from the right-click menu.

6


ChangeMan DS treats the Rollback request as a Check In transaction originating from the archive area. Therefore, if the home Production area requires an approval of the transfer request, then it must be signed off. ChangeMan DS creates a record in its metadata database for all Rollback transactions.

The version numbers for the files attached to the project, and in the corresponding Production areas, are updated. In addition, you can use the File Tree module to view the history and compare various versions.

MODIFYING A RELEASE

A release is generally considered to be a stable and complete set of components; note, however, that there may be instances in which you may want to modify a release. Modifying a release will allow you to keep the same release number but replace one or more of the attached file versions of the project release.

This function requires permissions to delete a release, because it copies the old release, modifies it, and deletes it in background processes.

Detaching a File from an Existing ReleaseUse this procedure to detach files from an existing release:

Step Action


2. Select the Attachments node.

3. Select the file you want to detach from the file list displayed on the right.

4. Right-click, then choose Detach from the right-click menu.

207

20


Attaching New Files to an Existing ReleaseUse this procedure to attach a new file to an existing release:

Changing Properties of a Frozen ReleaseThe ChangeMan DS Project Release Properties dialog lets you edit the properties for a frozen file. These settings are primarily for use with IDEs.

To access this dialog, choose Properties on the right-click menu for a frozen release .

On this dialog:

• To change the release name, type a name in the Release field.

• To add a description to the frozen release, type one in the Description field.

• To lock a release from being modified, select the Locked checkbox.

• To set a working area and path, click the browse button next to the Working Area field.

• To adjust options for working with a frozen release with an IDE, modify the settings on the IDE Option tab. These options include:

— Prompting for a home location on each transfer

Step Action


2. Right-click, then choose Attach from the right-click menu. The ChangeMan DS Select File(s) window displays.

3. Expand the nodes and highlight the files to attach from the file list displayed on the right.

4.Click from the toolbar.

5. In the ChangeMan DS Version Selection window, choose Use Latest Version or Select desired version.If you chose Select desired version, select the version of the file to attach.

6. Click OK, then respond to the verification prompt.

8


— Whether or not to always use the same Production area and to specify it if necessary.

— Whether or not to recreate the directory structure

— Whether or not to force branching when a non-latest version of the release is checked in.

— Whether or not to force branching when the latest version of the release is checked in.

MAINTAINING (BRANCHING) A RELEASEThe Maintain function branches the release to a new location.

If a freeze is initiated from a parent project, the Freeze Procedures dialog will suggest the projects to freeze, including the parent and all its subprojects.

This function requires permissions to branch to Production, because it copies the old release to a designated Production area. It also requires permissions to create a project, because it automatically creates a new project for the branched release.

See “Creating a Branch of a Release” on page 140 for more information.

CHANGING THE PROPERTIES FOR A FROZEN FILEThe ChangeMan DS Frozen File Properties dialog lets you edit the properties for a frozen file.

To access this dialog, choose Properties on the right-click menu for a file in the Attachments node underneath a frozen release.

On this dialog:

• To replace an attached frozen file with another file, click and select the file to be included in this frozen release.

• To change the version number of the file that was frozen, type a version number in the Version field, or click the arrows.

• To add a description to the frozen file, type one in the Description field.

• To set a new relative path for the frozen file, type it in the Relative Path field.

• If the selected attachment is also a dependency of the make procedure for the frozen release, select Update Make Procedures with New Properties to synchronize the dependency with the updated version number and file name.

209

21


TROUBLESHOOTING RELEASESI want to change the relative path for attachments to a frozen release, but the Set Relative Path feature is disabled on the right-click menu.

You can change the relative path for each file attached to a frozen release by right-clicking on the attached file and choosing Properties.

See “Changing the Properties for a Frozen File” on page 209 for more information.

0

REPORTING 1
4 ChangeMan DS has the following reporting features for your development environment:
• File Tree is a graphical depiction of the history of a file. It includes information such as branches and merges that have occurred to the file.

• Audit Trails show you what actions have been performed on a file, and who performed the action. It also shows you the current state of the file and if it requires any approvals.

• Impact Analysis determines which of your software components will be affected when you make a change to your software code.

VIEWING FILE INFORMATION FROM THE FILE TREEThe File Tree utility allows users to view the history information of a file in graphical representation.

Use this procedure to see the file information:

Step Action

1. Select a file.

2. Either:• right-click and choose File Tree.

• click from the Files toolbar.

211

21

Chapter 14: Reporting

ChangeMan DS displays a screen similar to the following:

The File Tree screen shows all branches, transfers, and merges created for the selected file.

Point the mouse at one of the version icons to display additional information about the file, such as status (checked out/in), the last owner or the last user to perform the transaction that created that version, and the date when the last transaction took place.

The following icons explain the file's status:

From the File Tree, you can perform different actions by selecting a version (or versions) of the file, and clicking a toolbar button.

This icon… Represents this type of file…

A checked out file currently located in a Development area.

The original version of a checked out file currently located in a Production area.

2


For example, you can view a previous version of a file by selecting the version of the

file and clicking View File .

See “File Tree UI” on page 400 for more information on the toolbar buttons.

AUDIT TRAILChangeMan DS creates a record in its database every time you issue a file transfer request, approve a pending transaction, invoke the Build module, or perform any other SCM activity. The recorded information lets you produce reports that indicate who changed a file, as well as when and why it was changed. Approvals, comparisons, and roll backs can be run directly from the report.

You can build an Audit Trail query by defining the search criteria and filter. The queries can produce audit trail reports that answer questions such as “Who is working on the project XYZ?” or “When did John modify the file ABC?” For example, if you enter “abc” in the file name field, ChangeMan DS displays the change history for all files that contain “abc” as a part of the file name, such as “abcnew” and “newabc”.

You can specify multiple search criteria during a single query. For example, you can display a list of transfer requests issued by a given user, during a certain date range, and for a specific file.

Saving a query for future use lets you generate reports on a regular basis. For example, you can produce a weekly report showing all files that are currently checked out by the software developers.

Running Audit Trail ReportsYou can create an audit trail report for one or more files under ChangeMan DS control. Creating an audit trail report involves searching for all transaction information recorded for each file.

The Audit Trail window is where you search for specific versions of a file, or view the audit trail information about a file. The Audit Trail window can be accessed from ChangeMan DS, or from your development environment when working on a project under ChangeMan DS control.

The Audit Trail Window can be accessed by one of the following methods:

• From Windows client, click on the Tools toolbar or choose Audit Trail from the Tools menu.

• From your IDE (refer to their documentation).

213

21


• From the Web browser and Java clients. Click the Audit Trail button on the toolbar, or select a file and choose Show History from the right-click menu.

• From the Command Line Interface. See the Serena® ChangeMan® DS Command Line Interface Guide for more information.

The Audit Trail window consists of the following sections:

• The top section contains fields for user input, and for defining queries.

• The middle section lists the results of a query.

• The bottom section contains toolbar buttons that represent available commands.

Viewing the Audit Trail for One FileUse this procedure to view the audit trail from ChangeMan DS:

Step Action

1. In ExplorerView, select the area that contains the file you want to see the history of. The list of files appears in the right pane.

2. Right-click on the file, then choose Show History. The Audit Trail window displays. The Show History command for a file is not available once a file has been promoted to another area.

3. In the Windows client, click Find Now or New Search. In the Web browser and Java clients, click Search. The history displays.

4. Continue to “Working with Audit Trail Reports” on page 222.

4


Creating an Audit Trail Report with a QueryUse this procedure to create an audit trail report:

Step Action

1. Either:

• Click on the Tools toolbar.

• Choose Audit Trail from the Tools menu. (Windows client)• Choose ChangeMan DS > Audit Trail (Web browser and Java cli-

ents)The Audit Trail window displays.

2.Optional.

To restrict the query to one file:Type the name of a file in the File Name field. The field is case sensitive.If you are qualifying by file name:• For Web browser and Java clients, you must search for the infor-

mation on each file individually.• For Windows client, wildcards are required to return multiple files.

The wildcards are in DOS/UNIX format, so you would use * for any sequence rather than the SQL format of using %.

If you are not qualifying by file name, all files meeting the other filter criteria set are reported.

3.Optional.

To restrict the query to certain criteria, complete the appropriate fields on the different tabs. See the following sections for more information on the different tabs:• “General Tab on Audit Trail Window” on page 218• “Location Tab on Audit Trail Window” on page 219• “Date Tab on Audit Trail Window” on page 220• “Filter Tab on Audit Trail Window” on page 220

4. To restrict the number of results, insert the maximum number in the Maximum Results field. The maximum number is 99999.In the Windows client, the Maximum Results field is not available.

215

21


Saving a QueryIn the Web browser and Java clients, the Save Query option is not available.

Use this procedure to save a query:

5. Click Find Now in the Windows client or Search in the Java and Web browser clients. Any matching information displays.Note: If your results are not what you expected, check the Audit Trail

Filter settings to see if the State, Opened button is toggled on. If this option is on, only information on currently checked out files will be displayed. Toggle it off to see the history of all transactions (subject to other filters).

6. Either:• Continue to “Working with Audit Trail Reports” on page 222.• Add information about more files, repeat Step 2 through Step 5. Do

not click New Search; this will clear the list and start a new search. In the Web browser and Java client Audit Trail, Find Now is not available.

Step Action

1. From the Tools menu, choose Audit Trail in the Windows client. The Audit Trail window appears.

2. Define the criteria for the query in the four tabs as described in “Creating an Audit Trail Report with a Query” on page 215.

3. Click Save Query.The Save As dialog box appears.

4. In the File Name field, type a descriptive name, then click OK.The query file extension is daq.

Step Action

6


Creating an Audit Trail Report Using a Saved QueryIn the Web browser and Java clients, the Load Query option is not available.

Use this procedure to create an Audit Trail report with a pre-defined query:

Viewing an Audit Trail from an IDEThe Audit Trail is invoked by using the Show History or History commands from most IDEs. Refer to the integrated product guide for your specific IDE for information on viewing the Audit Trail from your that IDE.

Query Criteria for an Audit TrailSpecify the criteria for searches in the user input area of the Audit Trail window. You can save the searches you define, and also load saved searches. The criteria are divided into the following areas, each on a different tab:

• “General Tab on Audit Trail Window” on page 218

• “Location Tab on Audit Trail Window” on page 219

• “Date Tab on Audit Trail Window” on page 220

• “Filter Tab on Audit Trail Window” on page 220

Step Action

1. From the Tools menu, choose Audit Trail. The Audit Trail window appears.

2. Click Load Query. The Open dialog box appears with a default file filter of ChangeMan DS Audit Query file types.

3. Select the file you want to use, then click Open. The search criteria are loaded into the Audit Trail window.

4. Click New Search.

217

21


General Tab on Audit Trail WindowUse the fields in the General tab to define basic search information.

Items on the screen are:

In this Field… Enter…

File Name The name of a file for which you want to view the SCM activity report. The field is case sensitive.On the Windows client, you may enter the first characters of a name to search for any matching names. For example: VBProj would match VBProject.exe and VBProj1.cpp. On the Web browser and Java clients, you must enter the full name in the field.

Home Area A Production area name. Click the browse button to select an area ID from the Product Area List dialog box.

Home Path The path to a Production area.

Project A project name to view the list of all SCM transactions

related to this project. Click to select a project ID from the Projects dialog box.

Release A frozen release name for the specified Project

User Name A ChangeMan DS user name to view the list of all SCM

transactions performed by this user. Click to select the user name from the User List dialog box.

8


Location Tab on Audit Trail WindowUse the fields in the Location tab to define search criteria based on source and target locations (areas).

It is not necessary to provide the host and path names for an area in addition to the area ID. You may, however, enter the path information to limit the search to a specific subdirectory in the area.


Description Any character string to find all ChangeMan DS transactions that contain the given text in the Description field. The field is case sensitive.

Version Select the Version box to limit the Audit Trail report to the range of version numbers selected in the From and To boxes. The limit is 100000.

In this Input Field… Enter…

Source

AreaThe name of a source area (or click next to the area field, then select the area from the displayed list).

Host A host name to view the history of file transfers originating from a given host.

Path A directory or folder path and name to view the history of file transfers originating from this location.

Target

AreaThe name of a target area (or click next to the area field, then select the area from the displayed list).

In this Field… Enter…

219

22


Date Tab on Audit Trail Window

On Date tab, the From and To dates constrain queries to between the selected dates, inclusive.

Click the Date check box (upper-right corner of the To date field), then select From (start) and To (end) dates to limit the query to the selected dates.

The Web browser and Java clients Audit Trail Date tab provides entry fields for start and end dates rather than a calendar selection.

Filter Tab on Audit Trail Window

On the Filter tab, select (or clear) the options to define the type and status of transactions to include on the report. You can include a specific transaction by selecting the transaction type or status. You can exclude the transaction by clearing the same option.

The selections in the Filter tab are “sticky;” that is, if you change the options on the Filter tab and perform a search, those settings remain, even if you close the Audit Trail window or ChangeMan DS. If you do not see the files you want in a search, look in the Filter tab to verify that the options you want to use are selected.

Host A host name to view the history of file transfers targeting this computer.

Path An area path to view the history of file transfers targeting this directory. You can limit the search by specifying a subdirectory name.

In this Input Field… Enter…

0



Select… To report…

Type

Initial Load Records created during the initial area configuration.

Check In All transfers targeting Production areas.

Check Out All transfers originating from Production areas.

Distribution Read-only transfers.

Cancel Check Out Records for cancelled check out transactions.

Merge Merge transactions.

Branch Branch transactions.

Approval The log of approval or sign-off activities.

Transfer Ownership Records for transfers between Development areas.

Status

Requested File transfer requests that had been processed by ChangeMan DS due to scheduling reasons.

Pending All file transfer requests that must be approved or signed off by the authorized personnel.

Completed All successfully-completed transactions.

Aborted Aborted transactions. Rejected transfers requests between areas are also marked as Aborted.

Halted Halted transactions, which indicate that the promoted copy of a file is identical to the file's original version. ChangeMan DS does not transfer the new copy of the Production file, but creates an audit trail record in the database.

Current State

Checked Out Only files that are currently checked out.

221

22


Hierarchical View of the Audit TrailOn the left side of the result window is a hierarchical tree view that allows you to filter the result view. After a search is performed, the result window displays only the entries among all search result that correspond to the current selection in the tree window.

Results can be filtered by:

• users

• Home areas

• releases

• projects and related releases

• transaction status

• transaction type

Working with Audit Trail ReportsAfter running an audit trail report as described in “Running Audit Trail Reports” on page 213, you can do the following with the results:

• Get information about the selected transactions. (Copy, View Description)

• Do something with the selected transactions. (Delete, Repeat/Restart)

• Get information about the files in the selected transactions. (View, File Tree, SignOff History)

• Do something with the files in the selected transactions. (Print, Print Preview, Rollback, Compare)

• Modify the layout of the report.

• Perform an additional query, appending new results to current list.

Modifying a Column LayoutYou can alter the view of the reports by manipulating the columns as follows:

• Rearrange report columns by dragging-and-dropping the column headers to desired positions.

• Remove column by dragging-and-dropping it off the column bar until an “X” appears over the name.

• Add columns back into the display by right-clicking on the column bar and checking item desired.

2


• Sort the information by any of the columns by clicking on that column header.

Printing an Audit Trail ReportYou can print the audit trail (transaction history) of any file or group of files under ChangeMan DS control. Before you can print an audit trail report, you must run an audit trail report.

This feature is not available in the Web browser and Java clients.

Use this procedure to print the report:

Deleting Records from Audit Trail Reports

It is recommend that you do not delete these database records. By deleting a database record, you delete all information associated with this transaction.

For example: if you delete a check out transaction, then the file's status is no longer considered to be checked out. If you delete a check in transaction, the system deletes the information about the file's previous version.

Only an authorized user can delete records from the Audit Trail report.

Step Action

1. Create an audit trail report for the file or files.

2.On the toolbar at the bottom of the Audit Trail window, click .

The report will be printed as it is arranged on the screen. Print two pages side-by-side to give more information if desired.In the Web browser and Java clients, the print option is not available.

223

22


Use this procedure to delete a record from an audit trail report:

Comparing a File with the Previous VersionA comparison can be run directly from the Audit Trail to see the actual lines of code that were changed.

Compare a file with its previous version, by selecting the file then clicking (or selecting Compare from the right-click menu or from the Web browser/Java client toolbars).

See “Comparing Files from an Audit Trail Report” on page 145 for more information.

Rolling Back from an Audit Trail Report

This option replaces the current version of the selected files with any of the previous versions archived by ChangeMan DS. The Check In transactions are primary candidates for the Rollback procedure because the old versions are typically saved during promotion to Production.

Only authorized users can perform the Rollback procedure in the Audit Trail report.

Step Action

1. Select the record you want to delete from the Audit Trail report.

2. Either:

• click Delete from the toolbar at the bottom of the Audit Trail window.

• right-click on the selected file and choose Delete.The “Are you sure?” prompt displays.

3. Click OK.

4


Use this procedure to roll back to a previous version of a file:

Approving a Pending Transaction from the Audit Trail

You can approve a pending transaction from the Audit Trail report, by selecting the pending transaction and clicking , or by selecting Approve from the right-click menu or from the Web browser/Java client toolbar.

See “Approving File Transfers” on page 237 for more information.

Viewing the Sign-off History of a File

You can view the sign-off history of any file under ChangeMan DS control that has been approved (type is Approval) by right-clicking on that file, and choosing Signoff History.

See “Viewing the Sign-off History of a File” on page 241 for more information.

In the Web browser and Java client, the sign-off history option is not available.

Copying the Audit Trail ReportYou can copy the Audit Trail report to the clipboard, so that it can be pasted into a document for editing or reformatting.

To copy the report, right-click on a file in the report, and select Copy.

The Copy option is not available in the Web browser and Java clients.

Viewing the File Tree for a FileView the File Tree for a file on the Audit Trail Report by right-clicking on the file, and selecting File Tree.

See “Viewing File Information from the File Tree” on page 211 for more information.

Step Action

1. Select one or more check in transactions from the Audit Trail report.

2. Either:

• click .

• right-click on the selected file and choose Roll Back.

225

22


Viewing a FileView a file’s contents from the Audit Trail Report by right-clicking on the file, and selecting View.

See “Viewing the Contents of a File” on page 54 for more information.

Viewing Transaction DescriptionsView the description of the selected transfer transaction by right-clicking on the file, and selecting View Description.

Although the description is shown on the report, only a limited number of characters are displayed. If the description is long, use View Description.

Repeating/Restarting TransfersRepeat a transfer or restart a transfer that has been halted by right-clicking on the file, and selecting Repeat/Restart. Although the transfer dialog contains no information, but clicking Transfer will try to transfer the selected file.

The Repeat/Restart option is not available in the Web browser and Java clients.

Appending Additional Query Results to Audit Trail ReportTo perform an additional query, append results to your current audit trail report by selecting new criteria on the tabs, and clicking Find Now.

This option is not available in the Web browser and Java clients.

Exiting the Audit Trail Module

To exit the Audit Trail module, either click Close from the Audit Trail toolbar

or click Exit from the Web browser and Java clients.

Troubleshooting Audit TrailWhy doesn’t the Show History command appear on the shortcut menu when I right-click on a file in ChangeMan DS?

The file has been promoted to another area, but the current area isn’t set up to delete files when they are promoted. To see the history of a file, select the controlled copy of the file in the area to which it was last promoted.

6


If you aren't sure where the controlled copy of the file currently resides, view the file from the Production area and look at the columns Current Area and Current Path. This information can also be searched for in the Audit Trail.

If you don’t want to see the copy of the file in an area once it is promoted, change the display by toggling on the Do Not Access Area Agent button.

If you want the file copies to be deleted upon promotion, ask your Administrator to set the Delete From option on the area to Yes.

Expected entries don’t appear in Audit Trail.

Check the Audit Trail Filter settings to see if the State, Opened button is toggled on. If this option is on, only information on currently checked out files will be displayed. Toggle it off to see the history of all transactions (subject to other filters).

What does the “Failed to retrieve first archive - #3003” error message mean when trying to compare a file in the Audit Trail window?

An Archive Path was not defined for the Production area when it was set up, therefore no previous version of the file exists. The Archive Path stores previous versions of files.

Even though a pending transfer request was approved and the Audit Trail indicates the transfer is complete, why does the user interface still show the file as Pending?

Check VCS_SCHEDULE on the UNIX ChangeMan DS Main Server. If the process is running, kill it and restart it. If it is not running, start it.

IMPACT ANALYSISChangeMan DS provides the ability to create a complete inventory of your software components automatically. This information is stored in the ChangeMan DS metadata database. The Impact Analysis module produces “where-used” reports based on the information collected during check in and initial loads of files to Production areas. This means that you can instantly identify all files that use a specific variable, dependency, or word.

Impact Analysis lets you determine the effect a change has on other components of the system. You can use the Impact Analysis results to group the related components by directly attaching the affected files to a project, or to perform other SCM activities.

227

22


Performing Impact AnalysisImpact Analysis can be performed in the following ways:

• Alphabetical, to view all elements documented by ChangeMan DS in alphabetical order. You can select one element from the list to display a list of files that use this item.

• Itemized, to search all files that use a specified element, function call, or include file.

You enable Impact Analysis for a Production area by selecting the AutoDoc (IA) option. Once you save the area information, ChangeMan DS automatically begins collecting data about files transferred to the area. ChangeMan DS keeps the information up-to-date by automatically re-scanning the files as they are checked in.

Note that if you deselect AutoDoc (IA) for a Production area, the previously gathered information will not be deleted, and will appear on Impact Analysis reports.

See “Area Configuration” in Serena™ ChangeMan® DS Administrator Guide for more information.

The Web browser and Java clients differ from the Windows client in several ways:

• The Impact Analysis report is created by clicking Search to execute against the entered criteria. The Find Now option is not available in the Web browser or Java clients.

• There are no buttons on the bottom of the display to execute common functions.

Alphabetical Impact AnalysisTo perform an alphabetical Impact Analysis:

Step Action

1. Expand the Impact Analysis node in the ExplorerView window.

2. Expand the letter of the alphabet of the term you are looking for.All documented elements that start with that letter are displayed. To stop the expansion of A through Z after you expanded the Impact Analysis node, choose Stop data retrieval on the Standard

toolbar.

8


Itemized Impact AnalysisItemized Impact Analysis identifies all files that use a specific element, function, or include file.

To perform an itemized Impact Analysis:

3. Click on the item you are looking for.

Only documents scanned for Impact Analysis information are listed. See “Performing Impact Analysis” on page 228 for configuring areas for Impact Analysis.

4. Continue to “Working with Impact Analysis Results” on page 230.

Step Action

1. Launch the Impact Analysis module.• Click the Impact Analysis node in the ExplorerView window.• Choose Tools > Impact Analysis (or ChangeMan DS > Impact

Analysis on the Web browser client.

• Click Impact Analysis on the Tools toolbar.

2. Supply a search item name on the Name Area tab.The Item Name field is case sensitive and does not accept abbreviations or wildcard characters.

Step Action

229

23


Working with Impact Analysis Results

ChangeMan DS displays results of the search process in the bottom portion of the Impact Analysis screen. The columns contain information about the particular files, and the column headings differ in between the Web browser client and the Win32 client.

The total number of files found during the search process displays in the bottom right corner of the Impact Analysis window.

By selecting one of the records and right-clicking on the item, you can perform certain functions on the records with the commands available from the right-click menu.

The Web client Impact Analysis does not include a right-click menu.

Choose to perform one of the following activities on your Impact Analysis Results

• “Modifying a Column Layout” on page 222

3.Optional.

Supply the name of a Production area to which to limit the search.If the Look in Area field is empty, then ChangeMan DS searches for the selected item in all areas.Click the Browse button to select an area from the list of all configured Production areas. (Not available in Web browser client)

4.Optional.

Choose options on the Advanced tab. (Not available in the Web browser client)See “Advanced Tab for Impact Analysis” on page 378 for description of the fields.

5. Either:• Click New Search (or Search on the Web Client.) to launch a new

search and erase the current list.• Click Find Now to append the results to the previous search.

See the descriptions for AND and OR under “Advanced Tab for Impact Analysis” on page 378 for more information.

To stop the search process, click Stop.

6. Click Close (or Exit from the Web browser client) to exit from Impact Analysis.

Step Action

0


• “Printing an Audit Trail Report” on page 223

• “Deleting Records from Audit Trail Reports” on page 223

• “Comparing a File with the Previous Version” on page 224

• “Rolling Back from an Audit Trail Report” on page 224

• “Approving a Pending Transaction from the Audit Trail” on page 225

• “Viewing the Sign-off History of a File” on page 225

• “Exiting the Impact Analysis Module” on page 233

Sorting Column Information

You can sort the information by any of the columns on the Impact Analysis report by clicking on that column header.

Columns for Win32 Client

Columns for Web Browser ClientThe Web client display includes special characters as well as alphanumeric characters. Information displayed includes the following:

This column… Displays this information…

Type Indicates if the entity is an element, function call, or include file.

File The full name of the file that uses the selected element.

Area The name of the Production area this file belongs to.

Path The directory path to the Production area this file belongs to.

Extension The file’s extension.


Word The word you selected.

Version The version of the selected file.

FileName The full name of the file that uses the selected element.

231

23


Printing Impact Analysis Reports

Print your Impact Analysis report, by either

• Clicking on the Impact Analysis toolbar.

• Selecting the content window and clicking on the Standard toolbar.

To preview you report before printing, click .

Viewing the File Tree for a File

View the File Tree for a file on the Impact Analysis Report by selecting a file then

clicking on the Impact Analysis toolbar.

See “Viewing File Information from the File Tree” on page 211 for more information.

Viewing a File

View a file’s contents on the Impact Analysis report by selecting the file, and clicking on the Impact Analysis toolbar.

See “Viewing the Contents of a File” on page 54 for more information.

Attaching a File to a Project in Impact Analysis

Attach a file from the Impact Analysis report to a project by selecting the file, and

clicking on the Impact Analysis toolbar.

See “Attaching Files from the Content Window” on page 84 for more information.

Click Refresh to reload the Impact Analysis data.

Area The name of the Production area this file belongs to.

Path The directory path to the Production area this file belongs to.


2


Refining an Impact Analysis Report

Search within the current Impact Analysis results by selecting AND on the Advanced tab, inserting your criteria, and clicking Find Now.

Appending Additional Results to an Impact Analysis Report

Add to your current Impact Analysis results, by selecting OR on the Advanced tab, inserting your criteria, and clicking Find Now.

Exiting the Impact Analysis ModuleTo exit the Impact Analysis module, either click Close from the Impact Analysis toolbar or click Exit from the Web client.

Troubleshooting Impact AnalysisWhy can’t Impact Analysis find my file?

This problem can be caused by the AutoDoc (IA) feature not being enabled on the Production area or from the file not being scanned when it was placed under control.

To rescan the files in a Production area, run vcs_doc.exe and point to the Production area where the file is located. For example:

vcs_doc.exe <area name>

where the <area name> is the name of the Production area.

By default, vcs_doc.exe is located in the <Program Files>\Serena\ChangeMan\DS\Server directory on the Main Server machine.

Note that you can view the output from vcs_doc in vcs_doc.log in the same directory.

233

23


4


235

23


6

APPROVING FILE TRANSFERS 1
5
Users who are on the sign-off list must approve transfer requests that are in pending status for a designated area. Until each user in the sign-off list approves pending transactions, the transactions are not complete and the files remain in the source area until all approvals are complete.

You can approve requests for transactions involving single files, multiple files, and for all approvals pending in a selected project, folder, or area.

Single-file transactions waiting for approval show a pending icon in the Request Status column in the ChangeMan DS Explorer window or show a status of Pending in the Audit Trail report.

Each person or group in the sign-off list must approve the transaction. For groups listed in the sign-off list, any user in that group can sign off for the group.

If one user or group on the sign-off list rejects the transaction, the transaction does not occur.

After the last person or group on the sign-off list approves the transfer request, ChangeMan DS creates a log record in the Audit Trail database and changes the request status to one of the following:

• Requested, if the transfer was scheduled to take place in the future.

• Completed, if the scheduling option was not used.

Only an authorized user can approve pending transactions, and only in the order established during the Area Setup process.

Refer to “Area Configuration” and “Sign-off Properties” in Serena® ChangeMan® DS Administrator’s Guide for additional information.

You can also create an approval process when implementing the Package-Oriented approach. See “Approvals in POA” on page 295.

237

23

Chapter 15: Approving File Transfers

APPROVING A PENDING TRANSACTION FROM EXPLORERVIEW

To approve a pending transfers from ExplorerView:

Note If there are additional members that need to sign off after you have given your approval, you receive an error message that you are not allowed to sign off for the next user. Disregard this message.

Step Action

1. Right-click and choose Promote > Approve on one of the following:• A file that shows a pending in the Request Status column.• Multiple files with a pending status (hold down Ctrl or Shift when

making your selection).• A folder that contains files with pending transfers.• An area with pending file transfers to or from it.• A project with attached files that have pending transfers.If you are not authorized to approve the request, or if it is not your turn, ChangeMan DS asks if you want to continue, or if you want to cancel the operation.If you are authorized, the ChangeMan DS Approval dialog displays.

2. Modify the list by removing pending transfers from the list by selecting the entries, and clicking Remove.

3. Approve all pending transfers in the list by clicking Approve All.

4. If the ChangeMan DS Select a User dialog displays, select the group that you are signing off for, and then click OK.Note: This dialog displays when multiple groups are next on the sign off

list.

5. If "OR" or “AND” password has been set in the sign-off properties for the area in which the files you are approving reside, then the following dialog displays.To complete the sign off, you must type the correct password, then click OK. This password is defined during the configuration of the given area.

8


APPROVING A PENDING TRANSACTION FROM AN AUDIT TRAIL REPORT

To approve pending transactions that are listed in an Audit Trail report:

Step Action

1. Create an audit trail report that contains the pending transaction:

a) Open the Audit Trail window. For example, choose Tools > Audit Trail. See “Audit Trail” on page 213 for more information.

b) Click on the Filter tab.

c) Deselect all but Pending in the Status group.

d) Click Find Now.

2. Select one or multiple pending transactions.

3.Click Approve .

If you are not authorized to approve the request, or if it is not your turn, ChangeMan DS asks if you want to continue, or if you want to cancel the operation.If you are authorized, the ChangeMan DS Approval dialog displays.

4.Optional

Modify the list by removing pending transfers from the list by selecting the entries, and clicking Remove.

5. Approve all pending transfers in the list by clicking Approve All.

239

24


Note If there are additional members that need to sign off after you have given your approval, you receive an error message that you are not allowed to sign off for the next user. Disregard this message.

REJECTING A PENDING FILE TRANSFERWhen you reject a file transfer, the file is not copied or moved to the target area. Anyone on the sign-off list for an area can reject a pending transfer to that area at anytime.

To reject a file transfer:

6. If the ChangeMan DS Select a User dialog displays, select the group that you are signing off for, and then click OK.Note: This dialog displays when multiple groups are next on the sign off

list.

7. If "OR" or “AND” password has been set in the sign-off properties for the area in which the files you are approving reside, then the following dialog displays.To complete the sign off, type the correct password, then click OK. This password is defined during the configuration of the given area.ChangeMan DS updates its metadata database with the latest information, then sends e-mails to all users configured in the sign-off notification list.

Step Action

1. Right-click and choose Promote > Approve on one of the following:• A file that shows a pending in the Request Status column.• A folder that contains files with pending transfers.• An area with pending file transfers to or from it.• A project with attached files that have pending transfers.

Step Action

0


When you reject a file transfer, the file is removed from the pending state, and the file is not transferred. You can query for rejected file transfers by running an Audit Trail. Rejected transfers have the status of Aborted, and contain Rejected by <user name> in the description.

Note ChangeMan DS does not notify the user who requested the file promotion that the promotion has been rejected.

VIEWING THE SIGN-OFF HISTORY OF A FILEYou can view the sign-off history of any file under ChangeMan DS control that has been approved.

In the audit trail for the Java and Web browser client, the sign-off history option is not available.

To view the sign-off history:

2. Reject a pending transfer by selecting the request in the lower pane, and clicking Reject.

3. Add a description for the rejection in the Enter Transaction Description dialog.If you are not authorized to reject the request, ChangeMan DS notifies you of the fact and the file transfer remains in the pending state.

Step Action

1. Create an audit trail report that contains pending transactions by clicking on the Filter tab in the Audit Trail window, deselecting all but Pending in the Status group, then clicking Find Now.

2. Select a record with the type of Approval.

3. Right-click on the file, then choose Signoff History. The sign-off history for that file appears.

4. Press Esc to close the sign-off list window.

Step Action

241

24


2

PACKAGE-ORIENTED APPROACH 1
6
ChangeMan DS offers two approaches to file organization: projects and the package- oriented approach.

Introduced in ChangeMan DS Version 5.4.1, POA provides a way to track change requests for your software throughout the change life cycle, so that the work being done at each phase is visible and approved before going forward. It enhances the project-level behavior of ChangeMan DS, taking change management to a higher level of organization.

Package functionality is available through the Web browser and Java client.

POA uses four main objects: Applications, Packages, Projects, and Areas.

• An Application is the highest level of organization of a set of software changes. It is a logical grouping of software components that represents a complete software entity, such as a software product or software system. You can attach additional documentation such as technical specifications to the application. An application includes areas, projects, and packages, and they help to further limit the scope of the changes.

• A Package is the set of components required to implement a change to your system. Packages can be tracked and manipulated as a single entity. A package is part of only one application, and may be linked to other packages in the same application. There can be many packages associated with an application.

A package follows a life cycle that determines the states and transitions that a package must traverse from the time it is created until the time it is successfully installed (see “Life Cycle States for Packages” on page 284).

Packages can be hierarchical, where parent-child relationship is defined (see “Establishing a Hierarchy for Packages” on page 270), and they can be dependent, where a predecessor-successor relationship is defined (see “Dependencies between Packages” on page 271).

243

24

Chapter 16: Package-Oriented Approach

• A Project is a logical grouping of software components associated with applications and packages, The projects are tracked and manipulated during the SCM promotion, build, and release processes. There can be many projects associated with applications and packages. The same project can be associated with many different packages across many applications. A project associated with a package must be associated with its parent application.

See “Using Projects” on page 63 for additional information about projects in ChangeMan DS.

• An Area is a physical location, in which the software components organized by applications, packages, and projects reside. Specific Production, Development, or QA areas can be associated with applications and packages to control the repository, work, and testing locations used during the change cycle. You can also associate particular Installation areas where the deliverables will be placed.

The ChangeMan DS package-oriented approach is similar to the approach used in the ChangeMan ZMF environment. By using ChangeMan ECP, a ChangeMan DS package can be linked to a ChangeMan ZMF package. When packages are linked in this manner, they can be approved as a single entity with ChangeMan ECP.

Note that two ChangeMan DS packages can be linked from within ChangeMan DS, but that link is not recognized by ChangeMan ECP, and has no effect on processing.

See “Linking Packages” on page 266 for additional information on linking, and see Serena® ChangeMan® Enterprise Change Portal Reference for information on using linked and coordinated packages with other Serena products.

USING THE PACKAGE-ORIENTED APPROACHThe following steps describe how to manage code using the package-oriented approach.

4


1. New files are placed under the control of ChangeMan DS.

See “Adding Files To ChangeMan DS Control” on page 47 for more information.

2. An application object is created. Creating applications include attaching projects, Development areas, and Installation areas.

See “Creating an Application” on page 250.

3. A change package is created that defines the files that need to be changed.

New File

The new file is checked into the Production (baseline) area.

The new file is attached to a ChangeMan DS project.

Production Area

Associated Project

Add projects to the application to define the scope the applications.

Attach Installation areas to your application.Installation of a package moves files marked as deliverable into these areas.

Attach all areas available to developers who will be working on the code components for this application.

Application

ProjectsDevelopment

Areas

Installation Areas

The package is a subset of projects and areas of a parent application. It defines the change set.

Package

Application

245

24


See “Creating a Package” on page 261.

4. A developer is notified of the change, and edits the file.

See “Editing Files in a Package” on page 279.

5. The developer promotes the package to the FRZ state, which creates a frozen release of all the projects associated with the package.

See “Freezing Files of a Package” on page 282.

6. An approval process can be created to require a manager’s approval before moving the package to the APR state.

Once approved, a package moves to the APR state automatically. If rejected, the package moves to the REJ state.

See “Approvals in POA” on page 295.

To edit files, the developer:1. Checks out the files to one of the Development areas attached to the package. 2. Edits the file.3. Checks in the updated file to the Production area.

Development Area Production Area

ChangeMan DS verifies that no files associated with the package are currently in the Development areas attached to the package, then a frozen release is created of all the projects in the package.

Frozen ReleaseProduction Files

6


7. Once in the APR state, the package waits to be installed. It automatically installs when the installation time defined in the package is reached.

If the files encounter problems being installed, the package moves to the IFL (install failed) state.

See “Viewing Installation History of a Package” on page 289 for the installation history of a package.

ACCESSING PACKAGE-ORIENTED FUNCTIONALITYPackage functionality is available through the Java and Web clients.

To use the package functionality, you must have the Web and Application/Package View boxes checked on the Clients tab of the ChangeMan DS Edit User dialog.

See “Clients” in Serena™ ChangeMan® DS Administrator Guide for information on these options; see “ChangeMan DS Java Client and Web Browser Client UI” on page 380 of this document for general information on the Web browser and Java clients.

When a package is installed,the files marked as deliverable are moved to the installation area that is designated in the package.

Production Area Installation Area

247

24


Log on to the ChangeMan DS Java or Web browser client (you must have Application/Package View permission).

Note that Applications, Approval, Approval Configuration, Notification Configuration, Contacts, and Dependency Configuration nodes are displayed for the package functionality, in addition to the standard ChangeMan DS tree nodes.

See “ChangeMan DS Java Client and Web Browser Client UI” on page 380 for more information on the nodes.

APPLICATIONSAn application is a logical grouping of files that defines the scope of the code components that are being developed. An application represents a complete software entity.

Note that the concept of application in the package-oriented approach is independent of the concept of application as used in the Application Process Flow.

Access applications by expanding the Applications node; all created applications display in the ExplorerView tree. (The Applications node is only available in the Web browser and Java clients.)

8


When expanded, each individual application node contains the following nodes:

• Packages: Displays attached packages and allows access to modifications.

• Projects: Displays attached projects and allows access to modifications.

• Areas: Displays attached areas.

See “Accessing Package-Oriented Functionality” on page 247 for more information.

The main dialog for creating and editing applications is the Application dialog:

Select this tab… To do this…

General Access the application’s ID, name, and description.

Specifications Add, remove, or edit files that specify the design of the application.

Projects Attach or remove ChangeMan DS projects to or from the application.

Areas Associate specific ChangeMan DS areas with the application.

Packages Create and edit change packages associated with the application.

249

25


Creating an ApplicationTo create an application:

Adding Specifications to an ApplicationWhen you define a software product or system information as an application, you can associate supporting documentation with the application. This could include original and revised design specifications or change specifications for later releases.

Step Action

1. With the Applications node selected, click New.This functionality is available only on the Web browser and Java clients.

2. On the General tab, create a name and description for your application.Both the Name and the Description field are mandatory.

3. On the Specifications tab, add any necessary files. See “Adding Specifications to an Application” on page 250 for more information.

4. On the Packages tab, add any necessary packages. See “Packages” on page 255 for information on packages.

5. On the Projects tab, attach any necessary ChangeMan DS projects, choosing from the list of available projects in the lower pane of the display. See the“Using Projects” on page 63 for information on projects.

6. On the Areas tab, associate any necessary ChangeMan DS areas. See “Areas” in Serena™ ChangeMan® DS Administrator Guide for information on areas.

7. Click Save.

0


To attach specification files to an application:

Attaching Projects to an ApplicationAttaching projects to an application groups files in the application. Each project is a group of files; an application consists of all files of projects associated with it.

Usually you need different projects for your source and deliverable code. The source projects are the grouping of your source files stored in your Home (Production) area. The deliverable projects are the compiled executables that are moved to the Installation area when packages are installed. Deliverable projects don’t need to be compiled: For example, they may be HTML, ASP, or JSP.

Step Action

1. Select the Specifications tab while creating or editing an application.This functionality is available only on the Web browser and Java clients.

2. Click Add.The specifications entry screen displays.

3. In the Name field, type a distinctive short identifier for the specifications file you are attaching.

4. In the Description field type as much detail as you need to explain the file you are attaching.

5. Click on the Java client or Click to edit on the Web browser client.A dialog appears below the label File.

6. Click Attach (Web browser) or Attach File (Java).A file browser displays.

7. Browse for, then select the file to attach. Either select the file, then click Open, or double-click the file to attach it to the application.

8. You must click Save to complete the attachment process.

9. Click Exit to return to the Specifications screen.All specifications attached are listed.

251

25


To attach projects to a package:

Attaching an Area to an ApplicationThere are two types of areas associated with an application: Installation and Development.

• An Installation area is where the built files will be placed. It is a Production area, and it should not be the baseline area referred to by the projects. Users should not be allowed to check out files from the area. You can create scripts to be performed on files entering these areas (see “Creating Scripts for Package Installation” on page 286).

Step Action

1. With the Application node selected, select the application, then either:• click Projects.• click Edit, then select the Projects tab.You can also add projects when you first create an application by selecting the Projects tab and following the remaining steps.This functionality is available only on the Web browser and Java clients.

2. From the Available Projects list, select the projects to add, then click Attach.The project is attached.

3. To set the project to be installed to the designated Installation area, select the project, then click Deliverable. Yes appears in the Deliverable column. To deselect this option, select the project then click Clear.See “Attaching an Area to an Application” on page 252 for information on Installation areas.

4. Click Exit.

2


• Development or work areas are to where the developers check out the files. When a package is promoted to FRZ, ChangeMan DS checks these attached Development areas for project files. If no project files exist in these areas, ChangeMan DS continues to create a Frozen Release. The attached areas are a superset of all areas to which developers check out files. Restrict checked out files to these areas to verify that Frozen Releases have up-to-date files.

To create areas, see “Areas” in the Serena® ChangeMan® DS Administrator’s Guide.

Note The Areas node under a specific application, displays all areas associated with an application.

Use this procedure to attach areas to an application:

Step Action

1. With the Application node selected, select the application, then either:• click Areas.• click Edit, then select the Areas tab.You can also add areas when you first create an application by selecting the Areas tab and following the remaining steps.This functionality is available only on the Web browser and Java clients.

2. From the Available Areas list, select the area to add, then click Attach.The area is attached.

3.Optional

To detach an area, select an Attached Area, then click Detach.

4.Optional

To set a sub-directory or add another sub-directory relative to the root of an area, select the area, click Change path, then either:• Navigate to the new path and click OK, or• Create a new directory by clicking New Directory.

5.Optional

To add a script to an Installation area, select an attached installation area, and click Script.See “Creating Scripts for Package Installation” on page 286.

6. Click Exit.

253

25


Creating a Default Area ConfigurationCreating a default area configuration for an application allows all of the packages of the application to inherit all configuration information from the default area, such as area script configuration.

To create a default area configuration:

Step Action

1. With the Application node selected, select the application, then either:• click Default Config.• right-click on your application node, and choose Default Config.This functionality is available only on the Web browser and Java clients.

2. On the Development tab:

a) select or deselect areas that will be default Development areas for this application.

b) Optional. To set a sub-directory or add another sub-directory relative to the root of an area, select the area, click Change path, then either:• Navigate to the new path and click OK, or• Create a new directory by clicking New Directory.

3. On the Installation tab:

a) Select or deselect Production areas that will be default Installation areas for this application.

b) Optional. To add scripts to an attached Installation area, select the area, and then click Script. See “Creating Scripts for Package Installation” on page 286 for descriptions of the different types of scripts.

c) Optional. To set a sub-directory or add another sub-directory relative to the root of an area, select the area, click Change path, then either:• Navigate to the new path and click OK, or• Create a new directory by clicking New Directory.

4. Click Exit.

4


Working with an Application’s ProjectsThe Project node under an application lets you work with projects attached to that application.

This functionality is available only on the Web browser and Java clients.

With the Projects node or any of its first level subnodes selected, the following options are available:

PACKAGESChanges to a software component or system are introduced to ChangeMan DS through a change package. This enables the change set to be tracked, modified, and installed as a single entity, even if it contains many ChangeMan DS projects.

To each package, you can assign a change request ID to track the package activity throughout its life cycle.

The package name is user-specified In ChangeMan DS, while in ChangeMan ZMF, the name is system-generated from the application name and a sequential number.

The “Package Type” parameter is notational only; it has no effect on package processing.

Packages are available only on the Web browser and Java clients.

Package Configuration ScreenThe Package Configuration screen is used for creating and modifying packages.

This button… Lets you…

Edit Edit the properties of the project such as name, owner, and authorization list.

Deliverable Set the project to be installed automatically.

Clear Clear the deliverable status from the project.

Show History View the Audit Trail.See “Audit Trail” on page 213 for more information on Audit Trails.

255

25


The package configuration screen looks like this:

Tabs on this screen are:

Select this tab… To do this task…

General Access the package’s ID, name, and description. See “General Tab on Package Configuration Dialog” on page 257 for more information.

Specifications Attach specifications for this package.

Projects Attach or remove ChangeMan DS projects to or from the package.

Areas Associate ChangeMan DS areas with the package.

Links Associate other packages with this package.

Change Set Define the scope of the change.

Dependency Display, add, or remove predecessor and successor packages.

6


General Tab on Package Configuration DialogThe General tab on the Package Configuration dialog contains the following fields:

Hierarchy Display, add, or remove parent and subordinated packages.

Life Cycle View where in the life cycle the package is.This tab is available only after the package is edited or promoted.

This field… Contains…

ID The ID assigned to the package by ChangeMan DS.To assign the package a unique tracking number, see Change Request Number.

Creator The user ID of the person who created this package.

Name The name of the package.The name must be less than 50 characters and it cannot contain single quotes or spaces. If the package name has more than 50 characters, a single quote or a space, you experience errors later in the package life cycle. For example, you cannot promote the package to the FRZ state.

Title The title of the package.The title of the package must be less than 40 characters.Using a title greater than 40 characters causes a database error.

Select this tab… To do this task…

257

25


Type One of the following types of packages:

This type… Represents…

Unplanned/Temporary

Unscheduled changes that run for a predetermined time.These are usually one-time or short-term emergency fixes.

Unplanned/Permanent

Unscheduled changes that become part of a new or previously implemented release.These are usually emergency fixes.

Planned/Temporary

Scheduled changes that run for a predetermined time.These are usually one-time or short-term processes.

Planned/Permanent

Scheduled changes that become part of a new or previously implemented release.

In ChangeMan DS, the package type has no effect on the processing of the package; it is a label only.


8


Level One of the following:

This level… Indicates that the package…

Simple Contains a change that is unrelated to any other package.

Complex Is the parent of two or more participating packages that have interdependent changes to software or operational procedures.

Super Is the parent of two or more participating packages that contain major changes to several applications.

Participating Is related to one or more other participating change packages.

In ChangeMan DS, package level has no effect on the processing of the package; it is a label only.

Application The application with which this package is associated.

Creation Date The date the package was created.


259

26


Installation Date The date and time of planned installation.If a time is not specified, the default is 12:00:00 (midnight).If a date is specified, the package is installed as follows:• If the package is promoted prior to (or up to 24 hours

after) the date and time it is due to be installed, it is installed automatically.

• If the promotion does not occur within 24 hours of the scheduled install date and time, the package must be installed manually.

When the package is installed, it is moved to the INS state. Installation scripts are performed for the files moving into the Installation areas. See “Creating Scripts for Package Installation” on page 286.The time and date can be changed for the package until it has been approved. After the it has been approved (APR status), the packages must be reverted to DEV status before you can change the installation date and time.

Company The company that requested the change.See “Adding a Contact (or Requester) to a Package” on page 269 for more information.

Requester The contact who requested the change.See “Adding a Contact (or Requester) to a Package” on page 269 for more information.

Change Request Number

A tracking number for the change request.Note: The tracking number is assigned by the user. The

Package ID number is assigned by ChangeMan DS.

Description A description of the package.


0


Creating a PackageUse this procedure to create a new package under an application:

Step Action

1. With the Packages node selected, (or with an Application’s Packages tab selected), click New.Note that this functionality is available only on the Web browser and Java clients.

2. On the General tab, fill in the following mandatory information:• Name (note that the name of the package must be less than 50

characters and it cannot contain single quotes)• Title• Type• Level• DescriptionSee “Package Configuration Screen” on page 255 for more information on these fields.

3. Optional. Add a company and requestor.See “Adding a Contact (or Requester) to a Package” on page 269.

4.Optional

Add an Installation time and date.If a time is not specified, the default is 12:00:00 (midnight).See “Creating Scripts for Package Installation” on page 286 for configuring scripts that run on automatic installation.

5.Optional

On the Specifications tab, add any specifications needed for this package. See “Adding Specifications to a Package” on page 262.

6. On the Projects tab, add any necessary ChangeMan DS projects. See “Using Projects” on page 63 for information on projects.

7. On the Areas tab, associate any necessary ChangeMan DS areas. See “Areas” in Serena™ ChangeMan® DS Administrator Guide for information on areas.

261

26


Adding Specifications to a PackageAttach supporting documentation to a package to assist developers with information describing the changes to be made.

Use this procedure to attach specification files to a package:

8.Optional

On the Links tab, add any packages to link to this package.See “Linking Packages” on page 266.

9.Optional

On the Change Set tab, add any files necessary to define the scope of the change.See “Adding Files to a Change Set” on page 267.

10.Optional

On the Dependency tab, add, remove, or view this package’s predecessor or successor packages.See “Adding Dependencies Between Packages” on page 272.

11.Optional

On the Hierarchy tab, add, remove, or view this package’s parent and subordinate packages.See “Establishing a Hierarchy for Packages” on page 270.

12.Optional

The Life Cycle tab displays the package lifecycle. This is a read-only display.See “Life Cycle States for Packages” on page 284.

13. Click Save.

Step Action

1. Select the Specifications tab while creating or editing a package.See “Creating a Package” on page 261.This functionality is available only on the Web browser and Java clients.

2. Click Add.The specifications entry screen displays.

3. In the Name field, enter a distinctive short identifier for the specifications file you are attaching.

Step Action

2


Attaching Projects to a PackageChangeMan DS projects are associated with change packages to control the lower-level units of work that are done during the change cycle of the package. One project may be part of many different packages.

Because packages represent the life span of a change set, they can be treated as transient, and can be deleted upon implementation of the change set and closing of the change request. Any projects associated are typically retained, because they store build and release history, and may map directly to IDE projects.

If the projects are not attached at the application level, they are not available to be attached to the package. See “Attaching Projects to an Application” on page 251.

4. In the Description field enter as much detail as you need to explain the file you are attaching.

5. Click on the Java client or Click to edit on Web browser client.

6. If using the Web browser client, click Attach.If using the Java client, click Attach File.A browser displays.

7. Browse for, then select the file to attach by either double-clicking the file, or selecting the file, then clicking Open.

8. You must click Save to complete the attachment process.

9. Click Exit to return to the Specifications screen.All specifications attached are listed.

Step Action

263

26


Use this procedure to attach projects to a package:

Attaching an Area to a PackageThe directory structure in the default area configuration mirrors the directory structure specified in the project.

The available areas to attach to a package are the areas attached to the parent application. See “Attaching an Area to an Application” on page 252 for definition of the types of areas attached to a package.

Note Before attaching areas, you must add projects to the package.

Step Action

1. With the Packages node selected under the appropriate application, select the package, then either:• Click Projects.• Click Edit, then select the Projects tab.You can also add projects when you first create a package by selecting the Projects tab and following the remaining steps.This functionality is available only on the Web browser and Java clients.

2. From the Available for attach list, select the projects to add, then click Attach.The Default Area Configuration displays.

3. If area configuration has been specified at the Application level, select that area, click Select to automatically inherit area configuration.If one does not exist, click Exit.See “Creating a Default Area Configuration” on page 254.

4. Click Exit.The project is attached.

4


To attach areas to a package (the package, and the area that is to be attached to it, must be attached to the same application):

Step Action

1. With the Packages node selected under the appropriate application, select the package and either:• Click Areas.• Click Edit, then select the Areas tab.You can also add areas when you create a package by selecting the Areas tab and following the remaining steps.This functionality is available only on the Web browser and Java clients.

2. Choose a project from the drop-down menu.The project marked as Deliverable must be mapped to its target Installation area, and may or may not be mapped to a Development area. If the project is both the source and deliverable, it must be mapped to both types of areas.The project NOT marked as Deliverable is a source project, which is associated with a Development area, and the Installation tab for non-deliverable projects is grayed-out.

3. From the Available Areas list on the Development and Installation tabs, select the area to add, then click Attach.The area is attached.

4.Optional

To detach an area, select an Attached Area, then click Detach.

5.Optional

To set a sub-directory or add another sub-directory relative to the root of an area, select the area, click Change path, then either:• Navigate to the new path and click OK, or• Create a new directory by clicking New Directory.Refer to “Working Location” on page 87 and “Relative Path” on page 90 for additional information on work areas.

265

26


Linking PackagesYou can link ChangeMan DS packages; however, that unlike links to ChangeMan ZMF packages that are created with ChangeMan ECP, the link is notational only, and has no effect on promotions, approvals, or other such activities. Note also that a single ChangeMan DS package can be linked to multiple ChangeMan DS packages.

Refer to Serena® ChangeMan® ECP User’s Guide for information on linking to ChangeMan ZMF packages.

To link (or unlink) packages:

6.Optional

To add a script to an Installation area, select an attached installation area, and click Script.See “Creating Scripts for Package Installation” on page 286.

7. Click Exit.

Step Action

1. Select the Packages node for the appropriate application.A list of packages displays.This functionality is available only on the Web browser and Java clients.

2. Select the package to be linked, then click Edit.The package configuration screen displays.

3. Select the Links tab.The package linking screen displays. Any packages that are already linked to this package are listed in the upper pane; packages that are available to be linked are displayed in the lower pane.

4. Select the package to be linked from the list of available packages, then click Link.The package name appears in the list of linked packages.

5. Repeat Step 4 as required.

6. When all packages are linked, click Exit

Step Action

6


Adding Files to a Change SetCreate a change set to identify the files that need to be changed. Choose from the files in the projects attached to the package.

You can add files to the change set when the package is in the development state or when the package is being promoted from DEV to FRZ.

A change set can be populated manually or automatically from an SCC-compliant IDE. Refer to the Serena® ChangeMan® Integrated Products Guide.

Projects must be attached to the package before you can specify the change set.

Use this procedure to add files to (or delete files from) a change set when the package is in the development state or being promoted from DEV to FRZ:

Step Action

1. Select the Change Set tab when creating or editing a package.See “Creating a Package” on page 261 for information on creating a package.

267

26


2. Select the Change Set tab on the Package dialog.Items on the tab are:

Projects: Pulldown menu; lists the projects that have been configured for this package.

Available Files

List of the files in the selected project. Any of these files can be included in the change set.

Add Adds the selected files to the change set

View Displays the contents of the selected file.See “Viewing the Contents of a File” on page 54 for more information on viewing contents of a file.

Tree Displays the File Tree. See “Viewing File Information from the File Tree” on page 211 for more information.

Properties Displays the ChangeMan DS file properties of the selected file. Refer to “Viewing File Properties” on page 57 for more information.

Attached Files

List of files that are included in the change set.

3. To add a file to a change set, select the file from the Available Files list, then click Add.The filename moves from the Available Files list to the Attached Files list.

4. To remove a file from a change set, select the file from the Attached Files list, then click Remove.The filename moves from the Attached Files list to the Available Files list.

5. If there are no more files to add or remove, click Save, then click Exit.

Step Action

8


Adding a Contact (or Requester) to a PackageThe requester and company field contain the person who requested the change and the company (or division of your company) for which the person works.

Note that you can add a contact or requester during this procedure, or under the Contacts node. See “Contacts Node Toolbar Buttons” on page 390 for more information.

Use the following procedure to add a requester or company to a package:

Step Action

1. With the Packages node selected under the appropriate application, select the package and click Edit, then select the General tab.You can also add contacts when you create a package by selecting the General tab and then following the remaining steps.See “Creating a Package” on page 261 for more information.

2. On the Company drop-down, select the company (or division of a company) for which the requester works.If the entry doesn’t exist, create it with the following procedure:

a) Select (New Company) in the Company drop-down.

b)Click .

The Company dialog displays.

c) Fill in the company name and address.

d) On the Contacts tab, click Add to add the new contact.The New Contact dialog displays.

e) Fill in the contact name, e-mail, and phone number.

f) Click Save to save the information and exit the New Contact dialog.

g) To add more contacts, return to Step d.

h) Click Save to save the information and exit the Company contact dialog.

269

27


Establishing a Hierarchy for PackagesHierarchy establishes a parent-child relationship between packages.

Note that actions (such as promotions) taken on the parent package do not always affect the child package in the same manner. For example, a parent package could be promoted and, because of hierarchy, one of the subordinated packages might not be promoted.

Working from a selected package, you can designate a different package as a parent (there can be only one parent), and you can designate any number of packages as subordinated (child) packages.

Use this procedure to establish the hierarchy:

3. On the Requester drop-down, select the person who requested the change.If the entry doesn’t exist, create it with the following procedure:

a) Select (New Contact) in the Requester drop-down.

b)Click .

The New Contact dialog displays.

c) Fill in the contact name, e-mail, and phone number.

d) Click Save to save the information and exit the New Contact dialog.

4. Click Save on the Package dialog to save the changes.

Step Action

1. Select the Packages node for the appropriate application.A list of packages displays.This functionality is available only on the Web browser and Java clients.

2. Select the package for which you will establish the hierarchy, then click Edit.The package configuration screen displays.

Step Action

0


Dependencies between PackagesDependency establishes a sequential, rule-based relationship between packages. You specify predecessor and successor packages, and rules that must be met in order for the specified action to occur. This functionality is available only on the Web browser and Java clients.

A predecessor package is a package that must be in a defined state before the successor package can be promoted.

3. Select the Hierarchy tab.The package hierarchy screen displays.The upper portion of the package hierarchy screen identifies the parent package (if one has been designated). The lower portion of the screen list any subordinated (child) packages that may have been designated.

4. To establish the parent package, click Set in the upper portion of the screen.A list of packages displays.

5. Select the package that is to be the parent, then click Save.The package hierarchy screen displays.

6. To terminate the relationship with the parent, click Clear in the upper portion of the screen, then respond to the Clear Parent prompt.

7. To establish the child package, click Add in the lower portion of the screen.A list of packages displays.

8. Select the package that is to be the child package from the list of subordinated packages, then click Save.You can use the Ctrl or Shift key to make multiple selections.

9. To terminate the relationship with a child package, select the appropriate package from Subordinated Packages list in the lower portion of the screen, click Remove, then respond to the Remove Subordinate prompt.

10. After establishing the hierarchy, click Exit.

Step Action

271

27


The successor package is the package whose promotion is dependent on the state of the predecessor package.

Dependency configuration lets you specify a relationship that must exist between successor and predecessor packages before a transition between states can be taken by the successor package.

When defining the relationship, you specify the transition of the successor package, and the required state (or states) of the predecessor package. For example, you may specify a “Finish-to-Start” relationship, in which the predecessor package must be in FRZ before the successor package can transition from DEV to FRZ. Note that Finish-to-Start (Freeze) and Finish-to-Start (Approve) dependencies are configured by default.

Adding Dependencies Between PackagesYou can add or delete any number of predecessor and successor packages in any order.

Use this procedure to establish dependencies:

Step Action

1. Select the Packages node for the appropriate application.A list of packages displays.

2. Select the package for which you will establish the dependency, then click Edit.The package configuration screen displays.

3. Select the Dependency tab.The package dependency screen displays. The upper portion of the package dependency screen identifies any packages that have been designated as predecessors; the lower portion of the screen lists any packages that have been designated as successor packages.

4. To establish a predecessor package, click Add in the upper portion of the screen.A list of packages displays.

2


Removing Dependencies Between Packages

To remove existing dependencies between packages:

5. Select the package that is to be the predecessor, select the appropriate rule from the pulldown menu in the Dependency Rule section, then click Save.The package hierarchy screen displays.

Click to configure additional dependency rules; see

“Dependencies between Packages” on page 271 for details.

6. To establish a successor package, click Add in the lower portion of the screen.A list of packages displays.

7. Select the package that is to be the successor, select the appropriate rule from the pulldown menu, then click Save.The package hierarchy screen displays.Use the Ctrl or Shift key to make multiple selections.

Click to configure additional dependency rules; see

“Dependencies between Packages” on page 271 for details.

8. After establishing the dependency, click Exit.

Step Action

1. Select the Packages node for the appropriate application.A list of packages displays.

2. Select the package for which you are removing the dependency, then click Edit.The package configuration screen displays.

Step Action

273

27


Creating a Dependency Rule for POA

Use this procedure to configure a dependency rule:

3. Select the Dependency tab.The package dependency screen displays. The upper portion of the package dependency screen identifies packages that are designated as predecessors; the lower portion of the screen lists packages that are designated as successors.

4. To remove a predecessor package dependency, select the appropriate package, click Remove in the upper portion of the screen, then click OK on the confirmation prompt.

5. To remove a successor package dependency, select the appropriate package, click Remove in the lower portion of the screen, then click OK on the confirmation prompt.

6. Click Exit.

Step Action

1. Select the Dependency Configuration node.If any dependencies are configured, they are displayed.

2. Click New to create a new dependency.A dialog displays to configure the dependency. Supply the following information:

Name Name for this dependency.

Description Description of this dependency.

Successor Transitions

Select the transition for the successor package.

Predecessor States

Select the state that the predecessor must be in.

Step Action

4


Editing a Dependency Rule in POA

To edit an existing dependency:

3. Click Save.The new dependency is added to the list.

4. Repeat Step 2 and Step 3 for each dependency.

Step Action

1. Select the Dependency Configuration node.If any dependencies are configured, they are displayed.

2. Select the dependency to be modified, then click Edit.A dialog displays to edit the dependency.

3. Click New to create a new dependency.You can modify the following information:

Name Name for this dependency.

Description Description of this dependency.

Transitions Select the transition for the successor package from the pulldown menu.

Allowed States

To remove a state, select the state, then click Remove.To add a state, click Add; a list of Available States displays. Select the states, then click Save.

4. Click Save.

Step Action

275

27


Promoting a PackageA package’s movement from one state to another lets you manage and track the code changes to the files.

When a user attempts to promote a package to another state, ChangeMan DS verifies that any project or area configurations specified exist. That is, if a project file attached to a package is checked out to the area specified in the package, a promotion to FRZ is not allowed.

When a Package is manually promoted to the INS state, the installation process is bypassed, and no files are moved to the attached Installation folder. Use manual promotion if the files are installed by means other than ChangeMan DS, such as FTP.

See “Life Cycle States for Packages” on page 284 for a description of each of the life cycle states and “Promotion Types for Packages” on page 278 for the different allowable promotions.

Use the following procedure to move the package from one state to another:

Step Action

1. Select the Packages node in the appropriate application.A list of packages displays.This functionality is available only on the Web browser and Java clients.

2. Select the package to be promoted, then click Promote.The object promotion screen displays.The allowed promotions are displayed in the left pane, and the life cycle displays in the right pane. The current state of the package is enclosed in a red square.

6


3. Select the state to which the package is to be promoted from the list in the left pane.

4. Click Activate.The Promote dialog displays.

5. If the package is being promoted between FRZ and DEV states, you can add files to the change set, which lets you note what (if any) additional files were changed in the package.See “Adding Files to a Change Set” on page 267.

6. Add a comment to describe what has happened to prompt the promotion, then click Promote.If the promotion is allowable, the package is promoted to the selected state, subject to approvals.If an approval is required (for example, when promoting from FRZ to APR), the package is not promoted until it is approved.When the object is promoted, the new current state appears in red, and the old state appears in yellow.

7. Click Exit (or Back on the Web browser client) to close the Start Activity dialog.

Step Action

277

27


Promotion Types for PackagesThe life cycle allows only specifically-designated promotions. The user or group requesting the promotion must have the appropriate permissions, and the promotion may require approval by an authorized approver.

The typical promotions are:

In this promotion… These activities occur…

DEV > FRZ Attach projects and files as required; view file contents, the tree, or the file properties; add comments. The package is marked as “pending approval”, and the appropriate approver is notified; it does not move to FRZ until it is approved.

DEV > REJ Typically not allowed.

DEV > DEL The package configuration screen displays. You can view file contents, the tree, or the file properties. No approval is required for this promotion.

FRZ > REJ The package is rejected. Typically, no approval is required.

FRZ > DEL Mark the package for deletion. You can view file contents, the tree, or the file properties. No approval is required for this promotion.

FRZ > APR The package is marked as “pending approval”, and the appropriate approver is notified; it does not move to APR until it is approved.

APR > REJ The package is rejected.

APR > INS The promotion to INS is automatic. It occurs at the date and time specified for package installation. The promotion triggers the scripts defined for the Installation area. See “Creating Scripts for Package Installation” on page 286 for more information.

DEL > DEV The package configuration screen displays. You can view file contents, the tree, or the file properties. No approval is required for this promotion

INS > REJ The package is rejected.

8


Editing Files in a PackageUnder the package-oriented approach, files attached to a project and associated with a package should be edited only when that package is in the DEV state.

ChangeMan DS limits editing the files by making visible the Attachments folder under the Package node only when the package is in the DEV state. If the package resides in another state, such as FRZ or APR, the Attachments folder is hidden. This feature only pertains when accessing ChangeMan DS through the Java/Web browser clients.

If you access the files using the ChangeMan DS Windows client, you will be able to check out files from Production, although the package is not in the DEV state.

Tip Notifications for packages can be configured to include the files in the change set, which notifies developers of the exact files that need to be changed.

Use the following procedure to edit a file under ChangeMan DS control:

Step Action

1. Access the associated package to view the change set (the files that need to be changed), which is found on the Change Set tab.See “Creating a Package” on page 261 for accessing the Package dialog.

2. Check out the files for editing using one of the following methods:• Supported IDE. See the Serena® ChangeMan® Integrated Prod-

ucts Guide for more information.• Attachments node. See “Editing Files from the Attachments

Node” on page 280.• File Tree dialog. See “Editing Files from the File Tree” on page

281.• Other ChangeMan DS methods for checking out the files. See

“Checking Out” on page 105 for more information.Note: It is important that you check out files into a Development area

specified in the package. If not, the frozen release may include a non-updated file. See “Freezing Files of a Package” on page 282 for more information.

3. Make the change to your components.

279

28


Editing Files from the Attachments NodeUnder the package-oriented approach, the Attachments node under a package’s project node is available only when the package is in the DEV state.

To check out files from the Attachments node under a project:

4. Check in the file through the IDE, File Tree, or other ChangeMan DS methods. See “Checking In” on page 114 for more information.

5. Freeze the code by promoting the package to the FRZ state.• See “Promoting a Package” on page 276 for instructions on pro-

moting the package to frozen.• See “Freezing Files of a Package” on page 282 for information

about frozen releases.

Step Action

1. Select the appropriate Attachments node under your Application.For example: Applications > Your_Application > Packages > By State > DEV > Your_Package > Your_Project > Attachments > your_folder.This functionality is available only on the Web browser and Java clients.

2. On the file’s right-click menu, choose Promote > Check Out.The Transfer Request dialog displays showing where the files will be moved.

3. Complete the form as required, then click Transfer.The files are moved to the designated Development area.See “Completing the Transfer Request Dialog” on page 96 for information on the dialog.

Step Action

0


Editing Files from the File TreeThe File Tree dialog is available for any change package files specified in the change set.

Use this procedure to check out files from the File Tree on the Change Set tab:

4. Edit the files by doing one of the following:• Right-click on the file and choose Edit.

Depending on your ChangeMan DS configurations, either the ChangeMan DS or the default editor for your local system appears to let you edit the file.

• Open the file from the development area through your develop-ment tool.

5. Check in the file, on the file’s right-click menu, choose Promote > Check In, and complete the Transfer Request dialog.

Step Action

1. On the Change Set tab of the Package dialog, select the file to edit.

See “Creating a Package” on page 261 for accessing the package dialog.

Step Action

281

28


Freezing Files of a PackageAfter you modify the files in a package, promote the package to the frozen (FRZ) state. The frozen state creates a frozen release of all current projects (associated with the package).

After promoting a package to freeze, a Frozen Release node appears under the particular projects node. (It is not available when the package is in the DEV state.)

You can perform various actions on frozen releases as described in “Managing Releases” on page 203.

2. Click Tree.The File Tree dialog displays.For more information on the functions available on this dialog, see “File Tree UI” on page 400.

3. Select the file, then click .

The Transfer Parameters dialog displays showing where the files will be moved.

4. Complete the dialog as required, then click Transfer.The files are moved to the Development area.See “Completing the Transfer Request Dialog” on page 96 for information on the dialog.

5. Edit the files by doing one of the following:

• Select the file, then click .

Depending on your ChangeMan DS configurations, either the ChangeMan DS or the default editor for your local system appears to let you edit the file.

• Open the file from the development area through your develop-ment tool.

6. Check in the file, select the file, click , then complete the

Transfer Parameters dialog.

Step Action

2


Before you can create frozen release of the projects in the package, all files attached to the projects must be checked in.

Use the following procedure to freeze a package:

Viewing the History of a PackageThe promotion history of a package shows the status of a package in the development life cycle and what actions were performed on the package.

Step Action

1. Verify that all of the files are checked in to Production.

2. Promote the package to FRZ.See “Promoting a Package” on page 276.This creates a frozen release which can be accessed under the Frozen Release node. See “Frozen Release Node” on page 389.

283

28


To view history of the package:

Life Cycle States for PackagesYou view the status of a package either on the Life Cycle tab of the Package dialog or on the History of a Package dialog (see “Use the following procedure to freeze a package: Viewing the History of a Package” on page 283).

Step Action

1. With the Packages node selected under the appropriate application, select the package then click History.(This functionality is available only on the Web browser and Java clients. See “Accessing Package-Oriented Functionality” on page 247 for information on accessing the package node.)The History of a Package dialog displays.

The current state appears in a red box.The list shows the movement of the package from one state to another, who performed the movement (Executor) and when it was performed. Refer to “Life Cycle States for Packages” on page 284 for descriptions of the individual states.

2. Click Exit to close the dialog.

4


The lifecycle is a process in which:

• a series of states, and transitions between those states, is defined.

• specific activities occur at each state.

• specified promotions must be approved before they can occur.

• appropriate persons are notified when their approvals are required.

• a history of package promotions is maintained.

The default lifecycle of the package has the following states:

In this state… This has occurred…

DEV The package files are being developed. This is the only state in which development activities can occur on a package or its associated files.See “Editing Files in a Package” on page 279.

FRZ All projects and packages have been compiled, and are waiting to be approved. All modifications and code changes have been completed.A Frozen Release is created for any attached projects. The name of the release corresponds to the package name.See “Freezing Files of a Package” on page 282.

APR The package was approved, and is ready to be installed.It will install automatically according to Installation Date when it is promoted to the INS state.

INS The projects marked as deliverable have been moved to the targeted Installation areas.The promotion to the Install state triggers the scripts defined for the Installation area. See “Creating Scripts for Package Installation” on page 286 for more information.Also, two frozen releases are created with the following names:• <packagename>_<targetareaname>_PreInstall• <packagename>_<targetareaname>_PostInstallThese names should not exceed 255 characters.

285

28


Creating Scripts for Package InstallationUpon installation of a package, attached projects marked as deliverable are promoted automatically to Installation areas. This promotion occurs at the time specified in the Installation Date field for the package (see “Creating a Package” on page 261). You could create POA scripts that are invoked automatically during the promotion.

If necessary, you can create three types of POA scripts that will run when the package is installed:

• Pre-Installation Script commands are performed on the files before they transferred into the Installation Area. This script could be used to create temporary directories or stop the server.

BAS The life cycle is complete. This state is symbolic only. It allows packages linked with ChangeMan ZMF packages to be in the same state. Note that in contrast to ChangeMan ZMF, the changed files become baseline when they were checked in to the Production area. This occurs before promotion to the FRZ state in ChangeMan DS.

REJ The package was rejected.

DEL The package is marked for deletion.

IFL The package failed the automatic installation.The failed installation triggers the fail-installation script defined for the Installation area. See Fail Installation script in “Creating Scripts for Package Installation” on page 286 for more information.At this state, the following options are available:• Create a notification to inform team members of the installa-

tion failure. See “Creating a Notification” on page 312.• Promote the package back to APR to be re-scheduled for

install. See “Promoting a Package” on page 276.• Generate reports to show which packages failed the auto-

mated install. See “Viewing Installation History of a Package” on page 289.

In this state… This has occurred…

6


• Post-Installation Script commands are performed on the files after they transferred into the Installation Area. This script could be used to delete temporary files or restart the server.

• Fail-Installation Script commands are performed on the files only if the package failed to install. This script could be used to delete any partially installed files or send an e-mail to a non-ChangeMan DS user notifying of the failed installation.

The POA script runs under this user ID, and user ID must have permission to execute scripts. For Windows, the script will always run as the Communication Agent user. For UNIX, you must define an OS user id in the Script User field.

The environment variables available to this user ID are available from the script.

To add a script:

Step Action

1. Select an Installation area on the Areas tab of the Package dialog, and then click Script.The Scripts dialog displays. The type of script appears in the Preference field (Default, File, or Script). For Controlled File scripts, the file name appears in the field. For Manually Configured scripts, the script appears in the text box.

287

28


2. To add or alter a script, click on the Scripts dialog.

The EditScript dialog displays, on which you perform the following:

a) Define an operating system user id in the Script User field. The POA script runs under this OS user ID, and user ID must have permission to execute scripts on the host.

b) Choose one the following options:• Default Settings from Application Configuration, which

uses the script defined at the application level for that area. See “Creating a Default Area Configuration” on page 254 for view-ing and configuring the default scripts.

• Controlled File, which uses the specified file under Change-Man DS that contains the commands. (Using a file is the pre-ferred method because it lets you version control your scripts, and lets you test your scripts in the native operating system before running it from ChangeMan DS.)

• Manually Configuring Script, which uses the script specified in the text field.See “Scripting” in the Serena® ChangeMan® DS Administrator’s Guide for more information on writing scripts.

Optionally select Ignore Error to ignore scripts with errors and continue with the installation. If not set, scripts with errors will be taken into account and the package will fail installation.

c) Select Save to apply the changes, or Exit to close the dialog without applying the changes.

3. To delete a script, click on the Scripts dialog.

Step Action

8


Viewing Installation History of a PackageView the installation history of the package to find the installation log of the package.

Use the following procedure to view the Installation History:

Step Action

1. Select the Packages Node.This functionality is available only on the Web browser and Java clients.

2. Select a package in the content window, then click Ins. History.The Package Installation History dialog displays.

3. Select the appropriate tab:• Last Activity • Complete History

4. Select an entry, then click Details.The History Entry Details dialog displays the installation information.

5. Click Close to exit the dialog.

289

29


Searching for PackagesTo search for packages in the Web browser or Java clients:

Step Action

1.Click on the Web browser or Java client toolbar.

The Search Package dialog displays.

2.Optional

On the General tab, fill in any of the following fields:

This option… Searches for packages…

Package Name Like With a name that contains the entered information.

Package Title Like With a title that contains the entered information.

Package Description Like

With a description that contains the entered information.

Package CRN Like With a change request number that contains the entered information.

Company Associated with the selected company.

Requester Associated with the selected requestor.

3.Optional

On the Properties tab, select any of the following criteria:

This option… Searches for packages that are…

Type Assigned the selected type.

State Assigned the selected state.

Level Assigned the selected level.

4.Optional

On the Applications tab, select any listed application to search for packages attached to a specific application.

5.Optional

On the Creators tab, select one or more users to search for packages created under those names.

0


To clear the criteria and perform a new search, you must exit from the search dialog,

then click again.

6.Optional

On the Attached Projects, select a project to search for packages associated with it.

7.Optional

On the Attached Areas tab, enter any of the following criteria:

This option… Searches for…

Area in State Packages in areas that are in the selected state.

Area Packages associated with that area.

8.Optional

On the Date tab, set any of the following criteria:

This option… Searches for…

Date Created At Least Packages with a creation date of no earlier than the date entered.

Date Created At Most Packages with a creation date of no later than the date entered.

Installation Date At Least

Packages with an installation date of no earlier than the date entered.

Installation Date At Most

Packages with an installation date of no later than the date entered.

9. Click Search.The search returns packages that meet the selected criteria. If you entered multiple options for one criteria, then packages matching any of the selected criteria are listed.The packages found display in the lower portion of the window. See “Packages” on page 255 for information on the options available.

Step Action

291

29


Saving a Package SearchIf you perform the same search repeatedly, consider naming and saving the search. This allows you to initiate subsequent searches by selecting the search name from a list without re-entering all of the search criteria (the filter).

To save a search filter:

SETTING SECURITY PERMISSIONS FOR POAChangeMan DS comes with a selection of predefined security permissions for packages and applications.

Security can be set at any of the following levels:

• Application

• Individual application

• All packages in an application

Step Action

1.Click on the Web browser or Java client toolbar.

The Search Package form displays.

2.Click (adjacent to the Filters: field).

You are prompted for a name and description of the filter (the search criteria).

3. Type a name and description of the search, then click Save.The Search Package form displays.

4. Select the search criteria.Go to “Searching for Packages” on page 290 for instructions on selecting the search options.

5.After all options are specified, click .

The filter is saved.

2


• Individual packages

Whatever permissions are set at the application level are inherited by the other objects. The application object is set as a logical parent of all other objects.

Each permission can be set with one of the following types:

• Granted

• Denied

During security authorization configuration, an administrator can either grant or deny (but not both) a given permission to the specific user and/or group.

Besides object-level permissions, life cycle promotion permissions also can be specified. For instance, a user may be denied permission to promote a package to the deleted state.

When checking permissions for a user, ChangeMan DS determines the group membership for that user. If a user belongs to more than one group, then it is sufficient that at least one of those groups has GRANTED authorization for a permission to grant the access to the user.

For instance, if a user is granted access as a Developer and also as a R&D Manager, and if only R&D Managers are allowed to delete packages, then this user is allowed to delete packages (unless specifically denied permission to delete packages at the user level).

Individual user permissions override the group permissions. For example, a user with permission to create a package can perform this function even if the group that the user belongs to is denied this permission.

The types of security authorizations are:

• Default - no permissions are configured and everyone has full access (granted) to all of the ChangeMan DS package-oriented functionality (except for that explicitly restricted by a user role view and user license).

• Distinctive - permissions are explicitly set (granted or denied) for a user or group.

• Inclusive - permissions are set at a group level; they become inclusive for the members of this group.

• Inference - based on how a permission is already configured for the other users or groups. If all occurrences of a permission have been granted to some users or groups, then, by inference, this permission is denied to all other users or groups.

293

29


If all occurrences of a permission have been denied to some users or groups, then, by inference, this permission is granted to all other users or groups. If there is a mix of granted and denied occurrences of a permission, then the default rules apply.

!!Caution!! Because the default security settings allow full access to all package-oriented functionality, including setting security, the ChangeMan DS administrator should configure security permissions for all users.

Use the following procedure to configure security permissions. Note that although this procedure makes use of the right-click menus, the same functionality is generally available by using the Security button.

The status of denied or granted is added to the authorization list under the Access column of the Authorization Configuration form.

Step Action

1. Log in as an administrator.

2. Determine how security is to be administered:

a) To administer permissions for all applications and all packages, select Applications from the tree, right-click and select Default Application Security, then go to Step 3.

b) To administer permissions for an individual application, select the specific application from the tree, right-click and select Security, then go to Step 3.

c) To administer permissions for all packages, select Applications from the tree, right-click and select Default Package Security, then go to Step 3.

d) To administer permissions for an individual package, select the package from the tree, right-click and select Security, then go to Step 3.

3. The Security Permissions form displays with a list of the Permissions description in the left pane and the Authorization list displayed in the right pane.Click Default to accept the default permissions, or select an individual permission, then click Grant or Revoke as appropriate.

4


An administrator may either define default permissions, or set permissions for the specific instance of an object. For example, user permissions may be set to allow the user editing properties for all applications (default application security), or for a given application only. In the latter case, the administrator would choose the specific application from the tree view and set the security at that level.

APPROVALS IN POAAn Approval Process ties an Approval Group to a stage in the life cycle. The Approval Group comprises the approvers for an activity; they may be configured to approve in a predefined order. You can assign an Approval Group for each type of transaction during the package life cycle.

An Approval Group is made up of those users who are designated as approvers. When the approver is designated, an approval level is assigned. This allows use of a hierarchical approval scheme, in which all lower-level approvers must approve the transaction before approvals are requested from higher-level approvers.

You can also specify whether or not to send an e-mail to the group to notify them of approval activity, and the content of the e-mail.

When you designate an Approval Process, all approvers must give their approval before a package can be promoted to the next state.

The POA Approval Process is different than the sign-off process for transferring files between areas. See “Approving File Transfers” on page 237 for more information on the transfer sign off process.

Creating an Approval ProcessThe Approval Process controls:

• The state in the package life cycle where approvals are required before the package can move to the next state (except for deleting or reverting to the DEV state).

• The approval group that needs to make the approval.

You can create one or multiple Approval Processes at the application level in the package-oriented approach, and the processes will apply to all of the packages related to the application.

Note It is possible to implement requiring approval for file transfers without using the Package-Oriented approach. See “Approving File Transfers” on page 237 for more information.

295

29


Use this procedure to configure an approval process:

Approving PackagesWhen you promote a package to a state that has an Approval Process, an approval assignment is created for each approver in the Approval Group specified by the Approval Process. You can see the packages waiting for your approval under your Pending My Approval node.

Each member has to give approval before the package can be promoted to the next state. After all of the necessary members have given their approval, you manually promote the package to the next state.

Step Action

1. With the Applications node selected on the left, select a listed application, then click the Approval button.The Approval Processes form displays.This functionality is available only on the Web browser and Java clients.

2. Click Add.

3. Enter a name for the process in the Name field.Because approvals are attached only to packages, Object Code is configured to Package, and General Package is the only Life Cycle.

4. Select the state where the approval needs to occur before the package can be promoted to the next state.The Approved Next State and Rejected Next State are automatically filled in.See “Life Cycle States for Packages” on page 284 for information on states.

5. Either:• Select an Approval Group from the Approval Group drop-down list.

• Create a new approval group by clicking . See “Creating an

Approval Group in POA” on page 298 for instructions on creating a new group.

6. Click Save.

6


If any approver rejects the package, the rest of the approval assignments are cancelled. The package cannot be promoted (and may be demoted to some other state).

See “Approvals in POA” on page 295 and “Approval Node Toolbar Buttons” on page 391 for additional details.

Use this procedure to enter your approval:

The Approval assignment is promoted to the selected state. If the selected state is also an end state, the assignment is removed from the Pending My Approval view and added to the Finished Approvals view.

Step Action

1. Log in as an approver who receives an approval notification.This functionality is available only on the Web browser and Java clients.

2. Open the Approval node, then select Pending My Approval in the navigation tree.A list of the approval assignments displays in the right pane.

3. Select an assignment to be reviewed, then click Promote. The Approval Assignment Promotion screen displays.

4. Select the desired promotion state: • Approved - approves the package.• Rejected - rejects the package.• Cancel - cancels the package.• Review - in review (interim state).• CheckOff - in review for a lengthy period of time, which may

involve contacting the developers responsible for the changes (interim state).

5. Click Activate.

297

29


Creating an Approval Group in POATo create an approval group:

Adding and Removing Users from an Approval GroupWhen creating or editing an Approval Group:

• To add users or groups to an Approval Group, select users or groups from the Unassigned Users and Unassigned Groups tabs, then click Assign. The users and groups selected appear in the Approvers list.

• To remove an approver, select the name in the Approvers list, then click Remove.

After completing your modifications to the group, click Save to save the modifications, or click Exit to discard the changes.

Step Action

1. Select the Approval Groups node, then click New.The ApprovalGroup object displays.This functionality is available only on the Web browser and Java clients.

2. Type a name for the approval group in the Name field.

3. Add or remove members from the group.See “Adding and Removing Users from an Approval Group” on page 298.

4. Set the order that the approvers must follow.See “Setting the Approval Order for Packages” on page 299.

5.Optional

Specify a password to use either as an override password or as extra security for an approval.See “Specifying a Password for Approvals in POA” on page 299.

6. Configure notifications that can be sent at different approval states such as when approvals are pending for a user.See “Configuring Notifications for Approvals” on page 300.

7. Click Save to save the approval group, or Exit to cancel group creation.

8


Setting the Approval Order for PackagesYou set the order in which approvers sign off in an Approval Group.

To set the order for an Approval Group, either:

• Select an approver in the Approvers list on the Approval Group Properties dialog (displayed when creating or editing a group), then click to increase the approval position or click to decrease the approval position.

• Change the approval order in the Order field of the selected user on the Approvers Properties dialog. The Approver Properties dialog displays when you select an approver on the Approval Group Properties dialog, and click Properties.

The default approval position is 1 for all users and groups in the list.

Specifying a Password for Approvals in POAUse the approval passwords in one of two ways:

• Require that the specified approver must enter a password to make an approval (AND option)

• Allow anyone to enter a password to approve for a specified approver (OR option)

To specify a password:

Step Action

1. Open the Approval Group Properties dialog.To open this dialog, either create an Approval Group (“Creating an Approval Group in POA” on page 298), or select an existing group from the Approval Groups node, then click Edit.This functionality is available only on the Web browser and Java clients.

2. Select a name from the Approvers list, then click Properties.

3. In the Requires portion of the Approver Properties dialog, type the password in the Password field, and again in the Confirm field.

299

30


Configuring Notifications for ApprovalsYou can configure notifications to be sent for different states in the approval process. Notifications can be sent when:

• A user or group needs to sign off (Pending state)

• A user or group approved or rejected the request (Approved and Rejected states)

• A user or group asked that the change be reviewed (Review state)

• A user or group asked the change be checked off (Checkoff state)

You can configure notifications at the Approval Group or Approver Properties levels.

Approval Group NotificationsApproval Group Notifications apply to all members of the approval group.

For example: Your Approval Group has three members (User1, User2, and User3) who must sign off in a specific hierarchical order; it has an Approval Group Notification that is set for the Approved state. After User1 makes his approval, the notification is sent out. After User2 makes her approval, the notification is sent out again. Same for User3.

You can use default or custom Approval Group Notifications See the following sections:

• “Enabling Default Approval Group Notification” on page 301

• “Creating Custom Approval Group Notifications” on page 302

4. Set AND or OR as follows:

AND Set AND if you want the approval user to enter a password. If set on a group, only group members that know the password can approve the transaction.

OR Set OR if this user or anyone in the approval list who knows the password can approve the transaction. In this case, one approver can approve the transaction for another approver.

5. Click Save, then click Exit.

Step Action

0


Approver Properties NotificationsApprover Properties Notifications apply to only the selected member in the Approval Group.

For example: Your Approval Group has three members (User1, User2, and User3) who must sign off in a specific hierarchical order; User1 has an Approval Properties notification that is set for the Pending state. When it is time for User1 to make her approval, the notification is sent out. The Approver Properties notification won't apply for User2 or User3.

See “Configuring Approver Properties Notifications for POA” on page 303 and the accompanying “Example of Creating an Approval Group with Approver Notifications” on page 304.

Enabling Default Approval Group NotificationYou can send default Approval Group notifications to each member of the Approval Group. The default notifications apply to the Pending and Rejected states.

Pending notifications are sent to approvers when it is their turn to approve the transaction. Rejected notifications are sent if an approver rejects the approval request.

To enable the default notifications, click Default on the Approval Group Properties dialog.

Note To open the Approval Group Properties dialog, either create an Approval Group (“Creating an Approval Group in POA” on page 298), or select an existing group from the Approval Groups node, then click Edit.

If you created custom Approval Group notifications, enabling default Approval Group notifications overlays your custom messages. Your custom messages will be lost.

After enabling the Default messages, you can customize them as you would other Approval Group Notifications.

301

30


Creating Custom Approval Group NotificationsTo create custom Approval Group Notifications:

Step Action

1. Open the Approval Group Properties dialog.To open the Approval Group Properties dialog, either create an Approval Group (“Creating an Approval Group in POA” on page 298), or select an existing group from the Approval Groups node, then click Edit.This functionality is available only on the Web browser and Java clients.

2. Click G-Notify.

3. Select an approval notification state from the States drop-down list.The state is when the approval notification will be sent. For example, to send an e-mail notifying the manager that she needs to make an approval on this package, set the state to Pending.See “Configuring Notifications for Approvals” on page 300 for information on the different states.

4. Click Edit.The Notification dialog displays with the Name field filled in with information pertaining to the selected state.

5.Optional

Fill in the Description, Data Source, Default Subject, and Default Message fields if you want a default message to be sent to each person in the notification list.See “Creating a Notification” on page 312 for information on completing these fields.

2


Configuring Approver Properties Notifications for POAYou can configure notifications at the user or group level for members of an Approval Group. These notifications are sent out when a certain approval state is reached for that member.

See the “Example of Creating an Approval Group with Approver Notifications” on page 304 for an example of how you would configure an Approver Group with the Approver Properties notifications.

6. Add users or groups to the notification list by clicking New.Each user or group in the notification list will receive a notification e-mail.On the New dialog:

a) Select a user or group from the list on the left.The User/Group Type and User/Group ID fields are populated.You can also set the User/Group ID to a field in a data source, which means ChangeMan DS automatically populates the field with a dynamically generated user or group.See “Data Sources” on page 306 for more information.

b) To reference a different data source, select it from the drop-down menu.

c) To enter a custom Subject or Message for this particular user or group, complete the Mail portion of the screen.The entered subject and message overrides the subject and message entered on the Notification dialog, which allows you to use different Data Source fields in the Subject and Message fields for each entry on the notification list.

d) Click Save.

e) Repeat this step for each user or group to add to the Notification List.

7. Remove or edit users on the Notification List by using Delete and Edit.

8. Click Save to save your changes and Exit to close the Notification dialog.

9. Click Exit to complete the configuration.

Step Action

303

30


To configure an Approver Properties notification for a member of an Approval Group:

Example of Creating an Approval Group with Approver NotificationsThis example shows the steps to create an example Approval Group “AppGroup” that has two approvers, User1 and Group2. Approver Properties Notifications are configured for User1.

Step Action

1. On the Approval Group Properties dialog, select a member on the Approvers list and click Properties.To open the Approval Group Properties dialog, either create an Approval Group (“Creating an Approval Group in POA” on page 298), or select an existing group from the Approval Groups node, then click Edit.This functionality is available only on the Web browser and Java clients.

2. On the Approver Properties dialog, set the State to when you want the e-mail sent.For example, to send an e-mail to a manager when the member approves, set the state to Approved.See “Configuring Notifications for Approvals” on page 300 for information on the different states.

3. Click Edit.

4. On the Notification dialog under the Notification List, click New to add a notifier.

5. On the New dialog, select the user who will receive the notification and type your custom e-mail subject and message, then click Save.

See “Data Sources” on page 306 for more information about inserting dynamic variables into the e-mail.

6. Either:• Add more members to the Notification List by repeating steps 4 and

5.• Click Save on the Notification dialog. The configured notification

appears on the Approver Properties dialog.

7. Click Save to save the notification.

4


AppGroup contains the following specifications:

• User1 must approve first, and then Group2 can approve.

• User1 receives a notification when a package promotion needs his approval.

• Group2 receives a notification after User1 approves the package.

Step Action

1. Create an Approval Group named AppGroup.See “Creating an Approval Group in POA” on page 298.

2. On the Approval Group Properties dialog for AppGroup, add unassigned user User1 and unassigned group Group2 to the Approvers list by clicking Assign.

3. Select User1 in the Approvers list and click Properties.

4. On the Approver Properties dialog for User1, set the Order number to 1 making User1 the first person to approve.

5. Set the State to Pending and click Edit.


7. On the New dialog, select User1 to receive the notification and type your custom e-mail subject and message (saying “It is time for you to approve”), then click Save.See “Data Sources” on page 306 for more information on inserting dynamic variables into the e-mail.

8. Click Save on the Notification dialog.The configured notification now appears on the Approver Properties dialog for User1.

9. Click Save to save the first notification.

10. Again, select User1 in the Approvers list and click Properties.

11. Set the State to Approved, then click Edit.


305

30


DATA SOURCESData sources are used to dynamically insert the contents of fields into the notification message at the time it is being sent. The Data Source drop-down contains the list of related tables that can be used in the notification for the object.

You can reference the data source fields (viewed by clicking the Field button) to reference a data field in the notification. Specify the field name in a notification by using double angle brackets, thus: <<Field Name>>.

For example, to include the Category Name of the request in the body of the notification message, select data source CategoryName, then click Fields. The available field for this data source is Category. Reference this field in either the subject or the message section of the notification in this manner: <<Category>>.

When the server generates the notification, it replaces this parameter with the actual value of the category name. The server first determines if a field exists in the object's native list of properties. If it doesn’t, the server proceeds by checking items in the list of the object's data sources.

13. On the New dialog, select Group2 to receive the notification and type your custom e-mail subject and message (saying “User1 has approved the transaction it is your turn”), then click Save.

14. Click Save on the Notification dialog.The configured notification now appears on the Approver Properties dialog for User1.

15. Click Save.

16. On the Approval Group Properties dialog, select Group2, and set its order number to 2.

17. Click Save.The AppGroup is configured for notifications and approvals as described above.

Step Action

6


For user or group ID in the To field, use of data source may be of value. For instance, the Task Assignee name is usually not known in advance. Instead of creating a user or group from the list, the administrator can select a data source (for example TaskInfo data source for the Task object) and specify <<Assignee_id>> in the User/Group ID field. The message will then be sent to the current assignee. Similarly, the <<Originator_id>> field may be used to notify the request originator.

You can also limit the notification to a particular entry in a data source field by entering a boolean expression or SQL scripts in the Criteria field, where available.

A few examples:

• In an approval process, set the criteria to:

<<Application_id>>==31

This means that this approval process will be applied to all packages coming from applications with ID of 31. <<Application_id>> is a parameter, referencing Application_id field value of package object instance.

• In a notification, set the criteria to:

<<Checkoff>>==1 AND <<ApprovalGroupId>>==9

This means that among other notification processes, the one with the Checkoff parameter set and ApprovalGroupId parameter equal to 9.

Also, SQL EXISTS constructions are allowed:

EXISTS(SELECT AppAreas.id idFROM AppAreas INNER JOIN vcs01 ON AppAreas.AreaName = vcs01.area_id WHERE AppAreas.AppId=<<Application_id>> AND vcs01.area_type='t' AND AppAreas.StateObjId = 0UNIONSELECT AppAreas.id idFROM AppAreas INNER JOIN vcs01 ON AppAreas.AreaName = vcs01.area_id WHERE AppAreas.AppId=<<Application_id>> AND vcs01.area_type='d' AND AppAreas.StateObjId = 0

)AND EXISTS(SELECT AppComponents.id idFROM AppComponents

307

30


INNER JOIN vcs09 ON AppComponents.ProjectName = vcs09.proj_id INNER JOIN PackageComponents ON AppComponents.id =PackageComponents.AppComponentsIdWHERE AppComponents.AppId=<<Application_id>> AND PackageComponents.PackageId=<<id>>)

This condition is for a trigger that performs configuration of an area list for a package. The first EXISTS statement checks if an area configuration exists for the parent application (looking particularly for Development and QA area types); the second EXISTS checks if a project configuration exists for the parent application.

If both of these are TRUE (EXISTS statement results in boolean value), trigger will fire; otherwise, it will not.

Approval Data SourcesThe data sources available in the approval configuration contain the following information:

• CurrentApprover Data Source

• CurrentGroupApprovers Data Source

• FormCode Data Source

• Package Data Source

• Activity/Event Drop-Down List for Notifications

CurrentApprover Data SourceThe CurrentApprover data source provides information on current approver. That information includes:

This field… Contains this information…

id ApprovalAssignment unique ID

ApprovalProcessId ApprovalProcess unique ID

ApproverId Approver unique ID

InstanceId Associated object instance unique ID

DateLastOperation Date/time when the current ApprovalAssignment was last promoted.

8


CurrentGroupApprovers Data SourceThe CurrentGroupApprovers data source provides a list of all approvers in the current Approver's group. That information includes:

FormCode Data SourceUnused. The FormCode data source retrieves a form code that is configured for an associated object instance.

ObjectCode Data SourceThe ObjectCode data source retrieves ApprovalProcess information for the current approval. That information includes:

Information Comments/Checkoff List/Reject Reason for the current ApprovalAssignment

UserGroupType 0 for users; 1 for groups. Defines current Approver entity type

UserGroupId User or Group ID of current Approver entity. Depending on UserGroupType, points to UserSys or GroupUser table.

ApprovalGroupId ApprovalGroup unique ID.


UserGroupType Defines type of the entry.

UserGroupId Reference to UserSys or GroupUser table, depending on UserGroupType value.


id ApprovalProcess unique ID

ApprovalGroupId Associated Approval Group unique ID

ApprovedActivityName Name of activity that will be executed when approval succeeds


309

31


Package Data SourceThe package data source contains information on an associated package. That information includes:

LifeCycleCode Code of a life cycle that has this approval process.

Name Name of approval process

ObjectCode Associated object code

RejectedActivityName Name of activity that will be executed if approval fails

StateName Name of a state that has this approval process

Priority Priority of this approval process

Criteria Criteria for this approval process


PackageId Package unique ID

id Package unique ID

Application_id Application unique ID

Creator ID of user who created the package

CRN Change request number

DateApproved Date/time of last promotion to APR state

DateBackedout Date/time of last promotion to BAK state

DateBaselined Date/time of last promotion to BAS state

DateCreated Date/time created

DateDeleted Date/time of last promotion to DEL state

DateFrozen Date/time of last promotion to FRZ state

DateInstalled Date/time of last promotion to INS state


0


NOTIFICATIONSChangeMan DS lets you create e-mail notifications that occur based on activities of packages. Notification is usually desired when a specified event occurs in a life cycle, such as when a package is promoted from one state to another. Notifications can be configured to be sent for each activity for each state.

You can create mutiple notifications for each event. All notification with same priority and satisfied criteria are sent for the event.

See “Activity/Event Drop-Down List for Notifications” on page 314 for information on each activity and “Life Cycle States for Packages” on page 284 for information on the states.

The notification recipients (users or groups) and the content of the notifications are configurable.

DateRejected Date/time of last promotion to REJ state

DateReverted Date/time last time reverted to DEV

InstallationDate Planned installation date

Name Name of package

State Current state of the package

Title Package title

Type Package type

Requester Person who requested creation of this package

Description Package description


311

31


Creating a NotificationUse this procedure to create a notification:

Step Action

1. Select the Notification Configuration node, then click New.The ApprovalGroup object displays.This functionality is available only on the Web browser and Java clients.

2. Enter a Name for the notification.

3. Enter a Description.

4. In ChangeMan DS, Package (Package Entity) is the only option in the Object drop-down list.

5. In ChangeMan DS, General Package is the only option in the Life Cycle drop-down list.

6. Select a State. See “Life Cycle States for Packages” on page 284 for more information.

7. Select an Activity/Event. See “Activity/Event Drop-Down List for Notifications” on page 314 for more information.

8. Select a Data Source if desired. See “Notification Data Source” on page 314 for more information.

9. Optional. Click Fields to see a list of the data source fields if you want to use the contents of one or more fields in your notification. See “Data Sources” on page 306 for more information.Click Exit to continue.

10. Enter any Criteria to narrow the notification to specific elements based on the data source fields.See “Data Sources” on page 306 for more information.

Click to check the criteria syntax.

11. Set the Priority

2


12. Fill in Default Subject and Default Message text areas.These are the subject line and message that will be used (unless overwritten for a specific user or group).To have information in the subject line or message body to be filled in dynamically, you can use a data source field here. See “Data Sources” on page 306 for more information.

13. Add users to the Notification List:The following buttons are used to create and maintain the notification list:• Click Add to add new users to the notification list.• Click Edit to edit an existing, selected user’s notification settings.• Click Delete to remove a selected user from the notification list.Click Save to create a new notification list. The NotificationList object displays.

To add a user or group:

a) Select a user or group from the list on the left.The User/Group Type and User/Group ID fields are populated.You can also set the User/Group ID to a field in a data source. See “Data Sources” on page 306 for more information.

b) To reference a different data source, select it from the drop-down menu.

c) To enter a custom message for this particular user or group, complete the Mail portion of the screen.

d) Click Save.

e) Repeat for each user or group you want to add.

14. Click Exit to save the notification.Because the changes you make to the notification list immediately update the notification, you do not need to click save before you exit. If you modify any other field after adding users to the list, you must click Save.

Step Action

313

31


Activity/Event Drop-Down List for NotificationsThe Activity/Event drop-down list contains the life cycle components for a state for which the notifications can be configured. The available activities and events are as follows:

Notification Data SourceThe Data Source drop-down lists data sources available for an object. Each data source contains a list of related data fields for the object to be used in the notification.

See “Data Sources” on page 306 for more information on data sources.

This Activity/Event… Sends notification when the package…

Activate: Approved approval is initiated.

Activate: Rejected rejection is initiated.

Activate: To DEL deletion marking is initiated.

Activate: To INS installation on remote sites is initiated.

Activate: To REJ rejection is initiated.

Done: Approved is approved.

Done: Rejected is rejected.

Done: To DEL is marked for deletion.

Done: To INS is installed on the remote sites specified in the change package.

Done: To REJ is rejected.

Event: on State Enter enters a state.

Event: on State Exit leaves a state.

Transition APR-DEL is promoted from APR to DEL.

Transition APR-INS is promoted from APR to INS.

Transition APR-REJ is promoted from APR to REJ.

4


The available data sources are:

Data source and Description Field Field Description

AllAppQuery list of all applications in the system.

id Application unique ID

Name Application name

AllLevelsRetrieve list of all possible package levels.

id Numeric level identifier

Name Symbolic level identifier

AllStatesRetrieve all states of General Package life cycle.

Name1 Name of state

Name2 A copy of Name1 value

AllTypesRetrieve list of all possible package types.

id Numeric type identifier

Name Symbolic type identifier

AllUsersQuery list of all users in the system.

id User unique ID

Name Username + user full name

AllUsersGroupsQuery list of all users and groups in the system.

Type 0 for users and 1 for groups

id A unique ID in the UserSys or GroupUser table

Name Name corresponding the entity (either username + user full name or group name)

Image A database-stored image representing the entity

ApplicationNameRetrieve application name for current package.


315

31


AttachedAreasRetrieve list of configured areas for the package.

id Unique ID of packageareas record

AppId Application unique Id

AreaName Area name

WorkDir Work directory (in area)

ProjectName Project name

AttachedAttachmentsRetrieve list of configured projects for the package.

id Unique ID of PackageComponents record

AppId Application unique ID


AllAppQuery list of all applications in the system.

id Application unique ID


AllLevelsRetrieve list of all possible package levels.

id Numeric level identifier

Name Symbolic level identifier

AllStatesRetrieve all states of General Package life cycle.

Name1 Name of state

Name2 A copy of Name1 value

AllTypesRetrieve list of all possible package types.

id Numeric type identifier

Name Symbolic type identifier

AllUsersQuery list of all users in the system.

id User unique ID

Name Username + user full name


6


AllUsersGroupsQuery list of all users and groups in the system.

Type 0 for users and 1 for groups

id A unique ID in UserSys or GroupUser table

Name Name corresponding the entity (either username + user full name or group name)

Image A database-stored image representing the entity

ApplicationNameRetrieve application name for current package.


AttachedAreasRetrieve list of configured areas for the package.

id Unique ID of PackageAreas record

AppId Application unique Id

AreaName Area name

WorkDir Work directory (in area)


AttachedAttachmentsRetrieve list of configured projects for the package.

id Unique ID of PackageComponents record

AppId Application unique ID



317

31


AttachedeCMfilesRetrieve “change set” for the package.

id Unique ID of eCM_Package_Files record

eCM_File File name

eCM_Area Area name

eCM_Path Path

RelativePath Relative path

eCM_Version Version number

Assignment_id Assignment ID

eCM_Project Project name

SCC_Provider String: “eChangeMan”

CompanyNameRetrieve package requester's company.

id Company unique ID

Name Company name

CurrentUserIDRetrieve information on logged in user.

id UserSys unique ID

Username User name

FullName User full name


8


DefaultConfigRetrieve default area configuration for an application.

State Associated state name

Type Area type

Area Area name

Description Area description

Path Work path (in area path)

Host Area host

OSName Area host OS

AppAreasId AppAreas unique ID

StateObjId State_of_object unique ID

DeletePackageApprovalAssignmentRetrieve list of existing ApprovalAssignment records associated with the package.

id ApprovalAssignment unique ID

DeletePackageeCMFilesRetrieve “change set” for the package.

id eCM_Package_Files unique ID

eCMArea Area name

eCMFile File name

eCMPath Path in area

eCMProject Project name

eCMVersion Version number

Package_id Package unique ID

SCCPath Relative path in project

SCCProvider String: “eChangeMan”


319

32


DeletePackageSecRetrieve list of configured security permissions for the package (non-inherited).

UserGroupTypeName User, group, or unknown

UserGroupIdName Username and user full name or group name

AccessType Denied, Granted, or Inherited

id SecTwoAuth unique ID

PermissionName SecTwoPerm name

Description SecTwoPerm description

Image Granted or denied status image

EmptyDateGet null value of smalldatetime type.

EmptyDate Null value of smalldatetime type

ListGroupsQuery list of all groups in the system.

(fields from GroupUser table - group profile)

ListUsersQuery list of all users in the system.

(fields from UserSys table - user profile)

PackageAreasForProjectQuery list of IDs of configured areas for the package.

id PackageAreas unique ID

PkgPermissionsQuery list of applicable permissions for packages.

id Permission unique ID

Name Permission name

Description Permission description


0


StateAppRetrieve list of states for object Package.

id Unique ID of life cycle state

Name Name of life cycle state

Description Description of life cycle state

UnattachedApplicationAreasUnused; at the time, returns list of all applications.

Not applicable

UnattachedApplicationAttachmentsGet list of components (projects) that are still not attached to the package (available for attach operation).

id AppComponents unique ID

AppId Application unique ID (should be same for all records in the result)



321

32


2

HOST VIEW 1
7 ChangeMan DS Host View provides a GUI-based file manager for UNIX platforms.
ChangeMan DS uses client/server technology and the Microsoft Windows GUI to simultaneously display the accounting structure of multiple hosts. You can use the drag-and-drop, point-and-click interface to copy, delete, and edit file sets on any host supported by ChangeMan DS, and you can change the file and directory properties.

Finally, you can perform all of the preceding operations from any workstation without having to issue an operating system command. This feature helps you to manage heterogeneous hosts, and shorten the learning curve in the multi-platform development environment.

This chapter describes how to:

• Navigate in the displayed data structures.

• Manage heterogeneous hosts.

Refer to “OS/400 Environments” on page 331 for details on this platform.

INFORMATION DISPLAYED IN HOST VIEWThe Host View module allows users who are familiar with Windows procedures to view the account structure of heterogeneous hosts.

To see the host data, click on the plus sign next to a node, or double-click on the column header.

ChangeMan DS displays the data for the corresponding host in the column format on the right side of the screen.

To customize Host View, you can perform the following operations:

• Change the sort order by clicking on the column header.

• Move a data column to another position.

• Change the width of a data column.

• Right-click on the column header to select the data displayed.

323

32

Chapter 17: Host View

Information displayed in the Host View depends on the host’s operating system.

Viewing the List of Commands Available on the File LevelTo view a list of commands available for a file, select a file and right-click.

Exploring a UNIX Host

Step Action

1. Expand the node for the host to be opened.When you expand the UNIX host node, ChangeMan DS displays the following registration dialog box.

2. Enter the necessary login information.The left section of the screen displays the directory structure.

3. Double-click the directory folder to view the files.

4


For the UNIX operating system, ChangeMan DS provides the following file level information:

• Status (the status icon indicates a binary file).

• File name

• File type

• File size

• Date and time of last modification

• Owner

• Group

• Links

• Attributes

Host View displays only those directories and files that you are allowed to view and manage, based on the security permissions of the logged on user. For example, if you are logged in as root, you can view and manage all files and directories on this host.

CONFIGURING THE HOST VIEWTo configure Host View, select the Host View tab in the lower-left of the main ChangeMan DS screen.

The Host View module is independent of the other SCM components offered in ChangeMan DS. Even though you may have added areas for hosts in ExplorerView, Host View does not know about them. You will need to use the Add Host option to add the host to the Host View, then you can expand the directories (UNIX) for the host.

325

32


Adding a HostAll users must configure the list of hosts to be accessed from their workstations. Because ChangeMan DS saves the host information in the local configuration files, this procedure is performed only once.

The node representing a host appears on the left side of the Host View screen. There are node icons for each operating system type.

The node is only a pointer. The connection is only established when you try to access that host and is disconnected when it is not used.

Step Action

1.Click from the Hosts toolbar.

ChangeMan DS displays the following dialog box.

2. Enter the host name or IP address.

3. Repeat this operation for all hosts to be added to the Host View module.

Node Icon Operating System

Windows

UNIX

6


Removing a Host

MANAGING HETEROGENEOUS HOSTSWhen working with heterogeneous hosts, there are three primary concerns:

• Managing Properties for Files and Directories. The ChangeMan DS Host View module lets you manage individual files, directories, groups, and accounts according to your registration information.

• Managing File Locations. Use ChangeMan DS to control all of your networked computers from a single screen.

• Viewing and Editing Files in the Host View. ChangeMan DS provides you with a powerful programming editor to view or edit the content of any file on any host.

MANAGING PROPERTIES FOR FILES AND DIRECTORIES

The Host View module lets you manage individual files, directories or groups, and accounts according to your registration information.

The following procedures describe how to manage file properties on various hosts without issuing any operating systems commands.

The set of file properties varies, depending on the operating system used on the host.

For UNIX systems, see the following topics:

• Managing File Properties on a UNIX Host

• Modifying Directory Properties on the UNIX Host

Step Action

1. Select the host node to delete from Host View.

2.Click Remove Hosts .

ChangeMan DS removes the selected host from the screen.

327

32


Managing File Properties on a UNIX Host

Step Action

1. Expand the host node.

2. Select the file whose properties are to be modified.

3.Click from the Host toolbar, or right-click and choose Properties from the right-click menu. The following dialog displays:

You can modify the following parameters:• File name• Security attributes• Owner• Group

4. Modify as required, then click Apply to employ the new file properties.

8


Modifying Directory Properties on the UNIX Host

Step Action

1. Expand the host node.

2. Select the file whose properties are to be modified.

3.Click from the Host toolbar, or right-click and choose Properties from the right-click menu.

4. Modify as required, then click Apply.

329

33


0

OS/400 Environments 1
8 The AS/400® Communication Agent increases the ease of use of the AS/400 (also know as eServer iSeries™) Application Servers for developers. ChangeMan DS users can drag and drop files between different AS/400 computers and non-AS/400 file systems (such as Windows NT and UNIX workstations) on their network.
See “Host View” on page 323 for additional information on managing files.

Programmers can develop programs on the PC using their preferred graphical development environments. The programmer can then drag files or transfer them using CMDS transfer into the development environment of the AS/400.

For information on starting the AS/400 Communication Agent, see the Serena® ChangeMan® DS Administrator’s Guide.

USING THE AS/400 COMMUNICATION AGENTWhen connecting to an AS/400 system with a ChangeMan DS Client, there are a few things you should know:

• There is no 5250 keyboard functionality in ChangeMan DS.

• Areas created in ChangeMan DS reside in the EBCDIC side and are assigned to libraries. Paths to these areas are displayed as UNIX paths in ChangeMan DS.

• The directory structure for areas is as follows:

— Name.lib displays as an area subdirectory in the /QSYS.LIB directory.

— Name.pgm is an item in the area subdirectory.

— Name.file is a subdirectory of Name.lib.

— Name.file (save file) is an item in the subdirectory

— Name.mbr is an item in subdirectory name.file.

With the communication agent on the AS/400, you can perform the following:

• Make Behaviors for AS/400

• Transfers in AS/400

331

33

Chapter 18: OS/400 Environments

• Scripting Behavior for the AS/400

MAKE BEHAVIORS FOR AS/400ChangeMan DS supports the following make behaviors for the AS/400:

Make One• Transfer members or file from the Production area to the assembly path

(from *.LIB/* .FILE/ *.MBR to *.LIB/* .FILE/ *.MBRor from /dir/folder/file to *.LIB/* .FILE/ *.MBR)

• Creation of CL , C , RPG modules in the assembly path

• Creation of *.PGM from CL, C, or RPG modules

• Transfer of *.PGM to target area on any system

• Output information about the make process

Restrictions• AS/400 file names cannot begin with a number. This is an AS/400 System

restriction.

• If the scripts are called from a non-AS/400 system and are using files from the AS/400 system, they will not work as the files in AS/400 system cannot begin with numbers.

• If the Scripts are run in the "/QSYS.LIB" File System, they cannot start with numbers. In AS/400 the first character should be alphabetic. If they are run in a UNIX file system, then script file name can start with any alpha-numeric character.

• The area and archive area paths for the target area must point to a LIB.

For example: /QSYS.LIB/name.LIB

• The archive area path for any Production area should point to a directory in the root file system.

• The area and archive area paths for dependencies must point to a .FILE.

For example: /QSYS.LIB/name.LIB/name.FILE

• The assembly path must point to a .FILE.

For example: /QSYS.LIB/name.LIB/name.FILE

• The build directory for the target must be ../.

2


• The area must be saved with a leading slash. The area and archive area paths must be configured with the fully-qualified path name.

For example, /QSYS.LIB/EXAMPLE.LIB.

TroubleshootingIf the script or make output file consists of non-ASCII characters, manually change the parameters of CODEPAGE and CCSID in the /serena/vcs_serv.cfg file.

TRANSFERS IN AS/400ChangeMan DS supports any object transfer on OS/400 systems, such as:

• Files from root file system to QSYS.LIB file system.

Any file (<name>.<ext>) that is targeted into /QSYS.LIB/<name>.LIB/<name>.File/ is treated as a text file; ChangeMan DS attempts to convert it to a source physical file member and store it in the target path.

For example:

Check out file: /ProdDir/MyTest.txtTo: /QSYS.LIB/MYLIB.LIB/MYFILE.FILE/Results: /QSYS.LIB/MYLIB.LIB/MYFILE.FILE/MyTest.MBR

ChangeMan DS attempts to store any file (<name>.<ext>) that is targeted into /QSYS.LIB/<name>.LIB/ according to QSYS.LIB file system rules, recognizing the QSYS.LIB object type by the <ext>.

For example:

Check out file: /ProdDir/Mytest.PGMTo: /QSYS.LIB/MYLIB.LIB/Results: /QSYS.LIB/MYLIB.LIB/MYTEST.PGM

Another example:

Check out file: /ProdDir/MyTest.MBRTo: /QSYS.LIB/MYLIB.LIB/Results: Fail

• Objects or files from QSYS.LIB file system to root file system.

Any object (<OBJNAME>.<OBJTYPE>) targeted into the root file system is treated as is, and ChangeMan DS stores it in the original format.

Transfers for the following object types are supported:*MBR, *PGM, *SRVPGM, *MODULE, *FILE (SAVFILE), and *CMD

333

33


• From a QSYS.LIB file system to a QSYS.LIB file system according to QSYS.LIB file system rules

• From a root file system to a root file system (any files or objects with any extension)

• Objects with other object types for a QSYS.LIB File System. (You need to clear the SERENAWRK.LIB)

SCRIPTING BEHAVIOR FOR THE AS/400ChangeMan DS supports the following script behavior on OS/400 systems:

• Automatic determination of the script’s environment.

— CL commands execute in the “/QSYS.LIB” file system.

See “/QSYS.LIB File System Script Examples for AS/400” on page 335 for examples.

— UNIX commands execute in the root file system.

See “Root File Script Examples for AS/400” on page 335 for examples.

• You can force the "/QSYS.LIB" File System environment by using #!AS400-EBCDIC as the first string of the script. See “Root File Script Examples for AS/400” for an example.

• Use of ChangeMan DS environmental variables.

See “VCS Variables for AS/400” on page 338.

Restrictions:

• AS/400 file names cannot begin with a number. This is an AS/400 system restriction.

• If the scripts are called from a non-AS/400 system and are using files from the AS/400 system, they will not work as the files in AS/400 system cannot begin with numbers.

• If the scripts are run in "/QSYS.LIB" File System, they cannot start with numbers. In AS/400 the first character should be alphabetic. If they are run in the Root File System, then script file name can start with any alpha-numeric character.

• Although you initiate the script from the ChangeMan DS side; you can verify it only from the AS/400 client or an IBM terminal.

4


SCRIPTING EXAMPLES FOR AS/400These examples show how ChangeMan DS can initiate execution of a script in either UNIX or native (EBCDIC) mode.

Note: Although you initiate the script from the ChangeMan DS side; you can verify it only from the AS/400 client or IBM terminal.

Root File Script Examples for AS/400

• Copying a File Between Directories on Root File System

• Forcing Native Area Script Execution

/QSYS.LIB File System Script Examples for AS/400

• Copying a File Between Directories in "/QSYS.LIB" Systemt

• Compiling a Member in "/QSYS.LIB" System

• Distributing a Member in "/QSYS.LIB" System

• Sending a Message in "/QSYS.LIB" System

Copying a File Between Directories in "/QSYS.LIB" SystemNote If a “/QSYS.LIB file system” exists on the host and area path name

begins with “/QSYS.LIB," ChangeMan DS treats the area as “/QSYS.LIB” or “native," which means executing CL commands as script. The following area is treated as “/QSYS.LIB”:

Area : AS_NATIVE_PROD

Path : /QSYS.LIB/AS_PROD.LIB

The following examples copy files with “/QSYS.LIB” File System script execution (CL commands) on AS400:

• To copy source physical file member MYMEMBER.MBR from directory /QSYS.LIB/AS_PROD.LIB/QCLSRC.FILE to directory /YourHome, use the script:CPYTOSTMF +FROMMBR(‘’/QSYS.LIB/AS_PROD.LIB/QCLSRC.FILE/MYMEMBER.MBR’’) +TOSTMF(‘’/YourHome/ MYMEMBER.MBR’’) STMFOPT(*REPLACE)

• To copy a checked in source physical file member from /QSYS.LIB/AS_PROD.LIB/QCLSRC.FILE to directory /YourHome, use the script:CPYTOSTMF +FROMMBR(‘’/QSYS.LIB/AS_PROD.LIB/QCLSRC.FILE/&vcsfile’’) +

335

33


TOSTMF(‘’/YourHome/&vcsfile’’) STMFOPT(*REPLACE)

• To copy checked in source physical file member from /QSYS.LIB/AS_PROD.LIB/QCLSRC.FILE to directory /QSYS.LIB/AS_DEV_LIB.LIB/TEST.FILE, use the script:CPYF FROMFILE(AS_PROD / QCLSRC) TOFILE(AS_DEV_LIB/TEST)

FROMMBR(&vcsfile_pr) +TOMBR(&vcsfile_pr) MBROPT(*REPLACE) FMTOPT(*NOCHK)

Note vcsfile and vcsfile_pr are ChangeMan DS VCS variables. See “VCS Variables for AS/400” on page 338 for more information.

Compiling a Member in "/QSYS.LIB" SystemNote If a “/QSYS.LIB file system” exists on the host and area path name




1. To compile a checked in source physical file member with "/QSYS.LIB" File System script execution (CL commands) on an AS/400: CRTCLMOD MODULE(AS_DEV_LIB/&vcsfile_pr) SRCFILE(AS_DEV_LIB/TEST) +SRCMBR(&vcsfile_pr) OUTPUT(*PRINT) OPTION(*XREF)

Note vcsfile_pr ia a ChangeMan DS VCS variables. See “VCS Variables for AS/400” on page 338 for more information.

Distributing a Member in "/QSYS.LIB" SystemNote If a “/QSYS.LIB file system” exists on the host and area path name




The following example distributes a checked in source physical file member with "/QSYS.LIB" File System script execution (CL commands) on AS/400:

CALL QP2SHELL +

6


(‘’/serena/dcm’’ ‘’-r’’ ‘’-h:172.20.103.29’’ ‘’-f:$vcsfile’’ ‘’-p:test’’ ‘’-u:Andrew’’ +

‘’-ta:QA’’ ‘’-tp:/QSYS.LIB/QA.LIB/TEST.FILE’’ +‘’-fa: AS_NATIVE_PROD’’ ‘’-fp: /QSYS.LIB/AS_PROD.LIB/MYFILE.FILE’’)

Sending a Message in "/QSYS.LIB" SystemNote If a “/QSYS.LIB file system” exists on the host and area path name




If the target area is on the "/QSYS.LIB" File System, use this test script:

sndmsg msg(TEST) tousr(username)

To check script execution at an AS/400 terminal, type the following:

WRKMSG MSGQ(SERENA/*ALL)

Copying a File Between Directories on Root File SystemThese AS/400 scripts will copy a file between directories when you are executing commands on the Root File System.'

• To copy a text file, readme.txt, from the directory /MyDirectory to the directory /YourHome, use the script:

cp /MyDirectory /readme.txt /YourHome

• To copy a checked in file from the directory /MyDirectory to the directory /YourHome, use the script:

cp /MyDirectory/$vcsfile /YourHome

Forcing Native Area Script ExecutionYou can force "/QSYS.LIB" File System script execution on a area when the area path name does not begin with the “/QSYS.LIB” but there is “/QSYS.LIB file system” on the host.

Area : ASProd

Path : /MyDirectory

337

33


To copy a source physical file member MYMEMBER.MBR from directory /QSYS.LIB/MYLIB.LIB/QCLSRC.FILE to directory /QSYS.LIB/YOURLIB.LIB/QCLSRC.FILE, the script is:

#!AS400-EBCDICCPYF FROMFILE(MYLIB/ QCLSRC) TOFILE(YOURLIB/ QCLSRC) +FROMMBR(MYMEMBER) TOMBR(MYMEMBER) MBROPT(*REPLACE)

VCS VARIABLES FOR AS/400The following table describes control variables provided by ChangeMan DS that can be used in Implementation and POA scripts. See "Scripting" in the Serena® ChangeMan® DS Administrator’s Guide for more information.

Note These variables cannot be used in a batch file unless the batch file is called within a script.

In the following table, IS signifies the variable can be used with Implementation Scripts, and POA signifies the variable can be used with POA scripts.

Root File System (Unix)

/QSYS.LIB file system (Native)

Description

from_dir(IS, POA)

from_dir(IS, POA)

Path of the directory from which the file is being transferred.

from_id(IS, POA)

from_id(IS, POA)

Name of the ChangeMan DS area from which the file is being transferred.

home_id(IS, POA)

home_id(IS, POA)

Name of the ChangeMan DS Production area for the file being transferred.

main_node(IS, POA)

main_node(IS, POA)

Host name where the ChangeMan DS Main Server is installed.

projinprod projinprod Equals 1 if all of the project components (files) are currently in Production.

projlocation projlocation Project’s current location (area name).

to_dir(IS, POA)

to_dir(IS, POA)

Path of the target directory to which the file is being transferred.

8


to_id(IS, POA)

to_id(IS, POA)

Name of the ChangeMan DS area to which the file is being transferred.

vcsdescription(IS)

vcsdescription(IS)

Contains the description from the transfer request up to the first new line break.

vcsfile(IS)

vcsfile(IS)

Contains the file name currently transferred by ChangeMan DS; for example, pay100.exe.

vcsfile_prefix(IS)

vcsfile_pr(IS)

Portion of the file name, which appears to the left of the period; for example, pay100.

vcsfile_suffix(IS)

vcsfile_su(IS)

Contains the period and the portion of the file name which appears to the right of the period; for example, .exe.

vcsproject(IS, POA)

vcsproject(IS, POA)

Name of the project being transferred.Available only when projects are being transferred.

vcstime(IS)

vcstime(IS)

Date and time of the file being transferred.

vcsuser(IS, POA)

vcsuser(IS, POA)

Name of the user who originated the file transfer process.

vcsversion(IS)

vcsversion(IS)

Version number associated with the file transfer process.

Root File System (Unix)

/QSYS.LIB file system (Native)

Description

339

34


0

TROUBLESHOOTING
A As with any software program, you may encounter problems while installing or using ChangeMan DS. This appendix provides common solutions to these problems and a general framework for troubleshooting. Troubleshooting questions and answers are divided into the following categories:
• Installation

• Determining Software Versions

• Web Browser Client

INSTALLATIONWhen I launch setup.exe, why doesn’t anything happen?

On Windows, the database is created with Java. The Java portion of the install requires the following display properties on the machine that is running the installation:

— More than 16 colors

— Resolution of 800x600 or better

When installing the ChangeMan DS Main Server, make sure you have the necessary video settings before you start. The proper video settings may require the installation of a new display driver.

When installing on UNIX, why does the root /directory fill up and the log file state that I’m out of space?

Java assumes the user’s home directory as the place to extract .jar files. Since Serena ChangeMan requires root for installation, the default home for root is /. If there is not enough room to extract .jar files in this directory, you will receive this message. Check the system requirements in the Serena® ChangeMan® Installation Guide for the amount of space recommended for .jar extraction.

To change the location where .jar files are extracted, edit the setup.sh file to read:

java -Duser.home=/tmp -jar setup.jar

341

34

Appendix A: Troubleshooting

where /tmp is the directory used for temporarily unzipping .jar files.

Why can’t I restart vcs_serv after rebooting the system?

If you installed ChangeMan DS on a UNIX system, you will need to run start.sh anytime the server is rebooted to set the environmental variables and start the necessary ChangeMan DS processes.

Note This is required only if the .profile for root is not altered to include the environmental variables from openlink.sh. If the .profile was changed, running the start.sh will remove the settings and also cause problems with the server.

Why did the VCS Server fail to restart after the system was rebooted?

The database must be running before the ChangeMan DS services connect to it. If using Microsoft SQL Server, you may need to set the SQLConnectTimeout option in the vcs_serv.ins file to allow enough time for the database to start up.

Other possibilities include:

— the environmental variables for TEMP and TMP changed

— the password for the user ID running the process changed

— the password for the user ID used to connect to the database changed

If you are given this response, the exact error message should display in the Event Viewer or in a dialog for this problem.

Can I manually stop my UNIX Main Server?

Why did I get the error message "CREATE UNIQUE INDEX terminated because a duplicate key was found for index ID2. Most significant primary key is....." ?

Your database management system was not set to be case sensitive. Most likely you have a Microsoft SQL Server. We recommend that you re-install your Microsoft SQL Server software. During the installation, be sure to choose Custom settings, and in the Collation Settings window, select the option “Dictionary order, case-sensitive, for use with 1252 Character Set.”

Why can’t I connect to the default port? I get the error Can’t open a socket on <server_name>:<port_number>. Check host and port number and make sure the security manager allows this connection. You can also try running the SocketApplet...?

This error message appears if you are using Microsoft SQL Server 2000. Your server and client must use the same port. To fix this problem:

2


a) Start SQL Server Enterprise Manager. Right-click on your server’s icon and select Properties. Click the Network Configuration button. The SQL Server Network Utility dialog appears.

b) In the Enabled Protocols list box, select TCP/IP, and then click the Properties button below it. A dialog appears showing you the setting for the default port. That number must match the number you entered as the default port during the installation of ChangeMan DS.

c) If the port numbers do not match, you can either change the default port from the TCP/IP Properties dialog, or re-install ChangeMan DS and when the Loading Predefined Database (1 of 2) screen appears, specify the port setting as it appears for your TCP/IP connection.

Why are there multiple entries added for each file when it contains non-USACII7 characters? For example, á in a file name causes two to three files to appear under control rather than one.

This occurs if the OpenLink Request Broker is started prior to the NLS_LANG and ORA_NLSnn being set. See "Setting Environment Variables" in the Serena® ChangeMan® DS Installation Guide for information on these variables.

To fix this problem:

a) Kill the ChangeMan processes.

b) Shut down the OpenLink Request Broker. rqbshut is located in ...DS/odbc/bin.

c) Set the variables. For example:NLS_LANG=AMERICAN_AMERICA.WE8ISO8859P1;export NLS_LANGORA_NLS33=$ORACLE_HOME/ocommon/nls/admin/data;export ORA_NLS33

Please note that ORA_NLSnn is dependant on Oracle release:

ORA_NLS is for Oracle 7.2, ORA_NLS32 for Oracle 7.3 and ORA_NLS33 for Oracle 8 and above.

d) Source OpenLink. openlink.sh is located in our install directory as follows ...DS\odbc.

e) Start OpenLink request broker - oplrqb is in .../DS/odbc/bin.

f) Start the Changeman processes.

g) Add the variables to the root profile so that it will work after restart.

DETERMINING SOFTWARE VERSIONSIn the ChangeMan DS Windows client, choose About from the Help menu.

343

34


CONNECTING TO CHANGEMAN DSWhy can’t I access areas or servers through a firewall?

ChangeMan DS requires that certain TCP/IP ports are open or available. These TCP/IP ports include 1099, 8040, 8080, 8081, 30767, and 30768.

See “TCP/IP Access” on page 66 for more information.

Why can’t the Remote Directory browser access the host?

You must have the permission to access the host. Verify with your ChangeMan DS administrator that you have the correct user permissions.

In addition, ChangeMan DS requires that certain TCP/IP ports are open or available. These TCP/IP ports include 1099, 8040, 8080, 8081, 30767, and 30768.

See “TCP/IP Access” on page 66 for more information.

WEB BROWSER CLIENTWhen I try to log on, why doesn’t the Web browser client display my areas?

Some possible reasons this could happen are:

— wrong JVM version

— not having Java enabled

— ports setting in properties.srv not being available

— database specified in properties.srv is incorrect

Verify the name of the database pointed to by the Web browser client by viewing the properties.srv file.

If the ChangeMan DS GUI client allows connection, then this information is correct and should not be changed.

When I try to log on as admin, why does ChangeMan DS say I have an invalid user even though it was created in the Windows client?

The user name admin is a special built-in user for the Web browser client and used by ChangeMan ALM. In the event that a user name admin is created in the Windows client, then this will cause a password mis-match and the user name will not work in the Web browser client. A user by the name of admin should not be created for ChangeMan DS.

4


When trying to log on to a server with non-USASCII7 (8 bit) characters in the host name by way of the Web browser client, why can’t I connect?

Non-USASCII7 characters are not supported in URLs. To connect to this server, use its IP address instead of its host name.

Why can’t I view files with special characters in their name with my Internet Explorer browser?

To open a file with special characters in the file name in View mode with the Internet Explorer Web browser client:

Go to Tools > Internet Options > Advanced > Browsing in the Internet Explorer browser, and deselect "Always send URLs as UTF-8 (requires restart)". After that, you must restart all instances of Internet Explorer browser.

Why am I having display problems when trying to use the Web browser client on Windows systems?

Incorrect display properties can cause problems with the Web client interface display. Increase display to:

— More than 16 colors

— Resolution of 800x600 or better

345

34


6

USER INTERFACE REFERENCE
B
ChangeMan DS interface consists of the following items:

• Content Window

• Windows Client UI

• ChangeMan DS Java Client and Web Browser Client UI

• System Configuration Dialog

• File Tree UI

• ChangeMan Diff Menus and Toolbar

• ChangeMan Edit Menus and Toolbars

• Impact Analysis Module

• Performance Monitor

CONTENT WINDOWThe content window is the area on the right in ExplorerView. The column headings change according to what is selected in ExplorerView.

The following topics describe the columns available when select a particular node in ExplorerView.

• “Selecting Areas or Projects Node in Explorer” on page 348

• “Selecting an Area Type in Explorer View” on page 348

• “Selecting a Project Type Node in ExplorerView” on page 350

• “Selecting a User-Created Area or Project in ExplorerView” on page 348

• “Selecting a Directory Node in ExplorerView” on page 349

• “Selecting a Frozen Release Node in ExplorerView” on page 350

• “Selecting a Make Procedure Node in ExplorerView” on page 351

• “Selecting the Attachments Node in ExplorerView” on page 351

347

34

Appendix B: User Interface Reference

For the description of the status icon column, see “Status Icons” on page 353.

Selecting Areas or Projects Node in ExplorerWhen you select the Areas or Projects node in the ExplorerView tree, the following columns are displayed in the content window:

Selecting an Area Type in Explorer ViewWhen you select any area type node (Production, Development, Quality Assurance, End User) in the ExplorerView tree, the following columns are displayed in the content window:

Selecting a User-Created Area or Project in ExplorerView

Column Displays

Type The icon for the contents in the selected area.

Name The name for the contents in the selected area.

Column Displays

Type The icon for contents in the selected area.

Area The names of the user-created areas for the selected area type.

Host The name of the host on which the selected area or file is located.

Path The path to the selected area or file on its host.

Description The description entered in the ChangeMan DS Edit Area dialog.

8


When you select a user created area or project in the ExplorerView tree, the following columns are displayed in the content window:

Selecting a Directory Node in ExplorerViewWhen you select a directory under an area node in the ExplorerView tree, the following columns are displayed in the content window:

Column Displays

Property Various options for the selected area.

Value The values set for the area properties.

Column Displays

Production Status

If a file is checked out of Production, if it is checked out by more than one person, and if it is attached to a project. Files checked out to a non-Production area do not indicate the checked out status in this column.

Local Status What files are under ChangeMan DS control, and if the file is checked out to the area in which you are looking.

Request Status What directories are awaiting approval before being promoted.

File The filename of each file.

Extension The extension of each file.

Current Modification Time

When the file was last modified.

Current Area The area to which the file is currently checked out.

Current Path The path to the area in which the file is currently checked out.

Home Version The version number of the file in the Production area.

Project The directory to which project is attached.

Local Version The version number of the file currently in the area.

Transfer User The last person to transfer the file between areas.

349

35


Selecting a Project Type Node in ExplorerViewWhen you select a project type node in the ExplorerView tree, the following columns are displayed in the content window:

Selecting a Frozen Release Node in ExplorerViewWhen you select the Frozen Release node under a project in the ExplorerView tree, the following columns are displayed in the content window:

Transfer Time The time the file was last transferred.

Current Size The current size of the file

Production Size The size of the version of the file in the Production area.

Production Mod When the file was introduced to the Production area.

Column Displays

Type The icons for all projects in the selected project type, and if they are in Development.

Request Status Projects awaiting approval before they can be promoted.

Project The name of the projects in the project type.

Status The status assigned during project creation.

Priority The priority assigned during project creation.

Parent Any parent project to which this project can be attached.

Description The description entered about the project.

Column Displays


Release The label used to identify a release.

Column Displays

0


Note that the you can also find the project name, release label, and description for a release by selecting the release, and choosing Properties from the right-click menu.

Selecting a Make Procedure Node in ExplorerViewWhen you select the Make Procedures node under a project in the ExplorerView tree, the following columns are displayed in the content window:

Selecting the Attachments Node in ExplorerView

User The owner of the release.

Date When the release was created.

Description The description entered about a release.

Column Displays

Make Name The identifier for each make procedure.

Assembly User The user ID for login on the host where the build process is to be executed.

Assembly Host The host name where the build is to be executed.

Assembly Path The sub-directory path where the build process is to be executed.

Location The location of dependency files.

Use Production The Production location of dependency files.

Column Displays

351

35


When you select the Attachments node under a project in the ExplorerView tree, the following columns are displayed in the content window:

Column Displays

Local Status Files that are under ChangeMan DS control, and if the file is checked out to the area you are looking in.

Production Status

If a file is checked out of Production, if it is checked out by more than one person, and if it is attached to a Project. Files checked out to a non-Production area you are currently looking at will not indicate the checked out status in this column.

Request Status The attachments awaiting approval before being promoted.


File The filename of each file.

Extension The extension of each file.

Relative Path The path of the attachment in relation to its project (if created).

Home Area The name of the file’s Production area.

Home Path The path to the file’s Production area.

Home Version The version number of the file in Production.

Current Area The area to which the file is currently checked out.

Current Path The path to the area in which the file is currently checked out.

Current Modification Time

When the file was last modified.

Local Version The version number of the file currently in the area.

Transfer User The last person to transfer the file between areas.

Transfer Time The time the file was last transferred.

Current Size The current size of the file

2


Status IconsStatus icons tell the status of the file, and the type of icons depend on the column.

For example, the following icon can appear in the Status column, depending on what item is active in the Explorer tree, and the status of that item.

Select the appropriate column for the meaning of other status icons:

• Status Icons for Local Status Column

• Status Icons for Production Status Column

• Status Icons for Request Status Column

Status Icons for Local Status ColumnThe following icons appear in the Local Status column, depending on what item is active in the Explorer tree, and the status of the item.

If you receive a red icon (Production file tampered), notify your ChangeMan DS administrator that someone has accessed the Production area directory outside of ChangeMan DS and corrupted file integrity. Since this change was made outside of

Production Size The size of the version of the file in Production.

Production Mod When the file was introduced to Production.

Icon Means

File in a frozen release. This item is in a frozen release.

Column Displays

353

35


ChangeMan DS, ChangeMan DS won’t have any information about the change such as what edits were made or who made the edits.

This icon... Indicates...

Not controlled. This item is not under ChangeMan DS control.If you select Do Not Access Area Agent on the Tools toolbar, uncontrolled files do not appear in the content window.If you deselect Show Controlled Status on the Tools toolbar, files in working areas that are not checked out will appear with the Not controlled icon (although a version of the file may be under ChangeMan DS control).

Controlled. This item is under ChangeMan DS control.If viewing a Development area and Show Controlled Status on the Tools toolbar is selected, this icon means a copy of the file resides in the Development area, however the copy is not currently checked out.

Under Control. Production file tampered. The Production file has been modified outside of ChangeMan DS.To remove the tampered status, either:• Replace the Production file with the last version of the file that

was checked in.• Check out the file, verify that the file is correct, and then check

in the file.

Under control. Checked out to local area. This item is under control and checked out to the selected area.Note that this is not the same as the Promote to Development icon; this icon may appear for items that are in areas other than Development.

Under control. Checked out to local area. Production file tampered. This item is under control, and checked out to the selected area. The Production version of the file has been modified outside of ChangeMan DS, and the Development file and Production file are identical.To remove the tampered status, check in the file.

4


Under control. Differs from baseline. This item is under control and a checked out version is different from the version in its Home Production area.

Under control. Differs from baseline. Production file tampered. This file is under control, and a copy has been checked out. The Production file was modified outside of ChangeMan DS while the file was checked out, and the Production file and Development file are now different.To remove the tampered status, either:• Replace the Production file with the last version of the file that

was checked in.• Check in the checked out file. Note that this will overwrite the

changes made to the Production file outside of ChangeMan DS.

Under control. Checked out to local area. Differs from baseline. This item is under control, checked out to the selected area, and is different from the version in its Home Production area.

Under control. Checked out to local area. Differs from baseline. Production file tampered. This item is under control, and checked out to the selected area. The Production file was modified outside of ChangeMan DS while the file was checked out, and the Production file and Development file are now different.To remove the tampered status, either:• Replace the Production file with the last version of the file that

was checked in.• Check in the checked out file. Note that this will overwrite the

changes made to the Production file outside of ChangeMan DS.

Under control. Deleted from local workspace. This item is under control, but has been deleted from the directory to which its area points.

This icon... Indicates...

355

35


Status Icons for Production Status ColumnThe following icons appear in the Production Status column, depending on what item is active in the Explorer tree, and the status of the item.

Icon Means

Checked out. This item is checked out by a user.

Checked out concurrently. This item is checked out by multiple users.

Attached to single project. This item is attached to only one project.

Attached to multiple projects. This item is attached to more than one project.

Attached file checked out. This item is checked out by a user and is attached to a single project.

Attached file concurrently checked out. This item is checked out by multiple users and is attached to a single project.

Attached to multiple projects and checked out. This item is checked out by a user and is attached to multiple projects.

Attached to multiple projects and checked out concurrently. This item is checked out by multiple users and is attached to multiple projects.

Production file is missing. This item is missing from its home Production area, usually because it was deleted outside of ChangeMan DS.

6


Status Icons for Request Status ColumnThe following icons appear in the Request Status column, depending on what item is active in the Explorer tree, and the status of the item.

WINDOWS CLIENT UIWhen accessing ChangeMan DS through the Windows client, there are slight differences in the following:

• “Main Window Menus—Windows Client” on page 357

• “Main Window Toolbars—Windows Client” on page 365

• “System Configuration Dialog” on page 374

• “File Tree UI” on page 400

• “Impact Analysis Module” on page 377

• “ChangeMan Diff Menus and Toolbar” on page 402

• “ChangeMan Edit Menus and Toolbars” on page 410

Main Window Menus—Windows ClientThe following topics explain the commands in the menus of the ChangeMan DS main window:

• ChangeMan DS Main Window File Menu

• ChangeMan DS Main Window Edit Menu

• ChangeMan DS Main Window View Menu

• ChangeMan DS Main Window Promote Menu

• ChangeMan DS Main Window Project Menu

• ChangeMan DS Main Window Files Menu

Icon Means

Pending. This item is awaiting approval before it can be transferred into this area.

Requested. This item is in the process of being transferred. Refresh the screen to remove this icon after transfer.

357

35


• ChangeMan DS Main Window Hosts Menu

• ChangeMan DS Main Window Tools Menu

• ChangeMan DS Main Window Help Menu

ChangeMan DS Main Window File MenuThis table describes the commands in the File menu for the ChangeMan DS Windows client:

ChangeMan DS Main Window Edit MenuThis table describes the commands in the Edit menu for the ChangeMan DS Windows client:

Command Description

File > Connect Opens the ChangeMan DS Login dialog to log on to the ChangeMan DS Main Server.

File > Print Preview

Print preview. Previews the print out of reports.

File > Print Print. Prints the item window report.

File > Print Setup Opens the Print Setup dialog for your printer.

File > Page Setup Opens the Page Setup dialog to set the margins for your printout.

File > Exit Exits ChangeMan DS.

Command Description

Edit > Copy Initiates a file or project promotion process. This button is active when you select a file, area, directory path, or project.

Edit > Paste Pastes a previously copied item into a target location. This button is active after you select the Copy command.

8


ChangeMan DS Main Window View MenuThis table describes the commands in the View menu for the ChangeMan DS Main Window:

ChangeMan DS Main Window Promote MenuThis table describes the commands in the Promote menu. This commands are also available on the “Promote Toolbar” on page 371 and when you right-click on a file and choose Promote.

Edit > Refresh Updates the screen with the most current file or directory status.

Edit > Stop Stops the process currently in progress. This button is active when ChangeMan DS loads data or reads the database.

Command Description

Toolbar Displays the toolbars at the top of the ChangeMan DS window.

Status Bar Displays the status bar at the bottom of the ChangeMan DS window.

Command Description

Synchronize Get the latest version of the selected file. This feature is active only when a non-Production area is selected in ExplorerView.

Check Out Retrieve a Production version of a file and create an identical copy in the target area.

Check In Introduce a new version of the file to the Production area.

Cancel Check Out

Remove the check out status from the file. Changes made are not sent back to the server.

Approve Approve selected pending transfers.

Promote to Production

Transfer files the target Production area.

Command Description

359

36


ChangeMan DS Main Window Project MenuThis table describes the commands in the Project menu. See “Project Toolbar” on page 370 for additional methods to access this functionality.

Promote to QA Transfer files to a Quality Assurance area.

Promote to Development

Transfer files to a Development area.

Distribute to End Users

Transfer files from the Production area to an End User area. This will make copies of the files without updating the file status.

Transfer Ownership

Transfer files between like type areas, such as Development to Development.

Bring Home Automatically return any checked out files to their Home Production areas.

Command Description

Freeze a project release

Freeze a release. This button is enabled when you select a project.

Attach to Project Attach files from one project to another. The button is active when you select a project.

Detach from Parent Detach files from a project. The button is active when you select a project.

Properties Let you configure properties of the item selected in the Projects folder.

New target/dependency

Create a new dependency file and define its properties.

Initiate Build procedures

Starts the build process from ExplorerView.

Export Make procedures

Automatically create a new build process from an existing make file.

Command Description

0


ChangeMan DS Main Window Files MenuThis table describes the commands in the Files menu. Note that you may access these commands on the “Files Toolbar” on page 369.

Maintain Release Branch an entire release to a new location

Rollback frozen release Replace the current version of the selected files with the corresponding frozen versions.

Delete Delete a frozen release or a Make Procedure History.

Command Description

Edit Opens the file for editing.

View View the file.

Show differences

While a file is selected, shows the differences between that version and the previous version.See “Comparing Files” on page 143 for more information.

File Tree Opens the File Tree for the currently-selected file. This button is active only for files under ChangeMan DS control. See “File Tree UI” on page 400 for more information on the File Tree.

Show History Displays the Audit Trail window with the File Name, Home Area, and Project ID fields filled in for the selected file. This button is active only for files under ChangeMan DS control.

Properties Displays the Source Control Properties dialog for the selected file. This button is active only for files under ChangeMan DS control.

Import Make File Automatically create a new build process from an existing make file.

File List This submenu presents options available to a file list. See “File List Toolbar and Submenu” on page 373 for more information.

Command Description

361

36


ChangeMan DS Main Window Hosts MenuThe following table describes the Hosts menu elements; these elements provide access to file management operations in the Host View. Host View is used for UNIX environments, and it runs under a different process than the ExplorerView.

The Host View may not be available at your site. If you cannot use these functions, check with your ChangeMan DS Administrator.

See “Hosts Toolbar” on page 372 for additional ways to access these functions.

Add to DS Control

Add the selected file to ChangeMan DS control. This button is active only for files that are not under ChangeMan DS control.

Remove from DS Control

Remove the selected file from ChangeMan DS control. This button is active only for files currently under ChangeMan DS control.

Attach to Project

Attach a selected file to a project. This button is active for all Production area files and the alphabetical Impact Analysis.

Detach from Project

Detach a selected file from an ChangeMan DS project. This button is active when you select a file attached to a project.Note: This does not delete the file.

Set Relative Path

Set the relative path for the selected file. This button is active when you select a file attached to a project.

Command Description

Add host Add host. Add a host/computer to the Host View structure.

Remove host Remove host. Remove a host from the Host View structure.

Properties Properties. View or change the file properties. This button is active when you select a file that you have permission to modify.

Edit file Edit. Edit the file. See “Editing the Contents of a File” on page 53 for more information.

Command Description

2


ChangeMan DS Main Window Tools MenuThis table describes the commands in the Tools menu. See “Tools Toolbar” on page 367 for additional ways to access this functionality:

View file View. View the file.See “Viewing the Contents of a File” on page 54 for more information.

Delete file Remove file(s) from the host. Remove the selected file from the host.

Binary mode Binary mode. Select this button when copying binary files. If this command is not selected, “carriage return” handling is enabled when copying files between heterogeneous hosts. Use this command when transferring binary files between homogeneous hosts.

Change Man hosts

Browse UNIX and HP e3000 hosts running SERENA’s StarServ Agent.

Command Description

Audit Trail Opens the Audit Trail dialog. See “Running Audit Trail Reports” on page 213 for more information on the Audit Trail.

Impact Analysis Opens the Impact Analysis dialog. See “Impact Analysis” on page 227 for more information on Impact Analysis.

System Configuration

Opens the Global - ChangeMan DS Process Control dialog. See “System Configuration Dialog” on page 374 for more information.

Performance Monitor

Opens the Performance Monitor dialog.

Command Description

363

36


Use ChangeMan DS Edit

When selected, uses the ChangeMan DS editor to edit a source file. When not selected, uses the editor specified in your IDE to edit source files. See “ChangeMan Edit Module” for more information on ChangeMan Edit.

Show Sharing Information

When selected, displays sharing information of files if the files are checked out by multiple users.

Show CheckOut Status

When selected, displays the check out status of files in the file list.

Show Pending & Schedule Information

When selected, displays the pending status of files if they are scheduled to be promoted.

Show Controlled Status

When selected, copies of controlled files that reside in the work area but are not checked out, will appear as controlled (gray icon).When this command is deselected and Do Not Access Area Agent is deselected (see below), files that reside in the Development area and are not checked out will appear as uncontrolled (white icon).Note: This command works only when you are viewing a

Development or QA area.Use this command to filter files that are under control and not checked out in a Development area.For example, if you check out files to a Development area 1, then cancel the check out, these files will appear as under control when Show Controlled Status is selected (gray icon). See “Status Icons” on page 353 for more information.

Command Description

4


ChangeMan DS Main Window Help MenuThis table describes the commands in the Help menu on the ChangeMan DS Windows client:

Main Window Toolbars—Windows ClientThe ChangeMan DS main window toolbars can be moved around the screen to best suit your working habits. These toolbars contain many of the same features that are in the menu bar. The toolbars are:

• Standard Toolbar – provides quick access to standard system commands.

• Tools Toolbar – provides access to major ChangeMan DS modules.

• Files Toolbar – provides access to file-level software configuration operations.

• Project Toolbar– provides access to project-level software configuration operations.

Show Modified Status

When selected, modification icons display in the Status column.Use this command to see which files have been edited.Note: The modification icon differs depending on whether you

are viewing a Production area or a Development area.See “Status Icons” on page 353 for more information.

Show Size & Time Information

When selected, displays the current size and modification time of the files in the list.

Command Description

Help > Index Help. Activates the ChangeMan DS Help module. Either:• Click this button, then click on the item for which you want

help.• Choose Help > Index to view the entire Help system.

Help > About ChangeMan DS

Opens the About ChangeMan DS dialog and displays the versions and patch levels of the ChangeMan DS Client and Server in use.

Command Description

365

36


• Promote Toolbar – provides access to file transfer operations.

• Hosts Toolbar – provides access to the file/directory management operations in Host View.

• File List Toolbar and Submenu – provides access to version control operations.

Toolbar buttons are active only when the correct view or item is selected.

The toolbars and the status bar are displayed on the screen by default. You can remove them from the screen by choosing Toolbar and Status Bar from the View menu.

Standard ToolbarThe following table describes elements of the ChangeMan DS Main window standard toolbar in the Windows client.

These functions are also available from the Main Window ChangeMan DS Main Window File Menu and ChangeMan DS Main Window Edit Menu:

Button Description

Copy. Initiates a file or project promotion process. This button is active when you select a file, area, directory path, or project.

Paste. Pastes a previously copied item into a target location. This button is active after you select the Copy command.

Print preview. Previews the print out of reports.

Print. Prints the item window report.

Refresh. Updates the screen with the most current file or directory status.

Stop. Stops the process currently in progress. This button is active when ChangeMan DS loads data or reads the database.

Help. Activates the ChangeMan DS Help module. Click this button, then click on the item for which you want help.

6


Tools ToolbarThe following table describes the Tools buttons; these items provide access to various utilities in ChangeMan DS.

See ChangeMan DS Main Window Tools Menu for additional ways to access this functionality:

Button Description

Audit trail. Opens the Audit Trail dialog. See “Running Audit Trail Reports” on page 213 for more information on the Audit Trail.

Impact analysis. Opens the Impact Analysis dialog. See “Impact Analysis” on page 227 for more information on Impact Analysis.

System configuration wizard. Opens the Global - ChangeMan DS Process Control dialog. See “System Configuration Dialog” on page 374 for more information.

Performance monitor. Opens the Performance Monitor dialog.

Local IDE integration options. Opens the IDE Integration Options dialog to set options for integrating an IDE with ChangeMan DS.

Use ChangeMan DS Edit. When selected, uses the ChangeMan DS editor to edit a source file. When not selected, uses the editor specified in your IDE to edit source files. See “ChangeMan Edit Module” for more information on ChangeMan Edit.

Show sharing information. When selected, displays sharing information of files if the files are checked out by multiple users.

Show checkout status. When selected, displays the check out status of files in the file list.

Show pending and schedule information. When selected, displays the pending status of files if they are scheduled to be promoted.

367

36


Show controlled status. When selected, copies of controlled files that reside in the work area but are not checked out, will appear as controlled (gray icon).When this command is deselected and Do Not Access Area Agent is deselected (see below), files that reside in the Development area and are not checked out will appear as uncontrolled (white icon).Note: This command works only when you are viewing a Development

or QA area.Use this command to filter files that are under control and not checked out in a Development area.For example, if you check out files to a Development area 1, then cancel the check out, these files will appear as under control when Show Controlled Status is selected (gray icon). See “Status Icons” on page 353 for more information.

Do not access area agent. If selected, the area agent will not search the area host for files. Only files under ChangeMan DS control are displayed.

Show modified status. When selected, modification icons display in the Status column.Use this command to see which files have been edited.Note: The modification icon differs depending on whether you are

viewing a Production area or a Development area.See “Status Icons” on page 353 for more information.

Show size and time information. When selected, displays the current size and modification time of the files in the list.

Show project work location view. When selected and a Development area is associated with a project, displays the status of files attached to the project as they appear in the working location. When not selected, files appear as they do in the Production area.This is primarily for developers. It allows them to view files attached to a project as they appear in the working location (generally a Development area).All other users should use the Production view.See “Project Working Location View” on page 88.

Button Description

8


Files ToolbarThe following table describes elements of the Files toolbar; these elements provide access to the file-level software configuration operations.

Note that you may access these commands on the ChangeMan DS Main Window Files Menu.

Button Description

Edit. Opens the file for editing.

View. View the file.

Show difference. While a file is selected, shows the differences between that version and the previous version.See “Comparing Files” on page 143 for more information.

File tree. Opens the File Tree for the currently-selected file. This button is active only for files under ChangeMan DS control. See “File Tree UI” on page 400 for more information on the File Tree.

Show history. Displays the Audit Trail window with the File Name, Home Area, and Project ID fields filled in for the selected file. This button is active only for files under ChangeMan DS control.

File properties. Displays the Source Control Properties dialog for the selected file. This button is active only for files under ChangeMan DS control.

Import make file. Automatically create a new build process from an existing make file.

Add to DS control. Add the selected file to ChangeMan DS control. This button is active only for files that are not under ChangeMan DS control.

Remove from source control. Remove the selected file from ChangeMan DS control. This button is active only for files currently under ChangeMan DS control.

369

37


Project Toolbar

The following table describes the Project toolbar elements; these elements provide access to the project-level configuration operations.

See ChangeMan DS Main Window Project Menu for additional methods to access this functionality.

Attach. Attach a selected file to a project. This button is active for all Production area files and the alphabetical Impact Analysis.

Detach. Detach a selected file from an ChangeMan DS project. This button is active when you select a file attached to a project.Note: This does not delete the file.

Set relative path. Set the relative path for the selected file. This button is active when you select a file attached to a project.

Button Description

Freeze. Freeze a release. This button is enabled when you select a project.

Attach to project. Attach files from one project to another. The button is active when you select a project.

Detach from project. Detach files from a project. The button is active when you select a project.

Properties. Let you configure properties of the item selected in the Projects folder.

Add target/dependency. Create a new dependency file and define its properties.

Build. Starts the build process from ExplorerView.

Button Description

0


Promote ToolbarThe following table describes the elements of the Promote toolbar; these elements provides access to version control operations.

If you select a button from the Promote toolbar, and if an application or project process flow is in force, you are asked to choose the target area from the list of configured areas, as defined by the process flow model.

See “Process Flow Setup” in Serena™ ChangeMan® DS Administrator Guide for more information on process flow.

Export make procedures. Automatically create a new build process from an existing make file.

Maintain release. Branch an entire release to a new location

Rollback. Replace the current version of the selected files with the corresponding frozen versions.

Delete. Delete a frozen release or a Make Procedure History.

Button Description

Synchronize version. Get the latest version of the selected file. This feature is active only when a non-Production area is selected in ExplorerView.

Check out. Retrieve a Production version of a file and create an identical copy in the target area.

Check in. Introduce a new version of the file to the Production area.

Cancel check out. Remove the check out status from the file. Changes made are not sent back to the server.

Button Description

371

37


Hosts ToolbarThe following table describes the Hosts toolbar elements; these elements provide access to file management operations in the Host View.

Approve transfer. Approve selected pending transfers.

Promote to Production. Transfer files the target Production area.

Promote to QA. Transfer files to a Quality Assurance area.

Promote to Development. Transfer files to a Development area.

Distribute to end users. Transfer files from the Production area to an End User area. This will make copies of the files without updating the file status.

Transfer ownership. Transfer files between like type areas, such as Development to Development.

Bring file(s) home. Automatically return any checked out files to their Home Production areas.

Button Description

Add host. Add a host/computer to the Host View structure.

Remove host. Remove a host from the Host View structure.

Properties. View or change the file properties. This button is active when you select a file that you have permission to modify.

Edit. Edit the file. See “Editing the Contents of a File” on page 53 for more information.

Button Description

2


File List Toolbar and SubmenuThe following table describes the File List toolbar elements and the File List submenu available when you right-click a file in the content window; these elements provide access to version control operations.

File List options should only be used when selecting a file that contains a list of files to operate on. For individual file or project activities, the “Promote Toolbar” on page 371 should be used instead.

Note that you can also access this functionality through File List submenu on the “ChangeMan DS Main Window Files Menu” on page 361.

This toolbar is active only if at least one file is selected.

View. View the file.See “Viewing the Contents of a File” on page 54 for more information.

Remove file(s) from the host. Remove the selected file from the host.

Binary mode. Select this button when copying binary files. If this command is not selected, “carriage return” handling is enabled when copying files between heterogeneous hosts. Use this command when transferring binary files between homogeneous hosts.

Command Button Description

Files > File List > Check Out

Check out. Retrieve a Production version of a file and create an identical copy in the target area.

Files > File List > Promote to QA

Promote to QA. Transfer files to a Quality Assurance area.

Files > File List > Promote to Development

Promote to Development. Transfer files to a Development area.

Files > File List > Check In

Promote to Production. Transfer files to the target Production area.

Button Description

373

37


System Configuration DialogThe System Configuration dialog (also known as the Global - ChangeMan DS Process Control dialog) is where you define and manage:

• Process Flows

• Users and Groups

• Areas

• Projects

It is available in the Windows client, and accessed by clicking System Configuration

on the Tools toolbar or menu.

Files > File List > Distribute

Distribute to end users. Transfer files from the Production area to an End User Area. This will make copies of the files without updating the file status.

Files > File List > Transfer Ownership

Transfer ownership. Transfer files between like type areas, such as Development to Development.

Files > File List > Bring Home

Bring file(s) home. Automatically return any checked out files to their Home Production areas.

Files > File List > Attach to Project

Attach. Attach a selected file to a project.


4


Access to this dialog is limited, according to the permissions you have been granted.

The following table describes the tools on the System Configuration toolbar:


File > New New rule. Create a new process flow.

File > Open Open rule. Open an existing process flow.

File > Save Save rule. Save a process flow.

File > Delete Delete rule. Delete a process flow.

Edit > Undo N/A Undo last action.

Edit > Validate Validate design rule. Verify that the rules of an application, project, or design flow match the global process flow.

Edit > Add Node Add node. Add a node to your process flow.

375

37


ChangeMan DS Project Configuration DialogThe ChangeMan DS Project Configuration dialog lets you create, edit, copy, delete, and print projects.

Edit > Process Modify rule. Opens the Rules Configuration screen where you can create and modify rules in your process flows.

Edit > Users Manage users. Opens the User Configuration screen where you create and modify users.

Edit > Areas Manage areas. Opens the Area Configuration screen where you create and modify areas.

Edit > Projects Manage projects. Opens the Project Configuration screen where you can create and modify projects.

Edit > Del Node Delete node. Delete the selected node in a process flow.

File > Print Print. Prints the current process flow.


N/A Print preview. Lets you preview what the printed output will look like.

File > Print Setup N/A Print setup. Lets you change the printer and print options.

View > Toolbar N/A Toggles the toolbar.

View > Status Bar N/A Toggles the status bar.

Help > About Process

About. Provides version information about ChangeMan DS process control.

Help > Contents N/A Displays help about the Process Flow dialog.

File > Exit N/A Exits. Closes the Process Flow dialog.


6


On this screen you can perform the following:

• To display a certain type of project, click the appropriate tab, such as New, Bug Fix, Custom, or Enhancement.

• To access the project filter screen, click .

• To create a project, click New.

• To edit a project, select a project, and click Edit. • To copy a project properties to another project, select a project, and click Copy.

• To delete a project, select a project, and click Delete.

• To print the properties of a project, select a project, and click Print. • To close the dialog, click Exit.

ChangeMan DS Area Configuration DialogThe ChangeMan DS Area Configuration dialog lets you create, edit, copy, delete, and print areas.

On this screen you can perform the following:

• To display a certain type of project, click the appropriate tab, such as Production, Development, QA, or End User.

• To create an area, click New.

• To edit an area, select an area, and click Edit. • To copy an area's properties into another area, select an area, and click Copy.

• To delete an area, select an area, and click Delete.

• To print the properties of an area, select an area, and click Print. • To close the dialog, click Exit.

Impact Analysis ModuleThe Impact Analysis Module lets you determine the effect a change has on other components of the system.

See “Impact Analysis” on page 227 for more information on performing impact analysis.

The Impact Analysis module contains the following elements:

• “Impact Analysis Toolbar” on page 378

377

37


• “Advanced Tab for Impact Analysis” on page 378

Impact Analysis ToolbarAt the bottom of the Impact Analysis dialog is a toolbar that provides the following commands:

Impact Analysis from the Web browser and Java clients does not provide these commands.

Advanced Tab for Impact AnalysisSelect the Advanced tab on the Impact Analysis dialog to add search criteria.

Note The Web browser client Impact Analysis does not include an Advanced tab.

Button Description

Attach the file to a project.See “Attaching Files from the Content Window” on page 84 for more information.

View the File Tree for the selected file.See “Checking In” on page 114 for more information.

View the actual file selected.See “Viewing the Contents of a File” on page 54 for more information.

Preview the printout of the Impact Analysis search results.

Print the Impact Analysis search results.

Close the Impact Analysis dialog.

8


You can select the following options for the Advanced Impact Analysis search:

Choose this option… To perform this search…

Search By

Element Limit the search process to items such as variables, data files, or objects.

Function Call Limit the search process to function calls.

Include File Limit the search process to include files.

Subset Mode

AND Search for files that reference both <ENTITY-1> and <ENTITY-2>, where <ENTITY-1> is the item name in the first search, and <ENTITY-2> is the item name in the second search.The Find Now option must be used for the second search to honor the AND or OR mode.See “Refining an Impact Analysis Report” on page 233.

OR Search for files that reference either <ENTITY-1> or <ENTITY-2>, where <ENTITY-1> is the item name in the first search, and <ENTITY-2> is the item name in the second search.The Find Now option must be used for the second search to honor the AND or OR mode.See “Appending Additional Results to an Impact Analysis Report” on page 233.

379

38


CHANGEMAN DS JAVA CLIENT AND WEB BROWSER CLIENT UI

The Web browser client and Java client contain similar functionality:

• The Web browser client allows users to connect to a ChangeMan DS from an Internet browser. This means that you don’t need to install a client to run the Web browser client from a local machine.

• The Java client is constructed completely in Java, and can be run on multiple platforms. To start the Java client, you need the communication client installed on your local system.

When you access the Java and Web browser clients, the displayed nodes depend on your view permissions that your administrator has set.

If you have access only to the Project/Area view, you see the following (Web browser client example):

0


With both views selected, you see the following:

Though all of the toolbars available in the ChangeMan DS main window are not available in the Java and Web browser clients, most of the features are available in the right-click menus provided when right-clicking on items.

!!Caution!! Using the Web browser’s Back button takes you to the login screen. Use the Exit button in dialogs to close them and return to the previous screen.

To display the name of the associated option on the status bar of your browser, move your mouse pointer over a toolbar button.

The following commands are available on the Java and Web browser clients:

Commands Button Description

ChangeMan DS > Audit Trail

Audit trail. Opens the Audit Trail dialog. See “Running Audit Trail Reports” on page 213 for more information on the Audit Trail.

381

38


ChangeMan DS > Impact Analysis

Impact analysis. Opens the Impact Analysis dialog. See “Impact Analysis” on page 227 for more information on impact analysis.

ChangeMan DS > View Options

Options. Opens the View Options dialog where you can enable properties and status to be displayed.

ChangeMan DS > Package Search

Package Search. Opens the Search Package dialog where can insert search criteria to find packages.

ChangeMan DS > New Area

Areas. Opens the Edit Area dialog, where you can create a new area. See “Areas” in Serena™ ChangeMan® DS Administrator Guide for more information on areas.

ChangeMan DS > New Project

Projects. Opens the Edit Project dialog, where you can create a new project. See “Projects” in Serena™ ChangeMan® DS Administrator Guide for more information on projects.

N/A Refresh. Refreshes the current view.

ChangeMan DS > Change Password

Change Password. Opens the Change Password dialog where you can select a new password.

ChangeMan DS > Relogin

Relogin. Returns you to the login screen to reconnect to ChangeMan DS.

Help > Help Index N/A Opens the ChangeMan DS online help.


2


ChangeMan DS Web ClientIf you set up the ChangeMan DS Main Server on a Windows NT or UNIX system, and if you are using Microsoft SQL Server or Oracle (UNIX) for your database, then you can access the ChangeMan DS server through the Web browser clients.

In the Web client, you have most of the functionality of the regular ChangeMan DS client, with the majority of the commands available through right-click menus.

You cannot view executable files from the Web Browser client.

You can execute most of the options available in the ChangeMan DS Windows client, including:

• Creating areas and projects.

• Promoting files and projects.

• Running Audit Trail reports.

• Running Impact Analysis reports.

• Viewing and editing file content.

• Comparing two files.

• Merging two files.

• Branching files and projects.

• Executing build management.

• Performing release management.

N/A Exit. Exits the ChangeMan DS client.


383

38


Display Permissions for Web Browser and Java Clients Upon login, the Web browser or Java client primary screen displays. If you have access only to the Project/Area view, you see the following:

ChangeMan DSAreasProjectsImpact Analysis

If you have access only to the Package/Application view, you see the following:

ChangeMan DSApplicationsApprovalsApproval Configuration

Approval GroupsNotification ConfigurationContacts

With both views are selected, you see the following:

ChangeMan DSAreasProjectsApplicationsImpact AnalysisApproval Configuration

Approval GroupsNotification ConfigurationContactsDependency Configuration

4


Changing Status OptionsYou can set the following status options by selecting the corresponding check box in the Web browser and Java clients. They control the status information that displays in the file display of the ExplorerView.

Note The Use ChangeMan DS Editor option is not applicable for the Web browser client. When you edit a text-based file from the Web browser client, ChangeMan Edit will be invoked.

Refer to “Tools Toolbar” on page 367 for an explanation of the status items.

Toolbar ButtonsThe Web browser and Java clients display different toolbar buttons depending on the nodes that are selected.

The following topics describe the different available toolbar buttons:

• “Applications Node Toolbar Buttons” on page 386

• “Packages Node under Applications Node” on page 387

• “Projects Node under Applications” on page 388

• “Frozen Release Node” on page 389

• “Contacts Node Toolbar Buttons” on page 390

• “Approval Node Toolbar Buttons” on page 391

• “Approval Configuration Node” on page 392

• “Notification Configuration Node” on page 393

385

38


Applications Node Toolbar ButtonsWith the Applications node selected, the following options are available for any created applications:

Command Description

Create a new application.

Edit an existing application.

Create a new package associated with an application.

Associate ChangeMan DS projects with an application. Projects attached at the application level become the defaults for all packages in the application, if the packages do not have their own project attachments.

Associate ChangeMan DS Development or QA areas with an application.

Designate a default area and state.

Delete a created application.

Define approval processes for the application.

6


With a created application selected in the ExplorerView tree, the following option is available:

Packages Node under Applications NodeWhen you select the Packages node under the Applications node, the following options are available:

Command Description

Edit the selected application.

Command Description

Create a new package.

Edit an existing package.

Delete a package.

Associate ChangeMan DS projects with the package and application. A list of projects available to be attached to the application will be displayed; you select from the list. You cannot introduce new items to the application from this level.

Associate ChangeMan DS areas with the package and application. A list of areas available to be attached to the application will be displayed; you select from the list. You cannot introduce new items to the application from this level.

Promote the package through the life cycle process.

387

38


Projects Node under ApplicationsThe Project node under an application node lets you work with projects attached to that application.

See “Using Projects” on page 63 for information on working with projects.

Under the package-oriented approach, the Attachments node under a project is available only when its associated package is in the DEV state. Files attached to a project and associated with a package can be edited only when that package is in the DEV state.

With the Projects node or any of its first level subnodes selected, the following options are available:

See the promotion history of the package.

Set package access permissions for users and groups.

See the package installation history.

Command Description

Edit the properties of the project.

Set the project to be installed automatically.

Command Description

8


Frozen Release Node The Frozen Releases node is found under Applications > Packages > Projects.

The Frozen Releases node is not available when the package is in the DEV state.

With a Frozen Releases node selected, the following options are available for any release selected on the right:

Clear the deliverable status from the project.

View the Audit Trail.

Command Description

Branches an entire release to a new location.

Synchronizes files in the currently-configured area with the contents of the selected frozen release. This feature is active only when a non-Production area is selected in ExplorerView.

Check out the entire frozen release to the currently-configured work area.

Promote the entire frozen release to the target Production area.

Transfers files to a quality assurance area.

Command Description

389

39


Contacts Node Toolbar Buttons

In Contacts, you can create a list of companies and individual members of those companies. When change requests come in from these companies, their name can be associated with the packages that relate to their request.

See “Adding a Contact (or Requester) to a Package” on page 269 for information on adding the contacts to a package.

Updates the list of frozen releases.

Promotes the entire frozen release to an End User area.

Lets you view/modify the selected frozen release’s name and description. Changing the frozen release name creates a new frozen release with the build procedures and attachments copied from the original release.

Creates a file of the project’s make procedure for use elsewhere.

Command Description

0


With the Contacts node selected, the following options are available:

Approval Node Toolbar ButtonsThe Approval node allows access to approvals created under Approval Configuration that are either currently awaiting action, or that have completed the approval process. The approvals are grouped as follows:

• Pending Approval: currently awaiting action.

• Pending My Approval: currently awaiting action by the current user.

• Finished Approvals: all completed approvals.

• Finished My Approvals: all approvals completed by the current user.

With the Approval node expanded and one of the approval groups selected, the following options are available:

Command Description

Lets you create a new contact entry.

Opens a contact entry for editing.

Deletes a contact entry

Command Description

Opens the approval assignment life cycle for approval promotion.

Opens the approval assignment to view comments entered by previous approvers.

391

39


Approval Configuration Node

With the Approval Configuration node expanded and the Approval Groups node selected, the following options are available:

Displays the history of the approval assignment’s progress.

Updates the screen with the most recent promotion status.

Command Description

Lets you create a new approval group.See “Creating an Approval Group in POA” on page 298.

Opens an existing approval group for editing.See “Creating an Approval Group in POA” on page 298.

Deletes an existing approval group.

Command Description

2


Notification Configuration NodeWith the Notification Configuration node selected, the following options are available:

Right-Click MenusThe Web browser and Java clients display different right-click menus depending on what is selected.

The following topics describe the different available right-click menus:

• Right-Click Menu at the File Level

• Right-Click Menu at the Area Name Level

• Right-Click Menu at the Folder Level

• Right-Click Menu at the Project Level

Right-Click Menu at the File LevelChangeMan DS operations to be applied to a file or files are executed by selecting a file or list of files from the file list displayed in the right side of the ExplorerView.

Command Description

Lets you create a notification to occur when package activities or events occur.

Opens a notification for editing.

Deletes a notification.

Prints a selected notification.

393

39


The following table lists the primary options found on the right-click menu at the file level for the Web browser and Java clients:

Command Description

Edit Modify the contents of a file. See “ChangeMan Edit Module” on page 437 for more information.

View Display the contents of a file. View invokes an edit routine in read-only mode. You cannot view executable files from the Web browser client.See “ChangeMan Edit Module” on page 437 for more information.

Show Differences Compare the contents of two text-based files.

File Tree View the graphical history of all versions and branches of a file. See “Viewing File Information from the File Tree” on page 211 for information.

Show History Invoke the Audit Trail to view the transaction history of transfers, merges, and branches. See “Audit Trail” on page 213 for information.

Import Makefile Populate a project’s Make Procedures automatically by bringing the selected make file information into ChangeMan DS. Use only upon selecting a valid make file. See “Importing an Existing Make File” in Serena™ ChangeMan® DS Administrator Guide.

Add to DS Control Put the selected files under ChangeMan DS source control by assigning them to a Production home area.


Eliminate the selected files from ChangeMan DS controlled status. This does not physically delete the files. Physical deletion of the files must be done by an authorized person in the native storage environment.

4


Right-Click Menu at the Area Name LevelChangeMan DS operations to be applied to an entire area are executed by selecting the area name node displayed on the left side of the ExplorerView.

The following table lists the primary options found in the area name node level right-click menu of the Web browser and Java clients:

Attach Associate the selected files with a designated project.

Promote Choose from a list of transfer activities for the selected files.

Refresh Update the currently displayed page with any recently added information.

Properties Display detailed status information for the selected file.

Command Description

Open Display the properties of the currently-selected area in the right side display.

Add to DS Control Put all files in the selected area under ChangeMan DS source control by assigning them to a Production home area.


Eliminate all files in the selected area from ChangeMan DS controlled status. This does not physically delete the files. Physical deletion of the files must be done by an authorized person in the native storage environment.

Attach Associate all files in the selected area with a designated project.

Promote Choose from a list of transfer activities for all files in the selected area.


Command Description

395

39


Right-Click Menu at the Folder LevelChangeMan DS operations to be applied to an entire folder can be executed by selecting the folder on the left side of the ExplorerView.

The following table lists the primary options found in the folder-level right-click menu of the Web browser and Java clients:

Right-Click Menu at the Project LevelChangeMan DS operations to be applied to an entire project are executed by selecting a project on the left side of the ExplorerView.

Command Description

Open Display the list of files in the currently selected folder in the right side display.

Add to DS Control Put all files in the selected folder under ChangeMan DS source control by assigning them to a Production home area.


Eliminate all files in the selected folder from ChangeMan DS controlled status. This does not physically delete the files. Physical deletion of the files must be done by an authorized person in the native storage environment.

Attach Associate all files in the selected folder with a designated project. See “Attaching Files” on page 81.

Promote Choose from a list of transfer activities for all files in the selected folder. See “Transferring Files and Projects” on page 95.


6


The following table lists the primary options found in the project level right-click menu of the Web browser and Java clients:

PERFORMANCE MONITORThe Performance Monitor displays the activity of ChangeMan DS’s processes as they are executing.

You can:

• View open sockets and threads. Most of the time, each thread has one socket open.

• Analyze the network traffic produced by the ChangeMan DS Windows client activities, including transfer activities.

• Stop the ChangeMan DS processes being monitored.

Configurations Description

Open Display the properties of the currently-selected project in the right side display.

Freeze Create a release of the project by capturing a point-in-time snapshot of the project Attachments and Make Procedures.See “Managing Releases” on page 203.

Show History Invoke the Audit Trail to view the transaction history of transfers, merges, and branches.See “Audit Trail” on page 213 for information.

Promote Choose from a list of transfer activities for the selected project.See “Transferring Files and Projects” on page 95.

Properties Display dialog for viewing and setting Working Location, Working Path, and IDE ChangeMan DS Properties.See “Using Projects” on page 63 for more information on project properties.


397

39


Initiate the Performance Monitor by one of the following:

• Click on the toolbar.

• Choose Performance Monitor from the Tools menu.

Leave the Performance Monitor dialog open while using other ChangeMan DS modules to view the performance information.

Note This module is primarily meant to help the Serena development team pinpoint problems while debugging ChangeMan DS. It is not recommended for use by the typical ChangeMan DS user.

Following are the explanations for each of the columns displayed for a thread (the top window of the dialog):

The displayed information for each thread disappears as soon as that thread has terminated.

Column Description

Thread Name Name of a thread for a currently executing process.

Type Type of thread.

Working Time Amount of time thread has executed in clock time. Format is HH:MM:SSwhere HH is 2-digit hours, MM is 2-digit minutes, SS is 2-digit seconds.

8


Following are the explanations for each of the columns displayed for a socket (the bottom window of the dialog):

The Total Sent and Total Received fields indicate the running total of socket I/Os sent and received for the duration of the ChangeMan DS session.

The buttons on the bottom of the dialog allow the following actions to be taken:

Column Description

Socket Name Name of a socket opened for a currently executing thread.

Type Type of socket.

Working Time Amount of time socket has been open in clock time. Format is HH:MM:SSwhere HH is 2-digit hours, MM is 2-digit minutes, SS is 2-digit seconds.

Sent Number of socket I/Os sent.

Received Number of socket I/Os received.

Button Description

Abort Thread Manually terminate the selected thread. Note: Do this only under instruction by Serena

Technical Support.

Close Socket Manually close the selected socket.Note: Do this only under instruction by Serena

Technical Support.

Close Monitor Exit the Performance Monitor.

399

40


FILE TREE UIThe file tree is a graphical representation of a file’s history. It lets you perform ChangeMan DS functions, such as merges, comparisons and promotions, on the various versions of the file.

Move and hold the mouse pointer over the desired icon to display history information.

The File Tree options that display in Web browser and Java clients are similar to the Windows File Tree options, but several of the button icons are different.

The following table lists the options at the top of the File Tree display for the Java, Web browser, and Windows clients:

Java/Web Client

Windows Client

Description

Compare versions. Click this button while two versions of the file are selected in the file tree to show the differences between them. See “Comparing Files” on page 143 for more information.

Merge files. Click this button while two versions of the file are selected in the file tree to merge the files. See “Merging” on page 153 for more information.

0


The following table lists the options located at the bottom of the File Tree display:

View file. Click this button to view the file.See “Viewing the Contents of a File” on page 54 for more information.

Edit the checked out file. Click this button to edit the checked out file.

N/A Show history. Click this button to launch the Audit Trail. See “Running Audit Trail Reports” for more information.

Refresh. Click this button to update the screen with the most current file status.

N/A Stop. Click this button to stop the process currently in progress.

N/A Print preview. Click this button to preview of the file tree printout.

N/A Print. Click this button to print the file tree.

Close the File Tree window and return to the ExplorerView.

Command Description

Check out. Click this button to retrieve a Production version of a file and create an identical copy in a target (usually Development) area.

Check in. Click this button to introduce a new version of a file to Production.

Java/Web Client

Windows Client

Description

401

40


ChangeMan Diff MENUS AND TOOLBARThe ChangeMan Diff window displays when you choose to show the differences between a file and its baseline version or when you choose to merge two files.

The ChangeMan Diff window displays the following toolbars:

• Standard

• Merge

• Diff Parameters

• Edit/View

The ChangeMan Diff menus have different options when depending on the client that you are in.

Promote to QA. Click this button to promote the file to a Quality Assurance area.

Promote to Development. Click this button to promote the file to a Development area.

Promote to Production. Click this button to promote the file to a Production area.

Distribute to End Users. Click this button to transfer the file from the Production area to an End User area.

Transfer ownership. Click this button to transfer files between like type areas, such as Development to Development

Cancel check out. Click this button to remove the check out status from the file.

Command Description

2


To help you, the following commands are available on the ChangeMan Diff utility Help menu and Standard Toolbar (Windows client):

These commands are not available on the Web browser client.

For more information:

• See “The following options are available from the Diff menu of the Web browser client:” on page 409 for the menus from the Web browser client.

• See “Merging” on page 153 and “Comparing Files” on page 143 for more information on the functions available from the ChangeMan Diff window.

File Menu—ChangeMan DiffThe ChangeMan Diff utility File menu and Standard toolbar consist of the following common tools:


Help > About ChangeMan Diff

About. Get version information for ChangeMan Diff.

Help > Help Topics

Help. Access Help for the module. Either:• Click this button, then click on the item for which

you want help.• Choose Help > Help Topics to view the entire

Help system.


File > Do diff Do diff. Click this button to perform a difference operation. This is useful when changes are made and a new compare is needed.See “Comparing Files” on page 143 for more information.

File > Do merge Do merge. Click this button to merge the compared files.See “Merging” on page 153 for more information.

File > Save Save. Save the changes made to the selected file.

403

40


Edit Menu—ChangeMan DiffThe ChangeMan Diff utility Edit menu, Standard toolbar, and Edit/View toolbar consist of the following common tools:

File > Save As Save as. Save the changed file under another name.

N/A Save and exit. Save the changes made and exit the file. This feature is available when merging files.

N/A Cancel and exit. Revert all changes made and exit the file. This feature is available when merging files.

File > Print Print. Print the active file.


Print preview. Preview the printout of the active file.

File > Print Setup N/A Print setup. Lets you change the printer and printing options.

File > Exit N/A Exit. Closes the ChangeMan Diff window.


Edit > Undo Undo. Undo the last change made.

Edit > Redo Redo. Reverse the last undone action.

Edit > Cut Cut. Remove the selected text.

Edit > Copy Copy. Copy the selected text.

Edit > Paste Paste. Paste the last copied or cut text.


4


Note that the toolbar buttons are not available on the Web browser client.

Merge Menu—ChangeMan DiffNote The Merge menu and toolbar buttons are not available on the Java

client, and the toolbar buttons are not available on the Web browser client.

The ChangeMan Diff utility Merge menu and Standard toolbar consist of the following common tools.See “Merging” on page 153 for more information on the following functions.

Edit > Select All N/A Select all. Selects the entire document.

Edit > Toggle bookmark

Toggle bookmark. Set a bookmark.

Edit > Next bookmark

Next bookmark. Go to the next bookmark.

Edit > Previous bookmark

Previous bookmark. Go to the previous bookmark.

Edit > Clear all bookmark

Clear All Bookmarks. Delete all bookmarks in the active file.

Edit > Find Find. Perform a search on the file.

Edit > Find Next Repeat. Repeat the last search done on a file. (Windows and Java Clients)

Edit > Next Error/Warning

N/A Next Error/Warning. Option disabled for merge and comparisons. (Java client)


405

40


Note that depending on the change, these functions can be accessed by right-clicking on the change.

Tools Menu—ChangeMan DiffThe Tools menu and Standard toolbar are not available on the Web browser client.

The ChangeMan Diff utility Tools menu and Standard toolbar consist of the following common tools:


Merge > Select/Deselect

Select/deselect. Select or deselect the highlighted line.

Merge > Reject changes

Reject changes. Reject the changes made.

Merge > Accept default

Accept default changes. Accept the changes made.

Merge > Accept from 1st file

Accept from first file. Accept the version of the line from the first file.

Merge > Accept from 2nd file

Accept from second file. Accept the version of the line from the second file.

Merge > Accept from common file

Accept from common ancestor. Accept the version of the line from the common ancestor.


Tools > Options Options dialog. Open the Diff Merge Manager to set options for file comparison.

6


See “View Options—ChangeMan Diff” on page 408 for additional options available when you select Tools > Options in the Java and Windows clients.

View Menu—ChangeMan DiffThe ChangeMan Diff utility View menu, Standard toolbar, and Edit/View toolbar consist of the following common tools for controlling the display:

Tools > Template Manager

Template manager. Open the Template Manager.

Tools > Set Template(Windows only)

Drop-down list (Java client only)

Lets you select the template to use with this file.


View > Toolbar N/A Toggles the display of the toolbar.

View > Status Bar N/A Toggles the display of the status bar.

View > Split Split. Split the active window into multiple panes.

View > Show/Hide Map

Show map bar. Show or hide the map bar along the left side of the screen.

View > Diff mode N/A Displays a two window view of the comparison files.

View > One Window diff

N/A Displays a one window view of a comparison file.

View > Merge mode

N/A Switches to merge mode view. Use after you have performed a merge.

View > Diff Output

N/A Displays a list of the changes and when they occurred for the current comparison files.


407

40


View Options—ChangeMan DiffThe following ChangeMan Diff View options can be set on the Diff Parameters toolbar or on the Diff tab of the Diff Merge Manager dialog.

View > Zoom In Zoom. Zoom into and out of the active file. Zooming in displays only the active file.

View > Synchronize Views

Align source code. Align the two files so the same source code lines are displayed next to each other.

N/A Toggle Marker Bar. Show or hide the Marker Bar.

N/A Toggle Ruler Bar. Show or hide the Ruler Bar.

N/A Toggle Line Number Bar. Show or hide the Line Number Bar.

N/A > Toggle Modification Date Bar. Show or hide the Modification Date Bar.

N/A Previous change. Move to the previous change.

N/A Next change. Move to the next change.


8


See “Merging” on page 153 and “Comparing Files” on page 143 for more information on the following functions.

Diff Menu—ChangeMan DiffThe following options are available from the Diff menu of the Web browser client:


Tools > Options(Java and Windows client)Diff > Ignore Case (Web browser client)

Ignore case. Ignore case when comparing code.

Tools > Options(Java and Windows client)Diff > Ignore Comments(Web browser client)

Ignore comments. Ignore comments when comparing code.

Tools > Options(Java and Windows client)Diff > Ignore Blank Line(Web browser client)

Ignore blank line. Ignore blank lines when comparing code.

Tools > Options(Java and Windows client)Diff > Ignore Spaces(Web browser client)

Ignore spaces. Ignore spaces when comparing code.

Option Description

Diff > Previous Change Moves the displayed code to the previous change.

Diff > Next Change Moves the displayed code to the next change.

Diff > Ignore Case Ignore case when comparing code.

Diff > Ignore Comments Ignore comments when comparing code.

409

41


CHANGEMAN EDIT MENUS AND TOOLBARSChangeMan DS Edit modifies and compiles files controlled by ChangeMan DS.

ChangeMan Edit Module contains the following menus and toolbars:

• See “ChangeMan Edit Module” on page 437 for more information on ChangeMan Edit.File Menu—ChangeMan Edit

• Edit Menu—ChangeMan Edit

• Find Toolbar—ChangeMan Edit

• View Menu—ChangeMan Edit

• Window Menu—ChangeMan Edit

• Tools Menu—ChangeMan Edit

To view your version of ChangeMan Edit, either click on the Standard toolbar, or choose Help > About ChangeMan Edit.

You can customize some components of the displayed screen by toggling corresponding options from the View menu.

The title bar displays the IP address of the host where the selected file is located, the full name of the file, and the Edit template.

Diff > Ignore Blank Line Ignore blank lines when comparing code.

Diff > Ignore Spaces Ignore spaces when comparing code.

Option Description

0


See “ChangeMan Edit Module” on page 437 for more information on ChangeMan Edit.File Menu—ChangeMan Edit

The File menu and Standard toolbar consist of the following common tools:

Edit Menu—ChangeMan Edit The Edit menu and Standard toolbar consist of the following common tools:


File > New New document. Select a template for a new document.

File > Open Open. Open an existing file.

File > Close N/A Closes the active document.

File > Save Save. Save the active file on the host of your choice.

File > Save As N/A Save the active file under a different name.

File > Save All Save all. Save all open files.

File > Print Print. Print the contents of the active file.

File > Print Setup N/A Lets you change printers and printing options.

File > Recent Documents

N/A Lets you open a document that was recently opened with ChangeMan Edit.

File > Exit N/A Exit. Closes the ChangeMan Edit window.


Edit > Cut Cut. Remove what is currently selected in the active file.

Edit > Copy Copy. Copy what is currently selected in the active file.

411

41


See “Find Toolbar—ChangeMan Edit for commands available in the Edit menu and Find toolbar.

Find Toolbar—ChangeMan Edit The Find toolbar and Edit menu help you search your files for text, and they allow you to place, and search bookmarks.

Edit > Paste Paste. Paste a previously copied or cut item into a target location.

Edit > Select All N/A Selects all of the contents.

Edit > Undo Undo. Undo the last action command.

Edit > Redo Redo. Redo a previously undone action.


Edit > Toggle Bookmark

Toggle bookmark. Set or clear a bookmark.

Edit > Next Bookmark

Next bookmark. Go to the next bookmark in the document.

Edit > Previous Bookmark

Previous bookmark. Go to the previous bookmark in the document.

Edit > Clear All Bookmarks

Clear all bookmarks. Clear all bookmarks in the active document.

Edit > Find Find. Open the Find dialog box.

Edit > Find Next Repeat. Repeat the last find operation.

Edit > Replace N/A Opens the Replace dialog.


2


See “View Menu—ChangeMan Edit” for additional commands on the View menu.

View Menu—ChangeMan EditThe View menu and Standard toolbar consist of the following common tools:

Window Menu—ChangeMan EditNote that open content windows are listed on the bottom of the Window menu. You can choose one to move its display to the front.

Edit > Next error/warning

Next error/warning. Go to the next error or warning message.

Edit > Impact Analysis

Impact analysis. Run Impact Analysis process for the selected item.


View > Toolbar N/A Show or hide the toolbars.

View > Status Bar N/A Show or hide the status bar.

View > Output Window

Toggle Output Bar. Show or hide the output window.

View > Marker Bar

Toggle Marker Bar. Show or hide the Marker bar.

View > Ruler Bar Toggle Ruler Bar. Show or hide the Ruler bar.

View > Line Number Bar

Toggle Line Number Bar. Show or hide the Line Number bar.

View > Modification Date Bar

Toggle Modification Date Bar. Show or hide the Modification Date bar.


413

41


The Window menu and Standard toolbar consist of the following common tools:

Tools Menu—ChangeMan Edit The Tools menu and Tools toolbar provides access to ChangeMan Edit tools.


Window > New Window

N/A Opens a second content window of the displayed code.

Window > Cascade

N/A Cascades the open content windows.

Window > Tile N/A Tiles the open content windows.

Window > Arrange Icons

N/A Arranges the minimized windows on the bottom of the screen.

Window > Split Split. Split the active window into multiple panes.


Tools > Save & Compile

Save compile. Save the current document and start execution of a compiler script.

Tools > Run Command

Run remote command. Start execution of a compiler script without automatically saving the file.

View > Monitor Monitor. View the ChangeMan Edit Performance Monitor.

Tools > Template Manager

Template manager. Open the Template Manager.

Tools > Error Output Script

Output script. View the result of executing the compiler script.

Tools > Output Window Properties

N/A Opens the Output Window Properties dialog which sets the font type for the output script window.

4


See “View Menu—ChangeMan Edit” for the Monitor button on the Tools toolbar.

415

41


6


417

41


8


419

42


0


421

42


2


423

42


4


425

42


6


427

42


8

CHANGEMAN DIFF MODULE
C
The ChangeMan Diff module is invoked when you merge or compare files.

There are three flavors of the module depending on your client (Windows, Java, and Web Browser), and the screen changes depending on whether you are merging or comparing files:

• Comparing Files—When you are comparing usually has two panels, a map, and a status bar. The following functionality is available when you are comparing files:

— “Altering the Display Mode” on page 430

— “Changing Display Options” on page 431

— “Changing Text Background Colors in ChangeMan Diff” on page 431

— “Merging the Files from a Comparison” on page 432

— “Selecting Templates” on page 433

— “Synchronizing Displayed Lines in ChangeMan Diff” on page 434

— “Toggling Display of Map and Status Bar” on page 435

— “Using Bookmarks” on page 444

See “Text-Based Comparisons” on page 147 for more information on comparing files with ChangeMan Diff.

• Merging Files—When you are comparing usually has two panels, a map, and a status bar. The following functionality is available when you are merging files:

— “Accepting/Rejecting Changed Lines during a Merge” on page 430

— “Editing the Merged File in ChangeMan Diff” on page 432

— “Altering the Display Mode” on page 430

— “Changing Display Options” on page 431

— “Changing Text Background Colors in ChangeMan Diff” on page 431

— “Performing a Comparison while Merging Files” on page 433

— “Merging the Files from a Comparison” on page 432

— “Editing the Merged File in ChangeMan Diff” on page 432

429

43

Chapter C: ChangeMan Diff Module

— “Performing a Comparison while Merging Files” on page 433

— “Saving and Exiting the Merge” on page 434

— “Selecting Templates for ChangeMan Diff” on page 434

— “Synchronizing Displayed Lines in ChangeMan Diff” on page 434

— “Toggling Display of Map and Status Bar” on page 435

— “Using Bookmarks” on page 444

ACCEPTING/REJECTING CHANGED LINES DURING A MERGE

For changed lines, you can right-click and Accept Changes or Reject Changes, or you can choose the change from a particular file by choosing Accept from First File, Accept from Second File, or Accept from Common Ancestor.

ACCEPTING/REJECTING INSERTED LINES DURING A MERGE

For inserted lines, right-click on the line and the choose either Unselect Block (reject) or Select Block (accept).

ALTERING THE DISPLAY MODEChange the display mode by choosing options on the View menu:

This option... Does this...

Split Lets you split the window using your mouse. The split can be altered by dragging the edge of the split.To remove the split (Windows and Java client), drag the edge out of the window.To remove the split (Web browser client), deselect View > Split.

Hide/Show Map Toggles the display of the Map.

0


CHANGING DISPLAY OPTIONS

Change the display options to ignore items such as blank lines, extra spaces, and case by choosing Tools > Options, or by clicking the appropriate button on the Diff Parameters tool bar.

CHANGING TEXT BACKGROUND COLORS IN CHANGEMAN DIFF

You can change the colors displayed by the ChangeMan Diff utility by choosing Tools > Options (except for the identical code which displays as white).

The default color categories mean the following:

Diff Mode Displays a two window view of the comparison files.

One Window Diff Displays a one window view of a comparison file.

Merge Mode Displays the merge mode view. ChangeMan DS invokes this view when you perform a merge.Not available in Web browser client.

Diff Output Displays changes in a text-based report form (similar to Unix Diff).

This category… Indicates… Default color…

Inserted lines Added lines. Yellow

Deleted lines Deleted lines. Red

Merged lines (Used in Merge Mode.) A line which is:• different in the two files being merged,• merged without conflict. and• selected as final merge result.

Green

This option... Does this...

431

43


EDITING THE MERGED FILE IN CHANGEMAN DIFFYou can edit any part of the merge file by placing your cursor in the line, then overtyping.

You can also cut code from File 1, File 2, or the Common Ancestor and paste into the merge file.

See “Editing Text in a Code Window” on page 438 for more information on editing text.

MERGING THE FILES FROM A COMPARISONYou can merge files that you were comparing in ChangeMan Diff.

If you don’t know the ancestor file, exit the utility, then merge both files. See “Merging” on page 153.

If you know the ancestor of the two files, you can perform a merge on the files by choosing File > Do Merge from the toolbar. You are prompted to select an ancestor file. After choosing the ancestor, the display changes to the Merge mode, and you can now perform an Interactive Merge. See “Merging” on page 153 for more information.

Not available in the Web browser client.

Virtual lines Placeholders. It means the other file contains a line here that this file doesn’t.

Gray

Changed lines Changed lines. Blue

Inserted from common file

Lines found in the common ancestor file. This appears only if each of the three files has a different change for a common line.

Red

Inserted from 1st file New lines added from the first file. Yellow

Inserted from 2nd file New lines added from the second file. Green

Overlapped block Block of text that appears in both documents. Blue

Merge Unselected Deselected lines. Gray

This category… Indicates… Default color…

2


NAVIGATING CHANGES DURING MERGE IN CHANGEMAN DIFF

Step through the changes in a file by placing the cursor in the file, then clicking either Next Change or Previous Change .

PERFORMING A COMPARISON WHILE MERGING FILES

To perform a comparison of the files (and discard changes to the merge file), choose

either File > Do Diff or Do Diff on the toolbar, then change to the comparison view by choosing View > Diff Mode. See “Comparing Files” on page 143 for more information.

REDOING A COMPARISON IN CHANGEMAN DIFFRedo the comparison by choosing File > Do Diff.

Not available in the Web browser client.

REDOING A MERGE IN CHANGEMAN DIFFTo discard changes and redo the merge file, choose either File > Do Merge or Do Merge on the toolbar.

On the Web browser client, choose File > Merge.

Note that your changes will be lost, even if you have selected File > Save.

SELECTING TEMPLATESAdd or edit templates for the ChangeMan Diff utility to define how ChangeMan DS displays the text.

433

43


The ChangeMan Diff utility’s Template Manager is identical to the ChangeMan Edit Template Manager: See “Template Manager” on page 456 for details on configuring the different Template Manager tabs.

Change the template used to display the code by choosing Tools > Set Template.

Note that the Merge Colors override syntax colors of the Template Manager.

SAVING AND EXITING THE MERGEAfter you have completed the merge, save the merge file by either choosing File > Save or clicking Save on the toolbar.

If you only select Save and don't exit the utility, your changes are saved in the metadata repository, and will be lost if you perform another merge by choosing File > Do Merge.

To exit and discard changes to the merged file, click the close button and reply No to the prompt.

SELECTING TEMPLATES FOR CHANGEMAN DIFFAdd or edit templates for the ChangeMan Diff utility to define how it displays the text.

The ChangeMan Diff utility’s Template Manager is identical to the ChangeMan DS Edit Template Manager: See “Template Manager” on page 456 for details on configuring the different Template Manager tabs.

Change the template used to display the code by choosing Tools > Set Template.

Note that the Merge Colors override syntax colors of the Template Manager.

SYNCHRONIZING DISPLAYED LINES IN CHANGEMAN DIFF

To toggle the synchronization between the files, choose View > Synchronize Views.

4


TOGGLING DISPLAY OF MAP AND STATUS BARTo display (or hide) the Map, choose View > Show Map (or View > Hide Map).

On the Web browser client, select or deselect View > Show/Hide Map.

To display (or hide) the Status Bar, choose View > Show Status Bar (or View > Hide Status Bar). You cannot toggle the Status Bar on the Web browser client.

435

43


6

CHANGEMAN EDIT MODULE
D
ChangeMan DS includes a full-function editor for convenient development and modification of files. ChangeMan Edit allows programmers to use the familiar Microsoft Windows GUI while working on files on UNIX and Microsoft Windows hosts.

The ChangeMan Edit development environment consists of the following components:

For information on opening a file with ChangeMan Edit, see “Editing a File with ChangeMan Edit” on page 56.

See “Setting the Editor” on page 55 for choosing ChangeMan Edit as the default editor launched from the ChangeMan DS interface.

This Component... Performs this task...

Code Window Provides a programming editor where you can view and modify the source code. The Code Window provides such features as color-coding of key words, auto formatting, undo/redo, find/replace, and numbered line support for third-generation languages.

Output Window Provides real time output from compilers based on remote hosts.

Impact Analysis Result Window

Shows the results of the online Impact Analysis process, which helps you to identify all files that use a specific entity.

Command Execution Window

Lets you execute the operating system commands on remote hosts.

Template Manager

Configures custom preferences for source editing, file formatting, and other display options associated with various programming languages.

437

43

Appendix D: ChangeMan Edit Module

EDITING TEXT IN A CODE WINDOWChangeMan Edit and ChangeMan Diff let you modify host-based files like you do in most Windows-based word-processing or development utilities.

Note You can only edit the merged file in ChangeMan Diff.

Once you have identified the point at which you want to begin editing, and you have set the insertion point, a flashing cursor is displayed. The current cursor position is always shown on the Ruler Bar and Line Number bar.

ChangeMan Diff and ChangeMan Merge allow you common word-processing functions such as:

• Finding Text

• Replacing Text

• Undo and Redo Commands

When editing more than one character, identify a selections with the following:

• To create a selection, place the insertion point at the start of the selection, hold the mouse button down, and drag the insertion point to the end of the selection.

• To remove an existing selection, click anywhere in the editable area, or press one of the arrow keys.

• To extend or restrict an existing selection, move the insertion point using either the mouse or keyboard while keeping the Shift key pressed.

The following topics describe how to move, copy, and paste text selections in ChangeMan Edit and the ChangeMan Diff merge file:

• Moving a Selection Using Commands

• Copying a Selection Using Commands

• Moving a Selection Using the Drag-and-Drop Method

• Copying a Selection Using the Drag-and-Drop Method

If you are unfamiliar with how to navigate in Windows-based word processing utilities, see Navigating the Text in Code Window.

8


Copying a Selection Using CommandsIn ChangeMan Edit or ChangeMan Diff, use the following procedure to copy a selection:

The Copy command can be used to copy selections in the same file, in different files opened in the Edit module, or between Edit and other Microsoft Windows programs.

The following example shows a file opened in ChangeMan Edit with the split window option. You can use this feature to copy your selection in the large file.

ChangeMan Edit uses the clipboard for all text movements. The clipboard is a shared resource that allows all Microsoft Windows applications to provide a temporary location for storing data that need to be moved/copied.

To copy a selection, you can also use a shortcut key combination such as Ctrl + C or Ctrl + V for the copy/paste commands.

Step Action

1. Make a selection.

2. Click Copy or choose Copy from the Edit menu.

3. Bring the insertion point to a new location.

4. Click Paste or choose Paste from the Edit menu.

439

44


Copying a Selection Using the Drag-and-Drop MethodIn ChangeMan Edit or ChangeMan Diff, use the following procedure to copy a selection:

Finding TextUse this procedure to find a text string in ChangeMan Edit or ChangeMan Diff:

To resume the Find search for the previously-defined criteria, click Repeat .

Step Action


2. Point to the selected text and hold down the left mouse button.

3. Drag the insertion point to the new location.

4. Press and hold CTRL while releasing the mouse button.

Step Action

1.Click Find , or choose Find from the Edit menu.ChangeMan DS displays the Find dialog box.

2. In the Find dialog box, enter the text to find.

3. You can customize your search by setting the following options:• Match whole words only - Select this option to find the whole

words, not parts of words, that match the text displayed in the Find what box.

• Match case - Select this option to find the text with the same capi-talization as the text displayed in the Find what box.

4. Click Find Next to start the search process.ChangeMan Edit highlights the next occurrence of the search text that matches the criteria.The Find dialog uses your current selection as the initial criteria to be displayed in the Find what box.

0


Moving a Selection Using CommandsIn ChangeMan Edit or ChangeMan Diff, use the following procedure to move a selection:

Moving a Selection Using the Drag-and-Drop MethodThe drag-and-drop method is a simple way to move or copy a limited selection a relatively short distance.

In ChangeMan Edit or ChangeMan Diff, use the following procedure to move a selection:

Navigating the Text in Code WindowNavigate the code windows in ChangeMan Edit and ChangeMan Diff the same way that you do other Windows-based word-processing or development utilities:

• Use the scroll bars to the right and bottom of the code window to scroll the editable area of the window.

• Use the mouse or keyboard to position the insertion point on a line of code:

Step Action


2. Click Cut or choose Cut from the Edit menu.

3. Bring the insertion point to a new location.

4. Click Paste or choose Paste from the Edit menu.

Step Action


2. Point to the selected text and hold down the left mouse button.

3. Drag the insertion point to the new location.

4. To move the text, release the mouse button.

441

44


— To use the mouse, scroll the editable area using the scroll bars, position the cursor, then click the left mouse button.

— If you use the keyboard to position the insertion point, ChangeMan Edit automatically scrolls the editable area to ensure that the new insertion point is always visible.

The current cursor position is always shown on the Ruler Bar and Line Number bar.

The following is a list of keyboard navigation commands available for a file opened in ChangeMan Edit and ChangeMan Diff.

Press… To Move…

Right arrow One character to the right.

Left arrow One character to the left.

Ctrl + Right arrow One word to the right.

Ctrl + Left arrow One word to the left.

Down arrow To the next line.

Up arrow To the previous line.

Page Down To the next non-visible line.

Page Up To the previous non-visible line.

Ctrl + Home To the start of the file.

Ctrl + End To the end of the file.

Home To the start of the current line.

End To the end of the current line.

2


Replacing TextUse this procedure to replace one text string with a different string:

Undo and Redo CommandsIf you make a mistake in the Code Window, you can undo your last action or commands. For example, if you delete a selection you can easily restore it.

To undo the last action, click Undo from the Standard toolbar, or select Undo from the Edit menu.

As you make changes in the Code Window, ChangeMan Edit records all of your actions, and lets you undo them if necessary. The number of actions that you can undo is based on the amount of available RAM.

Step Action

1. Choose Replace from the Edit menu.ChangeMan DS displays the Replace dialog.

2. In the Find what field, type the text to be replaced.

3. In the Replace with field, enter the replacement text.

4. Select the match search criteria (if necessary).

5. Determine how you want the search to proceed by choosing from the following options:

Click… To…

Replace Replace the text and find the next occurrence.

Replace All Change all occurrences of your selection without confirmation.

Find Next Leave the text unchanged and search for the next occurrence.

Cancel (or press ESC)

Cancel a search in progress or close the dialog box.

To undo the effects of the last replacement, choose Undo from the Edit menu. This will reverse the last change made.

443

44


After you undo the last action, you may realize that you need it after all. In this case, you can use the Redo command.

To redo the previously undone action, click Redo from the Standard toolbar, or select Redo from the Edit menu.

USING BOOKMARKSBookmarks provide a convenient way to mark specific lines in a file and enable you to quickly jump to the next/previous bookmark or cycle through all of the bookmarks.

Note Bookmark functionality is identical for ChangeMan Edit and the ChangeMan Diff utility.

To use bookmarks, you must display the marker bar. See “Displaying Marker Bar” on page 453 for more information.

The following topics describe using bookmarks:

• “Placing a Bookmark” on page 444

• “Removing a Bookmark” on page 445

• “Navigating to Bookmarks” on page 445

Notes for the Java Client

• ChangeMan Edit for the Java Client has a Marker tab in the Output Window, which lists all of your bookmarks.

• ChangeMan Diff for Java Client doesn't allow the insertion of bookmarks.

Placing a BookmarkUse this procedure to place a bookmark in ChangeMan Edit or ChangeMan Diff:

Step Action

1. Place the cursor in the text where you wish to insert a bookmark.

2. Either:

• Click .

• Choose Toggle Bookmark from the Edit menu.The bookmark symbol is placed on the Marker Bar for the that line.

4


Removing a BookmarkUse this procedure to remove a bookmark in ChangeMan Diff or ChangeMan Edit:

Navigating to BookmarksUse these actions to navigate bookmarks in ChangeMan Diff or ChangeMan Edit:

IMPACT ANALYSIS FROM CHANGEMAN EDITChangeMan Edit gives you access to the Impact Analysis module from the Code Window. This feature provides you with a way to identify all files that use a selected element. In addition, you can view or edit discovered files, as well as attach them to a project.

Step Action

1. Place the cursor in the line containing the bookmark.

2.Click Toggle Bookmark , or choose Toggle Bookmark from the Edit menu.The bookmark symbol is removed from the Marker Bar.

To… Do this…

Move to the next bookmark. • Click

• Choose Next Bookmark from the Edit menu.

Move to the previous bookmark

• Click • Choose Previous Bookmark from the Edit menu.

Remove all bookmarks in the active document

• Click • Choose Clear All Bookmarks from the Edit

menu.

445

44


The following procedure describes how to perform Impact Analysis from the code window.

Each time you invoke Impact Analysis in ChangeMan Edit, you receive a fresh set of data, which disregards previous searches. This function has the same effect as clicking the New Search button from the Impact Analysis screen.

ChangeMan DS Edit displays results in the following columnar format:

• Type

• File

• Area

• Path

Right-click on one of the records displayed on the report to view the list of the following commands:

• View - to open the selected file with ChangeMan Edit.

• Attach - to attach the selected file to a project.

See “Attaching Files” on page 81 for more information on attaching files to projects.

RUNNING A REMOTE COMMANDIn addition to compilation procedures, ChangeMan Edit can also execute simple commands on the remote server. The executed commands should contain all necessary parameters and not require any interactive user input.

Step Action


2.Click Impact Analysis or choose Impact Analysis from the Edit menu.The result of this Impact Analysis search displays in the Impact Analysis Result window.

6


Use this procedure to run a command on a remote server:

COMPILING A FILEChangeMan Edit offers access to the server-based compilers by executing a command on the remote server.

The server command should contain all parameters necessary for the successful execution of this command. In other words, it must not require any additional input from the user.

ChangeMan Edit saves all files that have been changed before compiling. This is done to ensure that any errors or warnings generated by the compiler can be correctly identified in the code window.

Step Action

1. Click Run Remote Command (or choose Run Command from the Tools menu).The Command Execution screen displays.

2. Enter the registration/login information.

3. Enter the command(s) to be executed on the remote host.

4. Click Start.The result displays in the output window.ChangeMan Edit automatically clears the result of the previous command prior to executing the next command.

447

44


Use this procedure to compile a file:

Choose Output Window Properties from the Tools menu to customize the way data displays in the Output Window.

COMPILE RESULT SCRIPT

The resulting output from a compile command can produce many lines, even when successful. Examining every line of the output, checking for warnings and errors can be a time-consuming process.

Step Action

1. Select the file.

2. Click Save Compile (or choose Save & Compile from the Tools menu).If the source file is located on a UNIX or Microsoft Windows host, ChangeMan Edit displays the following screen:

3. Enter the registration information. This information is required for the system security, and to give you the option of executing compilation scripts on different hosts.

4. You can write your own commands, or click Open to find an existing script.

5. Click Start to initiate script execution.Once executed, ChangeMan Edit traps the script’s output and displays it in the output window.

8


To assist programmers with this task, ChangeMan Edit can identify possible warnings and errors in the compiler output, and highlight those lines for closer examination. The Compile Result Script provides ChangeMan Edit with the instructions for identifying the lines.

Configuring Compile Result ScriptUse this procedure to configure a script that will analyze the compiler output:

Step Action

1. Click Output Script (or choose Error Output Script from the Tools menu).This window displays:

2. Click Select Variables . ChangeMan Edit displays the list of available variables and predefined compilers. The script can include any number of literal fields or variables from the list.One script can handle output from different compilers.

3. Create your custom script (or click Open to find an existing script).

449

45


Viewing Next Error or WarningUse this procedure to view the next error or warning:

Clearing Compile Command ResultsUse this procedure to clear the results of a Compile command:

4. Click Save to store a new script.When you have configured a compile result script, you can navigate through the output and review each error or warning.ChangeMan Edit does the following to indicate a line with error:• Places an error mark in the Marker Bar for the corresponding line.• Highlights the line number.• Highlights the output number.

Step Action

1. Press the F4 key.

2.Click the Next Error/Warning button.

3. Choose Next Error/Warning from the Edit menu.

4. Right-click inside the output window, then choose the Next Error command from the right-click menu.

Step Action

1. Right-click inside the output window.

2. Choose Clear from the right-click menu.This operation erases the content of the output window.

Step Action

0


SAVING A FILEChangeMan Edit provides Save and Save As options for saving files.

When you change a file, a date tag appears in the Modification Date Bar next to the changed line, indicating that the file has been modified. The modification date tag disappears when you save the file, and reappears when you make new changes to the file.

Saving File with Original Name

To save a file using the original name, click Save (or choose Save from the File menu). ChangeMan Edit checks the file for changes since it was last loaded or saved; if no changes are detected, the Save command is disabled.

All UNIX or Microsoft Windows files are saved automatically, without any prompts for additional information.

If you have more than one file opened for editing, you can save changes to all files by selecting the Save All command.

You can also save the changes to a new file.

Saving a File Under a Different NameUse this procedure to save files with a different name:

CREATING A NEW FILEChangeMan Edit lets you create a new file directly from the Edit module.

Step Action

1. Choose Save As from the File menu.Note: ChangeMan Edit saves new files on your local workstation.

2. Navigate to the folder into which the file is to be saved.

3. Enter the new name of the file in the File name box.

4. Click Save.

451

45


When creating new files, you first identify the Code Editor Template (which determines the format of the new file, whether the file contains line numbers, general language characteristics, and rules for handling special characters).

Use this procedure to create the file:

When you finish editing a new file, save it with the Save As command.

TOGGLING DISPLAY ITEMSChangeMan Diff and ChangeMan Edit contain different display items that help you to easily edit your code.

The Marker Bar shows the location of your bookmarks.

The Ruler Bar and Line numbers represent the current cursor location. As the insertion point is moved in the Code Window, the status bar displays the current line number and character position, where the first number indicates the ruler position and the second the line number.

The Status Bar shows either a color key for your text or the location of your cursor.

See the following topics for information on toggling these items:

• Displaying Line Numbers

• Displaying the Marker Bar

• Displaying the Ruler

• Displaying the Status Bar

Step Action

1.From ChangeMan Edit, click New Document (or choose New Document from the File menu).ChangeMan Edit displays a list of all the configured editor templates.

2. Select a template, then click OK.ChangeMan Edit opens a blank code window.

2


Displaying Line Numbers

All line numbers are displayed to the left of each line shown in the Code Window of ChangeMan Diff and ChangeMan Edit.

See “Template Manager” on page 456 for more information about line numbering for different templates.

For Windows Clients• To display line numbers, click Toggle Line Number Bar , or select View >

Line Number Bar.• To hide line numbers, click Toggle Line Number Bar , or deselect View >

Line Number Bar.• Note that on ChangeMan Diff, you must place your cursor in the code window that

you want the line numbers to display before clicking .

For Java and Web Browser Clients• To display the line numbers, select View > Line Number Bar.• To hide the line numbers, deselect View > Line Number Bar.

Displaying Marker BarMarker bar displays the bookmarks that you have inserted in the code.

See “Using Bookmarks” on page 444 for more information on using bookmarks to navigate code.

For Windows Clients• To display Marker Bar, click Toggle Marker Bar , or select View > Marker

Bar.• To hide Markers, click Toggle Marker Bar , or deselect View > Marker Bar.

Note Note that on ChangeMan Diff, you must place your cursor in the code

window that you want the Marker Bar to display before clicking .

For Java ClientsChangeMan Diff doesn't allow bookmarks, so it doesn't have a marker bar.

453

45


ChangeMan Edit doesn't let you toggle the marker bar on the left of the code window. Note that on the Java client the bookmarks also appear as a list on the Markers tab of the Output window.

For Web Browser Clients• To display the Marker Bar, select View > Marker Bar.• To hide the Marker Bar, deselect View > Marker Bar.

Displaying the RulerThe Ruler Bar provides a visual indication of the character position relative to the first character of each line.

For Windows Clients• To display the Ruler Bar, click Toggle Ruler Bar or select View > Ruler Bar.• To hide the Ruler Bar, click Toggle Ruler Bar or deselect View > Ruler Bar.

Note Note that on ChangeMan Diff, you must place your cursor in the code window that you want the ruler to display before clicking .

For Java and Web Browser Clients• To display the Status Bar, select View > Ruler Bar.• To hide the Status bar, deselect View > Ruler Bar.

Displaying the Status BarThe ChangeMan Diff and ChangeMan Edit modules include a status bar on the bottom of the screen, which either contains a color key (ChangeMan Diff) or the cursor location (ChangeMan Edit).

For Windows Clients• To display the Status Bar, choose View > Show Status Bar.• To hide the Status bar, choose View > Hide Status Bar.

You cannot toggle the Status Bar on ChangeMan Edit (Windows client).

4


For Java Clients• To display the Status Bar, select View > Status Bar.• To hide the Status bar, deselect View > Status Bar.

For Web Browser ClientsYou cannot toggle the Status Bar on the Web browser client.

CHANGEMAN EDIT VARIABLESIf desired, you may specify variables in the Editor’s Tools > Run Command so that you do not have to type the file name, path, or user each time for a command that you run regularly. The following variables can be used directly in the Run Command entry box to accomplish this.

• sgfile—contains name of file currently open in the ChangeMan DS Editor.

• sgpath—contains path for file currently open in the ChangeMan DS Editor.

• sguser—contains name of user requesting run remote command in the ChangeMan DS Editor.

Examples:

If you were editing a file called proga.c in path D:\ChangeMan\Prod\proga.c,

This: cl %sgpath%\%sgfile%

Yields: cl D:\ChangeMan\Prod\proga.c

The preceding example would compile the program proga.c upon clicking Start.

On Windows, variable names are enclosed by % (percent) symbols.

On UNIX, variable names are prefixed with a $ (dollar) sign.

So the equivalent example for UNIX would read:

This: cl $sgpath/$sgfile

Yields: cl /ChangeMan/Prod/proga.c

You may save commands to a file by clicking Save, and retrieve saved commands by clicking Open.

455

45


TEMPLATE MANAGERThe ChangeMan Edit and ChangeMan Diff utilities support programming languages such as C, C++, Java, Cobol, and Fortran. Each language has unique requirements for content editing, syntax highlighting, line numbering, and formatting. To support these variations, the utilities use a Template Manager, which describes the settings required by each language.

A number of standard templates are provided for programming languages. These templates supply most common options for each language.

Furthermore, you can create custom templates. Note that when you create a custom template in the Windows client, it is not available in the Java Client and Web browser clients. And vice-versa, if you create a template in the Java Client and Web browser clients, it is not available in the Windows client.

To create and manage the templates, you use the template mapper.

Please review the settings for the Templates prior to using them.

See “Comparing Files” on page 143 and “Merging” on page 153 for more information on using the ChangeMan Diff utility.

Opening the Template ManagerTo open the Template Manager, click the Template Manager button (or choose Template Manager from the Tools menu).

The following screen displays:

6


The Template Manager window is divided into two panes. The left pane displays a list of available templates. The right pane displays settings for the currently-selected template.

See “Template Manager Tabs” on page 460 for information on the tabs in the right pane.

The following procedures describe operations you can perform at the template level:

• “Creating a New Template” on page 457

• “Copying a Template” on page 458

• “Deleting a Template” on page 458

Creating a New TemplateUse this procedure to create a new template:

To simplify the process of creating a new template, you have the option of copying an existing template to a new one.

Step Action

1. Open the Template Manager.

2. Click Add Template .ChangeMan DS displays the following dialog box:

3. Enter a new template name and description.

4. Click OK.ChangeMan DS creates a new blank template. You must go through all of the options to define characteristics of this template.

457

45


Copying a TemplateUse this procedure to copy a template:

Deleting a TemplateUse this procedure to delete a template:

Modifying a List of KeywordsYou modify the list of keywords recognized by ChangeMan Edit and ChangeMan Diff on the Keywords Tab of the Template Manager.

Step Action

1. Open the Template Manager, then select the template to copy.

2. Click Copy Template .

ChangeMan DS displays the following dialog:

3. Enter the name and description of the new template.

4. Click OK.ChangeMan DS creates a new template with all the characteristics of the template you copied.

Step Action

1. Open the Template Manager, then select the template to delete.

2. Click Remove Template .

8


Use this procedure to modify the list of keywords:

Configuring Auto Line NumberingYou configure Auto Line Number for ChangeMan Edit and ChangeMan Diff on the Advanced Tab of the Template Manager.

Use this procedure to configure automatic line numbering:

If the Use to Show Errors option is selected, ChangeMan Edit highlights the line where a compiler error occurred.

ChangeMan Edit provides variables that can be used in the Modification Date Bar to represent day, month, year, and century. The following screen shows the list of variables representing the modification date.

Step Action

1. Open the template manger. See “Opening the Template Manager” on page 456 for more information.

2. Define the set of keywords to modify on the Keywords tab.

3. Click inside the list.

4. Add, delete, or edit words.

5. Click Apply to implement the changes.

Step Action


2. Select the Auto Line Numbering box on the Advanced tab.

3. Type (or select) a Start number value.

4. Type (or select) Number increment and Digits values.

5. Click Apply.

459

46


When the file is open for editing, ChangeMan Edit indicates the added and modified lines in the Marker Bar.

Changing ColorsYou configure the display colors for ChangeMan Edit and ChangeMan Diff on the Colors Tab of the Template Manager.

Use this procedure to change the background or foreground colors:

Template Manager TabsThe right pane of the main Template Manager window contains the following tabs:

Step Action


2. Select the category on the Colors Tab.

3. Click the Background or Foreground button.

4. Click the color from the palette.

5. Click OK and view the sample text.

0


• General Tab

• Syntax Tab

• Keywords Tab

• Advanced Tab

• Colors Tab

Each tab displays a screen with the set of options for the selected template.

When you modify the template characteristics you can choose one of the following:

• Apply - save the changes and keep the Template Manager open.

• OK - save the changes and close the Template Manager.

• Cancel - void any changes and exit Template Manager.

General TabThe General tab of the Template Manager provides information on loading, displaying, and saving options.

For the template selected in the left pane, a description and a set of pre-defined file types for that template are presented.

461

46


You can configure the template specifications by selecting or clearing the following options:

In addition, you can configure:

• Number of spaces for each tab

• Line length

• Display font

Syntax TabThe Syntax tab on the Template Manager defines a set of syntax options for the selected template, which include non-keywords, quoted string support, and comment styles.

Select… To…

Remove trailing spaces when loading

Delete spaces at the end of the line while loading the file.

Remove trailing spaces when saving

Delete spaces at the end of the line while saving the file.

Save tabs as spaces

Insert a variable number of spaces to simulate tab position formatting. It is necessary to convert tabs to spaces in certain applications, notably when using compilers that do not support the tab character.

2


The Syntax tab contains the following options:

Keywords TabThe Keywords tab on the Template Manager lists the various types of the programming languages keywords. Also, this screen provides an option to determine if the language is case sensitive.

Input Field Description

Word delimiters Symbols that define the end of the word.

String Literal Tokens

Symbols that define a string of characters.

Token exception To use literal tokens inside a string, enter the token exception.

Block comments Define the way you start and end the block comments.

Single line comments

You can configure two methods of defining the start symbol and position of the single line comments.

463

46


The Keywords type pull-down menu shows four sets of the template keywords:

• Standard - keywords such as commands for the selected language.

• Compiler - keywords such as compiler directives and calls.

• User defined

• Other - keywords such as function names and defines

Advanced TabThe Advanced tab in the Template Manager opens the screen where you can define options for line numbering and auto-modification date trailing.

4


Colors Tab

ChangeMan Edit and ChangeMan Diff utilities provide you with an option to customize the Code Window color scheme.

You can choose custom background and foreground colors for the Code Window categories, or use the Automatic option.

Note If you are using the ChangeMan Diff utility, the Merge Colors override the syntax colors of the Template Manager.

options needed to output detailed error messages during the build.

TROUBLESHOOTINGCHANGEMAN EDITWhen I try to edit a file with ChangeMan Edit, why can’t I log in?

Use your system login name and password (not your ChangeMan DS user name and password, unless they are the same as your system login).

This User ID needs the appropriate rights on the host which the file resides.

Why am I prompted for login information every time I want to edit a file?

If validating that each user has access to all host areas in your environment is not a concern, you can turn off the password validation. Edit the vcs_serv.ins file found in either the server (Windows), client (Windows), or serena (UNIX) directory with a text editor. The default value is disabled by removing the # (comment sign) from the line: ValidateEditPassword=0.

465

46


If this line is not present, you can add it as shown.

6

GLOSSARY

action A task; typical predefined actions include tasks such as:• Approvals• Getting status• Viewing files• Building projects

API Application Programming Interface. The interface with which an application program accesses the operating system and other services.

application A logical grouping of files that define the scope of the user software being developed.This is independent from the concept of application as used in the Application Process Flow.

Approval Group A list of users that participate in the approval process, their order of approval, and notifications being sent during the process.

Approval Process

A process in which members of a designated Approval Group must approve a package before it can move to the next state.

area A defined location in a file system where components are stored; the logical name of a physical location of files that are controlled by ChangeMan DS. Files are transferred from area to area as the development life cycle is traversed.

Area ID See area.

assignment Units of work that are assigned to a user to complete. Assignments are usually associated with change requests

Authorization list

A list of ChangeMan DS users who are allowed access to a particular ChangeMan DS area.

467

46

Glossary

branch A separate line of development, consisting of one or more versions that diverge from a baseline or another branch.Branching lets you develop alternative variants of a file in parallel with other users who are working on the same file. You can merge a branch version back into the baseline at any time. For example, if you have created a temporary branch to try out new changes, you can merge the branch version back into the main line of development at any time.

browser A program that lets you access the World Wide Web. Examples of browsers include Internet Explorer and Netscape Navigator.

category This field describes the general type of request; the values are:• Production Problem - Problem detected in production pro-

cess• Enhancement Request - the request is for an enhancement

to the product.• Project - the request is for a new project.

change package

See packages.

check box A box in a dialog window that determines if an option is to be exercised. Click on the check box to set or clear it.

check in To move a new version of a file or project to a Production area, and store the changes in an archive if set up to do so.

check out To copy a file from the Production area to a target area (usually a Development area).

class(field on form)

This field describes the general area affected by the request; the values are:• Software - software related problem• Hardware - hardware related problem• Software Compatibility - software compatibility problem• OS Compatibility - Operating system compatibility problem• Documentation - Documentation problem• Website Infrastructure - Website infrastructure problem• Website Content - Website content problem

8


class(OO definition)

A class is a collection of objects that have common structures, behaviors, relationships, and semantics.

client A computer system or process that requests a service of another computer system or process (a server), and accepts that server's responses. A client is part of a client-server software architecture.

client/server A networking architecture in which each computer or process on the network is either a client or server. A server is a powerful computer or process dedicated to managing disk drives (file server), printers (printer server), or network traffic (network server). Clients are usually less powerful PCs or workstations on which users run applications and issue requests to servers for resources.

CommunicationAgent

The Communication Agent is a process (UNIX daemon or Windows NT service module) running on each machine; it creates child processes for direct builds, makes, managing files, interfacing to the server, and other SCM activities. The results of each operation are sent back to the server.

component Any project, area, path, or file that is under ChangeMan DS control

CORBA Common Object Request Broker Architecture. A middleware standard for defining interfaces between applications distributed over the Internet.

CRB Change Request Board.

daemon A continuously-running, UNIX background process that performs a housekeeping or maintenance utility function when called. Upon completion of the function, the daemon returns to background mode.

datasource The source for the data; typically another table. For example, a field can require the customer’s name; that information can be obtained from the datasource, rather than creating a new (and duplicate) entry for customer data.

deferred request

A request that was evaluated to be non-essential or not viable for this release. When re-evaluated, the deferred request can be closed as never essential, or assigned to a specific release.

469

47

Glossary

demote To return the file or project to a prior node.

Dependency A dependency defines a relationship between elements on the same object level, and it determines the order in which multiple objects are deployed within the same object level.

Development area

Area used by programmers to modify or create the software.

distribute To transfer files from a Production area to an End User area. This will make a copy of the files without updating the file status

End User area This area contains the complete final product.

feature A set of logically related functional requirements that provide a capability to the user, or enable the satisfaction of a business requirement.

foreign key A reference from one record to another.

form A window, message box, dialog box, or property sheet used to request information.

freeze To lock a piece of software or a package against further change; to record the state of a project and its build information (including versions of the files that went into the release) when it is ready for distribution.

FTP File Transfer Protocol.

group A group is a collection of individual users that can be treated as a single entity, and that has been assigned the same permissions. For example, all members of the QA organization can be assigned to a Testers group, and all have been assigned the same permissions.By having individual users collected into groups, the administrator can modify the permissions for every individual in the group simultaneously, rather than one by one. Note that this does not prevent the administrator from modifying the permission of any member of the group individually.An unlimited number of groups can be defined. A group can contain an unlimited number of users, and a user can be assigned to an unlimited number of groups.

0


GUI Graphical User Interface

hierarchy The placing of objects above or below another. ChangeMan WCM has an inherent hierarchy among Websites, editions, requests, and tasks. A hierarchy can also be created among elements on the object level.

IDE Integrated Development Environment. Typical IDEs include WebSphere, Rational Rose, and VisualAge for Java.

impact analysis A “where used” query that returns a list of locations where a target is found. The target can be any element; a variable, data item, function call, or include file

incident An incident refers to an issue, problem, bug, modification, or enhancement to the development process.

inherit The ability to derive new classes from existing classes.

integration testing

Tests the assembled modules that are assembled or integrated to form the software. Focuses on how modules work together and program construction. Integration testing can be done by programmers or testers.

Java A platform-independent, general-purpose programming language.

life cycle A structured set of activities that leads to the production of usable software. The phases software goes through from when it is conceived, until when it is retired.

Main Server A host machine that is responsible for coordinating SCM activities, including user authentication and transfer request authorizations. The Main Server does not store files; they are stored in their native format, and in the original directories.

metadata Data about, or descriptive of, other data; such data can include configuration information, table formats, configurations, impact analysis, and audit trail information.

MSSCCAPI Microsoft Source Code Control Application Programming Interface.

node An item on the tree in ExplorerView

471

47

Glossary

object A logical entity that has a set of properties. As an example, the object “customer” could have the properties of customer ID, contact name, telephone number, and email address.An object can be designated as “system” or “user”.

package A logical grouping of files necessary to make a change to an application.

package type In ChangeMan DS, packages types are informational only; the type has no effect on processing. The types are:• Unplanned/Temporary - Unscheduled changes that run for

a predetermined length of time. These are usually one-time or short-term emergency fixes.

• Unplanned/Permanent - Unscheduled changes that update the baseline or Production libraries. These are usually emer-gency fixes.

• Planned/Temporary - Scheduled changes that run for a pre-determined length of time. These are usually one-time or short-term processes.

• Planned/Permanent - Scheduled changes that update the baseline or Production libraries.

package level In ChangeMan DS, packages levels are informational only; the level has no effect on processing (but see “Dependencies between Packages” on page 271 and “Establishing a Hierarchy for Packages” on page 270). The types are:Simple - This package contains a change that is unrelated to any other package.Complex - The parent for two or more participating packages that have interdependent changes to software or operational procedures.Super - The parent for two or more participating packages that contain major changes to several applications.Participating - The package is related to one or more other participating change packages.

2


permission A rule associated with an object that regulates which users can have access to the object, and what actions they can perform in relation to that object.An authorization to perform a specific task or action. For example, you can be granted permission to read a file, but not be granted permission to modify the file.A permission, or set of permissions, can be assigned to an individual user, or to a designated group of users. To simplify the administration and maintenance of permissions, consider assigning them at the group level, rather than at the user level.

predecessor In a dependency, the predecessor is the object that must be completed first.

priority A measure of the importance of an incident, and a suggestion as to how resources should be deployed in response to the incident.The priority levels are:• ASAP. Highest priority; attempt to resolve as soon as possi-

ble.• High.• Medium.• Low.• Unknown.

Production area Contains baseline components and prior versions.

project A group of related components, such as source files, executables, documents, and drawings, that are managed together as a single release.

promote To move the file or project to another state.To transfer a file from one area or state to another. An example of a promotion could be moving a file from a Development area to a Q/A area.

QA area Area used by quality assurance personnel for controlled testing

query A request for information from the database. Typically, queries are saved and reused, although there are ad hoc queries, which are used once, then discarded.

473

47

Glossary

release Reflects the change(s) that affect a version or revision of a product(s).

requester The person, department, or organization that submitted a requests.

requirement Something the product must do, or a property (such as quality), that the product must have. A requirement focuses on what and why you intend to build. A user need or necessary feature, function, or attribute of a product that can be sensed from a position external to that system. A requirement does not include design or implementation details, project planning or testing information.

right-click menu The term used for the menu displayed when you right-click on an item.Sometimes called shortcut menu.

rollback The process of replacing the current version of a release (or selected files) with a previous, frozen version.

SCC Source Code Control.

SCM Software Change Management/Software Configuration Management - a process for controlling and tracking software components. SCM enables a software development team to identify those components of data, documents, and programs that will undergo change; establish a strict procedure for specifying, evaluating, and approving changes; report changes; audit changes that are made to ensure that quality has been maintained; and reconstruct the software to accommodate the changes that have been implemented.

Serena™ ChangeMan® ALM

An application life cycle manager that provides the software infrastructure for creating and managing change throughout its entire life cycle.

Serena® ChangeMan® DS

A process-oriented product that controls change activities across multiple platforms and locations throughout the development, maintenance, and distribution phases of the product life cycle.

4


server A program or machine that provides some service to other (client) programs.A host machine that coordinates SCM activities, including user authentication and transfer request authorizations. The server does not store files; they are stored in their native format, in their original directories.

severity A measure of the severity of an incident. Levels of severity are:• Unknown - the level of severity is undetermined• Information only - general comment, or request for informa-

tion.• Minor - the problem presents a minor annoyance. There is a

workaround.• Medium - the problem presents a major inconvenience.

There is a workaround.• High - the problem is mission-critical, but other tasks con-

tinue. There is no workaround.• Critical - there is catastrophic disruption. Other systems are

affects. There is no workaround.

SMTP Simple Mail Transfer Protocol. A protocol for transferring electronic mail between computers, usually over Ethernet. SMTP is a server-to-server protocol; other protocols are used to access the messages.

software project A defined administrative and functional structure that collaborates to produce systems with software content.

states For packages, the positions along the life cycle to and from which the package can be promoted.

successor In a dependency, the successor is the object that is completed after the predecessor.

UNC(Universal Naming Convention)

A way to identify working directories and Development areas in a computer without having to specify (or know) the storage device it is on. In Windows operating systems, the UNC name format is:\\servername\sharename\path\filename

475

47

Glossary

view The image of the system presented to any one user. Based on the permissions assigned to the user, the view shows only those functions, areas, and projects that the user is allowed to work on or have access to.

wrapper Creates an interface from an application to some other user systems or services. Typically, the wrapper is written in the application’s native language (such as Java or C).

6

INDEX

Aaborted transactions 221accepting

changed lines, merging 430changes, ChangeMan Word Diff 163inserted lines, merging 430

accessibility, Online Help 22accessing

applications and packages 248Audit Trail 213ChangeMan DS 38ChangeMan Edit 55File Tree from packages 268itemized Impact Analysis 229project filter screen 64Template Manager 456

Activity/Eventlist of life cycle components 314

Add target/dependency permission 79adding

change set, files 267contact to a package 269dependencies, packages 272description to a file transfer 98keywords to text-based display 463project branch 139projects 67release branch 140specifications to applications 250split 430users to an Approval Group 298See also attaching, creating

Advanced tabImpact Analysis 378

Template Manager 464agent system requirements 36already checked out message 119AND 379appending

Impact Analysis reports 226, 233Application dialog 249applications 245

adding specifications 250attaching an area 252attaching areas 253attaching projects 252changing project properties 255creating 250projects 255projects, removing deliverable

status 255projects, viewing audit trail 255tree node described 386viewing Audit Trail, package node 255See also packages

approval assignments 296Approval Configuration Node 392Approval Data Sources 308Approval Groups

adding users 298customizing notifications 302enabling the Default notifications 301setting order of approvals 299

Approval node 391approval process 246approvals

477

47

Index

configuring Approval Group 298configuring process for POA 295described for POA 295notification states described 300reports, Audit Trail 213setting order, POA 299specifying passwords in POA 299Transfer Requests 237troubleshooting 227types 237

Approved state, POA 297approving

packages 296, 391transfer transactions 237

APR > REJ promotion 278APR state 285areas

approving transactions to 238attaching to application 252, 253attaching to package 265package definition 244packages, default area

configuration 254permissions, transfer 128rejecting transactions to 240synchronizing 165Web browser client, displaying 344

AS/400 Communication Agentmake behaviors 332scripts 334transfers 333using 331

assignments, approval 296associating

projects with transferred files 98TeamTrack items with transfers 98see also linking packages

Attach files to project permission 80attaching

documentation to packages 262

files to projects 83, 84files to release 208subprojects to projects 92See also adding, creating

attachmentsprojects 81viewing status 86

Attachments node 280projects 87

Audit Trailaccessing 213approving transactions 239comparing files 145creating queries 216Date Tab 220deleting records 223exiting 226Filter tab 220General tab 218Location tab 219printing report 223queries, loading pre-defined 217queries, saving 216reports, approving transactions 225rolling back to a previous version 224troubleshooting 226troubleshooting pending transfers 227user input area 217viewing from IDE 217viewing from packages 255viewing signoff history 225, 241

Auto hide 130auto line numbering 459AutoDoc option 228automatic merge 163

Bbackground colors, text 150, 431BAS state 286

8


binary filescomparing 143determining 148forcing binary transfers 96

bookmarks 444branching

described 133files 135, 137

Bring Home 360build

add dependencies 184delete history 195dependencies 184

adding to projects 186properties 187

history 192sending to a log file 194understanding 193

hostsuser login information 191

initiating from ExplorerView 190locating information storage 194Make Configuration

Global Compile 178Post Compile 180Pre Compile 177properties 175

make filesexporting 200importing 196properties 174

make procedure, creating 173preparing 170targets 181

adding to projects 182properties 183

build management, projects 63Build module

reports, Audit Trail 213builds

troubleshooting 201

CCancel check out permission

project level 79Cancel state, POA 297canceling

check out 359package approvals 296

capturing release information, freezing projects 63

change requests, grouping 63change set

adding or deleting files 267projects 63

changed lines, merging 430ChangeMan Diff

copying a selection 439, 440finding text 440line numbers, displaying 453moving a selection 441replacing text 443

ChangeMan Diff utilitybookmarks 444changing display mode 430changing display options 431changing text background colors 431comparing files 143Diff Mode 147Diff Parameters toolbar 408Edit/View toolbar 404, 407interface 402–409Merge Mode 161Merge toolbar 405Standard toolbar 403

ChangeMan DS Edittoolbar, Standard 411

ChangeMan DS File Properties dialog 268ChangeMan DS Merge dialog 158ChangeMan DS Prompt dialog 101, 102,

167

479

48

Index

ChangeMan DS, logging in 38ChangeMan Edit 465

altering access permissions 465bookmarks 444changing colors 460Colors tab, Template Manger 465compile

files 447result scripts 448

components 437configuring auto line numbering 459copying a selection 439, 440creating files 451described 437editing files 55finding text 440Impact Analysis 445line numbers, displaying 453modifying files 438moving a selection 441opening files 56redo 443replacing text 443ruler, displaying 454run commands 446saving files 451Template Manager 456undo 443variables 455viewing errors and warnings 450

ChangeMan Word Diff utilitychanging text background colors 150comparing documents 149merging documents 162merging from comparison 150Web browser client limitations 145, 146

ChangeMan ZMF, package names 255changing

colors, ChangeMan Diff 161colors, ChangeMan Edit 460display mode, ChangeMan Diff 430display options, ChangeMan Diff 431

package properties 255passwords 382text-colors, ChangeMan Diff 431text-colors, ChangeMan Word Diff 150users, reconnecting to ChangeMan

DS 40your password 40See also editing, modifying, setting

check in 359files, branching 137files, new file 116files, new version 115files, same version 116initiating 114merging 155projects 117projects, branching 139synchronizing 160

Check in permissionproject level 79

check out 359cancelling 359files, branching 135files, canceling 110files, File List 107files, previous version 109files, primary 106files, secondary 108folders 106frozen release 389initiating 105projects, branching 139projects, cancelling 113projects, primary 110projects, secondary 112secondary 134

Check out permissionproject level 79

checked out message 119Checkoff state, POA 297child projects 92

0


child, package hierarchy 270Clear button 255client

command line interface 35defined 35GUI client 35system requirements 36Web client 35

closingChangeMan Word Diff utility 150

codesynchronizing lines 434

Color tab, Template Manager 465colors

ChangeMan Diff 161ChangeMan Edit 460merging files 161

column information, Impact Analysis 222, 231

commandsfile level, Host View 324run, ChangeMan Edit 446

Communication Agentdefined 35

comparingfiles from Audit Trail 145files with Web browser client 409Microsoft Word documents 143, 149text-based files 143See also merging

comparing Word files 150compiling

files 447result scripts 448

Completed, approval type 237complex, package level 259components, grouping 63concurrent check outs

depiction on File Tree 134files 108

concurrent development 133configuring

approval group 298approval process for POA 295Approver Properties Notifications,

POA 303ChangeMan Diff utility 456ChangeMan Edit 456dependencies 272status display options, Web browser

client 385connection problems 344contacts

adding to Contacts node 390for packages 269

Contacts Node 390content window 42contributors, multiple

using subprojects 91controlled status symbol 48conversion utilities 36copying

files via branch 135, 137templates 458text 439, 440

Create release permission 79Create target/dependency permission 80creating

applications 250Approval Group in POA 298approval notifications, POA 300Audit Trail queries 216branch of a project 139branch of a release 140branch on file check in 137branch on file check out 135copy of a project 139

481

48

Index

default area configuration, packages 254

dependency rules 274files 451hierarchies, packages 270make procedure 173notifications 312packages 261project 65releases 203templates 457See also adding

customizingApproval Group notifications 302

Ddaq, file extension 216data retrieval, stopping 228data source

described 306notification 314

datepackage creation 259package installation 260, 276

Date Tab, Audit Trail 220Default Approval Group notifications,

described 301default area configuration 254Default notifications, enabling in POA 301default, security authorization 293defining

project properties 70DEL > DEV promotion 278DEL state 286Delete release permission 79Delete target/dependency permission 80deleting

Audit Trail records 223change set, files 267templates 458See also detaching, removing

Deliverable button 255deliverables

choosing Installation area 265marking projects as 255removing status 255

Demote from QA permission 79dependencies 184

adding 272adding to projects 186configuring 272define for build 184modify property 187properties 187removing 273

dependency rules, creating 274descriptions

adding to file transfers 98destination file

already checked out message 119Detach files from project permission 80detaching

files from project 86files from release 207See also removing, deleting

determining text-based/binary files 148DEV > DEL promotion 278DEV > FRZ promotion 278DEV > REJ promotion 278DEV state 285Development areas 246, 253development environment, integrated 36dialogs

ChangeMan DS Prompt 167System Configuration 374

2


Diff Mode 147Diff Output 431Diff Parameters toolbar 408directory properties, UNIX 329display mode, ChangeMan Diff utility 430display options, ChangeMan Diff utility 431display requirement

ChangeMan DS Main Server 341display requirements

Web browser client 345displaying

areas on Web browser client 344ChangeMan DS File Properties

dialog 268line numbers 453ruler 454status bar 359text-based file characteristics 461toolbars 359

distinctive, security authorization 293distributing

automated 124files 124frozen release 390initiating 124projects 125to End User area 360

distributionby DCM commands 128by Implementation Script 126by Post Compile script 127interactive 124

drag-and-dropattaching files to projects 84copying text 440moving text 441

DS Control Option 48

EEdit/View toolbar 404, 407editing

files 53, 55files from the File Tree 281files in packages 279inputting passwords 465merged file 432projects 67text 441See also changing, modifying, setting

editing filesChangeMan Edit 56

EditScript dialog 288Element, searching for 379elements

impact analysis 228e-mail

configuring notifications 311enabling

approvals in POA 295ChangeMan Edit 55default Approval Group

notifications 301Impact Analysis (AutoDoc option) 228

End 119End User area

promoting from 119end users, distributing to 360errors

viewing in ChangeMan Edit 450eserver iSeries, See AS/400exclamation icon 100exiting

Audit Trail 226Impact Analysis 233See also closing

ExplorerView

483

48

Index

Alphabetical Impact Analysis 228approving transactions 238attaching files to projects 84described 42main window 42

exploringUNIX, HostView 324

exportbuild rules 200make procedure, frozen release 390

Ffailed installation 341failed rebooting, VCS Server 342failed to retrieve first archive message 227fields

ChangeMan DS Merge dialog 158file contents

viewing 54file failed process control rule

message 129File List

checking out files 107file properties 57File Transfer Request Status dialog 104file transfer requests

reports, Audit Trail 213File Tree

comparing files 144displaying from packages 268interface 400merging 154target rules, merging 159viewing file history 211viewing from Impact Analysis 225, 232

File Tree dialog 281checking out files 282

file(s) failed to transfer 104file(s) merged 104file(s) skipped 104file(s) transferred 104files

approving transactions 238associating with files on transfers 98attaching during project creation 83attaching to a release 208attaching to projects 84branching 135, 137canceling check out 110check in 115check in, branching 137check out 106check out by folder 106check out from File List 107check out, branching 135check out, second 108checking out 282combining, see mergingcomparing 143comparing from Audit Trail 145compiling 447creating 451dependencies for build 184detaching from releases 207distributing 124editing 53editing with ChangeMan Edit 55forcing transfer as binary 96grouping as subprojects 91managing properties, UNIX 328modifying 438modifying list on transfers 98new, check in 116not finding in Impact Analysis 233opening with ChangeMan Edit 56permissions, file transfer 128placing under control 47previous version, check out 109promoting 120

4


properties, viewing 57rejecting promotions 240removing from projects 86same version, check in 116saving 451scheduling transfers 97searching for components, Impact

Analysis 227secondary check out 108status indicators 48synchronizing 165tampering 354, 355transferring 95troubleshooting promotions 128unable to place under control 51viewing contents 54viewing from Impact Analysis 226, 232viewing from packages 268viewing history 114viewing information 211viewing status 86

Files toolbar 369filter screen, projects 64filter, search criteria 292Find Now button 226, 233, 379firewall, accessing ChangeMan DS 344folder

approving transactions 238rejecting transactions 240

folders, checking out 106forcing file transfer as binary 96freezing

projects 204projects with subprojects 205

Frozen Release node, packages 389frozen release options 389Frozen Releases 246, 282Frozen Releases node, projects 87FRZ > APR promotion 278

FRZ > DEL promotion 278FRZ > REJ promotion 278FRZ state 246, 285Function Call, searching for 379

GGeneral tab, Template Manager 461G-Notify, described 302groups

adding to Approval Group 298configuring notifications in POA 303

Hhalted check in transaction(s) created 105help, online

accessing 365heterogeneous hosts 327Hide Map 147hierarchies, packages 270history

build 192packages, viewing 283

Home areadefined 47

Host Viewadding a host 326configuring 325file level commands 324information displayed 323managing heterogeneous hosts 327managing properties 327removing a host 327UNIX

exploring host 324managing file properties 328modifying directory properties 329

Hosts toolbar 372

485

48

Index

hosts_menu 362

Iicons

checked out, files 89controlled status 48Development icon, projects 86Local Status 353Production Status 356Request Status 100, 357

IDEattaching files to projects 81editing files 53integrations with 36viewing Audit Trail 217

identifyingfiles with specific elements 228

IFL state 247, 286Impact Analysis

advanced search 378alphabetical 228attaching files to projects 84, 232ChangeMan Edit 445exiting 233itemized 228, 229performing 228results 230stopping data retrieval 228toolbar 378troubleshooting 233types 228

Include File, searching for 379inclusive, security authorization 293inference, security authorization 293initiating

check in 114check out 105distribution 124promote 119

synchronizations 165See also starting

initiating build process 190INS state 285Ins. History button 289inserted lines 430inserting bookmarks 444install failed 247installation

date and time 260, 276Main Server 341

Installation area 252installation log 289integrated development environments 36integrity

indication of file tampering 354, 355interface

ChangeMan Diff window 402–409content window 347Edit menu 358File Tree 400Files menu 361Files menu, File List 373Files toolbar 369Help menu 365Hosts menu 362Hosts toolbar 372Main Window, File menu 358menus 357Performance Monitor 397Project menu 360Project toolbar 370Promote menu 359Promote toolbar 371Serena ChangeMan DS views 42Standard toolbar 366status icons 353System Configuration 374toolbars 365

6


Tools menu 363Tools toolbar, Main Window 367View menu 359Web browser client 383

invokingJava client 39

Itemized Impact Analysis 229

JJava client 150

invoking 39merging Word files 162projects 67status options, displaying 385

Kkeywords 463Keywords tab, Template Manager 463

Llanguages, effect on text-based or binary

files 148level, packages 259life cycle

described 284packages 284promoting packages 276viewing package history 283

line numbers, displaying 453lines, auto numbering 459linking packages 266Local Status icons 353Locale setting 148log in

changing password 40log, transfer requests 104

logging inreconnecting during session 40

MMain Server

accessing through firewall 344defined 35troubleshooting installation 341

main windowdescribed 42navigating 43

Maintain function, frozen release 209Maintain option

action described 140toolbar button 389

maintainingcomplex levels of work 94

make behaviorsAS/400 Communication Agent 332

Make ConfigurationGlobal Compile 178Post Compile 180Pre Compile 177properties 175Properties tab 175

make fileexporting 200importing 196properties

modifying 174make procedures

creating 173defining 170

Make Procedures node, projects 87managing

HostView properties 327Map 147, 161

toggling 435

487

48

Index

menuEdit Main Window 358Files 361Files, File List 373Help 365Hosts 362Project 360Promote 359View 359

menus 357File, Main Window 358right-click, Java and Web browser 393–

396Tools, Main Window 363

Merge Mode, ChangeMan Diff utility 161Merge toolbar 405merging

automatic 163described 153during check in 155editing merge file 432from the File Tree 154Merge dialog field descriptions 158Microsoft Word Documents 162synchronization 156synchronizing 165target rules 159Word file, ChangeMan Word Diff 150See also comparing

messagesalready checked out 119

metadata repositorydefined 35

Microsoft Word documentscomparing 143, 149merging 162

Modify target/dependency permission 79modifying

files 438keywords from text-based files 458

list of files being transferred 98releases 207UNIX directory properties 329See also editing, changing, setting

moving, text 441

Nnames, file name restrictions 51navigating

changes, ChangeMan Word Diff 151code with bookmarks 445

no requests were created message 130Notification Configuration Node 393notifications

configuring 311configuring for approvers, POA 303creating 312creating for approvals, POA 300customizing for Approval Groups,

POA 302data sources 314data sources for 306

OOff-line Transfers 97One Window Diff 431Online Help, Section 508 accessibility 22On-line transfers 97opening

ChangeMan DS 38files 56read-only version of a file 54

OR parameter, Impact Analysis 379out of space

UNIX 341override passwords

POA approvals 299

8


overwrite into working area 167overwriting, synchronizing 165owner

project, described 73Owner column 89Ownership, Transfer 360

PPackage dialog

Life Cycle tab 284package-oriented approach 243–321packages 245

adding contact 269adding dependencies 272approving 296, 391APR state 285attaching areas 265attaching projects 263attaching specifications 262Attachments node 280BAS state 286configuration screen 255configuring approval process 295creating 261default area configuration 254DEL state 286DEV state 285editing files 279FRZ state 285hierarchies 270history 283IFL state 286INS state 285levels 259life cycle 284life cycle, viewing 283linking 266names 255predecessor 272projects 388

promoting 276REJ state 286removing dependencies 273saving search criteria 292searching for 290security 292successor 272troubleshooting promotions to FRZ 257types 258viewing Audit Trails 255viewing files 268viewing history 283viewing installation history 289See also applications

parallel development 133parent projects 92parent, package hierarchy 270parent-child relationships, projects 92participating, package level 259passwords

changing 40, 382editing 465specifying for approvals in POA 299when editing 465

path, setting relative 90Pending 100, 357Pending option 100pending transaction(s) created 104pending transfers

reports, Audit Trail 213troubleshooting 227

Performance Monitorinterface 397

performingImpact Analysis 228Impact Analysis, alphabetical 228

permanent, package type 258permissions

489

49

Index

release branches 140See also securitytransfer activities 128

placing files under control 47planned, package type 258POA, see package-oriented approachposition locator, files 147, 161predecessor

adding dependencies 272removing dependencies 273

pre-defined queries 217preventing mistaken edits

project working location view 89printing

Audit Trail report 223Impact Analysis reports 232

procedure, make 173Process Control Rules

failed transfers 129Production area 246, 252Production Status icons 356Production view 88project file(s) not under source control 105Project node 255Project toolbar 370project working location

described 87setting views 88

projects 245, 255administration permissions 80approving transactions 238, 240associating with transferred files 98attaching files 83, 84attaching files during creation 83attaching to application 252attaching to package 263attachments 81

Attachments node 280attachments node 87authorization lists

adding groups 77adding users 77deleting groups 77deleting users 77

changing properties within applications 255

check out 110check out, canceling 113check out, secondary 112checking in 117creating 65, 67

based on existing project 68from Java client 67from Web browser client 67

creating a branch 139defined 244defining 70deleting 68described 31Development icon 86distributing 125editing 65, 67editing from Java client 67editing from Web browser client 67freezing 204freezing with subprojects 205Frozen Releases node 87implementation schemes 92Make Procedures node 87marking as deliverable 255owner 73permissions, transfer 128Project Authorization 76project priority 75project status 75project type 74promoting 63, 121

0


PropertiesDescription 73Name 73Notes 74Parent 74

Properties tab 73relative path 90removing attachments 85, 86removing deliverable status 255Status icon 89subprojects 91transferring 95user permissions 78–80view filter 64viewing status of attachments 86working location 87See also packages, subprojects

Projects dialog 84Projects node 388Promote menu 359Promote Options, adding to control 49Promote to Development 360Promote to Production 359Promote to QA 360Promote to QA permission

project level 79Promote toolbar 371promoting

adding files to control 49already checked out message 119defined 29, 95files 120frozen release 389initiating 119packages 276projects 63, 121promotion types 278releases 206subprojects 92troubleshooting 128

propertiesmodify dependencies 187modifying target 183package, changing 255viewing for a file 57viewing for frozen release 390

Properties tabprojects 73

Qqueries

Audit Trail 216file extension 216pre-defined 217

Rread-only file versions 54rebooting

VCS Server 342reconnecting to ChangeMan DS 40redo 443refining

Impact Analysis reports 233refresh list of frozen releases 390REJ state 286Rejected state, POA 297rejecting

changed lines, merging 430changes, ChangeMan Word Diff 163file transfers 240inserted lines, merging 430packages 296

relationships, predecessor & successor 272

relative pathusing with working location 87

relative path, setting 90

491

49

Index

releasesattaching files 208branching 140creating 203detaching files 207maintaining 140modifying 207promoting 206rolling back 206

relogin, ChangeMan DS 40remote commands 446remote directory browsers

failed access to host 344Remove from source control permission

project level 79removing

attachments from projects 86Audit Trail records 223bookmarks 445deliverable status, projects 255dependencies, packages 273files from control 50hierarchies, packages 270host 327spaces when saving text-based

files 462split 430tampered status 354users from Approval Group 298See also detaching, deleting

replacing text 443reported problems, grouping 63reports, See entries Audit Trail, Impact

AnalysisRequest Status icons 100, 357request transaction(s) created 104Requested 100, 357Requested, approval type 237requester 269

requests, file transferAudit Trail reports 213

restartingUNIX services 342

result scripts 448retrieving latest, see synchronizingReview state, POA 297reviewing, package approvals 296right-click menus

Java and Web browser 393–396right-click menus,

Show History command 226Rollback permission

project level 79rolling back

files to previous version 224releases 206

rulersdisplaying 454

rulesautomatic merge 163dependency 274promotion 119

run commands 446

Ssaving

Audit Trail queries 216files 451package search criteria 292

schedulingon-line/off-line transfers 97

scriptsAS/400 Communication Agent 334compile results 448

searching

2


elements, alphabetical impact analysis 228

Impact Analysis 378Impact Analysis, stopping search 230packages 290saving package search criteria 292text 440user who initiated last transaction 89

Second Check out permissionproject level 79

secondary check ins 116, 137secondary check outs 108, 134Section 508 Help 22security

approval passwords, POA 299setting package permissions 292setting permissions 280, 292

security permissionsediting 465message for violating permissions 129

selectingChangeMan Diff templates 433, 434

Serena ChangeMan DSextending SCM 29placing under control 47system requirements 36

Server system requirements 36setting

approval order in POA 299Audit Trail Filters 227project as deliverable 255relative path 90See also changing, editing, modifying

setup.exe 341Show Differences 144Show History command

when it appears 226sign off 237

signoff history, viewing 225, 241simple, package level 259software applications, grouping

components 63sorting, Impact Analysis columns 222, 231source control

adding to using promote 49placing files under 47removing from control 50troubleshooting 51

Source Control Properties, viewing 57specifications

adding to application 250attaching to packages 262

specifyingapproval passwords in POA 299

split view 430Standard toolbar

ChangeMan Diff 403ChangeMan DS Edit 411Main Window 366

standardizing, software executables 63states, life cycle 284Status Bar, toggling 435Status icons

checked out 89Development area, projects 86projects 89

status options, setting 385status, files 48stopping

Impact Analysis, data retrieval 228search, Impact Analysis 230

subordinate packages 270subprojects

attachment rules 92described 31

493

49

Index

freezing with projects 205promoting 92schemes 92using 91See also projects

successoradding dependencies 272removing dependencies 273

super, package level 259symbols, controlled status 48synchronizing

lines in code 434merge option 156process described 165promote option 359releases 389target rules 159

Syntax tab, Template Manager 462System Configuration dialog 374system requirements 36

display requirements 341

Ttampering

indication of file tampering 354, 355target area

Pending option 100target rules, merging 159targets

adding to projects 182build 181dependencies 184, 186, 187properties 183

team development 133TeamTrack

associating items with transfers 98Template Manager 456

Advanced tab 464

changing colors 460Color tab 465configuring auto line numbering 459General tab 461Keywords tab 463Syntax tab 462

templatesChangeMan Diff, selecting 433, 434copying 458creating 457deleting 458

temporary, package type 258text

ChangeMan Diff, background colors 150, 431

ChangeMan Word Diff, background colors 150

copying 439, 440displaying line numbers 453finding 440merging background colors 161moving 441replacing 443

text-based fileschanging display 461comparing 143determining 148editing 53merging 160rules for deciding 96

timepackage installation 260, 276

togglingMap, ChangeMan Diff 435Maps 147, 161project working location views 89Status Bar, ChangeMan Diff 435

toolbardescribed 43Files 369Hosts 372

4


Main Window, Standard 366Project 370Promote 371Tools, Main Window 367

Tools toolbar 89described 367

transactionsaborted 221reports, Audit Trail 213viewing all on Audit Trail 227

transfer activitiespermissions 128

Transfer Ownership 360transfer process 95Transfer Request dialog

Advanced button 135transfer requests

reports, Audit Trail 213summary 104viewing details 130

transfer requests, viewing details 130transferring

files and projects 95files as binary 96projects 63

transfersadding a description 98approval 237Approve 359AS/400 Communication Agent 333associating with TeamTrack items 98Bring Home 360cancel check out 359check in 359check out 359distributing to End Users 360modifying list of files 98process 99Promote to Development 360Promote to Production 359

Promote to QA 360scheduling on-line/off-line 97Synchronize 359Transfer Ownership 360

troubleshooting 341Audit Trail 226builds 201ChangeMan Edit 465connection to ChangeMan DS 344Impact Analysis 233installation 341promotion 128source control 51Web browser client 344

type, packages 258

UUnable to transfer file message 201uncontrolled status symbol 48undo 443UNIX

failed installation 341files, managing properties 328modifying directory properties 329out of space 341rebooting services 342unable to transfer file message 201

unlinking packages 266unplanned, package type 258Use ChangeMan Edit option 55users

adding to Approval Group 298changing their password 40configuring notifications in POA 303distributing to 360

Vvariables

495

49

Index

ChangeMan Edit 455VCS Server

rebooting 342vcs_serv, restarting on UNIX 342versions

check out files 109comparing 144

View menu 359View only permission

project level 79viewing

audit trail, project within an application 255

file contents 54file history 114file information 211file properties 57File Tree from Impact Analysis 225, 232files 226, 232files from a package 268files with special characters, Web

client 345history of a package 283installation history 289project attachments 88signoff history 241status of attached files 86subprojects 92transfer request details 130

Wwarning message(s) 104warning messages

failed to retrieve first archive 227file failed process control rule 129no requests were created 130unable to transfer file 201you are not authorized 129

warnings, viewing in ChangeMan Edit 450

Web browser clientaccessing 38ChangeMan Word Diff 145, 146comparing files 409comparing Word files 143, 150display requirements 345Impact Analysis, differences from

Windows 228interface 383merging Word files 162projects 67projects, editing 67status options, displaying 385troubleshooting 344using Admin as user name 344working at area name level 395

Windowsunable to transfer file message 201

Word documents 143work areas 253working location, See project working

location

Yyou are not authorized message 129

6