Extra Materials

Extra Materials

The Arc Macro Language

This Lecture

What is AML? Command line ArcGIS. Some basic concepts. Using variables and functions. Controlling program flow. Graphical User Interfaces (GUIs)

What is AML?A simple programming language in a text file.

Interpreted not compiled.Runs in the order that commands, directives, etc. appear

in the program.

A way to automate tedious tasks in ArcGIS.A way to write (“old skool”) interfaces.Allows you to write programs that:

manipulate ArcGIS objects such as Coverages and INFO files;

customise ArcGIS applications;increase productivity.

The older programming languages

AML is much better supported in ArcGIS 9.2 than in 8.x: there are no restrictions on the kinds of scripts you can run

(previously it was just ones that ran in Arc, not ArcPlot etc.)However, AML is an essentially dead language.

The old ArcView 3.x has its own language: “Avenue”.

This doesn’t run in ArcGIS 8.x.+

Textbook

ESRI’s “ARC Macro Language: Developing ARC/INFO Menus and Macros with AML Self-study Workbook: Version 7.1.1 for UNIX and Windows NT”

AMLThis is a very simple computer language. Basically just a text

file of the command line commands you want + some basic looping controls.

You can use it to run Arc without it starting up everything – this allows you to hide Arc inside other programs.

We’ll try and get in the habit of using script files in case stuff goes wrong.

AML is not being developed further, but still works in ArcWorkstation.

Example Tasks

Running batch jobs. Automating frequently performed tasks. Combining two or more existing commands to

create a new one. Creating menu driven interfaces. Integrating spatial models with ArcGIS. Standardising procedures for other people.

