ArcView Class Hunt Results

Summary

The ArcView Class Hunt was an unprecedented collaboration of the worldwide ArcView user and developer community. It was an effort to identify, through sleuthing and careful guessing, special words--"class" names--that might exist on some systems according to the software present and how they were configured. The goal was to publish a complete list of these words so that ArcView users and developers can avoid their use in Avenue scripts. A class name, used to name a variable, may work correctly on one system but fail unexpectedly on another system.

The ArcView Class Hunt began with a list of 575 known class names. Half of them were found in the help files for ArcView and Spatial Analyst, the other half were found buried in the ArcView executable files themselves.

Class Hunt participants found another 325 names that we have been able to verify, with ESRI's help, are either class names or were class names in older versions of ArcView or its extensions.

Early in the Hunt, ESRI generously contributed a large list of words that included hundreds of class names. (This was graciously done outside the auspices of the Class Hunt, so as not to skew the awarding of prizes.) After Class Hunt participants found many words not on that list, ESRI programmers were able to create a second list of 954 class names obtained from the current source code for ArcView and its ESRI extensions. 56 of these were new and had not been found by Class Hunt participants.

The list of all known class names (956 to date) is available in comma-delimited text format here. It contains three columns: class name, superclass (if documented), and whether it acts like a class in base ArcView 3.2 with no extensions loaded (true or false).

Many, many people downloaded the Class Hunt software and helped search for new classes. Only 14 people, however, earned the distinction of being the first to post at least one new class name. One of these was Direction Magazine's own Steve Wallace, who really just wanted to test the system. (We let his posting stand, but he is not eligible for any prize.)

It is impressive that the Class Hunt winner, Todd Plank, found more new class names than did ESRI. Almost as impressive is that the top six contributors produced at least two-thirds as many as ESRI. It was a close contest, as the numbers show.

Class Hunt results

Many thanks to all who submitted hunt candidates.

Directions Magazine offered prize money to add some interest to the Class Hunt. Five prizes were offered, of $100 (US) to the winner and four more prizes of $25 each. The first three finishers are automatically awarded prizes. To maintain interest throughout the four-week Class Hunt period, we decided to award the last two prizes randomly, providing equal chances to everyone who had contributed at least one new class.

Our winners

Introduction

The problem, in a nutshell, is that working, tested, ArcView scripts and extensions can mysteriously fail. Until recently this problem was purely hypothetical. That changed in late March when an ArcView user posted this message on the independent ArcView list (ArcView@listbot.com):

I have a rather large APR, the main one I'm working with at this time, that seems to function just fine, except when I open this APR a MS-DOS screen opens at the same time with the message, "c_wrodb.ave: path is both a variable and a class at 322."

Fortunately, Directions Magazine readers were aware of the problem and were actively creating a solution with the ArcView Class Hunt.

The problem

Avenue is the underlying language that drives all ArcView operations. All scripts and extensions (organized collections of scripts) are written in Avenue. Virtually every script uses variables, which store intermediate calculations.

Customarily, programmers construct variable names by concatenating (mashing together) short descriptive pieces, such as numB ("number B"), tIn ("time in"), or sTheme ("string theme"). This is the technique advocated by ESRI, developers of ArcView.

Certain words in Avenue have special meanings. These are class names--the words used to designate types of ArcView objects. There is no reliable way to tell whether an arbitrary word like "sTheme" is a class name or not, except by reading the Avenue documentation. (Incidentally, the case of the letters does not matter: "sTheme" and "stheme" are the same, for example.)

Classes behave differently than variables. A class is a kind of an object; a variable holds an object. Avenue lets you change a variable's value, but you cannot change the "value" of a class (it makes no sense). Trying to do so is an error. This limits Avenue's capabilities, but it prevents a lot of confusion.

Avenue programmers cannot create new classes. The language does not permit it, and for good reason. If programmers could create classes willy-nilly, chaos would ensue. Suppose one programmer created a class named "path" in her extension while another programmer independently created a variable "path" in his extension. The second programmer's code would load and run correctly on all computers everywhere, except when the first programmer's extension was loaded. At that point, "path" would become off-limits for use as a variable name and the second programmer's code would create nasty ArcView errors.

It is very bad when the correct execution of a program arbitrarily and unpredictably depends on the other software a user owns.

What about the situation in the Introduction? A user's project suddenly stopped working correctly because a conflicting extension had been loaded.

The problem occurred because ESRI developers add new classes to the language all the time. New classes provide new capabilities, such as reading CAD files, creating new dialogs, or processing grids.

