TOC PREV NEXT INDEX DOC LIST MASTER INDEX



Client/Server Concepts Guide

Note: Shadowing is not supported for Apex/ClearCase.

Apex commands are available to the user that has shadowed a view onto the PC through four mechanisms:

1 . Apex Ada NT version 1.0.2 or later.

During installation of Apex Ada NT, if the shadowing option is selected, access to Summit/CM from the Apex Client as well as from Apex NT will be enabled. This is described in detail in Apex NT and Shadowing

2 . The Apex Client Interface running on the PC.

The Apex Client Interface provides users with a way to run Apex from a Windows-based PC using an installation of Apex on another host. The Apex Client Interface currently provides a subset of the dialogs, menu items, and browsers, available in Apex. In addition, all Apex commands can be used.

The Client Interface is implemented in Java and is also called the Remote Java/Apex Interface or simply the Java Interface. The Java Interface can be run directly on the client machine or through a web browser such as Netscape Communicator or Microsoft Internet Explorer.

3 . Rose and Microsoft IDE's such as Visual Java, Visual C++, and Visual Basic.

The Apex Client Interface provides an implementation of the standard Microsoft Source Code Control Interface so that Summit/CM commands exposed in these IDEs will use Summit/CM commands to perform common Source Code Control commands, such as checking out a file from Apex.

4 . Through a PC X Server.

By installing a PC X Server and telling Apex to use the PC as the display, the entire Apex interface can then be used from Windows.

Shadowing is automatically enabled when the Apex session is started from Apex Ada 95/83 for Windows NT.

The following topics are covered in this chapter:


Remote Java Interface / Web Browser

There are several ways to run the Remote Java (Client) Interface.

1 . If the Shadowing option is selected during installation of Apex NT, the components necessary for the Apex client are installed. To use shadowing, click on the Control > Login to CM Server menu item. A login dialog will appear. On this dialog, you must specify the name of the Apex service machine and your username and password.

2 . The Interface can be run using the Java Runtime Environment (JRE) packages provided with Apex for clients on Windows NT, Windows 95, and Sun Solaris. These JRE packages include both the Java Interface and a Java Virtual Machine to execute the interface as a stand-alone program. The appropriate JRE package must be installed on the client machine.

3 . The Interface can be run over the Web using a Java-enabled browser, such as Netscape Communicator, Internet Explorer, or Hotjava, without installing any Apex software on the client machine. The browser must support Java 1.1.

4 . The Interface client can be run as a stand-alone Java application using a Java Virtual Machine such as that provided in Sun's JDK (Java Development Kit). JDK Version 1.1.3 or higher is recommended. In this case, the Java Interface archive file must be installed on the client machine.

Thus, users can run the Java Interface on Windows, on Sun Solaris, or on any platform which has a Java-enabled browser or a Java Virtual Machine compatible with Java 1.1.

Java Interface Capabilities

The Java Interface currently provides a subset of the GUI dialog boxes and menu items available in the Unix version of Apex. However, users can execute any Apex command through the File > Run dialog.

The Java Interface consists of the following browsers: Directory Browser, Versions Browser, History Browser, Source Browser, Imports Browser, Task Browser. It has support for the Summit/TM and Summit/CM products and the Apex Shadowing interface. The dialogs are similar to their Unix counterparts, but have been enhanced to better fit in the PC environment.

Using the Java Interface

To use the Java Interface, you must first install the cgi-bin scripts and programs into one or more of your Web servers. See the Installation instructions for more details on how to do this.

Once your Web server is updated, you can start the interface in any of the ways described below. Method 2 or 3 below is recommended for the best performance. In all cases, the server machine must be a Web server where Apex and the cgi-bin scripts have been installed.

When you start the Java Interface, a login panel is displayed asking for your username and password. Unless you are using a Web browser, you must also specify the name of the server machine. After you enter these values, the Java Interface logs into the server machine, starts an Apex session on your behalf, and connects you to that session. After a time, you will see an Apex Directory Browser window. This is very similar to the directory browser available on UNIX.

Java Interface invocation methods

Use one of the following methods to invoke the Java interface.

Apex NT GUI

From the Apex NT GUI, select the menu item Control > Login to CM Server. This brings up a login dialog. Enter the Unix host name, your user name, and password in the dialog and select OK. The Java interface is started on successful login.

Web Browser

Using a Java 1.1-enabled browser (such as Netscape Communicator), visit the location

The login dialog will appear in the browser's display area. This may take more than a minute because the browser must download the Java Interface program.

Windows JRE

For a Windows client machine, you can use the Windows JRE package provided with Apex. Copy the file $APEX_HOME/shadowing/SETUPEX.EXE to the client machine. Execute the file to complete the installation. A menu item Programs > Apex Shadowing > Apex Client will be added to your Start menu. This menu item invokes the Client Interface and displays the login dialog. Also see Windows Installation.

Solaris JRE

For a Solaris client, you can use the Sun Solaris JRE package provided with Apex in the directory $APEX_HOME/web/sun4_solaris2. To start the Java Interface directly from this directory, use the command

A login dialog will appear. It is not necessary to specify a Java CLASSPATH.

There is also a file called jre.tar.Z in the same directory that contains the Sun Solaris JRE software in a convenient form for downloading to remote client machines. To install the Java Interface on a remote machine, download the jre.tar.Z file into a new directory (denoted as <jre-dir>) on the remote machine.

Uncompress and extract the files using the commands:

You can then run the Java interface using the command:

The classes.jar file containing the Apex Java interface is included in the directory <jre-dir>/lib and is automatically invoked by the startapex script using the included JRE software.

Java Virtual Machine

Install and run the Java interface on a client machine.

If you have a Java 1.1 implementation on your client machine, such as JDK1.1.x (Sun's Java Development Kit), you can run remotely without a browser. The Java Interface is provided as a "jar" file (Java ARchive file) with the pathname $APEX_HOME/web/htdocs/classes.jar in your Apex release. Copy this file to the client machine and add the file's path to your CLASSPATH environment variable on that machine. You can then use the Java implementation on your client machine to run the interface with the command:

where "java" is the command that runs a Java program. A login dialog will appear. You must specify the name of the Apex server machine to be contacted and your username and password to login as described above.


Shadowing Overview

Shadowing support is based on the following concepts:


Installation and Setup

Installation

Windows Installation

The Apex Client software for Windows consists of the Apex Shadow Server, Apex Client, and Microsoft Integration DLL's. The required Windows installation is automatically done while installing Apex NT with shadowing enabled. If you are using shadowing but not using Apex NT the following installation instructions are required.

The Apex Client software for Windows consists of the Apex Shadow Server, Apex Client, and Microsoft Integration DLL's. This software is installed by using a self-extracting executable that is included as part of the Apex release in $APEXHOME/shadowing/SETUPEX.EXE. You should copy this file to the PC and then execute it and a series of dialogs will lead you through the installation.

The installation will prompt you for the directory in which the Apex Client and the Apex Shadow Server will be installed. The installation will install two items on your 'Programs' menu, one for starting the Apex Shadow Server and another for starting the Apex Client. The installation will also configure your machine so that Visual C++ and other Microsoft IDE's (Integrated Development Environments) will use the Apex Client to perform Source Code Control operations.

Shadowing on a Windows machine requires the Apex shadow server. The shadow server is a Windows application which uses TCP/IP stream-based sockets to communicate with an Apex session and handle I/O and other requests in support of shadowing. The installation program will install the shadow server on any PC on which you want to maintain working directories that are shadowed. Apex NT users should refer to the Installation Guide which contains a description of the steps necessary to install the shadowing components.

Unix Setup

To use shadowing on Windows, you must enable shadowing support in Apex and if you want to use the Apex Client program, you must install several web server scripts on a Unix host running an Internet Web Server.

To enable shadowing support in Apex:

1 . Set the environment variable APEX_SHADOW_ENABLED for your Apex session.

2 . Invoke Apex on Unix with the -shadow switch.

When the Apex Client executes on Windows, it invokes Apex on Unix with shadowing support enabled by default.

To install the appropriate web server scripts, you must first install the cgi-bin scripts and programs into one or more of your Web servers. See the Installation Guide for more details on how to do this. Once your Web server is updated, the Apex Client can connect to a version of Apex running on the same machine as the Web server.

It is important to remember that the Apex Client consumes an Apex license depending on which operations you invoke from the Apex Client.


Shadowing Concepts

Shadowing on the Apex side is controlled by two files, Policy/Shadow_Location and Policy/Shadowing.sw, located in your view. These files are automatically created and configured when an NT view is shadowed, otherwise these files must be manually configured. The shadow client uses the Shadow_Location and Shadowing.sw switch file to decide if, where, and how shadowing is to be performed for a particular view. The following is a list of all of the valid Shadow_Location fields and Shadowing switches followed by a sample Shadow_Location and Shadowing.sw file.

Table 1 Shadow_Location Fields
Field Name
Description
Default Value
MACHINE_NAME
Name of the PC where the PC-working directory resides
None. This field is mandatory
PORT_NUMBER
Port on which the shadow server is listening for requests
1041
REMOTE_CONTEXT
The context to use for the PC-working directory. Note: The interpretation of this field is controlled by the USE_CONTEXT_AS_BASE switch described below.
None. This field is mandatory

Table 2 Shadowing.sw Switches
Field Name
Description
Default Value
SHADOW_KIND
Specifies the kind of shadow. Possible values are Primary and Secondary.
Primary
FLATTEN_SUBDIRECTORIES
If set to True, view sub-directories are NOT created on the shadow. Instead, files residing in sub-directories of the current view are placed in the top level directory.
True
DEFAULT_IS_ASCII
When set to True, the default transfer mode for files in the view is ascii.
False
ALWAYS_USE_ASCII
A shell style regular expression which identifies files which should always be transferred as ascii.
*.c *.C *.cc *.cpp *.h
NEVER_USE_ASCII
A shell style regular expression which identifies files which should always be transferred as binary.
none
CONVERT_C_TO_CPP
If set to True, files with a .C extension are converted to use a .cpp extension on the remote machine.
False
USE_CONTEXT_AS_BASE
When set to True, the REMOTE_CONTEXT field is interpreted as a base directory name, to which a view name and subsystem name are appended before each object in the view. This switch is always set to False for shadowed Apex NT views.
False

The USE_CONTEXT_AS_BASE switch is provided as a way to give the Visual C++ compiler visibility to needed header files. Windows does not have symbolic links, so the solution is to have a structure that looks like:

By giving the compiler switch -I ViewName, names of the form Subsystem1/file1.h can be correctly processed by the C++ compiler. This isolates the changes that need to be made to both makefiles and source files. The following is an example which shows how the remote filename is arrived at when USE_CONTEXT_AS_BASE is set to True:

For example:

REMOTE_CONTEXT
d:/apex_dev
USE_CONTEXT_AS_BASE
True
Shadowed View
/ned/sierra/shadow.ss/sol.stuckey.wrk
PC-working directory
d:/apex_dev/sol.stuckey/shadow

In addition to facilitating use with Visual C++, USE_CONTEXT_AS_BASE provides a way to maintain the subsystem and view organization on the remote machine. This makes it easy for multiple developers to share machine resources. If each developer creates his own view(s) of the desired subsystems, USE_CONTEXT_AS_BASE will place them in a different subdirectory on the remote machine, thus avoiding possible conflicts which could arise if USE_CONTEXT_AS_BASE were NOT turned on and two views were using the same MACHINE_NAME and REMOTE_CONTEXT.

Note: The shadow_server does NOT detect or attempt to prevent this potential hazard - care should be exercised when using REMOTE_CONTEXTs with USE_CONTEXT_AS_BASE set to False.

Sample Shadow_Location file

Sample Shadowing.sw file

The Shadow_Location and Shadowing.sw files can be created by simply using your favorite text editor.


Windows Client Configurations

There are several different ways to use the Apex Client for Windows, depending on your needs and hardware setup. This section discusses how to setup shadowing and/or the Apex Client in each of these scenarios.

1 . Using Apex NT with shadowing enabled.

If using Apex NT with shadowing enabled, the Apex client can be invoked by selecting the Control > Login to Summit server command from the GUI. Apex NT and Shadowing describes the implementation and use of the shadowing functionality in Apex Ada 95/83 for Windows NT.

2 . Using Apex from the command line or a PC X Server.

You may want to use shadowing to maintain a copy of your controlled files on the PC, but are satisfied with using Apex from a telnet session or via a PC X Server. To use shadowing in this scenario, you would want to ensure that the Apex Shadow Server is running whenever you want files shadowed onto your PC. The easiest way to do this is to create a shortcut to the shadow_server executable in your Startup folder. We recommend starting it minimized. For instructions on how to add an item to the Startup folder, consult the Windows NT help topic "How to start a program each time Windows NT starts".

3 . Invoking the Apex Client directly.

Another scenario is to use the Apex Client directly. In this scenario, you can invoke the Apex Client from the Apex Shadowing item created in the Programs menu when you install the Apex Client on your PC. You will be prompted for the machine to connect to, your login, and your password. You should enter a machine that has Apex installed and on which you have installed the web server, and the web server scripts that are part of the Apex installation. The Shadow Server is implicitly started by the Apex Client.

4 . Using an Microsoft IDE to invoke the Apex Client indirectly via Source Code Control commands. This scenario is described in Using the Apex Client through an IDE.


Apex NT and Shadowing

Apex Ada 95/83 for Windows NT provides an integration with Apex Summit/CM on Unix for configuration and version control management. The set of commands provided by Apex NT, through the command line and via the GUI interface, allows the user to interact with the CM server.

Apex NT uses Summit licenses from the Apex Unix product. The assumption is that user uses the Unix machine only for CM repository and that development is done on the Windows NT system.

Table 3 describes the menu items and dialog boxes that implement the shadowing functionality for this product:

Table 3 Shadowing Commands and Dialogs
Command
Description
Control > Login to Summit Server
Displays a dialog box that can be used to log into the CM server. The remote host name, username and password must be supplied. The specified user must be able to run Summit on the supplied Unix host. After a successful connection to the CM server, the rest of the menu items listed in this table are enabled.
Control > Check In...
Check in and/or control a set of files or directories. The NT view must be shadowed on Unix for this command to work. For the file(s) being controlled (i.e., checked in for the first time), the check box Place under source control should be selected.
Control > Check Out...
Check out previously checked in sets of file(s).
Control > Abandon...
Abandon the check out on previously checked out file(s).
Control > CM Repository Browser...
Bring up a browser on NT, for the CM repository file system (on the CM Server). Several CM operations can be performed through the browser.
Control > Shadow_View...
Shadow an existing NT view on the CM server. In case the NT view is already shadowed (to different CM server view, of course), the user can override the existing shadowing info by ticking the override check box. Moreover, in case the requested view already exists on the CM Server, the user may opt for checking in any checked out files that view might have.

The following dialog boxes have been modified for shadowing:

Table 4 Dialog Box Modifications for Shadowing
Dialog Box
Modification(s)
Create_Subsystem (accessible from File > New > New Subsystem)
A shadow_location option has been added. This option is used to specify the location where the subsystem will be shadowed on the CM server. The specified subsystem is created on the CM server, under the shadow_location, if it does not exist. The simple name of the subsystem will be the same on the NT as well as the CM server.
Create_Working (accessible from File > New > New View)
A shadow_location option has been added. This option is used to specify the location where this view will be shadowed on the CM server. The view and enclosing subsystem are created on the CM server if they do not exist. The simple names of the view and enclosing subsystem will be the same on both the NT and the CM server.
Create_Ada (accessible from File > New > New Ada)
An option to make the file controlled. has been added. If this option is checked, the newly created file is controlled.

Buttons for Check_In, Check_Out, and Abandon have also been added to the File Open tab and the toolbar.

The File Open tab shows the attributes of files by default. This is useful because checked in files are normally read only while checked out files are normally read write.

Examples of the use of shadowing and Apex Ada for Windows NT can be found in the next section.

Using Apex NT with Shadowing for Configuration Management

Apex Ada NT 1.0.2 and later comes with built-in shadowing support. The advantage of shadowing over local (NT) version control tools is the ability to share the Unix sources. The Unix server on which Summit is started as the configuration management (CM) engine is referred to as 'CM Server'. The subsystem/view structure existing locally (on NT) is replicated on the CM server. The corresponding remote (on the CM server) views serve as a repository for storing the files. It is suggested that the development work (involving these files) be carried out on the Windows NT system (using Apex Ada NT), and not on the CM server. The absolute path to the parent where the shadowed view's subsystem is rooted on the CM server, is referred to as the 'shadow location'.

The following scenarios are discussed this section.

Shadowing an existing local (NT) view

Suppose there exists a view c:/Rational/Apex_Ada/project/math.ss/wnt.stuckey.wrk on your NT. You want to put this view under source code control. This can be done as follows:

1 . Establish a connection to the CM Server

In Apex NT, choose the menu item Control > Login to Summit Server and login to the CM server (you need to specify the machine, login id, and password, in the dialog box).

Once this is successful, the menu items for various control operations will become active (ungreyed).

2 . Visit the above mentioned view on your Windows NT system using Apex Ada for Windows NT

Use the directory panel on the left side of the Apex NT window.

3 . Make this view shadowable

Use the menu item Control > Shadow View. In the dialog box, specify the remote shadow location for this view. The shadow location should be an absolute path, with no subsystem/view as one of its components. For example, the shadow location base on the CM Server could be something like: /vc/stuckey/examples

Given this location, use the following command from an NT command shell to make the view shadowable:

4 . Check in the desired files

Invoke the menu item Control > Check In. This raises the Check In dialog box. Choose all the files you wish to control (choose files only, a directory folder cannot be chosen). Select the check box for Place under source control. This should be selected while controlling the files the first time. Select OK.

Use the following command from an NT command shell:

Instead of *.ada, you may list the files.

The designated files have been placed under source code control.

Shadowing a new view and/or subsystem

To create a new view locally (on the Windows NT system), use a command similar to the following:

In order to create a subsystem and a view, and at the same time shadow them, complete the following steps: (Skip step 1, if the subsystem already exists)

1 . Create the subsystem locally (on the Windows NT system).

Invoke the menu item File > New > New Subsystem. Specify the name of the subsystem (/Rational/Apex_Ada/project/complex.ss) and the remote shadow location (/vc/stuckey/examples). This creates the subsystem on the CM Server too.

Do this from the NT command shell with the following command:

2 . Create the view locally (on the Windows NT system)

Invoke the menu item File > New > New View. Specify the view name (wnt.stuckey.wrk). If you skipped step 1 (complex.ss existed already), then your remote shadow location will be empty. Fill in the shadow location base (/vc/stuckey/examples).

Do this from the NT command shell with the following command. This commands assumes you are using the default model.

If you just created the new subsystem (in step 1), you do not need to use the -shadow_location /vc/stuckey/examples option.

On the CM server, /vc/stuckey/examples/complex.ss/wnt.stuckey.wrk will be the shadow view corresponding to C:/Rational/Apex_Ada/project/complex.ss/wnt.stuckey.wrk on the Windows NT system.

Shadowing to an existing view on the CM Server

When you are using Control > Shadow View (to make an NT view shadowable) or File > New > New View (to create a new view on NT), if there exists, on the CM server, a subsystem/view structure with the same name, you have the option of checking in all the checked out files in the view.

Operations from the NT

After you have made a local view shadowable, you may create files, control them, check them out, check them in after modification or even abandon them. All these operations are present under the Control menu item.

Controlling the files

When you create an Ada file (using apex create_ada or the File > New > New Ada menu item), use the Control option to place the file under source code control when it is created.

For files already present that you wish to control, use the Control > Check In command from the GUI or the apex check_in <list_of_files> command from an NT command shell. If you are checking it in a file for the first time, you must place it under source control by selecting the check box Place under source control. Otherwise, the operation fails.

Checking out the files

Use the Control > Check Out menu item from the GUI or the apex check_out <list-of-files> command from an NT command shell. If the file is checked out in another view, you can still check it out by selecting the Private check-out check box on the dialog or using the -private option on the command line.

Abandoning the changes

To abandon your changes, use the Control > Abandon menu item from the GUI or the apex abandon <list-of-files> command from an NT command shell. To keep a copy of the changes, select the Save check box on the Abandon dialog. The changed file will be saved in filename.saved in the corresponding directory (for example, if you abandon imaginary.2.ada with the Save option set, it will be saved in imaginary.2.ada.saved).

Updating the changes

After you have completed your changes, update the files using the Control > Check In menu item.You do not need to select the check box saying Place under source control, if necessary as the file is or the files are already controlled.

Working in disconnected mode

The case may arise where you are not able to connect to the CM Server (for example, this may be due to a network problem or you might be away from the site), but you still want to be able to make modifications to a checked in file. You cannot check out this file as the connection to CM server is not established. In such a situation, use the Control > Make File Writable menu item to change the permission of the file on the NT. This will enable you to modify it. Be very careful doing this as it is then your responsibility to update or merge the file when you connect to the CM Server, so that the sources are in sync with those in the CM repository. It should be noted that this menu item doesn't affect files those are already checked out (that is, writable on NT). Checked out files can be modified whether you are connected to the CM server or not.

Operations from the CM Server

Operations can be issued from the CM server either through the Browser available with Apex NT, or from a remote shell for the CM Server. To use the browser, invoke the menu item Control > CM Repository Browser to raise the Directory Browser for the CM Server. It is a GUI based interface, similar to Apex. If you chose to display the Summit/CM attributes (by ticking the check box), you have further option of displaying checked in objects alone, checked out objects alone, or uncontrolled objects alone. The default is to display all the entries in the directory. You can perform all the operations specified in the previous subsection from the browser. In addition, you can change the properties of objects (files) and views (for example, you can change the history, or accept someone's changes, etc. using the menu items Control > Change Object Properties and Control > Change View Properties).

Tips on using DHCP server enabled NT

NT systems which have opted for Dynamic IP address allocation may find their IP address changing each time they connect to the network. This can cause problems for shadowing. Views shadowed on the CM server have their NT hostname or IP address information in the file Policy/Shadow_Location file in the view. The MACHINE_LOCATION switch holds this value.

This information is updated by default to reflect the current IP address of the NT machine initiating a check_In, check_Out, or abandon operation from the Ada Editor in Apex NT. This automatic update can be suppressed by explicitly deselecting this option in the dialog box while performing the above operations.


Warning: Operations performed from the CM repository browser do not currently do the automatic update of IP address on the CM server. Once the Shadow_Location file has been updated by one of the above operations other operations can be performed from the CM Repository Browser.

Releases prior to 1.0.4 did not do the automatic update of the IP address. Therefore to avoid having to edit the Shadow_Location file in all the shadowed views every time an NT machine was reconnected to the network, it was recommended that in all views, you replace the MACHINE_LOCATION line with the following line:

where, /vc/stuckey/My_Current_IP_Address was the included file which held the IP address. This file had to be updated manually to reflect the new IP address each time you connected to the CM server. Only one file needed to be updated in order for all shadowed views to be updated. This mechanism is no longer required (after 1.0.4). For users that are already using the include directive to specify the IP address, Apex NT can automatically update the included file instead of the Policy/Shadow_Location file.


Using the Apex Client through an IDE

This scenario comes into play when you are primarily programming for the Windows platform, but using Apex to perform configuration management and version control operations. In this mode, you can use Visual C++ 5.0, Visual Basic 5.0, or Rose as your primary IDE (Interactive Development Environment), and access Apex through the Microsoft standard Source Code Control Interface. This allows you to perform routine Summit/CM operations from the standard Windows tools via a "link" to the Apex Client. To perform more involved operations you can cause the Apex Client interface to become active.

The standard installation provided will perform the necessary steps to make Apex your Source Code Control provider so that it will be used from the Microsoft IDE's for operations such as check_in, check_out, etc. In this mode, both the Apex Client and the Apex Shadow Server are implicitly invoked by the IDE. When you first request an operation that requires an Apex server, you will be prompted for a machine name, login, and password just as when you invoke the Apex Client interface directly.

Linking a Project to a Shadowed View

When you create a new IDE project or when you first place a file under Source Code Control in a new IDE project, you will be prompted to specify the full pathname of the Apex view which corresponds to that project. The view specified must be a shadowed view and the shadow directory on the Windows client must be the project directory that will contain the project source files. This view name is saved as part of the IDE project. If you elicit this prompt for the view name by a request to place a file under Source Code Control, you can abort that action after you have specified the view name if you do not actually wish to control the file.

When a project that has been linked to a shadowed view in this way is re-opened, you are prompted to verify the name of the shadowed view. You should respond by simply pressing OK unless you wish to change the view name.

Source Code Control Operations

The operations appearing in the Source Control menu of the IDE are linked to Apex CM commands in a straight-forward manner. The Undo Check Out command is mapped to the abandon command. The Refresh Status command updates the display of the controlled and checked-in/out state in the IDE based on the current Apex CM status of each file. (The status display can become out of date if CM operations are performed without using the Source Control menu.) The Remove from Source Control command is mapped to the uncontrol command.

The Rational Summit/CM command causes the Apex Client to display the Directory Browser window so that the full set of Client operations can be accessed.


Windows Details

The Apex client uses a number of Windows registry keys to manipulate the Apex Client and the Apex Shadow Server. The default installation will set the registry keys correctly. However, it useful to understand which keys are which in the event that your Windows registry becomes corrupt.

The registry values are stored under the registry key

and

The different values for \MyComputer\HKEY_LOCAL_MACHINE\SOFTWARE\RationalSoftware\Apex are:

ApexJavaServerPath
Path of the executable that is used to invoke the Apex Client
ApexJavaServerPort
Socket that is used to communicate between a Source Code Control Provider (e.g. Visual C++ 5.0) and the Apex Client.
ApexShadowServerPath
Path of the executable that is used to invoke the Apex Shadow Server
ApexShadowServerPort
Socket number that is used to communicate between the Apex Shadow Server and an Apex session.
SCCServerName
Name used by an IDE to present Apex in a Source Code Control Provider.
SCCServerPath
Path of the dynamic link library that is loaded by a Source Code Control Provider to provide the link to the Apex Client interface and make Summit/CM operations available.

For \MyComputer\HKEY_LOCAL_MACHINE\SOFTWARE\SourceCodeControlProvide

ProviderRegKey
Identifies the path in the registry to Apex (e.g., Software/Rational Software/Apex)
InstalledSCCProviders
Another way to identify the path in the registry to Apex that is used by a Source Code Control Provider to identify the Summit/CM providers available.

Command Descriptions

shadow_server.exe

Syntax
Description

Starts the Apex shadow server, a Windows based application which handles requests from Apex to synchronize the view and the PC-working directory. When the server starts up, a log window is displayed which will hold tracing output from the various Apex connections. Tracing can be disabled, to provide a significant performance boost, by deselecting the tracing item from the View menu.

Parameters

ntserverw.exe, ntserver.exe

Syntax
Description

Starts the Apex Client, a Windows based application which connects to Apex and show a restricted set of the functions available in Apex. The Apex Client currently provides a subset of the GUI dialog boxes and menu items, available in the Unix version of Apex, but the user can execute any of the Apex command line interface commands through the File > Run dialog.

The Apex Client Interface consists of the following browsers: Directory Browser, Versions Browser, History Browser, Source Browser, Imports Browser, Task Browser. It has support for the Summit/TM and Summit/CM products and the Apex Shadowing interface. The dialogs are similar to their Unix counterparts, but have been enhanced to better fit in the PC environment.

Parameters

Manual Interaction with the Shadow

Although Apex has been customized to automatically transfer files between a view and its associated PC-working directory, there will be circumstances where manual interaction is necessary. Apex provides a GUI interface to commonly used commands under the Tools > Shadow menu item.

The Edit Switches dialog provides support for setting of the Shadow_Location file, the Shadowing.sw, or both from one place.

The Copy To PC dialog, depicted below, provides support for transferring controlled or uncontrolled files to the PC-working directory. When a view or directory is specified, which files are transferred depends on the type of shadowing. The text box at the bottom of the dialog describes these behavioral differences.

The Copy From PC dialog is used to specify files to be transferred from the PC-working directory to the Apex view. As with Copy To PC, the behavior is slightly different for views and directories. As the text box indicates, specifying a view or directory which is a primary shadow copies only checked out objects.

The Clear Failures and Retry Failures dialogs facilitate management of the shadow failures files for shadowed views.


Shadowing Commands

In addition to the commonly used subset of commands available from the GUI, the complete set of shadow commands are available via the apex_shadow command-line interface. The following describes the syntax and function of these commands.

Syntax

clear_failures - clears the failure file for the specified views

Syntax
Description

Clears the failure file, .sdw_failures, in the specified view(s).

Parameters

cmvc_get - copies uncontrolled file from PC

Syntax
Description

Copies a file from the PC that is not under control to the Apex host

Parameters

cmvc_get_file - copies file to host with different name

Syntax
Description

Copies a file from the PC that is or is not under control to the Apex host but to a different name so that the original file and the shadowed file can be compared.

Parameters

cmvc_put - copy Summit/CM information from host to PC shadow

Syntax
Description

Copies Summit/CM information from the Apex host to the PC shadow. This operation is performed whenever a file is shadowed to the PC so that the PC will have some record of the files that are being used on a particular PC. This operation is an internal operation that the user should never invoke.

Parameters

cmvc_put_switch - copy switch information to PC shadow

Syntax
Description

Copies Summit/CM switch information from the Apex host to the PC shadow. This operation is performed whenever a file is shadowed to the PC so that the PC will have some record of the files that are being used on a particular PC. This operation is an internal operation that the user should never invoke.

Parameters

create - create directory

Syntax
Description

Create the specified directories on the PC.

Parameters

expand - expand wildcard on PC

Syntax
Description

Expands the PC-working directory relative name(s), which may contain MS-DOS style wildcards, on the PC. The results are returned as a space delimited list on the standard output. The PC-working directory name is constructed from the Policy/Shadow_Location and Policy/Shadowing.sw settings (the same as for other commands) unless the -clone option is added (see options below for a description of how the PC-working directory name is generated in this instance). If the CONVERT_C_TO_CPP switch is set names with a .cpp extension are converted to a .C extension in the returned match string. This facilitates use of the results in subsequent apex_shadow commands. The filename portion of the name to expand may contain the '*' and '?' wildcard characters. The '*' character matches any string of characters, including the null string. The '?' character matches any single character. Since the Apex shell also supports pattern matching in filenames it is important to enclose arguments containing the aforementioned wildcard characters in double quotes to avoid expansion by the shell. Error output from this command is sent only to standard error to facilitate the use of the output in this command in scripts and as input to subsequent shadow commands.

Example:

Note: Care should be taken when using this command with the FLATTEN_SUBDIRECTORIES switch set since subdirectories are not flattened in the search result. With this switch set, matches returned from expand may not be valid arguments to subsequent apex_shadow commands since flattening will be performed for all other commands.

Parameters

get - transfer files from the PC-working directory to the view.

Syntax
Description

Transfers the specified files from the PC-working directory to the Apex view. If a directory or view is specified, the behavior is determined by the type of shadow. If a directory or view is specified, and the shadow is a primary shadow, all checked-out files in the directory or view are transferred. If a directory or view is specified, and the shadow is a secondary shadow, no action is taken for the specified directory or view.

Note: This command is available in the Apex GUI under Tools > Shadow as Copy From PC.

Parameters

help - display help message for the specified command

Syntax
Description

Displays a help message for the specified apex_shadow command. If no command is specified, help messages are displayed for all commands.

Parameters

info - displays information about how the view is shadowed

Syntax
Description

Displays information about how the view(s) are being shadowed. This information includes the values currently being used for the various shadow related switches.

Parameters

put - transfers files from the view to the PC-working directory

Syntax
Description

Transfers the specified files from the Apex view to the PC-working directory. If a directory or view is specified, the behavior is determined by the kind of shadow. If a directory or view is specified, and the shadow is a primary shadow, no action is taken for the directory or view. If a directory or view is specified, and the shadow is a secondary shadow, all checked-out files in the directory or view are transferred. The put command does not maintain the permissions in the PC-working directory (except in the case of secondary shadows where all files are maintained as read only) nor does it ensure write permission exists before attempting to transfer the file. If the file does not have write permission, the put command will fail.

Note: The put command is intended to be used for transferring uncontrolled or checked-out files. For all other files, the refresh command should be used.

This command is available in the Apex GUI under Tools > Shadow as Copy To PC (uncontrolled or checked-out files).

Parameters

read_only - make the files read-only on the PC

Syntax
Description

Changes the permissions for the specified files to read-only in the PC-working directory. If a directory or view is specified, the operation is performed on all controlled files in the directory or view.

Note: The shadow client maintains permissions according to the type of shadow and Summit/CM attributes of the files. In general use of this command is neither necessary nor recommended. However, it is provided as a tool for manually changing permissions for files in the PC-working directory.

Parameters

read_write - make the files read-write on the PC

Syntax
Description

Changes the permissions for the specified file to read-write in the PC-working directory. If a directory or view is specified, the operation is performed on all controlled files in the directory or view.

Note: The shadow client maintains permissions according to the type of shadow and Summit/CM attributes of the files. In general, use of this command is neither necessary nor recommended. However, it is provided as a tool for manually changing permissions for files in the PC-working directory.

Parameters

refresh - transfers controlled files to the PC-working directory

Syntax
Description

Transfers the specified files from the Apex view to the PC-working directory. If a directory or view is specified, the behavior is determined by the kind of shadow. If a directory or view is specified, and the shadow is a primary shadow, all checked-in files in the directory or view are transferred. If a directory or view is specified, and the shadow is a secondary shadow, all controlled files in the directory or view are transferred. The refresh command makes the files writable before the transfer and sets the permissions to coincide with those in the Apex view when the transfer is complete (except in the case of secondary shadows where all files are maintained as read-only). Uncontrolled files given as an argument to refresh are ignored. For uncontrolled files, the put command should be used.

This command is available in the Apex GUI under Tools > Shadow as Copy To PC (controlled files ONLY)

Parameters

retry_failures - retries the failures in the specified views

Syntax
Description

Retries the commands listed in the shadow failure file, .sdw_failures, for the specified views. Failures are retried in order until a failure occurs or all of the commands in the failure file have been executed successfully. The failure file is updated to reflect the successfully executed commands.

Parameters

set_location - set the location of the PC-working directory

Syntax
Description

Sets the specified fields in the view's Shadow_Location file to the new value. Field names for which options are not specified are left unchanged in the location file.

Parameters

visit - visits the files on the PC

Syntax
Description

Visits the file by spawning the appropriate application on the PC containing the PC-working directory. The application is determined by the Explorer or file manager associations. On Windows 95/NT 4.0 visiting a directory causes the explorer to be launched. If an association is not found for the specified file, an Open With... dialog is displayed, allowing you to choose the application with which the file is opened. Views, whether named explicitly or contained with in a configuration file, are treated like normal directories for the purposes of the visit command (i.e.; they are visited via the explorer).

Parameters


Handling of Failed Commands

If a shadow command issued by Summit/CM is unable to complete successfully, an error message is displayed in the Message Log and the command is appended to the shadow failure file. This might occur if, for example, the shadow server is running on the remote PC, the machine is not up and running, or the required disk is off-line or encounters a read or write error. The failure file is a normal text file named .sdw_failures, and is located at the root level of the shadowed view. Once a failure occurs in a particular shadowed view, no further shadow commands are processed until the failure file is emptied. This helps to maintain consistency between the Apex view and the PC-working directory. If a command is attempted while failures exist in the view, it will fail with a message indicating that it cannot be processed since failures exist in the view. If the command is generated by Summit/CM, it will be appended to the failure file. Once the problem which caused the failure has been alleviated, you can retry the failures using either the Tools > Shadow > Retry Failures command from the GUI or the apex_shadow retry_failures command from the command-line. Both of these commands cause the commands in the failure file to be retried in order until either all of the commands are successfully retried or a failure is encountered. In rare instances, you may end up with an entry or set of entries in the file which will never complete successfully. To alleviate this problem, you can simply edit the .sdw_failures file and remove them. If all of the entries are invalid or unnecessary, use the Tools > Shadow > Clear Failures dialog or apex_shadow clear_failures command to truncate the file.


Enhancements

The copy_view and create_view commands have been enhanced to better support creation of shadowed views. Both commands support three new switches

-shadow_machine
-shadow_port
-shadow_context

These switches allow setting of the corresponding fields in the Shadow_Location file of the destination view. These switches facilitate creating of shadowed views, copying of non-shadowed views to destination views with shadowing enabled, and modifying the Shadow_Location fields during a copy_view operation. See Shadowing Examples for an example of how these switches can be used.


Clones

In addition to the shadow or PC-working directory, Apex supports the concept of a clone. Clones are additional locations in which some or all of the contents of the Apex view are maintained. Unlike a shadow, Summit/CM does not contain support for automatic updating of clones. Updating the contents of a clone is accomplished through the use of the manual apex_shadow commands.

The clone mechanism allows one to distribute the contents of a single view to multiple remote machines. If, for example, your view contains artifacts such as object files and shared libraries (.dlls) which are used by a group of developers working on a layered project, you could provide these artifacts via the clone mechanism. One major advantage to this approach, over creating a shadowed view for each developer, is that the Unix disk space requirements are minimized. With a normal shadow, the objects and dlls exist on both the developer's PC and the corresponding Apex view. Using clones, there is a single source directory on Unix which contains the artifacts to be distributed.

Support for clones is provided via five command options: -clone, -clone_log, -machine_name, -port_number, and -remote_context. These options are supported by all of the various apex_shadow commands which perform operations on the remote PC. The -clone option indicates that the command is to be performed on a clone instead of the views shadow. The -clone_log option indicates that the operation is to be performed on a clone instead of the view's shadow and that a log entry should be entered in the specified logfile. Log entries are of the form:

Success is indicated by the "+++" prefix and a failure is indicated by the prefix "***". The following is an example log file:

The -machine_name and -remote_context options are both required when the -clone or -clone_log option is specified. These options identify the location of the clone. For example, if you wish to transfer the .dll files in your Apex view to a directory called d:/libraries on the machine "grumby", you would issue an apex_shadow put (or refresh if the files are controlled) command with the -clone option, and specify "grumby" as the machine_name and d:/libraries as the remote_context for the clone. Keep in mind, however, that the actual context used may be affected by the USE_CONTEXT_AS_BASE switch in the Policy/Shadowing.sw file. The -port_number option can be used to specify the port number to which the Apex shadow server is connected. If the -port_number option is omitted, the default value is used.


Shadowing Examples

The following are examples of the use of shadowing.

Microsoft Word Documents

This example illustrates how shadowing can be used to place a collection of Microsoft Word documents on a PC under Apex source code control. Specifically, two files, shadow.doc and shadow.html, will be placed under control in a hypothetical directory /ned/sierra/shadow/shadow_doc.ss/wnt.stuckey.wrk, using d:/apex_dev/doc as the base for the PC-working directory of a linked view on a hypothetical PC called "pc-5".

The following is a summary of the steps required followed by more detailed instructions.

1 . Create the Apex subsystem(s) and view(s) for the documents to be controlled.

2 . Create the Shadow_Location and Shadowing.sw switches file in the Policy directory of the view(s) you wish to shadow.

3 . Install the shadow_server on the machine you wish to maintain a PC-working directory.

4 . Check-in the documents you wish to control

Creating the Subsystem(s) and View(s)

From the directory viewer, select File > New > New Subsystem. Enter the path for the subsystem which, in our case, is /ned/sierra/shadow/shadow_doc.ss. From the directory viewer for the newly created subsystem, select File > New > New View. Enter the name of the view which would be wnt.stuckey.wrk.

For a detailed description of how to create and configure views and subsystems, consult the Apex on-line documentation.

Creating the Shadow Switch File

The next step is to create the Shadow_Location and Shadow.sw switch file which will describe when, where, and how to shadow our newly created view. From the directory view for the new view, select Tools > Shadowing > Edit Switches. Edit the dialog as follows and then press the Write files button at the top.

Installing the Shadow Server

For a description of how to install the server, consult Installation and Setup. Once you have gotten the server up and running on your PC, you are ready to start using shadowing.

Checking-In the Documents

In order to check-in the documents, you need to first get all of the documents you wish to control into either the PC-working directory or the view. If the PC-working directory doesn't already exist, you can create it using the apex_shadow create view command to create the empty PC-working directory. You can then use the File Manager or Explorer to copy or move the files into the PC-working directory. If the files are scattered across multiple machines you could use ftp to transfer the files into either the PC-working directory or the view. Below is an example of how to check-in the files for both scenarios.

Files reside in the Apex View prior to check-in

After transferring the files into the Apex view from the directory viewer for the shadowed view, select the files you wish to check-in (place under control) and select Control > Check-In. Click on the Place files under source control radio-box and then select OK. The files will be checked in, and transferred to the PC-working directory.

Files reside in the PC-working directory prior to check-in

From an Apex shell, cd to the view you are shadowing from. Use the command apex_shadow get filename to copy the files from the PC-working directory into your view. If there are a number of files to copy and they share, for example, a common extension, you can use the expand command in combination with the get command to make things simpler. The command might look something like:

Note: You can also perform the manual get by using the Tools > Shadowing > Copy From PC dialog. You can then use the Control > Check-In command to place the files under Apex control. The get command is required to transfer the files since, at this time, the check-in command does not allow you to specify files which do not exist in the Apex view.

Basic Operations

Once you have your Microsoft Word documents under Apex source code control, you can perform version control operations from Apex as you normally would. The controlled files in the PC-working directory will have their permissions set to reflect the state of the file in Apex. That is, checked-in files will be read-only and checked-out files will be read-write. In order to edit a file, you first check it out using Apex, edit the file under Microsoft Word, and when you are done, check the file in using Apex. When you issue the check-in command for the file, it will be automatically transferred from the PC to Apex before the check-in. You can even start up Microsoft Word (or any other application with the appropriate Windows File Association) using the special apex_shadow visit command on the desired file.

Microsoft Developer Studio Project

This example demonstrates how shadowing can be used to place objects in a Microsoft Developer Studio project under Summit/CM control. The mechanism and procedure will be essentially the same as that used in the Microsoft Word document example above. In this example, we will place the cube example from DevStudio, located in d:/samples/cube, under Apex control in a subsystem/view called /vc/stuckey/examples/cube.ss/wnt.stuckey.wrk.

The following is an outline of the steps we will take:

1 . Create the subsystem(s) and view(s) for the project.

2 . Create the shadow switches file in the Policy directory of the view(s).

3 . Install the shadow_server on the machine you wish to contain the shadowed view.

4 . Check-in the objects from the project you wish to place under control.

Creating the Subsystem(s) and View(s)

From the directory viewer select File > New > New Subsystem. Enter the path for the subsystem which, in our case, is /vc/stuckey/examples/cube.ss. From the directory viewer for the newly created subsystem, select File > New > New View. Enter the name of the view which would be wnt.stuckey.wrk.

For a detailed description of how to create and configure views and subsystems, consult the Apex on-line documentation.

Creating the Shadow Switch File

From the directory view for the new view, select Tools > Shadowing > Edit Switches. Enter the following into the dialog:

Installing the Shadow Server

For a description of how to install the server, consult Installation and Setup. Once you have gotten the server up and running on your PC, you are ready to start using shadowing.

Checking-In the Files

Now that we have things set up in the Apex view and on the PC, we are ready to actually place the files under Apex control. To check-in the files, you first need to get them into the view. For this operation, we will use the Tools > Shadowing > Copy From PC dialog to transfer the files. From the directory viewer for the view, bring up the Copy From PC dialog and enter the following:

Alternatively, you could have used the command-line apex_shadow get command to accomplish the same thing. Now that the files are in the view, you can check them in using Control > Check-In. You should now be able to enhance the cube example with all of your development efforts recorded in the Summit/CM database.

Using Clones

The following example shows how shadowing and clones could be used effectively to manage and automate the distribution of shared libraries and objects to a collection of developers while minimizing the Unix disk space requirements.

Suppose that a development team consists of one developer who is in charge of building and maintaining a set of dlls and objects which comprise the low-level API layer for the project, and several other engineers who are designing layered tools and libraries. In order for the tool and layer library developers to compile and link their code, they need visibility to the header files and potentially the objects and libraries built by the low-level API developer. One approach to solving this problem would be for each of these developers to simply create their own shadowed view of the subsystems associated with the base API. However, this approach requires enough disk space on the Unix system for each developer to have her own view in addition to the disk space requirements for the PC to which the view is shadowed. A better approach might be for the API developer to use the clone mechanism to distribute the contents of his shadowed views to the other developers.

To use this model, the API developer would first create shadowed views and place his source files under control in those views. He would then be able to maintain the files using Summit/CM. Once all of the desired changes were completed and the dlls and objects built on his PC, the developer would use a command similar to the following to move the uncontrolled compilation artifacts (the dlls and objects) from the PC-working directory to the view:

Finally, the API developer would distribute the header files and results of his builds using the clone mechanism. The commands would be something like:

These transfer commands would be issued for each developer's clone. The process could easily by automated by putting the list of clone commands into a shell script which the API developer would run once his view was in the desired state. After completion of the script, the clone log, clones.log could be examined to ensure that all of the commands were successful.

Creating Shadowed Views from Existing Views

Another common operation one might perform is the creation of a shadowed view from an existing shadowed or non-shadowed view. To do this, you simply specify the desired Shadow_Location settings as part of the copy_view command. For example, suppose your co-worker, beavis, wants to copy your wnt.stuckey.wrk view of cube.ss from the preceding example to wnt.beavis.wrk on his own PC so that he too can enjoy the wonders of PC development. The easiest way to do this is to bring up the File > Copy Object dialog to copy the view and then select the shadow options button. Selecting the shadow options radio button brings up a form which allows you to specify the Shadow_Location settings. The completed dialog for the aforementioned copy view operation would look like:

Alternately, the command-line copy_view command could be used to perform this operation. The command would be something like:

Either of the above mentioned view copying methods will copy the view, update the Shadow_Location file in the new view, and perform a shadow refresh to transfer the files to the PC-working directory on beavis' PC.


Rational Software Corporation 
http://www.rational.com
support@rational.com
techpubs@rational.com
Copyright © 1993-2002, Rational Software Corporation. All rights reserved.
TOC PREV NEXT INDEX DOC LIST MASTER INDEX TECHNOTES APEX TIPS