Version: 0.6
Date: 23 October 1996

Generic ArcView Object-Style Scripts Library

GAVOS USER DOCUMENT

John Ganter
Sandia National Laboratories

GAVOS is a form of middleware that connects a client application to an ESRI® ArcViewTM server. This GAVOS User Document explains what GAVOS is, how it may help you, what it requires, and how to install and use it. Note that the "user" that the document refers to is you, the applications developer, not the end user.

In writing this document, we have made the assumption that you know how to operate ArcView, hopefully at least some Avenue, and your chosen client language. Even if your client language is not Visual Basic, some knowledge of it will be useful in order to run the example client and translate its code for your needs. The GAVOS User Document is divided into three sections:


Contents

  1. Information on GAVOS
    1. What is GAVOS ?
    2. The Advantages of GAVOS
    3. What GAVOS can do for you
    4. The GAVOS Server
    5. GAVOS Objects and Requests
    6. The GAVOS Visual Basic Client
    7. Other Clients
    8. System Requirements
    9. Support and Feedback
  2. Installing and Using GAVOS
    1. Packing List
    2. Unpacking GAVOS
    3. Server Installation or Upgrade
    4. Testing the GAVOS Server
    5. Client Installation
    6. Testing the GAVOS Client
    7. Change Log
  3. Technical Details
    1. Overview of this section
    2. The Idea of GAVOS
    3. GAVOS Communications Protocols
    4. The Server Side
    5. GAVOS Server Side Utilities
    6. The Visual Basic (VB) Client
    7. Writing other clients
    8. The Server As Client: Handling Events on the Server
    9. GAVOS and DDE Performance Testing
    10. Conclusions
    11. References

Section 1: Information on GAVOS

What is GAVOS ?

GAVOS is a form of middleware for linking a generic GIS server, the ESRI® ArcViewTM GIS and its AvenueTM language, to one of several possible clients. On the server, GAVOS is a script library for ArcView, written in Avenue. GAVOS also includes a sample client, written in Visual Basic. Client and server are connected with the Windows DDE (dynamic data exchange) protocol. (Note that GAVOS is pronounced in a Spanish manner as "GAH-vose.") Back to Contents

The Advantages of GAVOS

The simplest way to connect ArcView to a client is to create Avenue code in the client and send it to the server. The problems with this approach are: (a) the client-side programmer must know Avenue; (b) the code is 'hard' (fixed) and wasteful; (c) the coding is tedious, verbose, and executes slowly since the client/server connection must be used constantly to both set and inquire about the state of the server.

GAVOS avoids or minimizes writing hard code on the client side. Instead of sending literal instructions to Avenue, the client programmer makes requests of pre-defined pseudo-objects (scripts written in an object style) on the server side. The object then performs an action and returns a status code, or it returns a status code and a comma-delimited string of answers ("a, b, 1, 2").

Other advantages of using GAVOS include:

What GAVOS can do for you

GAVOS is ideal for applications that do not need complete GIS functionality, but which also have requirements that a GIS cannot meet. Examples are:

GAVOS Client (VB3) and Server (AV)

Figure 1: GAVOS Visual Basic client on left, ArcView server on right

The GAVOS Server

The GAVOS server consists of several Avenue scripts beginning with g. These scripts provide 'wrappers' or pseudo-objects around several of the ArcView/Avenue objects. For instance, the gView script is a wrapper that simplifies the functionality of the ArcView View class. The gView object simplifies the most powerful operations of a View.

Within each pseudo-object are requests, which begin with r. For example, gView has a rZoomToTheme request that accepts two arguments. These arguments are the View, and the Theme. When the request is submitted, the specified View will zoom to the extent of the specified Theme (layer). The requests have long, descriptive names with the assumption that the user will copy-and-paste them using the Windows clipboard.

The gATester script includes sample invocations of all the objects. By uncommenting lines in this script, the user can learn how each object and request behaves. The gATester script is also intended for use in copy-and-paste operations into new scripts. Additional objects/scripts and requests are listed below. Back to Contents

GAVOS Objects and Requests


'####################################################################
GAVOS OBJECTS AND REQUESTS
This report produced by gAAHeaderPullerCaller
Wed Oct 23 15:05:59 1996
'####################################################################

'NOTE in Version 0.6: gFTab.rSetSelectionByValue now has a field type

