	======================================================================
	   README file for the "A" patch for Visual JavaScript release 1.0
				    Unix version
	======================================================================


WHAT IS THIS PATCH FOR?
=======================

  This patch is required to make Visual JavaScript 1.0 work with Netscape Enterprise
  Server version 3.5.1.  It will update sections of JavaScript code contained in JSB
  and HTML files throughout Visual JavaScript, and optionally in other directories.

  The patch will update the following component files:

	netscape/peas/
		CustomTable.jsb
		DBexport.jsb
		DBPool.jsb
		DBSelect.jsb
		FormAccept.jsb
		JSBufferedCursor.jsb

  In addition, because these components' constructors are included in HTML files that use
  the components, some HTML files need patching, too.  These HTML files are found in the
  standard palette, in user palettes, in the set of sample projects supplied with Visual
  JavaScript, and in any user-created projects that use the above-listed components.


INSTRUCTIONS FOR USING THE "A" PATCH FOR VJS 1.0:
=================================================

	General instructions:

	1. Unzip and un-tar the file VJS10aPatch.tar.gz in the Visual JavaScript
	   installation directory:

			mv VJS10aPatch.tar.gz <VJS-install-dir>
			cd <VJS-install-dir>
			gunzip -c VJS10aPatch.tar.gz | tar xvf -			

	   This will create a subdirectory called VJS10aPatch in the Visual JavaScript
	   installation directory.



	To patch all JSB and HTML files in the "Projects", "Palettes" and "netscape" directories
	(default behavior):

	1. Cd to the VJS10aPatch directory, run the .sh file VJS10aPatch.sh.

	   The patch utility will run without input, creating a log file, log.out, in
	   the VJS10aPatch directory.

	2. View the log.out file with any text viewer to see what was done.



	To patch all JSB and HTML files in an arbitrary directory or list of directories:

	1. Cd to the Visual JavaScript installation directory.

	2. Run the patch utility directly, with this command (all on one line):

		jre1.1.3/bin/sparc/green_threads/jre -cp ".:jre1.1.3/lib/rt.jar"
			VJS10aPatch.VJS10aPatch -v <dir>...

	   substituting the directory or directories to be patched for "<dir>...".  (Note:
	   the above command is typical for a Visual JavaScript 1.0 Unix installation;
	   compare it with the contents of VJS10aPatch.sh to get the exact configuration
	   if you have problems with the above command.)

	   The utility creates a log file, log.out, in the VJS10aPatch directory.  You
	   can inspect it with any text editor.


CAVEATS
=======

  This patch utility does not parse HTML or JavaScript, but uses a very simple pattern-
  matching scheme.  If you have modified or reformatted the JavaScript constructors in any
  HTML files, the pattern-match may fail for those, and you will have to patch those files
  yourself.

  The patch is not intended to be used on projects which have been deployed.  You will need
  to patch the "development" copy of the projects, and re-deploy them.


