Robust Application Development in ArcView

• Reducing development time.
• Writing robust Avenue code.
• Application portability across hardware platforms.
• Accessing of user-defined datasets without requiring re-coding.
• Eliminating hard-coded directory paths.

---

Introduction

• Must be robust, checking for errors both within the system and the data.
• Can be setup on different hard disks and directories.
• Are portable across Operating Systems.
• Can access a variety of data across different computers and clients.

This is because the paths to all of the data within the ArcView application are saved as part of the Project file.

Once the application has started successfully, any number of fatal error messages can occur, from the 'Nil Object' error:

Through the 'Unrecognized Command':

To the ever faithful, bad Script Parameters:

This document discusses how to avoid these error messages happening, together with other points that should be taken into account when developing a fully customized ArcView application that is robust and maintainable.

---

Structured Programming

What is the Problem?

There are many cases where good applications have been developed that do not solve the problem, or do not live up to the users expectations. In both of these cases, the application (regardless of its technical merit) will either not be used by the users, or will require extensive and costly reworking.

Application Design

• A breakdown of the problem into sub-problems.
• A schedule for implementing the solution.
• Any critical components of the solution.

Reliability

Hence, in the design phase all of the possible areas where reliability may be a problem should be addressed. The results of this analysis will either take the form of improved checking within the system, or (in the last resort) the placing of restrictions on the applications performance envelope. In all cases, the client should be made fully aware of the potential problems, and the steps that have been taken to address them.

Maintainability

---

Graphical User Interface Design

Modern user-interface design methodologies involve the users from the initial design to final implementation. If one of these methodologies is not followed, and the user is just presented with the prototype, it must be designed by experienced individuals familiar with the design methodologies and with users' "normal" requirements.

ArcView Menus

To minimize confusion, all of the customized options required for the application should be made available on a customized ArcView menu system. The series of customized menus (one or more for each ArcView document class) should be the primary menus for the application.

This involves creating a customized menu system, as well as performing small modifications to a copy of related native ArcView menu system. However, at no time should the native ArcView menu system be altered. If a menu system is to be customized (regardless of how minor the modification is), a copy of the native ArcView menu should be taken and it is this copy that is modified.

Toggling Menus

Dynamic Menus

User Feedback

The status bar should also be used to provide useful information to the user. This is useful as it does not delay the execution of a script. This can be in the form of brief help information, the results of a calculation, or details of the current process.

---

ArcView Project File

Hence, by opening and closing a single Project, the user can open or close all of the components needed for a specific task or application. For example, Views and related Scripts can be saved in a single Project file. This ensures that when working with a View the required Scripts are also available. In addition, Projects can be used to keep joined Tables, or Tables and Charts together.

Although this seems the most logical way of storing the information, it does create several problems.

• Portability. When a Project file is saved, absolute directory paths to all of the data are stored within it. Assuming neither the Project file or any of the data change location, this is not a problem. However, if the Project file were moved to a new location on the same computer, or copied onto a new computer, when the Project is launched, the system asks the user to specify the new directory paths to all of the required data. Depending upon the amount of data required by the Project, this can be a long and tedious process.
• Project File Size. As each Project file contains references to every document stored within it, the more documents, the larger the Project file. This impacts upon the Projects loading time.

• Rapid ArcView application development.
• Customize the GUI's depending upon the loaded data.
• Load spatial and attribute data, including joining data.
• Create Themes from the defined data.
• Improve Project loading speed by reducing the data processing required at startup. For example, Themes does not have to be created (which may require querying of the data) until they are requested.

---

Data Formats

Naming Convention

Spatial Data

With the introduction of ArcView 3.0, spatial data can be stored in several different formats. Each format has advantages and disadvantages.
 

Wherever possible, it is recommended that shapefiles are used as the standard spatial data format. If ArcInfo coverages are to be used, each separate spatial layer should be stored in its own workspace, so if it becomes corrupt, only one spatial layer needs to be replaced/repaired.

ArcView can also display AutoCAD drawings and Image data (i.e. satellite images, air photographs and other remotely sensed or scanned data). The valid image formats include ArcInfo GRID data, TIFF, Windows Bitmap (.bmp), TIFF/LZW compressed image data, and Sun rasterfiles.

Attribute Data