(How does ESRI do this when ordinary programmers cannot? It is done with DLLs--dynamic link library files. These are independent programs that can be "hooked" into the main ArcView program, as if they were originally part of it. You need to know the interface rules to make this work. That is a secret maintained by ArcView's developers.)

Almost everybody runs some ESRI extensions that add new classes. The popular add-ons Spatial Analyst and Network Analyst add a lot of classes. A half dozen extensions supplied with ArcView 3.2 (the latest version) create new classes: CAD Reader, Database access, Dialog designer, Imagine image support, JPEG image support, VPF viewer, Script log.

Which classes exist in ArcView at any moment therefore depend on which extensions are currently loaded. In addition to the extensions mentioned previously, ESRI sells several popular ones: Spatial Analyst, Network Analyst, Tracking Analyst (to name just a few). There are about 20 class-adding extensions all told. There are over a million different combinations of these that could be loaded on any user's machine.

The surprising thing is that no comprehensive list of these classes existed anywhere. The only sure way to tell whether a variable name is valid is to load every ESRI-developed extension simultaneously into ArcView and then test the script. Few can afford this test--and why bother, when the next ArcView extension or upgrade to be released will certainly add to the growing list of class names?

The solution

The class name problem is not serious--yet. With ArcView users contributing new scripts every day to ESRI's ArcScripts repository (five thousand of these are downloaded daily), with ArcView developers building businesses on sales of extensions, and with ongoing changes in ESRI's add-on offerings, the potential for serious conflict is growing exponentially.

A solution requires two parts. First, we have to live with the situation that exists. That means thoroughly documenting the classes that have been created. In the future, programmers can refer to this documentation to avoid creating bad variable names.

During the month of March 2000, ArcView users around the world collaborated to produce this documentation. They did this using tools (a) to find words that look like class names in the software on their systems and (b) to test those words within their ArcView environments.

This collaboration, which is really unprecedented in any GIS community, has been able to accomplish more than even ESRI developers could hope to. It exercised a huge range of installations. This comprised a wide variety of ArcView environments: different extensions, different versions of the software, different operating systems, different code pages, different languages. No company or institution in the world has access to such a variety of test environments.

At the same time, what the ArcView user community can accomplish is limited. There is no assurance that every possible situation has been tested. We may have overlooked things. Moreover, although we can document the existing state of affairs, we cannot change it and we cannot change the course of future developments.

This is where ESRI came in and provided the second part of the solution. Early in the Class Hunt, Damian Spangrud (Technical Product Management, ArcView) and Todd Stellhorn (Lead Programmer, ArcView) contacted us to offer assistance. ESRI, a developer of add-on extensions itself, is just as concerned with this potential problem as any other third-party developer would be.

Details for propeller-heads

Not just any word qualifies as a class. We found that out the hard way, as people submitted creative entries. We had to update the Class Hunt software five times (and it still isn't perfect).

First, there are the "reserved" words. These are special words like "if" and "while" that are explicitly documented in the Avenue language. They either control the flow of script execution or they represent operations (such as "and" or "mod"). Some special words represent very special things in Avenue, such as "SELF", "NL", and "TAB". There are 28 of these reserved words altogether.

Next, not every string of letters and numbers can be a class name. Class names must look like variable names. That is, they must begin with a letter and be followed by a sequence of zero or more letters or digits. And no, class names cannot begin with an underscore, even though variable names can.

At least 348 words presently do not act like class names in ArcView, but they do when one or more extensions are loaded. These are the "evanescent" classes that can arbitrarily come into and go out of existence depending on which ESRI extensions are currently loaded.

About half of the 956 known class names are not publicly documented. They are not intended for Avenue programmers to use and there's not much that can be done with them in Avenue scripts. However, using these names as variables will break a script just as surely as using any documented name.

Finally, the Avenue language includes about a thousand more words used as "requests" of classes. These are words like "GetX", "ReturnArea", and so on. They do not cause any problem, because the Avenue grammar alone can distinguish a request from a variable. The entire problem with class names arises because there is no grammatical distinction between class names and variable names.

One last detail. One ArcView 3.0a user found two names, "sdeadd" and "sqlqry", which we believe may be class names no longer in use. However, since older versions of ArcView are in wide use, such names have the potential to break Avenue code. Although neither ESRI nor we could independently confirm these two names, they look like class names. We are therefore including them as valid classes in our lists.

The results

ESRI is working to minimize the effects of any new class names they create. We look forward to hearing from them in the future about their solution. We expect it will be a lexical solution: that is, ESRI must declare a "name space" for all future class names. This will be a simple rule for determining whether a variable might possibly be a class name. For example, maybe all new class names could be required to contain a special character not allowed in variable names (characters like '!', '~', and others are available).

In the meantime, thanks to the many Class Hunt participants, we are able to offer on these pages a comprehensive table of Avenue class names. This table contains all confirmed Class Hunt entries plus some unconfirmed words believed to originate with obsolete or older extensions. It also contains all class names culled by ESRI from the source code for ArcView and the ESRI extensions.

Anybody who writes a script on one machine and intends to re-use it (either later or on another machine) or redistribute it should consult this list. Yes, it's a pain to do, but at least the information is out there. ArcView is the better for it.

Who knows--maybe some enterprising programmer will write a utility to automate this name checking. That's what makes ArcView so interesting, fun, and useful: its capabilities are constantly growing in the hands of its many dedicated users. Thank you all for making the Class Hunt a success.

--Bill Huber
Contributing Editor
Directions Magazine

• Table of Avenue class names
• Hunt software