WHAT IS IN THE PATCH?
=====================

  You install the patch in the Visual JavaScript installation directory.  This is important,
  because it ensures that a Java runtime environment is available to the patch utility, and
  that some standard directories are in known locations relative to the patch utility.

  The patch comes as a gzipped tar file.  When you have installed (unzipped) it, the patch
  will have this structure:

	<VJS install dir>/
		VJS10aPatch/
			README
			VJS10aPatch.sh
			VJS10aPatch.class
			VJS10aPatchFragment.class
			Files/
				netscape/
					peas/
						CustomTable.jsb
						DBexport.jsb
						DBPool.jsb
						DBSelect.jsb
						FormAccept.jsb
						JSBufferedCursor.jsb
			Fragments/
				CustomTable.jsb
				DBexport.jsb
				DBPool.jsb
				DBSelect.jsb
				FormAccept.jsb
				JSBufferedCursor.jsb

  The utility itself is the two class files.  The one with the "main" method is VJS10aPatch.
  They were compiled in the "VJS10aPatch" package, so to run the utility from the command line
  you would cd to the VJS install directory, and type (for example--don't actually type this)

		java VJS10aPatch.VJS10aPatch

  This is what the .sh file does, with a little additional code to ensure that the Java VM and
  standard class files are available.  It also includes the -v (verbose) option, to make the
  utility produce more output.

  Each file in the "Files" tree contains the complete text of a JSB file to be replaced.  Each
  file in the "Fragments" directory contains a search string on the first line; a stop string on the
  second line; and the rest of the file is the text which will replace everything between the
  search string and the stop string in HTML files.


WHAT DOES THE PATCH UTILITY DO?
===============================

  The utility first reads the "Files" directory, compiling a list of the files to be replaced.
  Then it reads the "Fragments" directory, compiling a list of JavaScript fragments (constructors)
  to be replaced in HTML files.

  If it is run without command-line arguments (except for the -v option, which produces more log
  output), as in the VJS10aPatch.sh file, the utility then searches the "palettes", "projects"
  and "netscape" directory trees.  When it finds one of the files that are to be replaced, it
  renames the original file <file>.old, and copies the replacement file into the directory.  When
  it finds an HTML file (extension .htm or .html, in any combination of cases), the utility reads
  the file line by line, searching for any of the search strings from the Fragments directory.

  When it finds one of the search strings, it searches for the corresponding stop string.  Since
  the patch is to replace constructors, the search strings are all constructor tags, such as

		<SERVER PURPOSE="JSConstructor" CLASS="netscape.peas.CustomTable">

  and the stop strings are all "</SERVER>" tags.  There are two things to note about this step:

	+ The search strings will not be found if they are broken across lines.  They are
	  always found on a single line in the files distributed with Visual JavaScript, but if
	  the constructors have been reformatted after inclusion in HTML files, this may no longer
	  be true, and those constructors would not be detected and patched by this utility.

	+ Text in a line before the "<SERVER..." tag, and after the "</SERVER>" tag, is preserved.

  The original HTML file is renamed <file>.old, and the patched version is put in its place.

  The *.old files are left in place so you can verify what was changed, but they are no longer
  required; you can remove them if you want.  One reason to leave them for a while:  if the patch
  utility finds a <file>.old, it does not replace or patch the corresponding <file>; this prevents
  the utility from operating twice on the same file, and removing its copies of the original files,
  in case the utility is accidentally run twice on the same directories.

  JSB files not in the list of those to be replaced are not modified.  HTML files not containing one
  of the listed constructors are not modified.


COMMAND REFERENCE
=================

  The utility has thls command form:

		java VJS10aPatch.VJS10aPatch [-?] | ([-v] [<dir}]+)

  Options:
		-?  (help) Causes the utility to print a usage message and terminate.
		-v  (verbose) Causes the utility to print a message for each file replaced or patched,
		    even when there are no errors.  Without -v, only errors or warnings cause output.

  Arguments:
		<dir>  The name (relative to the Visual JavaScript installation directory, or absolute)
		    of a directory tree whose files are to be processed.  If no directories are given,
		    the utility processes the "palettes", "projects" and "netscape" subdirectories of the
		    installation directory.  One or more directories may be specified, and they need not
		    be located in the Visual JavaScript installation tree.


