![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
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
- Shadowing Overview
- Installation and Setup
- Shadowing Concepts
- Windows Client Configurations
- Apex NT and Shadowing
- Using the Apex Client through an IDE
- Windows Details
- Shadowing Commands
- Handling of Failed Commands
- Enhancements
- Clones
- Shadowing Examples
Remote Java Interface / Web BrowserThere 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
http://<your-server-machine>/apex
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
$APEX_HOME/web/sun4_solaris2/bin/startapex
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:
cd <jre-dir> uncompress jre.tar.Z tar -xvf jre.tar
You can then run the Java interface using the command:
<jre-dir>/bin/startapex
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:
java displays.startApex
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 OverviewShadowing support is based on the following concepts:
- Shadowed view
Also referred to as a linked view or simply the view, is a view which has been configured to use shadowing to maintain its contents and state in both the Unix based Apex directory and a PC-working directory.
- PC-Working directory
Also referred to as a shadow, this is a directory located on a remote PC which is linked to a view. When shadowing is enabled, Apex issues commands to the shadow server to keep the contents of the shadowed view and the PC-working directory in sync.
- Apex Client
This is a Windows NT/95 executable required for each PC that wants to execute GUI commands without using a PC X Server. The Apex Client provides a graphical user interface to Apex that allows the user to browse subsystems and views on the Apex Host, browse versions and histories, as well as issue Apex commands, including Summit/TM support. It uses the http protocol to start an Apex session running on an Apex host and communicates with Apex via a TCP/IP connection.
- Microsoft Integration DLLs
These are a set of Windows DLL's that are installed by the Apex Client installation so that Microsoft IDE's will be enabled to use Apex for performing Summit.CM operations from the Microsoft IDEs such as Visual C++ and Visual Basic. In addition, recent versions of Rose have been enhanced to support using Apex commands directly from Rose for performing Summit/CM operations.
Rational recommends that Integration DLLS not be used with Apex Ada 95/83 for Windows NT.
- Shadow server
This is a Windows NT/95 executable required for each PC which is to hold a PC-working directory. The server maintains TCP/IP stream-based socket connections with various Apex sessions and responds to requests from Apex via these connections. The server, called shadow_server.exe is provided as part of the Apex release. Details on setup and configuration of the shadow server can be found in the setup section below. The shadow server is automatically installed when Apex NT is installed with shadowing enabled.
- Shadow location
This is comprised of three components; a machine name, a port number, and a remote context. The machine name and port number describe the shadow server to which a connection should be established for performing shadow operations. The remote context describes the remote directory context for the PC-working directory. It's exact use is dependent upon shadow context switch settings described below. The shadow location settings for a particular view can be found in the Policy/Shadow_Location file.
- Shadow Kinds
There are two kinds of shadows supported by Apex shadowing. The default shadow type is called a primary shadow and is intended for users who are going to develop their application on the PC. The second type of shadow is called a secondary shadow and is intended for users who are going to develop their application on Unix.
- Primary shadow
For a Primary shadow, checked-out files have their real source in the PC-working directory. When files are controlled or checked-in they are first transferred from the PC-working directory to the shadowed view before the operation is actually performed (this is done automatically by Apex). Controlled and checked-in files on a primary shadow have their real source in the view (uncontrolled files are not shadowed).
NT views shadowed from Apex NT are always primary shadows.
- Secondary shadow
For a secondary shadow, all files have their real source in the view. File permissions in the PC-working directory do not track those of the file in the linked view. Instead, all files in the PC-working directory are maintained with read-only permission. This is ideal for editing and controlling files under Apex on Unix and then compiling and linking in the PC-working directory.
- Clones
A clone is a location where some or all of the contents of a shadowed view can be maintained using the apex_shadow commands described below. This location is distinct from the PC-working directory described in the Policy/Shadow_Location file. Unlike the PC-working directory, Summit/CM does not automatically update the contents and permissions of files in the clone when a Summit/CM command is issued from Apex. The contents of the clone can only be updated via the manual apex_shadow commands. For additional information on clones, see Clones.
Installation and SetupInstallation
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 ConceptsShadowing 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.
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:
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.
MACHINE_NAME: pc-5 PORT_NUMBER: 1041 REMOTE_CONTEXT: d:/apex_dev
FLATTEN_SUBDIRECTORIES: false DEFAULT_IS_ASCII: false ALWAYS_USE_ASCII: *.C *.c *.cpp *.h *.mak NEVER_USE_ASCII: *.rc *.ico *.bmp *.mdp *.obj *.exe CONVERT_C_TO_CPP: true USE_CONTEXT_AS_BASE: true SHADOW_KIND: PrimaryThe Shadow_Location and Shadowing.sw files can be created by simply using your favorite text editor.
Windows Client ConfigurationsThere 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 ShadowingApex 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:
The following dialog boxes have been modified for shadowing:
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
- Shadowing a new view and/or subsystem
- Shadowing to an existing view on the CM Server
- Operations from the NT
- Operations from the CM Server
- Tips on using DHCP server enabled NT
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:
apex shadow /vc/stuckey/examples \ c:/Rational/Apex_Ada/project/math.ss/wnt.stuckey.wrk
- 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:
apex check_in -control *.ada
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:
c:/Rational/Apex_Ada/project/complex.ss/wnt.stuckey.wrk
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:
apex create_subsystem -shadow_location /vc/stuckey/examples \ -enable_shadow /Rational/Apex_Ada/project/complex.ss/wnt.stuckey.wrk- 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.
apex create_working -shadow_location /vc/stuckey/examples \ -enable_shadow wnt.stuckey.wrk
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:
#include /vc/stuckey/My_Current_IP_Address
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 IDEThis 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 DetailsThe 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
\MyComputer\HKEY_LOCAL_MACHINE\SOFTWARE\RationalSoftware\Apex
\MyComputer\HKEY_LOCAL_MACHINE\SOFTWARE\SourceCodeControlProvider
The different values for \MyComputer\HKEY_LOCAL_MACHINE\SOFTWARE\RationalSoftware\Apex are:
For \MyComputer\HKEY_LOCAL_MACHINE\SOFTWARE\SourceCodeControlProvide
Command Descriptions
shadow_server.exe
Syntax
shadow_server [port number]
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
- port number
Specifies the port the server is to listen on for Apex connections. If not specified, the default value is 1041.
ntserverw.exe, ntserver.exe
Syntax
ntserver,ntserverw -port <tcp-port-num> -show_browser -perm_server -help -trace -tracefile <filename>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
- -port <tcp-port-num>
Specifies the port number that is used in communicating with Apex running on a host platform
- -show_browser
Start the Apex Client and immediately show the directory viewer. Without this parameter, the Apex Client runs in the background waiting for a connection from an application (e.g. Visual C++) that supports the Microsoft Source Code Control interface.
- -perm_server
Normally the Apex Client exits when the number of connections from Source Code Control Providers plus the number of visible Windows from the Apex Client program is zero. However, you may want to run the Apex Client whenever you start up Windows and to continue even after exiting a typical Windows IDE. By setting this parameter, the Apex Client program will NOT terminate when you are not running an application that is using the Source Code Control Interface or running the client GUI and will wait for a later connection.
- -trace
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 CommandsIn 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
apex_shadowcommand
[options]arguments
clear_failures - clears the failure file for the specified views
Syntax
apex_shadow clear_failuresviews
| configurations ...Description
Clears the failure file, .sdw_failures, in the specified view(s).
Parameters
cmvc_get - copies uncontrolled file from PC
Syntax
apex_shadow cmvc_get [-clone] [-clone_log logfile] [-machine_name clone_machine] [-port_number clone_port] [-remote_context clone_context] files | directories | viewDescription
Copies a file from the PC that is not under control to the Apex host
Parameters
- files
These are the files to copy from the PC to the Unix host. They are specified using PC names relative to the shadow of the view from where cmvc_get is invoked.
- options
Specifies that the command is to be performed for a clone instead of the normal shadow location in Policy/Shadow_Location.
Specifies that the command is to be performed for a clone instead of the normal shadow location in Policy/Shadow_Location and that a log entry should be entered in logfile.
Specifies the machine name to use for the clone. This option is only valid if the -clone or -clone_log is present.
Specifies the port number to use when connecting to the shadow server for the clone. This option is only valid if the -clone or -clone_log option is also present.
Specifies the remote context for the clone. For expansion, this is the basename used to construct the PC-working directory in which to perform the pattern matching. This option is only valid if the -clone or -clone_log option is present.
cmvc_get_file - copies file to host with different name
Syntax
apex_shadow cmvc_get_file [-clone] [-clone_log logfile] [-machine_name clone_machine] [-port_number clone_port] [-remote_context clone_context] [-name filename] filesDescription
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
- -name filename
This is the filename that the file from the PC will be copied to.
- files
These are the files relative to the PC shadow that will be copied to the Apex Host.
- options
Specifies that the command is to be performed for a clone instead of the normal shadow location in Policy/Shadow_Location.
Specifies that the command is to be performed for a clone instead of the normal shadow location in Policy/Shadow_Location and that a log entry should be entered in logfile.
Specifies the machine name to use for the clone. This option is only valid if the -clone or -clone_log is present.
Specifies the port number to use when connecting to the shadow server for the clone. This option is only valid if the
-clone or -clone_log option is also present.Specifies the remote context for the clone. For expansion, this is the basename used to construct the PC-working directory in which to perform the pattern matching. This option is only valid if the -clone or -clone_log option is present.
cmvc_put - copy Summit/CM information from host to PC shadow
Syntax
apex_shadow cmvc_put [-clone] [-clone_log logfile] [-machine_name clone_machine] [-port_number clone_port] [-remote_context clone_context] filesDescription
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
- files
File whose Summit/CM information should be copied to the PC.
- options
Specifies that the command is to be performed for a clone instead of the normal shadow location in Policy/Shadow_Location.
Specifies that the command is to be performed for a clone instead of the normal shadow location in Policy/Shadow_Location and that a log entry should be entered in logfile.
Specifies the machine name to use for the clone. This option is only valid if the -clone or -clone_log is present.
Specifies the port number to use when connecting to the shadow server for the clone. This option is only valid if the -clone or -clone_log option is also present.
Specifies the remote context for the clone. For expansion, this is the basename used to construct the PC-working directory in which to perform the pattern matching. This option is only valid if the -clone or -clone_log option is present.
cmvc_put_switch - copy switch information to PC shadow
Syntax
apex_shadow cmvc_put_switch [-clone] [-clone_log logfile] [-machine_name clone_machine] [-port_number clone_port] [-remote_context clone_context] viewDescription
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
- view
View whose shadow switches should be copied to the PC.
- options
Specifies that the command is to be performed for a clone instead of the normal shadow location in Policy/Shadow_Location.
Specifies that the command is to be performed for a clone instead of the normal shadow location in Policy/Shadow_Location and that a log entry should be entered in logfile.
Specifies the machine name to use for the clone. This option is only valid if the -clone or -clone_log is present.
Specifies the port number to use when connecting to the shadow server for the clone. This option is only valid if the -clone or -clone_log option is also present.
Specifies the remote context for the clone. For expansion, this is the basename used to construct the PC-working directory in which to perform the pattern matching. This option is only valid if the -clone or -clone_log option is present.
create - create directory
Syntax
apex_shadow createdirectories
...Description
Create the specified directories on the PC.
Parameters
expand - expand wildcard on PC
Syntax
apex_shadow expand [-clone] [-clone_log logfile] [-machine_name machine] [-port_number port] [-remote_context context] msdos_wildcard_name ...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.
> apex_shadow expand "foodir/foo*.h" foodir/foo.h foodir/foobar.h
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
- msdos_wildcard_name
Specifies the PC-working directory relative name to perform pattern matching for on the PC. The filename may contain the "*" and "?" wildcard characters. Any subdirectories specified may not contain wildcards. That is, "*.h" and "headers/*.h" are acceptable, but "*/*.h" is not since it contains a wildcard in the directory name. Names containing wildcards should be enclosed in double quotes to avoid expansion by the shell.
- options
Specifies that the command is to be performed for a clone instead of the normal shadow location in Policy/Shadow_Location.
Specifies that the command is to be performed for a clone instead of the normal shadow location in Policy/Shadow_Location and that a log entry should be entered in logfile.
Specifies the machine name to use for the clone. This option is only valid if the -clone or -clone_log is present.
Specifies the port number to use when connecting to the shadow server for the clone. This option is only valid if the -clone or -clone_log option is also present.
Specifies the remote context for the clone. For expansion, this is the basename used to construct the PC-working directory in which to perform the pattern matching. This option is only valid if the -clone or -clone_log option is present.
get - transfer files from the PC-working directory to the view.
Syntax
apex_shadow get [-clone] [-clone_log logfile] [-machine_name machine] [-port_number port] [-remote_context context] files | directories | views | configurations ...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
- files | directories | views | configurations
Specifies the files to be transferred.
- options
Specifies that the command is to be performed for a clone instead of the normal shadow location in Policy/Shadow_Location.
Specifies that the command is to be performed for a clone instead of the normal shadow location in Policy/Shadow_Location and that a log entry should be entered in logfile.
Specifies the machine name to use for the clone. This option is only valid if the -clone or -clone_log is present.
Specifies the port number to use when connecting to the shadow server for the clone. This option is only valid if the -clone or -clone_log option is also present.
Specifies the remote context for the clone. This option is only valid if the -clone or -clone_log option is present.
help - display help message for the specified command
Syntax
apex_shadow help [command] ...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
apex_shadow infoviews
|configurations
...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
- views | configurations
Specifies the views for which the shadow information is to be displayed.
- options
put - transfers files from the view to the PC-working directory
Syntax
apex_shadow put [-clone] [-clone_log logfile] [-machine_name machine] [-port_number port] [-remote_context context]files
|directories
|views
|configurations
...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
- files | directories | views | configurations
Specifies the files to be transferred to the PC-working directory.
- options
Specifies that the command is to be performed for a clone instead of the normal shadow location in Policy/Shadow_Location.
Specifies that the command is to be performed for a clone instead of the normal shadow location in Policy/Shadow_Location and that a log entry should be entered in logfile.
Specifies the machine name to use for the clone. This option is only valid if the -clone or -clone_log is present.
Specifies the port number to use when connecting to the shadow server for the clone. This option is only valid if the -clone or -clone_log option is also present.
Specifies the remote context for the clone. This option is only valid if the -clone or -clone_log option is present.
read_only - make the files read-only on the PC
Syntax
apex_shadow read_only [-clone] [-clone_log logfile] [-machine_name machine] [-port_number port] [-remote_context context]files
|directories
|views
|configurations
...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
- files | directories | views | configurations
Specifies the files whose permissions are to be changed.
- options
Specifies that the command is to be performed for a clone instead of the normal shadow location in Policy/Shadow_Location.
Specifies that the command is to be performed for a clone instead of the normal shadow location in Policy/Shadow_Location and that a log entry should be entered in logfile.
Specifies the machine name to use for the clone. This option is only valid if the -clone or -clone_log is present.
Specifies the port number to use when connecting to the shadow server for the clone. This option is only valid if the -clone or -clone_log option is also present.
Specifies the remote context for the clone. This option is only valid if the -clone or -clone_log option is present.
read_write - make the files read-write on the PC
Syntax
apex_shadow read_write [-clone] [-clone_log logfile] [-machine_name machine] [-port_number port] [-remote_context context]files
|directories
|views
|configurations
...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
- files | directories | views | configurations
Specifies the files whose permissions are to be changed.
- options
Specifies that the command is to be performed for a clone instead of the normal shadow location in Policy/Shadow_Location.
Specifies that the command is to be performed for a clone instead of the normal shadow location in Policy/Shadow_Location and that a log entry should be entered in logfile.
Specifies the machine name to use for the clone. This option is only valid if the -clone or -clone_log is present.
Specifies the port number to use when connecting to the shadow server for the clone. This option is only valid if the -clone or -clone_log option is also present.
Specifies the remote context for the clone. This option is only valid if the -clone or -clone_log option is present.
refresh - transfers controlled files to the PC-working directory
Syntax
apex_shadow refresh [-clone] [-clone_log logfile] [-machine_name machine] [-port_number port] [-remote_context context]files
|directories
|views
|configurations
...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
- files | directories | views | configurations
Specifies the files to be transferred to the PC-working directory.
- options
Specifies that the command is to be performed for a clone instead of the normal shadow location in Policy/Shadow_Location.
Specifies that the command is to be performed for a clone instead of the normal shadow location in Policy/Shadow_Location and that a log entry should be entered in logfile.
Specifies the machine name to use for the clone. This option is only valid if the -clone or -clone_log is present.
Specifies the port number to use when connecting to the shadow server for the clone. This option is only valid if the -clone or -clone_log option is also present.
Specifies the remote context for the clone. This option is only valid if the -clone or -clone_log option is present.
retry_failures - retries the failures in the specified views
Syntax
apex_shadow retry_failuresviews
|configurations
...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
apex_shadow set_location [-machine_namemachine
] [-port_numberport
] [-remote_contextcontext
]views
|configurations
...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
- views | configurations
Specifies the view whose Shadow_Location file is to be updated.
- options
-machine_name machine
Specifies the value for the MACHINE_NAME field in the Shadow_Location file. This is the PC on which the PC-working directory is to reside.
-port_number port
Specifies the value for the PORT_NUMBER field in the Shadow_Location file. This is the port number being used by the shadow server.
-remote_context context
Specifies the value for the REMOTE_CONTEXT field in the Shadow_Location file. This is the context for the PC-working directory.
visit - visits the files on the PC
Syntax
apex_shadow visit [-clone] [-clone_log logfile] [-machine_name machine] [-port_number port] [-remote_context context]files
|directories
|views
|configurations
...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
- files | directories | views | configurations
Specifies the name of file or directory to visit on the PC.
- options
Specifies that the command is to be performed for a clone instead of the normal shadow location in Policy/Shadow_Location.
Specifies that the command is to be performed for a clone instead of the normal shadow location in Policy/Shadow_Location and that a log entry should be entered in logfile.
Specifies the machine name to use for the clone. This option is only valid if the -clone or -clone_log is present.
Specifies the port number to use when connecting to the shadow server for the clone. This option is only valid if the -clone or -clone_log option is also present.
Specifies the remote context for the clone. This option is only valid if the -clone or -clone_log option is present.
Handling of Failed CommandsIf 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.
EnhancementsThe 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_contextThese 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.
ClonesIn 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:
<timestamp> <success/failure indicator> <command>
Success is indicated by the "+++" prefix and a failure is indicated by the prefix "***". The following is an example log file:
11:26:20 +++ apex_shadow refresh -clone_log /vc/stuckey/logfile -machine_name grumby -remote_context d:/apex_dev sourcefile.h
11:27:23 *** apex_shadow put -clone_log /vc/stuckey/logfile -machine_name grumby -remote_context d:/apex_dev sourcefile.objThe -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 ExamplesThe following are examples of the use of shadowing.
- Microsoft Word Documents
- Microsoft Developer Studio Project
- Using Clones
- Creating Shadowed Views from Existing Views
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:
apex_shadow get `apex_shadow expand "*.doc" "*.html"`
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:
apex_shadow get `apex_shadow expand "*.dll" "*.obj"`
Finally, the API developer would distribute the header files and results of his builds using the clone mechanism. The commands would be something like:
apex_shadow refresh -clone_log clones.log -machine_name dev1 -remote_context c:/baselib *.h apex_shadow put -clone_log clones.log -machine_name dev1 -remote_context c:/baselib *.dll *.obj
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:
apex copy_view -shadow_machine pc-6 -shadow_port 1234 -shadow_context d:/beavis/dev/vc/stuckey/examples/cube.ss /wnt.stuckey.wrk /vc/beavis/examples/cube.ss/wnt.beavis.wrk
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. |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |