Title of Paper


Migrating Avenue to ArcGIS™


Authors' Names


Constantine N. Tonias, P.E. and Elias C. Tonias, P.E.




With the increased use and popularity of ArcGIS™, the need to migrate Avenue based applications to the ArcGIS™ environment has increased significantly.  As such, many developers are faced with the dilemma of how to efficiently convert their Avenue code into a format that utilizes ArcObjects, and which is compatible with ArcGIS™.  One approach, which this paper addresses, is to develop a series of “wraparounds” that facilitates the conversion process.  That is, the creation of a library of procedures that emulate the function of Avenue requests.  By establishing a one to one correspondence between Avenue requests and “wraparounds”, the developer is able to substitute an Avenue request with the appropriate “wraparound”, thereby significantly reducing the amount of time required to perform the conversion.


This paper is a case study of how thousands of lines of Avenue code were converted into VB/VBA using a “wraparound” approach.  Topics covered in this paper include: general Avenue to VB/VBA syntax differences, Views, Themes, Tables, Selection Sets, Graphic Elements, Querying, Calculating, File I/O operations, Message Boxes, Progress Bars, User-Document interaction, Manipulation of Feature Shapes, Legends, Classifications and Application deployment.


Paper Body


1. Introduction


With the increased use and popularity of ArcGIS™, the need to migrate Avenue based applications to the ArcGIS environment has increased significantly.  As such, many developers are faced with the dilemma of how to efficiently convert their Avenue code into a format that utilizes ArcObjects™, and which is compatible with ArcGIS.  One approach, which this paper addresses, is to develop a series of “wraparounds” that facilitates the conversion process.  That is, the creation of a library of procedures that emulate the function of Avenue requests.  By establishing a one to one correspondence between Avenue requests and “wraparounds”, the developer is able to substitute an Avenue request with the appropriate “wraparound”, thereby significantly reducing the amount of time required to perform the conversion.


Like most new explorations, it is the pioneers that catch the first arrows.  Having gone through the process of converting thousands of lines of Avenue code, the authors have learned, and wish to share a few lessons, which might benefit their fellow Avenue programmers who will be converting their applications to the ArcGIS environment.  After all, we don't all have to be pioneers.


During the mid to late 1990's, The CEDRA Corporation had developed a number of Avenue based applications for shapefile editing (CEDRA-AVcad™), coordinate geometry computations (CEDRA-AVcogo™), parcel mapping (CEDRA-AVparcel™), sewer modeling (CEDRA-AVsand™) and water distribution modeling (CEDRA-AVwater™).  All of these applications represented well over 500,000 lines of Avenue code.  As CEDRA began the conversion to the ArcGIS environment, a systematic approach was taken to develop a "wraparound" for each of the Avenue requests, which was used in their software.  As more and more of the software was converted, the number of "wraparounds" increased, and the conversion began to pick up speed.  CEDRA felt that since the use of these "wraparounds" greatly enhanced its conversion process, than surely others could benefit as well.  With this in mind, CEDRA has published a book titled Avenue Wraps, containing all of the "wraparounds" created during its conversion process in digital (optional CD), as well as, descriptive form.


Just as with the 90-10 software rule, that is, a user only uses 10% of a software's total functionality, Avenue developers probably only use 10% of the available Avenue requests.  Although an accurate figure is not available, it is approximated that at least 2500 to 3000 Avenue requests exist.  Avenue Wraps contains over 280 "wraparounds", which is approximately 10% of the total number of Avenue requests.  The "wraparounds" represent a one-to-one mapping for the most popular Avenue requests.  In addition to the Avenue requests used in the CEDRA software, all of the requests identified in the Introduction to Avenue™ training book have a corresponding Avenue Wrap.


Presented below, in the sequence of the Chapters in the Avenue Wraps book, is a description of what was involved in converting CEDRA's Avenue based applications to ArcGIS.  The intent of this presentation is to (a) demonstrate how Avenue code can be converted to ArcGIS code, and (b) describe the methodology behind the conversion.


2. General Conversion Guidelines


In migrating to the ArcGIS environment, the developer actually has a choice in how to integrate with ArcGIS.  Since ArcGIS is a Component Object Model (COM) based application, a developer can use any COM compliant programming language to interface with ArcGIS.  This includes Visual Basic, Visual C++ and the like.  If one wishes to minimize the amount of recoding, the clear choice is to perform the migration in the Visual Basic (VB) and Visual Basic for Applications (VBA) environments.  The reason being is that Avenue syntax is similar to VB/VBA.  So that, VB/VBA makes perfect sense, if one does not wish to perform a complete rewrite.  As a matter of fact, Avenue was developed using VB as the basis for the language.  Note that there is a difference between VB and VBA.  This difference will be addressed later on.


