Loading and Running an Avenue Script

Summary

  1. Create a new Script Editor document to manage your script.
  2. Load the script by pasting it from the clipboard or using ArcView's load text file button.
  3. Compile and name the script.
  4. Open the window in which the script is to run (usually a View, Table, Chart, or Layout document) without closing the Script Editor window.
  5. Immediately return to the Script Editor window and push the run button.

Introduction

Part of ArcView's power derives from its extensibility through the built-in Avenue scripting language.  Thousands of Avenue scripts are readily and freely available: the two largest sources are ESRI's ArcScripts site and the ArcView help system itself (link to Contents|Sample Scripts and Extensions).  Knowing how to run a script is a fundamental ArcView skill.

What is a Script?

A script is a text file containing Avenue source statements.  Usually it will have a ".ave" extension, sometimes a ".txt" extension.  Here is a tiny example of a script:

MsgBox.Info("Hello World!", "My first script")

You can create your own Avenue script right now simply by pasting this one script line into a new text document.

Scripts do everything in ArcView.  Every command launched from a menu item, button, tool, tool bar, pop-up window, or most dialogs really "just" runs an Avenue script.  The scripts "built in" to ArcView are called system scripts; all others must somehow be "loaded."

How to load a script into a project

You need to get the script's contents into a Script Editor document.  There are several fast, simple ways to do this.  First,

    Create a new Script Editor document by double-clicking on the "Scripts" icon in the ArcView project window.

The second step depends on where the source script is.  If the script's source is a text file:

    Press the Load Text File button in the Script Editor user interface, then navigate to the source script; or

    Open the source file (use Notepad or Wordpad on a Windows machine), copy the text, and then paste the copied text directly into the source script.

If you want to load a system script (to copy its code, for example), then

    Press the Load System Script button in the Script Editor user interface, then select the script by name.

You can also download extensions from ESRI's ArcScripts page (and elsewhere) that read scripts from ArcView project (".apr") files.

What to do with a loaded script

You name it and compile it.

  1. Name the script by naming the script editor document just as you would name any other document: through the Script|Properties menu item or through the Project window's Project|Rename... menu item.  Scripts can have practically any name--there are few restrictions.
  2. Compile it by pressing the compile button .

You may do these steps in either order.  You may even skip the naming step, but it's wise to provide a name.

How to run a script

Once your script has been loaded, compiled, and (optionally) named, you can run it.  This is the tricky part.  Scripts like the "hello, world" script above will run at the push of a button:

Use the run button while the Script Editor window is open , or
With your script selected in the Project window, press the run button .

Many scripts, however, must be run with a particular document (such as a View or Table) active.  This is a conundrum: you need the Script Editor document active (or the Project document active) in order to run the script.  ArcView solves this very simply: when you run a script directly from a Script Editor window, ArcView pretends the active document is the one that was active just before you activated the Script Editor.

So all you do is this:

  1. Open the Script Editor containing your script.  Keep it open for the next step.
  2. Open the document in which you want the script to run.
  3. Immediately re-activate the Script Editor.  Run the script.

Things to watch out for

If you do not follow the preceding instructions, very likely your script will immediately produce an error message like this:

(The offending request will vary from message to message because it reflects what was in the script.)  The hint in this message is the "Project object": chances are, you created a new Script Editor (from the Project window, of course), loaded the script, and then tried to run it.  ArcView therefore considers the Project window to be active.  Your script is trying to do something with a View or whatever, so it runs into trouble.  The solution is to follow steps 1-2-3 above.
When you try to compile the script, you may get syntax errors.  Usually ArcView places the cursor near the point in the Script Editor where it identified the error.  Identifying and fixing these errors is an art.  However, any script you downloaded or obtained from the help system should not have compile-time errors.  Try downloading the script again.
 Save your project before running any script.  An error in a script can crash ArcView.

Other ways to run scripts

There are many other ways to run scripts.  If it should become necessary, we will post the details here.  Some of the ways are:

Attach the script to a control such as a menu item, button, or tool.  Use the control to run the script.  Refer to "Customize (dialog box)" in the ArcView help for more information.  You launch this dialog through the Project|Customize menu item.
Call the script from another Avenue script.  This uses the .DoIt, av.Run, or av.DelayedRun requests.  Look these up in the ArcView help.
Give the script the same name as a system script.  It will then override (not modify) the system script and be used everywhere the system script would be called.
Run the script from the Table document's Calculator button.  Use the "av.Run" syntax.  For example, suppose your script is named "S" and that it returns a point created from a list of two input coordinates.  You can use it to position points in a point theme that has two numeric fields in its feature table (let's call them [X] and [Y]) by activating the [shape] field and typing    av.Run("S", {[X], [Y]})    into the field calculator dialog textbox.
Specify the script as the project startup or shutdown script.  This option is available in the Project|Properties dialog.

There are still other ways, but most of them require Avenue programs to set them up.