Setting Up jCVS To Open Files

This document describes the process of configuring jCVS to be able to open files in the editor of your chosing when you double click on them, or select the 'Edit File' command from a file's popup menu.

The operation of signaling an editor program on a specific platform to open a file is complex enough. On the Macintosh, Apple Events are required. Under Windows, DDE events are the trick. Under UNIX, one usually wants to exec() a process. The problem is compounded by the fact that we are coming from the Java world.

Fortunately, Java gives us the critical capability of making a system call, or exec!

Until better methods are available, jCVS provides only one method, currently, of opening files for edit - the exec() call. In the Properties.txt file, there is a property named jCVS.openFile.method that controls the processing of edit requests.

The jCVS.openFile.method property is a name that specifies the type of processing to perform to handle edit requests. Currently, only the 'SH' method is supported.

The 'SH' method is simply to exec() a list of arguments via the RunTime.exec() method in Java. The list of arguments passed to the exec() is determined by a list of properties.

The first property is jCVS.openFile.SH.argc. Note that the 'SH' method is included in the property name. This property determines the number of arguments to be passed to exec().

After the 'argc' property is retrieved, jCVS will scan for properties with the name jCVS.openFile.SH.argv.# where the '#' is replaced by the number of the argument. In other words, jCVS does a 'for loop' argc times looking for these argv properties to use for arguments.

NOTE The argument scanning has changed in release 4.7.

NOTE Release 4.7 supports "verbs" for the file commands. The verbs currently supported are "open" and "edit". The verb is retrieved with the '*V' escape.

As each argument is read, it is scanned for the character '*', followed by one of several capital letters, which will be replaced by jCVS with a value that the letter selects. The possible selectors are:

*D - The directory of the file.
*F - The full path name file.
*H - The user's home directory.
*W - The working directory.
*V - The verb to apply to the file.

of the file to be editted. This implies that you can not have an argument that contains the letter '*'. Please let me know if anyone anticipates this being a problem, or if there might be a better choice.

Here is are the default properties for setting up the edit command to open the file in question in a Notepad window under Windows.

	jCVS.openFile.method=SH
	jCVS.openFile.args=NPAD
	jCVS.openFile.SH.NPAD.argc=2
	jCVS.openFile.SH.NPAD.argv.0=notepad.exe
	jCVS.openFile.SH.NPAD.argv.1=*F

The Properties.txt file contains several more examples. Please, if you make a command work on another platform, email the settings to me so that I may include them in the distribution!

Windows DDE Commands

To make jCVS more useful, I created a simple program named 'jcvsdde.exe' to perform the DDE event passing required to open a file in an already running application. The most obvious example (my environment in fact) is to have a file opened in the MS Developer Studio. This can only be done with a DDE Execute event being sent to MSDev.exe. This is done by the 'jcvsdde.exe' application. This application takes three arguments:

The Service Name of the application in question.
The Topic Name of the DDE event.
The execute command string.

Here are the settings from Properties.txt for opening files for edit in MS Developer Studio.

	jCVS.openFile.args=DEV
	jCVS.openFile.method=SH
	jCVS.openFile.SH.DEV.argc=4
	jCVS.openFile.SH.DEV.argv.0=c:\\bin\\jcvsdde.exe
	jCVS.openFile.SH.DEV.argv.1=MSDEV
	jCVS.openFile.SH.DEV.argv.2=System
	jCVS.openFile.SH.DEV.argv.3=[open(\\"*F\\")]

Please note the requirement to double backslash. Also note that you must copy the jcvsdde.exe program to a directory on your disk drive (I placed mine in the 'bin' directory on my C drive) and provide the full pathname as the first argument.

NOTE Release 4.7 includes a more sophisticated program named 'shellex.exe', which uses the Windows API function 'ShellExecuteEx', which is more powerful than jcvsdde.exe. More specifically, shellex.exe will open the application needed to open the file, if the application is not running. The jcvsdde.exe simply failed if the application was not already running. Furthermore, shellex.exe uses the verb to specify how to operate on the file, which allows us to have different actions to edit or to open the file (e.g., open html in NewScape, edit html in MSDevStudio). Finally, shellex.exe maps documents to their respective application via the Windows File Types configuration, which is more complete and automatically picks up new installations.

The shellex.exe application takes five arguments:

The verb (usually 'edit' or 'open', use *V).
The file name (use *F).
The parameters.
The default directory (usually use *D or *W).
The show option (usually 'SHOW_NORMAL').
The execute command string.

Suffix Mapping

You may now establish open commands that are based on the file's name suffix. This allows you to open source code files in your favorite IDE, while opening GIF files in PhotoShop.

The means of mapping suffixes to different commands is simply to insert the suffix into the properties that are used to determine the open method and arguments. Instead of using 'jCVS.openFile.method', for '.c' files, you would use 'jCVS.openFile.method.c', and for GIF files, you would use 'jCVS.openFile.method.gif'. Instead of the default arguments specifications, you again add the suffix. Here is a suffix mapping for '.cpp' C++ source files:

	jCVS.openFile.args.cpp=DEV
	jCVS.openFile.method.cpp=SH

	jCVS.openFile.SH.DEV.argc=4
	jCVS.openFile.SH.DEV.argv.0=c:\\bin\\jcvsdde.exe
	jCVS.openFile.SH.DEV.argv.1=MSDEV
	jCVS.openFile.SH.DEV.argv.2=System
	jCVS.openFile.SH.DEV.argv.3=[open(\\"*F\\")]

Here is a suffix mapping for '.txt' settings files:

	jCVS.openFile.args.txt=TXT
	jCVS.openFile.method.txt=SH

	jCVS.openFile.SH.TXT.argc=2
	jCVS.openFile.SH.TXT.argv.0=C:\\WinNT40\\System32\\notepad.exe
	jCVS.openFile.SH.TXT.argv.1=*F

Here is a suffix mapping for GIF files:

	jCVS.openFile.args.txt=GIF
	jCVS.openFile.method.txt=SH

	jCVS.openFile.SH.GIF.argc=2
	jCVS.openFile.SH.GIF.argv.0=C:\\WinNT40\\System32\\mspaint.exe
	jCVS.openFile.SH.GIF.argv.1=*F

These settings will set the default to EMacs under Windows NT:

	jCVS.openFile.args.c=EMACS
	jCVS.openFile.method.c=SH

	jCVS.openFile.SH.EMACS.argc=3
	jCVS.openFile.SH.EMACS.argv.0=gnuclientw.exe
	jCVS.openFile.SH.EMACS.argv.1=-F
	jCVS.openFile.SH.EMACS.argv.2=*F

You may define as many suffix mappings as you like. Remember that the executable need to be in your PATH, if they are not specified as full pathnames in these settings. For instance, in the EMacs example above, gnuclientw.exe would need to be on your PATH, as would the emacs binary, which is invoked by the gnuclientw.exe application.

Paths

When the code tries to execute the program to edit or open the file, if the executable is not specified with a full path name (or is not found), jCVS will search for the executable in several places. First, those specified by properties, then in the working directory (user.dir), then in the user's home directory (user.home).

The path properties are specified with names "jCVS.openFile.@.path.#", where the "@" is replaced by the method (e.g. SH), and "#" is replaced by the an integer that increments (0, 1, 2, 3, ...). The properties will be read until there are no more.

Please refer to the properties.txt file for more comments on paths.

$Id: EditSetup.html,v 2.3 1998/07/06 13:41:25 time Exp $
Copyright (c) 1997 By Timothy Gerard Endres
jCVS is licensed to you under the GNU General Public License.