Between VB and VBA, the VBA environment is most similar to the Avenue environment.  Specifically, the programmer can easily develop, and test the application directly within ArcMap.  Any other COM programming language would involve the developer to (a) develop the code, (b) compile the code, (c) create an Active X DLL, (d) load the Active X DLL in ArcMap, and (e) test the code.  If an error were detected, the developer would have to exit ArcMap, correct the error, and repeat the process described above.  This approach leads to a much longer conversion process.  Therefore, it makes senses to convert Avenue code in the VBA environment.


In converting Avenue code there are primarily three aspects, which the programmer needs to address.


First, there is the issue of the syntax differences between Avenue and VB/VBA.  This includes:

         Differences in how statements are structured (if ... then ... end, for each ... end, etc.),

         Differences in names of intrinsic functions such as square root (sqrt vs. sqr),

         Manipulation of string variables (Count vs. len),

         Handling of lists (Get vs. Item),

and so forth.  These, however, are relatively easy to solve, and do not provide much of a problem, other than time.


Second, unlike Avenue in which variables did not have to be declared, in the VB/VBA environment variables do have to be declared.  This issue, although not terribly difficult, is time consuming and tedious, and if not done right, can cause errors, which are difficult to debug.  For those who have developed programs in Fortran, C, C++ and the like know, variable declaration is not a glamorous aspect of programming, and is a stark departure from Avenue, in which variables could be created without regard to specification of type.  So that, like the item discussed above, this part of the conversion is relatively easy to overcome.


Third, there is the issue of writing the appropriate ArcObjects code to perform the task of the Avenue request that is to be converted.  This is where most of the conversion work will be spent, and where the “wraparounds” come into play.  By using “wraparounds”, the developer no longer needs to worry about writing the appropriate ArcObjects code.  This code is buried within the “wraparound”.  Using Avenue Wraps, the developer searches its library of procedures for the “wraparound” which corresponds to the desired Avenue request.  For Avenue programmers, who have no experience with ArcObjects, trying to convert Avenue code using ArcObjects is going to be a difficult task.  That is why this notion of "wraparounds" is so important and essential to the conversion process.


As an example of how “wraparounds” can be used, let’s review the Avenue code shown below:


              Msg = "Okay to continue ?"

              Heading = "My Command"

              Default = True

              ians = MsgBox.YesNoCancel(Msg, Heading, Default)

              if (ians = Nil) then

                 .... do something


              if (ians.Not) then

                 .... do something


                 .... do something



The Avenue code demonstrates the use of the YesNoCancel request as applied to the MsgBox class along with how the response from the user is handled.  Below is how the Avenue code could be converted in VB/VBA using Avenue Wraps:


              Dim Msg As Variant, Heading As Variant

              Dim Default As Boolean

              Dim ians As Integer

              Msg = "Okay to continue ?"

              Heading = "My Command"

              Default = True

              Call avMsgBoxYesNoCancel(Msg, Heading, Default, ians)

              If (ians = vbCancel) Then

                 .... do something

              End If

              If (ians = vbNo) Then

                 .... do something

              End If

              If (ians = vbYes) Then

                 .... do something

              End If


Note the use of the “wraparound”, avMsgBoxYesNoCancel.  In addition to the use of the “wraparound”, note:

         That the variables have been declared using the Dim statement, and that in the first declaration statement where two variables appear, the type of variable assignment is applied to each variable (not just once at the end of the declaration),

         The syntax difference in the use of the “if ... then” statement (there must be an End If, and not just an End), and

         The variable “ians” that is passed back by the YesNoCancel request is a Boolean, while the avMsgBoxYesNoCancel “wraparound” returns the same variable as an integer value, which is equal to one of the predefined VB constants.


“If..Then” statements:            Regarding the use of the “If..Then” statement, although the overall structure of this statement is similar in both Avenue and VB/VBA, there are some minute differences that should be brought to light.  While VB/VBA does an excellent job in displaying syntax errors, it will not flag the “end” statement in the Avenue code sample as an error.  As shown in the VB/VBA code, the “End If” terminates the “if..then” statement, and not the statement “end” statement by itself.  Thus the programmer must be cognizant of this during the conversion.


Furthermore, in Avenue one may write:


              If (a.NE.B) then x = y End


While in VB/VBA, the programmer would write:


              If (a <> b) then

                 x = y

              End If


Thus, perhaps one of the first steps during the conversion process would be to convert these statements first.  Although there is a way to introduce concatenated statements in VB/VBA, it is felt that the above methodology is just as easy, and provides for a more clear representation of complex If...then statements.


"Iterative or Loop" Statements:             Another syntax issue is that of the iterative statements such as the “while”, “for each”, “for” and the like.  So that, once the “if...then” statements have been taken care of, the next thing that could be tackled would be the iterative statements.  Although it is understood that each programmer has a personal programming style and approach in performing the conversion, the above points merely illustrate the types of syntax differences, which the programmer will need to address.


