Traverse

Synopsis

Traverse(varname[,direction[,target]])

Description

The Traverse function returns the name of the next or previous subscript on the specified subscript level. Using the optional, target argument you can also return the data value of the located subscript.

To start a search from the beginning of the current level, specify a empty string ("") for the subscript. The following example returns the first subscript on the first subscript level:

subscript = Traverse(^Person(""))

When the Traverse reaches the end of the subscripts for the given level, it returns an empty string ("") .

The following example demonstrates how to use the Traverse function within a loop:

subscript = ""
subscript = Traverse(^Person(subscript))
While subscript <> ""
  subscript = Traverse(^Person(subscript))
  Println subscript
wend

If a target variable is specified and the node is defined (vbHasValue) the target variable will contain the data for this node. If the resulting node does not have a value the value of the target variable is unchanged.

Caché Basic provides two constants, vbForward and vbBackward to specify the direction.

Examples

The following example demonstrates the use of the Traverse function to return the subscript name of the next node. The first Traverse specifies the empty string as the subscript, and returns the name of the first subscript (“A”) in the array. The second and third Traverse functions specify a subscript name and return the name of the next subscript. The fourth Traverse specifies a subscript of “C” and a direction of -1 (backwards); it returns the name of the previous subscript (“B”). The final Traverse specifies the empty string as the subscript, and a direction of -1; it returns the name of the final subscript (the first subscript reading backwards from the end of the array), in this case “D”.

array("A") = "A node"
array("B") = "B node"
array("B", 1) = "B,1 node"
array("B", 2) = "B,2 node"
array("C", 1) = "C node"
array("D") = "D node"

Println Traverse(array(""))  ' prints A
Println Traverse(array("A")) ' prints B
Println Traverse(array("B")) ' prints C
Println Traverse(array("C"),-1) ' prints B
Println Traverse(array(""),-1) ' prints D

The following example demonstrates the use of the target argument. The first myString contains the data value of the “A” node. The second myString references a node (“C”) which contains on data value at this level. In this case, myString continues to contain its previous value.

array("A") = "A node"
array("B") = "B node"
array("C", 1) = "C1 node"
array("D") = "D node"

Println Traverse(array(""),1,myString)  ' prints A
Println myString                        ' prints A node
Println Traverse(array("B"),1,myString) ' prints C
Println myString                        ' prints A node

See Also

• Exists function