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.
\subsection Prompting_for_Vector_Files 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: \verbatim char *mapset; char name[GNAME_MAX]; mapset = G_ask_vector_old("Enter vector file to be processed", name); if (mapset == NULL) exit(0); \endverbatim \subsection Finding_Vector_Files_in_the_Database 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 mapset", 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 mapset" 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: \verbatim char name[GNAME_MAX]; char *mapset; if ((mapset = G_find_vector(name,"")) == NULL) /* not found */ \endverbatim \verbatim char name[GNAME_MAX]; if (G_find_vector(name,G_mapset()) == NULL) /* not found */ \endverbatim To check that the vector file exists in the current mapset: \subsection Opening_an_Existing_Vector_File 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 \ref Vector_Library).
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. \section Creating_and_Opening_New_Vector_Files 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 \ref 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 \ref Vector_Library.)
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. \subsection Reading_and_Writing_Vector_Files Reading and Writing Vector Files Reading and writing vector files is handled by routines in the Dig Library. See \ref Vector_Library for details. \section Vector_Category_File 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). */