CreateText Method (XDATA)

9.8A

The CreateText method generates a DOM_TEXT_NODE node at a specified position. The method uses the following format:

[label]	{object}.CreateText	[GIVING {return}] USING Position={position*}:
		Text={text}[,JSONType={type}][:
		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.
position: Required. A Numeric Variable or decimal number that specifies the position in the node tree where the text node is inserted.
text: Required. A Character String Variable or literal that specifies the text string value of the node.
type: Optional. A Character String Variable or literal that specifies the jsontype value used when outputing a document for JSON.
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 {type} parameter is only used for JSON output which causes the {text} data to be enclosed in double quotes when the JSON_TYPE_STRING is used. Otherwise, the JSON {text} is not enclosed by double quotes for any other JSON type value. If this parameter is not used, the JSON output defaults to use JSON_TYPE_STRING.
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	Meaning...
CREATE_AS_CURRENT_NODE	0	Replace the current node.
CREATE_AS_PARENT_NODE	1	Insert node as the parent.
CREATE_AS_FIRST_CHILD	2	Insert node as first child node.
CREATE_AS_LAST_CHILD	3	Insert node as last child node.
CREATE_AS_PREVIOUS_SIBLING	4	Insert node as previous sibling node.
CREATE_AS_NEXT_SIBLING	5	Insert node as next sibling node.

Value	Description
0x1	This bit value causes the current node tree position to be changed to the newly created node position of the attribute. See the MOVE_TO_CREATE_NODE value.

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

Example:

xData	XDATA
xText	INIT	"Somebody Listening?"
.
	xData.CreateText GIVING result:
		USING *POSITION=CREATE_AS_FIRST_CHILD:
		*TARGET=xText:
		*OPTIONS=MOVE_TO_CREATED_NODE

In this example code, the following simple JSON string is created by the previous XDATA CreateText method:

{"Somebody Listening?"}

In this example code, the following simple XML string is created by the previous XDATA CreateText method

Somebody Listening?

See Also: XDATA, XDATA Methods, Method Syntax