WDB

This is an old revision of the document!

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

List of Tables

Table of Contents

About this Manual Intended Usage Outline

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

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.

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.

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

Table of Contents

Overview Data Provider Place (Geographic Location)Reference Time Valid Time Value Parameter Level Data Version

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

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.

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 );

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 );

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.

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.

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 );

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 );

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.

Table of Contents

Outline Open a connection Initialize WCI Read from the WCI Reading Point Data from WCI Reading Grid Data from WCI Release WCI Close Connection

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

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

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.

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.

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.

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

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.

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

Using libpq,

PQfinish(connection_);

Table of Contents

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

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

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.

wci.addcodelevelparameter
(
	parameterName			text,
	parameterReference 		text
)

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.

The ParameterId (key reference number).

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' );

wci.addmeasurelevelparameter
wci.getcodelevelparameter
wci.getlevelparameter
wci.getmeasurelevelparameter

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

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.

wci.addcodevalueparameter
(
	parameterName			text,
	parameterReference 		text
)

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.

The ParameterId (key reference number).

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

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

wci.addparameterfunctiontype
wci.getcodevalueparameter
wci.getvalueparameter
wci.getparameterfunctiontype

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

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.

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

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.

The DataProviderId (key reference number).

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' );

wci.adddataprovidertogroup
wci.addwciuser
wci.getdataprovider
wci.getdataprovidername
wci.setdataprovidername

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

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.

wci.adddataprovidertogroup
(
	dataProviderName		text,
	dataProviderGroup		text
)

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.

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

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

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

wci.adddataprovider
wci.addwciuser
wci.getdataprovider
wci.getdataprovidername
wci.setdataprovidername

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

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.

wci.adddimensionlessvalueparameter
(
	parameterName			text,
	parameterDescription	text
)

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.

The ParameterId (key reference number).

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

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

wci.getvalueparameter

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

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.

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

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.

The ParameterId (key reference number).

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

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

wci.getvalueparameter

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

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.

wci.addlevelparameterusage
(
	levelParameterUsage		text,
	levelDescription		text
)

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

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

None.

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-' );

wci.getlevelparameterusage

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

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.

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

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.

None.

An example adding 'acceleration' measure to the database:

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

wci.getmeasure

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

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.

wci.addmeasurelevelparameter
(
	parameterUsage			text,
	parameterUnit			text
)

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.

The ParameterId (key reference number).

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

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

wci.getlevelparameter

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

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.

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

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.

The ParameterId (key reference number).

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

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

wci.addmeasure
wci.getmeasurevalueparameter

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

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.

wci.addparameterfunctiontype
(
	parameterFunctionType			text,
	parameterFunctionDescription	text
)

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.

None.

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' );

wci.getfunctionvalueparameter

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

The user must have write privileges on the database.

wci.addplacepoint
(
	placeName				text,
	placeGeometry 			text
)

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.

The PlaceId (key reference number).

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.

wci.addplacepolygon
wci.addplaceregulargrid
wci.addsrid
wci.getplacedefinition
wci.getplacename
wci.getplacepoint
wci.getplaceregulargrid
wci.getsrid
wci.setplacename

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

The user must have write privileges on the database.

wci.addplacepolygon
(
	placeName				text,
	placeGeometry 			text
)

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.

The PlaceId (key reference number).

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.

wci.addplacepoint
wci.addplaceregulargrid
wci.addsrid
wci.getplacedefinition
wci.getplacename
wci.getplacepoint
wci.getplaceregulargrid
wci.getsrid
wci.setplacename

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

The user must have write privileges on the database.

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

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

The PlaceId (key reference number).

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.

wci.addplacepoint
wci.addsrid
wci.getplacedefinition
wci.getplacename
wci.getplacepoint
wci.getplaceregulargrid
wci.getsrid
wci.setplacename

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

The user must have write privileges on the database.

wci.addsrid
(
	name				text,
	projection			text
)

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.

The SRID (spatial reference id).

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');

wci.addplacepoint
wci.addplaceregulargrid
wci.getplacedefinition
wci.getplacename
wci.getplacepoint
wci.getplaceregulargrid
wci.getsrid
wci.setplacename

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

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.

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

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

None.

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 );

