Tcl Commands Implemented
The general philosophy is that of dealing with the Shapefile files
(the data file .shp, the index file .shx, and the attribute file .dbf)
as a single entity that is called below a set of files. There are Tcl
commands for creating a new set and for opening (for reading) an
existing one, as well for closing a set that was created or opened.
Each set has a type and dimension associated to it. The basic types
are waypoint, route and track, that correspond to the Shapefile point
and polylines or polygons shapes. When reading from a
Shapefile polyline not of type ARCM the distinction
between routes and tracks is made if its attribute field names are the
same as those written by gpsmanshp. The type UNKNOWN is
used if this distinction cannot be made and also when reading
from a Shapefile ARCM or polygon. Shapefiles of type ARCM and POLYGONM
are dealt with as being UNKNOWN with dimension 2.
Input/output of polylines and input of polygons is
made by first getting/creating an internal description and then
reading/writing each point at a time. There can be no more than one
route and one track being created at the same time, and no more than 
one polyline or polygon being read from each set.
GSHPCloseFiles ID
- closes a set of files identified by the integer ID
    returned by the procedures that create new files (GSHPCreateFiles) or open existing files for reading (GSHPOpenInputFiles)
  
- returns 0 if ID is not a valid identifier; otherwise 1
GSHPCreateFiles BASEPATH TYPE DIM
- creates a new set of SHP files (.shp, .shx, .dbf) for writing
  
- TYPE is one of WP, RT or TR that are
    mapped into Shape types with the measure field set to 0 and fields
    in .dbf file as follows
    - WP (waypoint)
      - name, string up to 50 characters
      
- commt, comment, string up to 128 characters
      
- date, string up to 25 characters
      
 
- RT (route, a sequence of waypoints)
      - id, identifier, string up to 50 characters
      
- commt, comment, string up to 128 characters
      
 
- TR (track, a sequence of track points)
      - name, string up to 50 characters
      
- commt, comment, string up to 128 characters
      
 
 
- DIM is either 2 or 3 for plane or spatial coordinates
  
- returns a positive integer that identifies uniquely this
    set (until the files are closed), or 0 on error opening the files,
    -1 if TYPE is invalid, -2 if DIM is invalid, -3 if
    could not create .dbf fields, -4 if out of memory
GSHPWriteWP ID X Y ?Z? NAME COMMENT DATE
- writes waypoint to ID file set; the Z coordinate
    should be given only if the dimension for the file set was
    declared to be 3
  
- returns 1 on sucess, -1 if ID is invalid, -2 if type of
    ID set is not waypoint or the dimension is wrong, -3 if out
    of memory, -4 if failed to write .dbf field
GSHPCreateRT DIM RTID COMMENT
- starts creating a representation of a route; only one such
    representation can be handled at a time
  
- DIM is either 2 or 3 for plane or spatial coordinates
  
- returns 1 on success, 0 if there is already a route
    representation, -1 if DIM is invalid
GSHPForgetRT
- destroys current route representation
  
- returns 1 on success, 0 if there is no route representation
GSHPAddWPToRT X Y ?Z?
- adds waypoint to current route representation
  
- the Z coordinate can only be given if the route dimension
    is 3
  
- waypoints can be added after the current route has been
    written by GSHPWriteRT, but no files will be changed by this
  
- returns 1 on sucess, -1 if there is no route representation or
    the route dimension is not compatible with number of arguments, -2
    if out of memory
GSHPWriteRT ID FORGET
- writes current route representation to ID file set; if the
    integer FORGET is different from 0 forget the route representation
    after writing it
  
- returns 1 on sucess, -1 if there is no route representation,
    -2 if there are no waypoints, -3 if ID is invalid, -4 if
    type of ID set is not route or the dimension is different,
    -5 if out of memory, -6 if failed to write .dbf field
GSHPCreateTR DIM NAME COMMENT  ?SEGSTARTERS?
- starts creating a representation of a track; only one such
    representation can be handled at a time
  
- DIM is either 2 or 3 for plane or spatial coordinates
  
-  SEGSTARTERS is the list of indices (from 0) of
    points that start new segments (or parts); the list cannot contain
    0 and should be sorted in strictly increasing order
  
- returns 1 on success, 0 if there is already a track
    representation, -1 if DIM is invalid, -2 if out of
    memory, -3 if SEGSTARTERS is invalid
GSHPForgetTR
- destroys current track representation
  
- returns 1 on success, -1 if there is no track representation
GSHPAddTPToTR X Y ?Z?
- adds track point to current track representation
  
- the Z coordinate can only be given if the track dimension
    is 3
  
- track points can be added after the current track has been
    written by GSHPWriteTR, but no files will be changed by this
  
- returns 1 on sucess, -1 if there is no track representation or
    it has a dimension incompatible with the number of arguments, -2
    if out of memory