"Error Trapping":                       Finally, a good feature to take advantage of in the VB/VBA environment, which is not available in Avenue, is the ability to trap errors.  Error trapping provides the developer a means to avoid application runtime errors, which typically result in the application to cease to operate properly.  By avoiding application runtime errors, the application can still be used to perform other functions, should an error be encountered, rather than simply "dying".  This results in giving the application a more professional appearance.  The code below demonstrates the use of error trapping:


              Public Sub ShowErrorTrapping()


              Dim pMxApp As IMxApplication

              Dim pmxDoc As IMxDocument

              Dim pActiveView As IActiveView

              Dim pMap As IMap


              '  ---This statement informs the application where to

              '  ---branch when an error is detected in the procedure

              On Error GoTo Errorhandler


              '  ---Get the active view

              Call avGetActiveDoc(pMxApp, pmxDoc, pActiveView, pMap)


              '  ---do something else





              '  ---At this point, our work is done

              Exit Sub


              '  ---Handle any errors detected in the procedure



              '  ---Display detected error number and a description

              MsgBox "Error " & Err.Number & " - " & Err.Description & _

                     Chr(13) & "Subroutine: ShowErrorTrapping"


              End Sub


Note that the introduction of comments in VB/VBA is the same as in Avenue with the exception that comments appear in the color green.  In addition, syntax errors detected in VB/VBA appear in the color red as soon as the typing of a statement has been completed.  This is quite a good feature, but it has a bothersome side effect.  In addition to displaying the erroneous statement in red, VB/VBA also beeps and displays an error message box, which must be closed before the user can continue typing.


3. Application - Document Avenue Wraps


In Avenue the very first statement that typically appeared in a script was:


              theView = av.GetActiveDoc


The object, theView, gave the developer access to all of the themes in the view.  For example, a list of visible themes in the view could be ascertained by the statement:


              vThemesList = theView.GetVisibleThemes


Using Avenue Wraps the above statements would appear as:


              Dim pMxApp As IMxApplication

              Dim pmxDoc As IMxDocument

              Dim pActiveView As IActiveView

              Dim pMap As IMap

              Dim vThemesList As New Collection

              Call avGetActiveDoc(pMxApp, pmxDoc, pActiveView, pMap)

              Call avGetVisibleThemes(pmxDoc, vThemesList)


The first point that needs to be made, in reviewing the above code, is that in Avenue a developer applied a request to an object, which resulted in another object being created, vThemesList in the above Avenue example.  This approach is not possible using ArcObjects.  Therefore, to simulate the Avenue approach, Avenue Wraps provides a subroutine or function to perform the function of the Avenue request by using the argument list in the subroutine or function to pass objects in and out.


The second point is that a List object in Avenue translates to a Collection object in VB/VBA.  Note that List objects in Avenue are zero based, while Collections begin at the index value 1.  For example, the first visible theme in vThemesList would be found by issuing the following statement:


              firstVTheme = vThemesList.Get(0)


while in VB/VBA the statement would appear as:


              firstVTheme = vThemesList.Item(1)


Note that the Avenue request Get becomes Item in VB/VBA.  So that, the search for and revision of lists into collections, the change of Get to Item, and the altering of the indexing could be done at the start of the conversion process.


The final point is that the Avenue code contains two lines of code, while the VB/VBA code contains seven, the first five of which are declaration statements.  Thus, even though there is a one to one correspondence between the Avenue requests and the “wraparounds”, the number of lines of VB/VBA code is greater than its Avenue counterpart due to the declaration statements.  To make the VB/VBA code easier to read, it is suggested that all of the declaration statements be placed at the top of the procedure, rather than scattered throughout the subroutine or function.  One procedure, which one may consider, is to introduce the declaration statements within the code where new variables are first encountered, and then, after the code has been tested, move the declaration statements to the top of the procedure in the same sequence of occurrence.


4. File Input and Output Avenue Wraps


In dealing with file I/O, it is primarily native VB/VBA code that is used to accomplish reading and writing of files.  ArcObjects itself does not provide functionality to read and write files.  As such, the "wraparounds" found in Avenue Wraps are VB/VBA code which provide the functionality found in their Avenue counterparts.


