====================================================================== README file for the "A" patch for Visual JavaScript release 1.0 Windows version ====================================================================== WHAT IS THIS PATCH FOR? ======================= This patch is required to make Visual JavaScript work with Netscape's 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: ================================================= Running the patch in the default way: ==================================== 1. Get the self-extracting EXE file (VJS10aPatch.exe) on local disk, and either double-click on it in Windows Explorer, or use the Start menu's Run command to execute it. You will see a dialog prompting you for the directory to which you want to unzip the EXE. The default is C:\Program Files\Netscape Visual JavaScript 2. This patch must be installed in the Visual JavaScript installation directory. If the default value above is not the directory where Visual JavaScript is installed on your machine, please type the correct directory name in the highlighted field. 3. The dialog also shows checkboxes letting you overwrite files automatically on unzipping the EXE file (default is no), and to run the patch script automatically when the EXE has been unzipped (default is yes). When you are satisfied with the dialog's selections, press ENTER or select UNZIP. Unzipping the EXE creates a subdirectory called VJS10aPatch in the Visual JavaScript installation directory. If you selected automatic execution of the patch script (default), the script VJS10aPatch\Auto.bat runs immediately after. Some output is directed to a console window created for this purpose, but most of the patch utility's output is sent to a log file, log.out, in the VJS10aPatch directory. Default execution of the patch script updates files in the "Projects," "Palettes" and "netscape" directories under the Visual JavaScript installation directory. The log file will be opened with "notepad" when the patch utility finishes, so you can see exactly what was done. To patch all JSB and HTML files in the "Projects", "Palettes" and "netscape" directories (if you did not select automatic patch utility execution, or if you want to run it again): ========================================================================================= 1. From the VJS10aPatch directory, run the BAT file VJS10aPatch.bat. (The easiest way is to view the directory's contents in Windows Explorer, and double-click on the icon for the "VJS10aPatch.bat" file.) NOTE: do not run Auto.bat! The two scripts assume different starting directories! The patch utility will run without input, creating a log file, log.out, in the VJS10aPatch directory. 2. View the log.out file with Notepad or other text editor 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): VM\java\bin\java -classpath .;.\VM\java\lib\java40.jar VJS10aPatch.VJS10aPatch -v ... substituting the directory or directories to be patched for "...". 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 is distributed as a self-extracting EXE file. When you have installed (unzipped) it, the patch will have this structure: \ VJS10aPatch\ README.txt VJS10aPatch.bat 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 BAT 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, and redirects the output to a log file called "log.out" for later inspection. 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.bat 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 this 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.