GSHPWriteTR ID FORGET
- writes current track representation to ID file set; if
    the integer FORGET is different from 0 forgets the track
    representation after writing it
  
- returns 1 on sucess, -1 if there is no track representation,
    -2 if there are no track points, -3 if ID is invalid, -4 if
    type of ID set is not track or the track has a different
    dimension, -5 if out of memory, -6 if failed to write .dbf
    field, -7 if index of last segment (part) starting point
    exceeds the track length
GSHPOpenInputFiles BASEPATH
- opens for input a set of SHP files (.shp, .shx, .dbf)
  
 the type of objects in the file is determined by the
    type of SHP file and also by whether the fields in the .dbf file
    are the same as those written by the output commands above; if the
    fields are different in number or name, their names are returned
    by GSHPInfoFrom and their values by GSHPGetObj the type of objects in the file is determined by the
    type of SHP file and also by whether the fields in the .dbf file
    are the same as those written by the output commands above; if the
    fields are different in number or name, their names are returned
    by GSHPInfoFrom and their values by GSHPGetObj  
- returns a positive integer that identifies uniquely this
    set (until the files are closed), or 0 on error opening the .shp
    or .shx files, -1 if files are empty, -2 if files type is invalid,
    -3 if out of memory
GSHPInfoFrom ID
- returns information on the contents of the ID input file
    set; the normal result is a list with
    - the type of objects in the file set: one of WP, RT, TR, or UNKNOWN; the latter is used:
        - for a polyline of type ARCM
        
- for a polyline that can be taken either as a route or a
          track because there is no available information from the .dbf
          file
        
- when reading a polygon
        
 
- the number of objects in the file (always positive); this
        is needed because objects will be indexed (by GSHPGetObj)
        from 0 to this number less 1
      
- the dimension (2 or 3) of the objects
      
- if the type is RT, TR, or UNKNOWN, the
        index of the next point to be read; the initial value is -1
        when no object is being read or after all points of an object
        have already been read; the index is set to 0 by a call to
        GSHPGetObj, increased by GSHPReadNextPoint after a
        successful call, and set by this procedure to -1 when there
        are no more points
      
 the number of .dbf fields and a list with each
        field name followed by its precision (0 for integers or
        non-numeric fields), if the type is WP and the .dbf
        fields differ from those written by gpsmanshp, or the
        type is UNKNOWN the number of .dbf fields and a list with each
        field name followed by its precision (0 for integers or
        non-numeric fields), if the type is WP and the .dbf
        fields differ from those written by gpsmanshp, or the
        type is UNKNOWN  
 
- possible error result: 0 no such input file set
GSHPGetObj ID INDEX
- reads an object from the ID input file set; INDEX
    is a number from 0 to the number of objects less one; the normal
    result is, depending on the type,
    - WP: a list with name, comment, date, x- and
        y-coordinates, and z-coordinate if dimension is 3; the first
        three can be empty strings if no information is available,
         in which case the list ends with a list of the .dbf field
        values in which case the list ends with a list of the .dbf field
        values ; numeric values of less than -1035 should
        be considered as undefined ; numeric values of less than -1035 should
        be considered as undefined
- RT: a list with identifier, comment, number of
        waypoints; the first two can be empty strings if no information is
        available; the waypoints should be read by GSHPReadNextPoint
      
- TR: a list with name, comment, number of track
        points, and, possibly, the list of indices (from 0, but
        never containing 0) of points starting parts
        (segments); the first two can be empty strings if no
        information is available; the track points should be read by
        GSHPReadNextPoint
      
- UNKNOWN:  either the number of points, or a
        list with the number of points, the list of indices (from
        0, but never containing 0) of points starting parts
        (segments)  and a list with the .dbf field
        values and a list with the .dbf field
        values ; the points should be read by GSHPReadNextPoint ; the points should be read by GSHPReadNextPoint
 
- the result is an empty list if the object is null (these
    objects may appear in Shapefile files and should be skipped)
  
- possible error results (note that the number of points
    returned when the type is UNKNOWN may be 0): -1 no such
    input file set, -2 if INDEX is invalid, -3 if out of memory
    (only if type is TR or UNKNOWN)
GSHPReadNextPoint ID
- reads the next point from a route or track input file set
    with number ID; this can only be used after a call to GSHPGetObj returning a RT, TR or UNKNOWN type,
    and before a call of GSHPReadNextPoint for this set that gave a
    "no more points" result
  
- the normal result is a list with 2 or 3 coordinates depending
    on the dimension; numeric values of less than -1035 should be
    considered as undefined
  
- possible error results: 0 no such input file set, -1 if no
    route or track is currently being processed (no previous call to GSHPReadNextPoint with a suitable type result, or all points have
    already been read), -2 if there are no more points (after which a -1
    result will be given)
GPSManSHP WWW pages
©Miguel
    Filgueiras,
    mig_at_ncc.up.pt, DCC-FC & LIACC,
  Universidade do Porto, 2004