For a SAX-writer object, adds a single attribute to a start tag in the XML document represented by the SAX-writer object. For a SAX-attributes object, inserts an attribute and its value into the SAX-attributes object.

CAUTION: The SAX specifications specifically state that the order of attributes in an XML element's list are not guaranteed.

Return type: LOGICAL

Applies to: SAX-attributes object handle, SAX-writer object handle

Syntax

INSERT-ATTRIBUTE ( attribute-name , attribute-value[ , namespaceURI] )
attribute-name
A CHARACTER or LONGCHAR expression evaluating to the fully qualified or unqualified name of the attribute.
attribute-value
A CHARACTER or LONGCHAR expression evaluating to the value of the attribute.
namespaceURI
A CHARACTER or LONGCHAR expression evaluating to:
  • The URI of the attribute
  • A zero-length string
  • The Unknown value (?) if the attribute doesn't contain a namespace

SAX-writer object handle usage

Call this method to add a simple, single attribute to a start tag. You can only call this method immediately after a call to the START-ELEMENT, EMPTY-ELEMENT, INSERT-ATTRIBUTE, or DECLARE-NAMESPACE method. That is, you can only call this method when the WRITE-STATUS is SAX-WRITE-TAG. After calling this method, the status remains SAX-WRITE-TAG.

The STRICT attribute setting determines if the XML output for a SAX-writer object is well formed. However, regardless of the value of the STRICT attribute, this method fails if you do not call it following one of the methods listed in the previous paragraph.

SAX-attributes object handle usage

Call this method to add an attribute to a SAX-attributes object. If there are already attributes in the SAX-attributes object, then the new attribute is added to the end of the list. For example, if the SAX-attributes object has three attributes, then the NUM-ITEMS attribute value will be 3. After calling this method, NUM-ITEMS will be 4 and the new attribute will be located at index position 4.

You can use this method to populate a new SAX-attributes object from scratch. For example, if all the XML elements in a particular document have a default set of attributes, you can create one SAX-attributes object to hold the default set and reuse that SAX-attributes object when writing each XML element.

No validation is done on inserted data. Care must be taken to not enter duplicate attribute names. Non-unique attribute names prevent XML from being validated as well formed XML. Such a result will cause an error with the SAX-writer object during writing operations if the STRICT attribute is set to TRUE.

CAUTION: Use the UPDATE-ATTRIBUTE( ) to change attribute values. Using the INSERT-ATTRIBUTE( ) method with an attribute name that already exists in a SAX-attributes object results in duplicate attribute names. The resulting XML is not well-formed and may fail validation within ABL applications and within third-party XML-enabled applications.

Namespace declarations with attributes

Namespace declarations appear as attributes in an XML document. You can declare a namespace by using the INSERT-ATTRIBUTE( ) method instead of using the SAX-writer object's DECLARE-NAMESPACE( ) method. To do this, you must use the special prefix for namespaces, xmlns, with the name of the attribute, and the namespaceURI must be the value of the attribute.

swh:START-ELEMENT("prefix:name").
swh:INSERT-ATTRIBUTE("xmlns:prefix", "target.url").
swh:END-ELEMENT("prefix:name").

The previous example is equivalent to the following example, which uses the traditional method:

swh:START-ELEMENT("prefix:name").
swh:DECLARE-NAMESPACE("target.url", "prefix").
swh:END-ELEMENT("prefix:name").

Namespaces declared using the INSERT-ATTRIBUTE( ) method in this way are considered valid namespaces and will be included in namespace checking during the XML write operation. If the xmlns prefix does not appear, then the attribute is inserted as a regular attribute and it is not handled with the namespace checking during the XML write operation.

Similarly, namespaces that appear as such in a SAX-attributes object will also generate the appropriate namespace.

If you use namespaceURI, then the method resolves the prefix in the following order:

  • It attempts to extract the namespace from attribute-name.
  • It attempts to extract the namespace from a previously declared namespace.

If the method call only contains name and that value contains a prefix, then the SAX-writer attempts to resolve the prefix to a namespace. If it fails to resolve the namespace and the STRICT attribute is TRUE, then the method fails.

Note: The INSERT-ATTRIBUTE( ) method allows some non-printing characters to be written to XML documents. These characters (for example, #x1, #x1F) are not part of the XML Version 1.0 standard, but are allowed in order to support ABL applications.

The following is a SAX-attributes object example:

DEFINE VARIABLE hSAX-attributes AS HANDLE NO-UNDO.

CREATE SAX-ATTRIBUTES hSAX-attributes.

hSAX-attributes:INSERT-ATTRIBUTE( "language", "EN" ). /* index = 1 */
hSAX-attributes:INSERT-ATTRIBUTE( "year", "2006" ).   /* index = 2 */

See also

DECLARE-NAMESPACE( ) method, REMOVE-ATTRIBUTE( ) method, UPDATE-ATTRIBUTE( ) method