ArcView can also connect to database servers, such as Oracle, Ingress or Sybase, and retrieve records using SQL queries. For details on this process, refer to the ArcView Help section entitled "Connecting to a database to create a table", "Setting up a database connection with ODBC" (MS-Windows) and "Logging into a database with the Database Integrator" (UNIX).

---

Help Files

The method of creating the Help files depends upon both the operating system and the required sophistication of the Help system.

MS-Windows 3.1x, NT and '95

ArcView Method

Word Processor Method

UNIX Method

---

Extending ArcView

Extension Methods

• Is the ArcView application to work on multiple operating systems?
• Can the standard ArcView documents (View, Table, Chart, Layout or Script) be adapted to provide the required functionality?
• What level of sophistication is required?
• Is a large amount of data to be passed to the extension application?
• Is a response required from the extension application?

"Command-line" Interface

"Table" Interface.

Neuron Data

Dynamic Data Exchange (DDE)

Dynamic Link Libraries (DLL)

ArcView Extension

DDE/DLL Development Environment

It is recommended that the preferred development environment will be a high-level programming language (C/C++ or Visual Basic) together with a cross-platform set of GUI development libraries.

---

Programming Style

Naming Conventions

Avenue Scripts

As there are few length restrictions on Avenue script names, the script name should give a fairly detailed idea as to its function. Scripts normally fall into 3 main categories:

• Scripts that would be generally useful across different Projects.
• Scripts related to a specific ArcView document.
• Scripts that are specific to one Project.

GIS/Trans : Script Name
Document Name : {Menu Path}.{Type of Event}
App : Script Name

Local Variables

Esri has defined a convention as to the naming of variables created directly from Avenue classes.

• Unique variables. These are all variables that contain a unique example of a particular class.

• List variables. Many Avenue scripts return a homogeneous list of a particular class. The variable should be prefixed by 'the' and the class name should by plural.

• Loop variables. If a script has to process a homogeneous list, the loop variable will contain many variables of the same type. The loop variable should be prefixed by 'a' and the class name should be singular.

Global Variables

Traditionally, due to the way ArcView processed scripts at startup, all of the global variables had to be placed in one script which is named to be the first script in alphabetical order. For example, the script could be called aaGlobals. With the introduction of ArcView 2.1, this restriction was removed. However, all global variable definitions should be kept in one script.

Script Headers

However, the script name should give a good idea as to the purpose of the script. This is especially the case with Avenue scripts as described above. Also as many Avenue scripts are of a simplistic nature, the time expended on creating the header may never be recouped in future use of the code.

Although the actual headers will vary with the programming language, certain flags should be reserved for use in all headers. This means that set names are used for specific header fields, and has the added benefit that programs could be written that could automatically generate documentation form the source code. This process can be partially automated by changing the default ArcView project to always create a customized script.
 

Comments

The comments should be clear and concise!

Appendix A gives examples of commenting an Avenue script.

Indentation

To help reduce the number of levels of indentation, care should be taken to exit a script once an error has occurred or no further processing is required. A good example of this is a MsgBox that allows the user to press Cancel.

Example:
  ' Performing an inappropriate check requires the remainder of the script to
  ' be indented
  theResult = MsgBox.ChoiceAsString(theChoiceList,
                                    "Select the required choice",
                                    "Title")
  if (nil <> theResult) then
    ' Perform processing within the indentation
       :
       :
  end
 

  ' Careful checking of results remove a level of indentation
  theResult = MsgBox.ChoiceAsString(theChoiceList,
                                    "Select the required choice",
                                    "Title")
  if (nil = theResult) then
    return nil
  end

  ' Processing can now be performed without requiring indentation

This correct checking of returned values also means that the processing level is reduced as the remainder of the script does not have to be parsed.

---

Writing Robust Avenue Code

ArcView Versions

To combat incompatibilities between the different versions, Esri has included an av.GetVersion command which returns the version number plus any patch letter code (i.e. "2.1b"). Therefore, any version specific code must be bracketed by this command

Example:
  if ("2.1" = av.GetVersion.Left(3)) then
    ' Do v2.1x specific code
  else
    ' Do v3.0 specific code
  end

Note: This command was not available in v2.0. Hence, the first knowledge the application would have that it is running on version 2.0 is when it causes a system crash on the av.GetVersion command!

Note: The if.then.else statement should be written in order of version number. This means that if a command does not change in a future version, no Avenue code will have to be altered.