wci.addmeasure

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

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.

wci.addvalueparameterusage
(
	valueParameterUsage		text,
	valueDescription		text
)

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

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

None.

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.' );

wci.getvalueparameterusage

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

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.

wci.addwciuser
(
	dataProviderName		text
)

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

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

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

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

SELECT wci.addwciuser( 'michael' );

wci.adddataprovider
wci.adddataprovidertogroup
wci.getdataprovider
wci.getdataprovidername
wci.setdataprovidername

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

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

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

wci.begin (
	user                    name
)

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

No return expected.

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' );

wci.end

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.

The user must have access to group role wdb_read
The user must have called wci.begin

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
)

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.

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.

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 );

wci.read

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

The user must have read access to the database.

wci.configuration
(
)

None.

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.

An example to extract the configuration of the database:

SELECT wci.configuration ( );

wci.version

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

None.

wci.end
(
)

None.

No return expected.

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

SELECT wci.end ( );

wci.begin

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.

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

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

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

Currently, the function always returns a:

wci.grid

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.

wci.read
wci.write

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

The user must have read access to the database.

wci.getcodelevelparameter
(
	parameter		text
)

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.

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.

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%' );

wci.addcodelevelparameter

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

The user must have read access to the database.

wci.getcodevalueparameter
(
	parameter		text
)

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.

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.

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%' );

wci.addcodevalueparameter

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

The user must have read access to the database.

wci.getdataprovider
(
	dataProviderName		text
)

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.

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.

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%' );

wci.adddataprovider
wci.adddataprovider2group
wci.addwciuser
wci.getdataprovidername
wci.setdataprovidername

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

The user must have read access to the database.

wci.getdataprovidername
(
	dataprovidername		text
)

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.

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.

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%' );

wci.adddataprovider
wci.adddataprovider2group
wci.addwciuser
wci.getdataprovider
wci.setdataprovidername

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

The user must have read access to the database.

wci.getdimensionlessvalueparameter
(
	parameter		text
)

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.

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.

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%' );

wci.adddimensionlessvalueparameter

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

The user must have read access to the database.

wci.getfunctionvalueparameter
(
	parameter		text
)

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.

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.

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%' );

wci.addfunctionvalueparameter

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

The user must have read access to the database.

wci.getlevelparameter
(
	parameter		text
)

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.

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.

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%' );

wci.addcodelevelparameter
wci.addmeasurelevelparameter

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

The user must have read access to the database.

wci.getlevelparameterusage
(
	usage		text
)

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.

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.

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%' );

wci.addlevelparameterusage

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

The user must have read access to the database.

wci.getmeasure
(
	measure		text
)

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.

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.

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

SELECT wci.getmeasure ( 'distance' );

wci.addmeasure

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

The user must have read access to the database.

wci.getmeasurelevelparameter
(
	parameter		text
)

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.

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.

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%' );

wci.addmeasurelevelparameter

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

The user must have read access to the database.

wci.getmeasurevalueparameter
(
	parameter		text
)

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.

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.

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%' );

wci.addmeasurevalueparameter

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

The user must have read access to the database.

wci.getparameterfunctiontype
(
	type		text
)

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.

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.

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

SELECT wci.getparameterfunctiontype ( 'accumulated' );

wci.addparameterfunctiontype

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

The user must have read access to the database.

wci.getplacedefinition
(
	placename		text
)

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.

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.

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%' );

wci.addplacepoint
wci.addplaceregulargrid
wci.addsrid
wci.getplacename
wci.getplacepoint
wci.getplaceregulargrid
wci.getsrid
wci.setplacename

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

The user must have read access to the database.

wci.getplacename
(
	placename		text
)

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

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.

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.

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" );

wci.addplacepoint
wci.addplaceregulargrid
wci.addsrid
wci.getplacedefinition
wci.getplacepoint
wci.getplaceregulargrid
wci.getsrid
wci.setplacename

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

The user must have read access to the database.

wci.getplacepoint
(
	placename		text
)

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.

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.

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%' );

wci.addplacepoint
wci.addplaceregulargrid
wci.addsrid
wci.getplacedefinition
wci.getplacename
wci.getplaceregulargrid
wci.getsrid
wci.setplacename

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

