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”

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

assigned variables.

&l )

displays list of currently

Using Variables

 When using Variables they’re delimited by

% %

being assigned.

&sv cover = landuse build %cover% poly

except

when  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

they say.

and

&listglobal

directives do just what

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 {: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 done. The rest of code is done whatever.

actions 2

are You don’t need to have the

&else

Also if you just have one action, you don’t need the

&end

.

section.

&if &then &do

and

&if &then &do &end &else &do &end /* Rest of code

Expressions

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

 The expression

[username] = bob .TRUE.

or

.FALSE.

equates to either These are known as Logical Expressions.

 Examples of logical expressions:

3 + 6 = 10 3 + 6 = 9

equates to

.False.

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 &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 = &to &by &end i = &do burgers = 1 &to 3 &by 1 &type Eaten % burgers % &end &type Elvis ate %burgers% burgers &return Eaten 1 Eaten 2 Eaten 3 Elvis ate 3 burgers

Listed Loops

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

&do i &list … &end i

=

&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 &end &do &until &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]

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

 Menu files are:  ASCII files;  named with

.menu

 run with

&menu

extension; 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 Draw

Spaces

Menu name 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 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 0 1 1  Number on separate lines give position on screen.

1 -1

Key Menu

4 A sample key menu

Lines to display before Commands

7 Landuse Database

Text

Make a selection by typing the indicated letter L - Landuse R - Roads S - Sewers C - Clear Q - Quit this menu and leave ArcPlot L POLYGONSHADES LANDUSE LU-CODE LANDUSE.LUT

R ARCLINES ROADS RD-CODE ROADS.LUT

S ARCLINES SEWERS SYMBOL C Clear

Selections Commands

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

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).

For keyboard navigation (usually the SHIFT key)

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.

  Call it from Arc  brings up a second plotting window.

 Set your Workspace and set environment variables:  beforehand, use display 9999 to set graphic display; Set the map extent.



mapextent

 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 25 500 1000 Cockney Pony Monkey Grand This can then be used with the ArcEdit command Table.

Lookup

to convert one to the other in a

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 points pointtext arcs arclines What it Does

Draws a Points Coverage.

Adds Labels from a .PAT column.

Draws all Arcs in a line or Polygon Coverage.

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

arctext polygons polygonshades polygontext labels

Adds Labels to Arcs from an .AAT column.

Draws Polygons.

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

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

Draws Label IDs on a Polygon Coverage only.