'----------------------------------------------------------------
'SCRIPT: gAVApp
av.Run("gAVApp", "rTellme, alpha, beta")
av.Run("gAVApp", "rLongList, 2500")
av.Run("gAVApp", "rResize, 200, 200")
av.Run("gAVApp", "rReturnOrigin")
av.Run("gAVApp", "rReturnExtent")
av.Run("gAVApp", "rReturnScreenSizePixels") 'actually a System req
av.Run("gAVApp", "rMoveTo,0,0")
av.Run("gAVApp", "rMaximize")
av.Run("gAVApp", "rMinimize")
av.Run("gAVApp", "rRestore")
av.Run("gAVApp", "rSave")
av.Run("gAVApp", "rSave&Quit") 'will quit w/o warning in AV!!
av.Run("gAVApp", "rQuitNoSave")'will quit w/o warning in AV!!

'----------------------------------------------------------------
'SCRIPT: gDDE
av.Run("gDDE", "rStart,strServerName,strTopicName")
av.Run("gDDE", "rExecute,strExecute")
av.Run("gDDE", "rClose")

'----------------------------------------------------------------
'SCRIPT: gDoc
av.Run("gDoc", "rList, {View, Layout...}")
av.Run("gDoc", "rMinimize,strDocName")
av.Run("gDoc", "rMaximize,strDocName")

'----------------------------------------------------------------
'SCRIPT: gFTab
av.Run("gFTab", "rGetFTab,document") 'rogue method
av.Run("gFTab", "rGetFields,view,theme")
av.Run("gFTab", "rReturnRecordList,view,theme,field")
av.Run("gFTab","rSetSelectionByIndex",view,theme,0,1,2... null will clear)
av.Run(*,"rSetSelectionByStr",view,theme,0,1,2... null will clear)
*** Version 0.6: note addition of field type below
av.Run("gFTab", "rSetSelectionByValue,view,theme,field,type,0,1")
av.Run("gFTab","rSetSelectionByValueAndZoom,Mexico,State,Name,Yucatan")
av.Run("gFTab", "rDefineByQueryString,strView,strTheme,strQuery")
av.Run("gFTab", "rDefineByValueList,strView,strTheme,strField,strType,0,1,2... null will clear")

'----------------------------------------------------------------
'SCRIPT: gView
av.Run("gView", "rGetThemes,strView")
av.Run("gView", "rGetThemesOn,strView")
av.Run("gView", "rThemeOn,strView,strTheme")
av.Run("gView", "rThemeOff,strView,strTheme")
av.Run("gView", "rZoomToSelected,strView,strTheme")
av.Run("gView", "rZoomToTheme,strView,strTheme")
av.Run("gView", "rZoomToRecCen,strView,cenX,cenY,Wi,Hi")

'####################################################################
Back to Contents

The GAVOS Visual Basic Client

GAVOS comes with a sample client application, written in Visual Basic 3.0 and 4.0 (16 and 32-bit) called VBGAVOS. This sample contains the subroutines that implement the Poke-and-Look technique (see Section 3). These Subs and Functions hide most of the details of the conversation between client and server. The user can use VBGAVOS as a starting point for their own applications, or copy the needed functions into another VB project. Back to Contents

Other Clients

GAVOS should be usable with any other Windows applications that speaks DDE. The VBGAVOS Visual Basic code is a good starting point for writing new clients (see Section 3). Sandia has developed PowerBuilder routines that may be made available if there is sufficient interest. A PowerBuilder for Macintosh client that uses AppleScript is under development. Back to Contents

System Requirements

Support and Feedback

Questions, comments, and suggestions on GAVOS and the documentation are welcome. Please contact John Ganter, jganter@sandia.gov Back to Contents


Section 2: Installing and Using GAVOS

Packing List

The GAVOS distribution consists of these files:

0readme.txt : readme file similar to this section
install.ave : installer script for GAVOS server
gavos##.odb : GAVOS server source file, where "##" indicates the version
gavos##.htm : GAVOS documentation, in HTML format
gfigNN.GIF : figures for documentation
VB3 : directory for Visual Basic client
VB3 : directory for Visual Basic 3.0 client
VB4-16 : directory for Visual Basic 4.0, 16-bit client
VB4-32 : directory for Visual Basic 4.0, 32-bit client
VSVBX : directory for VSVBX custom control
VSOCX : directory for VSOCX custom control

