WDB Call Interface User Manual

Abstract

WDB is a data storage solution for weather and water data based on the PostgreSQL object-relational database system. The system utilizes PostGIS for GIS (Geographic Information Systems) support and handles regular grids (e.g., forecast fields) and point (e.g., observation) data.

This is the User's Manual for WDB Call Interface of WDB version WDB_VERSION

Table of Contents

1. IntroductionAbout this ManualIntended Usagesec:wci_outline2. Key ConceptsOverviewData Providersec:placeReference TimeValid TimeValue ParameterLevelsec:data_version3. Using the WCIOutlineOpen a connectionInitialize WCIsec:reading_wciReading Point Data from WCIReading Grid Data from WCIRelease WCIClose Connection4. Function Referencewci.addCodeLevelParameterPrerequisitessec:wci.addcodelevelparameter.syntaxParametersExpected ResultExamplesec:wci.addcodelevelparamater.seewci.addCodeValueParameterPrerequisitesSyntaxsec:wci.addcodevalueparameter.parametersExpected ResultExampleSee Alsosec:wci.adddataproviderPrerequisitessec:wci.adddataprovider.syntaxParametersExpected ResultExamplesec:wci.adddataprovider.seewci.addDataProviderToGroupPrerequisitesSyntaxsec:wci.adddataprovider2group.parametersExpected ResultExampleSee Alsosec:wci.adddimvalueparameterPrerequisitesSyntaxParameterssec:wci.adddimvalueparameter.resultExampleSee Alsowci.addFunctionValueParametersec:wci.addfunctionvalueparameter.prereqSyntaxParametersExpected Resultsec:wci.addfunctionvalueparameter.exampleSee Alsosec:wci.addlevelparameterusagePrerequisitesSyntaxParameterssec:wci.addlevelparameterusage.resultExampleSee Alsowci.addMeasuresec:wci.addmeasure.prereqSyntaxsec:wci.addmeasure.parametersExpected ResultExampleSee Alsosec:wci.addmeasurelevelparameterPrerequisitesSyntaxParameterssec:wci.addmeasurelevelparameter.resultExamplesec:wci.addmeasurelevelparamater.seewci.addMeasureValueParameterPrerequisitesSyntaxsec:wci.addmeasurevalueparameter.parametersExpected ResultExampleSee Alsosec:wci.addparameterfunctiontypePrerequisitesSyntaxParameterssec:wci.addparameterfunctiontype.resultExamplesec:wci.addparameterfunctiontype.seewci.addPlacePointPrerequisitesSyntaxsec:wci.addplacepoint.parametersExpected ResultExampleSee Alsosec:wci.addplacepolygonPrerequisitesSyntaxParameterssec:wci.addplacepolygon.resultExampleSee Alsowci.addPlacerRegularGridsec:wci.addplaceregulargrid.prereqSyntaxParametersExpected Resultsec:wci.addplaceregulargrid.exampleSee Alsosec:wci.addsridPrerequisitesSyntaxParameterssec:wci.addsrid.resultExampleSee Alsowci.addUnitsec:wci.addunit.prereqSyntaxParametersExpected Resultsec:wci.addunit.exampleSee Alsowci.addValueParameterUsagePrerequisitessec:wci.addvalueparameterusage.syntaxParametersExpected ResultExamplesec:wci.addvalueparameterusage.seewci.addWciUserPrerequisitesSyntaxsec:wci.addwciuser.parametersExpected ResultExampleSee Alsosec:wci.beginPrerequisitessec:wci.begin.syntaxParametersExpected ResultExamplesec:wci.begin.seewci.browsePrerequisitesSyntaxsec:wci.browse.parametersExpected ResultExampleSee Alsosec:wci.configurationPrerequisitesSyntaxParameterssec:wci.configuration.resultExampleSee Alsowci.endsec:wci.end.prereqSyntaxParametersExpected Resultsec:wci.end.exampleSee Alsowci.fetchPrerequisitessec:wci.fetch:syntaxParametersExpected ResultExamplessec:wci.fetch:seewci.getCodeLevelParameterPrerequisitesSyntaxsec:wci.getcodelevelparameter.parametersExpected ResultExampleSee Alsosec:wci.getcodevalueparameterPrerequisitesSyntaxParameterssec:wci.getcodevalueparameter.resultExampleSee Alsowci.getDataProvidersec:wci.getdataprovider.prereqSyntaxParametersExpected Resultsec:wci.getdataprovider.exampleSee Alsowci.getDataProviderNamePrerequisitessec:wci.getdataprovidername.syntaxParametersExpected ResultExamplesec:wci.getdataprovidername.seewci.getDimensionlessValueParameterPrerequisitesSyntaxsec:wci.getdimensionlessvalueparameter.parametersExpected ResultExampleSee Alsosec:wci.getfunctionvalueparameterPrerequisitessec:wci.getfunctionvalueparameter.syntaxParametersExpected ResultExamplesec:wci.getfunctionvalueparameter.seewci.getLevelParameterPrerequisitesSyntaxsec:wci.getlevelparameter.parametersExpected ResultExampleSee Alsosec:wci.getlevelparameterusagePrerequisitesSyntaxParameterssec:wci.getlevelparameterusage.resultExampleSee Alsowci.getMeasuresec:wci.getmeasure.prereqSyntaxsec:wci.getmeasure.parametersExpected ResultExampleSee Alsosec:wci.getmeasurelevelparameterPrerequisitesSyntaxParameterssec:wci.getmeasurelevelparameter.resultExamplesec:wci.getmeasurelevelparameter.seewci.getMeasureValueParameterPrerequisitesSyntaxsec:wci.getmeasurevalueparameter.parametersExpected ResultExampleSee Alsosec:wci.getparameterfunctiontypePrerequisitesSyntaxParameterssec:wci.getparameterfunctiontype.resultExamplesec:wci.getparameterfunctiontype.seewci.getPlaceDefinitionPrerequisitesSyntaxsec:wci.getplacedefinition.parametersExpected ResultExampleSee Alsosec:wci.getplacenamePrerequisitessec:wci.getplacename.syntaxParametersExpected ResultExamplesec:wci.getplacename.seewci.getPlacePointPrerequisitesSyntaxsec:wci.getplacepoint.parametersExpected ResultExampleSee Alsosec:wci.getplaceregulargridPrerequisitesSyntaxParameterssec:wci.getplaceregulargrid.resultExampleSee Alsowci.getSridsec:wci.getsrid.prereqSyntaxsec:wci.getsrid.parametersExpected ResultExampleSee Alsosec:wci.getunitPrerequisitesSyntaxParameterssec:wci.getunit.resultExampleSee Alsowci.getValueParametersec:wci.getvalueparameter.prereqSyntaxParametersExpected Resultsec:wci.getvalueparameter.exampleSee Alsowci.readPrerequisitessec:wci.read:syntaxParametersExpected ResultExamplessec:wci.read:seewci.setDataProviderNamePrerequisitesSyntaxsec:wci.setdataprovidername.parametersExpected ResultExampleSee Alsosec:wci.setlevelparameternamePrerequisitesSyntaxParameterssec:wci.setlevelparametername.resultExampleSee Alsowci.setPlaceNamesec:wci.setplacename.prereqSyntaxParametersExpected Resultsec:wci.setplacename.exampleSee Alsowci.setValueParameterNamePrerequisitessec:wci.setvalueparametername.syntaxParametersExpected ResultExamplesec:wci.setvalueparametername.seewci.versionPrerequisitesSyntaxsec:wci.version:parametersExpected ResultExamplesSee Alsoid2900563PrerequisitesSyntaxParametersExpected ResultSee Alsoid2900835wci.browsedataproviderwci.browseplacewci.browsereferencetimewci.browsevalidtimewci.browsevalueparameterwci.browselevelparameterwci.infodataproviderwci.infoplacewci.inforegulargridwci.infovalueparameterwci.infolevelparameterwci.returnFloatwci.returnGid6. Examplescha:wci_faq8. Known Problems, Bugs, and LimitationsLimit of 100,000 rows returned by wci.read from a single grid

List of Tables

4.1. wci.addCodeLevelParameter parameters4.2. wci.addCodeValueParameter parameters4.3. wci.addDataProvider parameters4.4. wci.addDataProviderToGroup parameters4.5. wci.addDimensionlessValueParameter parameters4.6. wci.addFunctionValueParameter parameters4.7. wci.addLevelParameterUsage parameters4.8. wci.addmeasure parameters4.9. wci.addMeasureLevelParameter parameters4.10. wci.addMeasureValueParameter parameters4.11. wci.addParameterFunctionType parameters4.12. wci.addPlacePoint parameters4.13. wci.addPlacePolygon parameters4.14. wci.addPlaceRegularGrid parameters4.15. wci.addSrid parameters4.16. wci.addUnit parameters4.17. wci.addLevelParameterUsage parameters4.18. wci.addWciUser parameters4.19. wci.begin parameters4.20. wci.configuration return row4.21. wci.fetch parameters4.22. wci.getCodeLevelParameter parameters4.23. wci.getCodeLevelParameter return row4.24. wci.getCodeValueParameter parameters4.25. wci.getCodeValueParameter return row4.26. wci.getDataProvider parameters4.27. wci.getDataProvider return row4.28. wci.getDataProviderName parameters4.29. wci.getDataProviderName return row4.30. wci.getDimensionlessValueParameter parameters4.31. wci.getDimensionlessValueParameter return row4.32. wci.getFunctionValueParameter parameters4.33. wci.getfunctionValueParameter return row4.34. wci.getLevelParameter parameters4.35. wci.getlevelParameter return row4.36. wci.getlevelparameterusage parameters4.37. wci.getlevelparameterusage return row4.38. wci.getmeasure parameters4.39. wci.getmeasure return row4.40. wci.getMeasureLevelParameter parameters4.41. wci.getmeasurelevelParameter return row4.42. wci.getMeasurevalueParameter parameters4.43. wci.getMeasurevalueParameter return row4.44. wci.getparameterfunctiontype parameters4.45. wci.getparameterfunctiontype return row4.46. wci.getPlaceDefinition parameters4.47. wci.getPlaceDefinition return row4.48. wci.getPlaceName parameters4.49. wci.getPlaceName return row4.50. wci.getPlacePoint parameters4.51. wci.getPlacePoint return row4.52. wci.getPlaceRegularGrid parameters4.53. wci.getPlaceDefinition return row4.54. wci.getSrid parameters4.55. wci.getSrid return row4.56. wci.getunit parameters4.57. wci.getunit return row4.58. wci.getvalueparameter parameters4.59. wci.getvalueparameter return row4.60. wci.read parameters4.61. wci.setDataProviderName parameters4.62. wci.setLevelParameterName parameters4.63. wci.setPlaceName parameters4.64. wci.setValueParameterName parameters4.65. wci.write parameters5.1. wci.browsedataprovider5.2. wci.browseplace5.3. wci.browsereferencetime5.4. wci.browsevalidtime5.5. wci.browsevalueparameter5.6. wci.browselevelparameter5.7. wci.infodataprovider5.8. wci.infoplace5.9. wci.infoplace5.10. wci.infovalueparameter5.11. wci.infolevelparameter5.12. wci.returnFloat5.13. wci.returnGid

Chapterï¿½1.ï¿½Introduction

Table of Contents

About this ManualIntended Usagesec:wci_outline

The WDB Call Interface (WCI) is the official API used for retrieving data from the WDB system.

About this Manual

This manual is intended for system designers, application developers and programmers. It describes in technical terms how weather data can be retrieved from the WDB system through the WCI. It is assumed that the reader has some familiarity with databases and weather data.

For a more elaborate description of the vision and system architecture of the WDB system, see the WDB Developer's Manual.

Intended Usage

WCI is intended to be used for retrieving weather data (e.g., temperature, air pressure, etc.) for a geographic point or area, given an altitude interval and a time or time interval. It is possible to retrieve individual data values or huge quantities of data using a single API.

Outline

This document is structured as follows:

Key Concepts: introduction to the concepts and terms used in the documentation

Using the WCI: an introduction to how the WCI is used

Function Reference: reference documentation for each of the WCI functions

Data Types Reference: reference documentation for the WCI data types

Examples: Example programs for WCI

FAQ: Frequently asked questions

Known bugs and limitations

Chapterï¿½2.ï¿½Key Concepts

Table of Contents

OverviewData Providersec:placeReference TimeValid TimeValue ParameterLevelsec:data_version

This section provides an overview of the WCI, including some important definitions and explanations.

Overview

WCI is an API designed to retrieve weather data from the WDB system. The WCI API resides on the database server.

All function calls on WCI are executed as SQL statements. The SQL statements can be executed through a dedicated SQL client application, such as psql, pgadmin3, DbVisualizer, or by an application program through a database API such as JDBC, ODBC, libpqxx, etc. The WCI is thus not linked into the application program itself, but is a component of the database.

A data item in WDB could be an observation, a forecast, an analysis, etc. Each item consists of a value and a number of dimensions that describe the value.

A dimension could be a description of the data item (e.g., temperature), its geographic position, its altitude (or depth), the time the data item was created, the origin of the data item, etc.

In order to access the data items in WDB, the user should have an understanding of the dimensions as they are the entry point into the database. When data is retrieved from the database, a set of search criteria is given for each of the WCI dimensions. If the search criteria for a dimension is not specified (i.e., all NULLs), it is assumed the user wants to retrieve all data items, regardless of their dimension description. Please do not attempt this unless the database you are querying is extremely small.

