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.