Skip Headers

Oracle® XML API Reference 10g Release 1 (10.1) Part No. B10789-01 |
| Contents

## Attr Interface

Table 4-1 summarizes the methods of available through the `Attr` interface.

Table 4-1 Summary of Attr Methods; DOM Package

Function | Summary
--- | ---
XmlDomGetAttrLocal | Returns an attribute's namespace local name as `NULL`-terminated string.
XmlDomGetAttrLocalLen | Returns an attribute's namespace local name as length-encoded string.
XmlDomGetAttrName | Return attribute's name as `NULL`-terminated string.
XmlDomGetAttrNameLen | Return attribute's name as length-encoded string.
XmlDomGetAttrPrefix | Returns an attribute's namespace prefix.
XmlDomGetAttrSpecified | Return flag that indicates whether an attribute was explicitly created.
XmlDomGetAttrURI | Returns an attribute's namespace URI as `NULL`-terminated string.
XmlDomGetAttrURILen | Returns an attribute's namespace URI as length-encoded string.
XmlDomGetAttrValue | Return attribute's value as `NULL`-terminated string.
XmlDomGetAttrValueLen | Return attribute's value as length-encoded string.
XmlDomGetAttrValueStream | Get attribute value stream-style,i.e.chunked.
XmlDomGetOwnerElem | Return an attribute's "owning" element.
XmlDomSetAttrValue | Set an attribute's value.
XmlDomSetAttrValueStream | Sets an attribute value stream style (chunked).

### XmlDomGetAttrLocal

Returns an attribute's namespace local name (in the data encoding). If the attribute's name is not fully qualified (has no prefix), then the local name is the same as the name.

A length-encoded version is available as `XmlDomGetAttrURILen` which returns the local name as a pointer and length, for use if the data is known to use `XMLType` backing store.

Syntax

    oratext* XmlDomGetAttrLocal(
       xmlctx *xctx,
       xmlattrnode *attr)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    attr
    IN
| attribute node

Returns

`(oratext *)` attribute's local name [data encoding]

See Also: XmlDomGetAttrLocalLen, XmlDomGetAttrName, XmlDomGetAttrURI, XmlDomGetAttrPrefix

### XmlDomGetAttrLocalLen

Returns an attribute's namespace local name (in the data encoding). If the attribute's name is not fully qualified (has no prefix), then the local name is the same as the name.

A `NULL`-terminated version is available as `XmlDomGetAttrLocal` which returns the local name as `NULL`-terminated string. If the backing store is known to be `XMLType`, then the attribute's data will be stored internally as length-encoded. Using the length-based `Get` `XXX` functions will avoid having to copy and `NULL`-terminate the data.

If both the input buffer is non-`NULL` and the input buffer length is nonzero, then the value will be stored in the input buffer. Else, the implementation will return its own buffer.

If the actual length is greater than `buflen`, then a truncated value will be copied into the buffer and len will return the actual length.

Syntax

    oratext* XmlDomGetAttrLocalLen(
       xmlctx *xctx,
       xmlattrnode *attr,
       oratext *buf,
       ub4 buflen,
       ub4 *len)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    attr
    IN
| attribute node
    buf
    IN
| input buffer; optional
    buflen
    IN
| input buffer length; optional
    len
    OUT
| length of local name, in characters

Returns

`(oratext *)` `Attr`'s local name [data encoding]

See Also: XmlDomGetAttrLocal, XmlDomGetAttrName, XmlDomGetAttrURI, XmlDomGetAttrPrefix

### XmlDomGetAttrName

Returns the fully-qualified name of an attribute (in the data encoding) as a `NULL`-terminated string, for example `bar\0` or `foo:bar\0`.

A length-encoded version is available as `XmlDomGetAttrNameLen` which returns the attribute name as a pointer and length, for use if the data is known to use `XMLType` backing store.

Syntax

    oratext* XmlDomGetAttrName(
       xmlctx *xctx,
       xmlattrnode *attr)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    attr
    IN
| attribute node

Returns

`(oratext *)` name of attribute [data encoding]

See Also: XmlDomGetAttrNameLen, XmlDomGetAttrURI, XmlDomGetAttrPrefix, XmlDomGetAttrLocal

### XmlDomGetAttrNameLen

