CMVC 2.3.1 Source Code

Simplified instructions on how to build the source code of CMVC and package the compiled code

*** Document data

Author:		Angel Rivera
			IBM CMVC Support Team
			IBM Software Solutions
			Research Triangle Park, North Carolina, USA.

Date last updated:	31-Oct-2001

Location of this document: 

a) External FTP site for CMVC:
	ftp://ftp.software.ibm.com/ps/products/cmvc/doc/tr/BuildSourceCode.rtf
b) Host "angel.raleigh.ibm.com"
	d:\work\cmvc\extended support\BuildSourceCode.rtf
c) See the corresponding entry in the VisualAge TeamConnection Tips Database.

*** Purpose of this document

The purpose of this document is to describe in a simplified manner, how to build the CMVC source code and to package the compiled code.

*** Auxiliary technical reports

The following technical reports (TRs) describe all the details on how to build, package and test the CMVC code. 

- “Building and packaging the CMVC Server/Client for UNIX”
  The URL for the PDF version (needs Acrobat Reader) is:
	ftp://ftp.software.ibm.com/ps/products/cmvc/doc/tr/trbldcmz.pdf

The purpose of this technical report is to provide a real example of the use of CMVC for developing, maintaining, building and packaging the CMVC Server and Client (line commands and GUI) for UNIX, which encompasses several operating systems and database management systems. It mentions the software requisites to build the CMVC code, as well as recommendations on the directory structure and commands actually used to build the code.

Editorial Comment:
 
However, the TR on Build/Packaging is too specific to our site, in which we needed to compile the code for different operating systems, different DBMSs and different hosts. Even though it is recommended to browse this TR because is a good reference for the build and packaging processes, this TR may give too many details that might not be relevant to your site. Therefore, this document was created to show the simplified version of the build and packaging processes.

- “Using Korn shell scripts to perform function test of CMVC  (a Unix client/server application)”
    The URLs are:
   a) PDF version, needs Acrobat Reader:
	ftp://ftp.software.ibm.com/ps/products/cmvc/doc/tr/trfvtksx.pdf
   b) Zip file with the tools described in the TR:
	ftp://ftp.software.ibm.com/ps/products/cmvc/doc/tr/trfvtksx.zip

This technical report provides recommendation on how to use Korn shell scripts to perform a function testing of the CMVC server and line commands in Unix. This type of information might be of interest to testers in general, even if they are not familiar with CMVC. This document concentrates on a set of scripts that perform a limited function testing of CMVC. Specifically, each CMVC line command is tested at least once, based on the most common usage scenario.

These test cases do not test the error messages, that is, they do not try to show that all error messages are eventually displayed; however, the scripts need to capture the situation when a line command fails to execute correctly. Also, the scripts rely in the return code of the executables; thus, this approach is not suitable for GUI applications.

Editorial Comment:
 
By the way, the testing process described in the TR is still applicable.

*** Assumptions

It is assumed that the source code for CMVC has been stored in a CMVC family using the recommended release names and component names, as mentioned in the document “SetupSourceCode.rtf”:

“CMVC 2.3.1 Source Code: How to setup a CMVC Build user id and to store the source code into a CMVC family”

The recommended component names are:
•	cmvcCS: to store the source code for the Client (line commands) and Server
•	cmvcGUI: to store the source code for the GUI
•	cmvcInst: to store the installation utilities
•	cmvcTools: to store miscellaneous tools.

The recommended release names are:
•	cs231: to store the source code for the Client (line commands) and Server
•	gui231: to store the source code for the GUI
•	inst231: to store the installation utilities
•	tools231: to store miscellaneous tools

It is also assumed that the appropriate Software Development Kit (SDK) or corresponding application development components for the operating system and the DBMS have been installed.

Starting with CMVC 2.3.1.1, the CMVC line commands do not longer use the licensing services from the NetLS server. Thus, it is important to specify the build option of not using NetLS:

COMPILEOPT=noNetLS