Note: The av.GetVersion command returns the full ArcView version. Hence, to perform version specific code, the left-most three characters need to be compared.

Returned Values

• The Script completed successfully
• The severity of the error condition
• Whether the current program branch should continue

1. Boolean. No Avenue object is returned so TRUE is returned if the script terminated successfully, FALSE otherwise.
2. Numeric Error Code. If a script does not return an Avenue object, but the state of termination of required, a numeric error code can be returned. The value 0 should indicate success, whilst errors should be indicated by various negative values.
3. Avenue Object. If on successful termination, a script returns an Avenue object, a error condition should be indicated by returning a nil. Although numeric error codes could be returned for failure, the calling script must filter the returned value.

Checking Returned Values

Example:
  theProject = av.GetProject
  theFTab = theTheme.GetFTab

However, in some cases the Script may be asked to find a field in a Table, open a disk file, or process the response of a message box. In all cases, the returned value may be incorrect (null) or invalid (nil). The response to these statements must be checked.

Example:
  ' Access the field XYZ in the FTab
  theField = theFTab.FindField("XYZ")
  if (nil = theField) then
    MsgBox.Error("Failed to find field 'XYZ' in table '"+theFTab.GetName+"'",
                 Script.The.GetName)
    return FALSE
  end

  ' Select one of the entries from the Choice List
  theChoice = MsgBox.ChoiceAsString(theChoiceList,
                                    "Select the required choice",
                                    "Title")

  ' If Cancel was pressed, then nil is returned
  if (nil = theChoice) then
    exit
  end

Clear Error Messages

The developer should also pick the level of the error and display the correct ArcView dialog.

• Information Dialog. Should be used when the system has to communicate information to the user, but can continue.
• Warning Dialog. A more serious error has occurred, but the system can continue with possibly some limitations.
• Error Dialog. A fatal error has occurred, and the system cannot continue in its current state. Processing will be terminated. It is advised that the name of the Script that the fatal error occurred within is used as the title for the dialog. This is help is locating of the error.

Checking Script Parameters

Example:
  ' It is assumed that a Script exists that takes 2 parameters:
  ' - the parameters passed to the Script (as a list)
  ' - a list of the required classes for those parameters
  if (av.Run("App : Verify List", {SELF, {String, Theme, FTab}}).Not)
    MsgBox.ListAsString(SELF,
                        "Invalid Parameters",
                        Script.The.GetName)
    exit
  end

Note: In the above code fragment, the message gives the name of the script that the error occurred within as its title. This gives the developer an idea as to where an error has occurred.

Checking the State of the System

This problem also arises when an error occurs in an update Script. ArcView immediately displays the offending Script, so the active document is now a Script Editor (SEd). However, the update event still has to be processed by all of the other update Scripts.

Hence, whenever the state of the system is requested, the response must be checked.

Example:
  theActiveDoc = av.GetActiveDoc
  if (theActiveDoc.Is(View).Not) then
    MsgBox.Error("The Active Document is not a View",
                 Script.The.GetName)
    exit
  end
 

Use of Menu Update Scripts

Checking for these conditions can be performed by the Script associated with the Click/Apply operation. However, by performing the checking in the Update script, the menu option can be enabled/disabled as appropriate. This gives several benefits:

• Stops the user selecting the option when the system is in the wrong state.
• Gives a visible indication of the valid operations.
• Minimizes the error checking in the Click/Apply script. (i.e. the script does not have to report to the user that the system is in an incorrect state for the requested operation)

Variable Comparison

• There is no confusion as to whether the variable is being set.
• If a coding error has been made (i.e. the if construct is omitted), the ArcView syntax checker will produce an error instead of trying to interpret the line incorrectly.

Note: Although the proposed method of variable comparison is not strictly necessary in Avenue, it is good practice to use one standard across programming languages. Hence, when a programming language is used that has different comparison and setting symbols (i.e. Pascal (= and :=) and C/C++ (== and =)), the proposed comparison method can still be used.

Use of Example Datasets

Use of the 'Tab' character

---

Conclusion

• A library of routines/scripts to be used for future development.
• Other scripts that can be shared more easily between ArcView Project configurations.
• An improved standard for written Avenue code.
• Better designed Projects.
• Cross-fertilization of ideas.

---

Appendix A - Example Avenue Script

