![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
Developing a Program Using Apex/ClearCase Programs written in Ada and/or C/C++ often contain many objects. An Ada and/or C/C++ application typically consists of many interdependent units. Apex is designed to support the development of large, complex systems. Most systems are decomposed, or divided, into subsystems to make them more manageable. Criteria for decomposing systems into subsystems are described in the Concepts Guide.
This chapter shows how to develop a simple program in a single subsystem using Apex/ClearCase. ClearCase, a version control and configuration management tool comes in two flavors: Base ClearCase and UCM. Base ClearCase consists of powerful tools to establish an environment in which developers can work in parallel on a shared set of files, and project managers can define policies that govern how developers work together. UCM is one prescribed method of using ClearCase. More information on ClearCase can be found in Managing Software Project with ClearCase.
Apex/ClearCase assumes you are familiar with ClearCase. A quick review of ClearCase concepts may be found in Appendix B on page 123.
Note: Apex performs all compilation in the context of subsystems, regardless of program size. In order for an element to be controlled in ClearCase, it needs to have its parent root in a VOB. This means that to have a controlled, compiled set of files, they need to be in controlled Rational subsystems which reside in VOB(s). A sample architecture might be
/vobs/my.vob test.rss pck1.1.ada pck1.2.ada proc1.2.ada
About This ChapterThis chapter contains three main sections:
- Creating a Simple Program Using Base ClearCase
- Creating a Simple Program Using UCM
- Additional Apex/ClearCase Operations
Note: The screen captures on your system may appear slightly different than those in this document. Some menus and dialog box fields depend on which options and/or layered products are installed.
Creating a Simple Program Using Base ClearCaseThis section describes how to develop a simple Ada "hello world" program. The ClearCase components, a VOB and a ClearCase View, are created using ClearCase commands directly. Then, using Apex/ClearCase is used to create and use a Rational Subsystem and to develop the program using the steps in Figure 23.
Figure 23 Steps in Creating a Simple Program Using Base ClearCase
![]()
The topics covered in this section are:
- Creating a VOB
- Creating and Activating a ClearCase View
- Starting Apex/ClearCase
- Creating a Rational Subsystem
- Creating an Ada Unit
- Using the Apex Editors
- Compiling and Linking a Program
- Executing a Program
- Updating an Ada Program - Checking Out, Editing, Checking In
Note: The type of program you can create is dependent on which variant of Apex you are using. If you are using Rational Apex Ada, follow the instructions to create the Ada program. If you are using Rational Apex C/C++, follow the instructions to create a C/C++ program. If you are using Rational Apex Duo, you can do either.
Another easy way to become familiar with subsystems and directories is to work through the exercises in the online tutorial, Tutorial which is started by the Help > Tutorial command.
Note: The general discussions of subsystems and the development process in this chapter are applicable to both native and embedded/cross Apex systems. However, due to the inherent complexity of embedded systems, there are additional steps that must be taken to use Apex cross products. These are discussed in detail in "Getting Started" in the following documents:
Creating a VOB
Note: The examples of Creating a VOB and Creating a ClearCase view are provided to get you up and running quickly. To establish your project development environment, please see the ClearCase Administrator Guide for details.
- 1 . Log into the VOB host
- 2 . Choose a location for the VOB storage directory. (/work1/vobstore)
- 3 . Choose a vob-tag for your VOB (/vobs/test). This cannot include symbolic links
- 4 . Login as superuser. create the directory and make it writable:
% su # mkdir /work1/vobstore # chmod 777 /work1/vobstore # exit
- 5 . Create the VOB structure:
% cleartool mkvob -public -tag /vobs/test /work1/vobstore/vob.test Registry password: Comments for "/work1/vobstore/vob.test": VOB for trying out ACCI . VOBs have special data backup considerations. ...- 6 . Mount the VOB
% cleartool mount /vobs/test
- 7 . If you want to verify your VOB, run cleartool lsvob which should list your VOB-tag, the VOB storage directory and the fact it is public.
Note: The VOB stays mounted until you explicitly unmount it with the cleartool umount command.
Note: It is convenient, but not required, to place all of your VOB storage directories in a common directory. If you want to do so, create this new common directory for the ClearCase VOBs first. The VOB storage directory must be accessible to all machines that need to use the Rational subsystems stored in that VOB. VOBs are public or private. If it is public, you need to specify a password that will be used for administrative operations. Making a VOB public requires knowing the registry password specified when ClearCase was installed.
Creating and Activating a ClearCase View
Note: The examples of Creating a VOB and Creating a ClearCase view are provided to get you up and running quickly. To establish your project development environment, please see the ClearCase Administrator Guide for details.
Note: The ClearCase view storage directory must be accessible to all machines that need to use the Rational subsystems stored in that ClearCase view.
A ClearCase view is similar to an Apex/Summit tower in that it selects certain versions of Rational subsystems.
- 1 . Create a ClearCase view (working environment for individual developer or closely coordinated group). You need a view-tag and writable view storage directory. To determine the view access, set your UNIX umask BEFORE creating your view.
% umask 022 # allow all members of our UNIX group to # create and modify view-private data % mkdir $HOME/views % chmod +w $HOME/views % cleartool mkview -tag test_view $HOME/views/test.vws
Note: For ClearCase 4.0 or higher, this command creates a dynamic view. For more information on types of ClearCase views, please see Developing Software with ClearCase and the view reference page in the ClearCase Command Reference.
- 2 . Activate your Clearcase view:
% cleartool setview test_view
Starting Apex/ClearCase
- 3 . If you installed Apex so that it runs with ClearCase by default, start up Apex/ClearCase using
% apexinit
Otherwise (Apex/Summit is the default), start up Apex using
% apexinit -clearcase
Apex displays the Apex ClearCase Panel window and the Welcome help file in the Netscape Browser.
- 4 . Visit your VOB directory to display a directory-viewer window by entering /vobs/test in the Visit field in the Apex ClearCase Panel and clicking the Visit button.
When a directory is visited or opened, Apex/ClearCase opens a directory-viewer window that displays the list of files and directories in your VOB directory.
Directory-Viewer Window
You can use the directory-viewer window to navigate through the directory structure, by visiting any of the listed files and directories.
When using Base ClearCase, the directory viewer displays two special fields at the bottom of the window. The Set View field displays the name of the current ClearCase setview that is in effect. This is fixed for an Apex session and is established before starting Apex. This ClearCase view allows accessing versions of elements as if they were ordinary files using ordinary pathnames.
The Working Directory View is determined from the context of the directory viewer: if the directory viewer is showing a directory located outside a VOB directory, then it show **NONE**; if the directory is located within a normal VOB directory, then label will match the current setview; if the directory is located within a fully qualified path using view extended pathnames, then the working directory view will display the view for the current directory. Please see the ClearCase User's Guide for ClearCase 3.2 or Using ClearCase for ClearCase 4.0 and higher for a detailed explanation of Set View and Working Directory View.
There are two ways to visit an object listed in the directory-viewer window. You can select the object's name and click Visit, or you can double-click the object's name.
You can also issue commands from the directory-viewer window's File menu to load, save, and print files and to execute and debug programs.
Figure 24 Directory-Viewer Window
.![]()
For more information about the directory-viewer window and how to use it, see Using and Customizing the Apex GUI.
Creating a Rational Subsystem
Compilation must be performed in a Rational subsystem. You can create a Rational subsystem anywhere in a directory hierarchy except in another Rational subsystem —— subject, of course, to normal permission restrictions. A Rational Subsystem must be in a VOB to be controlled by ClearCase. Objects in a Rational subsystem can only be controlled if the subsystem is controlled.
Models
One important characteristic of a Rational subsystem is its model. A model is a Rational subsystem or an Apex/Summit view that serves as a prototype for a Rational subsystem. The model provides a base structure of subdirectories, policies (compiler options, target keys, etc., by way of switches), and a base set of Imports. For Ada, a model provides a package standard and built-in Ada packages, such as Text_Io.2.ada. For C/C++, a model provides access to the standard C/C++ library. Apex/ClearCase provides a default model for programs that are compiled and run using the same platform architecture that Apex/ClearCase uses. For more information on Models, see Programming with Apex.
To create the /vobs/test/test.rss Rational subsystem:
- 1 . If not already displayed, open a directory viewer window of /vobs/test using the File > Open command.
- 2 . Select the File > New > New Subsystem menu item.
Apex/ClearCase then opens the New Subsystem dialog box illustrated in Figure 25.
Figure 25 New Subsystem Dialog Box for Ada Development
![]()
- 3 . Enter the full pathname for the new Rational subsystem in the text field labeled Subsystem Full Name.
The pathname must be a fully qualified pathname (a pathname that starts with /). It is not necessary to enter the .rss extension in the text field; Apex/ClearCase adds that extension automatically. For this example, we are using /vobs/test/test.
- 4 . Because we will be creating an Ada program, the Language field should be Ada. Verify the Host Architecture matches the architecture of the machine on which you are running.
- 5 . Make sure the Visit the new subsystem check box is selected.
- 6 . Select the Make it an element option so that this Rational subsystem will be controlled. Any element that is controlled needs the enclosing Rational subsystem to be controlled. If you do not control it now, it will need to be controlled when you control the first element in this Rational subsystem. When you select this option, a Note field will be displayed. Enter a Note to be associated with controlling this element.
- 7 . To create your new Rational subsystem, click OK or Apply.
Creating an Ada Unit
In Apex, the names of Ada source files follow a specific naming convention. The specification of a source file is always the name of the unit with the suffix .1.ada added. Similarly, the body of a source file is always the name of the unit with the suffix .2.ada added.
- 1 . Select the File > New > New Ada menu item from the /vobs/test/test.rss directory viewer.
Apex opens the New Ada dialog box.
- 2 . Reset the option buttons labeled Package and Spec to read Procedure and Body.
- 3 . Enter the name for the procedure you are creating, hello, in the Name text field.
It is not necessary to append the suffix .2.ada (the conventional suffix for an Ada procedure) to the filename you enter. Apex automatically does this.
- 4 . To have Apex open an editing window for your new source file as soon as the file is created, check the Visit it check box.
- 5 . We want this procedure to be controlled under ClearCase, so check the Make it an element check box. This will make the enclosing Rational subsystem, /vobs/test/test.rss, a VOB element in ClearCase. See Rational Subsystems (Apex/ClearCase only) to see what is controlled in the subsystem. ClearCase is described in ClearCase User's Guide.
- 6 . Make sure the Visit it check box is checked. If Visit it is not checked, Apex will not display your new source file in a window when it is created.
- 7 . Click OK or Apply.
This dialog box with the appropriate settings is shown in Figure 26.
Figure 26 New Ada Dialog Box
![]()
The file is created using the appropriate template file which defined the initial contents of this type of file.
Apex then opens an Ada editor window for your new source file as illustrated in Figure 27.
Figure 27 Ada Editor Window
![]()
Using the Apex Editors
The Apex Ada and C/C++ editors are powerful text editors designed specifically for editing Ada and C/C++ source files. They are described in detail in The Ada Editor and The C/C++ Editor chapters in Programming with Apex. The language editor windows resemble another Apex editor window —— the generic Apex text-editing window which is described in The Apex Text Editor chapter of Programming with Apex.
The Apex language editors, like the text editor, contain main buttons for commonly used commands. For example, the Save button duplicates the functionality of the File > Save command, the Search-> button is a shortcut for the Edit > Search menu item, and the Message-> button is a shortcut for the View > Message-> command.
- 1 . To make hello.2.ada editable, click on the Edit check box.
- 2 . Type in the code for hello.2.ada as shown in Figure 28.
Figure 28 Ada Editor Window with hello.2.ada
![]()
Compiling and Linking a Program
Commands for compiling and linking Ada and C/C++ programs are available from the Compile menu.
In Apex, a program is always compiled within the compilation context of its enclosing views. The compilation context of a Rational subsystem encompasses the compiler that is used, the values of the compiler's switches, and any imported Rational subsystems that provide external visibility to the units being compiled.
The Ada, text, and C/C++ editor window's Compile menus offers a selection of commands for semanticizing (Ada only), parsing (Ada only), pretty-printing (Ada only), compiling and linking Ada and C/C++ code in the compilation context of their enclosing Rational subsystems. For this brief example, you are going to use the Compile > Link command that compiles and links a program. For details, see Compiling and Executing in Programming with Apex.
The procedure for linking mixed language programs is essential the same. It is described in more detail in Programming with Apex.
- 1 . If you choose the Compile > Link item from a viewer window, Apex displays the Link dialog box. Note that the name of the selected item will normally be displayed in the Units to Link field.
- 2 . If you choose Compile > Link from an editor window, Apex links the current object using the Link dialog box defaults. Alternately, you can bring up the Link dialog box by selecting Control-Compile > Link.
For more details on the Compile > Link command, see the Online Reference.
Executing a Program
- 1 . To execute a program, select Run from the File menu.
Apex then opens the Run/Debug dialog box illustrated in Figure 29. The Run/Debug dialog box allows you to run a program and to redirect input, output, and error output. You can use the Debug command to run programs under the debugger.
Figure 29 Run Dialog Box-Native Systems
![]()
The Run/Debug dialog box contains text fields in which you can type the name of the program you want to execute, the UNIX arguments (if any) that you want to pass to the program, and the context in which the program will execute. Note that the Run/Debug dialog box is slightly different for native and embedded (cross) systems. Only the Run/Debug dialog for native systems is illustrated here. The Run dialog for embedded systems is described in detail in the Programming with {Rexec, Tornado, LynxOS} manuals.
- 2 . Select OK to use the defaults for the Run command which runs without the debugger.
The Output window will display:
--- execute of /vobs/test/test.rss/hello --- hello world!
You may also choose Tools > Shell to bring up a shell window. In the Window, enter the name of the program to run (hello.exe).
Placing the Program Under Control
If for some reason you did not control your hello.2.ada file in the previous sections, you can control it using the following steps:
- 1 . In the /vobs/test/test.rss directory viewer, select hello.2.ada and execute the CM > Make Element command.
The Place object(s) under ClearCase control dialog box is displayed and is illustrated in Figure 30.
- 2 . If you did not control your Rational subsystem yet, you need to select the Control enclosing subsystem check box or you will not be able to control this object. All controlled objects must be within Controlled Rational Subsystems. Select OK to execute.
Figure 30 Place object(s) under ClearCase control dialog box
![]()
Note: When you control an object, it is also checked in.
Updating an Ada Program - Checking Out, Editing, Checking In
Now we want to update the hello world program. The following steps make a new version of the hello.2.ada file:
- 1 . Execute the CM > Checkout command to check out the file for updating. Use the default options in the ClearCase Check Out dialog box illustrated in Figure 31.
Figure 31 ClearCase Check Out dialog box
![]()
Note: You can also click on the Edit button in the hello.2.ada editor window to display the ClearCase Check Out dialog box.
- 2 . Edit the hello.2.ada file.
- 3 . Execute the CM > Check In command using the default options.
The file is time-stamped when the version is checked in.
Note: You should select the Preserve modification time of objects check box when you are working with Ada files so that Apex/ClearCase does not perform unnecessary consistency check next time it compiles the unit.
You now have a controlled, checked in file on the main branch of an element in a Rational subsystem which resides in a VOB.
Creating a Simple Program Using UCMThis section describes how to develop a simple Ada "hello world" program. UCM is one prescribed method of using ClearCase. The ClearCase components, Project VOB, VOB, ClearCase Views, and Activities are created using ClearCase commands directly. Then, using Apex/ClearCase is used to create and use a Rational Subsystem and to develop the program using the steps in Figure 32. More information on ClearCase can be found in Managing Software Project with ClearCase.
UCM also supports using Rational ClearQuest, a very flexible defect and change tracking system. This example does not use ClearQuest, but more information on linking a ClearCase project with a ClearQuest database can be found in the mkproject page on the ClearCase Reference Manual.
Note: UCM is only available with ClearCase 4.0 and higher.
Figure 32 Steps in Creating a Simple Program Using UCM
![]()
The topics covered in this chapter are:
- Creating a Project in ClearCase
- Starting Apex/ClearCase
- Creating a Rational Subsystem
- Creating an Ada Unit
- Compiling and Linking a Program
- Executing a Program
- Placing the Program Under Control
- Creating a New Baseline
- Joining a Project as an Individual User
- Creating an Activity
- Updating an Ada Program - Checking Out, Editing, Checking In
- Rebase the Integration View
- Rebase Your Working View
Note: The type of program you can create is dependent on which variant of Apex you are using. If you are using Rational Apex Ada, follow the instructions to create the Ada program. If you are using Rational Apex C/C++, follow the instructions to create a C/C++ program. If you are using Rational Apex Duo, you can do either.
Another easy way to become familiar with subsystems and directories is to work through the exercises in the online tutorial, Tutorial which is started by the Help > Tutorial command.
Note: The general discussions of subsystems and the development process in this chapter are applicable to both native and embedded/cross Apex systems. However, due to the inherent complexity of embedded systems, there are additional steps that must be taken to use Apex cross products. These are discussed in detail in "Getting Started" in the following documents:
Creating a Project in ClearCase
Creating a PVOB
Note: The examples of creating a PVOB, a VOB, a project, a ClearCase view and an activity are provided to get you up and running quickly. To establish your project development environment, please see the Administering ClearCase Guide for details.
- 1 . Log into the PVOB host.
- 2 . Choose a location for the VOB storage directory. (/work1/vobstore)
- 3 . Choose a vob-tag for your VOB (/vobs/myproj.pvob). This cannot include symbolic links.
- 4 . Login as superuser. Create the directory and make it writable:
% su # mkdir /work1/vobstore # chmod 777 /work1/vobstore # exit
- 5 . Create the PVOB structure:
% cleartool mkvob -public -ucmproject -tag /vobs/myproj.pvob \ /work1/vobstore/myprojpvob.vbs Registry password: Comments for "/work1/vobstore/myprojpvob.vbs": PVOB for trying out Apex/ClearCase with UCM . VOBs have special data backup considerations. ...- 6 . Mount the PVOB:
% cleartool mount /vobs/myproj.pvob
- 7 . If you want to verify your PVOB, run cleartool lsvob which should list your PVOB-tag, the PVOB storage directory and the fact it is public.
Note: The PVOB stays mounted until you explicitly unmount it with the cleartool umount command.
Note: It is convenient, but not required, to place all of your VOB storage directories in a common directory. If you want to do so, create this new common directory for the ClearCase VOBs first. The VOB storage directory must be accessible to all machines that need to use the Rational subsystems stored in that VOB. VOBs are public or private. If it is public, you need to specify a password that will be used for administrative operations. Making a VOB public requires knowing the registry password specified when ClearCase was installed.
Creating and Activating a ClearCase View
Note: The examples of creating a PVOB, a VOB, a project, a ClearCase view and an activity are provided to get you up and running quickly. To establish your project development environment, please see the Administering ClearCase Guide for details.
Note: The ClearCase view storage directory must be accessible to all machines that need to use the Rational subsystems stored in that ClearCase view.
A ClearCase view is similar to an Apex/Summit tower in that it selects certain versions of Rational subsystems.
- 1 . Create a ClearCase view (working environment for individual developer or closely coordinated group). You need a view-tag and writable view storage directory. To determine the view access, set your UNIX umask BEFORE creating your view.
% umask 022 # allow all members of our UNIX group to # create and modify view-private data % mkdir $HOME/views % chmod +w $HOME/views % cleartool mkview -tag pvobview $HOME/views/pvobview.vws
Note: For ClearCase 4.0 or higher, this command creates a dynamic view. For more information on types of ClearCase views, please see Developing Software with ClearCase and the view reference page in the ClearCase Command Reference.
- 2 . Activate your Clearcase view:
% cleartool setview pvobview
Creating a VOB
Note: The examples of creating a PVOB, a VOB, a project, a ClearCase view and an activity are provided to get you up and running quickly. To establish your project development environment, please see the Administering ClearCase Guide for details.
- 1 . Log into the VOB host.
- 2 . Choose a vob-tag for your VOB (/vobs/my.vob). This cannot include symbolic links.
- 3 . Create the VOB structure:
% cleartool mkvob -public -tag /vobs/my.vob /work1/vobstore/myvob.vbs Registry password: Comments for "/work1/vobstore/myprojpvob.vbs": VOB for trying out Apex/ClearCase with UCM . VOBs have special data backup considerations. ...- 4 . Mount the VOB:
% cleartool mount /vobs/my.vob
- 5 . If you want to verify your VOB, run cleartool lsvob which should list your VOB-tag, the VOB storage directory and the fact it is public.
Create a Component
Components are the UCM mechanism for simplifying the organization of your files and directories. The elements that you group into a component typically implement a reusable piece of your system architecture. Create a component named testcomp1 based on the VOB named my.vob:
% cleartool mkcomp -nc -root /vobs/my.vob testcomp1@vobs/myproj.pvob Set Admin VOB for component "tempcomp1" Created component "testcomp1".
Creating the Project
Members of a project team work in a UCM project. A ClearCase project is the object that defines a set of development policies and a set of configurations used in a significant development effort. Your organization may create a project for each product it develops, for a group of products, for a subset of a product's functionality, or for a product release the configuration information needed to manage a significant development effort, such as a project release. A project contains one shared work area and typically multiple private work areas. Private work area allow a developer to work on activities in isolation. ClearCase stores projects in a data repository called a PVOB (project versioned object base). Please see Developing Software using ClearCase and Management Software using ClearCase for information on setting up your projects.
% clearprojexpThe Project Explorer displays. Please see Managing Software Projects with ClearCase for details on Creating the Project. The instructions below is just a quick way to get your project established.
- 1 . Select (highlight) /vobs/myproj.pvob in the left pane.
- 2 . Select File > New > Project to create a project. Answer the questions in the project wizard:
- a .
Step 1: Enter the Title and Description as below and select the Next> button.Description: Getting started with UCM.
- b .
Step 2: Select No in the ...Begin from a set of baselines - option and then select the Next> button.- c .
Step 3: For the field:Which component baselines will be used during this project:
select the Add button. Select the testcomp1_INITIAL object under the Baselines pane. Select the OK button.
This baseline appears in the which component baselines ... pane.
- d .
Step 4: Use the defaults for the project.Select the Finish button and then select the continue button in the Confirm Window.
The PVOB example project is displayed in the UCM Project Explorer's right pane.
Note: Creating the project creates the integration stream. A stream is a ClearCase UCM object that determines which versions of elements appear in any view configured by that stream. Streams maintain a list of baselines and activities. A project contains one integration stream and typically multiple development streams.
Creating an Integration View
When you created the project above, an integration stream was created for you. To see and make changes to the project's shared elements, you need an integration view. To create an integration view:
- 1 . In the UCM Project Explorer, expand the /vobs/myproj.pvob element and then expand the PVOB example element and select the Integration element.
- 2 . Select the File > New > View. Use the defaults to create an integrations dynamic view. Select the OK button.
- 3 . Select the Continue button on the Confirm dialog box.
Create an Activity
In order to perform any work, you need an associated activity. An activity is a ClearCase UCM object that tracks the work required to complete a development task. We now need to add elements to the integration stream to create our initial baseline. We need to be in the integration stream. For user hh, we do:
% cleartool setview hh_PVOB_example_integration
% cleartool mkactivity -headline "create initial version" create_initial Created activity "create_initial".
cleartool setactivity create_initial Set activity "create_initial" in view "hh_PVOB_example_integration"
At this point, we have our Clearcase view set to hh_PVOB_example_integration and our activity set to create_initial.
Starting Apex/ClearCase
- 1 . If you installed Apex so that it runs with ClearCase by default, start up Apex/ClearCase using
% apexinit
Otherwise (Apex/Summit is the default), start up Apex using
% apexinit -clearcase
Apex displays the Apex ClearCase Panel window and the Welcome help file in the Netscape Browser.
- 2 . Visit your VOB to display a directory-viewer window by entering /vobs/my.vob in the Visit field in the Apex ClearCase Panel and clicking the Visit button.
When a directory is visited or opened, Apex/ClearCase opens a directory-viewer window that displays a list of files and directories.
Directory-Viewer Window
You can use the directory-viewer window to navigate through the directory structure, by visiting any of the listed files and directories.
When using Apex/ClearCase with UCM, the directory viewer displays three special fields at the bottom of the window. The Set View field displays the name of the current ClearCase setview that is in effect. This is fixed for an Apex session and is established before starting Apex. This ClearCase view allows accessing versions of elements as if they were ordinary files using ordinary pathnames.
The Working Directory View is determined from the context of the directory viewer: if the directory viewer is showing a directory located outside a VOB directory, then it show **NONE**; if the directory is located within a normal VOB directory, then label will match the current setview; if the directory is located within a fully qualified path using view extended pathnames, then the working directory view will display the view for the current directory.
The Activity is the name of the current ClearCase setactivity that is in effect. This is fixed for an Apex session and is established before starting Apex. If no activity is set, **NONE** is displayed. Please see Using ClearCase for a detailed explanation of Set View, Working Directory View, and Set Activity.
There are two ways to visit an object listed in the directory-viewer window. You can select the object's name and click Visit, or you can double-click the object's name.
You can also issue commands from the directory-viewer window's File menu to load, save, and print files and to execute and debug programs. The directory-viewer window is illustrated in Figure 33.
Figure 33 Directory-Viewer Window
.![]()
For more information about the directory-viewer window and how to use it, see Using and Customizing the Apex GUI.
Creating a Rational Subsystem
Compilation and configuration management must be performed in a Rational subsystem. You can create a Rational subsystem anywhere in a directory hierarchy except in another Rational subsystem —— subject, of course, to normal permission restrictions.
Models
One important characteristic of a Rational subsystem is its model. A model is a Rational subsystem or Apex/Summit view that serves as a prototype for a Rational subsystem. The model provides a base structure of subdirectories, policies (compiler options, target keys, etc., by way of switches), and a base set of Imports. For Ada, a model provides a package standard and built-in Ada packages, such as Text_Io.2.ada. For C/C++, a model provides access to the standard C/C++ library. Apex/ClearCase provides a default model for programs that are compiled and run using the same platform architecture that Apex/ClearCase uses. For more information on Models, see Programming with Apex.
To create the /vobs/my.vob/test.rss Rational subsystem:
- 1 . If not already displayed, open a directory viewer window of /vobs/my.vob using the File > Open command.
- 2 . Select the File > New > New Subsystem menu item.
Apex/ClearCase then opens the New Subsystem dialog box illustrated in Figure 34.
Figure 34 New Subsystem Dialog Box for Ada Development
![]()
- 3 . Enter the full pathname for the new Rational subsystem in the text field labeled Subsystem Full Name.
The pathname must be a fully qualified pathname (a pathname that starts with /). It is not necessary to enter the .rss extension in the text field; Apex/ClearCase adds that extension automatically. For this example, we are using /vobs/my.vob/test.
- 4 . Because we will be creating an Ada program, the Language field should be Ada. Verify the Host Architecture matches the architecture of the machine on which you are running.
- 5 . Make sure the Visit the new subsystem check box is selected.
- 6 . Select the Make it controlled option so that this Rational subsystem will be controlled. Any element that is controlled needs the enclosing Rational subsystem to be controlled. If you do not control it now, it will need to be controlled when you control the first element in this Rational subsystem. When you select this option, a Comment options field will be displayed. Select the No Comment option for this example.
- 7 . To create your new Rational subsystem, click OK or Apply.
Creating an Ada Unit
In Apex, the names of Ada source files follow a specific naming convention. The specification of a source file is always the name of the unit with the suffix .1.ada added. Similarly, the body of a source file is always the name of the unit with the suffix .2.ada added.
- 1 . Select the File > New > New Ada menu item from the /vobs/my.vob/test.rss directory viewer.
Apex opens the New Ada dialog box.
- 2 . Reset the option buttons labeled Package and Spec to read Procedure and Body.
- 3 . Enter the name for the procedure you are creating, hello, in the Name text field.
It is not necessary to append the suffix .2.ada (the conventional suffix for an Ada procedure) to the filename you enter. Apex automatically does this.
- 4 . To have Apex open an editing window for your new source file as soon as the file is created, check the Visit it check box.
- 5 . We want this procedure to be controlled under ClearCase, so check the Make it an element check box. This will make the enclosing Rational subsystem, /vobs/my.vob/test.rss, a VOB element in ClearCase if it is not one already. See Rational Subsystems (Apex/ClearCase only) to see what is controlled in the subsystem. ClearCase is described in Using ClearCase.
- 6 . Use the default Comment Option of No Comment.
- 7 . Make sure the Visit it check box is checked. If Visit it is not checked, Apex will not display your new source file in a window when it is created.
- 8 . Click OK or Apply.
This dialog box with the appropriate settings is shown in Figure 35.
Figure 35 New Ada Dialog Box
![]()
The file is created using the appropriate template file which defined the initial contents of this type of file.
Apex then opens an Ada editor window for your new source file as illustrated in Figure 36.
Figure 36 Ada Editor Window
![]()
Using the Apex Editors
The Apex Ada and C/C++ editors are powerful text editors designed specifically for editing Ada and C/C++ source files. They are described in detail in "The Ada Editor" and "The C/C++ Editor" chapters in Programming with Apex. The language editor windows resemble another Apex editor window —— the generic Apex text-editing window which is described in "The Apex Text Editor" chapter of Programming with Apex
The Apex language editors, like the text editor, contain main buttons for commonly used commands. For example, the Save button duplicates the functionality of the File > Save command, the Search-> button is a shortcut for the Edit > Search menu item, and the Message-> button is a shortcut for the View > Message-> command.
- 1 . When you make an object an element, the object is checked in. To make hello.2.ada editable by checking out the object, click on the Edit check box. Use the defaults in the ClearCase Check In/Out dialog box by selecting OK.
- 2 . Type in the code for hello.2.ada as shown in Figure 37.
Figure 37 Ada Editor Window with hello.2.ada
![]()
Compiling and Linking a Program
Commands for compiling and linking Ada and C/C++ programs are available from the Compile menu.
In Apex, a program is always compiled within the compilation context of its enclosing views. The compilation context of a Rational subsystem encompasses the compiler that is used, the values of the compiler's switches, and any imported Rational subsystems that provide external visibility to the units being compiled.
The Ada, text, and C/C++ editor window's Compile menus offers a selection of commands for semanticizing (Ada only), parsing (Ada only), pretty-printing (Ada only), compiling and linking Ada and C/C++ code in the compilation context of their enclosing Rational subsystems. For this brief example, you are going to use the Compile > Link command that compiles and links a program. For details, see Compiling and Executing in the Programming with Apex.
The procedure for linking mixed language programs is essential the same. It is described in more detail in Programming with Apex.
- 1 . If you choose the Compile > Link item from a viewer window, Apex displays the Link dialog box. Note that the name of the selected item will normally be displayed in the Units to Link field.
- 2 . If you choose Compile > Link from an editor window, Apex links the current object using the Link dialog box defaults. Alternately, you can bring up the Link dialog box by selecting Control-Compile > Link.
For more details on the Compile > Link command, see the Online Reference.
Executing a Program
- 1 . To execute a program, select Run from the File menu.
Apex then opens the Run/Debug dialog box illustrated in Figure 38. The Run/Debug dialog box allows you to run a program and to redirect input, output, and error output. You can use the Debug command to run programs under the debugger.
- 2 . Select OK to execute the hello program.
The Output window will display:
--- execute of /vobs/my.vob/test.rss/hello --- hello world!
You may also choose Tools > Shell to bring up a shell window. In the Window, enter the name of the program to run (hello.exe).
The Run/Debug dialog box contains text fields in which you can type the name of the program you want to execute, the UNIX arguments (if any) that you want to pass to the program, and the context in which the program will execute. Note that the Run/Debug dialog box is slightly different for native and embedded (cross) systems. Only the Run/Debug dialog for native systems is illustrated here. The Run dialog for embedded systems is described in detail in the Programming with {Rexec, Tornado, LynxOS} manuals.
Figure 38 Run/Debug Dialog Box - Native Systems
![]()
Placing the Program Under Control
If you did not select the Make it an element option in the Create Ada dialog box, you can control this object now.
- 1 . In the /vobs/my.vob/test.rss directory viewer, select hello.2.ada and execute the CM > Make Element command.
The Place object(s) under ClearCase control dialog box is displayed and is illustrated in Figure 39.
- 2 . If you did not control your Rational subsystem yet, you need to select the Control enclosing subsystem check box or you will not be able to control this object. All controlled objects must be within Controlled Rational Subsystems. When you control an object, it is also checked in.
Figure 39 Place object(s) under ClearCase control dialog box
![]()
- 3 . If your object is already an element, check it in by executing the CM > Checkin command. Select the OK button to use all the defaults.
- 4 . Exit from Apex by selecting the File > Exit Apex command.
Creating a New Baseline
When you are working on a project with others, you need to lock the integration steam before making a baseline:
- 1 . In the UCM Project Explorer, expand the /vobs/myproj.pvob element and then expand the PVOB example element and select the Integration element.
- a .
Right-click and select Properties to bring up the property sheet.- b .
In the property sheet, select the Lock tab. Select the Locked option and then OK.- 2 . Select the Tools > Make Baseline command:
In the Make Baseline dialog box:
- a .
Enter a name in the Baseline Title. We used the defaults for everything.- b .
Select OK. Select Dismiss in the Progress dialog box.- 3 . Right-click and select Properties to bring up the property sheet. In the property sheet, select the Lock tab. Select the Unlocked option and then OK.
- 4 . Select File > Exit to exit the Project Explorer.
Please see Managing Software Projects with ClearCase for more information on Baselines.
Joining a Project as an Individual User
Now that the initial baseline version is established, users can update the baseline version to create the next version. To join a project:
- 1 . Step 1: Select the /vobs/myproj.vob project VOB. Select the PVOB example project. Select the Next > button.
- 2 . Step 2: Use the defaults for the development and integration steams by selecting the Next > button.
- 3 . Step 3: Use the defaults to create a Development view by select the Next > button.
- 4 . Step 4: Unselect the Create Integration View option and select the Finish button.
- 5 . Select Continue in the Progress dialog box. Select Cancel in the Start Development View dialog box.
Please see Developing Software with ClearCase for more information about this wizard.
Creating an Activity
- 1 . Set view to your private development stream:
% cleartool setview hh_PVOB_example_2
- 2 . Make a new activity for updating the baseline:
% cleartool mkactivity -headline "first improvement" \ first_improvement Created activity "first_improvement".
cleartool setactivity first_improvement Set activity "first_improvement" in view "hh_PVOB_example_2"
- 3 . Bring up Apex Again.
- 4 . Visit your subsystem, /vobs/my.vob/test.rss.
Updating an Ada Program - Checking Out, Editing, Checking In
In Apex, your ClearCase view is hh_PVOB_example_2 and your activity is first_improvement.
- 1 . Execute the CM > Checkout command to check out the file for updating. Use the default options in the ClearCase Check In/Out dialog box illustrated in Figure 40.
Figure 40 ClearCase Check In/Out dialog box.
![]()
Note: You can also click on the Edit button in the hello.2.ada editor window to display the ClearCase Check In/Out dialog box.
- 2 . Double click on the hello.2.ada item in the directory viewer window. In the Ada editor, edit the hello.2.ada file and save it.
- 3 . Compile, Link and Test the change(s) using the same steps as Compiling and Linking a Program and Executing a Program.
- 4 . Execute the CM > Check In command using the default options.
The file is time-stamped when the version is checked in.
Note: You should select the Preserve modification time of objects check box when you are working with Ada files so that Apex/ClearCase does not perform unnecessary consistency check next time it compiles the unit.
You now have a controlled, checked in file on the hh_PVOB_Example_2 branch.
Rebase the Integration View
Now we want to incorporate the new version of hello world into the baseline. When you are working on a project with others, you need to lock the integration steam before making a baseline:
% clearprojexp
- 1 . In the UCM Project Explorer, expand the /vobs/myproj.pvob element and then expand the PVOB example element and select the Integration element. Right-click and select Properties to bring up the property sheet.
- 2 . In the property sheet, select the Lock tab. Select the Locked option and then OK.
- 3 . In the UCM Project Explorer, select hh_PVOB_example_2 and select the Tools > Deliver from Steam command.
- a .
If you are presented with a ClearCase Prompt window, select the hh_PVOB_example_Integration integration vie w and select the OK button.- b .
In the Deliver Activities dialog box, enter yes or <return> to deliver.- c .
Enter Yes or <return> to the Do you wish to Compile the deliver operation question.- d .
Enter <return> to the Hit <Return> to Exit prompt.- 4 . In the UCM Project Explorer, select the Integration element. Right-click and select Properties to bring up the property sheet.
- 5 . In the property sheet, select the Lock tab. Select the Unlocked option and then OK.
- 6 . Select File > Exit to exit the Project Explorer.
Rebase Your Working View
When a new Baseline is ready, you probably want to update your working view using the following steps:
% clearprojexp
- 1 . In the UCM Project Explorer, expand the /vobs/myproj.pvob element and then select the hh_PVOB_example_2 element.
- 2 . Select the Tools > Rebaseline Stream command:
In the Rebase stream dialog box:
- a .
Enter the defaults for everything.- b .
Enter <return> to the Hit <Return> to Exit prompt.- 3 . Select File > Exit to exit the Project Explorer.
Note: After rebaselining, a recompilation may be needed to bring internal compilation structures (DIANA or SIENNA) in sync with the new source.
Please see Managing Software Projects with ClearCase for more information on Baselines.
Additional Apex/ClearCase OperationsThis section covers the following topics:
- Remodeling a Rational Subsystem
- Creating a New ClearCase View
- Setting Up Imports on Rational Subsystems - Example
- Displaying Additional Information
- CM Attributes
- Version Tree
- Metadata
- Creating and Using Attributes
- Creating and Using Branches
- Creating and Using Version Labels
- Performing Audited Builds and Winkins
- Performing Maintenance
- Limitations on Using Apex/ClearCase
Remodeling a Rational Subsystem
- Change the model of the Rational subsystem
- Update all the model information to be consistent with any change to the current model
- Recompute (refresh) information based on changes to switch settings.
Any remodel except a refresh requires the artifact files to be checked out if the Rational subsystem is controlled. The Remodel dialog box include an option to Check in/out artifacts button that aids in checking these files out.
Creating a New ClearCase View
ClearCase 4.0 and higher includes two kinds of views:
- Snapshot views, which copy files from data repositories called VOBs (versioned object bases) to your computer.
- Dynamic views, which use the ClearCase multiversion file system (MVFS) to provide immediate, transparent access to the data in VOBs.
For more information, see Developing Software with ClearCase and the view reference page in the ClearCase Command Reference.
The default to most commands is dynamic views.
You create a new ClearCase view with elements from your VOBs:
- 1 . Using cleartool, create a new ClearCase view. See Creating and Activating a ClearCase View for an example.
- 2 . Using cleartool, setview to this new ClearCase view.
- 3 . Bring up Apex. See Starting Apex/ClearCase for details.
- 4 . Remodel using the Compile > Maintenance > Remodel command with the Refresh option to refresh the subsystems. This will configure your subsystems correctly since you only get the controlled elements, no derived files when you create new ClearCase views. You can use a configuration file as input to the Remodel command.
More Information on Snapshot Views
Due to the nature of snapshot views, there is an imports issue when sharing Rational subsystems which import other Rational subsystems between a dynamic view and a snapshot view. The imports need to be updated using the Compile > Architectural Control > Imports command.
In this example using the Apex command line, vobs/bagel_read is the VOB, /a/mgupta/acci_snapshot is the snapshot view path.
- 1 . Create a snapshot view:
% cleartool mkview -tag acci_snapshot -snapshot /a/mgupta/acci_snapshot
- 2 . Edit the config_spec to load this VOB:
% cleartool edcs
The config file should contain the following lines:
element * CHECKEDOUT element * /main/LATEST load /vobs/bagel_read
- 3 . Update the snapshot view:
cleartool update /a/mgupta/acci_snapshot
- 4 . Go to the vob inside the snapshot view.
% cd /a/mgupta/acci_snapshot/vobs/bagel_read
- 5 . Create 2 controlled Rational subsystems:
% create_subsystem -control server.rss client.rss
- 6 . Import one into other:
% cd client.rss
checkout Imports/Description.cfg
% import . ../server.rss
- 7 . Check the imports
Notice that the import shows the full path name of the snapshot view. This is a problem. Now for build operations inside any other view (snapshot or dynamic), this import is going to be incorrect since it will evaluate contents of server.rss by config spec rules of acci_snapshot. Also, it is possible that /a/mgupta may not even accessible to another view. The bottom line is that this import is "view name dependent" and needs to be fixed manually using the Compile > Architectural Control > Imports command.
Setting Up Imports on Rational Subsystems - Example
To illustrate importing one Rational subsystem into another, we will use a very simple example:
- 1 . Create the first subsystem /vobs/test/test1.rss.
- 2 . Create an Ada package inc.1.ada in /vobs/test/test1.rss that defines a variable Status as illustrated in Figure 41.
Figure 41 Package Specification Inc (inc.1.ada) - the importee
![]()
- 3 . Create another Rational subsystem, /vobs/test/test2.rss.
- 4 . Create a procedure a1.2.ada that references the object Inc.Status as illustrated in Figure 42.
Figure 42 Procedure A1 (a1.2.ada) - the importer
![]()
- 5 . If you try to link a1.2.ada at this point, you will get a fatal error that there is no unit named inc.1.ada accessible to a1.2.ada. So, we need to import inc.1.ada.
- 6 . Import Rational subsystem test2.rss into Rational subsystem test1.rss.
- a .
In the test1.rss directory viewer or the Ada editor containing procedurea1
, select the Compile > Architectural Control > Imports command.This displays the Imports viewer illustrated in Figure 43.
Figure 43 Imports Viewer for test1.rss
![]()
- b .
From the Imports viewer, select the Add Import... button- c .
In the Add Import dialog box illustrated in Figure 44, select the Check Out/In Artifacts files... button to check out all the necessary files to update imports.This button displays the ClearCase Check Out dialog box with the Rational subsystem files is the Objects to Checkout field. This dialog box is illustrated in Figure 45.
Figure 44 Add Import dialog box
![]()
Figure 45 ClearCase Check Out dialog box - with subsystem Artifact files
![]()
- d .
Select OK to check these files out.- e .
Back in the Add Import dialog box illustrated in Figure 44, add the subsystem to be imported (/vobs/test/test2.ss) and select OK.The Imports viewer will be updated as illustrated in Imports viewer illustrated in Figure 46.
Figure 46 Imports Viewer for test1.rss
![]()
- 7 . When you Compile > Link the procedure in a1.2.ada now, it will succeed.
Displaying Additional InformationRational Subsystem Information
To display information about a Rational subsystem:
In a directory viewer where the Rational subsystem is listed, select (highlight) the subsystem.
Execute the Compile > Architecture Control > Show Properties command.
The output window displays information about the selected Rational subsystem.
CM Attributes
In a directory viewer, the CM attributes can be displayed by executing the View > Format > CM Attributes command. This is illustrated Figure 47.
Figure 47 CM Attributes
![]()
Version Tree
To display the Version Tree in ClearCase, select the element and execute the CM > Show Versions command.
You could also execute the ClearCase Native GUI command from any editor window. A File Browser is displayed.
If you select a controlled object and execute the Version > Show Version Tree command, a Vtree Browser is displayed. To see all the versions, select the All Versions button. An example of all versions of a controlled file, test.txt is illustrated in Figure 48.
Figure 48 Version Tree for test.txt
![]()
Note: This viewer uses the ClearCase naming conventions.
ClearCase Information
To see additional ClearCase Information, select the CM ClearCase Native GUI command. Please see the ClearCase Users Guide for ClearCase 3.2 or the Using ClearCase for ClearCase 4.0 or higher for information on the ClearCase File Browser.
Metadata
Metadata (user-defined attributes, labels, and branches) are easily created using the CM > ClearCase Native GUI or the mkattype, mkbrtype, or mklabel command line commands. Once the attribute, label, or branch type is defined, a name/value attribute pair or a label or branch can be attached to or removed from a version of a file or directory with the CM > Metadata command. This command displays the ClearCase Metadata Operations dialog box, illustrated in Figure 49, which is dynamic; it is updated as soon as any Metadata information changes. So, when you add a new Metadata type using cleartool in a shell window, even while the dialog is displayed, it will be updated with this new type.
Figure 49 ClearCase Metadata Operations Dialog Box
![]()
Please see the ClearCase User's Manual for ClearCase 3.2 or Using ClearCase for ClearCase version 4.0 or higher for more details on metadata attributes, metadata labels, and branches.
Note: Metadata names and metadata values (for attributes) are case-sensitive.
Creating and Using Attributes
As an example, we will create an ordinary attribute of type string that can have the values "TRUE" or "FALSE" called QA_OK and then attach it to a file called test.txt.
- 1 . Open an Apex shell window using the Tools > Shell command.
- 2 . Create the attribute using Cleartool:
cleartool mkattype -ord -nc -vtype string -enum '"TRUE","FALSE"' QA_OK- 3 . Attach the QA_OK attribute:
- a .
Select the element from a directory viewer (or enter the element in the Objects to operate field of the ClearCase Metadata Operations dialog box.)- b .
Select the CM > Metadata command from the directory.- c .
In the ClearCase Metadata Operations dialog box, select the following:i Select Attach in the Operation Type radio buttons.
ii Select Attribute in the Metadata type radio buttons.
iii In the Attribute Name field, enter QA_OK or select it using the Alternatives Icon. Once you specify the Attribute Name, the Attribute Value field becomes modifiable and the Range and Type information is filled in.
To View Attributes
- 1 . In the Vtree Browser of the element, select the version with the attribute and select the Report > Describe command. In the dialog box, select the Attributes tab. The attribute is shown.
- 2 . In a shell window, use the CLI command:
cleartool describe <element name
>
Creating and Using Branches
As an example, we will create an ordinary branch called bug and attach it to a file called test.txt:
- 1 . Open an Apex shell window using the Tools > Shell command.
- 2 . Create the branch using cleartool:
cleartool mkbrtype -ord -nc BUG
- 3 . Attach the BUG branch:
- a .
Select the element from a directory viewer (or enter the element in the Objects to operate on field of the ClearCase Metadata Operations dialog box.)- b .
Select the CM > Metadata command from the directory.- c .
In the ClearCase Metadata Operations dialog box, select the following:i Select Attach in the Operation Type radio buttons.
ii Select Branch in the Metadata type radio buttons.
iii In the Branch Name field, enter Tested or select it using the Alternatives Icon.
iv Use the default for the other options and select the OK button to attach this attribute.
The Output window displays a message that the branch Tested was created.
To View Branches
To view the branches of an object, display it in a Vtree Browser.
Creating and Using Version Labels
As an example, we will create an version label branch called Tested and attach it to a file called test.txt:
- 1 . Open an Apex shell window using the Tools > Shell command.
- 2 . Create the label using Cleartool:
cleartool mklbtype -ord -nc Tested
- 3 . Attach the Tested label:
- a .
Select the element from a directory viewer (or enter the element in the Objects to operate field of the ClearCase Metadata Operations dialog box.)- b .
Select the CM > Metadata command from the directory.- c .
In the ClearCase Metadata Operations dialog box, select the following:i Select Attach in the Operation Type radio buttons.
ii Select Label in the Metadata type radio buttons.
iii In the Label Name field, enter Tested or select it using the Alternatives Icon.
iv Use the defaults for the other options and select the OK button to attach this attribute.
The Output window displays a message that the Tested label was created.
To View Labels
To view the Labels of an object, display it in a Vtree Browser.
Performing Audited Builds and Winkins
Apex automates the following operations involving derived objects (DOs):
- Audited build for winkin —— coding or linking a Rational subsystem and its import closure so that the resulting derived objects can be winked in to another ClearCase view;
- Winking in compilation artifacts that were generated by an audited build in another ClearCase view;
- Generating a bill of materials from an audited link of a single main unit. This is a report that lists every source file or other filesystem object that contributed to the generation of the executable.
The Apex compilers have their own build avoidance strategies based on fine-grained dependency analysis (at the level of language constructs rather than whole source files) and optimal recompilation. These strategies are highly effective, but they also defeat the file-level build avoidance strategy of winkins in the general case.
Winkins are quite useful in Apex for eliminating the need to do an initial build in newly-created ClearCase views. The strategy is to first do a ClearCase audited build in a ClearCase view where:
- 1 . The contents of the ClearCase view represent a baselevel for configuring other ClearCase views; for example, all the element versions currently in the ClearCase view are labeled, and the label will be used in the config specs of other ClearCase views to select all the same versions. (This is actually not a strict requirement; if another ClearCase view winking in the compilation artifacts does in fact select all the same source file versions, then no recompilations will be necessary. If, however, the ClearCase view doing the winkin does not select all the same source versions, the Apex compiler will ensure that any out-of-date or incorrect compilation artifacts are regenerated next time a compilation operation is performed).
- 2 . The build is done "from scratch", that is, from Rational subsystems that have been cleaned of all compilation artifacts. This allows all of the inter-file dependencies to be captured as file references by the audited build. Apex automates cleaning of the Rational subsystems to be coded.
When new ClearCase views are created that select the same source file versions as the ClearCase view in which the audited build was performed, they can do a winkin from that ClearCase view. This populates the new ClearCase view with compilation artifacts, effectively promoting its Rational subsystems to a compiled state without performing any compilations!
For more information on Derived Objects and Winkins, see the Quick Review of ClearCase Concepts.
Generating Derived Objects for Winkin
To code a Rational subsystem and its import closure and generate DOs for winkin:
- 1 . From the Rational subsystem directory viewer, select the Compile > Code command.
- 2 . In the Code dialog box, select the Build derived objects option. When Build derived objects is selected, another radio button, Do not clean closure is displayed. This option is deselected by default, thus the closure will be cleaned.
- 3 . Fill in any other dialog box fields as usual and click OK or Apply.
Apex will clean the ClearCase view and its import closure, then it will invoke a ClearCase audited shell to do the code operation. This generates the compilation artifacts as DOs which are then available for winkin into other ClearCase views (see below).
Alternatively, you can use the do_clearcase_audit command from the command line.
Note: The do_clearcase_audit command is invoke by the Compile > Code and Compile > Link commands when the Build derived objects option is selected.
For more information on the do_clearcase_audit command, please see the Command Reference.
Winking In Derived Objects from Another ClearCase View
To winkin these derived objects from another ClearCase view:
- 1 . In an Apex session that is set into the target ClearCase view (the view that will winkin the DOs from the source view), execute the CM > WinkIn command.
- 2 . In the Winkin dialog box:
- a .
Enter the Rational subsystem(s) to winkin into the Target Subsystems field.- b .
To wink in artifacts for a Rational subsystem and its entire import closure, just enter the Rational subsystem into Target Subsystems, and select the Winkin import closure option (if multiple subsystems are listed in Target Subsystems, selecting this option will wink in the union of their closures).- c .
Enter the name of the source ClearCase view in which the DOs were generated into the Source View field. You can use this field's Alternatives icon to bring up a menu listing all registered ClearCase views.- d .
Click OK.The winkin will proceed. Note: there is no command-line version of the Apex CM > WinkIn command.
Generating a Bill of Materials
To generate a bill of materials for the link of an executable:
- 1 . Select the Compile > Link command.
- 2 . In the link dialog box, enter the unit to link.
- 3 . Select the Build derived objects option.
- 4 . Leave the Clean import closure option selected.
- 5 . Fill in the rest of the dialog as needed.
- 6 . Select OK or Apply.
Apex will clean the ClearCase view and its import closure, then it will invoke a ClearCase audited shell to do the link operation and produce a configuration record (CR) for the linked executable. We can now display this CR (see instructions below) as a bill of materials for the executable.
- You must specify the name of a main unit to link. If you specify a Rational subsystem, Compile > Link will perform a winkin-style audited build and the resulting CR will not be suitable for use in producing a bill of materials. (That style of audited link is like an audited code that has the side-effect of promoting the Rational subsystem and its closure to the "linked" state, that is, linking any units to which pragma
Main
is applied). By the same token, the audited link for a bill of materials produces a CR that is not of value for winking in DOs from the ClearCase view.- Since CRs are ClearCase view-specific, you can do a bill-of-materials-style audited link from one ClearCase view and this does not interfere with the ability of other ClearCase views to wink in DOs from a different ClearCase view in which a winkin-style audited build was performed.
Note: Audited builds and CR generation can only be performed within the context of a ClearCase dynamic view.
- 7 . To display the resulting CR, bring up an Apex xterm using the Tools > Shell command.
- 8 . In the xterm, enter the command:
% cleartool catcr <executable>
This audited link also generates compilation artifacts as DOs in the same manner as an audited code operation, so the resulting DOs can also be winked in to other ClearCase views.
Generating a Bill of Materials Example
This example performs an audited link on the program, planetary_motion (created during the online tutorial, ada debugger section). In an Apex xterm:
% cd /vobs/test/project1.rss
% do_clearcase_audit link clean planetary_motion
+++project1.rss was cleaned in /vobs/test
::: [ apex link has finished]The ClearCase command cleartool catcr is used to display configuration records. Many of the objects in the CR will be compilation artifacts, and as such do not really belong in a bill of materials. You can filter them out of the listing by piping the output through the grep command. For instance, to display the configuration record created in the example above you would issue the following command in an Apex xterm:
% cleartool catcr planetary_motion | grep -v \.Rational
Target ClearAudit_Shell built by hh.rational
Host "basol" running SunOS 5.6 (sun4u)
Reference Time 29-Jan-01.08:37:56, this audit started 29-Jan-01.08:37:56
View was basol:/vc/home/h_view
Initial working directory was basol:/vobs/test
----------------------------
MVFS objects:
----------------------------
/vobs/test/project1.rss/Imports/Description.cfg <27-Jan-01.14:02:07>
/vobs/test/project1.rss/Imports/Description.export_sets <27-Jan-01.14:02:10>
/vobs/test/project1.rss/Imports/Mutual_Description.cfg <27-Jan-01.14:02:10>
/vobs/test/project1.rss/Policy/Switches <27-Jan-01.14:02:07>
/vobs/test/project1.rss/coordinates_2d.1.ada <02-Nov-93.18:01:02>
/vobs/test/project1.rss/coordinates_2d.2.ada <02-Nov-93.18:01:12>
/vobs/test/project1.rss/display.1.ada <02-Nov-93.18:01:03>
/vobs/test/project1.rss/display.2.ada <02-Nov-93.18:01:12>
/vobs/test/project1.rss/orbit.1.ada <02-Nov-93.18:01:05>
/vobs/test/project1.rss/orbit.2.ada <02-Nov-93.18:01:06>
/vobs/test/project1.rss/orbit_decorations.1.ada <30-Nov-93.08:40:44>
/vobs/test/project1.rss/planet.1.ada <02-Nov-93.18:01:04>
/vobs/test/project1.rss/planet.2.ada <30-Nov-93.09:41:02>
/vobs/test/project1.rss/planetary_motion@@29-Jan.08:38.21493
/vobs/test/project1.rss/planetary_motion.1.ada <02-Nov-93.18:00:59>
/vobs/test/project1.rss/planetary_motion.2.ada@@29-Jan.08:38.21479
/vobs/test/project1.rss/screen_io.1.ada <02-Nov-93.18:01:04>
/vobs/test/project1.rss/screen_io.2.ada <02-Nov-93.18:01:08>
/vobs/test/project1.rss/sqrt.2.ada <02-Nov-93.18:01:07>
/vobs/test/project1.rss/universal_constants.1.ada <02-Nov-93.18:01:01>
/vobs/test/project1.rss/universal_types.1.ada <02-Nov-93.18:01:00>
/vobs/test/project1.rss/velocity_2d.1.ada <02-Nov-93.18:01:01>
/vobs/test/project1.rss/velocity_2d.2.ada <02-Nov-93.18:01:13>Performing Maintenance
All maintenance functions are done using ClearCase directly. Please see the ClearCase Administrator Manual for ClearCase 3.2 or Administering ClearCase for ClearCase 4.0 or higher for more information.
Limitations on Using Apex/ClearCase
NFS Stale Handle When Controlling Objects Using the Command Line
If you are in an Apex shell and you control the Rational subsystem or an object inside it while your current working directory is also a within this rss, then you get NFS stale handle error after the completion of operation. You just need to change the directory back the current working directory. This happens because in order to control directories, they need to be moved elsewhere, created anew as ClearCase elements and then their contents moved back inside the new ClearCase directory.
This does not happen from GUI.
For example, in an Apex xterm, an RSS (/vobs/test/src/day.rss) was created uncontrolled. The user does the following commands:
% cd /vobs/test/src/day.rss/
% control -control_enclosing_subsystem foo.2.ada
After this operation, you get an NFS Stale Handle error on executing any UNIX command.
% cd /vobs/test/src/day.rss/operation
To avoid this problem, it is suggested that you control object(s) when you create them using the -control option if you are using the command line or by selecting the make it controlled or the make it an element option in the New dialog box.
More than One User Simultaneously Controlling Objects in the Same Uncontrolled Directory
If more than one user control objects simultaneously inside the same uncontrolled directory in a Rational subsystem (it could be the .rss directory itself) then unpredictable things will happen. To avoid any problems, it is strongly suggested that you control object(s) when you create them using the -control option if you are using the command line or by selecting the make it an element option in the create dialog box.
Rational Software Corporation http://www.rational.com support@rational.com techpubs@rational.com Copyright © 1993-2002, Rational Software Corporation. All rights reserved. |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |