NEDpnp Interface

 

The NEDpnp acts as an interface between Prolog and the native module DLLs.  Prolog loads the NEDpnp, defines the A-pane items and reacts to the selections made on the A-pane.  If A-pane selection is made for a native module, Prolog tells the NEDpnp which module to load and run and waits for another A-pane selection.  You can view descriptions of the individual exported functions in the document NEDpnp routines. 

 

The following sections describe how the NEDpnp works with the individual native modules.  The native modules are DLLs with the same set of exported functions.  Descriptions of the exported routines can be found in the document Interface standard for Native Modules.

NED resource databases

The NEDpnp stores internal C++ classes that have descriptions for the NED variables, plant species, goals and reports.  This information is kept here and passed to the native modules.  By sharing these classes, there is no need to have more than one copy in memory.  This information is loaded when the NEDpnp is loaded, during the display of the splash screen.  The data is never modified within the NED-2 program. 

User screen display preferences

When loaded, NEDpnp.dll will retrieve a couple of screen positions from the system registry at HKEY_CURRENT_USER\Software\NED- USDA Forest Service\NED-2\Positions.  Note that root of this is HKEY_CURRENT_USER, so each user of a computer will have their own locations.  The window coordinates of the main window (left, right, top, bottom) and the point where the three panes meet (x, y – relative to the main window) are retrieved and stored.  When the NEDpnp.dll is closed, these values are stored back in the registry for next time.  There are also a few preferences about the screen that are kept in the same registry path.  These include whether or not the tool-bar, status-bar and tool-tips are to be displayed.

Menu contents

The NEDpnp.dll stores contents for the menu-bar displayed in the native modules.  The main menu is passed to the modules with a call to SetMainMenu.  The modules essentially all have the same menu items.  There are ways to add items to the menu, but they aren’t easy and I won’t describe them here.

‘A’ pane contents

NEDpnp.dll also stores the contents of the ‘A’ pane.  These can be modified by Prolog using exported routines AddAPaneItem and ClearAPaneItems.  An item can be selected by Prolog, using the routine SelectAPaneItem.  There are similar routines for manipulating the ‘A’ pane items in the modules.  See the document Interface standard for Native Modules for the descriptions of those routines.

Toolbar contents

The toolbar is much more complex and wasn’t easy to work with.  I forced all the modules to have the same toolbars and to call the function passed by SetMainMenu.  The toolbar is pretty simply and only contains the simplest operations.  If we need to expand that, it’s going to take some work.

Running the Native NED Modules

One of the main duties of NEDpnp.dll is to load and run the NED modules.  The NED modules are DLL files.  The names of the modules refer to registry keys in HKEY_LOCAL_MACHINE\Software\NED- USDA Forest Service\NED-2\Modules that have the locations of the actual DLL file.  The DLL files must be carefully crafted to work correctly.  NEDpnp.dll assumes that certain exported routines exist, have specific names and parameters, and behave with predicted results.  I have kept NEDpnp.dll fairly naive, so it doesn’t know what the module is doing.  It just knows how to pass the window information to it and let it run.  Standards for the native modules can be found in the document Interface standard for Native Modules.

 

Opening a module

Prolog always makes the decision for what module to run at any time.  This is done using a call to the routine RunModule.  Here are the steps taken when a call to RunModule is made with a valid NED module name:

  1. The name of the module is used to look up the actual file name for the DLL.  This is found in HKEY_LOCAL_MACHINE\Software\NED- USDA Forest Service\NED-2\Modules.  I have added a page to NEDcheckup to list the modules.
  2. The DLL is loaded.  If the NED module has a window, it is initially hidden from view.  So, at this point the window is constructed, but not displayed.
  3. A rectangle containing the screen location of where the window should be displayed is passed to the module.  The window is actually moved, but, once again, it isn’t displayed yet.
  4. The point where the three panes meet is passed to the module.  This requires that all three panes be re-sized to get the right layout.  I cleverly pass one single point where then intersect so that there won’t be any confusion that may have resulted in passing three separate rectangles.
  5. The items for the ‘A’ pane are sent to the module.  The module has control of how they are displayed.  The standard way is to display them in a tree control, but something better may be invented and exploited in future DLLs.
  6. A menu bar is built within the PnP and is passed to the module for display.  If there are additional menus the module wants to display, this where they will be added.
  7. Up until now, the module has remained hidden, so the last step is to display the window.

Closing a module

Now there are of course, certain steps that have to be taken when a module is closed (either to display another module, or when the program is quitting).  Here are those steps:

  1. A call is made to the module telling it to be suspended.  This gives the module a chance to save anything it’s done, or clean up anything that needs cleaning.
  2. NEDpnp gets the module’s current screen location.  If the user has moved the screen around, we want to know about it.
  3. NEDpnp gets the point where the three panes meet.  Once again, the user may have moved things around and we want to know.
  4. That’s about it.  The module is suspended and can be hidden.

Swapping modules

Given the above steps, NEDmain.dll can switch between two modules by closing the first module using steps 1-3 of “Closing a module”.  The module is closed, but still visible on the screen.  Now we can take the steps in “Opening a module”.  If the module is already loaded, but has been suspended, the process starts at step 3.  Since it’s using the same screen coordinates as the other module, it covers the old one.  Now the old module can be hidden.  For a very brief time both screens exist, but really only the new one can be seen.  This eliminates any annoying flicker that we’d see otherwise on slower computers.

 


Data Manager

 

NEDpnp.dll includes the Data Manager.  NED-2 does not work directly with user data files, but uses a temporary working file to manipulate data.  This protects the users data from irreversible changes made by the independent modules that don’t necessarily ask before saving data.  As part of it’s normal shutdown, NEDpnp will delete the temporary working file.  Here is a schematic of how the working file is created and used:

 

 

During start up, NEDpnp.dll initializes and loads an empty, working data file.  There is an empty NED data file that is created by the program CreateEmptyNEDFile.exe, whose location can be found in the Windows system registry under HKEY_LOCAL_MACHINE\Software\NED- USDA Forest Service\NED-2\Resources.  The key is “Empty NED file”.  A check is made to the table [table information] to see if all versions match the current versions in the NED variables database.  If the empty file is out of date, the program CreateEmtpyNEDFile.exe is run to create a new, clean database.  Once a valid empty file is available, it can be copied into a working file and registered for ODBC use by NEDpnp and the modules. 

 

Before copying and opening the new working file, NEDpnp checks to see if one already exists.  During normal shutdown the working file is deleted, but if the last NED-2 session was aborted for some reason, the working file will still be there when NED-2 is re-started.  The user will be asked if this old dataset should be loaded.  This provides at least some data recovery in the event of a system failure.

 

When requested, (by a call to Open File) the PnP will load the user’s data into the working file.  A check to the table [table information] in the user’s file is made to make sure it is current with the NED variables database.  If any table version is out of date, a call to UpdateNEDFile.exe is made.  This will assure that the working data always matches the variables database.  Once the file has been verified to match the variables database, it is copied to the working file.

 

When requested, (by a call to Save or Save As) the working file will be saved to a user-defined file.  This will be a simple file copy from the working file to the file specified by the user.