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 Selfstudy Workbook:
Version 7.1.1 for UNIX
and Windows NT”
AML
 This 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 topology
build buildings poly
clean 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 AML
 Arc 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 &on
build roads line
clean roads ~
roads_c # # line
build stations point
build urban poly
clean 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.
Variables
 Like 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 Variables
 When 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_type
dropitem %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 = landuse
build %.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: &DESCRIBE
 The &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 Arguments
 So 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 Arguments
 Example…
Arc: &run plot roads blue
&args cover colour:rest
arcedit
mapextent %cover%
edit %cover%
de arc node
nodecolor 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
&if <expression>
done. The rest of code is done &then
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>
&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 Loops
Used 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
Eaten
Eaten
Elvis
1
2
3
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
burger
squirrel
coke
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
Debugging
 Debugging 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 = landuse
build %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
[getchoice]
[getcover]
[getfile]
[getgrid]
[getitem]
[getsymbol]
[gettin]
[getunique]
Menu choices offered
user defined choices
coverage names
directory or file names
grid names
item names in INFO file
symbols of specified type
tin names
unique item values in INFO
Examples
 [getcover]
&sv cov [getcover]
&sv cov [getcover * -POLYGON 'Choose a Coverage:']
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 : pulldown
2 : sidebar
3 : matrix
4 : key
5 : tablet
6 : digitiser
7 : form
8 : enhanced
pulldown
You’re most likely to use:
 pulldown;
 sidebar;
 form;
 enhanced pulldown.
Menu Type
Example
1 A sample pulldown menu
Menu name
Draw
Landuse POLYGONSHADES LANDUSE LU-CODE LANDUSE.LUT
Spaces 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 ARC
Clear
Quit
Commands
Matrix Menu Example
3 A sample matrix menu
0 0
Position
‘Matrix Menu’
Landuse POLYGONSHADES LANDUSE LU-CODE LANDUSE.LUT
Roads
ARCLINES ROADS RD-CODE ROADS.LUT
Sewers ARCLINES SEWERS SYMBOL
Sites
POLYGONSHADES FINALCOV 1
Soils
POLYGONSHADES SOILS SUIT SOILS.LUT
Streams ARCLINES STREAMS STRM-CODE STREAMS.LUT
Template ARCS TEMPLATE
Clear
Quit
Matrix
Positioning
0
1
 Number on
separate lines
give position on
screen.
1 -1
-1
0
1
Key Menu
Lines to display before Commands
4 A sample key menu
7
Text
Landuse Database
Make a selection by typing the indicated letter
L - Landuse
R - Roads
S - Sewers
C - Clear
Selections
Q - Quit this menu and leave ArcPlot
L POLYGONSHADES LANDUSE LU-CODE LANDUSE.LUT
Commands
R ARCLINES ROADS RD-CODE ROADS.LUT
S ARCLINES SEWERS SYMBOL
C Clear
Q &return
Enhanced
Menu
Makes Landuse
Use Alt-L to use
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
Separator
MenuEdit
 Started 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 Elements
 Three 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.
Input
Display
Text
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
Control
 Used 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 Control
For keyboard navigation
(usually the SHIFT key)
Returns 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).
Customizing ArcTools
 You 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
ArcMap: replaces a
combination of ArcEdit
and ArcPlot.
 A window for displaying Coverages.
 Totally command driven and therefore we can
program it in AML.
Running
ArcPlot
 Quite like ArcEdit.
 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 blue
 Plot the Coverage.
arcs coverageName
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
Cockney
25
Pony
500
Monkey
1000
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 Commands
The following commands may be useful.
Command
What it Does
points
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.