Faking Cursors

Cursor processing allows the analysis of a selected set of objects, one record at a time. This is particularly useful for querying and/or setting attributes on a case-by-case basis. The following routine may be used in TABLES, ARCEDITW, or ARCPLOTW.

&r CURSOR DECLARE [cursor] {coverage / table} {feature_class}
&r CURSOR [cursor] FIRST / NEXT / PREVIOUS / LAST / n
&r CURSOR [cursor] MAKECURRENT
&r CURSOR [cursor] RELATE [to_table] [relate_item] {LINEAR / ORDERED / TABLE / LINK}
&r CURSOR [cursor] RELATE OFF
&r CURSOR [cursor] REMOVE {RESTORESEL}
&r CURSOR CLEAR

maintains one or more cursors, each pointing to a single element in a selection set.

arguments

[cursor] - the cursor identifier. May be up to 8 characters.

{coverage / table} - the coverage or table containing the selected features. Required in ARCPLOTW and TABLES.

{feature_class} - the coverage feature class (ARC, POINT, or POLY). Required in ARCPLOTW.

[FIRST / NEXT / PREVIOUS / LAST / n] - repositions [cursor] to the first, next, previous, last, or nth element in the selection set. The element at the new position of [cursor] becomes the current selection set.

[MAKECURRENT] - makes the element at the current position of [cursor] the current selection set (TABLES and ARCEDITW) and/or re-establishes the JOIN environment for that cursor.

[RELATE] - establishes a JOIN environment for a particular cursor.

[to_table] - the database file to be linked to [cursor].

[relate_item] - the common item by which [cursor] will be linked to [to_table].

{LINEAR / ORDERED / TABLE / LINK} - relate method (see JOIN in the PC ARC/INFO command reference for further information).

[RELATE OFF] - removes the JOIN environment from [cursor].

[REMOVE] - removes [cursor]. Any active JOIN is turned off.

{RESTORESEL} - if specified, the selection set represented by the cursor is restored. This is the default only in ARCPLOTW.

[CLEAR] - clears the cursor stack.

notes

In TABLES, cursors may represent selection sets of tabular records. In ARCEDITW, cursors may represent selection sets of arcs or labels. In ARCPLOTW, cursors may represent selection sets of arcs, points, or polygons. Cursor features must have attributes.
In TABLES and ARCEDITW, the currently selected records are automatically assigned to a cursor when it is declared. In ARCPLOTW, the {coverage} and {feature_class} must be specified. In TABLES, the current {table} must be identified.
Internal record numbers are utilized in TABLES and ARCPLOTW to identify elements in a selection set. Thus if records are sorted, added, or deleted in TABLES, any open cursors referring to that table will be invalidated and attempts to use them will lead to undesirable results. Because internal record numbers are dynamic in ARCEDITW, User-IDs are utilized as record identifiers. Thus User-IDs should be unique for the edit coverage or else more than one element may be selected by a cursor.
Cursors in ARCEDITW must refer to open edit coverages. If a cursor is addressed which refers to a coverage that is no longer open, it will automatically be removed.
CURSOR'S CLEAR option should be executed prior to exiting a module. Otherwise, if the module is immediately reopened, any unremoved cursors will still be present.

discussion

CURSOR is used to reselect a particular element in a selection set. Once that element is selected, it may be queried or modified using other commands (CALCULATE, MOVEITEM, etc.).

CURSOR is most useful as a routine for other applications. When called by an SML, CURSOR will return a status value (to be read using the &rv directive), equal to the current cursor position. If the return value is 0, an error has occured. If the return value is -1, an attempt was made to move beyond the end of the selection set. If the return value is -2, an attempt was made to move before the beginning of the selection set. If the return value is -3, the cursor was successfully removed and/or the cursor stack cleared.

Two stacks are maintained by CURSOR. One, starting at SML variable 999 and pushing downward, contains cursor environment data. The other, starting at SML variable 1001 and pushing upward, contains record identifiers. Variable 1000 stores the name of the current module. New cursors are pushed onto the top of each stack. Any cursor, however, may be removed at any time, after which the stacks are collapsed if necessary.

The structure of a cursor environment entry is 3 lines. The first line contains five tokens defining declaration and position information:

   CURSOR VEGPOLY POLYGON 45 1

In the above example, cursor VEGPOLY is declared as a polygon, the selection set contains 45 records, and the cursor is positioned at the first record. The second line contains the source coverage or table:

   C:\0HOME\TEST\VEG

The third line is blank unless a relate environment is set:

   C:\0HOME\TEST\VEG.LANDFORM MUNTNUMB ORDERED

In ARCPLOTW, WIN SEL is used to save a cursor's selection set to a file named [cursor].SEL in the WKSP directory. This file is used to restore the selection set when the cursor is removed. In ARCEDITW or TABLES, selection sets are restored one element at a time from the record list, a process which may be lengthy for large numbers of records.

Currently, the routine places no ceiling on the number of cursors and/or records which may be declared. SML limitations restrict the effective size of the record stack to 8998 records (variables 1002-9999). If necessary, limitations may be added to the source code to prevent collision with other applications.