*** Verify the directory structure for the CMVC Build user id

The $HOME directory for the CMVC Build user id is assumed to be /home/build. It might be possible that in Solaris the actual directory is /export/home/build; thus, if you use Solaris, when you see /home/build in this document, translate it to /export/home/build.

During the setup of this build user id, the following directory structure should have been created:

$HOME/bin	=>  tools from the release tools231
$HOME/tardir	=> temporary directory used during the packaging steps.
$HOME/lpptools	=> AIX only: directory with installp/smit packaging tools
$HOME/cmvc231	=> directory for the CMVC 2.3.1.x code
$HOME/cmvc231/cs	=> TOP directory to build the line commands and server
$HOME/cmvc231/gui	=> TOP directory to build the Motif GUI
$HOME/cmvc231/inst	=> directory that has the packaging utilities

*** Install the proper C compiler

As user root, ensure that the appropriate C compiler is installed. Some specific examples are shown below:

AIX 4.2.1:
File set: xlC.C 	Version: 3.1.4.6	Description: C for AIX Compiler, Version 3.1.4.6
$ which xlc
/usr/bin/xlc@ -> /usr/lpp/xlC/bin/xlC*
$ which cc
/usr/bin/cc@ -> /usr/lpp/xlC/bin/xlC*

For AIX 4.3.x:
Notes: 
- Cannot build the GUI code in AIX 4.3.x, because the include libraries for X11R5 are not included.
- Changes need to be done to the CMVC source code and makefiles, to compile under AIX 4.3.x.

Solaris 2.6:
$ which cc
/opt/SUNWspro/SC4.2/bin/cc

*** Create necessary links

In order to have a common interface for the build process, in some cases it is necessary to provide symbolic soft links between the actual path for the databases/tools and the paths used inside the make files.

To do these links, it is necessary to execute the following command as root:
	ln -s <actual-path> <desired-path>

NOTE: The actual-path (source) values shown in this document are the ones that apply to our environment. The desired-path (target path) should be the ones shown below.

- AIX with Oracle 7.3.4:
ln  -s  /disk2/u1/app/oracle/product/734  /usr/oracle73

- HP-UX with Informix 7:
ln  -s  /users/informix  /usr/informix

- Solaris with Sybase 11:
mkdir /usr/db
ln -s /export/home/sybase /usr/db/sybase

*** Compiling the Motif GUI code

Let’s start with the compilation of the Motif GUI code. The reason is that it is faster to compile than the line commands and the server. Also, it does not require any special setup for the DBMS.

- Login as the CMVC Build user id, “build”, into the specific system to use.

- Change the directory to the desired combination (this will be known as the “top directory” for the build), such as:

	cd $HOME/cmvc231/gui

- Delete "rm -fr" the appropriate top directory, such as:

	rm -fr $HOME/cmvc231/gui

- Do a full extract (attribute: -full) of the latest committed level, such as 1. You need to specify the command in one single line.

Level  -extract 1 -release gui231   -full  -node host-1 -root /home/build/cmvc231/gui   -uid 210 -gid 222 -dmask 777 -verbose

- (If doing additional development) Do a delta extract of the current non-committed level, such as 2 (notice that the “-full” flag is not specified).

Level  -extract 2 -release gui231          -node host-1 -root /home/build/cmvc231/gui   -uid 210 -gid 222 -dmask 777 -verbose

- Change the file permissions of  the file “qmake” to make it executable:

	chmod 755 qmake

- Modify manually the contents of qmake to use the appropriate options, such as the following. You can read the comments in this file to find out the purpose and the valid values for these options.

For Solaris 2.6:

export PLATFORMOPT=solaris         
export PLATFORMSTR=STR_Solaris26   
export BUILDOPT=stal               
export FLAGS="-D$PLATFORMSTR"
export X11R=.x11r5.solaris26        

For AIX 4.2.1:

