An AML Program For Calculating the Number
of Points within a Set of Polygons
John J. Bark
Contents
- Introduction
- Methodology
- A Step By Step Annotated Listing of the AML Program<
- Problems Encountered
- How to Run the AML
- References
- Appendix 1. The Complete Listing of the AML Program & Menu
- Appendix 2. Explanation of Labels
- Appendix 3. Explanation Of Variables Usage
- Appendix 4. An Example of the Screen Output Produced by the AML
Arc Marco Language (AML) is the programming language used to customise ARC/INFO. It allows the organisation of commands into easily performed Marco operations and can provide user-friendly menu interfaces. AML’s are convenient and save time, especially if the same sequence of commands is performed repeatedly.
The AML I designed is able to calculate the number of points that exist within a set of polygons and inserts the value into the Polygon Coverage Attribute Table. This report explains its creation and how it works.
Return to Top of DocumentBefore writing the AML code I designed the program as a flowchart (figure 1), allowing me to explore the its logic. I then decided which Arc commands to use for each command routine. For the Overlay Analysis I decided to use Intersect as this preserves the features common to both coverage’s, in this instance the points within the polygons. To calculate their frequency I used the Frequency Command as opposed to the Statistics as I felt it was tidier, and to join it to the Polygon Attribute Table I used Joinitem.
Using my flowchart I began writing the AML code. Whilst writing the code I used the &echo and &test directives to check the program logic, testing to find any programming bugs. This ensured the AML ran smoothly.
Once I had a working program I was able to develop its user presentation. The &messages &popup directive allows questions to appear in the form of a popup menu, offering the user a choice of either ‘yes’ or ‘no’. This directive must be used in conjunction with &messages &on to return to the default messages setting. Another directive I used throughout is &pause which halts the program flow temporarily. By altering the flow timing the user is able read and digest command window text before the program moves on. Using the &seconds option allows a program pause for a specified number of seconds. Several of these &pause directives include information for the user that they must confirm.
Return to Top of Document3. A Step By Step Annotated Listing of the AML Program
I have removed from this listing all the comment lines ease of clarity. A complete listing of the AML program is contained in Appendix while each label and variable are briefly explaining briefly in Appendices 2 and 3. Throughout this section I have included screenshots of the popup menus used but not the command window text, an example of this output is in Appendix 4.
3.1 AML Introduction and Workspace Selection
The AML runs through a number of introductory lines before the user selects their Workspace.
3.1.1 AML Introduction
&severity &error &routine exit &terminal 9999 &type &type &type ---------------------------------------- &type | | &type | This AML Calculates the Number of | &type | Points within a set of Polygons | &type | | &type ----------------------------------------
Before the user sees the title box in the command window two directives exist to set the working environment. The &severity directive specifies that in the event of an error message occurring, command of the AML is sent to routine exit (Section 3.9), whilst the &terminal directive must be set to permit the use of popup menus.
3.1.2 Confirming Current Workspace
&pause &seconds 1 &label correct_wspace &type &type &type w &type &sv i = 0 &pause &seconds 2 &messages &popup &sv correct_wspace = [query 'Are you in the correct Workspace'] &messages &on &if %correct_wspace% = .TRUE. &then &goto coverages
The current Workspace is displayed and a popup asks whether it is correct. If so, the user confirms this by clicking on ‘Yes’ (.TRUE.) and move to label coverages (Section 3.2.1) for the Coverage selection process, otherwise they flow to label change_wspace (Section 3.1.3). The reason variable ‘i’ is set equal to zero here is explained later.
3.1.3 Changing Workspace
&label change_wspace &messages &popup &sv change_wspace = [query 'Do you want to change Workspace'] &messages &on
&if %change_wspace% = .TRUE. &then &goto select_wspace &label not_help &type &type &type This Program cannot help you any further. &pause &seconds 1 &messages &popup &sv quit = [query 'Do you want to Quit'] &messages &on
&if %quit% = .TRUE. &then &goto end &type &type &type The AML will reset itself. &pause &seconds 2 &goto correct_wspace
If the user decide their present Workspace is incorrect, they are asked whether they would like to change their location. By deciding to change they move to label select_wspace, otherwise the not_help label informs them that the AML can no longer assist them and then offered the opportunity to quit. If not taken the AML restarts.
&label select_wspace w /home/magis/[username] &type &sv select_wspace = [getfile * -workspace 'Please ~ ~ select the Workspace you wish to enter' -sort -none]
&if %wspace% = ' ' &then &do &pause &seconds 1 &type &type &type You have not selected a Workspace. &pause &seconds 1 &goto not_help &end w %select_wspace% &sv wspace_name = [entryname %select_wspace%] &type &type &type You may now select Coverages from Workspace %wspace_name%. &pause &seconds 2
Label select_wspace moves the user to their home directory by recognising their username. Using the getfile function a selection menu is displayed containing their Workspaces. The inclusion of the -workspace option ensures only Workspaces appear while the -sort option sorts their appearance order and the -none option includes ‘none’ in the menu list. Selecting the -none option moves the user to label not_help, discussed earlier. After selected a Workspace, the movement is confirmed before coverage selection begins.
3.2 Selection of the Polygon & Points Coverage’s
After confirming or selecting their present workspace the user selects polygon and points coverage’s through a series of popup lists.
3.2.1 Selecting Coverage’s
&label coverages &type &type In a moment, Popup Menus will appear allowing you to select ~ ~ Polygon and Point Coverages for use within this AML. &type &type If the Coverage you require is not listed, select the NONE ~ ~ option.
This label explains to the user the coverage selection method.
3.2.2 Selecting the Polygon Coverage
&label polygon &sv poly [getcover * -poly -none 'Select a Polygon coverage'] &if %poly% = ' ' &then &goto none_cover &type &sv poly_name = [entryname %poly%] &if %i% = 1 &then &goto correct
Using the getcover command with the -poly option limits the popup menu to just Polygon Coverage’s, negating the need for topology checks. The use of the -none option inserts ‘none’ into the list, acting as an escape route to label none_cover (Section 3.2.4) if the coverage they want does not appear.
Later the user confirms their coverage selections (Section 3.4) and if they choose to change the polygon coverage they return to label polygon. This process sets variable ‘i’ to 1 so that they return to label correct and do not flow onward flow to select a points coverage.
3.2.3 Selecting the Points Coverage
&label point &sv point [getcover * -point -none 'Select a Point coverage'] &if %point% = ' ' &then &goto none_cover &sv point_name = [entryname %point%] &if %i% = 2 &then &goto correct &goto name_intersect
The same process as previously used to select a Polygon Coverage is followed selecting a Points Coverage. When the user has selected their coverage’s they move to label name_intersect (Section 3.3.1).
3.2.4 When NONE is Selected Instead of a Coverage
&label none_cover &pause &seconds 1 &type &type &type You selected the NONE option from the Popup Menu. &pause &seconds 2 &goto correct_wspace
If the user selects the -none option from either coverage selection menus they are sent to this label, which informs them of their choice before returning them to label change_wspace (Section 3.1.3).
3.3 Selection of a Name for the Intersect Coverage
With Polygon and Points coverage’s selected, a name is required for the Intersect Coverage that is subjected to validation checks.
3.3.1 Entering the Name
&label name_intersect &pause &seconds 1 &type &type To discard any Points located outside of the Polygons a new ~ ~ Coverage is created using an Intersect Overlay. &pause &seconds 2 &label name_loop &messages &popup &sv out_cov = [response 'Enter a name for the Intersect Coverage'] &messages &on
&if %out_cov% = ' ' &then &do &type &messages &popup &pause YOU MUST ENTER A NAME &messages &on &goto name_loop &end
The request for a user entered Intersect Coverage name is done using the response function, which displays a popup prompt for their response. If no response is returned a loop exists ensuring the user enters a name. They are informed of this through a popup created by the &pause directive to which they must respond.
3.3.2 Validating the Intersect Coverage Name
&type &type Checking Validation of Coverage Name ..... &pause &seconds 3 &if [exists %out_cov% -cover] &then &do &messages &popup &pause Coverage %out_cov% exists in this Workspace. You will need ~ ~ to enter another name.
&sv list_cov1 = [query 'Do you want to see a list of existing ~ ~ Coverage names in this Workspace']
&messages &on &if %list_cov1% = .TRUE. &then lc &goto name_loop &end &if [exists %out_cov%_freq.tab -info] &then &do &type &type Later in this AML a Frequency Table is produced, but a ~ ~ Frequency File already exists for coverage name %out_cov%. &type &type To prevent confusion you need to enter another name for the ~ ~ Intersect Coverage. &pause &seconds 3 &messages &popup &sv list_cov2 = [query 'Do you want to see a list of existing ~ ~ Coverage names in this Workspace'] &messages &on &if %list_cov2% = .TRUE. &then lc &goto name_loop &end
The Intersect Coverage name entered is subjected to two validation checks that ensure there is no duplication of coverage names or output files. The exists function determines whether the coverage name already exists and whether a ‘_freq.tab’ INFO file exists using that coverage name. In both instances the user is informed and presented with an opportunity to view a list of the existing coverage names. A Loop then returns them to label name_intersect and naming process begins again. If the name passes both checks, the user flows onward to confirm their selections.
3.4 Confirming Coverage Selections
Before performing the Intersect the user is presented with an opportunity to change their selections.
3.4.1 Coverage Selection List
&label correct &pause &seconds 1 &type &type &type This AML will now perform an Intersect Overlay between &type Polygon Coverage : %poly_name% &type Points Coverage : %point_name% &type Creating Intersect Coverage : %out_cov% &type &type If these details are correct the Intersect Overlay can be ~ ~ performed, otherwise you can change any of these selections. &pause &seconds 5 &messages &popup &sv intersect = [query 'Are these details correct'] &messages &on
&if %intersect% = .TRUE. &then &goto intersect &else &menu intersect.menu &stripe 'Do you wish to change the'
The user is informed of the selections they made and asked to confirm them. It their selections are correct they move to the Intersect procedure, but if they decide to change anything a change selection menu appears.
3.4.2 The Alteration Menu
The Alteration Menu Code:
	1 intersect.menu 	'Selected Coverages' 	 POLYGON &sv i = 1; &return 	 POINT &sv i = 2; &return 	'Intersect Coverage name' &sv i = 3; &return 	'OR Continue to the Intersect' &sv i = 4; &return
