Lecture 7

1. Lecture 7 The Arc Macro Language

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

3. 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”

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

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

6. A Simple Example /*program.aml &typeCreating coverage topology build buildings poly clean buildings &type Hello World! &return Arc: &runprogram.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.

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

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

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

10. 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(&lvor&l) displays list of currently assigned variables.

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

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

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

14. 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%

15. Command Line Arguments • So far we’ve looked at running AMLs with no arguments… &runplot • 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”.

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

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

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

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

20. 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 <, <=, >, >=, <>.

21. 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 &endloop: • Counted, List, While, Until.

22. 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 1 Eaten 2 Eaten 3 Elvis ate 3 burgers

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

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

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

26. 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 GUIs 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.

27. Menus from AML Scripts • AML Functions beginning with [get...] create menus for you.

28. Examples • [getcover] &sv cov = [getcover] &sv cov = [getcover * -POLYGON 'Choose a Coverage:']

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

30. Menu Types • You’re most likely to use: • pulldown; • sidebar; • form; • enhanced pulldown. • 8 supported types: • 1 : pulldown • 2 : sidebar • 3 : matrix • 4 : key • 5 : tablet • 6 : digitiser • 7 : form • 8 : enhanced pulldown

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

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

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

34. Input Display Text 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.

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

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

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

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

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

40. Next Lecture • VBA