Back to Contents

Unpacking GAVOS

If you have a floppy with files:

1 : copy files to a working directory

If you have an .exe self-extracting archive:
1 : move file to a directory
2 : at a DOS prompt, type 'gavos##.exe'
3 : the files will extract

Back to Contents

Server Installation or Upgrade

Please follow these steps to install the GAVOS server:

1 : start ArcView if it is not running
2 : in the Project window, choose Scripts and New button to make a script
3 : select the window of the new script
4 : select Script/Properties and set its name to "Install"
5 : select Script/Load Text File
6 : find the install.ave file and load it
7 : select Script/Compile
8 : select Script/Run
9 : you will be asked to find the gavos##.odb file
10 : you will then be asked whether to add (or replace if it exists) each script in the library.

11 : finally, you will be asked if you want to compile the added scripts. Choose "YES"

Save the ArcView Project file. You will need the path and name for the client (below).

Note on Server Upgrading: If you are upgrading, not all files need to be replaced. When you run the install.ave script, it will show you the old and new dates/versions of files (Step 10 above). If a newer version is available, choose to install it. Otherwise, go to the next file. Back to Contents

Testing the GAVOS Server

The gATester script is convenient for testing out the GAVOS server and making sure that everything is working before trying a client conversation.

By uncommenting the lines of gATester, you can test each object and request. The gFTab object, rSetSelectionByValue request is a good one to start with.

Note: If you wish to use gATester exactly as it is, you will need to make a Mexico View using the sample data that come with ArcView. Make a new view. Name the view Mexico. Now add a theme called State that uses the ..AVDATANAMERICAMEXICOMEXICO sample data. Back to Contents

Client Installation

VBGAVOS is supplied as a Visual Basic 3.0 project (VBGAVOS.MAK), and two VB 4.0 projects (16 and 32-bit), and related files. Thus the user can inspect, run, and modify the code.

Note: VBGAVOS makes use of the VSIndexTab, VSElastic and VSAwk custom controls in the VideoSoft VSVBX/VSOCX product. If you do not have this control installed on your system, you can use the demo copy that is supplied with GAVOS. If you find this product useful, a licensed copy can be ordered using the information in the Help file. Use the following files in Step 2 below:

1 : Copy all the files in the ..VB3 or ..VB4-16 or ..VB4-32 directory to a suitable location

2 : Install the VideoSoft controls. Copy the appropriate VS files to your windowssystem directory:

3 : Either double-click on VBGAVOS.MAK, or start VB and open VBGAVOS.MAK.

4 : The project should open, and show the related files in the Project window. The VSElastic and other VideoSoft controls should load into the Toolbox. You are now in VB design mode. If you have problems with the controls not loading in VB4, try opening the VB3 project in VB4. VB4 will import the VB3 project and update the controls.

Note: In VB3 design mode, you change VSTabs by double-clicking the right mouse button on the VSTabs.

5 : Open the VBGAVOS.FRM file. Go to the Form object, and the Load procedure. Set two variables for your particular installation:

rundir = "C:BARCVIEWBIN"
project_file = "D:Agavosg1gavos.APR"

The rundir variable is the location of the ArcView executable. VBGAVOS will use this to start ArcView if it is not running. The project_file variable is the location and name of the ArcView Project file (.APR) that the GAVOS server resides in.

Installation is complete! Go on to the next section for a tour. Back to Contents

Testing the GAVOS Client

Run the VBGAVOS project. If ArcView is not running, there will be a delay as VBGAVOS starts it up. Try the various controls on the menus; you can follow the tour below. When you wish to see how a control operates, stop VB and double-click on the control to see its associated code. Or you can push the VB Pause button, then the Step button, then the control that you are interested in. Additional Step pushes will step through the code.

The Objects tab has controls to establish a simple conversation.

  1. Pull down the combo box; a list of requests will appear.
  2. Select ReturnOrigin
  3. Press the Poke-N-Look button. The gAVApp object will be sent a rReturnOrigin request.
  4. The answer will appear in the text box

The DeskTop tab has buttons to arrange the client and server in various ways on the Windows desktop. Press the GAVOS beside ArcView button to have the client and server share the desktop.

