Understanding the behavior of the insert and append APIs

The tpf_doc_insertElement and tpf_doc_appendElement APIs have the following behaviors in common:

New elements are created as child elements of the element that immediately precedes (in document order) the current position pointer, or as child elements of the ancestors of that element.
When the element that immediately precedes the current position pointer (in document order) is the parent that was specified on the function call, the new element is created as the first child of that element for the tpf_doc_insertElement API and as the last child of that element for the tpf_doc_appendElement API.
When the element that immediately precedes the current position pointer (in document order) is not the parent that was specified for the function call, the z/TPF system traverses up the tree structure in tree order, where up means following the path to the root element starting with the element that immediately precedes the current position pointer and following the ancestors until the specified parent element is found or the root element is reached. When the correct parent is found, the new element is created as the next sibling of the last ancestor that was traversed before finding the specified parent for the tpf_doc_insertElement API or as the last child of the parent for the tpf_doc_appendElement API.