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.

Trademarks Serena, 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 Rights Any 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 Book Objective Audience Manual Organization Related Documents Accessing the Documentation Using the Online Manuals

Online Help Section 508 Compliant Help

Chapter 1:

Introduction ChangeMan DS Overview Multi-Site Development Environments Process Definition and Enforcement

Serena ChangeMan Product Compatibility Support for Serena Enterprise Change Packages

Chapter 2:

17 17 17 20 20 21 22 22

23 23 24 24 24

Product Overview Area Management Process Flow Control Software Change Control Security and Approvals About User Permissions

Projects and Subprojects Package-Oriented Approach Build and Release Management Reporting Terminology Concepts Architecture

28 28 29 30 30 31 31 32 32 32 33

3

Contents Conversion Utilities System Requirements

Chapter 3:

Getting Started About ChangeMan DS Clients Accessing ChangeMan DS with the Windows Client Accessing ChangeMan DS with the Web Browser Client Accessing ChangeMan DS with the Java Client Reconnecting to ChangeMan DS Changing your ChangeMan DS Password Exiting ChangeMan DS Overview of ChangeMan DS Interface Navigating the Main Window

Chapter 4:

53 54 55 56 57

Using Projects Promoting Projects Viewing Projects—Project Filter Screen Creating or Editing Projects in the Windows Client Creating Projects in the Web Browser and Java Clients Editing Projects in the Web Browser and Java Clients

4

48 49 50 51

Working With Files Editing the Contents of a File Viewing the Contents of a File Setting the Editor Editing a File with ChangeMan Edit Viewing File Properties

Chapter 6:

37 38 38 39 40 40 41 42 43

Adding Files To ChangeMan DS Control Adding to Control Using DS Control Option Adding to Control Using Promote Options Removing Files from Control Troubleshooting Adding Files To Source Control

Chapter 5:

36 36

63 64 65 66 67

Serena® ChangeMan® DS 5.7.1 User’s Guide Deleting a ChangeMan DS Project Copying Project Properties to Another Project Defining Projects Project Properties Project Type Project Status Project Priority

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

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

Working Location Setting Project Working Location Project Working Location View

Relative Path Setting Relative Path

Subprojects Attachment Rules for Subprojects Subproject Promotion Behavior Example Subproject Schemes

Chapter 7:

68 68 70 73 74 75 75 76 77 77 78 81 83 84 84 85 86 86 87 88 88 90 90 91 92 92 92

Transferring Files and Projects Completing the Transfer Request Dialog Scheduling On-line or Off-line Transfers Adding a Description to a Transfer Associating a Project with Transferred Files Associating Source Control Operations with TeamTrack Items

96 97 98 98 98

5

Contents Modifying the List of Files Being Transferred

Transfer Process File Transfer Request Status Dialog Checking Out Checking Out Files Checking Out Files by Choosing a Folder Checking Out Files Using a File List Issuing a Second Check Out Request for a File Checking Out a Previous Version of a File Canceling a Check Out Transaction for a File Checking Out a Project Issuing a Second Check Out Request for a Project Canceling a Check Out Transaction for a Project

Checking In Checking In Files Checking In New Files Checking In the Same Version of a File Checking In a Project

Promoting Promoting Files Promoting a Project

Distributing Interactive Distribution of Files Interactive Distribution of a Project Automatic Distribution by Implementation Script Automatic Distribution by Post Compile Option Automatic Distribution by Command Line Interface

Permissions Required to Transfer Files Troubleshooting File and Project Transfers

Chapter 8:

Branching Creating a Branch of a File During Check Out Creating a Branch of a File During Check In Creating a Branch of a Project

6

98 99 104 105 106 106 107 108 109 110 110 112 113 114 115 116 116 117 119 120 121 123 124 125 126 127 128 128 128

135 137 139

Serena® ChangeMan® DS 5.7.1 User’s Guide Creating a Branch of a Release

Chapter 9:

Comparing Files Comparing Files with the Show Differences Command Comparing Files from the File Tree Comparing Files from an Audit Trail Report Text-Based Comparisons Text-Based and Binary Files Locale Setting

Microsoft® Word Document Comparisons Changing Display Colors Closing the ChangeMan Word Diff Utility Merging Files during ChangeMan Word Diff Comparison Navigating Changes

Chapter 10:

140

144 144 145 147 148 149 149 150 150 150 151

Merging Merging from the File Tree Merging as Part of Check In Merging as Part of Synchronization Completing the ChangeMan DS Merge Dialog Target Rules for Merging Interactive Merges with Text-Based Files Interactive Merges with Microsoft® Word Documents Accepting/Rejecting Changes in ChangeMan Word Diff Saving and Exiting from ChangeMan Word Diff After Merging

Automatic Merge Rules Canceling a Merge

Chapter 11:

Synchronizing

Chapter 12:

Managing Builds Make Procedures Build Options

154 155 156 157 159 160 162 163 163 163 164

170 171

7

Contents Creating a New Make Procedure Modifying Existing Make Procedures Defining Make Procedure Properties Defining Make Procedure Pre Compile Script Defining Make Procedure Global Compile Script Defining Make Procedure Post Compile Script Make Procedure Targets Make Procedure Dependencies Examples of Build Scripts

Initiating the Build Process User Login Information for the Build Host

Build History Reviewing Build History Understanding the Build History Sending the Build History to a Log File Locating Build Information Storage Deleting the Build History

Importing a Make File Exporting Make Procedures Troubleshooting Builds

Chapter 13:

Managing Releases Creating Frozen Releases Promoting a Release Rolling Back a Release Modifying a Release Detaching a File from an Existing Release Attaching New Files to an Existing Release Changing Properties of a Frozen Release

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

8

173 174 175 177 178 180 181 184 187 189 191 192 192 193 194 194 195 196 200 201

203 206 206 207 207 208 208 209 209 210

Serena® ChangeMan® DS 5.7.1 User’s Guide

Chapter 14:

Reporting Viewing File Information from the File Tree Audit Trail Running Audit Trail Reports Viewing the Audit Trail for One File Creating an Audit Trail Report with a Query Saving a Query Creating an Audit Trail Report Using a Saved Query Viewing an Audit Trail from an IDE Query Criteria for an Audit Trail Working with Audit Trail Reports Troubleshooting Audit Trail

Impact Analysis Performing Impact Analysis Alphabetical Impact Analysis Itemized Impact Analysis Working with Impact Analysis Results Troubleshooting Impact Analysis

Chapter 15:

Approving File Transfers Approving a Pending Transaction from ExplorerView Approving a Pending Transaction from an Audit Trail Report Rejecting a Pending File Transfer Viewing the Sign-off History of a File

Chapter 16:

211 213 213 214 215 216 217 217 217 222 226 227 228 228 229 230 233

238 239 240 241

Package-Oriented Approach Using the Package-Oriented Approach Accessing Package-Oriented Functionality Applications Creating an Application Adding Specifications to an Application Attaching Projects to an Application Attaching an Area to an Application Creating a Default Area Configuration

244 247 248 250 250 251 252 254

9

Contents Working with an Application’s Projects

Packages Package Configuration Screen Creating a Package Adding Specifications to a Package Attaching Projects to a Package Attaching an Area to a Package Linking Packages Adding Files to a Change Set Adding a Contact (or Requester) to a Package Establishing a Hierarchy for Packages Dependencies between Packages Promoting a Package Promotion Types for Packages Editing Files in a Package Freezing Files of a Package Life Cycle States for Packages Creating Scripts for Package Installation Viewing Installation History of a Package Searching for Packages Saving a Package Search

Setting Security Permissions for POA Approvals in POA Creating an Approval Process Approving Packages Creating an Approval Group in POA Adding and Removing Users from an Approval Group Setting the Approval Order for Packages Specifying a Password for Approvals in POA Configuring Notifications for Approvals

Data Sources Approval Data Sources

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

10

255 255 255 261 262 263 264 266 267 269 270 271 276 278 279 282 284 286 289 290 292 292 295 295 296 298 298 299 299 300 306 308 311 312 314

Serena® ChangeMan® DS 5.7.1 User’s Guide Notification Data Source

Chapter 17:

Host View Information Displayed in Host View Viewing the List of Commands Available on the File Level Exploring a UNIX Host

Configuring the Host View Adding a Host Removing a Host

Managing Heterogeneous Hosts Managing Properties for Files and Directories Managing File Properties on a UNIX Host Modifying Directory Properties on the UNIX Host

Chapter 18:

323 324 324 325 326 327 327 327 328 329

OS/400 Environments Using the AS/400 Communication Agent Make Behaviors for AS/400 Transfers in AS/400 Scripting Behavior for the AS/400 Scripting Examples for AS/400 Copying a File Between Directories in "/QSYS.LIB" System 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 on Root File System Forcing Native Area Script Execution

VCS Variables for AS/400

Appendix A:

314

331 332 333 334 335 335 336 336 337 337 337 338 339

Troubleshooting Installation Determining Software Versions Connecting to ChangeMan DS Web Browser Client

341 343 344 344

11

Contents 345

Appendix B:

User Interface Reference Content Window Selecting Areas or Projects Node in Explorer Selecting an Area Type in Explorer View Selecting a User-Created Area or Project in ExplorerView Selecting a Directory Node in ExplorerView Selecting a Project Type Node in ExplorerView Selecting a Frozen Release Node in ExplorerView Selecting a Make Procedure Node in ExplorerView Selecting the Attachments Node in ExplorerView Status Icons

Windows Client UI Main Window Menus—Windows Client Main Window Toolbars—Windows Client System Configuration Dialog ChangeMan DS Project Configuration Dialog ChangeMan DS Area Configuration Dialog Impact Analysis Module

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

Performance Monitor File Tree UI ChangeMan Diff Menus and Toolbar File Menu—ChangeMan Diff Edit Menu—ChangeMan Diff Merge Menu—ChangeMan Diff Tools Menu—ChangeMan Diff View Menu—ChangeMan Diff View Options—ChangeMan Diff

12

347 348 348 348 349 350 350 351 351 353 357 357 365 374 376 377 377 380 383 384 385 385 393 397 400 402 403 404 405 406 407 408

Serena® ChangeMan® DS 5.7.1 User’s Guide Diff Menu—ChangeMan Diff

ChangeMan Edit Menus and Toolbars

409 410

See “ChangeMan Edit Module” on page 437 for more information on 411 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

Appendix C:

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

Appendix D:

411 412 413 413 414

430 430 430 431 431 432 432 433 433 433 433 433 434 434 434 435

ChangeMan Edit Module Editing Text in a Code Window Copying a Selection Using Commands Copying a Selection Using the Drag-and-Drop Method Finding Text Moving a Selection Using Commands Moving a Selection Using the Drag-and-Drop Method

438 439 440 440 441 441

13

Contents Navigating the Text in Code Window Replacing Text Undo and Redo Commands

Using Bookmarks Placing a Bookmark Removing a Bookmark Navigating to Bookmarks

Impact Analysis from ChangeMan Edit Running a Remote Command Compiling a File Compile Result Script Configuring Compile Result Script Viewing Next Error or Warning Clearing Compile Command Results

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

Creating a New File Toggling Display Items Displaying Line Numbers Displaying Marker Bar Displaying the Ruler Displaying the Status Bar

ChangeMan Edit Variables Template Manager Opening the Template Manager Creating a New Template Copying a Template Deleting a Template Modifying a List of Keywords Configuring Auto Line Numbering Changing Colors Template Manager Tabs

TroubleshootingChangeMan Edit

14

441 443 443 444 444 445 445 445 446 447 448 449 450 450 451 451 451 451 452 453 453 454 454 455 456 456 457 458 458 458 459 460 460 465

Serena® ChangeMan® DS 5.7.1 User’s Guide

Glossary

467

Index

477

15

Contents

16

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.

OBJECTIVE This 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.

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

MANUAL ORGANIZATION This document is organized as follows: Chapter

Description

1.

Introduction to ChangeMan DS.

2.

Overview of ChangeMan DS functionality.

17

About This Book Chapter

18

Description

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.

Serena® ChangeMan® DS 5.7.1 User’s Guide Chapter

Description

Appendix D

Using ChangeMan Edit.

Glossary

Glossary of ChangeMan DS terms.

Index

Index of ChangeMan DS subjects.

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.

19

About This Book

RELATED DOCUMENTS 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.

Accessing the Documentation All 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.

20

Serena® ChangeMan® DS 5.7.1 User’s Guide

Using the Online Manuals The 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

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 HELP The 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 Help Section 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.

22

INTRODUCTION

1

This chapter introduces you to Serena® ChangeMan® DS, compatible Serena® ChangeMan® DS products, and new features available in this release.

CHANGEMAN DS OVERVIEW ChangeMan 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 Environments ChangeMan 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

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 COMPATIBILITY This section describes other Serena ChangeMan products that ChangeMan DS integrates with.

Support for Serena Enterprise Change Packages The 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,

24

Serena® ChangeMan® DS 5.7.1 User’s Guide by programmatically linking distributed and mainframe development environments from a central management point. This minimizes reliance on lengthy meetings, emails 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

Chapter 1: Introduction

26

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

Chapter 2: Product Overview

AREA MANAGEMENT ChangeMan 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 CONTROL ChangeMan 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.

28

Serena® ChangeMan® DS 5.7.1 User’s Guide 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 CONTROL ChangeMan 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

Chapter 2: Product Overview

SECURITY AND APPROVALS ChangeMan 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 Permissions Every 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):

30

•

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.

Serena® ChangeMan® DS 5.7.1 User’s Guide

PROJECTS AND SUBPROJECTS ChangeMan 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 APPROACH ChangeMan 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

Chapter 2: Product Overview

BUILD AND RELEASE MANAGEMENT Build Management provides distributed build functionality with UNIX and Microsoftstyle 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.

REPORTING ChangeMan 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 CONCEPTS The following terms should be understood to comprehend ChangeMan DS:

32

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.

Serena® ChangeMan® DS 5.7.1 User’s Guide Term

Definition

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.

ARCHITECTURE The 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

33

Chapter 2: Product Overview •

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.

34

Serena® ChangeMan® DS 5.7.1 User’s Guide 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

Chapter 2: Product Overview •

Java

•

Command line (for use in scripts)

•

Supported Integrated Development Environments

About Supported Integrated Development Environments ChangeMan 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 dayto-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 UTILITIES ChangeMan 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.

36

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 CLIENTS ChangeMan 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

Chapter 3: Getting Started

ACCESSING CHANGEMAN DS WITH THE WINDOWS CLIENT Step

Action

1.

Either:

2.

•

Double-click the ChangeMan DS icon, or

•

Choose Programs > Serena > Serena ChangeMan DS.

Sign on as an authorized user.

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.

38

Serena® ChangeMan® DS 5.7.1 User’s Guide To initiate the ChangeMan DS Web browser client: 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.

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 1.

Action 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

Chapter 3: Getting Started Initiating the Java Client on Windows Platforms Step

Action

1.

Run Client.bat which can be found in the \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.

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

Action 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.

CHANGING YOUR CHANGEMAN DS PASSWORD To change your personal password: •

40

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.

Serena® ChangeMan® DS 5.7.1 User’s Guide •

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 DS To 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

Chapter 3: Getting Started

OVERVIEW OF CHANGEMAN DS INTERFACE The 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.

42

Serena® ChangeMan® DS 5.7.1 User’s Guide 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 Window The 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

Chapter 3: Getting Started

44

Serena® ChangeMan® DS 5.7.1 User’s Guide

45

Chapter 3: Getting Started

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

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 1.

Action 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.

4.

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.

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.

48

Serena® ChangeMan® DS 5.7.1 User’s Guide Step 5.

Action 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.

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. Step 1.

Action 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.

49

Chapter 4: Adding Files To ChangeMan DS Control Step 4.

Action 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.

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 screen and return to ChangeMan DS main module.

REMOVING FILES FROM CONTROL This procedure describes how to remove files from ChangeMan DS control. Note

50

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.

Serena® ChangeMan® DS 5.7.1 User’s Guide

!!Caution!!

Step 1.

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

Action 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.

2.

3.

Use one of the following options: •

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.

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.

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.

51

Chapter 4: Adding Files To ChangeMan DS Control

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 DS When 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

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 client)

•

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

Note

on the Files toolbar. (Windows .

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

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

From Outside ChangeMan DS When 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 FILE ChangeMan 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

54

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

Serena® ChangeMan® DS 5.7.1 User’s Guide 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 EDITOR When 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

Chapter 5: Working With Files

EDITING A FILE WITH CHANGEMAN EDIT Note

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 1.

Action 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.

3.

Click Edit from the Files toolbar, or right-click, then select Edit from the right-click menu. ChangeMan DS prompts you for the host login information to verify your security access. •

56

If the selected file is located on a Windows or UNIX host, this screen prompts you for the host login information.

Serena® ChangeMan® DS 5.7.1 User’s Guide Step 4.

Action 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.

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

VIEWING FILE PROPERTIES The 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.

57

Chapter 5: Working With Files An example of the File Properties dialog from the Web browser client follows:

58

Serena® ChangeMan® DS 5.7.1 User’s Guide 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

Chapter 5: Working With Files Feature

Description

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.

Concurrent Check Out Info The window at the top of this tab provides information on the concurrently checked out copies of the file including: 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.

You may also perform the following functions:

60

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.

Serena® ChangeMan® DS 5.7.1 User’s Guide Feature

Description

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.

Sharing Info From this tab you can see projects to which the file is attached. 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.

Pending and Scheduling Info From 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.

61

Chapter 5: Working With Files

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 PROJECTS Projects 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

Chapter 6: Using Projects

Enforced Project-level Promotion Some 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 Project Configuration dialog.

button on the ChangeMan DS

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

64

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

Serena® ChangeMan® DS 5.7.1 User’s Guide

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:

2.

•

Choose System Configuration from the Tools menu.

•

Click

on the Tools toolbar.

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

Chapter 6: Using Projects Step 4.

Action Input all necessary information under the following tabs: •

Properties

•

Authorization

•

Attachments

See “Project Properties” on page 73, “Project Authorization” on page 76, and “Attaching Files” on page 81 for more information. 5.

Click OK.

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:

66

•

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

Serena® ChangeMan® DS 5.7.1 User’s Guide To create a new project in the Web browser and Java clients: Step

Action

1.

Either:

2.

•

Click New Project button on the toolbar.

•

Select the Projects node in the ExplorerView and choose Create New Project from the right-click menu.

Input all necessary information under the following tabs: •

Properties

•

Authorization

•

Attachments

See “Project Properties” on page 73, “Project Authorization” on page 76, and “Attaching Files” on page 81 for more information. 3.

Click OK.

EDITING PROJECTS IN THE WEB BROWSER AND JAVA CLIENTS To edit an existing project in the Web browser and Java clients: Step

Action

1.

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

2.

Input all necessary information under the following tabs: •

Properties

•

Authorization

•

Attachments

See “Project Properties” on page 73, “Project Authorization” on page 76, and “Attaching Files” on page 81 for more information. 3.

Click OK.

67

Chapter 6: Using Projects

DELETING A CHANGEMAN DS PROJECT To delete an existing project: Step

Action

1.

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

2.

Click Delete.

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 Copy. ChangeMan DS displays the following dialog.

68

Serena® ChangeMan® DS 5.7.1 User’s Guide Step 3.

Action 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

4.

•

Replace

Replace the target profile with the selected source profile.

•

Append

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

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

5.

Select the target project and click OK.

69

Chapter 6: Using Projects

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 1.

Action 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.

70

Serena® ChangeMan® DS 5.7.1 User’s Guide Step

Action

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.

71

Chapter 6: Using Projects Step

Action

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.

72

Select the Attachments tab to attach files to the project.

Serena® ChangeMan® DS 5.7.1 User’s Guide Step

Action

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.

PROJECT PROPERTIES The 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. Field

Description

Name

Contains a unique name identifying the project (up to 10 characters).

Required.

Allowed characters are alphanumeric or embedded underscores. Description

Contains a brief description of the project.

Optional. Owner Required.

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.

73

Chapter 6: Using Projects Field

Description

Parent Optional.

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.

Notes

Contains narrative notes related to this project.

Optional.

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. Icon

Description New projects.

Bug Fix projects.

Custom projects.

Enhancement projects.

74

Serena® ChangeMan® DS 5.7.1 User’s Guide

Project Status Project 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. Icon

Description Open projects.

Development projects.

Quality Assurance projects.

Completed projects.

Project Priority Project 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 Low Priority projects.

Medium Priority projects.

75

Chapter 6: Using Projects Icon

Description High Priority projects.

ASAP Priority projects.

PROJECT AUTHORIZATION The 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. •

76

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

Serena® ChangeMan® DS 5.7.1 User’s Guide •

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 List To add users or groups to 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.

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 Authorization list column.

2.

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

77

Chapter 6: Using Projects

Configuring User Permissions for a Project To 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 projectlevel 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.

78

Serena® ChangeMan® DS 5.7.1 User’s Guide 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

Chapter 6: Using Projects Option

Permission

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.

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.

80

Option

Administrator

PowerUser

End User

Check out

Selected

Selected

Selected

Check in

Selected

Selected

Selected

Serena® ChangeMan® DS 5.7.1 User’s Guide Option

Administrator

PowerUser

End User

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

Selected

Selected

Cleared

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

Selected

Selected

Cleared

Create new target / dependency

Selected

Selected

Cleared

ATTACHING FILES Files 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.

81

Chapter 6: Using Projects 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:

82

•

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.

Serena® ChangeMan® DS 5.7.1 User’s Guide

Attaching Files to a Project during Configuration Use this procedure to attach files to a project on the Attachments tab while creating or editing a project: Step 1.

Action 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.

5.

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. Click

to attach the selected files to the 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.

83

Chapter 6: Using Projects

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

Action

1.

Select a file.

2.

Either: •

Right-click and choose Attach.

•

Click Attach

•

Click Attach

from the File toolbar 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 Windows 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.

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.

84

Serena® ChangeMan® DS 5.7.1 User’s Guide

Removing Files from a Project During Configuration To remove files from the Attachments tab: Step 1.

Action 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

Chapter 6: Using Projects

Removing Files from a Project Through ExplorerView Use this procedure to remove files from a project through ExplorerView: 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.

Viewing Status of Attached Files From the ExplorerView, use this procedure to view the status of project components: 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 checked out.

86

indicates that this project has been

Serena® ChangeMan® DS 5.7.1 User’s Guide Step 3.

Action Expand the project name to display the project structure. Each project in ChangeMan DS has the following structure:

4.

•

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.

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.

WORKING LOCATION A 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.

87

Chapter 6: Using Projects 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 Location Note 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: Step 1.

Action 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.

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

88

•

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.

Serena® ChangeMan® DS 5.7.1 User’s Guide 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

Chapter 6: Using Projects

RELATIVE PATH A 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 Path Use this procedure to set the relative path option: Step 1.

Action 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.

90

Serena® ChangeMan® DS 5.7.1 User’s Guide Step

Action

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.

SUBPROJECTS Projects 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.

91

Chapter 6: Using Projects 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 Subprojects Subprojects 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 Behavior For 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 A A parent project may have the same file attachments as its subprojects have, with the subprojects themselves having different sets of attachments.

92

Serena® ChangeMan® DS 5.7.1 User’s Guide 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 B Parent and child attachments may all be distinct, so that only the parent-child relationship is a common factor.

93

Chapter 6: Using Projects 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 C A 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.

94

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

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 Transfers ChangeMan DS examines the files to determine whether they are binary or textbased. 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 DIALOG The Transfer Request dialog appears during promotion activities, and is modified as needed.

96

Serena® ChangeMan® DS 5.7.1 User’s Guide 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 “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.

. See

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 Transfers The 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

Chapter 7: Transferring Files and Projects

Adding a Description to a Transfer Enter 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 Transferred Add or remove files from the transfer list on the Transfer Request dialog.

98

Serena® ChangeMan® DS 5.7.1 User’s Guide 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: 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.

TRANSFER PROCESS After you have invoked the transfer process by clicking Transfer on the Transfer Request dialog, ChangeMan DS performs the following steps: Step 1.

Action 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

Chapter 7: Transferring Files and Projects Step 2.

Action 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.

100

Serena® ChangeMan® DS 5.7.1 User’s Guide Step 6.

Action 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 target 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.

101

Chapter 7: Transferring Files and Projects Step 8.

Action 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 “TextBased 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.

•

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.

Binary file

102

Serena® ChangeMan® DS 5.7.1 User’s Guide Step 9.

Action ChangeMan DS places your file in a subdirectory depending on your area configuration: •

If a target Development area has the Same preference selected, transfers of individual files and folders from a Production area to a Development 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.

103

Chapter 7: Transferring Files and Projects

FILE TRANSFER REQUEST STATUS DIALOG The 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 0 0 0 0 0 0 2 0

file(s) transferred file(s) merged request transactions created file(s) failed to transfer pending transaction(s) created file(s) skipped warning message(s) halted check in transsaction(s) created project file(s) are not under source control

The output fields mean the following:

104

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.

Serena® ChangeMan® DS 5.7.1 User’s Guide This output field...

Means...

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.

CHECKING OUT When 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 Process You 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)

105

Chapter 7: Transferring Files and Projects

Checking Out Files Use this procedure to check out files: Step 1.

Action 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.

5.

Click: •

Transfer to initiate the file transfer process. 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.

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.

106

Serena® ChangeMan® DS 5.7.1 User’s Guide Use this procedure to check out the files in a folder: 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 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.

5.

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.

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.

107

Chapter 7: Transferring Files and Projects Use this procedure to check out the file in a file list: Step 1.

Action 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.

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.

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.

108

Serena® ChangeMan® DS 5.7.1 User’s Guide 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

Chapter 7: Transferring Files and Projects

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: Step 1.

Action 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.

2.

Use one of the following options: •

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.

Checking Out a Project To 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.

110

Serena® ChangeMan® DS 5.7.1 User’s Guide To check out a project: Step 1.

Action 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 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 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

Chapter 7: Transferring Files and Projects Step 5.

Action 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.

• 6.

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

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.

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.

112

Serena® ChangeMan® DS 5.7.1 User’s Guide

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.

2.

Use one of the following options: •

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

Chapter 7: Transferring Files and Projects

CHECKING IN After 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 Process You can initiate the check in process in variety of ways, including: •

Click

•

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

•

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

•

Click

•

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

114

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

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

Bring Home is enabled only in Production area views.

Serena® ChangeMan® DS 5.7.1 User’s Guide

Checking In Files This procedure describes how to introduce a new version of a file to a Production area: Step 1.

Action 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

3.

(Check In) on the Promote toolbar.

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

4.

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 screen and return to ChangeMan DS main module.

115

Chapter 7: Transferring Files and Projects

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 1.

Action Expand an area node, then select the file 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.

116

Serena® ChangeMan® DS 5.7.1 User’s Guide Step 2.

Action Use one of the “Ways to Initiate the Check In Process” on page 114: For example, click

3.

(Check In) on the Promote toolbar.

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

4.

Click: •

Transfer to initiate the file transfer process. 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 screen and return to ChangeMan DS main module.

Checking In a Project Projects point to Production-level versions of files and checked out (Developmentlevel) 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: Step 1.

Action Select the project to check in. Projects with status shown as checked out.

2.

Use one of the “Ways to Initiate the Check In Process” on page 114: For example, click

3.

have one or more of their files

(Check In) on the Promote toolbar.

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

117

Chapter 7: Transferring Files and Projects Step 4.

Action 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.

6.

118

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.

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

Serena® ChangeMan® DS 5.7.1 User’s Guide

PROMOTING When 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 Process You 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 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)

(Promote to Production) from the Promote toolbar. (Windows client

119

Chapter 7: Transferring Files and Projects •

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 1.

Action Expand the source area (Development or QA) node, then select the file to promote. 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. 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. 3.

120

Select the target area and path, if prompted.

Serena® ChangeMan® DS 5.7.1 User’s Guide Step 4.

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

5.

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 screen and return to the ChangeMan DS main screen.

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. Step 1.

Action Select the project to promote. Projects with a status shown as checked out.

2.

have one or more of their files

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. 3.

Select the target area and path, if prompted.

121

Chapter 7: Transferring Files and Projects Step 4.

Action 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

122

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

Serena® ChangeMan® DS 5.7.1 User’s Guide Step

7.

Action 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.

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.

DISTRIBUTING Distribution 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.

123

Chapter 7: Transferring Files and Projects Interactive Ways to Initiate the Distribution Process To initiate the distribution process for either files or projects: •

Click Distribute to end users only)

on the Promote toolbar. (Windows client

•

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.

124

Serena® ChangeMan® DS 5.7.1 User’s Guide To distribute files with the ChangeMan DS ExplorerView screen: Step 1.

Action 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 toolbar.

on the Promote

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. 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.

5.

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 screen and return to ChangeMan DS main module.

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.

125

Chapter 7: Transferring Files and Projects To distribute a project with the ChangeMan DS ExplorerView screen: 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 toolbar.

on the Promote

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. 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.

5.

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 screen and return to ChangeMan DS main module.

Automatic Distribution by Implementation Script Each 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.

126

Serena® ChangeMan® DS 5.7.1 User’s Guide 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 Option You 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

Chapter 7: Transferring Files and Projects

Automatic Distribution by Command Line Interface Execute 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 FILES ChangeMan 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?

128

Serena® ChangeMan® DS 5.7.1 User’s Guide 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

Chapter 7: Transferring Files and Projects 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.

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.

130

Serena® ChangeMan® DS 5.7.1 User’s Guide

131

Chapter 7: Transferring Files and Projects

132

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

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.

134

Serena® ChangeMan® DS 5.7.1 User’s Guide 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

Chapter 8: Branching Step 4.

Action 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.

136

Serena® ChangeMan® DS 5.7.1 User’s Guide Step 9.

Action If you selected to use the same name, select the new physical location to which to branch.

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: 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.

137

Chapter 8: Branching Step 4.

Action 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.

Note

138

If you elected to use the same name, select the new physical location to which to branch.

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.

Serena® ChangeMan® DS 5.7.1 User’s Guide

CREATING A BRANCH OF A PROJECT You 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

Chapter 8: Branching Step 6.

Action 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.

CREATING A BRANCH OF A RELEASE You 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: 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.

140

Serena® ChangeMan® DS 5.7.1 User’s Guide Step 4.

Action 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.

141

Chapter 8: Branching Step

142

Action

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.

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

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 TREE Through the File Tree, you can compare any two versions of the file that share the same ancestry, including file branches.

144

Serena® ChangeMan® DS 5.7.1 User’s Guide Use this procedure to compare two files from the File Tree: Step 1.

Action 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).

COMPARING FILES FROM AN AUDIT TRAIL REPORT From a report in the Audit Trail window, you can compare a file with its immediatelypreceding 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.

145

Chapter 9: Comparing Files 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 rightclick 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.

146

Exit the comparison utility by choosing File > Exit (or using other standard Windows exit methods).

Serena® ChangeMan® DS 5.7.1 User’s Guide

TEXT-BASED COMPARISONS When 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):

Map

File 1

File 2

Status Bar

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.

147

Chapter 9: Comparing Files 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

•

“Altering the Display Mode” on page 430

•

“Using Bookmarks” on page 444

TEXT-BASED AND BINARY FILES ChangeMan 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

148

•

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.

Serena® ChangeMan® DS 5.7.1 User’s Guide 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 Servers For 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 Setting The 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

Chapter 9: Comparing Files 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 2000 (v 9.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 Colors To 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 Utility You can close the utility by choosing Close or Exit on the File menu.

Merging Files during ChangeMan Word Diff Comparison You 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.

150

Serena® ChangeMan® DS 5.7.1 User’s Guide 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 Changes Step through the changes either manually by scrolling, or by choosing Changes > Prev Change or Changes > Next Change.

151

Chapter 9: Comparing Files

152

MERGING

10

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. 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.

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.

153

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 TREE To 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.

154

Serena® ChangeMan® DS 5.7.1 User’s Guide Step

Action

5.

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.

•

Click Auto Merge to have ChangeMan DS merge the files automatically. See “Automatic Merge Rules” on page 163 for the rules that ChangeMan DS uses to merge the files.

MERGING AS PART OF CHECK IN To merge during the check in process for a file that is concurrently checked out: Step 1.

Action 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.

•

Click Auto Merge to have ChangeMan DS merge the files automatically. See “Automatic Merge Rules” on page 163 for the rules that ChangeMan DS uses to merge the files.

155

Chapter 10: Merging

MERGING AS PART OF SYNCHRONIZATION To 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.

•

156

Click Auto Merge to have ChangeMan DS merge the files automatically. See “Automatic Merge Rules” on page 163 for the rules that ChangeMan DS uses to merge the files.

Serena® ChangeMan® DS 5.7.1 User’s Guide

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

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

158

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.

Serena® ChangeMan® DS 5.7.1 User’s Guide Field

Description

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

Project

to browse for an area from a list of Production areas.

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.

TARGET RULES FOR MERGING The 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 Tree If 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).

159

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 In If 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 Synchronization If 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 FILES The 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

160

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

Serena® ChangeMan® DS 5.7.1 User’s Guide •

“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:

File 1

Map

Common Ancestor

Merged File

File 2

Status Bar

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

161

Chapter 10: Merging •

“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

•

“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:

162

•

“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

Serena® ChangeMan® DS 5.7.1 User’s Guide ChangeMan Word Diff supports the following versions of Microsoft Word: •

Microsoft Word 97 (v 8.0)

•

Microsoft Word 2000 (v 9.0)

•

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 Diff You 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 RULES The 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

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 MERGE When 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.

164

SYNCHRONIZING

11

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 1.

Action 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

Chapter 11: Synchronizing Step 4.

Action 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.

166

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.

Serena® ChangeMan® DS 5.7.1 User’s Guide Step 7.

Action 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.

167

Chapter 11: Synchronizing

168

MANAGING BUILDS

12

Build Management provides distributed build functionality with UNIX and Microsoftstyle 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

Chapter 12: Managing Builds 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.

MAKE PROCEDURES You 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:

170

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.

Serena® ChangeMan® DS 5.7.1 User’s Guide 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 OPTIONS Expand the project node and right-click the Make Procedures node of that project to display the available build options.

171

Chapter 12: Managing Builds 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.

172

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.

Serena® ChangeMan® DS 5.7.1 User’s Guide

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

Chapter 12: Managing Builds

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

•

Choose Properties from the Project menu.

on the Project toolbar

The ChangeMan DS Make Configuration window displays.

174

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.

Serena® ChangeMan® DS 5.7.1 User’s Guide

Defining Make Procedure Properties Select 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

Chapter 12: Managing Builds In this field…

Enter…

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

176

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.

Serena® ChangeMan® DS 5.7.1 User’s Guide In this field…

Enter…

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.

Defining Make Procedure Pre Compile Script Select 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.

177

Chapter 12: Managing Builds Use the following buttons to edit the Make 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.

Defining Make Procedure Global Compile Script Select 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.

178

Serena® ChangeMan® DS 5.7.1 User’s Guide 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: This button…

Performs this function… Start editing the selected line. Create a new line.

Delete a selected line.

Move a selected line up.

Move a selected line down.

179

Chapter 12: Managing Builds

Defining Make Procedure Post Compile Script Select 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: This button…

Performs this function… Start editing the selected line. Create a new line.

Delete a selected line.

Move a selected line up.

Move a selected line down.

180

Serena® ChangeMan® DS 5.7.1 User’s Guide

Make Procedure Targets ChangeMan 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 Target Note 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

Chapter 12: Managing Builds Step 3.

Action 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.

4.

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.

Click OK to finish the target configuration process. You can define multiple levels of subdependencies.

Adding Target Information from a Project Instead 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.

182

Serena® ChangeMan® DS 5.7.1 User’s Guide To add target files to a make procedure: 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.

Modifying Target Properties Use this procedure to modify target file properties: Step 1.

Action Select the target file. When you select a target or dependency file, ChangeMan DS displays its properties in the Item Window.

2.

Do one of the following: •

Right-click, then choose Properties.

•

Click

on the Project toolbar

Choose Properties from the Project menu. 3.

Make the changes, then click OK.

183

Chapter 12: Managing Builds

Make Procedure Dependencies The 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 1.

184

Action Select the target file node under the Project Make Procedures.

Serena® ChangeMan® DS 5.7.1 User’s Guide Step 2.

Action Do one of the following: •

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.

185

Chapter 12: Managing Builds Step 3.

Action 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.

4.

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.

Click OK to finish the target configuration process. You can define multiple levels of subdependencies by repeating this procedure.

Adding a Dependency You can create a dependency after a target is created under a named make procedure. Dependencies can exist under targets or other dependencies.

186

Serena® ChangeMan® DS 5.7.1 User’s Guide To add a dependency to the project, expand the 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: Step 1.

Action Select the target file. ChangeMan DS displays the file’s properties in the Content Window.

2.

3.

Do one of the following: •

Right-click, then choose Properties.

•

Click

•

Choose Properties from the Project menu.

on the Project toolbar

Make any necessary changes, then click OK.

Examples of Build Scripts The 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.

187

Chapter 12: Managing Builds Visual Basic Script Example for Builds In 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 Example This example is for a basic Java project that creates a single .jar file as its deliverable output. The example assumes the following:

188

•

All source code starts at relative path .\src

•

The jar file is stored at .\lib\myJar.jar

Serena® ChangeMan® DS 5.7.1 User’s Guide

Step 1.

Action Create a new make procedure with the following information in each of the tabs: Pre Compile Tab SET 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:\myDepend encies\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 Tab javac -sourcepath .\src\*.java -d .\classes (This compiles everything under .\src and puts the class files in .\classes.) Post Compile Tab jar -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.

INITIATING THE BUILD PROCESS Invoke the Build process from the Make Procedures node for a project, or through ChangeMan DS scripts.

189

Chapter 12: Managing Builds 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

1.

Expand the project.

2.

Select the Make Procedures node.

3.

Do one of the following: •

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.

190

Serena® ChangeMan® DS 5.7.1 User’s Guide

User Login Information for the Build Host Supply 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 ChangeMan DS agent or server service to the list of users with the right Act as part of the operating system and Log on as a service.

For the user ID for executing builds:

Windows 9x

•

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.

Add the following lines to the vcs_serv.ins file in your ChangeMan DS \Client directory: ValidateMakePassword=1 MakeUser=abc MakePassword=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=xyz ValidateUser=abc ValidateAreaPassword=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

Chapter 12: Managing Builds

BUILD HISTORY At 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 History Use this procedure to review build history: Step

192

Action

1.

Expand the project.

2.

Expand the Make Procedure node to see the History node.

Serena® ChangeMan® DS 5.7.1 User’s Guide Step

Action

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.

Understanding the Build History Target and dependency files display one of the following icons: This icon…

Indicates… A successfully built target.

An unsuccessfully built target.

193

Chapter 12: Managing Builds This icon…

Indicates… 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.

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 File Although 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 Storage By 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

194

Serena® ChangeMan® DS 5.7.1 User’s Guide contains pre-compile commands projectname.newmakename.1 contains global compile commands projectname.newmakename.2 contains post-compile commands makes.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 history projectname.newmakename.1 contains global compile command history projectname.newmakename.2 contains post-compile command history makes.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 History If you no longer need a build record, you can delete it with the following procedure: Step 1.

Action Expand the Make Procedure node.

195

Chapter 12: Managing Builds Step

Action

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.

IMPORTING A MAKE FILE You can automatically populate a project’s build procedures by importing an existing make file. Use this procedure to import a make file: Step

196

Action

1.

Expand the area node containing the existing make file.

2.

Select an existing make file from the displayed list of files.

Serena® ChangeMan® DS 5.7.1 User’s Guide Step 3.

Action Do one of the following: •

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).

197

Chapter 12: Managing Builds Step

198

Action

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.

Serena® ChangeMan® DS 5.7.1 User’s Guide Step 10.

11.

Action 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).

When all items have been completed, click OK.

199

Chapter 12: Managing Builds Step 12.

Action 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.

EXPORTING MAKE PROCEDURES You can export existing ChangeMan DS make procedures into an external make file. To export the make procedures: Step

Action

1.

Expand the project node.

2.

Select the Make Procedure node.

3.

Do one of the following: •

Click

on the Project toolbar

•

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.

200

Enter the name of an external make file.

Serena® ChangeMan® DS 5.7.1 User’s Guide Step 5.

Action 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.

TROUBLESHOOTING BUILDS UNIX: 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.

201

Chapter 12: Managing Builds 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.

202

MANAGING RELEASES

13

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 RELEASES Freezing 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

Chapter 13: Managing Releases Use this procedure to freeze a project: Step 1.

Action 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.

4.

Supply the following information: Release

Label used to identify this release.

Description

Brief description of this release.

Click OK to freeze the release.

A new release node is created for your project.

204

Serena® ChangeMan® DS 5.7.1 User’s Guide 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

Chapter 13: Managing Releases 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 RELEASE Once 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: 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.

ROLLING BACK A RELEASE The 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

206

Action

1.

Expand the project node.

2.

Expand the Frozen node.

3.

Select the release.

4.

Right-click, then choose Rollback from the right-click menu.

Serena® ChangeMan® DS 5.7.1 User’s Guide 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 Release Use this procedure to detach files from an existing release: Step

Action

1.

Select the release.

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

Chapter 13: Managing Releases

Attaching New Files to an Existing Release Use this procedure to attach a new file to an existing release: Step

Action

1.

Select the release.

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 5.

from the toolbar.

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.

Changing Properties of a Frozen Release The 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

208

Serena® ChangeMan® DS 5.7.1 User’s Guide — 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 RELEASE The 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 FILE The 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 be included in this frozen release.

and select the file to

•

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

Chapter 13: Managing Releases

TROUBLESHOOTING RELEASES I 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.

210

14

REPORTING

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 TREE The 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

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: 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.

From the File Tree, you can perform different actions by selecting a version (or versions) of the file, and clicking a toolbar button.

212

Serena® ChangeMan® DS 5.7.1 User’s Guide 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 TRAIL ChangeMan 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 Reports You 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 the Tools menu.

on the Tools toolbar or choose Audit Trail from

•

From your IDE (refer to their documentation).

213

Chapter 14: Reporting •

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 File Use this procedure to view the audit trail from ChangeMan DS: Step 1.

Action 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.

214

Continue to “Working with Audit Trail Reports” on page 222.

Serena® ChangeMan® DS 5.7.1 User’s Guide

Creating an Audit Trail Report with a Query Use 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 clients)

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 information 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.

4.

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

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

Chapter 14: Reporting Step 5.

Action 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.

Saving a Query In the Web browser and Java clients, the Save Query option is not available. Use this procedure to save a query: Step 1.

Action 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.

216

Serena® ChangeMan® DS 5.7.1 User’s Guide

Creating an Audit Trail Report Using a Saved Query In 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: Step 1.

Action 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.

Viewing an Audit Trail from an IDE The 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 Trail Specify 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

217

Chapter 14: Reporting General Tab on Audit Trail Window Use 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 the Projects dialog box.

to select a project ID from

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 the user name from the User List dialog box.

218

to select

Serena® ChangeMan® DS 5.7.1 User’s Guide In this Field…

Enter…

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.

Location Tab on Audit Trail Window Use 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. Items on the screen are: In this Input Field…

Enter…

Source Area

The 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 Area

The name of a target area (or click next to the area field, then select the area from the displayed list).

219

Chapter 14: Reporting In this Input Field…

Enter…

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.

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.

220

Serena® ChangeMan® DS 5.7.1 User’s Guide Items on the screen are: 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

Chapter 14: Reporting Hierarchical View of the Audit Trail On 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 Reports After 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 Layout You can alter the view of the reports by manipulating the columns as follows:

222

•

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.

Serena® ChangeMan® DS 5.7.1 User’s Guide •

Sort the information by any of the columns by clicking on that column header.

Printing an Audit Trail Report You 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: Step 1. 2.

Action Create an audit trail report for the file or files. 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.

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.

223

Chapter 14: Reporting Use this procedure to delete a record from an audit trail report: Step

Action

1.

Select the record you want to delete from the Audit Trail report.

2.

Either: •

click Delete window.

from the toolbar at the bottom of the Audit Trail

•

right-click on the selected file and choose Delete.

The “Are you sure?” prompt displays. 3.

Click OK.

Comparing a File with the Previous Version A 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.

224

Serena® ChangeMan® DS 5.7.1 User’s Guide Use this procedure to roll back to a previous version of a file: 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.

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 Report You 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 File View 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.

225

Chapter 14: Reporting Viewing a File View 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 Descriptions View 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 Transfers Repeat 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 Report To 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 Trail Why 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.

226

Serena® ChangeMan® DS 5.7.1 User’s Guide 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 ANALYSIS ChangeMan 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

Chapter 14: Reporting

Performing Impact Analysis Impact 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 Analysis To 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.

228

Serena® ChangeMan® DS 5.7.1 User’s Guide Step 3.

Action 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.

Itemized Impact Analysis Itemized Impact Analysis identifies all files that use a specific element, function, or include file. To perform an itemized Impact Analysis: Step 1.

2.

Action 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.

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.

229

Chapter 14: Reporting Step 3. Optional.

Action 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.

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 •

230

“Modifying a Column Layout” on page 222

Serena® ChangeMan® DS 5.7.1 User’s Guide •

“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 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.

Columns for Web Browser Client The Web client display includes special characters as well as alphanumeric characters. Information displayed includes the following: This column…

Displays this information…

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

Chapter 14: Reporting This column…

Displays this information…

Area

The name of the Production area this file belongs to.

Path

The directory path to the Production area this file belongs to.

Printing Impact Analysis Reports Print your Impact Analysis report, by either •

Clicking

on the Impact Analysis toolbar.

•

Selecting the content window and clicking

To preview you report before printing, click

on the Standard toolbar. .

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.

232

Serena® ChangeMan® DS 5.7.1 User’s Guide 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 Module To exit the Impact Analysis module, either click Close Analysis toolbar or click Exit from the Web client.

from the Impact

Troubleshooting Impact Analysis Why 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

where the is the name of the Production area. By default, vcs_doc.exe is located in the \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

Chapter 14: Reporting

234

Serena® ChangeMan® DS 5.7.1 User’s Guide

235

Chapter 14: Reporting

236

APPROVING FILE TRANSFERS

15

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

Chapter 15: Approving File Transfers

APPROVING A PENDING TRANSACTION FROM EXPLORERVIEW To approve a pending transfers from ExplorerView: Step 1.

Action 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.

Note

238

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.

Serena® ChangeMan® DS 5.7.1 User’s Guide

APPROVING A PENDING TRANSACTION FROM AN AUDIT TRAIL REPORT To approve pending transactions that are listed in an Audit Trail report: Step 1.

Action 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.

2. 3.

b)

Click on the Filter tab.

c)

Deselect all but Pending in the Status group.

d)

Click Find Now.

Select one or multiple pending transactions. 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 5.

Modify the list by removing pending transfers from the list by selecting the entries, and clicking Remove. Approve all pending transfers in the list by clicking Approve All.

239

Chapter 15: Approving File Transfers Step 6.

Action 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.

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 TRANSFER When 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: Step 1.

240

Action 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.

Serena® ChangeMan® DS 5.7.1 User’s Guide Step

Action

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.

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 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 FILE You 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: 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.

241

Chapter 15: Approving File Transfers

242

PACKAGE-ORIENTED APPROACH

