
                     REVIEW: The dMILL Network Kit for Clipper
                                  by Mike Britten
   
   
   Enlightenment
   
   Sheesh!  Another illusion down the chute.  Imagine.... all this time I
   thought a "Semaphore" was a special kind of mushroom that only grows
   in the dank Redwoods along the Russian River in Northern California
   (just a few miles from where the river used to meet the sea before six
   years of drought dried it up).  Now I find out - well, read on...
   
   
   The Equation
   
            DOCUSOFTWARE = Tutorials + Techniques + Tools
   
   This one-of-a-kind product was developed by T. David Millican of
   Database Software Consultants in Austin, Texas.  Docusoftware, a
   trademark of the company, "designates products in which documentation
   and software receive equal attention during design and implementation".
   
   If this seems like one of those cool ideas that sounds better in a
   brochure than it turns out in real life, let me assure you that the
   esteemed Mr. Millican is up to the task.  In fact, before I go through
   the usual litany of features, I want to say right now that The Kit is
   an excellent investment.  I also wish to emphasize that it has much to
   offer for all skill levels.
   
   If you are about to code your first multi-user application from the
   ground up, or have been given the task to convert an existing system
   from single to multi-user, or even if you've been at LAN programming
   in Clipper for awhile, I consider The dMILL Network Kit indispensable.
   I can't imagine hand-coding a multi-user system without this tool by
   my side.
   
   If you have spent the last several years developing your own library
   of network functions and have a thorough grounding in the theoretical
   and analytical aspects of multi-user issues, ignore that last
   paragraph and go out and play.
   
   
   Just The Facts
   
   I don't have any idea what the registered user base is for The Kit. I
   simply cannot believe that more people in the Clipper community aren't
   aware of it.  One small reason for confusion may be that prior to
   version 4.0, the product was called dCL-Net Library.  The current
   version is 4.10, and this is a list of some of its components:
   
   1. Multi-user programming courseware with over 50 screens, including
      both slide-show and interactive demos.
   
   2. A facility to design windowed messages (to maintain the same look
      and feel with message routines used internally by the software).
   
   3. A facility to design semaphore protocols with the Kit's twenty (20)
      semaphore routines (by contrast, NetLib has 4).
   
   4. A 392-page manual which contains an extremely thorough multi-user
      programming course: 10 lessons, 146 pages, 56 topics, 152 "skills".
      Plus about a zillion tables, figures and screen shots. Six
      appendices.  Glossary, References and Index.
   
   5. Maintenance and debugging utilities. (Tracing and Auditing)
   
   6. 120K of source code, which runs on all MS-DOS networks and works
      with both the Summer '87 and 5.01 versions of Clipper, including 7
      resource contention handling routines, 20 semaphore routines, and 6
      windowed message routines controlled by 29 memvars.
   
   7. No overlap of functionality with NetLib, NOVLIB or CLIPnet, but
      works in a synergistic way with all of them.
   
   8. Drop-in replacement for the automatic single to multi-user
      conversion module of Buzzword International's dANALYST GOLD.
      This is completely optional, and there are no business connections
      between the two companies.  If you have dANALYST and use it to
      dispense with the more mundane chores of single user code
      conversion (like converting all your USE statements), the functions
      in dMILL are more robust by several orders of magnitude.
   
   9. An interactive utility for choosing your defaults for The Kit's
      memvars.
   
   10. Free technical support (including timely, but rarely needed, bug
       fix Bulletins) and a developer who is very open to including well
       thought out suggestions as features in upgrades.
   
   I'll jump the gun on the usual end-of-review ordering info and just
   tell you up front that The Kit costs $249.  That's at least $50 bucks
   less than it costs to try to stay awake for one day in a "Certified"
   Novell class, and you don't even have to inhale!  (But on the down
   side, that happens to be $205 more than the James Brown quadruple CD
   box-set, "Star Time!".  Ah well...)
   
   
   The Tutorials
   
   The present dMILL documentation (an 8.5 by 11 inch professionally
   typeset spiral bound book) includes six parts.  Part I is the
   general Introduction.  Parts II and III are the official "Tutorial"
   sections.
   
   Part II ("Network Concepts and Multiple-User Clipper Commands")
   contains 9 chapters that proceed from a general introduction through
   topics covering network preconditions, state and space analysis,
   semaphore programming, and the all-important issue of handling
   resource contention.  It is not possible to get in a deadly embrace
   with systems designed using The Kit.  What you do on your own time is
   none of the court's business.
   
   Part III ("Converting Clipper Applications From Single-User To
   Multiple-User") is a two chapter tutorial on guess what? This section
   is augmented and condensed later in the manual in one of T.'s beloved
   "Implementation Checklists".
   
   Each tutorial chapter begins with a brief introduction and a "Topics
   Covered In This Lesson" section.  Each tutorial ends with a "Summary"
   and a section called "Your New Skills" which challenges you to answer
   questions about what you've just studied.
   
   Tutorials contain sample code (usually in mercifully brief pseudocode
   style).  The writing is very lucid, to the point, and not dry. In
   fact, Mr. Millican lightens things up along the way with an original
   poem here, a drawing there, and quotes from sources as diverse as Sir
   Isaac Newton, Marvin Gaye, Donald E. Knuth, Mark Twain, and Ian
   Anderson of Jethro Tull!  (No Dr. Hepcat, though!  Hepcat avoids the
   Lone Star State these days like the plague for reasons that would be
   unsavory to reveal in a family publication such as this.)
   
   Sitting down away from my computer and studying the tutorials was very
   satisfying.  I experienced a lot of those "Eureka!" kinds of moments.
   "Oh, so that's what that means.  Far out, dude!"  This is in direct
   contrast to my usual experience of immediately tossing the docs in my
   impatience to get to the software.  In this regard dMILL succeeds in
   fulfilling one of its fundamental mandates - tools without knowledge
   can make for some lousy, even dangerous software.
   
   
   More on the Tutorial "Component" of The Kit
   
   I depleted two of those yellow highlighting pens when I was studying
   this stuff.  Maybe it should just be printed entirely in yellow.
   Anyway, here's a little more detail about the tutorial info taken at
   random from my yellow lamp lights:
   
   
   Recommendations
   
   Throughout the lessons the author is very thorough when he gets into
   an area where more than one solution is possible. In an early
   discussion about fundamentals such as SET EXCLUSIVE ON/OFF in
   Summer '87 vs. the SHARED keyword for USE added in 5.0,
   Millican sites the difference between Nantucket's advice and his.
   When he differs with the party line he explains why.  When he
   recommends following Nantucket's methodology, he also explains why.
   It would not be uncommon, in more advanced lessons, to introduce
   something to the stew like Rick Spence's variations on Nantucket's
   bundled LOCKS.PRG followed by a critique and improvements on the
   same using Kit routines.
   
   You may or may not choose to go the dMILL route in a particular case,
   but it is a highlight of the tutorials that Mr. Millican, while
   naturally advocating his position, is generous enough to present his
   ideas in a broader context.  This design provides the developer with
   the chance to make an informed decision.  The reader's intelligence is
   respected at all times.
   
   
   Division of Clipper commands and functions into Group A and Group B
   
   "In contrast to Group A commands, Group B Commands require special
   methods that are not directly supported by Clipper".
   
   "Well shucks Jethro, I don't see nothin' 'bout no A and B stuff in
   this here pretty lookin' Clippah manual..."
   
   No Homer, you won't.  That's because David Millican has given a lot of
   thought to developing his own terminology for the purpose of education
   and readability.  Gurdjieff said that "for an exact science, an exact
   language is needed."
   
   In this case, "Clipper offers built-in functions to test for the
   preconditions of Group A commands, whereas special techniques (such as
   semaphore locking) are required to test for the preconditions of Group
   B commands and functions."
   
   An example of a "Group A" command is APPEND BLANK, which is supported
   by the built-in function NetErr().  APPEND FROM is an example of a
   "Group B" command that requires special handling, for which The Kit
   supplies the Techniques and Tools.
   
   My point here is not to belabor this particular example, but rather to
   further illustrate how the author invents terms that are referred to
   again and again as each lesson builds on the previous one.  As you
   proceed, original terminology such as "Group B Commands" are
   seamlessly weaved into lessons using "official" network terminology
   such as Concurrency, Synchronization, Serialization, Semaphores,
   Deadlock, etc.
   
   
   Come on Come On Let's Go Little Darlin'
   
   Ok... we'll move on.  I just want to add that, in addition to the
   software engineering aspects of the tutorials, there are very
   interesting clarifications on hardware issues (not too much, not
   enough actually), network administration, comparisons with other
   network addons and more.  To borrow from the brilliantly anonymous
   critic for InfoWorld, "We rate the tutorial excellent."
   
   
   Installation Options and Implementation Instructions
   
   See?  That wasn't so bad.  We're already up to Part IV, page 195! This
   brief but essential section whisks you through an overview of The
   Kit's Software Component.  Installation instructions.  Configuration
   options.  Maintenance and Debugging, including use of The Kit's
   Utility program - DmUtil.EXE.
   
   As stated earlier, this version of The Kit is compatible with both
   Summer '87 and 5.01.  The software is distributed as source code only.
   There are no OBJ's, EXE's, LIB's or header files.  The code is
   distributed in two PRG files.  You only need one of them, and the
   difference is simply that one contains the semaphore routines while
   the smaller of the two does not.  They both contain all the code for
   handling resource-contention and message windows.
   
   Since the code will compile under either version of Clipper, you can
   either just include the code at the end of your top level program and
   lean on the old SET PROCEDURE TO method, or you can simply compile
   the code stand-alone and link in the .OBJ.
   
   Mr. Millican has informed me that a 5.x optimized version is in the
   works and will be released later this year under the guise of "The
   Professional Option".  Prior to that, a generic xBASE version of The
   Kit will be released for those of you needing multi-dialect support.
   
   At the core of Section IV is an explanation of The Kit's "Control"
   memory variables which are accessed through the utility mentioned
   above.  Now would be a good time to take a look at some of them.
   There are quite a few, so I'll take you just far enough so you can say
   that you've been there.
   
   
   DmCtrVar.MEM
   
   "The behavior of routines in the software component is controlled by
   several dozen memvars.  They are assigned with the Kit utility
   DmUtil.EXE and stored into the file DmCtrVar.MEM.  In an application,
   initialization routine DM_Init assigns values to the control memvars
   by restoring the file DmCtrVar.MEM".
   
   When a single copy of the .MEM file can serve all users of an
   application, the control file can be stored in the same directory as
   the application's .EXE file.  But instructions are provided on how to
   implement custom configurations by storing the .MEM file in a user's
   private subdirectory on the server.
   
   This is a sampling of ten of the memvars:
   
   DmTimeOutN - Numeric.  Number of seconds to continue requesting an
                unavailable resource.
   
   DmSuccessL - Logical.  True if resource request successful, else
                false.
   
   DmNetDelay - Numeric.  Number of seconds to wait between requests for
                an unavailable resource.
   
   DmNetNameL - Logical.  If true, get node identification with
                NetName(), else GETENV("NetName").
   
   DmBell_L   - Logical.  True to sound bell with resource contention.
   
   DmContrl2L - Logical.  Control trace: display resource request until
                keystroke or timeout after DmContrl2N seconds.
   
   DmContrl2N - Numeric.  Control trace. Amount of time resource requests
                are shown.
   
   DmSmBat_L  - Logical.  Batch semaphore routines?  (great feature!)
   
   DmSmHist_L - Logical. Control historical recording of semaphore
                activity?
   
   Dm_ColorBd - Character.  This is the color specification for box
                borders and border text.
   
   
   Ergonomic Notification
   
   I thought I'd liven things up for a second with a simulated screen
   shot of one of The Kit's notification boxes:
   
      Resource Not Available ͻ
          Sorry, I couldn't get the resource you requested.  I'm     
          waiting for one or more users to unlock or close the       
          database named Accounts.DBF so that I can open it.  I'll   
          continue to request this resource until it is granted,     
          you enter Shift + S, or timeout occurs.                    
     ͹
                  Press the arrow keys to move the window.           
                         Press H to hide the window.                 
      16 seconds so far  44 seconds before timeout ͼ
   
   They say a picture is worth a thousand words.  Seems to me ya got to
   take into account the picture and the words.  In this case, it's
   pretty elegant as these things go.
   
   
   Part V - Semantics and Interface Specifications of Service Routines
   
   This is where the nitty gritty hard core reference material starts to
   heat up.  Here we've got over a hundred pages of material that usually
   make up most, if not all, of your usual Clipper add-on docs, only done
   better.  Mr. Millican is a bit of a stickler for details.  Less is
   sometimes more, and in some areas I think the author goes a bit too
   far.  I do appreciate the reference material, though, and am hard-
   pressed to find any question that would force me to make a tech
   support call instead of checking this very accessible, if long, tome.
   
   The routines in the current version are divided into four groups for
   the purposes of documentation.  The groups are Resource Contention,
   Windowing Services, Semaphore Services, and Condition Reporting.
   
   Each group of procedures is explained in its own chapter with an
   introduction and an alphabetical listing that includes the usual
   Description, Syntax, Arguments, Return Value, Usage, Notes, Examples
   and "See also".  Where David goes beyond most references in this style
   is by also providing two other very important categories:
   Entry Conditions and Exit Conditions.
   
   From the manual - "In order to construct correct calls to a routine in
   a library, the programmer must know how the routine changes the state
   of the application.  This information can be expressed by listing
   conditions that should be true upon exit from the routine (exit
   conditions), assuming that certain conditions hold when the routine is
   entered (entry conditions)."  A robust error handling system augments
   this approach.
   
   Fatal error and warning condition data is written to .MEM files. There
   is a memvar for specifying the target directory for these files. To
   examine the screen saves, saved memvars, and other error reporting
   information, you select "Recover error and warning information" from
   the main menu of DmUtil.EXE.
   
   This error tracking feature of what Mr. Millican refers to as The
   Kit's "Omnibus Utility", along with that utility's tools for designing
   and testing semaphore protocol and other mysterious items, give this
   part of The Kit a quality similar to some much more expensive CASE
   tools.
   
       
            DmUtil, A General Utility for the dMILL Network Kit      
     
               World Class Tools for World-Class Programmers         
     
       C  Control memvars of Kit (set or inspect values).            
       E  Recover error and warning information saved in .MEM files. 
     
       T  Tutorial Demonstration of the dMILL Network Kit.           
     
       W  Windowed message routine design aid.                       
       S  Semaphore demos and design aid.                            
       D  Demos of windowed messages.                                
     
       .  Quit to the dot prompt.                                    
       Q  Quit to the operating system.                              
     
   
   
   
   Part VI - Reference Material
   
   The most significant chapter here is "Most Common Support-Line
   Questions".  This is followed by Legal and Support questions and
   answers, six appendices, a glossary, lists of references, and the
   Index.
   
   
   Yeah, yeah, yeah - but does the darn thing work?
   
   It works like a champ!  I've got several Summer'87 applications that
   started life as single user, and have been running without a peep
   using version 3.0 of dCL-Net, this product's younger sibling.  Version
   4.10 is a major upgrade to an already solid deal.  The apps mentioned
   above cover the territory from small Lantastic to large Novell shops.
   The Novell stuff also uses advanced NetLib functions with no hassles.
   If my memory serves me well, I threw in some of the Grumpfish Library
   network functions and other stuff just to liven things up a bit...
   
   What if you use an application generator that handles network code
   automatically?  Do you still need The Kit?  This is an interesting
   question.  I believe the best answer is "it depends".  First of all,
   with the simple linking of a dMILL .OBJ, you've got a whole toolbox
   for dealing with potentially very complex situations.  I'm thinking
   about a real big system where you know you're going to be inserting
   custom code by whatever method your generator supports, and where you
   know that your specs require some things that your generated code may
   not support, like locking multiple records.
   
   But even if you do not need the software component of The Kit now, you
   may one day, and I still can't speak highly enough of the educational
   value.  And again, if you're doin' it by hand,  my recommendation is
   check this out immediately!
   
   
   Suggestion Box
   
   Are there things I'd like to see that aren't there now?  Are there
   some things I'm not crazy about?  Of course.
   
   Going back to earlier Clipper times, Mr. Millican devised a clever
   replacement for the Ashton Tate RETURN TO MASTER statement.  This
   default action is used by the kit to return to an application's main
   menu when a resource request times out or is manually canceled by the
   user.  You can also have the app take a trip to DOS Land if you're
   angry with your users for expecting that you actually know what you're
   doing.
   
   Before I lodge my complaint, it is only fair to emphasize that you are
   in no way forced to go along with this behavior.  You can shut it off
   via a memvar and roll your own resource contention handling methods.
   Or, with the usual caveat to backup, you can modify the source code
   which is clearly written and commented.  That's what I did.
   
   However, this is nuts!  Think about it.  Say you've got an old pre-CUA
   style data entry form that's got a standard Add/Edit/Search/Delete
   menu at the bottom of the screen.  Say you got to this screen by going
   several menu levels deep in a large system.
   
   Okay... so you search for a record, get a hit, it shows up on the
   form, you press E for Edit and someone else has it locked.  Instead of
   waiting for automatic timeout you press the "forget it" key
   combination.
   
   I don't know about you, but I want to stay right where I am, Jack.
   Maybe I've got some new entries to make, maybe I want to try to edit
   some other record.  You mean to tell me that - BOOM - all of a sudden
   I'm at the main menu and have to work down the menu tree again to get
   back to from where I came?  Hey, I'll tell you what!  If I'm a data
   entry temp and this is my first day on the job, girlfriend, I'm goin'
   out to lunch and I ain't comin' back!
   
   With all due respect, there's only one possible reason that I can
   think of where this might be acceptable.  And that's if a system
   manager has exclusive use of files for a lengthy PACK, which
   probably wouldn't be done during peak use anyway.
   
   So my suggestion to Mr. Millican for the Clipper 5.x specific
   "Professional Option", is to offer the developer one or two additional
   default options for handling resource contention, without requiring
   hand-coding.
   
   Furthermore, I would very much like to see the the Clipper 5 version
   function-based rather than procedure-based.  However, given the large
   amount of Summer '87 code out there, I don't blame dMILL for sticking
   with the current strategy.  There are no problems with performance
   that I have been able to perceive that I would attribute to coding
   technique.  All in all, this unfairly obscure Kit is a remarkable
   achievement by a remarkable person.
   
   
   Ordering Information
   
   The dMILL Network Kit for Clipper costs $249 plus shipping and
   handling.  Call or E-mail for non-US shipping prices.
   
   The Kit is available from:
   
   Database Software Consultants
   2805 Dancy St.
   Austin, TX  78722-2317
   
   Phone: (512) 477-3423
   CompuServe ID: 73667,56
   
   Promotional Material is available upon request.
   
   
   About the Author
   
   Michael Britten lives in Oklahoma with his two goats, Otis and Clay.
   (Well, at least he wishes he did!)  Questions/Comments?  Contact him
   via the Aquarium Message Center.


This excerpt was reprinted by permission from The Aquarium, the best source of
Clipper technical expertise.  The Aquarium is published monthly by Grumpfish,
Inc.  For subscription information, contact Grumpfish, Inc. at (503) 588-1815,
or by facsimile at (503) 588-1980.
