~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
              This is the readme file for QVCS-Enterprise Client.
                      $Label: 2.1.24 $
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

QVCS-Enterprise Client is published by:

                           Quma Software, Inc.
                          20 Warren Manor Court
                         Cockeysville, MD  21030

To report problems or suggestions, please send e-mail to:

                       jimv@qumasoft.com

Make sure to include 'QVCS-Enterprise' in the subject line so that we'll be able
to distinguish your suggestion and/or bug report from the many SPAM messages that
we receive.


This zip file contains the files you need to run QVCS-Enterprise Client.  It
also contains the QVCSEnterpriseSCC.dll file which is needed if you wish to 
use QVCS-Enterprise with a Microsoft SCC compliant IDE (like Visual Studio
2008,VS 2005, VS 2003, or PowerBuilder).

For IDE integration, the installer that includes this readme.txt has already
modified your Windows Registry so that you can use this client with any
Microsoft SCC compliant IDE  (see below).

This installation does NOT contain the files needed to run QVCS-Enterprise Server.

In order for the files here to be useful, you must know some information about a 
QVCS-Enterprise Server that this client will connect to. Without a server,
there isn't much you can do with this software.


Getting Started:
================
Before you can use either server or client, you must first download and install
an appropriate Java virtual machine.  We have only tested with Sun's JVM's.
Sun's download site is available at this URL:

http://java.sun.com/j2se/downloads.html

We have tested with the Java 6 and Java 5 JVMs.  At the very minimum, QVCS-Enterprise 
requires J2SE 5.0 (a.k.a. 1.5) or later.


Step 1: Unzip the archive:
==========================
Unzip the QVCSEnterpriseClient.zip file into an empty directory, making sure to 
preserve the directory structure of the files present in the .zip file.  (If
you used the installer (Windows only), this has already been done for you).


Step 2: Start the client:
=========================
For Windows users, open a command window, and execute the gui.bat batch file.

For Linux or UNIX users, open a shell window, and execute the gui.sh shell
script (you may need to chmod +x to make it executable).

The client should start up, and display a 3 pane window.  You may want to 
resize the window and its elements.


Step 3: Define the server:
==========================
Click on the 'Servers' node on the tree control at the left side of the screen.
Right click, and select the 'Add Server' menu item.

On the resulting 'Server Properties' dialog, enter a name for the server, and
fill in the other two fields.  You will need to get this information from 
whomever is in charge of the server that you are wanting to connect to. (The
default port for QVCS-Enterprise Servers is 9889).

Click OK.


Step 4: Login to the server:
============================
Click on the new server node that appears beneath the 'Servers' node that you 
worked with in Step 3.

A 'Server Login' dialog will appear.  Enter your user name and password, and 
click OK. 

Note that an administrator must have already defined an account and projects for 
you in order for you to be able to login to the server.

The login may take a short while, depending on the speed of your machine, and
the speed of the connection between your machine and the server.

When the login succeeds, then you will see a list of the projects on that server
that you have READ rights to.  (You may also have WRITE rights to those projects.
If you do not have READ rights to the project, it will not appear in the list
of projects).


Step 5: Define your workfile location for a project:
====================================================
Click on any one of the project nodes that appear beneath the server node.

You should get a 'Define Workfile Location' dialog.  On that dialog, click the 
'...' button next to the 'Location of your files' edit box.  Use the resulting
dialog to define the root directory of the workfile directory hierarchy that
you want to use for the selected project.  Click OK.


Step 6:  Add files to version control:
======================================
When you successfully define the workfile location for a project, the gui client
will display the workfile location in the header control above the file list
pane on the right side of the screen.  If there are any files in the directory
that you selected, they will appear in the file list pane, and the 'File status'
column will show them with a status of 'Not controlled', meaning that they are
not currently under version control.

To add the files of your project to version control, select the project node
in the tree control on the left side of the screen.  Right click, and select the
'Auto-add File/Directories' menu option.

On the resulting 'Auto Add Files/Directories' dialog, fill in the fields as 
seems appropriate, and click OK.

A progress window should appear.  When everything is finished, You should see 
the status of the files change from 'Not Controlled' to 'Current'.


Step 7:  And Beyond:
====================
You now have some files at least under version control, and you are on your way.

The gui client has a toolbar which you can use if you do not want a dialog
to fine-tune your action -- e.g. clicking the 'Check out' button will check out
the latest revision from the selected file(s).