16

ChangeMan DS offers two approaches to file organization: projects and the packageoriented 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

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 APPROACH The following steps describe how to manage code using the package-oriented approach.

244

Serena® ChangeMan® DS 5.7.1 User’s Guide 1. New files are placed under the control of ChangeMan DS. The new file is checked into the Production Production (baseline) area. Area New File

The new file is attached to a ChangeMan DS project. Associated Project

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. Development Areas

Projects Application

Add projects to the application to define the scope the applications.

Installation Areas

Attach all areas available to developers who will be working on the code components for this application.

Attach Installation areas to your application. Installation of a package moves files marked as deliverable into these areas.

See “Creating an Application” on page 250. 3. A change package is created that defines the files that need to be changed. Package The package is a subset of projects and areas of a parent application. It defines the change set. Application

245

Chapter 16: Package-Oriented Approach See “Creating a Package” on page 261. 4. A developer is notified of the change, and edits the file. Development Area

Production Area

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. 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. Production Files

Frozen Release

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. 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.

246

Serena® ChangeMan® DS 5.7.1 User’s Guide 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. Production Area

Installation Area

When a package is installed, the files marked as deliverable are moved to the installation area that is designated in the package. 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 FUNCTIONALITY Package 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.

247

Chapter 16: Package-Oriented Approach 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.

APPLICATIONS An 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.)

248

Serena® ChangeMan® DS 5.7.1 User’s Guide 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

Chapter 16: Package-Oriented Approach

Creating an Application To create an application: Step 1.

Action 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.

Adding Specifications to an Application When 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.

250

Serena® ChangeMan® DS 5.7.1 User’s Guide To attach specification files to an application: Step 1.

Action 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 client.

on the Java client or Click to edit on the Web browser

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.

Attaching Projects to an Application Attaching 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.

251

Chapter 16: Package-Oriented Approach To attach projects to a package: Step 1.

Action 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.

Attaching an Area to an Application There are two types of areas associated with an application: Installation and Development. •

252

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).

Serena® ChangeMan® DS 5.7.1 User’s Guide •

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 1.

Action 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.

To detach an area, select an Attached Area, then click Detach.

Optional 4. Optional

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.

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

Chapter 16: Package-Oriented Approach

Creating a Default Area Configuration Creating 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 1.

Action 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.

3.

4.

254

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.

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.

Click Exit.

Serena® ChangeMan® DS 5.7.1 User’s Guide

Working with an Application’s Projects The 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: 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.

PACKAGES Changes 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 Screen The Package Configuration screen is used for creating and modifying packages.

255

Chapter 16: Package-Oriented Approach 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.

256

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.

Serena® ChangeMan® DS 5.7.1 User’s Guide Select this tab…

To do this task…

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.

General Tab on Package Configuration Dialog The General tab on the Package Configuration dialog contains the following fields: 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.

257

Chapter 16: Package-Oriented Approach This field…

Contains…

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 shortterm 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 shortterm 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.

258

Serena® ChangeMan® DS 5.7.1 User’s Guide This field…

Contains…

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

Chapter 16: Package-Oriented Approach This field…

Contains…

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.

260

Change Request Number

A tracking number for the change request.

Description

A description of the package.

Note: The tracking number is assigned by the user. The Package ID number is assigned by ChangeMan DS.

Serena® ChangeMan® DS 5.7.1 User’s Guide

Creating a Package Use this procedure to create a new package under an application: Step 1.

Action 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

•

Description

See “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

Chapter 16: Package-Oriented Approach Step 8. Optional 9. Optional

Action On the Links tab, add any packages to link to this package. See “Linking Packages” on page 266. 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.

Adding Specifications to a Package Attach 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: Step 1.

Action 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.

262

In the Name field, enter a distinctive short identifier for the specifications file you are attaching.

Serena® ChangeMan® DS 5.7.1 User’s Guide Step 4. 5. 6.

Action In the Description field enter as much detail as you need to explain the file you are attaching. Click

on the Java client or Click to edit on Web browser client.

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.

Attaching Projects to a Package ChangeMan DS projects are associated with change packages to control the lowerlevel 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.

263

Chapter 16: Package-Oriented Approach Use this procedure to attach projects to a package: Step 1.

Action 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.

Attaching an Area to a Package The 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

264

Before attaching areas, you must add projects to the package.

Serena® ChangeMan® DS 5.7.1 User’s Guide 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 1.

Action 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 nondeliverable 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.

To detach an area, select an Attached Area, then click Detach.

Optional 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

Chapter 16: Package-Oriented Approach Step 6. Optional

Action 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.

Linking Packages You 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: Step 1.

Action 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.

266

5.

Repeat Step 4 as required.

6.

When all packages are linked, click Exit

Serena® ChangeMan® DS 5.7.1 User’s Guide

Adding Files to a Change Set Create 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 1.

Action 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

Chapter 16: Package-Oriented Approach Step 2.

Action 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.

3.

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.

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.

268

If there are no more files to add or remove, click Save, then click Exit.

Serena® ChangeMan® DS 5.7.1 User’s Guide

Adding a Contact (or Requester) to a Package The 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 1.

Action 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) b)

Select (New Company) in the Company drop-down. 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

Chapter 16: Package-Oriented Approach Step 3.

Action 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) b)

Select (New Contact) in the Requester drop-down. Click

.

The New Contact dialog displays.

4.

c)

Fill in the contact name, e-mail, and phone number.

d)

Click Save to save the information and exit the New Contact dialog.

Click Save on the Package dialog to save the changes.

Establishing a Hierarchy for Packages Hierarchy 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: Step 1.

Action 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.

270

Serena® ChangeMan® DS 5.7.1 User’s Guide Step 3.

Action 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.

Dependencies between Packages Dependency 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.

271

Chapter 16: Package-Oriented Approach 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 Finishto-Start (Freeze) and Finish-to-Start (Approve) dependencies are configured by default.

Adding Dependencies Between Packages You can add or delete any number of predecessor and successor packages in any order. Use this procedure to establish dependencies: Step 1.

Action 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.

272

Serena® ChangeMan® DS 5.7.1 User’s Guide Step 5.

Action 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.

Removing Dependencies Between Packages To remove existing dependencies between packages: Step 1.

Action 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.

273

Chapter 16: Package-Oriented Approach Step 3.

Action 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.

Creating a Dependency Rule for POA Use this procedure to configure a dependency rule: Step 1.

Action 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:

274

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.

Serena® ChangeMan® DS 5.7.1 User’s Guide Step 3.

Action Click Save. The new dependency is added to the list.

4.

Repeat Step 2 and Step 3 for each dependency.

Editing a Dependency Rule in POA To edit an existing dependency: Step 1.

Action 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.

275

Chapter 16: Package-Oriented Approach

Promoting a Package A 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 1.

Action 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.

276

Serena® ChangeMan® DS 5.7.1 User’s Guide Step

Action

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.

277

Chapter 16: Package-Oriented Approach

Promotion Types for Packages The 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.

278

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.

Serena® ChangeMan® DS 5.7.1 User’s Guide

Editing Files in a Package Under 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 1.

Action 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 Products 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

Chapter 16: Package-Oriented Approach Step 4.

Action 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 promoting the package to frozen.

•

See “Freezing Files of a Package” on page 282 for information about frozen releases.

Editing Files from the Attachments Node Under 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: Step 1.

Action 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.

280

Serena® ChangeMan® DS 5.7.1 User’s Guide Step 4.

Action 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.

• 5.

Open the file from the development area through your development tool.

Check in the file, on the file’s right-click menu, choose Promote > Check In, and complete the Transfer Request dialog.

Editing Files from the File Tree The 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: Step 1.

Action 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.

281

Chapter 16: Package-Oriented Approach Step 2.

Action 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. • 6.

Open the file from the development area through your development tool.

Check in the file, select the file, click

, then complete the

Transfer Parameters dialog.

Freezing Files of a Package After 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.

282

Serena® ChangeMan® DS 5.7.1 User’s Guide 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: 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.

Viewing the History of a Package The promotion history of a package shows the status of a package in the development life cycle and what actions were performed on the package.

283

Chapter 16: Package-Oriented Approach To view history of the package: Step 1.

Action 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.

Life Cycle States for Packages You 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).

284

Serena® ChangeMan® DS 5.7.1 User’s Guide 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: •

__PreInstall

•

__PostInstall

These names should not exceed 255 characters.

285

Chapter 16: Package-Oriented Approach In this state…

This has occurred…

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 installation 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 automated install. See “Viewing Installation History of a Package” on page 289.

Creating Scripts for Package Installation Upon 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: •

286

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.

Serena® ChangeMan® DS 5.7.1 User’s Guide •

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 1.

Action 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

Chapter 16: Package-Oriented Approach Step 2.

Action 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 viewing and configuring the default scripts.

•

Controlled File, which uses the specified file under ChangeMan DS that contains the commands. (Using a file is the preferred 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) 3.

288

Select Save to apply the changes, or Exit to close the dialog without applying the changes.

To delete a script, click

on the Scripts dialog.

Serena® ChangeMan® DS 5.7.1 User’s Guide

Viewing Installation History of a Package View the installation history of the package to find the installation log of the package. Use the following procedure to view the Installation History: Step 1.

Action 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.

4.

Select the appropriate tab: •

Last Activity

•

Complete History

Select an entry, then click Details. The History Entry Details dialog displays the installation information.

5.

Click Close to exit the dialog.

289

Chapter 16: Package-Oriented Approach

Searching for Packages To 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

3. Optional

4. Optional 5. Optional

290

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.

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.

On the Applications tab, select any listed application to search for packages attached to a specific application. On the Creators tab, select one or more users to search for packages created under those names.

Serena® ChangeMan® DS 5.7.1 User’s Guide Step 6. Optional 7. Optional

8. Optional

9.

Action On the Attached Projects, select a project to search for packages associated with it. 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.

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.

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.

To clear the criteria and perform a new search, you must exit from the search dialog, then click

again.

291

Chapter 16: Package-Oriented Approach

Saving a Package Search If 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: 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.

SETTING SECURITY PERMISSIONS FOR POA ChangeMan DS comes with a selection of predefined security permissions for packages and applications. Security can be set at any of the following levels:

292

•

Application

•

Individual application

•

All packages in an application

Serena® ChangeMan® DS 5.7.1 User’s Guide •

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

Chapter 16: Package-Oriented Approach 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. Step

Action

1.

Log in as an administrator.

2.

Determine how security is to be administered:

3.

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.

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.

The status of denied or granted is added to the authorization list under the Access column of the Authorization Configuration form.

294

Serena® ChangeMan® DS 5.7.1 User’s Guide 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 POA An 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 Process The 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

Chapter 16: Package-Oriented Approach Use this procedure to configure an approval process: Step 1.

Action 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.

Approving Packages When 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.

296

Serena® ChangeMan® DS 5.7.1 User’s Guide 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: Step 1.

Action 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.

5.

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).

Click Activate.

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.

297

Chapter 16: Package-Oriented Approach

Creating an Approval Group in POA To create an approval group: Step 1.

Action 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.

Adding and Removing Users from an Approval Group When 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.

298

Serena® ChangeMan® DS 5.7.1 User’s Guide

Setting the Approval Order for Packages You 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 POA Use 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 1.

Action 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

Chapter 16: Package-Oriented Approach Step 4.

5.

Action 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.

Click Save, then click Exit.

Configuring Notifications for Approvals You 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 Notifications Approval 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:

300

•

“Enabling Default Approval Group Notification” on page 301

•

“Creating Custom Approval Group Notifications” on page 302

Serena® ChangeMan® DS 5.7.1 User’s Guide Approver Properties Notifications Approver 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 Notification You 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

Chapter 16: Package-Oriented Approach Creating Custom Approval Group Notifications To create custom Approval Group Notifications: Step 1.

Action 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.

302

Serena® ChangeMan® DS 5.7.1 User’s Guide Step 6.

Action 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.

Configuring Approver Properties Notifications for POA You 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.

303

Chapter 16: Package-Oriented Approach To configure an Approver Properties notification for a member of an Approval Group: Step 1.

Action 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.

7.

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.

Click Save to save the notification.

Example of Creating an Approval Group with Approver Notifications This 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.

304

Serena® ChangeMan® DS 5.7.1 User’s Guide 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 1.

Action 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.

6.

On the Notification dialog under the Notification List, click New to add a notifier.

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.

12.

On the Notification dialog under the Notification List, click New to add a notifier.

305

Chapter 16: Package-Oriented Approach Step

Action

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.

DATA SOURCES Data 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: . 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: . 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.

306

Serena® ChangeMan® DS 5.7.1 User’s Guide 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 in the User/Group ID field. The message will then be sent to the current assignee. Similarly, the 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: ==31

This means that this approval process will be applied to all packages coming from applications with ID of 31. is a parameter, referencing Application_id field value of package object instance. •

In a notification, set the criteria to: ==1 AND ==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 id FROM AppAreas INNER JOIN vcs01 ON AppAreas.AreaName = vcs01.area_id WHERE AppAreas.AppId= AND vcs01.area_type='t' AND AppAreas.StateObjId = 0 UNION SELECT AppAreas.id id FROM AppAreas INNER JOIN vcs01 ON AppAreas.AreaName = vcs01.area_id WHERE AppAreas.AppId= AND vcs01.area_type='d' AND AppAreas.StateObjId = 0 ) AND EXISTS ( SELECT AppComponents.id id FROM AppComponents

307

Chapter 16: Package-Oriented Approach INNER JOIN vcs09 ON AppComponents.ProjectName = vcs09.proj_id INNER JOIN PackageComponents ON AppComponents.id = PackageComponents.AppComponentsId WHERE AppComponents.AppId= AND PackageComponents.PackageId= )

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 Sources The 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 Source The CurrentApprover data source provides information on current approver. That information includes:

308

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.

Serena® ChangeMan® DS 5.7.1 User’s Guide This field…

Contains this information…

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.

CurrentGroupApprovers Data Source The CurrentGroupApprovers data source provides a list of all approvers in the current Approver's group. That information includes: This field…

Contains this information…

UserGroupType

Defines type of the entry.

UserGroupId

Reference to UserSys or GroupUser table, depending on UserGroupType value.

FormCode Data Source Unused. The FormCode data source retrieves a form code that is configured for an associated object instance.

ObjectCode Data Source The ObjectCode data source retrieves ApprovalProcess information for the current approval. That information includes: This field…

Contains this information…

id

ApprovalProcess unique ID

ApprovalGroupId

Associated Approval Group unique ID

ApprovedActivityName

Name of activity that will be executed when approval succeeds

309

Chapter 16: Package-Oriented Approach This field…

Contains this information…

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

Package Data Source The package data source contains information on an associated package. That information includes:

310

This field…

Contains this information…

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

Serena® ChangeMan® DS 5.7.1 User’s Guide This field…

Contains this information…

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

NOTIFICATIONS ChangeMan 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.

311

Chapter 16: Package-Oriented Approach

Creating a Notification Use this procedure to create a notification: Step 1.

Action 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

11.

312

to check the criteria syntax.

Set the Priority

Serena® ChangeMan® DS 5.7.1 User’s Guide Step 12.

Action 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.

14.

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.

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.

313

Chapter 16: Package-Oriented Approach

Activity/Event Drop-Down List for Notifications The 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: 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.

Notification Data Source The 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.

314

Serena® ChangeMan® DS 5.7.1 User’s Guide The available data sources are: Data source and Description

Field

Field Description

AllApp

id

Application unique ID

Query list of all applications in the system.

Name

Application name

AllLevels

id

Numeric level identifier

Retrieve list of all possible package levels.

Name

Symbolic level identifier

AllStates

Name1

Name of state

Name2

A copy of Name1 value

AllTypes

id

Numeric type identifier

Retrieve list of all possible package types.

Name

Symbolic type identifier

AllUsers

id

User unique ID

Query list of all users in the system.

Name

Username + user full name

AllUsersGroups

Type