Returns the fully-qualified name of an attribute (in the data encoding) as a length-encoded string, for example `("bar", 3)` or `("foo:bar", 7)`.

A `NULL`-terminated version is available as `XmlDomGetAttrName` which returns the attribute name as `NULL`-terminated string. If the backing store is known to be `XMLType`, then the attribute's data will be stored internally as length-encoded. Using the length-based `Get` `XXX` functions will avoid having to copy and `NULL`-terminate the data.

If both the input buffer is non-`NULL` and the input buffer length is nonzero, then the value will be stored in the input buffer. Else, the implementation will return its own buffer.

If the actual length is greater than `buflen`, then a truncated value will be copied into the buffer and `len` will return the actual length.

Syntax

    oratext* XmlDomGetAttrNameLen(
       xmlctx *xctx,
       xmlattrnode *attr,
       oratext *buf,
       ub4 buflen,
       ub4 *len)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    attr
    IN
| attribute node
    buf
    IN
| input buffer; optional
    buflen
    IN
| input buffer length; optional
    len
    OUT
| length of local name, in characters

Returns

`(oratext *)` name of attribute [data encoding]

See Also: XmlDomGetAttrName, XmlDomGetAttrURI, XmlDomGetAttrPrefix, XmlDomGetAttrLocal

### XmlDomGetAttrPrefix

Returns an attribute's namespace prefix (in the data encoding). If the attribute's name is not fully qualified (has no prefix), `NULL` is returned.

Syntax

    oratext* XmlDomGetAttrPrefix(
       xmlctx *xctx,
       xmlattrnode *attr)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    attr
    IN
| attribute node

Returns

`(oratext *)` attribute's namespace prefix [data encoding] or `NULL`

See Also: XmlDomGetAttrName, XmlDomGetAttrURI, XmlDomGetAttrLocal

### XmlDomGetAttrSpecified

Return the 'specified' flag for an attribute. If the attribute was explicitly given a value in the original document, this is `TRUE`; otherwise, it is `FALSE`. If the node is not an attribute, returns `FALSE`. If the user sets an attribute's value through DOM, its specified flag will be `TRUE`. To return an attribute to its default value (if it has one), the attribute should be deleted; it will then be re-created automatically with the default value (and specified will be `FALSE`).

Syntax

    boolean XmlDomGetAttrSpecified(
       xmlctx *xctx,
       xmlattrnode *attr)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    attr
    IN
| attribute node

Returns

`(boolean)` attribute's "specified" flag

See Also: XmlDomSetAttrValue

### XmlDomGetAttrURI

Returns an attribute's namespace URI (in the data encoding). If the attribute's name is not qualified (does not contain a namespace prefix), it will have the default namespace in effect when the node was created (which may be `NULL`).

A length-encoded version is available as `XmlDomGetAttrURILen` which returns the URI as a pointer and length, for use if the data is known to use `XMLType` backing store.

Syntax

    oratext* XmlDomGetAttrURI(
       xmlctx *xctx,
       xmlattrnode *attr)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    attr
    IN
| attribute node

Returns

`(oratext *)` attribute's namespace URI [data encoding] or `NULL`

See Also: XmlDomGetAttrURILen, XmlDomGetAttrPrefix, XmlDomGetAttrLocal

### XmlDomGetAttrURILen

Returns an attribute's namespace URI (in the data encoding) as length-encoded string. If the attribute's name is not qualified (does not contain a namespace prefix), it will have the default namespace in effect when the node was created (which may be `NULL`).

A `NULL`-terminated version is available as `XmlDomGetAttrURI` which returns the URI as `NULL`-terminated string. If the backing store is known to be `XMLType`, then the attribute's data will be stored internally as length-encoded. Using the length-based Get functions will avoid having to copy and `NULL`-terminate the data.

If both the input buffer is non-`NULL` and the input buffer length is nonzero, then the value will be stored in the input buffer. Else, the implementation will return its own buffer.

If the actual length is greater than buflen, then a truncated value will be copied into the buffer and len will return the actual length.

Syntax

    oratext* XmlDomGetAttrURILen(
       xmlctx *xctx,
       xmlattrnode *attr,
       oratext *buf,
       ub4 buflen,
       ub4 *len)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    attr
    IN
| attribute node
    buf
    IN
| input buffer; optional
    buflen
    IN
