MapOpen

Use this function to create a new map or to open an existing map.

Syntax

STRING MapOpen(STRING sMapName, INT nOpenMode, STRING sCloseCallback)

sMapName:

Name of the map to create or open. The default name is an empty string. If name is empty, it will generate an available random name.

nOpenMode:

Indicates the open or create mode of the map. Modes include:

Mode 0 - Create a new map. If a map with the same name exists an “Out of handles” error (271) will be raised.

Mode 1 - Opens an existing map. if there is no map with that name a “Record not found” error (536) will be raised.

Mode 2 – Open an existing map , or creates a new map if the map name does not exist. The error codes from modes 0 and 1 can occur.

sCloseCallback:

The function to call when this instance is closed.

Return Value

Name of map if successful, otherwise an empty string will be returned.

If the map name is empty an “Invalid argument” error (274) will be raised.

If the open mode is less than 0 or greater than 2, an “Invalid argument” error (274) will be raised.

If an empty map name is supplied along with open mode 1, an “Invalid argument” error (274) will be raised.

Example

! Demonstrate MapOpen.
STRING sMapName = MapOpen();
! sMapName is a randomly generated text that uniquely identifies the map
INT iMapCloseResult = MapClose(sMapName);
! The map that is identified by sMapName is now closed and unavailable
 
! Demonstrate MapOpen with a close callback
STRING sMapName = MapOpen(“”, 0, “MyCloseCallback”);
! sMapName is a randomly generated text that uniquely identifies the map
INT iMapCloseResult = MapClose(sMapName);
! The map that is identified by sMapName is now closed and unavailable
! The function MyCloseCallback is called, but it may or may not be
! completed before the MapClose function returns.

! This is a MapClose callback function
! The callback must take one string argument which is the name of the
! map that is being closed.
FUNCTION MyCloseCallback(STRING sMapName)
! sMapName is a valid map for the duration of the callback, at the
! exit of the callback the memory is released and any subsequent
! use of the map will result in an error.
END
	
			

Related Functions

MapClear, MapClose, MapExists, MapKeyCount, MapKeyDelete, MapKeyExists, MapKeyFirst, MapValueGet, MapKeyNext, MapValueSet, MapValueSetQuality

See Also

Published June 2018