Nodes in a tree are arranged into multi-branched structures as in the following example, which shows a partially expanded tree from a typical experiment. (An experimental tree may contain over 30,000 nodes, so obviously only a very small portion is shown in the figure.) The text in each box is the NODE NAME which is used to identify the node. Node names are limited to 12 characters.

The top of the hierarchy is a node whose name is the name of the tree; "Magnetics" in this example. Under the top node are a number of CHILD nodes. This type of node embodies the structural relationships of the tree and cannot contain data. There is essentially no limit on the number of levels which can be created with child nodes. The node on the far right "Ip" is an example of a MEMBER, a type of node used to contain data. It may be useful to think of child and member nodes as analogous to the directories and files on a typical operating system. A feature in MDSplus is that member nodes may have their own children or members underneath them.

Each node in a tree has a unique numerical node id or NID. These are 4 byte integers used by MDSplus code and not commonly referred to by users. However, there are special cases where these are useful, see for example the section below - TDI:Getting MDSplus Metadata.

Each node is assigned a USAGE when it is created. This node characteristic defines and limits how a particular node can be used. Some common node usage types are:

DEVICE            a composite node used for data acquisition o
                  automated analysis
NUMERIC           contains simple numerical data (including arrays)
SIGNAL            contains the composite datatype signal, which
                  stores data along with its independent axis
STRUCTURE         nodes used for tree structure - a "child" node
SUBTREE           the top node of an MDSplus tree
TEXT              contains simple character data (including arrays)

Specifying Nodes In A Tree

In order to access information from an MDSplus tree, a user must specify a unique, "fully qualified" name or reference pointing to the node which contains the information. Note that unqualified node names may not be unique in a particular tree. For example, there may be many nodes with the node name "channel_1". There are three ways to uniquely specify a node in a tree; the FULL PATH NAME (also called an absolute node reference), a RELATIVE PATH NAME (or relative node reference), and a TAG NAME. In the example shown, the full path for the node labeled "Ip" can be written as:

\magnetics::top.processed.current_data:ip

The syntax for MDSplus node specifications is \treename::top.child1.child2:member. The tree name is preceded by a backwards slash ("\") and followed by two colons ("::") and the string "top". Each child node in the path is preceded by a dot (".") and each member node preceded by a single colon (":"). To ensure that nodes can be uniquely specified, fully qualified names must be unique - that means that no node may have two child nodes or member nodes with the same name. We can see that the 12 character limitation on node names does not prevent the creation of meaningful node specifications, since these will use the full path designations.

Right after a tree has been opened (with mdsopen), the DEFAULT is set to the top node of the tree. So in our example, the same node could be accessed using a relative path name (relative to the top node in this case):

'.processed.current_data:ip'

A new default may be specified with the command like mdsset_def,'node_specification' (the precise syntax will depend on the programming language being used.) For example, if the default is set by the command, mdsset_def,'.processed', data in the node labeled "Ip" can be accessed using the relative path name:

'.current_data:ip'

The same node can also be specified by its TAG name. These names, limited to 23 characters, are associated with a node when it is first created in a model tree. A given node may have more than one tag name. To ensure that nodes can be uniquely specified, every tag name in a particular tree must be unique. Tag names allow a shorthand method for specifying paths which could otherwise get long and difficult to type. They also allow users point to data in a hierarchy-independent way. This can be useful for quantities which have a persistent meaning to users but whose place in the hierarchy may evolve over time. The following syntax specifies a node by its tag name, which is "Ip" in this case, the same as the node name.

'\magnetics::ip'  or 
'\ip'

That is tags are referred to with a backslash followed by their name or qualified with their tree name. The double colon is used to indicate that the name that follows is a tag. Tags need not point to the "leaves" of trees; they also provide a useful shorthand for intermediate nodes which are frequently referred to. Note in the full path example, magnetics::top, "top" is a reserved tag name which always points to the top of a tree, so another way to specify the node in question is:

'\top.processed.current_data:ip'

In which the tag name is followed by an explicit path name. Tag names are limited to 23 characters.

[Note: in the documentation that follows, the term "node name" may refer to either the label of a particular node or to one of the fully qualified path names as described above. Which term is meant should generally be clear from the context.]

More details on tree structures and syntax, including a description of the use of wild card characters in path names, can be found in the users manual; see TREE SYNTAX

next page