export PLATFORMOPT=ibm                                                
export PLATFORMSTR=STR_AIX421
export BUILDOPT=stal                                                  
export FLAGS="-D$PLATFORMSTR"                                         
export X11R=.x11r5

For AIX 4.3.x:
Notes: 
- Cannot build in AIX 4.3.x, because the include libraries for X11R5 are not included.
- Changes need to be done to the CMVC source code and makefiles, to compile under AIX 4.3.x.

Notes:
- The PLATFORMSTR value is only used to add the serviceability strings into the executable code, in order for the "what" command to get them. These values do not affect the compilation of the application.
- Please notice that the value for BUILDOPT must be “stal”, which is for the “standalone” version of the CMVC client; that is, not the integrated version for the obsolete Softbench product.

- A bit of explanation of the make files might be helpful:

+ The qmake file is a front end to the makefile specified below:

	make -f $PLATFORMOPT/$BUILDOPT/Makefile$X11R FLAGS="$FLAGS"

+ There is an intermediate make file for the appropriate combination of operating system and build-option (stal for standalone). For example:

For AIX 4.2.1:
	ibm/stal/Makefile.x11r5

For Solaris 2.6:
	solaris/stal/Makefile.x11r5.solaris26

+ The intermediate makefile calls the platform-independent makefile:
	cmvctarget.mk

+ The results of the compilation, including error messages, are stored in a file called: 
	nohup.build

+ There is no need to invoke “qmake ship” because the directory structure for building the Motif GUI for CMVC is simple.

- Known build warnings for Solaris:
  + During the compilation of utilities.c, ignore the warnings:
"./hour.h", line 11: warning: initializer does not fit or is out of range
"./hourMask.h", line 11: warning: initializer does not fit or is out of range

- By following these instructions up to this point, only the Motif GUI for CMVC has been built. In order to package the complete client for CMVC, it is necessary to build the line commands.

- Proceed to build the line commands and the server code.

*** Compiling the line commands and server code

- Login as the CMVC Build user id, “build”, into the specific system to use.

- Change the directory to the desired combination (this will be known as the “top directory” for the build), such as:

	cd $HOME/cmvc231/cs

- Delete "rm -fr" the appropriate top directory, such as:

	rm -fr $HOME/cmvc231/cs

- Do a full extract (attribute: -full) of the latest committed level, such as 1. You need to specify the command in one single line.

Level  -extract 1 -release cs231   -full  -node host-1 -root /home/build/cmvc231/cs   -uid 210 -gid 222 -dmask 777 -verbose

- (If doing additional development) Do a delta extract of the current non-committed level, such as 2 (notice that the “-full” flag is not specified).

Level  -extract 2 -release cs231          -node host-1 -root /home/build/cmvc231/cs   -uid 210 -gid 222 -dmask 777 -verbose

- Change the file permissions of  the file “qmake” to make it executable:

	chmod 755 qmake

- Modify manually the contents of qmake to use the appropriate options, such as the following. You can read the comments in this file to find out the purpose and the valid values for these options.

For Solaris 2.6 with Sybase 11:

PLATFORMOPT=solaris        
PLATFORMSTR=STR_Solaris26  
DATABASEOPT=sybase         
DATABASESTR=STR_SYBASE11     
BUILDOPT=all # that is, both server and line commands
COMPILEOPT=noNetLS # that is, do not include the NetLS code

For AIX 4.2 with Oracle 7.3.4:

PLATFORMOPT=AIX4
PLATFORMSTR= STR_AIX421
DATABASEOPT=oracle73
DATABASESTR=STR_ORACLE734
BUILDOPT=all # that is, both server and line commands
COMPILEOPT=noNetLS # that is, do not include the NetLS code

Note: The PLATFORMSTR and DATABASESTR values are only used to add the serviceability strings into the executable code, in order for the "what" command to get them. These values do not affect the compilation of the application.

- Start the build and monitor its progress. By default, the action for qmake is “build”:

	qmake