Note: The VB integrated development environment (IDE) tends to cover up the ArcView GUI. Now that you have customized the client (in Client Installation), you can make an executable and run it. Choose File/Make Exe File… to do this. Then you can run VBGAVOS as a standalone Windows application, and the IDE will not be involved.

The Client/Server tab demonstrates the interesting View and FTab operations.

  1. Click on Find Views to list the Views.
  2. Now click on a View (e.g., Mexico). This will list the Theme(s) for that View.
  3. Click on a Theme (e.g., State). This will list the Fields for the theme.
  4. Click on a Field (e.g., State-id). This will list all the values for that field.
  5. Select one or more values.
  6. Click the Select button. These values will be selected (highlighted) on the ArcView server's View.
  7. If you click the Zoom checkbox, ArcView will zoom to the selected values.

Note: Clicking on a Field will list all the values in the FTab for that Field. This can be a long list. We have found that this operation is memory sensitive, and it may not complete for some lists on some machines with smaller amounts of memory (< 16 megs). There seems to be constraint on the number of characters that can come across, but it does not seem to correspond to published VB limitations.

The Server Events tab shows an example of a server event, where ArcView sends a message to the VB client. This is a valuable feature, because it means the server can notify the client of random events like when an end-user selects a feature on a View, or when the user presses a button to indicate that they are finished and want to return to the client.

In the VB Client

  1. Click on the Server Events tab to make it active

In ArcView:

  1. Double-click on the GUI to bring up the Customize menu
  2. Add a Button to the View category/GUI (or another)
  3. Associate the gDDE-Example script with your new button's Click event
  4. Close the Customize menu
  5. Click the Button you added. On the client side, a message will appear in the Listbox

This concludes the client testing. Remember to look at the sample code behind the VB controls that interest you. This will show you how to tailor GAVOS to your own needs. Back to Contents

Change Log

The change log shows planned and completed changes, the date proposed, and the date and version that the change was completed (if completed).

IDCHANGE DATEINDONE VERS
01gFTab object: multiselect: capability to select a list of features 01-25-9602-07-960.2
02gView object: add zoom to selected features request 01-25-9602-07-960.2
03gAVApp object: add Save and Quit requests 01-25-9602-07-960.2
04gAAHeaderPuller: basic script manager object that reports on objects and their requests 01-25-9602-09-960.2
05gDoc object: rewrote gDocFinder to include DocWin object. Added Minimize/Maximize requests 02-05-9602-13-960.2
06gView: fixed rZoomToSelected request so that it accepts theme name and activates this theme 02-13-9602-14-960.2
07gView: added rThemeOn, rThemeOff, and rGetThemesOn requests 02-13-9602-15-960.2
08gView: added rZoomToTheme request 02-13-9602-15-960.2
... ..
09gView: added zoom to bounding box request 01-26-9603-22-960.3
10gDDE: new object for DDE link that will notify client of an event 01-26-9603-25-960.3
11avu-ScriptLibMgr, Usr: developed utility scripts that write scripts to/load scripts from ODB file 01-25-9603-25-960.3
... ..
12gFTab: rSetSelectionByIndex: this is a better-named version of rSetSelectionByStr, which has been retained for backward compatibility. 05-30-9605-31-960.4
13gFTab: rSetSelectionByValue: this allows selection by Field/Value, instead of just the Index 05-30-9605-31-960.4
14gAVApp: added rQuitNoSave request 05-30-9605-31-960.4
15gAVApp: modifed rMaximize and rMinimize requests so that a av.GetSymbolWin.Close command is given. This works around an ESRI bug that causes the SymbolWin to appear. 05-30-9605-31-960.4
... ..
16gFTab: rSetSelectionByValueAndZoom: this additional request is a workaround for a PowerBuilder client problem, and may be useful for others to use also. 07-09-9607-23-960.5
17NEW request: gFTab: rDefineByQueryString: sets the definition of a Theme so that features are shown or not shown 09-20-9610-23-960.6
18NEW request: gFTab: rDefineByValueList: sets the definition of a Theme so that features are shown or not shown 09-20-9610-23-960.6
19CHANGED request: gFTab: rSetSelectionByValue: now has a fieldtype argument following the field name 10-23-9610-23-960.6
... ..
??object to manage the GUI, especially simplifying it 01-25-96
... ..

Back to Contents


Section 3: Technical Details

Overview of this section

