ST_M function

The ST_M function takes a point as an input parameter and returns its measure (M) coordinate. You can optionally indicate an M coordinate as input parameter in addition to the point and the function returns the point itself with its M coordinate set to the given value.

If the specified M coordinate is null, then the M coordinate of the point is removed.

If the specified point is null or is empty, then null is returned.

This function can also be called as a method.

Syntax

Parameters

point: A value of type ST_Point for which the M coordinate is returned or modified.
m_coordinate: A value of type DOUBLE that represents the new M coordinate for point.
If m_coordinate is null, then the M coordinate is removed from point.

Return types

DOUBLE, if m_coordinate is not specified
db2gse.ST_Point, if m_coordinate is specified

Examples

Example 1

This example illustrates the use of the ST_M function. Three points are created and inserted into the SAMPLE_POINTS table. They are all in the spatial reference system that has an ID of 1.


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

INSERT INTO sample_points
  VALUES (1, ST_Point (2, 3, 32, 5, 1))

INSERT INTO sample_points
  VALUES (2, ST_Point (4, 5, 20, 4, 1))

INSERT INTO sample_points
  VALUES (3, ST_Point (3, 8, 23, 7, 1))

Example 2

This example finds the M coordinate of the points in the SAMPLE_POINTS table.


SELECT id, ST_M (geometry) M_COORD
  FROM sample_points

Results:


ID          M_COORD
----------- ------------------------
          1 +5.00000000000000E+000
          2 +4.00000000000000E+000
          3 +7.00000000000000E+000

Example 3

This example returns one of the points with its M coordinate set to 40.


SELECT id, CAST (ST_AsText (ST_M (geometry, 40) )
  AS VARCHAR(60) ) M_COORD_40
  FROM sample_points
  WHERE id=3

Results:



ID         M_COORD_40
---------- -------------------------------------------------------
         3 POINT ZM (3.00000000 8.00000000 23.00000000 40.00000000)