SDO_TOPO_MAP.LOAD_TOPO

Format (Function)

SDO_TOPO_MAP.LOAD_TOPO_MAP(     
  topo_map      IN VARCHAR2,      
  allow_updates IN VARCHAR2,      
  build_indexes IN VARCHAR2 DEFAULT 'TRUE'      
) RETURN VARCHAR2;

or

SDO_TOPO_MAP.LOAD_TOPO_MAP(     
  topo_map      IN VARCHAR2,      
  xmin          IN NUMBER,      
  ymin          IN NUMBER,      
  xmax          IN NUMBER,      
  ymax          IN NUMBER,      
  allow_updates IN VARCHAR2,      
  build_indexes IN VARCHAR2 DEFAULT 'TRUE'      
) RETURN VARCHAR2;

or

SDO_TOPO_MAP.LOAD_TOPO_MAP(     
  topo_map      IN VARCHAR2,      
  xmin          IN NUMBER,      
  ymin          IN NUMBER,      
  xmax          IN NUMBER,      
  ymax          IN NUMBER,      
  allow_updates IN VARCHAR2,      
  build_indexes IN VARCHAR2,      
  next_load     IN VARCHAR2 DEFAULT 'FALSE'      
) RETURN VARCHAR2;

Format (Procedure)

SDO_TOPO_MAP.LOAD_TOPO_MAP(     
  topo_map      IN VARCHAR2,      
  allow_updates IN VARCHAR2,      
  build_indexes IN VARCHAR2 DEFAULT 'TRUE');'

or

SDO_TOPO_MAP.LOAD_TOPO_MAP(     
  topo_map      IN VARCHAR2,      
  xmin          IN NUMBER,      
  ymin          IN NUMBER,      
  xmax          IN NUMBER,      
  ymax          IN NUMBER,      
  allow_updates IN VARCHAR2,      
  build_indexes IN VARCHAR2 DEFAULT 'TRUE');'

Description

Loads the topological elements (primitives) for an entire topology or a window (rectangular portion) of a topology into a TopoMap object. If you use a function format, returns the string TRUE if topological elements were loaded into the cache, and FALSE if no topological elements were loaded into the cache.

Parameters

topo_map

Name of the TopoMap object. (TopoMap objects are explained in TopoMap Objects.)

xmin

Lower-left X coordinate value for the window (rectangular portion of the topology) to be loaded.

See the Usage Notes and Figure 4-1 for information about which topological elements are loaded when you specify a window.

ymin

Lower-left Y coordinate value for the window (rectangular portion of the topology) to be loaded.

xmax

Upper-right X coordinate value for the window (rectangular portion of the topology) to be loaded.

ymax

Upper-right Y coordinate value for the window (rectangular portion of the topology) to be loaded.

allow_updates

TRUE makes the TopoMap object updatable; that is, it allows topology editing operations to be performed on the TopoMap object and changes to be written back to the database. FALSE makes the TopoMap object read-only with respect to the database; that is, it allows topology editing operations to be performed on the TopoMap object but does not allow changes to be written back to the database.

Making a TopoMap object updatable causes the topological elements in the TopoMap object to be locked, which means that they cannot be included in an updatable TopoMap object in the session of another database user. (Within any given user session, there can be no more than one updatable TopoMap object active.)

build_indexes

TRUE (the default) builds in-memory R-tree indexes for edge and face data; FALSE does not build in-memory R-tree indexes for edge and face data. The indexes improve the performance of editing operations, especially with large topologies.

next_load

TRUE allows you to expand the load window area (rectangular portion of the topology) in order to add more data if you discover that the existing window does not cover the area that you want to edit; FALSE (the default) does not allow you to add more data to the load window.

The first call to the function on a TopoMap object (topo_map) should always have next_load as FALSE (either by default or explicitly specified). If you need to expand the window area, call the function again but with next_load as TRUE, then perform any desired additional editing operations.

Usage Notes

Using a procedure format for loading the TopoMap object is more efficient than using the function format, if you do not need to know if any topological elements were loaded (for example, if the specified topology or rectangular area is empty). Using a function format lets you know if any topological elements were loaded.

You must create the TopoMap object (using the SDO_TOPO_MAP.CREATE_TOPO_MAP procedure) before you load data into it.

You cannot use this function or procedure if the TopoMap object already contains data, unless you use the function format with next_load as TRUE. Otherwise, if the TopoMap object contains any data, you must do one of the following before calling this function or procedure: commit the changes (using the SDO_TOPO_MAP.COMMIT_TOPO_MAP procedure) and clear the cache (using the SDO_TOPO_MAP.CLEAR_TOPO_MAP procedure), or roll back the changes (using the SDO_TOPO_MAP.ROLLBACK_TOPO_MAP procedure).

For information about using an in-memory cache to edit topological elements, see Approaches for Editing Topology Data.

This function or procedure is equivalent to using the loadTopology or loadWindow method of the TopoMap class of the client-side Java API (described in Topology Data Model Java Interface).

Every TopoMap object, whether for an entire topology or for a window specified using the xmin, ymin, xmax, and ymax parameters, has a region associated with it. For an updatable TopoMap object, updates are allowed only within this region. (The region might also contain topological elements that you cannot update directly, but that might be modified by Oracle Spatial as needed as a result of your editing operations.)

When a TopoMap object is loaded, all nodes, faces, and edges that intersect the region for the TopoMap object are loaded. When a face is loaded, all edges and nodes that are on the boundary of the face are loaded. When an edge is loaded, the start node and end node of the edge are loaded. Consider the topology and the window (shown by a dashed line) in Figure 4-1.

Figure 4-1 Loading Topological Elements into a Window

Description of "Figure 4-1 Loading Topological Elements into a Window"

With the window shown in Figure 4-1:

Face F1 is loaded because it partially overlaps the window.
The following edges are loaded: E3, E4, E5, E6, E7, E8, E9, E10, E11, E12, E13, E14, E16.

Edge E3 is loaded because it partially overlaps the window.

Edge E9 is loaded because it bounds a face (F1) that partially overlaps a window.

Edge E12 is loaded because it is an island edge in a face (F1) that partially overlaps the window.

Edge E1 is not loaded because it is not associated with any face that interacts with the window.
The following nodes are loaded: N2, N5, N6, N7, N8, N9, N10, N11, N12, N16, N19, N20.

Non-isolated node N2 is loaded because edge E3 is loaded.

Non-isolated node N12 is loaded because edges E9 and E11 are loaded.

Isolated node N16 is loaded because it is an isolated (island) node inside a locked face.

Examples

The following example loads all CITY_DATA topology elements into its associated TopoMap object for editing and builds the in-memory R-tree indexes by default. It returns a result indicating that the operation was successful and that some topological elements were loaded into the cache. (The example refers to definitions and data from Topology Built from Topology Data.)

CALL SDO_TOPO_MAP.LOAD_TOPO_MAP('CITY_DATA_TOPOMAP', 'TRUE') INTO :res_varchar;
 
Call completed.
 
PRINT res_varchar;
 
RES_VARCHAR
--------------------------------------------------------------------------------
TRUE