<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>GRASS GIS: g.ask</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link rel="stylesheet" href="grassdocs.css" type="text/css">
</head>
<body bgcolor="white">
<img src="grass_logo.png" alt="GRASS logo"><hr align=center size=6 noshade>
<h2>NAME</h2>
<em><b>g.ask</b></em> - Prompts the user for the names of GRASS data base files.
<h2>KEYWORDS</h2>
general
<h2>SYNOPSIS</h2>
<b>g.ask</b><br>
<b>g.ask help</b><br>
<b>g.ask</b> <b>type</b>=<em>string</em> [<b>prompt</b>=<em>"string"</em>] <b>element</b>=<em>string</em> [<b>desc</b>=<em>"string"</em>] <b>unixfile</b>=<em>string</em> [--<b>verbose</b>] [--<b>quiet</b>]
<h3>Parameters:</h3>
<DL>
<DT><b>type</b>=<em>string</em></DT>
<DD>The type of query</DD>
<DD>Options: <em>old,new,any,mapset</em></DD>
<DT><b>prompt</b>=<em>"string"</em></DT>
<DD>The prompt to be displayed to the user</DD>
<DT><b>element</b>=<em>string</em></DT>
<DD>The database element to be queried</DD>
<DT><b>desc</b>=<em>"string"</em></DT>
<DD>A short description of the database element</DD>
<DT><b>unixfile</b>=<em>string</em></DT>
<DD>The name of a unix file to store the user's response</DD>
</DL>
<H2>DESCRIPTION</H2>
<EM>g.ask</EM> is designed for shell scripts that need to
prompt the user for the name of a data base file in the
user's current GRASS location. After <EM>g.ask</EM> is
invoked with needed parameters, it will query the user for
a file name of the specified <EM>type</EM> and
<EM>element</EM>. After the user responds to this query,
the program will write four lines to the UNIX output file
specified by <EM>unixfile</EM>.
<!-- unused
<H2>OPTIONS</H2>
<H3>Parameters:</H3>
<DL>
<DT><B>type=</B><EM>name</EM>
<DD>The type of query. Options for <EM>name</EM> are
<EM>old</EM>, <EM>new</EM>,
<EM>any</EM>, and <EM>mapset</EM>; their functions are given below.
"New", "any", and "mapset" only look in the user's current mapset.
<DL>
<DD>
<DT><B>old</B>
<DD>For existing data files anywhere in the user's mapset search path.
<DT><B>new</B>
<DD>Used to create a new file in the current mapset, which must not
already exist there (if a file with this name exists there,
it will not be overwritten).
<DT><B>any</B>
<DD>Creates a file in the current mapset, which may or may not
already exist there. If a file with this name exists in the
current mapset, it will be overwritten;
if not, a new file with this name will be created.
<DT><B>mapset</B>
<DD>For files that must exist in the current mapset
The shell write wants the name of a file which exists
in the user's current mapset. This type would
used instead of "old" if the file is to be modified.
</DL>
<DT><B>prompt=</B>"<EM>string</EM>"
<DD>The prompt to be displayed to the user. If more than
one word, the prompt should be enclosed within double
quotes ("").
<DT><B>element=</B><EM>name</EM>
<DD>The name of the GRASS data base element (i.e.,
directory under a GRASS mapset) whose files are to be
queried.
<DT><B>desc=</B>"<EM>string</EM>"
<DD>A short description of the data base element which is
meaningful to the user. If description contains more than
one word, it should be enclosed within double quotes ("").
<DT><B>unixfile=</B><EM>name</EM>
<DD>The name of a UNIX file to store the user's response.
See next section for what is written to this file and how
it can be used by shell scripts.
</DL>
-->
<H2>OUTPUT</H2>
Upon receiving the user's response to its request for a
file name, <EM>g.ask</EM> writes four lines to the
specified <EM>unixfile</EM>; this output file is placed in
the user's current working directory, unless otherwise
specified, and contains the following lines:
<div class="code">
<PRE>
name='<EM>some_name</EM>'
mapset='<EM>some_mapset</EM>'
fullname='<EM>some_fullname</EM>'
file='<EM>some_fullpath</EM>'
</pre></div>
<P>
The output is <EM>/bin/sh</EM> commands to set the variable
<EM>name</EM> to the file name specified by the user (of
the <EM>element</EM> and <EM>type</EM> requested by
<EM>g.ask</EM>), <EM>mapset</EM> to the GRASS mapset in
which this file resides (or will be created),
<EM>fullname</EM> is the name with the mapset embedded in
it, and <EM>file</EM> to the full UNIX path name
identifying this file. These variables may be set in the
<EM>/bin/sh</EM> as follows:
<DL>
<DD>
<B>. unixfile</B>
</DL>
<P>
The . is a shell command which means read the
<EM>unixfile</EM> and execute the commands found there. It
is NOT part of the <EM>unixfile</EM> name and MUST be
followed by a space.
<H2>NOTES</H2>
The user may choose to simply hit the return key and not enter a file name.
If this happens the variables will be set as follows:
<div class="code">
<PRE>
name=
mapset=
fullname=
file=
</pre></div>
<P>
The following is a way to test for this case:
<div class="code">
<PRE>
if [ ! "$file" ]
then
exit
fi
</PRE></div>
<H2>SEE ALSO</H2>
<EM><A HREF="d.ask.html">d.ask</A></EM>,
<EM><A HREF="g.filename.html">g.filename</A></EM>,
<EM><A HREF="g.findfile.html">g.findfile</A></EM>,
<EM><A HREF="g.gisenv.html">g.gisenv</A></EM>,
<EM><A HREF="g.parser.html">g.parser</A></EM>
<H2>AUTHOR</H2>
Michael Shapiro,
U.S.Army Construction Engineering Research Laboratory
<p><i>Last changed: $Date: 2005-12-07 14:31:16 +0100 (Wed, 07 Dec 2005) $</i>
<HR>
<P><a href="index.html">Main index</a> - <a href="general.html">general index</a> - <a href="full_index.html">Full index</a></P>
<P>© 2003-2008 <a href="http://grass.osgeo.org">GRASS Development Team</a></p>
</body>
</html>
