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  containing	only characters from the US-ASCII
character set.	Records are  separated	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  loca-
       tion.  Both  types  of  fields (and thus site records) are
       variable 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)  character.	 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 informa-
       tion.


       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 rep-
       resent coordinate information about some space (e.g., ele-
       vation, 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, deci-
       mal, 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 character 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 different data formats.  There  may
       be  only one category field per record and it must be pre-
       fixed with a "pound" or "number" symbol	(#).   Categories
       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 con-
       tain 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 iden-
       tifier 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 comment lines (records containing a pound  symbol,
       0x23, in the first column) 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 descriptions. No spe-
	      cial 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 begin-
	      ning in column 6.  The special sample  data  record
	      is  a site data record (as describe above) contain-
	      ing  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 modi-
       fied 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)
