sites.format(1) 	      Grass User's Manual	       sites.format(1)



GRASS  5.0  Site  Record  Format  Specification  (DRAFT!)   Site files contain
records describing punctual information.  Records are limited  to  files  con-
taining  only  characters  from the US-ASCII character set.  Records are sepa-
rated by a newline character (ASCII 0x0a). There are three types  of  records:
comment  records, header records, and data records.  The formats of each these
types of records are described in the following sections.

SSiittee DDaattaa RReeccoorrdd DDeessccrriippttiioonn
       A site record in the GRASS Sites Format is divided into two parts, each
       with a different field separator. Part 1 contains location in 2 or more
       dimensions and part 2 optionally  contains  attribute  information  for
       this  location.	Both types of fields (and thus site records) are vari-
       able length.

   PPaarrtt 11 ooff aa SSiittee RReeccoorrdd:: LLooccaattiioonn
       Part 1 of a site record gives information about	location.   The  field
       separator in part 1 of the site record is a "pipe" (ASCII 0x7c) charac-
       ter.  The last (non-escaped) pipe signifies  the  end  of  part	1  (an
       escaped	character  is  defined as one prefixed by a "backslash" (ASCII
       0x5c)). Any additional fields are considered attribute information.


       Each field in part 1 indicates a coordinate in some space.  There  must
       be  at  least  two  fields in part 1: the first describing a geographic
       easting and the second describing a geographic northing. These  may  be
       in either decimal or degrees-minutes-second format.


       Additional  fields in part 1 are optional but must be stored in decimal
       format. They should only be used to  represent  coordinate  information
       about  some space (e.g., elevation, time; depending upon how a space is
       defined).

   PPaarrtt 22 ooff aa SSiittee RReeccoorrdd:: AAttttrriibbuutteess
       Part 2 contains attribute information for the location given in part 1.
       The field separator in part 2 of the site record is a "space" character
       (ASCII 0x20), except when the space character is  contained  in	double
       quotes (ASCII 0x22).  The three types of attributes are: category, dec-
       imal, and string. These attributes may be in any order.	Each of  these
       attributes  have  an  associated  identifier  tag  defining the type of
       attribute in a field:  # (ASCII 0x23), % (ASCII	0x25),	and  @	(ASCII
       0x40), for category, decimal, and string, respectively.	No space char-
       acter may immediately follow an identifier  tag.   Category  Attributes
       Categories  are a special kind of attribute. They are used to represent
       vector or raster categories when sites are transformed into these  dif-
       ferent  data  formats.  There may be only one category field per record
       and it must be prefixed with a "pound" or "number" symbol  (#).	 Cate-
       gories must be integers.  Decimal Attributes Decimal attributes include
       both integers and floating-point numbers.  They	are  prefixed  with  a
       "percent"  symbol  (%).	 There	may  be  be zero, one, or more decimal
       attributes in a site record.  String Attributes String  attributes  are
       fields  that  contain possibly non-numeric information and are prefixed
       with the "at" or "each" symbol (@). There may be be zero, one, or  more
       string attributes in a site record. String attributes may contain space
       (ASCII 0x20) characters if the  entire  attribute,  not	including  the
       attribute  tag  (@),  is contained within pairs of "double quotes" (").
       String attributes may also contain double quotes if they are escaped by
       prefixing  a  "backslash"  (.  Default If no identifier tag is prefixed
       (i.e., none of #, %, or @), the type of attribute defaults to string.

HHeeaaddeerr aanndd CCoommmmeenntt RReeccoorrdd FFoorrmmaatt
       In addition to the data record format, the site file may  contain  com-
       ment  lines (records containing a pound symbol, 0x23, in the first col-
       umn) and header lines, both of which are optional.  Header records must
       precede	all  data  records  while  comment  records may occur anywhere
       within a sites data file.


       There are five types of header records: (1) name, (2) description,  (3)
       timestamp, (4) label, and (5) format.

       name   A  name record contains the string "name|" beginning in column 1
	      and optionally specifies the name of the database file.

       description
	      A description record contains the string	"desc|"  beginning  in
	      column  1 and optionally describes the database file (metadata).

       timestamp
	      A timestamp record is special type of metadata that contains the
	      string "time|" beginning in column 1 and optionally gives a time
	      and date associated with the entire sites file.  Valid time data
	      strings  are  described  in  the	documentation for the DateTime
	      library (URL?).

       label  A label record describes what each dimension and attribute field
	      in site data records represent. It contains the string "labels|"
	      beginning in column 1 and  optionally  contains  field  descrip-
	      tions.  No  special  formatting is required since this record is
	      for user convenience only.

       format A format record describes the format of site data  records.   It
	      contains	the string "form|" beginning in column 1 and a special
	      sample data record beginning in column 6.   The  special	sample
	      data record is a site data record (as describe above) containing
	      only field  separators  and  identifier  tags  (i.e.,  all  data
	      removed).

       All  header  records  are  optional.   If present in a sites data file,
       header records must occur in the before any  data  records  in  a  site
       file.  Darrell McCauley Last modified on Friday, 25-Oct-96 15:55:23 CDT

       _L_a_s_t _c_h_a_n_g_e_d_: _$_D_a_t_e_: _2_0_0_2_/_0_1_/_2_5 _0_5_:_4_5_:_3_5 _$



GRASS 5.0						       sites.format(1)