A Simple Example/* program.aml&type Creating coverage topologybuild buildings polyclean buildings&type Hello World!&return

Arc: &run program.aml

At its most basic an AML program is just a list of ArcGIS commands. You can usually guess the Arc command from the ArcDesktop tool’s name.

With some ArcDesktop tools there’s a Save to AML button. This gives an AML file you can edit or copy from.

Parts of AMLArc Commands

build, clean, etc.

Variables - delimited by %%

%i%, %cover%

Functions - delimited by [ ] [exists %cover% -point]

Directives - preceded by & &return, &type, &if, &goto, etc.

Comments - preceded by /* /* I ‘heart’ ArcGIS (as in ‘stab in the…’).

Syntax

AML isn’t case sensitive.

But remember, some parts of ArcGIS are, so if you are using AML to pass it commands, the commands need to be the right case.

Some directives have abbreviations.

&setvar cover = landuse &sv cover = landuse &s cover = landuse

Basic Layout/* bldcln.aml&echo &onbuild roads lineclean roads ~roads_c # # linebuild stations pointbuild urban polyclean urban&return

Arc: &run bldcln.aml

&return ends the program and returns to the command line. &echo &on will write the commands on the screen as they are

done. &echo &off will stop this. “~” continues commands onto the next line. The bold lines

above are all one command.

VariablesLike a name you can attach to a value or set of text. Variables are set using &setvar directive.

&sv cover := landuse &sv cover = landuse&sv cover landuse

Variables store 4 data types. Character string, e.g. “buildings” Integer number, e.g. 23 Real number, e.g. 4.242 Boolean value, can be .TRUE. or .FALSE.

&listvar (&lv or &l) displays list of currently assigned variables.

Using VariablesWhen using Variables they’re delimited by % % except when

being assigned.&sv cover = landuse

build %cover% poly

Variables can be used together.

&sv cover = landuse&sv infotab = pat&sv item = landuse_typedropitem %cover%.%infotab% %cover%.%infotab% %item%

Which is the same as...

dropitem landuse.pat landuse.pat landuse_type

Local vs. Global Variables

So far we’ve looked at Local Variables that work in a single AML script.

However, you can define Global Variables that work throughout an Arc session.

Global Variable names begin with a fullstop/period (.)

&sv .cover = landusebuild %.cover% poly

&listlocal and &listglobal directives do just what they say.

Reserved Variables These contain information held internally by the system

including information about:

data (DSC$)the graphical cursor/pointer (PNT$)the status of AML programs (AML$)

DSC$FUZZY : fuzzy tolerance.PNT$X : x co-ordinate selected.AML$FILE : the current file being run.

Don’t assign these yourself.See ArcDocs > Customizing ArcInfo > AML > Using

Variables > Reserved Variables

Using Reserved Variables: &DESCRIBEThe &describe function takes in a Coverage and

sets up various reserve variables containing data on the Extent, number of Tics etc.

See ArcDocs > Command References > AML > Describe.

&describe newBuildings&sv numpoly = %DSC$POLYGONS%&type %numpoly%

Command Line ArgumentsSo far we’ve looked at running AMLs with no arguments…

&run plot

You can pass arguments to an AML when you run them, for example…&run plot roads blue

Use the &args directive to get the values. Should be first directive except for &echo.&args <variable...variable>{:rest}

For example&args cover colour:rest

:rest sticks any remaining text in the last Variable. ie for this example “colour”.

Using Command Line ArgumentsExample…

Arc: &run plot roads blue

&args cover colour:restarceditmapextent %cover%edit %cover%de arc nodenodecolor node %colour%draw&return

Functions

Functions perform the following operations:prompting for user input;calculating mathematical values;modifying & extracting values from character strings;reporting current conditions;reading and writing files.

Functions and their options are enclosed by square brackets [ ].

&s covername = [getcover]

Write your own “functions”: write AMLs taking in arguments and use &run / &amlpath to call them in other AMLs.

Directives: Controlling Program Flow

We can put in decision making (branching) and repetition (looping) in AML.

Can branch on the basis of user inputs or calculations – if “something” do “something”, otherwise do “something else”.

Can repeat to do multiple calculations – given a list, run through each item and do “something” to them.

Branching with “If”If the expression equals .TRUE.

then the actions 1 are done, otherwise the actions 2 are done. The rest of code is done whatever.

You don’t need to have the &else section.

Also if you just have one action, you don’t need the &do and &end.&if <expression>&then <actions><rest of code>

&if <expression> &then &do <actions 1> &end &else &do <actions 2> &end /* Rest of code

Expressions&if [username] = bob &then&type “hello bobster”&else &type “do I know you?”

The expression [username] = bob equates to either .TRUE. or .FALSE. These are known as Logical Expressions.

Examples of logical expressions:3 + 6 = 10 equates to .False.3 + 6 = 9 equates to .True.[date -dow] = Sunday equates to .False.

AML makes the comparison using Relational Operators like = or <, <=, >, >=, <>.

Looping

Iterative steps can be performed in AML using an &do &end loop

The &do loop structure&do <loop control clause> <action 1, 2...n>&end

There are four types of &do &end loop:Counted, List, While, Until.

Counted LoopsUsed when the number of iterations is known

&do i = <start> &to <stop> &by <increment> <action 1,2,...n>

&end

i = <loop control variable>

&do burgers = 1 &to 3 &by 1 &type Eaten %burgers%&end&type Elvis ate %burgers% burgers&return

Eaten 1Eaten 2Eaten 3Elvis ate 3 burgers

Listed Loops

Performs a set of identical actions on a list of elements (e.g. coverages)

&do i &list <list of elements> <action 1> <action 2>

…<action n>&end

i = <loop control variable>

&do food &list burger squirrel coke &type %food% &end

burgersquirrelcoke

While and Until Loops

Used when the number of iterations is not known, but while or until a specified condition is met

&do &while <logical expression> <action 1,2,...n>&end

&do &until <logical expression> <action 1,2,...n>&end

&do &until [query 'Do you feel sick yet?'] &type Another burger, thanky’verymuch.&end

DebuggingDebugging programs - finding and fixing errors.Three useful commands.

&echo &on : writes all commands and outputs to the screen.&test &on : puts Arc in AML test mode – actions aren’t done, but

the syntax and possibility of running are checked.&messages &on : sets Arc so it gives messages about what it’s

doing (usually this is set as the default).

&test &on&sv cover = landusebuild %cover% poly&return

Arc also has Error Handling, which lets you determine where errors come from and deal with them. See “Error handling in AML” in the ArcDocs.

Menus: Building a GUI

A menu is a graphical list of options from which the user can select a choice.

AML includes easy-to-use tools for creating menus.Menus can be used for:

creating menus for inexperienced users; eliminating errors by showing only valid options; customising user interfaces; creating highly visual demonstrations; reducing the amount of typing.

See, for example, ArcTools.

Menus from AML Scripts

AML Functions beginning with [get...] create menus for you.

Function Menu choices offered[getchoice] user defined choices[getcover] coverage names[getfile] directory or file names[getgrid] grid names[getitem] item names in INFO file[getsymbol] symbols of specified type[gettin] tin names[getunique] unique item values in INFO

Examples [getcover]

&sv cov [getcover * -POLYGON 'Choose a Coverage:']

&sv cov [getcover]

Separate Menus

[get] functions are OK but you can’t easily control:where they decide to appear on the screen;what they look like;what they do.

Menu files are:ASCII files;named with .menu extension;run with &menu directive.

Must set display environment with &terminal to let AML know the device type before use (also true for [get]). E.g. &terminal 9999

Menu Types

8 supported types:1 : pulldown2 : sidebar3 : matrix4 : key5 : tablet6 : digitiser7 : form8 : enhanced

pulldown

You’re most likely to use: pulldown; sidebar; form; enhanced pulldown.

Example

1 A sample pulldown menuDraw Landuse POLYGONSHADES LANDUSE LU-CODE LANDUSE.LUT

Sites POLYGONSHADES FINALCOV 1 Soils POLYGONSHADES SOILS SUIT SOILS.LUT Streams ARCLINES STREAMS STRM-CODE STREAMS.LUT Template ARCS TEMPLATE'List Attributes' Landuse LIST LANDUSE POLY Roads LIST ROADS ARC Sewers LIST SEWERS ARCClearQuit

Menu Type

Commands

Menu name

Spaces

Matrix Menu Example

3 A sample matrix menu0 0‘Matrix Menu’Landuse POLYGONSHADES LANDUSE LU-CODE LANDUSE.LUTRoads ARCLINES ROADS RD-CODE ROADS.LUTSewers ARCLINES SEWERS SYMBOLSites POLYGONSHADES FINALCOV 1Soils POLYGONSHADES SOILS SUIT SOILS.LUTStreams ARCLINES STREAMS STRM-CODE STREAMS.LUTTemplate ARCS TEMPLATEClearQuit

Position

Matrix Positioning

Number on separate lines give position on screen.

-1

0

1

0 1

1 -1

Key Menu4 A sample key menu7Landuse DatabaseMake a selection by typing the indicated letterL - LanduseR - RoadsS - SewersC - ClearQ - Quit this menu and leave ArcPlotL POLYGONSHADES LANDUSE LU-CODE LANDUSE.LUTR ARCLINES ROADS RD-CODE ROADS.LUTS ARCLINES SEWERS SYMBOLC ClearQ &return

SelectionsCommands

Text

Lines to display before Commands

Enhanced Menu

8 A sample enhanced pulldown menu&BEGIN_MENU &BEGIN_BLOCK "&Landuse" &MENUITEM "&Draw" POLYGONSHADES LANDUSE LU-CODE LAND.LUT &SEPARATOR &MENUITEM "&List" LIST LAND POLY&END_BLOCK&BEGIN_BLOCK "&Sewers" &MENUITEM "&Draw" ARCLINES SEWERS SYMBOL &MENUITEM "&List" LIST SEWERS ARC&END_BLOCK&BEGIN_BLOCK "&Option" &MENUITEM "&Clear" CLEAR &MENUITEM "&Quit" &RETURN&END_BLOCK&END_MENU

Makes LanduseUse Alt-L to use

Separator

MenuEditStarted by typing menuedit.Automatically generates your

menus and allows you to save them to a .menu file.

This allows you to make submenus with Pull Right.

The test facility brings up a test version.

Forms

A powerful menu extension allowing dynamic GUIs.

Windows based editor (type formedit) allows you to add: Command Buttons; Check boxes(multiple section); Radio buttons (one selection

from group); Slider bars (scrollbars); Text boxes; Lists.

Add items by clicking on the icons then in the Form.

Form ElementsThree kinds:

text control : for displaying descriptive text or labels;display control : for displaying the contents of a

variable to the user; input controls : allows user to enter in text or values.

All set up with Right click > Properties.

Display

Text

Input

Text Control

Used as a piece of descriptive text or in front of an input control.

Cannot resize but it will adjust to fit the size of the string you type in.

Display ControlUsed for holding

dynamic text, i.e. things that can change during the course of the program.

For example, you might want to process Coverages and then add their names to a display when finished.

You can resize this control.

Input ControlReturns you a variable and

value (can be global), or starts an action.

Some give you the option of setting up error messages (On Error tab).

For keyboard navigation(usually the SHIFT key)

Customizing ArcToolsYou can add Menus and AML to ArcTools in ArcWorkstation and

ArcToolbox.

These are just AML/Menu files in particular directories written in a particular format.

You can find more details of adding them to ArcTools in the ArcDocs under Customising ARC/INFO > Programming ArcTools.

Note: ArcGIS8.x: You can’t add full AML to ArcToolbox, however, you can run AML from it provided…

It only uses Arc and Info commands (i.e. no ArcEdit). It doesn’t use Menus.

Further info

The ArcDocs aren’t terribly helpful on Forms,but there’s stuff on Menus and AML in Customizing ARC/INFO.

Additional Info

Advanced AML

Displaying AML:ArcPlot

A window for displaying Coverages.Totally command driven and therefore we can

program it in AML.

ArcMap: replaces a combination of ArcEdit and ArcPlot.

Running ArcPlot

Set your Workspace and set environment variables:beforehand, use display 9999 to set graphic

display; Call it from Arc

brings up a second plotting window.Set the map extent.

mapextent <coverage>Set other parameters such as line colour.

linecolor bluePlot the Coverage.

arcs coverageName

Quite like ArcEdit.

Look-Up Tables (.LUT)

Special kind of INFO data file used to categorise Item Values (= columns in an INFO table).

Each lookup table must contain at least two items: Item Name from the Coverage’s Feature Attribute Table

(LUT must be sorted on this in ascending order).Lookup Item, which contains a value associated with

each Category from the FAT.

Pounds Cockney25 Pony500 Monkey1000 Grand

This can then be used with the ArcEdit command Lookup to convert one to the other in a Table.

LUTs and ArcPlot

In ArcPlot you can use LUTs to colour/symbolize your data or add a Label.

The LUT should include the data categories and associated Symbol or Text in columns called SYMBOL or LABEL.

Symbols are given by Symbol number (0 to 999) in a file called a Symbolset.

Many ArcPlot display commands can use LUTs.

See ArcDocs > Cartography > Map Display and Query using ArcPlot

ArcPlot CommandsThe following commands may be useful.

Command What it Doespoints Draws a Points Coverage.

pointtext Adds Labels from a .PAT column.

arcs Draws all Arcs in a line or Polygon Coverage.

arclines Same as arcs but can specify a column and /or a .lut or a symbol from the currently loaded symbol set

arctext Adds Labels to Arcs from an .AAT column.

polygons Draws Polygons.

polygonshades Shades Polygons by .PAT column and/or a .lut or a Symbol.

polygontext Draws Labels from a .PAT column and/or a .lut.

labels Draws Label IDs on a Polygon Coverage only.