0 for users and 1 for groups

Query list of all users and groups in the system.

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

Name

Application name

Retrieve all states of General Package life cycle.

ApplicationName Retrieve application name for current package.

315

Chapter 16: Package-Oriented Approach Data source and Description

Field

Field Description

AttachedAreas

id

Unique ID of packageareas record

AppId

Application unique Id

AreaName

Area name

WorkDir

Work directory (in area)

ProjectName

Project name

id

Unique ID of PackageComponents record

AppId

Application unique ID

ProjectName

Project name

AllApp

id

Application unique ID

Query list of all applications in the system.

Name

Application name

AllLevels

id

Numeric level identifier

Retrieve list of all possible package levels.

Name

Symbolic level identifier

AllStates

Name1

Name of state

Retrieve all states of General Package life cycle.

Name2

A copy of Name1 value

AllTypes

id

Numeric type identifier

Retrieve list of all possible package types.

Name

Symbolic type identifier

AllUsers

id

User unique ID

Query list of all users in the system.

Name

Username + user full name

Retrieve list of configured areas for the package.

AttachedAttachments Retrieve list of configured projects for the package.

316

Serena® ChangeMan® DS 5.7.1 User’s Guide Data source and Description

Field

Field Description

AllUsersGroups

Type

0 for users and 1 for groups

Query list of all users and groups in the system.

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

Name

Application name

AttachedAreas

id

Retrieve list of configured areas for the package.

Unique ID of PackageAreas record

AppId

Application unique Id

AreaName

Area name

WorkDir

Work directory (in area)

ProjectName

Project name

id

Unique ID of PackageComponents record

AppId

Application unique ID

ProjectName

Project name

ApplicationName Retrieve application name for current package.

AttachedAttachments Retrieve list of configured projects for the package.

317

Chapter 16: Package-Oriented Approach Data source and Description

Field

Field Description

AttachedeCMfiles

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”

CompanyName

id

Company unique ID

Retrieve package requester's company.

Name

Company name

CurrentUserID

id

UserSys unique ID

Retrieve information on logged in user.

Username

User name

FullName

User full name

Retrieve “change set” for the package.

318

Serena® ChangeMan® DS 5.7.1 User’s Guide Data source and Description

Field

Field Description

DefaultConfig

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

id

ApprovalAssignment unique ID

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”

Retrieve default area configuration for an application.

DeletePackageApprovalA ssignment Retrieve list of existing ApprovalAssignment records associated with the package. DeletePackageeCMFiles Retrieve “change set” for the package.

319

Chapter 16: Package-Oriented Approach Data source and Description

Field

Field Description

DeletePackageSec

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

EmptyDate

Null value of smalldatetime type

Retrieve list of configured security permissions for the package (noninherited).

EmptyDate Get null value of smalldatetime type. ListGroups

(fields from GroupUser table - group profile)

Query list of all groups in the system. ListUsers

(fields from UserSys table - user profile)

Query list of all users in the system. id

PackageAreas unique ID

PkgPermissions

id

Permission unique ID

Query list of applicable permissions for packages.

Name

Permission name

Description

Permission description

PackageAreasForProject Query list of IDs of configured areas for the package.

320

Serena® ChangeMan® DS 5.7.1 User’s Guide Data source and Description

Field

Field Description

StateApp

id

Unique ID of life cycle state

Retrieve list of states for object Package.

Name

Name of life cycle state

Description

Description of life cycle state

UnattachedApplicationAre as

Not applicable

Unused; at the time, returns list of all applications. UnattachedApplicationAtt achments Get 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)

ProjectName

Project name

321

Chapter 16: Package-Oriented Approach

322

HOST VIEW

17

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 VIEW The 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

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 Level To view a list of commands available for a file, select a file and right-click.

Exploring a UNIX Host Step 1.

Action 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.

324

Double-click the directory folder to view the files.

Serena® ChangeMan® DS 5.7.1 User’s Guide 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 VIEW To 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

Chapter 17: Host View

Adding a Host All 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. 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.

The node representing a host appears on the left side of the Host View screen. There are node icons for each operating system type. Node Icon

Operating System Windows UNIX

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.

326

Serena® ChangeMan® DS 5.7.1 User’s Guide

Removing a Host Step 1.

Action Select the host node to delete from Host View.

2. Click Remove Hosts

.

ChangeMan DS removes the selected host from the screen.

MANAGING HETEROGENEOUS HOSTS When 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

327

Chapter 17: Host View

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:

4.

328

•

File name

•

Security attributes

•

Owner

•

Group

Modify as required, then click Apply to employ the new file properties.

Serena® ChangeMan® DS 5.7.1 User’s Guide

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.

4.

Click from the Host toolbar, or right-click and choose Properties from the right-click menu. Modify as required, then click Apply.

329

Chapter 17: Host View

330

OS/400 Environments

18

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 AGENT When 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

Chapter 18: OS/400 Environments •

Scripting Behavior for the AS/400

MAKE BEHAVIORS FOR AS/400 ChangeMan 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/ *.MBR or 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

•

332

The build directory for the target must be ../.

Serena® ChangeMan® DS 5.7.1 User’s Guide •

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.

Troubleshooting If 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/400 ChangeMan DS supports any object transfer on OS/400 systems, such as: •

Files from root file system to QSYS.LIB file system. Any file (.) that is targeted into /QSYS.LIB/.LIB/ .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.txt To: /QSYS.LIB/MYLIB.LIB/MYFILE.FILE/ Results: /QSYS.LIB/MYLIB.LIB/MYFILE.FILE/MyTest.MBR ChangeMan DS attempts to store any file (.) that is targeted into / QSYS.LIB/.LIB/ according to QSYS.LIB file system rules, recognizing the QSYS.LIB object type by the . For example: Check out file: /ProdDir/Mytest.PGM To: /QSYS.LIB/MYLIB.LIB/ Results: /QSYS.LIB/MYLIB.LIB/MYTEST.PGM Another example: Check out file: /ProdDir/MyTest.MBR To: /QSYS.LIB/MYLIB.LIB/ Results: Fail

•

Objects or files from QSYS.LIB file system to root file system. Any object (.) 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

Chapter 18: OS/400 Environments •

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/400 ChangeMan 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 #!AS400EBCDIC 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:

334

•

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.

Serena® ChangeMan® DS 5.7.1 User’s Guide

SCRIPTING EXAMPLES FOR AS/400 These 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" System Note

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

Chapter 18: OS/400 Environments 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" System Note

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

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" System Note

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 example distributes a checked in source physical file member with "/ QSYS.LIB" File System script execution (CL commands) on AS/400: CALL QP2SHELL +

336

Serena® ChangeMan® DS 5.7.1 User’s Guide (‘’/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" System Note

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

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 System These 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 Execution You 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

Chapter 18: OS/400 Environments 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-EBCDIC CPYF FROMFILE(MYLIB/ QCLSRC) TOFILE(YOURLIB/ QCLSRC) + FROMMBR(MYMEMBER) TOMBR(MYMEMBER) MBROPT(*REPLACE)

VCS VARIABLES FOR AS/400 The 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.

338

Root File System (Unix)

/QSYS.LIB file system (Native)

Description

from_dir

from_dir

(IS, POA)

(IS, POA)

Path of the directory from which the file is being transferred.

from_id

from_id

(IS, POA)

(IS, POA)

home_id

home_id

(IS, POA)

(IS, POA)

main_node

main_node

(IS, POA)

(IS, POA)

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

to_dir

(IS, POA)

(IS, POA)

Path of the target directory to which the file is being transferred.

Name of the ChangeMan DS area from which the file is being transferred. Name of the ChangeMan DS Production area for the file being transferred. Host name where the ChangeMan DS Main Server is installed.

Serena® ChangeMan® DS 5.7.1 User’s Guide Root File System (Unix)

/QSYS.LIB file system (Native)

Description

to_id

to_id

(IS, POA)

(IS, POA)

Name of the ChangeMan DS area to which the file is being transferred.

vcsdescription

vcsdescription

(IS)

(IS)

vcsfile

vcsfile

(IS)

(IS)

vcsfile_prefix

vcsfile_pr

(IS)

(IS)

vcsfile_suffix

vcsfile_su

(IS)

(IS)

Contains the period and the portion of the file name which appears to the right of the period; for example, .exe.

vcsproject

vcsproject

Name of the project being transferred.

(IS, POA)

(IS, POA)

Available only when projects are being transferred.

vcstime

vcstime

Date and time of the file being transferred.

(IS)

(IS)

vcsuser

vcsuser

(IS, POA)

(IS, POA)

vcsversion

vcsversion

(IS)

(IS)

Contains the description from the transfer request up to the first new line break. Contains the file name currently transferred by ChangeMan DS; for example, pay100.exe. Portion of the file name, which appears to the left of the period; for example, pay100.

Name of the user who originated the file transfer process. Version number associated with the file transfer process.

339

Chapter 18: OS/400 Environments

340

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

INSTALLATION When 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

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 :. 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:

342

Serena® ChangeMan® DS 5.7.1 User’s Guide 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_LANG ORA_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 VERSIONS In the ChangeMan DS Windows client, choose About from the Help menu.

343

Appendix A: Troubleshooting

CONNECTING TO CHANGEMAN DS Why 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 CLIENT When 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.

344

Serena® ChangeMan® DS 5.7.1 User’s Guide 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

Appendix A: Troubleshooting

346

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 WINDOW The 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

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 Explorer When you select the Areas or Projects node in the ExplorerView tree, the following columns are displayed in the content window: Column

Displays

Type

The icon for the contents in the selected area.

Name

The name for the contents in the selected area.

Selecting an Area Type in Explorer View When 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: 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.

Selecting a User-Created Area or Project in ExplorerView

348

Serena® ChangeMan® DS 5.7.1 User’s Guide When you select a user created area or project 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.

Selecting a Directory Node in ExplorerView When you select a directory under an area node in the ExplorerView tree, the following columns are displayed in the content window: 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

Appendix B: User Interface Reference Column

Displays

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.

Selecting a Project Type Node in ExplorerView When you select a project type node in the ExplorerView tree, the following columns are displayed in the content window: 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.

Selecting a Frozen Release Node in ExplorerView When you select the Frozen Release node under a project in the ExplorerView tree, the following columns are displayed in the content window:

350

Column

Displays

Type

The icon for contents in the selected area.

Release

The label used to identify a release.

Serena® ChangeMan® DS 5.7.1 User’s Guide Column

Displays

User

The owner of the release.

Date

When the release was created.

Description

The description entered about a release.

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 ExplorerView When you select the Make Procedures node under a project in the ExplorerView tree, the following columns are displayed in the content window: 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.

Selecting the Attachments Node in ExplorerView

351

Appendix B: User Interface Reference When you select the Attachments node under a project in the ExplorerView tree, the following columns are displayed in the content window:

352

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.

Type

The icon for contents in the selected area.

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

Serena® ChangeMan® DS 5.7.1 User’s Guide Column

Displays

Production Size

The size of the version of the file in Production.

Production Mod

When the file was introduced to Production.

Status Icons Status 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. Icon

Means File in a frozen release. This item is in a frozen release.

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 Column The 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

353

Appendix B: User Interface Reference 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.

354

Serena® ChangeMan® DS 5.7.1 User’s Guide This icon...

Indicates... 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.

355

Appendix B: User Interface Reference Status Icons for Production Status Column The 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.

356

Serena® ChangeMan® DS 5.7.1 User’s Guide Status Icons for Request Status Column The following icons appear in the Request Status column, depending on what item is active in the Explorer tree, and the status of the item. 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.

WINDOWS CLIENT UI When 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 Client The 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

357

Appendix B: User Interface Reference •

ChangeMan DS Main Window Hosts Menu

•

ChangeMan DS Main Window Tools Menu

•

ChangeMan DS Main Window Help Menu

ChangeMan DS Main Window File Menu This table describes the commands in the File 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.

ChangeMan DS Main Window Edit Menu This table describes the commands in the Edit menu for the ChangeMan DS Windows client:

358

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.

Serena® ChangeMan® DS 5.7.1 User’s Guide Command

Description

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.

ChangeMan DS Main Window View Menu This table describes the commands in the View menu for the ChangeMan DS Main Window: 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.

ChangeMan DS Main Window Promote Menu This 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. 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.

359

Appendix B: User Interface Reference Command

Description

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.

ChangeMan DS Main Window Project Menu This table describes the commands in the Project menu. See “Project Toolbar” on page 370 for additional methods to access this functionality.

360

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.

Serena® ChangeMan® DS 5.7.1 User’s Guide Command

Description

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.

ChangeMan DS Main Window Files Menu This table describes the commands in the Files menu. Note that you may access these commands on the “Files Toolbar” on page 369. 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.

361

Appendix B: User Interface Reference Command

Description

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.

ChangeMan DS Main Window Hosts Menu The 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. 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.

362

Serena® ChangeMan® DS 5.7.1 User’s Guide Command

Description

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.

ChangeMan DS Main Window Tools Menu This table describes the commands in the Tools menu. See “Tools Toolbar” on page 367 for additional ways to access this functionality: 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.

Performance Monitor

Opens the Performance Monitor dialog.

See “System Configuration Dialog” on page 374 for more information.

363

Appendix B: User Interface Reference Command

Description

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.

364

Serena® ChangeMan® DS 5.7.1 User’s Guide Command

Description

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.

ChangeMan DS Main Window Help Menu This table describes the commands in the Help menu on the ChangeMan DS Windows client: Command

Description

Help > Index

Help. Activates the ChangeMan DS Help module. Either:

Help > About ChangeMan DS

•

Click this button, then click on the item for which you want help.

•

Choose Help > Index to view the entire Help system.

Opens the About ChangeMan DS dialog and displays the versions and patch levels of the ChangeMan DS Client and Server in use.

Main Window Toolbars—Windows Client The 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.

365

Appendix B: User Interface Reference •

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 Toolbar The 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.

366

Serena® ChangeMan® DS 5.7.1 User’s Guide Tools Toolbar The 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

Appendix B: User Interface Reference Button

Description 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.

368

Serena® ChangeMan® DS 5.7.1 User’s Guide Files Toolbar The 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

Appendix B: User Interface Reference Button

Description 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.

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. 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.

370

Serena® ChangeMan® DS 5.7.1 User’s Guide Button

Description 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.

Promote Toolbar The 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. 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.

371

Appendix B: User Interface Reference Button

Description 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.

Hosts Toolbar The following table describes the Hosts toolbar elements; these elements provide access to file management operations in the Host View. 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.

372

Serena® ChangeMan® DS 5.7.1 User’s Guide Button

Description 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.

File List Toolbar and Submenu The 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. 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.

373

Appendix B: User Interface Reference Command

Button

Description

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.

System Configuration Dialog The 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.

374

Serena® ChangeMan® DS 5.7.1 User’s Guide 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: Command

Button

Description

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

Appendix B: User Interface Reference Command

Button

Description

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.

File > Print Preview

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.

ChangeMan DS Project Configuration Dialog The ChangeMan DS Project Configuration dialog lets you create, edit, copy, delete, and print projects.

376

Serena® ChangeMan® DS 5.7.1 User’s Guide 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 Dialog The 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 Module The 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

Appendix B: User Interface Reference •

“Advanced Tab for Impact Analysis” on page 378

Impact Analysis Toolbar At the bottom of the Impact Analysis dialog is a toolbar that provides the following commands: 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.

Impact Analysis from the Web browser and Java clients does not provide these commands.

Advanced Tab for Impact Analysis Select the Advanced tab on the Impact Analysis dialog to add search criteria. Note

378

The Web browser client Impact Analysis does not include an Advanced tab.

Serena® ChangeMan® DS 5.7.1 User’s Guide 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 and , where is the item name in the first search, and 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 or , where is the item name in the first search, and 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

Appendix B: User Interface Reference

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):

380

Serena® ChangeMan® DS 5.7.1 User’s Guide 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 ChangeMan DS > Audit Trail

Button

