d.what.r.pg

NAME

d.what.r.pg - Report database attributes associated with a raster category value at a specified location. (GRASS-RDBMS Attribute Interface Program)

SYNOPSIS

d.what.r.pg
d.what.r.pg help
d.what.r.pg map=name tab=name col=name [join=tab,tabkey,pkey]

ALTERNATE

d.what.r.pg -s help
d.what.r.pg -s pql=filename map=name

DESCRIPTION

d.what.r.pg reports database attributes from the currently selected database associated with a raster category at a specific location on a raster map. The currently selected database is identified by the GRASS environment variable $PGDBASE which is set using the g.select.pg GRASS-RDBMS interface tool. If this environment variable is not set the program terminates with a message to the user. The current raster location is selected by the user with the mouse. If no join parameters are provided by the user on the command line the attributes in the table directly linked to the GRASS raster structure via the category value are returned. However, if a join is specified then attributes from a related table are displayed. If the alternate form of this command is selected with the -s flag the user has greater control over the number of relational joins and the manner in which the attribute information is displayed. Using the -s option the attributes from more than one table can be returned and displayed.

COMMAND LINE OPTIONS

Parameters:

map=map
Name of an existing raster map with category values linked to the currently selected database.

tab=databasetablename
Table in the currently selected database containing a column associated with raster category values.

col=databasecolumnname
Column associated with raster category values.

join=tab,tabkey,pkey
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.

For instance, assume that secosoilcats is a table containing column values associated with category values in a the GRASS raster file soils (cropname). In addition, assume that compyld is a table containing attribute data on the crop production capacity in the same area. In this example secosoilcats is the table associated with the GRASS raster map and grasscats is the column linking secosoilcats to the GRASS category file, the table compyld contains the attribute information to base the query/reclass on and it is linked to secosoilcats via the common column muid. To specify a query based on attribute values in the table compyld:

d.rast.pg key=grasscat tab=secosoilcats col=cropname input=soils join=compyld,compyld.muid,secosoilcats.muid

Specifying these conditions would insure that all rows from table compyld which satisfy the query criteria would be matched with the corresponding rows in table secosoilcats, 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.r.pg -s pql=statsgo.pql map=secosoils

statsgo.pql:
retrieve unique (secosoilcats.all)
where secosoilcats.tlid=?

Results:
Reports all attributes from the table secosoilcats associated with the raster category value at the current mouse location the raster map secosoils.

EXAMPLE (two table join)

d.what.r.pg -s sql=statsgo.sql map=secosoils

statsgo.sql:
retrieve unique (secosoilcats.all, mapunit.all, compyld.all)
where secosoilcats.grasscat=? and secosoilcats.muid=mapunit.muid and mapunit.muid=compyld.muid

Results:
Reports all attributes from the table secosoilcats, mapunit and compyld associated with the raster category value at the current mouse location in the raster map secosoils.

Flag:

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

Parameters:

sql=filename
PostQUEL statements specifying well formed selection criteria.

map=map
Name of an existing raster map with category values linked to a database.

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.s.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)