&if %i% = 1 &then &goto polygon &if %i% = 2 &then &goto point &if %i% = 3 &then &goto name_loop &if %i% = 4 &then &goto intersect
Their menu choice assigns variable ‘i’ a value before returned to the AML. Depending upon this value they are sent back to the label dealing with that selection process. The menu also gives the option to continue on to the Intersect.
3.5 Performing the Intersect
&label intersect &messages &popup &pause Click on OK to perform the Intersect &messages &on
&type &type Intersecting %point_name% with %poly_name% to create ~ ~ %out_cov% ..... &messages &off intersect %point% %poly% %out_cov% point # join &messages &on &type &type Coverage %out_cov% was created by the performing the ~ ~ Intersect Command. &pause &seconds 2
After confirming their selections the user informs the program to perform the Intersect by selecting ‘OK’ from the popup message. The &messages &off directive hides the command window text produced by the intersect while the &type lines inform the user the Intersect is happening and of its completion. This directive is used for other Arc commands that produce text supplementary to the course of this AML.
3.6 Calculating Frequency
&type &type The Frequency Command is now used to calculate the Points~ ~ Frequency within this Coverage. &type &pause &seconds 3 &messages &popup &pause Click on OK to Calculate Frequency &messages &on
&sv freq_item = [entryname %poly%] &sv freq_item = %freq_item%# &sv summary_item = %out_cov%-ID &type &type Calculating the Points Frequency ..... &messages &off frequency %out_cov%.pat %out_cov%_freq.tab %out_cov%_case_item %freq_item% END %summary_item% END &messages &on &type &type Points Frequency Calculated &pause &seconds 2
This section follows the same procedure as the Intersect with the user confirming the start of the Frequency command with similar procedure messages appearing. The frequency output file name is the Intersect Coverage name with ‘_freq.tab’ added to creating a unique file. A case item is created in both files for the Joinitem procedure and because it cannot already exist in the <in_info_file> I named it after the Intersect Coverage, with ‘_case_item’ added. Performing a Frequency command requires a ‘Frequency Item’ and a ‘Summary Item’ which are defined before entering Frequency.
3.7 Using Joinitem to Add Frequency to the Polygon Attribute Table
Joinitem is used to add frequency to the Attribute Table of the Polygon Coverage, after an item name for its value is confirmed.
3.7.1 Labelling Frequency
&type &type This program uses Joinitem to insert the calculated frequency ~ ~ into attribute table of Polygon Coverage %poly_name%. &type A name is required for this item in the attribute table. &sv freq_name = frequency
Before inserting the frequency value into the Polygon Coverage Attribute Table its item name needs confirming. Frequency itself would be the most convenient name to use therefore variable ‘freq_name’ is set to that value.
&if [iteminfo %poly% -polygon %freq_name% -exists] &then &do &type &type You cannot use item name Frequency as this already exists ~ ~ in the attribute table for %poly_name%. &pause &seconds 3 &label item_name &messages &popup &sv freq_name [response 'Please enter a new Item Name'] &messages &on &type
But an item with the name frequency may already exist in the Attribute Table and a check is made to this effect. If it does exist the user is informed that frequency cannot be named and a request is made for a new name.
&if %freq_name% = ' ' &then &do &messages &popup &pause YOU MUST ENTER A NAME. &messages &on &goto item_name &end &if [iteminfo %poly% -polygon %freq_name% -exists] &then &do &messages &popup &pause Item name %freq_name% is not acceptable as it already ~ ~ exists in the Attribute Table. &messages &on &goto item_name &end
Checks exist to ensure that the user enters a name and that this name does not already exist in the Attribute Table. If necessary a program loop return them to the name request label (item_name).
&else &do &type Item Name %freq_name% is acceptable. &pause &seconds 2 &goto freq_name &end &end &type &type The default item name is Frequency. &pause &seconds 2 &label freq_name &type &messages &popup &sv pat_item = [query 'Please confirm the use of this Item Name'] &messages &on &if %pat_item% = .FALSE. &then &goto item_name
When an acceptable item name is entered or the use of Frequency as the name is suggested the user most confirm the use of that name, otherwise the user is returned to the naming process. This method allows the user to alter the item name from frequency even if its use is agreeable.
3.7.2 Changing Frequency Item in INFO if Required
&if %freq_name% = frequency &then &goto joinitem &type &type Now changing Item Name Frequency to %freq_name% ..... &data ARC INFO > /dev/null ARC SELECT [UPCASE %out_cov%]_FREQ.TAB ALTER FREQUENCY [UPCASE %freq_name%] ~ ~ ~ ~ ~ ~ Q STOP &end &type &type Frequency Item Name changed to %freq_name%. &pause &seconds 2
If the user entered an item name, the item frequency in the Frequency Table requires altering to this new name. The ALTER command in INFO can change any item characteristic in an existing data file, including Item Name. Creating a data file through the &data directive ensures the INFO commands are performed. The user is informed when this procedure is required and of its completion.
3.7.3 Using Joinitem to Merge INFO files
&label joinitem &type &type Joinitem will attach Frequency file %out_cov%_freq.tab to the ~ ~ attribute table of Polygon Coverage %poly_name%. &pause &seconds 3 &messages &popup &pause Click on OK to perform Joinitem &messages &on
&type joinitem %poly_name%.pat %out_cov%_freq.tab %poly_name%.pat ~ ~ %poly_name%# %poly_name%# # &type
Joinitem merges the polygon coverage Attribute Table and the Frequency Table based upon a shared item created during the Frequency procedure. Again the user is asked to confirm this operation.
&type Unnecessary joined Items will be dropped from the attribute ~ ~ table of polygon coverage %poly_name%. &type dropitem %poly_name%.pat %poly_name%.pat %out_cov%_case_item dropitem %poly_name%.pat %poly_name%.pat %out_cov%-id &type
The Joinitem merges a number of items from the Frequency Table that are not required in the Polygon Attribute table and the Dropitem command allows their deletion.
3.8 Viewing Frequency Results & Additional Options
With the Points Frequency now contained in the Attribute Table the user has an opportunity to peruse it, and to delete the Intersect Coverage and Frequency Table if required.
3.8.1 Listing the Attribute Table
&pause &seconds 1 &messages &popup &sv list = [query 'Do you want to list the Attribute Table ~ ~ containing Frequency'] &messages &on
&if %list% = .TRUE. &then &do &type list %poly_name%.pat &end &type &goto exit
The user is presented with an option to view the updated Attribute Table.
3.8.2 Deleting Unwanted Coverage’s & Files
&label exit &type &type You have created the following: &type Intersect Coverage : %out_cov% &type Frequency File : %out_cov%_freq.tab &type &pause &seconds 2 &messages &popup &sv delete_inter = [query 'Do you want to Delete the Intersect ~ ~ Coverage'] &messages &on
&if %delete_inter% = .TRUE. &then &do &type Deleting Intersect Coverage %out_cov% ..... &type &messages &off kill %out_cov% &messages &on &type Intersect Coverage %out_cov% has been deleted &pause &seconds 2 &end &messages &popup &sv delete_freq = [query 'Do you want to Delete the Frequency File'] &messages &on
&if %delete_freq% = .TRUE. &then &do &type Deleting Frequency File %out_cov%_freq.tab ..... &type &data ARC INFO > /dev/null ARC SELECT [UPCASE %out_cov%]_FREQ.TAB DELETE [UPCASE %out_cov%]_FREQ.TAB Y Q STOP &end &type &type Frequency file %out_cov%_freq.tab has been deleted. &end
The names of the Coverage and Table produced by the program are shown to the user who has an opportunity to delete them. The Intersect Coverage is deleted with the Kill command whist the Frequency Table is removed from with inside INFO. The AML creates another data file with the &data directive to perform this operation.
3.8.3 Exiting
&label end &messages &on &type &return
This label exits the AML, returning command to the Arc prompt whilst ensuring that the program prompt display is returned to normal.
3.9 Error Routine
&routine exit &severity &error &ignore &messages &on &return &error An error has occurred.
The &severity directive used at the start ensures that in the event of an error this routine is run. It instructs the AML to ignore the error and informs the user that an error has occurred. Command is then returned to the Arc prompt.
Return to Top of DocumentWhilst designing and testing stage this AML I encountered a number of problems. My flowchart ensured that the moved through each process but I had difficulty getting the AML to perform several actions. Using the getcover selection method stores the complete pathname to the coverage, which prevented later commands operating. Therefore I needed to create a new variable solely containing the coverage name with the entryname function. I encountered a problem using the INFO commands and until I found the &data directive which ensures INFO commands are performed, the AML kept stalling at the INFO user name prompt. The AML includes a number of name validation checks and these are important as I encountered problems attempted to create files or items that already existed. For this reason the user is also presented with a number of delete options at the end. So that the AML does not just bail out if any unforeseen problems are encountered I included an error routine (Section 3.9).
Return to Top of DocumentThe command to run this AML is &run pip.aml, and it will start from within any of my Workspaces. This is possible due to the insertion of lines &arcpath $HOME/aml and &menupath $HOME/menu in my .arc file and storing the AML in a directory called aml & the Menu in one called menu.
- Arc/Info HyperHelp System
- AML User’s Guide (1993) Environmental Systems Research Institute, Inc.
- Understanding GIS The ARC/INFO Method (1997) Environmental Systems Research Institute, Inc.
Return to Top of Document or my GIS Page
Last Updated 08-03-99