DIAGNOSTICS
===========

  Informational (printed only in verbose mode):

	"Checking file <filename>"
		The utility is about to search an HTML file for constructors needing replacement.

	"File <filename> successfully patched"
		The named HTML file was patched and the old and patched versions are available for
		comparison.

	"Got good patch fragment for <filename>"
		The utility found a search string, stop string and replacement text in the
		named fragment file.  There should be one of these messages for every fragment file.

	"Replaced file <filename>"
		The named JSB file was successfully replaced.  There should be an "old" copy as well,
		if you want to compare them.

	"Replacement file:  <filename>"
		The utility found a replacement file during initialization.  There should
		be one of these messages for every replacement file.

	"Searching directory <directoryname>"
		When the utility encounters a directory, it recursively searches for more directories
		or files.  This message lets you see where it has gone.

	"starting directory = <directoryname>"
		Should be the Visual JavaScript installation directory.

	"Upgrade Visual JavaScript components (1.0 to 1.1)"
	"java VJS10aPatch.VJS10aPatch [-?] | ( [-v] [path...] )"
	"If no paths are specified, "netscape", "palettes" and "projects" are used"
		The usage message printed in response to the -? option.


  Warnings (always printed):

	"Warning: backup file <filename>.old already exists"
	"File <filename> not replaced (replaced previously?)"
		The utility was about to process a JSB file, but found that an "old" copy of it already
		exists.  The utility does nothing more with the named file, but proceeds normally otherwise.
		You should determine whether the patch utility has in fact already been run on the named
		file's directory tree, and if not, remove any "old" files that are interfering with the
		correct operation of the patch utility.

	"File <filename>.old exists; may have been patched previously; not patching again"
		The utility was about to search an HTML file, but found that an "old" copy of it already
		exists.  The utility does nothing more with the named file, but proceeds normally otherwise.
		You should determine whether the patch utility has in fact already been run on the named
		file's directory tree, and if not, remove any "old" files that are interfering with the
		correct operation of the patch utility.

	"Warning: could not rename file <filename>"
	"No backup copy of <filename> made"
		The named JSB file could not be renamed <file>.old.  This does not prevent the utility from
		continuing with this file:  it will still attempt to replace it.  This warning notifies you
		that there will not be an "old" copy of the original of the file.


  Errors (always printed):

	"Error: could not delete file <filename>"
	"File <filename> not replaced, but should have been"
		The named JSB file could not be deleted, so there is no way to replace it with a copy of the
		new, replacement file.  This problem only occurs if the original could not be renamed to
		<file>.old.  The original will be left in place.  You should remove the file manually, and
		replace it with the correct file from the patch directories.

	"Error: exception while replacing file <filename>"
	"<exception string>"
	"File <filename> not replaced, but should have been"
		The named JSB file could not be replaced, because of an exception (described) which occurred
		most likely during the copying of the replacement file.  Other files will be processed normally,
		but nothing more will be done with this one.  You should check to see if an "old" copy is left,
		and manually replace it with the correct file from the patch directories.

	"Error: invalid patch fragment file <filename>"
	"Exception: <exception string>"
		Indicates a problem with one of the fragment files.  The second line appears only if an
		I/O exception caused the problem.  Contact Netscape for help, or try downloading and installing
		again.  If this happens, the file named will not be used to patch HTML files, which means that
		the corresponding constructors will not be replaced in HTML files, but the rest of the utility's
		work will proceed normally.

	"Error: stop string <stopString> not found in <filename>"
	"File <filename> cannot be patched, but should have been"
		The utility found end-of-file while looking for a terminating string (</SERVER>) in an HTML file.
		Obviously, something is seriously wrong with this file, or with the fragment the utility is
		using.  It will do nothing more with the named file, but the rest of its work will proceed
		normally.  You should examine the file closely to see if there is something wrong with it, and
		will have to do the patch manually.

	"Exception <exception string>"
	"trying to check file <filename> for patching"
		The given exception happened during the processing of the named HTML file.  Depending on when
		the exception was thrown, the file may have been completely or partly processed, or not at all.
		Check the files (old, new and standard) that you find, and determine which to use.  If any
		patching is to be done, you should probably do it manually.

	"File <filename> could not be renamed"
	"File <filename> cannot be patched, but should have been"
		The original file could not be renamed <file>.old.  The original file, and a file called
		<file>.new (the patched version) will be left in place for you to compare, and determine which
		to use.

	"Patched file <filename>.new could not be renamed to original name"
        "Do this manually to use the patched version"
		The "new" (patched) version of the file could not be renamed to become the standard version.
		The original (now called <file>.old) and the new file (<file>.new) will be left in place for
		you to compare and determine which to use.

