FindNode Method (XDATA)

9.8A

The FindNode method locates a node starting at the current node by using the FILTER parameter. The method uses the following format:

[label]	{object}.FindNode	[GIVING {return}] USING Filter={filter*}[:
		Position={position}][,Options={mask}]

Where:

label: Optional. A Program Execution Label.
object: Required. An XDATA object.
return: Optional. A Numeric Variable that receives a value to signify a pass or fail condition for the method execution.
filter: Required. A Character String Variable or literal that specifies the filter string value used to find a node in the node tree.
position: Required. A Numeric Variable or decimal number that specifies the position in the node tree where the find operation starts searching.
mask: Optional. A Numeric Variable or decimal number that specifies a bit mask value to control the operations of this method.

Flags Affected: EOS, OVER, ZERO

Note the following:

The ZERO flag is set if the {return} value is zero.
The OVER flag is set TRUE if the {return} variable is too small where the returned value is truncated.
The EOS flag is always cleared.
The {position} values are defined as follows:

Keyword	Value	Start the find operation at the ...
START_CURRENT_NODE	0	current node.
START_PARENT_NODE	1	parent node.
START_FIRST_CHILD	2	first child node.
START_LAST_CHILD	3	last child node.
START_PREVIOUS_SIBLING	4	previous sibling node children.
START_NEXT_SIBLING	5	next sibling node.
START_DOCUMENT_NODE	6	document node.

The {return} value is a zero if the method execution is successful. Otherwise, a non-zero value is returned to indicate an error has occurred. See the XDATA Method Return Values for more details.
This method can return these values:

Value	Meaning
0	XDATA_ERR_NONE (Success)
1	XDATA_ERR_NO_MEM
2	XDATA_ERR_INVALID_POSITION_TYPE
11	XDATA_ERR_INVALID_POSITION

The FILTER parameter uses the same expression syntax that is for the FILTER instruction. However, all of the field names are static with the following names:

Comment

Data

JsonType

Label

Name

ParentLabel

PubId

SysId

Type

Text

Target

If a FindNode match is successful, the current node position is moved to the matching node.

Example:

xData	XDATA
.
	xData.FindNode GIVING result:
		USING *FILTER="label='FirstName'":
		*POSITION=START_DOCUMENT_NODE
.
	xData.FindNode GIVING result:
		USING *FILTER="jsontype=2 AND label LIKE '%ray%'":
		*POSITION=START_DOCUMENT_NODE

See Also: XDATA, XDATA Methods, Method Syntax