GAVOS is a script library for connecting an ArcView GIS server to a variety of clients with minimal effort and maximum code reuse. This section of the user document is a detailed discussion of how GAVOS works and how it was built. It talks about what we did, but more importantly why we did it. As a result, a few parts of this document are extremely detailed and will not be meaningful to some readers -- they can be safely skipped. These sections are included as reminders of design decisions made, and issues that may need to be revisited. Back to Contents

The Idea of GAVOS

GAVOS is an approach to linking a generic GIS server, the ArcView GIS and its Avenue language, to one of several possible clients. The simplest way to do this is to create Avenue code in the client and send it to the server. The problems with this approach are: (a) the client-side programmer must know Avenue; (b) the code is 'hard' (fixed) and wasteful; (c) the coding is tedious, verbose, and executes slowly since the client/server connection must be used constantly to both set and inquire about the state of the server.

GAVOS is an attempt to avoid or minimize writing hard code on the client side. Instead of sending literal instructions to Avenue, the client programmer makes requests of pre-defined pseudo-objects (scripts written in an object-style) on the server side. The object then performs an action and returns a status code, or it returns a status code and a comma-delimited string of answers ("a, b, 1, 2").

This distinction is analogous to two types of telephone conversations. In the first, the client laboriously instructs the server (a clerk) to walk to a shelf, look for items by moving their eyes left to right and up and down, create a list of the items, and return the list. This is a long, verbose, interactive conversation. In the second conversation, the client determines that the server/clerk supports a List request. The client makes this request. The clerk then performs the operation in a manner which is private with respect to the client, and returns an answer.

There are several advantages of the latter approach. The client does not need to know anything at all about how the items or 'shelves' are arranged, or how the 'clerk' works. The communication media becomes less important; the List request would work by telephone, mail, face-to-face conversation, etc. The List request can be completely rebuilt, as long as it is invoked in the same manner and returns results in the same way. Large investments can be made in optimizing the List request, because the request will serve any and all clients. In turn, this investment can be protected since the clients do not have to see how the request works. Back to Contents

GAVOS Communications Protocols

A GAVOS conversation takes place using a dynamic data exchange (DDE) link, a mature Microsoft communication protocol supported by most Windows 3.x, 95, and NT applications (Microsoft 1993). In DDE, the client in a conversation is termed the destination and the server is termed the source. A conversation occurs between a single source and destination, but a running application can have more than one conversation active.

There are three types of links used in conversations:

  1. Manual link: the destination (client) must request data from the source (server). This is the only type of link supported by ArcView (ESRI 1995).
  1. Notify link: the source notifies the destination that specified data have changed. Essentially, the server is detecting a change event and notifying the destination.
  1. Automatic link: the source automatically updates the destination. The server not only detects an event, but also executes an instruction (update the destination control) when it occurs.

Once a manual DDE link is established, an ArcView source/server supports three types of methods across the link (Table 1).

Table 1: Dynamic Data Exchange (DDE) Methods

Method from clientSends Receives
LinkExecutecommand, including run a script but without arguments .
LinkRequestcommandstring
LinkPokea value to insert. Can be used to run a script with passed arguments in the form of a string. .

A DDE conversation is semantically constrained. All of the verbs (i.e., Avenue commands) are available for use, but the only nouns are strings. This prevents any direct passing of objects from ArcView's rich object model. Instead, the objects must be referred to by names. Strings can also be parsed (by previous agreement on format) into lists of strings.

After making this discovery, we developed an approach to handle it termed the Marionette Layer. The marionette layer is a means of manipulating objects via strings only (Figure 2). The simplest way is to merely send a request to an ArcView object (Figure 2, Label A). This becomes unwieldy when instances of objects have to be created and destroyed. The Marionette Layer works more effectively when server scripts are written in an object style (Figure 2, Label B). These pseudo-objects parse the information on the incoming link, perform operations, and format and return a string.

Figure 2: Concept of a Marionette Layer between a client and ArcView server which passes string data types only. By having an implicit agreement between client and server, objects can be manipulated by using strings as object 'handles.'

