ST_Point

The ST_Point function has two variations.

In the first variation, ST_Point constructs a point from one of the following inputs:

A set of coordinates
A well-known text representation
A well-known binary representation
An ESRI shape representation
A Geography Markup Language (GML) representation

An optional spatial reference system identifier can be specified to indicate the spatial reference system that the resulting point is in.

If the point is constructed from coordinates, and if the X or Y coordinate is null, then an exception condition is raised (SQLSTATE 38SUP). If the Z or M coordinate is null, then the resulting point will not have a Z or M coordinate, respectively. If the point is constructed from its well-known text representation, and if the representation is null, then null is returned.

In the second variation, ST_Point takes ST_Geometry as an input parameter and casts the output type to ST_Point. If the given geometry is null, then null is returned.

Syntax for variation 1

Variation 1

coordinates

Parameters for variation 1

wkt: A value of type CLOB(8M) that contains the well-known text representation of the resulting point. If the well-known text representation is null, then null is returned.
wkb: A value of type BLOB(4M) that contains the well-known binary representation of the resulting point. If the well-known binary representation is null, then null is returned.
shape: A value of type BLOB(4M) that contains the shape representation of the resulting point. If the shape representation is null, then null is returned.
gml: A value of type CLOB(8M) that contains the GML representation of the geometry. If the GML representation is null, then null is returned.
srs_id: A value of type INTEGER that identifies the spatial reference system for the resulting point. This parameter is required.
If srs_id does not identify a spatial reference system listed in the catalog view DB2GSE.ST_SPATIAL_REFERENCE_SYSTEMS, an error is returned (SQLSTATE 38SU1).
x_coordinate: A value of type DOUBLE that specifies the X coordinate for the resulting point.
y_coordinate: A value of type DOUBLE that specifies the Y coordinate for the resulting point.
z_coordinate: A value of type DOUBLE that specifies the Z coordinate for the resulting point.
If the z_coordinate parameter is omitted, the resulting point will not have a Z coordinate.
m_coordinate: A value of type DOUBLE that specifies the M coordinate for the resulting point.
If the m_coordinate parameter is omitted, the resulting point will not have a measure.

Return type for variation 1

db2gse.ST_Point

Syntax for variation 2

Variation 2

Parameter for variation 2

geometry: A value of type ST_Geometry.

Return type for variation 2

ST_Point

Examples

In the following examples, the lines of results have been reformatted for readability.

Example 1

This example illustrates how ST_Point can be used to create and insert points. The first point is created using a set of X and Y coordinates. The second point is created using its well-known text representation. Both points are geometries in spatial reference system 1.


SET CURRENT PATH = CURRENT PATH, db2gse;
CREATE TABLE sample_points (id INTEGER, geometry ST_Point);

INSERT INTO sample_points
  VALUES (1100, ST_Point (10, 20, 1) );

INSERT INTO sample_points
  VALUES (1101, ST_Point ('point (30 40)', 1) );

The following SELECT statement returns the points that were recorded in the table:


SELECT id, CAST( ST_AsText( geometry ) AS VARCHAR(90)) POINTS
  FROM sample_points;

Results:


ID         POINTS
---------- ------------------------------------
      1110 POINT ( 10.000000 20.000000)
      1101 POINT ( 30.000000 40.000000)

Example 2

This example inserts a record into the SAMPLE_POINTS table with ID 1103 and a point value with an X coordinate of 120, a Y coordinate of 358, an M coordinate of 34, but no Z coordinate.


INSERT INTO SAMPLE_POINTS(ID, GEOMETRY) 
 VALUES(1103, db2gse.ST_Point(120, 358, CAST(NULL AS DOUBLE), 34, 1));

SELECT id, CAST( ST_AsText( geometry ) AS VARCHAR(90) ) POINTS
 FROM sample_points;

Results:


ID         POINTS
 ---------- ------------------------------------------------
       1100 POINT ( 10.000000 20.000000)
       1101 POINT ( 30.000000 40.000000)
       1103 POINT M ( 120.00000 358.00000 34)