====================================================================== 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 cd 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 ... substituting the directory or directories to be patched for "...". (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: / 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 .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 and the stop strings are all "" 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 "" tag, is preserved. The original HTML file is renamed .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 .old, it does not replace or patch the corresponding ; 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] [ 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 " The utility is about to search an HTML file for constructors needing replacement. "File successfully patched" The named HTML file was patched and the old and patched versions are available for comparison. "Got good patch fragment for " 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 " The named JSB file was successfully replaced. There should be an "old" copy as well, if you want to compare them. "Replacement file: " The utility found a replacement file during initialization. There should be one of these messages for every replacement file. "Searching directory " 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 = " 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 .old already exists" "File 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 .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 " "No backup copy of made" The named JSB file could not be renamed .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 " "File 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 .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 " "" "File 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 " "Exception: " 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 not found in " "File cannot be patched, but should have been" The utility found end-of-file while looking for a terminating string () 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 " "trying to check file 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 could not be renamed" "File cannot be patched, but should have been" The original file could not be renamed .old. The original file, and a file called .new (the patched version) will be left in place for you to compare, and determine which to use. "Patched file .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 .old) and the new file (.new) will be left in place for you to compare and determine which to use.