In the context of WCI search criteria, NULL is always interpreted to mean “ALL”.

The last parameter of a WCI function call that is intended to return data is always reserved for specifying the data type to be returned (this is because most functions are overloaded to return many different forms of data. By convention, this parameter is usually given as a NULL cast to the relevant data type; for example:

NULL::wci.browsereferencetime

The dimensions are described in the following sections.

Data Provider

The Data Provider identifies the source of the data; literally, the entity that provides the data. Where multiple sources could be identified as the source of the data, the entity that can be identified closest to the creation of the data item at the time of loading is usually used.

A data provider can be a software process (e.g., Hirlam), a meteorological or climate station, an aircraft, or a person. A data provider is identified by a DataProviderName. DataProviderNames are used to search for the data. For convenience, Data Providers may be collected into groups; e.g., the DataProviderName “Hirlam” might be used to search for any of the various Hirlam processes: “Hirlam 4”, “Hirlam 8”, etc.

When searching for data, the user may specify a single DataProviderName, a list of DataProviderNames (specified using an ARRAY constructor), or NULL. NULL indicates that the user wants all data items, regardless of the data source.

DataProviderNames exist within a data provider namespace. A namespace can be defined by the WDB administrator, in order to permit the user or an application to retrieve data in an accustomed language or code set. The default namespace of WDB is the DataProviderNameSpaceId 0, and is always based on English language names and international standard codes. The data provider namespace being used in a querying session can be defined by the user when starting up the session.

To retrieve all of the DataProviderNames (excluding data provider groups) that are currently stored in the database for the currently specified namespace, the following wci.browse function call could be used:

SELECT * FROM wci.browse( NULL::wci.browsedataprovider );

To retrieve all of the DataProviderNames (including data provider groups) that the database currently has the capacity to store and display in the currently specified namespace, the following wci.info function call could be used:

SELECT * FROM wci.getDataProvider( NULL );

Place (Geographic Location)

The place (geographic location) of a data item is the position of the item on the earth in a 2D space. In WDB, the geographic location is by default specified using longitude and latitude in a WGS84 coordinate system (though this can be changed when the database is set up; consult your system administrator). The geographic dimension is specified using a geometry object and can be either a point or a polygon.

In addition to using geometry objects to retrieve data, the user can also use a PlaceName - a pre-specified name that defines a geometry object in the database - to specify location.

As for DataProviderName, PlaceNames exist within a place namespace that can be defined by the WDB administrator. The default namespace of WDB is the PlaceNameSpaceId 0; defined in international english. As for the data provider namespace, the place namespace can be defined by the user when starting up the session.

To retrieve the full list of the PlaceNames for the data values currently being stored in the database, use the following wci.browse function call:

SELECT * FROM wci.browse( NULL::wci.browseplace );

At the same time as the user specifies a location to retrieve data from, it is also possible to specify an interpolation option for location calculations. These permit the user a great deal of flexibility in searching. Currently, interpolations such as “exact”, “nearest” (retrieve the data value closest to the specified place), and “bilinear” (retrieve the closest data values and perform a bilinear interpolation of those values) are implemented.

The form of place specification then becomes one of the two following:

'Oslo'

'nearest Oslo'

'POINT(61 9)'

'bilinear POINT(61 9)'

Specifying NULL for the place definition of a query is logically equivalent to asking for all of the data items in the database, irrespective of their location.

To retrieve all of the place names that are currently registered in the database, the following WCI function call can be used:

SELECT * FROM wci.getPlaceDefinition( NULL );

Reference Time

The reference time of a data item is the moment when the data item is referenced from. For forecast data, this would typically be the reference time of the data values the forecast is based upon; for observation data, it would typically be the time when the observation data was recorded.

When searching for data, the user specifies the reference time (with time zone), or NULL. NULL indicates that the user wants all data items, regardless of the reference time of the data. Time is specified in WCI as a text string with datetime's that are interpreted by the WCI parser.

To retrieve a list of the reference times currently being stored in the database, use the wci.browse functionality:

SELECT * FROM wci.browse( NULL::wci.browsereferencetime );

In addition to time points, it is also possible for the user to specify time periods using a variety of keywords. The keywords are: exact (default), before, after, inside, and contains. And interval can be specified using two timestamps and separating them with the keyword TO, or a timestamp and a duration separated by the keyword FOR. As examples, consider:

exact 2009-03-31T11:20:00+00

Denotes the specific time point of 11:20 UTC, on the 31st of March, 2009. The keyword “exact” is actually redundant, as this is the default interpretation of a timestamp in WCI.

before 2009-03-31T11:20:00+00

Denotes that the user wants to return all data for the time period prior to the time point of 11:20 UTC, on the 31st of March, 2009.

after 2009-03-31T11:20:00+00

Denotes that the user wants to return all data for the time period after the time point of 11:20 UTC, on the 31st of March, 2009.

inside 2009-03-31T11:20:00+00 TO 2009-05-31T11:20:00+00

Denotes that the user wants to return all data inside the time period between the time point of 11:20 UTC, on the 31st of March, 2009 and the same time two months later.

inside 2009-03-31T11:20:00+00 FOR 2 months

Denotes that the user wants to return all data inside the time period between the time point of 11:20 UTC, on the 31st of March, 2009 and the same time two months later.

Valid Time

The valid time of a data item is the time period for which the data item is valid. The valid time is always stored in the database as a time interval.

When searching for data, the user specifies the valid time (with time zone), or NULL. NULL indicates that the user wants all data items, regardless of the valid time of the data. Time is specified in WCI as a text string with datetime's that are interpreted by the WCI parser.

As usual, the list of valid times stored in the database can be retrieved using the wci.browse functionality.

SELECT * FROM wci.browse( NULL::wci.browsevalidtime );

Time is specified in the same way for time periods as for time points. Examples of how the qualifiers should be interpreted are given below:

exact 2009-03-31T11:20:00+00 TO 2009-05-31T11:20:00+00

The exact keyword returns only time periods that match precisely with the time period specified.

before 2009-03-31T11:20:00+00

The before keyword returns only time periods that end before the specified time point. In other words, the time period from 2009-03-29 to 2009-03-30 would be returned by the query but the time period from 2009-03-29 to 2009-04-01 would not.

after 2009-03-31T11:20:00+00

The after keyword returns only time periods that start after the specified time point.

inside 2009-03-31T11:20:00+00 TO 2009-05-31T11:20:00+00

The inside keyword for time periods is true if the time period both starts and ends within the designated time (the time point specified inclusive). It does not return time periods that merely overlap (i.e., where only the start time or the end time are within the given time period).

contains 2009-03-31T11:20:00+00 TO 2009-05-31T11:20:00+00

The contains keyword returns all the data with valid times beginning prior to the specified time and ending after the specified time. Semantics are inclusive, so a valid time that matches exactly would be returned as a row by this query.

Value Parameter

Each data value can be described using a “value parameter”. The value parameter is a name that describes the physics or code table basis of the parameter value. The value parameter concept in WCI is broadly similar to the concept of meteorological parameter used in, e.g., GRIB files.

The user searches the database for a specific parameter in the database using the ValueParameterName. ValueParameterNames are specified within a parameter namespace. As with the other namespaces, the ParameterNameSpaceId 0 is reserved for the default WDB namespace, and is based on international english. Additional namespaces can be defined by the administrator of the database.

To retrieve a list of the value parameters currently being stored in the database, use the wci.browse functionality:

SELECT * FROM wci.browse( NULL::wci.browsevalueparameter );

To list all of the value parameter names that can be stored in the database using the currently selected parameter namespace, the following wci.info function call could be used:

SELECT * FROM wci.getValueParameter( NULL );

Level

The Level dimension is normally used to designate the altitude or depth of the data value. Level is designated using a level interval (height from and to) and a level parameter (e.g., height above sea level, pressure). The level definition can be prefixed with a level interpolation option that permits the user a large degree of flexibility in expressing searches. Levels are specified using a level specification in string form that is parsed by the WCI.

The level designation in the WCI queries is a string. The form of the level designation when querying the database is as follows:

interpolation levelFrom TO levelTo leveparametername

The interpolations available are exact, below, above, inside, and any. The default interpolation is exact (specifying the interpolation is optional). One may also omit the TO levelTo construction if the level being specified is a point.

Specifying any for the level interpolation is logically equivalent to specifying a NULL for the level; i.e., it retrieves all data items regardless of their level (height).

The level parameter is specified using a LevelParameterName. LevelParameterNames are specified within the parameter namespace. Consequently, it is not possible to mix usage of ValueParameterNames and LevelParameterNames from different namespaces without defining a new parameter namespace. The default WDB ParameterNameSpaceId is 0 and is based on international english.

Examples of level designations are given below:

exact 2 height

above 0 height above mean sea level distance

inside 300 TO 500 isobaric surface pressure

To retrieve a full list of the levels and level parameters currently being stored in the database, use the wci.browse functionality:

SELECT * FROM wci.browse( NULL::wci.browselevelparameter );

To list all of the level parameter names that can be stored in the database using the currently selected parameter namespace, the following wci.info function call could be used:

SELECT * FROM wci.getLevelParameter( NULL );

Data Version

There can be several different versions of the same data value that is valid for the same time, position, etc. This can happen with probability forecast calculations or when a data value is edited (in which case the new value may often be inserted with a higher data version). A data version is always a positive whole number.

The user may specify one or several data versions as search criteria in WCI, as well as NULL. NULL indicates that the user wants all versions of the data items specified. In addition, the user may specify the data version as a negative number; e.g., -1. Specifying -1 retrieves the maximum data version in the database (i.e., the most recent version of the data item), -2 retrieves the second most recent, and so on.

There is no wci.browse functionality to list all of the data versions of the data in the database.

Chapterï¿½3.ï¿½Using the WCI

Table of Contents

OutlineOpen a connectionInitialize WCIsec:reading_wciReading Point Data from WCIReading Grid Data from WCIRelease WCIClose Connection

This section gives an overview on how to use the WCI to retrieve data values from WDB.

Outline

The following list provides a brief overview of the actions that the user takes in order to retrieve data from WCI.

Create a connection to the database

Initialize WCI

Read data from WDB using WCI functions (one or more times)

Release WCI

Close database connection

Open a connection

To enable communication with WCI, the user must open a connection to the database. How this is done depends very much on the application or API that is being used (consult the documentation of the program or API for information).

Using libpq,

connection_ = PQconnectdb("dbname=wdb user=myuser host=localhost");

The connection must be open and valid as long as commands are being sent and data retrieved from the database. It is worth noting that connections are a resource; the database will have limits on how many connections can be open at the same time. This is particularly important for massively multi-user applications (e.g., web applications). In such cases, the database connections must be managed with some care. There is also an amount overhead involved with setting up a connection, so it will always be more efficient to connect once and perform multiple database operations, than to connect repeatedly for each operation.

Initialize WCI

Before WCI may be used by the user, it must be initialized.

SELECT wci.begin('myuser'::name, 0::integer, 0::integer, 0::integer);

The username is used to identify the user with WCI (this is used in setting up internal WCI variables). The three following numbers are the namespace codes for data provider namespace, place name space, and parameter name space. The wci.begin can also be called without setting these three variables, in which case they are set to the default (usually 0, 0, 0) by the system.

The username of the wci user can be a different identity than the one the user connected with (always assuming, of course, that your user has appropriate rights). This allows, for instance, for a single system to act as a multiplexing front-end to retrieve data available from several distinct users.

Name spaces are used to identify what set of names should be used for searching the database. While the user is in a namespace, only the data defined in that namespace is visible to the user. If the user should wish, for some reason, to combine data from different namespaces within an application, it will be necessary to call wci.begin repeatedly; once for each time the application needs to change its namespace.

Read from the WCI

As soon as the user has initialized WCI using wci.begin, the database is ready for retrieval of data. Data is retrieved using the wci.read function, and data is searched for by setting the appropriate dimensions in that call.

Reading Point Data from WCI

The wci.read function is overloaded to permit the user to read either point data or binary data (entire grids) from the database. The last parameter in the wci.read function allows the user to specify the return type of the query. To return point data values, the user specifies wci.returnFloat.

SELECT *
FROM wci.read ( ARRAY['hirlam norway'], -- Data provider name
'POLYGON((10 60,11 60,11 61,10 61,10 60))', -- Location
'inside 1980-01-01 12:00:00Z TO 1980-01-01 18:00:00Z', -- Reference time
NULL, -- Valid Time
ARRAY['air temperature'], -- Value Parameter
'2 height', -- Level
ARRAY[-1], -- Data version
NULL::wci.returnfloat -- Return type
)

The above query returns Hirlam data for a specific region (given by the place geometry), whose referencetime is on or between 12:00 to 18:00 on January 1, 1980; the query will return data for any valid times, for any air temperature. It will return data at 2 metre above ground, but only the latest version of such data. Values will be returned as point data.

The data provider, place definition, value parameter and level parameter must all be defined within the namespaces given in the wci.begin call that preceded the wci.read call. In this particular case, the place definition is a geometry definition, but it would also have been possible to use a placename. Consider, for example, the following query:

SELECT *
FROM wci.read ( ARRAY['hirlam norway'], -- Data provider name
'oslo', -- Location
'1980-01-01 12:00:00Z', -- Reference time
'inside 1980-01-02 12:00:00 TO 1980-01-12 12:00:00', -- Valid Time
ARRAY['%precipitation%'], -- Value Parameter
NULL, -- Level
NULL, -- Data version
NULL::wci.returnfloat -- Return type
)

The above call returns all precipitation parameters valid for the 10 days following the given referencetime measured at the nearest point to oslo. Oslo, in this case, is a place name usually defined as a geographical point within the database. Prefixing the place name is the interpolation that we wish to use when retrieving points; we could also have used any of the alternatives defined in the reference manual below. Note the use of SQL wildcard characters in the value parameter; although these slow down queries (since wildcard searching is not as efficient as a straight comparison), it is possible to use the wci.read call in this way. Note also that names can be written in upper or lower case; the wci.read function call is not case-sensitive.

Return values

The return value from this call is one row for each value. This means that if you have chosen an interpolation type that will return several values for each grid, you will get many rows for each grid.

The actual data value is given in the column “value”. In some cases this may have a NULL value. This means that the there exists a data field for your query, and the point(s) you requested is inside the data's grid, but that grid point has explicitly gotten a “not defined” value.

Reading Grid Data from WCI

Reading grid data from the database is a two-step process. First the user retrieves the Grid ID with wci.read function (with wci.returnGId), and then the grid itself can be retrieved using the wci.fetch function call.

SELECT *
FROM wci.read ( ARRAY['hirlam norway'], -- Data provider name
'hirlam 10km grid', -- Location description
'1980-01-01 12:00:00Z', -- Reference time
NULL, -- Valid Time (returns all forecasts)
ARRAY['air temperature'], -- Value Parameter
'2 height', -- Level
ARRAY[-1], -- Data version
NULL::wci.returngid -- Return type
)

The above query returns the list of grids available for Hirlam data, defined on the hirlam 10km grid (i.e., if there were data on 20km or 4km grids, these would not be returned), whose referencetime is 12:00 on January 1, 1980. The query will return all grid references to air temperature forecasts for the above configuration.

Grid IDs are essentially 8-byte integers, that are then passed to the wci.fetch command, as given below:

SELECT *
FROM wci.fetch ( 7411403, -- Grid ID (bigint)
NULL::wci.grid -- Return Type
)

The above call returns a single row, containing a binary string containing the actual grid data. It also includes additional information detailing the configuration of the grid. For details about the wci.fetch call, see the function reference.

Return values

The return value from this call is one row for each grid. The number given in the “value” column may be used as input argument for a wci.fetch call.

Release WCI

Once the user has finished retrieving data using WCI, it is a good idea to close down WCI.

SELECT wci.end();

This is not strictly necessary, but allows the system to graciously deallocate resources and reset any settings that may have been changed by WCI.

Close Connection

Closes down the connection to the database, freeing up the resources on the database to be used by other applications.

Using libpq,

PQfinish(connection_);

Chapterï¿½4.ï¿½Function Reference

Table of Contents

wci.addCodeLevelParameterPrerequisitessec:wci.addcodelevelparameter.syntaxParametersExpected ResultExamplesec:wci.addcodelevelparamater.seewci.addCodeValueParameterPrerequisitesSyntaxsec:wci.addcodevalueparameter.parametersExpected ResultExampleSee Alsosec:wci.adddataproviderPrerequisitessec:wci.adddataprovider.syntaxParametersExpected ResultExamplesec:wci.adddataprovider.seewci.addDataProviderToGroupPrerequisitesSyntaxsec:wci.adddataprovider2group.parametersExpected ResultExampleSee Alsosec:wci.adddimvalueparameterPrerequisitesSyntaxParameterssec:wci.adddimvalueparameter.resultExampleSee Alsowci.addFunctionValueParametersec:wci.addfunctionvalueparameter.prereqSyntaxParametersExpected Resultsec:wci.addfunctionvalueparameter.exampleSee Alsosec:wci.addlevelparameterusagePrerequisitesSyntaxParameterssec:wci.addlevelparameterusage.resultExampleSee Alsowci.addMeasuresec:wci.addmeasure.prereqSyntaxsec:wci.addmeasure.parametersExpected ResultExampleSee Alsosec:wci.addmeasurelevelparameterPrerequisitesSyntaxParameterssec:wci.addmeasurelevelparameter.resultExamplesec:wci.addmeasurelevelparamater.seewci.addMeasureValueParameterPrerequisitesSyntaxsec:wci.addmeasurevalueparameter.parametersExpected ResultExampleSee Alsosec:wci.addparameterfunctiontypePrerequisitesSyntaxParameterssec:wci.addparameterfunctiontype.resultExamplesec:wci.addparameterfunctiontype.seewci.addPlacePointPrerequisitesSyntaxsec:wci.addplacepoint.parametersExpected ResultExampleSee Alsosec:wci.addplacepolygonPrerequisitesSyntaxParameterssec:wci.addplacepolygon.resultExampleSee Alsowci.addPlacerRegularGridsec:wci.addplaceregulargrid.prereqSyntaxParametersExpected Resultsec:wci.addplaceregulargrid.exampleSee Alsosec:wci.addsridPrerequisitesSyntaxParameterssec:wci.addsrid.resultExampleSee Alsowci.addUnitsec:wci.addunit.prereqSyntaxParametersExpected Resultsec:wci.addunit.exampleSee Alsowci.addValueParameterUsagePrerequisitessec:wci.addvalueparameterusage.syntaxParametersExpected ResultExamplesec:wci.addvalueparameterusage.seewci.addWciUserPrerequisitesSyntaxsec:wci.addwciuser.parametersExpected ResultExampleSee Alsosec:wci.beginPrerequisitessec:wci.begin.syntaxParametersExpected ResultExamplesec:wci.begin.seewci.browsePrerequisitesSyntaxsec:wci.browse.parametersExpected ResultExampleSee Alsosec:wci.configurationPrerequisitesSyntaxParameterssec:wci.configuration.resultExampleSee Alsowci.endsec:wci.end.prereqSyntaxParametersExpected Resultsec:wci.end.exampleSee Alsowci.fetchPrerequisitessec:wci.fetch:syntaxParametersExpected ResultExamplessec:wci.fetch:seewci.getCodeLevelParameterPrerequisitesSyntaxsec:wci.getcodelevelparameter.parametersExpected ResultExampleSee Alsosec:wci.getcodevalueparameterPrerequisitesSyntaxParameterssec:wci.getcodevalueparameter.resultExampleSee Alsowci.getDataProvidersec:wci.getdataprovider.prereqSyntaxParametersExpected Resultsec:wci.getdataprovider.exampleSee Alsowci.getDataProviderNamePrerequisitessec:wci.getdataprovidername.syntaxParametersExpected ResultExamplesec:wci.getdataprovidername.seewci.getDimensionlessValueParameterPrerequisitesSyntaxsec:wci.getdimensionlessvalueparameter.parametersExpected ResultExampleSee Alsosec:wci.getfunctionvalueparameterPrerequisitessec:wci.getfunctionvalueparameter.syntaxParametersExpected ResultExamplesec:wci.getfunctionvalueparameter.seewci.getLevelParameterPrerequisitesSyntaxsec:wci.getlevelparameter.parametersExpected ResultExampleSee Alsosec:wci.getlevelparameterusagePrerequisitesSyntaxParameterssec:wci.getlevelparameterusage.resultExampleSee Alsowci.getMeasuresec:wci.getmeasure.prereqSyntaxsec:wci.getmeasure.parametersExpected ResultExampleSee Alsosec:wci.getmeasurelevelparameterPrerequisitesSyntaxParameterssec:wci.getmeasurelevelparameter.resultExamplesec:wci.getmeasurelevelparameter.seewci.getMeasureValueParameterPrerequisitesSyntaxsec:wci.getmeasurevalueparameter.parametersExpected ResultExampleSee Alsosec:wci.getparameterfunctiontypePrerequisitesSyntaxParameterssec:wci.getparameterfunctiontype.resultExamplesec:wci.getparameterfunctiontype.seewci.getPlaceDefinitionPrerequisitesSyntaxsec:wci.getplacedefinition.parametersExpected ResultExampleSee Alsosec:wci.getplacenamePrerequisitessec:wci.getplacename.syntaxParametersExpected ResultExamplesec:wci.getplacename.seewci.getPlacePointPrerequisitesSyntaxsec:wci.getplacepoint.parametersExpected ResultExampleSee Alsosec:wci.getplaceregulargridPrerequisitesSyntaxParameterssec:wci.getplaceregulargrid.resultExampleSee Alsowci.getSridsec:wci.getsrid.prereqSyntaxsec:wci.getsrid.parametersExpected ResultExampleSee Alsosec:wci.getunitPrerequisitesSyntaxParameterssec:wci.getunit.resultExampleSee Alsowci.getValueParametersec:wci.getvalueparameter.prereqSyntaxParametersExpected Resultsec:wci.getvalueparameter.exampleSee Alsowci.readPrerequisitessec:wci.read:syntaxParametersExpected ResultExamplessec:wci.read:seewci.setDataProviderNamePrerequisitesSyntaxsec:wci.setdataprovidername.parametersExpected ResultExampleSee Alsosec:wci.setlevelparameternamePrerequisitesSyntaxParameterssec:wci.setlevelparametername.resultExampleSee Alsowci.setPlaceNamesec:wci.setplacename.prereqSyntaxParametersExpected Resultsec:wci.setplacename.exampleSee Alsowci.setValueParameterNamePrerequisitessec:wci.setvalueparametername.syntaxParametersExpected ResultExamplesec:wci.setvalueparametername.seewci.versionPrerequisitesSyntaxsec:wci.version:parametersExpected ResultExamplesSee Alsoid2900563PrerequisitesSyntaxParametersExpected ResultSee Also

The following sections provide a list of the functions available for usage through the WDB Call Interface.

wci.addCodeLevelParameter

The function wci.addCodeLevelParameter allows an administrator to add new Level Parameters representing code tables to the WDB system.

Prerequisites

The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group.

Syntax

wci.addcodelevelparameter
(
parameterName	text,
parameterReference	text
)

Parameters

Tableï¿½4.1.ï¿½wci.addCodeLevelParameter parameters

Parameter	Description
parameterName	The canonical parameter name to be used for the code table (i.e., the parameter name set in the default name space. Ideally, this should be a universally unique name or code.
parameterReference	Reference information for the code table.

Expected Result

The ParameterId (key reference number).

Example

An example adding the 'hybrid level' code parameter from WMO:

SELECT wci.addcodelevelparameter ( 'hybrid level', 'WMO Code Table 3, WMO publication no. 306 - Manual on Code' );

See Also

wci.addmeasurelevelparameter

wci.getcodelevelparameter

wci.getlevelparameter

wci.getmeasurelevelparameter

wci.addCodeValueParameter

The function wci.addCodeValueParameter allows an administrator to add new Value Parameters representing code tables to the WDB system.

Prerequisites

The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group.

Syntax

wci.addcodevalueparameter
(
parameterName	text,
parameterReference	text
)

Parameters

Tableï¿½4.2.ï¿½wci.addCodeValueParameter parameters

Parameter	Description
parameterName	The canonical parameter name to be used for the code table (i.e., the parameter name set in the default name space. Ideally, this should be a universally unique name or code.
parameterReference	Reference information for the code table.

Expected Result

The ParameterId (key reference number).

Example

An example adding the 'yr weather symbol' code parameter from www.yr.no:

SELECT wci.addcodevalueparameter ( 'yr weather symbol', 'http://www.yr.no' );

See Also

wci.addparameterfunctiontype

wci.getcodevalueparameter

wci.getvalueparameter

wci.getparameterfunctiontype

wci.addDataProvider

The function wci.addDataProvider allows an administrator to add a new Data Provider to the WDB system.

Prerequisites

The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group.

Syntax

wci.adddataprovider
(
dataProviderName	text,
dataProviderType	text,
domainDelivery	text,
dataProviderComment	text
)

Parameters

Tableï¿½4.3.ï¿½wci.addDataProvider parameters

Parameter	Description
dataProviderName	The canonical data provider name to be used (i.e., the data provider name set in the default name space. Ideally, this should be a universally unique name or code.
dataProviderType	The type of the data provider. Currently, this may be one of the following: * Aeroplane * Computer System * Data Provider Group * Named Observation Site * Person * Ship * WCI User
domainDelivery	The domain of the data delivered by the data provider. A precise domain definition helps the database to optimize the queries. The options are: * Any * Grid * Point
dataprovidercomment	Supplementary information about the dataprovider.

Expected Result

The DataProviderId (key reference number).

Example

An example setting up the data provider “michael” who provides point data:

SELECT wci.adddataprovider ( 'michael', 'Person', 'Point', 'Editor of point forecasts' );

Adding a new model to the database:

SELECT wci.adddataprovider( 'longyear', 'Computer System', 'Grid', 'Model generated from longyearbyen' );

See Also

wci.adddataprovidertogroup

wci.addwciuser

wci.getdataprovider

wci.getdataprovidername

wci.setdataprovidername

wci.addDataProviderToGroup

The function wci.addDataProviderToGroup allows an administrator to add a specified data provider to a data provider group in WDB.

Prerequisites

The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group.

Syntax

wci.adddataprovidertogroup
(
dataProviderName	text,
dataProviderGroup	text
)

Parameters

Tableï¿½4.4.ï¿½wci.addDataProviderToGroup parameters

Parameter	Description
dataProviderName	The data provider name to be added to the specified group.
dataProviderGroup	The data provider group that you want to add this data provider name to.

Expected Result

The DataProviderId (key reference number) of the assigned data provider.

Example

An example setting the data provider “michael” into group 'metno':

SELECT wci.adddataprovidertogroup ( 'michael', 'metno' );

See Also

wci.adddataprovider

wci.addwciuser

wci.getdataprovider

wci.getdataprovidername

wci.setdataprovidername

wci.addDimensionlessValueParameter

The function wci.addDimensionlessValueParameter allows an administrator to add new Value Parameters without a physical dimension to the WDB system.

Prerequisites

The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group.

Syntax

wci.adddimensionlessvalueparameter
(
parameterName	text,
parameterDescription	text
)

Parameters

Tableï¿½4.5.ï¿½wci.addDimensionlessValueParameter parameters

Parameter	Description
parameterName	The canonical parameter name to be used for the measure table (i.e., the parameter name set in the default name space. Ideally, this should be a universally unique name or measure.
parameterDescription	A description of the value parameter.

Expected Result

The ParameterId (key reference number).

Example

An example adding the 'land cover' value parameter from WMO:

SELECT wci.adddimensionlessvalueparameter ( 'land cover', 'Proportion of grid cell covered by land (WMO)' );

See Also

wci.getvalueparameter

wci.addFunctionValueParameter

The function wci.addFunctionValueParameter allows an administrator to add new function value parameters to the WDB system.

Prerequisites

The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group.

Syntax

wci.addfunctionvalueparameter
(
parameterUsage	text,
parameterUnit	text,
parameterFunction	text,
parameterQuantity	text
)

Parameters

Tableï¿½4.6.ï¿½wci.addFunctionValueParameter parameters

Parameter	Description
parameterUsage	The usage dimension of the value parameter.
parameterUnit	The SI unit of the value parameter. The unit is used to determine the physical dimension of the function value parameter.
parameterFunction	The function of the value parameter.
parameterQuantity	The quantity type of the value parameter; either scalar or vector.

Expected Result

The ParameterId (key reference number).

Example

An example adding the 'mean wind waves duration' value parameter to the database:

SELECT wci.addfunctionvalueparameter ( 'wind waves', 's', 'mean', 'scalar' );

See Also

wci.getvalueparameter

wci.addLevelParameterUsage

The function wci.addLevelParameterUsage allows an administrator to add new Level Parameter usages to the WDB system.

Prerequisites

The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group.

Syntax

wci.addlevelparameterusage
(
levelParameterUsage	text,
levelDescription	text
)

Parameters

Tableï¿½4.7.ï¿½wci.addLevelParameterUsage parameters

Parameter	Description
levelParameterUsage	A usage dimension for a level parameter.
levelDescription	A description of the usage dimensions.

Expected Result

None.

Example

An example adding the 'height above ground' level usage to the database:

SELECT wci.addlevelparameterusage ( 'height above ground',
'Denotes the height level of the value-' );

See Also

wci.getlevelparameterusage

wci.addMeasure

The function wci.addMeasure allows an administrator to add new measures (e.g., physical dimensions) to the WDB system.

Prerequisites

The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group.

Syntax

wci.addmeasure
(
measure	character varying,
distancepower	integer,
masspower	integer,
timepower	integer,
luminositypower	integer,
electriccurrentpower	integer,
temperaturepower	integer,
substanceamountpower	integer,
anglepower	integer
)

Parameters

Tableï¿½4.8.ï¿½wci.addmeasure parameters

Parameter	Description
measure	The measure being described.
distancepower	The distance dimension of the measure. Use 0 to denote none.
masspower	The mass dimension of the measure. Use 0 to denote none.
timepower	The time dimension of the measure. Use 0 to denote none.
luminositypower	The luminosity dimension of the measure. Use 0 to denote none.
electriccurrentpower	The electric current dimension of the measure. Use 0 to denote none.
temperaturepower	The temperature dimension of the measure. Use 0 to denote none.
substancepower	The substance dimension of the measure. Use 0 to denote none.
anglepower	The angular dimension of the measure. Use 0 to denote none.

Expected Result

None.

Example

An example adding 'acceleration' measure to the database:

SELECT wci.addmeasure ( 'acceleration', 1, 0, -2, 0, 0, 0, 0, 0 );

See Also

wci.getmeasure

wci.addMeasureLevelParameter

The function wci.addMeasureLevelParameter allows an administrator to add new level parameters based on measures to the WDB system.

Prerequisites

The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group.

Syntax

wci.addmeasurelevelparameter
(
parameterUsage	text,
parameterUnit	text
)

Parameters

Tableï¿½4.9.ï¿½wci.addMeasureLevelParameter parameters

Parameter	Description
parameterUsage	The usage dimension of the level parameter.
parameterUnit	The SI unit of the level parameter. The unit is used to determine the physical dimension of the measure value parameter.

Expected Result

The ParameterId (key reference number).

Example

An example adding the 'isobaric surface pressure' level parameter to the database:

SELECT wci.addmeasurelevelparameter ( 'isobaric surface', 'Pa' );

See Also

wci.getlevelparameter

wci.addMeasureValueParameter

The function wci.addMeasureValueParameter allows an administrator to add new value parameters based on measures to the WDB system.

Prerequisites

The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group.

Syntax

wci.addmeasurevalueparameter
(
parameterUsage	text,
parameterUnit	text,
parameterQuantity	text
)

Parameters

Tableï¿½4.10.ï¿½wci.addMeasureValueParameter parameters

Parameter	Description
parameterUsage	The usage dimension of the value parameter.
parameterUnit	The SI unit of the value parameter. The unit is used to determine the physical dimension of the measure value parameter.
parameterQuantity	The quantity type of the value parameter.

Expected Result

The ParameterId (key reference number).

Example

An example adding the 'air temperature' value parameter to the database:

SELECT wci.addmeasurevalueparameter ( 'air', 'K', 'scalar' );

See Also

wci.addmeasure

wci.getmeasurevalueparameter

wci.addParameterFunctionType

The function wci.addParameterFunctionType allows an administrator to add new function types to be used with value parameters to the WDB system.

Prerequisites

The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group.

Syntax

wci.addparameterfunctiontype
(
parameterFunctionType	text,
parameterFunctionDescription	text
)

Parameters

Tableï¿½4.11.ï¿½wci.addParameterFunctionType parameters

Parameter	Description
parameterFunctionType	The name of the function type being defined for value parameters.
parameterFunctionDescription	A description of the parameter function.

Expected Result

None.

Example

An example adding the 'max' function type to the database:

SELECT wci.addparameterfunctiontype ( 'max',
'Maximum value for the period specified by the valid time interval' );

See Also

wci.getfunctionvalueparameter

wci.addPlacePoint

The function wci.addPlacePoint allows an administrator to add a new place definition for a point to the WDB system.

Prerequisites

The user must have write privileges on the database.

Syntax

wci.addplacepoint
(
placeName	text,
placeGeometry	text
)

Parameters

Tableï¿½4.12.ï¿½wci.addPlacePoint parameters

Parameter	Description
placeName	The name (in the defined namespace) of the Point to be insered into the database. Note that the placeName will be replaced by a canonical placeName if the currently selected place name space is the zero (WDB core) name space.
placeGeometry	The point geometry to be inserted into the place definition tables.

Expected Result

The PlaceId (key reference number).

Example

An example setting up the place point “karasjok”:

SELECT wci.addplacepoint ( 'karasjok', geomfromtext('POINT( 25.51 69.47 )') );

Adding this point to the database while logged into a place name space other than zero, will add a point with the place name of 'karasjok' to the database and a canonical name in the zero name space. If the user was logged into the zero name space, only the canonical name would be added to the database.

See Also

wci.addplacepolygon

wci.addplaceregulargrid

wci.addsrid

wci.getplacedefinition

wci.getplacename

wci.getplacepoint

wci.getplaceregulargrid

wci.getsrid

wci.setplacename

wci.addPlacePolygon

The function wci.addPlacePolygon allows an administrator to add a new place definition for a polygon to the WDB system.

Prerequisites

The user must have write privileges on the database.

Syntax

wci.addplacepolygon
(
placeName	text,
placeGeometry	text
)

Parameters

Tableï¿½4.13.ï¿½wci.addPlacePolygon parameters

Parameter	Description
placeName	The name (in the defined namespace) of the Polygon to be insered into the database. Note that the placeName will be replaced by a canonical placeName if the currently selected place name space is the zero (WDB core) name space.
placeGeometry	The point geometry to be inserted into the place definition tables.

Expected Result

The PlaceId (key reference number).

Example

An example setting up a polygon for “square at nowhere”:

SELECT wci.addplaceplygon ( 'square at nowhere',
geomfromtext('POLYGON(() 10.0 61.3, 10.1 61.3, 10.1 61.4, 10.0 61.4, 10.0 61.3 ))') );

Adding this polygon to the database while logged into a place name space other than zero, will add a point with the place name of 'square at nowhere' to the database and a canonical name in the zero name space. If the user was logged into the zero name space, only the canonical name would be added to the database.

See Also

wci.addplacepoint

wci.addplaceregulargrid

wci.addsrid

wci.getplacedefinition

wci.getplacename

wci.getplacepoint

wci.getplaceregulargrid

wci.getsrid

wci.setplacename

wci.addPlacerRegularGrid

The function wci.addPlaceRegularGrid allows an administrator to add a new place definition for a regular grid to the WDB system.

Prerequisites

The user must have write privileges on the database.

Syntax

wci.addplaceregulargrid
(
placeName	text,
numX	int,
numY	int,
incX	float,
incY	float,
startX	float,
startY	float,
projection	text
)

Parameters

Tableï¿½4.14.ï¿½wci.addPlaceRegularGrid parameters

Parameter	Description
placeName	The name (in the defined namespace) of the grid to be insered into the database. Note that the placeName will be replaced by a canonical placeName if the currently selected place name space is the zero (WDB core) name space.
numX	The number of points along the X axis of the grid.
numY	The number of points along the Y axis of the grid.
incX	The distance between any two points on the X axis of the grid. The unit of measure is given by the projection.
incY	The distance between any two points on the Y axis of the grid. The unit of measure is given by the projection.
startX	The origin X point (lower left corner) of the grid in the specified projection.
startY	The origin Y point (lower left corner) of the grid in the specified projection.
projection	The original projection of the grid, which also corresponds to the form it is stored as in the database..

Expected Result

The PlaceId (key reference number).

Example

An example setting up the hirlam 10km grid:

SELECT wci.addplaceregulargrid ( 'hirlam 10km grid', 248, 400, 0.100, 0.100, 5.75, -13.25, '+proj=ob_tran +o_proj=longlat +lon_0=-40 +o_lat_p=22 +a=6367470.0 +no_defs' );

Adding this grid to the database while logged into a place name space other than zero, will add a grid with the place name of 'hirlam 10km grid' to the database and a canonical name in the zero name space. If the user was logged into the zero name space, only the canonical name would be added to the database.

See Also

wci.addplacepoint

wci.addsrid

wci.getplacedefinition

wci.getplacename

wci.getplacepoint

wci.getplaceregulargrid

wci.getsrid

wci.setplacename

wci.addSrid

The function wci.addSrid allows an administrator to add a new SRID definition to WDB.

Prerequisites

The user must have write privileges on the database.

Syntax

wci.addsrid
(
name	text,
projection	text
)

Parameters

Tableï¿½4.15.ï¿½wci.addSrid parameters

Parameter	Description
name	A descriptive name for the projection.
projection	The Proj.4 definition of the projection. To avoid duplicates, the Proj.4 definition should avoid unnecessary spacing and be ended with +no_defs. It is advised to manually check the spatial_ref_sys table (using wci.getSrid) before adding new entries.

Expected Result

The SRID (spatial reference id).

Example

An example setting up the SRID of the Hirlam 10 grid (a rotated, longitude/latitude projection:

SELECT wci.addsrid ( 'Hirlam 10 SRID',
'+proj=ob_tran +o_proj=longlat +lon_0=-40 +o_lat_p=22 +a=6367470.0 +no_defs');

See Also

wci.addplacepoint

wci.addplaceregulargrid

wci.getplacedefinition

wci.getplacename

wci.getplacepoint

wci.getplaceregulargrid

wci.getsrid

wci.setplacename

wci.addUnit

The function wci.addUnit allows an administrator to add a new unit to WDB.

Prerequisites

The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group.

Syntax

wci.addunit
(
unitname	character varying,
unittype	character varying,
measure	character varying,
description	character varying,
siunitconversioncoefficient	double,
siunitconversionterm	double
)

Parameters

Tableï¿½4.16.ï¿½wci.addUnit parameters

Parameter	Description
unitName	The UCUM designation of the unit.
unitType	The type of the unit. Permitted types are: 'SI Unit', 'Base Unit', and 'Conventional Unit'. Most units should be defined as the latter.
measure	The associated measure of the unit.
description	A description of the unit. For most units, this will simply be the unabbreviated (i.e., full) form of the unit name.
siunitconversioncoefficient	The coefficient to multiply the value with in order to get the SI unit. The SI unit conversion is: (value * coefficient) + term
siunitconversionterm	The term to add to the value in order to get the SI unit. The SI unit conversion is: (value * coefficient) + term

Expected Result

None.

Example

An example adding the degree Fahrenheit to the database:

SELECT wci.addunit( '[degF]', 'Conventional Unit', 'temperature', 'degree Fahrenheit', 0.555556, 459.67 );

An example adding the Kelvin to the database:

SELECT wci.addunit( 'K', 'SI Unit', 'temperature', 'Kelvin', 1, 0 );

See Also

wci.addmeasure

wci.addValueParameterUsage

The function wci.addValueParameterUsage allows an administrator to add new Value Parameter usages to the WDB system.

Prerequisites

The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group.

Syntax

wci.addvalueparameterusage
(
valueParameterUsage	text,
valueDescription	text
)

Parameters

Tableï¿½4.17.ï¿½wci.addLevelParameterUsage parameters

Parameter	Description
valueParameterUsage	A usage dimension for a value parameter.
valueDescription	A description of the usage dimension.

Expected Result

None.

Example

An example adding the 'mean sea level' value usage to the database:

SELECT wci.addvalueparameterusage ( 'mean sea level',
'Value reduced to sea level assuming an isothermal layer at the measuring point's temperature.' );

See Also

wci.getvalueparameterusage

wci.addWciUser

The function wci.addWciuser allows an administrator to add a WCI user to the database as a data provider in WDB.

Prerequisites

The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group.

Syntax

wci.addwciuser
(
dataProviderName	text
)

Parameters

Tableï¿½4.18.ï¿½wci.addWciUser parameters

Parameter	Description
dataProviderName	The data provider name to be added to the database as a WCI user.

Expected Result

The DataProviderId (key reference number) of the inserted data provider.

Example

An example adding the wci user “michael” as a new data provider:

SELECT wci.addwciuser( 'michael' );

See Also

wci.adddataprovider

wci.adddataprovidertogroup

wci.getdataprovider

wci.getdataprovidername

wci.setdataprovidername

wci.begin

The function wci.begin initializes the WDB Call Interface for a specified user.

Prerequisites

The user must have been set up as a WDB user (i.e., have access to one of the wdb user groups

Syntax

wci.begin
(
user name,
dataproviderNameSpaceId integer,
placeNameSpaceId integer,
parameterNameSpaceId integer
)

wci.begin (
user name
)

Parameters

Tableï¿½4.19.ï¿½wci.begin parameters

Parameter	Description
user	The userid to initialize the connection with
dataprovidernamespaceid	The namespace to be used for dataprovider names in the session
placenamespaceid	The namespace to be used for place names in the session
parameternamespaceid	The namespace to be used for parameter names in the session

Expected Result

No return expected.

Example

An example setting up the user “michael” with the data provider and parameter name spaces associated with the code 1, while retaining use of the default place names:

SELECT wci.begin ( 'michael', 1, 0, 1 );

Note that the default namespaces can be defined by the WDB administrator. Consequently, the user may frequently want to just install using this namespace, which would be done with the following wci.begin call:

SELECT wci.begin ( 'michael' );

See Also

wci.end

wci.browse

The wci.browse function is utilized to browse the meteorological, hydrological and oceanographic data in the database. Essentially, it can be used to retrieve summary data about what data values exist in the database. The function takes as input the same search parameters as the wci.read call, but returns summarized rather than detailed data about the values in the database. Using wci.browse will usually be significantly faster than performing a similar wci.read call followed by aggregation.

The function is overloaded, and exists in many different versions, depending on the return type required.

Prerequisites

The user must have access to group role wdb_read

The user must have called wci.begin

Syntax

wci.browse
(
dataProviders ARRAY[text],
place text,
referenceTime text,
validtime text,
parameters ARRAY[text],
level text,
dataVersions ARRAY[integer],
returnType wci.browsedataprovider
)

wci.browse
(
returnType wci.browsedataprovider
)

wci.browse
(
dataProviders ARRAY[text],
place text,
referenceTime text,
validtime text,
parameters ARRAY[text],
level text,
dataVersions ARRAY[integer],
returnType wci.browseplace
)

wci.browse
(
returnType wci.browseplace
)

wci.browse
(
dataProviders ARRAY[text],
place text,
referenceTime text,
validtime text,
parameters ARRAY[text],
level text,
dataVersions ARRAY[integer],
returnType wci.browsereferencetime
)

wci.browse
(
returnType wci.browsereferencetime
)

wci.browse
(
dataProviders ARRAY[text],
place text,
referenceTime text,
validtime text,
parameters ARRAY[text],
level text,
dataVersions ARRAY[integer],
returnType wci.browsevalidtime
)

wci.browse
(
returnType wci.browsevalidtime
)

wci.browse
(
dataProviders ARRAY[text],
place text,
referenceTime text,
validtime text,
parameters ARRAY[text],
level text,
dataVersions ARRAY[integer],
returnType wci.browsevalueparameter
)

wci.browse
(
returnType wci.browsevalueparameter
)

wci.browse
(
dataProviders ARRAY[text],
place text,
referenceTime text,
validtime text,
parameters ARRAY[text],
level text,
dataVersions ARRAY[integer],
returnType wci.browselevelparameter
)

wci.browse
(
returnType wci.browselevelparameter
)

Parameters

All the wci.browse input parameters, except the returnType, are precisely the same as the input paramaters to a wci.read call (see Section the section called â€œParametersâ€). Calling a function with only the “returnType” parameter specified is basically equivalent to calling the wci.browse function with all NULLs (indicating that all data is required). Be aware that trying to retrieve aggregates about all the data in a huge database can take a while.

The returnType specifies which of the six different types of summarized metadata the user wants to retrieve.

Expected Result

Depending on the returnType specified:

wci.browsedataproviderThis returns a list of the data providers that exist in the database for the parameter definitions given in the wci.browse call and the utilized namespace. For each dataprovider, the number of data records and the earliest and latest referencetimes that exist for that data value is also listed.

wci.browseplaceThis returns a list of the place definitions that exist in the database for the parameter definitions given by the wci.browse call and the used namespace. For each place definition, the number of data records in the database are listed.

wci.browsereferencetimeThis returns a list of the referencetimes that exist in the database for the parameter definitions given by the wci.browse call. For each referencetime, the number of data records in the database are listed.

wci.browsevalidtimeThis returns a list of the validtimes that exist in the database for the parameter definitions given by the wci.browse call. For each validtime, the number of data records in the database are listed.

wci.browsevalueparameterThis returns a list of the value parameters that exist in the database for the parameter definitions given by the wci.browse call and the used namespace. For each valueparameter, the number of data records in the database are listed.

wci.browselevelparameterThis returns a list of the level parameters that exist in the database for the parameter definitions given by the wci.browse call and the utilized namespace. For each level parameter, the number of data records in the database are listed.

Example

The following browse query could be used to retrieve the data provider names of all data providers in the database.

SELECT * FROM wci.browse ( NULL::wci.browsedataprovider );

The user might then utilize a result from this query to ask a follow-up determining the reference times of a specific data provider.

SELECT * FROM wci.browse ( ARRAY[ 'hirlam' ],
NULL, NULL, NULL, NULL, NULL, NULL,
NULL::wci.browsereferencetime );

The results from this query (a list of referencetimes), can then be used to drill down further into the data mass of the database. The following example retrieves the list of parameters for the given data provider and reference time.

SELECT * FROM wci.browse ( ARRAY[ 'hirlam' ], NULL,
'exact 1980-03-15 12:00:00+00',
NULL, NULL, NULL, NULL,
NULL::wci.browsevalueparameter );

See Also

wci.read

wci.configuration

The wci.configuration function returns all configuration information (i.e., the complete list of all versions installed) for the WDB database.

Prerequisites

The user must have read access to the database.

Syntax

wci.configuration
(
)

Parameters

None.

Expected Result

Configuration information.

Tableï¿½4.20.ï¿½wci.configuration return row

Attribute	Description
name	The name of the software package.
softwareversion	The version of the software.
packageversion	The version of the package; this is a sequential number independent of the software version.
description	A description of the software package.
installtime	The time when this version of WDB was installed.

Example

An example to extract the configuration of the database:

SELECT wci.configuration ( );

See Also

wci.version

wci.end

The function wci.end unsets any settings and frees up resources that may have been initialized by wci.begin.

Prerequisites

None.

Syntax

wci.end
(
)

Parameters

None.

Expected Result

No return expected.

Example

The wci.end function is just a simple functional call:

SELECT wci.end ( );

See Also

wci.begin

wci.fetch

wci.fetch is the function used to retrieve binary data values from the database. The function takes a binary object ID returned by a wci.read call and returns a row containing the binary data (as bytea data) as well as additional relevant information required for the manipulation of the binary data.

The returned binary data should be interpreted as 4-byte floats. Some of the data may have the value not-a-number. This means that that particular point does not have any defined value.

Prerequisites

The user must have a valid object ID that references a grid

The user must have access to group role wdb_read

The user must have called wci.begin

Syntax

wci.fetch
(
objectid bigint,
returnType wci.grid
)

Parameters

Tableï¿½4.21.ï¿½wci.fetch parameters

Parameter	Description
objectid	The object ID of the binary object to be returned, as given by a wci.read call
returnType	What type of data the user wants returned

Expected Result

Currently, the function always returns a:

wci.grid

Examples

The following query returns the grid referenced as 11702:

SELECT *
FROM wci.fetch ( 11702,
NULL::wci.grid -- Return type
)

The result is a single row containing the binary data of the grid itself (as a bytea), in addition to the number of points along the x and y axis of the grid, the distance between grid increments, the starting positions of the x and y points in the original projection, and the PROJ.4 string defining the original projection of the grid.

See Also

wci.read

wci.write

wci.getCodeLevelParameter

The function wci.getCodeLevelParameter returns information about the specified level parameter of the code type to the user.

Prerequisites

The user must have read access to the database.

Syntax

wci.getcodelevelparameter
(
parameter	text
)

Parameters

Tableï¿½4.22.ï¿½wci.getCodeLevelParameter parameters

Parameter	Description
parameter	The name of the parameter to be returned. NULL returns all level parameters in the namespace. PostgreSQL wild cards (used in LIKE statements) may be used.

Expected Result

A row of data describing the level parameter in the namespace.

Tableï¿½4.23.ï¿½wci.getCodeLevelParameter return row

Attribute	Description
levelparameterid	The internal parameter ID used in WDB.
levelcodeparametername	The canonical name of the level parameter.
codeparameterreference	The reference information for the level code.
parameternamespaceid	The parameter name space ID of the query.
levelparametername	The name of the level parameter in the current namespace. If the query is in the 0 (canonical) namespace, this will be the canonical level parameter name.

Example

An example to get information about code “hybrid level”:

SELECT wci.getcodelevelparameter ( 'hybrid level' );

To retrieve information about all code level parameters starting with “hybrid”:

SELECT wci.getcodelevelparameter ( 'hybrid%' );

See Also

wci.addcodelevelparameter

wci.getCodeValueParameter

The function wci.getCodeValueParameter returns information about the specified value parameter of the code type to the user.

Prerequisites

The user must have read access to the database.

Syntax

wci.getcodevalueparameter
(
parameter	text
)

Parameters

Tableï¿½4.24.ï¿½wci.getCodeValueParameter parameters

Parameter	Description
parameter	The name of the parameter to be returned. NULL returns all value parameters in the namespace. PostgreSQL wild cards (used in LIKE statements) may be used.

Expected Result

A row of data describing the value parameter in the namespace.

Tableï¿½4.25.ï¿½wci.getCodeValueParameter return row

Attribute	Description
valueparameterid	The internal parameter ID used in WDB.
valuecodeparametername	The canonical name of the value parameter.
codeparameterreference	The reference information for the value code.
parameternamespaceid	The parameter name space ID of the query.
valueparametername	The name of the value parameter in the current namespace. If the query is in the 0 (canonical) namespace, this will be the canonical value parameter name.

Example

An example to get information about code “ice presence”:

SELECT wci.getcodevalueparameter ( 'ice presence' );

To retrieve information about all code value parameters starting with “ice”:

SELECT wci.getcodevalueparameter ( 'ice%' );

See Also

wci.addcodevalueparameter

wci.getDataProvider

The function wci.getDataProvider returns information about the specified data provider to a user.

Prerequisites

The user must have read access to the database.

Syntax

wci.getdataprovider
(
dataProviderName	text
)

Parameters

Tableï¿½4.26.ï¿½wci.getDataProvider parameters

Parameter	Description
dataProviderName	The data provider name to be added to be returned. NULL returns all data providers in the namespace. PostgreSQL wild cards (used in LIKE statements) may be used.

Expected Result

A row of data describing the Data Provider in the namespace.

Tableï¿½4.27.ï¿½wci.getDataProvider return row

Attribute	Description
dataproviderid	The internal data provider ID used in WDB.
dataprovidertype	The type classification of the data provider in WDB.
spatialdomaindelivery	The spatial domain of data delivered by this data provider; either point data, gridded data, or both.
dataprovidernamespaceid	The currently selected data provider name space.
dataprovidername	The data provider name of the data provider in this namespace.
dataprovidernameleftset	An internal WDB code used for grouping.
dataprovidernamerightset	An internal WDB code used for grouping.
dataproviderstoretime	The store time of this data provider; i.e., when it was inserted into the database.
dataprovidercomment	Additional description or comment about the data provider.

Example

An example to get information about data provider “michael”:

SELECT wci.getdataprovider ( 'michael' );

To retrieve information about all data providers starting with “mich”:

SELECT wci.getdataprovider ( 'mich%' );

See Also

wci.adddataprovider

wci.adddataprovider2group

wci.addwciuser

wci.getdataprovidername

wci.setdataprovidername

wci.getDataProviderName

The function wci.getDataProviderName lists the data provider names in the namespace that match the search criteria.

Prerequisites

The user must have read access to the database.

Syntax

wci.getdataprovidername
(
dataprovidername	text
)

Parameters

Tableï¿½4.28.ï¿½wci.getDataProviderName parameters

Parameter	Description
dataProviderName	The data provider name for which information is requested. NULL returns all data providers in the namespace. PostgreSQL wild cards (used in LIKE statements) may be used.

Expected Result

The list of data provider names.

Tableï¿½4.29.ï¿½wci.getDataProviderName return row

Attribute	Description
dataproviderid	The internal data provider ID used in WDB.
dataprovidernamespaceid	The currently selected data provider name space.
dataprovidername	The data provider name of the data provider in this namespace.

Example

An example to list the data provider matching the name “michael”:

SELECT wci.getdataprovidername ( 'michael' );

List all data providers starting on “mich” in the name space:

SELECT wci.getdataprovidername ( 'mich%' );

See Also

wci.adddataprovider

wci.adddataprovider2group

wci.addwciuser

wci.getdataprovider

wci.setdataprovidername

wci.getDimensionlessValueParameter

The function wci.getDimensionlessValueParameter returns information about the specified value parameter of the dimensionless type to the user.

Prerequisites

The user must have read access to the database.

Syntax

wci.getdimensionlessvalueparameter
(
parameter	text
)

Parameters

Tableï¿½4.30.ï¿½wci.getDimensionlessValueParameter parameters

Parameter	Description
parameter	The name of the parameter to be returned. NULL returns all value parameters in the namespace. PostgreSQL wild cards (used in LIKE statements) may be used.

Expected Result

A row of data describing the value parameter in the namespace.

Tableï¿½4.31.ï¿½wci.getDimensionlessValueParameter return row

Attribute	Description
valueparameterid	The internal parameter ID used in WDB.
valuedimensionlessparametername	The canonical name of the value parameter.
valueparameterdescription	A description of the value parameter.
valueunitname	The unit of the value parameter.
parameternamespaceid	The parameter name space ID of the query.
valueparametername	The name of the value parameter in the current namespace. If the query is in the 0 (canonical) namespace, this will be the canonical value parameter name.

Example

An example to get information about the parameter “land albedo”:

SELECT wci.getdimensionlessvalueparameter ( 'land albedo' );

To retrieve information about all code value parameters starting with “land”:

SELECT wci.getdimensionlessvalueparameter ( 'land%' );

See Also

wci.adddimensionlessvalueparameter

wci.getFunctionValueParameter

The function wci.getFunctionValueParameter returns information about the specified value parameter of the function type to the user.

Prerequisites

The user must have read access to the database.

Syntax

wci.getfunctionvalueparameter
(
parameter	text
)

Parameters

Tableï¿½4.32.ï¿½wci.getFunctionValueParameter parameters

Parameter	Description
parameter	The name of the parameter to be returned. NULL returns all value parameters in the namespace. PostgreSQL wild cards (used in LIKE statements) may be used.

Expected Result

A row of data describing the value parameter in the namespace.

Tableï¿½4.33.ï¿½wci.getfunctionValueParameter return row

Attribute	Description
valueparameterid	The internal parameter ID used in WDB.
parameterfunctiontype	The parameter function.
valueparameterusage	The value parameter usage.
parameterquantitytype	The quantity type of the value parameter.
measure	The measure of the value parameter.
valueunitname	The unit name used for the value parameter.
parameternamespaceid	The parameter name space ID of the query.
valueparametername	The name of the value parameter in the current namespace. If the query is in the 0 (canonical) namespace, this will be the canonical value parameter name.

Example

An example to get information about the parameter “peak wave duration”:

SELECT wci.getfunctionvalueparameter ( 'peak wave duration' );

To retrieve information about all value parameters starting with “peak”:

SELECT wci.getfunctionvalueparameter ( 'peak%' );

See Also

wci.addfunctionvalueparameter

wci.getLevelParameter

The function wci.getLevelParameter returns information about the specified level parameter of the function type to the user.

Prerequisites

The user must have read access to the database.

Syntax

wci.getlevelparameter
(
parameter	text
)

Parameters

Tableï¿½4.34.ï¿½wci.getLevelParameter parameters

Parameter	Description
parameter	The name of the parameter to be returned. NULL returns all value parameters in the namespace. PostgreSQL wild cards (used in LIKE statements) may be used.

Expected Result

A row of data describing the level parameters in the namespace.

Tableï¿½4.35.ï¿½wci.getlevelParameter return row

Attribute	Description
levelparameterid	The internal parameter ID used in WDB.
parameternamespaceid	The parameter name space ID of the query.
levelparametername	The name of the level parameter in the current namespace. If the query is in the 0 (canonical) namespace, this will be the canonical value parameter name.
levelunitname	The unit of the level parameter.

Example

An example to get information about the level parameter “hybrid level”:

SELECT wci.getlevelparameter ( 'hybrid level' );

To retrieve information about all level parameters with “hybrid”:

SELECT wci.getlevelparameter ( '%hybrid%' );

See Also

wci.addcodelevelparameter

wci.addmeasurelevelparameter

wci.getlevelparameterusage

The function wci.getlevelparameterusage returns information about the specified level parameter usage to the user.

Prerequisites

The user must have read access to the database.

Syntax

wci.getlevelparameterusage
(
usage	text
)

Parameters

Tableï¿½4.36.ï¿½wci.getlevelparameterusage parameters

Parameter	Description
usage	The name of the parameter usage to be returned. NULL returns all parameter usages. PostgreSQL wild cards (used in LIKE statements) may be used.

Expected Result

A row of data describing the level parameter usages.

Tableï¿½4.37.ï¿½wci.getlevelparameterusage return row

Attribute	Description
levelparameterusage	The level parameter usage descriptor.
levelparameterusagedescription	A description of the level parameter usage.

Example

An example to get information about the level usage “sea surface”:

SELECT wci.getlevelparameterusage ( 'sea surface' );

To retrieve information about all level usages with “sea”:

SELECT wci.getlevelparameterusage ( '%sea%' );

See Also

wci.addlevelparameterusage

wci.getMeasure

The function wci.getMeasure returns information about the specified measure to the user.

Prerequisites

The user must have read access to the database.

Syntax

wci.getmeasure
(
measure	text
)

Parameters

Tableï¿½4.38.ï¿½wci.getmeasure parameters

Parameter	Description
measure	The name of the measure to be returned. NULL returns all measures. PostgreSQL wild cards (used in LIKE statements) may be used.

Expected Result

A row of data describing the measure.

Tableï¿½4.39.ï¿½wci.getmeasure return row

Attribute	Description
measure	The measure being described.
distancepower	The distance dimension of the measure. Use 0 to denote none.
masspower	The mass dimension of the measure. Use 0 to denote none.
timepower	The time dimension of the measure. Use 0 to denote none.
luminositypower	The luminosity dimension of the measure. Use 0 to denote none.
electriccurrentpower	The electric current dimension of the measure. Use 0 to denote none.
temperaturepower	The temperature dimension of the measure. Use 0 to denote none.
substancepower	The substance dimension of the measure. Use 0 to denote none.
anglepower	The angular dimension of the measure. Use 0 to denote none.

Example

An example to get information about the measure “distance”:

SELECT wci.getmeasure ( 'distance' );

See Also

wci.addmeasure

wci.getMeasureLevelParameter

The function wci.getmeasurelevelParameter returns information about the specified level parameter of the function type to the user.

Prerequisites

The user must have read access to the database.

Syntax

wci.getmeasurelevelparameter
(
parameter	text
)

Parameters

Tableï¿½4.40.ï¿½wci.getMeasureLevelParameter parameters

Parameter	Description
parameter	The name of the parameter to be returned. NULL returns all level parameters in the namespace. PostgreSQL wild cards (used in LIKE statements) may be used.

Expected Result

A row of data describing the level parameters in the namespace.

Tableï¿½4.41.ï¿½wci.getmeasurelevelParameter return row

Attribute	Description
levelparameterid	The internal parameter ID used in WDB.
levelparameterusage	The usage of the level parameter.
measure	The measure of the level parameter.
levelunitname	The unit of the level parameter.
parameternamespaceid	The parameter name space ID of the query.
levelparametername	The name of the level parameter in the current namespace. If the query is in the 0 (canonical) namespace, this will be the canonical value parameter name.

Example

An example to get information about the level parameter “sea surface pressure”:

SELECT wci.getmeasurelevelparameter ( 'sea surface pressure' );

To retrieve information about all level parameters with “sea”:

SELECT wci.getmeasurelevelparameter ( '%sea%' );

See Also

wci.addmeasurelevelparameter

wci.getMeasureValueParameter

The function wci.getmeasurevalueParameter returns information about the specified value parameter of the function type to the user.

Prerequisites

The user must have read access to the database.

Syntax

wci.getmeasurevalueparameter
(
parameter	text
)

Parameters

Tableï¿½4.42.ï¿½wci.getMeasurevalueParameter parameters

Parameter	Description
parameter	The name of the parameter to be returned. NULL returns all value parameters in the namespace. PostgreSQL wild cards (used in LIKE statements) may be used.

Expected Result

A row of data describing the value parameters in the namespace.

Tableï¿½4.43.ï¿½wci.getMeasurevalueParameter return row

Attribute	Description
valueparameterid	The internal parameter ID used in WDB.
valueparameterusage	The usage of the value parameter.
parameterquantitytype	The quantity type of the value parameter.
measure	The measure of the value parameter.
valueunitname	The unit of the value parameter.
parameternamespaceid	The parameter name space ID of the query.
valueparametername	The name of the value parameter in the current namespace. If the query is in the 0 (canonical) namespace, this will be the canonical value parameter name.

Example

An example to get information about the value parameter “air temperature”:

SELECT wci.getmeasurevalueparameter ( 'air temperature' );

To retrieve information about all temperature parameters:

SELECT wci.getmeasurevalueparameter ( '%temperature%' );

See Also

wci.addmeasurevalueparameter

wci.getParameterFunctionType

The function wci.getparameterfunctiontype returns information about the specified parameterfunctiontype to the user.

Prerequisites

The user must have read access to the database.

Syntax

wci.getparameterfunctiontype
(
type	text
)

Parameters

Tableï¿½4.44.ï¿½wci.getparameterfunctiontype parameters

Parameter	Description
type	The name of the parameterfunctiontype to be returned. NULL returns all types. PostgreSQL wild cards (used in LIKE statements) may be used.

Expected Result

A row of data describing the parameterfunctiontype.

Tableï¿½4.45.ï¿½wci.getparameterfunctiontype return row

Attribute	Description
parameterfunctiontype	The parameterfunctiontype being described.
parameterfunctiondescription	A description of the parameter function type.

Example

An example to get information about the parameterfunctiontype “accumulated”:

SELECT wci.getparameterfunctiontype ( 'accumulated' );

See Also

wci.addparameterfunctiontype

wci.getPlaceDefinition

The function wci.getPlaceDefinition lists the place definitions defined in the database that match the search criteria and are available in the namespace.

Prerequisites

The user must have read access to the database.

Syntax

wci.getplacedefinition
(
placename	text
)

Parameters

Tableï¿½4.46.ï¿½wci.getPlaceDefinition parameters

Parameter	Description
placename	The placename that you require information for. NULL returns all place definitions in the namespace. PostgreSQL wild cards (used in LIKE statements) may be used.

Expected Result

The list of place definitions.

Tableï¿½4.47.ï¿½wci.getPlaceDefinition return row

Attribute	Description
placeid	The internal place ID used in WDB.
placegeometrytype	The place geometry of the place definition. Currently points and grids are supported
placegeometry	The geometry of the place definition in the default SRID. Note that for regular grids, only a polygon of the four corner points is stored in this field.
placeindeterminatecode	The indeterminate code for the place definition.
placenamespaceid	The name space of the query.
placename	The place name of the place definition.
originalsrid	The original SRID of the place definition. This is particularly important to keep track of for grids.
placestoretime	The storetime of the place definition.

Example

An example to list the place definitions matching the name “oslo”:

SELECT wci.getplacedefinition ( 'oslo' );

List all place definitions starting on “os” in the name space:

SELECT wci.getplacedefinition ( 'os%' );

See Also

wci.addplacepoint

wci.addplaceregulargrid

wci.addsrid

wci.getplacename

wci.getplacepoint

wci.getplaceregulargrid

wci.getsrid

wci.setplacename

wci.getPlaceName

The function wci.getPlaceName lists the place names defined in the database that match the search criteria and are available in the namespace.

Prerequisites

The user must have read access to the database.

Syntax

wci.getplacename
(
placename	text
)

wci.getplacename
(
numberX	int,
numberY	int,
incrementX	float,
incrementY	float,
startX	float,
startY	float,
projdefinition	text
)

Parameters

Tableï¿½4.48.ï¿½wci.getPlaceName parameters

Parameter	Description
placename	The placename that you require information for. NULL returns all place names in the namespace. PostgreSQL wild cards (used in LIKE statements) may be used.
numberx	The number of points along the x axis in the regular grid.
numbery	The number of points along the y axis in the regular grid.
incrementx	The increment distance on the x axis; i.e., the distance between two adjacent points on the x axis. The unit of the attribute is given by the Proj.4, which means that it is usually either degrees (the default) or meters.
incrementy	The increment distance on the y axis.
startx	The starting point of the grid on the x axis of the original Proj.4 projection.
starty	The starting point of the grid on the y axis of the original Proj.4 projection.
projdefinition	The original PROJ.4 projection of the place definition.

Expected Result

The list of place grids.

Tableï¿½4.49.ï¿½wci.getPlaceName return row

Attribute	Description
placeid	The internal place ID used in WDB.
placenamespaceid	The name space of the query.
placename	The place name of the place definition.

Example

An example to list the placenames matching “osl”:

SELECT wci.getplacename ( 'osl%' );

List the place grid matching a set of attributes:

SELECT wci.getplacename ( 248,
400,
0.5,
0.5,
35.6,
-25.4,
"+proj=longlat +a=6367470.0 +towgs84=0,0,0 +no_defs" );

See Also

wci.addplacepoint

wci.addplaceregulargrid

wci.addsrid

wci.getplacedefinition

wci.getplacepoint

wci.getplaceregulargrid

wci.getsrid

wci.setplacename

wci.getPlacePoint

The function wci.getPlacePoint lists all the place points defined in the database that match the search criteria and are available in the namespace.

Prerequisites

The user must have read access to the database.

Syntax

wci.getplacepoint
(
placename	text
)

Parameters

Tableï¿½4.50.ï¿½wci.getPlacePoint parameters

Parameter	Description
placename	The placename that you require information for. NULL returns all place points in the namespace. PostgreSQL wild cards (used in LIKE statements) may be used.

Expected Result

The list of place points.

Tableï¿½4.51.ï¿½wci.getPlacePoint return row

Attribute	Description
placeid	The internal place ID used in WDB.
placegeometrytype	The place geometry of the place point. Currently points and grids are supported
placegeometry	The geometry of the place point.
placeindeterminatecode	The indeterminate code for the place point.
placenamespaceid	The name space of the query.
placename	The place name of the place point.
originalsrid	The original SRID of the place point.
placestoretime	The storetime of the place point.

Example

An example to list the place points matching the name “oslo”:

SELECT wci.getplacepoint ( 'oslo' );

List all place points starting on “os” in the name space:

SELECT wci.getplacepoint ( 'os%' );

See Also

wci.addplacepoint

wci.addplaceregulargrid

wci.addsrid

wci.getplacedefinition

wci.getplacename

wci.getplaceregulargrid

wci.getsrid

wci.setplacename

wci.getPlaceRegularGrid

The function wci.getPlaceRegularGrid lists the place grids defined in the database that match the search criteria and are available in the namespace.

Prerequisites

The user must have read access to the database.

Syntax

wci.getplaceregulargrid
(
placename	text
)

Parameters

Tableï¿½4.52.ï¿½wci.getPlaceRegularGrid parameters

Parameter	Description
placename	The placename that you require information for. NULL returns all place grids in the namespace. PostgreSQL wild cards (used in LIKE statements) may be used.

Expected Result

The list of place grids.

Tableï¿½4.53.ï¿½wci.getPlaceDefinition return row

Attribute	Description
placeid	The internal place ID used in WDB.
placegeometrytype	The place geometry of the place definition. Currently points and grids are supported
placegeometry	The geometry of the place definition.
placeindeterminatecode	The indeterminate code for the place definition.
placenamespaceid	The name space of the query.
placename	The place name of the place definition.
numberx	The number of points along the x axis in the regular grid.
numbery	The number of points along the y axis in the regular grid.
incrementx	The increment distance on the x axis; i.e., the distance between two adjacent points on the x axis. The unit of the attribute is given by the Proj.4, which means that it is usually either degrees (the default) or meters.
incrementy	The increment distance on the y axis.
startx	The starting point of the grid on the x axis of the original Proj.4 projection.
starty	The starting point of the grid on the y axis of the original Proj.4 projection.
originalsrid	The original SRID of the place definition. This is particularly important to keep track of for grids.
projdefinition	The original PROJ.4 projection of the place definition.
placestoretime	The storage time of the place definition.

Example

An example to list the place grid matching the name “hirlam 10 grid”:

SELECT wci.getplaceregulargrid ( 'hirlam 10 grid' );

List all place grid starting on “hirlam” in the name space:

SELECT wci.getplaceregulargrid ( 'hirlam%' );

See Also

wci.addplacepoint

wci.addplaceregulargrid

wci.addsrid

wci.getplacedefinition

wci.getplacename

wci.getplacepoint

wci.getsrid

wci.setplacename

wci.getSrid

The function wci.getSrid lists all the spatial reference ID's defined in the database that match the search criteria and are available in the namespace.

Prerequisites

The user must have read access to the database.

Syntax

wci.getsrid
(
projstr	text
)

Parameters

Tableï¿½4.54.ï¿½wci.getSrid parameters

Parameter	Description
projstr	The Proj.4 string that matches the SRID you want to retrieve. NULL returns all SRIDs in the spatial reference system table. PostgreSQL wild cards (used in LIKE statements) may be used.

Expected Result

The list of SRIDs.

Tableï¿½4.55.ï¿½wci.getSrid return row

Attribute	Description
srid	The spatial reference ID. An integer value that uniquely identifies the Spatial Referencing System (SRS) within the database.
auth_name	The name of the standard or standards body that is being cited for this reference system. For example, “EPSG” would be a valid auth_name.
auth_srid	he ID of the Spatial Reference System as defined by the Authority cited in the auth_name. For EPSG data, for example, this is the EPSD id number.
srtext	The Well-Known Text representation of the Spatial Reference System. WDB ignores this column and always inserts NULL.
proj4text	This is the Proj.4 coordinate definition string for a particular SRID.

Example

An example to list the SRID's with longitude/latitude projections:

SELECT wci.getsrid ( '%+proj=longlat%' );

See Also

wci.addplacepoint

wci.addplaceregulargrid

wci.addsrid

wci.getplacedefinition

wci.getplacename

wci.getplaceregulargrid

wci.addsrid

wci.setplacename

wci.getunit

The function wci.getunit lists all the units defined in the database that match the search criteria.

Prerequisites

The user must have read access to the database.

Syntax

wci.getunit
(
unit	text
)

Parameters

Tableï¿½4.56.ï¿½wci.getunit parameters

Parameter	Description
unit	The UCUM designation of the unit. NULL returns all units in the database. PostgreSQL wild cards (used in LIKE statements) may be used.

Expected Result

The list of units.

Tableï¿½4.57.ï¿½wci.getunit return row

Attribute	Description
unitname	The name (context-sensitive UCUM designation) of the unit.
unittype	The type of the unit.
measure	The measure of the unit, if any.
description	A description of the unit.
siunitconversioncoefficient	The coefficient to multiply the value with to get the SI unit (if any). The formula is (value * coefficient) + term
siunitconversionterm	The term to add to the value to get the SI unit (if any). The formula is (value * coefficient) + term

Example

An example to list all units with pressure (Pascal):

SELECT wci.getunit ( '%Pa%' );

See Also

wci.addunit

wci.getValueParameter

The function wci.getValueParameter lists all the value parameters defined in the database that match the search criteria.

Prerequisites

The user must have read access to the database.

Syntax

wci.getvalueparameter
(
parameter	text
)

Parameters

Tableï¿½4.58.ï¿½wci.getvalueparameter parameters

Parameter	Description
parameter	The name of the value parameter in the name space. NULL returns all value parameters in the name space. PostgreSQL wild cards (used in LIKE statements) may be used.

Expected Result

The list of valueparameters.

Tableï¿½4.59.ï¿½wci.getvalueparameter return row

Attribute	Description
valueparameterid	The internal parameter ID of the value parameter.
parameternamespaceid	The currently selected parameter name space.
valueparametername	The name of the valueparameter in the name space.
valueparameterunit	The unit of measure of the value parameter.

Example

An example to list all value parameters based on temperature:

SELECT wci.getvalueparameter ( '%temperature%' );

See Also

wci.addvalueparameter

wci.read

wci.read is the function that fetches MHO data from the database, and as such is the core of the WDB Call Interface. The function takes the user's search parameters as input and returns data as either individual point, or as a reference to a complete data grid (a Grid ID - shortened as GId).

The function is overloaded, and exists in two almost identical versions, depending on the return type required.

Prerequisites

The user must have access to group role wdb_read

The user must have called wci.begin

Syntax

wci.read
(
dataProviders ARRAY[text],
place text,
referenceTime text,
validtime text,
parameters ARRAY[text],
level text,
dataVersions ARRAY[integer],
returnType wci.returnfloat
)

wci.read
(
dataProviders ARRAY[text],
place text,
referenceTime text,
validtime text,
parameters ARRAY[text],
level text,
dataVersions ARRAY[integer],
returnType wci.returngid
)

Parameters

Tableï¿½4.60.ï¿½wci.read parameters

Parameter	Description
dataProviders	List of data providers for the MHO data to be retrieved
place	A text string containing either a geometry describing the geographic locations that the user is interested in retrieving data for (formatted using well-known-text) or a placename. The string may optionally be prefixed with a place interpolation description.
referenceTime	When the MHO data was created
validtime	What time is the MHO data valid for
parameters	What MHO-parameters the user is interested in retrieving
level	What level (altitude/depth) the data is located at
dataVersion	What version of the data should be returned
returnType	What type of data the user wants returned

&gt;Geospatial definitions are defined using well-known-text. Only POINTs and POLYGONs are currently supported.

Expected Result

Depending on the returnType specified:

wci.returnfloat

wci.returngid

Examples

The following query returns Hirlam 8 data from the database using a wci.read:

SELECT *
FROM wci.READ ( ARRAY['Hirlam norway'], -- Data provider name
'POINT(10 60)', -- Geometry
'1980-04-05 12:00:00', -- Reference time
'inside 1980-04-06 00:00:00 TO 1980-04-07 00:00:00', --Valid time
ARRAY['air pressure', 'air temperature'], -- Parameter
NULL, -- Level
ARRAY[-1], -- Data version
NULL::wci.returnFloat -- Return type
)

The above query returns Hirlam 8 data pressure and temperature data for the point closest to 10 degrees East, 60 degrees North that is valid for the twenty four hour time period of the 6th of April, 1980 and which was created (has the reference time) for the 5th of April, 12:00. The query returns all data that fulfills the above qualifications regardless of level, but only the latest version (dataversion) of the data available. Values will be returned as point data.

See Also

wci.begin

wci.end

wci.fetch

wci.write

wci.setDataProviderName

The function wci.setDataProviderName allows an administrator to set the data provider name of a data provider in the currently selected namespace of WDB. If another data provider name has already been set for the data provider in the namespace, this function will overwrite the old name.

Prerequisites

The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group.

Syntax

wci.setdataprovidername
(
fromNameSpaceId	int,
fromName	text,
dataProviderName	text
)

Parameters

Tableï¿½4.61.ï¿½wci.setDataProviderName parameters

Parameter	Description
fromNameSpaceId	The nameSpace Id of the fromName.
fromName	The name of the data provider to insert a name for. The name is taken from the fromNameSpaceId.
dataProviderName	The data provider name to be set.

Expected Result

No return.

Example

To rename the data provider with the canonical name “michael” to “michel”, we would use:

SELECT wci.setdataprovidername( 'michael', 'michel' );

See Also

wci.adddataprovider

wci.adddataprovidertogroup

wci.addwciuser

wci.getdataprovider

wci.getdataprovidername

wci.setLevelParameterName

The function wci.setLevelParameterName allows an administrator to set the name of a level parameter in the currently selected namespace of WDB. If another level parameter name has already been set in the namespace, this function will overwrite the old name.

Prerequisites

The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group.

Syntax

wci.setlevelparametername
(
canonicalName	text,
levelParameterName	text
)

Parameters

Tableï¿½4.62.ï¿½wci.setLevelParameterName parameters

Parameter	Description
canonicalName	The name of the level parameter in the canonical (0) namespace. Note that it is not possible to change the canonical name of a parameter using this function.
levelParameterName	The level parameter name to be set.

Expected Result

No return.

Example

To rename the parameter with the canonical name “hybrid level” to “HL”, we would use:

SELECT wci.setlevelparametername( 'hybrid level', 'HL' );

See Also

wci.addcodelevelparameter

wci.addmeasurelevelparameter

wci.getlevelparameter

wci.setPlaceName

The function wci.setPlaceName allows an administrator to set the place name of a place definition in the currently selected namespace of WDB. If another place name has already been set for the place definition in the namespace, this function will overwrite the old name.

Prerequisites

The user must have administrative access to the database.

Syntax

wci.setPlaceName
(
canonicalName	text,
placeName	text
)

Parameters

Tableï¿½4.63.ï¿½wci.setPlaceName parameters

Parameter	Description
canonicalName	The canonical name of the place definition that you wish to change the place name for.
placeName	The new place name of the place definition.

Expected Result

None.

Example

An example to set the name of the Hirlam 10 grid in the database:

SELECT wci.setplacename ( 'grid(5.75 -13.25, 0.1 0.1, 248 400, 50001)', 'hirlam 10km grid' );

See Also

wci.addplacepoint

wci.addplaceregulargrid

wci.addsrid

wci.getplacedefinition

wci.getplacename

wci.getplacepoint

wci.getplaceregulargrid

wci.setValueParameterName

The function wci.setValueParameterName allows an administrator to set the name of a value parameter in the currently selected namespace of WDB. If another value parameter name has already been set in the namespace, this function will overwrite the old name.

Prerequisites

The user must have administrative rights to the database; i.e., either be the system administrator or a member of the WDB_ADMIN user group.

Syntax

wci.setvalueparametername
(
canonicalName	text,
valueParameterName	text
)

Parameters

Tableï¿½4.64.ï¿½wci.setValueParameterName parameters

Parameter	Description
canonicalName	The name of the value parameter in the canonical (0) namespace. Note that it is not possible to change the canonical name of a parameter using this function.
valueParameterName	The value parameter name to be set.

Expected Result

No return.

Example

To rename the parameter with the canonical name “air temperature” to “2TM”, we would use:

SELECT wci.setvalueparametername( 'air temperature', '2TM' );

See Also

wci.addcodevalueparameter

wci.adddimensionlessvalueparameter

wci.addfunctionvalueparameter

wci.addmeasurevalueparameter

wci.getvalueparameter

wci.version

wci.version is a simple function that permits the user to retrieve version information about the WDB system.

Prerequisites

The user must have access to group role wdb_read

Syntax

wci.version ( )

Parameters

None.

Expected Result

The function returns a text with a string that describes the version of the WDB system in the PostgreSQL database.

Examples

The following query returns the WDB version:

SELECT wci.version ( )

The result is a single row of the text type containing the WDB version string.

See Also

wci.begin

wci.write

wci.write is function that can be utilized to write MHO data into the database.

The function is overloaded, and exists in several different versions depending on the input utilized.

Prerequisites

The user must be connected to the database

The user must have access to group role wdb_write

The user must have called wci.begin

Syntax

wci.write
(
value gid,
placename text,
referencetime timestamp without time zone,
validtimerom timestamp without time zone,
validtimeto timestamp without time zone
valueparameter text,
levelparameter text,
levelFrom float,
levelTo float
)

wci.write
(
value gid,
placename text,
referencetime timestamp without time zone,
validtimerom timestamp without time zone,
validtimeto timestamp without time zone
valueparameter text,
levelparameter text,
levelFrom float,
levelTo float
)

wci.write
(
row wci.returnGid
)

Parameters

Tableï¿½4.65.ï¿½wci.write parameters

Parameter	Description
value	The OID value to be retrieved
placename	A text string identifying the geographical location that the data is being inserted for
referenceTime	When the MHO data was created
validtimefrom	What time is the MHO data valid for; starting time
validtimefrom	What time is the MHO data valid for; ending time
valueparameter	What MHO-parameters the user is interested in retrieving
levelparameter	The parameter that describes the level designation
levelFrom	What level (altitude/depth) the data is located at; starting point
levelTo	What level (altitude/depth) the data is located at; ending point
row	A wci.returnOid row. This function allows the user to take the result a query and write the same (or a slightly modified row) easily into the database.

Expected Result

The valueid of the inserted row.

See Also

wci.read

wci.begin

wci.end

Chapterï¿½5.ï¿½Data Type Reference

Table of Contents

wci.browsedataproviderwci.browseplacewci.browsereferencetimewci.browsevalidtimewci.browsevalueparameterwci.browselevelparameterwci.infodataproviderwci.infoplacewci.inforegulargridwci.infovalueparameterwci.infolevelparameterwci.returnFloatwci.returnGid

This section provides an overview of the data types that are returned from the database through WCI; in particular the return rows used by the wci.read and wci.write calls.

wci.browsedataprovider

The wci.browsedataprovider data type is a simple row type used to return summarized information about the data providers of the rows currently stored in the database. The following table describes the attributes.

Tableï¿½5.1.ï¿½wci.browsedataprovider

Order	Attribute	Description
0	dataprovidername	The name of the data provider that the summary information is about.
1	referencetimefrom	The earliest referencetime in the database for the dataprovider for which there exists data.
2	referencetimeto	The latest referencetime in the database for the dataprovider for which there exists data.
3	numberoftuples	The number of data rows that exist in the database for the given dataprovider.

wci.browseplace

The wci.browseplace data type is a simple row type used to return summarized information about the placenames of the rows currently stored in the database. The following table describes the attributes.

Tableï¿½5.2.ï¿½wci.browseplace

Order	Attribute	Description
0	placename	The name of the placedefinition that the summary information is about.
1	referencetimefrom	The earliest referencetime in the database for the placename for which there exists data.
2	referencetimeto	The latest referencetime in the database for the placename for which there exists data.
3	numberoftuples	The number of data rows that exist in the database for the given placename.

wci.browsereferencetime

The wci.browsereferencetime data type is a simple row type used to return summarized information about the referencetime of the rows currently stored in the database. The following table describes the attributes.

Tableï¿½5.3.ï¿½wci.browsereferencetime

Order	Attribute	Description
0	referencetime	The reference time that the summary information is about.
1	numberoftuples	The number of data rows that exist in the database for the given referencetime.

wci.browsevalidtime

The wci.browsevalidtime data type is a simple row type used to return summarized information about the validtime of the rows currently stored in the database. The following table describes the attributes.

Tableï¿½5.4.ï¿½wci.browsevalidtime

Order	Attribute	Description
0	validtimefrom	The start time of the validtime period that is being summarized.
1	validtimeto	The end time of the validtime period being summarized.
2	numberoftuples	The number of data rows that exist in the database for the given validtime period or time point .

wci.browsevalueparameter

The wci.browsevalueparameter data type is a simple row type used to return summarized information about the valueparameters currently used by the rows in the database. The following table describes the attributes.

Tableï¿½5.5.ï¿½wci.browsevalueparameter

Order	Attribute	Description
0	valueparametername	The name of the valueparameter that the summary information is about.
1	valueunitname	The unit of the parameter in the database.
2	numberoftuples	The number of data rows that exist in the database of the given valueparameter.

wci.browselevelparameter

The wci.browselevelparameter data type is a simple row type used to return summarized information about the levelparameters and level values currently stored by the rows in the database. The following table describes the attributes.

Tableï¿½5.6.ï¿½wci.browselevelparameter

Order	Attribute	Description
0	levelparametername	The name of the levelparameter that the summary information is about.
1	levelunitname	The unit of the parameter in the database.
2	levelfrom	The level from value of the rows in the database.
3	levelto	The level to value of the rows in the database.
4	numberoftuples	The number of data rows that exist in the database of the given level parameter and level value combination.

wci.infodataprovider

The wci.infodataprovider data type is a simple row type used to return metadata information about the dataproviders that can be stored in the database. The following table describes the attributes.

Tableï¿½5.7.ï¿½wci.infodataprovider

Order	Attribute	Description
0	dataprovidername	The name of the dataprovider.
1	dataprovidertype	The type of the dataprovider. This specifies whether the dataprovider is a person, computer system, meteorological station, or something else. It can also specify that the dataprovidername represents a group of other dataproviders.
2	spatialdomaindelivery	The spatialdomaindelivery describes the spatial domain in which the dataprovider returns data. Examples are points and grids. The spatialdomaindelivery any is used to indicate that the dataprovider can store and return data in several formats on the database.
3	dataprovidercomment	A text field that provides additional descriptive information about the dataprovider.
4	dataproviderstoretime	Describes the time at which the dataprovider information was created.

wci.infoplace

The wci.infoplace data type is a simple row type used to return metadata information about the place definitions that can be stored in the database. The following table describes the attributes.

Tableï¿½5.8.ï¿½wci.infoplace

Order	Attribute	Description
0	placename	The name of the place definition.
1	placegeometry	The geometry (in WKT) that describes the place definition. For regular grids, this is a polygon of the four corners of the grid transformed into the default projection of the database.
2	placeindeterminatetype	The place indeterminate type is used to describe imprecision or missing data in the place definition information.
3	placegeometrytype	The placegeometrytype describes what type of geometry the row describes.
4	placestoretime	Describes the time at which the place definition was created.

wci.inforegulargrid

The wci.inforegulargrid data type is a simple row type used to return detailed metadata information about the place definitions of the grid type that can be stored in the database. The following table describes the attributes.

Tableï¿½5.9.ï¿½wci.infoplace

Order	Attribute	Description
0	placename	The name of the place definition.
1	numberX	The number of points along the X axis of the grid (i.e., the width).
2	numberY	The number of points along the Y axis of the grid (i.e., the height).
3	incrementX	The distance between two points on the X axis of the grid in the original projection of the grid.
4	incrementY	The distance between two points on the Y axis of the grid in the original projection of the grid.
5	startX	The starting point (lower left corner) of the grid on the X axis in the original projection of the grid.
6	startY	The starting point (lower left corner) of the grid on the Y axis in the original projection of the grid.
7	projDefinition	The proj.4 string that defines the original projection of the grid. Since the structure of a grid is not reprojected, this information maya be useful if you need to deal with the grid information directly.

wci.infovalueparameter

The wci.infovalueparameter data type is a simple row type used to return metadata information about the value parameters that can be stored in the database. The following table describes the attributes.

Tableï¿½5.10.ï¿½wci.infovalueparameter

Order	Attribute	Description
0	valueparametername	The name of the value parameter.
1	valueunitname	The name of the unit that the parameter data is stored in. By default, this will always be the SI unit, where possible.

wci.infolevelparameter

The wci.infolevelparameter data type is a simple row type used to return metadata information about the level parameters that can be stored in the database. The following table describes the attributes.

Tableï¿½5.11.ï¿½wci.infolevelparameter

Order	Attribute	Description
0	levelparametername	The name of the level parameter.
1	levelunitname	The name of the unit that the parameter data is stored in. By default, this will always be the SI unit, where possible.

wci.returnFloat

The wci.returnFloat data type is a simple row type used for returning floating-point data to the user from the wci.read call. The following table describes the attributes that are returned from wci.returnFloat; including the ordering of the attributes in the type.

Tableï¿½5.12.ï¿½wci.returnFloat

Order	Attribute	Description
0	value	The floating point value returned by the query
1	data provider name	The name of the data provider of the value (as defined within the dataprovidernamespace selected)
2	place name	The name of the grid definition selected (as defined within the placenamespace selected). The place name can be then be used to retrieve the original grid definition of the grid, if needed.
3	place geometry	The geometry definition of the value returned. This is less useful for rotated grids, as the coordinates will be in regular WGS84.
4	referencetime	The time of reference for the value returned
5	validtime from	The first point in time for which the value is valid
6	validtime to	The last point in time for which the value is valid
7	validtime indeterminate code	The validtime indeterminate code is used to describe imprecision or missing data in the level information. The code 0 is used to describe exact, which implies that the validtime interval given is precise.
8	value parameter name	The parameter name for the value returned (as defined within the parameter name space selected)
9	value parameter unit	The measurement unit for the value returned
10	level parameter name	The parameter name for the level of the value returned (as defined within the parameter name space selected)
11	level unit name	The measurement unit for the level of the value returned
12	level from	The lower value of the level
13	level to	The upper value of the level
14	level indeterminate code	The level indeterminate code is used to describe imprecision or missing data in the level information. The code 0 is used to describe exact.
15	data version	The data version of the value. Data version is utilized for two separate purposes; to indicate different version of the same data (i.e., to allow corrections and edits to co-exist in the database) and for perturbed versions of the same data (e.g., ensemble members).
16	confidence code	Quality marker (not currently used)
17	value store time	The time when the data was inserted into the database
18	value id	The ID of the value within its value type. Together with valuetype, this costitutes a key of the WDB value
19	value type	The type of the value returned. Together with the valueid, this constitutes a key of the WDB value

wci.returnGid

The wci.returnGid data type is a simple row type used for returning data to the user from the wci.read call. The following table describes the attributes that are returned from wci.returnGid; including the ordering of the attributes in the type.

Tableï¿½5.13.ï¿½wci.returnGid

Order	Attribute	Description
0	value	The grid ID (GID) of the value being returned
1	data provider name	The name of the data provider of the value (as defined within the dataprovidernamespace selected)
2	place name	The name of the grid definition selected (as defined within the placenamespace selected). The place name can be then be used to retrieve the original grid definition of the grid, if needed
3	place geometry	The geometry definition of the value returned. This is less useful for rotated grids, as the coordinates will be in regular WGS84.
4	referencetime	The time of reference for the value returned
5	validtime from	The first point in time for which the value is valid
6	validtime to	The last point in time for which the value is valid
7	validtime indeterminate code	The validtime indeterminate code is used to describe imprecision or missing data in the level information. The code 0 is used to describe exact, which implies that the validtime interval given is precise.
8	value parameter name	The parameter name for the value returned (as defined within the parameter name space selected)
9	value parameter unit	The measurement unit for the value returned
10	level parameter name	The parameter name for the level of the value returned (as defined within the parameter name space selected)
11	level unit name	The measurement unit for the level of the value returned
12	level from	The lower value of the level
13	level to	The upper value of the level
14	level indeterminate code	The level indeterminate code is used to describe imprecision or missing data in the level information. The code 0 is used to describe exact.
15	data version	The data version of the value. Data version is utilized for two separate purposes; to indicate different version of the same data (i.e., to allow corrections and edits to co-exist in the database) and for perturbed versions of the same data (e.g., ensemble members).
16	confidence code	Quality marker (not currently used)
17	value store time	The time when the data was inserted into the database
18	value id	The ID of the value within its value type. Together with valuetype, this costitutes a key of the WDB value
19	value type	The type of the value returned. Together with the valueid, this constitutes a key of the WDB value

Chapterï¿½6.ï¿½Examples

You can find a number of examples using SQL, perl, java, and C++ in the source package of WDB, under the examples directory.

Chapterï¿½7.ï¿½Frequently Asked Questions

This page is for a list of frequently asked questions about WCI.

Chapterï¿½8.ï¿½Known Problems, Bugs, and Limitations

Table of Contents

Limit of 100,000 rows returned by wci.read from a single grid

The following page describes some of the known problems and limitations of the WCI interface, and how to deal with them.

Limit of 100,000 rows returned by wci.read from a single grid

The wci.read function is limited to returning no more than 100,000 rows from a single grid operation. If you need to retrieve a greater number of values from one grid in the database, you should use wci.fetch to retrieve the Grid object directly and perform the retrieval manually.