Description Audit trail. Opens the Audit Trail dialog. See “Running Audit Trail Reports” on page 213 for more information on the Audit Trail.

381

Appendix B: User Interface Reference Commands

Button

ChangeMan DS > Impact Analysis

Description 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

382

N/A

Opens the ChangeMan DS online help.

Serena® ChangeMan® DS 5.7.1 User’s Guide Commands

Button

N/A

Description Exit. Exits the ChangeMan DS client.

ChangeMan DS Web Client If 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.

383

Appendix B: User Interface Reference

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 DS Areas Projects Impact Analysis If you have access only to the Package/Application view, you see the following: ChangeMan DS Applications Approvals Approval Configuration Approval Groups Notification Configuration Contacts With both views are selected, you see the following: ChangeMan DS Areas Projects Applications Impact Analysis Approval Configuration Approval Groups Notification Configuration Contacts Dependency Configuration

384

Serena® ChangeMan® DS 5.7.1 User’s Guide

Changing Status Options You 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 Buttons The 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

Appendix B: User Interface Reference Applications Node Toolbar Buttons With 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.

386

Serena® ChangeMan® DS 5.7.1 User’s Guide With a created application selected in the ExplorerView tree, the following option is available: Command

Description Edit the selected application.

Packages Node under Applications Node When you select the Packages node under the Applications node, the following options are available: 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

Appendix B: User Interface Reference Command

Description See the promotion history of the package.

Set package access permissions for users and groups.

See the package installation history.

Projects Node under Applications The 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: Command

Description Edit the properties of the project.

Set the project to be installed automatically.

388

Serena® ChangeMan® DS 5.7.1 User’s Guide Command

Description Clear the deliverable status from the project.

View the Audit Trail.

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: 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 currentlyconfigured work area.

Promote the entire frozen release to the target Production area.

Transfers files to a quality assurance area.

389

Appendix B: User Interface Reference Command

Description 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.

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.

390

Serena® ChangeMan® DS 5.7.1 User’s Guide With the Contacts node 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

Approval Node Toolbar Buttons The 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 Opens the approval assignment life cycle for approval promotion.

Opens the approval assignment to view comments entered by previous approvers.

391

Appendix B: User Interface Reference Command

Description Displays the history of the approval assignment’s progress.

Updates the screen with the most recent promotion status.

Approval Configuration Node With the Approval Configuration node expanded and the Approval Groups node selected, the following options are available: 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.

392

Serena® ChangeMan® DS 5.7.1 User’s Guide Notification Configuration Node With the Notification Configuration node selected, the following options are available: 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.

Right-Click Menus The 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 Level ChangeMan 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.

393

Appendix B: User Interface Reference 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.

Remove from DS Control

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.

394

Serena® ChangeMan® DS 5.7.1 User’s Guide Command

Description

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.

Right-Click Menu at the Area Name Level ChangeMan 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 rightclick menu of the Web browser and Java clients: 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.

Remove from DS Control

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.

Refresh

Update the currently displayed page with any recently added information.

395

Appendix B: User Interface Reference Right-Click Menu at the Folder Level ChangeMan 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: 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.

Remove from DS Control

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.

Refresh

Update the currently displayed page with any recently added information.

Right-Click Menu at the Project Level ChangeMan DS operations to be applied to an entire project are executed by selecting a project on the left side of the ExplorerView.

396

Serena® ChangeMan® DS 5.7.1 User’s Guide The following table lists the primary options found in the project level right-click menu of the Web browser and Java clients: 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-intime 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.

Refresh

Update the currently displayed page with any recently added information.

PERFORMANCE MONITOR The 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.

397

Appendix B: User Interface Reference 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): 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:SS where HH is 2-digit hours, MM is 2-digit minutes, SS is 2-digit seconds.

The displayed information for each thread disappears as soon as that thread has terminated.

398

Serena® ChangeMan® DS 5.7.1 User’s Guide Following are the explanations for each of the columns displayed for a socket (the bottom window of the dialog): 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:SS where 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.

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: 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

Appendix B: User Interface Reference

FILE TREE UI The 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.

400

Serena® ChangeMan® DS 5.7.1 User’s Guide Java/Web Client

Windows Client

Description 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. The following table lists the options located at the bottom of the File Tree display: 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.

401

Appendix B: User Interface Reference Command

Description 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.

ChangeMan Diff MENUS AND TOOLBAR The 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.

402

Serena® ChangeMan® DS 5.7.1 User’s Guide To help you, the following commands are available on the ChangeMan Diff utility Help menu and Standard Toolbar (Windows client): Command

Button

Description

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.

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 Diff The ChangeMan Diff utility File menu and Standard toolbar consist of the following common tools: Command File > Do diff

Button

Description 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

Appendix B: User Interface Reference Command

Button

Description

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.

File > Print Preview

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 Menu—ChangeMan Diff The ChangeMan Diff utility Edit menu, Standard toolbar, and Edit/View toolbar consist of the following common tools: Command

404

Button

Description

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.

Serena® ChangeMan® DS 5.7.1 User’s Guide Command

Button

Description

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)

Note that the toolbar buttons are not available on the Web browser client.

Merge Menu—ChangeMan Diff Note

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.

405

Appendix B: User Interface Reference Note that depending on the change, these functions can be accessed by right-clicking on the change. Command

Button

Description

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 Menu—ChangeMan Diff The 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: Command Tools > Options

406

Button

Description Options dialog. Open the Diff Merge Manager to set options for file comparison.

Serena® ChangeMan® DS 5.7.1 User’s Guide Command

Button

Tools > Template Manager Tools > Set Template (Windows only)

Description Template manager. Open the Template Manager.

Dropdown list (Java client only)

Lets you select the template to use with this file.

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 Diff The ChangeMan Diff utility View menu, Standard toolbar, and Edit/View toolbar consist of the following common tools for controlling the display: Command

Button

Description

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

Appendix B: User Interface Reference Command

Button

Description

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.

View Options—ChangeMan Diff The following ChangeMan Diff View options can be set on the Diff Parameters toolbar or on the Diff tab of the Diff Merge Manager dialog.

408

Serena® ChangeMan® DS 5.7.1 User’s Guide See “Merging” on page 153 and “Comparing Files” on page 143 for more information on the following functions. Command

Button

Description Ignore case. Ignore case when comparing code.

Tools > Options (Java and Windows client) Diff > Ignore Case (Web browser client)

Ignore comments. Ignore comments when comparing code.

Tools > Options (Java and Windows client) Diff > Ignore Comments (Web browser client)

Ignore blank line. Ignore blank lines when comparing code.

Tools > Options (Java and Windows client) Diff > Ignore Blank Line (Web browser client)

Ignore spaces. Ignore spaces when comparing code.

Tools > Options (Java and Windows client) Diff > Ignore Spaces (Web browser client)

Diff Menu—ChangeMan Diff The following options are available from the Diff menu of the Web browser client: 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

Appendix B: User Interface Reference Option

Description

Diff > Ignore Blank Line

Ignore blank lines when comparing code.

Diff > Ignore Spaces

Ignore spaces when comparing code.

CHANGEMAN EDIT MENUS AND TOOLBARS ChangeMan 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.

410

Serena® ChangeMan® DS 5.7.1 User’s Guide 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: Command

Button

Description

File > New

New document. Select a template for a new document.

File > Open

Open. Open an existing file.

File > Close

N/A

File > Save File > Save As

Closes the active document. Save. Save the active file on the host of your choice.

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 Menu—ChangeMan Edit The Edit menu and Standard toolbar consist of the following common tools: Command

Button

Description

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

Appendix B: User Interface Reference Command

Button

Edit > Paste Edit > Select All

Description Paste. Paste a previously copied or cut item into a target location.

N/A

Selects all of the contents.

Edit > Undo

Undo. Undo the last action command.

Edit > Redo

Redo. Redo a previously undone action.

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. Command

Description

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

412

Button

N/A

Opens the Replace dialog.

Serena® ChangeMan® DS 5.7.1 User’s Guide Command

Button

Description

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.

See “View Menu—ChangeMan Edit” for additional commands on the View menu.

View Menu—ChangeMan Edit The View menu and Standard toolbar consist of the following common tools: Command

Button

Description

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.

Window Menu—ChangeMan Edit Note that open content windows are listed on the bottom of the Window menu. You can choose one to move its display to the front.

413

Appendix B: User Interface Reference The Window menu and Standard toolbar consist of the following common tools: Command

Button

Description

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 Menu—ChangeMan Edit The Tools menu and Tools toolbar provides access to ChangeMan Edit tools. Command

Description

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

414

Button

N/A

Opens the Output Window Properties dialog which sets the font type for the output script window.

Serena® ChangeMan® DS 5.7.1 User’s Guide See “View Menu—ChangeMan Edit” for the Monitor button on the Tools toolbar.

415

Appendix B: User Interface Reference

416

Serena® ChangeMan® DS 5.7.1 User’s Guide

417

Appendix B: User Interface Reference

418

Serena® ChangeMan® DS 5.7.1 User’s Guide

419

Appendix B: User Interface Reference

420

Serena® ChangeMan® DS 5.7.1 User’s Guide

421

Appendix B: User Interface Reference

422

Serena® ChangeMan® DS 5.7.1 User’s Guide

423

Appendix B: User Interface Reference

424

Serena® ChangeMan® DS 5.7.1 User’s Guide

425

Appendix B: User Interface Reference

426

Serena® ChangeMan® DS 5.7.1 User’s Guide

427

Appendix B: User Interface Reference

428

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

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 MODE Change 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

430

Toggles the display of the Map.

Serena® ChangeMan® DS 5.7.1 User’s Guide This option...

Does this...

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).

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: 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:

Green

•

different in the two files being merged,

•

merged without conflict. and

•

selected as final merge result.

431

Chapter C: ChangeMan Diff Module This category…

Indicates…

Default color…

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

EDITING THE MERGED FILE IN CHANGEMAN DIFF You 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 COMPARISON You 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.

432

Serena® ChangeMan® DS 5.7.1 User’s Guide

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 DIFF Redo the comparison by choosing File > Do Diff. Not available in the Web browser client.

REDOING A MERGE IN CHANGEMAN DIFF To 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 TEMPLATES Add or edit templates for the ChangeMan Diff utility to define how ChangeMan DS displays the text.

433

Chapter C: ChangeMan Diff Module 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 MERGE After 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 DIFF Add 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.

434

Serena® ChangeMan® DS 5.7.1 User’s Guide

TOGGLING DISPLAY OF MAP AND STATUS BAR To 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

Chapter C: ChangeMan Diff Module

436

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: 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.

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.

437

Appendix D: ChangeMan Edit Module

EDITING TEXT IN A CODE WINDOW ChangeMan 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.

438

Serena® ChangeMan® DS 5.7.1 User’s Guide

Copying a Selection Using Commands In ChangeMan Edit or ChangeMan Diff, use the following procedure to copy a selection: Step 1. 2.

Action Make a selection. 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.

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.

439

Appendix D: ChangeMan Edit Module

Copying a Selection Using the Drag-and-Drop Method In ChangeMan Edit or ChangeMan Diff, use the following procedure to copy a selection: Step

Action

1.

Make a selection.

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.

Finding Text Use this procedure to find a text string in ChangeMan Edit or ChangeMan Diff: Step 1.

Action 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:

4.

•

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 capitalization as the text displayed in the Find what box.

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.

To resume the Find search for the previously-defined criteria, click Repeat

440

.

Serena® ChangeMan® DS 5.7.1 User’s Guide

Moving a Selection Using Commands In ChangeMan Edit or ChangeMan Diff, use the following procedure to move a selection: Step 1. 2. 3. 4.

Action Make a selection. Click Cut

or choose Cut from the Edit menu.

Bring the insertion point to a new location. Click Paste

or choose Paste from the Edit menu.

Moving a Selection Using the Drag-and-Drop Method The 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: Step

Action

1.

Make a selection.

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.

Navigating the Text in Code Window Navigate 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:

441

Appendix D: ChangeMan Edit Module — 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.

442

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.

Serena® ChangeMan® DS 5.7.1 User’s Guide

Replacing Text Use this procedure to replace one text string with a different string: Step 1.

Action 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.

Undo and Redo Commands If 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.

443

Appendix D: ChangeMan Edit Module 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 BOOKMARKS Bookmarks 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 Bookmark Use 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.

444

Serena® ChangeMan® DS 5.7.1 User’s Guide

Removing a Bookmark Use this procedure to remove a bookmark in ChangeMan Diff or ChangeMan Edit: Step 1. 2.

Action Place the cursor in the line containing the bookmark. Click Toggle Bookmark Edit menu.

, or choose Toggle Bookmark from the

The bookmark symbol is removed from the Marker Bar.

Navigating to Bookmarks Use these actions to navigate bookmarks in ChangeMan Diff or ChangeMan Edit: 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.

IMPACT ANALYSIS FROM CHANGEMAN EDIT ChangeMan 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.

445

Appendix D: ChangeMan Edit Module The following procedure describes how to perform Impact Analysis from the code window. Step 1. 2.

Action Make a selection. Click Impact Analysis menu.

or choose Impact Analysis from the Edit

The result of this Impact Analysis search displays in the Impact Analysis Result 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 COMMAND In 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.

446

Serena® ChangeMan® DS 5.7.1 User’s Guide Use this procedure to run a command on a remote server: Step 1.

Action Click Run Remote Command Tools menu).

(or choose Run Command from the

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.

COMPILING A FILE ChangeMan 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.

447

Appendix D: ChangeMan Edit Module Use this procedure to compile a file: Step 1. 2.

Action Select the file. Click Save Compile menu).

(or choose Save & Compile from the Tools

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.

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.

448

Serena® ChangeMan® DS 5.7.1 User’s Guide 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 Script Use this procedure to configure a script that will analyze the compiler output: Step 1.

Action Click Output Script Tools menu).

(or choose Error Output Script from the

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

Appendix D: ChangeMan Edit Module Step 4.

Action 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.

Viewing Next Error or Warning Use this procedure to view the next error or warning: Step 1. 2.

Action Press the F4 key. 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.

Clearing Compile Command Results Use this procedure to clear the results of a Compile command: 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.

450

Serena® ChangeMan® DS 5.7.1 User’s Guide

SAVING A FILE ChangeMan 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 Name Use this procedure to save files with a different name: Step 1.

Action 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.

CREATING A NEW FILE ChangeMan Edit lets you create a new file directly from the Edit module.

451

Appendix D: ChangeMan Edit Module 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: Step 1.

Action From ChangeMan Edit, click New Document Document from the File menu).

(or choose New

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.

When you finish editing a new file, save it with the Save As command.

TOGGLING DISPLAY ITEMS ChangeMan 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:

452

•

Displaying Line Numbers

•

Displaying the Marker Bar

•

Displaying the Ruler

•

Displaying the Status Bar

Serena® ChangeMan® DS 5.7.1 User’s Guide

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 Line Number Bar.

, or select View >

•

To hide line numbers, click Toggle Line Number Bar 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 .

, or deselect View >

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 Bar Marker 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 Bar.

•

To hide Markers, click Toggle Marker Bar

Note

, or select View > Marker , or deselect View > Marker Bar.

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 Clients ChangeMan Diff doesn't allow bookmarks, so it doesn't have a marker bar.

453

Appendix D: ChangeMan Edit Module 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 Ruler The 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

•

To hide the Ruler Bar, click Toggle Ruler Bar

Note

or select View > Ruler Bar. or deselect View > Ruler Bar.

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 Bar The 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).

454

Serena® ChangeMan® DS 5.7.1 User’s Guide For Java Clients •

To display the Status Bar, select View > Status Bar.

•

To hide the Status bar, deselect View > Status Bar.

For Web Browser Clients You cannot toggle the Status Bar on the Web browser client.

CHANGEMAN EDIT VARIABLES If 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

Appendix D: ChangeMan Edit Module