GAVOS and the Marionette Layer should also work using Remote Procedure Calls (RPC), a predominantly UNIX communications protocol that is also supported on Windows NT. On the server side, there are no anticipated changes to the code. On the client side, mechanisms would have to be developed to fill the role of a DDE control. A DDE control is a receptacle for the outgoing message in LinkExecute and LinkPoke, and the incoming message in a LinkRequest. The control thus hides details of the conversation from the applications programmer. Unlike DDE, RPC can operate between applications running on different computers. Back to Contents

The Server Side

We have discussed the client/server architecture of GAVOS, and the communications protocols that allow it to engage in conversations with clients. In this section, we focus on the core functionality of GAVOS itself: the functions that it provides through Avenue scripts that behave like objects.

Avenue is not a truly object-oriented language. It provides encapsulated, pre-defined objects which have properties and support 'requests' (methods). There is inheritance in the provided object model, and this helps the applications developer to understand the object model. For instance, a View is a type of Doc(ument) which inherits Doc properties (e.g., CreationDate) while adding its own specialized properties (e.g., Projection). The user cannot develop new objects. But the user can write pseudo-objects, which are scripts (essentially subroutines) that accept 'requests' in the form of arguments.

A greatly simplified GAVOS script appears in Figure 3. The name is gAVApp; in the Hungarian notation this script is in the GAVOS library (its name begins with g), and handles the ArcView application. The sequence of operations is (keyed to the (1), etc. labels in figure):

  1. Client sends a LinkPoke to the gAVApp object, with an argument string
  2. The LinkPoke activates the named script, which parses the argument string into a Request (rMoveTo) and arguments (x,y).
  3. An If-ElseIf-End statement selects the code appropriate for the request.
  4. A MoveTo request is sent to the AV (application) object, which causes it to move to the specified location on the Windows desktop.
  5. A status string is returned to the client. Note: this last operation is simplified considerably; see the Link-and-Request discussion below.

Thus GAVOS uses an object, "request, argument" naming/calling syntax. An alternative is the "smartly-named scripts" approach of Richards (1995). Richards names scripts in a object.request format. From a naming and calling perspective, the Richards approach is more elegant. But we believe that the labor of constructing a separate script (with header, compilation, etc.) for each request is undesirable. Thus we employ a ArcTools-like approach wherein each Request is handled by an ElseIf section in a single Object script.

Figure 3: Structure of a GAVOS script. See text for explanation of labels.

The "request, argument" format has caused some problems. If the argument consists of a comma-delimited list, List = ("a,b,c,d"), then using the List.AsTokens(",") request on the argument will split it into more than just the request and argument. One quick fix is the use a less common delimiter (e.g., "request|argument"). A more elegant approach would be to pass a Dictionary consisting of a String object for the Request, and a List object for the arguments.

On occasion, scripts break the ArcView object hierarchy because only names of objects, not objects themselves, can be passed. For example, gFTab will accept a document name, get the FTab object for it, then perform operations on the FTab object. Ideally the object (the Doc) would be passed. Another approach would be to use an object's name as a 'handle.' The object would be passed among multiple scripts by using the name/handle as a key in a shared Dictionary object. So far, the simpler name approach seems adequate since fetching the object using the name is a single, rapid Avenue request (typically, object = av.GetProject.FindDoc(strName_of_object) ).

Another refinement would be an object request broker script. This script would be called by the client. It would check the requested object against a Dictionary, and ensure that the requests and arguments were valid. It would then dispatch the request. An object request broker would be more elegant and probably more reliable than calling scripts directly, but the additional development effort and overhead does not seem justified at present. Back to Contents

GAVOS Server Side Utilities

GAVOS has several utility scripts (gAA prefix), and it makes use of general-purpose Avenue utility scripts (avu- prefix); see Ganter 1996. These scripts are listed below.

Utilities for the GAVOS Manager/Developer

gAATemplate : standard template with headers for use in developing new objects/scripts

gAAHeaderPullerCaller : extracts requests and arguments from selected GAVOS scripts, in order to prepare a report for GAVOS users.

avu-ScriptLibMgr : allows a library manager to review and set an ObjectTag on any selected script(s). This ObjectTag is a List containing a Date object and a Number object (a version number). The library manager can then load the script(s) into a portable Object Database (.ODB) file for distribution to users.

avu-ScriptLibUsr : allows a script library user to extract scripts from a script library, i.e. an .ODB file. If a script already exists, the user is shown the existing/new dates and version numbers, and asked to decide whether the script should be replaced. This script can be renamed and customized by the script library manager to be an 'Installer' for a specific library, and to work with only a specific .ODB file.