The user must have read access to the database.

wci.getplaceregulargrid
(
	placename		text
)

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.

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.

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%' );

wci.addplacepoint
wci.addplaceregulargrid
wci.addsrid
wci.getplacedefinition
wci.getplacename
wci.getplacepoint
wci.getsrid
wci.setplacename

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.

The user must have read access to the database.

wci.getsrid
(
	projstr			text
)

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.

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.

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

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

wci.addplacepoint
wci.addplaceregulargrid
wci.addsrid
wci.getplacedefinition
wci.getplacename
wci.getplaceregulargrid
wci.addsrid
wci.setplacename

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

The user must have read access to the database.

wci.getunit
(
	unit		text
)

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.

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

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

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

wci.addunit

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

The user must have read access to the database.

wci.getvalueparameter
(
	parameter		text
)

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.

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.

An example to list all value parameters based on temperature:

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

wci.addvalueparameter

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.

The user must have access to group role wdb_read
The user must have called wci.begin

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
)

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

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

Depending on the returnType specified:

wci.returnfloat
wci.returngid

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.

wci.begin
wci.end
wci.fetch
wci.write

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.

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.

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

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.

No return.

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

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

wci.adddataprovider
wci.adddataprovidertogroup
wci.addwciuser
wci.getdataprovider
wci.getdataprovidername

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.

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.

wci.setlevelparametername
(
	canonicalName			text,
	levelParameterName		text
)

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.

No return.

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

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

wci.addcodelevelparameter
wci.addmeasurelevelparameter
wci.getlevelparameter

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.

The user must have administrative access to the database.

wci.setPlaceName
(
	canonicalName		text,
	placeName			text
)

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.

None.

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' );

wci.addplacepoint
wci.addplaceregulargrid
wci.addsrid
wci.getplacedefinition
wci.getplacename
wci.getplacepoint
wci.getplaceregulargrid

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.

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.

wci.setvalueparametername
(
	canonicalName			text,
	valueParameterName		text
)

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.

No return.

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

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

wci.addcodevalueparameter
wci.adddimensionlessvalueparameter
wci.addfunctionvalueparameter
wci.addmeasurevalueparameter
wci.getvalueparameter

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

The user must have access to group role wdb_read

wci.version ( )

None.

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

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.

wci.begin

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.

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

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
)

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.

The valueid of the inserted row.

wci.read
wci.begin
wci.end

Table of Contents

wci.browsedataprovider wci.browseplace wci.browsereferencetime wci.browsevalidtime wci.browsevalueparameter wci.browselevelparameter wci.infodataprovider wci.infoplace wci.inforegulargrid wci.infovalueparameter wci.infolevelparameter wci.returnFloat wci.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.

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.

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.

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.

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 .

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.

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.

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.

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.

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.

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.

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.

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

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

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.

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.

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.

WDB Call Interface User Manual

Chapterï¿½1.ï¿½Introduction

About this Manual

Intended Usage

Outline

Chapterï¿½2.ï¿½Key Concepts

Overview

Data Provider

Place (Geographic Location)

Reference Time

Valid Time

Value Parameter

Level

Data Version

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

Outline

Open a connection

Initialize WCI

Read from the WCI

Reading Point Data from WCI

Return values

Reading Grid Data from WCI

Return values

Release WCI

Close Connection

Chapterï¿½4.ï¿½Function Reference

wci.addCodeLevelParameter

Prerequisites

Syntax

Parameters

Expected Result

Example

See Also

wci.addCodeValueParameter

Prerequisites

Syntax

Parameters

Expected Result

Example

See Also

wci.addDataProvider

Prerequisites

Syntax

Parameters

Expected Result

Example

See Also

wci.addDataProviderToGroup

Prerequisites

Syntax

Parameters

Expected Result

Example

See Also

wci.addDimensionlessValueParameter

Prerequisites

Syntax

Parameters

Expected Result

Example

See Also

wci.addFunctionValueParameter

Prerequisites

Syntax

Parameters

Expected Result

Example

See Also

wci.addLevelParameterUsage

Prerequisites

Syntax

Parameters

Expected Result

Example

See Also

wci.addMeasure

Prerequisites

Syntax

Parameters

Expected Result