CMVC FREQUENTLY ASKED QUESTIONS: SERVER INSTALLATION, INITIAL CONFIGURATION AND CONFIGURABLE FIELDS Document Number TR 29.xxxx Angel Rivera, Lee Perlov, Clifford Meyers CMVC/TeamConnection Development IBM Software Solutions Research Triangle Park, North Carolina Copyright (C) 1997 IBM Corp. All rights reserved. ii CMVC FAQ: installation ABSTRACT This technical report provides answers to frequently asked questions made by CMVC users with respect to server installation, initial configuration and configurable fields ITIRC KEYWORDS o CMVC o server installation o initial configuration o configurable fields ABSTRACT iii iv CMVC FAQ: installation 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 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. CLIFFORD MEYERS Mr. Meyers is an advisory programmer and the technical team lead for ISSC Distributed Configuration Management Services. He joined IBM in 1985 as support for AIX/370 and AIX/ESA before accepting his current assignment in 1993. The ISSC organization in RTP provides consulting and support ser- vices for over 7,000 internal and external customers. Cliff was also involved in the development of the original Motif GUI for CMVC and all of the tools in the appendices of this docu- ment. +--- CLIFF, PLEASE UPDATE. -------------------------------------+ | | +---------------------------------------------------------------+ ABOUT THE AUTHORS v vi CMVC FAQ: installation CONTENTS ABSTRACT . . . . . . . . . . . . . . . . . . . . . . . . . III ITIRC KEYWORDS . . . . . . . . . . . . . . . . . . . . . iii ABOUT THE AUTHORS . . . . . . . . . . . . . . . . . . . . . . V Angel Rivera . . . . . . . . . . . . . . . . . . . . . . . v Lee Perlov . . . . . . . . . . . . . . . . . . . . . . . . v Clifford Meyers . . . . . . . . . . . . . . . . . . . . . . v 1.0 INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . 1 1.1 Acknowledgements . . . . . . . . . . . . . . . . . . . 1 1.2 Important warnings about your CMVC installation . . . 1 1.2.1 Do not alter the contents and/or structure of $CMVC_HOME . . . . . . . . . . . . . . . . . . . . . . . . 1 1.2.2 Do not alter the contents of the database or the $HOME/vc directory . . . . . . . . . . . . . . . . . . . . 2 1.2.3 Avoid using the string "cmvc" . . . . . . . . . . . 2 1.2.4 Same version is needed if using both Server and Client in the same host . . . . . . . . . . . . . . . . . 3 2.0 EXAMPLE OF A COMPLETE INSTALLATION AND INITIAL CONFIGURATION . . . . . . . . . . . . . . . . . . . . . . 5 2.1 How to install DB2 and CMVC together? . . . . . . . . 5 3.0 INSTALLATION OF THE CMVC CODE . . . . . . . . . . . . . 9 3.1 AIX: after installing the CMVC server, the wrong one is installed . . . . . . . . . . . . . . . . . . . . . . . . . 9 3.2 Where are the error messages from the CMVC daemon and databases? . . . . . . . . . . . . . . . . . . . . . . . . 9 3.3 What are the trade-offs of using installp (smit) versus tar files? . . . . . . . . . . . . . . . . . . . . 10 3.4 Installation from tape: need to add bs=31744 to dd statement . . . . . . . . . . . . . . . . . . . . . . . . 11 3.5 Support for remote installation when installing from tape . . . . . . . . . . . . . . . . . . . . . . . . . . 11 3.6 Additional install packages needed for AIX 4.1 . . 12 3.7 How to find the install images for SCCS on HP-UX? . 12 3.8 Problems with Solaris when trying to add CMVC to the startup process . . . . . . . . . . . . . . . . . . . . . 13 4.0 INITIAL CONFIGURATION OF A NEW CMVC FAMILY . . . . . . 15 4.1 Sample profile for a CMVC family server . . . . . . 15 4.2 Does CMVC support splitting the database across servers in a network? . . . . . . . . . . . . . . . . . . 16 4.3 How to reinstall a CMVC family from scratch . . . . 16 4.4 Error message 0010-525 when creating a family . . . 17 4.5 Do not change the file permissions nor the ownership of cmvc files . . . . . . . . . . . . . . . . . . . . . . 18 4.6 Error message: 0010-063 with keyword bind() . . . . 18 Contents vii 4.7 Cannot create database (mkdb) for new family - DB2 SQL1092N . . . . . . . . . . . . . . . . . . . . . . . . 20 4.8 Error when Informix database not On-line mode . . . 21 4.9 Error with notifyd, 0010-063, chdir() function . . . 21 5.0 DATABASE ISSUES RELATED TO INSTALLATION AND CONFIGURATION . . . . . . . . . . . . . . . . . . . . . 23 5.1 General notes on SQL statements used in the Server manual . . . . . . . . . . . . . . . . . . . . . . . . . 23 5.2 Limitations of CMVC Server for DB2 . . . . . . . . . 23 5.3 New DB2_CODESET and DB2_TERRITORY variables . . . . 24 5.4 What is the number of DB2 licenses for a CMVC family? 24 5.5 CMVC and DB2: Could not load library libdb2.a[shr.o] 25 5.6 CMVC cannot work when more than one version of DB2 are present . . . . . . . . . . . . . . . . . . . . . . . . . 25 5.7 Error -818 from DB2 . . . . . . . . . . . . . . . . 26 5.8 How many CMVC families can a single DB2 instance handle? . . . . . . . . . . . . . . . . . . . . . . . . . 26 5.9 Conflict with stopCMVC with names of DB2 instance and CMVC family . . . . . . . . . . . . . . . . . . . . . . . 28 5.10 Additional notes on Oracle 7 . . . . . . . . . . . 28 5.11 mkdb and ORACLE/INFORMIX errors . . . . . . . . . . 29 5.12 Can the CMVC server work under Informix 6 or Informix 7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 5.13 Informix 7: need to update .rhosts and /etc/hosts.equiv . . . . . . . . . . . . . . . . . . . . 30 5.14 Specify TCP/IP and not shared memory for sqlhosts . 31 5.15 Problem when using unbuffered setting for database logging in Informix . . . . . . . . . . . . . . . . . . . 31 5.16 Informix: increase logical logs to avoid problems with Level -check . . . . . . . . . . . . . . . . . . . . 31 6.0 CONFIGURABLE FIELDS . . . . . . . . . . . . . . . . . 33 6.1 What are some of the characteristics of the configurable fields? . . . . . . . . . . . . . . . . . . 33 6.2 Using chfield to add a new configurable field with selection values . . . . . . . . . . . . . . . . . . . . 33 6.3 Using chfield to add a new configurable field with "free-text" . . . . . . . . . . . . . . . . . . . . . . . 38 6.4 What are the files related to chfield? . . . . . . . 39 6.5 How to replicate the configurable fields from one family to another . . . . . . . . . . . . . . . . . . . . 40 6.6 How to disable a configurable field? . . . . . . . . 40 6.7 How to retrieve information about the configurable fields? . . . . . . . . . . . . . . . . . . . . . . . . . 41 6.8 I added a new configurable field but the report does not include it, why? . . . . . . . . . . . . . . . . . . 41 6.9 How to configure reports in CMVC? . . . . . . . . . 42 6.10 chfield: how to fix an invalid database column name 43 6.11 chfield: how to fix a report with database error . 44 6.12 Can I change any field to be optional or mandatory? 45 6.13 How to make "release name" mandatory while opening a Defect? . . . . . . . . . . . . . . . . . . . . . . . . . 45 6.14 Cannot delete an existing configurable field . . . 45 viii CMVC FAQ: installation 6.15 Use only the DB Column Name in reports . . . . . . 46 6.16 Configurable fields are not shown in details view . 46 6.17 Adding new configurable field in Stanza View Format 46 6.18 Create and Required fields for Files using chfield 47 6.19 DB2, maximum number of configurable fields is 17 for Defect/Feature . . . . . . . . . . . . . . . . . . . . . 47 6.20 DB2 error SQL1040N during chfield . . . . . . . . . 48 6.21 Oracle pause stops the execution of chfield . . . . 48 6.22 Only 10 configurable fields can be handled with Sybase . . . . . . . . . . . . . . . . . . . . . . . . . 49 APPENDIX A. BIBLIOGRAPHY . . . . . . . . . . . . . . . . . 51 A.1 How to get electronic copies of manuals and technical reports . . . . . . . . . . . . . . . . . . . . . . . . . 51 A.1.1 IBM Intranet . . . . . . . . . . . . . . . . . . 51 A.1.2 Internet . . . . . . . . . . . . . . . . . . . . 52 APPENDIX B. COPYRIGHTS, TRADEMARKS AND SERVICE MARKS . . . 55 Contents ix x CMVC FAQ: installation 1.0 INTRODUCTION This technical report provides answers to frequently asked questions made by CMVC users with respect to server installation, initial configuration and configurable fields This technical report covers the following topics: o Installation of a CMVC family o Initial configuration of a CMVC family o Describing some installation topics related to databases. o Handling configurable fields For many routine tasks related to the operating systems and the databases, see the technical report "CMVC frequently asked questions: handling OEM platforms and databases". 1.1 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! 1.2 IMPORTANT WARNINGS ABOUT YOUR CMVC INSTALLATION 1.2.1 Do not alter the contents and/or structure of $CMVC_HOME _______________________________________________________________ After you install the TeamConnection code in its directory struc- ture (represented by $TC_HOME), please keep in mind the following guidelines: o Do not remove directories, files or symbolic links from $TC_HOME. Exception: To uninstall the product, you need to remove $TC_HOME. Introduction 1 o Do not change the file permissions nor the ownership of the directories and/or files in $TC_HOME. o * Use $TC_HOME only to store the TeamConnection code: - Do not use $TC_HOME as the home directory for users. - Do not use $TC_HOME as the home directory for TeamConnection families. 1.2.2 Do not alter the contents of the database or the $HOME/vc ________________________________________________________________ directory _________ 1. We strongly recommend to our customers to always use CMVC to access the database for the CMVC server. There are many relationships between objects and some of them are rather complex and some of them trigger some actions in CMVC. If you decide to modify directly the database, you will be doing this at your own risk and we will not help you in case that you get into problems as a direct result of this action. You can access the database in read-only mode to provide reports that you may want and that are not available from CMVC. 2. Similarly, the file changes stored in the vc directory struc- ture contain information that is used by CMVC. If you rename, delete or move files in the vc directory structure, you will be doing this at your own risk and we will not help you in case that you get into problems as a direct result of this action. 1.2.3 Avoid using the string "cmvc" ____________________________________ Because the stopCMVC script uses "ps -ef" to identify the CMVC daemons that are logged, it is possible to misidentify some other processes that have the "cmvc" string in them, such as a user "cmvcdemo", "cmvca" (for user CMVC "A"), "cmvc23", a DB2 instance called "cmvc", etc. The problem is that stopCMVC may kill these processes even though they are not running the cmvcd daemons. If you really want to use the string "cmvc" in your userids, then you will need to modify stopCMVC to avoid terminating the proc- esses for these userids. 2 CMVC FAQ: installation 1.2.4 Same version is needed if using both Server and Client in ________________________________________________________________ the same host _____________ Because both the CMVC Server and the CMVC Client use the same message catalog file (cmvc.cat), it is critical that both CMVC components must be at the same version-release-level. For example, you should not have a CMVC Server version 2.3.0.0 in the same host with a CMVC Client version 2.3.0.14, because it is pos- sible for the user may get strange warning or error messages, due to the mismatch in the version of the message catalog. However, if the CMVC client is not in the same host as the CMVC server, then it is possible for the client to be a different level than the server, because they are not sharing the same message catalog. That is, you can use a CMVC 2.1 client from host A, with a CMVC 2.3.0.22 server in host B. The only incompatibility problems is when you are using a CMVC client for OS/2 or for Windows, in which the version of the CMVC server must be 2.2 or later (that is, CMVC 2.1 or 2.1.1 servers do NOT support these clients). Introduction 3 4 CMVC FAQ: installation 2.0 EXAMPLE OF A COMPLETE INSTALLATION AND INITIAL CONFIGURATION 2.1 HOW TO INSTALL DB2 AND CMVC TOGETHER? QUESTION: How to install DB2 with CMVC? ANSWER: The following instructions take you step by step through the installation of DB2 and CMVC for demonstration purposes. The instructions include the definition of all AIX users, loading of CMVC demo data, and the invocation of CMVC. At the end of this procedure, the CMVC family name should be "cmvcdemo" and the DB2 instance name should be "db2". 1. Create a group for DB2 instance (for example, sysadm). a. logon to root b. smit groups c. add a group d. specify group-name (sysadm) and leave ADMINISTRATIVE group as false 2. Create two userids and set passwords for each userid: a. smit users b. add a user c. specify user-name (db2) and PRIMARY Group (sysadm) and Group set (sysadm) d. specify user-name (cmvcdemo) and PRIMARY Group (system) and Group set (sysadm) e. smit passwd f. specify user-name (db2) and set password g. specify user-name (cmvcdemo) and set password 3. Create a 15-20 MB file system to hold the CMVC family data- base (for example, /db2space). The CMVC server DB2_DBPATH environment variable will be set to this file system, for example: DB2_DBPATH=/db2space. This should be owned by the DB2 instance owner (for example, db2) and have the same group as the DB2 instance owner (for example, sysadm). a. smit storage b. File Systems c. Add ... File Systems d. Journaled File Systems Example of a complete installation and initial configuration 5 e. Add a Journaled File System f. select a volume group g. mount AUTOMATICALLY = yes, PERMISSIONS = read/write h. return to screen to Mount a File System and select the filesystem just created i. chown db2 /db2space j. chgrp sysadm /db2space 4. Install DB2 server (db2_##_##_####.db2) a. smit install b. Install/Update Software c. Install/Update Selectable Software d. Install Software Products at Latest Available Level e. select input device f. get list of software to install and select db2_##_##_####.db2 and g. Automatically install PREREQUISITE software = yes and COMMIT software = no and Save replaced files = yes 5. Configure DB2 according to the manuals. Execute the db2instance command. Update the nodelock file with the license information. Execute the db2ln command. a. /usr/lpp/db2_01_01_0000/instance/db2instance db2 b. /usr/lpp/db2_01_01_0000/cfg/db2ln 6. Install CMVC. The files required from the demo package are: cmvccltstal.obj cmvccltstalmEn_US.msg cmvcsrvmEn_US.msg cmvcsrvdb2.obj Ensure that you select ONLY one image for the CMVC server. If you select ALL, then all the CMVC server images will be installed and this will not be correct, because each CMVC server install image will overwrite the previously installed one. a. smit install b. Install/Update Software c. Install/Update Selectable Software d. Install Software Products at Latest Available Level e. select input device f. get list of software to install and install those objects listed above and Automatically install PREREQUISITE soft- ware = yes and COMMIT software = no and Save replaced files = yes 7. Add the CMVC family name as an alias of this workstation in the TCP/IP environment in the /etc/hosts file. Entries in this file are in the format: 6 CMVC FAQ: installation IP address alias-1 alias-2 ... alias-n a. hostname b. vi /etc/hosts c. Find the entry which has the hostname returned above in the second column. d. Add the CMVC family name "cmvcdemo" to the end of this line. e. Exit and save changes to /etc/hosts. 8. Define a TCP/IP port for the CMVC server in the /etc/services file. a. Entries in this file are in the format: identifier port-number/usage b. vi /etc/services c. Select a number for the port which is not already defined in this file. d. Add an entry (sequentially if appropriate) for this new port number as follows: cmvcdemo 3125/tcp 9. Exit from root and login as db2 instance owner (db2). 10. Set up the db2 profile by copying db2profile in the sqllib directory to .profile a. cp sqllib/db2profile .profile b. logoff and login again to refresh your environment. 11. Start the DB2 database: db2start 12. Exit from the db2 instance owner and login as the cmvc family (cmvcdemo). 13. Extract the Demo tar files relative to the CMVC family home directory. a. cd $HOME b. tar -xvf /usr/lpp/cmvc/samples/mkdemo2.tar 14. Read $HOME/demo2setup/README.demo2 for instructions. Set up the .profile for cmvcdemo from the db2.profile in demo2setup. a. cp demo1setup/demo1.profile.db2 .profile b. vi .profile c. Change the value for CMVC_FAMILY to reflect the cmvcdemo host name and the cmvcdemo port number. Example of a complete installation and initial configuration 7 d. If the values for db2 instance were used as above, uncom- ment and change DB2_DBPATH to /db2space. If different values were used, then change DB2INSTANCE, DB2_HOME. e. Change the value for DB2_PASS to reflect the password for the CMVC family userid. f. Change the value of DEMO_CLIENT_HOSTNAME=hostname-of-client g. Exit and save changes to the profile. h. logoff and login again to refresh your environment. In case that you want to use the non-demo profile, you could do the following: cp /usr/lpp/cmvc/install/profile.db2 .profile 15. Copy the *.ld files from usr/cmvc/lpp/instal to $HOME. cp $CMVC_HOME/install/*.ld $HOME 16. Create the family files and database. a. cd $HOME b. mkfamily c. mkdb -d 17. Bring up the cmvcd server daemons: a. cmvcd cmvcdemo 2 b. notifyd 18. Populate the Demo family data. a. cd $HOME/demo2setup b. mkdemo2 NOTE: If mkdemo2 does not complete without errors, then you should perform the following steps: a. stopCMVC cmvcdemo b. rmdb c. rmfamily d. return to step 16 and try again 19. Copy the CMVC demo resource file to the home directory. a. cd $HOME b. cp demo1setup/.cmvcrc .cmvcrc 20. You can now use the CMVC client to interact with the CMVC server. 8 CMVC FAQ: installation 3.0 INSTALLATION OF THE CMVC CODE 3.1 AIX: AFTER INSTALLING THE CMVC SERVER, THE WRONG ONE IS INSTALLED QUESTION: During the installation of CMVC in AIX, I specified to install all components and the CMVC server is always assuming that is for Oracle, even though I wan to use another database, such as Sybase. Why? ANSWER: One of the limitations of smit in AIX is the inability to provide an exclusive OR function when installing the CMVC server code. Only one CMVC server code can be installed in the same directory and the last installed server overwrites the previously installed server. Thus, when choosing "ALL" from smit, the installation will install according to the physical location of the components in the table of contents (file .toc), and it happens that the last one is the CMVC server for Oracle. This means that in your installation that you did, this is what happened: first the CMVC for DB2 server was installed, then on top of it the CMVC for Informix server (erasing the one for DB2), then the CMVC for Sybase (erasing the Informix one) and finally the one for Oracle (erasing the Sybase). We have added a paragraph in the CMVC manuals to warn the users about this, but unfortunately, it is rather common for the AIX administrator to always install "ALL". Thus, when installing the CMVC server code, please, select only one component for the server. Of course, you need to select also the component for the Message Catalog for the Server (cmvcservm_En_US). 3.2 WHERE ARE THE ERROR MESSAGES FROM THE CMVC DAEMON AND DATABASES? QUESTION: Where are the error messages from the CMVC daemon and databases? ANSWER: Installation of the CMVC code 9 The error messages from the CMVC daemon and the database are logged in the syslog. You need to enable the syslog facility, as explained in the technical report "CMVC frequently asked questions: handling OEM platforms and databases", section "Where are the error messages from the CMVC daemon and databases?". NOTE: We strongly recommend that you setup the syslog facility in order to better diagnose any possible problems with CMVC, the database, or the operating system. 3.3 WHAT ARE THE TRADE-OFFS OF USING INSTALLP (SMIT) VERSUS TAR FILES? QUESTION: For IBM internal users the CMVC code for AIX is provided in both installp (for use with the smit tool) and tar files. What are the trade-offs of using installp (smit) versus tar files? ANSWER: The main advantage of installing CMVC by means of tar files is that you can choose which directory to use to place the final code. With smit you do not have a choice, it is always /usr/lpp/cmvc. Thus, if you have disk space and would like to have the old version around, then you could create a new direc- tory such as /usr/lpp/cmvc.new or whatever and specify this directory when using tarinstall. Of course, if you specify /usr/lpp/cmvc, then the old version will be overwritten. The main disadvantage of using tar files is that the product database that is automatically maintained by smit, is NOT updated, and thus, you cannot use the smit utilities to find out which level was installed by the tarinstall (but you can always do the following to find out): 1. cd /usr/lpp/cmvc/bin (or equivalent) 2. what cmvcd | grep cmvc An advantage of using installp images is that the uninstall process is far easier to do than when using tar images. 10 CMVC FAQ: installation 3.4 INSTALLATION FROM TAPE: NEED TO ADD BS=31744 TO DD STATEMENT QUESTION: Installation from tape: need to add bs=31744 to dd statement ANSWER: The instructions to install CMVC for SunOS, Solaris and HP-UX from tape need to be updated in the dd statement which needs the parameter bs=31744. Thus, the complete dd statement must be: dd if=TAPEDEV skip=0 bs=31744 > cmvcinstall or dd if=TAPEDEV skip=0 bs=31744 of=cmvcinstall 3.5 SUPPORT FOR REMOTE INSTALLATION WHEN INSTALLING FROM TAPE QUESTION: Support for remote installation when installing from tape ANSWER: The tape installation script for CMVC for Solaris, SunOS and HP-UX systems has been enhanced to allow for remote installation. Furthermore, you may optionally install into directories other than /usr/lpp/cmvc. To configure your system for remote installation, you must add an entry for "root" in the /.rhosts file on the system with the tape drive attached. Optionally, you can extract the script remotely with the fol- lowing commands: Installation of the CMVC code 11 # Change the directory which will contain cmvc, default is /usr/lpp/cmvc cd /usr/lpp/cmvc # Retrieve the install script remotely # For HP-UX systems, use "mt -t" instead of "mt -f" rsh mt -f rewind rsh "dd if= skip=0 bs=31744" > cmvcinstall # Retrieve the install script remotely # For HP-UX systems, use "mt -t" instead of "mt -f" rsh mt -f rewind rsh "dd if= skip=0 bs=31744" > cmvcinstall # Run the cmvcinstall script chmod u+x cmvcinstall ./cmvcinstall 3.6 ADDITIONAL INSTALL PACKAGES NEEDED FOR AIX 4.1 QUESTION: Additional install packages needed for AIX 4.1 ANSWER: It is recommended that the user should install the following packages in AIX 4.1 for compatibility with AIX 3.2 for the CMVC servers (such as for the CMVC use of 'mount'): bos.compat.libs 4.1 bos.compat.links 4.1 3.7 HOW TO FIND THE INSTALL IMAGES FOR SCCS ON HP-UX? QUESTION: A customer wants to try CMVC on a HP-UX workstation, but SCCS seems not to be installed in that workstation How can the cus- tomer obtain SCCS? ANSWER: SCCS is part of the SRC-CNTL fileset on HP-UX V9 & V10. It might be part of the application development bundle which you need to buy separately if you want a proper C compiler. 12 CMVC FAQ: installation 3.8 PROBLEMS WITH SOLARIS WHEN TRYING TO ADD CMVC TO THE STARTUP PROCESS QUESTION: We have CMVC installed in a Solaris/Sybase environment, and we are trying to add CMVC to our startup procedures. The problem is that the following command, when run as root, gives a segmenta- tion fault: % su - tme -c "/tivoli/scm/1/cmvc/solaris2/bin/cmvcd tme 2" Segmentation fault If I login as the family administrator, tme, then I can start it up with no problem. It seems that cmvcd does not like it when my real user id is root, which is the case above (even though my effective userid is tme). ANSWER: Try putting your "cmvcd ..." command in a shell script and starting it with an "at" job: % su - tme -c "at now /$HOME/bin/cmvcStart" where cmvcStart contains: #!/usr/bin/ksh cmvcd tme 2 CMVC explicitely checks to insure that you are NOT root when starting daemons. Installation of the CMVC code 13 14 CMVC FAQ: installation 4.0 INITIAL CONFIGURATION OF A NEW CMVC FAMILY 4.1 SAMPLE PROFILE FOR A CMVC FAMILY SERVER QUESTION: Is there a sample profile ready-to-use for a CMVC family server? ANSWER: Starting with CMVC 2.3.0.18, we are providing an excellent sample profile for a CMVC family. We strongly recommend that for every new family, regardless of the expertise of the CMVC adminis- trator, the CMVC server sample profile should be used as the profile for the CMVC family (or at least to be used as the basis for the profile). We are constantly adding new environment vari- ables and adding new hints and tips, such as how to create a table space in Oracle and a dbspace for Informix. Furthermore, each sample profile is tailored for a single data- base and those variables that are dependent on the operating system are commented out and it is the responsibility of the CMVC administrator to review the entire profile and uncomment those variables that are appropriate, and create the necessary table spaces or dbspaces. To avoid confusion, only one CMVC server profile is provided with each CMVC server version, that is, if you install the CMVC server for Oracle, then only the profile for Oracle is provided. The CMVC server profile is found in (starting with 2.3.0.18): /usr/lpp/cmvc/install/profile. By the way, there is a CMVC user sample profile which is included with the CMVC client code in: /usr/lpp/cmvc/samples/profile.user Initial configuration of a new CMVC family 15 4.2 DOES CMVC SUPPORT SPLITTING THE DATABASE ACROSS SERVERS IN A NETWORK? QUESTION: Does CMVC support splitting the database across servers in a network? ANSWER: The CMVC server sees the database and the file system for the change history of the files as being local resources in the serve host. CMVC has no facilities for explicitly working with remote resources. As long as the CMVC server "thinks" that the database or the file system or both are local resources, everything is fine. This means that you can "trick" CMVC to think that a remote resource is a "local" one, for example, you can mount the file system for CMVC from a remote host and from an operational view, the file system can be considered to be a "local" file system. Also, if you use database facilities to disguise a remote database or databases as a single local database, then CMVC should be fine. 4.3 HOW TO REINSTALL A CMVC FAMILY FROM SCRATCH QUESTION: A customer has installed a CMVC family and decides to remove the CMVC family and start all over again. ANSWER: 1. Login as the CMVC family to be installed. 2. Do a "rmdb" to remove the database. 3. Do a "rmfamily" to remove the directories created by "mkfamily" 4. Do "rm -fr configField" to remove the directory that contains information about the configurable fields. 5. Rename the .profile to .profile.original 6. Copy the sample profile for CMVC families using DB2: cp /usr/lpp/cmvc/install/profile.db2 .profile 7. Edit and customize the new .profile. Please read the entire file because there are many actions to be taken. 8. Exit and login again to obtain a clean environment. 9. Do "mkfamily" 10. Do "mkdb -d" 11. Check that the syslog daemon is up and running. 12. Do "cmvcd newfamily 2" 16 CMVC FAQ: installation 13. Verify that the cmvc daemons are working: "ps -ef | grep cmvcd" 14. Issue a CMVC command to test the CMVC server: Report -testServer 15. Ensure that there are no errors logged in the syslog due to action tail /var/spool/syslog 4.4 ERROR MESSAGE 0010-525 WHEN CREATING A FAMILY QUESTION: I am installing a new CMVC family and when I start the family daemons I am getting the following error: 0010-525 The User Exit Index was not found. What does this mean? ANSWER: Check the following: 1. Login as the family id. 2. Check that you have the config directory that should be owned by the user and group of the family, and which should have file permissions of 644. 3. Change to the config directory and check the file "userExits" which should be owned by the user and group of the family and which should have file permissions of 644. 4. If the file is there with the correct ownership and permis- sions, then edit the file and remove any blank lines that you find. 5. Restart the cmvcd family in order to pick up the new userExits file. Initial configuration of a new CMVC family 17 4.5 DO NOT CHANGE THE FILE PERMISSIONS NOR THE OWNERSHIP OF CMVC FILES QUESTION: A customer modified the ownership of the executable of cmvcd in /usr/lpp/cmvc/bin from root:system to bin:bin (probably by mistake) and this action caused a LOT of problems that were dif- ficult to diagnose, such as messages in the syslog about not able to open the audit/log, error message 0010-063 with chown() when creating or checking a file, and problems with fchown() during a release extract. ANSWER: NOTE: Please, do not change the file permissions or the owner- ship of any of the CMVC executables. For your information, the cmvcd must have: -rwsr-xr-x 1 root system /usr/lpp/cmvc/bin/cmvcd* While the other executables must be: -rwxr-xr-x 1 bin bin /usr/lpp/cmvc/bin/Report* 4.6 ERROR MESSAGE: 0010-063 WITH KEYWORD BIND() QUESTION: Error Message: 0010-063 Error, Address already in use, occurred when the CMVC Server/6000 attempted to process the bind() function. ANSWER: o Situation A: dealing with a new family When creating and starting a new family, if this error appears, the most likely cause is that the port number for the new family is already being used by another service. Please take a look at the /etc/services file and ensure that the port number for the new family is unique and not in use by another service. Try to avoid "nice and round" numbers such as "3000", and try to use "odd" numbers such as "3125". We have encountered a couple of situations where a port number with a "nice and round" number was hard-coded in an application instead of being defined in the /etc/services" file. 18 CMVC FAQ: installation o Situation B: dealing with existing families, part 1 We have seen these errors when there is a conflict with the shared memory. We have added some cleaning up code in the stopCMVC sample in CMVC 2.3.0.18. In the meantime, please do the following steps: 1. Ensure that all the CMVC daemons are down: stopCMVC familyName 2. Ensure that there are no "orphan" cmvcd daemons: ps -ef | grep cmvcd If there are "orphan" cmvcd daemons, kill them with "kill -15". 3. Invoke the CMVC Activity Monitor which shows the activity of the CMVC daemons (which at this point there should be none) and performs the cleaning of the shared memory (which is what we are trying to accomplish in this step). monitor 1 Press enter to terminate the monitor command. 4. Restart your family: cmvcd yourFamily 2 5. Verify that the daemons are running: ps -ef | grep cmvcd p. In this example there should be 4 entries with cmvcd. o Situation C: dealing with existing families, part 2 When using an existing family and the situation above is not applicable, then this error may happen when stopping and restarting the cmvcd daemons; the most likely explanation is: What was probably happening was that you tried to restart the daemons, but the nfsmounthelper process was still attempting to do the NFS write. Therefore, the port or socket was already reserved for the communications between server and client. 1. If you have to re-ipl the server to fix the problem because you cannot restart the daemons and could not unmount the filesystem in /tmp. Initial configuration of a new CMVC family 19 2. Then you might have had reasonable luck stopping NFS, perhaps via /etc/nfs.clean. 3. Then "kill -1 1" to kick off the orphaned NFS process that got attached to init when you stopped NFS. 4. Then restart NFS. If using AIX, this can be accomplished by either through SMIT or /etc/rc.nfs. 4.7 CANNOT CREATE DATABASE (MKDB) FOR NEW FAMILY - DB2 SQL1092N QUESTION: I am trying to create a DB2 database for a new CMVC family and when I run the "mkdb" command it comes back with the error: SQL1092N "familyId" does not have authority to perform the requested command. The userid does have the database group "dba" as defined and has the primary GID as 0 (as does all the other families). ANSWER: These are some additional hints on how to setup a family under DB2: 1. Choose a name for your CMVC family, and create an account for that name with the primary group of ID 0 to prevent other groups from accessing files in the CMVC family. For example, the primary group of ID 0 on AIX systems is "system". 2. Find out the group ID for the DB2 instance, for example, the command "id db2inst1" (where "db2inst1" is the account for the DB2 instance) will give: uid=201(db2inst1) gid=200(sysadm1) groups=1(staff) 3. Add the DB2 group ID as a secondary group ID for the CMVC family account. For example, if the group ID of the DB2 database instance owner "db2inst1" is "sysadm1", the sec- ondary group ID of the CMVC family should be "sysadm1". For example, the command "id amstest3" (where "amstest3" is a real CMVC family) will give: uid=208(amstest3) gid=0(system) groups=200(sysadm1) 4. Ensure that the CMVC family name does not contain uppercase characters. This is a restriction from DB2. 5. Ensure that the length of the password must be less than or equal to 18 characters. 20 CMVC FAQ: installation 4.8 ERROR WHEN INFORMIX DATABASE NOT ON-LINE MODE QUESTION: Error when Informix database not On-line mode ANSWER: Below is a copy of a log file generated by mkdb. The log file is placed in the /tmp directory when mkdb encounters an error. This particular error is a result of the fact that the Informix data- base was not in "on-line" mode. Creating the INFORMIX database. 529: Cannot attach to shared memory. 123: ISAM error: no shared memory Error in line 1 Near character position 1 4.9 ERROR WITH NOTIFYD, 0010-063, CHDIR() FUNCTION QUESTION: Error with notifyd, 0010-063, chdir() function ANSWER: If your CMVC family HOME directory does not have the queue sub- directory, notifyd will give you the following error in your syslog file: May 12 19:01:07 case7 notifyd[17037]: 0010-133 /u/tutfam2/queue May 12 19:01:07 case7 notifyd[17037]: 0010-063 Error, No such file or directory, occurred when the CMVC Server/6000 attempted to process the chdir() function. Initial configuration of a new CMVC family 21 22 CMVC FAQ: installation 5.0 DATABASE ISSUES RELATED TO INSTALLATION AND CONFIGURATION For details on how to start and stop the databases, how to backup and restore them, and how to do other system tasks such as adding additional file system space to them, see the following technical report: "CMVC frequently asked questions: handling OEM plat- forms and databases". 5.1 GENERAL NOTES ON SQL STATEMENTS USED IN THE SERVER MANUAL QUESTION: General notes on SQL statements used in the Server manual ANSWER: CMVC supports 4 databases (DB2, Oracle, Informix and Sybase) and unfortunately the SQL syntax for each one of these databases is slightly different and to avoid repetition in the manual, we use in general 1 single case and we assume that the reader is familiar with her/his database. However, in order to aid those CMVC family administrators that are beginners with their data- bases, we are adding the following: o For DB2, you have to add a semicolon at the end of each statement. o For Oracle, you have to add a semicolon at the end of each statement. o For Informix, you have to add a semicolon at the end of each statement. o For Sybase, you do not need to add a semicolon; but you need to use the keyword "go" in order to commit the transaction. 5.2 LIMITATIONS OF CMVC SERVER FOR DB2 QUESTION: Limitations of CMVC Server for DB2 ANSWER: o The DB2 row length limitation of 4005 bytes limits the number of configurable fields which can be added to certain CMVC objects. The File object can have up to 17 configurable fields and Defect and Feature objects can have up to 19 configurable fields. Database issues related to installation and configuration 23 o The CMVC family name cannot contain upper case characters. o The length of the family's password cannot be greater than 18 characters. o The DB2 SQL limitation (SQL0129N) described as: A single SQL statement can reference up to 15 tables. Each table in any view referenced is included in this limit. ... may affect some customized Report queries if subselects are used in the 'where' clause. 5.3 NEW DB2_CODESET AND DB2_TERRITORY VARIABLES QUESTION: New DB2_CODESET and DB2_TERRITORY variables ANSWER: The mkdb CMVC installation utility (which calls mkrmchdf) and the sample profile.db2 were changed to use codeset/territory for DB2 during the creation of a DB2 database for the CMVC family. The new variables are DB2_CODESET and DB2_TERRITORY. In common situations this is not really needed, but when migrating CMVC DB2 families from AIX 3 to AIX 4 it is critical that these variables are in sync: in AIX 3 the default is En_US.IBM-850 but in AIX 4 the new default is en_US.ISO8859-1. If the user does not specify these variables, they will default to the proper value according to the version of AIX. 5.4 WHAT IS THE NUMBER OF DB2 LICENSES FOR A CMVC FAMILY? QUESTION: What is the number of DB2 licenses for a CMVC family? ANSWER: Because the chfield tool needs at least 4 licenses for DB2 (16 is recommended), the following example will show you how many licenses for DB2 are needed to run 10 cmvc daemons: 24 CMVC FAQ: installation 1 license for the notify daemon 4 licenses for chfield 2 licenses for other CMVC tools, such as cmvcarchive, vcPath, etc. 10 one license for each cmvcd daemon. --- 17 Total 5.5 CMVC AND DB2: COULD NOT LOAD LIBRARY LIBDB2.A[SHR.O] QUESTION: I have just installed CMVC 2.3 with DB2. When I try to start the cmvcd daemon I get the following messages: Could not load program cmvcd Could not load library libdb2.a[shr.o] Error was: No such file or directory ANSWER: During the installation of DB2, it is necessary to link the DB2 libraries over to /usr/lib. The user root needs to invoke the command db2/adm/db2ln. The DB2 manual says it is optional but it is indeed required for the CMVC daemon. 5.6 CMVC CANNOT WORK WHEN MORE THAN ONE VERSION OF DB2 ARE PRESENT QUESTION: CMVC cannot work when there are more than one version of DB2 installed in the machine (such as with version 1 and version 2). ANSWER: The following facts are important to keep in mind: o DB2 has a utility called "db2ln" to link the runtime libraries for each particular version. This allows processes to use the LIBPATH to use the proper runtime library. o The CMVC daemons are processes that run with the s-bit in order to get authority to change the user-id of the files and for mounting NFS. Database issues related to installation and configuration 25 o AIX does NOT allow a process that runs with s-bit to use the LIBPATH. o Fact 4: When you combine all the previous facts, the end result is that when you install first DB2 V1 and then DB2 V2 to co-exist, then the CMVC daemons are running with the DB2 V2 executables but with the DB2 V1 libraries because the stuff in LIBPATH is ignored due to AIX !! The workaround is to uninstall or inactivate one of the DB2 ver- sions. In that way, CMVC will see only 1 version of DB2. 5.7 ERROR -818 FROM DB2 QUESTION: The DB2 error -818 happens when doing the following actions with a CMVC family: o Installing a refresh of CMVC on an existing CMVC family. o After migrating a family. o After doing reorg. ANSWER: The infamous DB2 error -818 is due to a feature (which we con- sider to be nuisance because we do not change the database schema) of DB2 which requires that a time stamp that is used by the database must match the time stamp of the executable files from the application and for DB2. To synchronize the time stamp, we have prepared the shell /usr/lpp/cmvc/install/db2bind which invokes the BIND command from DB2. 5.8 HOW MANY CMVC FAMILIES CAN A SINGLE DB2 INSTANCE HANDLE? QUESTION: It seems that the number of CMVC families (databases) per DB2 instance is 8 ( by default): 1. Should I have 8 families per instance? Are there performance ramifications? 2. Should I create a new DB2 instance for every family? 26 CMVC FAQ: installation 3. From other people experience, is there a good ratio of fami- lies per DB2 instance? ANSWER: a. 8 databases per DB2 instance is the default value setting. The DB2 Administration Guide states that you can increase the value, but it also states that other values may need to be changed. Because each database creates its own database global memory, agent private memory, etc. regardless of which instance it is in, it seems that there may not be much performance degradation in using 8 databases per DB2 instance. b. There is no need to create a new DB2 instance for each family. However, you may want to do it in order to separate test databases from production databases and to provide some separation for security reasons (you may want to keep, for example, a payroll database on its own instance). You have to consider that the total configuration parame- ters of a database is a combination of what is configured at the instance level as well as on an individual data- base level. Also, keep in mind that if you are handling a database in one instance and you encounter a bud in DB2 that causes the instance to crash, then all the databases that are running under that instance will crash. c. If you plan to have more than one instance, then, given the above considerations, you should balance the load of the CMVC families across instances. For example, you may put in separate instances, CMVC fam- ilies that may have a lot of activity and use many files, but you could put smaller CMVC families in the same instance. Database issues related to installation and configuration 27 5.9 CONFLICT WITH STOPCMVC WITH NAMES OF DB2 INSTANCE AND CMVC FAMILY QUESTION: We are using CMVC with DB2. We created a new DB2 instance called 'cmvc23'. Next, I created CMVC family called 'cmvc23'(same DB2 instance). I ran "db2start", "cmvcd cmvc23 3" and "notifyd". There are no problems at this point. However, when I ran "stopCMVC cmvc23", besides killing the CMVC notifyd daemon and cmvcd daemons, all the db2 instance's daemons were killed at same time. Is this a bug or not? ANSWER: Your problem is caused by the stopCMVC script and it occurs because the name of the DB2 instance is the same as the family name. The script stopCMVC script uses "ps -ef" to identify the CMVC daemons that are logged, it is possible to misidentify some other processes that have the "cmvc" string in them, such as a user "cmvcdemo", "cmvca" (for user CMVC "A"), "cmvc23", a DB2 instance called "cmvc", etc. You will have to set the DB2 instance with a different name to overcome the problem. 5.10 ADDITIONAL NOTES ON ORACLE 7 QUESTION: Additional notes on Oracle 7 ANSWER: o Due to the elimination in Oracle 7.3 of APIs that are used by CMVC, the CMVC server daemons cannot start when using Oracle 7.3. Thus, we do not support this version of Oracle. o The environment variable ORACLE_PASS is required to start the CMVC daemons; therefore, the information in page 37 for this variable is incorrect, because this variable should not be removed from the .profile file. o ORACLE (Transaction Processing Options) TPO (Runtime) is not an option to install with Oracle 7. Thus, page 8 of the CMVC Server Administration and Installation manual for CMVC 2.3 has a redundant entry. 28 CMVC FAQ: installation Oracle TPO is part of the RDBMS beginning with Release 7 and therefore is not an option to install, and in fact it is automatically installed with Oracle RDBMS. 5.11 MKDB AND ORACLE/INFORMIX ERRORS QUESTION: mkdb and ORACLE/INFORMIX errors 1. I got error "... cannot use system rollback segment for non- system tablespace ..." when I ran mkdb. 2. I got error " ... ISAM error: no more locks ..." when I ran mkdb. ANSWER: 1. When you create a tablespace the first time, you also have to create at least one rollback segment if you do not have a rollback segment other than the system rollback segment. You must include this new rollback segment in the database initialization file e.g. $ORACLE_HOME/dbs/initSID.ora. You must bring the database down then up to pick up this new rollback segment. To store your CMVC tables and indexes into different tablespaces, set the ORACLE_TBLSP and ORACLE_NDXSP environment variables. These tablespaces must have been created prior to running mkdb. The ORACLE command to create a rollback segment is as follows: CREATE ROLLBACK SEGMENT rbs_1; The entry that you have to put in /usr/oracle/dbs/initSID.ora is as follows: rollback_segments=(rbs_1) To store your CMVC/6000 tables and indexes into a different dbspace, set the INFORMIX_DBSP environment variable. This dbspace must have been created prior to running mkdb. Use the tbmonitor command to create a new dbspace. 2. When you install INFORMIX, remember to set the number of locks to at least 3000. When you initialize the parameters for your INFORMIX data- base, if you take all the default values, INFORMIX sets the number of locks to 2000. Database issues related to installation and configuration 29 Use the tbmonitor command option "Parameters" then option "Shared-memory" to change the number of locks to at least 3000. 5.12 CAN THE CMVC SERVER WORK UNDER INFORMIX 6 OR INFORMIX 7 QUESTION: Can the CMVC server work under Informix 6 or Informix 7 ANSWER: The CMVC server can now work under Informix Version 6 and Version 7. It is necessary to add the following new Informix environment variables: export INFORMIXSERVER= export SQLEXEC=$INFORMIXDIR/lib/sqlrm 5.13 INFORMIX 7: NEED TO UPDATE .RHOSTS AND /ETC/HOSTS.EQUIV QUESTION: To avoid the following problem when using the CMVC command "mkdb" to create the database for the family, it is necessary to add the name of the CMVC family in the files $INFORMIX/.rhosts and /etc/hosts.equiv in order to become an Informix trusted user. Creating the Informix database. 956: Client host or user (cmhp3inf@oem-hp03) is not trusted by the server No such file or directory Error in line 1 Near character position 1 ANSWER: In $INFORMIXDIR create/update the .rhosts file and in the system root directory create/update the /etc/hosts.equiv file, for example: /users/informix(99) cat .rhosts oem-hp03.raleigh.ibm.com informix oem-hp03 informix oem-hp03.raleigh.ibm.com cmhp3inf oem-hp03 cmhp3inf Where the second item in each row is the Informix user id (in the first 2 rows) and the CMVC family (in the last 2 rows). 30 CMVC FAQ: installation 5.14 SPECIFY TCP/IP AND NOT SHARED MEMORY FOR SQLHOSTS QUESTION: Specify TCP/IP and not shared memory for sqlhosts ANSWER: To avoid problems with unreleased shared-memory when doing some CMVC tasks, it is critical to NOT use the shared-memory con- nection for the Informix databases and use the TCP/IP connection. For example the file /usr/informix/etc/sqlhosts below shows one correct entry and one incorrect entry (which is commented out): oem_hp03 onsoctcp oem-hp03 online3 # oem_hp03 onipcshm oem-hp03 online3 5.15 PROBLEM WHEN USING UNBUFFERED SETTING FOR DATABASE LOGGING IN INFORMIX QUESTION: Problem when using unbuffered setting for database logging in Informix ANSWER: A customer reported problems using the Informix database when the setting for the database logging was "unbuffered". This causes the transactions to hang. To avoid this situation the setting must be "unbuffered ANSI". 5.16 INFORMIX: INCREASE LOGICAL LOGS TO AVOID PROBLEMS WITH LEVEL -CHECK QUESTION: Informix: increase logical logs to avoid problems with Level -check ANSWER: You might need to increase the size of the logical logs (which may need to be greater than 4MB) to avoid a problem with Level Database issues related to installation and configuration 31 -check, which may fill up the logical logs if the logs are not big enough. If these logical logs are filled up, the symptom from CMVC is: 0010-256 An error occurred when the CMVC server software tried to process function txLevelCheck. It is possible that the network or CMVC server is experiencing problems. 32 CMVC FAQ: installation 6.0 CONFIGURABLE FIELDS 6.1 WHAT ARE SOME OF THE CHARACTERISTICS OF THE CONFIGURABLE FIELDS? QUESTION: What are some of the characteristics of the configurable fields? ANSWER: o New fields are always appended to the last column of the table. o Database views are updated with the newly created fields: - For Defect - DefectView - For Feature - FeatureView - For File - FileView - For User - none (there is no view for User) o Config fields access added to command lines after cmvcd is restarted. o Config fields access added to GUI after family is switched or the GUI is restarted. 6.2 USING CHFIELD TO ADD A NEW CONFIGURABLE FIELD WITH SELECTION VALUES QUESTION: How to use chfield to add a new configurable field to Defects whose values will be selected from a list of choices? ANSWER: Scenario: To create a new configurable field for Defects called "answerCancel" whose values must be chosen from a set of values (that is, it does not have a free form). This new configurable field should not be present when opening a defect, and should be Configurable fields 33 shown only during the modification of it. The stanza and table reports should be updated to reflect the new field. Sequence of tasks: Unfortunately the CMVC terminology may be a bit confusing at the beginning: o If you want the user to fill in a CMVC field by selecting from a set of values, then you have to use the configurable values which are specified in the file config.ld and loaded into the database by using the chcfg utility. Some examples are the prefix and the severity fields for Defects. o If you want to add a new field in Defect, Feature, File or User, then you have to use the command chfield to add and modify the field. Also, you can select to have the new field to use configurable values from config.ld. Follow these instructions to add a new configurable field to Defects: 1. Stop the CMVC family by using: stopCMVC familyName 2. Because the desired field will have values that are NOT free form, and which need to be chosen from a set of values, it is necessary to create this set of values first in the file config.ld a. Logon into the CMVC family administrator account. b. Edit the config.ld file and add the entries for the new field "answerCancel", such as: answerCancel|as_designed|no|0|0|"The program works as designed" answerCancel|limitation|no|0|0|"The problem is a current limitation" c. Save the file and then reload the new contents of the config.ld into the database tables by using the CMVC utility: chcfg 3. Use the chfield command to add the new configurable field. a. Enter: chfield -object Defect 34 CMVC FAQ: installation Then you will see the menu: Select one of the following actions: 1. Create a configurable field 2. Modify a configurable field 3. Update stanza and table reports 4. Display HELP 5. Exit Please enter command number: 1 b. Select 1 to create a new field: The Field Label is shown in the dialogs, and the Title label is shown in the column headers in the window lists. Thus, you can add spaces and colons to the string in Field Label (such as Answer Cancel:), but to avoid con- fusion with other column headers, it is recommended NOT to add spaces into the Title (such as AnswerCancel). You have selected to create a new field. Enter DB Column Name: answerCancel Enter CMD Attribute: answerCancel Enter Field Label: Answer Cancel: Enter Title: AnswerCancel Is it an attribute for "Create" action (n): n Enter the field type: answerCancel *New field properties: Active DB Column Name CMD Attribute Field Label Title Create Required Type yes answerCancel answerCancel Answer Cancel: AnswerCancel no no answerCancel Do you wish to commit the change (y)? c. Type "y" to commit the change: Active DB Column Name CMD Attribute Field Label Title Create Required Type yes answerCancel answerCancel Answer Cancel: AnswerCancel no no answerCancel *Checking the columns in the Database ... *Check completed d. The menu will be displayed again. Select 3 to update the stanza and table reports to add the new field: Configurable fields 35 Select one of the following actions: 1. Create a configurable field 2. Modify a configurable field 3. Update stanza and table reports 4. Display HELP 5. Exit Please enter command number: e. The appropriate template files will be shown to you by using the "vi" editor. Edit the files (only the relevant portions of the files will be shown here, and the *** characters will be shown to show the new stuff, but these marking characters should NOT be part of the file. # StanzaViewFormat prefix %s name %s reference %s abstract %s duplicate %s answerCancel %s *** new *** state %-25.25s severity %-25.25s age %ld ... # StanzaViewColumn prefix,name,reference,abstract,duplicate,answerCancel,state,severity,age,... ************ # TableViewFormat %-4.4s %-15.15s %-15.15s %-8.8s %-8.8s %-8.8s %-3.3s %-3.3ld %-55.55s %-15.15s ******** # TableViewColumn prefix,name,compName,state,originLogin,ownerLogin,severity,age,abstract,answerCancel ************* # TableViewHeader pref name compName state originLo ownerLog sev age abstract answerCancel **************** ---- --------------- --------------- -------- -------- -------- --- --- -------- ----------------------------------------------- ---------------- **************** f. From the menu, select 5 to exit. 36 CMVC FAQ: installation Select one of the following actions: 1. Create a configurable field 2. Modify a configurable field 3. Update stanza and table reports 4. Display HELP 5. Exit Please enter command number: 5 4. Start the cmvc daemons: cmvcd yourFamily 2 5. From the CMVC client issue the command: Defect -configInfo You should be getting something like this: Attribute Name DB Column Name Create/Required Type --------------- --------------- --------------- --------------- answerCancel answerCancel no /no answerCancel This command is used by the CMVC GUI to find out which configurable fields to use. 6. Now test the change by using the CMVC GUI to do the fol- lowing: a. Invoke the create defect dialog to verify that the new field is not show there. b. Invoke the modify defect dialog to verify that the new field is shown at the bottom. Select a value, such as "limitation" for this new field. Submit the change. c. Refresh the window list for Defects, and verify that the column AnswerCancel is shown, and that there is one entry that has the value "limitation" from the step above. d. Select the defect and show the details. Verify that there is an entry for the new field, such as: prefix c name 6 reference abstract testing new variables duplicate answerCancel limitation ************************ state verify severity 2 age 0 Configurable fields 37 e. Issue the following command (if you have a large amount of defects, you can use a query that will show you a smaller set of defects) report -view DefectView -where "1=1" -table The results may look like this (the width has been short- ened to fit the entries in a single row): pref name compName state originLo ownerLog sev age abstract answerCancel ---- ---- ----------- -------- -------- -------- --- --- -------- ---------- c 1 test-play closed rivera rivera 2 000 test def c 2 test-play closed rivera rivera 1 000 adding m d 3 test-import working rivera rivera 4 000 test imp c 6 test-play verify rivera rivera 2 000 testing limitation 4 records selected To see how to create a new configurable field that has "free- text" form, instead of selecting the value from a list of choices, see 6.3, "Using chfield to add a new configurable field with "free-text"." 6.3 USING CHFIELD TO ADD A NEW CONFIGURABLE FIELD WITH "FREE-TEXT" QUESTION: How to use chfield to add a new configurable field to Defects whose values are "free-text" and which will not be selected from a list of choices? ANSWER: See 6.2, "Using chfield to add a new configurable field with selection values" on page 33 for the details of the overall process. However, you will need to just press enter at the question of "Enter the field type: " (that is, leave it blank). In that way the value for this field will be "free-text" when the user fills it in. Of course, there are limitations, such as no space blanks, but you can use underscores: this_is_an_example. 2) Select 1 to create a new field: You have selected to create a new field. Enter DB Column Name: answerCancel Enter CMD Attribute: answerCancel Enter Field Label: Answer Cancel: Enter Title: AnswerCancel 38 CMVC FAQ: installation Is it an attribute for "Create" action (n): n Enter the field type: **** leave it blank, just press enter *** *New field properties: Active DB Column Name CMD Attribute Field Label Title Create Required Type yes answerCancel answerCancel Answer Cancel: AnswerCancel no no ******* this field (Type) should be blank ***** 6.4 WHAT ARE THE FILES RELATED TO CHFIELD? QUESTION: What are the files related to chfield? ANSWER: The following files in $CMVC_HOME/install are related to chfield: o mkdb - From the mkdb file, chfield determines what database is used for the family. o ConfigFieldHelp - Help file for chfield o DefectConfigTbl.default and DefectConfigFormat.default - Shipped default configurable field files for Defect. - These files will be loaded to $HOME/$CMVC_FAMILY/configField if mkdb -d is run. o FeatureConfigTbl.default and FeatureConfigFormat.default - Shipped default configurable field files for Feature - These files will be loaded to $HOME/$CMVC_FAMILY/configField if mkdb -d is run. o DefectConfigDBTemplate, FeatureConfigDBTemplate, FileConfigDBTemplate and UserConfigDBTemplate - chfield uses these file as the base to update the object database view for the newly created configurable fields. Configurable fields 39 6.5 HOW TO REPLICATE THE CONFIGURABLE FIELDS FROM ONE FAMILY TO ANOTHER QUESTION: How can I replicate the configurable fields from one family to another? ANSWER: Scenario: I have 2 families in the same host, and I just created several configurable fields using chfield in family-A and now I want to have family-B with the same configurable fields. I would like to avoid retyping the configurable field stuff for the family-B, is there a quicker way? Procedure: If you want the family-B to have EXACTLY the same configurable fields as family-A, then you can do the following: 1. Copy all the files from the directory configField from family-A into the directory configField in family-B. 2. Run the command: chfield -object Defect -source family-B 3. Repeat the previous step for Feature, File and User (when applicable). NOTE: The above procedure works only when duplicating EXACTLY the configurable fields from one family to another. If you want to change the order of the fields, or just adding some but not all the configurable fields from the other family, it is better to add manually all the desired configurable fields and do not follow the procedure mentioned above. For more details, see section "Running the chfield program with the -source Option" in page 52 of the CMVC 2.3 Server Administration manual. 6.6 HOW TO DISABLE A CONFIGURABLE FIELD? QUESTION: How to disable a configurable field? ANSWER: o Stop the CMVC family daemons. 40 CMVC FAQ: installation o Use chfield program. o Mark the active flag to 'no'. o Exit from chfield. o Restart the cmvcd daemons. Some important facts to know about this process: o The column in the database table will not be deleted. o Configurable fields access is withdrawn from command lines after cmvcd is restarted. o Configurable fields access is withdrawn from the GUI after family is switched or the GUI is restarted. 6.7 HOW TO RETRIEVE INFORMATION ABOUT THE CONFIGURABLE FIELDS? QUESTION: How to retrieve information about the configurable fields? ANSWER: You can obtain information about the configurable fields in your CMVC family by doing the following: o Use the -configInfo option from the appropriate object command to show the characteristics of the configurable fields: - Defect -configInfo - Feature -configInfo - File -configInfo - Use -configInfo Only the active configurable fields are shown 6.8 I ADDED A NEW CONFIGURABLE FIELD BUT THE REPORT DOES NOT INCLUDE IT, WHY? QUESTION: I added a new configurable field but the report does not include it, why? ANSWER: When you add a new configurable field, chfield does not automat- ically add that new field in the stanza report, nor in the table report because chfield does not know where you want to place the configurable field in the layout of the report. Configurable fields 41 You need to select the option in chfield that allows you to modify the report formats in order to specify where you want the field to be displayed. 6.9 HOW TO CONFIGURE REPORTS IN CMVC? QUESTION: How to configure reports in CMVC? ANSWER: The following report formats can be configured for Defects, Fea- tures, Users and Files: o Stanza report format. o Table report format. The configuration is done by means of the "chfield" command: o chfield verifies the report format file. o If no previous report format defined, chfield starts with the default formats. o chfield invokes the vi editor. o chfield verifies the user's new configurations, format and column names. o chfield saves the new configuration into the system file. The following files are used to keep the report format: o For Defect - $HOME/$CMVC_FAMILY/configField/DefectConfigFormat o For Feature - $HOME/$CMVC_FAMILY/configField/FeatureConfigFormat o For File - $HOME/$CMVC_FAMILY/configField/FileConfigFormat o For User - $HOME/$CMVC_FAMILY/configField/UserConfigFormat The layout of the report format files is as follows: o For Stanza Report - StanzaViewFormat 42 CMVC FAQ: installation Stanza format described in C Language syntax - StanzaViewColumn The database column names appear in the same order as described in StanzaViewFormat o For Table Report - TableViewFormat Table format described in C Language syntax - TableViewColumn The database column names appear in the same order as described in TableViewFormat - TableViewHeader Header description for table report Keep in mind the following information about the raw format report: o The raw format report is not configurable. o Raw format consist of two portions: - Fixed Portion - system predefined information. - Configurable Fields Portion - configurable fields infor- mation. Configurable Fields Portion is appended to the end of the Fixed Portion o The configurable fields information is organized in the same order as the -configInfo report 6.10 CHFIELD: HOW TO FIX AN INVALID DATABASE COLUMN NAME QUESTION: chfield: how to fix an invalid database column name ANSWER: 1. Execute chfield and verify the properties of the configurable fields: Configurable fields 43 o If fields are not found or properties are not set prop- erly, create the fields or modify the properties, and restart the cmvc daemon. o If field properties appear to be fine, exist from chfield and restart the cmvc daemon 2. If problem persists, run: chfield -object objectName -source familyName -s This command checks the consistency of the database table with the system generated configurable field files. The database table will be updated if any inconsistency has occurred 6.11 CHFIELD: HOW TO FIX A REPORT WITH DATABASE ERROR QUESTION: If you encounter reports with the following database errors: o Error 0010-256: An error occurred when the CMVC server soft- ware tried to process function %1$s. o Error 0010-061: Database error, %1$d (invalid column name), has occurred. If the error is a result of an invalid column name, then check the syntax of the command. ANSWER: It is important to notice that: o chfield checks and validate the column names input to the ConfigFormat files. o Possibly the file has been changed manually by the system administrator. You could try do the following: o Run chfield and select update report action. o chfield will indicate what is wrong o Modify the file accordingly and exit chfield. o Restart the cmvc daemon 44 CMVC FAQ: installation 6.12 CAN I CHANGE ANY FIELD TO BE OPTIONAL OR MANDATORY? QUESTION: Can I change any field to be optional or mandatory? Such as changing the Release field for a defect to be mandatory. ANSWER: By definition, only configurable fields can be configured and thus, they are the only ones that can be marked as optional or mandatory. The CMVC administrator has to do this task. However, it is NOT possible to change the non-configurable- fields. 6.13 HOW TO MAKE "RELEASE NAME" MANDATORY WHILE OPENING A DEFECT? QUESTION: ANSWER: The release field in a Defect is not a configurable field. The only way to make it required is to define/create a userExit (DefectOpen 0) that ensures that the field is filled in. 6.14 CANNOT DELETE AN EXISTING CONFIGURABLE FIELD QUESTION: Cannot delete an existing configurable field. ANSWER: Once a configurable field has been created, it is not possible to delete it. However, it is possible to rename some of the attributes for the field, but the DB Column Name cannot be changed. Configurable fields 45 6.15 USE ONLY THE DB COLUMN NAME IN REPORTS QUESTION: Use only the DB Column Name in reports ANSWER: The only field that can be used in the reports, such as the stanza format, is the DB Column Name. If you use other fields, such as Field, Title, they will be ignored and no data will be shown for that field in the report. 6.16 CONFIGURABLE FIELDS ARE NOT SHOWN IN DETAILS VIEW QUESTION: I added 2 configurable fields to Features. These fields are shown in the list of features, but not in the details view for a feature. What should I do to achieve this? ANSWER: You have to use the chfield tool and specify the option to "Update report details.". Then you should modify the Stanza Report format to add the new fields. 6.17 ADDING NEW CONFIGURABLE FIELD IN STANZA VIEW FORMAT QUESTION: I would like to add a new configurable field for Defects on the same line as the "age" field in the Stanza View Report. After trying this, I cannot get the new field to line up with the field above it, as the new field is a string and age is an integer. How can I add this new field in the second column next to "age" and have it line up? For example: the new field is called "due" state %-25.25s priority %-20.20s severity %-25.25s target %-20.20s age %ld due %-20.20s ANSWER: Try the following: 46 CMVC FAQ: installation state %-25.25s priority %-20.20s severity %-25.25s target %-20.20s age %-25.1ld due %-20.20s 6.18 CREATE AND REQUIRED FIELDS FOR FILES USING CHFIELD QUESTION: I am trying to add a configurable field to Files. I have modi- fied and reloaded the config.ld to add the choices I want, but when I run chfield -object File, I do not get the option to specify Create or Required. What is causing this? ANSWER: The configurable fields for Files are different than the rest. You can specify only a field for the modify action but not for the create one. One important limitation to keep in mind for Files is that the values for the configurable fields for Files are lost when linking files from one release to another. 6.19 DB2, MAXIMUM NUMBER OF CONFIGURABLE FIELDS IS 17 FOR DEFECT/FEATURE QUESTION: In DB2 the maximum number of configurable fields is 17 for Defect/Feature. ANSWER: Although the CMVC Server manual says that the limit on active configurable fields for Defect and Feature objects is 19, in reality the limit is 17. However, you can have more than 17 configurable fields (such as 30), but only 17 can be active at a time. Configurable fields 47 6.20 DB2 ERROR SQL1040N DURING CHFIELD QUESTION: When using chfield, it might be possible to reach the limit of the maximum number of DB2 applications, and therefore the fol- lowing message will be displayed: SQL1040N The maximum number of applications is already connected to the database. SQLSTATE=57030 ANSWER: Increase the "maxappls" parameter for the database: 1. Login as the DB2 instance owner. 2. Invoke "db2adm" 3. Select "System database directory" 4. From the "System database directory" window select the data- base in question (same name as the CMVC family). 5. From the menu bar, select "Local database" then "Configure". 6. From the "Configure Database" window, increase the number for "maxappls". 7. Exit db2adm. 8. Make sure that the cmvc daemons and other tools that use the CMVC family database are disconnected. 9. Stop the database: db2stop 10. Restart the database: db2start 6.21 ORACLE PAUSE STOPS THE EXECUTION OF CHFIELD QUESTION: Oracle pause stops the execution of chfield ANSWER: The default Oracle options may be set in the file $ORACLE_HOME/glogin/sql. If one of these options is "SET PAUSE ON", the query issued by chfield to get the columns in a table is truncated. Thus, chfield does not see all of the columns in the table and attempts to add a column which is already there. This 48 CMVC FAQ: installation can be avoided by including the directive "SET PAUSE OFF" in the Oracle instructions. 6.22 ONLY 10 CONFIGURABLE FIELDS CAN BE HANDLED WITH SYBASE QUESTION: When I try to add more than 10 configurable fields in a CMVC family that uses Sybase, I get an error 416 from Sybase. ANSWER: There is a limitation on the number of configurable fields that a CMVC family can have when using Sybase. The maximum number is 10 for object. Note that the combination of the configurable fields for defects and features should be 10 because both objects in reality use the same database table. Configurable fields 49 50 CMVC FAQ: installation 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 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 51 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. 52 CMVC FAQ: installation 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 53 54 CMVC FAQ: installation 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/6000, DB2 | | | TeamConnection | | +---------------------+-------------------------------------------+ | PostScript | Adobe Systems Incorporated | +---------------------+-------------------------------------------+ | HP-UX | Hewlett-Packard Company | +---------------------+-------------------------------------------+ | Informix | Informix Inc. | +---------------------+-------------------------------------------+ | Microsoft | Microsoft Corporation | | Windows | | +---------------------+-------------------------------------------+ | Oracle | Oracle Corp. | +---------------------+-------------------------------------------+ | NFS | Sun Microsystems Inc. | | SunOS | | | Solaris | | +---------------------+-------------------------------------------+ | Sybase | Sybase Inc. | +---------------------+-------------------------------------------+ | UNIX | X/Open Co., Ltd. | +---------------------+-------------------------------------------+ END OF DOCUMENT Appendix B. Copyrights, Trademarks and Service marks 55