Caché Basic Reference
Traverse
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

Traverses an array and returns the next subscript.
Synopsis
Traverse(varname[,direction[,target]])
Arguments
varname The name of a variable representing an array. varname must specify a subscript level.
direction Optional — Numeric value, which specifies either forward (1) or backward (-1). If this parameter is omitted the Traverse function will move forward to the next subscript.
target Optional — Variable which contains the data of the resulting node.
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