| input buffer length; optional
    len
    OUT
| length of URI, in characters

Returns

`(oratext *)` attribute's namespace URI [data encoding] or `NULL`

See Also: XmlDomGetAttrURI, XmlDomGetAttrPrefix, XmlDomGetAttrLocal

### XmlDomGetAttrValue

Returns the "value" (character data) of an attribute (in the data encoding) as `NULL`-terminated string. Character and general entities will have been replaced.

A length-encoded version is available as `XmlDomGetAttrValueLen` which returns the attribute value as a pointer and length, for use if the data is known to use `XMLType` backing store.

Syntax

    oratext* XmlDomGetAttrValue(
       xmlctx *xctx,
       xmlattrnode *attr)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    attr
    IN
| attribute node

Returns

`(oratext *)` attribute's value

See Also: XmlDomGetAttrValueLen, XmlDomSetAttrValue

### XmlDomGetAttrValueLen

Returns the "value" (character data) of an attribute (in the data encoding) as length-encoded string. Character and general entities will have been replaced.

A `NULL`-terminated version is available as `XmlDomGetAttrValue` which returns the attribute value as `NULL`-terminated string. If the backing store is known to be `XMLType`, then the attribute's data will be stored internally as length-encoded. Using the length-based `Get` `XXX` functions will avoid having to copy and `NULL`-terminate the data.

If both the input buffer is non-`NULL` and the input buffer length is nonzero, then the value will be stored in the input buffer. Else, the implementation will return its own buffer.

If the actual length is greater than buflen, then a truncated value will be copied into the buffer and len will return the actual length.

Syntax

    oratext* XmlDomGetAttrValueLen(
       xmlctx *xctx,
       xmlattrnode *attr,
       oratext *buf,
       ub4 buflen,
       ub4 *len)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    attr
    IN
| attribute node
    buf
    IN
| input buffer; optional
    buflen
    IN
| input buffer length; optional
    len
    OUT
| length of attribute's value, in characters

Returns

`(oratext *)` attribute's value

See Also: XmlDomGetAttrValue, XmlDomSetAttrValue

### XmlDomGetAttrValueStream

Returns the large "value" (associated character data) for an attribute and sends it in pieces to the user's output stream. For very large values, it is not always possible to store them [efficiently] as a single contiguous chunk. This function is used to access chunked data of that type.

Syntax

    xmlerr XmlDomGetAttrValueStream(
       xmlctx *xctx,
       xmlnode *attr,
       xmlostream *ostream)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    attr
    IN
| attribute node
    ostream
    IN
| output stream object

Returns

`(xmlerr)` numeric error code, `0` on success

### XmlDomGetOwnerElem

Returns the `Element` node associated with an attribute. Each attr either belongs to an element (one and only one), or is detached and not yet part of the DOM tree. In the former case, the element node is returned; if the attr is unassigned, `NULL` is returned.

Syntax

    xmlelemnode* XmlDomGetOwnerElem(
       xmlctx *xctx,
       xmlattrnode *attr)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    attr
    IN
| attribute node

Returns

`(xmlelemnode *)` attribute's element node [or `NULL`]

See Also: XmlDomGetOwnerDocument

### XmlDomSetAttrValue

Sets the given attribute's value to data. If the node is not an attribute, does nothing. Note that the new value must be in the data encoding! It is not verified, converted, or checked. The attribute's specified flag will be `TRUE` after setting a new value.

Syntax

    void XmlDomSetAttrValue(
       xmlctx *xctx,
       xmlattrnode *attr,
       oratext *value)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    attr
    IN
| attribute node
    value
    IN
| new value of attribute; data encoding

See Also: XmlDomGetAttrValue

### XmlDomSetAttrValueStream

Sets the large "value" (associated character data) for an attribute piecemeal from an input stream. For very large values, it is not always possible to store them efficiently as a single contiguous chunk. This function is used to access chunked data of that type.

Syntax

    xmlerr XmlDomSetAttrValueStream(
       xmlctx *xctx,
       xmlnode *attr,
       xmlistream *istream)

Parameter | In/Out | Description
--- | --- | ---
    xctx
    IN
| XML context
    attr
    IN
| attribute node
    isream
    IN
| input stream

Returns

`(xmlerr)` numeric error code, `0` on success