Metadata statement - MapBasic - 2023

Purpose

Manages a table's metadata. You can issue this statement from the MapBasic window in MapInfo Pro.

Syntax 1

Metadata Table table_name 
	{ SetKey key_name To key_value | 
		DropKey key_name [ Hierarchical ] | 
		SetTraverse starting_key_name [ Hierarchical ] 
		Into ID traverse_ID_var }

table_name is the name of an open table.

key_name is a string, representing the name of a metadata key. The string must start with a backslash ("\"), and it cannot end with a backslash.

key_value is a string up to 239 characters long, representing the value to assign to the key.

starting_key_name is a string representing the first key name to retrieve from the table. To set up the traversal at the very beginning of the list of keys, specify "\" (backslash).

traverse_ID_var is the name of an IntPtr variable; MapInfo Pro stores a traversal ID in the variable, which you can use in subsequent Metadata Traverse... statements.

Syntax 2

Metadata Traverse traverse_ID 
	{ Next Into Key key_name_var In key_value_var | 
	 Destroy } 

traverse_ID is an integer value (such as the value of the traverse_ID_var variable described above).

key_name_var is the name of a string variable; MapInfo Pro stores the fetched key's name in this variable.

key_value_var is the name of a string variable; MapInfo Pro stores the fetched key's value in this variable.

Description

The Metadata statement manages the metadata stored in MapInfo tables. Metadata is information that is stored in a table's .TAB file, instead of being stored as rows and columns.

Each table can have zero or more keys. Each key represents an information category, such as an author's name, a copyright notice, etc. Each key has a string value associated with it. For example, a key called "\Copyright" might have the value "Copyright 2001 Precisely." For more information about Metadata, see the MapBasic User Guide.

Modifying a Table's Metadata

To create, modify, or delete metadata, use Syntax 1. The following clauses apply:

SetKey

Assigns a value to a metadata key. If the key already exists, MapInfo Pro assigns it a new value. If the key does not exist, MapInfo Pro creates a new key. When you create a new key, the changes take effect immediately; you do not need to perform a Save operation.

MetaData Table Parcels SetKey "\Info\Date" To Str$(CurDate())

DropKey

Deletes the specified key from the table. If you include the Hierarchical keyword, MapInfo Pro deletes the entire metadata hierarchy at and beneath the specified key. For example, if a table has the keys "\Info\Author" and "\Info\Date" you can delete both keys with the following statement:

MetaData Table Parcels DropKey "\Info" Hierarchical

Reading a Table's Metadata

To read a table's metadata values, use the SetTraverse clause to initialize a traversal, and then use the Next clause to fetch key values. After you are finished fetching key values, use the Destroy clause to free the memory used by the traversal. The following clauses apply:

SetTraverse

Prepares to traverse the table's keys, starting with the specified key. To start at the beginning of the list of keys, specify "\" as the starting key name. If you include the Hierarchical keyword, the traversal can hierarchically fetch every key. If you omit the Hierarchical keyword, the traversal is flat, meaning that MapInfo Pro will only fetch keys at the root level (for example, the traversal will fetch the "\Info" key, but not the "\Info\Date" key).

Next Into Key... Into Value...

Attempts to read the next key. If there is a key to read, MapInfo Pro stores the key's name in the key_name_var variable, and stores the key's value in the key_value_var variable. If there are no more keys to read, MapInfo Pro stores empty strings in both variables.

Destroy

Ends the traversal, and frees the memory that was used by the traversal.

Example

The following procedure reads all metadata values from a table; the table name is specified by the caller. This procedure prints the key names and key values to the Message window.

Sub Print_Metadata(ByVal table_name As String) 
	Dim i_traversal As Integer 
	Dim s_keyname, s_keyvalue As String 

	' Initialize the traversal: 
	Metadata Table table_name 
		SetTraverse "\" Hierarchical Into ID i_traversal 

	' Attempt to fetch the first key: 
	Metadata Traverse i_traversal 
	Next Into Key s_keyname Into Value s_keyvalue 

	' Now loop for as long as there are key values; 
	' with each iteration of the loop, retrieve 
	' one key, and print it to the Message window. 
	Do While s_keyname <> "" 
		Print " "
		Print "Key name: " & s_keyname 
		Print "Key value: " & s_keyvalue

	Metadata Traverse i_traversal 
		Next Into Key s_keyname Into Value s_keyvalue 
	Loop 

	' Release this traversal to free memory: 
	MetaData Traverse i_traversal Destroy 

End Sub 

See Also: