See especially GRASS 6 Vector Architecture for details (extra page).

GRASS Vector File Processing

Authors:
(Written by CERL, with contributions from David D. Gray)

The GIS Library contains some functions related to vector file processing. These include prompting the user for vector files, locating vector files in the database, opening vector files, and a few others.

Note. Most vector file processing, however, is handled by routines in the Vector Library, which is described in Vector_Library.

Prompting for Vector Files

The following routines interactively prompt the user for a vector 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 vector 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. These routines have a built-in 'list' capability which allows the user to get a list of existing vector files.

The user is required to enter a valid vector 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 vector file lives or is to be created is returned. Both the name and the mapset are used in other routines to refer to the vector file.

char *G_ask_vector_old(char *prompt, char *name) prompt for an existing vector file

Asks the user to enter the name of an existing vector file in any mapset in the database.

char *G_ask_vector_in_mapset(char *prompt, char *name) prompt for an existing vector file

Asks the user to enter the name of an existing vector file in the current mapset.

char *G_ask_vector_new(char *prompt, char *name) prompt for a new vector file

Asks the user to enter a name for a vector 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[GNAME_MAX];

mapset = G_ask_vector_old("Enter vector file to be processed", name);

if (mapset == NULL)
   exit(0);

Finding Vector Files

in the Database

Noninteractive modules cannot make use of the interactive prompting routines described above. For example, a command line driven module may require a vector file name as one of the command arguments. GRASS allows the user to specify vector file names (or any other database file) either as a simple unqualified name, such as "roads", or as a fully qualified name, such as "roads in <I>mapset</I>", where mapset is the mapset where the vector file is to be found. Often only the unqualified vector file name is provided on the command line.

The following routines search the database for vector files:

int G_find_vector(char *name, char *mapset) find a vector file

int G_find_vector2(char *name, char *mapset) find a vector file

Look for the vector file name in the database. The mapset parameter can either be the empty string "", which means search all the mapsets in the user's current mapset search path (see Mapset_Search_Path for more details about the search path), or it can be a specific mapset name, which means look for the vector file only in this one mapset (for example, in the current mapset). If found, the mapset where the vector file lives is returned. If not found, the NULL pointer is returned.

The difference between these two routines is that if the user specifies a fully qualified vector file which exists, then G_find_vector2() modifies name by removing the "in <I>mapset</I>" while G_find_vector() does not. Be warned that G_find_vector2() should not be used directly on a command line argument, since modifying argv[ ] may not be valid. The argument should be copied to another character buffer which is then passed to G_find_vector2(). Normally, the GRASS programmer need not worry about qualified vs. unqualified names since all library routines handle both forms. However, if the programmer wants the name to be returned unqualified (for displaying the name to the user, or storing it in a data file, etc.), then G_find_vector2() should be used.

For example, to find a vector file anywhere in the database:

char name[GNAME_MAX];
char *mapset;

if ((mapset = G_find_vector(name,"")) == NULL)
   /* not found */

char name[GNAME_MAX];

if (G_find_vector(name,G_mapset()) == NULL)
   /* not found */

To check that the vector file exists in the current mapset:

Opening an Existing Vector File

The following routine opens the vector file name in mapset for reading.

The vector file name and mapset can be obtained interactively using G_ask_vector_old() or G_ask_vector_in_mapset(), and noninteractively using G_find_vector() or G_find_vector2().

FILE *G_fopen_vector_old(char *name, char *mapset) open an existing vector file

This routine opens the vector file name in mapset for reading. A file descriptor is returned if the open is successful. Otherwise the NULL pointer is returned (no diagnostic message is printed).

The file descriptor can then be used with routines in the Dig Library to read the vector file (See GRASS 6 Vector Architecture).

Note. This routine does not call any routines in the Dig Library; No initialization of the vector file is done by this routine, directly or indirectly.

Creating and Opening

New Vector Files

The following routine creates the new vector file name in the current mapset (GRASS does not allow files to be created outside the current mapset. See Database_Access_Rules) and opens it for writing. The vector file name should be obtained interactively using G_ask_vector_new(). If obtained noninteractively (e.g., from the command line), G_legal_filename() should be called first to make sure that name is a valid GRASS file name.

Warning. If name already exists, it will be erased and re-created empty. The interactive routine G_ask_vector_new() guarantees that name will not exist, but if name is obtained from the command line, name may exist. In this case G_find_vector() could be used to see if name exists.

FILE *G_fopen_vector_new(char *name) open a new vector file

Creates and opens the vector file name for writing.

A file descriptor is returned if the open is successful. Otherwise the NULL pointer is returned (no diagnostic message is printed).

The file descriptor can then be used with routines in the Dig Library to write the vector file (See GRASS 6 Vector Architecture.)

Note. This routine does not call any routines in the Dig Library; No initialization of the vector file is done by this routine, directly or indirectly. Also, only the vector file itself (i.e., the dig file), is created. None of the other vector support files are created, removed, or modified in any way.

Reading and Writing Vector Files

Reading and writing vector files is handled by routines in the Dig Library. See GRASS 6 Vector Architecture for details.

Vector Category File

GRASS vector files have category labels associated with them. The category file is structured so that each category in the vector file can have a one-line description.

The routines described below read and write the vector category file. They use the Categories structure which is described in GIS_Library_Data_Structures.

Note. The vector category file has exactly the same structure as the raster category file. In fact, it exists so that the module v.to.rast can convert a vector file to a raster file that has an up-to-date category file.

The routines described in Querying_and_Changing_the_Categories_Structure which modify the Categories structure can therefore be used to set and change vector categories as well.

int G_read_vector_cats(char *name, name *mapset, struct Categories cats) read vector category file

The category file for vector file name in mapset is read into the cats structure. If there is an error reading the category file, a diagnostic message is printed and -1 is returned. Otherwise, 0 is returned.

int G_write_vector_cats(char *name, struct Categories *cats) write vector category file

Writes the category file for the vector file name in the current mapset from the cats structure.

Returns 1 if successful. Otherwise, -1 is returned (no diagnostic is printed).