Lotus 1-2-3 ADK - WIZMGR.TXT

This file includes information about:
 - using the LSX Wizard to create LSXs.
 - maintaining changes to LSXs created using the LSX Wizard.

================================================================================
Using the LSX Wizard

The LSX Toolkit provides the LSX Wizard Notes database that sets up all of the boilerplate structure that Script requires of an LSX.  To use the Wizard you must know the object structure that you want your LSX to expose.  You enter this information into a Notes form.  When the information has been entered the Wizard will generate the code for a skeleton LSX.  All that the user has to do is fill in the routines to make them do what is desired.

Those who are superb top-down planners will find this quite sufficient.  The rest of us find it necessary to change the design from time to time.  Unfortunately the Wizard has no incremental mode.  You can regenerate the files, but this overwrites any changes you've made. It does, however, provides standard files (<<class name>>.tab) that allow you to change the exposed interface of your LSX classes after they have been generated.

If you have a lot of changes to the structure of your LSX classes or if you have to add a new class, treat it like a parallel development problem.  Keep a copy of the old skeleton and take a copy of the current state of your source code just before you make the change.  Then regenerate the LSX using the Wizard (updating your previous design if you wish).  You should then compare the old and new skeletons and make changes to the current source to match the changes made to the skeleton.  Any decent merge facility should handle the bulk of the work.  For Windows NT users a simple batch file method has been included to do this - more details are given below.

================================================================================
Managing LSX Wizard Changes R2.0 - Windows NT

The MKS toolkit contains a facility to perform the necessary merge.  The batch files mksbase.bat, merge.bat, dbldiff.bat and mrgdiff.bat will do the job in NT.  Because of differences in the way the shell behaves, these files will not work in Windows 95.

Merging:
At the time of the first Wizard creation of an LSX directory, create 4 subdirectories from it: before, after, chkout, merge.  Copy the contents of the LSX directory immediately after creation to before.  Immediately preceding re-running the Wizard to make changes, copy the current version of the same files to after.  Re-run the Wizard, make the desired changes and re-create the boilerplate.  Copy the new versions of the files to chkout.

In the LSX directory, run the batch file mrgdiff on each filename that is in before or after (there might be new files - obviously they don't need to be merged.)   The results will be in the merge subdirectory, and changes that the process could not resolve will be set off by "<<<<<<", "========", ">>>>>>>".   Copy the merge contents to the LSX directory and resolve the problems that could not be resolved automatically.   When this process is complete the contents of the chkout directory should go into the before directory, and the corrected contents of the merge directory should go into the LSX directory.   The LSX directory files (which may include new files) should then go into the after directory to be ready for the next design change.  The mksbase.bat file will have to be edited for local mks location.

Notes:

1.  You must have the MKS toolkit, and the executables directory must be on the path.  Moreover an environment variable MKSH must be set to the executables path with each backslash doubled.

2.  The most problematic line is the invocation of the MKS shell, sh, in the middle of merge.bat.  The present format works in NT but not in 95, and is what requires the MKSH variable.

3.  Dbldiff uses a file viewer, "l", which is not part of MKS (near the end of the batch file).  This is simply a monitoring step to allow the user to note any problems.  If that is not available a variety of viewers/editors should work instead.  Note that three files are viewed.

4.  Changing a class name:   In this case the Wizard will create three new files, NewName.hpp, .cpp and .tab, that correspond to the OldName.xxx versions.   To merge these, rename the OldName.xxx files to NewName.xxx in the before and after subdirectories (and in your controlling merge script if you use one).   The merge process will detect several conflicts which must be appropriately resolved.   In addition, existing implementation will have instances of "OldName" and "OLDNAME" in method and constant names - generally these should be appropriately replaced.

General Wizard/Toolkit Note -

The Wizard and the Toolkit assume the Toolkit was installed in \lsx.  Most consequences can be handled by suitably modifying the setup batch file, but the linkresp.XXX file has explicit \lsx\ usage.   This file, needed by each LSX subdirectory, must be edited if you do not install in \lsx.