+ The qmake file is a front end to “MAKE.cmvc” which uses other makefiles.

+ There is an intermediate make file for the appropriate combination of operating system and DMBS. For example:

For Solaris 2.6 with Sybase 11:
	Make.sybase.solaris

For AIX 4.2.1 for Oracle 7.3.4:
	Make.oracle73.AIX4

+ The results of the compilation, including error messages, are stored in a file called: 
	nohup.build

+ For your information: the last directory to be processed during the build is “samples”.

- In some cases when compiling in Solaris, there could be some compilation errors that may require manual intervention. The workarounds are known and easy to apply manually, but there is no way to automate them. See the TR on Build for details, specifically the section “Known building problems”, sub-section “If the build fails for Solaris”.

- After the compilation is done, copy the shippable code into the "ship" directory (such as $HOME/cmvc231/cs/ship). This directory is very similar to the directory where the code will be installed at the customer machine. This ship directory will be the location that the CMVC packaging utilities will pick up the code. This step is needed because of the complex directory structure for the line commands and server for CMVC code.

	qmake ship

- Proceed to package the code.

*** Update the packaging utilities to reflect your directory structure

The makefiles that are used during the packaging step reflect the directory structure prevalent in the CMVC development machines at IBM. However, to reduce confusion, the directory structure mentioned in this document has been simplified for customer usage, and thus, the makefiles need to be updated to reflect these changes.

- There are 4 variables that you need to change in the makefiles:

BUILDER_DIR => this is the TOP directory where the line commands and server were compiled

MKTAR_DIR   => this is a temporary directory used by the installation utilities.
If you used “tardir” during the setup, then there is no need to modify it.

INSTALL_DIR => this is the directory that has the installation utilities

SA_GUI_DIR  => this is the TOP directory where the Motif GUI was compiled (the standalone version). This variable is needed ONLY when packaging the client code.

- Because the SoftBench Integrated version of the CMVC GUI is obsolete, there is no need to specify the variable INT_GUI_DIR when packaging the client.

- As the CMVC Build user id, checkout the appropriate files from the CMVC family, release inst231:

+ For Solaris:

Makefile.SOLARIS.client	  # It packages both the Motif GUI and the line commands

	The lines to modify are the following:
Current:
	BUILDER_DIR = /export/home/build/cmvc231/solaris/cs/sybase11
	MKTAR_DIR   = /export/home/build/tardir                     
	INSTALL_DIR = $(BUILDER_DIR)/../../../installp              
	SA_GUI_DIR  = $(BUILDER_DIR)/../../gui/x11r5/stal           

They have to be changed to reflect your site, such as:
	BUILDER_DIR = /export/home/build/cmvc231/cs/
	MKTAR_DIR   = /export/home/build/tardir                     
	INSTALL_DIR = $(BUILDER_DIR)/../inst
	SA_GUI_DIR  = $(BUILDER_DIR)/../gui           

Makefile.SOLARIS.sybase		# It packages the server for Sybase 11

	The lines to modify are the following:
Current:
	BUILDER_DIR = /export/home/build/cmvc231/solaris/cs/sybase11
	MKTAR_DIR   = /export/home/build/tardir                     
	INSTALL_DIR = $(BUILDER_DIR)/../../../installp              

They have to be changed to reflect your site, such as:
	BUILDER_DIR = /export/home/build/cmvc231/cs/
	MKTAR_DIR   = /export/home/build/tardir                     
	INSTALL_DIR = $(BUILDER_DIR)/../inst

+ For AIX:

Makefile.AIX4.client	# It packages both the Motif GUI and the line commands

	The lines to modify are the following:
Current:
	BUILDER_DIR = /home/build/cmvc231/aix4/cs/db2v5
	MKTAR_DIR   = /home/build/tardir                     
	INSTALL_DIR = $(BUILDER_DIR)/../../../installp              
	SA_GUI_DIR  = $(BUILDER_DIR)/../../gui/x11r5/stal           

They have to be changed to reflect your site, such as:
	BUILDER_DIR = /home/build/cmvc231/cs/
	MKTAR_DIR   = /home/build/tardir                     
	INSTALL_DIR = $(BUILDER_DIR)/../inst
	SA_GUI_DIR  = $(BUILDER_DIR)/../gui           

Makefile.AIX4.oracle73	# It packages the server for Oracle 7.3.4

	The lines to modify are the following:
Current:
	BUILDER_DIR = /home/build/cmvc231/aix4/cs/oracle73
	MKTAR_DIR   = /export/home/build/tardir                     
	INSTALL_DIR = $(BUILDER_DIR)/../../../installp              

They have to be changed to reflect your site, such as:
	BUILDER_DIR = /home/build/cmvc231/cs/
	MKTAR_DIR   = /home/build/tardir                     
	INSTALL_DIR = $(BUILDER_DIR)/../inst

*** Package the code (tar format)

Now that the Motif GUI, the line commands, and the server have been built, and the packaging utilities have been updated to reflect the appropriate directories, then it is time to package the code into tar files.

- Login as user “root”. This is necessary in order to give the proper file permissions to the executable files to be packaged.

	su - root

- Change to the directory that has the installation utilities:

	cd /home/build/cmvc231/inst

- Invoke the make utility and specify the desired makefile. The result of each invocation will be 2 tar files that will be placed under /home/build/cmvc231/inst/$OPSYS/tar

For the Solaris client (both Motif GUI and line commands)

	make -f Makefile.SOLARIS.client

The resulting files are:

	# Client: line command and Motif GUI
	/home/build/cmvc231/inst/solaris/tar/solstal.tar

	# Message catalog for the client	/home/build/cmvc231/inst/solaris/tar/solstalm.tar  

For the Solaris server for Sybase

	make -f Makefile.SOLARIS.sybase

The resulting files are:

	# Server for Sybase
	/home/build/cmvc231/inst/solaris/tar/solsyb.tar

	# Message catalog for the server	/home/build/cmvc231/inst/solaris/tar/solsrvm.tar  

For the AIX client (both Motif GUI and line commands)

	make -f Makefile.AIX4.client

The resulting files are:

	# Client: line command and Motif GUI
	/home/build/cmvc231/inst/aix4/tar/aix4stal.tar

	# Message catalog for the client	/home/build/cmvc231/inst/aix4/tar/aix4stalm.tar  

For the AIX server for Oracle

	make -f Makefile.AIX4.oracle73

The resulting files are:

	# Server for Oracle
	/home/build/cmvc231/inst/aix4/tar/aix4ora7.tar

	# Message catalog for the server	/home/build/cmvc231/inst/aix4/tar/aix4srvm.tar  

- Logoff from root. Login back to the userid “build”.

- If packaging for AIX, you may want to consider preparing files in installp format, which can be installed via smit. Proceed to the following section.

- If not packaging for AIX, skip the next section and proceed to install the new code in a test machine to test the code.

*** Package the code (installp format for smit in AIX)

- If packaging for AIX, you may want to consider preparing files in installp format, which can be installed via smit.

- Ensure that you are the userid “build” and not “root”.

	cd /home/build/cmvc231/inst

- Edit the following script, which is used to prepare all the installp images:

	vi bld.all.images4

-  Some changes to consider are:

a) Update the following 4 lines to reflect the refresh modification and level, such as: 2.3.0001.0005, where 0001 is the Modification and 0005 is the Level.
                                                         
export    GUIMOD=0001                                      
export GUICOMLVL=0005                                      
                                                           
export    CSMOD=0001                                       
export CSCOMLVL=0005                                       

b) Update the directory:

old:
cd $HOME/cmvc231/installp

new:
cd $HOME/cmvc231/inst

