English

How To: CURSORS: Creating cursor loops with AML

Procedure

Question

How to create a cursor loop to step through a selected set of records in an INFO file?

Answer

This can be done using the following steps:

1. Declare the cursor
-----------------------
In Arc and ArcPlot, give the cursor a name and a file to operate on. This is accomplished automatically in ArcEdit using the command EDIT or EDIFEATURE.

2. Select data
---------------
Use the selection commands in ArcPlot and ArcEdit (e.g. RESELECT, ASELECT, SELECT, etc.). In Arc, issue the selection statement when declaring the cursor.

3. Open the cursor
-------------------
A newly opened cursor points to the first record of the selected set and sets a number of AML program variables. These variables fall into two categories: cursor variables and cursor descriptors. Cursor variables contain the data stored in the items of the selected record. Cursor descriptors store data about the file.

4. Start the loop
------------------
Use the cursor descriptor AML$NEXT to set up the loop. AML$NEXT is a keyword, and the variable reference syntax is:

:<cursor>.AML$NEXT

This variable is set to ".FALSE." if attempting to move the cursor past the end of the selected set of records or related records. The variable is set to ".TRUE." if the next record is successfully retrieved. Use &DO &WHILE to control access to the table. As long as the cursor is pointing to data, the loop continues.

5. Query and manipulate data
-----------------------------
Use the CURSOR NEXT command to step through the selected set on a record-by-record basis. The CURSOR ... RELATE ... NEXT can be used to access related records. While accessing the records in the selected set, use cursor variables ( :<cursor>.<item_name> ) to report or update the data in each record.

6. Close the cursor
--------------------
The cursor must be closed before changing the selected set. Close the cursor, change the selected set, and then reopen it for processing.

7. Remove the cursor
---------------------
When finished using the cursor in Arc or ArcPlot, remove it from the session to free up system resources. Removing a cursor also closes it if the cursor had not been closed previously.

EXAMPLES

These three examples show how the same task is performed in Arc, ArcEdit, and ArcPlot. Suppose the INFO table landuse.pat has two items, lu-code and cost_ha, representing landuse code and cost per hectare, respectively. Industrial areas, represented by a landuse code of 200, have the cost per hectare changed from 15000 to 30000. The landuse.pat needs to be updated to reflect these changes. In every case where lu-code = 200, cost_ha needs to be changed from 15000 to 30000. In order to update landuse.pat using cursors, perform the following:

In ARC:
=======
Arc: cursor
Usage: CURSOR <cursor> DECLARE <cover> <feature_class> {RO | RW} {logical_expression}
Usage: CURSOR <cursor> DECLARE <info_file> INFO {RO | RW} {logical_expression}
Usage: CURSOR <cursor> <OPEN | CLOSE | INSERT | DELETE | REMOVE>
Usage: CURSOR <cursor> <NEXT | FIRST | record_number>
Usage: CURSOR <cursor> RELATE <relate> <NEXT | FIRST | INSERT | DELETE>

CURSOR cur1 DECLARE landuse poly rw cost_ha = 15000
CURSOR cur1 OPEN
&DO &WHILE %:cur1.AML$NEXT%
&if %:cur1.lu-code% = 200 &then
&sv :cur1.cost_ha = 30000
CURSOR cur1 NEXT
&END
CURSOR cur1 CLOSE
CURSOR cur1 REMOVE
&RETURN

In ARCPLOT:
===========
Arcplot: usage cursor
Usage: CURSOR <cursor> DECLARE <cover> <feature_class> {RO | RW}
Usage: CURSOR <cursor> DECLARE <info_file> INFO {RO | RW}
Usage: CURSOR <cursor> <OPEN | CLOSE | INSERT | DELETE | REMOVE>
Usage: CURSOR <cursor> <NEXT | FIRST | record_number>
Usage: CURSOR <cursor> RELATE <relate> {NEXT | FIRST | INSERT | DELETE}
Arcplot:

CURSOR cur1 DECLARE landuse poly rw
CURSOR cur1 OPEN
&DO &WHILE %:cur1.AML$NEXT%
&IF %:cur1.lu-code% = 200 &THEN
&SV :cur1.cost_ha = 30000
CURSOR cur1 NEXT
&END
CURSOR cur1 CLOSE
CURSOR cur1 REMOVE

In ARCEDIT:
===========

Arcedit: usage cursor
Usage: CURSOR <OPEN | CLOSE | NEXT | FIRST | record_number>
Usage: CURSOR RELATE <relate> {NEXT | FIRST | INSERT | DELETE}
Arcedit:

SEL ALL
CURSOR OPEN
&DO &WHILE %:edit.AML$NEXT%
&IF %:edit.lu-code% = 200 &THEN
&SV :cur1.cost_ha = 30000
CURSOR NEXT
&END
CURSOR CLOSE