GRASS 4.2 Sites Structure and API Prototypes

Record Structure and Definitions

Function Prototypes

Prompting for Site List Files

The following routines interactively prompt the user for a site list file name. In each, the prompt string will be printed as the first line of the full prompt which asks the user to enter a site list file name. If prompt is the empty string "" then an appropriate prompt will be substituted. The name that the user enters is copied into the name buffer. (The size of name should be large enough to hold any GRASS file name. Most systems allow file names to be quite long. It is recommended that name be declared char name[50].) These routines have a built-in "list" capability which allows the user to get a list of existing site list files.

The user is required to enter a valid site list file name, or else hit the RETURN key to cancel the request. If the user enters an invalid response, a message is printed, and the user is prompted again. If the user cancels the request, the NULL pointer is returned. Otherwise the mapset where the site list file lives or is to be created is returned. Both the name and the mapset are used in other routines to refer to the site list file. 

char * G_ask_sites_old (prompt, name)
  char *prompt, *name;
Asks user to input name of an existing site list file in any mapset in the database. 
char * G_ask_sites_in_mapset (prompt, name)
  char *prompt, *name;
Asks user to input name of an existing site list file in the current mapset. 
char * G_ask_sites_new (prompt, name)
  char *prompt, *name;
Asks user to input name for a site list file which does not exist in the current mapset.

Here is an example of how to use these routines. Note that the programmer must handle the NULL return properly. 

  char *mapset;
  char name[50];

  mapset = G_ask_sites_old("Enter site list file to be processed", name);
  if (mapset == NULL)
       exit(0);

Opening Site List Files

The following routines open site list files: 

FILE *G_sites_open_new (name)
  char *name;
Creates an empty site list file name in the current mapset and opens it for writing.
Returns an open file descriptor is successful. Otherwise, returns NULL. 
FILE *G_sites_open_old (name, mapset)
  char *name, *mapset;
Opens the site list file name in mapset for reading.
Returns an open file descriptor is successful. Otherwise, returns NULL.

Site Memory Management

Sites routines require the use of a Site structure. Routines to allocate and deallocate memory are provided, as well as a routine which describes the format of a site list, helpful in determining the amount of memory to be allocated. 
Site *G_site_new_struct (c, n, s, d)
  RASTER_MAP_TYPE c;
  int n, s, d;
Allocates and returns pointer to memory for a Site structure for storing n dimensions (including easting and northing; must be > 1), an optional category c, s string attributes, and d decimal attributes. The category c can be CELL_TYPE, FCELL_TYPE, DCELL_TYPE (as defined in gis.h), or -1 (indicating no category attribute). Returns a pointer to a Site structure or NULL on error. 
int G_site_describe (fd, n, c, s, d)
  FILE *fd;
  RASTER_MAP_TYPE c;
  int *n, *s, *d;
Guesses the format of a sites list (the dimensionality, the presence and type of a category, and the number of string and decimal attributes) by reading the first record in the file. The type of category will be CELL_TYPE, FCELL_TYPE (as defined in gis.h), or -1 (indicating no category attribute). Reads fd, rewinds it, and returns:
0
on success,
-1
on EOF, and
-2
for any other error. 
void G_site_free_struct (site)
  Site *site;
Free memory for a site struct previously allocated using G_site_new_struct.

Here is an example of how to use these routines. 

  int dims,cat,strs,dbls;
  FILE *fp;
  Site *mysite;

  /* G_site_describe should be called immediately after the
   * file is opened or at least before any seeks are done
   * on the file.
   */
  if (G_site_describe (fp, &dims, &cat, &strs, &dbls)!=0)
    G_fatal_error("failed to guess format");
  /* 
   * Allocate enough memory, according to the output 
   * of G_site_describe() 
   */
  mysite = G_site_new_struct (cat, dims, strs, dbls);

  G_site_free_struct (mysite);

Reading and Writing Site List Files

int G_site_get (fd, s)
  FILE *fd;
  Site *s;
Reads one site record from fd and returns:
0
on success
-1
on EOF
-2
on fatal error or insufficient data
1
on format mismatch (extra data) 
int G_site_put (fd, s)
  FILE *fd;
  Site s;
Writes a site to file pointed to by fd. 
char * G_site_format (s, fs, id)
  Site *s;
  char *fs;
  int id;
Returns a string containing a formatted site record, with all fields separated by fs. If fs is NULL, a space character is used. If id is non-zero, attribute identifiers (#, %, and @) are included. 
int G_site_get_head (fd, head)
  FILE *fd;
  Site_head *head;
Reads the header from fd and stores it in head. If a type of header record is not present in fd, the corresponding element of head is returned as NULL. 
int G_site_put_head (fd, head)
  FILE *fd;
  Site_head head;
Writes header information stored in head to fd. Only non-NULL fields of head struct are written. 
int G_site_in_region (site, region)
  Site *site;
  struct Cell_head *region;
Returns 1 if site is contained within region, 0 otherwise. 
int G_site_c_cmp (a, b)  /* compare category attributes */
  void *a, *b;
int G_site_d_cmp (a, b)  /* compare first decimal attributes */
  void *a, *b;
int G_site_s_cmp (a, b)  /* compare first string attributes */
  void *a, *b;
Comparison functions for sorting an array of Site records using qsort. See examples.
Darrell McCauley and Bill Brown
Last modified on