Utilities for the GAVOS User

Install : a version of avuScriptLibUsr (see above) that has been customized to install a specific version of GAVOS.

gATester : script that lists all the GAVOS objects and requests. By uncommenting these lines, the various GAVOS objects can be called. This is useful for testing on the server side, without involving the client. Back to Contents

The Visual Basic (VB) Client

The GAVOS Visual Basic 3.0 client is a descendent of the BUSYBOARD tutorial (Ganter 1995). While BUSYBOARD did simple LinkExecute and LinkRequest operations, it would not call server-side scripts with arguments, and receive data in reply. GAVOS experiments led to the Poke-and-Request Approach which is described below.

The client consists of a form containing an instance of a VideoSoft VSTab VBX (Visual Basic custom control) and several instances of the VSElastic VBX (see Figure 1). This results in a tabbed form which adjusts itself automatically to various monitor resolutions. Other VBXs on the form provide DDE controls to transmit and receive DDE LinkExecutes, LinkRequests, etc.

There is no DDE method that combines a command with arguments and returned information. The Poke-and-Request technique combines a LinkPoke and a LinkRequest to deliver this functionality. Poke-and-Request is encapsulated in several Visual Basic subroutines. The approach consists of a Poke, with arguments, to an Avenue script on the server. When finished, the script places a string into a predetermined, hard-coded Avenue global variable. This string may simply be a status code, or it may be a status code followed by a comma-delimited list. When the Poke is complete, the client does a LinkRequest to obtain the value of the global. It then strips the status code from the first position in the string. If there are additional characters, they are parsed into an array for convenient access by VB.

A more detailed explanation of Poke-and-Request is shown in Figure 4. The sequence (keyed to the (1), etc. labels in the figure) is:

  1. Any Visual Basic routine that is in scope can call the Sub SLinkPokeNLook subroutine, with arguments for a GAVOS request and appropriate arguments. Note that there is a difference in nomenclature between the older DDE and Avenue/GAVOS. A DDE 'request' is actually for an object (a script), not for a method within that object. From the perspective of the GAVOS user, the Object is gAVAPP, the Request is rLongList, and the argument to the Request is 100. (In this illustration, all subroutine arguments are simplified for discussion purposes. For example, in most cases the first argument is the DDE control (txtInBox)).

  2. SLinkPokeNLook modifies the arguments for DDE usage. It then begins a series of calls to additional subroutines.

  3. SLinkPoke is called. It sets up the DDE control (txtInbox) with appropriate properties, using the arguments it has been passed. It then performs the LinkPoke.

  4. The gAVApp script is called and receives the string passed along through the LinkPoke. The string is parsed into a Request (in the GAVOS sense) and arguments. The script then finds the Request using If-Then-Else, performs the request, calculates a Status value, and sends to the gVarBox object a rSend Request, the Status, and the List (answer).

  5. The gVarBox object parses out the Request, Status, and List. For the rSend Request, it builds a string from the Status and List.

  6. The gVarBox object places its string into a hard-coded, pre-arranged Avenue global variable called _gAAA.

  7. Meanwhile, on the client side the SLinkPokeNLook has waited synchronously for the SLinkPoke subroutine to complete. It then calls SLinkRequest which sets up txtInbox to obtain the value of _gAAA, and does a LinkRequest.

  8. SLinkPokeNLook then calls SLinkParse, which gets the string from txtInbox, and splits it into two Visual Basic variables: strStatus and strResponse.

  9. Since strResponse is unwieldy, SLinkPokeNLook then calls SLinkParse2Array, which uses the VSAwk VBX to split strResponse on comma boundaries into an array for each item.

  10. The calling VB code now has access to strStatus and arrResponse, which can be used appropriately. For instance, if strStatus is 1 (OK), then the code might fill a ListBox with the values in arrResponse.

Figure 4: The Poke-and-Request technique

This explanation will seem very complex, because it exposes all of the machinery underneath the GAVOS library. But because of the encapsulated design, the GAVOS user (the application programmer) really only needs to know the GAVOS Objects and Requests, and how to call SLinkPokeNLook (or equivalent) with some simple arguments. Everything else, including DDE, is hidden from view. Back to Contents

Writing other clients

