CreateElement Method (XDATA)

9.8A

The CreateElement method generates an element node at a specified position. The method uses the following format:

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 document type is inserted.

label

Required. A Character String Variable or literal that specifies the label string value of the node.

text

Optional. 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:

1. After the create operation, the node tree position does not move to the newly created node unless the OPTIONS parameter is used.

2. The ZERO flag is set if the {return} value is zero.

3. The OVER flag is set TRUE if the {return} variable is too small where the returned value is truncated.

4. The EOS flag is always cleared.

5. 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.

 

6. The *OPTIONS {mask} values are defined as follows:

 

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.

 

7. 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.

8. 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

 

9. If the {text} parameter and the JSON {type} parameters are not being used, the default method behavior when outputting a JSON document is to generate a JSON object.

10. If the parent of the created element has a JSONTYPE of JSON_TYPE_ARRAY, then a special label prefix of 'object' can be used when creating a JSON_TYPE_OBJECT to prevent the label from being output in the JSON array object elements. See Example 5.

Examples:

1. Example of CreateElement method for JSON or XML:

 

xData	XDATA
.
	xData.CreateElement GIVING result:
		USING *POSITION=CREATE_AS_LAST_CHILD:
		*LABEL="employee":
		*JSONTYPE=JSON_TYPE_OBJECT:
		*OPTIONS=MOVE_TO_CREATED_NODE
.
	xData.CreateElement GIVING result:
		USING *POSITION=CREATE_AS_FIRST_CHILD:
		*LABEL="firstName":
		*TEXT="John":
		*JSONTYPE=JSON_TYPE_STRING:
		*OPTIONS=MOVE_TO_CREATED_NODE
.
	xData.CreateElement GIVING result:
		USING *POSITION=CREATE_AS_NEXT_SIBLING:
		*LABEL="lastName":
		*TEXT="Doe":
		*JSONTYPE=JSON_TYPE_STRING

 

In this example code , the following simple JSON object string is created by the previous XDATA CreateElement methods

 

     "employee":{"firstName":"John", "lastName":"Doe"}

 

In this case, the "employee" is a JSON object with two JSON fields named "firstName" and "lastName". These JSON fields have a value that is a JSON string.

 

In this example code, the following simple XML string is created by the previous XDATA CreateElement methods:

 

     <employee>

     <firstName>John</firstName>

     <lastName>Doe</lastName>

     </employee>

 

2. Example of CreateElement method for JSON or XML when no {text} or JSON {type} parameters are used. In this example, all of the elements are defaulting to a JSON_TYPE_OBJECT.

 

xData	XDATA
.
	xData.CreateElement GIVING result:
		USING *POSITION=CREATE_AS_LAST_CHILD:
		*LABEL="employee":
		*OPTIONS=MOVE_TO_CREATED_NODE
.
	xData.CreateElement GIVING result:
		USING *POSITION=CREATE_AS_FIRST_CHILD:
		*LABEL="firstName":
		*OPTIONS=MOVE_TO_CREATED_NODE
.
	xData.CreateElement GIVING result:
		USING *POSITION=CREATE_AS_NEXT_SIBLING:
		*LABEL="lastName"

 

In this example code , the following simple JSON object string is created by the previous XDATA CreateElement methods where the "firstName" and the "lastName" are JSON objects that are empty.

 

     "employee":{"firstName":{}, "lastName":{}}

 

In this case, the "employee" is a JSON object with two JSON fields named "firstName" and "lastName". These JSON fields have a value that is an empty JSON object.

 

In this example code, the following simple XML string is created by the previous XDATA CreateElement methods.

 

     <employee>

           <firstName></firstName>

           <lastName></lastName>

     </employee>

 

3. Example of CreateElement method for JSON or XML for array output:

 

xData	XDATA
.
	xData.CreateElement GIVING result:
		USING *POSITION=CREATE_AS_LAST_CHILD:
		*LABEL="employee":
		*JSONTYPE=JSON_TYPE_ARRAY:
		*OPTIONS=MOVE_TO_CREATED_NODE
.
	xData.CreateElement GIVING result:
		USING *POSITION=CREATE_AS_FIRST_CHILD:
		*LABEL="firstName":
		*TEXT="John":
		*JSONTYPE=JSON_TYPE_STRING:
		*OPTIONS=MOVE_TO_CREATED_NODE
.
	xData.CreateElement GIVING result:
		USING *POSITION=CREATE_AS_NEXT_SIBLING:
		*LABEL="lastName":
		*TEXT="Doe":
		*JSONTYPE=JSON_TYPE_STRING

 

In this example code , the following simple JSON object string is created by the previous XDATA CreateElement methods to output a JSON array.

 

     "employee":[{"firstName":"John"}, {"lastName":"Doe"}]

 

In this case, the "employee" is a JSON array with two array JSON object elements.

 

In this example code, the following simple XML string is created by the previous XDATA CreateElement methods

 

     <employee>

           <firstName>John</firstName>

           <lastName>Doe</lastName>

     </employee>

 

4. This example shows an 'employees' JSON array that contains JSON objects for each 'Employee':

In this example code , the following simple JSON object string is created by the previous XDATA CreateElement methods to output a JSON array where each array element has the "Employee" label name.

"employees":[{"Employee":{"firstName":"John,"lastName":"Doe"}}]

In this case, the "employees" is a JSON array with one JSON object element that has the "Employee" label.

1. This example shows an 'employees' JSON array that contains JSON objects where each JSON object element DOES NOT have an "Employee" label reference:

 

 

xData	XDATA
.
	xData.CreateElement	GIVING result:
		USING *POSITION=CREATE_AS_LAST_CHILD:
		*LABEL="employees":
		*JSONTYPE=JSON_TYPE_ARRAY:
		*OPTIONS=MOVE_TO_CREATED_NODE
.
. By adding the prefix of 'object' ( Is case sensitive! ) to
. use the LABEL of "objectEmployee", the JSON array output
. DOES NOT include the "Employee" for each JSON array object element.
.
	xData.CreateElement	GIVING result:
		USING *POSITION=CREATE_AS_FIRST_CHILD:
		*LABEL="objectEmployee":
		*JSONTYPE=JSON_TYPE_OBJECT:
		*OPTIONS=MOVE_TO_CREATED_NODE
.
	xData.CreateElement	GIVING result
		USING *POSITION=CREATE_AS_FIRST_CHILD:
		*LABEL="firstName":
		*TEXT="John":
		*JSONTYPE=JSON_TYPE_STRING:
		*OPTIONS=MOVE_TO_CREATED_NODE
.
	xData.CreateElement	GIVING result:
		USING *POSITION=CREATE_AS_NEXT_SIBLING:
		*LABEL="lastName":
		*TEXT="Doe":
		*JSONTYPE=JSON_TYPE_STRING

 

 

In this example code, the following simple JSON object string is created by the previous XDATA CreateElement methods to output a JSON array where each array element object does not have the "Employee" label name.

 

"employees":[{"firstName":"John,"lastName":"Doe"}]

 

In this case, the "employees" is a JSON array with one JSON object element that does not have an "Employee" label.

See Also: XDATA, XDATA Methods, Method Syntax