TEMPLATE MANAGER The 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 Manager To open the Template Manager, click the Template Manager Template Manager from the Tools menu). The following screen displays:

456

button (or choose

Serena® ChangeMan® DS 5.7.1 User’s Guide 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 Template Use this procedure to create a new template: 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.

To simplify the process of creating a new template, you have the option of copying an existing template to a new one.

457

Appendix D: ChangeMan Edit Module

Copying a Template Use this procedure to copy a template: Step 1. 2.

Action Open the Template Manager, then select the template to copy. 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.

Deleting a Template Use this procedure to delete a template: Step 1. 2.

Action Open the Template Manager, then select the template to delete. Click Remove Template

.

Modifying a List of Keywords You modify the list of keywords recognized by ChangeMan Edit and ChangeMan Diff on the Keywords Tab of the Template Manager.

458

Serena® ChangeMan® DS 5.7.1 User’s Guide Use this procedure to modify the list of keywords: Step 1.

Action 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.

Configuring Auto Line Numbering You 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: Step 1.

Action Open the template manger. See “Opening the Template Manager” on page 456 for more information.

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.

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.

459

Appendix D: ChangeMan Edit Module

When the file is open for editing, ChangeMan Edit indicates the added and modified lines in the Marker Bar.

Changing Colors You 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: Step 1.

Action Open the template manger. See “Opening the Template Manager” on page 456 for more information.

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.

Template Manager Tabs The right pane of the main Template Manager window contains the following tabs:

460

Serena® ChangeMan® DS 5.7.1 User’s Guide •

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 Tab The 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

Appendix D: ChangeMan Edit Module You can configure the template specifications by selecting or clearing the following options: 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.

In addition, you can configure: •

Number of spaces for each tab

•

Line length

•

Display font

Syntax Tab The 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.

462

Serena® ChangeMan® DS 5.7.1 User’s Guide

The Syntax tab contains the following options: 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.

Keywords Tab The 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.

463

Appendix D: ChangeMan Edit Module

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 Tab The Advanced tab in the Template Manager opens the screen where you can define options for line numbering and auto-modification date trailing.

464

Serena® ChangeMan® DS 5.7.1 User’s Guide 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 EDIT When 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

Appendix D: ChangeMan Edit Module If this line is not present, you can add it as shown.

466

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

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.

468

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 process

•

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

Serena® ChangeMan® DS 5.7.1 User’s Guide 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.

Communication Agent

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

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.

470

Serena® ChangeMan® DS 5.7.1 User’s Guide 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

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:

package level

•

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 emergency fixes.

•

Planned/Temporary - Scheduled changes that run for a predetermined length of time. These are usually one-time or short-term processes.

•

Planned/Permanent - Scheduled changes that update the baseline or Production libraries.

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.

472

Serena® ChangeMan® DS 5.7.1 User’s Guide 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 possible.

•

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

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.

474

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.

Serena® ChangeMan® DS 5.7.1 User’s Guide 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 information.

•

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 continue. 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

Glossary

476

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).

INDEX A aborted transactions

Template Manager

agent system requirements

221

accepting changed lines, merging 430 changes, ChangeMan Word Diff inserted lines, merging 430 accessibility, Online Help

163

22

Activity/Event list of life cycle components

79

adding change set, files 267 contact to a package 269 dependencies, packages 272 description to a file transfer 98 keywords to text-based display 463 project branch 139 projects 67 release branch 140 specifications to applications 250 split 430 users to an Approval Group 298 See also attaching, creating 378

AND

119

379

appending Impact Analysis reports Application dialog

314

Add target/dependency permission

36

already checked out message

accessing applications and packages 248 Audit Trail 213 ChangeMan DS 38 ChangeMan Edit 55 File Tree from packages 268 itemized Impact Analysis 229 project filter screen 64 Template Manager 456

Advanced tab Impact Analysis

464

226, 233

249

applications 245 adding specifications 250 attaching an area 252 attaching areas 253 attaching projects 252 changing project properties 255 creating 250 projects 255 projects, removing deliverable status 255 projects, viewing audit trail 255 tree node described 386 viewing Audit Trail, package node See also packages approval assignments

296

Approval Configuration Node Approval Data Sources

392

308

Approval Groups adding users 298 customizing notifications 302 enabling the Default notifications setting order of approvals 299 Approval node

255

301

391

approval process

246

approvals

477

Index configuring Approval Group 298 configuring process for POA 295 described for POA 295 notification states described 300 reports, Audit Trail 213 setting order, POA 299 specifying passwords in POA 299 Transfer Requests 237 troubleshooting 227 types 237 Approved state, POA

297

approving packages 296, 391 transfer transactions 237 APR > REJ promotion APR state

278

285

areas approving transactions to 238 attaching to application 252, 253 attaching to package 265 package definition 244 packages, default area configuration 254 permissions, transfer 128 rejecting transactions to 240 synchronizing 165 Web browser client, displaying 344 AS/400 Communication Agent make behaviors 332 scripts 334 transfers 333 using 331 assignments, approval

478

86

Attachments node projects 87

280

Audit Trail accessing 213 approving transactions 239 comparing files 145 creating queries 216 Date Tab 220 deleting records 223 exiting 226 Filter tab 220 General tab 218 Location tab 219 printing report 223 queries, loading pre-defined 217 queries, saving 216 reports, approving transactions 225 rolling back to a previous version 224 troubleshooting 226 troubleshooting pending transfers 227 user input area 217 viewing from IDE 217 viewing from packages 255 viewing signoff history 225, 241 130

auto line numbering

associating projects with transferred files 98 TeamTrack items with transfers 98 see also linking packages attaching documentation to packages

attachments projects 81 viewing status

Auto hide

296

Attach files to project permission

files to projects 83, 84 files to release 208 subprojects to projects 92 See also adding, creating

80 262

AutoDoc option automatic merge

459

228 163

B background colors, text BAS state

286

150, 431

Serena® ChangeMan® DS 5.7.1 User’s Guide binary files comparing 143 determining 148 forcing binary transfers bookmarks

C 96

444

360

build add dependencies 184 delete history 195 dependencies 184 adding to projects 186 properties 187 history 192 sending to a log file 194 understanding 193 hosts user login information 191 initiating from ExplorerView 190 locating information storage 194 Make Configuration Global Compile 178 Post Compile 180 Pre Compile 177 properties 175 make files exporting 200 importing 196 properties 174 make procedure, creating 173 preparing 170 targets 181 adding to projects 182 properties 183 build management, projects Build module reports, Audit Trail builds troubleshooting

Cancel state, POA

297

canceling check out 359 package approvals

branching described 133 files 135, 137 Bring Home

Cancel check out permission project level 79

63

296

capturing release information, freezing projects 63 change requests, grouping

63

change set adding or deleting files projects 63

267

changed lines, merging

430

ChangeMan Diff copying a selection 439, 440 finding text 440 line numbers, displaying 453 moving a selection 441 replacing text 443 ChangeMan Diff utility bookmarks 444 changing display mode 430 changing display options 431 changing text background colors comparing files 143 Diff Mode 147 Diff Parameters toolbar 408 Edit/View toolbar 404, 407 interface 402–409 Merge Mode 161 Merge toolbar 405 Standard toolbar 403 ChangeMan DS Edit toolbar, Standard 411 ChangeMan DS File Properties dialog

213

201

431

ChangeMan DS Merge dialog ChangeMan DS Prompt dialog 167

268

158 101, 102,

479

Index ChangeMan DS, logging in

38

ChangeMan Edit 465 altering access permissions 465 bookmarks 444 changing colors 460 Colors tab, Template Manger 465 compile files 447 result scripts 448 components 437 configuring auto line numbering 459 copying a selection 439, 440 creating files 451 described 437 editing files 55 finding text 440 Impact Analysis 445 line numbers, displaying 453 modifying files 438 moving a selection 441 opening files 56 redo 443 replacing text 443 ruler, displaying 454 run commands 446 saving files 451 Template Manager 456 undo 443 variables 455 viewing errors and warnings 450 ChangeMan Word Diff utility changing text background colors 150 comparing documents 149 merging documents 162 merging from comparison 150 Web browser client limitations 145, 146 ChangeMan ZMF, package names

255

changing colors, ChangeMan Diff 161 colors, ChangeMan Edit 460 display mode, ChangeMan Diff 430 display options, ChangeMan Diff 431

480

package properties 255 passwords 382 text-colors, ChangeMan Diff 431 text-colors, ChangeMan Word Diff 150 users, reconnecting to ChangeMan DS 40 your password 40 See also editing, modifying, setting check in 359 files, branching 137 files, new file 116 files, new version 115 files, same version 116 initiating 114 merging 155 projects 117 projects, branching 139 synchronizing 160 Check in permission project level 79 check out 359 cancelling 359 files, branching 135 files, canceling 110 files, File List 107 files, previous version 109 files, primary 106 files, secondary 108 folders 106 frozen release 389 initiating 105 projects, branching 139 projects, cancelling 113 projects, primary 110 projects, secondary 112 secondary 134 Check out permission project level 79 checked out message Checkoff state, POA child projects

92

119 297

Serena® ChangeMan® DS 5.7.1 User’s Guide child, package hierarchy Clear button

270

255

client command line interface 35 defined 35 GUI client 35 system requirements 36 Web client 35 closing ChangeMan Word Diff utility code synchronizing lines

134

concurrent development

133

configuring approval group 298 approval process for POA 295 Approver Properties Notifications, POA 303 ChangeMan Diff utility 456 ChangeMan Edit 456 dependencies 272 status display options, Web browser client 385

150

434

Color tab, Template Manager

depiction on File Tree files 108

465

connection problems 344

colors ChangeMan Diff 161 ChangeMan Edit 460 merging files 161

contacts adding to Contacts node for packages 269

column information, Impact Analysis 231

222,

Contacts Node

390

content window

42

commands file level, Host View 324 run, ChangeMan Edit 446

contributors, multiple using subprojects 91

Communication Agent defined 35

conversion utilities

comparing files from Audit Trail 145 files with Web browser client 409 Microsoft Word documents 143, 149 text-based files 143 See also merging comparing Word files 150 compiling files 447 result scripts

448

Completed, approval type

237

complex, package level 259 components, grouping concurrent check outs

63

controlled status symbol

390

48

36

copying files via branch 135, 137 templates 458 text 439, 440 Create release permission

79

Create target/dependency permission

80

creating applications 250 Approval Group in POA 298 approval notifications, POA 300 Audit Trail queries 216 branch of a project 139 branch of a release 140 branch on file check in 137 branch on file check out 135 copy of a project 139

481

Index Audit Trail records 223 change set, files 267 templates 458 See also detaching, removing

default area configuration, packages 254 dependency rules 274 files 451 hierarchies, packages 270 make procedure 173 notifications 312 packages 261 project 65 releases 203 templates 457 See also adding customizing Approval Group notifications

Deliverable button

deliverables choosing Installation area marking projects as 255 removing status 255

79

dependencies 184 adding 272 adding to projects 186 configuring 272 define for build 184 modify property 187 properties 187 removing 273

302

216

data retrieval, stopping

265

Demote from QA permission

D daq, file extension

255

228

dependency rules, creating

data source described 306 notification 314

274

descriptions adding to file transfers 98

date package creation 259 package installation 260, 276

destination file already checked out message

Date Tab, Audit Trail

detaching files from project 86 files from release 207 See also removing, deleting

Detach files from project permission

220

Default Approval Group notifications, described 301 default area configuration

254

Default notifications, enabling in POA default, security authorization defining project properties DEL > DEV promotion DEL state

119

301

293

70 278

286

determining text-based/binary files DEV > DEL promotion

278

DEV > FRZ promotion

278

DEV > REJ promotion

278

DEV state

80

148

285

Development areas

246, 253

Delete release permission 79

development environment, integrated

Delete target/dependency permission 80

dialogs ChangeMan DS Prompt 167 System Configuration 374

deleting

482

36

Serena® ChangeMan® DS 5.7.1 User’s Guide Diff Mode Diff Output

E

147 431

Edit/View toolbar

Diff Parameters toolbar

408

directory properties, UNIX

329

display mode, ChangeMan Diff utility display options, ChangeMan Diff utility display requirement ChangeMan DS Main Server display requirements Web browser client

341

345

430 431

404, 407

editing files 53, 55 files from the File Tree 281 files in packages 279 inputting passwords 465 merged file 432 projects 67 text 441 See also changing, modifying, setting

displaying areas on Web browser client 344 ChangeMan DS File Properties dialog 268 line numbers 453 ruler 454 status bar 359 text-based file characteristics 461 toolbars 359

editing files ChangeMan Edit

distinctive, security authorization

enabling approvals in POA 295 ChangeMan Edit 55 default Approval Group notifications 301 Impact Analysis (AutoDoc option)

distributing automated 124 files 124 frozen release 390 initiating 124 projects 125 to End User area 360

DS Control Option

48

84

288

Element, searching for elements impact analysis

379

228

e-mail configuring notifications

End

distribution by DCM commands 128 by Implementation Script 126 by Post Compile script 127 interactive 124 drag-and-drop attaching files to projects copying text 440 moving text 441

293

EditScript dialog

56

311

228

119

End User area promoting from

119

end users, distributing to 360 errors viewing in ChangeMan Edit

450

eserver iSeries, See AS/400 exclamation icon

100

exiting Audit Trail 226 Impact Analysis 233 See also closing ExplorerView

483

Index file(s) failed to transfer

Alphabetical Impact Analysis 228 approving transactions 238 attaching files to projects 84 described 42 main window 42 exploring UNIX, HostView

390

F failed installation

341

failed rebooting, VCS Server

342

failed to retrieve first archive message fields ChangeMan DS Merge dialog

227

158

file contents viewing 54 file failed process control rule message 129 File List checking out files file properties

107

57

File Transfer Request Status dialog file transfer requests reports, Audit Trail

104

213

File Tree comparing files 144 displaying from packages 268 interface 400 merging 154 target rules, merging 159 viewing file history 211 viewing from Impact Analysis 225, 232 File Tree dialog 281 checking out files 282

484

104

file(s) skipped

104

file(s) transferred

324

export build rules 200 make procedure, frozen release

file(s) merged

104

104

files approving transactions 238 associating with files on transfers 98 attaching during project creation 83 attaching to a release 208 attaching to projects 84 branching 135, 137 canceling check out 110 check in 115 check in, branching 137 check out 106 check out by folder 106 check out from File List 107 check out, branching 135 check out, second 108 checking out 282 combining, see merging comparing 143 comparing from Audit Trail 145 compiling 447 creating 451 dependencies for build 184 detaching from releases 207 distributing 124 editing 53 editing with ChangeMan Edit 55 forcing transfer as binary 96 grouping as subprojects 91 managing properties, UNIX 328 modifying 438 modifying list on transfers 98 new, check in 116 not finding in Impact Analysis 233 opening with ChangeMan Edit 56 permissions, file transfer 128 placing under control 47 previous version, check out 109 promoting 120

Serena® ChangeMan® DS 5.7.1 User’s Guide properties, viewing 57 rejecting promotions 240 removing from projects 86 same version, check in 116 saving 451 scheduling transfers 97 searching for components, Impact Analysis 227 secondary check out 108 status indicators 48 synchronizing 165 tampering 354, 355 transferring 95 troubleshooting promotions 128 unable to place under control 51 viewing contents 54 viewing from Impact Analysis 226, 232 viewing from packages 268 viewing history 114 viewing information 211 viewing status 86 Files toolbar

369

filter screen, projects

64

filter, search criteria

292

Find Now button

firewall, accessing ChangeMan DS

344

folder approving transactions 238 rejecting transactions 240 96

freezing projects 204 projects with subprojects

205

Frozen Release node, packages

389

389

Frozen Releases 246, 282 Frozen Releases node, projects FRZ > APR promotion

278

FRZ > REJ promotion

278

FRZ state

246, 285

Function Call, searching for

379

G General tab, Template Manager G-Notify, described

461

302

groups adding to Approval Group 298 configuring notifications in POA 303

H halted check in transaction(s) created help, online accessing

105

365

heterogeneous hosts

327

147

hierarchies, packages

270

history build 192 packages, viewing

283

Home area defined 47

106

forcing file transfer as binary

frozen release options

278

Hide Map

226, 233, 379

folders, checking out

FRZ > DEL promotion

87

Host View adding a host 326 configuring 325 file level commands 324 information displayed 323 managing heterogeneous hosts 327 managing properties 327 removing a host 327 UNIX exploring host 324 managing file properties 328 modifying directory properties 329 Hosts toolbar

372

485

Index hosts_menu

synchronizations See also starting

362

initiating build process

I icons checked out, files 89 controlled status 48 Development icon, projects Local Status 353 Production Status 356 Request Status 100, 357 IDE attaching files to projects editing files 53 integrations with 36 viewing Audit Trail 217

INS state

86

inserting bookmarks

444

247

installation log

252 289

integrated development environments 228

379 293

inference, security authorization 293

486

430

Installation area

inclusive, security authorization

289

installation date and time 260, 276 Main Server 341

Impact Analysis advanced search 378 alphabetical 228 attaching files to projects 84, 232 ChangeMan Edit 445 exiting 233 itemized 228, 229 performing 228 results 230 stopping data retrieval 228 toolbar 378 troubleshooting 233 types 228

initiating check in 114 check out 105 distribution 124 promote 119

inserted lines install failed

247, 286

Include File, searching for

190

285

Ins. History button

81

identifying files with specific elements IFL state

165

integrity indication of file tampering

36

354, 355

interface ChangeMan Diff window 402–409 content window 347 Edit menu 358 File Tree 400 Files menu 361 Files menu, File List 373 Files toolbar 369 Help menu 365 Hosts menu 362 Hosts toolbar 372 Main Window, File menu 358 menus 357 Performance Monitor 397 Project menu 360 Project toolbar 370 Promote menu 359 Promote toolbar 371 Serena ChangeMan DS views 42 Standard toolbar 366 status icons 353 System Configuration 374 toolbars 365

Serena® ChangeMan® DS 5.7.1 User’s Guide Tools menu 363 Tools toolbar, Main Window View menu 359 Web browser client 383 invoking Java client

367

Main Server accessing through firewall 344 defined 35 troubleshooting installation 341

229

J Java client 150 invoking 39 merging Word files 162 projects 67 status options, displaying

main window described 42 navigating 43 Maintain function, frozen release

maintaining complex levels of work

463

Keywords tab, Template Manager

463

L languages, effect on text-based or binary files 148 level, packages

259

line numbers, displaying

make procedures creating 173 defining 170

linking packages

266

Local Status icons Locale setting

459

Make Procedures node, projects

353

managing HostView properties

148

log in changing password log, transfer requests

40 104

332

Make Configuration Global Compile 178 Post Compile 180 Pre Compile 177 properties 175 Properties tab 175 make file exporting 200 importing 196 properties modifying 174

lines, auto numbering

94

make behaviors AS/400 Communication Agent

life cycle described 284 packages 284 promoting packages 276 viewing package history 283 453

209

Maintain option action described 140 toolbar button 389

385

K keywords

40

M

39

Itemized Impact Analysis

logging in reconnecting during session

87

327

Map 147, 161 toggling 435

487

Index list of files being transferred 98 releases 207 UNIX directory properties 329 See also editing, changing, setting

menu Edit Main Window 358 Files 361 Files, File List 373 Help 365 Hosts 362 Project 360 Promote 359 View 359

moving, text

N

menus 357 File, Main Window 358 right-click, Java and Web browser 393– 396 Tools, Main Window 363 Merge Mode, ChangeMan Diff utility Merge toolbar

161

405

merging automatic 163 described 153 during check in 155 editing merge file 432 from the File Tree 154 Merge dialog field descriptions 158 Microsoft Word Documents 162 synchronization 156 synchronizing 165 target rules 159 Word file, ChangeMan Word Diff 150 See also comparing messages already checked out

names, file name restrictions

51

navigating changes, ChangeMan Word Diff code with bookmarks 445

151

no requests were created message

130

Notification Configuration Node

393

notifications configuring 311 configuring for approvers, POA 303 creating 312 creating for approvals, POA 300 customizing for Approval Groups, POA 302 data sources 314 data sources for 306

O Off-line Transfers

97

One Window Diff

431

Online Help, Section 508 accessibility 119

On-line transfers

metadata repository defined 35

54

OR parameter, Impact Analysis

Modify target/dependency permission 79 modifying files 438 keywords from text-based files

97

opening ChangeMan DS 38 files 56 read-only version of a file

Microsoft Word documents comparing 143, 149 merging 162

488

441

458

out of space UNIX 341 override passwords POA approvals 299

379

22

Serena® ChangeMan® DS 5.7.1 User’s Guide overwrite into working area overwriting, synchronizing owner project, described Owner column

167 165

73

89

Ownership, Transfer

360

P Package dialog Life Cycle tab

284

package-oriented approach

243–321

packages 245 adding contact 269 adding dependencies 272 approving 296, 391 APR state 285 attaching areas 265 attaching projects 263 attaching specifications 262 Attachments node 280 BAS state 286 configuration screen 255 configuring approval process 295 creating 261 default area configuration 254 DEL state 286 DEV state 285 editing files 279 FRZ state 285 hierarchies 270 history 283 IFL state 286 INS state 285 levels 259 life cycle 284 life cycle, viewing 283 linking 266 names 255 predecessor 272 projects 388

promoting 276 REJ state 286 removing dependencies 273 saving search criteria 292 searching for 290 security 292 successor 272 troubleshooting promotions to FRZ types 258 viewing Audit Trails 255 viewing files 268 viewing history 283 viewing installation history 289 See also applications parallel development parent projects

133

92

parent, package hierarchy

270

parent-child relationships, projects participating, package level

92

259

passwords changing 40, 382 editing 465 specifying for approvals in POA when editing 465 path, setting relative Pending

257

299

90

100, 357

Pending option

100

pending transaction(s) created 104 pending transfers reports, Audit Trail 213 troubleshooting 227 Performance Monitor interface 397 performing Impact Analysis 228 Impact Analysis, alphabetical permanent, package type

228

258

permissions

489

Index release branches 140 See also security transfer activities 128 placing files under control planned, package type

47

258

POA, see package-oriented approach position locator, files

147, 161

predecessor adding dependencies 272 removing dependencies 273 pre-defined queries

217

preventing mistaken edits project working location view printing Audit Trail report 223 Impact Analysis reports procedure, make

89

232

173

Process Control Rules failed transfers 129 Production area

246, 252

Production Status icons Production view

356

88

project file(s) not under source control 105 Project node Project toolbar

255 370

project working location described 87 setting views 88 projects 245, 255 administration permissions 80 approving transactions 238, 240 associating with transferred files 98 attaching files 83, 84 attaching files during creation 83 attaching to application 252 attaching to package 263 attachments 81

490

Attachments node 280 attachments node 87 authorization lists adding groups 77 adding users 77 deleting groups 77 deleting users 77 changing properties within applications 255 check out 110 check out, canceling 113 check out, secondary 112 checking in 117 creating 65, 67 based on existing project 68 from Java client 67 from Web browser client 67 creating a branch 139 defined 244 defining 70 deleting 68 described 31 Development icon 86 distributing 125 editing 65, 67 editing from Java client 67 editing from Web browser client 67 freezing 204 freezing with subprojects 205 Frozen Releases node 87 implementation schemes 92 Make Procedures node 87 marking as deliverable 255 owner 73 permissions, transfer 128 Project Authorization 76 project priority 75 project status 75 project type 74 promoting 63, 121

Serena® ChangeMan® DS 5.7.1 User’s Guide Properties Description 73 Name 73 Notes 74 Parent 74 Properties tab 73 relative path 90 removing attachments 85, 86 removing deliverable status 255 Status icon 89 subprojects 91 transferring 95 user permissions 78–80 view filter 64 viewing status of attachments 86 working location 87 See also packages, subprojects Projects dialog

84

Projects node

388

Promote menu

Promote to Development

49

queries Audit Trail 216 file extension 216 pre-defined 217

redo

359

342

233

refresh list of frozen releases REJ state

371

390

286

Rejected state, POA 119

40

443

refining Impact Analysis reports

360

promoting adding files to control 49 already checked out message defined 29, 95 files 120 frozen release 389 initiating 119 packages 276 projects 63, 121 promotion types 278 releases 206 subprojects 92 troubleshooting 128

rebooting VCS Server

54

reconnecting to ChangeMan DS

360

Promote to QA permission project level 79 Promote toolbar

Q

read-only file versions

Promote Options, adding to control

Promote to QA

Properties tab projects 73

R

359

Promote to Production

properties modify dependencies 187 modifying target 183 package, changing 255 viewing for a file 57 viewing for frozen release 390

297

rejecting changed lines, merging 430 changes, ChangeMan Word Diff file transfers 240 inserted lines, merging 430 packages 296

163

relationships, predecessor & successor 272 relative path using with working location relative path, setting

87

90

491

Index requests, file transfer Audit Trail reports 213

releases attaching files 208 branching 140 creating 203 detaching files 207 maintaining 140 modifying 207 promoting 206 rolling back 206 relogin, ChangeMan DS remote commands

restarting UNIX services result scripts

342

448

retrieving latest, see synchronizing Review state, POA

297

reviewing, package approvals

40

right-click menus Java and Web browser

446

remote directory browsers failed access to host 344

right-click menus, Show History command

Remove from source control permission project level 79

Rollback permission project level 79

removing attachments from projects 86 Audit Trail records 223 bookmarks 445 deliverable status, projects 255 dependencies, packages 273 files from control 50 hierarchies, packages 270 host 327 spaces when saving text-based files 462 split 430 tampered status 354 users from Approval Group 298 See also detaching, deleting

rolling back files to previous version releases 206

replacing text

443

reported problems, grouping

63

reports, See entries Audit Trail, Impact Analysis Request Status icons

100, 357

request transaction(s) created Requested

100, 357

Requested, approval type requester

492

269

237

104

rulers displaying

296

393–396 226

224

454

rules automatic merge 163 dependency 274 promotion 119 run commands

446

S saving Audit Trail queries 216 files 451 package search criteria 292 scheduling on-line/off-line transfers

97

scripts AS/400 Communication Agent compile results 448 searching

334

Serena® ChangeMan® DS 5.7.1 User’s Guide elements, alphabetical impact analysis 228 Impact Analysis 378 Impact Analysis, stopping search 230 packages 290 saving package search criteria 292 text 440 user who initiated last transaction 89 Second Check out permission project level 79 secondary check ins

116, 137

secondary check outs Section 508 Help

security approval passwords, POA 299 setting package permissions 292 setting permissions 280, 292

341

Show Differences

144

Show History command when it appears 226 sign off

237

sorting, Impact Analysis columns

222, 231

source control adding to using promote 49 placing files under 47 removing from control 50 troubleshooting 51

split view 129

433, 434

57

299

430

Standard toolbar ChangeMan Diff 403 ChangeMan DS Edit 411 Main Window 366 standardizing, software executables states, life cycle

36

435

Status icons checked out 89 Development area, projects projects 89 status options, setting status, files

63

284

Status Bar, toggling

setting approval order in POA 299 Audit Trail Filters 227 project as deliverable 255 relative path 90 See also changing, editing, modifying setup.exe

software applications, grouping components 63

specifying approval passwords in POA

Serena ChangeMan DS extending SCM 29 placing under control 47 system requirements 36 Server system requirements

259

specifications adding to application 250 attaching to packages 262

22

selecting ChangeMan Diff templates

simple, package level

Source Control Properties, viewing

108, 134

security permissions editing 465 message for violating permissions

signoff history, viewing 225, 241

86

385

48

stopping Impact Analysis, data retrieval search, Impact Analysis 230 subordinate packages subprojects attachment rules described 31

228

270 92

493

Index changing colors 460 Color tab 465 configuring auto line numbering General tab 461 Keywords tab 463 Syntax tab 462

freezing with projects 205 promoting 92 schemes 92 using 91 See also projects successor adding dependencies 272 removing dependencies 273 super, package level

templates ChangeMan Diff, selecting copying 458 creating 457 deleting 458

259

symbols, controlled status 48 synchronizing lines in code 434 merge option 156 process described 165 promote option 359 releases 389 target rules 159

text ChangeMan Diff, background colors 150, 431 ChangeMan Word Diff, background colors 150 copying 439, 440 displaying line numbers 453 finding 440 merging background colors 161 moving 441 replacing 443

462

374

system requirements 36 display requirements 341

T tampering indication of file tampering target area Pending option

354, 355

100

target rules, merging

159

Template Manager 456 Advanced tab 464

494

260, 276

toggling Map, ChangeMan Diff 435 Maps 147, 161 project working location views 89 Status Bar, ChangeMan Diff 435

133

TeamTrack associating items with transfers

text-based files changing display 461 comparing 143 determining 148 editing 53 merging 160 rules for deciding 96 time package installation

targets adding to projects 182 build 181 dependencies 184, 186, 187 properties 183 team development

433, 434

temporary, package type 258

Syntax tab, Template Manager System Configuration dialog

459

98

toolbar described 43 Files 369 Hosts 372

Serena® ChangeMan® DS 5.7.1 User’s Guide Promote to QA 360 scheduling on-line/off-line 97 Synchronize 359 Transfer Ownership 360

Main Window, Standard 366 Project 370 Promote 371 Tools, Main Window 367

troubleshooting 341 Audit Trail 226 builds 201 ChangeMan Edit 465 connection to ChangeMan DS Impact Analysis 233 installation 341 promotion 128 source control 51 Web browser client 344

Tools toolbar 89 described 367 transactions aborted 221 reports, Audit Trail 213 viewing all on Audit Trail 227 transfer activities permissions 128 Transfer Ownership transfer process

360

95

type, packages

Transfer Request dialog Advanced button 135

258

U

transfer requests reports, Audit Trail 213 summary 104 viewing details 130 transfer requests, viewing details

344

Unable to transfer file message uncontrolled status symbol undo 130

transferring files and projects 95 files as binary 96 projects 63 transfers adding a description 98 approval 237 Approve 359 AS/400 Communication Agent 333 associating with TeamTrack items 98 Bring Home 360 cancel check out 359 check in 359 check out 359 distributing to End Users 360 modifying list of files 98 process 99 Promote to Development 360 Promote to Production 359

201

48

443

UNIX failed installation 341 files, managing properties 328 modifying directory properties 329 out of space 341 rebooting services 342 unable to transfer file message 201 unlinking packages

266

unplanned, package type

258

Use ChangeMan Edit option

55

users adding to Approval Group 298 changing their password 40 configuring notifications in POA 303 distributing to 360

V variables

495

Index ChangeMan Edit VCS Server rebooting

455

342

vcs_serv, restarting on UNIX

342

versions check out files 109 comparing 144 View menu

359

View only permission project level 79 viewing audit trail, project within an application 255 file contents 54 file history 114 file information 211 file properties 57 File Tree from Impact Analysis 225, 232 files 226, 232 files from a package 268 files with special characters, Web client 345 history of a package 283 installation history 289 project attachments 88 signoff history 241 status of attached files 86 subprojects 92 transfer request details 130

W warning message(s)

104

warning messages failed to retrieve first archive 227 file failed process control rule 129 no requests were created 130 unable to transfer file 201 you are not authorized 129 warnings, viewing in ChangeMan Edit

496

450

Web browser client accessing 38 ChangeMan Word Diff 145, 146 comparing files 409 comparing Word files 143, 150 display requirements 345 Impact Analysis, differences from Windows 228 interface 383 merging Word files 162 projects 67 projects, editing 67 status options, displaying 385 troubleshooting 344 using Admin as user name 344 working at area name level 395 Windows unable to transfer file message Word documents work areas

201

143

253

working location, See project working location

Y you are not authorized message

129