The Poke-and-Request client-side subroutines can probably be emulated in any Windows development environment that fully supports the DDE methods (Execute, Request, Poke). By design, the server side will hopefully not require any modification.

One difference that we have noted is how VB handles DDE conversations; they are based on controls. Thus VB3 can easily detect events in the controls which have to do with the DDE conversation. Other environments, in contrast, use function calls for all DDE operations.

Sandia has developed a PowerBuilder client; this may be made available if there is sufficient interest. A PowerBuilder for MacIntosh client, which will use AppleScript instead of DDE, is under development. Back to Contents

The Server As Client: Handling Events on the Server

In some applications, random events can occur on the server that the client needs to be aware of. For instance, an end-user might close a window or push a button. The gDDE object can be used to create DDEClient object on the ArcView server. This object can then send a message to, for example, a Visual Basic form on the client side. If the client-side programmer has associated some code with the form.Update event, then this code will execute when the server event occurs. It is questionable whether this approach will work with RPC, since a loop would probably have to be run continuously on the client side in order to detect the new value. Some coding at a lower level of UNIX inter-process communication would probably have to be done. Back to Contents

GAVOS and DDE Performance Testing

An initial concern was the speed and capacity of the DDE link. The gAVApp.rLongList request was written to test performance on the development machine (Dell XMT100, a 100mhz Pentium with 32 meg RAM, running Windows NT 3.51). Experiments showed that a Visual Basic textbox control can LinkRequest up to 11400 characters. Since the stated capacity of a textbox Text property is 32K, there appears to be a limitation in the DDE link.

A speed test using gAVApp.rLongList was performed. On the server alone, the request listed the numbers 1 to 2500 in 10.8 seconds. Called through DDE, the request took 11.3 seconds. The delay was about 0.5 seconds, or 5% overhead. This overhead is barely noticeable by the user.

When the VSAwk VBX is used to parse the returned comma-delimited string into an array, there is a significant delay. A list with 2500 items requires 24 seconds. We hope that the 32-bit OCX version will be significantly faster. Since VSAwk is a generic and very flexible component, it may be possible to write a much faster special-purpose parser. Back to Contents

Conclusions

Our initial impression was that GAVOS should be a 'generic' script library. This view has evolved. We still believe that there are general classes of functionality that are required by several applications. For instance, most applications need to highlight polygons on a map. ArcView, along with some simple GAVOS scripts, can fill this need. Thus GAVOS is 'generic.' But increasing generality (i.e., supporting more and more applications) requires that more and more Avenue functionality be encapsulated into objects. Taken to extremes, this would mean writing object wrappers around every ArcView object so that it can be marionetted with strings. For some purposes GAVOS is appropriate, but we should avoid re-making the entire Avenue language and object hierarchy.

For example, it is probably better to have a few GAVOS scripts and a much larger number of utility scripts that fully utilize Avenue without the restrictions of marionetting. These scripts can then be used in general Avenue programming, and also be called by the GAVOS scripts. Back to Contents

References

ESRI, 1995. ArcView version 2: Working with Visual Basic, ArcView White Paper Series, July 1995. Available at: http://www.esri.com/resources/papers/papers.html#VISUAL

Ganter, J.H., 1995. "Inter-Application Communication (IAC) Using ESRI Software and Other Development Tools," Proceedings of the 1995 ESRI User Conference (SAND 95-0397). Abstract on CD-ROM and WWW: http://www.esri.com/resources/userconf/proc95/to250/p248.html Details at: http://www.sandia.gov/gis/tutrs/iactut2.html

Ganter, J.H., 1996. ArcView/Avenue: Coding Styles and Utility Scripts for Efficient Development. Proceedings of the 1996 ESRI User Conference (SAND 96-1371C). Abstract on CD-ROM and WWW: http://www.esri.com/external/resources/userconf/proc96/TO200/PAP160/P160.HTM. Paper and code at: http://www.sandia.gov/gis/tech/avcsus.htm

Microsoft, 1993. Communicating with Other Applications. Chapter 21 in Visual Basic 3.0 Programmers Guide.

Richards, James. 1995. "Advanced Application Development with ArcView2," Proceedings of the 1995 ESRI User Conference. Abstract on CD-ROM and WWW: http://www.esri.com/resources/userconf/proc95/to150/p108.html

Back to Contents



Acknowledgement and Disclaimer