For example the Avenue statement to open a file for writing would appear as:


              aLineFile = LineFile.Make (aFileName, #FILE_PERM_WRITE)


while using Avenue Wraps, the statement would look like this:


              Dim aFileName As String

              Dim aLineFile

              Set aLineFile = avLineFileMake(aFileName, "WRITE")


Note the use of the word Set.  In VB/VBA when dealing with objects the keyword Set is used to create an object.  In this example, aLineFile is a file system object.  In addition, in Avenue there were enumerations (predefined values or constants), which certain requests recognized.  Avenue Wraps simulates enumerations by using strings that reflect the enumeration, such as "WRITE" for "FILE_PERM_WRITE".


5. Theme and Table Avenue Wraps


This is the heart of any application.  This is where the developer manipulates the data in a table.  In Avenue the developer would operate on an FTab or VTab object depending upon the type of table being processed.  Using ArcObjects, the developer uses:

         The IFeature interface, if dealing with an FTab, or,

         The IRow interface, if dealing with a VTab.

To avoid having to create a separate set of "wraparounds", one for FTab's and one for VTab's, most of the "wraparounds" have been written to process both FTab's and VTab's by having the user pass the name of the theme or table to be processed, rather than, passing an FTab or VTab object.


For example the following Avenue code writes a value, 24, to a specific record, 12, in an FTab:


              theView = av.GetActiveDoc

              theTheme = theView.FindTheme("L_0ln")

              theFTab = theTheme.GetFTab

              col = theFTab.FindField("MAP")

              rec = 12


              theFTab.SetValue(col, rec, 24)



Using Avenue Wraps, the above code could be converted as follows:


              Dim pMxApp As IMxApplication, pmxDoc As IMxDocument

              Dim pActiveView As IActiveView, pMap As IMap

              Dim theTheme As String

              Dim theFTab As IFields

              Dim pFeatCls As IFeatureClass, pLayer As IFeatureLayer

              Dim col As Long, rec As Long

              Call avGetActiveDoc(pMxApp, pmxDoc, pActiveView, pMap)

              theTheme = "L_0ln"

              Call avGetFTab(pmxDoc, theTheme, theFTab, pFeatCls, pLayer)

              col = theFTab.FindField("MAP")

              rec = 12

              Call avSetEditable(pmxDoc, theTheme, true)

              Call avSetValue(pmxDoc, theTheme, col, rec, 24)

              Call avSetEditable(pmxDoc, theTheme, false)


The Avenue Wraps code shown above could be used on either an FTab or a VTab, because the "wraparounds" check if the given name passed in corresponds to a theme or to a table.  Note that the FindField request has a direct counterpart in the ArcObjects world.  This is one of the very, very few examples where a "wraparound" was not required.


As stated above, the "wraparound", avSetValue, operates on either an FTab or a VTab.  However, it cannot be used to store geometry (a feature's shape).  In this case the "wraparound", avSetValueG, must be used.  The reason is that when storing attribute information with avSetValue, the ArcObjects Value property is used.  However, in order to store geometry (a feature's shape), the ArcObjects Shape property needs to be used.  Since there are two different properties, two different “wraparounds” were created, one to store attribute data and the other to store geometry.


Continuing with the example above, the Avenue code below would store a two-point line in record 12 of the FTab:


              aShape = Polyline.Make({{20000.0, 20000.0, 30000.0, 25000.0}})

              col = theFTab.FindField("SHAPE")


              theFTab.SetValue(col, rec, aShape)



Using Avenue Wraps, the above code could be converted as follows:


              Dim aShape As IPolyline

              Dim col As Long

              Set aShape = avPolyline2Pt(20000#, 20000#, 30000#, 25000#)

              col = theFTab.FindField("SHAPE")

              Call avSetEditable(pmxDoc, theTheme, true)

              Call avSetValueG(pmxDoc, theTheme, col, rec, aShape)

              Call avSetEditable(pmxDoc, theTheme, false)


In reviewing the above Avenue Wraps code, note the # character in the "wraparound" avPolyline2Pt.  When a number is hard coded with .0, .00, .000, etc., VB/VBA will remove the zeros and replace them with the # character.  In addition, note that there is no direct Avenue counterpart to the "wraparound", avPolyline2Pt.  During CEDRA's conversion process, in an effort to minimize the amount of recoding, certain "wraparounds" were developed that do not have corresponding Avenue requests, but satisfy a need in that they facilitate the conversion process.  In the CEDRA software there were a lot of cases in which two point lines were being created using the double left ({{) and the double right (}}) brace characters.  Rather than using the "wraparound", CreateList and adding point features to the lists (reference is made to the Section 8 example), the "wraparound", avPolyline2Pt was created.


As a matter of fact, there are a number of "wraparounds" which do not have an Avenue counterpart, but when used, greatly help in the conversion of Avenue to VB/VBA code.


Finally, a good feature to take advantage of is the Undo / Redo capabilities of ArcObjects.  The “wraparound”, avSetEditable, when used with the false parameter on a theme will not terminate the editing of the theme.  Rather, the “wraparound” only flushes any buffered writes there may be on the theme.  Thus, the theme remains in an editable state.  This is intentionally done so that the developer can take advantage of the Undo / Redo capabilities.  To do so, the “wraparounds”, avStartOperation and avStopOperation, should be used.  These “wraparounds” begin and terminate an edit operation which is added to the Editor’s operation stack.  This enables the end user to perform an Undo or Redo operation.  The avStartOperation subroutine is called after the theme has been made editable.  The avStopOperation subroutine is called when the desired editing has been completed.  A call to the avStopOperation subroutine must be made if a call to the avStartOperation subroutine has been issued.  There is no limit to the number of times these subroutines can be called within an edit session.  The “wraparound”, avStopEditing, will terminate the Editor saving any edits that may have been made.


6. Feature Selection Avenue Wraps


The "wraparounds" in this section follow the convention in the previous section in that the developer passes the name of the theme or layer to be processed rather than an FTab or VTab object.  For example, the following Avenue code could be used to cycle through the selected set of features in a theme to compute a total value for a field called Deposits:


              theView = av.GetActiveDoc

              theTheme = theView.FindTheme("L_0ln")

              theFTab = theTheme.GetFTab

              col = theFTab.FindField("Deposits")

              sel = theFTab.GetSelection

              total = 0.0

              for each rec in sel

                  deposit = theFTab.ReturnValue(col, rec)

                  total = total + deposit



Using Avenue Wraps, the above code could be converted as follows:


              Dim pMxApp As IMxApplication, pmxDoc As IMxDocument

              Dim pActiveView As IActiveView, pMap As IMap

              Dim theTheme As String

              Dim theFTab As IFields

              Dim pFeatCls As IFeatureClass, pLayer As IFeatureLayer

              Dim col As Long

              Dim sel As ISelectionSet, selList As New Collection

              Dim total As Double, iRec As Long, rec As Long

              Dim pFeat As IFeature

              Dim deposit As Double

              Call avGetActiveDoc(pMxApp, pmxDoc, pActiveView, pMap)

              theTheme = "L_0ln"

              Call avGetFTab(pmxDoc, theTheme, theFTab, pFeatCls, pLayer)

              col = theFTab.FindField("Deposits")

              Call avGetSelection(pmxDoc, theTheme, sel)

              Call avGetSelectionIDs(sel, selList)

              total = 0#

              For iRec = 1 to selList.Count

                  rec = selList.Item(iRec)

                  Set pFeat = pFeatCls.GetFeature(rec)

                  deposit = pFeat.Value(col)

                  total = total + deposit



In reviewing the above Avenue Wraps code, note the use of the "wraparound", avGetSelectionIDs.  This "wraparound" returns a collection of OIDs (object identification numbers) for each of the selected features.  So that, rather than looping on the selected set, sel, as was done in Avenue, a loop is performed on the collection, selList.  An OID is extracted from selList and a feature extracted from the pFeatCls object.  Using the feature, pFeat, the deposit value is extracted and added to total.  This example illustrates the main difference between Avenue and ArcObjects, in that, in Avenue manipulation of data was performed on FTab or VTab objects.  Using ArcObjects, manipulation of data is performed using the IFeature interface, for FTab's, and the IRow interface, for VTab's.  Obviously, this difference poses an obstacle in converting Avenue code, but using the "wraparound", avGetSelectionIDs, a work-around is fairly easily achieved.


7. Message and Menu Boxes Avenue Wraps


This was the portion of the conversion that was probably the easiest to deal with.  Basically what was done was to create a single form, and then programmatically alter the form based upon the type of dialog box that needed to be displayed.  For example, the Avenue Info request which appeared as:


              MsgBox.Info("A sample message string.", "MsgBox Test")


would be converted using Avenue Wraps as:


              Call avMsgBoxInfo("A sample message string.", "MsgBox Test")


Internally, avMsgBoxInfo calls another subroutine passing information, which denotes that the Info request is to be simulated.  By taking the approach to programmatically modify a single form, we avoid the alternative of having to create a unique form for every type of dialog box that is used in the CEDRA software.  So that, the Avenue requests Warning, YesNo and YesNoCancel, as well as Info, all end up calling the same subroutine which in turn uses the same Avenue Wraps form, MessageBox.  Likewise, the other Avenue message box requests, Choice, Input, List, MultiInput and MultiList all end up using the Avenue Wraps form, VDialogBox.  Thus, based upon what information is passed into the controlling subroutine, the appropriate dialog box is displayed.


In addition, to simply the conversion of the standard MsgBox requests, additional "wraparounds" were developed to provide for more sophisticated dialog boxes, such as dialog boxes that could contain "drop-down" items in addition to typical data line items.  Shown below is an example of a dialog box created with the VDBbuild subroutine.  So that, not only is VDBbuild used to create the Choice, Input, List, MultiInput and MultiList dialog boxes, it can also be called directly to create the dialog box below.



Additionally, some CEDRA commands required the use of a horizontal version of VDBbuild.  In the ArcView GIS 3.x environment, the Dialog Designer was used to create the appropriate dialog boxes.  In Avenue Wraps, the subroutine HDBbuild was written to provide the developer a horizontal implementation of VDBbuild.  Shown below is an example of a dialog box created by HDBbuild.



The VDBbuild and HDBbuild “wraparounds” are examples of where the extended functionality in VB/VBA was used to enhance the appearance of CEDRA's applications.


8. Geometry Avenue Wraps


This section is similar to the message box section, and converts rather straight forwardly with Avenue Wraps.  However, there are some minor issues that need to be recognized.  For example:


q                   To create a point in Avenue, the developer could use the statement:


              aPoint = 5000.0 @ 5000.0


There is no counterpart for the @ character, so that, the above statement needs to be rewritten as:


              Dim aPoint As IPoint

              Set aPoint = avPointMake(5000#, 5000#)


Again, note the use of the word Set, when an object is being created.


q                   To create a polyline, which is comprised of four vertex points in Avenue, the developer could use the statement:


              myLine = PolyLine.Make({{aPt1, aPt2, aPt3, aPt4}})


Since, like the @ character, there is no substitution for the left ({) and for the right (}) brace characters, which are used to create a list object, the above statement needs to be converted as follows:


              Dim shapeList As New Collection

              Dim partList As New Collection

              Dim aPt1 As IPoint, aPt2 As IPoint, aPt3 As IPoint, aPt4 As IPoint

              Dim myLine As IPolyline

              Call CreateList(shapeList)

              Call CreateList(partList)

              partList.Add aPt1

              partList.Add aPt2

              partList.Add aPt3

              partList.Add aPt4

              shapeList.Add partList

              Set myLine = avPolylineMake(shapeList)


It is important to keep in mind the following:

         The Avenue Wrap CreateList simulates the function of the left ({) and of the right (}) brace characters

         When an object is added to a collection, the left parenthesis (() and the right parenthesis ()) characters are not used.  For example, when the point objects aPt1, aPt2, aPt3 and aPt4 are added to partList, and when the collection, partList, is added to shapeList.


Using the left and right parenthesis characters, when objects are involved, will result in the display of an error message.


As shown in the Section 5 example, it is possible to use the Avenue Wrap, avPolyline2Pt, to create a two-point line.  However, for non two-point line shapes, the approach using the Avenue Wrap, CreateList, will need to be followed.


9. User Document Interaction


This section pertains to the creation of the graphical user interface (GUI).  That is, the creation of the menu items and tools which are to be made available to the end user.  Unfortunately there is no correspondence in the creation of menu items and tools between the Avenue and VB/VBA environments.  So that, the developer is basically starting from scratch using native VB/VBA functionality to create the GUI.


Regarding the use of tools, there is the issue of how the user interacts with the map display.  That is, how is a "pick" made, how is a line, circle or polygon drawn and so forth.  In Avenue there were the ReturnUserPoint, ReturnUserPolyLine, ReturnUserPolygon and so forth requests, which were applied to a Display object.  In VB/VBA, the programmer will need to write code for the type of "event" that is desired.  Every tool will have a certain set of events, for which the programmer can write code for, if desired.  That is to say, the developer does not have to write code for every event that is supported by a tool.  Depending upon the operation of the tool, one or many events can be coded.


In the case of the ReturnUserPolyLine request, the developer could write code for the MouseDown event to simulate the request.  To simulate the yellow balloon help message, which was displayed when the user moved the mouse over a tool, code for the tool's ToolTip event could be written.


Since VB/VBA provides a far more robust environment for dealing with user-application interaction, this is an area where the developer can truly enhance the Avenue application in the VB/VBA environment.


As noted above, there is a difference between VB and VBA, so that if an Active X DLL is to be created, the developer will need to recreate in VB any menu items and tools that were created using VBA.  Although duplicitous, there is no alternative.


10. Graphics and Symbols


Although not used extensively in CEDRA's applications, the "wraparounds" corresponding to the requests, which operate on graphic elements, were developed to satisfy those used in the Introduction to Avenue training book.  One difference between the Avenue requests and the "wraparounds" is that the "wraparounds" require the developer to specify the type of graphic that is being processed.  For example, to create in Avenue a graphic element which represents a point, the following statement could be used:


              aShape = Point.Make(5000.0, 5000.0)

              theShape = GraphicShape.Make(aShape)


With ArcObjects, every type of graphic element uses a different interface.  Hence, the easiest way to implement graphic element support is to have the developer pass in the type of graphic element that is being operated on.  As such, the above Avenue statement would be converted into:


              Dim aShape As IGeometry

              Dim theShape As IElement

              Set aShape = avPointMake(5000#, 5000#)

              Set theShape = avGraphicShapeMake("MARKER", aShape)


The first argument in avGraphicShapeMake denotes the type of graphic element to be created.  This value could be PEN, MARKER or FILL, which correspond to line, point and polygon graphic elements, respectively.


Another difference between the Avenue requests and the "wraparounds" is that in the ArcGIS environment, the developer can control which layer (annotation target) the graphics are added to.  In Avenue all graphics, in a view, were added to the view's graphic list.  In the ArcGIS environment, the developer has the option of adding graphics to the basic graphics layer or to any other graphics layer that may exist.  This gives the developer a lot more flexibility in managing graphic elements.


11. Classifications and Legends


The "wraparounds" for this section were probably the most frustrating to develop because the terminology between Avenue and ArcObjects is so completely different.  For example in Avenue the developer worked with Legends.  The corresponding term in ArcObjects is Renderer.  In addition, the way ArcObjects handles classifications makes it difficult to correlate Avenue requests to ArcObjects.  That is why the "wraparounds" for classifications, such as avInterval, avUnique, etc., operate on the name of the theme rather than on a Legend object.  For example, the Avenue code shown below assigns a single symbol classification to a theme:


              theView = av.GetActiveDoc

              thmName = "SomeName"

              aTheme = theView.FindTheme(thmName)

              aLegend = aTheme.GetLegend



Using Avenue Wraps, the above code would appear as:


              Dim pMxApp As IMxApplication

              Dim pmxDoc As IMxDocument

              Dim pActiveView As IActiveView

              Dim pMap As IMap

              Dim thmName As String

              Dim aDesc As String, aLabel As String

              Dim pSym As ISymbol

              Call avGetActiveDoc(pMxApp, pmxDoc, pActiveView, pMap)

              thmName = "SomeName"

              Call avSingleSymbol(pmxDoc, thmName, aDesc, aLabel, pSym)


The last three arguments allow the user to control the name of the renderer, the classification name that appears in the Table of Contents, and the symbol used to display all of features in the theme, respectively.  Should the developer wish to use default values, the statement would appear as:


              Call avSingleSymbol(pmxDoc, thmName, NULL, NULL, NOTHING)


Note that in Avenue the keyword NIL could be used to signify that a variable had no value.  In VB/VBA, the keyword NULL is used for string and variant types, while NOTHING is used for objects.


12. Utility Macros


Like Avenue, where the scripts are embedded in the ArcView project file, in VBA, the modules, which contain the VBA code, are embedded in the ArcMap document file.  Therefore, if the document file is deleted or becomes corrupt, all of the VBA code would be lost.  To avoid such distasteful situations it is highly recommended that the VBA code be saved to external disk files.  The "wraparound", ExportVBAcode, is provided solely for this purpose.  In addition to exporting all of the VBA modules, the "wraparound" also exports all of the forms that exist in the document file, as well as, all of the Class modules.  Conversely, the "wraparound", LoadVBAcode, can be used to import the modules and forms, which were exported.  Note that the file ThisDocument.cls contains the menu items and tools (GUI) created by the user with VBA.


Note that when using VB, not VBA, no source code is stored in the VB project file.  That is, the VB project file simply contains pointers to disk files, which actually contain the source code.  So that, a text editor could be used to modify a file (outside of VB), and then, when VB is invoked, the modifications to the file would be visible to the developer within the VB project file.


13. Avenue Wraps Forms


In Avenue, the developer could use the Dialog Designer to create a custom form.  In VB/VBA, the form designer is used to create custom forms.  Operating like the Dialog Designer, the VB/VBA form designer enables the designer to add specific types of controls to a form.  Each control has a specific set of properties and associated events.  Thus, the developer is basically starting from scratch using native VB/VBA functionality to create any custom forms.


Note that any form created in VBA will need to be recreated in VB.  While VBA modules (source code) can be imported into a VB project file, VBA forms cannot be imported.  They will need to be recreated.  In addition, some VB form controls contain different properties than their VBA counterparts, so the developer has to be aware of this when designing the form.


14. Application Deployment Methods


Once the application has been tested and is ready for distribution, the programmer can either:

         Package the application as a protected ArcMap template file (.mxt) in the VBA environment, or

         Build an Active X DLL in the VB environment.


To package the application as a protected ArcMap template file requires very little work, and is a quick and easy way of deploying an application.  Within minutes, a developer can create a protected ArcMap template file.


Building an Active X DLL, on the other hand, requires a fair amount of work.  Depending upon the complexity of the GUI, building an Active X DLL can take anywhere from a few hours to several days.  For clarification, Avenue developers can think of an Active X DLL as an ArcView GIS 3.x extension.  That is, the Active X DLL exists external to the ArcMap document file, much like an extension exists external to the ArcView project file.  Thus, there is an advantage in creating an Active X DLL.


In building an Active X DLL the developer operates in the VB environment.  As a by-product of this, the developer will need to recreate the graphical user interface (GUI) that was previously created in the VBA environment, by building Class objects, and writing code for the appropriate events to perform the same functionality provided in the VBA environment.  All of the other VBA modules, however, will not have to be re-written, but rather, they can be loaded in the VB environment as is.


Shown below is a possible directory structure for converting an Avenue based application, or developing a new ArcMap based application.



As can be seen, a top-level directory is created for the application.  Within this directory, three sub-directories are created, Testing, VBAcode and DLL, although any naming convention can be used.  These directories will contain certain information, as described below, which will be established during the conversion or development cycle.


The Testing directory is to contain the ArcMap document file appl.mxd, where the application will be initially developed and debugged.  As mentioned above, all of the code modules, forms, etc. are stored within the document file, just like an ArcView GIS 3.x project file contains all of the dialogs and scripts that comprise an application.  Therefore, for safety reasons, it is suggested that the ExportVBAcode “wraparound” be used to export the modules, forms, etc., within the ArcMap document file, into the VBAcode folder.  In so doing, should "tragedy" strike the ArcMap document file, all would not be lost.


The VBAcode directory, as stated above, provides a repository for the code modules forms, etc., external to the ArcMap document file.  In addition to providing this service, it is the code modules in this directory that will be added to the VB project file, which is used to create the Active X DLL.


The DLL directory is to contain the VB project file appl.vbp, which builds the Active X DLL for the application.  In addition, all of the Class modules and forms comprising the Active X DLL will also be stored in this directory.  Note that the forms created in the VBA environment within the ArcMap document file will need to be recreated in the VB environment.  The code modules in the VBAcode directory will be added to the VB project file without modification.  Thus, the DLL directory will contain only those modules that are specific to building the Active X DLL.  Note that the VB project file does not actually contain the code.  The VB project file only contains pathnames to the files referenced in the project file.  So that, if one of the files referenced by the VB project file is deleted or modified, the VB project file will not function as desired.


15. Summary


After spending more than five years of developing Avenue based applications, the notion of having to convert all of that code to ArcGIS was a little overwhelming.  However, over the course of a year, the first two months being the most frustrating, the conversion was completed, applications were made available for ArcGIS, and a book, Avenue Wraps, was published.


The philosophy of writing equivalent procedures for the Avenue requests truly simplified the conversion process, in that, large blocks of code did not have to be rewritten.  Instead, a simple name substitution could be made.  The examples shown in this paper illustrate this concept.


As an additional by-product of this type of approach, developers who are used to programming in Avenue can develop new applications for ArcGIS using the same Avenue approach, with which they are familiar, by using the Avenue Wraps “wraparounds”.


Since a direct translator from Avenue to ArcObjects does not exist, the next best solution is to have a library of procedures that emulate Avenue requests.  The authors hope that the information put forth in this paper, and in the Avenue Wraps publication, help Avenue developers move forward to the ArcGIS environment.  Like any new endeavor, the biggest hurdle to overcome is getting started.  In the case of converting Avenue code, the “wraparound” approach makes that first step a little bit smaller to take.




To all those who supplied the sample code included in the ArcObjects Developer Help.  The samples provided a valuable resource in being able to determine how certain tasks could be accomplished.




End Notes




CEDRA-AVcad, CEDRA-AVcogo, CEDRA-AVland, CEDRA-AVparcel, CEDRA-AVsand and CEDRA-AVwater are trademarks of The CEDRA Corporation, Rochester, New York.


ArcView GIS, ArcGIS, ArcObjects and Introduction to Avenue are trademarks of Environmental Systems Research Institute, Inc. (ESRI), Redlands, California.


Visual Basic, Visual C++ are registered trademarks of Microsoft, Inc., Redmond, Washington


Author Information


Constantine N. Tonias, P. E. is a professional civil engineer and president of The CEDRA Corporation.  Graduating from Rensselaer Polytechnic Institute with Bachelor of Science and Masters of Science degrees in Civil Engineering he oversees the research and development operations of the corporation. Mr. Tonias has been responsible for the development of The CEDRA System, an interactive design and drafting system particularly tailored for the civil engineering practice, major portions of which have been ported to ArcView® GIS 3.x and ArcGIS™.  His computer experience also includes the conversion of numerous computing programs between various computing hardware and operating system environments.


Organization: The CEDRA Corporation

Address: 65 West Broad Street

Phone: 585-232-6998

Fax: 585-262-2042

E-mail: cedra@cedra.com


Elias C. Tonias, P. E., is a professional civil engineer and a pioneer in the application of computers in Civil Engineering.  Mr. Tonias holds a Bachelor of Science degree in Civil Engineering from Rensselaer Polytechnic Institute and a Masters of Science from The Ohio State University and is a technical consultant to The CEDRA Corporation in the development of engineering computing software.  He has written extensively in this field, and has managed the development of a wide variety of software.  Having been involved with software development since the very early days of the computer age, he was forced to go through a series of program conversions from computer environment to computer environment.


Organization: Tonias Engineers

Address: 65 West Broad Street

Phone: 585-232-6995

Fax: 585-262-2042

E-mail: ect@tonias.com