START-ELEMENT( ) method

Syntax
START-ELEMENT( `name` [, `namespace-URI` ] [, `SAX-attributes-handle` ] )

name

A CHARACTER or LONGCHAR expression evaluating to the fully qualified or unqualified name of the element.

namespace-URI

A CHARACTER or LONGCHAR evaluating to the URI of the element, or an empty string ("") or the Unknown value (?) if the element doesn’t contain a namespace. If the handle is the Unknown value (?), then no attributes are added. If the handle is not valid or not a SAX-attributes object, then the method fails and returns FALSE.

SAX-attributes-handle

A HANDLE to a SAX-attributes object. The attributes in the SAX-attributes object are added to the new XML element.

For every call of the START-ELEMENT( )method, there must be a following corresponding call of the END-ELEMENT( ) method. All the parameter values from the two calls must match for the methods to correspond.

If namespace-URI is present, then the prefix will be resolved in the following order:

The method attempts to extract the namespace from the name.

The method attempts to extract the namespace from a previously declared namespace.

The method attempts to generate the default namespace.

If the name contains a prefix, namespace-URI is present, and this is the first instance of the namespace-URI, then the namespace is added to the element. This technique is equivalent to calling the DECLARE-NAMESPACE( ) method.

If only the name is present and it contains a prefix, then the SAX-writer attempts to resolve the prefix to a namespace.

If the SAX-attributes-handle is supplied, then attributes are written out after the name of the element, in the order that they are indexed in the SAX-attributes object. If they contain namespace information, then that information is handled as if the attribute were added using the INSERT-ATTRIBUTE( ) method.

If the STRICT attribute is TRUE, the FRAGMENT attribute is FALSE, and the call would result in more than one document-level element (that is, root node), then the method fails. Also, if STRICT is TRUE, an external DTD has been declared, and the call would create the root node, then the name used for the DTD declaration must match the name of the root node or the method fails.