c) Comment out (by adding a # character in the first column) the “bldimages4” commands that are not appropriate for your site, such as DB2. Leave uncommented the bldimages4 commands that you want.

- Once you have edited and saved the script, execute it to actually prepare all the desired installp images:

	bld.all.images4

- Assuming that you only wanted the Client, the Server for Oracle, and the message catalogs, the resulting files are:

	# Server for Oracle
	/home/build/cmvc231/inst/aix4/obj/4ora7.obj

	# Message catalog for the server	/home/build/cmvc231/inst/aix4/obj/4srvm.obj

	# Client: line command and Motif GUI
	/home/build/cmvc231/inst/aix4/obj/4stal.obj

	# Message catalog for the client	/home/build/cmvc231/inst/aix4/obj/4stalm.obj

- Proceed to install the code in a test machine to test the code.

*** Installing the code in a testing machine

Some recommendations to test the code are:
	* Do not use for testing, machines that have production CMVC families.

- Login as root into the testing machine.

- If installing tar images, do the following:

	# Ensure that the umask is 022:
	umask 022

	# Create directory for the CMVC code.
	# The option -p indicates to create parent directory, if needed.
	mkdir -p /usr/lpp/cmvc	
	cd /usr/lpp/cmvc
	
	# Copy the contents from the appropriate directory that 
	# has the tar files.
	# You may use ftp or NFS. This example assumes NFS.
	# The option -p indicates to preserve the file 
	# properties (date).
	# Solaris:
	cp -p /home/build/cmvc231/inst/solaris/tar/*  .
	# AIX:
	cp -p /home/build/cmvc231/inst/aix4/tar/*  .

	# Follow the instructions in README.inst.tar.txt

- If installing AIX installp images, do the following:
	
	# Create a temporary directory for the CMVC code,
	# such as /tmp/cmvc
	mkdir /tmp/cmvc
	cd /tmp/cmvc

	# Copy from the appropriate directory that has 
	# the install files, ONLY those files that you want
	# to install.
	# You may use ftp or NFS. This example assumes NFS.
	cp -p /home/build/cmvc231/inst/aix4/obj/4ora7.obj  .
	cp -p /home/build/cmvc231/inst/aix4/obj/4srvm.obj  .
	cp -p /home/build/cmvc231/inst/aix4/obj/4stal.obj  .
	cp -p /home/build/cmvc231/inst/aix4/obj/4stalm.obj  .
	cp -p /home/build/cmvc231/inst/aix4/obj/README.inst.*.txt .

	# Follow the instructions in README.inst.smit.txt

*** Testing the code

Now that the CMVC code has been installed in the testing machine, you can proceed to perform the Function Verification Test (FVT).

The recommendation is to use the scripts and the methodology explained in the technical report “Using Korn shell scripts to perform function test of CMVC  (a Unix client/server application)”, which is mentioned at the beginning of this document.

The scripts for FVT are stored in the CMVC Build user id, under the $HOME/fvt directory.

If the FVT testing is successful, then proceed with the rest of this document.

*** Check-in updated files back into the CMVC family

If you checked-out some files from the CMVC family, such as the Makefiles used for the packaging process, then you need to check-in those updated files.

*** Making backup copies

After a successful FVT, you may want to make a backup copy of the CMVC family, of the file system of the CMVC Build user id, and of the installation images.

*** Preparing a CD-ROM with the install images

The final step is to create a CD-ROM that has all the appropriate files for the desired operating system.

For Solaris:

Top directory in the CD-ROM	Obtained from:
README.inst.cdrom.txt		/home/build/cmvc231/inst/README.inst.cdrom.txt
tar/*					/home/build/cmvc231/inst/solaris/tar/*

For AIX:

Top directory in the CD-ROM	Obtained from:
README.inst.cdrom.txt		/home/build/cmvc231/inst/README.inst.cdrom.txt
tar/*					/home/build/cmvc231/inst/aix4/tar/*
obj/*					/home/build/cmvc231/inst/aix4/obj/*

The file README.inst.cdrom.txt has the installation instructions on how to install the product from the CD-ROM.

*** end ***