CMVC FREQUENTLY ASKED QUESTIONS: FILES, RELEASES, LEVELS, AND TRACKS Document Number TR 29.2296 Angel Rivera, Lee Perlov CMVC/TeamConnection Development IBM Software Solutions Research Triangle Park, North Carolina Copyright (C) 1997 IBM Corp. All rights reserved. ii CMVC FAQ: releases, tracks, levels ABSTRACT This technical report provides answers to frequently asked questions made by CMVC users with respect to handling files, releases, levels, and tracks. ITIRC KEYWORDS o CMVC o File o Release o Level o Track ABSTRACT iii iv CMVC FAQ: releases, tracks, levels ABOUT THE AUTHORS ANGEL RIVERA Mr. Rivera is an Advisory Software Engineer and team lead for the development of CMVC 2.3. He joined IBM in 1989 and since then has worked in the development and support of library systems. Mr. Rivera has an M.S. in Electrical Engineering from The Univer- sity of Texas at Austin, and B.S. in Electronic Systems Engi- neering from the Instituto Tecnologico y de Estudios Superiores de Monterrey, Mexico. LEE R. PERLOV Mr. Perlov is a Staff Software Engineer in the TeamConnection/CMVC development group. He started working for IBM in 1985 in Gaithersburg, Md, working in the Federal Systems Division on various projects for the United States intelligence community. He then moved to RTP to work on library development and support. Mr. Perlov received a B.S.Acc degree in Accounting from the Uni- versity of Florida in 1983. He also completed two years of grad- uate work in the Department of Computer Science at the University of Florida. ABOUT THE AUTHORS v vi CMVC FAQ: releases, tracks, levels CONTENTS ABSTRACT . . . . . . . . . . . . . . . . . . . . . . . . . III ITIRC KEYWORDS . . . . . . . . . . . . . . . . . . . . . iii ABOUT THE AUTHORS . . . . . . . . . . . . . . . . . . . . . . V Angel Rivera . . . . . . . . . . . . . . . . . . . . . . . v Lee R. Perlov . . . . . . . . . . . . . . . . . . . . . . . v 1.0 INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . 1 1.1 About this and previous technical reports . . . . . . 1 1.2 About CMVC and TeamConnection . . . . . . . . . . . . 1 1.3 Acknowledgements . . . . . . . . . . . . . . . . . . . 2 2.0 FILES . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.1 Always checkout a file in order to change it! . . . . 3 2.2 I lost my changes when I checked out the file . . . . 3 2.3 What are the differences between text and binary files? 4 2.4 File path name with forward or backward slashes . . . 6 2.5 What is the difference between File Delete and File Destroy? . . . . . . . . . . . . . . . . . . . . . . . . . 6 2.6 Why is a backup version of a file created during File Check-out? . . . . . . . . . . . . . . . . . . . . . . . . 8 2.7 What is the date for a file during extract or checkout? . . . . . . . . . . . . . . . . . . . . . . . . 10 2.8 How to query for common files and files that are not common . . . . . . . . . . . . . . . . . . . . . . . . . 10 2.9 How to change the path name for a set of files? . . 12 2.10 How to deal with error 0010-350, function open() . 12 2.11 Is it possible to modify files in an old level? . . 13 2.12 Can a common file be linked to a release with tracks and without tracks? . . . . . . . . . . . . . . . . . . . 14 2.13 Problems deleting a file . . . . . . . . . . . . . 14 2.14 Cannot use a file name that should be available after a file is renamed? . . . . . . . . . . . . . . . . . . . 15 2.15 Cannot create a link to an existing file . . . . . 16 2.16 Extra CR/LF (0d 0a) inserted at the end of file during File -create . . . . . . . . . . . . . . . . . . . 16 2.17 Cannot check in a very large file (260 MB) . . . . 17 2.18 Creating many files at once . . . . . . . . . . . . 17 2.19 Can I use wildcards to process multiple files? . . 18 2.20 Is there an easy way to break the link to many files at once? . . . . . . . . . . . . . . . . . . . . . . . . 18 2.21 Clarification on FileCheckIn and FileUndo authority actions . . . . . . . . . . . . . . . . . . . . . . . . . 19 2.22 Clarification of File -checkin with -relative . . . 19 2.23 File differences between checked in version and extracted version . . . . . . . . . . . . . . . . . . . . 20 2.24 Easy undoing of file changes when using Tracks and Levels . . . . . . . . . . . . . . . . . . . . . . . . . 20 2.25 Shadowing files to another system . . . . . . . . . 21 Contents vii 3.0 GENERAL QUESTIONS ABOUT THE RELEASE, LEVEL AND FILE -EXTRACT . . . . . . . . . . . . . . . . . . . . . . . . 23 3.1 How are the file permissions handled during an extract? . . . . . . . . . . . . . . . . . . . . . . . . 23 3.2 How to extract only the changed files? . . . . . . . 23 3.3 How to interrupt Release/Level extracts . . . . . . 24 4.0 RELEASES . . . . . . . . . . . . . . . . . . . . . . . 27 4.1 How to setup and use releases that have common files? 27 4.2 Common set of questions with linked files . . . . . 28 4.3 Release link to a specific level of another release 29 4.4 Only "active files" are linked during Release/File -link . . . . . . . . . . . . . . . . . . . . . . . . . . 29 4.5 Is it possible to protect Releases to prevent new file changes? . . . . . . . . . . . . . . . . . . . . . . . . 30 4.6 What happens to defects when linking a release into another? . . . . . . . . . . . . . . . . . . . . . . . . 31 4.7 How could I create a release from a given level? . . 31 4.8 Can we do a partial link from one release to another? 32 4.9 Is it possible to rename a release with a committed level? . . . . . . . . . . . . . . . . . . . . . . . . . 32 4.10 Creating new releases - what about active defects/tracks? . . . . . . . . . . . . . . . . . . . . . 33 5.0 LEVELS . . . . . . . . . . . . . . . . . . . . . . . . 35 5.1 Does a new level include all the changes from previous levels? . . . . . . . . . . . . . . . . . . . . . . . . . 35 5.2 Using CMVC_LEVEL_COMMIT_SHORT_CHECK to select the desired method . . . . . . . . . . . . . . . . . . . . . 36 5.3 Can I extract an old level? . . . . . . . . . . . . 36 5.4 Is it possible to rename a committed level? . . . . 37 5.5 Can we work in the same release on multiple levels at the same time? . . . . . . . . . . . . . . . . . . . . . 38 5.6 Why does Level -extract create a .gone file? . . . . 39 5.7 Two different ways for %W% string expansion in Level -extract . . . . . . . . . . . . . . . . . . . . . . . . 40 6.0 TRACKS . . . . . . . . . . . . . . . . . . . . . . . . 41 6.1 How can I move a track from integrate state back to fix state? . . . . . . . . . . . . . . . . . . . . . . . 41 6.2 Erroneous state change: Test->Verify on first Track Completion . . . . . . . . . . . . . . . . . . . . . . . 41 6.3 Is there a way to view who changed the ownership of a track? . . . . . . . . . . . . . . . . . . . . . . . . . 43 6.4 Use Track -check to view existing corequisites . . . 43 APPENDIX A. BIBLIOGRAPHY . . . . . . . . . . . . . . . . . 45 A.1 How to get electronic copies of manuals and technical reports . . . . . . . . . . . . . . . . . . . . . . . . . 45 A.1.1 IBM Intranet . . . . . . . . . . . . . . . . . . 45 A.1.2 Internet . . . . . . . . . . . . . . . . . . . . 46 APPENDIX B. COPYRIGHTS, TRADEMARKS AND SERVICE MARKS . . . 49 viii CMVC FAQ: releases, tracks, levels 1.0 INTRODUCTION This technical report provides answers to frequently asked questions made by CMVC users with respect to handling files, releases, levels, and tracks. This technical report is organized as follows: 1. Files 2. General questions about the Release, Level and File -extract 3. Releases 4. Levels 5. Tracks 1.1 ABOUT THIS AND PREVIOUS TECHNICAL REPORTS This document, as well as other recently released technical reports related to CMVC, contains some information that was pre- viously available in other "unofficial" documents. We have endeavored to better organize the information and improve its readability so that you will find it more useful. This technical report is a companion to the document /USR/LPP/CMVC/DOC/README.FIX.RELEASE.EXTRACT.PROBLEMS. 1.2 ABOUT CMVC AND TEAMCONNECTION TeamConnection is the successor product to CMVC. It has greatly expanded capabilities and is built upon an object model. While this and related technical reports discuss CMVC issues, we will periodically refer to new solutions provided in TeamConnection. Where a CMVC technical report covers a topic that might be of importance to TeamConnection users and if the TeamConnection doc- umentation does not already cover the topic, a TeamConnection technical report is or will be available. Introduction 1 1.3 ACKNOWLEDGEMENTS Many of the questions and answers that are compiled in this tech- nical report were obtained from the CMVC forum in the IBMPC con- ferencing disk, and from the CMVC6000 forum in the IBMUNIX conferencing disk. We want to thank the main participants in these electronic forums for their support! Also, we want to thank Dodde Stark for editing this technical report. 2 CMVC FAQ: releases, tracks, levels 2.0 FILES 2.1 ALWAYS CHECKOUT A FILE IN ORDER TO CHANGE IT! QUESTION: I change an extracted copy of file.c, lock the file and check it in as version 1.3. The next day someone on my team complains that their changes are lost. ANSWER: Whenever you change a file without checking it out first, you take the risk of not picking up all of the changes that exist in the file as it is currently stored in CMVC. In this case, the other user checked in version 1.2 with their changes between the time the first user extracted the file and checked in their changes. You can verify this by selecting the file from a CMVC File window and then choose the option "Show Differences" and specify the file changes 1.2 and 1.3; this can be done only from OS/2 or UNIX, because there is no support in the CMVC GUI for Windows to see the differences. 2.2 I LOST MY CHANGES WHEN I CHECKED OUT THE FILE QUESTION: I was editing an extracted copy of file.c, then checked it out and checked it in. The next time I extracted the file, my changes were gone. ANSWER: This is a common problem for new users. Many users have the bad habit of changing the attribute of an extracted file in the work- station to read-write (from read-only), edit the file, then do a File Check-out (which overrides the previous version) and then do a File Check-in. The result is that the file they modified is renamed and the current version of the file in CMVC is extracted in place of the modified file. If the user then checks the file in, it is the same version that was just checked out. Files 3 One suggestion to avoid the above problem is to activate the Verbose/Confirmation choice, which will always return a message when the file is checked-in, and if the file is a text file, then it will show the number of lines that were changed. Then, when you checkin a file or a set of files, pay attention to these lines that indicate if the file was indeed changed. In some cases, when dealing with many files, you could sometimes catch a mistake in which you are checkin in a file that has not changed. 2.3 WHAT ARE THE DIFFERENCES BETWEEN TEXT AND BINARY FILES? QUESTION: What are the differences between text and binary files? ANSWER: o In SCCS, text files are stored in a forward delta fashion. That means version 1.1 of a file is complete and unmodified, whereas all subsequent versions are deltas (that is, just the changes), computed from the previous version. Thus, in order to get version 1.5, the deltas 1.2, 1.3, 1.4 and 1.5 must be applied to 1.1 in that sequence. By contrast, when using SCCS, CMVC stores binary files are stored using reverse deltas. That means that the latest version (such as 1.5) contains the complete file and the pre- vious versions are deltas. Thus, when getting version 1.5, NO deltas are applied. However, to get version 1.4, then a delta 1.4 is applied to the complete version 1.5. o Keyword expansion is done only with text files and not with binary files. o CR/LF (Carriage Return and Line Feed) translation is done only with text files, not binary files. NOTES: 1. While many versions of NFS provides a CR/LF conversion option, this is not used by CMVC. The conversion is done by the CMVC server daemon during extract. 2. CMVC provides an option on Intel-based clients to perform the CR/LF conversion during file, release and level -extract actions. 3. CMVC automatically turns CR/LF conversion on whenever it determines that the target file system is OS/2, DOS or Windows. In other words, if you specify your destination 4 CMVC FAQ: releases, tracks, levels directory as "c:\work", CMVC will always perform CR/LF conversion for text files. 4. If you NFS mount "c:\work" to a Unix system as "/tmp/work" and specify your destination directory as "/tmp/work", you will need to use the -crlf option for the conversion to take place. o What happens with text files, when created from an OS/2 client? The CMVC server converts CR/LF to newline as it saves the file. This allows for the file to be extracted in readable fashion on UNIX systems. The CR/LF's are replaced during extraction. NOTE: Text files conform to the above rules in all cases except where the server sees a non-ascii character and changes the file type to binary. o What happens with binary files? There are a lot of details associated with binary files: - Binary files are not altered in any way (from a user point of view). - Binary files (as well as text files that contain any lines of more than 512 characters) are versioned outside of SCCS: - Each version of the file is contained in a separate file on the server as either a full copy or a forward-delta file. - The determination of whether the file is stored as a full copy or a delta is based on the value of the CMVC_BINARY_THRESHOLD variable in the family account. If a delta file becomes bigger than the CMVC_BINARY_THRESHOLD, then the server stops comparing the new version to the previous version and saves a full source copy. The default value for CMVC_BINARY_THRESHOLD is 15000 bytes. NOTE: There is much more detail on the internal workings of the CMVC version control system in the Technical Report: CMVC FRE- QUENTLY ASKED QUESTIONS: VERSION CONTROL AND DATABASE SYNCHRONI- ZATION ISSUES Files 5 2.4 FILE PATH NAME WITH FORWARD OR BACKWARD SLASHES QUESTION: How does CMVC handle the file path names with forward or backward slashes? ANSWER: The CMVC client and server will take into account the usage of the slashes, both backward (for DOS, OS/2 and Windows) and forward (for UNIX). The file will be treated according to the target platform. That is, you can extract the file tmp\file.dos into a UNIX directory and the end result will be a file in tmp/file.dos. The reverse is also true, you can extract the file tmp/file.aix into a DOS directory and the end result will be a file in tmp\file.aix. You can use the GUI to specify the relative directory to store the code. In the UNIX GUI it is called "Set Directory", in the OS/2 and Windows GUI it is called "Relative directory". When using the line commands the CMVC_TOP environment variable can be used. For more details on this topic, please see the technical report "CMVC frequently asked questions: handling file, release and level extract problems". An example of the relative directory is shown next: if the user specifies the relative directory to C:\pages, and the file tmp\file.dos is extracted, then the file will be located in C:\pages\tmp\file.dos. Another point to consider is the difference between "path name" and "base name" when doing queries. The base name is the file name with NO directory information, such as file.dos, while the path name is the complete file name with the directory informa- tion, such as tmp\file.dos. 2.5 WHAT IS THE DIFFERENCE BETWEEN FILE DELETE AND FILE DESTROY? QUESTION: What is the difference between File Delete and File Destroy? What happens to deleted files when I do a Release -link? How do I reclaim space in the family account by removing destroyed files? ANSWER: 1. Question: 6 CMVC FAQ: releases, tracks, levels If I "delete" a file, and then do an extract of the current version of the release that it is in, does the "deleted" file get extracted? Answer: This assumes that the level where the file is deleted has not been committed yet: o The "deleted" file is not extracted when doing a release extract of the current release or when doing a level extract of the uncommitted level. o The "deleted" file is extracted when doing a release extract or level extract of the committed files. NOTE: In the case of a level -extract, CMVC will also create a ".gone" file ("CMVC.GON" for Windows and OS/2). This file will contain a list of files that were deleted or renamed. For more details on .gone, see 5.6, "Why does Level -extract create a .gone file?" on page 39. 2. Question: What happens to deleted files when I do a Release -link? Answer: Deleted files are not included in a link and will not be part of the new release. See 4.4, "Only "active files" are linked during Release/File -link" on page 29 for more details. 3. Question: If I "destroy" a file, does it only destroy it at the level that I destroy it at, or does it destroy it at all previous levels as well? Answer: You destroy the file only in the current release. This has no impact on other releases. Actually, a destroyed file is rarely deleted from the CMVC. The only times that CMVC will remove a file from the server are: o If the file exists in only one release (that is, it is not common to any other releases). o When cmvcarchive is run with the delete option. Destroyed files are not only not extracted, but do not appear in "gone" files. Files 7 4. Question: How do I reclaim space in the family account by removing destroyed files? Answer: This is a complicated task that can only be performed by the family administrator. A recommended process is provided in the Technical Report: CMVC FREQUENTLY ASKED QUESTIONS: VERSION CONTROL AND DATABASE SYNCHRONIZATION ISSUES 2.6 WHY IS A BACKUP VERSION OF A FILE CREATED DURING FILE CHECK-OUT? QUESTION: After I do File checkout, the file name is slightly changed and the file still remains in my work directory in the workstation. In addition, its attributes are changed from read-write to read- only. ANSWER: The CMVC File line command for all our clients (UNIX, OS/2 and Windows) has the following behavior during file check-in, check-out and extract: 1. The file attributes change to read-only after create or checkin. ;p. If a file, such as file1.c, is created via CMVC, then the contents of the file is copied into CMVC and the file mode in the user's workstation is changed to Read- Only (RO for short). One reason for keeping the file in the workstation is that you may need to use the file in a compilation (for example). The attribute is changed to RO to prevent accidental modifi- cations to the file. In order to modify the file, the user needs to check out the file from CMVC. 2. The file attributes change to read-write after checkout. After the file is created or checked in, the file attributes are RO; thus, if the user wants to modify the file, then the file needs to be checked out; this action will do the fol- lowing: a. The file will be extracted from CMVC. Because CMVC cannot assume that you have already the latest version of 8 CMVC FAQ: releases, tracks, levels the file in your wosktation, The CMVC client will extract the file from the CMVC family by using File -extract (under the covers): 1) If there is a backup-file, then it is deleted. Please see the next item for more explanation on backup-files. 2) In case that there is an old copy of the file in the workstation, then before extracting the file, the CMVC client renames the existing file in the work- station as a backup-file: o In UNIX the file name is changed to .file1.c (which makes the file a hidden file when doing a normal "ls"; you need to do "ls -a" in order to see the hidden files). o In OS/2 and Windows the file name is changed to file1.$c. The creation of a backup file allows the user to recover any file changes that were not checked-in in CMVC. 3) The file is actually extracted from CMVC using the correct file name. b. CMVC changes the file permissions to Read-Write, in that way you can modify the file. c. CMVC obtains a lock for that file, in that way no other CMVC users can modify that file. Although this is the default behavior in CMVC and most of our customers are satisfied with this behavior, we have received feedback from a few customers requesting more customization in this matter. For CMVC users, here are some suggestions: o Delete the file from the workstation after a CMVC file create and file check-in. o Do not make a backup file when doing a file extract. o Customize the names of the backup files. TEAMCONNECTION NOTE: TeamConnection has new options in the GUI and line commands to control more extract behaviors. Files 9 2.7 WHAT IS THE DATE FOR A FILE DURING EXTRACT OR CHECKOUT? QUESTION: What is the date for a file during extract or checkout? ANSWER: When a file is extracted from a CMVC client, the date/time stamp used with the extracted file in the local directory or file system is the date/time stamp when the extraction was done. TEAMCONNECTION NOTES: 1. This behavior has been changed in TeamConnection. There are no plans to change it in CMVC. 2. In TeamConnection, the date/time stamp of the actual file on the workstation is read during the create and checkin and it is restored on checkout and extract. 3. This behavior is different from CMVC, and should make build processes easier to implement. 4. Finally, TeamConnection provides a build facility that makes use of the new timestamp paradigm, and even provides a "Part -touch" action to update that timestamp as one means of forcing a build. 2.8 HOW TO QUERY FOR COMMON FILES AND FILES THAT ARE NOT COMMON QUESTION: Is there a way to do the following queries related to common files? 1. List all pathnames that are common to releaseA and releaseB. 2. List all pathnames that are in releaseA but not in releaseB. ANSWER: Look at the following CMVC samples (written in Korn shell): o showAllCommonFiles It shows all the common files for a given release; it does not show the releases to which each file is linked to. o showCommonFiles It shows all the common files and releases for a given file in a release. 10 CMVC FAQ: releases, tracks, levels o commonFileCheckin It does a file checkin for a common file to other releases. If you want to know if a specific file is common, double-click on the file name in the CMVC - Files window to show the information about the file. However, the above method is not practical for many files. If an administrator or a project leader wants to know all the files that are still common, then the following queries can be used: NOTE: These queries worked with Oracle, but they fail in DB2 giving error SQL129 which indicates that more than 15 tables are involved in a select. Thus, it is necessary to avoid using the FileView view and instead use the File table or related tables. 1. List all pathnames that are common to releaseA and releaseB. Report -view fileview -where "\ dropdate is null and \ releaseName = 'release1' and \ sourceId in\ (select sourceId from fileview where \ releaseName = 'release2') and \ nuVersionSID in \ (select nuVersionSID from fileview where \ releaseName = 'release2')" 2. List all pathnames that are in releaseA but not in releaseB. Report -view fileview -where "\ dropdate is null and \ releaseName = 'release1' and \ nuPathId not in\ (select nuPathId from fileview where \ releaseName = 'release2')" Another query: Report -view fileview -r -where "\ releasename='$CMVC_RELEASE' and\ nuDropDate is null and \ not exists \ (select id from files where \ sourceid=fileview.sourceid and \ nuDropDate is null and \ nuVersionId=fileview.nuVersionId and \ id != fileview.id)" Files 11 2.9 HOW TO CHANGE THE PATH NAME FOR A SET OF FILES? QUESTION: I created several files without path names and now I want to append a directory name to all these files. Is it possible to do it easily instead of modifying the files one by one? ANSWER: The bad news is that you do have to modify all the files one by one, the good news is that this can be quickly done via the command line. 1. Construct a directory which has all the files which you wish to rename. 2. From within that directory issue: for %i in (*) do file -rename %i -path new\path\info\%i Add -defect, -release, or -family, -common, etc. as appro- priate. 2.10 HOW TO DEAL WITH ERROR 0010-350, FUNCTION OPEN() QUESTION: When using the CMVC client for OS/2, a user is doing a "File -checkin" is getting the following error: 0010-350 The error (The file or directory specified is read-only.) occurred when the CMVC server software processed function open() on the file with path name tmpVCJDE.C2T. Check that the path name, the file permissions, and the directory permissions are correct. If problems persist, contact the system administrator or the family administrator. 0010-777 The CMVC client was attempting to transmit the file: d:\user\DIS\os2\dis.mak to the server and failed. 0010-352 An error occurred when the CMVC server software tried to open the file, tmpVCJDE.C2T, on the CMVC client. Check that the access permission of the file allow the CMVC server software to read it. What might be the problem? Is the tmp file being written to the server or the client workstation? ANSWER: Here are some things to check: 12 CMVC FAQ: releases, tracks, levels o Use "attrib" to make sure that the file that you want to use is not a system or hidden file. Using attrib always seems easier than remembering the syntax for showing hidden and system files with "dir /a:h", which only displays hidden files. o Use "attrib" to make sure the file, tmpVCJDE.C2T, does not already exist in either of the above directories. o Check if you have enough disk space for 2 copies of the file on the D: drive. o Check if you have enough disk space for 1 copy of the file on the disk specified by the %TMP% variable. o If either of the above directories are on a FAT file system, make sure you have less than 255 files in that directory. o If this file is binary (that is, non-ascii characters, long lines or you selected binary), make sure you have 3 times the size of the file in /tmp on the server. 2.11 IS IT POSSIBLE TO MODIFY FILES IN AN OLD LEVEL? QUESTION: One of my users committed a level '1' against release 'x', and other levels were committed against the same release later on. At this point the user wants to modify one of the files at level '1'. Is this possible? If I link release 'x' to another release 'y', I would get all committed files after level '1'. Is there a way that I can create a release and link it to all the files that were committed at level '1'. ANSWER: o Once a level is committed, you cannot "undo" the file changes associated with that level. If the level is not yet committed, then you can remove the track from the level, change the state of the track to "fix", then activate the fix records and then do file -undo. o You could use the new sample "fileVersionsInLevel" to find out the files and their file changes that are in one level, then do a File link for those files from release-A to the new release-B. Files 13 2.12 CAN A COMMON FILE BE LINKED TO A RELEASE WITH TRACKS AND WITHOUT TRACKS? QUESTION: Can I have a file that is common in 2 releases if one release uses the no-track process and the other uses track-level? What would you expect to happen if I check the file out, change it and check it in again? ANSWER: The CMVC Commands Reference V2.2, Chapter 10 "File", page 44, 2nd paragraph from the bottom says: "You can define a common file for releases whose process does not include the track subprocesses; however, commonality is broken when a change is made to the file." If I have file.c that is common to rel-1 (no tracks) and rel-2 (with tracks) then changing that file, in either rel-1 or rel-2, will break the commonality. 2.13 PROBLEMS DELETING A FILE QUESTION: We have a defect in WORKING state with a track in FIX state, but when we try to delete a file we get the message: 0010-310 File LXTASTAT.MAK associated with release vsetrel1 cannot be deleted. The file has changes pending that must first be committed. ANSWER: How you approach this situation would depend on whether the file has been committed or created in this Release. If it has been committed, you can do the following: o EITHER complete the Track you now have, add the Track to a Level, commit the Level and then create another Defect and Track in which you can delete the file. o OR you can undo the changes to this file, go back to a com- mitted version of the file, and then delete the file in this Track/Level. 14 CMVC FAQ: releases, tracks, levels If the file was created in this release (but never committed), just undo all versions of the file right back to the beginning and you will eventually undo the file creation. 2.14 CANNOT USE A FILE NAME THAT SHOULD BE AVAILABLE AFTER A FILE IS RENAMED? QUESTION: From the "Files" window I have renamed a file, using Modify-PathName as follows: Path Name Base Name --------------- ------------- Original File: myfiles/file1.c file1.c Renamed File: myfiles/file1.c file1.c.old Now I want to create a new file with the name "file1.c" which should be now available, but when I try to do it, I receive the following error message: 0010-047 You cannot create file myfiles/file1.c. A file with this path is already associated with release MyRelease. Specify a different path. 1. Why does the Path Name not get changed when I do a Files-Modify-PathName, but the base name does get changed? 2. Is there a way for me create a file with the same name as a pre-existing file? ANSWER: To reuse the original path and name of the file, you must commit the file changes. CMVC will not let you use that original name because until the file is actually committed, it is possible for a file undo to be performed to the original file which would result in CMVC having 2 files with the same path and name, and having 2 different source ids in the database. In order to avoid this situation, CMVC does not allow you to change the path name in this situation. If this file have never been committed, you could do file undo's on it until the file is completely removed from CMVC. Then you could create the original file with the new path and base name and then create the 2nd file using the original's path and base name. Files 15 2.15 CANNOT CREATE A LINK TO AN EXISTING FILE QUESTION: I have 2 different files with the same name (file1.c) in 2 releases. However, when I try to link file1.c from one release into the other release, I get an error message saying that this cannot be done. ANSWER: If you have 2 different files with the same name in 2 releases, such as file1.c in release-1 and file1.c in release-2, then you cannot link file1.c from release-1 to file1.c in release-2. However, you can do any of the following: o Delete file-1 in release-2, and then you can do the link from release-1. o Rename file-1 in release-2, and then you can do the link from release-1: File -rename file1.c -path file2.c -release release-2 The file file-1 in release-2 is renamed to file2.c, and thus, the file1.c name can be used now as the target for a link. NOTE: In all cases, the first change (delete or rename) must be committed before CMVC will allow you to do the second change (link). 2.16 EXTRA CR/LF (0D 0A) INSERTED AT THE END OF FILE DURING FILE -CREATE QUESTION: On a File -create, the control characters Carriage Return and Line Feed (CR/LF pair, for short), represented by hexadecimal OD and OA, were inserted at the end of file (the last characters of the original file were hex 61 61. Is this normal? Is there an option to disable this feature? ANSWER: CMVC uses SCCS as the underlying versioning system. Because there are some restrictions with SCCS, CMVC has to ensure that the text files comply with these restrictions. Under certain circumstances CMVC has to add the control characters Carriage Return and Line Feed (CR/LF) at the end of the file or change the file from type "text" to "binary". 16 CMVC FAQ: releases, tracks, levels If you do not want CMVC to touch the contents of your files, then you will have to specify "binary". However, CMVC is NOT able to provide "show differences" for binary files. For more details on the version control system used by CMVC, see the technical report CMVC FREQUENTLY ASKED QUESTIONS: VERSION CONTROL AND DATABASE SYNCHRONIZATION ISSUES 2.17 CANNOT CHECK IN A VERY LARGE FILE (260 MB) QUESTION: How much space is needed to checkin a very large file (such as having a size of 260 MB)? ANSWER: So you should have space about 3.2 times the size of the file in /tmp. Once the file has been received into /tmp, the File command itself checks for space. Since this is probably a binary file, it says it wants the size of the input file plus the size of the previous version plus 10% also in /tmp. Bear in mind that this is for one single file. If you attempt to checkin 2 such files at once, then you will need space in /tmp to accommodate both of them! NOTE: You only need about 2 times the size of the file in /tmp if the file type is "binary" and the family account has the CMVC_BINARY_THRESHOLD variable set to 0 (set CMVC_BINARY_THRESHOLD=0). 2.18 CREATING MANY FILES AT ONCE QUESTION: How could I create many files at once? ANSWER: From the CMVC GUI for OS/2 and Windows: select Windows=>Settings, select environment page, enter the name of your "top" directory in the Working Directory entry field. Press Apply. Files 17 From the CMVC GUI for UNIX: select Options and specify the directory. Then from the Task Window, select the Files window, then Files=>Create. Press CHOICES. Select files from the list. Press OK. From the command line, wildcards are supports. For example: File -create * -component c -release r WARNING for OS/2 and Windows: CMVC will use the file names as provided by the underlying system calls, which provide the names in UPPERCASE. 2.19 CAN I USE WILDCARDS TO PROCESS MULTIPLE FILES? QUESTION: Is it possible to specify a wildcard to checkout more than one file from the line command?. ANSWER: The File line command actions (create, checkin, checkout and lock) support wildcards; however it is important to note these wildcards are evaluated based upon the current contents of the target directory, not the contents in CMVC. 2.20 IS THERE AN EASY WAY TO BREAK THE LINK TO MANY FILES AT ONCE? QUESTION: Is there an easy way to break the link to many files at once? Is there a "release break-link" concept? Or do I have to break the link for each file? ANSWER: The only way to break the link of all the files is to check all files out (for 1 release) and check them all in again specifying to break the link (using the -force flag from the command line). If you want to control the file changes to the old release, then you could prevent unwanted updates by activating the approval process for the old release. 18 CMVC FAQ: releases, tracks, levels NOTES: 1. Once links are broken, each time a file is updated in any one release a new version is created. As a result, there will be more versions of the file, thereby using more disk space. 2. Once links are broken, it is much more difficult to determine when you have made the same change to the same file in mul- tiple releases. This information will be in the defect and track; however, since the files are no longer common the version numbers will be different. 2.21 CLARIFICATION ON FILECHECKIN AND FILEUNDO AUTHORITY ACTIONS QUESTION: Clarification on FileCheckIn and FileUndo authority actions ANSWER: o The FileCheckIn authority gives a person the power to check in a file EVEN if the file is locked by someone else. o The FileUndo action for a specific change can be done by the user who did that change, even if this action is not explic- itly given to that user. 2.22 CLARIFICATION OF FILE -CHECKIN WITH -RELATIVE QUESTION: Clarification of File -checkin with -relative ANSWER: File -checkin with "-relative" appends -relative "path" with path/basename specified. If "path" is not fully specified, the checkin will NOT look in the same place as a checkout using the same relative path. NOTE: You might also want to look up the definition of "-top" and use of the CMVC_TOP variable in the "CMVC User's Guide" or "CMVC Commands Reference" or in the technical report: "CMVC fre- quently asked questions: handling file, release and level extract problems" Files 19 2.23 FILE DIFFERENCES BETWEEN CHECKED IN VERSION AND EXTRACTED VERSION QUESTION: In the following situations, we have seen differences between the version of a file that was checked in and the version that is just extracted: o If the file contains a text line without CR/LF, then CMVC is adding a CR/LF to this line. o If the file contains an empty line without CR/LF, then CMVC removes the line. ANSWER: It sounds as if your customer needs to set the CRLF to 'on' in the options settings window. It is important to know that carriage returns are not needed on the UNIX server and when you check the files in and out you are constantly removing carriage returns from and adding them back into the file. The default of 'on' is the best option because then the system does it for you. Also if you want a blank line in the file you need to end it with a carriage return or the system does not recognize it. Any time you extract directly to an OS/2 or Windows client the CR/LF flag will be set "on" in the CMVC server (it recognizes the difference between a Unix and Intel path). 2.24 EASY UNDOING OF FILE CHANGES WHEN USING TRACKS AND LEVELS QUESTION: Is there an easy way to undo file changes when using Tracks and Levels? ANSWER: It is highly recommended to use the tracks/levels because they will facilitate your build activities. Furthermore, you can always use the action File -undo to undo the latest uncommitted changes to a file. If the file was created in a track that has not been committed, you can continue applying the undo action repeatedly until the file is deleted. 20 CMVC FAQ: releases, tracks, levels This approach is better than the explicit action File -delete (which keeps the file, but adds a value in the file dropDate field). 2.25 SHADOWING FILES TO ANOTHER SYSTEM QUESTION: I am trying to find out how to shadow the file changes made in CMVC to a local disk (such as when using OS/2). In this way, the developers can do a build without having to extract the source code and then rebuild everything. ANSWER: Some alternatives that CMVC users have proposed are: o Whenever a file is changed a user exit (usually exitID 2) is kicked off that does an RSH to a server and replaces the old file. NOTE: This is problematic for OS/2, since OS/2 only supports one RSH session at a time. Therefore, if more than one file is changed at the same time the second and subsequent RSHes will fail, causing the shadow area to be out of sync with what is in CMVC. However, if you have a "Unix-like" utility package, you can schedule an "at" job to run later that can invoke RSH and perform retry logic until the command is suc- cessful. o Instead of using rsh, use rexec. NOTE: This method also was not considered reliable on OS/2. Furthermore, when it was tried in conjunction with an NFS mount problems still occurred. o Some users wait to perform the shadow when a level is com- mitted, again using a user exit. o Finally, it is possible to schedule a "cron" job to check for changes in a release and to perform the necessary file extracts to update the shadow at regular intervals (for example, at midnight). Such a process checks the lastUpdate timestamp (either in the FileView or Changes table). File extracts of only the changed files are generally preferred so that the timestamp in the shadow most closely reflect the actual time of change. Files 21 22 CMVC FAQ: releases, tracks, levels 3.0 GENERAL QUESTIONS ABOUT THE RELEASE, LEVEL AND FILE -EXTRACT For problems related to Release -extract or Level -extract, see the technical report: CMVC FREQUENTLY ASKED QUESTIONS: HANDLING FILE, RELEASE AND LEVEL EXTRACT PROBLEMS. 3.1 HOW ARE THE FILE PERMISSIONS HANDLED DURING AN EXTRACT? QUESTION: How are the file permissions handled during an extract? ANSWER: The fmode field in FileView contains the file mode information about how to set the permissions assumed by the file on extract. For File extracts, the file mode assigned to the file minus the write permission will be assumed. For Level/Release extracts, where a fmask is given, the fmask will override the file mode assigned to the file. 3.2 HOW TO EXTRACT ONLY THE CHANGED FILES? QUESTION: How do you extract ONLY the changed files? How do you know which are files? ANSWER: If you are NOT using levels, then CMVC does not provide a func- tion that will allow you to have a baseline to determine which files have changed. If you are using levels, then there are several ways to look at the changed files: o You can do a delta level extract (committed or uncommitted) and you will get ALL the file changes done in that level. This means that if you do not include tracks with file changes into a level, then you cannot get those file changes simply by using level extract. General questions about the Release, Level and File -extract 23 o You can get all the file changes since the last level commit, regardless if the tracks are level members by using the fol- lowing procedure: - List all the files for a release, showing the most recent changes first and not showing the deleted files; for example, the following query can be used: releaseName in ('rel') and nuDropDate is null order by lastUpdate DESC - Select by hand all the files that are shown that have different versions in the fields "Current" and "Com- mitted"; by using the above query these files will be shown at the top of the window. Then do file extract. 3.3 HOW TO INTERRUPT RELEASE/LEVEL EXTRACTS QUESTION: If I interrupt a Report or a Level -extract command by using CTRL-C in the client, the command issued on the client returns, but the process on the server that is performing the extract con- tinues. This has to run until completion. One problem here is that if I start extracting the wrong level, and the file system is only big enough for one 'build' at a time, I have to wait before cor- recting. ANSWER: You are not affecting the server when you interrupt the line command at the client by using CTRL-C. To terminate the command on the server do the following: 1. Run the monitor from the family account to determine the process id (PID) of the daemon running the extract (the value is in column 2). 2. Execute the following to recycle the CMVC daemon, freeing it up so that it can process other commands: kill -1 Such as: kill -1 12345 It is often useful to provide the ability for a non-root user to perform selected priviledged commands. The tool "backdoor" pro- vides a simple architecture for giving a finite list of users 24 CMVC FAQ: releases, tracks, levels such access; furthermore, it gives them a small degree of freedom on the parameters for these commands. It has been called to our attention that there are now products designed for this purpose, including IBM's Tivoli. For more details on this tool see the readme file and the source code for "backdoor" available from our FTP sites. General questions about the Release, Level and File -extract 25 26 CMVC FAQ: releases, tracks, levels 4.0 RELEASES For problems related to Release -extract or Level -extract, see the technical report: CMVC FREQUENTLY ASKED QUESTIONS: HANDLING FILE, RELEASE AND LEVEL EXTRACT PROBLEMS. 4.1 HOW TO SETUP AND USE RELEASES THAT HAVE COMMON FILES? QUESTION: Now that I have one release done, I need to link it to another new release. However, I want to be able to maintain the common- ality of the files between these releases (as much as feasible). How could I do that? ANSWER: After performing a Release -link, you can continue doing mainte- nance that includes both releases. If you have not yet created the new release, you can perform the following steps: 1. Create the new release (such as release-2) and create a new level for that release (such as level-1-rel-2). 2. Create a feature and a subsequent track for release-2 to do the link from release-1 to release-2. 3. Commit the level that you want to have as a baseline for the release-1. 4. Link the release-1 to release-2 and specify the track. After this step, both releases will have the same amount of files and file versions. 5. (Optional) Now you can cleanup the new release and use File Undo to get rid of obsolete/deleted files by using the track. RESIST THE TEMPTATION and do not do any changes to the files at this time. The important point is that by having this committed first level in release-2, you have a reliable baseline with respect to release-1. 6. Then put the track in the level for the new release. 7. Commit and complete the level. Releases 27 8. Now you can make changes to the files in both releases. If you want to keep the files common between these releases, then you will need to open 2 tracks for each defect: one for release-1 and another for release-2. Also, you can break the link of a file in order to ensure that the changes will be reflected in only one release and not in the other. NOTE: Many new users make the mistake of creating new releases and performing Release -link when they only need to create a new level. If you do not plan to make unique changes in the old release, just add a new level to the current release and save yourself the extra work. 4.2 COMMON SET OF QUESTIONS WITH LINKED FILES QUESTION: 1. I am planning to link all the files from one release to another. In this way, changes in R2 will automatically prop- agate themselves into R1 as long as the files are linked between R1 and R2. Is this correct? 2. Can I tell that the file I am checking out is linked between R1 and R2? If so, how? 3. Once I break the link upon checking in a file, the changes now ONLY go into the release specified for the track, correct? ANSWER: 1. Yes, but you have to be careful not to break the links between the releases for each file. Also, you will need to create 2 tracks for each defect/feature, one track for R1 and another for R2, and when you are doing checkin on a file, you will need to specify both releases. NOTE: CMVC warns you when you forget. 2. Select the file and perform the action to see the information on that file. In the output, there is a section that shows the commonality of the file. 3. When breaking the link (or when the link is already broken) you need to specify only the track and the release that will get the file change. 28 CMVC FAQ: releases, tracks, levels 4.3 RELEASE LINK TO A SPECIFIC LEVEL OF ANOTHER RELEASE QUESTION: The CMVC release link command will not let me select a specific level of another release, instead it uses either the uncommitted version or the latest committed version of the file changes; thus, I cannot select another level. ANSWER: In the directory structure of the CMVC family account there exist level map files that contain the following information about all committed release levels: filename database_version_id database_file_id change_type The location of these files is: ${FAMILY_HOME}/maps/${CMVC_RELEASE}/${LEVEL_NAME} You can take advantage of the fact that a CMVC Release Link is really under the covers a CMVC File Link for each file involved. Thus, you need to write a script that will convert the database_version_id to a real SCCS SID and then run the appro- priate File links. For example. cat ${FAMILY_HOME}/maps/${CMVC_RELEASE}/${LEVEL_NAME} | while read filename database_version_id junk do # Convert database_version_id to SID via SQL query using # the family versions table File -link ${filename} -to ${new_release} -version ${SID} \ -release ${old_release} done There is more documentation on map files and how they are used in the technical report CMVC FREQUENTLY ASKED QUESTIONS: HANDLING FILE, RELEASE AND LEVEL EXTRACT PROBLEMS. 4.4 ONLY "ACTIVE FILES" ARE LINKED DURING RELEASE/FILE -LINK QUESTION: What are "active files" and why are they the only ones linked during a Release/File -link? ANSWER: From the point of view of linking a file from one release to another, the file must be an "active file". Releases 29 This means that the file to be linked must exist, must not be deleted, must not be checked out, and should not have any pending changes (such as renaming of the file). If these conditions are not met, then the error 0010-309 will be shown. 0010-309 File %1$s associated with release %2$s cannot be linked to release %3$s. The destination file has changes pending that must first be committed. To avoid this error message it is recommended that you do the Release link (which invokes individual File links) from a com- mitted level, because it might be possible that some of the above conditions may be present in an uncommitted level. 4.5 IS IT POSSIBLE TO PROTECT RELEASES TO PREVENT NEW FILE CHANGES? QUESTION: Is it possible to protect Releases to prevent new file changes? I want to lock a release after it is created so that no one can checkout or perform any actions on that release (except for the family superuser or root). ANSWER: There are only three ways to "protect" a specific release against new file changes: 1. The easy and recommended way: o You can add the Approval subprocess for the release process. Then until somebody approves the approval records for tracks, there is no way for users to check in changes (not even for the superusers or root). o For existing tracks with no file changes, delete those tracks from the release. o For existing tracks with file changes, it is up to you to decide to incorporate those changes, or undo them and delete the tracks from the release. NOTE: The drawbacks to this approach are that users will create tracks that someone will need to cancel later; also, 30 CMVC FAQ: releases, tracks, levels users will need to find someone to authorize a track that really should not be there. Therefore, carefully select who has approval authority. 2. The harder, but more comprehensive way: Remove all appropriate file authorities (for example, FileCheckOut) from all users for each component that owns a file effected by the release. NOTE: This has the significant drawback of impacting ALL releases that include files in the effected components. 3. A compromise: Use a user exit to prevent accesses as you see fit. 4.6 WHAT HAPPENS TO DEFECTS WHEN LINKING A RELEASE INTO ANOTHER? QUESTION: I have release-1 and I want to create release-2, and link all the files from release-1 to release-2. What happens to the defects and features from release-1 when linked to release-2? How are they linked? ANSWER: The defects/features are opened against components, not against the releases. Although there is an optional field to specify the release, this field is NOT used to associate a defect with a release. Thus, when you link release-1 to a new release-2 you link only the files, and not the defects. It is up to you to assign the defects to the new release and to open tracks to the new release. Of course, you can create a user exit to do this work for you. 4.7 HOW COULD I CREATE A RELEASE FROM A GIVEN LEVEL? QUESTION: How could I create a release from a given level? ANSWER: o If you have access to the CMVC family account, you can get the map files associated with the levels. Each time a level is committed, CMVC creates a map file. For more information, Releases 31 see 4.3, "Release link to a specific level of another release" on page 29. o You can always obtain the files from a given level by using: Level -extract level-X -full Then create a maintenance release for this level. When a change is required, create or link the appropriate file(s) to this maintenance release. 4.8 CAN WE DO A PARTIAL LINK FROM ONE RELEASE TO ANOTHER? QUESTION: I have 2 groups of users using one release (release-1). One group is ready to link to a new release (release-2), but the other group is not ready yet. Can we do a partial link from release-1 to release-2? Can the second group link at a later time? ANSWER: The Release -link operates on all files within a release. However, Release -link actually performs a series of File -link operations under the covers. Thus, if group A is ready to link, then find out which files from release-1 are used by group A and then do a File Link for each of these files; you can repeat this step when group B is ready. The components used by different groups working within a release often differ, this may help make selection of files easier. 4.9 IS IT POSSIBLE TO RENAME A RELEASE WITH A COMMITTED LEVEL? QUESTION: Is it possible to rename a release if a level of that release has been committed? ANSWER: You can rename a release to a unique name, regardless of the status of associated levels. 32 CMVC FAQ: releases, tracks, levels 4.10 CREATING NEW RELEASES - WHAT ABOUT ACTIVE DEFECTS/TRACKS? QUESTION: We need to do a release cutoff and start a new release containing only committed files from the old release. In addition, we have several open defects/features (and the tracks that go along with them) that are still open and being actively worked in the old release. We want to startup the new release, and we would like to 'move' the open defects, features, and tracks from the old release to the new release. ANSWER: One method suggested by CMVC users is shown below: 1. At least a week before the cutoff, create the new release, and turn on the approval subprocess in the old release. This lets the release leader have more control over which tracks can move to the fix state (that is, how many file changes can be checked in). 2. Finish working as many defects as possible so they can be included in the level we want to use as the starting point for the new release. 3. Make sure we have a commitable level, and commit it. 4. Do a "Release -link -committed" from the old release to the new release. The track that is used to do the link is added as a single levelMember of the first level in the new release. This is more of a convenience for us, so we can be clear about "level 0 in the new release is the same as level N in the old release". NOTE: Set level type to a value that identifies the level in the old release as the source for linking to the new release. 5. List all files where "versionSID <> nuversionSID" (that is, all files with pending changes that did not make it into the build). The longer the old release was in approval mode, the fewer files fall into this category. 6. For each file listed in the previous step do: Releases 33 a. View the file information in order to see which tracks the pending changes were made under and if any remarks were entered at file checkin time. Do not close this window yet. b. Create track(s) in the new release. c. Extract each uncommitted file change. If we "clamp down" on file changes early enough, there usually is not more than one pending change, otherwise we have to iterate this step several times. d. Undo each uncommitted file change in the old release. e. Check-in back each uncommitted file change, but this time check in to both releases to maintain file commonality. If any remarks were specified the first time the file was checked in, cut/paste the original remarks from the file info window. If there was more than one pending change, be sure to restore each change in the original order. We could, of course, simply break file commonality with the new release, but it is easier to see that the same change has been applied to both releases when the version numbers are the same. This is not so obvious when the version number is 1.N in the old release and version 1.(N-1).1.1 in the new release. 34 CMVC FAQ: releases, tracks, levels 5.0 LEVELS For problems related to Release -extract or Level -extract, see the technical report: CMVC FREQUENTLY ASKED QUESTIONS: HANDLING FILE, RELEASE AND LEVEL EXTRACT PROBLEMS. 5.1 DOES A NEW LEVEL INCLUDE ALL THE CHANGES FROM PREVIOUS LEVELS? QUESTION: If I create a level for a release, does this level include all the changes that are in the former level? ANSWER: A level has only the file changes that are associated to the tracks that are level members for that level. However, there are 2 types of extracts: o Delta extract: It extracts the files that are associated to that level. This option is available for both committed and uncommitted levels. o Full extract: It extracts all the files of all the previously committed levels, as well as those for the specified (current) level. This option is available only for committed levels. Most of the CMVC users empploy a model of using 1 active (uncom- mitted) level at a time. When they want to build the code, they do a full extract of the most recent committed level, and then they do a delta extract of the uncommitted level. Levels 35 5.2 USING CMVC_LEVEL_COMMIT_SHORT_CHECK TO SELECT THE DESIRED METHOD QUESTION: How to use the environment variable CMVC_LEVEL_COMMIT_SHORT_CHECK to select the desired method for the action "Level -check" (long or short) that is performed when the action "Level -commit" is done? ANSWER: Before CMVC 2.3.0.17, we had a large query that was done for Level -commit to check for all the pre-requisites and co- requisites for the specified level. Because this query was very large, in a few cases it consumed most of the computing resources in the host, and did not complete the Level -commit step. Starting with CMVC 2.3.0.17, we changed the approach on how the Level -commit handled this check. It simply calls Level Check Long (to check both tracks and files). However, this seemed to cause some side effects for some customers (particularly those using Informix), and when in fact the old approach worked fine for them. Therefore, starting with CMVC 2.3.0.22 we provide both approaches so that customers can select the appropriate one for their situ- ation. By default, the approach introduced with CMVC 2.3.0.17 is used: Level check long is used inside Level -commit to check for the tracks and files for the pre-requisites and co-requisites for the specified level. If you have problems with this approach, for example, if the pre-requisites and co-requisites reported by the Level -commit do not match the ones reported by Level -check -long, you can set the following new environment variable in the family account and the Level -commit will check the pre- requisites and co-requisites using the Level check short to check for only the tracks: export CMVC_LEVEL_COMMIT_SHORT_CHECK=yes 5.3 CAN I EXTRACT AN OLD LEVEL? QUESTION: I have a base release which has 3 committed and completed levels: 1. Can I extract the base release without these 3 levels? 2. Can I extract the release plus 2 of the three levels? 3. Can I extract the 2nd level by itself? 36 CMVC FAQ: releases, tracks, levels 4. Can I have several levels active (integrate state) at the same time? For example, one level might deal with defects and another with features. ANSWER: 1. The nice thing about levels is that you can always use the Level command to extract the full level (that is, the current level plus ALL the previous committed levels) or extract the delta level (only the changes in that level). 2. A committed level becomes part of a release, because when you use the Release command to extract a release, either com- mitted or current, you will get the changes for ALL the com- mitted levels for that release. 3. You can extract the full or the delta for a specific com- mitted level, regardless of when the level was created and committed. 4. Based on our experience, we recommend to have ONLY ONE active level at a time for a given release, and not to work with several levels at the same time (for the same release). Furthermore, we also recommend that you work with small levels and avoid putting thousands of file changes over several months into a single level; it is better to have a dozen or so of tracks per level and commit levels frequently. 5.4 IS IT POSSIBLE TO RENAME A COMMITTED LEVEL? QUESTION: Is it possible to rename a committed level? ANSWER: Levels have the restriction that once they are committed, you cannot change the name; the only thing that you can change is the "type". The values for the "type" field are choices that are defined in the "config.ld" file (in the CMVC family account). The entries that have "leveltype" in the first column are the ones used for the type choice. You could add more entries in the config.ld file to suit your needs. In fact, this is how we circunvent to the problem caused by not having a formal "comments" field and by not being able to change the name of a committed level. We simply add "leveltype" entries that reflect our comments, such as: leveltype|gold|no|0|0|"GOLD level" leveltype|refresh|no|0|0|"Refresh Level" Levels 37 When we commit a level and later we decided that this is the GOLD level, then we change the type from "other" to "gold". 5.5 CAN WE WORK IN THE SAME RELEASE ON MULTIPLE LEVELS AT THE SAME TIME? QUESTION: Can we work in the same release on multiple uncommitted levels at the same time? For example: Release 1 Level 1.0 Level 1.1 Level 1.2 (uncommitted) (uncommitted) (uncommitted) Level Members 1,2,3 1,2,3,4 2,6,7 ANSWER: It is strongly recommended to work with only 1 uncommitted level at a time. If you use several uncommitted levels, it will be very easy to have co-dependencies between files and tracks and levels (identi- fied by the level -check action) and it could be difficult to untangle the "spaghetti" of cross-references. In the example above, level member 3 is included in all these levels. Thus in your example above, If you follow our recommendations of working with only 1 uncommitted level at a time, then the picture for the above example looks like follows: Release 1 Level 1.0 (uncommitted) Level Members 1,2,3 Level 1.0 Level 1.1 (committed) (uncommitted) Level Members 1,2,3 4 Level 1.0 Level 1.1 Level 1.2 (committed) (committed) (uncommitted) Level Members 1,2,3 4 6,7 Notice that the above picture shows a time frame with 3 stages, and in each stage there is only 1 uncommitted level. In the middle or in the bottom stage, by doing a full extract of Level 1.1, the level members of Level 1.0 (1,2,3) will be extracted too. 38 CMVC FAQ: releases, tracks, levels When it is time to commit one of the levels, you may need to spend a significant amount of time moving tracks between levels. TEAMCONNECTION NOTE: TeamConnection provides a mechanism for synchronizing active levels through the use of "Workarea -refresh". 5.6 WHY DOES LEVEL -EXTRACT CREATE A .GONE FILE? QUESTION: Why does Level -extract create a .gone file? ANSWER: During a Level -extract, CMVC will create a file named ".gone" in UNIX and "cmvc.gon" in OS/2 and Windows, which contains a list of files that were deleted or renamed. This file does not do any processing/checking of the list. You can use this file as input to a script that verifies that the file is actually gone from the release. If the file is gone, then you can remove it from your workstation. The .gone file is described in page 68 of the CMVC Commands Ref- erence manual: o Files that have been deleted or renamed in the current level must be deleted from an extracted file tree. CMVC creates a file named .gone that specifies the full path name of each file deleted or renamed that has not already been committed. This file is extracted with the files in a delta tree extraction. Extracting the delta file tree of an uncommitted level extracts all files listed in the .gone file. o After merging a delta tree with a base file tree, or when extracting uncommitted levels, run the following UNIX command from the top of the extracted file tree to remove deleted and renamed files from the tree: xargs rm < .gone o When you extract a committed level, any files that were con- tained in that level when it was committed are accessed. o When you destroy a file, the database record for that file is destroyed but the file remains on the server, so that previ- ously committed levels can be re-built. Levels 39 5.7 TWO DIFFERENT WAYS FOR %W% STRING EXPANSION IN LEVEL -EXTRACT QUESTION: How to use the two different ways for %W% string expansion in Level -extract. ANSWER: The SCCS keyword %W% is used by CMVC to identify CMVC specific information in a source file during extract. Specifically inserted into the text file are: path, component name, release name, and conditionally the level name. o The first and original way (this is the default), is to expand the %W% string to: , , , o You can select the second way of %W% string expansion by setting in the CMVC family account the environment variable CMVC_WSTRING_WITHOUT_LEVELNAME to yes (YES), so that it will expand the %W% string to: , , Which is consistent with the %W% string expansion in Release/File -extract. 40 CMVC FAQ: releases, tracks, levels 6.0 TRACKS 6.1 HOW CAN I MOVE A TRACK FROM INTEGRATE STATE BACK TO FIX STATE? QUESTION: I promoted some modules (but not all, unfortunately) and then marked the fix record as complete. This moved the track to inte- grate state. Now I would like to move the track back to fix state so that I can promote the remaining modules. ANSWER: 1. If the track is in a level then go to the levelMembers window and remove it from the level (Actions->Remove). " 2. From the Track window, highlight the desired track and change the state back to fix by doing the following: Actions->Fix 3. Display the fix records for the track and change them back to active: Actions->Activate. 4. Create or checkin the missing files. 5. Complete the fix records to move the track back to the inte- grate state. 6.2 ERRONEOUS STATE CHANGE: TEST->VERIFY ON FIRST TRACK COMPLETION QUESTION: We have a project which has 2 releases with Track, Level, Fix, Test and Verify subprocesses enabled. Whenever a defect is opened, two tracks must be opened and code changes made in each releases; then the two tracks progress through separate but iden- tical flows, to Test Record acceptance. The state of the defect is changed from "working" to "verify" upon completion of ONE test record! Then the component owner completes the Verification record and expects the defect to change to the closed state. But the state remains in verify. ANSWER: Tracks 41 Some workarounds are shown below: 1. Workaround 1 (Thanks to Ken Mann from Poughkeepsie, NY, for his advice) By the way, there is a defect opened against the CMVC code to solve this problem. In the meantime, you can follow these suggestions: o If the release field of the defect is NULL, then the defect moves to verify when the first track moves to com- plete. o If the release field of the defect is set to a release that also has a track associated with that release, the defect moves to verify only when the track in that release moves to complete. o If the Defect's release field is set to a release that will never have a track associated with it, the defect moves to verify only when ALL tracks have moved to com- plete. The last scenario prevents premature verification notifica- tion. Therefore, you can create a dummy release (because CMVC will only allow you to place a valid CMVC release in the release field for a defect), and when a defect is open, you can set the release field to be that dummy release. The result is that the defect will not move to verify until ALL tracks that we use for that defect move to complete. The side effect of this method is a potential "overdue ver- ification notification" when you have one release out in the field and another in test. 2. Workaround 2: a. Ensure that the defects with the wrong state have all the related tracks in the complete state and all the verifi- cation records in the accepted state. b. Stop the CMVC daemons and do a complete backup of the CMVC family (database and file system). c. Manually access the database for the Defects table and change the state of the desired defects to "closed". NOTE: You have to be very careful when doing this part. We need to repeat that if you cause a problem when accessing directly the database, the CMVC support group will not help you. d. Restart the CMVC family and verify if the defects are now shown as closed. 42 CMVC FAQ: releases, tracks, levels e. Make another backup, this time with the updates in it. f. Restart the CMVC family and let the rest of the users access it. 6.3 IS THERE A WAY TO VIEW WHO CHANGED THE OWNERSHIP OF A TRACK? QUESTION: Is there a way to view who changed the ownership of a track? ANSWER: Many actions on objects are tracked in a change history for the object, but some others are not. For example, there is no change history for the ownership for a track. Thus, it is not possible to view who changed the owner- ship. However, the audit/log file in the CMVC family account might be used to determine who did it. 6.4 USE TRACK -CHECK TO VIEW EXISTING COREQUISITES QUESTION: Use Track -check to view existing corequisites ANSWER: The command Coreq cannot be used to view the existing corequisites for a track. You have to use the command Track -check to view the existing corequisites. Tracks 43 44 CMVC FAQ: releases, tracks, levels APPENDIX A. BIBLIOGRAPHY For more information on how to use CMVC, you can consult the fol- lowing manuals and publications: SC09-1596-01 IBM CMVC Client Installation and Configuration SC09-1597-01 IBM CMVC User's Reference SC09-1631-02 IBM CMVC Server Administration and Installation SC09-1633-00 IBM CMVC Concepts SC09-1635-01 IBM CMVC Commands Reference The following Redbooks offer practical advice on CMVC: GG24-4178-00 Did you say CMVC? GG24-4345 CMVC: Customer's Perspective The following technical reports describe in detail useful hints on using CMVC: 29.2130 Diagnosing and solving Release -extract problems with CMVC 29.2169 How to use CMVC with National Language Support (NLS) and Double-Byte Character Sets (DBCS) 29.2180 How to do routine tasks in the OEM Platforms for CMVC 29.2183 Using CMVC for Products with Multiple National Language Versions (NLVs) 29.2232 How to do migration tasks with CMVC 29.2244 How to build and package the CMVC client for Windows 3.1 29.2245 How to build and package the CMVC client for OS/2 29.2253 Comparison between CMVC 2.3 and TeamConnection 2 29.2254 Migrating from CMVC 2.3 to TeamConnection 2 29.2268 CMVC frequently asked questions: license management with NetLS/iFOR 29.2269 How to build and package the CMVC Server/Client for UNIX A.1 HOW TO GET ELECTRONIC COPIES OF MANUALS AND TECHNICAL REPORTS Many of the manuals and technical reports mentioned in this docu- ment can be downloaded as follows: o From the IBM intranet (only for IBM employees). o From the Internet (open to everyone). A.1.1 IBM Intranet ___________________ Appendix A. Bibliography 45 A.1.1.1 Web Home Page You can access the CMVC Service/Development Home Page at: http://keithp.raleigh.ibm.com/&tilde.cmvcsupt From the index at the top of the page, select: o Technical Reports and related tools o Copies of ALL the archived versions for the forums CMVC and CMVC6000 o Documentation in PostScript files o Documentation in ASCII text files A.1.1.2 FTP You can download the code from our internal FTP site, by doing: 1. ftp keithp.raleigh.ibm.com 2. login as 'anonymous' and for password give your email address. 3. cd pub/cmvc/doc 4. binary 5. get fileName 6. quit A.1.2 Internet _______________ A.1.2.1 Web Home Page Not available. 46 CMVC FAQ: releases, tracks, levels A.1.2.2 FTP You can download the code from our external FTP site, by doing: 1. ftp ftp.software.ibm.com 2. login as 'anonymous' and for password give your email address. 3. cd ps/products/cmvc/doc 4. binary 5. get fileName 6. quit Appendix A. Bibliography 47 48 CMVC FAQ: releases, tracks, levels APPENDIX B. COPYRIGHTS, TRADEMARKS AND SERVICE MARKS The following terms used in this technical report, are trademarks or service marks of the indicated companies: +---------------------+-------------------------------------------+ | TRADEMARK, | COMPANY | | REGISTERED | | | TRADEMARK OR | | | SERVICE MARK | | +---------------------+-------------------------------------------+ | IBM | IBM Corporation | | AIX | | | OS/2 | | | CMVC | | | DB2 | | | TeamConnection, | | +---------------------+-------------------------------------------+ | PostScript | Adobe Systems Incorporated | +---------------------+-------------------------------------------+ | Informix | Informix Inc. | +---------------------+-------------------------------------------+ | Intel | Intel Corp. | +---------------------+-------------------------------------------+ | Microsoft, | Microsoft Corporation | | Windows, | | +---------------------+-------------------------------------------+ | Oracle | Oracle Corp. | +---------------------+-------------------------------------------+ | NFS | Sun Microsystems Inc. | +---------------------+-------------------------------------------+ | UNIX | X/Open Co., Ltd. | +---------------------+-------------------------------------------+ END OF DOCUMENT Appendix B. Copyrights, Trademarks and Service marks 49