The Source Integrity Professional Edition User Guide - MKS

Mortice Kern Systems (MKS) Inc.
Source Integrity Professional
Edition
User Guide

MKS Source Integrity Professional Edition
User Guide
© Copyright 2000 by Mortice Kern Systems Inc.
All rights reserved.
Printed in Canada.
MKS, MKS logo, MKS Change Integrity, and MKS Source Integrity are registered trademarks of Mortice Kern Systems Inc.
Other brand and product names are trademarks or registered trademarks of their respective holders.
Portions © copyright BEA Systems Inc. All rights reserved.
Portions © copyright KL Group or its suppliers. All rights reserved.
Portions © copyright PointBase, Inc. All rights reserved.
Customer Support
Include your MKS product name, release and serial number, as well as your operating system name and release number
with all Technical Support correspondence. MKS product information is available on the CD-ROM label.
Thirty days of free telephone support covering installation and configuration queries are provided with your purchase.
This period begins with your first request for assistance. Support beyond the initial 30 days is available through a Preferred
Customer Subscription package, or through a “pay as you go” program. Charges can be billed to your American Express,
VISA, or MasterCard.
Corporate Headquarters
Mortice Kern Systems (MKS) Inc.
185 Columbia Street West
Waterloo, Ontario
Canada N2L 5Z5
Phone: (519) 884-2251
Fax: (519) 884-8861
North American Sales: 1 800 265-2797
E-mail: info@mks.com
MKS/DataFocus
12450 Fair Lakes Circle
Suite 400
Fairfax, Virginia 22033
Phone: +1 703 803-3343
Fax: +1 703 803-3344
E-mail: nutcracker@mks.com
MKS France
11C Quai Conti
78430 Louveciennes
France
Phone: +331 3082 2762
Fax: +331 3082 7278
E-mail: france@mks.com
4.0-0300
Customer Support: (519) 884-2270
(8:00 a.m. – 8:00 p.m. Eastern Time, Monday – Friday)
Internet: sales@mks.com
support@mks.com
World Wide Web: http://www.mks.com
FAX: (519) 884-8861
US Headquarters
MKS US Inc.
2500 S. Highland Ave.
Suite 200
Lombard, Illinois 60148
Phone: (630) 495-2108
Fax: (630) 495-3591
E-mail: sales@mks.com
MKS (UK) Ltd.
Block D,
Dukes Court,
Woking, Surrey
United Kingdom
GU21 5BH
Phone: +44 (0) 1483 733 900
Fax: +44 (0) 1483 733 901
E-mail: uk@mks.com
MKS US Inc.
9020-I Capital of Texas Highway North
Great Hills Corporate Center
Suite 335
Austin, Texas 78759
Phone: (512) 342-2220
Fax: (512) 342-2939
E-mail: austin@mks.com
MKS Germany
Martinstraße 42-44
73728 Esslingen
Deutschland
Phone: +49 711 351775 0
Fax: +49 711 351775 11
E-mail: info@mks.de
MKS Japan
Kounike Building 4F
2-5-7 Minamisuna
Koto-Ku, Tokyo
Japan
Phone: (416) 626 7097
Fax: (416) 626 7354
E-mail: japan@mks.com

Table of Contents
1 Welcome to Source Integrity Professional Edition . . . . 1
The Source Integrity Professional Edition User Guide. . . . . . . . . . . . . . . . .2
Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4
Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4
2 Understanding Source Integrity . . . . . . . . . . . . . . . . . . . . 5
What Is Configuration Management? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6
The Role of Configuration Management . . . . . . . . . . . . . . . . . . . . . . . . . . . .7
Managing Constant Change . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7
The Cost of Change. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7
Managing Change . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9
Implementing Change . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9
Configuration Management Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10
Archives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10
Revisions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10
Branches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11
Metadata. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11
Source Integrity Basics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11
Related Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11
Changing States. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12
Understanding Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13
Logical and Functional Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13
Understanding Archives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13
About Archives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14
What Happens at Check-in Time? . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15
Branches and Trunks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17
Checkpointing Your Project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20
Sandboxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21
Sandbox Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21
A Typical Workplace Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22
How Sandboxes Can Help. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22
Variant Sandboxes and Development Paths. . . . . . . . . . . . . . . . . . . . .24
Build Sandboxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25
User Guide i

Table of Contents
Locking in Variant Sandboxes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26
Converting Old-Style Variant Sandboxes . . . . . . . . . . . . . . . . . . . . . . .28
Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29
About Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29
About Revision Descriptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30
About Timestamps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31
About Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32
About Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33
About Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33
Security and Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34
Source Integrity Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34
The SAM Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34
Managing Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36
Promotion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36
Reporter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37
3 Introducing the Source Integrity Interfaces . . . . . . . . . 39
The Windows interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40
Starting the Source Integrity Windows Interface . . . . . . . . . . . . . . . . .40
The Application Window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40
The Project Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42
The Archive Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43
Using Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44
Filtering Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45
Using Tree View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45
Using Source Integrity With Windows Explorer . . . . . . . . . . . . . . . . .48
The Source Integrity Web Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48
Installing the Source Integrity Web Interface . . . . . . . . . . . . . . . . . . . .49
Installing Additional Browser Plugins . . . . . . . . . . . . . . . . . . . . . . . . .50
Starting the Source Integrity Web Interface . . . . . . . . . . . . . . . . . . . . .50
The Source Integrity Web Interface Home Page . . . . . . . . . . . . . . . . .52
Introduction to Views. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52
Setting the Proxy Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58
Setting Your Timezone Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60
The Command Line Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61
Project Commands Versus Archive Commands . . . . . . . . . . . . . . . . .61
Command-Line Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62
Path Separator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62
Wildcard Expansion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62
File Name Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63
ii Source Integrity Professional Edition

Table of Contents
4 Getting Started With Projects,
Sandboxes, and Members . . . . . . . . . . . . . . . . . . . . . . . 65
Creating a Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .66
Registering a Project in the Source Integrity Web Interface. . . . . . . . . . . .69
Registering a Sandbox in the Source Integrity Web Interface . . . . . . . . . .69
Opening a Project or Sandbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70
Opening the Master Project From a Sandbox. . . . . . . . . . . . . . . . . . . . . . . .71
Adding Members to a Project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .72
Removing Members From a Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75
Creating a Sandbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .76
Checking Out a Member . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81
Viewing and Editing a Member . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .85
Checking In a Member . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87
Starting a Branch When Checking In a Member . . . . . . . . . . . . . . . . .87
Assigning Revision Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88
Assigning Revision Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89
Assigning Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .94
Assigning a State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .94
Assigning a Different Revision Number . . . . . . . . . . . . . . . . . . . . . . . .94
Viewing and Editing Project and Sandbox Information. . . . . . . . . . . . . . .94
Setting Project or Sandbox Attributes . . . . . . . . . . . . . . . . . . . . . . . . . .97
Comparing the Working File to Its Member Revision . . . . . . . . . . . . . . . .99
Discarding Changes to Working Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . .100
Locking a Member . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101
Unlocking a Member . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102
Removing Unused Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103
Detecting Sandbox Members Out of Sync With the Project. . . . . . . . . . .104
Resynchronizing Your Project or Sandbox. . . . . . . . . . . . . . . . . . . . . . . . .104
Freezing Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .106
Thawing Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107
Viewing Member Information (Windows Only). . . . . . . . . . . . . . . . . . . .108
Viewing and Editing Member Attributes . . . . . . . . . . . . . . . . . . . . . .109
Promoting and Demoting a Member . . . . . . . . . . . . . . . . . . . . . . . . . . . . .110
Updating to Head Rev. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113
Updating to Tip Revision . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .114
Scanning Your Project for Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .114
Refreshing Your View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .115
Assigning Labels to Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116
Deleting a Member’s Label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117
Building a Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .118
Calculating Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .118
Using the Build Command (Windows) . . . . . . . . . . . . . . . . . . . . . . . .120
Using pj build . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122
User Guide iii

Table of Contents
Using pj mkmf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123
The Reporter Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124
About the Report Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124
About Graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124
Report Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125
Creating Reports with the Command Line Interface. . . . . . . . . . . . .128
Using Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .129
Locating Keywords. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .130
Removing Keyword Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131
Table of Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131
5 Managing Projects and Sandboxes . . . . . . . . . . . . . . . 133
Freezing a Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .134
Thawing a Project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .135
Checkpointing a Project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .136
Opening a Project Archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .140
Promoting and Demoting a Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .140
Logging Project Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .142
Cleaning Up Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .142
Viewing Changes to a Project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .143
Restoring a Project’s Member List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .146
Importing Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .148
Importing SCCS Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .149
Importing PVCS Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .149
Importing Visual SourceSafe Files . . . . . . . . . . . . . . . . . . . . . . . . . . . .150
Using Existing RCS Archives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .151
Accessing Project Information With the Command Line Interface . . . .152
List of Members. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .152
Changed Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .152
Variables and Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .153
Project and Sandbox Information and System Settings. . . . . . . . . . .153
Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .153
Deleting Variant Projects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .158
Cleaning Up Working Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .159
Encrypting Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .160
Automatic Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .160
Explicit Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .160
Choosing an Encryption Key. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .161
Changing the Encryption Key. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .162
Working With Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .162
Encryption and Other Applications . . . . . . . . . . . . . . . . . . . . . . . . . . .162
iv Source Integrity Professional Edition

Table of Contents
6 Managing Archives and Revisions . . . . . . . . . . . . . . . 165
Opening a Project’s Archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .166
Opening a Member’s Archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .166
Creating Archives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .167
Importing Archives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .171
Checking Out Revisions From Archives. . . . . . . . . . . . . . . . . . . . . . . . . . .172
Checking Out by Revision Number or Label . . . . . . . . . . . . . . . . . . .173
Checking Out by State Setting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .174
Checking In Revisions to Archives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .174
Checking In—Setting Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .175
Checking In—State Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .176
Viewing and Editing Archive Information. . . . . . . . . . . . . . . . . . . . . . . . .176
Viewing and Editing Revision Information . . . . . . . . . . . . . . . . . . . . . . . .178
Viewing Revision Metadata With Archive Commands . . . . . . . . . .180
Locked Revisions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .182
Assigning Labels to Revisions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .183
Viewing and Editing the Working File or Revision . . . . . . . . . . . . . . . . .184
Promoting and Demoting a Revision . . . . . . . . . . . . . . . . . . . . . . . . . . . . .185
Locking Revisions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .187
Unlocking Revisions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .187
Deleting Revisions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .189
Comparing Revisions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .190
Merging Revisions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .192
Logging Archive Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .193
Log File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .194
Cleaning Up Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .195
Cleaning Up Working Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .195
Storing Binary Files in Reference Format . . . . . . . . . . . . . . . . . . . . . . . . . .196
7 Using Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Introduction to Source Integrity Extensions. . . . . . . . . . . . . . . . . . . . . . . .198
The Project Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .199
The Archive Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .206
Using the Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .209
Differences Between Extensions and Source Integrity . . . . . . . . . . . . . . .210
Creating Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .210
Creating Sandboxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .212
Microsoft Visual Basic 5.0 and 6.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .214
Creating a Source Integrity Project. . . . . . . . . . . . . . . . . . . . . . . . . . . .215
Creating a Sandbox. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .216
Checking Out Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .216
Checking In New Revisions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .217
The Microsoft Visual C++ 6.0 Extension. . . . . . . . . . . . . . . . . . . . . . . . . . .218
User Guide v

Table of Contents
Creating a Source Integrity Project. . . . . . . . . . . . . . . . . . . . . . . . . . . .219
Creating a Sandbox. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .219
Checking Out Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .219
Checking in New Revisions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .220
Using Microsoft Visual C++ 6.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .221
The Borland Delphi Extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .223
Creating a Source Integrity Project. . . . . . . . . . . . . . . . . . . . . . . . . . . .224
Creating a Sandbox. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .225
Checking Out Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .225
Checking Out Multiple Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .226
Checking In New Revisions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .226
Checking In Multiple Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .227
The Microsoft Windows Explorer Extension . . . . . . . . . . . . . . . . . . . . . . .227
Creating an Archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .228
Checking Out Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .229
Checking In New Revisions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .229
8 Building Projects With Source Integrity . . . . . . . . . . . 231
Before You Build. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .232
Creating a Makefile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .233
Building . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .234
Object File Associations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .235
Template Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .236
Language Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .236
Conditional Expansion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .236
@Depends. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .237
@Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .237
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .237
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .239
The Build Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .239
Templates and Configuration Language. . . . . . . . . . . . . . . . . . . . . . .240
Templates and Variable Expansion . . . . . . . . . . . . . . . . . . . . . . . . . . .240
9 Using the MKS Make Utility . . . . . . . . . . . . . . . . . . . . . 243
Compatibility Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .244
Getting the Right Make . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .244
Search Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .245
Changing Your Search Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .245
Getting Started With MKS Make . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .246
Dependency of Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .246
Makefiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .247
Writing a Rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .248
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .250
vi Source Integrity Professional Edition

Table of Contents
More About Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .250
Running MKS Make. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .252
Specifying Targets on the Command Line . . . . . . . . . . . . . . . . . . . . .252
Using a Different Makefile. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .252
The Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .253
How Make Finds Its Makefile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .254
Using Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .256
Macro Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .258
Defining Macros on the Command Line . . . . . . . . . . . . . . . . . . . . . . .259
Nesting Macros in other Macros. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .259
Modifying Macro Expansions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .261
Controlling MKS Make . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .265
Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .265
Special Target Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .267
Special Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .271
How Make Finds Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .277
Using Inference Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .281
Metarules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .282
Suffix Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .286
More About Executing Recipes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .288
Regular Recipes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .288
Built-In Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .289
Group Recipes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .289
Control Macros Used With Group Recipes. . . . . . . . . . . . . . . . . . . . .290
Text Diversions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .291
Making Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .293
Metarules for Library Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .294
Suffix Rules for Library Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .295
Compatibility Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .296
Conditionals. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .296
Other Makes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .298
Using the Generic CC Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .302
Compilation Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . .302
Using CC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .303
Generic Command-line Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .303
Examples of Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .304
Problem Solving . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .304
Without a Makefile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .304
Simple Makefile. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .305
Separate Object Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .305
MKS Make and Source Integrity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .306
Using a Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .306
Recursive Makes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .307
Clean-up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .307
User Guide vii

Table of Contents
Back-up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .308
Default Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .308
Miscellaneous Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .309
10 Starting a Change Integrity Session . . . . . . . . . . . . . . 311
Change Integrity Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .312
Issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .312
Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .312
User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .312
Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .313
Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .313
Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .313
Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .313
Charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .313
Before You Start a Change Integrity Session . . . . . . . . . . . . . . . . . . . . . . .314
Starting a Change Integrity Session. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .314
Logging In . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .314
The Change Integrity Graphic User Interface . . . . . . . . . . . . . . . . . . . . . .317
The Application Window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .317
The Change Integrity Web Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .320
Setting Session Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .321
Email Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .323
Saving Session Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .327
Ending a Change Integrity Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .328
Logging Out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .328
Closing a Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .328
11 Submitting Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
Submitting an Issue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .332
Relating an Issue With a Submitted Issue . . . . . . . . . . . . . . . . . . . . . .335
Adding Attachments to an Issue . . . . . . . . . . . . . . . . . . . . . . . . . . . . .340
12 Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
Creating a New Query. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .350
Creating Saved Queries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .354
Reverting a Saved Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .356
Deleting a Saved Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .356
Viewing and Editing Saved Query Properties . . . . . . . . . . . . . . . . . .357
Running Queries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .359
13 Viewing and Editing Issues . . . . . . . . . . . . . . . . . . . . . 363
Viewing Query Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .364
viii Source Integrity Professional Edition

Table of Contents
Selecting Issues to View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .367
Printing Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .371
Saving Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .373
Editing Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .376
Batch Editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .377
14 Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
Change Integrity Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .386
Creating Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .386
Editing Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .393
Running Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .395
Deleting Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .397
Copying Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .398
Saving and Printing Reports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .400
Saving Reports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .400
Printing Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .401
15 Charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
Change Integrity Charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .406
Creating Distribution Charts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .407
Creating Trend Charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .417
Editing Existing Charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .427
Running Charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .428
Deleting Charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .431
Copying Charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .432
Saving and Printing Charts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .433
Saving Charts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .434
Printing Charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .434
16 Integrated Version Control . . . . . . . . . . . . . . . . . . . . . . 437
Configuring Change Integrity Connect . . . . . . . . . . . . . . . . . . . . . . . . . . .438
Associating Active Issues With Project Members . . . . . . . . . . . . . . . . . . .441
Viewing Change Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .442
A Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445
Source Integrity Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .445
Change Integrity Terms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .454
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457
User Guide ix

Table of Contents
x Source Integrity Professional Edition

Welcome to
Source Integrity
Professional Edition
1
Source Integrity is a comprehensive, project-oriented configuration
management system that gives you control over the evolution of your
files. It not only documents the changes made to your files, but also
tracks who made them, when they were made, and the reasons why.
In addition, its project functionality lets you group related files into
projects that can follow your development cycle. Source Integrity
includes extensive configuration options to provide configuration
management that conforms with your established policies.
As part of MKS Source Integrity Professional Edition, Change
Integrity integrates with Source Integrity, to give you a highly
customizable issue-tracking, software change management, and team
management tool. Change Integrity helps your development team
capture and track all the data related to software change, which is
particularly important when your organization has implemented a
Software Configuration Management (SCM) process for the proposal,
review, and approval of all software changes on your project.
Whether you work on one-person projects, or in multipleprogrammer
development environments, Source Integrity
Professional Edition has the features to help you get the job done. Its
function set and project-oriented architecture are available in both
command-line and graphical user interfaces.
User Guide 1

Welcome to Source Integrity Professional Edition
The Source Integrity Professional Edition
User Guide
This manual is designed to provide users with an overview of
configuration management and problem tracking and how they can
use Source Integrity Professional Edition to implement these
principles in their environment. For the purposes of this manual, a
user is considered to be anyone who needs to work with Source
Integrity or Change Integrity projects.
This chapter introduces you to the Source Integrity Professional Edition
User Guide and its contents. The following is a list of the book’s other
chapters with a brief description of each chapter’s topic:
Chapter 2: “Understanding Source Integrity” (page 5)
Discusses basic concepts of software configuration management,
and how they are implemented within Source Integrity.
Chapter 3: “Introducing the Source Integrity Interfaces”
(page 39)
Provides an introduction to the three main interfaces to Source
Integrity: the Windows interface, the Source Integrity Web
interface, and the command line interface.
Chapter 4: “Getting Started With Projects, Sandboxes, and
Members” (page 65)
Describes how to create projects and sandboxes, and work with
members. Explains tasks in each of the three main Source
Integrity interfaces.
Chapter 5: “Managing Projects and Sandboxes” (page 133)
Describes how to manages projects as a whole, explaining
commands in all three main interfaces.
Chapter 6: “Managing Archives and Revisions” (page 165)
Describes how to manage your Source Integrity archives directly,
without using projects.
Chapter 7: “Using Extensions” (page 197)
Explains how to integrate Source Integrity with a number of
popular programming platforms.
Chapter 8: “Building Projects With Source Integrity”
(page 231)
Explains how to use Source Integrity’s build features.
2 Source Integrity Professional Edition

The Source Integrity Professional Edition User Guide
Chapter 9: “Using the MKS Make Utility” (page 243)
Explains how to use Source Integrity’s MAKE utility.
Chapter 2: “Starting a Change Integrity Session” (page 5)
Provides an overview of important Change Integrity concepts,
logging in to Change Integrity, the Change Integrity graphic user
interface, the Change Integrity Web interface, setting session
preferences, logging out, and exiting a Change Integrity session.
Chapter 3: “Submitting Issues” (page 25)
Discusses how to submit new issues.
Chapter 4: “Queries” (page 43)
Describes how you can query the Change Integrity database for
issue types that meet specific criteria.
Chapter 5: “Viewing and Editing Issues” (page 57)
Describes how to view issues and edit issue information.
Chapter 6: “Reports” (page 79)
Discusses how to create, edit, and generate reports from issue
data.
Chapter 7: “Charts” (page 99)
Discusses how to create, edit, and generate charts from issue
data.
Chapter 8: “Integrated Version Control” (page 131)
Describes using Change Integrity to activate issues for use in
Source Integrity, configuring Change Integrity Connect in Source
Integrity, and associating active issues with project members in
Source Integrity.
Appendix A: “Glossary” (page 445)
A glossary of common terms and definitions for Source Integrity
and Change Integrity.
User Guide 3

Welcome to Source Integrity Professional Edition
Typographical
Conventions
Related
Documentation
Throughout the manuals, the following typographical conventions
identify the features, functions and components of Source Integrity
Professional Edition.
Items in documentation Appear as follows
Menu items, nested menu items Edit > Role
Drop-down menus the Archive menu item
Dialog boxes, features Edit Options, Cancel, OK
Command-line commands pj ci
Screen information, messages Enter a name for this
development path:
Environment variables TMPDIR
Path names c:\srcint\work
Source Integrity Professional
Edition terms
appear in italics the first time
Keyboard keys appear in bold between angle
brackets, for example:
Procedures for the Windows
interface, graphic user interface,
Web interface, and Command-Line
interface
The MKS Source Integrity Professional Edition Reference Guide provides
information on Source Integrity Configuration and MKS Make, and
includes the manual pages for both the Source Integrity commandline
interface and MKS Make.
The MKS Source Integrity Professional Edition Administrator Guide
provides information on installing, configuring, and administrating
Source Integrity and Change Integrity at your site.
The MKS Change Integrity Solutions Guide recommends ways of
configuring Change Integrity to best suit your development
processes.
You can access online help from within the Source Integrity Windows
interface and Change Integrity graphic user interface; and through
the Source Integrity Web interface and Change Integrity Web
interface. You can access online man pages for Source Integrity from
the command line interface.
4 Source Integrity Professional Edition

Understanding Source
Integrity
2
This chapter describes basic concepts of configuration management
and how these concepts are applied within Source Integrity. If you
are unfamiliar with configuration management or revision control
applications, you should read this chapter.
This chapter covers the following topics:
what is configuration management
configuration management concepts
Source Integrity basics
understanding projects
understanding archives
understanding sandboxes
security and administration
managing development
User Guide 5

Understanding Source Integrity
What Is Configuration Management?
Configuration management supports developers who create, revise,
and deliver large amounts of interrelated source material that
changes over time.
Developers can include primary software developers, quality
assurance specialists, and others who work with source material. This
source material is usually source code, header or script files, thirdparty
libraries, documentation, graphic files, or other included
resources.
An effective configuration management tool has to address all the
revision-control needs of the development team. Such a tool should
preserve the evolving revisions of source code and resource files
define relationships between the files and the other components
needed to build applications
retrieve previous versions of files, application components, or
entire applications
To enhance the management of the overall project, it should also
protect work in progress from inadvertent loss or overwriting
reduce duplication of effort
isolate work in progress from the testing environment
provide analytical capabilities (it should provide reports to help
managers assess and control the flow of work during the
development cycle)
take advantage of system security facilities to protect valuable
data
encourage a responsible and disciplined approach to
implementing change
allow a managed product-release strategy
reduce maintenance costs by simplifying or automating the
replication of any previous release state
6 Source Integrity Professional Edition

The Role of Configuration Management
Managing
Constant
Change
The Cost of
Change
The Role of Configuration Management
In today’s competitive software world, developers need to be able to
bring robust, maintainable products to market in a timely way.
Consequently, they need to establish an environment that encourages
disciplined development practices and managed propagation of
change.
In an industry where post-implementation maintenance accounts for
a significant portion of product costs, anything that reduces the
maintenance burden can provide a significant competitive edge.
From the outset, virtually every software development project tries to
hit a moving target, and the need to manage the resulting change
constructively is paramount. For instance, consider a typical project.
Initial designs are modified to accommodate the needs of
implementation, user requirements, and new hardware
platforms.
Maintenance and additional release schedules are based on—and
require changes to—source code and resources produced in the
implementation phase.
No one expects software products to be carved in stone. Pressures
from users and the marketplace mean that every software project is
an ongoing process of upgrade, modification, and maintenance.
The issue today is not whether this trend can—or should—be
reversed, but how well it can be managed. The challenge is to
minimize its negative impact and attempt to turn it to competitive
advantage.
Undisciplined software development can have an enormous price
tag. Duplication of effort, propagation of changes in “free-fire”
development zones, and constantly changing construction
environments all add to the cost of software production.
Consider two scenarios that are common at software development
sites.
User Guide 7

Understanding Source Integrity
Source Changes
A bug report is issued against a released product, but a check of the
latest source code reveals no obvious reason for the problem. It is
known that the product in the field was built from an earlier release
of the code, but the precise configuration of code and resource
modules used in the release cannot be reproduced.
To make matters worse, the source code currently under
development cannot be shipped as a fix because it is still in a
prerelease state. The only way to solve the problem is to take time
and resources away from current development to produce and
distribute an expensive patch.
Environmental Changes
A programmer spends several weeks writing a program. It runs
successfully in the development environment, but when it is turned
over to the product team for integration into a new release it
immediately fails all tests in the product environment.
As a result, both time and money are lost trying to discover the
difference between the programmer’s and the product team’s
development environments.
The problems in these scenarios are all too common in the software
industry: companies are unable to replicate previous states of source
code and resources, and efficiency is degraded due to changes in the
development environment. The result is wasted time and money.
Common Development Problems
Development problems can occur for a number of reasons.
Two programmers may be working on different modules of the
same set of source-code files, each unaware of the other. When
one programmer finishes a fix and tries a test build, he or she
picks up the incomplete file that the other programmer is
working on and the build fails.
Time is spent debugging a problem that has nothing to do with
the work done by the first programmer.
A programmer alters a fundamental resource file—such as a C
header—resulting in unexpected changes that ripple across the
entire application.
The configuration of source files used to build product releases is
not easily replicable when post-release maintenance is needed.
8 Source Integrity Professional Edition

Managing
Change
Implementing
Change
The Role of Configuration Management
The tools used to build an application are not maintained as part
of the release, along with the source code and resource files.
Libraries are often a culprit here, as are preprocessor scripts or
build scripts, which are modified for current releases and no
longer work for earlier ones.
All of these problems are related to the way source code is
maintained and how product configuration is managed. They
demonstrate poor management practices and a lack of discipline in
the way many organizations develop and maintain software
applications.
Configuration management is the key to streamlining software
development, reducing costs, and increasing the efficiency and
profitability of the process.
A successful configuration management system does more than track
a development project’s structure and contents. It also encourages
and supports healthy practices during all phases of the development
cycle: design, implementation, testing, and maintenance.
At its heart, a configuration management system is a comprehensive
approach to software development that addresses
how the environment is configured (its directory structures and
file distribution, for example)
how programmers work in the development environment (for
instance, their revision management, locking, and promotion
practices)
how discipline is encouraged and how management objectives
are supported throughout the development cycle
In an industry that takes pride in its own creativity, the mention of
discipline or management controls can send people running for
cover. This type of response, however, has led to many of the
problems and bad work habits in the realm of software development.
Discipline, thoughtfully instituted and supported by tools that make
it easy to implement, can provide a well-structured work
environment for managers and programmers alike.
For programmers, it significantly reduces down time. It reduces
time spent recreating previous development states, or time spent
isolating themselves from other developers so that problems can
be identified and corrected.
User Guide 9

Understanding Source Integrity
For managers, such discipline helps streamline the development
cycle, allowing them to get products to market in a more timely—
and therefore more profitable—manner.
Source Integrity gives programmers and managers a comprehensive
set of configuration management tools. These tools are flexible
enough to enforce the discipline required by management, and
organized enough to free programmers from endless maintenance
cycles. In short, these tools allow developers to concentrate on what
they are really good at—the creative aspects of developing
applications.
Configuration Management Concepts
Archives
Revisions
Traditional configuration management, and advanced configuration
management systems such as Source Integrity, have evolved around
a few commonly held concepts.
Traditional source files, even in advanced file systems, do not lend
any advantage to data that changes over time. A file contains one and
only one version of data—if the data changes over time and you want
to retain the changes, you need one file for each new version. These
files can be organized within folders or directories, but they are not
directly interrelated.
Configuration management systems like Source Integrity create
archives to provide these enhancements. Archives are structures that
store multiple revisions of a source file. They can store many different
types of user-supplied data and can efficiently store data between
revisions that have not changed much. Source Integrity stores one
archive file for each source file, but other systems use methods such
as databases.
Revisions are the basic unit of data placed under configuration
management control. Each revision corresponds to the content of a
source file at a particular instant in time. The collection of revisions of
a particular source file is the archive for that source file. When a
revision is extracted (or checked out) and changed, the new version
(once it is checked in) becomes the next revision.
10 Source Integrity Professional Edition

Branches
Metadata
Source Integrity Basics
Source Integrity Basics
Not all development is linear—different developers may want to take
the same piece of source material in different directions.
Configuration management systems like Source Integrity can branch
an archive, to preserve a copy of the original content for each
developer as they begin their individual work. Through the process
of merging, those different branches can be selectively woven back
together.
Any information about the source material in question is metadata.
Traditional file systems make little provision for metadata. Files
commonly have a file name that can be less than informative.
Systems keep timestamps and ownership information, but they do
not traditionally keep comments for each file.
With configuration management tools, you can assign plain-language
comments to each revision of a source file, communicating to anyone
who will use your revisions exactly what you changed. You can also
assign arbitrary or prescribed labels or state descriptors.
Configuration management tools can also add your identity (as an
author) to the metadata, to preserve an audit trail.
At its heart, any configuration management system must deal with
two basic facts:
Relationships exist between objects in the development
environment.
An object’s revision history must be tracked so that past versions
of projects can be recreated.
Once you understand that these key concepts are the core of your
configuration management system, all the other pieces begin to fall
into place.
Related Objects Even the simplest development effort consists of multiple files that
must come together to build a finished product, and the vast majority
of today’s projects are far from simple. Finished applications consist
of executables, libraries, resource and data files, help systems, and
myriads of other components. Each component of an application may
contain dozens of individual objects.
User Guide 11

Understanding Source Integrity
Changing
States
Often, the same files are shared by more than one component, and
entire components may be part of several larger modules. Source
Integrity’s projects let you define development objects and the
relationships among them. Source Integrity handles both simple and
complex objects—files, components, modules, or complete
applications—and automates the intricate weave of their
relationships.
What Are Development Objects?
Source Integrity lets you define objects and establish their place in the
development hierarchy at every stage of the development process.
Source Integrity can help you organize your resources into
meaningful, easy-to-manage units, so you can work with confidence
in a stable environment. This ability to group objects into logically
and functionally related projects, and to define relationships between
objects, provides a foundation for good development practices.
If building a software application were like building a house, Source
Integrity’s archives and projects—the building blocks—would be all
you would need. But software development is not a static process.
Imagine trying to build a house when the bricks and timbers keep
changing shape.
Unlike bricks and timbers, the objects used in software applications
change over time: files are updated and code modules are expanded
or broken down into smaller components. Software building blocks
change even after they are put into place.
Dealing With Constant Change
Source Integrity handles this problem by letting you take “snapshots”
of any object at every stage of its development. This snapshot—or
revision—then becomes a static building block that you use to build
your application while the object continues to evolve.
When a file or code module reaches a milestone, you can check in the
object to preserve its current state as a revision. When you need that
object to build your application or compile another module, it can be
recreated automatically, in precisely the same state as it was saved.
Using this technique, different revisions of the same object (that is,
the same object in different states) can be used to build various
components of an application. You can recreate components—or an
entire product release—if post-release fixes become necessary.
12 Source Integrity Professional Edition

Understanding Projects
Logical and
Functional
Structures
Understanding
Archives
Understanding Projects
With Source Integrity, you can control the granularity of your
development process. Source Integrity’s projects let you define
complex development objects and the relationships among them.
Individual files represent the development object at its lowest level.
However, modern software development’s size and complexity make
it impractical to manage at this level. Instead, Source Integrity takes
another approach.
Source Integrity’s approach to configuration management lets you
modularize your development effort. It lets you create logically and
functionally related subprojects that come together to build a finished
application. Every unit—or subproject—in the hierarchy is a
development object that can be managed either individually or
relative to the other objects it interacts with.
You can determine the number, size, and complexity of the
objects you work with.
You can define the relationships between development objects.
You can shape the project to address the management
requirements at your site.
There are two key issues to consider when you decide on the best
structure for your projects:
the functional structure, the directory trees where files reside
the logical structure of the Source Integrity project
Ideally, these two structures should be identical. The physical
organization of stored files—the project’s directory tree—should
reflect the logical relationships among files. Except for very small
projects, however, this ideal is almost never achieved. Usually, as a
project grows, new files and modules are added until the internal
relationship among components becomes too varied and complex to
be accurately reflected by the project’s directory tree.
A Source Integrity archive is the “place” where revisions (snapshots of
an object’s state at a particular point in time) are preserved. Any
development object can have an archive where revisions of itself are
stored, and from which they can be retrieved at any time. It is this
ability to save and recreate every development object—at any stage of
its development—that makes Source Integrity so effective as a
configuration management tool.
User Guide 13

Understanding Source Integrity
About Archives
Archives and revisions are fully integrated with Source Integrity
projects. When you add an archived object to a project, you add a
specific revision of the object, not the entire development object, which
might contain dozens or hundreds of different snapshots of itself.
Once the object becomes a project member, the project and object
automatically maintain their relationship: you can freeze the project
or the revision so only that particular revision will ever be used, or
you can track the archive and update the member whenever a newer
revision is available.
Because archives store development objects, you can have them at
any level of your development hierarchy. You can archive
individual files
entire projects consisting of any number of files and subprojects
No matter how simple or complex your objects are, you can save
snapshots of them in an archive and reproduce them—accurately and
reliably—whenever they are needed.
Archives provide the underlying storage structure for Source
Integrity. They contain your source files and the changes you make to
them. Archives also contain detailed information, or metadata, about
your files and their change history.
About Archive Structure
A new archive contains
Archive Information
Information about the archive itself (for example, the archive
description).
The first revision of your working file. The content of the file you
checked in.
Revision Information
Information about the revision (for example, the revision number
and the name of the person who has it locked).
The new archive can be represented graphically, as the following
illustration on the left shows. As you continue to work with your files
and add more revisions to the archive, it develops a structure much
like the trunk of a tree.
Each new revision adds to the line of revisions, as the illustration on
the right shows.
14 Source Integrity Professional Edition

This main line of revisions is
referred to as the trunk of the
archive.You can also add
branches to the archive to take
the content in a different
direction.
What Happens
at Check-in
Time?
Understanding Projects
When Source Integrity creates an archive for a source file, it performs
the following steps:
creates a new archive file
adds a revision to the archive and assigns it a unique revision
number (usually number 1.1)
copies the original file into the new revision
During subsequent check-ins to the archive, Source Integrity does
things slightly differently. Source Integrity
creates a new revision and assigns it a unique revision number
(for example, revision 1.2)
copies the working file into the new revision
compares the new revision (revision 1.2) with the previous
revision (revision 1.1) and calculates the differences between
them
replaces the contents of the previous revision (revision 1.1) with
the differences between it and the newer revision.
The list of differences between a revision and its immediate ancestor
is called a delta. An archive usually contains a complete copy of the
latest revision and all of the deltas required to reconstruct earlier
revisions. An archive can also be made up of complete copies of each
revision if you choose to configure the system that way.
User Guide 15

Understanding Source Integrity
Storing Deltas
When Source Integrity performs a check-in operation, it calculates
and stores the delta between the new revision and the previous one in
the archive.
For instance, in the situation described earlier, revision 1.1 (that is, the
first revision checked in) now contains a complete description of the
changes that must be made to revision 1.2 to rebuild revision 1.1. This
list of changes, the delta, is the key to understanding how archives
store revisions and rebuild working files on demand.
To check out revision 1.1, Source Integrity
reads the list of differences (that is, the delta) it contains
applies the changes to revision 1.2., rebuilding a duplicate of the
original revision 1.1
copies the revision to a working file
Using this technique, Source Integrity can recreate any revision
without having to store complete copies. Usually, if you save only the
changed portion of each revision, the archive will be much smaller
than if the entire file were saved each time. There are situations when
this may not be the case; if you are storing binary files in an archive, a
complete copy of each revision is stored by default (see “Storing
Entire File” next).
When Source Integrity compares the file being checked in to the
preceding revision in the archive, it compares the two files line by
line. While this is a logical—and efficient—way to handle text files, it
is not always effective with binary files, since a relatively small
change at the beginning of a binary file can displace all subsequent
characters in the file, cascading changes through all remaining lines.
As a consequence, the record of changes (that is, the delta) for some
binary files may be as large as, or larger than, the file itself. For this
reason, Source Integrity provides a number of configurable
techniques for checking in files.
Storing Changes Only
With this method, Source Integrity calculates and stores a delta for
each revision of a file when it is checked in. This is the default and
recommended method for checking in text files. You can use this
method for storing binary files, but MKS does not recommend it.
16 Source Integrity Professional Edition

Branches and
Trunks
Storing Entire File
Understanding Projects
With this method, Source Integrity does not calculate deltas, but still
stores all of the revisions of the file in one archive.
This is the default and recommended method for checking in binary
files.
Storing Entire File by Reference
With this method, Source Integrity does not calculate differences
between a file and the current revision. Instead, Source Integrity uses
the Reference format. In the Reference format, the archive file only
contains a summary of each revision with a pointer to a file that
contains that revision. Although this method requires more disk
space to store archives, it improves performance when checking large
binary files in or out of a project.
Note You can choose Store Changes Only or Store Entire File for both
text and binary files on the Checkin tab of the Personal Configuration
dialog box. You can choose Store By Reference for an individual archive
using the Archive Information dialog box.
The original development path of your project is also called the trunk,
and its most recent revision is called the head revision. If you check out
the head revision, modify it, and check it back in, Source Integrity
places a new revision at the top of the trunk, making it the new head
revision.
To move away from the main development path by creating a new
path, you check out, modify, and check in a revision that is not the
head revision. When you check it back in, by default, Source Integrity
will suggest that you create a branch; your new revision will now be
the tip of the branch.
A branch is an independent revision line that uses an existing
revision as its starting point. Branches have several uses. You may be
pursuing a line of development that will not be included in the
finished product or may need to create a branch to perform postrelease
maintenance on an earlier revision.
Revisions on the trunk are characterized by two-part revision
numbers (for example, 1.2 or 3.5), and branch revision numbers are
prefixed with the number of the revision they start from (that is, the
root revision).
User Guide 17

Understanding Source Integrity
Branching the archive permits
development to continue
unhindered on the trunk.
Contrast the branched
structure, previous
illustration, with the nonbranched
structure.
If a branch is started from trunk revision number 1.2, the revisions of
the branch are numbered (from bottom to top)
1.2.1.3
1.2.1.2
1.2.1.1
and so on. The first two digits of the number identify the root revision
the branch springs from; the last two represent a revision on the
branch.
Starting a Branch
Source Integrity always tries to build the revision tree vertically by
adding a new level every time you check in a file.
When you check in a revision that is not a tip revision, Source
Integrity assumes it should create a branch for the new revision,
because there is already a revision in place above it.
18 Source Integrity Professional Edition

Branching occurs when you
check in a revision that is not
at the top of the revision tree.
Understanding Projects
Replacing an existing revision or inserting a new revision between
two existing ones would alter the archive’s change history—this
behavior would undermine the entire process of revision control and
is therefore not allowed.
Revision Number, Branch Number, Branch Level
The revision number is the particular number of a revision. It is
composed of branch.version pairs.
Source Integrity considers the revision number without the last dot
and digits to be the branch number. As well, the branch level is the
“degree of removal” from the trunk. The following table shows the
relationship between revision numbers, branch numbers, and branch
levels.
Example Revision Number Branch Number Branch Level
1.3 1 0
1.9.2.3 1.9.2 1
1.11.2.4.1.1 1.11.2.4.1 2
Example
If you make four revisions to a source file named prog.c, Source
Integrity records revision 1.1 (the original revision), 1.2, 1.3, and 1.4.
This is the trunk of the archive.
If you need to work from revision 1.2 and make some new changes,
trying to check in the result will branch the archive, as our new
changes cannot replace the existing revision 1.3. Source Integrity
creates revision 1.2.1.1 for our changes to 1.2.
User Guide 19

Understanding Source Integrity
There is no limit to the
number of branches you can
create in an archive. You can
even have multiple branches
stemming from the same
revision.
Checkpointing
Your Project
The number of the branch created in the prog.c archive is 1.2.1 (since
it stems from revision 1.2 and it is the first branch from that revision).
The branch level of the 1.2.1 branch is 1, because it is one level
removed from the trunk (0). You could create a second branch from
revision 1.2 in the prog.c archive by repeating the steps you used to
create the first one.
Default Branch
Each archive has a default branch. Source Integrity tries to check in
files as revisions along this branch, unless you explicitly specify a
revision number. The default branch is the trunk of the archive, until
changed by the user.
When your project has reached a significant milestone, you should
save the state of the project and all of its components so you can
recreate it later if need be. In Source Integrity, this is called a
checkpoint. When you checkpoint a project, you create an archive for
your project file and check it in. Since the project file contains your
project’s directory structure and the list of members with their
revision numbers, you can recreate the project as it existed at the time
of the checkpoint.
Some users checkpoint at the end of each day or week, while others
wait until their work has reached a desired level of stability.
20 Source Integrity Professional Edition

Sandboxes
The directory structure in the
illustration is typical, although
most projects will be much
more complex, consisting of
dozens of directories and
hundreds (or thousands) of
files.
Sandbox Files
Sandboxes
The typical directory structure of a software development project will
look something like the illustration below. Problems can occur in
such structures when multiple users are active in a common
workspace. For example, if two programmers need to make changes
to a module, one has to wait until the other is finished.
Consider programmers working in the traditional “free-fire zone.”
There are obvious problems associated with an environment where
all developers work in the same directory tree.
It is easy to accidentally overwrite somebody else’s changes.
There are no safeguards to protect you from picking up another
developer’s incorrect or incomplete changes.
File access is restricted to one user at a time.
Because all of these situations can mean loss of data and result in
delays, Source Integrity offers a unique sandbox environment that
can eliminate such collisions. Sandbox environments are private
workspaces where individual programmers can work on projects
outside the free-fire zone. These separate workspaces allow
developers to work more efficiently, without conflict with other users.
When you use a sandbox, Source Integrity copies any or all of the
project files into an identical directory tree on your local machine,
where changes can be made and fixes tested. You can even test build
an entire project in a sandbox, without interfering with work being
done by other team members. When changes are completed and
tested in the sandbox, you can check them back in to update the
master project.
User Guide 21

Understanding Source Integrity
Sandboxes mirror the original
project and provide a safe
working environment.
A Typical
Workplace
Scenario
How Sandboxes
Can Help
Consider what could happen in a sample project if a customer
encounters a bug in an earlier release that requires an immediate fix.
In this example, the work is done in a free-fire zone and programmers
need to examine the earlier revisions of affected NT and UNIX files.
This process would halt any development on those files, due to
file naming conflicts in the workspace.
If the NT developer were to complete his or her work before the
UNIX developer, neither could test the fix until both are
complete, since a comprehensive build uses all files in the project.
The result is that maintenance only progresses at the pace of the
slowest component.
If more than one iteration is required to complete either or both
fixes, the time delay is further compounded.
Source Integrity has designed the sandbox environment to deal with
these potential conflicts. A sandbox is a personal workspace where
changes can be made and tested on working copies of project
members, independent of the master project. Sandboxes let each
developer work on a shared project in a personal, protected
workspace, without disrupting the master project or other
developers.
When work takes place using sandboxes, it presents a totally different
picture. When sandboxes are used in the previous scenario, each
developer makes a complete copy of the earlier release in a separate
sandbox and works on the files he or she is responsible for.
The developer who finishes first can test the fix in the sandbox—
even build the entire project to make sure it functions as
anticipated—then check the modified files back into the master
project and continue with new development.
22 Source Integrity Professional Edition

Once a Source Integrity
project has been created, you
have the option of creating an
associated sandbox. This
sandbox includes a directory
tree that mirrors the structure
of the master project.
Sandboxes
When the second developer completes and tests changes, they
too are checked into the master project. The buildmaster can
make a new sandbox, and do a final build incorporating both sets
of changes. The fix can then be shipped to the customer.
When you execute a Source Integrity command in a sandbox, the
action is redirected to the master project. Source Integrity can
perform almost the entire range of project commands in the sandbox,
as if it were in the master project. For example, if you check out a
sandbox member, Source Integrity physically checks out the member
from the master project, but copies the working file to the sandbox
directory.
In this way, you are assured of working with current data from the
master project, with the knowledge that your work will not interfere
with other users (or vice versa). This streamlines product
maintenance, saving time, saving money, reducing delays to ongoing
development, and increasing customer satisfaction.
Within your sandbox, you can see if new updates are available in the
master project. It is up to you to decide when and if you will pick up
these changes in your sandbox. Thus, you are protected from a “freefire
zone”, but still have the ability to coordinate with other users’
work when it is convenient for you.
User Guide 23

Understanding Source Integrity
Variant
Sandboxes and
Development
Paths
Regular sandboxes are based upon the current or head revision of the
project. You can also create a sandbox that is based upon a previous
checkpointed revision of the project. This type of sandbox is called a
variant. When you create a variant sandbox, you choose a checkpoint
(snapshot) of your project and use it as a starting point for new
development. Source Integrity allows you to do this by defining a
new development path.
A development path is an identifier given to a new direction of
software development; it includes the new revision history created by
Source Integrity as developers vary from a main project. Changes
made through the development path are kept separate from the main
development trunk unless you choose to merge them into it later.
Source Integrity allows multiple developers to point to the same
development path, each using their own variant sandbox. In the
variant sandbox, you can see the current state of software along the
development path and the changes made by other developers using
it.
When a variant sandbox is created for the first time, it is also created
for all subprojects, reserving the assigned name as a unique identifier
and ensuring no two paths can share the same name.
Development paths are useful for performing post-release
maintenance. Variant sandboxes pointing to a post-release
development path allow you to make changes to a previous revision
of a project. Any fixes, patches, or changes you check in go onto a
branch and do not affect the main project, unless you choose to merge
them.
Example: Multiple Development Paths
A team approach to development is shown in the following
illustration. Three development teams work on the product. Each
team is concerned with a slightly different aspect of getting the
product to market and satisfying customer needs.
24 Source Integrity Professional Edition

The labels in the illustration
indicate milestones in the
product’s development, rather
than any particular revision
number.
Build
Sandboxes
Sandboxes
Team one is composed of the developers who work on the main
trunk of development. Their concern is to create new features for
the software and therefore to move from release 3.2 to release 3.3.
This is considered the main development path.
Team two, the beta team, must test the functionality of the
product and prepare it for the beta trial. They work with the same
software, but just before the beta release, they must polish the
beta product on their own and their objectives force them to
diverge from the main path.
Team three is the post-release maintenance team. They want to
change the functionality of a feature in the shipping version to
satisfy a customer request, and then release a patch for the
product.
The teams all have slightly different goals for the software and each
group needs to move the product in a different direction without
affecting another team’s ability to work. Each team is following a
different development path.
After major milestones such as product releases, you might want to
recreate a static version of an entire project as it existed at some point
in the past. You use a build sandbox, as it is called, to build or test the
project, not to begin further work along a new development path.
A build sandbox is associated with a particular project revision, and
has no development path (since it is static and not meant for further
development).
Within a build sandbox, you cannot
check out, lock, or check in members
User Guide 25

Understanding Source Integrity
Locking in
Variant
Sandboxes
remove or add members
set the development path
However, within a build sandbox, you can
change labels and states
resynchronize your sandbox
compare a member revision in the build sandbox to another
revision
merge a member revision in the build sandbox with another
revision (of course, you cannot check that merged file back into
the build sandbox)
query for differences between project revisions, such as changes
to a project since it was last checkpointed
calculate dependencies, but you cannot add dependent files to
the project
update sandbox attributes
Source Integrity can manage access to source files by locking
revisions in the name of developers who check them out. This
provides a level of security, as it discourages two people from
working on the same revision at the same time.
When developers are following different development paths,
however, this kind of security can become inconvenient. Two (or
more) developers, working along different development paths, may
want to lock the same revision for different purposes.
Even though development paths are logically separate, Source
Integrity maintains one revision history for each source file, in a
corresponding archive. A revision can only be checked out locked by
one Source Integrity user. Conflicts can arise from this.
Those working in variant sandboxes are forced to lock revisions
that might be needed by developers working in standard
sandboxes.
Similarly, those following one development path would lock out
those following a different path.
To accommodate developers following different development paths,
Source Integrity will suggest to branch an archive. It does this
whenever a check-out operation would lock out other developers,
who might need access to the revision.
26 Source Integrity Professional Edition

Sandboxes
The process starts with developers who use variant sandboxes. If you
are using a variant sandbox, your check-out operations might cause
conflict if you try to lock
a revision in the main trunk of an archive (probably used by the
main project and standard sandboxes)
a revision on a branch that was created by others, working from a
different development path
Source Integrity will then suggest you start a branch from that
revision. This creates a duplicate of the revision on a new branch. The
duplicate is locked in your name, allowing you to edit it freely.
On the other hand, there is no perceived conflict when you want to
use a revision on a branch created through your own development
path. Source Integrity assumes locking is desirable between those
who share your own development path.
The process is repetitive: if users on another development path
attempt to check out locked a revision from one of your resulting
branches, they will in turn be encouraged to branch the archive again,
to avoid locking you out of your revisions.
This branching is not mandatory—you can opt to lock a (potentially
conflicting) revision from within a variant sandbox. This amounts to
crossing the invisible line between your development path and
another path or the main project.
For instance, if you have adopted a trunk revision as a member
revision in an otherwise variant sandbox and you intend on checking
in changes to the trunk, locking the revision on check-out is
appropriate.
If for some reason your branch needs to be integrated into the trunk,
this can be accomplished by merging the tip revision of the branch
and the head revision of the trunk (1.x) in a standard merge
operation. This is normally done by a developer using a standard
sandbox.
Note Even if the head revision of an archive is not the member revision
of your variant sandbox, Source Integrity will suggest to start a branch if
you attempt to check out the head revision locked. This functionality is
maintained for backward compatibility with previous versions of Source
Integrity.
User Guide 27

Understanding Source Integrity
Converting Old-
Style Variant
Sandboxes
Example
You have created a variant sandbox and a new development path,
based on revision 1.3 of a project. Your sandbox represents an older
version of the project, but you find you still need to make changes to
the head revision, revision 1.5 of main.c. You check out locked
revision 1.5 of main.c.
Source Integrity will by default suggest to branch the main.c archive.
It does this because you will otherwise lock other developers out of
main.c, and your work is on a development path other than on the
main path.
If you accept the default, Source Integrity creates revision 1.5.1.1 of
main.c. It copies revision 1.5 to 1.5.1.1, and checks out 1.5.1.1 locked
in your name. You can make changes to the new revision, and check it
back in as 1.5.1.2.
Because Source Integrity branched the archive, other developers are
not locked out of revision 1.5. They can continue development
unhindered.
If you do not accept the default, you will acquire a lock on revision
1.5 of main.c. You could make changes and check in revision 1.6.
Variant sandboxes created in Source Integrity version 7.2 or earlier
must be converted to work with later versions. This is a one-way
process that makes the variant sandboxes incompatible with previous
versions of Source Integrity.
A command-line utility, cnvrnt72, is available to do the conversion
automatically. You must have sufficient permissions in the Security
and Administration Module (SAM) to perform the conversion:
ModifyProject, ModifySandbox, and CreateSandbox. (For details
on usage, see the cnvrnt72 manual page in the Source Integrity
Professional Edition Reference Guide.)
28 Source Integrity Professional Edition

Metadata
About Labels
Metadata
The most important conversion step is the establishment of a
development path for the variant sandbox. This development path
will begin at a new checkpoint in the master project.
Note If a master project has other subprojects as members, then a
sandbox based on it will have subsandboxes, individual sandbox files
matching the same structure. cnvrnt72 converts the specified sandbox,
and recursively converts all subsandboxes as well.
Running cnvrnt72 on a subsandbox file will convert it and all of those
below it, but cnvrnt72 cannot convert any sandbox files above it in the
hierarchy. This will cause problems when using the sandbox, and when
later trying to finish the conversion. You should run cnvrnt72 on the
uppermost sandbox, that is, on the one that is not a subsandbox.
Source Integrity maintains a variety of information about your
development objects. This metadata can be used to monitor and
manage projects, identify and retrieve revisions, update working
files, and prepare activity reports on your development efforts.
An important part of any configuration management system is the
regular input of significant metadata, such as
archive descriptions when archives are created
revision descriptions and labels when objects are checked in, and
at project milestones
automatic records, such as timestamps and transaction logs
This section describes some of the ways you can take advantage of
the metadata Source Integrity maintains.
When you check in a file, Source Integrity lets you assign a revision
label to it. Labels serve as identifiers for revisions in an archive, and
make it easier to locate significant revisions of your objects. Many
Source Integrity functions use labels to specify the revision a
command will operate on. For instance, you can check out a revision
by specifying its label.
User Guide 29

Understanding Source Integrity
About Revision
Descriptions
Labels provide an effective mechanism for tracking development
objects. Because revisions can have more than one label, they are
perfectly suited to multi-track development. The fact that labels are
unique within an archive makes them an efficient tool to mark
milestones for later retrieval.
Labeling Requirements
Labels have a number of restrictions on their contents.
They cannot
exceed 1,024 characters in length
contain left square brackets ([), right square brackets (]), or
colons (:)
contain a leading space
resemble a revision number; that is, a number of the form x.y,
such as 2.13.
Versions of Source Integrity prior to Release 7.3c, Source Integrity for
UNIX, and Source Integrity for OS/2 will still be able to read archives
with the current label format, but labels will show up with new
characters translated (for example, a space will appear as %20).
To be useful, labels must be accessible and convey the same meaning
to everyone who uses them. A well-thought-out system of consistent
labels can simplify the ability to identify and retrieve important
revisions, and let you script repetitious file management tasks.
For example, some sites use a system of standard prefixes to identify
the scope of labels: site-wide labels use a specific prefix (like MKS_ or
SITE_); labels for individual projects have prefixes that reflect their
associations.
When you checkpoint your projects, you can also apply a label to the
project itself and, optionally, to every project member. This simple
step makes reconstructing any development environment for postrelease
maintenance a one-step process; just create a new sandbox
based on a labeled checkpoint and let Source Integrity create and
populate it with all the correct member revisions.
Revision descriptions let you add notes and explanations to your work
every time you check in a revision. They provide a useful tool for
managing your development by helping you document the reasons
for a change. You should develop the habit of including a detailed
description of every revision you check in.
30 Source Integrity Professional Edition

About
Timestamps
Metadata
When you finish making changes to a file and check it in, the nature
of the changes, and the reasons for them, are clear to you. They may
not be clear to everyone else, and in six months they probably will
not be obvious to you either.
If you consistently add notes to your revisions in the form of revision
descriptions, you can preserve a detailed project record. You can then
use Source Integrity’s Reporter utility to retrieve, display, and
analyze these revision descriptions.
You can also append new comments onto an existing revision
description. The time and author of such additional comments are
automatically included.
Most developers realize how critical timestamps are during the build
process. Building a program requires linking a number of objects that
are themselves compiled from source code. These files could include
header files, source files, object modules, and executables. The source
code usually depends on other source modules and one or more
header files. These dependencies are recorded in a makefile that is
used by a build or make program.
During a build, the make program uses timestamps to streamline the
process; it refers to file timestamps to find components that have
changed since the last build and that, therefore, need to be rebuilt.
When the make utility finds a file that another component depends
on—and determines that the file has a newer timestamp than the
component—it assumes that either the file has changed, or the
component that depends on the file must be rebuilt.
If a component’s timestamp is identical to, or newer than, all of the
files it depends on, the make utility reuses the component without
rebuilding it.
When you check a file into or out of an archive, you can specify how
the timestamp of the working file should be set. Since timestamp
changes affect dependencies between files (and therefore the make
process), Source Integrity must be configured to set timestamps
appropriately for your build environment.
Timestamps can be set at check in and check out. At check in you can
set the timestamp of the new revision to either the current time or to
the timestamp of the working file. At check out, you can set the
working file’s timestamp to the current time or to the timestamp of
the revision.
User Guide 31

Understanding Source Integrity
For information about
configuring timestamps, see
the “Configuring Source
Integrity” chapter in the
Source Integrity Professional
Edition Administrator Guide.
About
Attributes
Example: How Timestamps Affect the Build Environment
The significance of timestamp settings can be illustrated with the
following example. If these files are dependent
hello.exe --> hello.obj --> hello.c
and Source Integrity is configured to set timestamps to the current
time at both check in and check out, the following scenario arises:
On Monday morning hello.c is checked out locked, and some
changes are made to it.
The make utility is run to build the program. Everything builds
smoothly and all three files (hello.exe, hello.obj, hello.c)
have Monday’s timestamp.
Since the program was built without incident, hello.c is then
checked in unlocked.
Note When you check in a file unlocked, Source Integrity actually
checks it in and then checks it out unlocked, replacing the editable working
file with a read-only copy.
The make utility is run again, but this time everything is rebuilt,
even though the source files have not changed.
The result of using the current time at check-in and check-out is that
components are rebuilt unnecessarily. This is not only frustrating, but
a waste of valuable development time.
This problem can be avoided by using the SaveTimestamp and
RestoreTimestamp configuration options as follows.
SaveTimeStamp sets the timestamp of revisions to the timestamp
of the working files when they are checked in.
RestoreTimeStamp sets the timestamp of working files to that of
the revision they are checked out from.
You can assign attributes to projects and their members. Attributes
can be used to identify members, to define or restrict the scope of
project commands, or to automate project management operations.
Attributes are variable statements with the form
var [=value]
32 Source Integrity Professional Edition

For information about
configuring attributes, see the
“Configuring Source
Integrity” chapter in the
Source Integrity Professional
Edition Administrator Guide.
Metadata
where var is the name of the attribute, and value is its optional
assigned value. Attribute names may contain any combination of
alphanumeric or underscore characters; they may not begin with a
number.
Some project attributes are reserved by Source Integrity. Because of
their special meaning, they are called Configuration Options. If present,
Source Integrity overrides its built-in defaults and takes its
configuration from them.
The value portion of an attribute statement may contain any number
of printable ASCII characters.
About Log Files Source Integrity can monitor and keep track of actions that change
archives (for example, checking in a new revision). This ability
provides a powerful mechanism your organization can use to
generate audit trails for individual archives, development projects, or
an entire site.
About
Keywords
Whenever you check in or check out locked a revision, Source
Integrity adds a line to a log file describing the operation.
Automatic transaction logging can help managers assess the progress
of development projects, as well as the contributions of individual
programmers. Depending on site requirements, records can be
maintained in two ways:
in a single, monolithic log file describing all activity for all files at
the site
in a project log file containing reports for a single project
A keyword is a placeholder that can be inserted into text-based
working files. Source Integrity updates keywords with information
about the revision or archive. Keywords provide a handy mechanism
for accessing up-to-the-minute revision information from within a
working file.
User Guide 33

Understanding Source Integrity
Security and Administration
Source Integrity
Security
For information about filelevel
security, see the Source
Integrity Professional Edition
Administrator Guide, “Source
Integrity Security”.
The SAM
Hierarchy
No matter how well-designed or feature-filled your configuration
management system is, it will be less effective if it is not used
consistently by everyone at your site. Since no two sites are alike,
Source Integrity provides SAM to let administrators define and
enforce Source Integrity’s configuration management policies.
SAM lets administrators control configuration management activities
at your site by defining which users have access to any or all Source
Integrity functions (and, therefore, to the files in your development
environment). SAM’s management controls can be applied at
whatever level your site and corporate situation require, that is
to all files and users at the site
to specific projects
to specific groups of users
to individual archive files
to individual users
Using SAM, the administrator of your site defines which files and
projects under Source Integrity you have access to, and the degree of
that access. This is done by defining a number of structures within
SAM: policies, users, groups of users, and roles.
Policies
A policy is a group of Source Integrity configuration statements that
can be associated with your entire site or with any development
object within it.
Policies are arranged in a hierarchical inheritance structure to
simplify management. Your administrator can define general
practices at the global (that is, site-wide) level, and then fine tune
these policies for individual projects and archives.
For example, your site could have a global policy that establishes a
strict-locking policy for all objects at the site, plus a policy at the
project level to require encryption on a particularly sensitive project.
Users
The SAM database contains the names of all users with access to
Source Integrity.
34 Source Integrity Professional Edition

Groups
Security and Administration
Users can be placed together in groups according to how they should
be using Source Integrity.
Roles
A role is a set of Source Integrity permissions that can be associated
with a user or with a group of users. It defines access and restrictions
for the Source Integrity users with that role at your site.
When a user invokes a command, Source Integrity checks any roles
associated with the user and reads the permissions they contain in
order to determine whether to allow the action.
Example: Group Permissions
If your corporate development standards include a protocol for
passing work from one person to another, you may want to take
advantage of the freezing and thawing capabilities of Source
Integrity.
Let’s assume that Development must sign-off on the work by
checkpointing the project. At that point, they might also freeze the
project and alert the Testing group that the product is ready for
evaluation. Testing might thaw the project if they need to make very
minor fixes.
In order to ensure there is no going back, the Source Integrity
administrator can convey FreezeProject (but not ThawProject)
permissions to the Development group.
Rather than doing this individually, the administrator can create a
group in SAM and add all the development members. The
administrator would also create a role holding the FreezeProject
permission, and assign the role to the group. Therefore, every Source
Integrity user that is part of the group receives the FreezeProject
permission.
Permissions are additive, so the administrator must ensure a user is
not obtaining the ThawProject permission from any other source,
that is, a role assigned
directly to the user in the same module
directly to a user in another module
to another group the user is a member of
User Guide 35

Understanding Source Integrity
Managing Development
Promotion
Source Integrity includes two features that help you track the
development process.
The Promotion feature lets you impose a step-by-step
progression on the development cycle.
The Reporter utility lets you view the audit trail of files and
resources.
The Promotion feature lets you track the progress of your product
through the development cycle to a finished product. The Promotion
model at your site
defines your development cycle
specifies how files will be handled at each development stage
controls who can modify development objects at each promotion
state
Although most aspects of the promotion policy at your site will be
defined by your administrator, you can customize some settings
locally.
The development cycle at your site might include the stages
Development, when code is being actively written
Testing, when each code module and application is tested
Release, when the code is declared finished, and distribution
disks can be produced
In this case, your administrator could set Source Integrity promotion
policy as follows:
All development objects must pass through each stage in the
development cycle, from lowest to highest.
During the Development phase, only the Development Leader
can promote objects to the Testing phase. (Source Integrity lets
you define who may promote and demote.)
Any tester can demote an object back to the Development phase
if it fails a test, but only the Quality Assurance Manager can
promote an object to the Release state.
This policy guarantees that the state of every product component
would be obvious at any time, and that each component would pass
through each phase of the development process successfully before
moving on to the next.
36 Source Integrity Professional Edition

Reporter
Managing Development
Most sites need a way of examining ongoing projects so they can
identify trends, check hot spots, predict problems, or prevent
schedule slippage. To deal with this need, Source Integrity includes
the Reporter. This utility helps you analyze the revision history of
project members and revisions.
Depending on the requirements at your site, you can view any of the
Reporter’s built-in reports on development patterns and activities.
The Reporter also lets you import raw data into your own database,
where you can create custom reports tailored to your own needs.
Report Types
The Reporter utility includes nine different types of reports based on
the information Source Integrity maintains about project members
and revisions. Reports can be presented as formatted text and some
can be displayed as graphs (bar, pie, line, or area charts).
Changes Grouped by Author lists changes to members or revisions
grouped by the person who made them.
Changes Grouped by Author (Summary) summarizes the changes
to project members, or archives, grouped by author.
Revisions Newer Than Member Revision shows which project
members have more recent revisions available.
Changes from Member Revision to Label lists all the revisions
between the project member and another revision with a
specified label.
Changes From Member Revision to Revision lists revisions in a
project member’s archive between the member revision and
another revision (specified by revision number).
List Locked Revisions lists all locked revisions in a project or an
archive, giving the name of the member, the revision number,
and the person who has it locked.
List Revisions Associated with Labels scans the archives of all
project members and extracts any labels they contain.
List Revisions Associated with States scans the archives of all
project members and extracts any state settings they contain.
Project Member History displays change information for all
revisions of a specified project member.
User Guide 37

Understanding Source Integrity
38 Source Integrity Professional Edition

Introducing the Source
Integrity Interfaces
3
This chapter provides a brief introduction to the three interfaces to
Source Integrity:
The Windows interface, a standard Windows application.
The Source Integrity Web Interface, which gives you the ability to
access development projects remotely using their web browser
(either Microsoft Internet Explorer 4.0+ or Netscape Navigator
4.0+).
The command-line interface, which allows you to type powerful
commands at a command prompt or develop scripts for
automating common activities.
If you are unfamiliar with Source Integrity, you should begin with
the Windows interface.
You will probably not use Source Integrity through just one of these
interfaces exclusively, but rather decide over time which interface is
best for a particular activity within your environment and workflow.
For detailed information about how to use Source Integrity, with
specific instructions for each of the three interfaces, see Chapter 4:
“Getting Started With Projects, Sandboxes, and Members” on
page 65.
For information about how to use Source Integrity within
development environments, see Chapter 7: “Using Extensions” on
page 197.
User Guide 39

Introducing the Source Integrity Interfaces
The Windows interface
Starting the
Source Integrity
Windows
Interface
The Application
Window
The most commonly used interface to Source Integrity is the standard
Windows application, with a menu bar and tool bar for choosing
commands.
If you have performed the standard installation, you can start the
Source Integrity Windows interface application by choosing
Programs > MKS Source Integrity > Source Integrity for Win32 from
your Start menu or double-clicking the Source Integrity icon in the
MKS Source Integrity program group.
When you open the application for the first time, Source Integrity
displays a Tip Wizard and Startup Wizard.
If you want to open an existing Source Integrity project or sandbox,
you can also browse to the project directory in Windows Explorer and
double-click the .pj file.
The application window contains a number of common Windows
features explained in this section.
Title bar
Menu bar
Toolbar
Workspace
Status bar
Menu Bar
Context menu
(right click menu)
Filter list
The menu bar is located directly below the title bar and contains the
available pull-down menus. When you first start Source Integrity,
there are three menus in the menu bar: File, Configuration, and Help.
The list of available menus and commands varies depending on the
40 Source Integrity Professional Edition

For more information on
filters, see “Using Filters” on
page 44
The Windows interface
function you are performing (for example, working with an archive
or a project). In the previous diagram, the Source Integrity menus that
are available when working with a project or sandbox are displayed.
Toolbar
Immediately below the menu bar is an optional toolbar that provides
easy access to the most commonly used Source Integrity commands.
Toolbar functions are executed by clicking the appropriate icon with
the left mouse button. If a command is not currently available, its
toolbar icon is grayed out.
Two toolbars are available for Source Integrity: one for archiverelated
functions and the other for project-related functions. When an
Archive window is current in the application window, the archive
toolbar is displayed; when a Project window is current, Source
Integrity automatically presents the project toolbar. Both toolbars can
be modified in the Toolbar panel of the Personal Configuration dialog
box. To set up a toolbar, choose the one you want to work with from
the Select Toolbar box, and the remaining options in the panel act on
the selected toolbar.
Filter List
Beside the toolbar is an optional list of built-in filters that allows you
to focus your view on a subset of project members you are currently
interested in. Only those members that meet the criteria specified by
the filter are displayed. You can decide whether to display this list of
filters through the View menu. Choose Filters when you want the list
of filters to be available, and deselect it when you want to hide the list
from view.
Note The list of built-in filters is disabled when there is no project or
sandbox currently loaded, as well as when you are working in the
Archive window.
Workspace
Everything between the toolbar and the status bar is considered the
workspace. This is where Source Integrity displays windows
containing your projects, sandboxes, or archives. For example, when
you open a project, its members are presented in a Project window in
the workspace.
When you first start Source Integrity, the workspace is empty.
User Guide 41

Introducing the Source Integrity Interfaces
The Project
Window
Context Menu
Source Integrity supports Windows 95/98 and Windows NT
standard context menus. Selecting and right-clicking
a project member in a project window
an archive revision in an archive window
the empty application window
displays a pop-up menu of actions you can perform on the selected
item.
Status Bar
When you select a command in a Source Integrity pull-down menu, a
brief explanation of its purpose is displayed in the status bar. In
addition, if the Hint mode (in the Toolbar panel of the Configuration
command) is set to Both or Status Bar Tips, explanations of the
toolbar buttons are displayed when the mouse pointer rests over
them.
When you open a Source Integrity project, the status bar displays
total number of members in the current project
number of members that are currently locked
number of members you have selected
When you open a project or sandbox, Source Integrity displays its
contents in a Project window. The window has the title Sandbox
path\filename or Project path\filename where path\filename represents
the fully qualified DOS filename of the sandbox or project.
Source Integrity offers you a choice between two different views of
your Project and Sandbox windows: You may choose to work with
the List view or the Tree view.
The List view of the Project window contains a selectable list with
entries for every member of the sandbox or project. The information
for each member includes:
Type of member.
If you freeze a project or freeze a member, the snowflake icon
alerts you to the archived member’s condition. The description
Frozen Member appears at the bottom of the window.
If either the member’s working file or archive has been modified,
a change symbol (delta) appears, and a description of the changes
is shown at the bottom of the window.
42 Source Integrity Professional Edition

The Archive
Window
The Windows interface
The delta symbol with a page icon means your working file has
changed. It also appears when no working file exists for the
member.
The delta symbol with a book icon means the member archive
has later revisions available. It also appears when no archive
exists for the member.
If you lock a member, a padlock alerts you to its condition. The
date and time the lock was placed also appears next to the user
name of the person who locked the member.
Member’s revision number.
Name of the member’s working file.
State of the member revision.
Any labels assigned to the particular revision.
Select a member by clicking it, or by moving the selector bar to it with
the cursor control keys. A box below the list of members displays
change information if the selected member’s working file has
changed, relative to the member revision. For example, if the working
file has been updated but not checked in, a message alerts you that
the working file is newer than the member revision.
The Project window can be resized within the Source Integrity
application window’s workspace or reduced to an icon in the
application window.
The Project window also supports Windows 95/98 and Windows NT
standard context menus. Selecting and right-clicking a project
member in a Project window displays a pop-up menu of actions you
can perform on the selected item.
When you open an archive, Source Integrity displays its contents in
an Archive window. The window has the title Archive path\filename
where path\filename represents the fully qualified DOS filename of
the archive.
The Archive window contains a selectable list with entries for
working file (if one exists)
every revision in the archive
Select a revision by clicking it or moving the selector bar to it with the
cursor control keys.
User Guide 43

Introducing the Source Integrity Interfaces
Using Filters
Each entry in the list contains information about a single revision in
the archive. This information is displayed in columns with the
following headings:
Revision. The revision number.
Author. The user who checked in the revision.
Date. The date and time the revision was checked in.
Locker. The user name of the person who locked the revision, as
well as the date and time the lock was placed.
State. The revision’s state setting.
Labels. The label attached to the revision.
A box below the list of revisions displays the revision description for
the currently selected revision. As you move the selector bar from one
revision to another, the description changes to reflect the currently
selected revision.
The first entry in the Archive window is the archive’s working file (if
one exists). The entry shows the fully qualified filename of the
working file.
If the working file can be edited, the entry is preceded by a pencil
icon. If the working file is read-only, the pencil icon is crossed out in
red.
The Archive window can be resized within the Source Integrity
application window’s workspace or reduced to an icon in the
application window.
The Archive window also supports Windows 95/98 and
Windows NT standard context menus. Selecting and right-clicking an
archive revision in an Archive window displays a pop-up menu of
actions you can perform on the selected item.
As projects become large, they can become more difficult to navigate.
Finding and selecting the members you are interested in becomes
increasingly difficult. Filters allow you to view and manipulate a
predefined subset of project members that are grouped according to
their properties.
In the Windows interface, the filters appear in a drop-down list
located on the toolbar. Choose one of the following filters, and your
view is filtered accordingly:
All members. All members of the current project or sandbox.
Modified members. Members with a working file that has been
modified.
44 Source Integrity Professional Edition

Filtering Modes
Using Tree View
The Windows interface
Out-of-sync members. Members whose revision in a sandbox is
not the same as the member revision in the corresponding
project.
Locked members. Members locked by any user.
Locked by me. Members locked by the current user only.
Frozen members.
Subprojects. Members that are themselves projects.
Members with label. Members with a particular label. If you
choose this filter, Source Integrity prompts you for a label.
Members with state. Members with a particular state. If you
choose this filter, Source Integrity prompts you for a state.
Note The list of built-in filters is only displayed if a Project or Sandbox
window is the active window.
Source Integrity provides two filtering modes: Global and Per-
Project. If filtering is set to Global, the filter currently displayed in the
list of filters applies to all open projects. With Per-Project filtering,
each open project has its own filter.
To set the filtering mode:
1. Choose Configuration > Personal.
The Personal Configuration dialog box appears with the
Preferences panel displayed.
2. In the View Defaults section, select Global or Per-Project as your
preferred filtering mode and click OK.
Source Integrity offers you a choice between two different views of
your Project and Sandbox windows: You may choose to work with
the List view or the Tree view.
Note You cannot switch an Archive window from List view to Tree
view.
When expanded, subdirectories and subprojects now appear as tree
branches. The right pane of the current window still displays the List
view (list of members and subprojects) with the same columns.
User Guide 45

Introducing the Source Integrity Interfaces
You can move two sets of pane splitter bars to resize the window
panes: the splitter bar between the left and right pane, and the one
between the right pane and the status area.
Select items from the right pane to perform operations on these
selected items. Multiple members and subprojects can be selected
and operated on in the right pane just like the Source Integrity List
view window.
To change the current view
Choose View > Tree view or View > List view, depending on the current
view.
If you choose List view when the Tree view is active, the List view
window displays members and subprojects of the master project.
You can set the default view for projects upon startup in your
personal configuration.
1. Choose Configuration > Personal.
The Personal Configuration dialog box appears with the
Preferences panel displayed.
2. In the View Defaults section, select either List view or Tree view as
your preferred default Project view and click OK.
Expanding a Project
To expand a project in the left pane of the Tree view:
Click the “+” symbol to see the subprojects and subdirectories (if
applicable) in the project.
Select the subdirectory to update the right pane with the list of
project members in the subdirectory.
Select the project (it becomes highlighted) to see the list of
members in the current directory and any subprojects in the right
pane.
Subprojects expand like the master project: members and subsubprojects
are listed in the right pane.
Double-click the project to both select and expand the project.
This updates both window panes.
In the List view, when you double-click a subproject a new List view
appears. If you double-click a subproject in the right pane of the Tree
view, the corresponding subproject in the left pane is selected and its
46 Source Integrity Professional Edition

The Windows interface
members are displayed in the right pane. To open a separate window
for a subproject, right-click the project in the left pane and choose
Open In New Window.
The right pane uses the same context menu as the standard project
window to operate on members selected in the right pane.
The left pane has its own context menu items:
Create Sandbox
Open Project Archive
Checkpoint
Open In New Window
Project Information
Development Path (for variant sandboxes)
Drag and Drop
List View
Users can drag files and projects from outside the Project window
(for example, from Windows Explorer) and drop them into the
Project window. Dropped items are added to the current project as
members and subprojects.
Tree View
The Tree view exhibits similar behavior if the right pane is displaying
members and subprojects: items dropped into either pane are added
to the current project (that is, the project selected in the left pane) as
members and subprojects.
Using the Restore Desktop Feature
When you close Source Integrity with Project or Sandbox windows
still open, Source Integrity can save the view type (List or Tree) for
each window so that the same view of each project or sandbox
appears the next time you open Source Integrity.
To turn on the Restore Desktop feature:
Select the Restore Desktop option in the Preferences panel of
Personal Configuration dialog box.
User Guide 47

Introducing the Source Integrity Interfaces
Using Source
Integrity With
Windows
Explorer
For more information on the
Source Integrity extensions,
see “Using Extensions” on
page 197.
In addition to the application window, Source Integrity commands
are also available from the Windows Explorer. If you installed the
Source Integrity Windows Explorer Extension when you installed
Source Integrity, a Source Integrity sub-menu was automatically
added to the Windows Explorer File menu. You can also access
Source Integrity commands via the right-click context menu.
If you did not choose this installation option, you can install the
Source Integrity Extensions any time by double-clicking the
setup.exe file in the root directory of the Source Integrity CD and
choosing the Source Integrity Extensions option.
The Source Integrity Web Interface
The Source Integrity Web Interface allows you to access some Source
Integrity functionality through a web browser. It is a true clientserver
product, with the Internet forming the basic connection
between the client and the server. It has three components:
client
browser plugin
session applet
The client component is a local server that generates the interface for
the browser to display and provides local file access. It communicates
directly with the Integrity Server over the Internet to access the
version control services. The browser plugin starts up the client
component of the Source Integrity Web interface. The session applet is
a small applet that informs the client component of a browser page’s
status.
The look and feel of the product has been adapted to its web-based
environment. Source Integrity users will find that the web-enabled
version of the product provides easier access to common operations,
and that commonly used operations have been simplified.
48 Source Integrity Professional Edition

Installing the
Source Integrity
Web Interface
The Source Integrity Web Interface
To install the Source Integrity Web Interface on a client machine
for the first time:
1. Contact the Integrity Server with your browser. The
administrator can tell you the URL.
A typical URL of the Integrity Server may be of the form:
http://machine_name.your_domain_name.com:/
A web page appears inviting you to download the Source
Integrity Web Interface.
2. Download the Source Integrity Web Interface installation
program (that is, save it to disk).
3. Close the browser.
4. Run the installation program following the instructions
provided.
5. Restart the browser and connect to the Integrity Server.
The Source Integrity Web Interface home page appears.
6. Add this page to your list of bookmarks (on Netscape) or
favorites (on Internet Explorer) for convenience.
To update an existing version of the Source Integrity Web
Interface:
1. Uninstall your current version of the Source Integrity Web
Interface by choosing Start > Settings > Control Panel and doubleclicking
Add/Remove Programs.
The Add/Remove Programs Properties dialog box appears.
2. From the Install/Uninstall tab, select MKS Source Integrity Web
Interface from the list of installed applications and click Add/
Remove.
You are asked to confirm that you want to remove the MKS
Source Integrity Web Interface and all of its components. Click
Yes.
3. Follow the instructions above, “To install the Source Integrity
Web Interface on a client machine for the first time”.
User Guide 49

Introducing the Source Integrity Interfaces
Installing
Additional
Browser
Plugins
Starting the
Source Integrity
Web Interface
4. Contact the Integrity Server with your browser.
Note The Source Integrity Web Interface provided with Source Integrity
Professional must always be upgraded when a version is available from
the Integrity Server. There is no optional upgrade feature available.
When you install the Source Integrity Web Interface, it installs a
plugin for each chosen browser on your system at installation time.
However, you may also want to use the Source Integrity Web
Interface with additional browsers (such as one you installed after the
original installation).
To install a plugin for one or more additional browsers:
1. Click Start > Programs> MKS Source Integrity Web Interface >
Plugin Configuration Utility.
The Welcome window appears.
2. Click Next>.
The Install Plugin window appears and displays the web
browsers the plugin is already installed for.
3. Add or remove a browser from the list by selecting the browser
and clicking the Add or Remove buttons.
4. Click Next> to complete the installation of the plugin.
To start the Source Integrity Web Interface, start your web browser
and browse to the Integrity Server. Your Source Integrity
administrator can provide you with its location.
A typical URL of the Integrity Server may be of the form
http://machine_name.your_domain_name.com:/
If the location you entered is correct and the Integrity Server is
configured properly, your browser displays the Integrity Server home
page.
50 Source Integrity Professional Edition

The Source Integrity Web Interface
On the Integrity Server home page, click Source Integrity. Your
browser displays one of the following:
If you have already installed the most recent Source Integrity
Web Interface client component on your local machine, your
browser displays a window that prompts you for a user name
and password.
After you enter them, your browser displays the Source Integrity
Web Interface home page (see “The Source Integrity Web
Interface Home Page” on page 52). For convenience, add this
page to your list of bookmarks (on Netscape) or favorites (on
Internet Explorer).
If you have not yet installed the client component, your browser
displays a page that allows you to download and install the client
component.
If the version of the server is newer than your client, the client
will still work with the new server. When you want to install the
new client, you must first uninstall the old client.
On that page, click Source Integrity Web Interface Client Install to
download the client install executable, called siwi.exe. Run the
executable and follow its instructions.
When you have finished installing the client, restart your browser
and return to the Source Integrity Web Interface home page.
User Guide 51

Introducing the Source Integrity Interfaces
The Source
Integrity Web
Interface Home
Page
Introduction to
Views
The Source Integrity Web Interface displays information about your
projects and sandboxes and provides commands in a web browser
window.
Across the top of the window, there are drop-down menus that allow
you to choose commands that affect sandboxes and projects and set
configuration options.
In the Sandbox and Project views (“Introduction to Views” next), you
can use filters to allow you to see a currently significant subset of
information, without having to sort through the entire project. You
can also use selections to choose files that fit a particular category.
In the Source Integrity Web Interface, you can choose from four ways
to look at your projects and sandboxes, or views. You select a view by
clicking its button on the toolbar on the left side of the window. The
button for the current view is highlighted, and buttons for views that
are inaccessible or do not apply are disabled and grayed out.
Overview of the Sandbox View
The Sandbox view displays the members of a sandbox and provides
commands that act on them.
A hierarchical list of the sandbox members appears in the view. Each
member appears with its corresponding metadata, as well as status
information and icons for some of the commands that may be
performed on that member.
52 Source Integrity Professional Edition

The Source Integrity Web Interface
Icons that tell you about the state of a particular member appear
beside the name of the member. If you rest your pointer on an icon, a
tooltip describes the action performed by clicking that icon.
In the command area at the top of the window, commands are
grouped into two drop-down menus: commands that can be
performed on members and commands that affect the entire sandbox.
There are two other drop-down menus: a filter menu for choosing
which members are displayed, and a selection menu for selecting
subsets of the sandbox.
The hierarchical list of members lets you open and close directories,
allowing you to reduce the number of members visible at one time,
and letting you focus on the task at hand.
For each member, the following appears:
Member Name. The name of the sandbox member.
Revision. The number of the revision in the sandbox (not the
member revision in the project).
Locked. If the member is locked, a padlock ( ) appears with the
name of the person who placed the lock.
A selection checkbox for selecting a member before choosing a
command to act upon it.
Each member may have one or more symbols displayed in front of it,
to quickly convey the status of that member.
The Out-of-Sync delta signals that the revision in your sandbox
does not match the member revision in the project.
The Working File delta signals that the working file has been
modified from the revision in your sandbox.
The missing file symbol identifies a missing file: the file is part of
the sandbox, but is not on the client machine. To get a copy of the
file, click this symbol.
The snowflake icon indicates that the individual member or
project is frozen and therefore cannot be updated.
The Inaccessible icon indicates that the project or archive is
currently inaccessible.
Sandbox View Filters
The Sandbox view may be filtered to reduce the number of members
that are visible at any one time.
You can choose one of the following filters from the Filters dropdown
list:
User Guide 53

Introducing the Source Integrity Interfaces
Members displays all members in currently open directories and
subsandboxes in the sandbox
Locked by me displays only those members that are locked by the
user at the current sandbox revision in currently open directories
or subsandboxes.
Out of Sync Members displays only those members that are not at
member revision in currently open directories or subsandboxes.
Modified Members displays only those members that have a
working file delta in currently open directories or subsandboxes.
Not Present Members displays those members that are part of the
current project, but are not on the client machine in currently
open directories or subsandboxes.
Everything displays all files in currently open directories and
subsandboxes of the sandbox, including local files that are not
part of the project.
Non-Members displays all files in currently open directories and
subsandboxes of the sandbox that are not members of the project.
All Members recurses into any subdirectories and subsandboxes
and displays all members.
All Locked by me recurses into any subdirectories and
subsandboxes and displays all members that are locked by the
user at the current sandbox revision.
All Out of Sync Members recurses into any subdirectories and
subsandboxes and displays only those members that are not at
member revision.
All Modified Members recurses into any subdirectories and
subsandboxes and displays only those members that have a
working file delta.
All Not Present Members recurses into any subdirectories and
subsandboxes and displays those members that are part of the
current sandbox, but are not on the client machine.
Sandbox View Selections
The Selections drop-down list allows you to select multiple files that
fit a particular category, based on their status, in just one click.
Reset All deselects all files listed in the sandbox.
All Visible Members selects all files listed in the sandbox.
Out of Sync selects all members whose revision is not the same as
the revision in the project.
54 Source Integrity Professional Edition

The Source Integrity Web Interface
Modified selects all files whose working files have been modified
since the member was last checked out.
Locked by me selects all members that are locked in the current
user’s name.
Archived selects all members that have been archived.
Exists selects all members that have a working file.
Non-Member selects all members that are not members of the
sandbox, but do exist in the sandbox’s directory.
Invert Current reverses the selected and unselected files in the
current filter.
Overview of the Member View
The Member view displays detailed information about a particular
member and provides commands that act upon that member.
This view can be reached from either the Project or Sandbox view. To
open the member view for a member, select it and choose Member >
Open Member View.
A list of the revisions in the member’s archive appears, each revision
displayed with its corresponding metadata.
The following metadata is displayed:
Revision. The revision number of the archive. To view the
contents of a revision, click its revision number (for example,
“1.4”). The revision appears in its associated editor.
Locked. If the revision is locked, a padlock (
name of the person who placed the lock.
) appears with the
Author. The name of the person who checked in the revision.
Date. The date and time when the revision was checked in.
State. The current state of the revision.
Description. The description of the revision (entered upon check
in).
Labels. Any labels associated with the revision.
Each revision may have a symbol displayed next to it, to convey the
status of that revision quickly:
The Member Revision icon identifies the revision that represents
the member revision in the project. To set a different revision as
the member revision in the project, check the checkbox next to the
revision and select Set Member Revision from the list of available
commands.
User Guide 55

Introducing the Source Integrity Interfaces
The revision that is current in the user’s sandbox is highlighted
with a dark line in the view.
Overview of the Project View
The Project view focuses on the structure and status of the master
project, and ignores what is in the user’s sandbox. This view provides
some of the same features of the sandbox view, but from a more
administrative perspective.
A hierarchical list of the project members is displayed in the view.
Each member appears with its corresponding metadata, as well as
status information and icons for some of the commands that may be
performed on that member.
In the command area at the top of the window, commands are
grouped into two drop-down menus: commands that can be
performed on members and commands that affect the entire project.
There are two other drop-down menus: a filter menu for choosing
which members are displayed, and a selection menu for selecting
subsets of the project.
The hierarchical list of members lets you open and close directories,
allowing you to reduce the number of members visible at one time,
and letting you focus at the task at hand.
Each member is displayed at its member revision (the revision in the
project). Therefore, all the corresponding metadata, as well as the
member commands, relate to the member revision.
The following appears:
Member Name. The name of the project member.
Revision. The number of the revision in the project.
Locked. If the member is locked, a padlock ( ) appears with the
name of the person who placed the lock.
A selection checkbox for selecting a member before choosing a
command to act upon it
Each member may have a symbol displayed next to it, to convey the
status of that member quickly:
The Tip Revision delta signals that the member revision of this
member is not at tip revision. In other words, there is a newer
revision available along the member revision’s branch. Click this
delta to update the member to its most recent revision.
The Frozen icon indicates that the individual member or project
is frozen and therefore cannot be updated.
56 Source Integrity Professional Edition

The Source Integrity Web Interface
The Inaccessible icon indicates that the project or archive is
currently inaccessible.
Project View Filters
The Project view may be further filtered to reduce the number of
members that are visible at any one time.
You can choose one of the following filters from the drop-down list:
Members displays all members in the project in currently open
directories and subprojects.
Locked by me displays only those members that are locked by the
user at the current project revision in currently open directories
and subprojects.
Locked displays all members that are locked by anyone at the
current project revision in currently open directories and
subprojects.
New Tip Revision display all members whose archive contains a
revision number greater than the current one, but in the same
branch in currently open directories and subprojects.
Frozen Members displays only those members which are frozen
in currently open directories and subprojects.
Everything displays all files in the current project directory,
including local files that are not part of the project in currently
open directories and subprojects.
Non-Members displays all files in the current project directory
that are not members of the project in currently open directories
and subprojects.
All Members recurses into any subprojects and subdirectories and
displays all members.
All Locked by me recurses into any subprojects and subdirectories
and displays all members that are locked by the user at the
current project revision.
All Locked recurses into any subprojects and subdirectories and
displays all members that are locked by anyone at the current
project revision.
All New Tip Revision recurses into any subprojects and
subdirectories and displays all members whose archive contains
a revision number greater than the current one, but in the same
branch.
All Frozen Members recurses into any subprojects and
subdirectories and displays only those members that are frozen.
User Guide 57

Introducing the Source Integrity Interfaces
Setting the
Proxy Server
Project View Selections
You can select multiple files that fit a particular category, based on
their status, by selecting one of the following options in the Selections
drop-down list:
Reset All deselects all members listed in the project.
All selects all members listed in the project.
New Tip Revision selects all members whose archive contains a
revision number greater than the current one, but in the same
branch.
Frozen selects all members that are frozen.
Locked by me selects all members that are locked in the current
user’s name.
Archived select all members that have been archived.
Invert Current reverses the selected and unselected files in the
current filter.
Overview of the History View
The History view displays the history of all checkpoints performed
on the project. It is similar to the Member view, but with a subset of
its features.
The History view displays a list of the project revisions. Each revision
is displayed with its corresponding metadata.
The following appears:
Revision. The number of the revision in the project’s archive.
Author. The name of the person who checkpointed the project.
Date. The date and time when the project was checkpointed.
State. The current state of the revision in the project’s archive.
Description. The description of the project revision (entered when
checkpointed).
Labels. Any labels associated with the revision in the project’s
archive.
A selection checkbox for selecting a revision before choosing a
command to act upon it.
A proxy is a server that manages communication between a user and
the Internet to ensure administrative control of your website.
58 Source Integrity Professional Edition

The Source Integrity Web Interface
Proxy settings for the Source Integrity Web Interface specify how it
communicates with the Integrity server using your browser.
Note Changing your proxy settings can interrupt communication
between the Source Integrity Web Interface and the Integrity server.
Please contract your web administrator before changing your proxy
settings.
To set the proxy servers for the Source Integrity Web Interface:
1. Choose Configuration > Configuration.
The Configuration Guide page appears.
2. Click Set the proxy servers. Your current proxy setting is
displayed beside this link.
The Set Proxies page appears.
3. Set the following proxy server options:
Use Proxy Server. Select this checkbox if you are using a
proxy server to access the Integrity server. This is not the
same as an autoproxy. If you are using an autoproxy, you
need to set a manual proxy on this page.
Fully compliant to HTTP 1.0. The method of communication
between the Source Integrity Web Interface and the Integrity
server depends upon whether your proxy is fully compliant
to HTTP 1.0 protocol. If it is, then select this checkbox.
Selecting Use Proxy Server automatically selects this option.
HTTP Proxy and Port. Enter the address of your proxy server
(for example, proxy.mks.com) and the port it uses (for
example, 4040). The address does not require the http://
prefix.
Security Proxy and Port. If you use a secure proxy server,
enter the address (for example, proxys.mks.com) and the
port it uses (for example, 200). The address does not require
the https:// prefix.
Exceptions. A list, separated by commas or semi-colons, of
sites accessed without using the proxy. You can use the
asterisk (*) character to identify a group of sites (for example,
local.*:*).
4. When you are finished, click OK to accept these settings, or
Cancel to cancel them.
User Guide 59

Introducing the Source Integrity Interfaces
Setting Your Timezone Display
You can choose whether to display timestamps in Greenwich Mean
Time (GMT) or your own local server timezone. Your administrator
will set the default behavior of your installation, but you can change
this setting in both the Windows interface and the Source Integrity
Web Interface.
If your installation of the the Windows interface or Source Integrity
Web Interface is set to display times in GMT, the letter Z is appended
to the timestamp.
Note This setting does not affect date strings in log files or revision
descriptions.
To set your timezone display in the Windows interface:
1. Choose Configuration > Personal.
The Personal Configuration dialog box appears, showing the
Preferences tab.
2. To display timestamps in your server’s local timezone, select the
Use Local Timezone checkbox. To display them in GMT, leave the
checkbox empty.
3. Click OK to accept these settings, or click Cancel.
To set your timezone display in the Source Integrity Web
Interface:
1. From the Source Integrity Web Interface home page, choose
Configuration > Configuration.
The Configuration Guide page appears.
2. Click Select the default Time Zone. Your current default timezone
setting is displayed beside this link.
The Select Timezone Display Mode page appears.
3. Select one of the following options:
GMT. Displays all timestamps in Greenwich Mean Time. If
you choose this option, timestamps will be followed by the
letter Z.
60 Source Integrity Professional Edition

The Command Line Interface
Project
Commands
Versus Archive
Commands
The Command Line Interface
Local Time Zone. Displays all timestamps in the time zone of
your local server.
4. When you are finished, click OK to accept these settings, or
Cancel to cancel them.
Note In the Source Integrity Web Interface, keywords are expanded on
your server, and then copied to your client machine even though your
working files reside on your client machine. Therefore, any dates and
times will be server-relative rather than client-relative.
Source Integrity provides a complete command line interface to
manage your projects and archives. With few exceptions, the
command-line interface and Windows interface of Source Integrity
provide the same functionality.
Note The command line interface is not accessible from the Source
Integrity Web Interface.
Source Integrity’s command line interface has two types of
commands:
Project commands operate on project members or entire projects;
they automatically update project metadata when they perform
their functions.
Archive commands operate on archives only, even if the archive is a
member of a Source Integrity project.
Their main difference concerns project functionality. Project
commands provide extra project management capabilities, assistance
in the build process, and reporting information. They are the most
versatile way to manage source materials.
Archive commands are supplied mainly for legacy purposes.
Although compatible with project commands, they do not provide
project functionality. The sole exception to this allows archive
commands to examine a project file to find archives. Most archive
commands accept the -Pprojfile.pj parameter to do this.
User Guide 61

Introducing the Source Integrity Interfaces
Command-Line
Length
Path Separator
Wildcard
Expansion
While archive commands are individual executables, the project
commands are available through the pj executable. Project
commands follow the general syntax pj directive, where directive is a
Source Integrity function (ci, co, freeze, build, and others).
Which Project Will Project Commands Operate On?
If you do not specify a project when you call a pj command, it uses
the following order of precedence to determine the project it should
act on
the project named by the PROJECT environment variable
the project named by the ROOTPROJECT environment variable
a sandbox named sandbox.pj in the current working directory
a project named project.pj in the current working directory
The operating system and shell where Source Integrity commands
are run determines the allowable length of the commands.
Under the DOS command.com shell, the maximum length is 128
bytes.
Under the KornShell (provided with MKS Toolkit) the maximum
length is 8K.
On UNIX systems, the maximum length is usually greater than
16K.
If the number of files to be included in a command extends the line
past these limits, you can use a file list (explained later) or include all
the files in a project and issue commands for the entire project at
once.
The DOS, OS/2 and Windows 95/98 and NT versions of Source
Integrity understand both the DOS and UNIX path separators (that is,
the backslash and slash character, respectively). On these systems, the
following commands are both valid:
rlog c:\src\work\graphics.c
rlog c:/src/work/graphics.c
On UNIX systems, Source Integrity commands understand only the
UNIX path separator.
Under Source Integrity, the asterisk wildcard can indicate all files in a
directory, as well as zero or more characters in a filename.
62 Source Integrity Professional Edition

File Name
Arguments
For more information about
how Source Integrity resolves
wildcards in filenames, see
“Wildcard Expansion” on
page 62.
The Command Line Interface
For example, to check in all of the files in the current directory, you
can use either
pj ci *
pj ci *.*
Wildcards are allowed anywhere in a path or filename. For example,
the characters “*a*” represent any files that contain the letter “a” in
the basename or the extension.
For project commands, file refers to members of a Source Integrity
project. If the file argument is omitted for project commands, the
command is applied to all of the members of the project.
The file element must be the last entry of a command statement. There
are three ways to apply a command to multiple files.
Enter Multiple File Names
You can enter two or more filenames, separated by spaces, as the
file component. For example, the command
pj co -l prog.c brochur.toc brochur.idx
checks out all three files. You can name as many files as you like
on the command line (subject to the line length limitations of
your operating system).
Use Wildcards
Use wildcards in the file component. For example, the command
pj ci brochur.*
checks in all files with the basename brochur and any extension.
Specify a File List
A file list (specified with the -Ffilename option) is a text file
containing the names of the files a command should be applied
to. For example, the command
pj ci -Fflist.lst
checks in all the files listed in the flist.lst file.
Files named in the file element may have any level of path
qualification.
A file list is a text file containing a list of filenames, with each name on
a line by itself. When you pass a file list to Source Integrity, it reads
the filenames and applies the command to them in sequence.
User Guide 63

Introducing the Source Integrity Interfaces
You can create a file list with any text editor by entering filenames—
one name per line—in a plain text file. Alternatively, you can compile
a list of files with the find command and copy them to a text file. The
find command is a standard UNIX utility and is available on PC
systems with MKS Toolkit.
File lists can be used with project commands, as well as the ci, co,
rcs, rcsdiff, rcsclean, rlog, pvcs2rcs, sccs2rcs, and report
commands.
64 Source Integrity Professional Edition

Getting Started With
Projects, Sandboxes,
and Members
4
This chapter describes the Source Integrity features that you will use
in your day-to-day activities, and explains how to perform tasks
using the three main interfaces to Source Integrity:
Windows interface
Command line interface
Source Integrity Web Interface
For introductory information about these three interfaces, see
Chapter 3: “Introducing the Source Integrity Interfaces” on page 39.
For information about using Source Integrity in development
environments, see Chapter 7: “Using Extensions” on page 197.
User Guide 65

Getting Started With Projects, Sandboxes, and Members
Creating a Project
When you are ready to place a group of files under Source Integrity
control, the first step is to create a project. Organizing your files in a
project allows you to perform configuration management operations
on the files as a group.
You should place the project file in the topmost directory of the
source file hierarchy. Source Integrity projects work best when all
project members reside in a single directory tree under the project
directory. While members can reside anywhere on the system,
spreading projects across multiple directory trees increases the
chances that something will go wrong, since different users may map
network drives differently, and there is no guarantee that all users
will be able to access every directory on the system. Project members
which are not located in the same directory tree as the rest of the
project are called out-of-tree members.
Note The Source Integrity Web Interface does not support out-of-tree
members. If you want to use the Source Integrity Web Interface to access
a project, all of its members must be in the same directory tree.
The Windows interface provides a wizard to lead you through the
process of creating projects. You can choose to add members and
create a sandbox while you are creating the project, or choose to do it
later.
To create a project in the Windows interface:
1. Choose File > Create Project, or click .
Step 1 of the Create Project Wizard appears.
66 Source Integrity Professional Edition

2. In Step 1, enter the following options:
The Project Name (default is project.pj).
Creating a Project
The Project Location. You can type a full directory pathname,
or click Browse to find or create a directory.
Click Next.
Step 2 of the Create Project Wizard appears.
3. In Step 2, enter the names of any members you want to Add to the
project. This step is optional; you can always add members to
your project later. While adding members, you can also choose
the following options:
whether to create member archives, and whether you want
the member archives created automatically or interactively
whether to create a project archive
Note It is recommended that you create archives for all members and
the project, so that all changes to these objects can be tracked.
To create the project without creating an associated sandbox, click
Finish. To create an associated sandbox for the project, click Next.
Step 3 of the Create Project Wizard appears.
User Guide 67

Getting Started With Projects, Sandboxes, and Members
For information about the
different types of sandboxes,
see “Creating a Sandbox” on
page 76.
4. In Step 3, if you want to create an associated sandbox, click Yes.
Enter a Sandbox Name and Sandbox Location. You can type a full
directory pathname, or click Browse to find or create a directory.
You can specify any name you want for the sandbox.
5. Click Finish.
Source Integrity opens the project and displays the list of members in
a Project window.
To create a project in the Source Integrity Web Interface:
1. Choose Project > Create Project.
2. On the Create Project page, choose the drive, directory, and file
name for your project on the server file system and click OK. You
can accept the default project name project.pj.
The project is created and the Project page appears.
When you create a project using the Source Integrity Web Interface, it
is automatically registered (see “Registering a Project in the Source
Integrity Web Interface” on page 69). You cannot add members,
create archives, or create a sandbox while creating a project in the
Source Integrity Web Interface; you must perform these actions
afterward.
To create a project in the command-line interface:
Change to the directory that will be the root of the project directory
tree, and enter the command
pj create [-Pprojname]
This creates a project file with the name projname in the current
directory. If you omit the optional -P parameter, the project is given
the default name set by the PROJECT environment variable, or
project.pj if there is no PROJECT variable defined.
You cannot add members, create archives, or create a sandbox while
creating a project in the command-line interface; you must perform
these actions afterward.
68 Source Integrity Professional Edition

Registering a Project in the Source Integrity Web Interface
Registering a Project in the Source Integrity
Web Interface
Before you can use the Source Integrity Web Interface to access a
project that was created using the Source Integrity Windows interface
or command-line interface, you must register it first. Any projects
created using the Source Integrity Web Interface are automatically
registered (see “Creating a Project” on page 66).
If you create (and therefore register) a project with the Source
Integrity Web Interface, you can still use the Windows interface or
command-line interface to Source Integrity to access the project, as
long as you have file-system access to the project directory.
To register an existing project:
1. Choose Project > Register Project from the Source Integrity Web
Interface home page.
The Register Project page appears.
2. Browse the server file system to select the project file you want to
register, or enter the full path name and click OK.
Registering a Sandbox in the Source
Integrity Web Interface
Before you can use the Source Integrity Web Interface to access a
sandbox that was created using the Source Integrity Windows
interface or command-line interface, you must register it first. Any
sandbox created using the Source Integrity Web Interface are
automatically registered (see “Creating a Sandbox” on page 76).
If you create (and therefore register) a sandbox with the Source
Integrity Web Interface, you can still use the Windows interface or
command-line interface to Source Integrity to access the project, as
long as you have file-system access to the project directory.
To register an existing sandbox:
1. Choose Project > Register Sandbox from the Source Integrity Web
Interface home page.
The Register Sandbox page appears.
User Guide 69

Getting Started With Projects, Sandboxes, and Members
2. In step 1, to register a sandbox of a registered project, click the
select it link. Whether a project is selected appears to the right of
this link.
3. In step 1, if the project is not registered, click the register it link.
4. In step 2, click the specify link to locate the sandbox.
Opening a Project or Sandbox
5. In step 3, click the register the sandbox link. To close this page
without registering a sandbox, click Cancel.
To perform actions upon a member file in the Windows interface or
Source Integrity Web Interface, you must first open the project or
sandbox that it belongs to. In the command line interface, just
navigate to the project directory before issuing any commands.
To open a project or sandbox in the Windows interface:
1. Choose File > Open Project/Sandbox, or click .
The Open Project/Sandbox browser appears.
2. If the project or sandbox you want to open is not in the current
directory, navigate to the proper drive and directory.
3. Select one or more sandboxes or projects from the list and press
, or click OK.
You can also open recently accessed projects or sandboxes by
choosing their names from the list at the bottom of the File menu.
Upon installation, Source Integrity creates a Windows association
between itself and files that have the .pj extension. If you have not
changed this association, you can also open a project or sandbox by
double-clicking on the file name in Windows Explorer.
To open a project in the Source Integrity Web Interface:
1. Register the project, if it has not been registered (see “Registering
a Project in the Source Integrity Web Interface” on page 69).
2. From the Source Integrity Web Interface home page, choose the
Project > Open Project command.
The Select Project page appears.
70 Source Integrity Professional Edition

Opening the Master Project From a Sandbox
3. In the Select Project page, choose the project you want to open
from the list of registered projects and click OK.
To open a subproject, select the project from the list of registered
projects, click List Subprojects, select the subproject, and click OK.
If you have no projects currently registered, the Source Integrity Web
Interface displays an error message.
To open a sandbox in the Source Integrity Web Interface:
1. Register the sandbox, if it has not been registered (see
“Registering a Sandbox in the Source Integrity Web Interface” on
page 69).
2. From the Source Integrity Web Interface home page, choose the
Sandbox > Open Sandbox command.
The Select Sandbox page appears.
3. In the Select Sandbox page, choose the sandbox you want to open
from the list of registered sandboxes and click OK.
To open a subsandbox, select the sandbox from the list of registered
sandboxes, click List Subsandboxes, select the subsandbox, and click
OK.
If you have no sandboxes currently registered, the Source Integrity
Web Interface displays an error message.
Opening the Master Project From a Sandbox
If you are working within a sandbox in the Windows interface or
Source Integrity Web Interface, you can open the sandbox’s master
project.
To open a master project of a sandbox in the Windows interface:
With a Sandbox window active, choose Project > Open Master Project.
The master project appears in a Project window.
To open a master project of a sandbox in the Source Integrity
Web Interface:
In the Sandbox view, click Project.
The Project view of the master project appears.
User Guide 71

Getting Started With Projects, Sandboxes, and Members
Adding Members to a Project
As your body of source code grows, you will want to add members to
your existing projects. You can add members using all three
interfaces, but each interface handles the creation of member archives
differently.
In the Windows interface, you can choose to have Source Integrity
create an archive for any file that does not already have one. Archives
can be created either interactively (you will be prompted before the
archive is created) or automatically (default settings will be used).
When you add members using the Source Integrity Web Interface,
archives are always created for members that do not already have
archives.
The command-line interface does not allow you to create archives
automatically as you add members. This must be done by explicitly
checking the members in after you have added them.
To add members to a project in the Windows interface:
1. Choose Project > Add Members, or click (if you previously
added this button to the toolbar).
The Add Project Members dialog box appears.
72 Source Integrity Professional Edition

Adding Members to a Project
2. Select one or more files from the displayed file list, navigating to
the desired directory if necessary. You can add all of the files and
subdirectories in the current directory by clicking Select All.
3. Click the Create Archives option to have Source Integrity create
archives for any files that do not already have one. You may
choose to have the archives created Automatically, in which case
default settings are used, or Interactively, whereby you are
prompted before each archive is created.
4. To recursively add all files in any selected subdirectories, click
Recursive Add.
5. Press or click Add to add the new members to the project.
Note If you want to add a very large number of files (more than 10,000,
for example) from the same directory, you should navigate to the parent
directory, select the directory that contains the files, and click Recursive
Add.
To add members to a project or sandbox using Windows
Explorer:
1. Position the Source Integrity application window and the
Windows Explorer window so that they are both visible on your
Windows desktop.
2. In Windows Explorer, navigate to the appropriate directory and
select one or more files to add as members. Click and drag the
files onto a Project or Sandbox window in the Source Integrity
application window.
The files are added to the project or sandbox. Members added
through Windows Explorer do not have archives created for them
by default. To create archives for these members, check them in.
To add members to a project in the Source Integrity Web
Interface:
1. From the Project or Sandbox view, choose Filters > Everything to
display all files in the project or sandbox’s directory or Filters >
Non-Members to display just those files that are not members of
the project or sandbox.
2. In the list of files, select the files you want to add to the project,
and choose Member Commands > Add.
User Guide 73

Getting Started With Projects, Sandboxes, and Members
3. From the Add Member page, enter an Archive Description and a
Label if desired. If you are adding more than one member, you
can click OK to continue to the next member or choose Apply to
All and then click OK to apply these properties to all of the
members.
The files are added to the project as members. If they did not
already have archives, then archives are created for them.
If an archive already exists, the file being added is checked in on a
branch off of the archive’s head revision, to ensure that any
changes to that file are stored in the archive while not creating a
new revision on the trunk.
To add members to a project in the command line interface:
From the project or sandbox directory, use the pj add command. Its
syntax is
pj add [-R] [-rrev] [-ttype] [-Pprojname] [path/]filename
where path is either the absolute path to the file or the path relative to
the project or sandbox directory. Other options include the following:
-R recursively applied this operation to any directories specified
on the command line
-rrev uses rev instead of head revision as the member’s revision
-ttype overrides determination of a member’s type. A member’s
type cannot be set to archived unless the member already has an
archive.
Normally, pj add and other pj commands use the file name of the
working file, not of its archive (archives can be used, but are not
required). Source Integrity uses the project file (and its own defaults)
to locate archives. If archives exist for members you add, Source
Integrity sets the member revision to the head revision of the archive.
If archives do not exist for members you have just added, you can
create them by checking them in with the pj ci command.
74 Source Integrity Professional Edition

Removing Members From a Project
Removing Members From a Project
If a member has outlived its usefulness or just does not belong in a
project anymore, you can remove it at any time.
After you remove a member from a project, the member is no longer
listed as part of the project, but the member’s working file and
archive remains, in case you need to recreate an earlier version of the
project.
To remove a member in the Windows interface:
1. In a Project or Sandbox window, select one or more members to
remove from the project.
2. Choose Project > Remove Members, or click .
A message box appears asking you to confirm the deletions.
3. To remove the selected member(s), click Yes or Yes to All.
The members are removed from the project.
To close the dialog box without removing any members, click No
or No to All.
To remove a member in the Source Integrity Web Interface:
1. In the Project or Sandbox view, choose the member(s) you want
to remove, and choose Member Commands > Drop.
You are asked for confirmation.
2. Click Yes.
To remove a member in the command line interface:
From the project directory, use the pj drop command. Its syntax is
pj drop [-R] [options] file…
where -R recursively applies this operation to any directories
specified on the command line. The command line interface does not
ask for confirmation.
User Guide 75

Getting Started With Projects, Sandboxes, and Members
Creating a Sandbox
For more information, see
“Freezing Members” on
page 106.
When you want to work in your own workspace without interfering
with the work of others, you create a sandbox of the project you are
working in.
If you create a sandbox of a project that contains frozen subproject
members, the members that populate your sandbox correspond to
the member revisions in the checkpointed frozen revision of the
subproject.
While you can create a sandbox when you create a new project in the
Windows interface, most users will create their own sandboxes to
access the contents of existing projects. The Windows interface
provides a wizard to lead you through the process of creating a
sandbox.
To create a sandbox in the Windows interface:
1. Choose File > Create Sandbox, or click .
The Step 1 panel of the Create Sandbox Wizard appears.
2. In Step 1, enter the fully qualified name of the Master Project, or
click Browse to locate it. If you have a project currently open, that
project will be the default. Click Next.
The Step 2 panel of the Create Sandbox Wizard appears.
76 Source Integrity Professional Edition

For more information, see
“Build Sandboxes” on
page 25.
Creating a Sandbox
3. In the Step 2 panel, enter the Sandbox Name (default is
sandbox.pj), and enter or Browse for the Sandbox Location. If
you want to have working copies of the project’s members copied
to the sandbox workspace, select the Copy Members to Sandbox
option. If this option is not selected, the sandbox is created, but
working copies of member files must then be copied or checked
out to the sandbox workspace. Click Next.
The Step 3 panel of the Create Sandbox Wizard appears.
4. In the Step 3 panel, select the type of sandbox you want to create:
Normal Sandbox, one that is based upon the most recent or
head revision of the project. Click Finish.
Variant Sandbox, one that is based upon a specific revision of
the master project and is used for branching off of the main
development path. Click Next.
The Step 4 panel of the Create Sandbox Wizard appears,
allowing you to select an Existing Development Path by
specifying the Development Path Name; or a New Development
Path by selecting By Revision or By Label and entering a new
Development Path Name.
Build Sandbox, a static sandbox that is based upon a specific
revision of the master project, but is used for building or
testing the project, not for further development. Click Next.
User Guide 77

Getting Started With Projects, Sandboxes, and Members
The Step 4 panel of the Create Sandbox Wizard appears.
Select a project By Revision or By Label. Click Finish.
The wizard dialog box closes, and a Sandbox window appears
displaying the contents of the new sandbox.
If the Create Sandbox option is set in the Recursion panel of the
Personal Configuration dialog box, this command recursively creates
sandboxes for subprojects that are members of the project (or
members of subprojects) a sandbox is being created for. If this option
is not enabled, Source Integrity prompts you to recurse for each
subproject encountered in the master project.
To create a sandbox in the Source Integrity Web Interface:
1. Choose Sandbox > Create Sandbox.
The Create Sandbox Guide appears.
2. To create a sandbox from a registered project, click the select it
link. On the Create Sandbox - Select Project page, select the
desired project (click List Subprojects if you want to select a
subproject), and click OK.
If the desired project is not registered on the server, click the
register it link. On the Create Sandbox - Register Project page,
browse to the location of the desired project, select it, and click
OK.
3. On the Create Sandbox Guide page, click the link to select (or
create) the directory where you want to locate the sandbox. On
the Create Sandbox - Locate Sandbox Directory page, type the
path of the desired directory on your local client file system, or
click Browse to locate a path, and click OK. In the Source Integrity
Web Interface, the name of the sandbox file must be the same as
that of the project (for example, project.pj).
4. To choose whether or not to copy the project members to your
local sandbox, click the Choose a populate sandbox option link.
The current setting is displayed beside the link.
5. When you are finished setting options, click the create the
sandbox link.
The Source Integrity Web Interface then displays the Sandbox
view of your new sandbox.
You cannot create a variant or build sandbox through the Source
Integrity Web Interface.
78 Source Integrity Professional Edition

Creating a Sandbox
To create a sandbox in the command line interface:
Use the pj sandbox command. Its syntax is
pj sandbox [-Ssbxname] -Pprojname
where sbxname is the name of the new sandbox file (must be either
fully qualified or relative to the current directory), and projname is the
fully qualified file name of the master project.
The -S argument is usually omitted in favor of the default file name
sandbox.pj, as long as you are in the directory where you want to
create the sandbox. Naming your sandboxes sandbox.pj or
project.pj relieves you from using the -Psbxname argument in pj
commands.
By default, Source Integrity copies the project member files into the
sandbox directory. If a project member is archived, Source Integrity
copies the revision of the member listed in the project. If the sandbox
directory tree already contains writable copies of project members,
they are not overwritten.
To create a variant sandbox in the command line interface:
Use the pj sandbox command with the syntax
pj sandbox [-krev] -Npathname [-Ssbxname] [-Pprojname]
where
The -krev option specifies which revision of an archived project
you want to use as the starting point for your new development
path. A development path is a named diversion from the main
evolution of the project. The -krev option automatically
creates a sandbox for a specific revision of the project
rebuilds a sandbox copy of the master project’s directory tree
as it existed when the project was checkpointed
populates the sandbox directory tree with copies of the
appropriate revisions of project members
The -Npathname option takes a development path name
parameter. It uses the revision named with -krev as a starting
point, and changes to variant sandboxes based on this path do
not influence the main project (or sandboxes based on it).
Other users can join an existing development path by issuing
pj sandbox with only the -Npathname parameter, not the -krev
option.
User Guide 79

Getting Started With Projects, Sandboxes, and Members
After creating a new variant sandbox, you should checkpoint the
master project recursively by changing to the master project directory
and issuing the pj checkpoint command
pj -Pprojname -i checkpoint
This step preserves Source Integrity’s record of the variant sandbox.
For example, suppose you are currently working on Release 2 of a
project; six months ago you finished Release 1, which you
checkpointed and labeled as “Release_1”. Now, a change request has
come in from a user of the Release_1 product and you have to go back
and work on the earlier version.
You create a sandbox just as you would any other, but you use the
-krev option to specify the starting revision of the project, and the
-Ndevname option to specify a development path name that others
may use to follow the same path. For example, to recreate the revision
of the gamble project that was labeled Release_1, enter
pj sandbox -Pp:\gamble\project.pj -N postrm -k
Release_1
This creates a variant sandbox named sandbox.pj in the current
directory that points to the Release_1 revision of the gamble project. It
also creates a new development path, postrm that others can use to
work on the same new direction of development.
To preserve the record of the development path, issue the
pj checkpoint command from the project directory. This checkpoints
the master project, so that all its development paths can be recreated
if necessary.
You can now check out files and make changes in the variant sandbox
of the gamble project.
If others want to participate in the same divergent development, they
can create their own variant sandboxes by specifying the
development path name, without giving a revision.
pj sandbox -Pp:\gamble\project.pj -N postrm
To create a build sandbox in the command line interface:
Use the pj sandbox command with the syntax
pj sandbox -krev [-Ssbxname] [-Pprojname]
where -krev option allows you to specify which revision of an
archived project you want to recreate. It automatically
creates a sandbox for a specific revision of the project
80 Source Integrity Professional Edition

For more information about
build sandboxes, see “Build
Sandboxes” on page 25.
Checking Out a Member
rebuilds a sandbox copy of the master project’s directory tree as it
existed when the project was checkpointed
populates the sandbox directory tree with copies of the
appropriate revisions of project members
Note that you do not specify a development path name when
creating a build sandbox.
To create “Sparse Sandboxes” in the command line interface:
When a sandbox is sparse, only those project members that you check out
are actually copied to the sandbox. This can minimize your local
storage requirements when working with large projects.
You can include a policy option Sparse in SAM to cause Source
Integrity to make sparse sandboxes by default. If the Sparse option is
present in SAM, Source Integrity does not automatically copy project
members to your sandbox when it is created or refreshed.
The pj sandbox command then creates only the sandbox file and a
member usage file.
If SPARSE is not set as the default, you can still create a sparse
sandbox with the command
pj sandbox -Vsparse …
Checking Out a Member
Before you can make changes to a member, you must first check it out
of its archive. When you check out a revision, it is copied to a
working file where you can view or modify its contents.
To check out a project member or revision in the Windows
interface:
1. To check out a project member, select one or more members in a
Sandbox or Project window and choose Member > Check Out, or
click .
To check out from an archive, select a revision in the Archive
window and choose Archive > Check Out, or click .
The Check Out dialog box appears.
User Guide 81

Getting Started With Projects, Sandboxes, and Members
2. Fill in or modify the check-out options, and click OK to check out
the revision or member(s). To cancel the check out without
checking out any files, click Cancel to stop the check out of a
single file, or Cancel All to stop all remaining check out
operations.
Note To be able to perform check-out operations without the Check Out
dialog box appearing, deselect the Show Dialog setting on the Checkout
tab of the Personal Configuation dialog box. If you do this, Source
Integrity will use the settings in your personal configuration, combined
with default settings, when checking out files.
Check-Out Options
You can specify a number of options upon check out, including:
Working File. The fully qualified name of the working file the
revision will be checked out to.
If you use the Locked (for editing) option (following), you cannot
set the name and location of the working file because its existing
location is used to establish a link between the archive and its
working file. If a writable file with the selected file name already
exists, you are asked to confirm that it should be overwritten.
If a revision is checked out unlocked from an archive with a strict
locking policy, Source Integrity does not allow you to check it back
in as a new revision.
Selection of which revision of the member to check out.
Default Rev. Checks out the tip revision of the default branch,
usually the head revision.
82 Source Integrity Professional Edition

Checking Out a Member
Member Rev. Checks out the member revision, that is, the
revision shown in the Sandbox or Project window (this is the
default). This option is not available if you are checking out a
revision from an Archive window that is not project aware.
Revision. Checks out the revision with the specified revision
number.
Label. Checks out the revision with the specified label.
Locked (for editing). Checks out a writable working file, and
ensures no one else can make changes to the revision while you
have it checked out by locking it in your name. If strict locking is
enabled, you must check out a revision locked if you want to
make changes to it. When a revision is checked out locked, the
Working File field cannot be changed.
Restore Timestamp. Sets the timestamp of the working file to the
date and time of the revision in the archive. Otherwise, the
working file’s timestamp is set to the current date and time.
Create Branch. Creates a duplicate revision (that is, creates a
branch in the archive) and checks it out. Note that if Update
Member is not set as well, the working file and member revision
will not match.
All Files. When checking out more than one member, this applies
the current set of options to all subsequent check-out operations.
This option is disabled if only one member is selected.
Expand Keywords. Replaces keywords in the revision with literal
values in the working file. This option is disabled if the revision
contains binary data.
Update Member. When checking out from a project or sandbox,
this causes the revision you check out to become the new member
revision in the project. For example, if the current project member
is listed as Revision 2.3 and you check out Revision 1.7 using this
option, Revision 1.7 replaces Revision 2.3 as the member of the
project.
To check out a member in the Source Integrity Web Interface:
1. Click the Sandbox view tab to see the contents of your sandbox.
User Guide 83

Getting Started With Projects, Sandboxes, and Members
2. Select the member(s) you want to check out, and choose Member
Commands > Check Out Locked.
The Web Interface locks the sandbox member in your name and
copies the content of the revision into a writable working file.
If the Check Out page informs you that the working file has been
changed, you can click Yes to overwrite the working file, or click
Show Differences to view the differences between the working
file and the revision you are checking out.
To check out a member in the command line interface:
Use the pj co command. Its syntax is
pj co [-l] [-r rev|label] [-Pprofile.pj] [file…]
The -l option lets you check out and lock a revision for editing.
When you check out a revision locked, Source Integrity extracts a
writable copy of the revision to your working directory. While you
hold a lock on a revision, no one else can check out a writable copy of
it; this ensures that only one person at a time makes changes to a
given revision.
A revision that is checked out unlocked is copied to a read-only
working file, if a strict locking policy is in effect for the archive. In
addition, with a strict locking policy, Source Integrity only lets you
check in a file if it was first checked out locked.
When strict locking is not in effect, check-in operations are
unrestricted, provided no one else has a lock on the revision.
For example, the command
pj co -l filesys.c
checks out a writable copy of the project member filesys.c and
locks it in your name. If the revision is already locked by another
user, you can still check out a read-only copy with
pj co filesys.c
You can check out a revision by specifying its revision number or
label, using the -r option to the pj co command.
For example, the command
pj co -rworking betting.c
84 Source Integrity Professional Edition

Viewing and Editing a Member
checks out a revision with the label “working” from the betting.c
archive. If the revision is not the project’s member revision, the
following message appears:
d:\gamble\src\betting.c: checkout revision 1.1
update project revision from 1.15 to 1.1? [yn](y)
Whether you press y or n, the file is checked out. If you press y, the
project file is changed to use this as the member revision.
Viewing and Editing a Member
Using Source Integrity commands, you can open a member in your
default editor application (for example, Microsoft Windows Notepad
or MKS Toolkit’s vi editor). Whether you can edit or just view the
contents of the member depends upon whether you have read-only
or read-write access to the member. You must have a member locked
in your name to be able to edit it.
In the Windows interface, the Member menu command that is
available depends upon the type of member you have selected.
Member Menu
Command
Selected Member of Type
View Working File Archived or Non-Archived member, with a read-only
working file.
Edit Working File Archived or Non-Archived member, with a writable
working file.
Open Subproject Subproject.
User Guide 85

Getting Started With Projects, Sandboxes, and Members
The preceding commands behave differently depending on the type
of member they act upon.
Member Type Behavior
Archived Opens the member’s working file.
Non-Archived Opens the member file for a master project, or its
sandbox copy.
Subproject Opens a Project window to display the subproject’s
members (Windows interface) or displays the
subproject’s members in the Project view (Source
Integrity Web Interface).
To view a revision of a member (not the working file):
1. Choose Member > Open Member Archive to open the member’s
archive window.
2. Select the revision, and choose Archive > View Revision, or
click . When you view a revision of a member, Source
Integrity copies the revision to a read-only temporary file and
opens it for you. The temporary file is not the actual revision, but
rather a read-only copy of it.
To view or edit the working file:
Select the member in the project or sandbox window, and choose
Member > View/Edit Working File.
The working file is opened in your default editor, or in the
application associated with the file’s extension.
To set your default editor:
1. In your Personal Configuration dialog box, Preferences panel,
choose either of the two Editor options:
Use File Manager/Explorer File Associations: opens files in the
applications associated with each file’s extension. If you
choose this option, the View/Edit Working File toolbar button
will be an icon that represents the application associated with
the file that you have selected in the Project or Sandbox
window.
Editor: Enter or Browse for the editing application you would
like as your default.
86 Source Integrity Professional Edition

Checking In a Member
Starting a
Branch When
Checking In a
Member
Checking In a Member
2. When finished, click OK to accept changes, or Cancel to close the
dialog box without changing any settings.
To view a member in the Source Integrity Web Interface:
Select a member. From the Project or Sandbox view, choose Member
Commands > View.
To view a revision of a member (not the working file), select a
revision in the Member view and choose View.
To set the default editor in the Source Integrity Web Interface:
1. From the Source Integrity Web Interface home page, choose
Configuration.
The Configuration Guide appears, displaying the current default
editor setting. When Source Integrity is first installed, it is set to
use Windows Explorer file associations unless you change this
setting.
2. To change this setting, choose Select the default editor.
The Select Default Editor page appears.
3. Select the Editor setting and enter or Browse for the editor
application you want to use. Click OK.
When you are satisfied with the changes you have made to a member,
you should check in the member to preserve those changes as a new
revision in the archive. Files should be checked in on a regular basis.
Source Integrity usually places new revisions at the top of the trunk,
assigning them two-part revision numbers, such as 1.15. There are
times, however, when you do not want your work to be checked into
the trunk. You may be pursuing a line of development that will not be
included in the finished product, for instance, or you may be doing
post-release maintenance while development for the next release
continues on the trunk.
Divergent lines of development in the same archive are managed
through the use of branches. A branch is an independent revision line
that uses an existing revision as its starting point. Members of a
branch revision are identified by their revision numbers. Whereas
User Guide 87

Getting Started With Projects, Sandboxes, and Members
Assigning
Revision
Numbers
revisions on the trunk are characterized by two-part revision
numbers (for example, 1.2 or 3.5), branch revision numbers are
prefixed with the number of the revision they start from. For
example, if a branch revision is started from revision number 1.2, the
members of that branch is numbered
1.2.1.3
1.2.1.2
1.2.1.1
and so on. The first two digits of the number identify the revision
where the branch diverges from the trunk, and the last two represent
a position on the branch.
To start a branch during the check-in operation:
1. Check out a revision (other than the tip of the trunk) locked.
2. Make the desired changes to the working file.
3. Check in the working file, without specifying a new revision
number. By default, Source Integrity detects that this is a new
branch and assigns an appropriate four-part revision number. For
example, if you have checked out and locked revision 1.2, the
new revision has the number 1.2.1.1 assigned to it. In the
Windows interface, the revision number field is primed with the
appropriate number.
By default, when you check in a file, Source Integrity automatically
assigns a unique revision number to the new revision. It does this by
incrementing the current revision number by one. For example, if the
previous revision is 1.3, the new revision is assigned number 1.4.
You can choose the revision number of the changes you are checking
in, so long as your revision number
is greater than the last revision number (you cannot use
previously “skipped” revision numbers)
has no leading zeros (zeros as complete revision numbers are
acceptable)
starts a new branch based on an existing revision
If you check in a revision using an already existing revision number,
Source Integrity attempts to add one to the revision number and
check it in as that revision. If that revision already exists, Source
Integrity then chooses the next available branch number and creates a
new branch.
88 Source Integrity Professional Edition

Assigning
Revision
Descriptions
Checking In a Member
For example, if you are checking in a new revision to an archive
where the head revision is 1.7, the following numbers are valid:
1.8 (greater than head revision)—if you check in a revision as 1.7,
which already exists, Source Integrity assigns it 1.8
1.10 (greater than head revision)
1.72 (although misleading—none of the numbers between 7 and
72 may be used afterward)
2.0 is valid (zero as a revision number is valid)
1.7.1.1 is valid (if it starts a new branch)
The following numbers are invalid:
1.3, even if there was no revision 1.3 previously (Source Integrity
branches the archive and assign 1.3.x.1, where x is the first
available branch number)
1.08 (leading 0 in last portion)
02.1 (leading zero in branch number)
A revision description is a string of text that becomes a permanent part
of the archive’s metadata. It allows you to provide a record of the
changes you made and why you made them. This can be of great
value to you or other team members if it ever becomes necessary to
revise or update the file.
Once a new revision has been checked in, its revision description
cannot be changed, although you can append new information to a
revision description.
To check in a member in the Windows interface:
1. Select one or more files in the Sandbox or Project window and
choose Member > Check In, or click .
The Check In dialog box appears.
User Guide 89

Getting Started With Projects, Sandboxes, and Members
If you check in one or more members that are themselves
subprojects, the Checkpoint dialog box appears instead (see
“Checkpointing a Project” on page 136).
2. Fill in or modify the check-in options (see “Check-In Options”,
below), and click OK to check in the member as a new revision.
To cancel the check-in operation, click Cancel.
To check in a revision in the Windows interface:
1. To check in an archive’s working file, display the appropriate
Archive window and choose Archive > Check In, or click .
The Check In dialog box appears.
2. Fill in or modify the check-in options, and click OK to check in the
working file as a new revision.
To cancel the check-in operation, click Cancel.
Check-In Options
Revision Label. A unique text string that identifies the new
revision. Revision labels are usually assigned during check in,
but can be added later, for instance, using the Label command in
the Windows interface.
90 Source Integrity Professional Edition

Checking In a Member
Revision Number. If you do not specify one, Source Integrity
provides a default, usually the next revision number available in
the archive. For instance, if the file you checked out was revision
3.2 and that is the highest revision number on the trunk, Source
Integrity defaults to revision 3.3.
If you choose to override the suggested revision number, the
number you supply must be higher than the head revision
number (if you are checking into the trunk), or the tip revision
number (if you are checking into a branch). If you try to assign an
invalid number, such as 2.01 to a revision, you receive an error
message.
State. A one-word description of a new revision’s status. This
option is necessary for tracking the promotion of the member. If
promotion is turned off, the default for this value is “Exp” (for
Experimental) and can be edited. If promotion is turned on, the
default is the lowest promotion state, and the states cannot be
edited.
Author. The name of the person who made the changes to the
new revision. This field may be editable depending upon your
permissions. By default, this is set to your user name.
Locked. Checks in the working file, then immediately locks the
new revision. This allows you to update the project while
retaining control of the revision. Without this option, the working
file is checked in and your lock on it is removed.
Check In Same. Tells Source Integrity you are intentionally
checking in a file that is unchanged. In the Windows interface, if
this option is not used and no changes have been made, you are
prompted to confirm the check-in operation.
Update Member. Makes the new revision the member revision in
the project, replacing the existing member revision.
Keep Work File. Checks in the file and immediately checks it out
again. If this option is not used, the working file is automatically
deleted when it is checked in.
Replace Label. If the label you choose already exists in the
archive, this option deletes the label from the revision it is
currently attached to and applies it to the new revision. In the
Windows interface, if this option is not used and a labeling
conflict occurs, you are prompted to move the label to the new
revision.
User Guide 91

Getting Started With Projects, Sandboxes, and Members
For more information on
associating active propoals
and configuring Change
Integrity Connect, see
“Integrated Version Control”
on page 437
All Files. If you are checking in more than one file, this option
causes the current set of options to be applied to all subsequent
check-in operations. If you are checking in only one file, this
option is disabled
Active CI Issue. An active issue associated with the member. This
field is greyed out if Change Integrity Connect is not enabled.
Revision Description. A long, free-form comment about the new
revision. For example, you can enter a detailed description of
what you changed, what bug in the software the changes were
meant to correct, or instructions for the next person who will
work on the file.
To check in a member in the Source Integrity Web Interface:
Note You can not associate an issue with members in the Source
Integrity Web interface.
Use the Check In command from the Sandbox view.
1. Select the members you want to check in. Choose Locked by Me
or Modified from the Selections menu.
2. From the Member Commands menu, choose Check In.
The Check In page appears, listing the member(s) to be checked
in, and the full path of the current project or sandbox.
3. To see the changes you have made before checking them into the
archive, click Show Differences.
Source Integrity Web Interface displays the differences between
the working file you are about to check in and the revision from
which it was derived, using the Visual Difference utility.
4. Enter your metadata in the fields provided.
Revision Description. Text commenting on the content of, or
reason for, the new revision
Label. Text which can be used to identify the revision. To
move an existing label from a previous revision to the current
revision, select Replace Label.
State. A one-word description of the new revision’s status.
Author. The name of the person checking in the revision, by
default your user name.
92 Source Integrity Professional Edition

Checking In a Member
5. Select Keep Locked After Check In to keep the revision locked
after it has been checked in.
6. For multiple members, select Apply to All to apply the metadata
and selected options to all members being checked in.
7. Click OK.
To check a member into a project with the command line
interface:
Use the pj ci command. Its syntax is
pj ci [options] [-l] filename…
where options are zero or more modifying options (see the Source
Integrity Professional Edition Reference Guide or the online man pages).
By default, the pj ci command releases your lock on the member
revision, allowing other users to make changes to it. However, if you
want to maintain your lock (perhaps you intend to keep working on
the file) you can use the -l option to check it in without releasing
your lock.
pj ci -l filename
For example, to check in a member named nt\filesys.c, you would
enter
pj ci nt\filesys.c
Source Integrity displays the message:
d:\gamble\nt\filesys.c: checking in revision 1.1
revision is now 1.2
Enter log message:
(Terminated with End-of-File or ‘.’ RETURN:)
>>
This message tells you the number of the revision you had checked
out (revision 1.1), and that revision number 1.2 is being assigned to
the new revision. The >> prompt allows you to enter a revision
description for the new revision.
Enter the first line of the revision description at the >> prompt and
press . Another >> prompt is displayed. Repeat these steps to
enter as many description lines as you choose.
When you have completed the revision description, enter a single
period “.” at the >> prompt, and press .
User Guide 93

Getting Started With Projects, Sandboxes, and Members
Assigning
Labels
Assigning a
State
For more information on this
more structured use of state
settings, consult the States
configuration option and the
Promote and Demote SAM
permissions.
Assigning a
Different
Revision
Number
You can assign a label to the new revision at check-in time, using the
-Nlabel option of the pj ci command for project members. To assign a
multi-word label, enclose label in quotes.
To check in the member filesys.c and assign the label “Test
Version” to the new revision, you would enter the command
pj ci -N"Test Version" filesys.c
You can set a revision’s state at check in, using the -s state option to
the check in command.
For example, the command
pj ci -s Review prog.c
checks in the project member prog.c and assigns a state of “Review”
to the new revision. If promotion is turned on, the specified state
must be a valid state in the promotion states list.
State settings can also be used to establish and enforce promotion
policies at your site.
Normally, Source Integrity assigns the next available revision number
to the revision. If you want to assign a number that is greater than the
next available one, you can use the -rrev option, where rev is your
new revision number. If you want to create a branch at a particular
revision, then specify a revision rev that already exists.
Viewing and Editing Project and Sandbox
Information
The Windows and command line interfaces allow you to view, edit,
or delete some important pieces of information about a project or
sandbox, listed below. Those that apply only to the Windows
interface are indicated.
Project/Sandbox Name. The fully qualified name of the master
project or the sandbox.
Working Directory. By default, this is the root of the sandbox
directory tree for sandboxes, or the root of the master project’s
directory tree for projects.
Total Members. The number of members in the project or
sandbox.
94 Source Integrity Professional Edition

Viewing and Editing Project and Sandbox Information
Locked Members. The number of locked members in the project
or sandbox (Windows only).
Revision. The master project’s revision number.
SAM Database. The location of the SAM database.
Description. A free-form text description of the master project.
This information cannot be modified from a sandbox.
Attributes. The attribute settings for the master project (see
“Setting Project or Sandbox Attributes” on page 97). The master
project’s attributes cannot be changed in the Sandbox
Information dialog box, but can be overridden by duplicate
Sandbox Attributes (Windows only).
In the Project Information dialog box, you can also view and
delete any development paths associated with it (Windows only).
Note This functionality is not available in the Source Integrity Web
Interface.
To view or edit project or sandbox information in the Windows
interface:
1. With a project or sandbox window active, choose Project >
Project/Sandbox Information, or click .
If a master project is active, the Project Information dialog box
appears.
If a sandbox is active, the Sandbox Information dialog box
appears.
User Guide 95

Getting Started With Projects, Sandboxes, and Members
2. View or modify the project or sandbox information, as required.
3. In the Project Information dialog box, click Development Paths to
show or hide a selectable list of different development paths that
have been created from the current project. To delete a
development path, select one from the list and click Delete.
4. Click OK to accept any changes you have made, or click Cancel to
close the dialog box without making changes.
96 Source Integrity Professional Edition

Setting Project
or Sandbox
Attributes
For more information about
attributes, see the Source
Integrity Professional Edition
Administrator Guide.
Viewing and Editing Project and Sandbox Information
Attribute statements define local variables or set options. You can set
master project attributes that apply across an entire project, or
sandbox attributes that apply only in your workspace, sometimes
overriding project attributes. They have one of the three following
formats:
variable
variable=value
WorkToArch variable=value
For example, the WorkToArch project attribute, which directs Source
Integrity to the correct files, uses the following format:
WorkToArch c:/test=c:/archives/test
To view project and sandbox information in the command line
interface:
Use the pj header command, whose syntax is
pj header [options]
For sandboxes, the name of the sandbox file is also listed and the only
variant project information included is the name of the variant (if
any) used to create the sandbox.
Here is an example of pj header output for a project:
Directory: F:/proj_dir
User: sandy
SAM User: sandy
SAM Database: P:\mkssi\mkssam\mkssam
Author: sandy
Project: F:/proj_dir/project.pj
Working directory: F:/proj_dir
Repository: F:/proj_dir
Archive: F:/proj_dir\rcs\project.pj
Project on disk: F:/proj_dir/project.pj
Revision: 1.9
Log file: F:/proj_dir/project.trn
Number members: 24
Variant Projects available:
Name: german_version
Revision: 1.3
Project file on disk: F:/proj_dir/project.vpj/
vp0000.pj
Name: i18n_version
Revision: 1.7
User Guide 97

Getting Started With Projects, Sandboxes, and Members
Project file on disk: F:/proj_dir/project.vpj/
vp0001.pj
Change Integrity Connect - context:
Database IP Address: 1.0.3.24
CI User: sandy
Active CI Issue(s):
Identifier: Solution_45
Summary: context-sensitive help missing
To edit project and sandbox information in the command line
interface:
Use the pj set, pj unset, and pj delvariant commands.
The pj set command sets an attribute name to a value. Its syntax is
pj set name=value [options]
For example,
pj set include=.;/myinclude;/watcom/h
causes this include setting to be used when finding dependencies
with finddep and mkmf. If this command is used on a sandbox, the
sandbox attribute is set, not the project attribute
The pj unset command drops a project attribute. Its syntax is
pj unset name [options]
You can only unset one name at a time. If this command is used on a
sandbox, the sandbox attribute is dropped, not the project attribute.
The pj delvariant command deletes a development path. Its syntax
is
pj delvariant [-f] [-N devpath] [options]
where -f forces a subproject variant to be deleted (without this
option, only variants of the main project are deleted) and -N devpath
specifies the name of the development path you want to delete. If you
issue this command from a variant sandbox, the -N option is not
required; the variant sandbox’s development path is used.
98 Source Integrity Professional Edition

Comparing the Working File to Its Member Revision
Comparing the Working File to Its Member
Revision
After you have made changes to a member’s working file, you will
usually check those changes back into the member’s archive as a new
revision. But you may also decide that those changes should be
discarded. Before you make this decision, you have to be able to view
the changes that you will be checking in, or those that you will be
discarding if you choose.
If you are using the Windows interface or Source Integrity Web
Interface, use the Source Integrity Visual Difference utility to view the
differences between the working file and a member revision, or
between any two files.
To compare a working file to its member revision in the Windows
interface:
1. Select a member that has a modified working file (indicated by
the working file delta).
2. Choose Member > Differences.
The Visual Difference utility launches and displays the two files
side-by-side, highlighting the differences between them or
informing you that there are no differences between the files.
To compare a working file to its member revision in the Source
Integrity Web Interface:
1. In the Sandbox view, select a member that has a modified
working file (indicated by the working file delta).
2. Choose Member Command > Differences.
The Visual Difference utility launches and displays the two files
side-by-side, highlighting the differences between them or
informing you that there are no differences between the files.
When checking in the working file, you can compare it to its member
revision by clicking Show Differences in the Check In page.
To compare a working file to its member revision in the
command line interface:
Use the pj diff command to see a text-based listing of the differences
between the files.
User Guide 99

Getting Started With Projects, Sandboxes, and Members
Discarding Changes to Working Files
If you are sure you do not want to check in the modified working file,
you can discard it, update the working file with the member revision,
and unlock the member.
To discard changes to a member in the Windows interface:
1. Select one or more members in a Sandbox or Project window that
are locked in your name and choose Member > Undo Checkout.
A confirmation dialog box appears, warning you that any
changes to working files will be lost if you proceed.
2. To proceed with the Undo Checkout for a single file, click Yes (for
multiple files select Yes to All). Otherwise, click No (or No to All
for multiple files).
Click Cancel to abort all remaining Undo Checkout operations.
To discard changes to a member in the Source Integrity Web
Interface:
1. Click the working file delta beside the member or select the
member and choose Member Commands > Revert.
The Revert Member confirmation dialog box appears.
2. To see the changes you will lose if you revert the member, click
Show Differences to invoke the Visual Difference utility.
3. Once you are done comparing the files in the Visual Difference
utility, choose File > Exit to return to the Revert Working File
confirmation dialog box.
4. Click Yes to abandon the changes you have made since you
checked out the file. Otherwise, click No to cancel the operation.
To discard changes to a member in the command line interface:
1. Use the pj unlock command, which unlocks the specified
member. Its syntax is
pj unlock member
100 Source Integrity Professional Edition

Locking a Member
Locking a Member
2. Then use the pj refresh command to refresh the working file of
the specified member, with the following syntax
pj refresh -f member
where -f overwrites the working file even if it is writable. If -f is
not specified, writable files are not overwritten.
When you want to prevent others from changing a member revision
that you are working on, you can lock the member. Normally you
lock a member by using an option while checking the member out of
its project. Sometimes, however, you may have made changes to a
working file that was not checked out in your name first. In this case,
you can set a lock without overriding your changes.
In both the Windows interface and the Source Integrity Web Interface,
a locked member is denoted with a padlock symbol ( ), along with
the locker’s name and the time the member was locked.
Caution Locking a member does not affect the working file in any way.
Source Integrity does not make the working file writable if it was readonly,
and does not verify that it corresponds to the revision being locked.
Make sure that the working file corresponds to the revision that you
want to lock.
To lock a member in the Windows interface:
1. Select one or more members in a Sandbox or Project window.
2. Choose Member > Lock or click (if added to the toolbar)
A padlock symbol ( ) appears next to the revision number to
inform you the member has been locked.
To lock a member in the Source Integrity Web Interface:
1. Select one or more members in the Sandbox view.
2. Choose Member Commands > Lock.
A padlock symbol ( ) appears next to the revision number to
inform you the member has been locked.
User Guide 101

Getting Started With Projects, Sandboxes, and Members
Unlocking a Member
To lock a member in the command line interface:
Use the pj lock command. Its syntax is
pj lock [-hR] [-r rev] [options] [file…]
with the following options:
-h locks the head revision
-r rev locks the revision rev
-R recursively applies this operation to any directories specified
on the command line
If no files (file…) are specified, this command applies to all project
files with an associated archive. The -rrev and -h options do not
update the project setting for the member revision.
When you no longer need the exclusive ability to change a member,
you can unlock it again. This is normally done by default when you
check the member into its archive. You can unlock a member without
checking it in, but your changes will not be recorded if you choose to
do so.
Depending upon what permissions your administrator has defined,
you may be able to unlock a revision that is locked by another user.
Some environments will be set up to require that you send an
electronic message to the person whose lock you are “breaking”. You
should be cautious about breaking locks, since it can result in
confusion and duplication of effort in shared working environments.
To unlock in a member in the Windows interface:
1. Select one or more locked members in a Sandbox or Project
window.
2. Choose Member > Unlock, or click (if added to the toolbar).
The revision is unlocked and the padlock symbol (
removed.
) is
To unlock a member in the Source Integrity Web Interface:
1. Select one or more members in the Project or Sandbox view.
102 Source Integrity Professional Edition

Removing Unused Locks
2. Choose Member Commands > Unlock.
The revision is unlocked and the padlock symbol ( ) is removed.
To unlock a member in the command line interface:
Use the pj unlock command. Its syntax is
pj unlock [-hR] [-r rev] [options] [file…]
with the following options:
-h unlocks the head revision
-r rev unlocks the revision rev
Removing Unused Locks
-R recursively applies this operation to any directories specified
on the command line
If no files are specified, this command applies to all project files with
an associated archive. The -rrev and -h options do not update the
project setting for the member revision.
If you want to remove all locks you are holding for files you have not
modified in a project, you can do so in the Windows interface with
the Member > Remove Unused Locks command. Invoking this
command causes Source Integrity to compare all members you have
locked to their working files and unlock the ones you have not
changed.
To remove unused locks in the Windows interface:
Choose Member > Remove Unused Locks.
If the Remove Unused Locks option is set in the Recursion panel of the
Personal Configuration dialog box, this command recursively
removes unused locks in archives of any subprojects that are
members of the project (or members of members) the command is
run on.
User Guide 103

Getting Started With Projects, Sandboxes, and Members
To remove unused locks in the command line interface:
Use the pj clean command with the -u option. Use the -R option as
well to apply this command recursively through subprojects.
Note This command is not available in the Source Integrity Web
Interface.
Detecting Sandbox Members Out of Sync
With the Project
When many users are working from sandboxes based on the same
master project, it is common for the members in an individual
sandbox to become out of sync with the member revisions in the
master project. For example, the member revision of a particular file
may be at 1.5, while you still have revision 1.2 in your sandbox.
When this happens, a delta symbol ( ) appears next to the member
in the Windows interface and Source Integrity Web Interface,
signaling its status. In the command line interface, you can use the pj
what command to display changes to files and archives.
Resynchronizing Your Project or Sandbox
To resynchronize members of a project or sandbox in the
Windows interface:
Select one or more members, and choose Member > Resynchronize.
This command has no effect on working files that are identical to the
member file or revision.
If the Resynchronize option is set in the Recursion panel of the
Personal Configuration dialog box, this command recursively
resynchronizes subprojects that are members of the project (or
members of members) the command is run on.
104 Source Integrity Professional Edition

Resynchronizing Your Project or Sandbox
To resynchronize members of a project or sandbox in the Source
Integrity Web Interface:
Click the delta symbol, or select the member and choose the Member
Commands > Resynchronize command from the Sandbox view to get
the latest revision of the member.
The member in your sandbox is automatically updated to the most
recent revision in the member’s archive.
If the working file is writable, you are asked for confirmation before it
is replaced.
To resynchronize members of a project or sandbox in the
command line interface:
Use the pj refresh command from the project or sandbox directory.
Its syntax is
pj refresh file…
If no files are specified, then this command acts upon all members of
the project. The pj refresh command compares sandbox working
files with the current content of the master project members and
checks out a new copy if either of the following is true:
The sandbox member is read-only and it differs from the project
member (Source Integrity leaves files read-only when you have
no lock on them, to prevent making casual, uncontrolled
changes).
There is no copy of a project member in the sandbox directory
tree.
The pj refresh command does not replace a writable file in the
sandbox directory tree (unless you specify the -f (force) option), so
your work in progress cannot be overwritten. In addition, if a file is
identical to its master project counterpart, no action is taken; this
ensures your next build does not have to do more work than
required.
User Guide 105

Getting Started With Projects, Sandboxes, and Members
Freezing Members
When your development team has largely finished some portion of a
project and some project members are in a stable state, you can freeze
individual members within a project. Freezing restricts member
information from being updated, preventing these members from
being changed by accident. For example, if new revisions are checked
into the member’s archive, Source Integrity does not update the
project’s member revision.
Freezing prevents Source Integrity from changing member
information in the member’s project file, but does not affect a
member file itself. Revisions can still be checked out, modified, and
checked in.
You can change the label or state of frozen members, but not their
attributes.
Freezing can be used immediately before a checkpoint operation to
ensure that no one changes the project or its members before the
checkpoint is complete.
When you open a frozen subproject member, you get the
checkpointed revision, if it is an archived subproject.
When you want to allow project members to be changed, you can
thaw them (see “Thawing Members” on page 107).
Source Integrity reports the availability of new revisions when
anyone checks them into the archive. Source Integrity does not
update the project to the latest revision, so an appropriate person
must make the decision to lift the freeze and update the project.
To freeze a member in the Windows interface:
In an active Project or Sandbox window, select the archived
member(s) you want to freeze and choose Member > Freeze, or
click (if added to the toolbar).
A snowflake symbol ( ) appears beside each selected archived
member in the window.
To make this command act recursively in all subprojects of the
specified member, make sure the Freeze Members option is selected in
the Recursion panel of the Personal Configuration dialog box.
106 Source Integrity Professional Edition

Thawing Members
Thawing Members
To freeze a member in the Source Integrity Web Interface:
In the Project View, select the member you want to freeze and choose
Member > Freeze.
A snowflake symbol ( ) appears beside each selected archived
member in the window.
To freeze a member in the command line interface:
Use the pj freeze command in the project directory. Its syntax is
pj freeze [-mi] filename [-Pproject_file.pj]
where -m alone causes the freeze to be applied to members, but not
subprojects; -i causes the freeze to be applied recursively to
subprojects; and -Pproject_file.pj specifies a project file name if your
project file is not called project.pj. To recursively freeze all
members of all subprojects, use -m and -i together.
Use pj print to confirm the freeze.
When you have decided to allow project members to evolve again,
you can thaw any frozen ones. Thawing removes the restriction on
changing member information in the project.
To thaw a member in the Windows interface:
In an active Project or Sandbox window, select the archived
member(s) you want to thaw (members that have the snowflake
symbol ( ) beside them) and choose Member > Thaw, or click (if
added to the toolbar).
The snowflake symbol beside the selected members disappears.
To thaw a member in the Source Integrity Web Interface:
In the Project view, select the member you want to thaw and choose
Member > Thaw.
The snowflake symbol beside the selected members disappears.
User Guide 107

Getting Started With Projects, Sandboxes, and Members
Viewing Member Information
(Windows Only)
To thaw a member in the command line interface.
Use the pj thaw command in the project directory. Its syntax is
pj thaw [-mi] [-Pproject_file.pj] [files…]
where -m alone causes the freeze to be applied to members, but not
subprojects; -i causes the freeze to be applied recursively to
subprojects; and -Pproject_file.pj specifies a project file name if your
project file is not called project.pj. To recursively freeze all
members of all subprojects, use -m and -i together.
Use pj print to confirm that Source Integrity removed the freeze.
Note Thawing a project does not automatically update the project file to
later revisions of frozen members. Use pj update -h to do this.
Source Integrity maintains a range of information on each member.
Member. The fully qualified name of the member’s working file
in the project.
Working File. The fully qualified name of the member’s working
file.
Archive File. The fully qualified name of the member’s archive.
Date. The timestamp of the member’s revision as stored in its
archive.
Author. The name of the person who created the member’s
revision.
Locker. If the member is locked, the name of the person who
holds the lock, as well as the date and time he or she locked the
member.
Type. The member’s type. This may be Archived ( ), Non-
Archived ( ), or Subproject ( ).
Revision. The revision number of the member.
State. The state assigned to the member.
Label. Any labels associated with the member’s revision.
108 Source Integrity Professional Edition

Viewing and
Editing Member
Attributes
Viewing Member Information (Windows Only)
Revision Description. A description of the reason for or purpose
of the revision, especially useful in multi-user environments.
Active CI Issue. An active issue associated with the member.
Active issues appear as hyperlinks with a brief description. To
view the complete issue in the Change Integrity Web Interface,
click on the hyperlink.
To view member information in the Windows interface:
1. Select the member whose information you want to see.
2. Choose Member > Member Information, or click .
The Member Information dialog box appears.
3. View or make changes to the member information as required.
You cannot change an existing revision description from this
dialog box, but you can append additional comments to it. To do
so, click Advanced, select the Append Revision Description tab,
and enter any supplemental information in the edit box.
Within the Member Information dialog box, you can also add or
remove member attributes that allow you categorize members,
groups of members, or projects and then perform an operation on
them as a group.
For example, you could use the Select Members command to
highlight only those members with the attribute “SYS=DOS” and then
check them out as a group.
User Guide 109

Getting Started With Projects, Sandboxes, and Members
For more information on
attributes, see the Source
Integrity Professional Edition
Administrator Guide.
Attributes can be added, deleted, or edited using the Variable and
Value fields.
To view or edit member attributes:
1. In the Member Information dialog box, click Advanced to display
the member attributes.
You can add, delete, or edit attributes using the following fields:
Variable. When you select a member attribute in the
Attributes list, the variable portion of the attribute is
displayed in this field. The variable portion of the statement
names the attribute. It must start with a letter or underscore,
and may be followed by up to 30 letters, digits, or
underscores. You edit the variable portion of the attribute by
making changes here and clicking Add to update the entry in
the Attributes list. To delete the selected attribute, click Delete.
Value. When you select a member attribute in the Attributes
list, the value portion of the attribute is displayed in this
field. The value part may contain only printable ASCII
characters. You edit the value portion of the attribute by
making changes here and clicking Add to update the entry in
the Attributes list. To delete the selected attribute, click Delete.
Attribute list. A selectable list of attributes for the current
member. Attributes can be added, deleted, or edited using
the Variable and Value fields. Every project member can have
any number of Attribute statements which define variables
for the member. Attributes have the format
variable
or
variable=value
2. When you are finished with attributes, click OK to accept the
changes, or Cancel to close the dialog box without making any
changes.
Promoting and Demoting a Member
At particular milestones, project members will be ready to move to
the next stage of their development cycle (for example, from
“Development” to “Testing”). As long as promotion is enabled and
110 Source Integrity Professional Edition

Promoting and Demoting a Member
you have the appropriate SAM permissions, you can promote a
member to a predefined higher state, or demote it back to a lower
state.
If no state is assigned to a revision at check-in, a default value of
“Exp” (for Experimental) is used.
To promote a member in the Windows interface:
1. Select one or more members in a Sandbox or Project window.
2. Choose Member > Promote.
The Promote Member dialog box appears.
3. Select a new promotion state from the Promote to state dropdown
list.
4. Click OK to accept the new promotion state, or click Cancel to
close the dialog box without changing the member’s state.
If the Member > Promote command is not available, make sure the
promotion feature is enabled on the Promotion tab of the Personal
Configuration dialog box.
If the Promote and Demote Member option is set in the Recursion
panel of the Personal Configuration dialog box, this command
recursively promotes the members of any subprojects that are
themselves members of the project (or members of members) the
command is run on.
To demote a member in the Windows interface:
1. Select one or more members in a Sandbox window or Project
window
2. Choose Member > Demote.
The Demote Member dialog box appears.
User Guide 111

Getting Started With Projects, Sandboxes, and Members
3. Select a new promotion state from the Demote to state drop-down
list.
4. Click OK to accept the new promotion state, or click Cancel to
close the dialog box without changing the member’s state.
To promote or demote a member in the Source Integrity Web
Interface:
Use the Promote and Demote commands from the Member view. If
promotion is turned off in the Source Integrity Web Interface, a Set
State command appears instead of Promote and Demote.
To promote or demote a member in the command line interface:
Use the pj state command. Its syntax is
pj state [-hR] [-r rev] [options] state [file…]
where state is the new state you would like to change to. If no files are
specified, pj state changes the state of all archived project members
to state, subject to any restrictions imposed by the current promotion
scheme in effect.
-h assigns the state to the head revision of file, not the project’s
member revision
-r rev assigns the state to the given rev
-R recursively applies this operation to any directories specified
on the command line
Note The -rrev and -h options do not update the project setting for the
member revision.
112 Source Integrity Professional Edition

Updating to Head Rev
Updating to Head Rev
Within the Windows interface, you can use the Update Member option
when you are checking in to ensure that the most recent revision of
each member is added to the list of members in the project.
If this option is not set, or if you are using the command line
interface, the project list might not reflect the most current revision of
each member’s archive. For instance, if someone checks in a new
revision directly to a member’s archive instead of its project, the
project list is not updated.
For example, if the current project member is revision 2.7 of an
archived file, but a newer revision (revision 2.8) has been added to
the member’s archive, you can update the member to the head
revision.
If the default branch in a member archive is set to a branch off of the
trunk, updating to head revision updates to the tip revision of the
branch rather than the trunk.
To update to head revision in the Windows interface:
Choose Member > Update to Head Rev.
To update to head revision in the Source Integrity Web Interface:
If there is a newer revision available to the project, a delta appears
beside the member name in the Project view. To update the project
with the newer revision, click this delta or select the member in the
Project view and choose Member Commands > Update to Tip Revision.
To update to head revision in the command line interface:
Use the pj update command with the -h option.
Note Updating to the tip revision does not affect the member’s working
file. To update the working file, use the Windows interface’s Member >
Resynchronize command or the Source Integrity Web Interface’s Member
Commands > Resynchronize command from the Sandbox view.
User Guide 113

Getting Started With Projects, Sandboxes, and Members
Updating to Tip Revision
When you check out a revision of a file that is not the head of the
trunk, and then make changes to it and check it back in, Source
Integrity requires that you make a branch in the archive.
For example, a project member, myfile.c, is currently at revision
1.10. If you check out, revise, and check back in revision 1.8 of
myfile.c, Source Integrity defaults to revision number 1.8.1.1. The
first digits (1.8) represent the early revision that the changes are based
on. “1.8.1.1” identifies the first revision on the first branch starting at
“1.8”. Later revisions become 1.8.1.2, 1.8.1.3, and 1.8.1.4.
Updating to tip revision sets the member revision to the latest
revision along the member’s current branch of development.
To update to tip revision in the Windows interface:
Choose Member > Update to Tip Rev. In the earlier example, the
project member’s revision would be updated from 1.8.1.1 to 1.8.1.4.
To update to tip revision in the Source Integrity Web Interface:
Select the member in the Project view and choose Member Commands
> Update to Tip Revision.
Scanning Your Project for Changes
By default in the Windows interface, Source Integrity scans each
project member to search for changes (deltas) whenever it opens a
project or sandbox. This feature can be disabled to decrease the time
required to open large projects or sandboxes. The Source Integrity
Web Interface always scans for deltas.
To disable the Scan for Changes feature in the Windows
interface:
1. Choose Configuration > Personal and select the Preferences tab.
2. Deselect the Scan Members on Open Project/Sandbox setting and
click OK.
114 Source Integrity Professional Edition

Refreshing Your View
Refreshing Your View
When this feature is disabled, Source Integrity displays a question
mark in the delta column for each unscanned member upon opening
a project or sandbox. As well, a message “Member not scanned for
changes” appears in the status bar at the bottom of the window.
To scan a project for changes manually in the Windows
interface:
If the Scan for Changes option has been disabled, choose Member >
Scan for Changes.
To scan a project for changes in the command line interface:
Use the pj what command.
The information in a Project, Sandbox, or Archive window can
become “out of sync” with the actual condition of member data. If
another user locks (or deletes) a member after you open a project, this
information is not immediately reflected in your Sandbox window.
To update your view of the currently active Project, Sandbox, or
Archive window in the Windows interface:
Choose Window > Refresh.
To update your view of projects, sandboxes, and archives in the
Source Integrity Web Interface:
Choose one of the following commands:
Project Commands > Refresh Project in the Project view
Sandbox Commands > Refresh Sandbox in the Sandbox view
Refresh in the Member or History view
User Guide 115

Getting Started With Projects, Sandboxes, and Members
Assigning Labels to Members
For more information about
changing member
information, see “Viewing
Member Information
(Windows Only)” on
page 108.
Labels are unique text that describe and refer to a revision in an
archive. Labels can be based on the product release the revision was
included in, on the content of the revision, on changes made to the
revision, or any other sort of information that would be useful in
identifying that particular revision.
Although you generally assign a label to a new revision upon check
in, there may be times when you want to add an additional label or
change the label assigned to a revision.
To set a member’s state or label in the Windows interface:
1. Select one or more archived members in a Sandbox or Project
window.
2. Choose Member > Label, or click (if added to the toolbar).
The Label Members dialog box appears.
3. Fill in or select the Label Members options.
4. Click OK to accept the new label and/or state settings, or click
Cancel to close the dialog box without modifying the settings.
You can also use the Member Information dialog box to set the
member’s label.
If the Label option is set in the Recursion panel of the Personal
Configuration dialog box, this command recursively adds labels to
subprojects that are members of the project (or members of members)
the command is run on.
To set a member’s label in the Source Integrity Web Interface:
In the Member view, select the revision you want to add a label to,
and select Add Label from the list of available commands.
116 Source Integrity Professional Edition

Deleting a Member’s Label
Deleting a Member’s Label
To set a member’s label in the command line interface:
Use the pj label command. Its syntax is
pj label label -hR -rrev filename
where -h applies the label to the head revision, -R applies the label
recursively to any directories specified, and -rrev applies the label to
revision rev.
If no filename is specified, the label is applied to all project members
with associated archives.
For example, to add the label “Complete” to revision 1.6 of the
filesys.c member, enter
pj label Complete -r 1.6 filesys.c
When the command terminates, Source Integrity displays the
message
d:\gamble\src\filesys.c: revision 1.6 given label
Complete
There may be times when you want to delete a label from a revision.
For instance, you may decide the label no longer accurately reflects
that particular revision. Also, if you have assigned the same label to a
number of members, you might want to remove them all with one
command.
To delete the label from one or more members in the Windows
interface:
1. Select one or more archived members in a Sandbox or Project
window.
2. Choose Member > Remove Label.
The Remove Label dialog box appears.
User Guide 117

Getting Started With Projects, Sandboxes, and Members
For more information about
changing member
information, see “Viewing
Member Information
(Windows Only)” on
page 108.
Building a Project
Calculating
Dependencies
3. Enter the label to remove and click OK, or click Cancel to close the
dialog box without removing the label.
You can also use the Member Information dialog box to delete a label.
To delete a member’s label in the Source Integrity Web Interface:
In the Member view, select the revision whose label you want to
remove and choose Delete Label from the list of available commands.
To delete a member’s label in the command line interface:
Use the !label option to the pj label command.
For example, to delete the working label from the betting.c
member, enter
pj label !working betting.c
Since each label is unique, you do not need to specify the revision
number.
Along with configuration management and source code control
features, Source Integrity also allows you to coordinate your build
procedure.
In the Windows interface, you can use the Member > Dependencies
and Project > Build commands to generate a list of files necessary to
compile a member and run your make file.
Note This functionality is not available in the Source Integrity Web
Interface.
The first step in building a project is determining what files a given
member needs before it can be compiled.
In the Windows interface, the Member > Dependencies command
recursively scans a project member for #include statements and
generates a list of files necessary to compile the member. It searches
the following types of files for #include statements:
118 Source Integrity Professional Edition

C and C++ files
Pascal files
Fortran files
Microsoft RC files
Building a Project
Assembler files
You can add the resulting list of files to an existing make file with the
Project > Build command.
To calculate a member’s dependencies:
1. Select the member in a Sandbox or Project window.
2. Choose Member > Dependencies.
The Member Dependencies dialog box appears.
3. Fill in or modify these options:
Path. A list of directories to search in for files listed in the
member’s #include statements. This list uses the DOS PATH
format, a list of paths separated by semi-colons.
Get From Compiler File. If this option is selected, the include
path from the compiler file is used instead of the Path field;
you also choose a Compiler File Type from the dropdown
menu.
File name. The path and name of the compiler file. Enter or
browse for the name.
User Guide 119

Getting Started With Projects, Sandboxes, and Members
Using the Build
Command
(Windows)
Exclude Path. Paths that you do not want to be searched
when looking for #include files. This is useful if the include
path is taken from a compiler file and you do not want to
look in all the listed directories.
4. To recalculate the member’s dependencies, click Recalculate.
5. To check that all files in the dependency list are also members of
the project and add those that are not, click Add Missing Files.
6. When you are done, click OK to save the list of dependencies. To
close the Member Dependencies dialog box without saving the list
of dependencies, click Cancel.
To calculate dependencies in the command-line interface:
You use the pj finddep command. Its syntax is
pj finddep [-fR] [-w dir] [options] [file…]
where -f forces dependencies to be added to the project; -R
recursively applies this operation to any directories specified on the
command line; and -w dir uses the directory dir as the project
directory.
This command finds and lists the dependencies of the specified files
and prompts the user to add to the project each file used that is not a
member of the project. If no files are specified, pj finddep operates
on all project members.
If a file is found to be needed (included) and that file is not a member
of the project, you will be asked if you want to add it to the project.
Enter y to add a file to the project, n to ignore the file, or q to
terminate. Dependencies are cached in a file with the name
project.use in the sandbox or project repository directory, where
project is the file name of the project file.
To build a project:
1. Choose Project > Build, or click .
The Build Project dialog box appears.
120 Source Integrity Professional Edition

Building a Project
2. Fill in the Build options (see “Make Program Options”, “Make
File Options”, and “Dependencies Options” on page 121).
3. Click Run Make to make the project.
4. When you are ready, click OK to save the Build option settings
and close the dialog box.
To close the Build Project dialog box without saving the option
settings, click Cancel.
Make Program Options
Filename. The name of the Make program to run (for example,
c:\bin\make.exe). Enter or browse for the name.
Optional Parameters. Parameters to be passed to the Make
program. If %f is specified, Source Integrity replaces it with the
name of the makefile specified in the Filename field.
Startup Directory. The directory the Make program is run in.
Make File Options
Filename. The name of the makefile. Enter or browse for it. Click
View to view the makefile in your default text editor.
Dependencies Options
Add to Makefile. Click to add member dependencies to the
makefile.
User Guide 121

Getting Started With Projects, Sandboxes, and Members
Using pj build
Recalculate. Click to recalculate the member dependencies.
For example, consider a project containing members foo.c and
bar.c in which foo.c contains the line
#include "rcsbase.h"
If you specify that member dependencies should be added to the
makefile, the following lines are added to the makefile:
### Source Integrity generated dependencies
follow, do not remove/change this line
foo.obj : rcsbase.h
This tells the Make program to rebuild foo.obj whenever
rcsbase.h is newer than foo.obj.
Add Missing Files. Click to check that all files in the dependency
list are also members of the project. If they are not already
members, the missing files are added to the project.
Ignore Non-Members When Calculating. When this option is
selected, files that are not members of the current project are not
scanned when recalculating dependencies.
For example, suppose a project contains the files foo.c and
bar.c, and foo.c contains the line
#include "rcsbase.h"
Source Integrity normally adds rcsbase.h to the dependency list
for foo.c. However, if the Ignore Non-Members When Calculating
option is selected, rcsbase.h is not be added to the dependency
list.
Run Make. Click to run the specified Make program, using the
current Build Project options.
In the command line interface, you use the pj build command. Its
syntax is
where
pj build [-i] [-Mmakefile] [-Ttemplate] [-w dir] [options]
-i performs builds of included subprojects before building
parent (including) project.
-Mmakefile writes new makefile to file makefile. If not specified, pj
build uses project or sandbox makefile=val setting; if that
setting is not provided, filename makefile is used.
122 Source Integrity Professional Edition

Using pj mkmf
Building a Project
-Ttemplate expands the makefile template by interpreting the
template and writing it to new makefile. If not specified, pj
build uses project or sandbox MakeTemplate=val setting; if that
setting is not provided, filename make.t is used.
-w dir uses directory dir as the project directory.
In the command line interface, use the pj mkmf command to calculate
the dependencies of project members and generate a makefile before
you build your project. The generated makefile can be created from
scratch, or be based on an existing makefile or template. The
command’s syntax is
where
pj mkmf [-fR] [-Mmakefile] [-Ttemplate] [-wdir] [options]
[file…]
-f forces pj mkmf to ignore any saved information and rebuild all
dependencies before creating the new makefile.
-Mmakefile updates makefile rather than generating a new
makefile.
-Ttemplate uses template as a template to generate a new makefile.
-R recursively applies this operation to any directories specified
on the command line.
-wdir uses the directory dir as the project directory.
file … is a list of filenames of one or more project members for
which dependencies will be calculated. If file is omitted, all
project members are used.
If -Mmakefile is not specified, the value of the project attribute
makefile is used. If neither of these is defined, the makefile is written
to a file named makefile in the current directory.
When the -Ttemplate option is not used to generate a makefile, a
marker line is inserted in the makefile immediately before the
generated dependencies. The marker takes the form
### MKS SI generated dependencies follow,
do not remove/change this line
If pj mkmf encounters a marker line while updating a makefile, all
lines after the marker are replaced with the newly calculated
dependencies.
User Guide 123

Getting Started With Projects, Sandboxes, and Members
The Reporter Utility
For information on accessing
the reporting features through
the command line interface,
see “Creating Reports with the
Command Line Interface” on
page 128.
About the
Report
Information
About Graphs
In the Windows interface, the Source Integrity Reporter utility
analyzes projects, their members, or individual archives, and allows
you to generate a variety of reports and graphs based on its findings.
Reports and graphs can be printed or viewed on the screen. To use
the Reporter utility, you must have a default printer installed.
Note The Reporter is not available in the Source Integrity Web Interface.
The Reports command (from either the Project or Archive menu)
creates database tables, from which the Reporter utility generates
status and activity summaries for projects (including sandboxes) and
archives. The Reporter calculates a summary of the changes to a
project or archive, then displays or prints the summary as text or, for
some reports, as a graph. Customized reports, created using
Microsoft Access, can also be produced.
The Reporter’s data files (containing the results of its project or
archive analysis) can be saved as text files that can be read by most
database applications.
This utility generates
changes introduced by individual authors
changes between the member revision and a revision with a
particular label
changes between the member revision and any other revision
which members are locked, and by whom
which revisions have a particular label or state
project member history (including revision descriptions) by file
Whenever graphs are available in the Reporter, you are given the
option of displaying the report in a text version (the default) or as a
graph. If you display a report as a graph, you can define how you
want it to look. Using graphs, you can give reports a custom look to
suit your preferences or for quick, project-specific identification.
124 Source Integrity Professional Edition

Report Types
The Reporter Utility
The Reports command allows you to generate different types of
reports based on the information Source Integrity maintains about
project members and revisions in the archives. The Source Integrity
Reporter can generate the following report types:
Sandbox, Project, and Archive Reports
changes grouped by author
summary of changes grouped by author
list of locked revisions
list of revisions associated with labels
list of revisions associated with particular states
Sandbox and Project Reports
list of revisions newer than the member revision
changes from the member revision to a revision with a particular
label
changes from the member revision to a particular revision
number
project member history
Changes by Author
This type of report lists changes to members or revisions grouped by
the person who made them. For example, if both Fred and Ethel
made changes to several members, the report would include two
sections; one for Fred and one for Ethel. Each section of the report
shows
name of the member
revision number of changed revisions
date the change was made
number of lines (or bytes for binary files) that were added or
deleted
This type of report offers two additional options.
The report can be on a single, specified author, or all authors.
It can be restricted to changes made before or after a specified
date.
User Guide 125

Getting Started With Projects, Sandboxes, and Members
Summary of Changes by Author
This type of report shows a brief summary of changes made by each
user. Each type of project member (Text, Binary, Auto-Detect) appears
in a separate section of the report, subdivided according to the person
who made the changes. The information summarized includes
name of the member
total number of revisions changed by each person
total number of lines (or bytes for binary files) that were added or
deleted by each person
This report type offers two additional options.
The report can be on a single, specified author, or all authors.
It can be restricted to changes made before or after a specified
date.
Locked Revisions
This report lists all locked revisions in a project or archive. For each
locked revision, the report lists
name of the member
revision number
person who has it locked
Revisions with Labels
This report scans the archives of all project members and extracts any
labels they contain. For each label it finds, the report lists
name of the label
name of the member’s archive
revision number the label is associated with
Revisions with States
This report scans the archives of all project members and extracts any
state settings they contain. For each state setting it finds, the report
lists
state setting
name of the member’s archive
most recent revision with which the state is associated
126 Source Integrity Professional Edition

Revisions Newer Than Member Revision
The Reporter Utility
This report tells you which members have more recent revisions
available. For example, if a member revision is revision number 1.3,
but the archive contains revisions numbered 1.4, 1.5, and 1.6, this
report lists the newer available revisions and information about each,
including
name of the member
revision numbers of newer revisions in the archive
date of the newer revisions
revision description for each newer revision
Changes From Member Revision to Label
This report lists all revisions in a member’s archive between the
member revision and another revision with a specified label. This
report can be generated for a single member, or for all project
members. For each member, the report shows
name of the member
revision numbers of all the revisions between the member and
the labeled revision
author of each revision
date of each revision
revision description for each revision
Changes From Member Revision to Revision Number
This report lists all revisions in the member’s archive between the
member revision and another revision with a specified revision
number. This report can be generated for a single member, or for all
project members. For each member, the report shows
name of the member
revision numbers of all the revisions between the member
revision and the selected revision number
author of each revision
date of each revision
revision description for each revision
Project Member History
This report displays all the revisions of a specified project member.
For each revision, it shows
User Guide 127

Getting Started With Projects, Sandboxes, and Members
Creating
Reports with
the Command
Line Interface
revision number
revision date
revision description
When you choose the member to report on, you can specify that the
information should be sorted according to Revision Number or
Revision Date, in either ascending or descending order.
The command line interface’s report command produces commadelimited
text files with data from a wide range of queries to
sandbox, project and archive files. Its syntax is
report [options] file…
where options is zero or more command-line options, and file is the
name of one or more sandbox, project, and archive files (files are
treated as archives, unless they have a .pj extension).
To generate reports, move to the appropriate sandbox or project
directory and enter the report command. The command generates a
set of six information files for each file queried. By default, the
basename of the files is taken from the source file (that is, the
sandbox, project, or archive file being examined), and the extension
indicates the type of information in the file.
Extension Information
.txa Archive information
.txr Revision information
.txp Project information
.txm Member information
.txs Assigned labels
.txx Access information
128 Source Integrity Professional Edition

Using Keywords
Using Keywords
In the information files, fields are separated by commas, and text
within fields is delimited by double quotes. For each set of source
files, the ArchId and the ProjId fields are guaranteed to be unique,
so they can be used as keys for relational database operations.
Note If you specify an archive file instead of a project or sandbox file,
report still generates six files, although the project and member
information files are empty.
Keywords are placeholders that can be inserted into text-based
working files. Source Integrity updates them with information about
the revision or archive.
To use a keyword, simply include it in a working file, surrounded by
dollar signs (for example, $Date$) and check the file back into its
archive.
The next time you check out the revision, Source Integrity scans it for
keywords and replaces them with the appropriate information, if
keyword expansion is turned on.
For example, if the $Date$ keyword is encountered, the date and
time of the revision (assigned at check in) is added to the working file
as part of the keyword. When expanded, the entry would look
something like
$Date: 1999/06/12 10:25:32$
This method of adding or updating information in a keyword is
called keyword expansion.
Here’s another example. If the file main.c has the keywords
$Author$ and $State$ embedded within it, checking out main.c
and issuing the command
returns
ident main.c
main.c:
$author: paula_t $
$state: Exp $
User Guide 129

Getting Started With Projects, Sandboxes, and Members
Locating
Keywords
In the Windows interface, keyword expansion is turned on or off with
the KeywordExpand option in SAM or your Personal Configuration
dialog box (Checkout tab).
Note Keyword expansion applies to text files only. It is disabled for
binary files.
Text before and after the keyword is preserved, making them suitable
for use within expressions, as above, and within comments.
If keyword expansion is turned on and you are checking out a text
file that contains the string
$Revision$
Source Integrity, when it encounters this string, automatically adds
the value of the keyword $Revision$ in the format
$Revision: value $
where value is the appropriate value of the keyword (in this case, the
revision number).
For example, including the statement
char revnum[] = "$Revision$";
in a C source file creates a character string named revnum containing
the file’s revision number. The program can then be configured to
display this string when it starts up, automatically presenting the
current revision of the program’s source file.
Using the $Revision$ keyword to obtain the revision number of a
file is one of the common applications of keywords. Following are
some others.
The $Header$ keyword provides a one-line summary of useful
information associated with a revision. Including this
information in a comment makes the information available to
anyone looking at the file.
The $Log$ keyword supplies the same sort of information as
$Header$ plus the revision description. The $Log$ keyword
provides a complete list of changes that have been made to the
file over time.
You can use the ident command line interface command to locate
and display keywords (expanded or unexpanded) in one or more
files.
130 Source Integrity Professional Edition

For more information about
the ident command, see the
Source Integrity Professional
Edition Reference Guide or the
online man pages.
Removing
Keyword Values
Table of
Keywords
Using Keywords
This command displays the name of each file that contains keywords,
as well as the keywords themselves. This provides an easy way to
extract identification information from source files, as well as
compiled object files.
In the Source Integrity Web Interface, keywords are expanded on the
server before being sent to the client. Therefore, path information in
keywords will be server-side paths and date and time information
will be server-side dates and times.
In the command line interface, at check-out time, you can remove the
value portion of keywords from a revision by specifying the -K
option to the co command.
For example, if a revision in the brochur.txt archive contains a
keyword expansion
$Author: fred $
and it is checked out without keyword expansion, the keyword in the
working file reads
$Author$
Source Integrity maintains several keywords that can be used in
working files. The following table describes each keyword and what
it expands to.
Note Keywords are case-sensitive.
Keyword Expands To
$Author$ The author name of the user who checked in
the revision.
$Date$ The check in date and time of the revision
(assigned at check in). The time is shown in
Greenwich Mean Time (GMT/UTC).
$Header$ The fully qualified file name of the archive, as
well as the revision number, date and time,
author, state and locker (if locked).
$Id$ The same as $Header$, except that the
archive’s file name is not qualified.
$Locker$ The user name of the user who locked the
revision (empty if not locked).
User Guide 131

Getting Started With Projects, Sandboxes, and Members
Keyword Expands To
$Log$ The revision description supplied during check
in, preceded by the archive’s file name,
revision number, author and revision date.
Repeated check-out operations append
revision descriptions, rather than replacing
existing ones.
$Name$ The revision label (or labels) attached to a
revision.
$ProjectName$ The fully qualified name of the project of which
the archive is a member.
$ProjectRevision$ The revision number of the project with which
the archive is related.
$RCSfile$ The archive’s unqualified file name.
$Revision$ The revision number.
$Source$ The archive’s fully qualified file name.
$State$ The revision’s state setting.
132 Source Integrity Professional Edition

Managing Projects and
Sandboxes
5
Source Integrity allows you to archive your projects just as you do
your members, so you can always reproduce complete project
configurations (including the files and the directory trees in which
they reside) at any time in the future. This ability to replicate projects
precisely is essential to successful post-release maintenance.
This chapter describes how to
freeze projects to prevent changes, and thaw them to allow
changes
checkpoint projects to provide a snapshot of their contents at
particular points
promote and demote projects from one state to another through a
development cycle
log transactions that have been performed on projects
view changes from one version of a project to another
restore a project to previous checkpointed version
delete variant projects
User Guide 133

Managing Projects and Sandboxes
Freezing a Project
If you decide that a project has advanced to the point where further
changes may destabilize it, you can freeze the project.
At the project level, freezing prevents
adding, updating, or deleting any project members
changes to project attributes and configuration options
any changes to event triggers that are part of the project file
Freezing a project extends an “implied” freeze to all the members in
the project. However, members in a frozen project cannot be thawed
or frozen individually. You first have to thaw the project. Because of
this, when the current project is frozen, freeze and thaw member
commands in the Windows interface are not available.
The state of being frozen is inherited. If a frozen project contains a
subproject, the subproject too is frozen and, in turn, all of its archived
members.
In the Windows interface and Source Integrity Web Interface, a frozen
project is denoted with a snowflake symbol ( ).
Note The ability to freeze or thaw projects can be controlled through
SAM. Therefore, administrators with responsibility for Source Integrity
may have restricted the use of freezing or thawing through SAM
permissions. Consult the SAM documentation or the person responsible
for administering SAM.
To freeze a project in the Windows interface:
With a Project or Sandbox window active, choose Project > Freeze
Project, or click (if added to the toobar).
Source Integrity freezes the project and places a snowflake symbol
( ) beside each member in the Sandbox or Project window, to
remind you that the project is frozen and that changes are not
allowed.
The word “Frozen” also appears in the window title.
To make this command act recursively in all subprojects of the active
project, make sure the Freeze Project option is selected in the
Recursion panel of the Personal Configuration dialog box.
134 Source Integrity Professional Edition

Thawing a Project
Thawing a Project
To freeze a project in the Source Integrity Web Interface:
In the Project view, choose Project > Freeze Project. If this project
contains subprojects, you are asked whether or not you want to
recurse into them.
To freeze a project in the command line interface:
Use the pj freezeproject command from the project directory. Its
syntax is
pj freezeproject [-i] [-Pprojfile.pj]
where -i causes the freeze to be applied recursively to all subprojects,
and -Pprojfile.pj specifies a project file name if your project file is not
called project.pj.
Use the pj vars or pj header commands to confirm the freeze.
Note Invoking pj print reveals that all the project members have been
frozen, but it does not reveal that the project itself is frozen.
If you decide that a project no longer needs to be frozen, you can thaw
it, thus removing the restriction on changing member information in
the project.
Thawing a project removes the “implied” freeze on member files,
except for those that were previously frozen individually. Thawing a
project also permits changes to project attributes, configuration
language blocks, and event triggers in the project file.
If a member or subproject of a frozen project has been previously
frozen, you must thaw the project before you thaw the member or
subproject.
To thaw a project in the Windows interface:
With a Project or Sandbox window active, choose Project > Thaw
Project, or click (if added to the toolbar).
Source Integrity thaws the project and removes the snowflake symbol
( ) from beside each member in the Sandbox or Project window.
This indicates that changes to the project are allowed once again.
User Guide 135

Managing Projects and Sandboxes
Checkpointing a Project
The word “Frozen” also disappears from the window title.
To thaw a project in the Source Integrity Web Interface:
In the Project view, choose Project > Thaw Project.
Source Integrity thaws the project and removes the snowflake symbol
( ) from beside each member in the Sandbox or Project window.
This indicates that changes to the project are allowed once again.
If the project contains subprojects, a prompt appears asking if you
want to thaw subprojects as well.
To thaw a project in the command line interface:
Use the pj thawproject command from the project directory. Its
syntax is
pj thawproject [-i] [-Pprojfile.pj]
Include the -P parameter with your project file name if your project
file is not project.pj. Include the -i parameter to have Source
Integrity recursively thaw all subprojects.
Use pj vars or pj header to confirm that Source Integrity has
removed the project freeze.
Just as you check in a source file to preserve the changes that are
made to it from one revision to another, you must also be able to track
the evolution of a project. In Source Integrity, this process is called
checkpointing.
Checkpointing saves a copy of the project file in the project archive as
a revision, including the list of members along with their revision
numbers and project attributes (including configuration statements
and event triggers).
You can use the project’s revision number to keep track of your
projects. But to simplify post-release maintenance, use a label to
identify significant project development milestones when you
checkpoint a project.
For example, if you checkpoint a project and label it with a release
identifier (for example, “Release 6.2”), you be able to find and
recreate that particular development state more easily.
136 Source Integrity Professional Edition

Checkpointing a Project
Remember that checkpointing a project affects the project file only; it
does not check in every member of the project.
If you are working in a sandbox, issuing a checkpoint command
checkpoints the sandbox’s master project.
If you want to create a variant sandbox or build sandbox, you must
have a checkpointed project to start with.
To checkpoint a project in the Windows interface:
1. With a Project or Sandbox window active, choose Project >
Checkpoint Project.
If the Checkpoint Project option is set in the Recursion panel of
the Personal Configuration dialog box, this command recursively
checkpoints subprojects that are members of the project the
command is run on.
The Checkpoint dialog box appears.
2. Fill in the options as you like, and click OK to create a new
revision of the project. Following are the options you can set:
Label. Enter a revision label (unique text that identifies the
new revision) in this field. You may want to label significant
checkpoints with a product release number, to aid in postrelease
maintenance.
Number. This field is primed with a suggested revision
number for the new revision. You may accept this
recommendation or enter another number of your choice. If
you choose to override the suggested revision number, the
User Guide 137

Managing Projects and Sandboxes
number you supply must be higher than the head revision
number (if you are checkpointing the main project), or the tip
revision number (if you are checkpointing a variant project).
State. This field holds a one-word summary describing the
status of the new revision. For example, if the revision is an
early version of the work, you might assign it a state of
“Experimental”. When later revisions are checked in and the
work is ready to be viewed by other team members, a state of
“Testing” can be assigned.
Initially, the State field is primed with a value of “Exp” (for
Experimental), or the lowest promotion state setting, if
promotion is turned on. Blank spaces or punctuation marks
may not be included in the State field. This field may not be
left blank.
If promotion is enabled, you can choose from a list of all
available promotion states.
Author. This field is used to identify the person who made the
changes to the new revision. By default, this box is primed
with the author name defined in your configuration, but you
are free to change it to any name you choose.
Apply Label To All Members. This option lets you apply the
label you enter to all members in the current project. The
label is applied recursively if the Label option is selected in
the Recursion panel of the Personal Configuration dialog box.
Apply State To All Members. This option lets you apply the
state you choose to all members in the current project. The
state is applied recursively if the Promote and Demote
Member option is selected in the Recursion panel of the
Personal Configuration dialog box.
Replace Label. If the label you choose already exists in the
archive, this option tells Source Integrity to delete the label
from the revision it is currently attached to and apply it to the
new revision.
Update Member. If you are checking in a subproject member
to a project or sandbox, this option lets you update the
revision number of the subproject member to that of the
newly checked-in revision.
All Subprojects. If you are checking in more than one
subproject member, the Checkpoint dialog box appears with
this option available. Selecting this option causes the current
set of options to be applied to all subsequent check-in
operations.
138 Source Integrity Professional Edition

Checkpointing a Project
To checkpoint a project in the Source Integrity Web Interface:
1. From the Project view, select the project file and choose the
Checkpoint Project command.
The Checkpoint page appears, displaying the full path of the
project file to be checked in.
2. Enter your metadata in the fields provided, remembering that the
metadata entered is applied to the revision of the project, not its
members.
Revision Description. Text commenting on the content, or
members, of the project revision
Label. Text which can be used to identify the project revision
To move an existing label from a previous revision to the
current revision, select Replace Label. To attach the label
entered to all member revisions in the project, select Apply
Label to All Members.
State. A one-word description of the new revision’s status.
Author. The name of the person checkpointing the project, by
default your user name.
3. Click OK to checkpoint the project.
The Source Integrity Web Interface creates a new revision of the
project in the project’s archive. If the project has subprojects, they
are automatically checkpointed as well.
To checkpoint a project in the command line interface:
Use the pj checkpoint command. Its syntax is
pj checkpoint [-Nlabel] [-sstate] [-rrev] [-t
[mesg|@mesgfile]] [-i] [options]
where label is a label (if it exists, it is moved up to this revision), rev
specifies a revision to be checkpointed, mesg is an archive description
(if this is the first time you are checkpointing a particular archive),
and mesgfile is a file containing text for the archive description.
User Guide 139

Managing Projects and Sandboxes
Opening a Project Archive
When naming a symbolic label, you should not use periods (.) in the
name, since this can create ambiguous situations when labels are
used to specify a revision. Labels cannot contain colons (:), square
brackets ([ ]), or leading spaces. They also may not resemble a
revision number.
Note MKS strongly recommends you use the -i option, which causes
all subprojects to also be checkpointed.
When you want to view the revision history of a project, you can
open its project archive. Opening the project archive of a sandbox is
the same as opening the project archive of its master project.
To open a project’s archive in the Windows interface:
With a Sandbox or Project window active, choose Project > Open
Project Archive.
The project’s archive opens and displays in an Archive window.
To open a project’s archive in the Source Integrity Web Interface:
Go to the Project view and choose Project Commands > Open History
View, or click History on the toolbar. This shows the checkpoint
history of the project.
Promoting and Demoting a Project
Just as you can with a project member, you can promote or demote the
project itself (change its state, in other words) as long as promotion is
enabled and you have the necessary SAM permissions. This can assist
in management of an entire project through a development cycle,
especially if the promotion and demotion functions are restricted to
key project personnel.
Normally, you promote or demote a project (set its state) when you
checkpoint it, but you can do so at any time.
140 Source Integrity Professional Edition

Promoting and Demoting a Project
If you promote or demote a sandbox, the master project is promoted
or demoted. Only the project file is promoted or demoted, not the
members of the project.
To promote a project in the Windows interface:
1. With a Sandbox window or Project window active, choose Project
> Promote Project.
The Promote Project dialog box appears.
2. Select a new promotion state from the Promote to state dropdown
list.
3. Click OK to accept the new promotion state, or click Cancel to
close the dialog box without changing the project’s state.
If the Project > Promote Project command is not available, make sure
the promotion feature is enabled on the Promotion tab of the Personal
Configuration dialog box.
To demote a project in the Windows interface:
1. With a Sandbox window or Project window active, choose Project
> Demote Project.
The Demote Project dialog box appears.
2. Select a new promotion state from the Demote to state drop-down
list.
3. Click OK to accept the new promotion state, or click Cancel to
close the dialog box without changing the project’s state.
User Guide 141

Managing Projects and Sandboxes
To promote or demote a project in the Source Integrity Web
Interface:
Use the Promote and Demote commands from the History view.
To promote or demote a project in the command line interface:
Use the rcs command as follows: with the -sstate option. Its syntax is
rcs -sstate[:rev] file
where state is the new state you would like to change to.
Logging Project Transactions
For information about logging
archive transactions, see
“Logging Archive
Transactions” on page 193.
Cleaning Up
Log Files
Source Integrity keeps track of the transactions it performs upon
projects in a file called project.trn, where project is the name of the
.pj file for your project.
To view the transaction log in the Windows interface:
Choose Project > View Log.
Your default editor is launched with the log file open in it.
The Log file has the same name as the project (.pj) file, but with a
.trn extension, and is stored in the project directory.
You can also open a text editor, browse to your project directory, and
open the .trn file from there.
The easiest way to clean up a log file is to delete the file. Source
Integrity automatically creates a new one the next time it records a
project transaction. You can also open the log file in a text editor and
delete transaction records. For instance, you could delete transaction
records that are greater than a particular number of days or weeks
old.
142 Source Integrity Professional Edition

Viewing Changes to a Project
Viewing Changes to a Project
When you checkpoint a project, you are actually saving a revision of
the project file itself (for example, project.pj). The project file
contains information that can help you manage and understand the
progress of your projects as they move through the development
cycle. This information includes
revision number of the current project
names and locations of all project members
revision numbers of all project members
any project attributes
member attributes
project-specific event triggers
As you work with the project and its members, the content of the
project file changes.
The revision number of the project is updated every time you
checkpoint it (that is, check in the project).
As you check in individual members, their revision numbers
change.
Members may be added or deleted.
Project attributes may be added or deleted.
Source Integrity, in its Windows and command line interfaces, allows
you to view the changes that have occurred between two versions of
the project file.
Note This functionality is not available in the Source Integrity Web
Interface.
To view changes to a project in the Windows interface:
1. With a Project or Sandbox window active, choose Project > View
Project Changes.
The View Project Changes dialog box appears.
User Guide 143

Managing Projects and Sandboxes
2. Select which revisions of the project you want to compare.
Compare the current version of the project with its last
checkpointed revision.
Compare the current version of the project with a specific
revision or label.
If you select this option, select the specific revision by
Revision number or by Label.
Compare two revisions or labels of the project.
If you select this option, select the two specific revisions by
Revision number or by Label.
3. Click OK.
If no changes to the project have occurred, a box appears to
inform you. If changes have occurred, the Project Changes dialog
box appears, displaying the changes that have occurred.
144 Source Integrity Professional Edition

Viewing Changes to a Project
4. To copy the text in the dialog box to your Windows clipboard,
select the text you want to copy and press .
5. When you are finished, click OK or Cancel.
To view changes to a project in the command line interface:
Use the pj mods command. Its syntax is
pj mods [-k rev1] [-k rev2] [options]
where rev1 and rev2 define the range of project revisions to be
compare.
There are three ways you can compare project revisions:
If you use no -k options, the most current revision of the project
file is compared with the working file in the project directory. In
other words, it shows all of the changes to the project file since
the last time it was checkpointed.
If you specify only one -k option, pj mods compares the specified
revision with the current project working file.
For example, the command
pj mods -k 1.2
compares revision 1.2 of the project file to the project file in the
project directory.
If you specify both -k options, the two specified revisions are
compared.
For example, the command
pj mods -k 1.3 -k 1.5
compares revision 1.3 of the current project to revision 1.5 of the
same project. Its output might look something like
d:\gamble\handler.c: revision changed: was 1.12,
now 1.15
This information tells you that when you checkpointed revision 1.3 of
the project, the member named handler.c was at revision 1.12, and
in project revision 1.5 the member had moved to revision 1.15.
User Guide 145

Managing Projects and Sandboxes
Restoring a Project’s Member List
The Restore Project Member List feature restores the member list of a
previously checkpointed revision of a project. This feature modifies
the project’s working file on the current development path to reflect
the member list of the restored project revision, allowing
development in the project to proceed from that point.
Note If you want to create a branch for new development from a
previously checkpointed project revision, you should create a variant
sandbox (see “Creating a Sandbox” on page 76).
If the project file has changed since the last checkpoint, this command
checkpoints the current project file before restoring the member list.
If the Restore Member List option is set in the Recursion panel of the
Personal Configuration dialog box, this command recursively
checkpoints subprojects that are members of the project (or members
of members) the command is run on.
Some items cannot be restored using the Restore Project Member List
feature, including:
Project attributes, because they represent current development
practices that are probably still in effect even after you have
restored a previous version of a project. They include
Source Integrity configuration policies
project mappings
project build variables
project-related event triggers
user-defined project variables.
Members that have a type of “other”, indicating that they are
non-archived.
Note MKS strongly recommends that you archive all members when
adding them to a project.
Revision locks, revision state, and revision labels.
146 Source Integrity Professional Edition

Restoring a Project’s Member List
To restore the project member list in the Windows interface:
1. Choose Project > Restore Member List.
The Restore Project Member List dialog box appears.
2. Select the revision you want to restore By Revision, By Label, or
By Development path.
3. Optionally, enter a comment in the Description field.
4. Click OK to restore the project member list, or click Cancel to
close the dialog box without making changes.
To restore the project member list in the command-line
interface:
Use the pj restore command, specifying which project to restore by
its revision, label, or development path. Its syntax is
pj restore -rrev | -rlabel | -Ndevpath [-i]
where rev is a revision number, label is a label assigned to the project,
and devpath is the project’s development path. To recursively restore
the subprojects of the specified project, use the -i option.
User Guide 147

Managing Projects and Sandboxes
Importing Files
For complete details, see the
online command reference for
the sccs2rcs, pvcs2rcs,
and vss2rcs commands.
For information on syntax of
vss2rcs command, see
“Importing Visual SourceSafe
Files” on page 150.
If you are already using a revision control system (for example, SCCS,
PVCS, or Visual SourceSafe) and you want to move to Source Integrity,
you can import your existing archives and automatically convert
them to Source Integrity format.
This functionality does not exist in the Source Integrity Web Interface.
To import a PVCS or SCCS archive in the Windows interface:
Use the File > Import Archives command.
To import an archive in the command line interface:
Use the pvcs2rcs (for PVCS files), sccs2rcs (for SCCS files), and
vss2rcs (for Visual SourceSafe) commands.
The pvcs2rcs and sccs2rcs commands use the same syntax:
pvcs2rcs -Fflist | file…
sccs2rcs -Fflist | file…
where flist is a file list containing the names of the files to import (one
per line), and file is one or more files to import into Source Integrity.
Note The pvcs2rcs and sccs2rcs commands do not work on files that
reside on secure servers (such as one secured by the MKSSI NT Security
Service or Novell NLM). To convert such files, first copy them to an
unsecured file system. Perform the conversion there and copy the newly
created Source Integrity archives to the secured server (and secure
them).
Example
The command
sccs2rcs sample01.txt sample02.txt sample03.txt
imports the three named files, while
sccs2rcs -Ffiles.lst
imports all the files listed in the file files.lst.
Importing files preserves virtually all the file and revision
information contained in the PVCS or SCCS file formats. There are,
however, some differences in the way various revision control
148 Source Integrity Professional Edition

Importing SCCS
Files
Importing PVCS
Files
Importing Files
systems express specific aspects of the process. The following
sections describe the way Source Integrity handles these differences,
as well as other features unique to Source Integrity.
Source Integrity imports SCCS files as follows:
SCCS files are not deleted.
The state of all revisions is set to “Exp”.
On DOS systems, if the SCCS file has its working file name (m)
flag set, the Source Integrity archive takes the name specified by
the m flag; otherwise, it takes the name of the SCCS file, with the
.s suffix (if present) removed.
Note On UNIX systems, the name of the Source Integrity archive is the
same as the SCCS input file, with the .s suffix removed.
If the SCCS file has its default revision flag set, the default branch
in the Source Integrity archive is set to the corresponding
revision.
If MR (Modification Request) numbers are provided with any
SCCS revisions, these numbers are added to the revision
descriptions of the corresponding Source Integrity revisions.
Locks are not preserved. Revisions locked under SCCS are not
locked when imported into Source Integrity.
Source Integrity imports PVCS files as follows:
PVCS files are not deleted.
The state of all revisions is set to “Exp”.
The sequence of revision numbers is preserved, but since PVCS
revision numbers start at 1.0 and Source Integrity revision
numbers start at 1.1, all components of PVCS revision numbers
(except the first character) are incremented by one. For example,
PVCS revision number 1.0 becomes Source Integrity revision
number 1.1; 1.3.2.5 becomes 1.4.3.6, and so on.
If the CHECKLOCK option is specified in the PVCS input file, strict
locking is enabled by Source Integrity.
If the WRITEPROTECT option is specified in the PVCS input file, the
Source Integrity archive is created as a read-only file.
The Source Integrity archive takes the name of the PVCS working
file.
User Guide 149

Managing Projects and Sandboxes
Importing
Visual
SourceSafe
Files
The vss2rcs command’s syntax is
vss2rcs [-D] [-B branch] [-a SI_workdir] [-s VSS_path]
[-f filelist] [vssfile …]
The working file for the converted archive is placed in the current
directory. The actual archive is placed in the directory indicated by
the RCSPATH SAM configuration variable. Often, this will be
SI_workdir/rcs/vssfile.
Note You must have Visual SourceSafe installed on the machine on
which you are running the conversion, and you must be logged into
Windows as a valid Visual SourceSafe user.
vss2rcs accepts the following options:
-a SI_workdir specifies the directory in which to place the
working file for the converted archive.
-B branch creates the converted archive on the specified branch.
-D displays debugging messages. When this option is specified,
conversion is slowed down.
-f filelist provides an alternate way to specify archives to be
converted. The given filelist contains a list of Visual SourceSafe
archives to be converted along with the information on the Visual
SourceSafe project path and the directory for Source Integrity
working files which is normally specified by -s and -a options,
respectively.
The filelist file has the following format:
A line starting with SS-SI-PROJECT followed by a space and
the full path name of the Visual SourceSafe project containing
the archives to be converted.
A line starting with SS-SI-WORKDIR followed by a space
and the path name of the directory containing the Source
Integrity working file.
Several lines, each of which specifies the name of a Visual
SourceSafe archive from the project specified by the SS-SI-
PROJECT that you wish to convert.
You can convert multiple projects with one filelist by repeating
this format one or more times.
-s VSS_path specifies the path name of the Visual SourceSafe
project that contains the archive being converted.
150 Source Integrity Professional Edition

Using Existing
RCS Archives
Example
The command
vss2rcs $/proj1/proj2/file1
Importing Files
converts the Visual SourceSafe archive file1 from the project
$/proj1/proj2 and places the resulting Source Integrity working file
in the current directory. The corresponding archive is placed in a
location determined by the value of the RCSPATH configuration
variable.
Similarly,
vss2rcs -s $/proj1/proj2 file1 file2
converts the Visual SourceSafe archives file1 and file2 and places
the resulting working files in the current directory.
With the -a option, you can have the Source Integrity working files
created in a location other the current directory. For example,
vss2rcs -a c:/temp $/proj1/file1 $/proj1/file2
places the working files created from the Visual SourceSafe archives
$/proj1/file1 and $/proj2/file2 in the c:/temp directory.
Source Integrity accepts traditional RCS archives without conversion.
Source Integrity will, however, begin to add proprietary information
to the archives to accommodate its specialized functionality.
Source Integrity provides the configuration option VanillaRCS to
allow compatibility with traditional RCS. When VanillaRCS is set in
a project, or in your Personal Configuration, any new archives
created will be made RCS-compatible.
Note Other RCS systems, such as GNU RCS, are not able to take
advantage of Source Integrity project information.
User Guide 151

Managing Projects and Sandboxes
Accessing Project Information With the
Command Line Interface
One of the features of Source Integrity is the project and member
metadata (that is, information about projects and their members) it
stores and maintains. At the project level, the metadata it saves or can
generate includes
a list of project members
a record of all the changes made to project members
a record of changes made to the project itself
You can also use the report command to generate archive and
project information in a form that can be imported and manipulated
by most database programs.
List of Members The pj print command can search out and display information
about a project and its members. Using the -S format option, you can
specify the type of information it displays.
For example, the command
pj print -S “%n %r %t”
Changed
Members
displays the name, revision number, and type of all project members.
In fact, the above format string does not need to be supplied, as it is
the default format.
Here’s a sample of output from this command
p:\gamble\handler.c 1.14 archived
p:\gamble\init.c 1.9 archived
p:\gamble\makefile 1.10 archived
p:\gamble\nt\filesys.c 1.22 archived
with an entry for every member of the project. By changing the format
modifier with the -S option, you can display a wide variety of project
and member information.
The pj what command displays the status of project members and
any differences between project members and their working files. It
can report if
a member’s archive is missing or corrupt
there is a newer revision available for a member
a member is locked
a member’s working file is missing or inaccessible
152 Source Integrity Professional Edition

Variables and
Attributes
Project and
Sandbox
Information and
System Settings
Attributes
a member’s working file has changed
Accessing Project Information With the Command Line Interface
a member’s working file is newer than its revision
You can use the -T criteria option to specify the information you want
to see.
For example, the command
pj what -T changed,touched
tells you which members’ working files have been changed, and
whether they are newer than the project member revision.
By modifying the criteria portion of the -T option, you can generate a
range of reports to help you manage and analyze the progress of your
projects.
You can use the pj vars command to view all variables and attributes
accessible from a project or sandbox. Its syntax is:
pj vars [-ceEg]
where -c shows local configuration only, -e shows project
configuration only, -E shows sandbox configuration only, and -g
shows global configuration only.
You can view current project and sandbox information and system
settings with the pj header command. Its syntax is:
pj header [options]
where options are the standard pj options.
Attributes are settings that persist between sessions of Source
Integrity. Depending on the attribute, they are stored in the project or
the sandbox.
Member Attributes
Any member of a Source Integrity project can be assigned attributes,
which can be used to locate and identify individual members—or
groups of members—and to direct project commands to members
with a particular attribute.
Member attributes are set with the pj addrule command. Its syntax
is
pj addrule var[=value] [file…]
User Guide 153

Managing Projects and Sandboxes
For more information about
the -v option, see the online
reference for the pj command.
where var is the name of an attribute, value is the value it is set to, and
file is one or more project members the attribute will be assigned to. If
file is omitted, the attribute is assigned to all project members.
Example
You might use attributes to identify the components needed to build
the NT and OS/2 versions of the gamble project.
You could accomplish this by creating an attribute named “SYS” for
all project members and assigning appropriate values for individual
members.
Files that are used to build both versions of the command (for
example, header and most code files) are assigned a value of
“Both”.
Files used only for the NT version are assigned a value of “NT”.
Files used only for the OS/2 version are assigned a value of
“OS2”.
The easiest way to implement this for the gamble project is as follows:
1. Use the pj addrule command to assign the SYS attribute to all
project members, with a value of “Both”.
pj addrule SYS=Both
2. Run the command twice more to change the value of SYS for
those members used for only one operating system
pj addrule SYS=NT nt\filesys.c
pj addrule SYS=OS2 os2\filesys.c
Note To change a member attribute, simply run pj addrule again and
assign a new value.
With these attributes in place, you can use the -v option to the project
commands to specify that they should operate only on members with
a particular attribute, or an attribute set to a certain value.
For example, to print information about all project members with the
SYS attribute, enter
pj print -v SYS
To see the same information about only those members associated
with the NT platform, you would enter
pj print -v SYS=NT
154 Source Integrity Professional Edition

Accessing Project Information With the Command Line Interface
You remove member attributes with the pj droprule command.
For example, to remove the SYS attribute from all gamble project
members, enter
pj droprule SYS
Note Member attributes are case sensitive; “SYS” and “Sys” are
interpreted as different attributes.
Project Attributes
You can assign attributes to projects, which then define local settings
for the project as a whole.
You can create and set any project attributes you choose, provided
they conform to the rules of the Source Integrity configuration
language.
Note Some attributes are predefined and understood by Source
Integrity. In this capacity, they are called Policy Options, because of their
special meaning and additionally their availability in SAM.
Source Integrity does not permit multiple attributes with the same
name. There are a few exceptions: some configuration options can be
set several times, with different values or settings. The most common
example is the AutoAction option, which is set once for each event
trigger to be defined.
Project attributes (and policy options) are created and set with the
pj set command. Its syntax is
pj set var[=value]
where var is the name of the attribute and value is the value assigned
to it.
If your settings have spaces in them, remember to use quotes. This is
important for several types of settings. For example
pj set my_flag
pj set approved=checked_by_kz
User Guide 155

Managing Projects and Sandboxes
pj set “states=new changed approved final”
pj set “worktoarch c:\proj=c:\rcs\proj”
Note You can view the list of project attributes with the pj vars
command. For a description of pj vars, see the online command
reference or the Source Integrity Professional Edition Reference Guide.
You can remove project attributes with pj unset. When unsetting
attributes, remember to quote them if they include spaces. For
example
pj unset my_flag
pj unset approved
pj unset states
pj unset “worktoarch c:\proj”
Example
You can specify the utility the pj build command uses to build the
project by setting the reserved project option Build.
pj set Build=c:\wcc\bin\make.exe
To remove the Build attribute from the current project you would
enter
pj unset Build
After setting several WorktoArch statements
pj set “worktoarch c:\proj=c:\rcs\proj”
pj set “worktoarch c:\other=d:\archives\other”
you must specify the WorktoArch statement to delete
pj unset “worktoarch c:\proj”
pj unset “worktoarch c:\other”
Note Project attributes are not case sensitive; “SYS” and “Sys” are
interpreted as the same attributes. Member attributes, on the other hand,
are case sensitive.
156 Source Integrity Professional Edition

Editing Code Blocks
Accessing Project Information With the Command Line Interface
Before using the pj set command to create a new AutoAction
statement, you may want to use the pj editblock command to create
a new code block, or replace an existing one within a project or
sandbox. Its syntax is
pj editblock [options] [-m [“block” | [@]blockfile]]
blockname
where
options is zero or more valid project command options.
block is the text of a code block, entered on the command line.
This text should be enclosed in quotes.
-m[@]blockfile is a file containing the new text for the code block
blockname. Use the @ sign to indicate that blockfile is a file name. If
you omit the @ sign, blockfile is treated as code block text.
If you omit the -m option, your default editor opens with a
temporary file that is empty if your block is new, or contains the
current contents of the block if it already exists. Edit the block,
save the file, and exit to add it to the project.
blockname is the name of the code block to add or replace.
For example, the command
pj editblock -m @block.txt NotifyChange
replaces a code block named NotifyChange with the contents of the
file named block.txt.
You delete an existing code block with the pj dropblock command.
For example, the command
pj dropblock NotifyChange
deletes a code blocked named NotifyChange from the project file.
User Guide 157

Managing Projects and Sandboxes
Deleting Variant Projects
If a development path within a project has become obsolete, you can
remove it without disturbing the main trunk or other development
paths in the project. This functionality is only available in the
Windows and command line interfaces.
You can only perform this operation on development paths created
through variant sandboxes. Source Integrity does not support
removing the main trunk of a project.
Caution Take care when using this command. This command removes
a development path from within a master project. Doing this will
invalidate and make useless the variant sandboxes of anyone else
following this development path.
To delete a development path in the Windows interface:
1. With a Project window active, choose Project > Project
Information.
The Project Information dialog box appears.
2. Click Development Paths to expand the dialog box to show the list
of development paths.
3. From the list of development paths, select one or more and click
Delete.
To delete a development path in the command line interface:
From within the master project directory, use the pj delvariant
command. Its syntax is
pj delvariant -Ndevpathname
where devpathname is the name of the development path you want to
eliminate.
You can also delete a variant sandbox from its own directory rather
than the project directory. Give the command
pj delvariant [-Psbxname.pj]
without specifying the development path name. Source Integrity
removes the development path referenced by the variant sandbox.
Include the -P parameter if your sandbox is not named sandbox.pj.
158 Source Integrity Professional Edition

Cleaning Up Working Files
For example, if you create a variant sandbox with the pj sandbox
command
pj sandbox -Pmyproj.pj -N mydevpath -k 1.3
you can remove the development path mydevpath by issuing the
command
pj delvariant -N mydevpath
from the master project (myproj.pj) directory, or
pj delvariant
from the directory of the new sandbox.
Cleaning Up Working Files
For a detailed description, see
the online reference for the pj
clean command.
Note This command makes your variant sandbox invalid. It does not
remove the sandbox files or copies of member files—they may still be
read-only, and may therefore need to be chmod’ed or attrib’ed before
you can delete them.
The pj clean command compares the most recent revision of a file to
its working file and deletes the working file if it has not changed
since it was checked out. To clean up unused working files in an
archive, use rcsclean.
The syntax for pj clean is
pj clean file…
where file is one or more files to be examined.
Source Integrity normally makes a working file writable when you
have a lock on the revision it was generated from. If pj clean finds
the working file is read-only, it assumes you do not have a lock on the
revision, and so removes the working file if it has not changed. If you
had explicitly locked the revision (using pj lock or rcs -l), pj clean
does not clear this lock.
Note This functionality is available only in the command line interface.
User Guide 159

Managing Projects and Sandboxes
Encrypting Files
Automatic
Encryption
Explicit
Encryption
Source Integrity can encrypt archives to supplement security. When
an archive is encrypted, Source Integrity requires you to supply a
encryption key before performing any operation on the archive.
Note The Source Integrity Web Interface does not support encryption. If
archives are to be used by both the Source Integrity Web Interface and
either Source Integrity’s Windows or command line interfaces, you
should not use encryption. In this case, you can use a third-party
encryption scheme. For the implications of this, see “Encryption and
Other Applications” on page 162.
You can automatically encrypt all newly created archives by setting
the Encrypt option in SAM or a Personal Configuration file.
Note Existing archives (that is, those created before the Encrypt option
was set) are not affected.
In the Windows interface, you can encrypt new archives when you
create them by selecting the Encrypted option in the Create Archive
dialog box.
You can also encrypt existing archives by selecting the Encrypted
option in the Archive Information dialog box.
The -Z[key] option to the ci, pj ci, and rcs commands modifies an
archive so all existing and/or subsequent revisions are encrypted. Its
syntax is
ci -Z[key] file…
rcs -Z[key] file…
pj ci -Z[key] file…
where key is the encryption key for one or more archives named in
file. If key is omitted, Source Integrity prompts you to supply an
encryption key.
For example, the command
ci -Zpuck prog.c
160 Source Integrity Professional Edition

Choosing an
Encryption Key
Encrypting Files
checks in a new revision to prog.c and encrypts the archive, using
the encryption key “puck”.
Likewise, the command
rcs -Zpuck prog.c
encrypts prog.c using the same encryption key. Once an archive is
encrypted, you are required to supply the encryption key to perform
any operation that reads from or writes to the archive, such as a check
in or check out.
You can permanently decrypt an encrypted archive with the -z[key]
option to the rcs command.
For example, the command
rcs -zpuck prog.c
decrypts prog.c. If key is omitted, Source Integrity prompts you for
the encryption key.
When you run a Source Integrity command on an encrypted archive,
Source Integrity asks you to provide its encryption key, which is used
to encrypt and decrypt the file.
The encryption key can be up to eight characters long; it may contain
any alphanumeric character, but no spaces. The case of characters in
an encryption key is significant.
The first time you specify an encryption key you are asked to enter it
twice, to ensure that the entry is correct. The two entries must be
identical for the encryption key to be accepted.
Here are some tips for choosing an encryption key:
Choose a key that is at least six characters long.
Do not use a common word or acronym.
Replacing selected letters in a common word with digits
discourages dictionary-based attacks.
User Guide 161

Managing Projects and Sandboxes
Changing the
Encryption Key
Working With
Encryption
For more information on file
lists, see “File Name
Arguments” on page 63.
Encryption and
Other
Applications
Mix uppercase and lowercase characters with punctuation.
To make the key easier to remember, you can base it on a
mnemonic phrase.
Caution Do not forget your encryption key! If you forget it, the
contents of the archive are as good as lost. Furthermore, there is no way
to determine an archive’s encryption key, since it is not stored in the
archive.
You change an archive’s encryption key by decrypting the archive,
then encrypting it again, using a different encryption key.
Example
To change the encryption key for the archive prog.c, enter the
command
rcs -zpuck prog.c
to decrypt the archive. Next, enter the command
rcs -Zfeste prog.c
to encrypt the archive with the new encryption key “feste”.
You can use any Source Integrity command on an encrypted archive;
you must supply its encryption key, however, before you can see its
contents.
If you have a body of existing archives you want to encrypt, use the
-Z option to the rcs command, and a file list containing the names of
all the files.
If you use Source Integrity with applications that support security
schemes of their own, MKS recommends you use Source Integrity’s
encryption feature rather than those of your applications.
When you check in a file, Source Integrity determines the differences
between it and the previous revision, then saves only the differences.
In some cases, two revisions will differ by only a single line. If the
files are checked in before encryption, Source Integrity identifies the
single different line, encrypts that line, and saves only the encrypted
line in the archive.
162 Source Integrity Professional Edition

Encrypting Files
However, if the files are encrypted by another program before check
in, the differences between the file and the previous revision will be
substantial, forcing Source Integrity to save all the differences and
resulting in a much larger revision.
User Guide 163

Managing Projects and Sandboxes
164 Source Integrity Professional Edition

Managing Archives
and Revisions
6
While sandboxes and projects allow you to manage and access
project members, the contents of individual member files—and the
history of changes you make to them—are saved in the archives.
Source Integrity lets you save—and recreate—every stage (or
revision) in the development of every file you use.
When you make changes to a project member and then check it back
in, your changes are automatically added to the member’s archive. If
you ever need to see that version of the file again, just check out the
appropriate revision, and Source Integrity rebuilds an exact copy for
you. Not only can every file in a project be archived, the project itself
can be archived (checkpointed), allowing you to rebuild the entire
project configuration at any time.
While the archive commands are as safe and easy to use as their
project-oriented counterparts, they do not communicate their
activities to your projects. For example, if you normally access a file
through a Project window, but another developer uses the archive
commands to check out the file, makes changes to it, and checks it
back into the archive, the project is not automatically updated. MKS
therefore recommends that you usually work through projects and
sandboxes.
User Guide 165

Managing Archives and Revisions
Opening a Project’s Archive
To open a project’s archive in the Windows interface:
With a Project or Sandbox window active, choose Project > Open
Project Archive.
The project’s archive (either the current project or the master project
of the current sandbox) opens and appears in an Archive window.
Opening a Member’s Archive
To open a project’s archive in the Source Integrity Web Interface:
From the Project view, choose Project Commands > Open History View.
To open a member’s archive in the Windows interface:
1. Select an archived member in a Sandbox or Project window.
2. Choose Member > Open Member Archive or press +.
The member’s archive appears in an Archive window. The title of
the Archive window includes the statement
(from projname)
after the archive file name, where projname is the file name of the
sandbox or project the Open Member Archive command was
invoked from. This lets you know the archive is “project aware”
and will ignore the WorkToArch, ArchivePath, and WorkPath
constructs when checking out to, or checking in from working
files.
166 Source Integrity Professional Edition

Creating Archives
Creating Archives
To open an archive directly without a project or sandbox in the
Windows interface:
1. Choose File > Open Archive, or click .
The Open Archive file browser appears.
2. If the archive you want to open is not in the current directory, use
the Drives and Directories boxes to navigate to the proper
location.
3. Select one or more archives (or their corresponding working files)
and press , or click OK.
An Archive window appears for each file.
To open a member’s archive in the Source Integrity Web
Interface:
Select the member in the Project or Sandbox view and choose Member
Commands > Open Member View.
Archives are usually created when you create a project or add
members to a project. However, if you need to create an archive
outside the project context, you can do so. Standalone archives (ones
that have no projects associated with them) can be added to projects
at a later time.
Note The Source Integrity Web Interface does not support standalone
archives.
To create an archive in the Windows interface:
1. Choose File > Create Archive or click .
The Create Archive file browser appears.
User Guide 167

Managing Archives and Revisions
2. If the file you want to bring under version control is not in the
current directory, navigate to the appropriate directory.
3. Select one or more files you want to create archives for, and click
OK.
The Create Archive dialog box appears.
4. Fill in the Create Archive dialog box options as you like, and click
OK to create the new archives.
When creating an archive, you can set a number of options (see
“Archive Settings” on page 169 and “Revision Settings” on page 169)
that determine how the archives are managed, whether an initial
revision should be checked in, and what revision details will be
recorded.
168 Source Integrity Professional Edition

For more information about
SAM permissions, see the
Source Integrity Professional
Edition Administrator Guide or
ask your system
administrator.
Creating Archives
The availability and functionality of options depends on your SAM
permissions.
Archive Settings
Strict Locking. Selecting this option causes the new archive to use
a strict-locking policy, which forces you to lock a member if you
want to edit it and check it in. This option might be unavailable if
a locking policy is enforced.
Compressed. Selecting this option causes the archive to be saved
in compressed format, which is especially useful if you are
working with large files, or if disk space is at a premium. This
option might be unavailable if a compression policy is enforced.
Data Type. Use this option to set the type of data you will be
storing in the archive. You may select one of three possible data
types:
Binary. A file containing unprintable characters, or lines too
long to be handled by text editors.
Text. A file that is always saved in a format expected by
standard text editors (for example, Notepad or vi).
Auto Detect. The default setting, which can be used safely
with any file. Source Integrity determines the type of the file
and creates an appropriate archive for it.
Encrypted. Selecting this option causes Source Integrity to
encrypt the archive when it creates it. This option requires an
encryption password.
Caution Do not forget the encryption password! Without it, data in
the archive is unrecoverable. This option might be unavailable if an
encryption policy is enforced.
Archive Description. Enter a free-form description of the archive.
You may include any information you want here.
Open Archive. Selecting this option causes Source Integrity to
open the new archive in the application window.
Revision Settings
Check In. This option checks in the selected file as the first
revision in the archive. If this option is not set, an empty archive
is created.
User Guide 169

Managing Archives and Revisions
Locked. This option creates the new archive and immediately
locks the first revision, allowing you to retain control of the first
revision while creating the archive. If this option is not set, the
first revision is checked in unlocked.
Label. Enter unique text that identifies the new revision for the
first revision in the new archive. Labels can be viewed or
modified later.
Number. This is the revision number for the first revision of the
new archive. The default is 1.1.
All Files. This option applies the option settings for the current
archive to all subsequent archives, if more than one archive is
being created.
Keep Work File. This option creates the archive, checks in the file,
and immediately checks it out again. If this option is not set, the
working file is deleted when the archive is created.
State. A one-word flag describing the status of the new revision.
Default is “Exp” (for Experimental), or the lowest promotion
state setting, if promotion is turned on.
Author. Identifies the person who creates the new revision. The
default is the author name specified in your Personal
Configuration, but you can set it to another name.
To create archives in the command line interface:
Check in the first revision with the ci archive command; you do not
have to explicitly create the archive. Its syntax is
ci [options] file…
where file is one or more files archives will be created for.
The first time you check in a file, Source Integrity
determines whether it is binary (Source Integrity considers a file
to be binary if it contains nulls, or lines too long to be handled by
text editors)
creates an archive of the appropriate format (binary or auto)
adds the content of the working file as the first revision
Unlike the pj ci command, the default behavior of the ci archive
command is to delete the original file when it checks it in. This can be
avoided by using the -l or -u options.
170 Source Integrity Professional Edition

Importing Archives
If you use the -l option when creating a new archive, Source
Integrity locks the first revision in your name and leaves a writable
copy of the working file on your disk. With the -u option, the revision
is not locked and a read-only copy of the working file is left.
Example
Importing Archives
For more information, see
“Importing Files” on page 148.
To create a new archive for the prog.c file and retain a writable
working copy of the file, enter
ci -l prog.c
This presents the message
rcs\prog.c >
The first line tells you an archive named prog.c will be created in the
rcs directory of the current directory. The second line tells you the
first revision will have revision number 1.1 and will be locked in your
name.
The rest of the message advises you can enter a description of the
new archive by entering it at the >> prompt. The archive description
can be of any length, and should describe the contents and purpose of
the new archive.
When you have entered the first line of the archive description, press
. This presents another >> prompt where you can continue
the description. To end the archive description, enter a single period
at the >> prompt and press .
If you are already using a revision control system such as SCCS or
PVCS and want to move to Source Integrity, you can import your
existing archives and convert them automatically to Source Integrity
format. Importing files preserves virtually all of the file and revision
information contained in the SCCS or PVCS file format.
You can also convert Source Safe archives to Source Integrity format.
For more information, see the Source Safe to Source Integrity
conversion documentation on your CD-ROM.
User Guide 171

Managing Archives and Revisions
Checking Out Revisions From Archives
When a revision is checked out from a sandbox or project, the
location of the working file is determined at the project level. When
you check out a revision directly from an archive, however, the
location of the working file is calculated from the WorkToArch, or
Archive Path and WorkPath settings.
To check a revision out of an archive in the Windows interface:
Use the Archive > Check Out command. You can specify the same
check-out options that are available when you check out a member
from a project (see “Checking Out a Member” on page 81).
To check a revision out of an archive using the command line
interface:
Use the co command. Its syntax is
co [options…] [-Pprojname] file…
where options is zero or more modifying options (see the Source
Integrity Professional Edition Reference Guide or the online man pages),
-Pprojname is the name of the Source Integrity project file is a member
of, and file is one or more files to check out. Named files may contain
any level of path qualification.
If the file being checked out is a member of a Source Integrity project,
the -Pprojname option uses project file mapping information to locate
archives. Whenever possible, use pj co when dealing with members
of a project or sandbox.
A revision can be checked out in one of two modes: locked or
unlocked. If you intend to make changes to the revision, you should
use the -l option to check it out locked; if you plan only to view or
process the revision (for example, to build a software release), simply
use co without the lock option.
A revision that is checked out unlocked is copied to a read-only
working file if a strict locking policy is in effect for the archive. In
addition, with a strict locking policy, Source Integrity only lets you
check in a file if it was first checked out locked.
When strict locking is not in effect, check-in operations are
unrestricted, provided no one else has a lock on the revision.
For example, the command
co prog.c
172 Source Integrity Professional Edition

Checking Out
by Revision
Number or
Label
displays the message
Checking Out Revisions From Archives
rcs\prog.c --> prog.c
revision: 1.4
done
The first line of the message tells you a revision was checked out of
the prog.c archive (in the rcs directory of the current directory), and
was copied to a working file named prog.c in the current directory.
The second and third lines indicate the number of the revision that
was checked out (that is, revision 1.4), and that the operation
completed successfully.
If you use the command
co -l prog.c
the second line of the message reads
revision: 1.4 (locked)
indicating the revision was checked out locked. When you check out
a revision locked, Source Integrity copies it to an editable working
file.
By default, the co command checks out the head revision from an
archive. The head revision is the most recent revision along the main
development path of an archive. If you want to check out an earlier
revision, use the -rrev option to the co command. Its syntax is
co -rrev [-Pprojname] file…
where rev is the revision number or label of the revision you want to
check out.
For example, to check out and lock the first revision in the prog.c
archive, you would use the command
co -r1.1 -l prog.c
To check out the revision labeled “Release_1”, you would enter
co -rRelease_1 -l prog.c
Note If the revision number you specify is not found in the archive,
Source Integrity checks out the revision whose revision number is closest
to—and lower than—the number you supply.
User Guide 173

Managing Archives and Revisions
Checking Out
by State Setting
You can check out a particular revision by its state setting. You do this
with the -sstate option to the co command. Its syntax is
co [options] [-sstate] file
where state is the state setting of a revision in the archive.
Because state settings may not be unique within the archive, Source
Integrity scans the archive and checks out the revision closest to the
default revision with this state setting.
For example, to check out the most recent revision of prog.c with the
state setting “proposed” you would enter
co -sproposed prog.c
Checking In Revisions to Archives
When you are finished making changes to a working file that you
checked out directly from the archive, you can archive the changed
file as a new revision. If Source Integrity cannot find an archive for
the file, it creates a new archive and adds the file as the first revision.
To check a revision into an archive in the Windows interface:
Use the Archive > Check In command. You can specify the same
check-in options that are available when you check a member into a
project (see “Checking In a Member” on page 87).
To check a revision into an archive using the command line
interface:
Use the ci command. Its syntax is
ci [options] [-Pprojname] file…
where options is zero or more modifying options (see the Source
Integrity Professional Edition Reference Guide or the online man pages),
projname is the name of the Source Integrity project file belongs to, and
file is one or more files to check in. Named files may contain any level
of path qualification.
If the file being checked in is a member of a Source Integrity project,
the -Pprojname option updates the project in a manner similar to the
pj ci command. Whenever possible, use pj ci to check in members
of a project or sandbox.
174 Source Integrity Professional Edition

Checking In—
Setting Labels
Checking In Revisions to Archives
For example, to check in and lock a file named prog.c, which is also a
member of a project in the current directory, you would enter
ci -l -Pproject.pj prog.c
This presents the message
rcs\prog.c >
The message reports the revision numbers of both the new revision
and the previous revision.
Source Integrity asks you to enter a description for the new revision.
The revision description allows you to provide a record of changes as
you make them and to explain why they were made.
You add the revision description by entering it at the >> prompt and
pressing . This presents another >> prompt. Repeat the
process to enter as many lines of description as you choose.
When you have completed the revision description, enter a single
period at the >> prompt, and press .
The -l option
leaves a writable copy of the working file
locks the revision in your name, so you can continue to make
changes to it, but other users cannot
You should use the -u option if you do not intend to edit the file
immediately; this leaves a read-only copy of the file available. If
neither option is used, Source Integrity checks in and immediately
deletes the working file.
For example, to check in prog.c and assign revision number 2.0 to
the new revision, use the command
ci -r2.0 prog.c
You can set a label at check-in with the -N option to the ci command,
or at any other time with the -N option to the rcs command.
The -Nlabel option removes label from the revision it is currently
attached to, and assigns it to the new revision being checked in. This
operation has no other impact on the original revision.
User Guide 175

Managing Archives and Revisions
Checking In—
State Settings
For more information on this
more structured use of state
settings, consult the States
configuration option and the
Promote and Demote SAM
permissions.
For example, the following command reassigns the label “Revised” to
the revision being checked in to prog.c archive.
ci -u -NRevised prog.c
To reassign a label from one existing revision to another in an archive,
use the rcs command. To reassign the label “Revised” from another
revision of prog.c to revision 1.1 of the same file, enter the command
rcs -NRevised:1.1 prog.c
At check-in time, state settings are added with the -sstate option to
the ci command, where state is the state setting for the new revision.
State settings can also be used to establish and enforce promotion
policies at your site.
For example, the command
ci -sReview prog.c
checks in prog.c and sets the state of the new revision to “Review”.
Viewing and Editing Archive Information
Just as it maintains metadata about each project member, Source
Integrity also maintains extra information about each archive, called
archive information.
In the Windows interface, you can view and edit information about
an archive using the Archive > Archive Information command. Unlike
most Source Integrity commands, which can be accessed from
sandboxes and projects, this command is available only when an
Archive window is active.
To see an archive’s information:
1. With an Archive window active, choose Archive > Archive
Information, or click .
The Archive Information dialog box appears.
176 Source Integrity Professional Edition

2. View or make changes to the archive information.
Viewing and Editing Archive Information
3. Click OK to save your changes, or Cancel to close the dialog box
without making changes.
You can view, but not change, the following archive information:
Working File. The fully qualified name of the working file
associated with the archive.
Archive File. The fully qualified file name of the archive whose
information is displayed.
Labels. A listing of all revision labels in the archive and their
associated revision numbers.
Locks. A list of all users who have locks on revisions in the
archive, the revisions they have locked, and the lock time.
Projects. A list of all projects which use this archive as a member
archive.
You can edit the following options:
Strict Locking. Selecting this option turns on strict locking for the
archive.
Compressed. Selecting this option causes the archive to be
compressed.
User Guide 177

Managing Archives and Revisions
Encrypted. Selecting this option encrypts the archive. If you do
so, when you click OK to leave the Archive Information dialog box,
another box prompts you for an encryption password.
Caution Do not forget the encryption password! Without it, data in
the archive is unrecoverable.
Data Type. Select the type of data stored in the archive. For a list
of data types, see “Creating Archives” on page 167.
Default Branch. Select the starting point of the default branch.
Archive Description. Select text that describes the archive.
Store By Reference. Selecting this option causes each revision to
be saved to a separate file, instead of saving the entire archive to
one file. This feature improves performance for archives that
contain large binary files.
Viewing and Editing Revision Information
Source Integrity maintains detailed information for each revision in
an archive. In the Windows interface, this revision information is
displayed in columns in the Archive window. It can also be viewed
and modified with the Revision Information command.
To view and edit revision information in the Windows interface:
1. Select a revision in the Archive window.
2. Choose Archive > Revision Information, or click .
The Revision Information dialog box appears.
178 Source Integrity Professional Edition

Viewing and Editing Revision Information
3. View or make changes to the archive information.
4. Click OK to accept your changes, or Cancel to close the dialog box
without making changes.
Any changes you make are reflected in the Archive window.
You can view, but not change, the following revision information:
Revision. The revision number of the selected revision.
Date. The revision timestamp.
Author. The name of the user who checked in the revision.
Locker. If the revision is locked, the name of the user who owns
the lock appears here, as well as the date and time locked.
You can edit the following options:
State. The revision’s state appears here. You can assign a state to
any revision, indicating the status of its content.
Label. A list of labels assigned to the revision. When you check in
a revision you have the option of assigning it a revision label.
Labels allow you to describe a revision more fully than the
revision number alone can do. Although revisions in the same
archive cannot have identical labels, labels can be used to crossreference
revisions in different archives.
Revision Description. When you check in a revision, you can enter
a free-form description of its purpose and function. This
description can be used to provide context for the changes made
to a file and is especially helpful in multi-user projects. You can
append new comments onto a revision description. The date and
user name are also included.
User Guide 179

Managing Archives and Revisions
For more information on
using active issues, see
“Integrated Version Control”
on page 437.
Viewing
Revision
Metadata With
Archive
Commands
Active CI Issue. An active issue associated with the member
revision. Active issues appear as hyperlinks with a brief
description. To view the complete issue in the Change Integrity
Web interface, click on the hyperlink.
You can view archive and revision metadata with the rlog command
(there is an similar project command, pj rlog). Its syntax is
rlog [options] file…
where options is zero or more modifying arguments, and file is the
name of one or more files whose metadata you want to see. The file
entry may point to either working files or archives.
When it is run with no options, the rlog command shows you all the
archive and revision information contained in an archive.
You can choose to view only archive related metadata by specifying
the -t or -h options to the rlog command. Source Integrity can
display the following pieces of information about each archive:
name of the archive
name of the associated working file
revision number of the head revision
number of the default branch (if defined)
archive’s locking policy (strict or non-strict)
names of users with locks on revisions
names of users on the archive’s access list
any labels assigned to revisions in the archive
comment leader symbol
total number of branches in the archive
total number of revisions in the archive
total number of branch revisions
archive’s file format (text or binary)
archive’s delta storage format (RCS or Reference)
archive description
Example
For example, to see all the metadata about the prog.c archive and the
revisions it contains, you would enter
rlog prog.c
180 Source Integrity Professional Edition

Viewing and Editing Revision Information
The information displayed by this command would look something
like the following (some text is wrapped):
Archive file: C:/dev/prog\rcs\prog.c;
Working file: C:/dev/prog/stories.txt
head: 1.2
branch:
locks: SIUSER: 1.2; strict
access list:
symbolic names: Dev_1: 1.2;
comment leader:
total revisions: 2; branches: 0; branch revisions: 0
file format: text
revision storage: RCS reverse deltas
project: C:/dev/prog/project.pj;
description:
This archive contains the routines for the product
demo.
--------------------------revision
1.2 locked by: SIUSER;
date: 1998/06/09 18:38:44; author: SIUSER; state: Exp;
lines: +4 -0
Added some features
--------------------------revision
1.1
date: 1998/06/09 15:31:01; author: SIUSER; state: Exp;
Initial revision
--------------------------selected
revisions: 2
====================================================
The first fourteen lines show the archive information, including the
names of anyone who holds a lock on a revision, any labels in use,
and the archive description.
The remainder of the message shows metadata for each revision in
the archive, including its timestamp, state, locker, and revision
description. The information for each revision is separated by lines of
dashes to make them easier to read.
The last line of the rlog message shows the total number of revisions
about which information was displayed (in this case, all of them).
To see only the archive information for the prog.c archive, use the -t
option with rlog.
The -h option presents an abbreviated version of the archive
information, leaving out the archive description.
User Guide 181

Managing Archives and Revisions
Locked
Revisions
The -H option restricts rlog output to information about the head
revision of an archive.
The -T option restricts rlog output to one line with basic information
about the archive.
For example, the command
rlog -HT prog.c
returns the message
C:/dev/prog/prog.c 1.4 1995/05/29 10:46:40 SIUSER
Release_1
To determine which archives are currently undergoing change, you
can look for those archives that contain locked revisions. This is
accomplished with the -L[locker1[,locker2]] option to the rlog
command.
The -L option can be used alone, or modified with the names of one
or more users. If it is used without user names, it presents archive and
revision information for only those archives that contain locked
revisions.
For example, if you run the command
rlog -L *
rlog shows archive and revision information for every archive that
contains one or more locked revisions. It produces the same long
output displayed by rlog with no options.
If one or more user names are specified with the -L option, rlog
presents information for only those archives with revisions locked by
the named users.
For example
rlog -Lsiuser *
shows information for only those archives “Siuser” holds a lock in.
Note The information returned by rlog can be abbreviated by including
the -T option: rlog -TLsiuser *
182 Source Integrity Professional Edition

Assigning Labels to Revisions
Assigning Labels to Revisions
Labels are unique text that describe and refer to a revision in an
archive. Labels can be based on the product release the revision was
included in, on the content of the revision, on changes made to the
revision, or any other sort of information that would be useful in
identifying that particular revision.
Although you generally assign a label to a new revision upon check
in, there may be times when you want to add an additional label, or
change the label assigned to a revision.
To view, add, change, or delete a revision’s label (or view or
change a revision’s state) in the Windows interface:
Use the Revision Information dialog box, as described in “Viewing
and Editing Revision Information” on page 178.
To add a label to a revision in the Source Integrity Web Interface:
1. Switch to the Member view for the selected member.
2. Select the revision you want to add a label to, and select Add
Label from the list of available commands.
To delete a revision’s label in the Source Integrity Web Interface:
1. Switch to the Member view for the selected member.
2. Select the revision with the label you want to delete, and select
Delete Label from the list of available commands.
To add a label to a revision in the command line interface:
Use the -nlabel[:rev] option to the rcs command. Its syntax is
rcs [options] [-nlabel[:rev]] [-P[projname]] file…
where label is a unique revision label to assign to revision rev of file,
and where rev is number of the revision label will be assigned to. If
:rev is omitted, label is deleted from the archive of file.
If label is already associated with another revision in the archive, rcs
returns an error.
For example, to add the label “Release_1” to revision 1.3 of the
prog.c archive, you would enter
rcs -nRelease_1:1.3 prog.c
User Guide 183

Managing Archives and Revisions
When the revision is updated with the new label, the rcs command
displays the message
done
To assign a revision label to the head revision, simply specify the
revision label followed by a colon (omitting the revision number).
rcs -nRelease_1: prog.c
To add a label that contains a space, place quotation marks around
the label text.
rcs -n “Release 1.x”:1.4 prog.c
To delete a label from a revision in the command line interface:
Use the -n option to the rcs command.
For example, to delete the label “working” from the betting.c
archive in the project.pj project, enter
rcs -Pproject.pj -nworking betting.c
Viewing and Editing the Working File or
Revision
When an Archive window is open in the Windows interface, you can
view the contents of the working file or any revision in the list by
double clicking it, or by selecting it and choosing the View Revision or
View/Edit Working File command from the Archive or context menu, or
from the toolbar.
When the Archive window selector bar is over the working
file, the View Revision command in the Archive menu changes
to Edit Working File (or View Working File if it is read-only).
To display a file or revision, the View Revision command launches
your default editor and loads the working file or revision. The editor
that gets launched depends on your Personal Configuration.
Although it can be used to show the contents of any revision in an
archive, this command is best used with the working file, since it
provides a mechanism to open and edit the file without leaving the
Source Integrity application environment.
184 Source Integrity Professional Edition

Promoting and Demoting a Revision
When you view a revision, Source Integrity copies the revision to a
read-only temporary file and opens it for you.
Note The temporary file is not the revision. If you make changes to the
file and want to save it, you must give it a new file name since the
original revision is read-only.
To view a working file in the Source Integrity Web Interface:
Select the working file from the Sandbox view and choose Member
Commands > View.
To view a revision in the Source Integrity Web Interface:
Select the revision in the Member view and choose Commands > View.
Promoting and Demoting a Revision
If promotion is turned on, you can promote a revision to the next
state of development or demote it to a lower state.
In the Windows interface, if you select more than one member and
promote or demote them, the state change is based on the first
selected member. If the selected members are at different states from
the first member, all members are brought to the new state.
To promote a revision in the Windows interface:
1. Select a revision in the Archive window.
2. Choose Archive > Promote Revision.
The Promote Revision dialog box appears.
3. Select a new promotion state from the Promote to state dropdown
list.
User Guide 185

Managing Archives and Revisions
4. Click OK to accept the new promotion state.
To close the dialog box without changing the revision’s state,
click Cancel.
To demote a revision in the Windows interface:
1. Select a revision in the Archive window.
2. Choose Archive > Demote Revision.
The Demote Revision dialog box appears.
3. Select a new promotion state from the Demote to state drop-down
list.
4. Click OK to accept the new promotion state.
To close the dialog box without changing the revision’s state,
click Cancel.
To promote or demote a revision in the Source Integrity Web
Interface:
Select a revision from the Member view and choose Promote or
Demote.
To promote or demote a revision in the command line interface:
Use the rcs command with the -s option. Its syntax is
rcs -sstate[:rev]
where rev is the revision number and state is the state. If rev is a
branch number, the latest revision on that branch is assumed. If rev is
omitted, the latest revision on the default branch is assumed.
186 Source Integrity Professional Edition

Locking Revisions
Unlocking Revisions
Locking Revisions
Revisions are normally locked at check-out time, but you can lock a
revision without checking it out of the archive. Locking a revision
ensures you alone are allowed to modify the revision.
To lock a revision in the Windows interface:
1. Select a revision in the Archive window.
2. Choose Archive > Lock Revision.
A padlock symbol ( ) appears next to the revision number to
inform you the revision is locked, and your user name appears in
the Locker column.
To lock a revision in the Source Integrity Web Interface:
Select it in the Sandbox or Member view and choose Lock.
To lock a revision in the command line interface:
Use the rcs command with the -l option. Its syntax is
rcs -l[rev]
where rev is the revision number. If a branch is given, the latest
revision on that branch is locked. If rev is omitted, the latest revision
on the default branch is locked. Locking prevents overlapping
changes.
You can also unlock a revision without checking it back into the
archive, but you will lose any changes you have made to the locked
revision.
If you attempt to unlock a revision that is locked by another user, a
message warns you that you are about to break someone else’s lock.
Breaking another user’s lock on a system that is enabled with
User Guide 187

Managing Archives and Revisions
Microsoft’s Messaging Application Program Interface results in a
mail notification dialog box that lets you send email to the user
whose lock you are breaking.
Note Although you may not be prohibited from breaking some else’s
lock, you should be cautious about doing so, since it can result in
confusion and duplication of effort in shared working environments. For
information on permissions, see “Security and Administration” on
page 34.
To unlock a revision in the Windows interface:
1. Select a locked revision in the Archive window, one that has a
padlock symbol ( ).
2. Choose Archive > Unlock Revision or click .
The padlock symbol and the name of the user who had the
revision locked both disappear.
To unlock a revision in the Source Integrity Web Interface:
Select a locked revision in the Member, Sandbox, or Project views and
choose Unlock.
To unlock a revision in the command line interface:
Use the rcs command with the -u option. Its syntax is
rcs -u[rev]
where rev is the revision number. If a branch is given, the latest
revision on that branch is unlocked. If rev is omitted, any revision
locked by the user is unlocked. If no such revision exists, the most
recent lock that has been set is removed, if there is one.
188 Source Integrity Professional Edition

Deleting Revisions
Deleting Revisions
If you know you will not use a revision again, you can delete it.
Caution Only delete a revision when you are absolutely certain you
will never need it again. Once you delete a revision, it cannot be
retrieved. A revision cannot be deleted if it locked or the starting point
(root) of a branch. You should never delete the head revision of an
archive.
To delete a revision in the Windows interface:
1. In the Archive window, select one or more revisions that you
want to delete.
2. Choose Archive > Delete Revision.
A message box asks you to confirm the deletion.
3. To remove the selected revision(s), click Yes or Yes to All.
Source Integrity removes the revision(s) from the archive and
updates the Archive window to show the revision(s) have been
deleted from the archive.
To remove the message box without deleting any revisions, click
No or No to All.
To delete a revision in the Source Integrity Web Interface:
Select the revision in the Member view and choose the Delete
command.
To delete a revision in the command line interface:
Use -o option to the rcs command. Its syntax is
rcs -o[range] file…
where range specifies the revisions to be deleted, and file is one or
more archives. The range modifier can take one of four forms:
rev is the number of the revision to delete. For example, to delete
revision 1.2 in the archive prog.c, enter
rcs -o1.2 prog.c
User Guide 189

Managing Archives and Revisions
Comparing Revisions
rev1-rev2 deletes all revisions from revision number rev1 to
revision number rev2, inclusive, provided they are all on the same
branch. For example
rcs -o1.2-1.4 prog.c
deletes revisions 1.2, 1.3 and 1.4 in the archive prog.c.
rev1- deletes all revisions from rev1 to the end of the branch. If the
tip revision of the branch is 1.2.1.3, the command
rcs -o1.2.1.2- prog.c
deletes revisions 1.2.1.2 and 1.2.1.3 in the archive prog.c.
-rev2 deletes all revisions from the beginning of the branch
containing rev2, up to and including revision number rev2. For
example
rcs -o-1.2.1.3 prog.c
deletes revisions 1.2.1.1, 1.2.1.2 and 1.2.1.3 in the archive prog.c.
When you are working with an evolving body of source files, you
must be able to compare two files to see exactly how one differs from
another. This can become necessary when you are developing on a
branch or new development path, or when two people are working
independently on the same problem.
With Source Integrity you can compare
any two text-based revisions in an archive
a text-based revision and its associated working file in a sandbox,
project, or archive
any two text files
The commands discussed in this section use the Visual Difference
utility, which calculates the differences between files or revisions and
displays them side by side in their own window, along with a
summary of the differences between them. Using the Visual
Difference utility, you can also interactively merge two files or
revisions.
Unlike most features of Source Integrity, the Visual Difference utility
is not presented in the application window, but is a standalone
Windows application that compares and merges files and revisions.
190 Source Integrity Professional Edition

To compare two revisions in the Windows interface:
Comparing Revisions
1. Select two revisions, or a revision and the working file from an
Archive window. To select two revisions, select the first revision
as usual, then hold down the key and click a second
revision.
2. Choose Archive > Differences > Compare, or click .
The Visual Difference utility appears. Both revisions and a
summary of the differences between them are shown in the
Visual Difference window.
To compare two revisions in the Source Integrity Web Interface:
In the Member view, select two revisions and choose Compare Two
Revisions.
To compare two revisions in the command line interface:
Use the rcsdiff command. See the Source Integrity Professional
Edition Reference Guide or the online command reference for the full
syntax.
User Guide 191

Managing Archives and Revisions
Merging Revisions
You can also use the Visual Difference utility to merge two revisions.
To merge two revisions in the Windows interface:
1. Select two revisions, or a revision and the working file from an
Archive window. To select two revisions, select the first revision
as usual, then hold down the key and click a second
revision.
2. Choose Archive > Differences > Merge, or click .
The Visual Difference utility appears. Both revisions and a
summary of the differences between them are shown in the
Visual Difference window.
To merge two revisions in the Source Integrity Web Interface:
1. Switch to the Sandbox view (if you are not already there).
A delta symbol appears next to the member revision in the
Sandbox, signaling that the revision in your Sandbox does not
match the member revision in the Project (because you checked
out a previous revision and therefore made it the current revision
in your Sandbox).
2. Select Merge from the list of available commands.
The Merge Working File dialog box appears, displaying the name
of the current member, and the full path of the sandbox it is a
member of.
3. Confirm that you want to merge the working file with the
member revision by clicking Yes in the Merge Working File dialog
box.
Source Integrity Web Interface invokes the Visual Difference
utility to display the differences between the two working files
side-by-side.
In both the Windows interface and Source Integrity Web Interface, a
working file delta now appears next to the revision in the Sandbox
view, signaling that the working file has changed as a result of the
merge. To preserve these changes, check them in as a new revision in
the member’s archive.
192 Source Integrity Professional Edition

Logging Archive Transactions
To merge two revisions in the command line interface:
Use the rcsmerge command. See the Source Integrity Professional
Edition Reference Guide or the online command reference for the full
syntax.
Logging Archive Transactions
For information about logging
project transactions, see
“Logging Project
Transactions” on page 142.
Source Integrity keeps track of the transactions it performs upon
archives, as long as you have a log file named in the SAM database
or your personal configuration.
Most sites turn it on within SAM to ensure standard logging
procedures are applied site wide. By default, logging is turned off. To
have it turned on site wide, contact your SAM administrator.
This archive transaction log includes contains a record of all check-in
and check-out (locked) operations on revisions of archives.
Note This functionality is not available in the Source Integrity Web
Interface.
To enable logging locally in the Windows interface:
1. Choose Configuration > Personal and click the Logging tab.
2. Select the Enable Logging checkbox.
3. Enter the name of the log file in the Filename box. The name can
be fully qualified or relative to the current directory. Using a fully
qualified, absolute file name ensures only one log file is created to
log Source Integrity operations.
4. Click OK to accept these settings, or Cancel to close the dialog box
without making any changes.
To enable logging locally in the command line interface:
Use the pj set command as follows:
pj set “logfile=filename”
where filename is either fully qualified or relative to the current
directory. Using a fully qualified, absolute file name ensures only one
log file is created to log Source Integrity operations.
User Guide 193

Managing Archives and Revisions
Log File Format
You can also insert the following line in your local configuration file
(rcs.rc or rcs.c):
logfile=filename
Each archive transaction recorded in a log file occupies a single line,
or record. Information within each record is divided into fields, each
describing one aspect of the archive transaction.
You can customize logfile records with the LogFormat configuration
option in SAM or in your personal configuration.
By default, archive transactions contain six fields.
Field Description
Field 1 The operation performed (for example, ci or co, same
for command line interface, Windows interface, or
Source Integrity Web Interface).
Field 2 The user’s login name.
Field 3 The revision number affected by the command.
Field 4 The name of the affected archive.
Field 5 The current date and time in the format
yyyy.mm.dd hh:mm:ss
Field 6 The name of the person who holds the lock on the
affected revision.
This corresponds to the default LogFormat value of
%C %u %r %f %D %l
Typical output from this initial setting appears as
ci siuser 2.4 prog.c 1999.03.12 14:21:32 siuser
You can alter the LogFormat value to record different information.
For example, the following LogFormat statement could be used to
record the command that was executed, the archive file name and
revision number involved, and the date of the revision.
LogFormat=%C: %f Rev %r on %d
The output from this entry would appear as
ci: prog.c Rev 2.4 on 99/06/12 09:21:32
194 Source Integrity Professional Edition

Cleaning Up
Log Files
Cleaning Up Working Files
For a detailed description, see
the online reference for the
rcsclean command.
Cleaning Up Working Files
The easiest way to clean up a log file is to delete the file. Source
Integrity automatically creates a new one the next time it records an
archive transaction. You can also open the log file in a text editor and
delete transaction records. For instance, you could delete transaction
records that are greater than a particular number of days or weeks
old.
The rcsclean command compares the most recent revision of a file
to its working file and deletes the working file if it has not changed
since it was checked out. To clean up unused working files in a
sandbox or project, use pj clean.
The syntax for rcsclean is
rcsclean file…
where file is one or more files to be examined.
Source Integrity normally makes a working file writable when you
have a lock on the revision it was generated from. If rcsclean finds
the working file is read-only, it assumes you do not have a lock on the
revision and so removes the working file, if it has not changed. If you
had explicitly locked the revision (using pj lock or rcs -l),
rcsclean will not clear this lock.
Note This functionality is available only in the command line interface.
User Guide 195

Managing Archives and Revisions
Storing Binary Files in Reference Format
If you want to store large binary files in your archives, using Source
Integrity’s traditional RCS archive format will result in very large
archives and decreased performance. When storing binary files in
archives, you should use the Reference archive format instead. With
the Reference format, Source Integrity stores complete revisions
instead of just deltas between revisions. It also stores each revision in
a separate file; the archive itself contains only header and summary
information. Archives stored in this format require more disk space,
but have improved performance.
To change archive formats in the Windows interface:
Select the Store By Reference option in the Archive Information dialog
box.
To change archive formats in the command line interface:
Use the rcs command to change archive formats.
rcs -S RCS|Reference file
196 Source Integrity Professional Edition

Using Extensions
For instructions on installing
extensions and a complete list
of the supported host
environments, see the Source
Integrity Professional Edition
Administrator Guide.
7
Source Integrity Extensions transparently blend the Source Integrity
functionality into the Integrated Development Environments (IDEs)
you use, allowing you to work within your favorite development
environment. Source Integrity Extensions enable you to access the
functionality available in the core product, right from within the host
environment.
This chapter explains how Source Integrity interacts with your IDEs,
and gives more specific information about interacting with the
following host environments:
Microsoft Developer Studio 97 (Visual C++, Visual J++, Visual
Basic, Visual FoxPro)
Borland Delphi and 3.0 and 4.0
Microsoft Windows Explorer
User Guide 197

Using Extensions
Introduction to Source Integrity Extensions
Source Integrity Extensions provide seamless access to many
features, including:
Create Project
Take files that form a single body of work and group them in a
related project. Source Integrity’s project-oriented approach to
configuration management makes it easier to control the
evolution of your files.
Create Sandbox
A reflection of the master project, a sandbox provides a way for
you to work in a personal, protected workspace without
interfering with the master project. This way, changes can be
made and tested before being merged into the master project.
Create Variant Sandbox
If you want to work with a particular revision of the project to
maintain past releases of a product, you can create a variant
sandbox and work without interference on your own
development path.
Add Members
Manage files not in the IDE project. Help files, databases, and
other related files can be added to the same project as your IDE
files.
Check In
Add a new revision of the file to its archive. The new revision
becomes the archive’s head revision unless you check in the file
to a revision other than the head revision, in which case a new
branch is created. For IDEs that have associated files such as .FRM
and .FRX files in Visual Basic, or .DFM and .PAS files in Borland
Delphi, Source Integrity ensures all related files are checked in
and out together.
Check Out
Extract the contents of a revision in an archive and copy it to a
working file. Any revision can be checked out by its revision
number or label. After being checked out, working files are
automatically reloaded in the host environment or IDE.
Configuration
Customize the Extensions to work the way you want them to
work, right from within each host environment or IDE. For
example, you can decide whether or not the Check Out command
198 Source Integrity Professional Edition

The Project
Window
Introduction to Source Integrity Extensions
automatically checks out the selected files, or if a dialog box is
displayed for each file, allowing you to check out old revisions.
Run Source Integrity
If you require functionality not available through the Source
Integrity extensions, open the Source Integrity application with
the Source Integrity project associated with your current IDE
project already loaded.
Context-sensitive Help
Get Help for individual controls and fields within each dialog
box. You can also choose to view useful hints as your mouse
pointer passes over dialog box fields and functions.
The Source Integrity Project Window gives you control over the
Source Integrity Project associated with your current IDE project,
from within the IDE. Operations on the Source Integrity project and
its members are synchronized between the Source Integrity project
window and the IDE, allowing you to focus on the Source Integrity
project without losing touch with the related IDE project. The tool bar
provides quick access to the most commonly used functions in the
Source Integrity project window.
If you want to hide the toolbar while you work on your IDE project,
de-select Toolbar in the View menu. Simply select Show Toolbar to
display the toolbar once again.
The project window contains a list of members in the sandbox or
project, with fields you can easily sort. Source Integrity subprojects
are now supported within the extensions, allowing you to treat a
Source Integrity project as a member of the current project.
User Guide 199

Using Extensions
Using Filters Within the Project Window
As your Source Integrity projects grow, you will find it increasingly
difficult to find and select the specific members you need to work
with at a given time. In addition to sorting by fields, the project
window offers an optional drop-down list of built-in filters that allow
you to focus your view on a particular subset of project members you
are currently interested in. Once you select a particular filter, only
those members that meet the criteria specified by the filter are
displayed.
Here is a list of the built-in filters provided, and what it means to
apply each of them.
All Members displays all members in the current project or
sandbox (the default).
Modified Members displays all members that have a working file
that has been modified.
Out-Of-Synch members displays all members whose member
revision is not currently at head revision.
Locked displays all members that are currently locked.
Locked By Me displays all members that are currently locked in
your name.
Frozen Members displays all members that are currently frozen.
Subprojects displays all members that are projects themselves.
Members With Label displays all members that currently have a
particular label associated with them. After choosing this filter,
specify the label you want to base your selection on by selecting it
from the drop-down list of available labels.
Members With State displays all members that are currently
associated with a particular state. After choosing this filter,
specify the state you want to base your selection on by selecting it
from the drop-down list of available states.
200 Source Integrity Professional Edition

Introduction to Source Integrity Extensions
The member list provides the following information on each member:
Field Description
Type Project members may be one of three file types:
Archived (under revision control)
Non-Archived (not under revision control); nonarchived
members can only be added from within
the Source Integrity application
Subproject
If you freeze a member, a snowflake alerts you to the
state of the file. The description “Frozen Member” also
appears at the bottom of the window. Freezing prevents
member information from being updated. Thawing
removes the frozen state so changes can again be
made to the project file or member information.
When there is a delta symbol in a member listing, this
means the member’s archive or working file has
changed.
This delta symbol means your working file has
changed.
This delta symbol means the member archive has
later revisions available.
A question mark in the delta field means the member
has not been scanned for changes, a Configuration
option in the Preferences panel. Select the member and
choose Member > Scan For Changes to search for
any changes to the member archive or working file, or
choose Window > Refresh to scan all members of a
project for changes.
Member Name The full path name of the member’s working file.
Locked If the member revision is locked, the name of the
locker appears beside a padlock symbol.
Revision The revision number associated with the member
revision in your sandbox or master project.
State The development state associated with the member
revision.
Labels Any labels assigned to the member revision.
User Guide 201

Using Extensions
The Information Area below the list of members displays information
about a selected member. For example, if the member revision’s
working file has been updated but not checked in, a message alerts
you that the working file is newer than the member revision. Other
information displayed includes: locker name, member frozen, and
member not scanned for changes.
If you want to hide this Information Area while you work on your
IDE project, de-select Information Area from the View menu.
Member Menu Commands
The Member menu contains commands that act upon members.
Member-specific functionality is also accessible using the right-click
context menu. Select a member and click your right mouse button to
display a pop-up menu of actions you can perform on the selected
item.
Note Commands that are not available in the SCC Project window are
marked with the text “Not in SCC” in the margin.
Not in SCC. Check In checks in all selected files to their archive, provided they
are locked by you.
Not in SCC. Check Out checks out all selected files. If you already have a
selected file checked out, you will be asked if you want to
overwrite your working copy. If you choose to do so, any changes
made in your original working copy will be lost.
Not in SCC. Undo Checkout unlocks a revision that was previously checked
out locked (in your name), and resynchronizes it, so the working
file once again reflects the member revision.
Not in SCC. Resynchronize reverts selected files you have checked out to their
state prior to modification and reflects the change in your IDE.
Select selects all, locked, or changed members.
Label adds a label to the member revision of the selected file. If
multiple files are selected for this operation, the label chosen will
apply to all files.
Differences opens the Visual Difference utility on the selected text
file. You can determine where the file has changed since check
out, by displaying a side-by-side comparison of the selected file
with another revision.
202 Source Integrity Professional Edition

Introduction to Source Integrity Extensions
Not in SCC. Unlock removes a lock you own from the member revision of a
selected member without changing the member revision or
working file.
Scan for Changes scans selected members to search for any
changes to the member archive or working file. If
Source Integrity detects changes in either the member archive or
working file, the appropriate delta symbol appears next to the
changed member.
By default, Source Integrity scans each project member to search
for changes. You can disable this feature by de-selecting the Scan
Members on Open Project/Sandbox option in the Preferences
panel of the Personal Configuration dialog box.
Upon opening a project or sandbox with this option disabled,
Source Integrity displays a question mark in the delta column,
and reports “Member not scanned for changes” in the
Information Area at the bottom of the Project window.
Choose Window > Refresh to scan all members of a project for
changes.
Open Member Archive opens a member’s Archive window,
allowing you to view and compare all revisions.
Member Information opens a dialog box that displays the project
or sandbox the member is a part of, and the full path of both the
working file and archive location.
You may also use the Member Information dialog box to append
the Revision Description associated with the revision, and add,
edit, or delete labels associated with the revision.
Member Report opens a window that presents information stored
in the archive about the selected member. See who created a new
revision, when it was created, its state, any labels assigned to the
revision, the master project or sandbox it is a part of, and the full
path of the archive location.
Open Subproject displays the members of the selected subproject
in the Project window.
Promote promotes the state of the selected member revisions to a
state you choose. You must define the promotion states in
Personal Configuration (Promotion panel) in order to make them
available in the Promote Member dialog box’s drop-down list.
Your SAM administrator can also define promotion states.
This command is available only when promotion is enabled in
Configuration.
User Guide 203

Using Extensions
Demote demotes the state of the selected member revisions to a
state you choose. You must define the promotion states in
Configuration (Promotion panel), in order to make them available
in the Demote Member dialog box’s drop-down list.
This command is available only when promotion is enabled in
Configuration.
Freeze freezes the member in its current state to prevent changes
being made to the member revision. For example, you cannot
update the member revision or change the member type for a
frozen member. You can still check in and check out frozen
members, but the member revision in the master project or
sandbox will not change.
Thaw removes freezing so changes can be made to the member
revision in the master project or sandbox.
Not in SCC. Lock locks the member revision of selected members, without
changing the member revision or working file (that is, without
checking out the revision to a working file). This prevents others
from modifying the file.
Not in SCC. Unlock removes a lock from a revision without checking it in (and
thereby creating a new revision). Since strict locking is enforced
in the IDE Extensions, you can only remove a lock you own. By
removing a lock on a file that is checked out and modified, you
risk losing these modifications. If the file is checked out again
before it is checked in, the user receives the unmodified revision.
Not in SCC. Remove Unused Locks removes any locks you own from files that
have not changed since you locked them. This allows you to
safely free up files for other people to work on.
Not in SCC. Update to Tip Rev, for all selected members, replaces the member
revision with the latest revision in the branch your member
revision is on.
Not in SCC. Update to Head Revision, for all selected members, replaces the
member revision with the latest revision from the main branch of
that member’s archive.
Project Menu Commands
All of these commands appear in the SCC Project window.
Open Project Archive opens the current project’s Archive window,
allowing you to view and compare project revisions.
Checkpoint Project saves the current state of your project. You can
restore it later by creating a variant sandbox.
204 Source Integrity Professional Edition

Introduction to Source Integrity Extensions
Project Information displays the master project name, the project
name, the number of members, the number of locked members, a
project description, and a list of development paths.
Project Report opens a window that displays information stored
in the archive about the Source Integrity project.
Promote Project promotes the state of the project to a state you
choose.
Demote Project demotes the state of the project to a state you
choose.
Freeze Project freezes a project in its current state. You cannot add
or remove project members, or change Configuration settings for
a frozen project. You can still check out and check in members of
a frozen project, but the member revision in the master project or
sandbox will not change.
Thaw Project removes freezing so changes can be made to the
project.
Add Members allows you to add files to the Source Integrity
project.
Remove Members removes the member selected in the member
list from the Source Integrity project. The working file and the
member archive remains, but the file is no longer treated as part
of the project.
Open Parent opens the parent project associated with the
subproject currently selected in the Project window.
Window Menu Command
Refresh updates both the Project Window and any files open in
your IDE with the latest information.
Right-click a project member or revision to display a pop-up menu of
actions you can perform on the selected item.
User Guide 205

Using Extensions
The Archive
Window
When you open an archive, Source Integrity displays information
about the revisions in the archive. The Archive window contains a
selectable list with entries for the working file (if one exists), and each
revision in the archive.
The toolbar provides quick access to the most commonly used
functions in the Archive Window. If you want to hide the toolbar
while you work on your IDE project, de-select Toolbar in the View
menu.
In the Archive window, you can view and compare revisions, as well
as launch the Source Integrity application. Right-click on an archive
revision in an Archive window to display a pop-up menu of actions
you can perform on the selected item.
206 Source Integrity Professional Edition

Introduction to Source Integrity Extensions
Each entry in the list contains information about a single revision in
the archive. This information is displayed in columns with the
following heading:
Column Description
Revision Revision number.
Author User who checked in the revision.
Date Date and time the revision was checked in.
Locked User name of the person who locked the revision.
State Revision’s state setting.
Labels Labels attached to the revision.
The Information area below the list of revisions displays the Revision
Description for the currently selected revision.
If you want to hide the toolbar while you work on your IDE project,
de-select Toolbar in the View menu.
The first entry in the Archive Window is the archive’s working file (if
one exists). The entry shows the path name of the working file.
If the working file can be edited, the entry is preceded by a pencil
icon ( ). If the working file is read-only, the pencil icon is crossed
out in red.
User Guide 207

Using Extensions
Archive Menu Commands
Note Commands that are not available in the SCC Archive window are
marked with the text “Not in SCC” in the margin.
Not in SCC. Check In checks in the selected working file to an archive,
provided the revision is locked by you.
Not in SCC. Check Out checks out the selected revision from its archive,
provided the revision is not locked by someone else. If you
already have a revision checked out, you will be asked if you
want to overwrite your working copy. If you choose to do so, any
changes made to your original working file will be lost.
Not in SCC. Undo Check Out unlocks a revision that was previously checked
out locked (in your name), and resynchronizes it, so the working
file once again reflects the member revision.
View Revision displays the contents of the selected revision in its
associated application (for example, Notepad).
Compare Revisions opens the Visual Difference utility and
displays a side-by-side comparison of the selected revisions. This
allows you to visually determine the differences between the two
revisions. You can also compare the working file to a revision by
selecting the working file and a revision.
Not in SCC. Lock Revision allows you to place a lock on the selected revision,
without checking it out of the archive. This prevents others from
modifying the revision.
Not in SCC. Unlock Revision removes a lock from a revision without checking
it in to the archive (and thereby creating a new revision). Since
strict locking is enforced in the IDE Extensions, you can only
remove a lock that you own. By removing a lock on a revision
that is checked out and modified, you risk losing these
modifications. If the revision is checked out again before it is
checked in, the user receives the unmodified revision.
Set Default Branch opens a dialog box in which you can set the
default branch to which Source Integrity will check in your files.
View Menu Commands
The following commands appear in the SCC window:
Stay On Top causes the Archive Window to remain visible while
you work on your IDE project.
208 Source Integrity Professional Edition

Using the Extensions
Using the Extensions
Tool Bar displays the Archive Window toolbar, which provides
easy access to the most commonly used archive commands.
Information Area shows the area below the list of revisions, which
displays information about a selected revision.
Window Menu Command
Refresh gets the latest archive and working file information and
updates the Source Integrity Archive window.
Follow these basic steps to use Source Integrity:
1. Create a Source Integrity project.
Add your IDE project to source control by creating a
Source Integrity project using the IDE.
2. Add project members.
Add IDE project files to the Source Integrity project.
Source Integrity automatically checks in and creates an archive
for each file added.
3. Check out files as you need them.
Source Integrity creates a working file from the selected revision
in the archive.
4. Make changes to the project members from within the IDE.
5. Check in modified files.
This creates a new revision in the member’s archive. The new
revision becomes the archive’s head revision unless you
specifically check in the file to a revision other than the head
revision. When you check in a file to a revision other than the
head revision, a new branch is created.
User Guide 209

Using Extensions
Differences Between Extensions and
Source Integrity
Creating
Projects
When you create a master project, you should create the project at the
top level of the directory tree that contains your files. Source Integrity
projects work best when all project members reside in a single
directory tree under the project directory.
With Source Integrity
As you create a new project, you can also create a sandbox, add
members, and create archives for both the project members and the
project itself. Source Integrity wizards now lead you through the
process of creating projects and sandboxes.
Once you select a project location and enter the full path names of the
new project and sandbox, the remainder of the Create Project dialog
box is used to add members to the new project, and to create archives
for both the project and its new members.
With the Extensions
When you create a Source Integrity project using the Extensions, the
process is different. The Source Integrity project or sandbox is
automatically created in the same directory where your IDE project
resides.
Notice that the Create Project dialog box is different.
1. Type an initial optional comment to associate with the new
Source Integrity project in the area provided.
2. Select one of two options for project creation:
210 Source Integrity Professional Edition

Differences Between Extensions and Source Integrity
Master Project Only creates a new Source Integrity project and
archive directory in the same directory as your IDE project.
Master Project and Sandbox creates a Source Integrity
sandbox in your current IDE project directory, and creates a
master project and archive in a directory of your choice. If
you choose this option, another dialog box appears,
prompting you for a Master Project Location.
The Add Project Members dialog box appears after having
determined the Source Integrity project’s location. It presents a
list of all files in the IDE project.
Note The dialog box that appears may differ slightly depending on the
IDE.
If there are files you do not want to place under version control, select
them and click Remove. If you want to add files to the
Source Integrity project that are not members of the corresponding
User Guide 211

Using Extensions
Creating
Sandboxes
IDE project, click Add to browse for and select these files. Once you
have the list of files you want, click OK. All listed files are archived
and added to the Source Integrity project.
You can create a sandbox for a project while you are creating the
project, but you can also create a sandbox later. Use the Create
Sandbox command.
With Source Integrity
Source Integrity wizards now lead you through the process of
creating projects and sandboxes.
With the Extensions
When you create a Source Integrity sandbox using the Extensions, the
process is different.
Notice that the Create Sandbox dialog box is different.
If you have a project open in the IDE that has an associated
Source Integrity project, the Master Project Name field will contain the
path to this master project. You may edit this field if you want to
create a sandbox for a different project.
1. In the Sandbox Location field, enter the directory path you want
to place your sandbox in.
Note Relative path names in the Sandbox Location field are taken in
relation to the path given in the Master Project Name field.
212 Source Integrity Professional Edition

Differences Between Extensions and Source Integrity
2. If you want to work with a particular project revision in the
sandbox, enable the Create Variant Sandbox check box. When you
click OK in this case, the Create Variant Sandbox dialog box
appears, wherein you may select a revision by number or by
label.
Sometimes you must include files in directories that are not part of
the master project directory tree. These files are called out-of-tree
members because they are located outside of the main directory tree.
Source Integrity normally places out-of-tree members in the root
directory of the sandbox (that is, the directory containing the
sandbox.pj file). However, in order to preserve relative path
associations, you have the option of specifying where the files in the
external directory should be placed in the sandbox.
When a sandbox is created from such a Master Project, the Create
Sandbox Directory dialog box appears.
User Guide 213

Using Extensions
If you have a project open in the IDE that has an associated
Source Integrity project, Master Project displays the path for this
master project.
Sandbox displays the name and path of the sandbox associated
with the current Source Integrity project.
Project Directory displays the name and path of the directory that
contains out-of-tree members (ones that are not part of the project
directory tree).
Fill in the Create Sandbox Directory dialog box as follows:
1. In the Sandbox Directory field, enter the full path where you want
to put files in this directory. If the specified directory does not
already exist, Source Integrity creates it for you.
2. Click Create to make the new directory. If you want
Source Integrity to place the out-of-tree members in the root
directory of the sandbox (as it would by default), click Skip.
Microsoft Visual Basic 5.0 and 6.0
This section describes how to access Source Integrity through
Microsoft Visual Basic 5.0 and 6.0.
Once you have installed the Source Integrity 32-bit SCC Extension,
opening a project in Visual Basic under source control automatically
loads its archive information.
Access version control functionality from within Visual Basic and 5.0
and 6.0 by selecting the menu item that corresponds to the
Source Integrity function you want to perform.
Menu Item Function
Get Gets the latest version of the selected file and
puts it in your working directory.
Check Out Checks out a revision of the currently active file
in the Visual Basic window, either locked (for
editing) or unlocked.
Check In Checks in the currently active file in the Visual
Basic window.
214 Source Integrity Professional Edition

Creating a
Source Integrity
Project
For more on creating
Source Integrity projects using
the extensions, see “Using the
Extensions” on page 209.
Menu Item Function
Microsoft Visual Basic 5.0 and 6.0
Undo Check Out Replaces the selected working file with the
revision that was checked out, as it appeared
prior to modification.
Open New MKS
Source Integrity
Project
Run MKS
Source Integrity
Add Project to
MKS Source Integrity
Creates a sandbox for the current or any other
Source Integrity project.
Invokes the Source Integrity application. If a
project is currently loaded, this command opens
the Source Integrity project window instead.
Opens the Create Project dialog box to bring
the current Visual Basic project under source
control.
Options Configures how Source Integrity will work, both
within Visual Basic and by itself.
The Source Integrity right-click context menu reveals the memberspecific
commands that you can perform on a selected file.
Even the Visual Basic Project window is enhanced with version
control features and indicators. For instance, a check mark beside a
file icon indicates the file is currently checked out. When a file is readonly,
a small lock appears next to the file icon in the project window.
To create a Source Integrity project in Visual Basic:
1. Open the Visual Basic project you want to put under version
control.
2. Choose Tools > MKS Source Integrity > Add Project to MKS
Source Integrity.
The Create Project dialog box appears.
User Guide 215

Using Extensions
Creating a
Sandbox
For more on creating
Source Integrity sandboxes
using the extensions, see
“Using the Extensions” on
page 209.
Checking Out
Files
To create a sandbox in Visual Basic:
Choose Tools > MKS Source Integrity > Open New MKS Source Integrity
Project.
The Create Sandbox dialog box appears.
To check out files in Visual Basic:
1. Bring any file(s) you want to check out into focus in the Visual
Basic environment. You may also select a file from the Visual
Basic project explorer: choose Check Out from the right-click
context menu and follow from Step 3.
2. Choose Tools > Check Out.
A list of all files that can be checked out appears.
You may choose additional files to check out from this list by
setting their check boxes.
Selecting a .frm file automatically selects the corresponding .frx
file. If you have selected Show Dialog in Configuration, the Check
Out dialog box appears. Otherwise, the member revision is
checked out.
3. Fill in or modify options in the dialog box as you like, and click
OK to check out the file. To cancel the check-out operation, click
Cancel. To cancel the operation for all files, click Cancel All.
A check mark beside a file icon indicates the file is currently checked
out.
216 Source Integrity Professional Edition

Checking In
New Revisions
To check in new revisions in Visual Basic:
Microsoft Visual Basic 5.0 and 6.0
1. Bring any file(s) you want to check in into focus in the Visual
Basic environment. You may also select a file from the Visual
Basic project window: choose Check In from the right-click
context menu, and follow from Step 3.
2. Choose Tools > Check In. A list of all files that can be checked in
appears.
You may choose additional files to check in from this list by
setting their check boxes. Selecting a .frm file automatically
selects the corresponding .frx file. If you have selected Show
Dialog in Configuration, the Check In dialog box appears.
Otherwise, each file is checked in with the next logical revision
number and no label.
3. Fill in or modify options in the dialog box as you like, and click
OK to check in the file. To cancel the check-in operation, click
Cancel. To cancel the operation for all files, click Cancel All.
A check mark beside a file icon indicates the file is currently checked
out.
User Guide 217

Using Extensions
The Microsoft Visual C++ 6.0 Extension
This section describes how to access Source Integrity through
Microsoft Visual C++, which is part of Microsoft Visual Studio.
Once you have installed the Source Integrity Microsoft Visual Studio
Extension, opening a project in Microsoft Visual C++ 6.0 under source
control automatically loads its archive information.
You can access version control functionality through the Source
Control sub-menu of the Project menu. Select the menu item that
corresponds to the Source Integrity function you want to perform.
Menu Item Function
Get Latest Version Gets the latest version of the selected file and
puts it in your working directory.
Check Out Checks out a revision of the currently active file.
Check In Checks in the currently active file.
Undo Check Out Replaces the selected working file with the
revision that was checked out, as it appeared
prior to modification.
Add to Source
Control
Remove from Source
Control
Adds the selected file to Source Control.
Removes the currently active file from
Source Integrity. Its member archive remains
accessible from the Source Integrity project.
Show Differences Invokes the Visual Difference utility to compare
the selected working file with the member
revision.
MKS Source Integrity
Properties
Configures how Source Integrity will work, both
within the different IDEs and by itself.
Refresh Status Updates the status and archive information of
the selected file.
MKS Source Integrity Invokes the Source Integrity program. If a
project is currently loaded, this command opens
the Source Integrity project window instead.
The Source Integrity right-click context menu reveals the memberspecific
commands you can perform on a selected file.
218 Source Integrity Professional Edition

Creating a
Source Integrity
Project
For more on creating
Source Integrity projects using
the extensions, see “Using the
Extensions” on page 209.
Creating a
Sandbox
For more on creating
Source Integrity sandboxes
using the extensions, see
“Using the Extensions” on
page 209.
Checking Out
Files
The Microsoft Visual C++ 6.0 Extension
The Microsoft Visual C++ 6.0 Project Workspace window is also
enhanced with version control features and indicators. For instance, a
file’s icon turns gray once the file is placed under version control, and
a red checkmark beside a file’s icon indicates the file is currently
checked out.
To create a Source Integrity project in Microsoft Visual C++ 6.0:
1. Open the project you want to put under version control.
(If you create a new project, you will be prompted to add it to
source control upon creation.)
2. Choose Project > Source Control > Add to Source Control.
The Create Project dialog box appears.
To create a sandbox in Microsoft Visual C++ 6.0:
1. Choose File > Open Workspace.
2. Click Source Control.
The Create Sandbox dialog box appears.
To check out files in Microsoft Visual C++ 6.0:
1. Bring one or more files that you want to check out into focus in
the Microsoft Visual C++ 6.0 environment.
2. Choose Project > Source Control > Check Out.
A list of the file(s) that you have selected appears.
User Guide 219

Using Extensions
Checking in
New Revisions
3. Once you have selected all the files you want to check out, click
OK. If you have selected Show Dialog in Configuration, the Check
Out dialog box appears for each file. Otherwise, the member
revisions are checked out.
4. Fill in or modify options in the dialog box as you wish, and click
OK to check out the file. To cancel the check-out operation, click
Cancel. To cancel the operation for all files, click Cancel All.
To check in new revisions in Microsoft Visual C++ 6.0:
1. Bring one or more files that you want to check in into focus in the
Microsoft Visual C++ 6.0 environment.
2. Choose Project > Source Control > Check In.
A list of the file(s) that you selected appears.
3. To associate a revision description with these files, enter one in
the space provided. If you want to keep the files locked after
checking them in, indicate so in the check box.
4. Once you have selected all the files you want to check in, click
OK. If you have selected Show Dialog in Configuration, the Check
In dialog box appears for each file. Otherwise, each file is checked
in with the next logical revision number and no label.
220 Source Integrity Professional Edition

Using Microsoft
Visual C++ 6.0
The Microsoft Visual C++ 6.0 Extension
5. Fill in or modify options in the dialog box as you like, and click
OK to check in the file. To cancel the check-in operation, click
Cancel. To cancel the operation for all files, click Cancel All.
Each Visual C++ Project file and workspace will have its own
Source Integrity project file, unless the workspace and project have
the same name. In that case, both the workspace and project will be
added to the same Source Integrity project, which is named after the
workspace.
So, you should create your workspace with a different name than the
project file that it will contain. This will keep each workspace and
project file separate for creating sandboxes.
Creating a Source Integrity Project
Create the Visual C++ workspace and the projects within it. Then,
create a Source Integrity project, first for your Visual C++ projects
and then for your workspace. Using the Source Integrity project
window, insert the Source Integrity projects for the Visual C++
projects into the Source Integrity project associated with the
workspace.
For example
n:\master\myproject\workspace.dsw
contains
n:\master\myproject\myproject.dsp
User Guide 221

Using Extensions
Associated with these will be:
n:\master\myproject\workspace.pj
n:\master\myproject\myproject.pj
Creating a Source Integrity Sandbox
When creating a sandbox, create it from workspace.pj and recurse
into the subprojects (that is, the Source Integrity projects for each
Visual C++ project). All the Visual C++ projects contained within the
workspace will be copied into your sandbox.
If you want to work with an individual Visual C++ project, you can
choose to create a sandbox of myproject.pj (that is, you do not have
to create a sandbox of the entire workspace).
Adding an Existing Project to Source Control
When an existing project contains files that are not in subdirectories
of the directory containing the Visual C++ project or workspace file,
the Source Integrity project will be created at the highest level that
contains all of the files in subdirectories. Visual C++ specifies this
location to Source Integrity.
For example
n:\master\myproject\myproject.dsp
contains
n:\master\otherproject\include\resource.h
When you add n:\master\myproject\myproject.dsp to source
control, the Source Integrity project will be created as
n:\master\myproject.pj since n:\master is the lowest common
denominator between these files.
Note You should not put a project under source control that contains
files on different drives. Visual C++ cannot determine where to locate the
project file and puts it in an arbitrary location.
222 Source Integrity Professional Edition

The Borland Delphi Extension
The Borland Delphi Extension
This section describes how to access Source Integrity through
Borland Delphi 3.0 and 4.0.
Once you have installed the Source Integrity Delphi Extension,
opening a project in Delphi under source control automatically loads
its archive information.
The Workgroups menu provides convenient access to the
Source Integrity operations you are likely to use most frequently as a
Delphi programmer. Extended functionality is accessible through the
Source Integrity Project Window.
To access version control functionality from within Borland Delphi,
select the menu item that corresponds to the Source Integrity function
you want to perform.
Menu Item Function
View SI Project
Window
Open the Source Integrity Project Window,
which gives a full view of the Source Integrity
project associated with your current Delphi
project, and advanced version control
functionality.
Check In Checks in the currently active Delphi form or
unit.
Check Out Checks out a revision of the currently active
Delphi form or unit.
Check In All Files Checks in all files in the Source Integrity project
you currently have checked out and locked.
Check Out All Files Checks out all the files in the Source Integrity
project that are currently checked in and
unlocked.
Create SI Project Opens the Create Source Integrity Project
dialog box to bring the current Delphi project
under source control.
Add Project
Members
Adds files to the Source Integrity project, and
creates an archive for each file.
Create SI Sandbox Creates a sandbox for the current or any other
Source Integrity project.
User Guide 223

Using Extensions
Creating a
Source Integrity
Project
For more on creating
Source Integrity projects using
the extensions, see “Using the
Extensions” on page 209.
Menu Item Function
SI Configuration Configures how Source Integrity will work, both
within Delphi and by itself.
Run Source Integrity Invokes the Source Integrity program, with the
current project loaded.
The Source Integrity right-click context menu reveals the memberspecific
commands you can perform on a selected file.
To create a Source Integrity project in Delphi:
1. Open the Delphi project you want to put under version control.
2. Choose Workgroups > Create SI Project.
The Create Project dialog box appears.
Some Useful Tips for Creating Your Source Integrity Project
You should add the following Delphi project files to your
Source Integrity project: .DPR, .RES, .OPT, .DOF, .PAS, and .DFM. The
only file MKS recommends you do not archive is a project’s .DSK file.
This file changes frequently and is usually specific to each
developer's working environment.
Of course, you can always put any file under version control,
whether or not it is a part of the Delphi project.
To add new members to a Source Integrity project, use the Add
Member function in the Project Window, or choose the Add Project
Members command in the Delphi Workgroups menu to add new
members to a Source Integrity project.
You should also archive Help documents and other related files, such
as specifications and databases, with your projects. This procedure,
combined with checkpointing your projects, enables you to recreate
old releases of your entire project including the documentation.
When you are finished, click OK. You are prompted to save the
project.
224 Source Integrity Professional Edition

Creating a
Sandbox
For more on creating
Source Integrity sandboxes
using the extensions, see
“Using the Extensions” on
page 209.
Checking Out
Files
To create a sandbox in Delphi:
Choose Workgroups > Create SI Sandbox.
The Create Sandbox dialog box appears.
To check out files in Delphi:
The Borland Delphi Extension
1. Bring the file you want to check out into focus in the Delphi
environment.
2. Choose Workgroups > Check Out.
If this file is a form or its associated .pas file, both the .dfm and
.pas files will be checked out. If you have selected Show Dialog in
Configuration, the Check Out dialog box appears. Otherwise, the
member revision is checked out.
3. Fill in or modify options in the dialog box as you like, and click
OK to check out the file. To cancel the check-out operation, click
Cancel.
Alternatively, you may check out a single file by selecting it in the
Source Integrity Project Window, and selecting Check Out via the
right-click context menu, Member menu or speed bar. This method
will ignore the relationship between a Delphi Unit’s .pas and .dfm
files, and only check out the selected file.
User Guide 225

Using Extensions
Checking Out
Multiple Files
Checking In
New Revisions
To check out multiple files in Delphi:
Choose Workgroups > Check Out All Files to check out all available
files in the Source Integrity project, or select the files you want to
check out from the Source Integrity Project Window and select
Check Out via the right-click context menu, Member menu, or speed
bar.
Follow the same procedure for checking out individual files and
check All files in the first dialog box. No subsequent dialog boxes will
appear.
To check in new revisions in Delphi:
1. Bring the file you want to check in into focus in the Delphi
environment.
2. Choose Workgroups > Check In.
If this file is a form or its associated .pas file, both the .dfm and
.pas files will be checked in. If you have selected Show Dialog in
Configuration, the Check In dialog box appears. Otherwise, the
file is checked in with the next logical revision number and no
label.
3. Fill in or modify options in the dialog box as you like, and click
OK to check in the file. To cancel the check-in operation, click
Cancel.
226 Source Integrity Professional Edition

Checking In
Multiple Files
The Microsoft Windows Explorer Extension
Alternatively, you may check in a single file by selecting it in the
Source Integrity Project Window, and selecting Check In via the rightclick
context menu, Member menu, or speed bar. This method will
ignore the relationship between a Delphi Unit’s .pas and .dfm files,
and only check in the selected file.
To check in multiple files in Delphi:
Choose Workgroups > Check In All Files to check in all files in the
Source Integrity project that you currently have locked, or select the
files you want to check in from the Source Integrity Project Window
and select Check In via the right-click context menu, Member menu, or
speed bar.
Follow the same procedure for checking in individual files and check
All files in the first dialog box. No subsequent dialog boxes will
appear.
The Microsoft Windows Explorer Extension
This section describes how to access Source Integrity through
Microsoft Windows Explorer.
Once you have installed the Source Integrity Windows Explorer
Extension, the File menu allows you to check in or check out files and
more with a click of your mouse. Right-click a file to reveal the
context menu of Source Integrity commands you can perform on the
selected file.
To access version control functionality from within Windows
Explorer, select the menu item that corresponds to the
Source Integrity function you want to perform.
Menu Item Function
Create Archive Places the selected files under version control,
by creating an archive for each file.
Check In Checks in the files you currently have selected
and checked out.
Check Out Checks out the files you currently have selected.
Compare to Head
Rev
Invokes the Visual Difference utility to compare
the selected working file with that member’s
head revision.
User Guide 227

Using Extensions
Creating an
Archive
Menu Item Function
Compare to Locked
Rev
Invokes the Visual Difference utility to compare
the selected working file with a revision in its
archive locked in your name.
Compare Files When two files are selected, this command
launches the Visual Difference utility with the
two files displayed side-by-side in a Compare
window.
Archive Window Opens the Archive window, displaying
information about the archive of the currently
selected file.
Disable Menu Disables the Windows Explorer Extensions. To
enable them, choose Enable Menu.
To create an archive in Windows Explorer:
1. Select the files you want to place under version control, and
choose Source Integrity > Create Archive from the right-click
context menu.
The Create Archive dialog box appears.
2. If you want, enter an initial Archive Description to associate with
the archive.
3. Fill in or modify the available options, and click OK to create an
archive for each selected file.
228 Source Integrity Professional Edition

Checking Out
Files
Checking In
New Revisions
The Microsoft Windows Explorer Extension
4. To cancel the create archive operation for an individual file, click
Cancel. To abort the operation for all files, click Cancel All.
To check out files from Windows Explorer:
1. Select the files you want to check out.
2. Choose Source Integrity > Check Out from the right-click context
menu.
3. Fill in or modify options in each dialog box as you like. To apply
settings to all files, enable All files in the first dialog box. No
subsequent dialog boxes will appear.
4. Click OK to check out the files. To cancel the check-out operation
for an individual file, click Cancel when its dialog box appears.
To abort the operation for all files, click Cancel All.
To check in new revisions from Windows Explorer:
1. Select the files you want to check in.
2. Choose Source Integrity > Check In from the right-click context
menu. This option will not be available if any selected file cannot
be checked in at present.
User Guide 229

Using Extensions
3. Fill in or modify options in each dialog box as you like. To apply
settings to all files, enable All files in the first dialog box. No
subsequent dialog boxes will appear.
4. Click OK to check in the files. To cancel the check-in operation for
an individual file, click Cancel when its dialog box appears. To
abort the operation for all files, click Cancel All.
230 Source Integrity Professional Edition

Building Projects With
Source Integrity
For more information about
MKS Make, see Chapter 9,
“Using the MKS Make
Utility”.
For more information about
command line interface
commands, see the Source
Integrity Professional Edition
Reference Guide or the online
man pages.
8
This chapter provides information about building projects from
source code under Source Integrity control.
With Source Integrity’s support for the build process and
configuration options, you can use it with your existing build
program or MKS Make, which is included with Source Integrity.
Source Integrity can:
examine your source files
track file dependencies and update your makefile
interpret “include” statements for C, C++, FORTRAN, Pascal,
and Assembler
use templates that include configuration language and
conditionally interpreted sections to create makefiles
Note Source Integrity’s building features are not available in the Source
Integrity Web Interface.
User Guide 231

Building Projects With Source Integrity
Before You Build
During your project build, you should follow some guidelines. If you
are building within your own sandbox, these guidelines are not as
important, but they are still useful.
Note If you want to create a sandbox to perform a build, you should use
a build sandbox instead of a conventional one. For information about
build sandboxes, see “Build Sandboxes” on page 25 and “Creating a
Sandbox” on page 76.
The guidelines are:
Check to see whether any users have any project members
locked. If a member is checked out locked, there may be work
still in progress.
Recursively freeze all of your members. This will prevent any
changes from taking place while checkpointing. Otherwise, it is
quite possible with hundreds of project members that one will
change its member revision in the middle of your checkpoint
operation. Remember, developers can continue to check in
revisions, without modifying the member revision.
Checkpoint the project to create a new revision of the project
itself. Assign it a label that will allow you to identify the build.
For example, from the project or sandbox directory enter
pj checkpoint -N Release_1
from the command line interface, or open the project in the
Windows interface and choose Project > Checkpoint. This creates
a new revision in the master project archive. By archiving the
project, you guarantee that you will be able to duplicate the build
precisely at any time in the future. This can make it easier to
identify members that have changed later.
Create a build sandbox workspace based on the checkpointed
revision. Working in a build sandbox will allow you to compile
your program, label members, and change members’ states
without disrupting other developers.
You can also label each member with the
pj label -N Release_1
command in the command line interface. In the Windows
interface, you can add a label to members when you checkpoint
232 Source Integrity Professional Edition

Creating a Makefile
Creating a Makefile
the project or select the members in the Project window and
choose Member > Label. This will serve as a reference point when
viewing archive information or Source Integrity reports.
Thaw the master project to allow developers to continue work.
Your build sandbox workspace allows you to continue the build
process uninterrupted.
If a high-priority bug appears in the build, a developer can make
a variant sandbox and fix it there. Later, the developer can merge
the changes into the head revisions to continue the main project.
The pj mkmf command allows you to calculate the dependencies of
project members and uses them to generate a makefile before you
build your project. The makefile it generates can be created from
scratch, or it can be based on an existing makefile or template.
where
pj mkmf [options] [-fR] [-M makefile] [-T template] [file…]
-f forces pj mkmf to ignore any saved information and rebuild all
dependencies before generating a makefile
-R recursively applies this operation to any directories specified
on the command line
-M makefile updates the makefile rather than generating a new one
-T template uses a template to generate a new makefile
file includes the names of one or more project members
dependencies will be calculated for. If omitted, all project
members are used
If -M makefile is omitted, the value of the policy option Makefile is
used. If neither is defined, the makefile is written to a file named
makefile in the current directory.
If -T template is not specified, Source Integrity uses the value of the
policy option MakeTemplate as a template file. If MakeTemplate is not
set, Source Integrity uses a makefile called make.t (if it exists) as a
template.
User Guide 233

Building Projects With Source Integrity
Building
As well, if the -T template option is not used to specify a makefile
template, a marker line is inserted in the makefile immediately before
the generated dependencies. The marker takes the form
### MKS SI generated dependencies follow,
do not remove/change this line
If pj mkmf encounters a marker line while updating a makefile, all
lines after the marker are replaced with the newly calculated
dependencies.
In the command line interface, use the pj build command to run
your configuration builder program.
In the Windows interface, choose Project > Build to open a dialog box
you can set parameters in and run your build program.
As well as setting parameters for the build process itself, you can
generate makefile dependencies using Source Integrity’s built-in
dependency-checking functions.
To generate dependencies in your makefile, click Recalculate. If there
are any problems in scanning the “include” statements, Source
Integrity reports them.
After recalculating the dependencies, click Add to Makefile to add the
new recipes to the makefile.
234 Source Integrity Professional Edition

Object File
Associations
Building
If any targets depend upon files that are not Source Integrity project
members, you can quickly add the files by clicking Add Missing Files.
By default, Source Integrity builds your project using MKS Make.
You can specify the command that builds your product with the
Build option for the project.
Depending upon the platform where it runs, Source Integrity makes
some default associations between source files and object files.
On PC platforms, it assumes source files with the extensions
.c .cpp .asm .f .for .p .pas
compile to object files with the extension .obj.
On UNIX systems, it assumes source files with the extensions
.c .C .cpp .s .asm .p .pas .f .for
compile to object files with the .o extension.
In addition, on PC platforms Source Integrity’s default assumption is
that files with a .rc extension generate resource (.res) files.
If your project uses files or processors with different extensions, you
can define your own rules with the project attribute TargetExt. Your
newly defined rules will completely replace Source Integrity’s default
associations. For example, to use a .xp extension for Pascal files and a
.c extension for C files, you should use the following command to set
TargetExt
pj set TargetExt=xp-obj;c-obj
Note You may need to quote arguments for your command processor.
For more details, refer to the section on MKS Make in the Source Integrity
Professional Edition Reference Guide.
User Guide 235

Building Projects With Source Integrity
Template Files
Language
Statements
Conditional
Expansion
The most powerful and flexible way to generate makefiles is by
specifying a template makefile with the -T template option to the
pj mkmf command. Makefile templates are text files that may contain
any number of make statements
Source Integrity configuration language statements and variables
the @Depends template statement
the @Template statement
Using these components, you can develop makefile templates for any
project; you can even generate multiple makefiles from the same
template by conditionalizing the expansion of template entries.
Source Integrity makefile templates may contain appropriate
statements from the Source Integrity configuration language.
Language statements are included by prefixing them with an at sign
(@) identifier, for example
@set var=value
@echo string
Note When configuration language statements are used in a template
file, the @ prefix must be the first character (excluding white space) in the
line where it appears.
Enter @@ (two at sign characters) in your template file to expand to a
literal @ character in a generated makefile.
The expansion of template entries can be made conditional with the
if..elseif..endif configuration language construct. In makefile
templates its syntax is
@if expr
statement_1
statement_2
[@elseif expr
statement_3
statement_4]
@endif
236 Source Integrity Professional Edition

@Depends
@Template
Variables
Template Files
Makefile statements included in the if/elseif/endif construct are
not prefixed with an @ character; the statements are only copied to the
new makefile if the conditional expr resolves to true.
The @Depends configuration statement is used to generate the first
line of a make rule, in the format
target : [dependency_file…]
where dependency_file is zero or more project member file names
dependencies will be calculated for. If dependency_file is omitted,
dependencies are calculated for all project members.
Like standard Source Integrity configuration language statements,
@Depends statements must be entered as individual lines in the
template file, with the @ character as the first non-white space
character on the line.
The statement
@Template filename
in a makefile template “reads in” the contents of filename as if it were
part of the template.
Like standard Source Integrity configuration language statements,
@Template statements must be entered as individual lines in the
template file, with the @ character as the first non-white space
character on the line.
Any Source Integrity configuration variable can be included in a
template file by bracketing it with @ characters, using the form
@var@
where var is the name of the variable that will be expanded to its
value in the generated makefile. Unlike configuration language
statements, variable references may be included anywhere in a
makefile, not just at the beginning of a line.
In addition to standard configuration variables, templates may also
include special template variables that expand to lists of file names
(based on recognizable file extensions from Source Integrity’s default
list, or your definition of TargetExt) when the makefile is generated.
User Guide 237

Building Projects With Source Integrity
The following table lists special template variables:
Reserved Word Expands To
@Sources@ A list of project members with source file
extensions. If any member is included by another
member, it is added to @Headers@ rather than this
list. When used from a sandbox environment, file
names use sandbox file mapping conventions.
@Headers@ A list of header files. Header files are project
members that are included by a source file.
@Objects@ A list of object files that will be generated by the
makefile. File names in the list are based on
@Sources@ with the appropriate object file
extension added. Files included by any other
source file are not included in this list. File names in
this list contain no path qualification.
@ProjectFiles@ A list of project members. When used from a
sandbox environment, names in the list use
sandbox file-mapping conventions.
Template variables are expanded like any other configuration
variable. However, if a name in the list causes the list to exceed 70
characters, the list is printed across multiple lines using the following
algorithm:
1. No portion of the file name that causes a line to exceed column 70
is printed on the current line.
2. The current line is terminated with a backslash (\).
3. A new line is begun, starting with three blank spaces and the
offending file name.
4. Steps 1 to 3 are repeated until the complete list has been printed.
Files that are included by any other file are not added to @Objects@
list. This ensures that inappropriate targets are not generated by your
make utility.
Example
Consider the source file control.asm, with a line
include defines.asm
238 Source Integrity Professional Edition

Examples
The Build
Process
Source Integrity does the following:
Examples
adds the source file control.asm to the @Sources@ list, but does
not add defines.obj to the @Objects@ list, since it is included
by control.asm; instead, defines.asm appears in the
@Headers@ list
adds control.obj to the @Objects@ list, if it is not included by
any other source file; the make utility can then apply its rules to
create control.obj from control.asm and defines.asm
If you have a project containing the classic “Hello, world!” program
#include
main(){
printf(“Hello, world!\n”);
}
you can set up the project so you can build it using MKS Make:
1. Set the include variable to tell Source Integrity where to look for
included files (c:\wcc\include):
pj set include=c:\wcc\include
This list can contain more than one directory, separated by
semicolons. If more than one directory is specified, the include
path must be enclosed in quotes:
pj set include=”c:\wcc\include;g:\project\include”
2. Create a makefile that contains the recipe to build the target. In
this example, the trivial header file dependency is left out:
hello.exe: hello.obj
cc -o hello.exe hello.obj
3. Add the dependencies to the makefile using pj mkmf. (For
instance, hello.obj depends upon a file called fin_func.h.
These lines are added to the makefile (the first line has been
folded to fit on the page):
### MKS SI generated dependencies follow,
do not remove/change this line
hello.obj : c:\wcc\include\fin_func.h
User Guide 239

Building Projects With Source Integrity
Templates and
Configuration
Language
Templates and
Variable
Expansion
4. You could also add those included files as members of the project
with the pj finddep command:
c:\usr\work\hello.c depends on:
c:\wcc\include\fin_func.h
Add ‘c:\wcc\include\fin_func.h’ to project?
[ynq](y):
To add the file, press .
This procedure only needs to be done once for each project, although
the makefile will have to be updated (with pj mkmf) if new members
are added to the project. You should also
add the makefile as a member of the project
put the makefile under revision control
To build the project, simply give the command pj build.
If SYSTEM is defined in the environment as “nt”
@@
@set OS=$getenv(SYSTEM)
@OS@
TEXT@OS@TEXT
Line one expands to a literal @ character.
Line two sets a variable named OS to “nt” but does not produce
any output in the makefile.
Line three produces a line in the expanded makefile containing
the value of the variable OS (in this example, “nt”).
Line four produces a line in the makefile containing the text
TEXTntTEXT
If a template named base.t contains the following lines
@set version=1
@set system=$getenv(SYSTEM)
# Generated @SYSTEM@ makefile, Version @version@
OBJ=@Objects@
target.exe: $(OBJ)
bcc -o $@@ $(OBJ)
@Depends
and the environment variable SYSTEM is set to “nt”, running the
command
pj mkmf -T base.t -M makefile
240 Source Integrity Professional Edition

creates a new makefile with the contents
# Generated nt makefile, Version 1
OBJ=control.obj
target.exe: $(OBJ)
bcc -o $@ $(OBJ)
control.obj: control.asm defines.asm
Examples
User Guide 241

Building Projects With Source Integrity
242 Source Integrity Professional Edition

Using the MKS Make
Utility
9
MKS Make offers developers, project managers and authors an
efficient way to automate the production and maintenance of any
project, large or small. Whenever you make changes to an element of
a development project, MKS Make automatically re-compiles all
related files and no others, saving valuable time and eliminating
errors.
For example, suppose you build a program from several separate
object modules, each depending upon its own source file. If you
change a source file, MKS Make automatically determines which
object modules are out of date (that is, older than the corresponding
source files), recompiles the changed source files, and links the
component object modules to produce an updated version of the
program.
In large, complex projects, where a change to one file may necessitate
changes in many others, it is easy to lose track. MKS Make eliminates
the worry of manually keeping your project up to date. Just give it a
list of interdependent files and a description of how to rebuild each,
and MKS Make takes care of the rest.
User Guide 243

Using the MKS Make Utility
Compatibility Issues
For details on these features,
see the man page for the make
command.
Getting the
Right Make
The Make utility originated under the UNIX operating system.
MKS Make tracks the POSIX standard. POSIX is an evolving family of
standards that describe a wide variety of operating system
components (ranging from shell and utility interfaces to system
administration). While POSIX has been influenced heavily by UNIX,
it is not UNIX (indeed many UNIX-based systems do not conform to
the POSIX standard). POSIX is important because it encourages crossplatform
compatibility. With your version of MKS Make, you can
create portable makefiles that work on operating systems
manufactured by IBM, Hewlett Packard, DEC, and Microsoft, or any
others that follow the POSIX standard.
MKS Make also conforms with UNIX versions to the greatest extent
possible, and makefiles that work with a UNIX make have the same
behavior when used with MKS Make. MKS Make also has many
additional, useful features that are extensions to the POSIX
guidelines.
Most C compilers come with their own version of make. There are
many reasons to believe MKS Make is superior to these other
versions. For the time being, be aware that your system may already
have a version of make from some other source. If you run a make
command and it does not behave the way our documentation says,
you might be running one of the other versions.
If you are using the MKS KornShell, part of MKS Toolkit, you can
find out which version of make you are running by using the which
command, as in the example
which make
The reply should look like the following for each operating system:
$ROOTDIR/mksos2/make.exe on OS/2
$ROOTDIR/mksnt/make.exe on Microsoft Windows NT and
Windows 95
Since $ROOTDIR represents the contents of the ROOTDIR environment
variable, $ROOTDIR actually appears as ROOTDIR’s value. If you are
not running MKS Make and you want to do so, simply change your
search order to include the directory with MKS Make before the
directory containing another make executable.
244 Source Integrity Professional Edition

Search Order
For more information about
search order, see the
documentation for your
operating system.
Changing Your
Search Order
See your operating system
documentation for more
information on changing your
path search order.
Compatibility Issues
Whenever you use a program, the system must locate a file
containing the program you want to run. It does this using the PATH
search order.
You can install MKS Make into any directory in your path, or change
your search order to accommodate a new directory for MKS Make.
To display your search order under command.com or cmd.exe, use the
command
path
If you are working in the MKS KornShell (sh.exe), use
print -r $PATH
which displays a list of directory names separated by semicolons.
When you issue a make command, the command interpreter searches
for a make program in each of these directories, in the order they
appear.
MKS Make is usually installed under
the $ROOTDIR/mksos2 directory on OS/2 systems
the $ROOTDIR/mksnt directory on Windows 95 and Windows NT
systems
If the command interpreter finds one of the other make programs
before it finds MKS Make, it runs that one instead.
If you find out that the system is running one of the other make
programs, there are two ways to fix the problem. First, you can
explicitly tell your command interpreter to run the correct version of
make by specifying the appropriate path to the program. For example,
you can type one of the following commands with the rest of the make
command line:
c:\mksos2\make on OS/2
c:\mksnt\make on Windows NT and Windows 95
A second (and better) solution is to change your search order. On
OS /2 systems, you change your search order by changing your
initial configuration files or the value of PATH. On Windows NT and
Windows 95 systems, you change your search order by changing
your initial configuration files, changing the user registry database
(on NT only), or changing the value of the PATH (PATH under NT’s
cmd.exe) environment variable.
User Guide 245

Using the MKS Make Utility
Getting Started With MKS Make
Dependency of
Files
To use MKS Make, you require a makefile. A makefile contains a list of
rules. Rules describe the dependencies among files that you want
MKS Make to maintain. A rule may also specify the commands—or
recipes—for rebuilding files when required.
You create makefiles as simple text files, so you can use your favorite
text editor or word processor to create and edit them. You must make
certain you save the files without any embedded word processor
formatting characters (such as changes in font); MKS Make cannot
interpret these special characters.
You must also ensure the editor you use does not translate the
control character into a group of spaces (make signals the beginning
of recipe lines with the character). Most editors allow you to
turn off the translation feature or insert a literal
character.
When you run the make program, it processes the makefile, checking
each rule for files you have recently modified. If make finds such a
file, it may also discover a dependent file that has not been rebuilt
since your modifications to the first file. If this is the case, make
proceeds to process the recipe associated with the dependent file‘s
particular rule.
The word dependency implies that a file may depend upon another
file or files for some reason. MKS Make refers to files that depend on
others as targets. It refers to the files a target depends on as
prerequisites. The same file can be a prerequisite, and later a target, in
the same makefile. If you modify a prerequisite file, make discovers it
needs to rebuild its associated target file. If you remove a target file,
make takes the steps necessary to recreate it.
When a file that is a prerequisite for a target is modified, or recently
changed, that file’s target is considered to be out of date with respect
to that prerequisite.
The makefile describes the dependency relationships of targets and
prerequisites. Each rule identifies a target file, and specifies the
target’s prerequisite file(s). The rules’ recipes describe any actions
MKS Make must take if it discovers an out-of-date target.
246 Source Integrity Professional Edition

Makefiles
Getting Started With MKS Make
At this point, an example may help explain these concepts. This
example is purposefully larger than necessary and somewhat limited.
Later in this chapter, you can learn how to make your makefiles more
useful and compact. The contents of a sample makefile for a small
program, using the Borland C++ compiler are:
program.exe : main.obj func.obj
bcc -eprogram.exe -ml main.obj func.obj
main.obj: main.c
bcc -c -ml main.c
func.obj: func.c
bcc -c -ml func.c
If you want the same makefile using the Microsoft C/C++ compiler,
you might write
program.exe : main.obj func.obj
cl -AL main.obj func.obj -o program.exe
main.obj: main.c
cl -c -AL main.c
func.obj: func.c
cl -c -AL func.c
For the Watcom C/C++ compiler, it might look like
program.exe : main.obj func.obj
wcl -ml -fe=program.exe main.obj func.obj
main.obj: main.c
wcc -c -ml main.c
func.obj: func.c
wcc -c -ml func.c
With all three compilers, the form of the makefile is similar. For the
sake of convenience, this chapter looks at the Borland C++ example
more closely, but what follows applies to all versions equally.
The makefile consists of three rules. The first rule in the Borland
example looked like
program.exe : main.obj func.obj
bcc -eprogram.exe -ml main.obj func.obj
The first line in this rule states that the file program.exe depends
upon the two .obj files that follow the colon. If any or all of the .obj
files have changed since the last time program.exe was made,
MKS Make attempts to remake it. It does this using the recipe on the
next line. This recipe consists of the Borland C bcc command that
links program.exe from the two object files.
User Guide 247

Using the MKS Make Utility
Writing a Rule
For more information about
special targets that are not
files, see “Special Macros” on
page 271.
However, before MKS Make remakes program.exe, it checks to see if
any of the .obj files need remaking. To do this, it checks the other
rules in the makefile to determine the dependencies of the .obj files.
If any of the .obj files need remaking (because their associated .c
files have been changed), MKS Make remakes the .obj files first
using the bcc command. It then makes program.exe.
MKS Make updates each target file (the program.exe file, and all the
.obj files) by executing the recipe that follows the appropriate file.
The previous example showed a collection of simple rules. All of the
rules follow a consistent format:
target target… : prerequisite prerequisite…
recipe
MKS Make accepts rules with much more complex formats, but this
example uses just this simple form.
The term target usually refers to a file made from other files. Each rule
may have several targets. MKS Make also recognizes a number of
special targets that are not files.
The prerequisites consist of a list of files (each rule may also have
more than one prerequisite). The targets depend directly or indirectly
on these files; if any of the files change, the targets require remaking.
The prerequisite list appears on the same line as the targets, separated
from the targets by the colon rule operator.
Consider the following example:
func1.obj func2.obj : includes.h
bcc -c -ml func1.c
bcc -c -ml func2.c
The rule in the example describes a dependency between a header file
(the prerequisite) and the object files that use it (the targets). If you
change the prerequisite file includes.h, you must update both target
files, func1.obj and func2.obj. Notice that you do not need to
express the dependency between the header file and the source files,
as the contents of the object files depend, in turn, upon the source
files.
The recipe consists of one or more commands MKS Make uses to
remake the target(s) when necessary. The recipe usually begins on the
line following the target and prerequisite list. A recipe can consist of
248 Source Integrity Professional Edition

Getting Started With MKS Make
any number of lines. Each and every line in the recipe must begin
with a character. A line that does not begin with a
signals the start of a new rule.
Note A common cause of syntax errors results from makefiles with
leading blank characters at the beginning recipe lines.
In the interests of efficiency, MKS Make executes most recipe lines
itself. However, a recipe line may contain a character special to your
command interpreter or shell (for example, the > and < redirection
symbols). In these cases, MKS Make calls the command interpreter or
shell to execute the line, so the special characters are handled
properly.
File Names Containing a Colon
Occasionally, the names of target files may contain a colon.
a:file
Usually, MKS Make interprets a colon as a rule operator—the mark
separating the target names from the prerequisite list. To avoid
confusion, use quotes to enclose any file name that contains a colon:
"a:program.exe" : "a:main.obj" func1.obj…
recipe
Usually, however, you specify all file names relative to the current
directory, so you do not need to include a drive specifier (or colon).
White Space
White space consists of one or more blanks or characters.
White space separates the names of items in a target or prerequisite
list. You can also surround the colon between the target list and the
prerequisite list with white space; however, you do not have to.
You can also insert blank lines wherever you want in a makefile. make
ignores blank lines when it reads the makefile.
User Guide 249

Using the MKS Make Utility
Comments
More About
Rules
Continuation Lines
Using a backslash character (\) as the last character of a line indicates
the line is not finished—that it continues on to the next line of the file.
The first two lines in the following example have the same meaning
as the third:
target list : \
prerequisite list
target list : prerequisite list
You might find this useful if the length of a list makes it impossible to
fit everything on one line. You can do this several times. A single line
can be broken into any number of continuation lines.
Note Always use a backslash to continue a line, whether you use the
MKS KornShell, command.com, or cmd.exe.
A makefile can contain comments. A comment begins with a sharp
character (#), and extends to the end of the line. Consider the
following example:
# This is a comment line
target : prerequisite #This is another comment
recipe # One more comment
MKS Make ignores all comments.
So far, this chapter has given a simple description of what rules in a
makefile look like. All rules use the following general format (for a
complete description, see the man page for the make command).
targets [attr] oprtr [prereqs] [;recipe]{ recipe}
targets A list of one or more files.
attr A list, possibly empty, of attributes to apply to the targets. For
more information, see “Controlling MKS Make” on page 265.
oprtr A rule operator, separating the targets from the associated
prerequisites. Usually this is a colon, but MKS Make supports a
number of other rule operators for specific purposes. For more
information, see the online command reference for the make
command.
250 Source Integrity Professional Edition

Missing Rules
Getting Started With MKS Make
prereqs Zero or more file names the specified targets depend on.
recipe May appear on the same line as the prerequisites, following
them, and separated by a semicolon. If such a recipe exists,
MKS Make uses it as the first in a list of recipe lines defining a
method for remaking target. Additional recipe lines may follow
the first line of the rule. Each additional recipe line must begin
with a character.
If MKS Make cannot find a rule for a particular target, it displays this
message on the standard error stream:
Make: Don’t know how to make target
If it cannot find a rule for a particular prerequisite and the file named
by that prerequisite does not already exist, the same message is
displayed.
More About Recipes
Recipes are lists of lines used by MKS Make to rebuild the target(s)
listed in the associated rule. A rule may have zero or more recipe
lines. Comments and empty lines are ignored when recipes are read.
When MKS Make is reading recipes and encounters a line that does
not begin with a character, it assumes the previous rule has
finished and a new one has begun.
Command Prefixes
You can begin any recipe line with a command prefix immediately
following the character. MKS Make supports the following
three command prefixes:
- (dash) Ignore non-zero exit values when executing this recipe
line. Use this when you want to use a command in a recipe
that may not return a proper (zero) exit value when it
succeeds.
@ (at sign) Inhibits the echoing of a recipe line to the standard output
prior to its execution. Use this if a recipe line sends
messages to standard output, and you do not want to
clutter the output stream.
+ (plus sign) Forces execution of the recipe line, even if the -n, -q, or -
t options are specified on the command line.
User Guide 251

Using the MKS Make Utility
For more information, see the
man page for the make
command.
Running MKS Make
Specifying
Targets on the
Command Line
Using a
Different
Makefile
You can use more than one command prefix with a recipe line,
provided they are grouped together, immediately following the
character. You may put the prefixes for a recipe in any order,
for example:
-@ echo "rebuilding foo"
To run MKS Make, enter
make
at the command line. By default, MKS Make expects to find your
makefile in the current directory with the name makefile or
Makefile. Once it finds your makefile, MKS Make checks to see if the
first target has become out of date with respect to its prerequisites. As
part of this process, it first looks to see if the prerequisites themselves
require remaking. MKS Make rebuilds all the files it needs to
properly rebuild the first target.
Often, you might find it useful to put an artificial rule at the
beginning of your makefile, naming all the targets you remake most
frequently.
herring : prerq1 prerq2…
The target file in the example (named herring) does not exist, but
when MKS Make tries to rebuild it, it automatically checks each one
of its prerequisites to determine whether they require rebuilding.
If you specify the names of specific targets on the command line,
MKS Make attempts to remake only the targets you specify. Again, it
first attempts to rebuild any prerequisites (associated with your
specified targets) that have become out of date with respect to any
files they depend on.
In the following example, make rebuilds the given object files, should
they require it.
make func1.obj func2.obj
If you give your makefile a name other than makefile, or place it in a
separate directory, you usually have to specify its name. You do this
with the -f option, for example:
make -f foo.mk
252 Source Integrity Professional Edition

The Command
Line
You can combine options to make, as in the example
make -f foo.mk func1.obj func2.obj
Running MKS Make
The previous sections gave you a glimpse of MKS Make’s versatility.
You can specify a number of options and items on the command line
to modify its behavior. In general, your command lines should
conform to the format
make [options] [macro definitions] [target…]
You can specify a number of options on the command line. Options
take the form of a single letter, prefixed with a dash. MKS Make
distinguishes between uppercase and lowercase on the command
lines, so it would treat the -e option and the -E option differently.
If you want to specify several options on the same command line, you
can bundle them together following a single dash. For example
make -n -u
make -nu
are considered identical.
Some options require an additional argument, as you saw previously
with the -f option. You can bundle one of these options with others
on the command line; however, it must appear last in the bundle, to
allow for its argument. These lines are considered identical:
make -nuf foo.bar
make -n -u -f foo.bar
You may also append an argument directly to an option, although
this syntax is now obsolete
make -nuffoo.bar
The following table briefly explains some of the most common
command-line options. For the complete list of options, see the man
page for the make command.
User Guide 253

Using the MKS Make Utility
For more information on the
-D option, see the man page
for the make command. For
more information on macros,
see “Using Macros” on
page 256.
How Make
Finds Its
Makefile
Option Description
-f file Uses file as the makefile. If you specify a dash in place of file,
MKS Make reads the makefile from standard input. In other
words, it expects you to type in the makefile from the keyboard,
or redirect it from a file.
-k Makes all independent targets, even if an error occurs.
Ordinarily, processing stops after a command in a recipe
produces an error. Specifying -k forces MKS Make to continue
making other targets, provided they are unrelated to the one
associated with the error.
-n Displays all the commands needed to update the chosen
targets, but does not execute them. Use this to check that your
makefile does exactly what you expect it to do, without actually
affecting any of your files.
-u Rebuilds all the targets whether their prerequisites have
changed or not. Use this to guarantee that everything gets
rebuilt at the same time, whether needed or not.
Any macro definitions you specify on the command line have the
same form as macro definitions in a makefile, and supersede
definitions in the makefile or default rules file. You can place macro
definitions anywhere on the command line, even after the names of
targets.
You can also define macros on the command line with the -D option.
This option forces MKS Make to use these macro definitions before
reading any makefile.
When you run MKS Make, it uses information from a number of
different sources. The following subsections describe each source of
information in the order used by make.
254 Source Integrity Professional Edition

For more information on the
control macros, see
“Controlling MKS Make” on
page 265.
Built-in Rules
Running MKS Make
MKS Make contains a number of built-in rules. These rules may
evolve somewhat from release to release. You cannot change them
yourself. You can display the built-in rules for your version of make,
with the -V option.
Note The POSIX standard refers to default rules as built-in rules. MKS
uses the term built-in to emphasize the difference between the provided
rules that you cannot configure (built-in) and those that you can
(default).
Default Rules
Default rules are specified in the standard startup file. By default,
MKS Make looks for a file called $ROOTDIR/etc/startup.mk, to use
as its startup file. You can specify a different name for the startup file
by setting a value for the MAKESTARTUP environment variable, or by
giving the MAKESTARTUP control macro a value on the command line
as an argument to the -D option.
You can edit the contents of the startup file with a normal text editor.
When you install MKS Make, a startup file is provided for you in
$ROOTDIR/etc/startup.mk. You should not customize this file until
you are familiar with MKS Make and know how to modify its
behavior. If you delete this file or put incorrect material into it,
MKS Make does not work as documented.
Local Default Rules
The last line of the default startup file prompts MKS Make to include
a file called startup.mk in the current directory. If this file exists,
MKS Make reads it next. Once you are more familiar with
MKS Make, you may want to create different local default rules files
for different projects.
Makefile
Lastly, under the direction of its built-in rules, MKS Make looks for a
file called makefile in the current directory. If no such file exists, it
looks for a file called Makefile in the current directory. If it cannot
find either file, it displays a message and stops.
You can specify a makefile with a different name, or in a different
directory, by using the -f option, as previously described.
User Guide 255

Using the MKS Make Utility
Using Macros
Suppose you use MKS Make to maintain a C program that you are
compiling. Most compilers let you compile programs in accordance
with several memory models. The Borland C++ compiler, for
example, provides this ability with the -ms, -mc, -mm, -ml, and -mf
options. Other compilers have similar options.
You need to compile all the program modules with the same memory
model options, so you could write your makefile like the one in
following example for the Borland C++ compiler.
module1.obj : module1.c
bcc -ms -c module1.c
module2.obj : module2.c
bcc -ms -c module2.c
# And so on
These commands all use the small memory model. They also make
use of the -c option, which compiles the source code without linking
it.
Now suppose your program grows to the point that the small
memory model is no longer appropriate. You would need to go back
to your makefile and change all the -ms references into one of the
larger models. This task is time-consuming and error-prone. You may
easily miss one of the recipes that require changing, or make a typing
mistake while you are editing the file.
Macros help solve this problem. A macro is a symbol that represents a
string of text. When MKS Make encounters a macro in your makefile,
it replaces the macro symbol with its predefined value (the text
string). This process of replacement is called expansion. You can define
a macro at the top of your makefile, by using a line with the format
macro_name = text_string
Later on in your makefile, you can use this macro to replace its text
string equivalent. To force MKS Make to expand the value of a macro,
you surround it with a dollar sign and either parentheses or braces.
or
$(macro_name)
${macro_name}
256 Source Integrity Professional Edition

Using Macros
Refer back to the previous memory model example. You can use
macros to represent explicit references to the memory model, the
compiler name, and so on.
CC = bcc
CFLAGS = -ms
O = .obj
module1$(O) : module1.c
$(CC) -c $(CFLAGS) module1.c
module2$(O) : module2.c
$(CC) -c $(CFLAGS) module2.c
# And so on
You create a macro in the first line named CC, and assign it the
command name that invokes your compiler.
On the second line, you create the macro CFLAGS, and assign it the
options you want your compiler to use.
On the third line is an example of a common practice used with
MKS Make—the assignment of your system’s object file extension to
the O macro (the letter O, not zero). This macro is useful for helping to
ensure the portability of your makefiles across platforms. Object files
typically employ .obj as the object file extension on PCs. On POSIX
and UNIX platforms, object files typically use .o as the object file
extension. Notice that our definition of the O macro includes the dot
as well as the extension name. We do this so the makefile can work on
platforms that do not use an extension for object files at all (and thus,
have no dot in object file names).
This convention is also used for the A and E macros, which expand to
the archive library and executable file extensions, respectively. The
examples in this chapter use these macros; the default rules file
provided when you installed MKS Make defines values appropriate
to your system.
Now, when you run MKS Make with this makefile, it expands all the
occurrences of $(CC) and $(CFLAGS), replacing the macro references
with the strings you have defined at the top of the file.
To change the options you pass to the compiler, you only have to
make a single change—the value assigned to the CFLAGS macro at the
top of the makefile. You can even switch to a different compiler by
changing the value of CC to indicate the command name for the new
compiler. Adding the new options you need to pass to your new
compiler is easy; you have just learned how to do that. You do not
ever have to touch the rules in the body of the makefile; you only
need to change the macro assignments at the top.
User Guide 257

Using the MKS Make Utility
Macro Naming
Conventions
Notice that, in the example, the -c option is in the body of the
makefile. You may want some options to take effect all the time and
not change every time the values of your macros change. Be careful
with this practice, though; if you specify values for your macros that
are incompatible with the options you have left in the main body of
your makefile, you may run into problems.
You can use any sequence of standard alphanumeric characters in a
macro name, although the name cannot begin with a digit. You can
also use underscores. You should use uppercase letters in macro
names, as it makes them easy to identify.
Actually, you can use nearly any printable characters in macro names,
except any of the following:
: ; $ { } =
However, your makefiles are much more readable if you use only
uppercase letters, numbers, and the underscore in your macro names.
Since you can nest macro names inside one another (see “Nesting
Macros in other Macros” on page 259), take care when using the
dollar sign in macro values. You must type two dollar signs in
sequence to represent a literal dollar sign when the macro is
expanded. The following example shows a macro called DOLLAR,
holding the string for a dollar sign:
DOLLAR = $$
When MKS Make expands the DOLLAR macro, it replaces the macro
with a single dollar sign.
You can assign an empty (NULL) string to a macro (MKS Make
predefines NULL). You might find this useful with macros that you
only want to use in certain cases. To assign a null value to a macro,
simply leave the right side of the assignment blank.
MY_BLANK_MACRO =
Note that MKS Make ignores white space (blanks and tabs) in the
string after the equal sign. To include white space as part of your
macro string, enclose it in double quotes.
Finally, if you create a macro with a single-letter name, MKS Make
lets you omit the parenthesis in references to the macro. Thus, if you
use the conventional E macro to hold the your executable file
extension string, you can place $E in the makefile and MKS Make
expands this to E’s contents. The rest of the examples in this manual
employ this convention.
258 Source Integrity Professional Edition

Defining
Macros on the
Command Line
For more information on the
-D option, see the online
command reference for the
make command.
Nesting Macros
in other Macros
Using Macros
You can define (or redefine) macros anywhere on the make command
line. In the following example, the user defines a macro specifying
the directory containing object modules:
make DIROBJ=/usr/project/obj program.exe
If you define a macro on the command line, the value cannot be
changed by macro definitions in makefiles that are read by the
command. However, you can force MKS Make to handle the
command-line macro before reading the makefile with the -D option;
if you use this option to define a macro on the command line, any
definitions made in the makefile overwrite it.
If your command-line macro needs to have white space in it, you
need to surround the entire definition in quotes.
make "FILES= a.c b.c c.c" target1 target2
Note MKS Make ignores any leading or trailing white space around the
macro definition, so it treats " FILES = foo bar " and "FILES=foo
bar" as equivalent.
Any macro’s value can contain another macro reference. When
MKS Make expands a macro and detects another macro reference in
the replacement string, it automatically expands that reference as
well, for example:
PROJECT = myProj
SRCDIR = $(PROJECT)/src
When make expands the SRCDIR, it notices that another macro string
has appeared, and expands the second macro as well.
/usr/lindsay/$(SRCDIR)
expands first to
/usr/lindsay/$(PROJECT)/src
and expands again to
/usr/lindsay/myProj/src
User Guide 259

Using the MKS Make Utility
For a more useful example, suppose you maintain one set of header
files, but each person working with those header files has their own
directories containing source and object files. You can still have one
makefile to trace the dependency between a header file and each
person’s source files.
# these macros contain the appropriate directories
SRCDIR = $(HOME)/project/src
OBJDIR = $(HOME)/project/obj
HDRDIR = /usr/main/hdr
# makefile rules follow
$(OBJDIR)/module$O : $(HDRDIR)/includes.h
# compile the out of date object file
# from its source
$(CC) -c $(CFLAGS) $(SRCDIR)/module.c
To use this makefile, you would need to specify a command-line
value for HOME on the command line, using the -D option (to assign
the command-line value to HOME before reading the makefile and
performing any macro expansion).
For any value of HOME, you can see that the makefile defines macros
for all the appropriate directories. If HOME is /usr/main, when
MKS Make expands the $(SRCDIR) and $(OBJDIR), it also expands
the $(HOME) macro. $(SRCDIR) eventually expands to
/usr/main/project/src
If Lindsay wanted to use the makefile, the following command
would perform the appropriate expansion:
make -DHOME=/usr/lindsay module.obj
or, if Lindsay has exported $HOME in the environment
make -DHOME=$HOME module.obj
Notice that you must name the target explicitly on the command line;
you can not use the O macro. You may define macros on the
command line, but you cannot pass them as part of a target’s name.
You may only use the values assigned to macros within the makefile
itself.
Note If you define a macro on the command line with the -D option,
you may include these macros as components of target names on the
command line. For more information on the -D option, see the man page
for the make command.
260 Source Integrity Professional Edition

For more information on
special target directives (and
.IMPORT in particular), see
“Controlling MKS Make” on
page 265, and the online
reference for the make
command.
Modifying
Macro
Expansions
Using Macros
Also notice that Lindsay provided a specific value for HOME on the
command line. To avoid this requirement, you could import a value
for a macro from the environment, with the .IMPORT special target
directive in the makefile.
.IMPORT: HOME
RCDIR = $(HOME)/project/src
and so on…
Note Using .IMPORT this way is not strictly necessary, as MKS Make
imports variables from the environment by default.
You can modify the way MKS Make expands macros by adding a
colon followed by one or more macro modifiers after the macro
name:
$(macro_name:modifier_list:modifier_list:…)
Each modifier_list consists of one or more characters that tell
MKS Make to expand the macro in a specific way. MKS Make applies
each macro modifier in the modifier_list from right to left.
For example, if you have a macro called FILE that represents the full
path name of a file, you can use $(FILE:d) to select only the directory
portion of the path name:
FILE = /usr/lindsay/program.c
$(FILE:d)
expands to
/usr/lindsay
You can use uppercase or lowercase letters for macro modifiers; so
both $(FILE:d) and $(FILE:D) would produce /usr/lindsay in the
previous example.
User Guide 261

Using the MKS Make Utility
The following table describes some of the modifiers you can use.
Modifier Description
b Use the base file name, without suffix, of a macro string path
name.
d Use the directory portion of a path name. This modifier gives a
dot for path names that do not have explicit directories.
f Use the full file name portion, with suffix, of a path name.
l Convert all characters in the macro string to lowercase.
s Perform string substitution. For more information, see “String
Substitution” on page 262.
t Expand the macro into tokens. For more information, see
“Tokenization” on page 263.
u Convert all characters in the macro string to uppercase.
^ Add a prefix string to each token in the macro string. For more
information, see “Prefix and Suffix Modifiers” on page 264.
+ Append a suffix string to each token in the macro string. For
more information, see “Prefix and Suffix Modifiers” on
page 264.
String Substitution
The substitution modifier differs slightly from standard modifiers.
Use the substitution modifier to search for all occurrences of a
substring in the macro string and replace them with another
substring. The format of the substitution modifier is:
:s/string/replace/
Using the macro definition for FILE from the previous section.
$(FILE:s/lindsay/dale/)
expands to
/usr/dale/program.c
You can apply the substitution modifiers with other modifiers, and
MKS Make applies the modifiers in order from left to right. For
example
$(FILE:s/lindsay/dale/:d)
262 Source Integrity Professional Edition

expands to
/usr/dale
Using Macros
You can use any printing character in place of the slash to delimit the
pattern and replacement substrings, as long as you use it consistently
within the command. For example
$(FILE:s~lindsay~dale~:d)
expands to
/usr/dale
For compatibility with UNIX System V make, MKS Make also
supports the suffix replacement modifier. This modifier, when used
according to the following example, replaces any occurrences of
old_suffix with new_suffix.
$(macro_name:old_suffix=new_suffix)
Notice that the string replacement only applies to file suffixes.
Consider the example
FILE = /usr/lindsay/src/parse.y
$(FILE:.y=.c)
expands to
/usr/lindsay/src/parse.c
Tokenization
MKS Make interprets any sequence of non-white space characters as
a token. The format of the tokenization modifier is
$(macro:t"string")
The construct expands the given macro, inserting string between
tokens. This process is called tokenization. Consider the example
LIST = a b c
$(LIST:t"+")
expands to
a+b+c
Notice that MKS Make places the + between each pair of tokens, but
not after the last one.
User Guide 263

Using the MKS Make Utility
You can use a number of special escape sequences in the separator
string. The following table describes each one’s effect.
Escape
Sequence
Effect
\" "
\\ \
In this example, using the previous definition of LIST
$(LIST:t"+\n")
expands to
a+
b+
c
Prefix and Suffix Modifiers
You use prefix and suffix modifiers to add a string to the beginning or
end of each space separated token in the macro string, according to
the form
$(macro_name:^"prefix_string")
$(macro_name:+"suffix_string")
In an example using the TEST macro
TEST = main func1 func2
$(TEST:^"/src/")
expands to
\a Alert (bell sound)
\b Backspace
\f Formfeed
\n Newline
\r Carriage Return
\t Horizontal Tab
\v Vertical Tab
\nnn Octal Character nnn
/src/main /src/func1 /src/func2
264 Source Integrity Professional Edition

and
$(TEST:+".c")
expands to
main.c func1.c func2.c
Controlling MKS Make
If the prefix and suffix strings themselves consist of a list of tokens
separated by blanks, the resulting expansion provides the cross
product of both lists. Consider the following example using a
different value for the TEST macro.
TEST = a b c
$(TEST:^"1 2 3")
expands to
and
1a 1b 1c 2a 2b 2c 3a 3b 3c
$(TEST:+"1 2 3")
expands to
a1 b1 c1 a2 b2 c2 a3 b3 c3
If you combine these two references
$(TEST:^"1 2 3":+"1 2 3")
expands to
Controlling MKS Make
For a complete technical
description, see the man page
for the make command.
Attributes
1a1 1b1 1c1 2a1 2b1 2c1 3a1 3b1 3c1
1a2 1b2 1c2 2a2 2b2 2c2 3a2 3b2 3c2
1a3 1b3 1c3 2a3 2b3 2c3 3a3 3b3 3c3
This chapter has covered a few ways to control the way MKS Make
proceeds when rebuilding a file. To really control its behavior, you
need to understand how to use attributes, special targets, and special
macros.
This section introduces you to these concepts and describes some
commonly used examples.
Attributes represent qualities that you can attach to targets. When
make updates a target, it triggers any attributes associated with that
target.
User Guide 265

Using the MKS Make Utility
You can assign attributes to a single target, a group of targets, or to all
targets in a makefile. You can use several forms when including
attributes in your makefiles. Both of the following examples assign
the attributes specified in attribute_list to each of the targets.
targets attribute_list : prerequisites
attribute_list : targets
You can also write a rule with an attribute_list on the left side, and
with no targets on the right side.
attribute_list :
This applies all attributes in the list to every target in the makefile.
Traditional versions of make may let you do this with .IGNORE
attribute, but not with any other attribute.
The following table describes a number of commonly used attributes.
For a complete list, see the man page for the make command.
Attribute Description
.EPILOG Inserts shell epilog code when executing a group recipe
associated with any target having this attribute set.
.IGNORE Ignores any errors encountered when trying to make a
target.
.PRECIOUS Does not remove this target under any circumstances. Any
automatically inferred prerequisite inherits this attribute. By
default, MKS Make removes intermediate targets that did
not exist before it began execution.
.PROLOG Inserts shell prolog code when executing a group recipe
associated with any target having this attribute set.
266 Source Integrity Professional Edition

Special Target
Directives
Attribute Description
Controlling MKS Make
.SETDIR Changes current working directory to pathname when
making associated targets. You use this attribute with the
following syntax:
.SETDIR=pathname
If pathname contains any colons, you must quote the entire
attribute string, not just the path name.
While .SETDIR might be necessary to work with primitive
commands that do not understand directories, you may
find it awkward and troublesome. You should use
the.SOURCE special target directive described in the next
section, “Special Target Directives”.
.SILENT Does not echo the recipe line, and does not issue any
warnings when making a target with this attribute. This is
equivalent to placing the @ command prefix before every
recipe line in the rule.
You can use any attribute with any target (including some special
targets). If you specify an attribute that cannot be used with a
particular special target, MKS Make issues a warning and ignores the
attribute. Some combinations serve no useful purpose (for example,
.INCLUDE with .PRECIOUS). You might find other combinations quite
useful.
Special target directives, or simply special targets, appear in the
target position of rules, but are not really targets. They act as
keywords that provide directives to control they way MKS Make
functions. A rule with a special target may not have any other targets
(normal or special); however, you can assign attributes to special
targets. Some combinations serve no purpose, but others are useful
(for example, combining the .IGNORE attribute with the .INCLUDE
special target, as shown in the previous section).
User Guide 267

Using the MKS Make Utility
The following table describes a number of commonly used special
target directives. For a complete list, see the man page for the make
command.
Target
Description
Directive
.EXPORT Treats all the prerequisites associated with this target
as macro names. MKS Make then exports these
macros and their values to the environment as
environment variables, at the point in the makefile
where it reads the rule. The following example builds a
source directory macro from the HOME macro, and then
exports that value to the user’s environment.
SRCDIR=$HOME/project/src
.EXPORT : SRCDIR
# exports SRCDIR to the environment
MKS Make ignores any attributes associated with this
target. It exports the specified value to the environment
when it reads the rule, but does not execute any
commands until it finishes reading the entire makefile.
This means that if you .EXPORT a value more than
once in a makefile, only the last value affects executed
commands.
.IMPORT Make searches in the environment for prerequisite
names specified for this target and defines them as
macros with their value taken from the environment. If
the prerequisite .EVERYTHING is given, make reads in
the entire environment.
268 Source Integrity Professional Edition

Target
Directive
Description
Controlling MKS Make
.INCLUDE Process one or more additional makefiles, as if their
contents had been inserted at this point. MKS Make
behaves as if the contents of the additional makefile
were inserted after the line where it finds this special
target. You specify these extra makefiles as
prerequisites to the .INCLUDE special target. If the
prerequisite list contains more than one file, they are
read from left to right. The following example tells
MKS Make to look for an additional set of default rules
in the users personal project directory:
.INCLUDE : $HOME/project/startup.mk
make uses the following rules to search for extra
makefiles:
If a relative file name is enclosed in quotes, or is not
enclosed with angle brackets (< and >), look in the
current directory. If the file is not present, look in each
directory specified by the .INCLUDEDIRS special
target.
If a relative name is enclosed with angle brackets
(< and >), search only in the directories specified by
the .INCLUDEDIRS special target.
If an absolute path name is given, look for that file
and ignore the list associated with the
.INCLUDEDIRS special target. An absolute path
name could be any one of
./foo.c
/foo.c
/src/foo.c
c:/foo.c
c:/src/foo.c
If MKS Make cannot find a file, it normally issues an
error message and terminates; however, if you have
associated the .IGNORE attribute with this special
target, it just ignores the missing file error. The
.IGNORE attribute is the only one that serves a
meaningful purpose when associated with
.INCLUDE.
For compatibility with MKS Make on UNIX System V,
the following two lines produce equivalent results.
include file #at beginning of a line
.INCLUDE: file
User Guide 269

Using the MKS Make Utility
Target
Directive
Description
.INCLUDEDIRS Specifies a list of prerequisites that define the
directories to search when trying to include a makefile
with the .INCLUDE special target. The following
example looks for .INCLUDE files in a central admin
directory, then in a central source directory, then in a
personal source directory.
.INCLUDEDIRS : /etc /rd/src $HOME/project
.POSIX Process the makefile as specified in the POSIX.2
standard. If present, this special target must appear on
the first non-comment line in the makefile. This target
may have no associated prerequisites or recipes. Use
this when you need to ensure your makefiles’ portability
to any other POSIX-based platform.
Using this special target has the following effects.
Causes MKS Make to always use a separate
instance of the shell to execute each recipe line,
instead of trying to run the commands directly.
Disables any brace expansion, and ignores any
instance of the .BRACEEXPAND special target. For
more information about the deprecated
.BRACEEXPAND special target, see the man page for
the make command.
Disables metarule inferencing.
Disables conditionals.
Disables the use of dynamic prerequisites.
Disables the use of group recipes.
Restricts library prerequisites to explicitly named
members. For more information, see the description
of the .NOAUTODEPEND special target in the online
reference for the make command.
Checks only the archive when checking the time
stamp on a library module; it does not check for an
object file.
Prevents make from checking for the string $(MAKE)
when you specify the -n option on the command line.
270 Source Integrity Professional Edition

Special Macros
Target
Directive
Description
Controlling MKS Make
.SOURCE Check the list of directories, defined by the associated
prerequisite list, when trying to locate a target file
name. The following example checks a user’s personal
source directory first, and then a central one.
.SOURCE : $HOME/project/src /rd/src
For more information, see “How Make Finds Files” on
page 277.
.SOURCE.x When trying to locate a file with a name ending in the
suffix .x, search first in the list of directories defined by
the associated prerequisite list. The following example
directs make to look in two different sets of directories
for source and object file targets.
.SOURCE$O : $HOME/project/object /rd/object
.SOURCE.c : $HOME/project/src /rd/src
.SUFFIXES When inferring a rule using suffix rules, the list of valid
suffixes is defined by this target’s associated
prerequisite list. If you specify the special target more
than once, MKS Make adds each list of suffixes to a
single list, in the order they appear. The following
example specifies four valid suffixes for use with suffix
rules.
.SUFFIXES : y .c $O $E
To clear the list, specify this special target with an
empty prerequisite list. The .SUFFIXES special target
has no effect on metarule inferencing.
For additional information, see “Suffix Rules” on
page 286.
Special macros usually behave like macros, except they can hold
special kinds of information. MKS Make supports two kinds of
special macros; control macros and runtime macros.
Control macros control MKS Make’s behavior. A control macro
having the same function as an attribute, also has the same name.
MKS Make defines the runtime macros during the process of making
targets. Runtime macros usually only serve a useful purpose within
recipes; they can expand to contain the name of prerequisites or
targets within recipes. Dynamic prerequisite macros (a special type of
User Guide 271

Using the MKS Make Utility
runtime macro), however, serve a useful function when used in
prerequisite lists; they can refer to the associated target’s name (in
full, or in part).
Control Macros
MKS Make groups control macros into two sets: string-valued macros
and attribute macros.
MKS Make automatically creates internally defined macros. For
example, you can use $(PWD) to expand to the name of the present
working directory.
The following table describes some of the most useful string valued
macros. For a complete list, see the online command reference for the
make command.
Macro Description
DIRSEPSTR Defined internally, provides the characters that you can
use to separate components in a path name.
On UNIX and POSIX systems, this macro simply contains
the slash character (/).
On Windows 95/NT, and OS/2 systems, the startup.mk
file redefines DIRSEPSTR, according to the value you
specify for your SHELL environment variable. If the SHELL
variable is undefined, and COMSPEC is set, then the startup
file redefines DIRSEPSTR to contain a backslash, a
forward slash, and a colon (\/:). If you run MKS Make
with -r (so startup.mk is not read), or if SHELL is
defined, or if both SHELL and COMSPEC are undefined,
then the DIRSEPSTR special macro contains a string
consisting of forward slash, a backslash, and a colon (/
\:). If MKS Make finds it necessary to make a path name,
it uses the first character of DIRSEPSTR to separate path
name components.
NULL Defined internally, expands to an empty string. Use this for
comparisons in conditional expressions, and in
constructing metarules without ambiguity.
For more information, see “Using Inference Rules” on
page 281.
OS Defined internally, expands to the name of the operating
system.
OSVERSION Defined internally, expands to a string giving the major
version of your current operating system.
272 Source Integrity Professional Edition

For more information, see
“Attributes” on page 265.
Macro Description
Attribute Macros
Controlling MKS Make
OSRELEASE Defined internally, expands to a string giving the release
number of your current operating system.
The attribute macros let you turn global attributes on and off. You use
the macros by assigning them a value. If you assign a NULL value to
the macro, make turns off the associated attribute. If you assign a non-
NULL value to the macro, MKS Make turns on the associated
attribute and gives all targets that attribute.
The following macros correspond to attributes of the same name:
.EPILOG
.PRECIOUS
.PROLOG
.SILENT
PWD Defined internally, expands to the full path name of the
present working directory (that is, the directory that
MKS Make considers the current directory).
SHELL Set by the default rules and may be changed by you,
expands to the full path to the executable image used as
the shell (command interpreter) when processing singleline
recipes. You must define this macro if you use recipes
that require execution by a shell.
The default rules assign a value to this macro by
inspecting the value of the SHELL environment variable. If
this variable has no value, MKS Make gives it the value of
the COMSPEC environment variable.
SWITCHAR Defined internally, expands to the switch character
currently used to mark command-line options.
User Guide 273

Using the MKS Make Utility
Runtime Macros
MKS Make expands runtime macros when it carries out the recipes
that contain them. Except for dynamic prerequisite macros, runtime
macros do not produce useful values if placed outside recipes. The
following table describes the expansions for the runtime macros.
Macro Description
$@ The full name of the target, when building a normal target.
When building a library, it expands to the name of the archive
library (for example, if you specify the target as
mylib(member), $@ expands to mylib).
$% Also the full name of the target, when building a normal target.
When building a library, it expands to the name of the archive
member. With a target of mylib(member), $% expands to
member.
$* The target name, with no suffix. This macro produces the same
value as $(%:db).
$> The name of the library, if the current target is a library member.
With a target of mylib(member), $> produces the string
mylib.
$^ The list of prerequisites given in the current rule (that is, the rule
associated with the recipe that MKS Make is executing).
$& The list of all prerequisites in all rules that apply to the current
target. In :: rules, $& produces the same strings as $^.
$? The list of all prerequisites in all rules associated with the
current target, which are newer than that target or which need
to be created. However, in double colon rules (rules with the ::
rule operator) this macro produces the same string as the $<
macro.
$< Similar to $?, except it produces only those prerequisites that
prompt the execution of the current rule (not all changed
prerequisites associated with a single target). In normal rules,
the expansions contains the list of all changed prerequisites in
the current rule. In inference rules, however, it always contains
the single prerequisite of the executing rule. In rules using the
:! operator, this macro produces the current changed
prerequisite. For more information on rule operators, see the
man page for the make command.
$$ Produces a single dollar sign ($).
274 Source Integrity Professional Edition

For more information on
using libraries, see “Making
Libraries” on page 293.
Examples
Controlling MKS Make
The following examples help make the use of runtime macros a little
more clear. This first example begins with a simple pair of rules (to
ensure the portability of this example across platforms, it uses the
predefined macro, O, to represent the suffix string your system uses
for object files).
a$O : a.c
a$O : b.h c.h
recipe for making a’s object file
Assuming that a.c and c.h have recently changed, and that b.h has
not changed since the last time you built a$O, when MKS Make
executes the recipe for making a$O, the runtime macros expand to the
following values:
$@ a$O
$% a$O
$* a
Note that MKS Make would further expand the $@ macro’s
expansion, to produce the value for the O macro.
Next, here is an example of a library target.
mylib$A(mem1$O) :
recipe
When MKS Make rebuilds mylib$A, the appropriate runtime macros
would produce the following values:
User Guide 275
$>
$^ b.h c.h
$& a.c b.h
c.h
$? a.c c.h
$< c.h
$@ mylib$A
$% mem1$O
$* mem1

Using the MKS Make Utility
For more information on
dynamic prerequisites, see the
man page for the make
command.
Dynamic Prerequisite Macros
You can use a number of the runtime macros to create dynamic
prerequisites. When MKS Make encounters dynamic prerequisite
macros in the prerequisite list of a rule, it expands them when it
attempts to update the target. Only a few runtime macros produce
meaningful results when you use them as dynamic prerequisite
macros.
To construct a dynamic prerequisite macro, you place an additional
dollar sign in front of the runtime macro reference. The following
table explains the use of two runtime macros as dynamic prerequisite
macros.
Macro Description
$$@ Expands to the target name. If the target is a library, it produces
the name of the archive library. For example, with the macro
project : $$@.c
when MKS Make attempts to rebuild the object file, it expands
the $$@ dynamic prerequisite to produce the name of the target,
in this case project. You can make this example more useful
when you modify the value of $$@
project$O : $$(@:b).c
This time, you modify the $$@ macro’s value to select the
basename of the object file (and still produce project). The next
example shows a practical use for this macro.
file1 file2 : $$@.c
$(CC) -c $(CFLAGS) $@.c
You can see that, by using the $$@ dynamic prerequisite macro
in conjunction with the $@ runtime macro, you can compact two
rules into one general one. Without the runtime macros, you
would need a separate rule for each of the two files.
$$* Produces the name of the target, but without the suffix. The
following two rules contain identical prerequisites.
project$O : $$(@:b).c
project$O : $$*.c
You can also use the symbols $$% and $$> to create useful dynamic
prerequisites.
276 Source Integrity Professional Edition

How Make
Finds Files
Controlling MKS Make
Makefiles often specify target names in the shortest manner possible,
relative to the directory that contains the target files. MKS Make
possesses sophisticated techniques to search for the file that
corresponds to a target name in a makefile.
Assume that MKS Make tries to locate a target with a name in the
format pathname.ext, where .ext is the suffix and pathname is the stem
portion (that is, that part which contains the path and the file name).
When given an relative path name, MKS Make uses the following
rules to find the file.
1. Look for pathname.ext relative to the current directory, and use it,
if found.
2. Otherwise, if the .SOURCE.ext special target is defined, search
each directory given in its list of prerequisites for pathname.ext. If
.ext is a NULL suffix (that is, pathname.ext is simply pathname)
use .SOURCE.NULL instead. If found, use that file.
3. If .SOURCE is defined, search each directory in its prerequisite list
for pathname.ext. If found, use that file.
4. If still not found and the target is a member of a library, try to find
the target in that library. This same set of rules is used to bind a
file to the library target at an earlier stage of the makefile
processing.
5. If still not found, the search fails. MKS Make returns the original
name pathname.ext.
If at any point the search succeeds, MKS Make replaces the name of
the target with the file name it finds, and refers to it by that name
internally.
There is potential here for a lot of search operations. The trick is to
define .SOURCE.x special targets with short search lists and leave
.SOURCE undefined, or as short as possible. Initially, MKS Make
simply defines .SOURCE as
.SOURCE : .NULL
In this context, .NULL in the prerequisite list prompts MKS Make to
search the current directory by default.
The search algorithm has the following useful side effect. When
MKS Make searches for a target that is a member of a library, it first
searches for the target as an ordinary file. When a number of library
members require updating, you may find it most efficient to compile
User Guide 277

Using the MKS Make Utility
all of them first and to update the library at the end in a single
operation. If one of the members does not compile and MKS Make
stops, you can fix the error and run it again.
MKS Make does not remake any of the targets it has already
generated object files for, as long as their prerequisite files remain
unchanged.
If the target is a library member, MKS Make begins its search for the
target in that library. If it finds the target, it searches for the member
using the search rules. Thus, MKS Make first binds library entry
point specifications to a member file, and then checks that member
file to see if it has changed.
If you specify the .SOURCE or .SOURCE.x targets more than once,
MKS Make appends all the prerequisites to one list. However, you
can clear the list of prerequisites by specifying the target with a null
prerequisite list. In addition, you can use MKS Make’s :- rule
operator to clear a previously set list of path names. Thus, the
following two examples are equivalent.
.SOURCE :
.SOURCE : /usr/fred /usr/gerry
# these two lines are equivalent to the next one
.SOURCE :- /usr/fred /usr/gerry
More generally, the processing of the .SOURCE special targets is
identical to the processing of the .SUFFIXES special targets.
Example: Directory Navigation Within a Makefile
Sometimes you might want to have a recipe run while the directory is
set to something else other than the current directory. The .SETDIR
attribute tells make to change the current directory for the duration of
the recipe with the attribute set. Here’s an example:
all: subdir two
echo not in subdir
pwd
# Remember to clean up afterwards by
# removing subdir.
subdir:
mkdir subdir
# Note: We can’t put "subdir" as a prerequisite
# for "two" because subdir has to exist before
# anything to do with "two" is processed.
two .SETDIR=subdir:
echo in subdir
pwd
278 Source Integrity Professional Edition

Controlling MKS Make
Note that .SETDIR does not work with metarules. The previous
example is written to work with the MKS Toolkit. If you do not have
the MKS Toolkit installed, then change pwd to cd to display the
current directory.
Example: Including External Makefiles
Make has facilities for including other makefiles into the current
makefile. Normally, make looks in the current directory for these files.
The special targets, .INCLUDEDIRS and .INCLUDE, can be used to
inform make to look elsewhere for these files.
The following example relates back to the following three makefiles,
two of which are located in the subdirectories 1 and 2.
The main makefile:
all: one two
.INCLUDEDIRS: 1
.INCLUDE:
.INCLUDE: 2/2.mak
Makefile 1/1.mak:
one:
echo one
Makefile 2/2.mak:
two:
echo two
The “.INCLUDEDIRS” line in makefile tells make where it should look
for makefiles not found in the current directory. In effect,
subdirectory 1 becomes part of the search path for makefiles. The
“.INCLUDE: ” line in makefile asks make to find the file
1.mak; the “” indicates to make that it should not look in the current
directory for 1.mak but it should look elsewhere in the .INCLUDEDIRS
list of directories. 1.mak is found in the subdirectory 1 so make
includes it. The “.INCLUDE: 2/2.mak” line asks make to include the
file 2/2.mak.
After the .INCLUDE’s are replaced by the appropriate files, the
effective makefile would look like this:
all: one two
.INCLUDEDIRS: 1
one:
echo one
two:
echo two
User Guide 279

Using the MKS Make Utility
Another method of indicating which files should be used as
makefiles is to use the .MAKEFILES special target in the startup.mk
file. Consider
.MAKEFILES: $(PWD:f).mk
This tells make to look in the current directory for the makefile, with
the name of the makefile the same as the current directory name (that
is if in src/make, look for make.mk). Adding dependencies using
.MAKEFILES does not override the standard makefile lookup
behavior; it just adds new file names for make to consider as
makefiles. By default, make looks for the file makefile. On UNIX
versions, make also looks for Makefile.
Example: Creating Prologs and Epilogs
With make, you can formulate recipes so that certain processes always
happen before a recipe is run, or after the recipe has completed. This
capability is controlled with the .PROLOG and .EPILOG attributes, and
with the .GROUPPROLOG and .GROUPEPILOG special targets. Consider
the makefile
all: GroupWithProlog GroupWithEpilog
GroupWithBoth NonGroupRecipe
GroupWithProlog .PROLOG .SILENT:
[
echo In prolog group recipe
echo
]
GroupWithEpilog .EPILOG .SILENT:
[
echo In epilog group recipe
]
GroupWithBoth .PROLOG .EPILOG .SILENT:
[
echo In prolog/epilog group recipe
]
.GROUPPROLOG:
echo Running prolog
.GROUPEPILOG:
echo Running epilog
echo
NonGroupRecipe .PROLOG .EPILOG .SILENT:
echo In non group recipe with .PROLOG and .EPILOG
attributes set
280 Source Integrity Professional Edition

Using Inference Rules
For more information, see
“Suffix Rules” on page 286.
Using Inference Rules
The .GROUPPROLOG special target defines a special recipe that gets run
before a group recipe runs. Only those group recipes that have the
.PROLOG attribute are so affected; all others behave normally.
Similarly, the .GROUPEPILOG special target defines a special recipe
that gets run after a group recipe runs, again, only for those group
recipes with the .EPILOG attribute.
In the previous example, the targets GroupWithProlog and
GroupWithBoth have the .GROUPPROLOG recipe executed before their
recipes run. The targets GroupWithEpilog and GroupWithBoth have
the .GROUPEPILOG recipe executed after their recipes run.
The regular recipe NonGroupRecipe has neither special recipe run,
even considering that it has the .PROLOG and .EPILOG attributes.
Prologs and epilogs only apply to group recipes.
Macros present one means for making your makefiles more general.
MKS Make has another feature that can help you construct truly
generic makefiles—inference rules. When you make an inference, you
associate a target with a prerequisite by matching specific files
against general patterns and determining whether the target needs
rebuilding.
Inference rules can help you build makefiles to handle general cases.
You can create a single makefile that can check any object file and
rebuild it from its associated source file if it is out of date. MKS Make
provides two different kinds of inference rules.
Metarules employ a form similar to normal rules; however, they
describe general methods, not specific procedures.
Other versions of make may not recognize the new metarule format
presented here; instead they use a less general form of inference rules
called suffix rules. For compatibility, MKS Make still supports suffix
rules.
When you run MKS Make, it searches through the makefile using the
following rules, attempting to find a recipe to rebuild a target. Once a
step succeeds, it skips the subsequent steps.
1. Search all the explicit rules in the makefile for one that matches
the target.
2. Check to see if an appropriate metarule matches the target.
User Guide 281

Using the MKS Make Utility
For more information on how
to use the .DEFAULT special
target, see the man page for
the make command.
Metarules
3. Check to see it an appropriate suffix rule matches the target.
4. Check to see if you have defined the .DEFAULT special target. You
can use this special target to specify a recipe that MKS Make
should use when no other rule would apply to a target.
If you have not defined the .DEFAULT special target, and no other rule
matches the target, MKS Make displays an error and stops.
A metarule states that targets with names that match a pattern depend
upon prerequisites with names that match a pattern. You may specify
either pattern in the rule.
Every metarule has a standard format. MKS Make treats any rule
with a % symbol in the target as a metarule.
target_pref %target_suffix : prereq_prefix%prereq_suffix
recipes
You can omit any of the prefix and suffix strings. If the % symbol
appears in the prerequisite, it stands for whatever string matched the
% symbol in the target.
Note To include more than one prerequisite entry, you should use the :|
rule operator instead of the single colon operator. For more information
on this rule operator, see the man page for the make command.
For example, consider the metarule that matches object file targets
with their source file prerequisites.
%$O : %.c
$(CC) -c $(CFLAGS) $<
The target in the metarule represents any file with an object file
extension; in other words, any object file. The percent symbol
represents the base name of the target; the O macro expands, as usual,
to your system’s object file extension.
The prerequisite represents the source file corresponding to the
target. MKS Make determines the appropriate source file by looking
for a file with the same base name as the target, coupled with the .c
source file extension.
The recipe for this rule contains the command to compile the single
prerequisite that matches the target (note the use of the $< special
macro here). MKS Make expands this macro to provide the single
inferred prerequisite, that is, the single prerequisite it was able to
match to the target file.
282 Source Integrity Professional Edition

Here is another example, this time of a makefile employing
metarules.
Using Inference Rules
FILES = main myFunc
# notice the use of the $E macro representing
# the executable file extension
program$E : $(FILES:+$O)
$(CC) $(CFLAGS) -e$@ $&
%$O : %.c
$(CC) -c $(CFLAGS) $<
When MKS Make attempts to rebuild program$E (here the
predefined E macro represents the executable file extension for your
system), it checks the two specified object files to see if they, in turn,
require rebuilding.
MKS Make notes that these files end in the object file extension for
your system, by expanding the O macro. Since these files lack a
particular rule that names them as targets, MKS Make subsequently
checks for any matching metarule. The metarule (the second rule in
the makefile) does match the object file names, so it is used to rebuild
the object files.
Employing the metarule, MKS Make looks for the object files’
matching source files (which end in a .c extension), and runs them
through the compiler.
Note the lack of specific reference to any object file in this makefile.
MKS Make infers the appropriate object files by expanding
$(FILES:+$O), and uses the metarule to match object files with their
associated source.
Here is another example, one that demonstrates the use of another
common metarule.
% .PRECIOUS : rcs/%$V
-co -q $<
The metarule states that any target (file) depends upon a prerequisite
(an associated archive file) located in an rcs subdirectory. MKS Make
matches any archive file to its associated working file. The recipe line
uses the $< runtime macro to represent the prerequisite matching the
target. Notice that it uses the dash command prefix. MKS Make
ignores the failure of the check out (co) command (as it should, for
example, if a revision of the file has already been checked out).
Also, notice that it uses a macro called V to represent the possible
archive file extension for the archive file. On UNIX-based systems,
archive files usually end with a ,v extension. On PC-based systems,
User Guide 283

Using the MKS Make Utility
For more information on
attributes, see the man page
for the make command.
archive files may have names identical to their associated working
files (that is, V would have a null value). Source Integrity allows you
to change your archive file names; thus you can change the V macro
to match the extension you chose for archive files.
A metarule may specify an attribute for a target. The previous
example assigned the .PRECIOUS attribute to the target. Any attribute
specified in a metarule gets inherited by any target that matches that
metarule.
If MKS Make attempts to make a target that has an attribute, it first
checks for a metarule that applies to the target and specifies the given
attribute. If no such metarule exists, it looks for a metarule that does
not specify the attribute. This lets you specify different metarules for
targets with different attributes. MKS Make performs this test for all
attributes except .SILENT, .IGNORE, and .SYMBOL.
Using the :| Rule Operator with Metarules
MKS Make supports a rule operator for use specially in metarules
that have more than one entry in the prerequisite list. This operator
allows you to write one metarule as a short form for a number of
similar metarules. The :| rule operator prompts MKS Make to treat
each inferred match in the prerequisite list as an independent
metarule.
To understand this more clearly, take another look at the previous
example. It included a metarule that would allow you to check out
any working file from its associated archive. What if you maintain
different archive locations for different kinds of working files? You
store some files in local archive subdirectories and some more general
files in a central archive tree.
You would be tempted to compose two metarules to handle the two
particular cases separately, but the following simple example does
the trick.
% .PRECIOUS :| rcs/%$V /archive/%$V
-co -q $<
When MKS Make encounters the :| operator, it handles each
prerequisite in the list independently, applying the same recipe to
each prerequisite in turn. Thus, the previous example is identical to
these two rules.
% .PRECIOUS : rcs/%$V
-co -q $<
% .PRECIOUS : /archive/%$V
-co -q $<
284 Source Integrity Professional Edition

Using Inference Rules
When MKS Make uses these rules, it first checks to see if an archive
associated with the working file exists in the rcs subdirectory. If no
archive exists there, it attempts to infer a match with an archive file in
a central directory.
Transitive Closure
With metarules, MKS Make can draw a chain of inferences across files
that may not exist, resulting in the eventual creation of a target. This
process is called transitive closure of inferences. Consider the
following example of two metarules:
%$E : %$O
recipe one
%$O : %.c
recipe two
When you use MKS Make to rebuild an executable called foo$E, it
uses the first metarule to look for the object file, foo$O. If this file does
not exist, and it cannot find an explicit rule that describes the way to
create the necessary object file, MKS Make finds the second metarule,
which describes the general procedure for rebuilding an object file.
MKS Make considers each metarule only once when performing
transitive closure, to avoid an endless loop. If it did not do this,
certain rules would create problems. For example
% : %.c
recipe
If you used this metarule, when using MKS Make with the target foo,
it would first look for the file foo.c. If it could not find this file, it
would then look for foo.c.c, and so on. Because MKS Make uses
each metarule only once, it avoids the endless loop.
MKS Make computes transitive closure once for each metarule, the
first time the pattern matches a target. As metarules match,
MKS Make joins the recipes together, in order leading backwards to
the first metarule.
Thus, using the previous example of two metarules, transitive closure
produced the following rule, when foo.exe matched the first
metarule (the one for executables).
%$E : %.c
recipe two
recipe one
User Guide 285

Using the MKS Make Utility
For more information on this
process, see the man page for
the make command.
Suffix Rules
If the object file for the executable does not exist, transitive closure
allows MKS Make to infer that it needs to first build the required
object file from source, using this newly generated rule.
When MKS Make finishes the computation for the rule head, it marks
that rule head as transitive closure completed. Since it adds all
possible new rules to the rule set the first time it performs the
computation, MKS Make will not compute transitive closure again;
nothing new can be added to the rule set.
To understand this process best, you might want to experiment on
small makefiles, using the -v option to the make command. This
displays the behavior in detail: which rules it searches, when it
computes transitive closure, and which rules it adds to the set.
MKS Make follows a particular order when attempting to make
inferences.
An older portable form of inference rules, suffix rules use the format
# typical suffix rule
.suf1.suf2:
recipe
MKS Make matches the suffixes against the suffix of a target when it
cannot locate an explicit rule for that target. However, suffix rules are
not as powerful or as intuitive as metarules.
For example, to express the dependence of object files upon source
files, you would need a suffix rule that looked like
.c$O:
$(CC) -c $(CFLAGS) $<
Compare this with the equivalent metarule.
# normal rule
file$O : file.c
$(CC) -c $(CFLAGS) file.c
# metarule
%$O : %.c
$(CC) -c $(CFLAGS) $<
You can see that the construction of the suffix rule seems backwards.
By itself, this gives a good reason to avoid suffix rules; you will find
makefiles with suffix rules much more difficult to read.
286 Source Integrity Professional Edition

Using Inference Rules
You can also construct suffix rules with only one suffix. These match
any file ending in that suffix and provide a recipe for making a target
with no suffix from a prerequisite with a given suffix.
# single suffix rule
.c :
$(CC) -o$@ $(CFLAGS) $<
For a suffix rule to work, you must list the component suffixes in the
prerequisite list of the .SUFFIXES special target. To turn off suffix
rules, simply use the special target with a null prerequisite list.
.SUFFIXES:
This clears the prerequisites of any previously declared .SUFFIXES
special targets, and prevents make from using any suffix rules when
inferring matches. You determine the order in which MKS Make uses
suffix rules by the order of the prerequisites associated with the
.SUFFIXES special target.
The following list describes how MKS Make handles suffix rules with
targets that have suffixes in their names.
Extract the suffix from the target.
Check the .SUFFIXES special target’s prerequisite list; if the suffix
does not appear in the list, quit searching.
If the suffix does appear in the list, look for a double suffix rule
that matches the target suffix.
If one exists, extract the base name of the target, add on the
second suffix, and look for a file with the resulting name. If such a
file exists, use the recipe from that double suffix rule to rebuild
the target. If no such file exists, look for another double suffix rule
that matches the target suffix.
If MKS Make cannot find a double suffix rule to construct the
name of an existing file with the new suffix, the inference fails.
The following list describes how MKS Make handles suffix rules with
targets that have no suffix in their name.
Check the single suffix rules in the order specified by the
.SUFFIXES special target.
For each single suffix rule, add the suffix to the target name, and
check to see if a file exists with the resulting name. If such a file
exists, use that recipe to rebuild the target.
If MKS Make cannot find a single suffix rule to construct the
name of an existing file, the inference fails.
User Guide 287

Using the MKS Make Utility
Try some experiments on small makefiles, using make with the -v
option, to see suffix rules work.
More About Executing Recipes
Regular
Recipes
Note Because MKS Make searches met-rules first, you should specify
the -r option on the command line to disable the default met-rules when
experimenting with suffix rules.
To update a target, MKS Make expands and executes a recipe. The
expansion process replaces all macros and text diversions within the
recipe, then either executes the commands directly, or passes them to
a shell or command interpreter, depending on the occurrence of shell
metacharacters in the recipe.
When MKS Make calls a regular recipe, it executes each line of the
recipe separately. This means that the effect of some commands may
not carry over from one recipe line to the next.
For example, a change directory request (cd) in a recipe line changes
the current directory only for that recipe line. The next recipe line
reverts to the previous current directory.
The value of the control macro SHELLMETAS determines whether
MKS Make uses a shell to execute a command. If it finds any
character in SHELLMETAS in the expanded recipe line, it passes the
command to the shell for execution; otherwise, it executes the
command directly.
Note If the makefile contains the .POSIX special target, MKS Make
always uses the shell to execute recipe lines.
To force the use of a shell, you can add characters from SHELLMETAS to
the recipe line, as in the example
rule 1
# the next lines contains shell metacharacters
command_one > file_one
command_two | command_three
…
288 Source Integrity Professional Edition

Built-In
Commands
Group Recipes
More About Executing Recipes
The value of the control macro SHELL specifies the shell used for
execution. The value of the control macro SHELLFLAGS provides the
options that passed to that shell. The SWITCHAR control macro gives
the character used to mark the beginning of the flags.
Therefore, the command to run the expanded recipe line is
$(SHELL) $(SWITCHAR)$(SHELLFLAGS) expanded_recipe_line
Normally, just before MKS Make invokes a recipe line, it writes the
line to the standard output. If you have set the .SILENT attribute for
the current target or recipe line (using the @ command prefix), the line
is not echoed to the standard output.
Since command.com and cmd.exe incorporate some frequently used
commands as built in commands (for example, del, dir, and type),
you cannot execute these commands directly from makefiles. You
can, however, call the command interpreter to execute the instruction.
The following example demonstrates how to delete a file called
myfile.txt on Windows 95/98:
command $(SWITCHAR)c del myfile.txt
This invokes a command interpreter (as determined by the value of
the COMSPEC macro) with the c option prefaced by the value of the
SWITCHAR control macro, and passes it the del command with an
appropriate argument (that is, the name of the file you want to
delete).
On OS/2 or NT systems, you would use
cmd /c del myFile.txt
MKS Make can also handle bundles of commands, or group recipes, by
passing them to the appropriate command interpreter (shell) as a
single unit. Traditional versions of make do not offer this feature.
A group recipe begins with an opening bracket ([) in the first
non-white space position of a line, and ends with a closing bracket (])
in the last non-white space position of a line. Group recipes do not
need a character as the first characters on a line.
When MKS Make determines that the associated target requires
rebuilding, it passes the entire group recipe in a block to the shell.
User Guide 289

Using the MKS Make Utility
Control Macros
Used With
Group Recipes
A typical group recipe might involve special command constructs,
like the looping constructs of the MKS KornShell. The following
example creates a loop that use the fmt command to format each file
in a directory, appending the formatted material to the book file:
book : chap1.tr chap2.tr chap3.tr
[
>book
for chapFile in $^
do
fmt -j -l 66 $$chapFile >>book
done
]
MKS Make expands the group recipe before passing it to the shell.
Thus, you need to place an extra dollar sign in front of the chapFile
variable, to prevent MKS Make from attempting to expand the
variable before it passes the line to the shell for execution.
You can assign command prefixes to entire group recipes by placing
the command prefix immediately after the initial bracket. The
command prefix then applies to the group recipe exactly as it would
for a single recipe line.
When MKS Make processes a group recipe, it writes the recipe to a
temporary file. You specify an appropriate suffix for the temporary
file with the value of the GROUPSUFFIX control macro. The command
interpreter that handles the group recipe must recognize the suffix
you specify with the GROUPSUFFIX control macro.
If you use command.com, you must specify the .bat suffix. If you use
cmd.exe, specify .cmd (although NT also accepts the .bat suffix). If
you use the MKS KornShell, specify .ksh.
You specify the shell MKS Make passes the group recipe to by
defining a value for the GROUPSHELL macro. The value of the
GROUPFLAGS macro determines the flags that are passed to the
appropriate shell, along with the group recipe.
If you have associated the .PROLOG attribute with the target of the
rule containing the group recipe, MKS Make prepends the recipe
associated with the .GROUPPROLOG special target to the front of the
group recipe before passing it to the appropriate shell.
290 Source Integrity Professional Edition

Text Diversions
More About Executing Recipes
If the group recipe’s target has the .EPILOG attribute, MKS Make
appends the recipe associated with the .GROUPEPILOG special target
to the end of the group recipe before passing it to the shell. You can
use these two procedures to append a common header or trailer to
group recipes.
MKS Make echoes group recipes to standard output just like
standard recipes, unless you use the .SILENT attribute with the
associated target or the @ command prefix.
MKS Make allows you to directly create files from within a recipe.
This feature is an extension to traditional versions of make. The
following example shows the format of a text diversion:
The specified text can be anything—several lines long if desired.
When MKS Make encounters this construct, it creates a temporary
file with a unique name, expands any macros in the text, and copies
the text to the temporary file. It then executes the recipe with the
name of the temporary file inserted in place of the diversion. When
MKS Make finishes processing, it removes all the temporary files.
Note Use the -v option to the make command to show the names of
these temporary files and leave them around to be examined.
MKS Make places temporary files in the $ROOTDIR/tmp directory
unless you have specified a value for the TMPDIR environment
variable, in which case, it places all temporary files in $TMPDIR.
All macro references found in the text are expanded in the normal
way; references in the temporary file are replaced by their associated
strings. MKS Make copies all newline characters as they appear in the
diversion.
Normally, MKS Make does not copy white space at the beginning of
lines into the temporary file. However, if you put a backslash at the
front of a white space character, it copies all the white space in that
line to the temporary file.
For example,
User Guide 291

Using the MKS Make Utility
As a simple example of text diversion, suppose you redefine the
value of the MAKESTARTUP macro on the command line to point to
your personal startup file (/usr/lindsay/startup.mk). Next, you
write a recipe line like
copy startup.msg
MKS Make creates a temporary file containing the text
using /usr/lindsay/startup.mk as make startup file
Since white space is stripped from the beginning of the second line,
the contents of the temporary file end at the newline character that
terminates the first line.
MKS Make gives this temporary file a unique name. Suppose it uses
the name temp.txt. The original recipe line is changed to
copy temp.txt startup.msg
When finished, startup.msg holds the contents of the temporary file.
Here is a more useful example.
OBJECTS=program$O module1$O module2$O
program$E: $(OBJECTS)
link @
The tokenizing expression
$(OBJECTS:t"+\n")
adds a + and a newline after each token in the OBJECTS macro.
Remember the runtime macro $@ stands for the name of the target
being made. As a result, the temporary file created from the text
diversion has the following contents (with all the macros expanded,
of course).
program$O+
module1$O+
module2$O
program$E/noignorecase
$(LDLIBS)
The link command can easily handle an input file like this. Here’s
the recipe line after MKS Make processes the text diversion.
link @tempfile
292 Source Integrity Professional Edition

Making Libraries
Making Libraries
All the MKS utilities can handle command lines of at least 8192
characters in length.
If you need to use non-MKS utilities, text diversions can help you
pass input to a utility such as a linker, while respecting the commandline
length restriction, as in this example:
program$E : $(OBJECTS)
bcc -eprogram$E @
This example builds program$E from a lengthy list of object files,
using the Borland C++ compiler.
A library is a file containing a collection of object files and a symbol
table. You can explicitly signal MKS Make that a target is a library, by
giving the target the .LIBRARY attribute; however, you do not need to
do this.
You can construct rules to handle libraries simply by writing rules in
the following format:
program_name : library_name(member)
library_name :
recipe
MKS Make can automatically determine that the target library_name
is a library. In other rules it interprets member as a prerequisite of the
library target. MKS Make internally associates the library name with
the prerequisites. This lets the file searching mechanism look for the
member in an appropriate library if it cannot be found as an object
file.
Note If you specify either the .POSIX or .NOAUTODEPEND special target,
MKS Make does not check for an object file; it always looks in the library
archive.
Using these features, you can write rules like
program$E : mylib$A(mem1$O)
recipe for making program
mylib$A :
recipe for making library
mem1$O : mem1.c
recipe provided by built-in rules
User Guide 293

Using the MKS Make Utility
Metarules for
Library Support
For further information, see
the man page for the ar
command.
Note that MKS Make startup rules give the A macro and the
LIBSUFFIX macro the appropriate file extension for library files on
your system. On UNIX and Xenix systems this would be .a; under
command.com and cmd.exe, this would be .lib.
If any target or prerequisite has the following format, MKS Make
assumes that entry is a member of a library called name:
name((entry))
MKS Make then searches the library for the entry, determining the
modification time of the member that defines entry, and the name of
the member file. This name then replaces entry, and MKS Make uses it
to make the member file.
The startup file defines several macros and metarules useful for
manipulating libraries. A gives the standard suffix for a library, and O
gives the standard suffix for an object file.
The AR macro specifies the librarian program. By default, the macro
contains the ar program provided with MKS Make, and ARFLAGS
contains the string -ruv. These flags cause ar to update the library
with all the specified members that have changed since the library
was last updated.
The startup file contains the metarule
%$A .LIBRARY .PRECIOUS :
$(AR) $(ARFLAGS) $@ $?
With this metarule, you need not directly use the ar command in
your makefile. MKS Make automatically rebuilds a library with the
appropriate suffix when any of the prerequisite object modules have
changed. As an example of the effect of this metarule, consider the
rule
lib$A .LIBRARY : mod1$O mod2$O mod3$O
MKS Make gives the .LIBRARY attribute to the lib$A target, so the
metarule applies. Using the command.com or cmd.exe command
interpreters, the following command remakes the library from the
appropriate object modules:
make lib.lib
On UNIX and POSIX compliant systems, libraries have the .a suffix,
so the following command is equivalent:
make lib.a
294 Source Integrity Professional Edition

For more information on the
+= symbol, see the man page
for the make command.
Suffix Rules for
Library Support
Making Libraries
The startup file contains a metarule that MKS Make uses to rebuild
executable files from object files. This metarule adds the value of the
macro LDLIBS as a list of libraries you want make to link with the
object files. If you have several programs, all of which depend on the
same library, you can add the name of your library to the definition of
LDLIBS and automatically get it linked when using the metarule.
For example, assume the startup file specifies the following metarule
for your compiler:
%$E : %$O
$(LD) $(LDFLAGS) -o $@ $^ $(LDLIBS)
You can add the following lines to your makefile:
LDLIBS += mylib$A
program$E : mylib$A
The first line appends mylib$A to the current definition of LDLIBS.
The second line handles the program you want to build using this
library (you could have any number of different program file targets
with the same prerequisite). Because you have not specified a recipe,
MKS Make uses the metarule from the startup file to relink the
programs.
Thus, when you want make to rebuild the program file target,
MKS Make remakes the library file mylib$A if required, and then
relinks the executable from the object file with the libraries specified
in LDLIBS.
Suffix rules also have a feature that supports archive library
handling. If you specify a suffix rule with the following form, the rule
matches any target having the .LIBRARY attribute set, regardless of
the target’s actual suffix.
.suf.a:
recipe
For example, if mem.obj exists and your makefile contains the rules
.SUFFIXES: .a .obj
.obj.a :
@echo adding $< to library $@
the command
make -r "mylib(mem)"
User Guide 295

Using the MKS Make Utility
causes MKS Make to print
adding mem.obj to library mylib
Compatibility Considerations
Conditionals
Note The -r option keeps the rules in the startup.mk file from
interfering with the command in this example.
MKS Make attempts to remain compatible with versions of the make
utility found on UNIX and POSIX compliant systems, while meeting
the needs of different environments such as Windows 95/98,
Windows NT, and OS/2.
This section examines ways in which MKS Make differs from
traditional versions of make. It also discusses techniques to write
makefiles that work on UNIX, Windows 95/98, Windows NT, and
OS/2 systems.
Conditionals let you selectively include or exclude parts of a makefile.
This lets you write rules that have different formats for different
systems. Note that traditional implementations of make do not
recognize conditionals. Conditionals are extensions to the POSIX
standard.
You construct conditionals with the following format:
.IF expression1
input1
{.ELSIF expression2
input2}
[.ELSE
input3]
.END
You may have any number of .ELSIF expressions, but only one
.ELSE expression.
When MKS Make encounters a conditional construct, it begins by
evaluating expression1 (associated with the .IF). If the value of
expression1 is true, MKS Make processes the first input block (input1)
and ignores all subsequent input blocks until the .END.
296 Source Integrity Professional Edition

Compatibility Considerations
If the value of expression1 is false, MKS Make ignores the first input
block and tests expression2 (associated with the .ELSIF). If expression2
is true, the second input block (input2) is processed, and all
subsequent input blocks until the .END are ignored.
If the value of expression2 is false, MKS Make ignores the first two
input blocks and automatically process the third input block
(associated with the .ELSE).
When MKS Make evaluates expressions, it accepts an expression with
one of the following forms:
text
text1 == text2
text1 != text2
The first entry is false if text is null; otherwise, it is true. The value of
the second entry is true if text1 and text2 are equal. The last entry
resolves to true if text1 and text2 are not equal.
The .IF, .ELSE, .ELSIF, and .END keywords must begin in the first
column of an input line (that is, with no leading white space).
Although you may be used to indenting material inside IF/ELSE
constructs, you must not use s to indent text inside conditional
blocks (except for recipe lines, which are always indented with a
).
Text in a conditional block should have the same form that you
would use outside the block. You may omit the .ELSE and .ELSIF
conditional operators. This would produce a conditional block that
MKS Make would process if the .IF expression were true, and
completely ignore if that expression were false.
This example shows the concept behind the O macro.
.IF $(OS) == NT
O = .obj
.ELSE
O = .o
.END
This begins by checking the predefined value of the OS macro that
identifies your operating system. If the macro expands to NT,
MKS Make assigns the value .obj to the O macro; otherwise, the
macro receives the value .o.
User Guide 297

Using the MKS Make Utility
Other Makes
You can use conditionals to prepare a makefile that runs on
Windows 95, Windows NT, OS/2, and UNIX systems. You may find
it simplest to check the value of the macro OS (defined in the built in
rules). You can then use conditionals like
.IF $(OS) == NT
# NT style input
.ELSE
# UNIX style input
.END
With care, you can produce a makefile that works under more than
one operating system.
.IF $(OS) == NT
E=.exe #suffix for executable programs
O=.obj #suffix for object files
S=.asm #suffix for assembler source
A=.lib #suffix for libraries
F=.for #suffix for fortran source
V= #suffix for Source Integrity archives
.ELSE
E=
O=.o
S=.s
A=.a
F=.f
V=,v
.END
LIBSUFFIX=$A
These macro definitions specify suffixes used on UNIX systems. You
can then use a suffix macro like
%$O : %.c
$(CC) $(CFLAGS) $^
It expands to .o on UNIX and POSIX compliant systems.
Note The default startup rules for MKS Make already provide most of
these definitions with values appropriate to your system.
Several other versions of the make utility exist for Windows 95/98,
Windows NT, and OS/2. The following sections examine some
popular make utilities and how they differ from MKS Make.
298 Source Integrity Professional Edition

Borland Make
Compatibility Considerations
The Borland C++ packages from Inprise Corporation comes with
their own version of make. Here are some of the ways in which the
Borland Make differs from MKS Make:
Borland Make does not support the general metarule format of
inference rules, only the suffix rule format.
Borland Make does not support multiple command processors
(for example, the MKS KornShell); it uses only the native
command processor.
Borland Make does not have general macro modifiers (such as :d
and :f).
The directives of Borland Make take the form !word, where word
is the directive name. The set of directives includes conditionals,
include facilities (similar to .INCLUDE), and a facility for
undefining macros. No other directives are supported. The
format of these facilities is not compatible with any UNIX or
POSIX compliant version of make.
Borland Make has no facilities for handling libraries or Source
Integrity files. It does not have group recipes or special rule
operators, and lacks most of the special macros and special
targets supported by MKS Make.
Borland Make lets you specify a number and compare it to the
return status of a command in a recipe line. If the return status
exceeds this number, Borland Make stops the make process,
saying that an error was detected.
MKS Make lets you use the minus sign to ignore errors entirely. To
compare a specific exit value, use the MKS KornShell as your SHELL
and write a group recipe like
[
]
command to be tested
if [ $? != 5 ]
echo "diagnostic"
exit 1
fi
exit 0
If you have a makefile for Borland Make that you want to convert for
use with MKS Make, you need to change all the directives from the
!word format into the MKS Make equivalent.
User Guide 299

Using the MKS Make Utility
Microsoft Make
The Microsoft C++ package also comes with its own version of make.
Here are some of the differences between Microsoft Make and
MKS Make:
Microsoft Make does not support the general metarule format of
inference rules; it only supports the suffix rule format.
Microsoft Make does not support multiple command
interpreters; it uses only the native command processor.
Microsoft Make has no facilities for handling libraries or Source
Integrity archives. It does not have group recipes, and lacks most
of the special macros and special targets supported by
MKS Make.
The set of special macros recognized by Microsoft Make is much
smaller. It uses $** to represent the same thing as the $& runtime
macro in MKS Make (that is, the complete list of prerequisites for
the current target).
Because Microsoft Make operates at such a simple level, any makefile
that works with Microsoft Make works with MKS Make by simply
changing the $** symbols to $& runtime macros.
Note Naturally, you must use the MKS Make command-line options
instead of those for Microsoft Make.
BSD UNIX Make
The following is a list of the notable differences between MKS Make
and the 4.2/4.3 BSD UNIX make:
BSD UNIX make supports file name generation for prerequisite
names. Thus, if a directory contains a.h, b.h, and c.h, BSD UNIX
make performs the following expansion:
target: *.h
expands to
target: a.h b.h c.h
MKS Make does not support this type of file name expansion.
300 Source Integrity Professional Edition

Compatibility Considerations
Unlike BSD UNIX make, touching library members causes
MKS Make to search the library for the member name and to
update the time stamp if the member is found (see the
description of the -t option in the online reference for the make
command).
MKS Make does not support the BSD UNIX VPATH variable. A
similar and more powerful facility is provided through the
.SOURCE special target.
System V MAKE
The following special features have been implemented to make
MKS Make more compatible with System V make:
You can use the word include at the start of a line instead of the
.INCLUDE special target that is normally understood by
MKS Make.
MKS Make supports the macro modifier expression
$(macro:str=sub) for suffix changes.
When defining special targets for the suffix rules, the special
target .X is equivalent to .X.NULL.
MKS Make supports both the
lib(member)
and
lib((entry))
library handling features of System V make.
The built in rules contain the following definitions for System V
make compatibility:
@B = $(@:b)
@D = $(@:d)
@F = $(@:f)
?B = $(?:b)
?D = $(?:d)
?F = $(?:f)
*B = $(*:b)
*D = $(*:d)
*F = $(*:f)

Using the MKS Make Utility
Using the Generic CC Interface
For a description of the
command-line format, see the
man page for the cc
command.
Compilation
Configuration
Files
The command-line syntax of different C compilers varies widely.
Under Windows 95/98, Windows NT, and OS/2, some compilers use
a dash to mark options, others a slash, while some accept both
characters. In addition, each compiler usually requires that
command-line arguments be specified in a different order. On UNIX
and POSIX compliant systems, there is a greater degree of uniformity,
but there are still differences from one system to the next.
Because of this diversity, it is difficult to write makefiles that apply to
several compilers and/or systems. The following example is typical,
but even this format is not universal. In particular, the -c argument
may not have the same meaning to different compilers or may not be
allowed in the position shown.
$(CC) -c $(CFLAGS) files
You can find similar differences in the various available linkers and
library editors. Their command lines may have different formats and
different sets of options.
To make it easier for you to write universal makefiles, MKS Make
comes with a generic interface to the C compilers and linkers on the
systems where MKS Make is available. The interface is called cc.
However, this interface is not the default; you must edit your default
rules file to call cc. Programmers developing software on several
machines find cc useful; you may never need it if you do not intend
to port your makefiles to other machines.
You always call cc with the same command-line format, regardless of
the compiler you want to invoke. You specify command-line
arguments in a universal format. It is then up to cc to rearrange and
convert these arguments (if necessary) to the form required by your
chosen compiler or linker and to invoke the compiler/linker as
necessary.
The cc command employs a compilation configuration file. The
configuration file instructs cc on how to convert generic commandline
arguments into the format required by a specific compiler or
linker.
MKS Make comes with appropriate compilation configuration files
for the popular C compilers and linkers on your system. The
installation procedure takes care of setting up the configuration files.
Under Windows 95/98, Windows NT, and OS/2, MKS Make stores
the configuration file for cc in $ROOTDIR/etc/compiler.ccg. On
302 Source Integrity Professional Edition

Using CC
Generic
Command-line
Format
Using the Generic CC Interface
UNIX-based systems, the configuration file is /etc/compiler.ccg.
Alternatively, you can set the CCG environment variable to point to
another configuration file.
The online reference for cc provides information on writing your
own configuration files, if you want to use an unsupported compiler
or linker. Certainly, the best way to start is copy and modify one of
the provided configuration files.
The cc command is installed in the same directory as the make
command. If this directory is in your search rules, you can call the
command by using the name cc.
The supplied default rules file defines the CC macro to refer to your
favorite C compiler. For example, if you use the Borland C compiler,
it would contain
CC = bcc
LD = bcc
To use CC, you would edit your default rules file to
CC = cc
LD = cc
From this point on $(CC) and $(LD) invoke cc instead of your
chosen compiler or linker. Since the installation process sets up
appropriate configuration files, cc converts its generic command line
to the format required by your chosen compiler and linker before
invoking that compiler or linker.
The cc command uses the following generic command-line format
for compilation:
cc -c [options] file…
where each option begins with a dash.
For example, the recommended way of selecting compiler memory
models is with the -mmodel option. If you are using Microsoft C
version 6.0 and want a large model program, you enter
cc -c -ml file
instead of using the /AL option. You could still use the /AL option, but
your makefile would not be portable.
The files specified on the command line are the C source files you
want compiled. cc invokes your chosen compiler to compile each
source file.
User Guide 303

Using the MKS Make Utility
Examples of
Use
Problem Solving
Without a
Makefile
As source files are compiled, cc strips the name of the source file of
its .c suffix and adds an appropriate suffix for object files. If you do
not specify the -c (compile-only) option, cc subsequently passes all
these files—as well as any other object and library files named on the
command line—to your linker.
You specify the output executable with the option
-o executable
To use cc for linking, use the following generic command-line
format:
cc [options] -o executable_file object_file…
Here is an excerpt from a startup file that uses the generic cc
interface.
CC = cc
LD = cc
%$E : %$O
$(LD) $(LDFLAGS) $(CFLAGS) -o $@ $^ $(LDLIB)
%$O : %.c
$(CC) -c $(CFLAGS) $^
The metarules describe how to link an executable file from object files
and how to compile an object file from a source file. The commandline
format is independent of the compiler and/or linker being used.
You can use the CFLAGS macro to give options that are specific to your
chosen compiler. The LDFLAGS macro gives options that are specific to
your chosen linker.
This section gives additional examples of using MKS Make.
Assume the file prog.c contains the C source code that should be
compiled to make prog.exe. No makefile is necessary; simply type
make prog.exe
MKS Make does everything using default rules, which specify how a
.exe can be built from a .c file.
304 Source Integrity Professional Edition

Simple Makefile
Separate Object
Directory
Problem Solving
Assume a program is built from the C source code in the files a.c,
b.c, and c.c. Two of these files #include definitions from hdr.h, as
shown.
MOD = a b c
OBJ = $(MOD:+"$O")
program$E : $(OBJ)
$(LD) $(LDFLAGS) -o $@ $<
a$O b$O : hdr.h
MKS Make uses the default rules to create the individual object files
and links them into the final program.
Assume the same situation as the previous, except that object and
executable files are kept in a separate directory named objdir. This
example assumes your C compiler has a -ndirectory flag to place the
object file into a specific directory.
There are two ways to handle this with MKS Make, either with
.SOURCE special targets or with .SETDIR attributes. Using .SOURCE,
you set up your makefile as
MOD = a b c
OBJ = $(MOD:+"$O")
OBJDIR=objdir
.SOURCE$O :- $(OBJDIR)
.SOURCE$E :- $(OBJDIR)
CFLAGS += -n$(OBJDIR)
program$E : $(OBJ)
$(LD) $(LDFLAGS) -o $@ $^
a$O b$O : hdr.h
Users of a file server probably want to explore these possibilities, as
they allow sources to be kept on a networked disk, while object and
executables are built on a (usually faster) local disk.
To do the same using .SETDIR, you give the appropriate files
.SETDIR attributes telling make where the files appear. Note that,
even though the source files are in the current directory, a .SETDIR
User Guide 305

Using the MKS Make Utility
MKS Make and
Source Integrity
Using a Library
attribute is required for them as well. However, since MKS Make now
changes to the objdir directory before compiling, it no longer
requires the -ndirectory option.
MOD = a b c
OBJ = $(MOD:+"$0")
OBJDIR=objdir
".SETDIR=$(OBJDIR)" : program$E $(OBJ)
".SETDIR=$(PWD)" : $(MOD:+".c") hdr.h
program$E : $(OBJ)
$(LD) $(LDFLAGS) -o $@ $<
a$O b$O : hdr.h
MKS Make requires the quotes in the .SETDIR setting, if a device
name with a colon may appear in the directory name.
Note Normally, after MKS Make has run the recipe for a target, it marks
the target as made, and does not remake it, even if another target
depends upon it. When you use the .SETDIR attribute, MKS Make
switches to the newly specified directory every time it encounters the
attribute and retests all of the target’s prerequisites. The result is that it
does much more work when you use .SETDIR than when you use
.SOURCE.
For the previous examples, assume the source code is contained in
Source Integrity archives. The same makefile applies; the default
rules in the startup file instructs make to check out missing source
files as required.
Going back to the simple example with the source files a.c, b.c, and
c.c, assume a new file named program.c is required, and you keep
the other objects in an object library. In this case, program.exe
depends upon the library and the file program.obj.
The following example uses the macro A to stand for the library
suffix:
MOD = a b c
OBJ = $(MOD:+"$O")
program$E: program$O mylib$A
$(LD) $(LDFLAGS) -o $@ $<
mylib$A : $(OBJ)
a$O b$O : hdr.h
306 Source Integrity Professional Edition

Recursive
Makes
For more information on this
option, see the man page for
the make command.
Clean-up
Problem Solving
When building a large complex project, you can use multiple
directories for separate components of the project. Within each
directory, you use a makefile to control the building of that
component of the project. At the top level, you can use a single
makefile, which simply invokes the subdirectory makefiles in turn,
ensuring the entire project is up to date.
Assume a project has the subpackages system and commands, each
stored in a subdirectory of a master directory. Within each system and
commands directories, you keep a makefile to rebuild that
subpackage. To ensure the project is up to date, you must ensure the
subpackages are up to date; you can easily do this with a makefile in
the following format, stored in master:
all:
$(MAKE) -c system
$(MAKE) -c commands
The -c option forces MKS Make to switch into the specified directory
when it starts up.
The macro MAKE is defined to contain the current setting of
MAKEFLAGS. MKS Make has a feature whereby if the macro MAKE is
used in a recipe line, then that line is executed, even if the -n option
was passed to MKS Make. This ensures the command
make -n
which sets MAKEFLAGS to -n, recursively runs MKS Make in the
subdirectories named. The only limits to this sort of recursive
processing is the available memory on your machine.
Some software creates work or backup files that do not need to be
kept. Assume the current directory contains such files, identified by
the suffixes $O and .bak. To clean out these files, add the following
lines to a makefile:
clean :
-rm -f *.bak *$O
The command
make clean
then gets rid of the files.
User Guide 307

Using the MKS Make Utility
Back-up
Default Rules
Assume a makefile defines a macro named SRC giving the base name
of the C source files that make up a program. Also assume from time
to time, you want to back up all recently changed copies to a
directory named savedir. Add the following to the makefile:
backup : $(SRC:+".c") makefile
cp $? savedir
touch backup
With this rule, you can do a backup with the command
make backup
The target backup is a file you create the first time you perform the
backup. Each time you perform it, the touch command sets the
change date of backup to the correct time. In this way, the next time
you run the command, MKS Make only saves files newer than
backup.
You can use a similar approach to get printouts of source files that
have been changed.
printchk : $(SRC:+".c")
echo printing $?
PRINT $?
touch printchk
Note that PRINT appears in uppercase above. This avoids a conflict
with the lowercase print command built into the MKS KornShell.
The startup file contains a good example of most of the popular
features of MKS Make. Spend some time looking at this file to get a
better understanding of how various things work. Use the -v flag to
get trace information of what MKS Make is doing at each stage.
308 Source Integrity Professional Edition

Miscellaneous Details
Miscellaneous Details
The maximum length of a single line in a makefile is 16384 characters.
If you use the MKS KornShell, you can write commands with up to
8192 characters when using make.exe.
You can only nest included makefiles up to a depth of 10. In other
words, if a makefile uses the .INCLUDE special target to include
another makefile (which includes another makefile, and so on), you
are allowed a maximum of 10 nested includes.
MKS Make also allows nesting of conditional expressions up to a
limit of 25 nested expressions, as in
.IF
.IF
…
.END
.END
up to a limit of 25 nested expressions.
User Guide 309

Using the MKS Make Utility
310 Source Integrity Professional Edition

Starting a Change
Integrity Session
10
This chapter provides an overview of Change Integrity concepts; the
basic tasks necessary to start, configure, and close a Change Integrity
session; and an overview of the Change Integrity interfaces.
Specifically, this chapter provides details on:
Change Integrity concepts
logging in to Change Integrity
the Change Integrity graphic user interface
the Change Integrity Web interface
setting session preferences
configuring email notification
logging out
closing a session
User Guide 311

Starting a Change Integrity Session
Change Integrity Concepts
Issues
Workflow
User
This section provides you with a brief orientation to important
Change Integrity concepts.
Change Integrity uses issues to track changes in the software
development cycle. For example, your administrator can configure
Change Integrity in a way that a problem issue may be associated with
a solution issue for easy tracking and monitoring of both issues. Each
issue has an audit trail, which may be used to evaluate internal
processes for the effectiveness of the problem resolution process. In
effect, issues track all aspects of any engineering endeavor.
Issue types capture and track a specific change request, defect,
problem, solution, or task. For example, one issue type could record
bugs and deficiencies in design. Another issue type could be used to
request design changes that fix problems, or propose enhancements
or new functionality for your product. Similarly, an issue type could
be created that assigns work tasks that address problems, or prepare
and implement solutions.
Administrators create and define specific issue types; however, MKS
provides three solution templates with built in issue types.
Specific issue types can be linked to one another as references to a
specific issue. For example, an issue type that tracks problems could
be linked to an issue type that provides solutions. Similarly, an issue
type that sets out tasks could be linked to an issue type that tracks
problems.
Administrators define issue relationships.
Each issue follows workflow, the process established by your
administrator to capture and track information during your software
development cycle. Each issue type can have its own set of states to
advance through the development cycle. For example, a change
request may go through the following states: submitted, work
started, tested, reviewed, closed. Issues and their current states
provide change management information necessary to support
business decisions.
A user is anyone who needs to work with Change Integrity issues.
Users are assigned user permissions to them by the administrator.
Users are also assigned to groups that have specific Change Integrity
group permissions assigned to them by the administrator.
312 Source Integrity Professional Edition

Group
Projects
Query
Reports
Charts
Change Integrity Concepts
A group consists of one or more users who need to work with Change
Integrity issues.
Your administrator decides who does what. In setting up the project,
the administrator assigns permissions to different groups for gaining
access to certain areas within Change Integrity, and then puts each
user into a group.
For example, some groups may be designated for submitting and
editing problems only, while the submitting of work tasks may be
restricted to a group of managers.
With that in mind, you should be aware that not all users will be able
to use all of the functionality of Change Integrity. If you find you
cannot do something that you think you should be able to do, then
contact your administrator.
Projects are labels that help you sort and organize issues in a
hierarchical structure. For example, your administrator might
organize projects according to:
the modular structure of a software application
the information architecture of a Web site
group responsibilities within a department
A query is a request to select and list the issue types that meet specific
selection criteria. The selection criterion is a logical expression of
specific values, or ranges of values, of the standard and custom fields
of the issue type.
Reports are summaries of the data in your project. Reports are based
on the standard and custom fields of issue types. Reports can be
customized to include images, fonts, hyperlinks, and can be saved as
HTML files for viewing on the Web.
Charts are graphs that present trends over time or distributions of the
data in your project. Charts are based on the standard and custom
fields of issue types. Trend charts may be displayed as line graphs.
Distribution charts may be displayed as pie graphs or bar graphs.
User Guide 313

Starting a Change Integrity Session
Before You Start a Change Integrity Session
Before you start a Change Integrity session, ensure you have the
following:
a copy of the Change Integrity client installed locally on your
computer
a Web browser, such as Netscape Navigator or Microsoft Internet
Explorer, to use the Change Integrity Web interface
the name of the Change Integrity server and port number you
want to connect to
your Change Integrity user name and password
Starting a Change Integrity Session
Logging In
For both the Change Integrity graphic user interface and Web
interface, you must log in to a database on a Change Integrity server
before you can perform any Change Integrity operations.
To log in using the graphic user interface:
When you start the Change Integrity client for the first time, the MKS
Change Integrity login dialog box appears, prompting you for your
login information.
314 Source Integrity Professional Edition

Starting a Change Integrity Session
1. In the Server field, enter the name of the server you want to
connect to, for example, localhost, or the numerical IP address,
for example, 1.234.53.
Note Do not use back slashes (\) in the server name, for example,
\\localhost.
2. In the Port field, enter the server’s port number, for example,
7001.
3. In the Name field, enter your user name, for example, gmiller.
User names must be a minimum of one character.
4. In the Password field, enter your password, for example,
docsteam. Passwords must be a minimum of eight characters.
5. To save your password for every time you log in, select the
Remember My Password checkbox.
Note User names and passwords are assigned by your administrator—
you should contact your administrator for the correct entries.
6. To accept the log in information, click OK. To close the MKS
Change Integrity login dialog box, click Cancel.
Change Integrity validates your login information, then the
Change Integrity graphic user interface appears.
To log in using the Web interface:
1. Start your Web browser, such as Netscape Navigator or Microsoft
Internet Explorer.
2. Browse to the location of the Change Integrity home page. Your
administrator can provide you with its location.
A typical URL of the Change Integrity home page may be of the
form:
http://server_name:port_#/
User Guide 315

Starting a Change Integrity Session
The Change Integrity home page appears.
3. Click Change Integrity.
A browser password dialog box appears, prompting you for your
Change Integrity user name and password.
4. In the User Name field, enter your user name, for example,
gmiller. User names must be a minimum of one character.
5. In the Password field, enter your password, for example,
docsteam. Passwords must be a minimum of eight characters.
6. To accept the log in information, click OK. To close the login
dialog box, click Cancel.
316 Source Integrity Professional Edition

The Change Integrity Graphic User Interface
Change Integrity validates your login information, then the
Change Integrity Web interface appears.
The Change Integrity Graphic User Interface
The Application
Window
Title Bar
Menu Bar
Toolbar
Query Bar
Query Builder
Query Results
Context Menu
Issue Details
Status Bar
The application window contains a number of common features
explained in this section.
Many of the features in the application window can be customized.
For more information, see “Setting Session Preferences” on page 321.
Menu Bar
The menu bar is located directly below the title bar and contains
available pull-down menus. When you first start Change Integrity as
a user, there are seven menus in the menu-bar: Session, Query,
Results, Issue, Reports, Charts, and Help.
Note The Administration menu is only available to Change Integrity
administrators.
User Guide 317

Starting a Change Integrity Session
Toolbar
Immediately below the menu bar is a toolbar that provides easy
access to the most commonly used Change Integrity commands.
Query Bar
Below the toolbar is the Query Bar that provides easy access to saved
queries. is a default query that queries for all issue types
assigned to the current logged in user. If the user does not have any
saved queries, this default query appears the first time a new user
logs in. If another Change Integrity user creates a shared saved query,
the shared saved query appears in the Query Bar instead of .
Context Menu
Change Integrity supports standard context menus. Selecting and
right-clicking
the Query Builder
the Query Bar
columns in the Query Results
issues in the Query Results
displays a menu of actions you can perform.
Status Bar
The status bar displays the number of issues visible in the Query
Results, your user name, and the name and port number of the server
you are connected to. You can hide or show the status bar.
Query Builder
When you first launch Change Integrity, the Query Builder appears
on the far-left side of the application window, below the Query Bar.
The Query Builder provides filters that allow you to focus your
queries of specific issue types. The Type filter box is always present.
Additional filters can be selected by right-clicking the Query Builder
and choosing a filter from the context menu.
Query Results
The Query Results appear on the far-right side of the application
window below the Query Bar. When you run a query, the results are
displayed in the Query Results. You can choose specific display
options, and double-click an issue to display specific issue
information in the Issue Details.
318 Source Integrity Professional Edition

Issue Details
The Change Integrity Graphic User Interface
The Issue Details displays specific information about a selected issue.
The top of the Issue Details shows the issue type, ID, who created the
issue and when, and who last modified the issue and when.
The Issue Details contains five tabbed panels:
The Fields panel displays a summary of the issue, the issue’s
state, who the issue is assigned to, the group the issue is assigned
to, the project the issue is assigned to, and custom field
information.
The History panel displays a read-only log of all state changes to
the issue.
The Attachments panel displays a list of attached files.
The Relationships panel displays a list of related issues.
The Change Package panel displays files that are affected by an
issue type. For example, a solution’s change package might
include files that are required to change in order to satisfy a
problem.
User Guide 319

Starting a Change Integrity Session
The Change Integrity Web Interface
Query Toolbar
Status
Toolbar
Content Page
The Change Integrity Web interface contains a number of common
features explained in this section.
Note Your administrator can customize the appearance of the Change
Integrity Web interface, for example, toolbar buttons, and background
colors.
Toolbar
In the left frame is a toolbar that provides easy access to the most
commonly used Change Integrity commands: submitting issues,
viewing charts, viewing reports, logging out, choosing query display
options, and viewing the Change Integrity Web interface online help.
Query Toolbar
In the top frame is the Query toolbar that allows you to perform
query functions: creating, saving, running, viewing, editing, and
deleting queries.
320 Source Integrity Professional Edition

Setting Session Preferences
My Inbox is a default saved query that queries for all issue types
assigned to the current logged in user. If the user does not have any
saved queries, this default query appears the first time a new user
logs in. If another Change Integrity user creates a shared saved query,
the shared saved query appears in the Saved Queries drop-down
menu instead of My Inbox.
Content Page
Whenever you perform a Change Integrity operation from the
toolbar or Query toolbar, command options and results are displayed
in the right frame, for example, query results.
Status
Setting Session Preferences
The status of a Change Integrity session is displayed in two areas:
the browser’s address bar displays the server name and port
number that you are connected to
the left frame displays your user name under the MKS logo
Session preferences allow you to customize your Change Integrity
client session and configure email notification.
To set session preferences in the graphic user interface:
1. Choose Session > Preferences.
User Guide 321

Starting a Change Integrity Session
For more information about
running queries, see “Running
Queries” on page 359.
The Preferences dialog box appears.
2. To automatically connect to a database on a Change Integrity
server when you launch the Change Integrity client, select the
Automatic Connect checkbox.
With this option selected, you do not have to enter your host
information, user name, and password every time you log in.
3. To save your password for every time you log in, select the
Remember My Password checkbox.
This option is also available from the MKS Change Integrity login
dialog box.
4. To run a query only when you choose Query > Run, select the
Query Only on Demand checkbox.
If you do not select this checkbox, Change Integrity runs a query
as you specify query filters.
To set layout preferences:
1. Click the Layout tab.
The Layout panel appears.
322 Source Integrity Professional Edition

Email
Notification
2. Set up your layout as follows:
Setting Session Preferences
To display the Query Bar, select the Show Query Bar checkbox
under Query Bar.
To choose a position for the Query Bar, select the Horizontal or
Vertical radio button.
To display the Query Builder, select the Show Query Builder
checkbox under Query Builder.
To choose a position for the Query Builder, select the Align
Left or Align Right radio button.
To choose a position for the Issue Details, select the Above
Query Results or Below Query Results radio button.
To show the status bar, select the Show Status Bar checkbox.
Any Change Integrity user can be notified via email whenever a new
issue is submitted, or issue information changes. This is useful for
users who need to review and approve state changes on new
submissions or existing issues, and users who need to work on issues
assigned to them. Notifications also keep users informed of project
progress.
You configure Change Integrity to send you email notification by
creating rules. Rules are made up of conditions, which are logical
expressions of specific issue field changes that you want to be
notified about. For example, you could create a simple rule
containing one condition that sends you email every time a new
User Guide 323

Starting a Change Integrity Session
problem assigned to you is submitted. Similarly, you could create a
complex rule containing two conditions that send you email every
time a new problem assigned to you is submitted, and when existing
problems become assigned to you. Rules can contain as many
conditions as you want.
To set email notification preferences:
1. Click the Notifications tab.
The Notifications panel appears.
2. In the Address field, enter your email address, for example,
omille@mks.com.
3. If certain conditions are met, nodes specify if email notification
will be sent. Choose a node option by clicking a button:
And specifies that all of the conditions specified must be true
for an email notification to be sent. For example, if an issue’s
assigned group = documentation and the project =
editor, then an email notification is sent.
Or specifies that one or more of the conditions must be true in
order for an email notification to be sent. For example, if an
issue’s state = submitted, but the priority does not =
high, an email notification is sent.
Swap replaces the selected node with the opposite node. For
example, swapping an Or node replaces it with an And node.
Remove deletes the selected node.
324 Source Integrity Professional Edition

Setting Session Preferences
Tip You do not need to use the And and Or nodes if your rule contains
only one condition.
4. Under Condition, choose a field to be notified about from the Field
drop-down menu, for example, Assigned User.
You can select from two types of fields: prime fields and non-prime
fields. A prime field, indicated by a prime symbol ( ), specifies a
new value. A non-prime field specifies an existing value.
5. From the Operator drop-down menu, choose an operator. The
available operators are:
= equal to
not equal to
> greater than
>= greater than or equal to

Starting a Change Integrity Session
8. To accept the changes, click OK. To discard any changes, click
Cancel.
Once you create a rule, you receive email notification whenever an
issue matches the conditions specified in your rule, for example,
whenever an issue becomes assigned to you.
326 Source Integrity Professional Edition

Saving Session
Preferences
Setting Session Preferences
The email displays the issue type; ID; summary; who edited the issue
and when; a hyperlink, that when clicked opens the issue in the
Change Integrity Web interface; modified fields; and comments.
To set toolbar preferences:
1. Click the Toolbars tab.
The Toolbar panel appears.
2. Choose an option by selecting a radio button:
Show Only Images displays only images on toolbar buttons.
Show Images and Text displays images and text on toolbar
buttons.
Show Images and Selective Text displays images and text on
some of the toolbar buttons.
Show Only Text displays only text on toolbar buttons.
To save session preferences:
To accept the session preferences, click OK. To discard any changes to
the session preferences, click Cancel
User Guide 327

Starting a Change Integrity Session
Ending a Change Integrity Session
Logging Out
Closing a
Session
You can log out of Change Integrity and log in as another user, or
allow another user to log in.
To log out using the graphic user interface:
Choose Session > Logout.
The MKS Change Integrity login dialog box appears.
To log in again, see “Logging In” on page 314.
To log out using the Web interface:
Click .
The Change Integrity home page appears.
To log in again, see “Logging In” on page 314.
Closing a Change Integrity session shuts down the client and
disconnects from the server.
To close a session using the graphic user interface:
Choose Session > Exit.
The Change Integrity client shuts down and disconnects from the
server.
328 Source Integrity Professional Edition

To close a session using the Web interface:
1. Click .
The Change Integrity home page appears.
2. Close the browser window.
Ending a Change Integrity Session
The Change Integrity client shuts down and disconnects from the
server.
User Guide 329

Starting a Change Integrity Session
330 Source Integrity Professional Edition

Submitting Issues
11
This chapter describes how to submit issues in the Change Integrity
graphic user interface and Web interface.
The chapter covers:
submitting an issue
adding attachments to an issue
linking an issue with a submitted issue
User Guide 331

Submitting Issues
Submitting an Issue
To submit an issue in the graphic user interface:
1. Choose Issue > New, or click .
2. Select an issue type.
Note The list of available issue types may vary depending on the issue
types your administrator created. Problems, solutions, and tasks are
issue types provided with Change Integrity.
The Submit New dialog box appears.
3. Enter the issue data in the fields provided.
In the Summary field, enter a brief summary of the issue, up
to 100 alpha-numeric characters.
In the State drop-down menu, choose a state for the issue, for
example, Submitted. Your administrator defines states.
332 Source Integrity Professional Edition

Submitting an Issue
In the Assigned User drop-down menu, assign a user to the
issue. Your administrator defines users.
Note Assigning an issue to a user does not automatically assign the
issue to the user’s assigned group. You must select the user’s assigned
group from the Assigned Group drop-down menu.
In the Assigned Group drop-down menu, assign a group to
the issue, for example, development. Your administrator
defines groups.
In the Project drop-down menu, assign the issue to a specific
project. Your administrator defines projects.
Your administrator defines custom fields, for example, Fix
Progress. Custom fields can be either text fields or dropdown
menus.
4. If you do not know the information required for a specific field,
click the field.
A icon appears to the left of the field.
5. Click the icon or press F2.
unspecified appears in the field.
6. To edit the field, click the field and enter text or choose a menu
item.
7. To submit the issue, click OK. To close the Submit New dialog box
without saving any changes, click Cancel.
The issue is submitted and appears in the Query Results for the
specified project.
User Guide 333

Submitting Issues
To submit an issue in the Web interface:
1. Under Submit, click an issue type button, for
example, .
Note Your administrator defines issue types. Problems, solutions, and
tasks are example issue types provided with Change Integrity.
The Submit Issue page appears.
2. Enter the issue data in the fields provided.
In the Summary field, enter a brief summary of the issue, up
to 100 alpha-numeric characters.
In the State drop-down menu, choose a state for the issue, for
example, Submitted. Your administrator defines states.
In the Assigned User drop-down menu, assign a user to the
issue. Your administrator defines users.
Note Assigning an issue to a user does not automatically assign the
issue to the user’s assigned group. You must select the user’s assigned
group from the Assigned Group drop-down menu.
In the Assigned Group drop-down menu, assign a group to
the issue, for example, development. Your administrator
defines groups.
334 Source Integrity Professional Edition

Relating an
Issue With a
Submitted Issue
For information on opening
the Submit New dialog box,
see “Submitting an Issue” on
page 332.
Submitting an Issue
In the Project drop-down menu, assign the issue to a specific
project. Your administrator defines projects.
Your administrator defines custom fields, for example, Fix
Progress. Custom fields can be either text fields or dropdown
menus.
Note In date fields, use the format mm/dd/yyyy.
3. If you do not know the required information for a specific field,
select the field’s checkbox. (Unspecified) will appear in the field
after it is submitted.
4. To submit the issue, click . To make changes, click the
browser’s Back button.
The issue is submitted and appears in the Issue Details page.
Issues can be related to one another as references. For example, an
issue type that tracks problems could be linked to an issue type that
provides solutions. Similarly, an issue type that sets out tasks could
be linked to an issue type that tracks problems.
Note Your administrator defines issue types and issue type
relationships.
To relate an issue with a submitted issue in the graphic user
interface:
1. With the Submit New dialog box open, click the Relationships tab.
The Relationships panel appears.
User Guide 335

Submitting Issues
2. Click .
The Add Linked Issue dialog box appears.
3. Enter the issue’s ID, for example, 67.
4. Click OK.
The issue appears in the Relationships list.
336 Source Integrity Professional Edition

Submitting an Issue
5. Repeat for all issues you want to associate with the issue you are
submitting.
To relate an issue with a submitted issue in the Web interface:
1. With the Submit Issue page open, click the Relationships tab.
The Relationships panel appears.
2. Enter the issue’s ID, for example, 43.
3. Click Add Relationship.
User Guide 337

Submitting Issues
The issue appears in the Relationships list.
4. Repeat for all issues you want to associate with the issue you are
submitting.
Removing a Related Issue
To remove a related issue in the graphic user interface:
1. With the Submit New dialog box open, click the Relationships tab.
The Relationships panel appears.
2. Select the issue from the Relationships list.
3. Click .
The issue is removed from the Relationships list.
338 Source Integrity Professional Edition

To remove a related issue in the Web interface:
Submitting an Issue
1. With the Submit Issue page open, click the Relationships tab.
The Relationships panel appears.
2. Select the related issue’s checkbox from the Relationships list.
3. Click Remove Selected.
The issue is removed from the Relationships list.
Opening a Related Issue
You can view complete information about an issue related to a
submitted issue.
To open a related issue in the graphic user interface:
See “Selecting Issues to View” on page 367.
To open a related issue in the Web interface:
1. Submit the issue, as explained in “Submitting an Issue” on page
332.
The Issue Details page appears.
2. Click the Relationships tab.
User Guide 339

Submitting Issues
Adding Attachments to an Issue
For information on opening
the Submit New dialog box,
see “Submitting an Issue” on
page 332.
The Relationships panel appears.
3. Click the issue’s ID from the Relationships list.
The issue opens in the Issue Details page.
Change Integrity allows you to attach copies of a file to an issue so
other users may view them.
To add an attachment to an issue in the graphic user interface:
1. With the Submit New dialog box open, click the Attachments tab.
The Attachments panel appears.
340 Source Integrity Professional Edition

2. Click .
The Add Attachments dialog box appears
3. Browse to a specific file on your local drive.
4. Click Open.
Submitting an Issue
User Guide 341

Submitting Issues
The selected file is added to the Attachments list.
5. Repeat for all files you want to attach to the issue.
To add an attachment to an issue in the Web interface:
1. With the Submit Issue page open, click the Attachments tab.
The Attachments panel appears.
2. Click Browse.
The Choose file dialog box appears.
3. Browse to a specific file on your local drive.
4. Click Open.
The file appears in the Filename field.
5. Click Add Attachment.
342 Source Integrity Professional Edition

The selected file is added to the Attachments list.
6. Repeat for all files you want to attach to the issue.
Removing an Attachment
To remove an attachment in the graphic user interface:
Submitting an Issue
1. With the Submit New dialog box open, click the Attachments tab.
The Attachments panel appears.
2. Select the attachment from the Attachments list.
3. Click .
The attachment is removed from the Attachments list.
User Guide 343

Submitting Issues
To remove an attachment in the Web interface:
1. With the Submit Issue page open, click the Attachments tab.
The Attachments panel appears.
2. Select the attachment’s checkbox from the Attachments list.
3. Click Remove Selected Attachments.
The attachment is removed from the Attachments list.
Opening an Attachment
To open an attachment in the graphic user interface:
1. With the Submit New dialog box open, click the Attachments tab.
The Attachments panel appears.
2. Select the attachment from the Attachments list.
344 Source Integrity Professional Edition

3. Click .
The attachment opens in its associated application.
Submitting an Issue
To open an attachment in the Web interface:
1. Submit the issue, as explained in “Submitting an Issue” on page
332.
The Issue Details page appears.
2. Click the Attachments tab.
User Guide 345

Submitting Issues
3. Click the file name from the Attachments list.
The attachment opens in a new browser window.
Saving an Attachment
You can save attachments to your local drive for later viewing.
To save an attachment in the graphic user interface:
1. With the Submit New dialog box open, click the Attachments tab.
The Attachments panel appears.
2. Select the attachment from the Attachments list.
3. Click .
The Save Attachments dialog box appears.
4. Browse to the location on your local drive where you want to
save the attachment.
5. Click Save As.
To save an attachment in the Web interface:
1. Submit the issue, as explained in “Submitting an Issue” on page
332.
The Issue Details page appears.
346 Source Integrity Professional Edition

2. Click the Attachments tab.
3. The Attachments panel appears.
Submitting an Issue
4. Click the file name from the Attachments list.
The attachment opens in a new browser window.
5. Choose File > Save As.
A standard Save dialog box appears.
6. Browse to the location on your local drive where you want to
save the attachment.
7. Click Save As.
User Guide 347

Submitting Issues
348 Source Integrity Professional Edition

Queries
12
You can define and store any number of queries using Change
Integrity. A query is basically a request to select and list the issue
types that meet specific selection criteria. The selection criterion is a
logical expression of specific values, or ranges of values, of the
standard and custom fields of the issue.
The queries you define are stored on the Change Integrity client, but
they may be run by other users if the saved query is shared.
Queries are created in the Query Builder and can be saved for future
use.
This chapter explains how to:
create a new query
create saved queries
run queries
User Guide 349

Queries
Creating a New Query
To create a new query in the graphic user interface:
1. From the drop-down menu in the Type filter box, choose an issue
type to query by selecting an issue type checkbox. Not selecting
an issue type checkbox means that the query is not restricted to
any issue types. You can select multiple issue types.
Note Your administrator defines issue types.
2. Right-click the Query Builder and select filters specific to your
query from the context menu:
Tip To insert all filters, right-click the Query Builder and choose Insert
All from the context menu. To hide a specific filter, right-click the filter
box and choose Hide from the context menu. To hide all filters, right-click
the Query Builder and choose Hide All from the context menu.
ID queries by issue ID. From the operator drop-down menu,
choose an operator. In the ID field, enter the issue ID, or click
or to select an issue ID.
350 Source Integrity Professional Edition

Creating a New Query
Created By queries by the user who created the issue. From
the user drop-down menu, select a user checkbox. Your
administrator defines users.
Created Date queries by the date the issue was created. From
the From drop-down menu, select the date you want the
query to begin with by choosing a date from the calendar.
From the To drop-down menu, select the date you want the
query to end with by choosing a date from the calendar.
Note The To field in all date queries is mutually exclusive. For example,
if you wanted to view all issues created up to March 25, 2000, you would
enter March 26, 2000 in the To field.
Modified By queries by the user who last modified the issue.
From the user drop-down menu, select a user checkbox. Your
administrator defines users.
Modified Date queries by the date the issue was last modified.
From the From drop-down menu, select the date you want
the query to begin with by choosing a date from the calendar.
From the To drop-down menu, select the date you want the
query to end with by choosing a date from the calendar.
Summary queries by words in the issue’s summary. In the
summary field, enter a word or phrase to search for up to 100
characters. All text field queries are case-sensitive.
Assigned User queries by the user who is assigned to the
issue. From the user drop-down menu, select a user
checkbox. Your administrator defines users.
Assigned Group queries by the group assigned to the issue.
From the group drop-down menu, select a group checkbox.
Your administrator defines groups.
Project queries by project. Choose a project. Your
administrator defines projects.
Note To choose multiple projects, select a project while holding down
the Ctrl or Shift keys, then select additional projects. You can open and
close project folders by double-clicking them or using the and
icons.
User Guide 351

Queries
State queries by the issue’s state. From the issue drop-down
menu, select a state checkbox. Your administrator defines
states.
Custom fields, such as Description, can be either drop-down
menus or text fields. Your administrator defines custom
fields. Text field queries are case-sensitive.
Tip To close an open filter box you do not want to use, click .
3. For the filters you have selected, select the filter checkboxes ( ).
To create a new query in the Web interface:
Note To create a query in the Web interface, you must save it.
1. Click .
The Query Details page appears.
2. In the Name field, enter a name for the query.
3. To share the query with other Change Integrity users, select the
Shared checkbox.
4. In the Description field, enter a description of the query.
5. Under Types, select issue types to query for by selecting issue
type checkboxes. Not selecting an issue type checkbox means
that the query is not restricted to any issue types. Your
administrator defines issue types.
352 Source Integrity Professional Edition

Creating a New Query
6. Choose a field to query for by selecting a field from the Fields
drop-down menu.
7. Click Add.
The field appears below the Fields drop-down menu.
8. To remove the field, click Remove.
The field is removed.
9. Repeat for as many fields as you want to add to the query.
10. In the available fields under the Fields drop-down menu, select
values to query for. Note the following:
To select multiple values in a drop-down menu, select a value
in a field while holding down Ctrl or Shift, then select
additional values.
You can enter up to 100 characters in text fields.
Text field queries are case-sensitive.
Use the format mm/dd/yyyy in date fields.
11. To save the query, click .
The results of the query appears in the Query Results page.
User Guide 353

Queries
Creating Saved Queries
To create a saved query in the graphic user interface:
Note For information on creating a saved query in the Web interface,
see “Creating a New Query” on page 350.
1. Choose Query > New.
The New Query dialog box appears.
Tip You can also access the Query menu by right-clicking the Query Bar.
2. In the Name field, enter a name for the new query.
3. To allow all Change Integrity users access to the query, select the
Shared checkbox.
4. Choose an image option for your saved query by selecting a radio
button:
Use default image uses the default image for the saved
query’s icon.
354 Source Integrity Professional Edition

Creating Saved Queries
Use custom image to select a custom image for the saved
query’s icon. Click Select and browse to an image file.
No Image is specified for the saved query’s icon.
Note Images must be GIF or JPEG format, and no larger than 16 by 24
pixels.
5. Click the Description tab.
The Description panel appears.
6. In the Description field, enter a description of the saved query.
7. Click OK. To discard the new query, click Cancel.
The new query appears in the Query Bar.
8. Click the saved query from the Query Bar.
9. Create a query in the Query Builder, as described in “Creating a
New Query” on page 350.
User Guide 355

Queries
Reverting a Saved Query
Deleting a Saved Query
10. Choose Query > Save.
The query is saved.
While making changes to a saved query, you can undo the changes
and revert to the original saved query.
Note Reverting a saved query only works if a save has not been done.
To revert a saved query (graphic user interface only):
Choose Query > Revert, or right-click the query and choose Revert
from the context menu.
The query reverts back to its original state.
Eventually, you may want to delete saved queries that you no longer
use, or if you have too many to manage.
Note Shared queries can only be deleted by the owner. In the graphic
user interface, the Save, Revert, and Delete menu items in the Query
menu are greyed out. In the Web interface, a dialog appears, informing
you can not delete the query.
To delete a saved query in the graphic user interface:
1. Select the query you want to delete from the Query Bar.
The Query Results appear.
2. Choose Query > Delete, or right-click the query and choose Delete
from the context menu.
Change Integrity asks you to confirm that you want to delete the
query.
3. To delete the query, click Yes. To cancel the operation, click No.
356 Source Integrity Professional Edition

To delete a saved query in the Web interface:
Note Shared queries can only be deleted by the owner.
Creating Saved Queries
1. Select the query from the Saved Queries drop-down menu.
The Query Results page appears.
2. Click .
Change Integrity asks you to confirm that you want to delete the
query.
3. To delete the query, click Yes. To cancel the operation, click No.
Viewing and Editing Saved Query Properties
To view and edit saved query properties in the graphic user
interface:
Note Share queries can only be edited by the owner. The edit options
will be greyed out.
1. Select the query from the Query Bar.
The Query Results appear.
2. Choose Query > Properties, or right-click the query and choose
Properties from the context menu.
User Guide 357

Queries
The Edit Query dialog box appears.
3. Edit the query properties, if desired.
4. Click OK to save any changes made to the query. Click Cancel to
discard any changes made to the query.
To view and edit saved query properties in the Web interface:
1. Select a saved query from the Saved Query drop-down menu.
The Query Results page appears.
2. Click .
The Query Details page appears.
358 Source Integrity Professional Edition

Running Queries
3. Make changes to the query as needed.
Running Queries
4. To save any changes made, click . To discard any changes
made, click the browser’s Back button.
If you made changes to the saved query, the results of the query
appear in Query Results page.
To run a new query in the graphic user interface:
1. Create a query in the Query Builder.
2. Choose Query > Run.
Note Choosing Query > Run only works if Query Only on Demand is
selected in the Preferences dialog box. For more information, see
“Setting Session Preferences” on page 321.
The results of your query appear in the Query Results.
User Guide 359

Queries
To run a query in the Web interface, see “Creating a New Query” on
page 350.
To run a saved query in the graphic user interface:
Click a saved query from the Query Bar, or right-click the query and
choose Run from the context menu.
The results of your query appear in the Query Results.
To run a saved query in the Web interface:
Choose a saved query from the Saved Query drop-down menu.
The results of your query appear in the Query Results page.
360 Source Integrity Professional Edition

Refreshing Queries
Running Queries
After you run a query, you may want to run it again to see if any
changes have been made to the issues included in the query
Note Queries automatically refresh in the graphic user interface.
To refresh a query (Web interface only):
Click .
The results of the query appear in the Query Results page.
User Guide 361

Queries
362 Source Integrity Professional Edition

Viewing and Editing
Issues
13
When you run a query, you are able to see query results, select
individual issues for further viewing, and edit issues, depending on
the permissions given to you by your administrator.
This chapter explains how to:
view query results
view issue information
edit issue information
edit multiple issues
print issue information
save issue information
User Guide 363

Viewing and Editing Issues
Viewing Query Results
For information on creating
and running queries, see
“Queries” on page 349.
After you run a query, the results appear in the Query Results. You
can view the issues in a number of ways, such as sorting by a specific
field, or in ascending or descending order. In addition, there are
many common list actions you can perform for viewing and sorting
issues.
To view specific columns in the graphic user interface:
1. Choose Results > Columns, or right-click a column title and
choose Columns from the context menu.
The Columns dialog box appears.
2. To add or remove a column from the Query Results, select a
column and click the add ( ) or remove ( ) buttons.
Note Your administrator sets the fields you can select in the Columns
dialog box.
3. To reorder the columns, select a column and click the move up
( ) or move down ( ) buttons.
4. To specify a column’s pixel width, select a column and enter a
value up to 1000 pixels in the pixel width box.
5. To accept the changes, click OK. To discard any changes made,
click Cancel.
364 Source Integrity Professional Edition

Viewing Query Results
If any changes were made in the Columns dialog box, the issues
are re-organized in the Query Results.
Common List Actions
The following actions are common to all lists in the graphic user
interface:
To see additional details, scroll the data grid lists horizontally
and vertically.
The list is unsorted by default. To sort the list by a specific
column, click any column’s title once—the sort sequence is
displayed in the column’s title by an arrow.
You can re-arrange columns by clicking a column’s title and
dragging it to a new position.
You can also expand or shrink any column by selecting the
vertical dividing bar between two fields on the column title line,
and then dragging it left or right.
Choosing Results > Sort By allows you to select several sort
options:
Sort Ascending sorts the selected column title in ascending
order.
Sort Descending sorts the selected column in descending
order.
You can sort query results by the fields available in the Sort
By drop-down menu. The available fields are set in the
Columns dialog box.
Right-clicking a column title allows you to choose several options
from a context menu:
Hide hides the selected column title from view.
Sort allows you to sort the column title in Ascending or
Descending order.
Columns brings up the Columns dialog box so you can set
view options in the Query Results, as explained earlier.
User Guide 365

Viewing and Editing Issues
You can show custom fields in the Query Results by selecting
a custom field from the context menu. Your administrator
defines custom fields.
To view specific columns in the Web interface:
1. Click .
The Columns page appears.
2. Choose the fields you want to view by selecting field checkboxes.
Note Your administrator sets the fields you can select in the Columns
page.
3. To accept the changes made, click Apply. To discard any changes
made, click Reset.
366 Source Integrity Professional Edition

Selecting Issues to View
If any changes were made in the Columns page, the issues are reorganized
in the Query Results page.
Common List Actions
Selecting Issues to View
The following actions are common to all lists in the Web interface:
To see additional details, scroll the data grid lists horizontally
and vertically.
The list is unsorted by default. To sort the list by a specific
column, click any column’s title once—the sort sequence is
displayed in the column’s title by an arrow.
To view issue details in the graphic user interface:
Select an issue to open by double-clicking the appropriate line in the
Query Results, generated either by listing all issues, or as a result of a
specific issue type query.
User Guide 367

Viewing and Editing Issues
The issue opens in the Issue Details.
The top of the Issue Details shows the issue type, ID, who created the
issue and when, and who last modified the issue and when.
To view specific information about the issue, click a tab:
The Fields panel displays a summary of the issue, the issue’s
state, who the issue is assigned to, the group the issue is assigned
to, the project the issue is assigned to, a description of the issue,
and custom field information.
The History panel displays a read-only log of all state changes to
the issue.
The Attachments panel displays a list of attached files.
To open an attachment, see “Opening an Attachment” on page
344.
To save an attachment, see “Saving an Attachment” on page 346.
The Relationships panel displays a list of related issues.
To open a related issue, select it from the Attachments list, then
click .
The issue opens in the Issue Details.
368 Source Integrity Professional Edition

For more information on
change packages, see
“Integrated Version Control”
on page 437.
Selecting Issues to View
The Change Package panel displays a list of files that are affected
by an issue type. For example, a solution’s change package might
include files that are required to change in order to satisfy a
problem.
Tip To resize the Issue Details, point to the divider between the Issue
Details and the Query Results until you get a double arrow, and then
drag the divider up or down.
To select an issue by ID in the graphic user interface:
With issues in the Query Results, click the and buttons at the
top of the Issue Details to move up and down through the list of
issues by ID. You can also type in the issue ID in the ID field.
The issue appears in the Issue Details.
User Guide 369

Viewing and Editing Issues
To view issue details in the Web interface:
Select an issue to view by clicking an issue value, for example, an ID
or user name.
The issue opens in the Issue Details page.
The top of the Issue Details page shows the issue type, ID, who
created the issue and when, and who last modified the issue and
when.
To view specific information about the issue, click a tab:
The Fields panel displays a summary of the issue, the issue’s
state, who the issue is assigned to, the group the issue is assigned
to, the project the issue is assigned to, a description of the issue,
and custom field information.
The History panel displays a read-only log of all state changes to
the issue.
The Attachments panel displays attached files.
370 Source Integrity Professional Edition

For more information on
change packages, see
“Integrated Version Control”
on page 437.
Printing Issues
Selecting Issues to View
To open an attachment, see “Opening an Attachment” on page
344.
To save an attachment, see “Saving an Attachment” on page 346.
The Relationships panel displays related issues.
To open a related issue, see “Opening a Related Issue” on page
339.
The Change Package panel displays files that are affected by an
issue type. For example, a solution’s change package might
include files that are required to change in order to satisfy a
problem.
To print an issue in the graphic user interface:
1. Select an issue from the Query Results.
Tip You can select multiple issues to print by selecting an issue, then
while holding down Ctrl or Shift, select additional issues.
2. To print one issue, choose Issue > Print, or right-click and choose
Print from the context menu.
To print multiple issues, choose Issue > Batch > Print, or rightclick
and choose Print from the context menu.
A Print Issues window appears.
User Guide 371

Viewing and Editing Issues
Note Multiple issues appear in the same Print Issues window.
3. Click Print.
A standard Print dialog box appears.
4. Select the print options you want.
5. Click OK.
372 Source Integrity Professional Edition

Saving Issues
To print an issue in the Web interface:
Selecting Issues to View
1. To print one issue, run a query and open the issue.
To print multiple issues, run a query and select the checkboxes of
the issues that you want to print.
2. Click .
A Print Issues window appears.
Note Multiple issues appear in the same Print Issues window.
3. Choose File > Print.
A standard Print dialog box appears.
4. Select the print options you want.
5. Click OK.
To save an issue in the graphic user interface:
1. Select an issue from the Query Results.
User Guide 373

Viewing and Editing Issues
Tip You can select multiple issues to save by selecting an issue, then
while holding down Ctrl or Shift, select additional issues.
2. To save one issue, choose Issue > Print, or right-click and choose
Print from the context menu.
To save multiple issues, choose Issue > Batch > Print, or right-click
and choose Print from the context menu.
A Print Issues window appears.
Note Multiple issues appear in the same Print Issues window.
3. Click Save.
A standard Save dialog box appears.
374 Source Integrity Professional Edition

Selecting Issues to View
4. Browse to the location on your local drive where you want to
save the issue.
Note You can only save the issue(s) as an HTML file.
5. Click OK.
To save an issue in the Web interface:
1. To save one issue, run a query and open the issue.
To save multiple issues, run a query and select the checkboxes of
the issues that you want to print.
2. Click .
A Print Issues window appears.
Note Multiple issues appear in the same Print Issues window.
3. Choose File > Save As.
A standard Save dialog box appears.
User Guide 375

Viewing and Editing Issues
Editing Issues
4. Browse to the location on your local drive where you want to
save the issue.
Note You can only save the issue(s) as an HTML file.
5. Click OK.
Besides making submissions, you can perform other common tasks
as a user of Change Integrity, including editing issues. As described
in the previous chapter, each user may list and select issues. In
addition to reviewing the corresponding information, you can edit
and update these issues, depending entirely upon the permissions
assigned to you by your administrator.
Someone on your project team might assign an issue to you, making
you responsible to perform some action. Or you might be responsible
for reviewing all new submissions and assigning them.
To edit an issue in the graphic user interface:
1. Open the issue you want to edit, as described in “Selecting Issues
to View” on page 367.
2. Choose Issue > Edit, or click .
The fields become editable.
3. Edit the issue as needed.
376 Source Integrity Professional Edition

Batch Editing
Editing Issues
4. When you are finished making changes to the issue, choose Issue
> Save, or click .
To discard any changes made to the issue, choose Issue > Cancel,
or click .
The issue is updated.
To edit an issue in the Web interface:
1. Open the issue you want to edit, as described in “Selecting Issues
to View” on page 367.
2. Click .
The fields become editable.
3. Edit the issue as needed.
4. When you are finished making changes to the issue, click
. To discard any changes made to the issue,
click .
The issue is updated.
Batch editing allows you to edit the standard and custom fields of
multiple issues at once. For example, you could change the state of
multiple problems from Submitted to Fixed.
In the graphic user interface, you can add related issues and
attachments to multiple issues.
Note Your administrator defines which issue types and custom fields
you can batch edit.
User Guide 377

Viewing and Editing Issues
To edit a field in multiple issues in the graphic user interface:
Note The field you want to edit must exist for all selected issues.
1. Run a query, as explained in “Running Queries” on page 359.
The Query Results appears.
2. Choose the issues you want to edit by selecting an issue, then
while holding down Ctrl or Shift, select more issues.
3. Choose Issue > Batch > Edit, or right-click and choose Edit from
the context menu.
4. Choose a standard field to edit. Your administrator defines
custom fields you can edit. The available standard fields are:
Summary
Assigned User
Assigned Group
State
Project
An Edit Issues dialog box appears.
5. Click unspecified or press F2.
A drop-down menu or text field appears.
378 Source Integrity Professional Edition

Editing Issues
6. Select a value from the drop-down menu, or enter text in the text
field, up to 100 characters.
7. If you do not know the information required for a specific field,
click the field.
A appears to the left of the field.
8. Click or press F2.
unspecified appears in the field.
9. To edit the field, click the field and enter text, or choose a menu
item.
10. To accept the changes to the field, click OK. To discard any
changes made, click Cancel.
If any changes were made, the changed issues appear in the
Query Results.
To add attachments to multiple issues (graphic user interface
only):
Note Your administrator defines which issue types you can add
attachments to.
1. Run a query, as explained in “Running Queries” on page 359.
The Query Results appears.
2. Choose the issues you want to edit by selecting an issue, then
while holding down Ctrl or Shift, select more issues.
User Guide 379

Viewing and Editing Issues
3. Choose Issue > Batch > Add Attachment, or right-click and choose
Add Attachment from the context menu.
The Add Attachment dialog box appears.
4. Browse to a specific file on your local drive.
5. Click Open.
The selected file is added to the issues.
To add related issues to multiple issues (graphic user interface
only):
1. Run a query, as explained in “Running Queries” on page 359.
The Query Results appears.
2. Choose the issues you want to edit by selecting an issue, then
while holding down Ctrl or Shift, select more issues.
3. Choose Issue > Batch > Relationship, or right-click and choose
Add Relationship from the context menu.
The Add Linked Issue dialog box appears.
380 Source Integrity Professional Edition

4. Enter the issue ID, for example, 34.
Editing Issues
5. To accept the changes, click OK. To discard any changes made,
click Cancel.
The linked issue is added to the issues.
To edit a field in multiple issues in the Web interface:
1. Run a query, as explained in “Running Queries” on page 359.
The Query Results page appears.
2. Select the checkboxes of the issues you want to edit.
3. Click .
Note You may have to scroll down to the end of the Query Results to
see the button.
The Select Field to Edit page appears.
User Guide 381

Viewing and Editing Issues
4. Choose a field to edit from the Field drop-down menu, for
example, State.
Note You can only edit one field per batch edit.
5. Click Select new value.
The Edit Field page appears.
6. From the New Value drop-down menu or text field, choose or
enter a new value.
7. In the Comment field, enter a comment, for example, the reason
for changing the field value.
8. Click Save Batch Edit.
The issues are updated in the Query Results page.
382 Source Integrity Professional Edition

Editing Issues
User Guide 383

Viewing and Editing Issues
384 Source Integrity Professional Edition

Reports
14
Change Integrity allows you to create, edit, and generate various
reports on the data in your projects. Reports can be printed,
displayed on screen, or exported as an HTML file for viewing on the
Web.
This chapter explains how to:
create, edit, and generate reports
save and print reports
User Guide 385

Reports
Change Integrity Reports
Creating Reports
Using Change Integrity, you can create, edit, and generate your own
reports. Reports can be based on new queries or saved queries.
Change Integrity comes with three example reports: tabular reports,
breakdown by project reports, and problem summary reports.
To create a new report (graphic user interface only):
1. Choose Reports > Customize, or click .
The Reports dialog box appears.
2. Click New.
The New Report dialog box appears.
386 Source Integrity Professional Edition

Change Integrity Reports
3. In the Name field, enter a name for the report. This is the name of
the report as it appears in the Reports menu. A report name is
mandatory.
4. To allow other Change Integrity users access to the report, select
the Shared checkbox.
Creating a Report Template
Report templates allow you to specify the appearance of reports and
what data they will include. Once you create a report template, you
can generate the report to view in Change Integrity. You can also
import the report to a Web site for others to view.
Report templates are created using HTML (hyper-text markup
language) and special tags for Change Integrity objects, such as fields
and issue types. Because reports in Change Integrity are written in
HTML, you can create simple text reports or elaborate reports with
graphics, special fonts, background colors, and hyperlinks.
Before you create a report template, carefully consider what data you
want the report to show and how you want the data to appear. Use
HTML table tags to organize the report data and use other tags, such
as headings, bolding, and images, to add style.
User Guide 387

Reports
The following example shows how to create a report that displays
submitted problems for individual projects. The data includes each
project’s name, the problem’s ID, who the problem is assigned to, the
problem’s priority, state, and when the problem was created.
To specify a report template:
1. Click the Template tab, if it is not selected already.
The Template panel appears.
2. After the tag, start a new line and insert tags to specify
font size, heading size, color, and a title. For example:
Issue Summary grouped by Project
3. Start a new line and insert a table tag that specifies the border and
width of the table. The table organizes the data into columns. For
example:
388 Source Integrity Professional Edition

Change Integrity Reports
4. Insert report tags to specify what data you want the report to
include. Use table row tags to organize field data. The following
table shows the available report tags and what they do.
Insert Report Tag... To...
Display the value of a specific
field, such as State.
Possible values for
FIELD_NAME: ID, Created Date,
Created By, Modified Date,
Modified By, Assigned User,
Assigned Group, State, Project,
Summary, and Type. The name
of custom fields are defined by
your administrator.
Field names are case-sensitive
because you can create two
fields with the same name, but
varying case.
You can not use the < (less than)
symbol in field tags, otherwise,
the values for fields after the <
symbol do not appear in the
report.
Loop all occurrences of the value
for the field specified in
, for
example, the report displays all
problems that have a state of
submitted.
Group the data for a specific
field, for example, the report
displays submitted problems, the
ID, and summary for each project
in the Change Integrity database.
User Guide 389

Reports
For example:
Project:
.
Title
ID
Assigned User
Priority
State
Created
.
Tip Right-clicking the Template field allows you to choose basic editing
commands from the context menu: Undo, Cut, Copy, Paste, Delete, and
Select All.
390 Source Integrity Professional Edition

For information on using
filters in queries, see “Creating
a New Query” on page 350.
Change Integrity Reports
5. Start a new line and insert an ending table tag to close the table,
for example:
Restricting the Report With a Query
When you create a report, you filter your data according to the issue
type(s) you want to match, such as all problems in the database. You
can further restrict the report by filtering specific fields, such as all
problems that are of a certain priority and assigned to a particular
user.
To specify query filters for the report:
1. Click the Query tab.
The Query panel appears.
2. From the Type drop-down menu, select an issue type to create a
report for by selecting an issue type checkbox.
3. To add filters to your query, choose filters from the Additional
Constraints list.
To create a report from a saved query:
1. Click the Query tab.
User Guide 391

Reports
2. Click Copy Saved Query.
The Copy Saved Query dialog box appears.
3. Choose a saved query from the drop-down menu.
4. To accept the operation, click OK. To cancel the operation, click
Cancel.
To add a description of the report:
1. Click the Description tab.
The Description panel appears.
2. In the Description field, enter a description of the report.
To save the custom report:
1. To save the custom report, click OK. To cancel the operation, click
Cancel.
392 Source Integrity Professional Edition

Editing Reports
The report is saved and appears in the Reports list.
2. To close the Reports dialog box, click OK.
To edit a report (graphic user interface only):
Change Integrity Reports
Note Shared reports can only be edited by the owner. The Edit button is
greyed out.
1. Choose Reports > Customize, or click .
The Reports dialog box appears.
User Guide 393

Reports
2. Choose a report from the Reports list.
3. Click Edit.
The Edit Report dialog box appears.
4. Edit the report options as desired.
394 Source Integrity Professional Edition

Running Reports
Change Integrity Reports
5. To save your changes, click OK. To discard any changes made,
click Cancel.
6. To close the Reports dialog box, click OK.
To run a report in the graphic user interface:
1. Click , or choose Reports > Customize.
The Reports dialog box appears.
2. Select a report from the Reports list.
3. Click Run.
Tip You can also run a report by choosing Reports, then selecting a
saved report from the Reports menu.
User Guide 395

Reports
The report appears in a Report window.
To run a report in the Web interface:
1. Click .
The Reports List page appears.
2. Click a report from the Reports list.
The report appears in a reports page.
396 Source Integrity Professional Edition

Deleting Reports
To delete a report (graphic user interface only):
Change Integrity Reports
Note Shared reports can only be deleted by the owner. The Delete
button is greyed out.
1. Choose Reports > Customize, or click .
User Guide 397

Reports
Copying Reports
The Reports dialog box appears.
2. Select a report from the Reports list and click Delete.
Change Integrity asks you to confirm that you want to delete the
selected custom report.
3. To confirm the operation, click Yes. To cancel the operation, click
No.
To copy a custom report (graphic user interface only):
1. Choose Reports > Customize, or click .
The Reports dialog box appears.
2. Select the report you want to copy from the Reports list.
398 Source Integrity Professional Edition

3. Click Copy.
The Copy Report dialog box appears.
4. Rename the report and make changes as required.
Change Integrity Reports
5. To save your changes, click OK. To discard any changes made,
click Cancel.
User Guide 399

Reports
Saving and Printing Reports
Saving Reports
When you select the type of report you want to generate, the report
appears in a Report window that allows you to save and print the
report.
To save a report in the graphic user interface:
1. Run the report, as described in “Running Reports” on page 395.
The reports appears in a Report window.
2. Click Save.
3. Browse to the location on your local drive where you want to
save the report.
Note You can only save the report as an HTML file.
4. Click OK.
400 Source Integrity Professional Edition

Printing Reports
To save a report in the Web interface:
Saving and Printing Reports
1. Run the report, as described in “Running Reports” on page 395.
The report appears in the Reports page.
2. Click File > Save As.
A standard browser Save dialog box appears.
3. Browse to the location on your local drive where you want to
save the report.
Note You can only save the report as an HTML file.
4. Click Save.
To print a report in the graphic user interface:
1. Run the report, as described in “Running Reports” on page 395.
User Guide 401

Reports
The reports appears in a Report window.
2. Click Print.
A standard Print dialog box appears.
3. Select the print options you want.
4. Click OK.
To print a report in the Web interface:
1. Run the report, as described in “Running Reports” on page 395.
The report appears in the Reports page.
402 Source Integrity Professional Edition

2. Choose File > Print.
A standard browser Print dialog box appears.
3. Select the print options you want.
4. Click OK.
Saving and Printing Reports
User Guide 403

Reports
404 Source Integrity Professional Edition

Charts
15
Change Integrity allows you to create, edit, and generate
distribution and trend charts on the data in your projects. Charts can
be printed, displayed on screen, or exported as an image file for use
in other applications.
This chapter explains how to:
create, edit, and generate distribution charts
create, edit, and generate trend charts
save and print charts
User Guide 405

Charts
Change Integrity Charts
Charts are graphs that present trends over time, or distributions of the
data in your project. Charts are based on the standard and custom
fields of issue types. Distribution charts may be displayed as pie
graphs or bar graphs. Trend charts may be displayed as line graphs.
The graphs can be customized to include titles, legends, point
markers, pie values or percentages, three-dimensional bar graphs,
and three-dimensional pie graphs. The color, perspective, shading,
backdrop, three-dimensional effects, fonts, and all other plot
attributes of the graph can also be customized to produce photoquality
presentation graphs.
You can define and store any number of custom charts using Change
Integrity. Charts can report on all data in your project, or you can
specify selection criteria to restrict the data to analyze. The selection
criteria is a logical expression of specific values, or ranges of values,
of the standard and custom fields of issue types. Charts are unique
for each project because each project may have different custom
fields.
The custom charts you define are stored in the Change Integrity
database and may be run by any user if the chart is shared. Also, any
user may view and edit the chart for any project he or she has
visibility into.
A distribution chart shows the distribution of all values of a specified
standard or custom choice field for issue types. Selection criteria can
be attached to the report to limit the records chosen for analysis. For
example, you can generate a pie graph of the distribution of
submitted problems by specific users.
A trend chart is based on the submit date and shows the trend of issue
types that have a specific field value, over a specified time period.
For example, you may want to see the number of problems submitted
over the last 10 months that have a state of fixed, plotted on a
monthly basis.
406 Source Integrity Professional Edition

Creating Distribution Charts
Change Integrity Charts
To create a distribution chart (graphic user interface only):
1. Choose Charts > Customize, or click .
The Charts dialog box appears.
2. Click New.
The Chart Type dialog box appears.
3. Select Distribution from the drop-down menu.
4. Click OK.
User Guide 407

Charts
The New Distribution Chart dialog box appears.
5. In the Name field, enter a name for the distribution chart. This is
the name of the chart as it appears in the Charts menu. A chart
name is mandatory.
6. To allow other Change Integrity users access to the chart, select
the Shared checkbox.
7. In the Title field, enter a title for the distribution chart. This is the
title as it appears on the chart. A title is optional.
8. To choose a font for the title, click Font, then select a font and size
from the Select Font dialog box.
9. In the Description field, enter a description of the distribution
chart. This is optional.
10. To show the description on the chart, select the Show description
checkbox.
11. To choose a font for the description, click Font, then select a font
and size from the Select Font dialog box.
12. In the Footnote field, enter a footnote for the trend chart. A
footnote is optional.
408 Source Integrity Professional Edition

Change Integrity Charts
13. To choose a font for the footnote, click Font, then select a font and
size from the Select Font dialog box.
To specify the fields:
1. Click the Fields tab.
The Fields panel appears.
2. From the Field drop-down menu, choose a field to base the
distribution chart on, such as State.
3. From the Grouping drop-down menu, choose a corresponding
value, such as Project, or none.
Note You can not create distribution charts using non-absolute values,
such as text-based and interger-based fields. For example, Summary and
Build are not selectable from the Field and Grouping drop-down menus.
User Guide 409

Charts
For information on using
filters in queries, see “Creating
a New Query” on page 350.
Restricting the Chart With a Query
When you create a distribution chart, you filter your data according
to the issue type(s) you want to match, such as all problems in the
database. You can further restrict the chart by filtering specific fields,
such as all problems that are of a certain priority and assigned to a
particular user.
To specify query filters for the chart:
1. Click the Query tab.
The Query panel appears.
2. From the Type drop-down menu, select an issue type to create a
chart for by selecting an issue type checkbox.
3. To add filters to your query, choose filters from the Additional
Constraints list.
To create a distribution chart from a saved query:
1. Click Copy Saved Query.
The Copy Saved Query dialog box appears.
410 Source Integrity Professional Edition

2. Choose a saved query from the drop-down menu.
Change Integrity Charts
3. To accept the operation, click OK. To cancel the operation, click
Cancel.
To specify a graph:
1. Click the Graph tab.
The Graph panel appears.
2. Under Graph Type, choose a graph type by clicking a graph type
button:
vertical bar graph
vertical stacked bar graph
horizontal bar graph
horizontal stacked bar graph
pie graph
User Guide 411

Charts
3. To create a 3D chart, select the 3D Chart checkbox.
4. To specify the outline color of the graph bars, click Edit in the
Outline Color field, then select a color from the Select Color dialog
box.
5. To specify the background color of the chart, click Edit in the
Background Color field, then select a color from the Select Color
dialog box.
6. Under Data Labels, choose an option:
None does not show any values for the data labels.
Show Values shows values for the data labels.
To specify the chart’s data colors:
1. Click the Colors tab.
The Colors panel appears.
2. Choose a data color option:
To allow Change Integrity to select data colors automatically,
select the Automatic radio button.
To customize the data colors, select the Custom radio button,
then proceed to step 3.
412 Source Integrity Professional Edition

3. Click Add.
The Select Color dialog box appears.
4. Choose a color from the palette.
5. Click OK.
Change Integrity Charts
User Guide 413

Charts
The data series appears in the Data Colors list.
6. To edit the color of an existing data series, select it from the list,
and click Edit, then select a color from the Select Color dialog box.
7. To remove an existing data series, select it from the list, and click
Remove.
8. Repeat for each data series in the chart.
To specify the chart’s axes:
Note If you chose a pie graph, the Axes tab is grayed out.
1. Click the Axes tab.
The Axes panel appears.
414 Source Integrity Professional Edition

Change Integrity Charts
2. From the Label Rotation drop-down menu for the Horizontal Axis,
choose a location for the horizontal axis labels. The available
locations are:
Horizontal
Vertical (90 degrees)
Vertical (270 degrees)
3. From the Orientation drop-down menu for the Horizontal Axis,
choose a position for the horizontal axis. The available positions
are:
Right
Left
4. To show gridlines on the horizontal axis, select the Show Gridlines
checkbox.
5. To show the title for the horizontal axis, select the Horizontal Axis’
Show Title checkbox.
6. From the Label Rotation drop-down menu for the Vertical Axis,
choose a location for the vertical axis labels. The available
locations are:
Horizontal
Vertical (90 degrees)
User Guide 415

Charts
Vertical (270 degrees)
7. From the Orientation drop-down menu for the Vertical Axis,
choose a position for the vertical axis. The available positions are:
Up
Down
8. To show gridlines on the vertical axis, select the Show Gridlines
checkbox.
9. To show the title for the vertical axis, select the Vertical Axis’ Show
Title checkbox.
To specify the legend:
1. Click the Legend tab.
The Legend panel appears.
2. To show the legend, select the Show Legend checkbox.
3. In the Title field, enter a title for the chart legend. A title is
optional.
4. In the Number of Columns field, enter the number of columns for
the legend, or click or .
416 Source Integrity Professional Edition

Creating Trend Charts
Change Integrity Charts
5. In the Position field, choose a position for the legend on the chart
from the drop-down menu. The available positions:
Right
Left
Top
Bottom
6. To choose a background color for the legend, click Edit, then
select a color from the Select Color dialog box.
To save the distribution chart:
1. To save the chart, click OK. To cancel the operation, click Cancel.
The distribution chart appears in the Charts list, indicated by a
distribution chart icon.
2. To close the Charts dialog box, click OK.
To define a trend chart (graphic user interface only):
1. Choose Charts > Customize, or click .
User Guide 417

Charts
The Charts dialog box appears.
2. Click New.
The Chart Type dialog box appears.
3. Select Trend from the drop-down menu.
4. Click OK.
The New Trend Chart dialog box appears.
418 Source Integrity Professional Edition

Change Integrity Charts
5. In the Name field, enter a name for the trend chart. This is the
name of the chart as it will appear in the Charts menu. A chart
name is mandatory.
6. To share the chart with other Change Integrity users, select the
Shared checkbox.
7. In the Title field, enter a title for the trend chart. This is the title as
it appears on the chart. A title is optional.
8. To choose a font for the title, click Font, then select a font and size
from the Select Font dialog box.
9. In the Description field, enter a description of the trend chart. A
description is optional.
10. To show the description on the chart, click the Show Description
checkbox.
11. To choose a font for the description, click Font, then select a font
and size from the Select Font dialog box.
12. In the Footnote field, enter a footnote for the trend chart. A
footnote is optional.
13. To choose a font for the footnote, click Font, then select a font and
size from the Select Font dialog box.
User Guide 419

Charts
Restricting the Chart by Fields
When you create a trend chart, you filter your data by specific time
intervals, dates, and fields. For example, you might want your trend
chart to show the number of submitted problems each day from
March 1, 2000 to April 15, 2000.
To filter trend chart data:
1. Click the Fields tab.
The Fields panel appears.
2. From the Type drop-down menu, choose an interval for each
point on the graph, such as Day. The available intervals are:
Hour
Day
Week
Month
Quarter
Year
3. From the Start drop-down menu, choose a starting date from the
calendar, for example, Feb. 15, 2000. The default is the current
system date.
420 Source Integrity Professional Edition

Change Integrity Charts
4. From the End drop-down menu, choose an ending date from the
calendar, for example, March 21, 2000. The default is the current
system date.
5. From the Field drop-down menu, choose a field to monitor, such
as Type.
Note You can not create trend charts using non-absolute values, such as
text-based and interger-based fields. For example, Summary and Build
are not selectable from the Field drop-down menu.
To specify a graph:
1. Click the Graph tab.
The Graph panel appears.
2. To specify the background color of the chart, click Edit in the
Background Color field, then select a color from the Select Color
dialog box.
3. Under Data Labels, choose an option:
None does not show any values for the graph.
Show values shows values for the graph.
User Guide 421

Charts
To specify data colors in the chart:
1. Click the Colors tab.
The Colors panel appears.
2. Choose a data color option:
To allow Change Integrity to select data colors automatically,
select the Automatic radio button.
To customize the data colors, select the Custom radio button,
then proceed to step 3.
3. Click Add.
The Select Color dialog box appears.
422 Source Integrity Professional Edition

4. Choose a color from the palette.
5. Click OK.
The data series appears in the Data Colors list.
Change Integrity Charts
6. To edit the color of an existing data series, select it from the list,
and click Edit, then select a color from the Select Color dialog box.
User Guide 423

Charts
7. To remove an existing data series, select it from the list, and click
Remove.
8. Repeat for each data series in the chart.
To specify the chart’s axes:
1. Click the Axes tab.
The Axes panel appears.
2. From the Label Rotation drop-down menu for the Horizontal Axis,
choose a location for the horizontal axis labels. The available
locations are:
Horizontal
Vertical (90 degrees)
Vertical (270 degrees)
3. From the Orientation drop-down menu for the Horizontal Axis,
choose a position for the horizontal axis. The available positions
are:
Right
Left
4. To show gridlines on the horizontal axis, select the Show Gridlines
checkbox.
424 Source Integrity Professional Edition

Change Integrity Charts
5. To show the title for the horizontal axis, select the Horizontal Axis’
Show Title checkbox.
6. From the Label Rotation drop-down menu for the Vertical Axis,
choose a location for the vertical axis labels. The available
locations are:
Horizontal
Vertical (90 degrees)
Vertical (270 degrees)
7. From the Orientation drop-down menu for the Vertical Axis,
choose a position for the vertical axis. The available positions are:
Up
Down
8. To show gridlines on the vertical axis, select the Show Gridlines
checkbox.
9. To show the title for the vertical axis, select the Vertical Axis’ Show
Title checkbox.
To specify the legend:
1. Click the Legend tab.
The Legend panel appears.
2. To show the legend, select the Show Legend checkbox.
User Guide 425

Charts
3. In the Title field, enter a title for the chart legend. A title is
optional.
4. In the Number of Columns field, enter the number of columns for
the legend, or click or .
5. In the Position field, choose a position for the legend on the chart
from the drop-down menu. The available positions are:
Right
Left
Top
Bottom
6. To choose a background color for the legend, click Edit, then
select a color from the Select Color dialog box.
To save the trend chart:
1. To save the chart, click OK. To cancel the operation, click Cancel.
The trend chart appears in the Charts list, indicated by a trend
chart icon.
2. To close the Charts dialog box, click OK.
426 Source Integrity Professional Edition

Editing Existing Charts
To edit an existing chart (graphic user interface only):
Change Integrity Charts
Note Shared charts can only be deleted by the owner. The Edit button is
greyed out.
1. Choose Charts > Customize, or click .
The Charts dialog box appears.
2. Select a chart to edit from the Charts list.
3. Click Edit.
User Guide 427

Charts
Running Charts
The Edit Chart dialog box appears.
4. Edit the chart options as desired.
5. To save the chart, click OK. To discard any changes, click Cancel.
6. To close the Charts dialog box, click OK.
To run a chart in the graphic user interface:
1. Choose Charts, or click .
Note Trend charts that include a long time span, for example, a year,
and a small step, for example, an hour, may take a long time to generate.
The Charts dialog box appears.
428 Source Integrity Professional Edition

2. Select a chart from the Charts list.
3. Click Run.
The chart appears in a Chart View window.
Change Integrity Charts
User Guide 429

Charts
Tip You can change the view of the chart data by clicking the graph and
dragging it in any direction. Hovering your cursor over a graph unit
displays a value tooltip.
To run a chart in the Web interface:
1. Click .
The Charts List page appears.
2. Click a chart from the Charts list.
The chart appears in a charts page.
Note The Change Integrity Web interface does not support chart view
options.
430 Source Integrity Professional Edition

Deleting Charts
To delete a chart (graphic user interface only):
Change Integrity Charts
Note Shared charts can only be deleted by the owner. The Delete button
is greyed out.
1. Choose Charts > Customize, or click .
The Charts dialog box appears.
2. Select a chart from the Charts list.
3. Click Delete.
Change Integrity asks you to confirm that you want to delete the
selected chart.
4. To confirm the operation, click Yes. To cancel the operation, click
No.
User Guide 431

Charts
Copying Charts
To copy a chart (graphic user interface only):
1. Select the chart you want to copy from the Charts list.
2. Click Copy.
The Copy dialog box appears.
432 Source Integrity Professional Edition

Saving and Printing Charts
3. Rename the chart and make changes as required.
Saving and Printing Charts
When you select the type of chart you want to generate, the chart
appears in a Chart window so you can save and print the chart.
User Guide 433

Charts
Saving Charts
Printing Charts
To save a chart (graphic user interface only):
1. Click Save.
A Save dialog box appears.
2. Browse to the location on your local drive where you want to
save the chart.
Note You can only save the chart as a JPEG image.
3. Click OK.
To print a chart in the graphic user interface:
1. Click Print.
434 Source Integrity Professional Edition

A standard Print dialog box appears.
2. Select the print options you want.
3. Click OK.
To print a chart in the Web interface:
1. Choose File > Print.
A standard browser Print dialog box appears.
2. Select the print options you want.
3. Click OK
Saving and Printing Charts
User Guide 435

Charts
436 Source Integrity Professional Edition

Integrated Version
Control
16
As part of the integration with Source Integrity, you can associate
project members with an issue, effectively adding the project
members as part of a change package.
A change package allows you to specify groups of files that are
affected by an issue type, for example, a solution’s change package
might contain files that need to be changed in order to satisfy a
problem.
Administrators define what issue types can use change packages and
configure Source Integrity to allow files to be checked in or checked
out only if they are associated with an issue.
This chapter provides details on:
configuring Change Integrity Connect
associating active issue types with project members
viewing change packages in Change Integrity
User Guide 437

Integrated Version Control
Configuring Change Integrity Connect
To configure Change Integrity Connect (Windows interface
only):
1. With the Source Integrity Windows interface open, choose
Configuration > Change Integrity Connect.
The Change Integrity Connect - Configuration dialog box appears.
Note If the configuration has already been defined by your
administrator in SAM, then the dialog is filled with the pre-defined
values.
2. To activate Change Integrity Connect, select the Enable Change
Integrity Connect checkbox.
All fields and buttons become active.
438 Source Integrity Professional Edition

Configuring Change Integrity Connect
3. In the Integrity Server field, enter the name of the server you want
to connect to, for example, localhost, or the numerical IP
address, for example, 1.234.53.
Note Do not use back slashes (\) in the server name, for example,
\\localhost.
4. In the CI User Name field, enter your Change Integrity user name.
Your Source Integrity User Name appears by default. The SAM
policy option AllowCIMultipleRoles must be set in order to change
this field.
5. As an option, you can choose to track locked and unlocked
project members in Source Integrity by selecting the Track Locks
checkbox. This field may be set and enforced by your
administrator in SAM with the TrackLocks policy option.
6. As an option, you can choose to add tracking labels to project
members in Source Integrity by checking the Add Tracking Labels
check-box. This field may be set and enforced by your
administrator in SAM with the AddTrackingLabel policy option.
7. To view active issues, click Refresh. The Current Set of Active CI
Issues section displays information about active issues.
Note You can only view active issues assigned to you.
Default Issue displays the selected default issue. To make an
issue your default issue, select an issue from the active issues
list, then click Make Default.
Selected Issue displays the selected issue in the list of active
issues.
Summary displays a brief summary about the issue.
User Guide 439

Integrated Version Control
Active issues are displayed in the active issue list below the
Default Issue field.
Note Your administrator defines which issue types can include change
packages.
8. To set no default issue, select None from the active issues list. This
option does not appear if Enforce Mandatory Tracking is set in the
Change Integrity Connect policy statement in SAM.
9. When you have finished configuring the Change Integrity
Connect options, choose an option by clicking a button:
OK saves the current configuration options.
Cancel closes the configuration dialog box without saving
any changes.
Launch CIWI connects to the Change Integrity Web interface
and displays complete information about the issue.
The Change Integrity Web interface opens, displaying the
issue.
440 Source Integrity Professional Edition

Associating Active Issues With Project
Members
Associating Active Issues With Project Members
Once you have configured Change Integrity Connect, you can
associate active issues with project members, effectively adding the
project members as part of a change package.
To associate an active issue with a project member (Windows
interface only):
1. In the Source Integrity Windows interface, check out one or more
files in the Sandbox or Project window. If you are tracking locks,
then these files are associated with the default issue.
2. Select one or more files in the Sandbox or Project window.
3. Choose Member > Check In.
User Guide 441

Integrated Version Control
The Check In dialog box appears.
Viewing Change Packages
4. Choose an issue from the Active CI Issue drop-down list.
5. Add additional metadata if needed, such as a revision
description.
6. Click OK.
If you select more than one file to check in, you can either
associate them all with the same issue, by selecting the All Files
checkbox, or associate each file with a different issue.
Once you associate project members with an issue, Change Integrity
adds the members as part of the issue’s change package. You can
view change packages in the Change Integrity graphic user interface
and Web interface.
To view a change package in the graphic user interface:
1. Open the issue, as described in “Selecting Issues to View” on
page 367.
The issue opens in the Issue Details.
442 Source Integrity Professional Edition

2. Click the Change Package tab.
The Change Package panel appears.
Viewing Change Packages
The Change Package panel displays the project the member belongs
to, member name, revision number, author name, lock status,
revision date, and revision description.
To view a change package in the Web interface:
1. Open the issue, as described in “Selecting Issues to View” on
page 367.
The issue opens in the Issue Details page.
User Guide 443

Integrated Version Control
2. Click the Change Package tab.
The Change Package panel appears.
The Change Package panel displays the project the member belongs
to, member name, revision number, author name, lock status,
revision date, and revision description.
444 Source Integrity Professional Edition

A P P E N D I X
Glossary
Source Integrity Terms
archived (project
member)
A
archive A file containing the most recent version of a document and a record
of all the changes made to it since it was put under revision control.
From the information contained in the record of changes,
Source Integrity can reconstruct any previous version of the file.
The archive is sometimes referred to as the RCS file, for historical
reasons.
The data of an archived project member is held in a revision of a
Source Integrity archive. The actual project member is, therefore, the
revision in the archive, not the archive itself.
archive description A set of general comments that describes the purpose of an archive.
You are asked to enter an archive description when an archive is
created. The text of the archive description can be viewed with the
Archive Information command.
archive directory The default location where Source Integrity looks for archives when
checking in working files. The archive directory is specified with the
Configuration > Personal command (Directories panel).
archive file See archive.
archive information In addition to an archive’s contents, Source Integrity also maintains
detailed information about each archive, including:
a list of revision labels used in the archive
a list of users who have locks on revisions in the archive
the starting point of the default branch revision
the type of data stored in the archive (that is, text or binary)
whether the archive is compressed
User Guide 445

Appendix A: Glossary
whether the archive is encrypted
whether a strict-locking policy is applied to the archive
a description of the archive (supplied by the user when the
archive was created)
archive log The file where archive transactions are recorded when logging is
turned on. The name and location of the log file is specified with the
Configuration > Personal command (Logging panel). If it exists, the log
file contains a record of each check-in and check-out (locked)
operation performed on the archive.
archive path The default location where Source Integrity looks for archives when
checking in files, if no appropriate WorkToArch statement is defined.
The archive path is specified with the Configuration > Personal
command (Directories panel).
archive transaction Any check-in or check-out (locked) action that is performed on an
archive. If logging is turned on, archive transactions are recorded in
the log file.
Archive window A window that allows you to view the contents of an archive, and
information about the archive and the revisions it contains.
author Usually, this is the name of the user who checked in a revision,
although any name can be used. On systems that use a login
procedure, this is typically the user’s login name. If the system does
not use login names, Source Integrity uses the name specified with
the Configuration > Personal command (Preferences panel).
author name The name Source Integrity knows you by. Your author name is
defined with the Configuration > Personal command (Preferences
panel). It is used to prime the Author field during check-in.
binary file A file containing unprintable characters, or lines too long to be
handled by text editors.
branch A secondary revision path that diverges from the main line of
development (or trunk) in an archive. A branch is created by
checking in a file to a revision other than the head revision. This most
recent revision of a branch is called the tip revision.
Changes made on a branch can be merged back into the trunk with
the Visual Difference utility’s Merge feature.
446 Source Integrity Professional Edition

Source Integrity Terms
check in An operation that adds a new revision of a file to an archive. The new
revision becomes the archive’s head revision unless you specifically
check in the file to a revision other than the head revision. When a file
is checked in to a revision other than the head revision or a branch tip
revision, a new branch is created.
check out An operation that extracts the contents of a revision in an archive and
copies it to a working file. You can check out any revision by
specifying either its revision number or label.
checkpoint An operation that creates an archive for your project file and checks it
in. When you checkpoint a project, you save all the information
needed to recreate the project completely at any time in the future.
The saved information includes the directory tree and the list of
members with their revision numbers.
compare window A window in which two text-based files or revisions are displayed for
comparison, along with a summary of the differences between them.
configuration file A file containing detailed descriptions of where archive and working
files are stored, locking policies, and other tailoring options.
Configuration files are referenced by Source Integrity each time the
program is started and are updated with the Configuration command.
data types The data preserved in Source Integrity archives can be one of three
types:
Binary
A file containing unprintable characters, or lines too long to be
handled by text editors.
Text
This is the file format expected by DOS and Windows text file
editors. When a file of type “Text” is checked out,
Source Integrity adds a carriage return at the end of each line.
Unspecified
This is the file format expected by most UNIX and other non-
DOS text file editors. When a file of type “Unspecified” is
checked out, Source Integrity does not add a carriage return
character to the end of each line.
date The date and time when a revision was checked in.
User Guide 447

Appendix A: Glossary
default branch The branch Source Integrity tries to check in files to. The default
branch is set with the Archive Information command. If unspecified,
files are checked in to the trunk.
default editor The editor used by the View Revision and View/Edit Working File
commands to display a working file or revision. It is also used to
view the log file. The default editor is defined with the Configuration
> Personal command (Directories panel).
deltas The differences (stored in an archive) between one revision and its
immediate ancestor. An archive contains one complete version of the
working file and all the deltas needed to reconstruct any revision.
demotion The process of changing a revision’s promotion state setting from a
higher to a lower level. When promotion is turned on, the range of
state settings that can be applied to revisions in an archive is defined
by the Configuration > Personal command (Promotion panel).
enforce An attribute that can be applied in SAM to protect file options from
being overridden by your personal configuration settings.
freeze (a member) To place a member in a state that prevents changes being made to the
member information that resides in the project file. For example, you
cannot update the member revision or change the member type for a
frozen member. The opposite of thaw.
freeze (a project) To place a project in a state that prevents changes being made to the
information in the project file. For example, you cannot perform
operations such as adding or deleting members, changing
configuration blocks, or setting variables on a frozen project. The
opposite of thaw.
global configuration
file
folder A term used in Microsoft Windows and NT to replace directory.
frozen The state a project or member (archived) exists in after you perform a
freeze action upon it.
A file containing default information about where archives and
working files are stored, locking policies and other tailoring options.
Global Configuration File settings cannot be set with the
Configuration command.
head revision The most recent revision on the main path of development (the trunk)
in an archive.
448 Source Integrity Professional Edition

Source Integrity Terms
keyword A special variable construct (for example, $Date$, $Author$,
$State$) used to represent textual information in a working file.
Keywords can be expanded (that is, replaced with their literal values)
when a revision is checked out.
keyword expansion The process of automatically adding or updating information to a
keyword reference when a revision is checked out or viewed.
non-archived (project
member)
label See revision label.
lock A Source Integrity feature that prevents more than one user from
simultaneously making changes to the same revision. When a
revision is locked, no one other than the locker can check in changes
to that revision. A revision can be locked when it is checked in,
checked out, or with the Lock Revision command.
locker The person who has a revision locked.
log file The file where archive transactions are recorded when logging is
turned on. The name and location of the log file is specified with the
Configuration > Personal command (Logging panel). If it exists, the log
file contains a record of each check-in and check-out (locked)
operation performed on the archive.
metadata Information about a revision or archive, as opposed to the information
that is part of the object. For example, a revision’s Revision
Description is information about the revision, while the text of the
revision is part of the revision itself.
Personal
Configuration File
A project member whose content is held in a single file that is not
under Source Integrity revision control.
A file containing user-specific information about where archive and
working files are stored, locking policies, and other tailoring options.
Personal Configuration File values are set with the Configuration
command.
The Personal Configuration File is called mksrcs.rc and is located in
the directory where Windows is installed.
project A group of files that, taken together, forms a single body of work.
Projects are presented in Project Windows, which list the members of
the project and provide access to them.
project directory The root of the directory tree where project member files reside.
User Guide 449

Appendix A: Glossary
project log A file that contains a record of all project transactions (for example,
check in, check out, and add member) since the last time the project
was checked in. It is viewed with the Project > View Log command.
project member Any file that is included in a project. Project members may include:
archived files
non-archived files
other Source Integrity projects (see subproject)
Project members are displayed in a Project window.
Project view In the Source Integrity Web Interface, a page that displays all the
members of a single project.
Project window In the Windows interface version, a window displayed in the
Source Integrity application window that contains all the members of
a single project.
promotion The process of managing data as it moves through a structured
development cycle. Any project (whether it is software development,
document production, or any other type of data management) goes
through recognizable phases: from inception, through development,
testing, quality assurance, and completion.
Using promotion, you can define the phases (or states) of your
development cycle and track and manage the progress of each file as
it moves through the process.
promotion state A state setting defined with the Configuration > Personal command
(Promotion panel). When promotion is turned on, only the defined
promotion state settings may be used.
revision A version of a file under revision control. Revisions are held in an
archive and may be stored as the complete content of the file (in the
case of the head revision) or a record of the changes that must be
applied to rebuild a specific version of the file.
A new revision is produced each time a working file is checked into
its archive.
revision description Free-form comments describing a revision. The revision description
can contain anything from a detailed description of changes, to
instructions for the next person who will work on the file.
450 Source Integrity Professional Edition

Source Integrity Terms
The revision description (sometimes referred to the log message) is
attached to a new revision at check-in time, and may be viewed and
appended with the Revision Information command. In the Windows
interface version, the Revision Description is also displayed in the
bottom panel of the Archive window.
revision label Text that describes and refers to revisions in an archive. When a file is
checked in, you are given the option of assigning it a revision label.
Revisions in an archive can be displayed and selected either by
revision number or revision label.
Revision labels can be added, appended, or deleted with the Revision
Information command.
revision number A unique number used to identify a revision in an archive. Revisions
on the trunk are numbered as two-part decimals (that is, 1.1, 1.2, 1.3,
…). Revisions on a branch are numbered by adding two-part
decimals to the number of the revision they branch from.
For example, if a branch is started from revision 1.3, its members
would be numbered
1.3.1.3
1.3.1.2
1.3.1.1
and so on.
sandbox A mirror image of a Source Integrity project. Although it looks and
acts like the project it mirrors, it is actually a collection of pointers to
its real-life counterparts in the master project.
Sandboxes provide a way for developers to work on projects in a
personal, protected workspace, without immediately impacting the
condition of the project or disrupting the work patterns of other
project developers.
With sandboxes, each user creates a personal workspace for a project
where changes can be made and tested before being merged back into
the master project. A Source Integrity sandbox consists of a sandbox
file and the directory it resides in.
Sandbox view In the Source Integrity Web Interface, a page that displays all the
members of a single project.
Sandbox window In the Windows interface version, a window displayed in the
Source Integrity application window that contains all the members of
a single sandbox.
User Guide 451

Appendix A: Glossary
state Free-form text used to classify the condition of a revision in an
archive. For example, a document could initially have a state of
“Draft”. As work progresses it might be changed to “Review” and
eventually “Complete”. If no state is assigned to a revision, a default
value of “Exp” (for Experimental) is used.
The state of a revision is assigned at check-in time. If promotion is
turned on, only the predefined promotion states may be used.
strict locking When strict locking is enabled for an archive, revisions must be
checked out locked if they are to be checked back into the archive as a
new revision. Revisions checked out unlocked are copied into readonly
files and may not be checked into the archive until a lock has
been obtained.
When strict locking is not enabled, revisions may be checked out
unlocked, edited, and checked back in.
subproject A member type applied to a sandbox or project member that is itself a
Source Integrity project.
tip revision The most recent revision on a branch of an archive.
thaw To remove the frozen state of a project or member so that changes can
again be made to the project file or member information. The
opposite of freeze.
trunk The primary line of a file’s change history in an archive. The first
member of the trunk is always the original file checked into the
archive. The most recently checked in member of the trunk is referred
to as the head revision.
type (project member) Project members may be one of following types of files:
archived (files under Source Integrity revision control)
non-Archived (files not under Source Integrity revision control)
subproject (another Source Integrity project)
user name The name Source Integrity knows you by. User name is defined using
the Configuration > Personal command (Preferences panel). By
default, user name is used as the author during check-in.
variant sandbox A sandbox that is created from a previous project checkpoint rather
than the current (or head) revision of a project. You create a variant
sandbox when you want to branch to a variant development path. It
is akin to creating a branch archive.
452 Source Integrity Professional Edition

Visual Difference
window
Source Integrity Terms
The main window of the Visual Difference utility used by the
Compare Files, Compare Revisions, and Differences commands to
display the differences between text-based files or revisions.
working directory The complete path to the root of the work tree (that is, the directory or
hierarchy of directories where working files are stored and changes
are made to them). Each sandbox or project has its own working
directory.
See sandbox directory; project directory.
working file A file that contains a working copy of a checked-out revision. Users
edit and change the working file, not the revision itself. Changes to
the working file are added to the archive (as a new revision) when the
working file is checked in.
work tree The directory or hierarchy of directories where working files are
stored and changes are made to them.
User Guide 453

Appendix A: Glossary
Change Integrity Terms
administrator The administrator installs the Change Integrity database on a
network, defines and customizes issue types and workflow, and
creates additional user accounts, allowing users to access the
program.
attached files Change Integrity allows you to attach copies of files to an issue, so
that other users may view them.
change package A change package allows you to specify groups of files that are
affected by an issue type, for example, a solution’s change package
might contain files that need to be changed in order to satisfy a
problem.
charts Charts are graphs that present trends over time, or distributions of the
data in your project. Charts are based on the standard and custom
fields of issue types. Trend charts may be displayed as line graphs.
Distribution charts may be displayed as pie graphs or bar graphs.
database A database is the container of Change Integrity projects, and may
contain any number of Change Integrity projects. You can easily
access multiple databases from Change Integrity, but only one at a
time.
group A group consists of one or more users who need to work with
Change Integrity issues.
issues Issues track changes in the software development cycle. For example,
your administrator can configure Change Integrity in a way that a
problem issue may be associated with a solution issue for easy tracking
and monitoring of both issues. Each issue has an audit trail, which
may be used to evaluate internal processes for the effectiveness of the
problem resolution process. In effect, issues track all aspects of any
engineering endeavor.
issue types Issue types capture and track a specific change request, defect,
problem, solution, or task.
project Projects are labels that help you sort and organize issues in a
hierarchical structure.
454 Source Integrity Professional Edition

Change Integrity Terms
query A query is a request to select and list the issue types that meet specific
selection criteria. The selection criterion is a logical expression of
specific values, or ranges of values, of the standard and custom fields
of the issue type. Queries are unique for each project because each
issue type may have different custom fields.
reports Reports are summaries of the data in your project. Reports are based
on the standard and custom fields of issue types. Reports can be
customized to include images, fonts, hyperlinks, and can be saved as
HTML files for viewing on the Web.
states Issue types can each have their own set of states to advance through.
They can also follow a state model defined by the project
administrator, giving greater control over who has access to a specific
issue type at a given time, as well as who has responsibility for
approving the advancement of the state.
user A user is anyone who needs to work with Change Integrity issues.
Users are assigned user permissions to them by the administrator.
Users are also assigned to groups that have specific Change Integrity
group permissions assigned to them by the administrator.
workflow Each issue follows workflow, the process established by your
administrator to capture and track information during your software
development cycle. Each issue type can have its own set of states to
advance through the development cycle. For example, a change
request may go through the following states: submitted, work
started, tested, reviewed, closed. Issues and their current states
provide change management information necessary to support
business decisions.
User Guide 455

Appendix A: Glossary
456 Source Integrity Professional Edition

Index
-, 251
$, 274
$$, 274
$$*, 276
$$@, 276
$%, 274
$&, 274
$*, 274
$>, 274
$?, 274
$@, 274
$^, 274
+, 251
.DEFAULT, 282
.ELSE, 296
.ELSIF, 297
.END, 297
.EPILOG, 266, 273, 280
.EXPORT, 268, 268
.GROUPEPILOG, 280
.GROUPPROLOG, 280, 290
.IGNORE, 266, 284
.IMPORT, 261
.INCLUDE, 269, 279
.INCLUDEDIRS, 270, 279
.LIBRARY, 293, 295
.NOAUTODEPEND, 293
.POSIX, 270, 288, 293
.PRECIOUS, 266, 273
.PROLOG, 266, 273, 280, 290
.SETDIR, 267, 305, 305
.SILENT, 267, 273, 284, 291
.SOURCE, 271, 277, 305, 306
.SOURCE.x, 271
.SUFFIXES, 287, 287
.SYMBOL, 284
@, 251
@Depends configuration statement, 237
@Template configuration statement, 237
A
accessing metadata, 152
activating an issue, 438
active issue, 92
Add Label
Web interface command, 116, 183
Add Members
Windows interface command, 72
adding
attachments
batch edit, 379
labels, 116
members to a project, 72
related issues
batch edit, 380
administrator
described, 454
All Files option, 92
application window
graphic user interface, 317
archive
branches, 17
checking in revisions, 174
checking out revisions, 172
commands, 61
creating, 167
automatically or interactively, 67
using Microsoft Windows Explorer, 228
defined, 10, 13
deltas, 16
described, 445
editing information, 176
file format
User Guide 457

Index
text or binary, 170
importing, 171
existing RCS archives using CLI, 151
in configuration management, 10
information
using CLI, 152
library extensions, 257
managing, 165–196
settings, 169
structure, 14
trunks, 17
viewing archive information, 176
archive
overview, 13
archive description
described, 445
archive directory
described, 445
archive file
described, 445
Archive Information
Windows interface command, 176
archive information
described, 445
archive log
described, 446
archive path
described, 446
archive transaction
described, 446
Archive window
described, 446
archived (project member)
described, 445
archived member type, 86
ARFLAGS, 294
Associating, 441
associating
active issues with project members, 441
at-sign in Make, 251
attached files
described, 454
attachments
adding to an issue, 340
opening, 344
removing, 343
saving, 346
attributes, 32, 265–267
in Make, 250
member, 153
removing using CLI, 155
setting using CLI, 153
project, 97, 155
assigning using CLI, 155
removing using CLI, 156
sandbox, 97
author
described, 446
Author keyword, 131
author name
described, 446
Author option, 91
automatic encryption, 160
B
backslash, 250, 291
back-up, 308
batch editing, 377
adding attachments, 379
adding related issues, 380
fields, 378
bcc, 247
before starting
Change Integrity, 314
binary files, 17
described, 446
storing in Reference format, 196
blank characters, 249
Borland C++, 247, 256, 299
Borland Delphi 1.0, 2.0, &3.0, 197
Borland Delphi extension, 223
checking in, 226
multiple files, 227
checking out, 225
multiple files, 226
creating
Source Integrity project, 224
Source Integrity sandbox, 225
Borland Make, 299
branch, 17
default, 20
defined, 11
described, 446
in configuration management, 11
level, 19
458 Source Integrity Professional Edition

number, 19
root revision, 17
specifying, 19, 19
starting, 18
starting during check-in, 87
branch revision
defined, 87
revision numbers, 87, 87
browser plugin for Source Integrity Web Interface,
48, 50
BSD UNIX Make, 300
Build
Windows interface command, 119
building, 234
conditional expansion, 236
language statements, 236
object file associations, 235
preparation, 232
projects, 118
template files, 236
variables, 237
built-in commands in Make, 289
built-in rules in Make, 255
C
CC, 257, 302–304
cc, 302, 303
CFLAGS, 257, 304
Change Integrity
before starting, 314
concepts, 312
graphic user interface, 317
Web interface, 320
Change Integrity Connect
add tracking labels, 439
Change Integrity Server, 439
Change Integrity user name, 439
configuration, 438
configuring, 438
default issue, 439
enable Change Integrity Connect, 438
issue summary, 439
launch Change Integrity Web interface, 440
refresh, 439
selected issue, 439
track locks and unlocks, 439
change package
described, 454
viewing, 442
changing
search order in Make, 245
charts, 406
copying, 432
deleting, 431
described, 313, 454
distribution, 406
editing, 427
printing, 434
running, 428
saving, 434
trend, 406
Check In
Web interface command, 92
Windows interface command, 89
working file, 174
check in
described, 447
Check In Same option, 91
Check Out
Windows interface command, 81
check out
described, 447
keywords, 129
Check Out Locked
Web interface command, 84
checking in
active issue, 92
members, 87
multiple files
using Borland Delphi, 227
using Borland Delphi, 226
using Microsoft Developer Studio, 220
using Microsoft Visual Basic, 217
using Microsoft Windows Explorer, 229
what happens, 15, 15
Windows interface options
All Files, 92
Author, 91
Check In Same, 91
Keep Work File, 91
Locked, 91
Replace Label, 91
Revision Description, 92
Revision Label, 90
Revision Number, 91
User Guide 459

Index
State, 91
Update Member, 91
checking out
by revision, 173
by state setting, 174
locked
using CLI, 172
multiple files
using Borland Delphi, 226
revision number, 173
state settings, 174
unlocked
using CLI, 172
using Borland Delphi, 225
using Microsoft Developer Studio, 219
using Microsoft Visual Basic, 216
using Microsoft Windows Explorer, 229
Windows interface options
All Files, 83
Expand Keywords, 83
Locked (for editing), 83
name of working file, 82
Restore Timestamp, 83
Update Member, 83
which revision, 82
checkpoint
described, 447
Checkpoint Project
Web interface command, 139
Windows interface command, 137
checkpointing projects, 20, 136
ci CLI command, 170
cleaning up
makefiles, 307
working files, 159, 195
CLI commands, 68–128, 136–158, 170–196
pj build, 234
pj mkmf, 233
closing a session, 328
cmd.exe, 250, 289
cnvrnt72, 28
co CLI command, 172
code blocks
editing using CLI, 157
command prefixes
Make, 251
command.com, 250, 289
commands
bcc, 247
cc, 303, 303
CLI
ci, 170
co, 172
delvariant, 158
pj add, 74
pj addrule, 153
pj build, 156
pj checkpoint, 80, 139
pj ci, 93
pj clean, 159, 195
pj co, 84
pj create, 68
pj dropblock, 157
pj droprule, 155
pj editblock, 157
pj freeze, 107
pj freezeproject, 135
pj header, 153
pj label, 117
pj mods, 145, 153
pj print, 152
pj refresh, 105
pj sandbox, 79, 159
pj set, 157
pj thaw, 108, 174
pj thawproject, 136
pj unset, 156
pj what, 152
pvcs2rcs, 148
rcs, 183, 189, 191, 193, 196
rcsclean, 195
report, 128, 152
rlog, 180
sccs2rcs, 148
ident, 130
link, 292
make, 252
syntax
line length, 62
naming files, 63
path separator, 62
wildcard expansion, 62
touch, 308
Web interface
Add Label, 116, 183
Check In, 92
460 Source Integrity Professional Edition

Check Out Locked, 84
Checkpoint Project, 139
Create Sandbox, 78
Delete, 189
Delete Label, 118, 183
Differences, 99
Drop, 75
History > Demote, 142
History > Promote, 142
Lock, 101
Member > Demote, 112
Member > Promote, 112
Member Commands > Add, 73
Member Commands > View, 185
Merge, 192
Open History View, 140, 166
Open Member View, 167
Open Project, 70
Open Sandbox, 71
Promote, 186
Refresh, 115
Refresh Project, 115
Refresh Sandbox, 115
Register Project, 69
Register Sandbox, 69
Resynchronize, 105, 113
Unlock, 103
Update to Tip Revision, 113, 114
View, 87
which, 244
Windows interface
Add Members, 72
Archive Information, 176
Build, 119
Check In, 89
Check Out, 81
Checkpoint Project, 137
Configuration > Personal, 114
Create Sandbox, 76
Delete Revision, 189
Demote, 186
Demote Revision, 186
Differences, 99
Edit Working File, 85
Freeze, 106
Freeze Project, 134
Lock, 101
Member > Demote, 111
Member > Promote, 111
Member Information, 109
Open Member Archive, 86, 166
Open Project Archive, 140, 166
Open Project/Sandbox, 70
Open Subproject, 85
Project/Sandbox Information, 95
Promote Revision, 185
Refresh, 115
Remove Members, 75
Remove Unused Locks, 103
Reports, 124
Resynchronize, 104, 113
Revision Information, 178
Scan for Changes, 115
Thaw, 107
Thaw Project, 135
Undo Checkout, 100
Unlock, 102
Update to Head Rev, 113
Update to Tip Rev, 114
View Log, 142
View Revision, 86, 184
View Working File, 85
View/Edit Working File, 184
comments in Make, 250
common list actions, 365, 367
compare window
described, 447
comparing
files, 190
revisions, 190
working file to member revision, 99
compatibility in Make, 244, 296
compilation configuration files in Make, 302
concepts
Change Integrity, 312
conditional expansion, 236
conditionals in Make, 296
Configuration > Personal
Windows interface command, 114
configuration file
described, 447
configuration management
concepts, 10
introduction, 6
configuration statements
@Depends, 237
User Guide 461

Index
@Template, 237
configuring
Change Integrity Connect, 438
content page
Web interface, 321
context menu
graphic user interface, 318
continuation lines in Make, 250
control macros
in Make, 272–273
used with group recipes, 290
copying
charts, 432
reports, 398
Create Sandbox
Web interface command, 78
Windows interface command, 76
wizard, 76
creating
archives, 167
distribution charts, 407
makefiles, 233
projects
in Source Integrity Web Interface, 68
reports, 386
sandboxes, 76
saved queries, 354
trend charts, 417
D
dash in Make, 251
data types
described, 447
database
described, 454
date
described, 447
Date keyword, 131
DEFAULT, 282
default branch, 20
described, 448
default editor
described, 448
default rules in Make, 255
default startup rules for Make, 298
defining
Make macros on the CLI, 259
Delete
Web interface command, 189
Delete Label
Web interface command, 118, 183
Delete Revision
Windows interface command, 189
deleting
charts, 431
files, 170
labels, 116
queries, 356
reports, 397
revisions, 189
variant sandboxes
using CLI, 158
deltas
archives, 16
described, 448
storing changes only, 16, 17
storing entire file by reference, 17
delvariant CLI command, 158
Demote
Windows interface command, 186
Demote Revision
Windows interface command, 186
demoting
members, 110
projects, 140
revisions, 185
demotion
described, 448
dependencies, 118
dependency of files in Make, 246
descriptions
reports, 392
development cycle, 36
development objects
defined, 12
development paths
and variant sandboxes, 24
development, managing, 36
Differences
Web interface command, 99
Windows interface command, 99
directories
master, 307
mksnt, 244
mksos2, 244
462 Source Integrity Professional Edition

DIRSEPSTR, 272
distribution charts, 406
creating, 407
creating from a saved query, 410
saving, 417
specifying a graph, 411
specifying a legend, 416
specifying axes, 414
specifying colors, 412
specifying fields, 409
specifying query filters, 410
specifying text, 408
Drop
Web interface command, 75
dynamic prerequisite macros, 276
E
Edit Working File
Windows interface command, 85
editing
archive information, 176
charts, 427
code blocks using CLI, 157
issues, 376
members, 85
multiple issues, 377
project information, 94
reports, 393
revision information, 178
revisions, 184
sandbox information, 94
saved query properties, 357
working file, 184
ELSE, 296
ELSIF, 297
encrypting files
using CLI, 160
encryption
automatic, 160
changing encryption key, 162
choosing encryption key, 161
explicit, 160, 161
using CLI, 160
with other applications, 162
working with, 162
END, 297
enforce
described, 448
environment variables
MAKESTARTUP, 255
PROJECT, 62
ROOTPROJECT, 62
EPILOG, 266, 280
examples
.EPILOG, 280
.GROUPEPILOG, 280
.GROUPPROLOG, 280
.INCLUDE, 279
.INCLUDEDIRS, 279
.PROLOG, 280
.SETDIR, 267
cc, 303, 304
cleaning up makefiles, 307
conditionals in Make, 296
continuation lines in Make, 250
defining Make macros on the CLI, 259
finding files in Make, 278
group recipes in Make, 290
macro expansion in Make, 256
macro naming conventions in Make, 258
make, 253
makefile, 256
makefiles, 247
making libraries in Make, 293
prefix and suffix modifiers, 264
printchk, 308
recipes in Make, 292
running Make without a makefile, 304
run-time macros in Make, 275
simple makefile, 305
specifying targets on the CLI in Make, 252
string substitution, 262–263
suffix rules in Make, 286
tokenization, 263
using a library, 306
using a separate object directory in Make, 305
using different makefile, 252
writing rules in Make, 248
executable file extensions, 257
expansion, 256
wildcard, 62
explicit encryption, 160
EXPORT, 268
expressions in Make, 297
extensions
User Guide 463

Index
archive window, 206
Borland Delphi, 223
creating projects, 210
creating sandboxes, 212
difference between extensions and Source Integrity,
210
features, 198
Microsoft Developer Studio 97, 218
Microsoft Visual Basic, 214
Microsoft Windows Explorer, 227
project window, 199
using, 209
F
fields
batch editing, 378
file names containing a colon in Make, 249
files
.bat, 290
.obj, 248, 257, 297
format
text or binary, 170
filters
project view, 57
sandbox view, 53
using within extensions Project window, 200
Windows interface
all members, 44
frozen members, 45
locked by me, 45
locked members, 45
members with label, 45
members with state, 45
modified members, 44
out-of-sync members, 45
subprojects, 45
using, 44
finding files
Make, 277–278
folder
described, 448
Freeze
Windows interface command, 106
freeze (a member)
described, 448
freeze (a project)
described, 448
Freeze Project
Windows interface command, 134
freezing
members, 106
projects, 134
frozen
described, 448
G
generic command line format in Make, 303
global configuration file
described, 448
glossary of terms, 445
graph, 124
graphic user interface
application window, 317
context menu, 318
Issue Details, 319
menu bar, 317
Query Bar, 318
Query Builder, 318
Query Results, 318
status bar, 318
toolbar, 318
group
described, 313, 454
permissions
described, 313
group recipes, 289
GROUPEPILOG, 280
GROUPFLAGS, 290
GROUPPROLOG, 280, 290
groups
defined, 35
GROUPSHELL, 290
GROUPSUFFIX, 290
H
head rev
updating to, 113
head revision
described, 448
Header keyword, 131
headers
makefile variable, 238
History > Demote
464 Source Integrity Professional Edition

Web interface command, 142
History > Promote
Web interface command, 142
history view, 58
I
Id keyword, 131
ident command, 130
IDEs, 197
IGNORE, 266, 284
Ignore Non-Members option, 122
ignoring errors in Make, 299
IMPORT, 261
importing
archives, 171
files
PVCS, 149
SCCS, 149
using CLI, 148
INCLUDE, 269, 279
INCLUDEDIRS, 270, 279
inheriting meta-rules, 284
installing
Source Integrity Web Interface, 50
Source Integrity Web Interface browser plugin,
48, 50
Integrated Development Environments
see IDEs
Integrity Server, 48, 49
Issue Details
graphic user interface, 319
issue type relationships
described, 312
issue types
described, 312, 454
relationships
described, 312
issues
adding attachments, 340
associating with project members, 441
described, 312, 454
editing, 376
linking, 347
printing, 371, 371
relating, 335
saving, 373
selecting, 367
submitting, 332
viewing, 367
K
Keep Work File option, 91
keyword
Author, 131
Date, 131
described, 449
Header, 131
Id, 131
Locker, 131
Log, 132
Name, 132
ProjectName, 132
ProjectRevision, 132
RCSfile, 132
Revision, 132
Source, 132
State, 132
keyword expansion, 129
described, 449
keywords, 33
check out, 129
defined, 33, 129
locating, 130
removing keyword values, 131
using, 129
working file, 129
L
label
described, 449
labels, 29
adding, 116
assigning
in GUI and Source Integrity Web Interface,
116
in Windows and Web interfaces, 183
with CLI, 94
changing, 175
deleting, 116
requirements, 30
language statements for building, 236
LDFLAGS, 304
LDLIBS, 295
User Guide 465

Index
LIBRARY, 293
link, 292
linking
issues, 347
lists
common actions, 365, 367
local default rules in Make, 255
locating keywords, 130
Lock
Web interface command, 101
Windows interface command, 101
lock
described, 449
Locked option, 91
locker
described, 449
Locker keyword, 131
locking
in variant sandboxes, 26
members, 101
revisions, 187
locks
removing unused, 103
log file
described, 449
log files, 33
Log keyword, 132
logging, 142, 193
cleaning up log files, 142, 195
log file format, 194
logging in, 314
password, 315, 316
port number, 315
server name, 315
user name, 315, 316
logging out, 328
M
macro definitions, 254
macro expansion in Make, 256
modifying, 261–265
macro modifiers in Make, 262
macro naming conventions in Make, 258
MAKE, 307
Make
attributes, 265–267
back-up, 308
built-in commands, 289
built-in rules, 255
cc, 303
changing your search order, 245
cleaning up, 307
colons in file names, 249
command prefixes, 251
compatibility, 244, 296
compilation configuration files, 302
conditionals, 296
control macros, 272–273
used with group recipes, 290
default rules, 255
default startup rules, 298
defining macros on the CLI, 259
dependency of files, 246
dynamic prerequisite macros, 276
finding files, 277–278
forms of expressions, 297
generic command line format, 303
group recipes, 289
ignoring errors, 299
local default rules, 255
macro definitions, 254
macro naming conventions, 258
makefiles, 246, 247
MAKESTARTUP, 255
making libraries, 293–296
metarules, 282–286
metarules for library support, 294
missing rules, 251
modifying macro expansions, 261–265
nesting macros in other macros, 259–261
options
-D, 254, 255
-f, 255
-f file, 254
-k, 254
-n, 254
-u, 254
prefix and suffix modifiers, 264
problems, 304–308
recipes, 288–293
recursive makes, 307
rules, 247, 250–251
running Make without a makefile, 304
run-time macros, 274–275
search order, 245
466 Source Integrity Professional Edition

special target directives, 267–271
specifying targets on the CLI, 252
string substitution, 262–263
suffix rules, 286–288
suffix rules for library support, 295
text diversions, 291
tokenization, 263
transitive closure, 285
using a separate object directory, 305
using CC, 302–304
using different makefile, 252
using inference rules, 281–288
using macros, 256–265
writing rules, 248–249
make command, 252, 253
makefile, 246, 247, 255
creating, 233
template, 236
MAKEFLAGS, 307
MAKESTARTUP, 255, 292
making libraries, 293–296
managing archives, 165–196
managing development, 36
master project
see project
Member > Demote
Web interface command, 112
Windows interface command, 111
Member > Promote
Web interface command, 112
Windows interface command, 111
member attributes, 153
removing using CLI, 155
setting using CLI, 153
Member Commands > Add
Web interface command, 73
Member Commands > View
Web interface command, 185
Member Information
Windows interface command, 109
member type
archived, 86
non-archived, 86
subproject, 86
member view, 55
members
associating an active issue, 441
checking in, 87
demoting, 110
editing, 85
freezing, 106
information
active issue, 109
Archive File, 108
Author, 108
Date, 108
Label, 108
Locker, 108
Member, 108
Revision, 108
Revision description, 109
State, 108
Type, 108
Working File, 108
locking, 101
promoting, 110
removing from project, 75
thawing, 106
unlocking, 101
viewing, 85
viewing information, 108
menu bar
graphic user interface, 317
Merge
Web interface command, 192
merging working files, 192
metadata, 152
attributes, 32
defined, 11
described, 449
in configuration management, 11
keywords, 33
labels, 29
log files, 33
revision descriptions, 30
timestamps, 31
and building, 31
setting, 31
metarules, 282–286
for library support in Make, 294
Microsoft C++, 300
Microsoft C/C++, 247
Microsoft Developer Studio, 197
Microsoft Developer Studio 97 extension, 218
Microsoft Developer Studio extension
checking in, 220
User Guide 467

Index
checking out, 219
creating Source Integrity project, 219
creating Source Integrity sandbox, 219
Microsoft Make, 300
Microsoft Visual Basic extension, 214
checking in, 217
checking out, 216
creating Source Integrity project, 215
creating Source Integrity sandbox, 216
Microsoft Windows Explorer, 197
Microsoft Windows Explorer extension, 227
checking in, 229
checking out, 229
creating archives, 228
missing rules in Make, 251
mksnt, 244
mksos2, 244
modifiers, 262
N
Name keyword, 132
nesting macros in other macros, 259–261
new submissions
notifications, 323
NOAUTODEPEND, 293
non-archived
member type, 86
non-archived (project member)
described, 449
notifications
new submissions, 323
NULL, 258, 272, 273, 277
O
object file, 257
associations, 235
OBJECTS, 292
objects
makefile variable, 238
Open History View
Web interface command, 140, 166
Open Member Archive
Windows interface command, 86, 166
Open Member View
Web interface command, 167
Open Project
Web interface command, 70
Open Project Archive
Windows interface command, 140, 166
Open Project/Sandbox
Windows interface command, 70
Open Sandbox
Web interface command, 71
Open Subproject
Windows interface command, 85
opening
attachments, 344
project archives, 140
projects, 70
in Source Integrity Web Interface, 70, 71
in Windows interface, 70
related issues, 339
OS, 272
OS/2, 245
OSRELEASE, 273
OSVERSION, 272
P
PATH, 245
Path, 245
path separator, 62
Personal Configuration File
described, 449
pj add CLI command, 74
pj addrule CLI command, 153
pj build CLI command, 156, 234
pj checkpoint CLI command, 80, 139
pj ci CLI command, 93
pj clean CLI command, 159, 195
pj co CLI command, 84
pj create CLI command, 68
pj dropblock CLI command, 157
pj droprule CLI command, 155
pj editblock CLI command, 157
pj freeze CLI command, 107
pj freezeproject CLI command, 135
pj header CLI command, 153
pj label CLI command, 117
pj mkmf CLI command, 233
pj mods CLI command, 145, 153
pj print CLI command, 152
pj refresh CLI command, 105
pj sandbox CLI command, 79, 159
468 Source Integrity Professional Edition

pj set CLI command, 157
pj thaw CLI command, 108, 174
pj thawproject CLI command, 136
pj unset CLI command, 156
pj what CLI command, 152
plugin for Source Integrity Web Interface, 48, 50
plus-sign in Make, 251
policy
defined, 34
POSIX, 244, 257, 270, 288, 293
PRECIOUS, 266
prefix and suffix modifiers in Make, 264
prerequisites in Make, 251
printing
charts, 434
issues, 371, 371
reports, 401
product terms
defined, 445
project
adding members, 72
with CLI, 74
attributes, 155
assigning using CLI, 155
removing using CLI, 156
building, 118
checkpointing, 20, 136
commands, 61
creating
in Source Integrity Web Interface, 68
using Borland Delphi, 224
using Microsoft Developer Studio, 219
using Microsoft Visual Basic, 215
using Source Integrity extensions, 210
defined, 13
demoting, 140
described, 313, 449, 454
editing information, 94
freezing, 134
opening, 70, 328
in Source Integrity Web Interface, 70
in Windows interface, 70
opening in Source Integrity Web Interface, 71
opening project archives, 140
organization, 13
overview, 13
promoting, 140
refreshing, 115
registering, 69
removing members, 75
resynchronizing, 104
scanning for changes, 114
structure, 13
thawing, 134
viewing information, 94
project directory
described, 449
PROJECT environment variable, 62
project file, 143
changes, 143
project information
changed members, 152
list of members, 152
reports, 128
variables and attributes, 153
project log
described, 450
project member
described, 450
project members
associating with an active issue, 441
Project view
described, 450
project view, 56–58
filters, 57
selections, 58
Project window
described, 450
Project/Sandbox Information
Windows interface command, 95
projectFiles
makefile variable, 238
ProjectName keyword, 132
ProjectRevision keyword, 132
PROLOG, 266, 273, 280, 290
Promote
Web interface command, 186
Promote Revision
Windows interface command, 185
promoting
members, 110
projects, 140
revisions, 185
promotion
described, 450
promotion state
User Guide 469

Index
described, 450
PVCS
importing, 149
pvcs2rcs CLI command, 148
PWD, 272, 273
Q
queries
creating saved, 354
deleting, 356
filters
reports, 391
refreshing, 361
reverting, 356
running, 359
query
described, 313, 455
Query Bar
graphic user interface, 318
Query Builder
graphic user interface, 318
Query Results
graphic user interface, 318
viewing, 364
query toolbar
Web interface, 320
R
rcs CLI command, 183, 189, 191, 193, 196
rcsclean CLI command, 195
RCSfile keyword, 132
recipes in Make, 251, 288–293
recursive makes, 307
Reference format, 17, 196
Refresh
Web interface command, 115
Windows interface command, 115
refresh
queries, 361
Refresh Project
Web interface command, 115
Refresh Sandbox
Web interface command, 115
refreshing project or sandbox, 115
Register Project
Web interface command, 69
Register Sandbox
Web interface command, 69
registering
projects, 69
related issues
opening, 339
removing, 338
relating
issues, 335
Remove Members
Windows interface command, 75
Remove Unused Locks
Windows interface command, 103
removing
attachments, 343
keyword values, 131
project members, 75
related issues, 338
unused locks, 103
Replace Label option, 91
report CLI command, 128, 152
report types, 37
Reporter, 124
overview, 37
report types, 37
change history, 37
changes by author, 37
changes from member to label, 37
changes from member to revision, 37
locked revisions, 37
newer revisions, 37
revisions with label, 37
revisions with state, 37
summary of changes by file type, 37
Reports
Windows interface command, 124
reports, 128, 386
copying, 398
creating, 386
creating from saved queries, 391
deleting, 397
described, 313, 455
descriptions, 392
editing, 393
graphs, 124
printing, 401
query filters, 391
running, 395
470 Source Integrity Professional Edition

saving, 392, 400
templates, 387
Resynchronize
Web interface command, 105, 113
Windows interface command, 104, 113
resynchronizing
projects, 104
sandboxes, 104
reverting
queries, 356
revision
described, 450
revision description
described, 450
Revision Description option, 92
revision descriptions, 30
adding, 175
Revision Information
Windows interface command, 178
revision information
locked revisions, 182
revision description, 175
using CLI, 152
Revision keyword, 132
revision label
described, 451
see labels
Revision Label option, 90
revision labels
changing, 175
revision number
described, 451
Revision Number option, 91
revision numbers
changing, 91
defined, 19
valid, 88
revisions
comparing, 190
defined, 10, 12
deleting, 189
demoting, 185
editing, 184
revision information, 178
in configuration management, 10
locking, 187
promoting, 185
unlocking, 187
viewing, 184
revision information, 178
viewing metadata
with archive commands, 180
rlog CLI command, 180
roles
defined, 35
root revision, 17
defined, 17
ROOTDIR, 244
ROOTPROJECT environment variable, 62
rule operator in Make, 250
rules in Make, 250–251
running
charts, 428
queries, 359
reports, 395
run-time macros in Make, 274–275
S
SAM, 34–35
groups
defined, 35
overview, 34
policy
defined, 34
roles
defined, 35
structure, 34
users
defined, 34
Sandbox view
described, 451
filters, 53
sandbox view, 52–55
selections, 54
Sandbox window
described, 451
sandboxes, 21, 115
and projects, 22
applications, 22
creating, 76
using Borland Delphi, 225
using Microsoft Developer Studio, 219
using Microsoft Visual Basic, 216
using Source Integrity extensions, 212
described, 451
User Guide 471

Index
editing information, 94
overview, 21
resynchronizing, 104
sparse, 81
using, 21
variant, 24
viewing information, 94
saved queries
creating reports, 391
properties
editing, 357
viewing, 357
undo changes, 356
saving
attachments, 346
charts, 434
distribution charts, 417
issues, 373
reports, 392, 400, 400
session preferences, 327
trend charts, 426
Scan for Changes
Windows interface command, 115
scanning projects for changes, 114
SCCS
importing, 149
sccs2rcs CLI command, 148
SCM
see Software Configuration Management
search order, 245
security, 34–35
and SAM, 34–35
Security and Administration Module
see SAM
selecting
issues, 367
selecting a project, 328
selections
project view, 58
sandbox view, 54
session
closing, 328
logging in, 314
logging out, 328
preferences
email notification, 323
general, 321
layout, 322
saving, 327
setting, 321
toolbar, 327
session preferences
setting, 321
SETDIR, 267, 305
setting
session preferences, 321
SHELL, 273
SHELLFLAGS, 289
SHELLMETAS, 288
SILENT, 267, 273, 284, 291
slash, 263
Software Configuration Management, 1
solving problems in Make, 304–308
SOURCE, 271, 277, 305, 306
source control, 437
Source Integrity, 284, 300
Source Integrity extensions
features, 198
using, 209
Source Integrity Web Interface, 49, 50
browser plugin, 48, 50
client component, 48
installing, 50
session applet, 48
starting, 50–51
Source keyword, 132
SOURCE.x, 271
sources
makefile variable, 238
sparse sandboxes, 81
special target directives, 267–271
macros and, 261
specifying targets on the CLI in Make, 252
starting
branch during check-in, 87
Source Integrity Web Interface, 50–51
state
assigning, 94
described, 452
settings
assigning, 94, 176
State keyword, 132
State option, 91
states
described, 455
status
472 Source Integrity Professional Edition

Web interface, 321
status bar
graphic user interface, 318
storing
binary files, 17
text files, 16, 17
strict locking, 84
check in using CLI, 172
described, 452
using CLI, 172
string substitution, 262–263
submissions
notifications, 323
submitted issues
relating
issues, 335
submitting
issues, 332
subproject
described, 452
member type, 86
suffix rules, 286–288
for library support in Make, 295
SUFFIXES, 287
SWITCHAR, 273, 289
SYMBOL, 284
symbols
beside members
frozen member, 56
inaccessible archive, 57
tip revision, 56
beside revisions
member revision, 55
System V MAKE, 301
T
template files, 236
templates
reports, 387
terms
defined, 445
text diversions in Make, 291
Thaw
Windows interface command, 107
thaw
described, 452
Thaw Project
Windows interface command, 135
thawing
members, 106
projects, 134
timestamps, 31
and building, 31
in build environment, 32
setting, 31
tip rev
updating to, 114
tip revision
defined, 17
described, 452
tokenization, 263
toolbar, 320
graphic user interface, 318
Web interface, 320
touch, 308
transitive closure, 285
trend charts, 406
creating, 417
saving, 426
specifying a graph, 421
specifying a legend, 425
specifying axes, 424
specifying colors, 422
specifying filters, 420
specifying text, 418
trunk, 17
described, 452
type (project member)
described, 452
U
undo changes
saved queries, 356
Undo Checkout
Windows interface command, 100
UNIX, 244, 257, 283, 294
UNIX System V, 263
Unlock
Web interface command, 103
Windows interface command, 102
unlocking
members, 101
revisions, 187
Update Member option, 91
User Guide 473

Index
Update to Head Rev
Windows interface command, 113
Update to Tip Rev
Windows interface command, 114
Update to Tip Revision
Web interface command, 113, 114
updating
to head rev, 113
to tip rev, 114
URL
Change Integrity home page, 315
user
described, 312, 455
user name
described, 452
users
defined, 34
using
different makefile, 252
extensions, 209
inference rules in Make, 281–288
keywords, 129
macros in Make, 256–265
V
VanillaRCS configuration option, 151
variant sandbox, 24
converting old-style, 28
deleting
using CLI, 158
described, 452
locking in, 26
using to build, 232
version control, 437
View
Web interface command, 87
View Log
Windows interface command, 142
View Revision
Windows interface command, 86, 184
View Working File
Windows interface command, 85
View/Edit Working File
Windows interface command, 184
viewing
archive information, 176
change packages, 442
issues, 367
member information, 108
members, 85
project information, 94
Query Results, 364
revision information, 178
revisions, 184
sandbox information, 94
saved query properties, 357
working file, 184
views
history, 58
introduction, 52–58
member, 55
project, 56–58
sandbox, 52–55
Visual Basic
see Microsoft Visual Basic
Visual C++, 197
Visual Difference window
described, 453
Visual J++, 197
W
Watcom C/C++, 247
Web interface
Change Integrity, 320
content page, 321
query toolbar, 320
status, 321
toolbar, 320
which, 244
white space in Make, 249
wildcard, 63
expansion, 62
Windows 95, 272, 298
Windows Explorer
see Microsoft Windows Explorer
Windows interface filters
all members, 44
frozen members, 45
locked by me, 45
locked members, 45
members with label, 45
members with state, 45
modified members, 44
out-of-sync members, 45
474 Source Integrity Professional Edition

subprojects, 45
using, 44
Windows NT, 272, 298
work tree
described, 453
workflow
described, 312, 455
working directory
described, 453
working file
check in, 174
cleaning up, 159, 195
comparing to member revision, 99
deleting, 170
described, 453
discarding changes, 100
editing, 184
keywords, 129
merging, 192
viewing, 184
writing a rule in Make, 248–249
User Guide 475

Index
476 Source Integrity Professional Edition