To download the install pack, click HERE. Unzip in a temporary directory and execute CURSOR.BAT.

NOTE: The routines assume that ARCEDITW and ARCPLOTW are invoked by their proper names or by AE and AP, respectively (see Customizing PC ARC/INFO 3.5.X).

EXAMPLE ONE: Generating Boundary Attributes

Polygon coverage VEG has four vegetation types:

TYPE TYPE_TXT

1    Conifer
2    Pinyon-Juniper
3    Sagebrush
4    Grassland

Arcs comprising vegetation boundaries are to be classified as follows (lookup table LUT.VEGB):

TYPE TYPE_TXT

0    Edge of Project Area
1    Conifer/PJ
2    Conifer/Sagebrush
3    Conifer/Grassland
4    PJ/Sagebrush
5    PJ/Grassland
6    Sagebrush/Grassland

First, TYPE and TYPE_TXT are added to VEG.AAT:

ADDITEM VEG.AAT VEG.AAT TYPE 1 1 I
ADDITEM VEG.AAT VEG.AAT TYPE_TXT 20 20 C

The following routine will calculate the attributes in TABLES:

&routine calcb

&define resp -11 &var
SEL VEG.AAT
&rem **** add temporary items
&sv [resp]
ADDITEM
T_TMP_
11
I
[resp]
T_TMP_LT
1
I
[resp]
T_TMP_RT
1
I
[resp]
[resp]
&rem **** populate temporary items
CALC T_TMP_ = VEG_
CALC VEG_ = LPOLY_
JOIN VEG.PAT VEG_
CALC T_TMP_LT = #TYPE
CALC VEG_ = RPOLY_
CALC T_TMP_RT = #TYPE
JOIN OFF
&rem **** declare cursor
&r cursor DECLARE VEG VEG.AAT
&rv [resp]
&rem **** relate cursor to lookup table
&r cursor VEG RELATE LUT.VEGB TYPE ORDERED
&rv [resp]
&rem **** set up cursor loop
&while &ne [resp] -1 &do
   CALC -1 = T_TMP_LT * T_TMP_RT
   &if &eq %-1 2 &do
      CALC TYPE = 1
   &elseif &eq %-1 3 &do
      CALC TYPE = 2
   &elseif &eq %-1 4 &do
      CALC TYPE = 3
   &elseif &eq %-1 6 &do
      CALC TYPE = 4
   &elseif &eq %-1 8 &do
      CALC TYPE = 5
   &elseif &eq %-1 12 &do
      CALC TYPE = 6
   &else
      CALC TYPE = 0
   &end
   MOVE #TYPE_TXT TO TYPE_TXT
   &r CURSOR VEG NEXT
   &rv [resp]
&end
&rem **** remove cursor
&r CURSOR VEG REMOVE
&rv [resp]
&rem **** restore internal ID
ASEL
CALC VEG_ = T_TMP_
&rem **** drop temporary items
DROPITEM T_TMP_
Y
DROPITEM T_TMP_LT
Y
DROPITEM T_TMP_RT
Y
&return

See Sample Data to compare results.

EXAMPLE TWO: Repositioning Points

The lead agency insists that the monitoring stations (see Faking Dynamic Segmentation) be offset from the roads by 200 meters in random directions. First, the item DIRECTION is added to the event table STATIONS:

ADDITEM STATIONS STATIONS DIRECTION 3 3 I

In this example, 0 degrees is north, 90 degrees is east, 180 degrees is south, and 270 degrees is west. The following SML is executed in TABLES to generate the random directions:

SEL STATIONS
&r cursor declare item stations
&rv -1
&cv -2 1 RAN
&label while
   &cv -2 360 * ( 0 RAN )
   CALC DIRECTION = %-2
   &r cursor item next
   &rv -1
   &goback while &if &ne %-1 -1
&label end
&r cursor item remove
&return

For example:

STATION_ID DIRECTION
307-01     202
307-02      52
307-03     258
307-04      31
307-05     225
307-06      64
307-07     146
307-08     273
307-09      16
310-01     179
310-02      92
310-03     140
310-04      93
310-05      36
310-06      35
310-07      33
311-01     312

Coverage STATIONS is copied to STATION2, and the following SML is executed in ARCEDIT to reposition the points:

EDITC STATION2
EDITF LABEL
SHOW COORDINATE -18
COO KEY
SEL ALL
&r cursor declare item
&r cursor item relate stations station_id ordered
&rv -19
&label while
   &cv -1 200
   CALC -2 = #DIRECTION
   &cv -3 %-1 * ( ( 90 - %-2 ) cos )
   &cv -4 %-1 * ( ( 90 - %-2 ) sin )
   MOVE
   1 0 0
   1 %-3 %-4
   &r cursor item next
   &rv -19
   &goback while &if &ne %-19 -1
&label end
&r cursor item remove
UNSEL ALL
COO %-18
&return

In the above figure, boxes represent the original station positions and crosses the new positions.

One final note: a Pentium-based PC really helps speed things up!

Return to ArcTips page