If you want finer control of the action, then use the context (right click) menus
that popup when you right click on a file, or other control element.

In the gui, most of the things you will want to do can be done via context 
(right click) menus.  The menu bar menus at the top of the screen also supply
functionality similar to the functionality supplied by the context menus.

Step 8: (Optional, for Windows users only):
===========================================
In order to use IDE integration, you must first have files under version control
and visible within the client application.  Provided you have done that, then
getting IDE integration to work is straight forward:

============================================================================
============================================================================

IMPORTANT == IMPORTANT == IMPORTANT == IMPORTANT == IMPORTANT == IMPORTANT
IMPORTANT == IMPORTANT == IMPORTANT == IMPORTANT == IMPORTANT == IMPORTANT
IMPORTANT == IMPORTANT == IMPORTANT == IMPORTANT == IMPORTANT == IMPORTANT

MAKE SURE YOU INSTALLED YOUR CLIENT USING THE CLIENT INSTALLER APPLICATION
AVAILABLE AS A SEPARATE DOWNLOAD FROM THE QUMA WEB SITE:

http://www.qumasoft.com/downloads.html

The qvcsEnterpriseClientInstaller.exe installer installs the client application
(similar to the result you get by unzipping the QVCSEnterpriseClient.zip that
you can download directly from your QVCS-Enterprise server) and it also adds
entries to your Windows Registry that identify the QVCS Enterprise client
.dll that can supply IDE integration functionality.

============================================================================
============================================================================

Launch your IDE.  The QVCS-Enterprise client installer has already set the Windows
registry so that QVCS-Enterprise is registered as the default version control 
tool.

You should just have to select the project that is already under version control.
The IDE should then require you to login to the QVCS-Enterprise server.  Make sure
to use the same username/password that you have already used when running the 
QVCS-Enterprise client application.

That's all there is to it.  Within the IDE, you'll be able to checkout, checkin,
show revision history, compare revisions (using an external visual compare utility),
etc.


Other tips:
===========
* Make sure to try clicking on the 'Recurse (CTRL-R)' button on the toolbar.
  When it shows the open folder, it means the file pane will display all the 
  files in the current directory AND all the files in any and all child directories
  (for as deep as those child directories may go).  Using this feature makes it
  very easy for you to keep track of other's changes to files within the project.

* Use the F5 key to refresh the display.  Updates from the server are automatic,
  but to update the client's view of your workfiles, you need to type the 
  F5 function key, or enable the automatic refresh feature from the Admin/
  User Preferences dialog.

* You can define new file filters by selecting the Filters/Maintain Filters menu
  item.

* You can create file groups to help you make sure that you operate on a set
  of files whenever you select any one of the files that share the same base
  file name.  You enable and define the file groups feature by clicking on 
  the 'Define File Groups' button on the toolbar.

* You can change the current file filter by selecting it from the drop-down
  combo box on the toolbar.

* You can create a report by using the Reports/Generate Report menu item.  
  Selecting this menu item will create an .html file that reports on all the 
  files and revisions that satisfy (pass) the current filters.

* Take a look at the property files contained in the qvcsBehaviorProperties 
  subdirectory.  The qvcs.extension.attributes.properties file defines the 
  QVCS attributes to assign to newly created archives that have the given 
  extensions.  See the comments in the file for more details.

  The qvcs.keywords.properties file defines the keywords that QVCS-Enterprise
  recognizes.

* You can tailor the Copyright keyword to suit you circumstances by manually 
  editing the qvcs.keywords.properties properties file.  You can find this properties
  file in the qvcsBehaviorProperties directory beneath the gui_out.jar
  jar file that contains gui client application.  Within that file, modify the
  line that looks like:

CopyrightMessage=Your Company, Inc.  ALL RIGHTS RESERVED WORLDWIDE.

  where you tailor the copyright message to suit your own circumstances.

* You can change the width of columns in the file list pane by dragging the 
  boundary between the columns in the header area.

* You can sort the contents of the file list pane by clicking on the column
  header that you want to sort by.  Click the column header again to sort in 
  the reverse order.

* Right clicking on a file or directory will produce a context menu that 
  allows you to perform operations on the selected item.

* You can drag-and-drop single files from the file list to your favorite 
  tool for that file type.

* You can move a file from one directory within a project to another 
  directory in that same project by dragging the file from its current
  location and dropping it onto the destination directory.