'N  Name           : ADM : Verify List
'
'C  Copyright      : (c) GIS/Trans, Ltd. 1997
'
'D  Description    : Verifies a set of Objects in a List against a set of Classes in a List. The two
'D                 : Lists must be the same size.
'
'P  Parameters     : List - List of Classes
'P                 : List - List of Objects
'P                 : Boolean - TRUE if errors should be displayed in a MsgBox. FALSE otherwise
'
'R  Returns        : Boolean - TRUE if the List of Objects is valid against the List of Classes.
'R                 :           FALSE otherwise
'
'E  Called Scripts : ADM Message : Set Error
'
'S  Called By      : ADM Message : Display
'S                 : ADM Message : Get
'S                 : ADM Message : Get Level
'S                 : ADM Message : Get Title
'
'K  Keywords       : Parameters Verify
'
'O  OS Depends.    : None
'
'H  History        : K Howard    1-Jan-97  Initial Coding
'

' Check to make sure that a list of 2 items as been passed
if (nil = SELF) then
  av.Run("ADM Message : Set Error", {"nil pointer passed to function",
                                     Script.The.GetName})
  return nil
end
if (SELF.Is(List).Not) then
  av.Run("ADM Message : Set Error", {"SELF object is not a List - it is a '"+SELF.GetClass.GetClassName+"'",
                                     Script.The.GetName})
  return nil
end

' Retrieve the parameters from the list
parametersList = SELF.Get(0)
if (nil = parametersList) then
  av.Run("ADM Message : Set Error", {"Parameters List pointer is nil",
                                     Script.The.GetName})
  return nil
end
if (parametersList.Is(List).Not) then
  av.Run("ADM Message : Set Error", {"Parameters List is not a List - it is a '"+
                                       parametersList.GetClass.GetClassName+"'",
                                     Script.The.GetName})
  return nil
end

' See how many parameters are passed. If there are only two, set the
' report errors flag to TRUE
if (3 = SELF.Count) then
  reportErrors = SELF.Get(2)
else
  av.Run("ADM Message : Set Error", {"There is an invalid number of parameters ("+SELF.Count.AsString+
                                       ") in the passed list",
                                     Script.The.GetName})
  return nil
end

' Get the passed class definitions
classList = SELF.Get(1)
if (nil = classList) then
  if (reportErrors) then
    av.Run("ADM Message : Set Error", {"Class List pointer is nil",
                                       Script.The.GetName})
  end
  return nil
end
if (classList.Is(List).Not) then
  if (reportErrors) then
    av.Run("ADM Message : Set Error", {"Class List is not a List - it is a '"+classList.GetClass.GetClassName+"'",
                                       Script.The.GetName})
  end
  return nil
end

' Check to see that there is the the same number of passed parameters
' as there are class definitions
if (parametersList.Count <> classList.Count) then
  if (reportErrors) then
    av.Run("ADM Message : Set Error", {"Number of parameters ("+parametersList.Count.AsString+
                                         ") and classes ("+classList.Count.AsString+") do no match",
                                       Script.The.GetName})
  end
  return nil
end

' Check each parameter against it's class definition
listSize = parametersList.Count
for each i in 0..(listSize - 1)
  aParameter = parametersList.Get(i)
  aClass = classList.Get(i)
  if (nil = aClass) then
    if (reportErrors) then
      av.Run("ADM Message : Set Error", {"Failed to get Class "+i.AsString+" from Class List",
                                         Script.The.GetName})
    end
    return nil
  end

  ' Check to see parameter is of the correct class
  if (aParameter.Is(aClass).Not) then
    if (reportErrors) then
      av.Run("ADM Message : Set Error", {"Parameter "+i.AsString+" is not of type '"+aClass.GetClassName+"'"+nl+
                                           "It has Class '"+aParameter.GetClass.GetClassName+"'",
                                         Script.The.GetName})
    end
    return nil
  end
end

' The parameter list has been successfully verified
return TRUE

Tel: +1 (617) 354-2771
Fax: +1 (617) 354-8964
E-Mail: khoward@ma.gistrans.com
WWW: www.gistrans.com
 

Robert J. Hallett Jr.
Analyst
GIS/Trans, Ltd.
675 Massachusetts Ave
Cambridge, MA 02139

Tel: +1 (617) 354-2771
Fax: +1 (617) 354-8964
E-Mail: rhallett@ma.gistrans.com
WWW: www.gistrans.com