d.what.s.pg

NAME

d.what.s.pg - Report database attributes associated with a specific point location. (GRASS-RDBMS Attribute Interface Program)

SYNOPSIS

d.what.s.pg
d.what.s.pg help
d.what.s.pg tab=name xcol=name ycol=name distance=value[join=tab,tabkey,pkey]

ALTERNATE

d.what.s.pg help -s
d.what.s.pg -s pql=filename distance=search radius

DESCRIPTION

d.what.s.pg reports database attributes in the currently selected database which are associated with a specific point location. The current database is identified by the GRASS environment variable $PGDBASE which is set using the g.select.pg GRASS-RDBMS interface tool. The location to query is selected by the user with the mouse. The radius around this point to search is specified by the distance argument. Sites are selected by comparing the values in the database columns containing X and Y coordinate data against the coordinate data at the current mouse location. If no join arguments are supplied by the user the columns in the table containing the coordinate values are returned in the report. By specifying a join criteria attribute information from a related table can be returned in the report. If information from more than one table is required use the -s flag and the alternate command line format (see below).

COMMAND LINE OPTIONS

Parameters:

tab=databasetablename
Table containing X, Y coordinate values

xcol=databasecolumnname
Column containing the X coordinate (E/W) value.

ycol=databasecolumnname
Column containing the Y coordinate (N/S) value.

distance=value
Radius distance from the current mouse location to conduct database search.

join=tab,tabkey,pkey
Optionally, a series of join parameters can be supplied to retrieve information from related database tables. The format for these parameters is reviewed in the following discussion. Tab is the table used to develop the current postQUEL query. Tabkey is the database column used to relate information in this table with data in the table linked to the GRASS category file. Pkey is the associated column in the table linked to the GRASS category file which is related to tabkey in the current table.
d.what.s.pg tab=well xcol=utmeast ycol=utmnorth distance=500

For instance, assume that well is a table containing X,Y coordinate values and that wellowners is a table containing ownership information associated with well logs. To base a query on site location which would return attribute data on ownership and locational information in the table well the following join would be needed on the command line:

tab = well join=wellowners,wellowners.wellid,well.wellid

The column wellid is common to both the well and the wellowners table. Because of this attribute data from both tables will be returned if the coordinates registered by the mouse return a record from the table well within a radius specified by the distance parameter on the command line. Specifying these conditions would insure that all rows from table roads which satisfy the query criteria would be matched with the corresponding rows in table main, which are then related to the spatial features in the GRASS data layer via the GRASS category values.

This syntax is adequate to accomplish 2 table joins. However, if the query demands joins between more than 2 tables it is advisable to use the -s option [see Alternate Command Line Usage] to read a user prepared query, complete with join requirements, from a file.

ALTERNATE COMMAND LINE USAGE

The alternate command line usage is provided to simplify the process of retrieving information from more than one table in the query criteria. The alternate command line structure is selected using the the [-s] flag on the command line. When using this flag the user must include the name of a text file on the command line as well. This file must include a complete, well formed postQUEL SELECT statement specifying the query criteria and all relevant JOINS needed to retrieve values which correspond to category values in a GRASS data layer.

The user must also specify the name of the GRASS data layer containing these category values on the command line. The following example illustrates the syntax which must be used in constructing a SELECT statement for use with the -s flag.

EXAMPLE (single table)

d.what.s.pg -s pql=well.pql distance=10

well.pql:
retrieve unique (well.all)
where (((well.utmeast-?) * (well.utmeast-?) + (well.utmnorth-?) * (well.utmnorth-?)) < ?) and well.utmeast > 0 and well.utmnorth >0

EXAMPLE (two table join)

d.what.s.pg -s pql=nri.pql distance

nri.pql:
retrieve unique (well.all,wellowners.all)
where (((well.utmeast-?) * (well.utmeast-?) + (well.utmnorth-?) * (well.utmnorth-?)) < ?) and well.utmeast > 0 and well.utmnorth >0 and wellowners.lastname ~ "SM" and wellowners.wellid=well.wellid

NOTE

The symbol ? in these examples is a meta character used to evaluate coordinate locations returned by the GRASS pointer against records in the database. The ? symbols must be included in the pql file.

Flag:

-s
PostQUEL select statements are input from a prepared file.

Parameters:

pql=filename
PostQUEL statements specifying well formed selection criteria. These criteria must include the database table name, the Xcol and Ycol names as well as the search distance and any "JOINS" needed to retrieve the coordinate values. Additional criteria may be placed in the "where" clause to further subset information returned from the database.

input=map
Name of an existing raster map

BUGS

None known.

NOTE

This program requires the Postgres database software.

SEE ALSO

g.column.pg, g.select.pg, g.stats.pg, g.table.pg, d.rast.pg, d.site.pg, d.vect.pg, d.what.r.pg, d.what.v.pg, r.reclass.pg, r.rescale.pg, v.reclass.pg

AUTHOR

Original Informix SQL-tools: James A. Farley, Wang Song, and W. Fredrick Limp University of Arkansas, CAST

Postgres modifications: Janne Soimasuo, Faculty of Forestry, University of Joensuu, Finland.

Updated to GRASS 5 by Alex Shevlakov (sixote@yahoo.com)