PK nFJoa,mimetypeapplication/epub+zipPKnFJMETA-INF/container.xml PKYuPKnFJOEBPS/soap.htm Package SOAP APIs for C

9 Package SOAP APIs for C

W3C: "SOAP is a lightweight protocol for exchange of information in a decentralized, distributed environment. It is an XML based protocol that consists of three parts: an envelope that defines a framework for describing what is in a message and how to process it, a set of encoding rules for expressing instances of application-defined datatypes, and a convention for representing remote procedure calls and responses."

Attachments are not allowed in Soap 1.1. In Soap 1.2, body may not have other elements if Fault is present.

The structure of a SOAP message is:

[SOAP message (XML document)
   [SOAP envelope
      [SOAP header?
            element*
      ]
      [SOAP body
           (element* | Fault)?
      ]
   ]
]

Package SOAP Interfaces

Table 9-1 summarizes the methods available through the SOAP package.

Table 9-1 Summary of SOAP Package Interfaces

FunctionSummary

XmlSoapAddBodyElement()

Adds an element to a SOAP message body.

XmlSoapAddFaultReason()

Adds additional Reason to Fault.

XmlSoapAddFaultSubDetail()

Adds additional child to Fault Detail.

XmlSoapAddHeaderElement()

Adds an element to a SOAP header.

XmlSoapCall()

Sends a SOAP message then waits for a reply.

XmlSoapCreateConnection()

Creates a SOAP connection object.

XmlSoapCreateCtx()

Creates and returns a SOAP context.

XmlSoapCreateMsg()

Creates and returns an empty SOAP message.

XmlSoapDestroyConnection()

Destroys a SOAP connection object.

XmlSoapDestroyCtx()

Destroys a SOAP context.

XmlSoapDestroyMsg()

Destroys a SOAP message created with XmlSoapCreateMsg.

XmlSoapError()

Gets a human readable error code.

XmlSoapGetBody()

Return a SOAP message's envelope body.

XmlSoapGetBodyElement()

Gets an element from a SOAP body.

XmlSoapGetEnvelope()

Returns a SOAP part's envelope.

XmlSoapGetFault()

Returns Fault code, reason, and details.

XmlSoapGetHeader()

Returns a SOAP message's envelope header.

XmlSoapGetHeaderElement()

Gets an element from a SOAP header.

XmlSoapGetMustUnderstand()

Gets mustUnderstand attribute from SOAP header element.

XmlSoapGetReasonLang()

Gets the language of a reason with the specified index.

XmlSoapGetReasonNum()

Determines the number of reasons in Fault element.

XmlSoapGetRelay()

Gets Relay attribute from SOAP header element.

XmlSoapGetRole()

Gets role from SOAP header element.

XmlSoapHasFault()

Determines if SOAP message contains Fault object.

XmlSoapSetFault()

Sets Fault in SOAP message.

XmlSoapSetMustUnderstand()

Sets mustUnderstand attribute for SOAP header element.

XmlSoapSetRelay()

Sets Relay attribute for a SOAP header element.

XmlSoapSetRole()

Sets role for SOAP header element.



XmlSoapAddBodyElement()

Adds an element to a SOAP message body. Sets the numeric error code.

Syntax

xmlelemnode *XmlSoapAddBodyElement(
   xmlsoapctx *ctx, 
   xmldocnode *msg,
   oratext *qname,
   oratext *uri, 
   xmlerr *xerr);
ParameterIn/OutDescription
ctx
IN
SOAP context
msg
IN/OUT
SOAP message
qname
IN
QName of element to add
uri
IN
Namespace URI of element to add
xerr
IN/OUT
Error code

Returns

(xmlelemnode *) created element


XmlSoapAddFaultReason()

Add additional Reason to Fault. The same reason text may be provided in different languages. When the fault is created, the primary language/reason is added at that time; use this function to add additional translations of the reason.

Syntax

xmlerr XmlSoapAddFaultReason(
   xmlsoapctx *ctx, 
   xmldocnode *msg,
   ratext *reason,
    oratext *lang);
ParameterIn/OutDescription
ctx
IN
SOAP context
msg
IN/OUT
SOAP message
reason
IN
Human-readable fault Reason
lang
IN
Language of reason

Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success


See Also:

XmlSoapSetFault()


XmlSoapAddFaultSubDetail()

Adds an additional child to Fault Detail. XmlSoapSetFault allows for creation of a Deatail element with only one child. Extra children could be added with this function.

Syntax

xmlerr XmlSoapAddFaultSubDetail(
   xmlsoapctx *ctx, 
   xmldocnode *msg,
   xmlelemnode *sub);
ParameterIn/OutDescription
ctx
IN
SOAP context
msg
IN/OUT
SOAP message
sub
IN
subdetail tree

Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success


XmlSoapAddHeaderElement()

Adds an element to a SOAP header.

Syntax

xmlelemnode *XmlSoapAddHeaderElement(
   xmlsoapctx *ctx, 
   xmldocnode *msg,
   oratext *qname,
   oratext *uri, 
   xmlerr *xerr);
ParameterIn/OutDescription
ctx
IN
SOAP context
msg
IN/OUT
SOAP message
qname
IN
QName of element to add
uri
IN
Namespace URI of element to add
xerr
IN/OUT
error code

Returns

(xmlelemnode *) created element


XmlSoapCall()

Send a SOAP message over a connection and wait for the response; the message reply (an XML document) is parsed and returned as a SOAP message (equivalent to a DOM).

The message buffer is first used to serialize the outgoing message; if it's too small (overflow occurs), xerr gets XMLERR_SAVE_OVERFLOW and NULL is returned. The same buffer is then re-used to receive the replied SOAP message.

Opening the connection object is expected to cause an active SOAP handler to appear on the end-point; how this happens is up to the user. For HTTP, the URL should invoke a cgi-bin, or detect the application/soap+xml content-type.

Syntax

xmldocnode *XmlSoapCall(
   xmlsoapctx *ctx, 
   xmlsoapcon *con,
   xmldocnode *msg, 
   xmlerr *xerr);
ParameterIn/OutDescription
ctx
IN
SOAP context
con
IN
SOAP connection object
msg
IN
SOAP message to send
xerr
IN
numeric code of failure

Returns

(xmldocnode *) returned message, or NULL on failure with xerr set


XmlSoapCreateConnection()

Create a SOAP connection object, specifying the binding (transport) and endpoint. The binding is an enum of type xmlsoapbind, and the endpoint depends on the binding.

Currently only HTTP binding is supported, and the endpoint is a URL. That URL should be active, i.e. a cgi-bin script or some mechanism to trigger SOAP message processing based on the Content-type of the incoming message ("application/soap+xml").

To control the HTTP access method (GET or POST), use the web-method property named XMLSOAP_PROP_WEB_METHOD which can have possible values XMLSOAP_WEB_METHOD_GET and XMLSOAP_WEB_METHOD_POST.

(conbuf, consiz) is the connection buffer used with LPU; for sending, it contains only the HTTP header, but on reception it holds the entire reply, including HTTP header and the full SOAP body. If no buffer is provided, one will be allocated for you. If size if zero, the default size (64K) will be used.

(msgbuf, msgsiz) is the message buffer used to form SOAP messages for sending. It needs to be large enough to contain the largest message which will be sent. If no buffer is specified, one will be allocated for you. If the size is zero, the default size (64K) will be used.

Two buffers are needed for sending since the SOAP message needs to be formed first in order to determine it's size; then, the HTTP header can be formed, since the Content-Length is now known.

Syntax

xmlsoapcon *XmlSoapCreateConnection(
   xmlsoapctx *ctx, 
   xmlerr *xerr,
   xmlsoapbind bind, 
   void *endp,
   oratext *conbuf, 
   ubig_ora consiz,
   oratext *msgbuf, 
   ubig_ora msgsiz, 
   ...);
ParameterIn/OutDescription
ctx
IN
SOAP context
xerr
OUT
numeric error code on failure
bind
IN
connection binding

endp
IN
connection endpoint
conbuf
IN/OUT
connection buffer (or NULL to have one allocated)
consiz
IN
size of connection buffer (or 0 for default size)
msgbuf
IN/OUT
message buffer (or NULL to have one allocated)
msgsiz
IN
size of message buffer (or 0 for default size)
...
IN
additional HTTP headers to set, followed by NULL

Returns

(xmlsoapcon *) connect object, or NULL on error with xerr set


XmlSoapCreateCtx()

Creates and returns a SOAP context. This context must be passed to all XmlSoap APIs. Note the name provided should be unique and is used to identify the context when debugging. Options are specified as (name, value) pairs, ending with a NULL, same as for XmlCreate. If no options are desired, the NULL is still needed. Options are: debug_level (enables SOAP debug output to stderr), numeric level (the higher the level, the more detailed extensive the output), 0 for no debug (this is the default setting).

Syntax

xmlsoapctx *XmlSoapCreateCtx(
   xmlctx *xctx, 
   xmlerr *xerr, 
   oratext *name, 
   ...);
ParameterIn/OutDescription
xctx
IN
XML context
xerr
OUT
error return code on failure
name
IN
name of context; used for debugging
...
IN
options, as (name, value) pairs, followed by NULL

Returns

(xmlsoapctx *) SOAP context, or NULL on failure (w/xerr set)


XmlSoapCreateMsg()

Creates and returns an empty SOAP message. The SOAP message will consist of an Envelope. The Envelope contains an empty Header and Body. A SOAP message is an XML document represented by a DOM, and is no different from any other XML document. All DOM operations are valid on the document, but be sure not to harm the overall structure. Changes should be restricted to creating and modifying elements inside the Header and Body.

Syntax

xmldocnode *XmlSoapCreateMsg(
   xmlsoapctx *ctx, 
   xmlerr *xerr);
ParameterIn/OutDescription
ctx
IN
SOAP context
xerr
OUT
error retrun code on failure

Returns

(xmldocnode *) SOAP message, or NULL on failure (w/xerr set)


XmlSoapDestroyConnection()

Destroys a SOAP connection object made with XmlSoapCreateConnection and frees all allocated resources.

Syntax

xmlerr XmlSoapDestroyConnection(
   xmlsoapctx *ctx, 
   xmlsoapcon *con);
ParameterIn/OutDescription
ctx
IN
SOAP context
con
IN
SOAP connection

Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success


XmlSoapDestroyCtx()

Destroys a SOAP context created with XmlSoapCreateCtx. All memory allocated will be freed, and all connections closed.

Syntax

xmlerr XmlSoapDestroyCtx(
   xmlsoapctx *ctx);
ParameterIn/OutDescription
ctx
IN
SOAP context

Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success


See Also:

XmlSoapCreateCtx()


XmlSoapDestroyMsg()

Destroys a SOAP message created with XmlSoapCreateMsg; this is the same as calling XmlFreeDocument.

Syntax

xmlerr XmlSoapDestroyMsg(
   xmlsoapctx *ctx,
   xmldocnode *msg);
ParameterIn/OutDescription
ctx
IN
SOAP connection
msg
IN
SOAP message

Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success


See Also:

XmlSoapCreateMsg()


XmlSoapError()

Retrives human readable representation of the error code. Optionally, retrieves the information about the error code of the underlying layer.

Syntax

oratext *XmlSoapError(
   xmlsoapctx *ctx, 
   xmlsoapcon *con,
   xmlerr err,
   uword *suberr,
   oratext **submsg);
ParameterIn/OutDescription
ctx
IN
SOAP context
con
IN
Connection about which additional info is requested
err
IN
Error code for which human readable information will be returned.
suberr
OUT
Error code from con
submsg
OUT
Human readable information about con error

Returns

(oratext *) error code


XmlSoapGetBody()

Returns a SOAP message's envelope body.

Syntax

xmlelemnode *XmlSoapGetBody(
   xmlsoapctx *ctx, 
   xmldocnode *msg,
   xmlerr *xerr);
ParameterIn/OutDescription
ctx
IN
SOAP context
msg
IN
SOAP message
xmlerr
IN/OUT
error code

Returns

(xmlelemnode *) SOAP Body


See Also:

XmlSoapGetHeader()


XmlSoapGetBodyElement()

Gets an element from a SOAP body.

Syntax

xmlelemnode *XmlSoapGetBodyElement(
   xmlsoapctx *ctx, 
   xmldocnode *msg,
   oratext *uri,
    oratext *local,
    xmlerr *xerr);
ParameterIn/OutDescription
ctx
IN
SOAP context
msg
IN
SOAP message
uri
IN
Namespace URI of element to get
local
IN
Local name of element to get
xerr
IN/OUT
error code

Returns

(xmlelemnode *) named element, or NULL on error


XmlSoapGetEnvelope()

Returns a SOAP part's envelope

Syntax

xmlelemnode *XmlSoapGetEnvelope(
   mlsoapctx *ctx, 
   xmldocnode *msg, 
   xmlerr *xerr);
ParameterIn/OutDescription
ctx
IN
SOAP context
msg
IN
SOAP message
xerr
IN/OUT
error code

Returns

(xmlelemnode *) SOAP envelope


XmlSoapGetFault()

Returns Fault code, reason, and details. Fetches the Fault information and returns through user variables. NULL may be supplied for any part which is not needed. For lang, if the pointed-to variable is NULL, it will be set to the default language (that of the first reason).

Syntax

xmlerr XmlSoapGetFault(
   xmlsoapctx *ctx, 
   xmldocnode *msg, 
   oratext **code,
   oratext **reason, 
   oratext **lang,
   oratext **node,
   oratext **role,
   xmlelemnode **detail);
ParameterIn/OutDescription
ctx
IN
SOAP context
msg
IN/OUT
SOAP message
code
OUT
Code (1.2), faultcode (1.1)
reason
OUT
Human-readable fault Reason (1.2), faultreason (1.1)
lang
IN
Desired language for reason (1.2), not used ( NULL in 1.1)
node
OUT
Fault node
role
OUT
Role: next, none, or ulitmate receiver. Not used in 1.1
detail
OUT
User-defined details

Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success




See Also:

XmlSoapSetFault()


XmlSoapGetHeader()

Returns a SOAP message's envelope header.

Syntax

xmlelemnode *XmlSoapGetHeader(
   xmlsoapctx *ctx, 
  xmldocnode *msg, 
   xmlerr *xerr);
ParameterIn/OutDescription
ctx
IN
SOAP context
msg
IN
SOAP message
xerr
IN/OUT
error code

Returns

(xmlelemnode *) SOAP header


See Also:

XmlSoapGetBody()


XmlSoapGetHeaderElement()

Gets an element from a SOAP header. Sets a numeric error code.

Syntax

xmlelemnode *XmlSoapGetHeaderElement(
   xmlsoapctx *ctx,
   xmldocnode *msg,
   oratext *uri,
   oratext *local,
   xmlerr *xerr);
ParameterIn/OutDescription
ctx
IN
SOAP context
msg
IN
SOAP message
uri
IN
Namespace URI of element to get
local
IN
Local name of element to get
xerr
IN/OUT
Error code

Returns

(xmlelemnode *) named element, or NULL on error


XmlSoapGetMustUnderstand()

Gets mustUnderstand attribute from SOAP header element. The absence of this attribute is not an error and treated as value FALSE. To indicate the absence of an attribute, the error code XMLERR_SOAP_NO_MUST_UNDERSTAND is returned in this case, XMLERR_OK (0) is returned if the attribute is present. Other appropriate error codes might be returned. User supplied mustUnderstand value is set accordingly.

Syntax

xmlerr XmlSoapGetMustUnderstand(
   xmlsoapctx *ctx, 
   xmlelemnode *elem,
   boolean *mustUnderstand);
ParameterIn/OutDescription
ctx
IN
SOAP context
elem
IN
SOAP header element
mustUnderstand
OUT
mustUnderstand value, TRUE|FALSE

Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success


XmlSoapGetReasonLang()

Gets the language of a reason with a particular index.

Syntax

xmlerr XmlSoapGetReasonLang(
   xmlsoapctx *ctx, 
   xmldocnode *msg,
   ub4 index, 
   oratext **lang);
ParameterIn/OutDescription
ctx
IN
SOAP context
msg
IN
SOAP message
indx
IN
Index of fault reason
lang
IN
Reason language

Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success


XmlSoapGetReasonNum()

Determines the number of reasons in Fault element. Returns 0 if Fault is not present.

Syntax

ub4 XmlSoapGetReasonNum(
   xmlsoapctx *ctx, 
   xmldocnode *msg);
ParameterIn/OutDescription
ctx
IN
SOAP context
msg
IN
SOAP message

Returns

(ub4 *) #num reasons


XmlSoapGetRelay()

Gets Relay attribute from SOAP header element.

Syntax

xmlerr XmlSoapGetRelay(
   xmlsoapctx *ctx, 
   xmlelemnode *elem,
   boolean *Relay);
ParameterIn/OutDescription
ctx
IN
SOAP context
elem
IN
SOAP header element
Relay
OUT
Relay value

Returns

xmlerr numeric error code, XMLERR_OK on success


XmlSoapGetRole()

Gets role from SOAP header element. If the element has no role, XMLERR_SOAP_NO_ROLE is returned, otherwise XMLERR_OK (0) is returned and the user's role is set accordingly. if the element has no role, then according to the standard, the user's role is set to XMLSOAP_ROLE_ULT.

Syntax

xmlerr XmlSoapGetRole(
   xmlsoapctx *ctx, 
   xmlelemnode *elem, 
   xmlsoaprole *role);
ParameterIn/OutDescription
ctx
IN
SOAP context
elem
IN
SOAP header element
role
OUT
Role value

Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success


XmlSoapHasFault()

Determines if SOAP message contains Fault object.

Syntax

boolean XmlSoapHasFault(
   xmlsoapctx *ctx, 
   xmldocnode *msg, 
   xmlerr *xerr);
ParameterIn/OutDescription
ctx
IN
SOAP context
msg
IN
SOAP message
xerr
IN/OUT
Error code

Returns

(boolean) TRUE if there's a Fault, FALSE if not


See Also:

XmlSoapGetFault()


XmlSoapSetFault()

Sets Fault in SOAP message.

Syntax

xmlerr XmlSoapSetFault(
   xmlsoapctx *ctx, 
   xmldocnode *msg,
   oratext *node, 
   oratext *code, 
   oratext *reason, 
   oratext *lang, 
   oratext *role, 
   xmlelemnode *detail);
ParameterIn/OutDescription
ctx
IN
SOAP context
msg
IN/OUT
SOAP message
node
IN
URI of SOAP node which faulted, Node (1.2), faultactor(1.1)
code
IN
Code (1.2), faultcode (1.1)
reason
IN
Human-readable fault Reason (1.2), faultreason (1.1)
lang
IN
Language of reason (1.2), unused (1.1)
role
IN
URI representing role, Role (1.2), unused (1.1)
detail
IN
detail elements (user-defined)

Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success


XmlSoapSetMustUnderstand()

Sets mustUnderstand attribute for SOAP header element. According to the standard, if the value is FALSE, the attribute is not set.

Syntax

xmlerr XmlSoapSetMustUnderstand(
   xmlsoapctx *ctx, 
   xmlelemnode *elem,
   boolean mustUnderstand);
ParameterIn/OutDescription
ctx
IN
SOAP context
elem
IN/OUT
SOAP header element
mustUnderstand
IN
mustUnderstand value, TRUE|FALSE

Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success


See Also:

XmlSoapSetRole()


XmlSoapSetRelay()

Sets Relay attribute for a SOAP header element. If tkhe value is FALSE, the attribute is not set.

Syntax

xmlerr XmlSoapSetRelay(
   xmlsoapctx *ctx,
   xmlelemnode *elem,   boolean Relay);
ParameterIn/OutDescription
ctx
IN
SOAP context
elem
IN/OUT
SOAP header element
Relay
IN
Relay; TRUE|FALSE

Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success


See Also:

XmlSoapGetRelay()


XmlSoapSetRole()

Sets role for SOAP header element. If the role specified is XMLSOAP_ROLE_ULT, then according to the standard the attribute is not set.

Syntax

xmlerr XmlSoapSetRole(
   xmlsoapctx *ctx, 
   xmlelemnode *elem, 
   xmlsoaprole role);
ParameterIn/OutDescription
ctx
IN
SOAP context
elem
IN/OUT
SOAP header element
role
IN
Role value

Returns

xmlerr numeric error code, XMLERR_OK on success

PK*)kPKnFJOEBPS/xmldiff.htme| Package XmlDiff APIs for C

12 Package XmlDiff APIs for C

The methods of the package XmlDiff allow you to compare and modify XML documents. The XmlDiff() and XmlPatch() methods are generally equivalent to UNIX commands diff and patch, and in addition are optimized for, and aware of XML.

This chapter contains this section:


XmlDiff Interface

Table 12-1 summarizes the methods available through the XmlDiff interface.

Table 12-1 Summary of XmlDiff Methods

FunctionSummary

XmlDiff()


Determines the changes between two XML documents.

XmlHash()


Computes a hash value for an XML document or a node in DOM.

XmlPatch()


Applies changes on input XML document.



XmlDiff()

Determines the changes between two XML documents.

XmlDiff() captures the diff between two documents in an XML format that conforms to the Xdiff XML schema; you can customize this output.

These input documents can be specified either as DOM Trees, files, URI, orastream, and so on. DOM trees for both the inputs will be created if they are not supplied as DOM trees. The DOM for the diff document is created, and the doc node is returned.

If the caller supplies inputs as DOMs, the memory for the DOMs will not be freed.

Data (DOM) encoding of both documents must be the same as the data encoding in xctx. The diff DOM will be created in the data encoding specified in xctx.

There are four algorithms that can be run in XmlDiff(): global, local, global with hashing, and local with hashing. The diff may be different in the four cases.

The global algorithm will generate minimal diff using insert, append, delete and update operations. It needs more memory and time than the local algorithm. The local algorithm may not generate minimal diff, but is faster and uses less space than the global algorithm.

Hashing can be used with both global and local algorithms. If hashing is used with the global algorithm, it will speed up diff computation significantly, but may reduce the quality of diff. With local algorithm, it improves the quality of the diff.

You must specify a depth at which to use hashing. In hashing, the hash value for every element node is associated with a digest for the entire subtree rooted at that node. The tree is not investigated beyond the specified hash level depth while computing the diff.

The output of the global algorithm with or without hashing meets 'operations-in-docorder' requirement (the nodes must appear in same order as a preorder traversal of the document tree), but the output of the local algorithm does not.

The namespace prefixes XmlDiff() will use in the xdiff document may be same as those in either the first or second doc, depending on which prefix was seen first while processing. The NS URI will be bound to the prefix in the output appropriately. If this NS does not have a prefix in both docs, a new prefix will be generated and bound to the NS in xdiff doc.

You can read more about XmlDiff() method in the Oracle XML Developer's Kit Programmer's Guide. Section "XmlDiff Command Line" of the same guide should provide additional resources.

Syntax

xmldocnode *XmlDiff(
   xmlctx *xctx,
   xmlerr *err,
   ub4  flags,
   xmldfsrct firstSourceType,
   void *firstSource,
   void *firstSourceExtra,
   xmldfsrct secondSourceType,
   void *secondSource,
   void *secondSourceExtra,
   uword hashLevel,
   oraprop *properties);
ParameterIn/OutDescription
xctx
IN
XML context
xmlerr
OUT
numeric error code, XMLERR_OK on success
flags
IN
The following options are available:
  • XMLDF_FL_DEFAULTS(=0) chooses defaults

  • XMLDF_FL_ALGORITHM_GLOBAL is the global algorithm

  • XMLDF_FL_ALGORITHM_LOCAL is the local algorithm

  • XMLDF_FL_DISABLE_UPDATE indicates a disable update operation, with the global algorithm

By default, global algorithm is used.

firstSourceType
IN
Type of source for first document; if zero, firstSource is assumed to be a DOM doc node.
firstSource
IN
Pointer to the source for the first document
firstSourceExtra
IN
An additional pointer to the source for the first document; used for buffer length pointer
secondSourceType
IN
Type of source for second document; if zero, secondSource is assumed to be a DOM doc node.
secondSource
IN
Pointer to the source for the second document
secondSourceExtra
IN
An additional pointer to the source for the second document; used for buffer length pointer
hashLevel
IN
The depth (counting from 1 for the root) at which to use hashing for sub trees; <=1 means not to use hashing
properties
IN
Used for Output Builder

Returns

(xmldocnode) Doc node for the diff document, or NULL on error


XmlHash()

Computes a hash value for an XML document or a node in DOM.

If the hash values for two XML subtrees are equal, the corresponding subtrees are equal to a very high probability. Computes the hash value using the Message Digest algorithm 5 (MD5), a widely-used cryptographic hash function with a 128-bit hash value, so there is a very small probability that two different inputs might map to same MD5 digest.

The source can be specified as a file, a URL, and so on. It can also be a Document node in DOM, or any other DOM node, and must be specified using the inputSource parameter. If inputSource is a non-Document DOM node, inputSourceExtra must point to the Document node for the DOM.

You can read more about XmlHash() method in the Oracle XML Developer's Kit Programmer's Guide.

Syntax

xmlerr XmlHash(
   xmlctx *xctx,
   xmlhasht *digest,
   ub4 flags,
   xmldfsrct iputSourceType,
   void *inputSource,
   void *inputSourceExtra,
   oraprop *properties);
ParameterIn/OutDescription
xctx
IN
XML context
digest
OUT
The hash value for the XML sub-tree
flags
IN
Not used
inputSourceType
IN
Type of source for the input document; if zero, inputSource is assumed to be a DOM doc node
inputSource
IN
Pointer to the source for the input document
inputSourceExtra
IN
An additional pointer to the source for the input document; if used for a node pointer in a DOM, inputSource must be a document node.
properties
IN
Not used

Returns

(xmlerr) numeric error code, XMLERR_OK on success


XmlPatch()

XmlPatch() applies Xdiff schema-conforming changes to an input document. The input document and the diff document can be specified either as a DOM tree, file, URI, or buffer.

DOMs are built for both the input and diff document if they are not supplied as DOMs.

Data(DOM) encoding of both input and diff documents must be the same as the data encoding in xctx. The patched DOM will be in the data encoding specified in xctx.

Only the simple XPath is supported in the snapshot model. The XPath should identify a node with a posistion predicate in abbreviated syntax, such as /a[1]/b[2]. The XPaths generated by XmlDiff() meet this requirement. Also, 'operations-in-docorder' condition must be TRUE; the nodes must appear in same order as a preorder traversal of the document tree. Global (with or without hashing) meets this requirement. Local does not.

The programming interface should specify the output model used in the diff doc. The oracle-xmldif should be the first child of the top level xdiff element. It should also use flags to specify if operations are in document order (TRUE or FALSE), and wether the output model is a snapshot or current.

You can read more about XmlPatch() method in the Oracle XML Developer's Kit Programmer's Guide. Section "XmlPatch Command Line" of the same guide should provide additional resources.

Syntax

xmldocnode *XmlPatch(
   xmlctx *xctx,
   xmlerr *err,
   ub4  flags,
   xmldfsrct inputSourceType,
   void *inputSource,
   void *inputSourceExtra,
   xmldfsrct diffSourceType,
   void *diffSource,
   void *diffSourceExtra,
   oraprop *properties);
ParameterIn/OutDescription
xctx
IN
XML context
xmlerr
OUT
numeric error code, XMLERR_OK on success
flags
IN
The following option is available:
  • XMLDF_FL_DEFAULTS(=0) chooses defaults

inputSourceType
IN
Type of source for the input document; if zero, inputSource is assumed to be a DOM doc node.
inputSource
IN
Pointer to the source for the input document
inputSourceExtra
IN
An additional pointer to the source for the input document; used for buffer length pointer
diffSourceType
IN
Type of source for diff document; if zero, secondSource is assumed to be a DOM doc node.
diffsSource
IN
Pointer to the source for the diff document
diffSourceExtra
IN
An additional pointer to the source for the diff document; used for buffer length pointer
properties
IN
Not used

Returns

(xmldocnode) Doc node for the pathed DOM, or NULL on error

PK[S4eePKnFJ OEBPS/sax.htm Package SAX APIs for C

7 Package SAX APIs for C

SAX is a standard interface for event-based XML parsing, developed collaboratively by the members of the XML-DEV mailing list. To use SAX, an xmlsaxcb structure is initialized with function pointers and passed to one of the XmlLoadSax calls. A pointer to a user-defined context structure is also provided, and will be passed to each SAX function.

For event-based schemava validation APIs, refer to Chapter 4, "Package Event APIs for C".

This chapter contains the following section:


SAX Interface

Table 7-1 summarizes the methods available through the SAX interface.

Table 7-1 Summary of SAX Methods

FunctionSummary

XmlSaxAttributeDecl()


Receives SAX notification of an attribute's declaration.

XmlSaxCDATA()


Receives SAX notification of CDATA. Oracle extension.

XmlSaxCharacters()


Receives SAX notification of character data

XmlSaxComment()


Receives SAX notification of a comment.

XmlSaxElementDecl()


Receives SAX notification of an element's declaration. Oracle extension.

XmlSaxEndDocument()


Receives SAX end-of-document notification.

XmlSaxEndElement()


Receives SAX end-of-element notification.

XmlSaxNotationDecl()


Receives SAX notification of a notation declaration.

XmlSaxPI()


Receives SAX notification of a processing instruction.

XmlSaxParsedEntityDecl()


Receives SAX notification of a parsed entity declaration. Oracle extension.

XmlSaxStartDocument()


Receives SAX start-of-document notification.

XmlSaxStartElement()


Receives SAX start-of-element notification.

XmlSaxStartElementNS()


Receives SAX namespace-aware start-of-element notification.

XmlSaxUnparsedEntityDecl()


Receives SAX notification of an unparsed entity declaration.

XmlSaxWhitespace()


Receives SAX notification of ignorable (whitespace) data.

XmlSaxXmlDecl()


Receives SAX notification of an XML declaration. Oracle extension.



XmlSaxAttributeDecl()

This event marks an element declaration in the DTD. The element's name and content will be in the data encoding. Note that an attribute may be declared before the element it belongs to!

Syntax

xmlerr XmlSaxAttributeDecl(
   void *ctx, 
   oratext *elem, 
   oratext *attr, 
   oratext *body);
ParameterIn/OutDescription
ctx
IN
user's SAX context
elem
IN
element for which the attribute is declared; data encoding
attr
IN
attribute's name; data encoding
body
IN
body of an attribute declaration

Returns

(xmlerr) error code, XMLERR_OK [0] for success


XmlSaxCDATA()

This event handles CDATA, as distinct from Text. If no XmlSaxCDATA callback is provided, the Text callback will be invoked. The data will be in the data encoding, and the returned length is in characters, not bytes. See also XmlSaxWhitespace, which receiving notification about ignorable (whitespace formatting) character data.

Syntax

xmlerr XmlSaxCDATA(
   void *ctx, 
   oratext *ch, 
   size_t len);
ParameterIn/OutDescription
ctx
IN
user's SAX context
ch
IN
pointer to CDATA; data encoding
len
IN
length of CDATA, in characters

Returns

(xmlerr) error code, XMLERR_OK [0] for success


See Also:

XmlSaxWhitespace()


XmlSaxCharacters()

This event marks character data, either Text or CDATA. If an XmlSaxCDATA callback is provided, then CDATA will be send to that instead; with no XmlSaxCDATA callback, both Text and CDATA go to the XmlSaxCharacters callback. The data will be in the data encoding, and the returned length is in characters, not bytes. See also XmlSaxWhitespace, which receiving notification about ignorable (whitespace formatting) character data.

Syntax

xmlerr XmlSaxCharacters(
   void *ctx, 
   oratext *ch, 
   size_t len);
ParameterIn/OutDescription
ctx
IN
user's SAX context
ch
IN
pointer to data; data encoding
len
IN
length of data, in characters

Returns

(xmlerr) error code, XMLERR_OK [0] for success


See Also:

XmlSaxWhitespace()


XmlSaxComment()

This event marks a comment in the XML document. The comment's data will be in the data encoding. Oracle extension, not in SAX standard.

Syntax

xmlerr XmlSaxComment(
   void *ctx, 
   oratext *data);
ParameterIn/OutDescription
ctx
IN
user's SAX context
data
IN
comment's data; data encoding

Returns

(xmlerr) error code, XMLERR_OK [0] for success


XmlSaxElementDecl()

This event marks an element declaration in the DTD. The element's name and content will be in the data encoding.

Syntax

xmlerr XmlSaxElementDecl(
   void *ctx, 
   oratext *name, 
   oratext *content);
ParameterIn/OutDescription
ctx
IN
user's SAX context
name
IN
element's name
content
IN
element's context model

Returns

(xmlerr) error code, XMLERR_OK [0] for success


XmlSaxEndDocument()

The last SAX event, called once for each document, indicating the end of the document. Matching event is XmlSaxStartDocument.

Syntax

xmlerr XmlSaxEndDocument(
   void *ctx);
ParameterIn/OutDescription
ctx
IN
user's SAX context

Returns

(xmlerr) error code, XMLERR_OK [0] for success


XmlSaxEndElement()

This event marks the close of an element; it matches the XmlSaxStartElement or XmlSaxStartElementNS events. The name is the tagName of the element (which may be a qualified name for namespace-aware elements) and is in the data encoding.

Syntax

xmlerr XmlSaxEndElement(
   void *ctx, 
   oratext *name);
ParameterIn/OutDescription
ctx
IN
user's SAX context
name
IN
name of ending element; data encoding

Returns

(xmlerr) error code, XMLERR_OK [0] for success


See Also:

XmlSaxEndElement()


XmlSaxNotationDecl()

The even marks the declaration of a notation in the DTD. The notation's name, public ID, and system ID will all be in the data encoding. Both IDs are optional and may be NULL.

Syntax

xmlerr XmlSaxNotationDecl(
   void *ctx, 
   oratext *name, 
   oratext *pubId, 
   oratext *sysId);
ParameterIn/OutDescription
ctx
IN
user's SAX context
name
IN
notation's name; data encoding
pubId
IN
notation's public ID as data encoding, or NULL
sysId
IN
notation's system ID as data encoding, or NULL

Returns

(xmlerr) error code, XMLERR_OK [0] for success


XmlSaxPI()

This event marks a ProcessingInstruction. The ProcessingInstructions target and data will be in the data encoding. There is always a target, but the data may be NULL.

Syntax

xmlerr XmlSaxPI(
   void *ctx, 
   oratext *target, 
   oratext *data);
ParameterIn/OutDescription
ctx
IN
user's SAX context
target
IN
PI's target; data encoding
data
IN
PI's data as data encoding, or NULL

Returns

(xmlerr) error code, XMLERR_OK [0] for success


XmlSaxParsedEntityDecl()

Marks an parsed entity declaration in the DTD. The parsed entity's name, public ID, system ID, and notation name will all be in the data encoding.

Syntax

xmlerr XmlSaxParsedEntityDecl(
   void *ctx, 
   oratext *name, 
   oratext *value, 
   oratext *pubId, 
   oratext *sysId, 
   boolean general);
ParameterIn/OutDescription
ctx
IN
user's SAX context
name
IN
entity's name; data encoding
value
IN
entity's value; data encoding
pubId
IN
entity's public ID as data encoding, or NULL
sysId
IN
entity's system ID; data encoding
general
IN
TRUE if general entity, FALSE if parameter entity

Returns

(xmlerr) error code, XMLERR_OK [0] for success


XmlSaxStartDocument()

The first SAX event, called once for each document, indicating the start of the document. Matching event is XmlSaxEndDocument.

Syntax

xmlerr XmlSaxStartDocument(
   void *ctx);
ParameterIn/OutDescription
ctx
IN
user's SAX context

Returns

(xmlerr) error code, XMLERR_OK [0] for success


XmlSaxStartElement()

This event marks the start of an element. Note this is the original SAX 1 non-namespace-aware version; XmlSaxStartElementNS is the SAX 2 namespace-aware version. If both are registered, only the NS version will be called. The element's name will be in the data encoding, as are all the attribute parts. See the functions in the NamedNodeMap interface for operating on the attributes map. The matching function is XmlSaxEndElement (there is no namespace aware version of this function).

Syntax

xmlerr XmlSaxStartElement(
   void *ctx, 
   oratext *name, 
   xmlnodelist *attrs);
ParameterIn/OutDescription
ctx
IN
user's SAX context
name
IN
element's name; data encoding
attrs
IN
NamedNodeMap of element's attributes

Returns

(xmlerr) error code, XMLERR_OK [0] for success


XmlSaxStartElementNS()

This event marks the start of an element. Note this is the new SAX 2 namespace-aware version; XmlSaxStartElement is the SAX 1 non-namespace-aware version. If both are registered, only the NS version will be called. The element's qualified name, local name, and namespace URI will be in the data encoding, as are all the attribute parts. See the functions in the NamedNodeMap interface for operating on the attributes map. The matching function is XmlSaxEndElement (there is no namespace aware version of this function).

Syntax

xmlerr XmlSaxStartElementNS(
   void *ctx, 
   oratext *qname, 
   oratext *local, 
   oratext *nsp, 
   xmlnodelist *attrs);
ParameterIn/OutDescription
ctx
IN
user's SAX context
qname
IN
element's qualified name; data encoding
local
IN
element's namespace local name; data encoding
nsp
IN
element's namespace URI; data encoding
attrs
IN
NodeList of element's attributes, or NULL

Returns

(xmlerr) error code, XMLERR_OK [0] for success


XmlSaxUnparsedEntityDecl()

Marks an unparsed entity declaration in the DTD, see XmlSaxParsedEntityDecl for the parsed entity version. The unparsed entity's name, public ID, system ID, and notation name will all be in the data encoding.

Syntax

xmlerr XmlSaxUnparsedEntityDecl(
   void *ctx, 
   oratext *name, 
   oratext *pubId, 
   oratext *sysId, 
   oratext *note);
ParameterIn/OutDescription
ctx
IN
user's SAX context
name
IN
entity's name; data encoding
pubId
IN
entity's public ID as data encoding, or NULL
sysId
IN
entity's system ID; data encoding
note
IN
entity's notation name; data encoding

Returns

(xmlerr) error code, XMLERR_OK [0] for success


XmlSaxWhitespace()

This event marks ignorable whitespace data such as newlines, and indentation between lines. The matching function is XmlSaxCharacters, which receives notification of normal character data. The data is in the data encoding, and the returned length is in characters, not bytes.

Syntax

xmlerr XmlSaxWhitespace(
   void *ctx, 
   oratext *ch, 
   size_t len);
ParameterIn/OutDescription
ctx
IN
user's SAX context
ch
IN
pointer to data; data encoding
len
IN
length of data, in characters

Returns

(xmlerr) error code, XMLERR_OK [0] for success


See Also:

XmlSaxCharacters()


XmlSaxXmlDecl()

This event marks an XML declaration. The XmlSaxStartDocument event is always first; if this callback is registered and an XMLDecl exists, it will be the second event. The encoding flag says whether an encoding was specified. Since the document's own encoding specification may be overridden (or wrong), and the input will be converted to the data encoding anyway, the actual encoding specified in the document is not provided. For the standalone flag, -1 will be returned if it was not specified, otherwise 0 for FALSE, 1 for TRUE.

Syntax

xmlerr XmlSaxXmlDecl(
   void *ctx, 
   oratext *version, 
   boolean encoding, 
   sword standalone);
ParameterIn/OutDescription
ctx
IN
user's SAX context
version
IN
version string from XMLDecl; data encoding
encoding
IN
whether encoding was specified
standalone
IN
value of the standalone document; < 0 if not specified

Returns

(xmlerr) error code, XMLERR_OK [0] for success

PK[`PKnFJ OEBPS/toc.htm Table of Contents

Contents

List of Examples

List of Tables

Preface

What's New in the XML C APIs?

1 Datatypes for C

2 Package Callback APIs for C

3 Package DOM APIs for C

4 Package Event APIs for C

5 Package Orastream APIs for C

6 Package Range APIs for C

7 Package SAX APIs for C

8 Package Schema APIs for C

9 Package SOAP APIs for C

10 Package Traversal APIs for C

11 Package XML APIs for C

12 Package XmlDiff APIs for C

13 Package XPath APIs for C

14 Package XPointer APIs for C

15 Package XSLT APIs for C

16 Package XSLTVM APIs for C

A Mapping of APIs used before Oracle Database 10g Release 1

Index

PKBN<2PKnFJOEBPS/datatypes.htm Datatypes for C

1 Datatypes for C

This package defines macros which declare functions (or function pointers) for XML callbacks. Callbacks are used for error-message handling, memory allocation and freeing, and stream operations.

This chapter contains this section:


C Datatypes

Table 1-1 lists all C datatypes and their descriptions.

Table 1-1 Summary of C Datatypes

DatatypePurpose

oracheck


Checkword for validating data structures.

oraerr


Error code: 0 is success, non-0 is failure.

oraprop_id


The id of property; if >= 0 it is valid, if < 0, it is invalid.

oramemctx


Opaque memory context.

oraprop


Property name.

oraprop_t


Property value type.

oraprop_v


Value: union of storage for all data types.

orastream


Opaque stream object.

orastreamhdl


Storage for file handles.

xmlcmphow


Constant used for DOM Range comparisons.

xmlctx


Context shared for all documents in an XML session.

xmldfsrct


Specifies input types for XmlDiff operations

xmlerr


Numeric error code returned by many functions.

xmlevctx


XML Event context.

xmlhasht


The hash value of an XML tree or sub-tree; also known as a digest.

xmlistream


Generic user-defined input stream.

xmliter


Control structure for DOM2 NodeIterator and TreeWalker.

xmlnodetype


The numeric type code of a node.

xmlostream


Generic user-defined output stream.

xmlpoint


XPointer point location.

xmlrange


Controls structure for DOM2 Range.

xmlsoapbind


Binding for SOAP connections.

xmlsoapcon


SOAP connection object.

xmlsoapctx


Context for SOAP operations.

xmlsoaprole


Role for a SOAP node.

xmlshowbits


Bit flags used to select which node types to show.

xmlurlacc


This is an enumeration of the known access methods for retrieving data from a URL.

xmlurlhdl


This union contains the handle(s) needed to access URL data, be it a stream or stdio pointer, file descriptor(s), and so on.

xmlurlpart


This structure contains the sub-parts of a URL.

xmlxptrloc


XPointer location datatype.

xmlxptrlocset


XPointer location set datatype.

xmlxslobjtype


Type of XSLT object that may be returned.

xmlxslomethod


Type of output produced by the XSLT processor.

xmlxvm


An object of type xmlxvm is used for XML document transformation.

xmlxvmcomp


An object of type xmlxvmcomp is used for compiling XSL stylesheets.

xmlxvmflags


Control flags for the XSLT compiler.

xmlxvmobjtype


Type of XSLTVM object.

xpctx


XPath top-level context.

xpexpr


XPath expression.

xpobj


XPath object.

xsdctx


XMLSchema validator context.

xslctx


XSL top-level context.

xvmobj


XSLVM processor run-time object; contents are private and must not be accessed by users.



oracheck

Checkword for validating data structures.

Definition

typedef ub4 oracheck;

oraerr

Error code: 0 is success, non-0 is failure.

Definition

typedef ub4 oraerr;

oraprop_id

The id of property; if >= 0 it is valid, if < 0, it is invalid.

Definition

typedef sb2 oraprop_id;

oramemctx

Opaque memory context.

Definition

typedef struct oramemctx oramemctx;

oraprop

Property name.

Definition

typedef struct oraprop {
    oratext    *name_oraprop;
    oraprop_id  id_oraprop;
    oraprop_t   type_oraprop;
    oraprop_v   value_oraprop;
} oraprop;

oraprop_t

Property value type.

Definition

typedef enum {
    ORAPROP_TYPE_BOOLEAN,
    ORAPROP_TYPE_SIGNED,
    ORAPROP_TYPE_UNSIGNED,        
    ORAPROP_TYPE_POINTER
} oraprop_t;

oraprop_v

Value: union of storage for all data types.

Definition

typedef union oraprop_v {
    boolean b_oraprop_v;
    sb4     s_oraprop_v;
    ub4     u_oraprop_v;
    void   *p_oraprop_v;
} oraprop_v;

orastream

Opaque stream object.

Definition

typedef struct orastream orastream;

orastreamhdl

Storage for file handles.

Definition

typedef union orastreamhdl {
    void  *ptr_orastreamhdl;      /* generic pointer stream/file/etc */
    struct {
        sb4 fd_orastreamhdl;     /* file descriptor(s) [FTP needs all 3!] */
        sb4 fd2_orastreamhdl;
        sb4 fd3_orastreamhdl;
    } fds_lpihdl;
} orastreamhdl;

xmlcmphow

Constant used for DOM Range comparisons.

Definition

typedef enum {
    XMLDOM_START_TO_START ,
    XMLDOM_START_TO_END   ,
    XMLDOM_END_TO_END     ,
    XMLDOM_END_TO_START   
} xmlcmphow;

xmlctx

Context shared for all documents in an XML session. Contains encoding information, low-level memory allocation function pointers, error message language or encoding and optional handler function, and so on. Required to load (parse) documents and create DOM, generate SAX, and so on.

Definition

struct xmlctx;
typedef struct xmlctx xmlctx;

xmldfoptype

Operation type, represents one or more operations. Used for passing the diff to a custom Operation Buildder (OB) in XmlDiff().

Definition

typedef enum {
  XMLDF_OP_NONE, /* Should not be set to non-zero for XMLDF_NUM_OP macro below */
  XMLDF_OP_UPDATE,
  XMLDF_OP_RENAME,
  XMLDF_OP_DELETE,
  XMLDF_OP_INSERT_BEFORE,
  XMLDF_OP_APPEND
} xmldfoptype;

xmldfsrct

Specifies input types for XmlDiff operations.

Definition

typedef enum {
   XMLDF_SRCT_NONE ,    /* default is DOM */
   XMLDF_SRCT_DOM,      /* DOM: doc node must be specified */
   XMLDF_SRCT_FILE,     /* file name must be specified */
   XMLDF_SRCT_URL,      /* URL in compiler encoding */
   XMLDF_SRCT_BUFFER,   /* buffer: buffer pointer and length must be specified */
   XMLDF_SRCT_FILEP,    /* FILE */
   XMLDF_SRCT_OSTREAM,  /* orastream: stream pointer must be specified */
   XMLDF_SRCT_DOMNODE   /* DOM node, used with XmlHash() */
} xmldfsrct;

xmlerr

Numeric error code returned by many functions. A zero value indicates success; a nonzero value indicates error.

Definition

typedef enum {
   XMLERR_OK              , /* success return */
   XMLERR_NULL_PTR        , /* NULL pointer */
   XMLERR_NO_MEMORY       , /* out of memory */
   XMLERR_HASH_DUP        , /* duplicate entry in hash table */
   XMLERR_INTERNAL        ,  /* internal error */
   XMLERR_BUFFER_OVERFLOW ,  /* name/quoted string too long */
   XMLERR_BAD_CHILD       ,  /* invalid child for parent */
   XMLERR_EOI             ,  /* unexpected EndOfInformation */
   XMLERR_BAD_MEMCB       ,  /* invalid memory callbacks */
   XMLERR_UNICODE_ALIGN   , /* Unicode data misalignment */
   XMLERR_NODE_TYPE       , /* wrong node type */
   XMLERR_UNCLEAN         , /* context is not clean */
   XMLERR_NESTED_STRINGS  , /* internal: nested open str */
   XMLERR_PROP_NOT_FOUND  , /* property not found */
   XMLERR_SAVE_OVERFLOW   , /* save output overflowed */
   XMLERR_NOT_IMP         , /* feature not implemented */
   XMLERR_NLS_MISMATCH    , /* specify lxglo/lxd or neither*/
   XMLERR_NLS_INIT        , /* error at NLS initialization */
   XMLERR_LEH_INIT        , /* error at LEH initialization */
   XMLERR_LML_INIT        , /* error at LML initialization */
   XMLERR_LPU_INIT          /* error at LPU initialization */
} xmlerr;

xmlevctx

XML Event context.

Definition

typedef  struct {
   void *ctx_xmlevctx;       /* implementation specific context */
   xmlevdisp disp_xmlevctx;  /* dispatch table */         
   ub4 checkword_xmlevctx;   /* checkword for integrity check */
   ub4 flags_xmlevctx;       /* mode; default: expand_entity */
   struct xmlevctx;          /* input xmlevctx; chains the XML Event context */   
} xmlevctx;

xmlevtype

The event type for parser pull events.

Definition

typedef enum  xmlevtype {
   XML_EVENT_FATAL_ERROR,            /* Fatal Error */
   XML_EVENT_BEFORE_START,           /* Before Start Document */
   XML_EVENT_START_DOCUMENT,         /* Indicates Start Document */
   XML_EVENT_START_DTD,              /* Start DTD */
   XML_EVENT_END_DTD,                /* End DTD */
   XML_EVENT_NOTATION_DECLARATION,   /* Notation Decl */
   XML_EVENT_PE_DECLARATION,         /* PE Decl */
   XML_EVENT_UE_DECLARATION,         /* US Decl */
   XML_EVENT_ELEMENT_DECLARATION,    /* Element Decl */ 
   XML_EVENT_ATTLIST_DECLARATION,    /* Attribute Decl */
   XML_EVENT_START_ELEMENT,          /* Start Element */
   XML_EVENT_END_ELEMENT,            /* End Element */
   XML_EVENT_CHARACTERS,             /* Characters (text) */
   XML_EVENT_CHARACTERS_CONT,        /* Characters Continued */
   XML_EVENT_PI,                     /* Processing Instruction */
   XML_EVENT_PI_CONT,                /* Processing Instruction Continued */
   XML_EVENT_COMMENT,                /* Comment */
   XML_EVENT_COMMENT_CONT,           /* Comment Continued */
   XML_EVENT_SPACE,                  /* White Space */
   XML_EVENT_SPACE_CONT,             /* White Space Continued */
   XML_EVENT_ENTITY_REFERENCE,       /* Entity Reference */
   XML_EVENT_CDATA,                  /* CDATA */
   XML_EVENT_CDATA_CONT,             /* CDATA continued */
   XML_EVENT_START_ENTITY,           /* Start Entity */
   XML_EVENT_END_ENTITY,             /* End Entity */
   XML_EVENT_END_DOCUMENT,           /* End Document */
   XML_EVENT_ERROR                   /* Error */
}xmlevtype;

xmlhasht

The hash value of an XML tree or sub-tree; also known as a digest.

If the hash values for two XML trees are equal, the trees are considered equal, to a very high probability; uses the MD5 algorithm.

Definition

struct xmlhasht {
   ub4  l_xmlhasht;   /* lenght of digest in bytes */
   ub1  d_xmlhasht[XMLDF_DIGEST_MAX];   /* the digest */
};
typedef struct xmlhasht xmlhasht;

xmlistream

Generic user-defined input stream. The three function pointers are required (but may be stubs). The context pointer is entirely user-defined; point it to whatever state information is required to manage the stream; it will be passed as first argument to the user functions.

Definition

typedef struct xmlistream {
   XML_STREAM_OPEN_F(
      (*open_xmlistream),
      xctx, 
      sctx, 
      path,
      parts,
      length);
   XML_STREAM_READ_F(
      (*read_xmlistream),
      xctx, 
      sctx, 
      path, 
      dest, 
      size,
      nraw, eoi);
   XML_STREAM_CLOSE_F(
      (*close_xmlistream),
      xctx,
      sctx);
   void *ctx_xmlistream;                         /* user's stream context */
} xmlistream;

xmliter

Control structure for DOM 2 NodeIterator and TreeWalker.

Definition

struct xmliter {
   xmlnode *root_xmliter;   /* root node of the iteration space */
   xmlnode *cur_xmliter;    /* current position iterator ref node */
   ub4      show_xmliter;   /* node filter mask */
   void    *filt_xmliter;   /* node filter function */
   boolean  attach_xmliter; /* is iterator valid? */
   boolean  expan_xmliter;  /* are external entities expanded? */
   boolean  before_xmliter; /* iter position before ref node? */
};
typedef struct xmliter xmliter;
typedef struct xmliter xmlwalk;

xmlnodetype

The numeric type code of a node. 0 means invalid, 1-13 are the standard numberings from DOM 1.0, and higher numbers are for internal use only.

Definition

typedef enum {
    XMLDOM_NONE     , /* bogus node */
    XMLDOM_ELEM     , /* element */
    XMLDOM_ATTR     , /* attribute */
    XMLDOM_TEXT     , /* char data not escaped by CDATA */
    XMLDOM_CDATA    , /* char data escaped by CDATA */
    XMLDOM_ENTREF   , /* entity reference */
    XMLDOM_ENTITY   , /* entity */
    XMLDOM_PI       , /* <?processing instructions?> */
    XMLDOM_COMMENT  , /* <!-- Comments --> */
    XMLDOM_DOC      , /* Document */
    XMLDOM_DTD      , /* DTD */
    XMLDOM_FRAG     , /* Document fragment */
    XMLDOM_NOTATION , /* notation */

    /* Oracle extensions from here on */
    XMLDOM_ELEMDECL , /* DTD element declaration */
    XMLDOM_ATTRDECL , /* DTD attribute declaration */

    /* Content Particles (nodes in element's Content Model) */
    XMLDOM_CPELEM   , /* element */
    XMLDOM_CPCHOICE , /* choice (a|b) */
    XMLDOM_CPSEQ    , /* sequence (a,b) */
    XMLDOM_CPPCDATA , /* #PCDATA */
    XMLDOM_CPSTAR   , /* '*' (zero or more) */
    XMLDOM_CPPLUS   , /* '+' (one or more) */
    XMLDOM_CPOPT    , /* '?' (optional) */
    XMLDOM_CPEND      /* end marker */
} xmlnodetype;

xmlostream

Generic user-defined output stream. The three function pointers are required (but may be stubs). The context pointer is entirely user-defined; point it to whatever state information is required to manage the stream; it will be passed as first argument to the user functions.

Definition

typedef struct xmlostream {
   XML_STREAM_OPEN_F(
      (*open_xmlostream),
      xctx,
      sctx, 
      path, 
      parts,
      length);
   XML_STREAM_WRITE_F(
      (*write_xmlostream),
      xctx, 
      sctx,
      path, 
      src,
      size);
   XML_STREAM_CLOSE_F(
      (*close_xmlostream),
      xctx,
      sctx);
   void *ctx_xmlostream;        /* user's stream context */
} xmlostream;

xmlpoint

XPointer point location.

Definition

typedef struct xmlpoint xmlpoint;

xmlrange

Control structure for DOM 2 Range.

Definition

typedef struct xmlrange {
 xmlnode *startnode_xmlrange;  /* start point container */
 ub4      startofst_xmlrange;  /* start point index */
 xmlnode *endnode_xmlrange;    /* end point container */
 ub4      endofst_xmlrange;    /* end point index */
 xmlnode *doc_xmlrange;        /* document node */
 xmlnode *root_xmlrange;       /* root node of the range */
 boolean  collapsed_xmlrange;  /* is range collapsed? */
 boolean  detached_xmlrange;   /* range invalid, invalidated?*/
} xmlrange;

xmlsoapbind

Binding for SOAP connections. SOAP does not dictate the binding (transport) used for conveying messages; however the HTTP protocol is well-defined and currently the only choice.

Definition

typedef enum xmlsoapbind {
   XMLSOAP_BIND_NONE ,  /* none */
   XMLSOAP_BIND_HTTP    /* HTTP */ } xmlsoapbind;

xmlsoapcon

SOAP connection object. Each distinct connection requires an instance of this type, which contains binding and endpoint information.

Definition

typedef struct xmlsoapcon xmlsoapcon;

xmlsoapctx

Context for SOAP operations. Only a single context is needed and it can be shared by several SOAP messages.

Definition

typedef struct xmlsoapctx xmlsoapctx;

xmlsoaprole

Role for a SOAP node.

Definition

typedef enum xmlsoaprole {
    XMLSOAP_ROLE_UNSET,   /* not specified */
    XMLSOAP_ROLE_NONE,    /* "none" */
    XMLSOAP_ROLE_NEXT,    /* "next" */
    XMLSOAP_ROLE_ULT,     /* "ultimateReceiver" */
    XMLSOAP_ROLE_OTHER    /* other - user defined */
} xmlsoaprole;

xmlshowbits

Bit flags used to select which nodes types to show.

Definition

typedef ub4 xmlshowbits;
#define XMLDOM_SHOW_ALL        ~(ub4)0
#define XMLDOM_SHOW_BIT(ntype) ((ub4)1 << (ntype))
#define XMLDOM_SHOW_ELEM       XMLDOM_SHOW_BIT(XMLDOM_ELEM)
#define XMLDOM_SHOW_ATTR       XMLDOM_SHOW_BIT(XMLDOM_ATTR)
#define XMLDOM_SHOW_TEXT       XMLDOM_SHOW_BIT(XMLDOM_TEXT)
#define XMLDOM_SHOW_CDATA      XMLDOM_SHOW_BIT(XMLDOM_CDATA)
#define XMLDOM_SHOW_ENTREF     XMLDOM_SHOW_BIT(XMLDOM_ENTREF)
#define XMLDOM_SHOW_ENTITY     XMLDOM_SHOW_BIT(XMLDOM_ENTITY)
#define XMLDOM_SHOW_PI         XMLDOM_SHOW_BIT(XMLDOM_PI)
#define XMLDOM_SHOW_COMMENT    XMLDOM_SHOW_BIT(XMLDOM_COMMENT)
#define XMLDOM_SHOW_DOC        XMLDOM_SHOW_BIT(XMLDOM_DOC)
#define XMLDOM_SHOW_DTD        XMLDOM_SHOW_BIT(XMLDOM_DTD)
#define XMLDOM_SHOW_FRAG       XMLDOM_SHOW_BIT(XMLDOM_FRAG)
#define XMLDOM_SHOW_NOTATION   XMLDOM_SHOW_BIT(XMLDOM_NOTATION)
#define XMLDOM_SHOW_DOC_TYPE   XMLDOM_SHOW_BIT(XMLDOM_DOC_TYPE)

xmlurlacc

This is an enumeration of the known access methods for retrieving data from a URL. Open/read/close functions may be plugged in to override the default behavior.

Definition

typedef enum {
    XML_ACCESS_NONE    , /* not specified */
    XML_ACCESS_UNKNOWN , /* specified but unknown */
    XML_ACCESS_FILE    , /* filesystem access */
    XML_ACCESS_HTTP    , /* HTTP */
    XML_ACCESS_FTP     , /* FTP */
    XML_ACCESS_GOPHER  , /* Gopher */
    XML_ACCESS_ORADB   , /* Oracle DB */
    XML_ACCESS_STREAM    /* user-defined stream */
} xmlurlacc;

xmlurlhdl

This union contains the handle(s) needed to access URL data, be it a stream or stdio pointer, file descriptor(s), and so on.

Definition

typedef union xmlurlhdl {
    void  *ptr_xmlurlhdl;  /* generic stream/file/... handle */
    struct {
        sb4 fd1_xmlurlhdl; /* file descriptor(s) [FTP needs all 3!] */
        sb4 fd2_xmlurlhdl;
        sb4 fd3_xmlurlhdl;
    } fds_lpihdl;
} xmlurlhdl;

xmlurlpart

This structure contains the sub-parts of a URL. The original URL is parsed and the pieces copies (NULL-terminated) to a working buffer, then this structure is filled in to point to the parts. Given URL http://user:pwd@baz.com:8080/pub/baz.html;quux=1?huh#fraggy, the example component part from this URL will be shown.

Definition

typedef struct xmlurlpart {
 xmlurlacc access_xmlurlpart;   /* access method code, XMLACCESS_HTTP */
 oratext   *accbuf_xmlurlpart;  /* access method name: "http" */
 oratext   *host_xmlurlpart;    /* hostname:         "baz.com" */
 oratext   *dir_xmlurlpart;     /* directory:        "pub" */
 oratext   *file_xmlurlpart;    /* filename:         "baz.html" */
 oratext   *uid_xmlurlpart;     /* userid/username:  "user" */
 oratext   *passwd_xmlurlpart;  /* password:         "pwd" */
 oratext   *port_xmlurlpart;    /* port (as string): "8080" */
 oratext   *frag_xmlurlpart;    /* fragment:         "fraggy" */
 oratext   *query_xmlurlpart;   /* query:            "huh" */
 oratext   *param_xmlurlpart;   /* parameter:        "quux=1" */
 ub2        portnum_xmlurlpart; /* port (as number): 8080 */
 ub1        abs_xmlurlpart;     /* absolute path?     TRUE */
} xmlurlpart;

xmlxptrloc

XPointer location data type.

Definition

typedef struct xmlxptrloc xmlxptrloc;

xmlxptrlocset

XPointer location set data type.

Definition

typedef struct xmlxptrlocset xmlxptrlocset;

xmlxslobjtype

Type of XSLT object that may be returned.

Definition

typedef enum xmlxslobjtype {
    XMLXSL_TYPE_UNKNOWN , /* Not a defined type */
    XMLXSL_TYPE_NDSET   , /* Node-set */
    XMLXSL_TYPE_BOOL    , /* Boolean value */
    XMLXSL_TYPE_NUM     , /* Numeric value (double) */
    XMLXSL_TYPE_STR     , /* String */
    XMLXSL_TYPE_FRAG      /* Document Fragment */
} xmlxslobjtype;

xmlxslomethod

Type of output to be produced by the XSLT processor.

Definition

typedef enum xmlxslomethod {
 XMLXSL_OUTPUT_UNKNOWN , /* Not defined */
 XMLXSL_OUTPUT_XML     , /* Produce a Document Fragment */
 XMLXSL_OUTPUT_STREAM  , /* Stream out formatted result */
 XMLXSL_OUTPUT_HTML      /* Stream out HTML formatted result */
} xmlxslomethod;

xmlxvm

An object of type xmlxvm is used for XML documents transformation. The contents of xmlxvm are private and must not be accessed by users.

Definition

struct xmlxvm; 
typedef struct xmlxvm xmlxvm;

xmlxvmcomp

An object of type xmlxvmcomp is used for compiling XSL stylesheets. The contents of xmlxvmcomp are private and must not be accessed by users.

Definition

struct xmlxvmcomp; 
typedef struct xmlxvmcomp xmlxvmcomp;

xmlxvmflags

Control flags for the XSLT compiler.

Definition

typedef ub4 xmlxvmflag;
#define XMLXVM_NOFLAG   
#define XMLXVM_DEBUG      /* insert debug info into bytecode */
#define XMLXVM_STRIPSPACE /* same as xsl:strip-space elements="*" */

xmlxvmobjtype

Type of XSLTVM object.

Definition

typedef enum xmlxvmobjtype {
    XMLXVM_TYPE_UNKNOWN ,
    XMLXVM_TYPE_NDSET   ,
    XMLXVM_TYPE_BOOL    ,
    XMLXVM_TYPE_NUM     ,
    XMLXVM_TYPE_STR     ,
    XMLXVM_TYPE_FRAG    
} xmlxvmobjtype;

xpctx

XPath top-level context.

Definition

struct xpctx;
typedef struct xpctx xpctx;

xpexpr

XPath expression.

Definition

struct xpexpr;
typedef struct xpexpr xpexpr;

xpobj

Xpath object.

Definition

struct xpobj;typedef struct xpobj xpobj;

xsdctx

XML Schema validator context, created by XmlSchemaCreate and passed to most Schema functions.

Definition

# define XSDCTX_DEFINED
struct xsdctx; typedef struct xsdctx xsdctx;

xslctx

XSL top-level context.

Definition

struct xslctx;
typedef struct xslctx xslctx;

xvmobj

XSLVM processor run-time object; content is private and must not be accessed by users.

Definition

struct xvmobj;
typedef struct xvmobj xvmobj;
PKPKnFJ OEBPS/toc.ncxP Oracle® Database XML C API Reference, 11g Release 2 (11.2) Cover Title and Copyright Information Contents List of Examples List of Tables Preface What's New in the XML C APIs? 1 Datatypes for C 2 Package Callback APIs for C 3 Package DOM APIs for C 4 Package Event APIs for C 5 Package Orastream APIs for C 6 Package Range APIs for C 7 Package SAX APIs for C 8 Package Schema APIs for C 9 Package SOAP APIs for C 10 Package Traversal APIs for C 11 Package XML APIs for C 12 Package XmlDiff APIs for C 13 Package XPath APIs for C 14 Package XPointer APIs for C 15 Package XSLT APIs for C 16 Package XSLTVM APIs for C A Mapping of APIs used before Oracle Database 10g Release 1 Index Copyright PK؍UtUPPKnFJOEBPS/xsltvm.htm Package XSLTVM APIs for C

16 Package XSLTVM APIs for C

Package XSLTVM implements the XSL Transformation (XSLT) language as specified in W3C Recommendation 16 November 1999. The XSLTVM package contains two interfaces.

This chapter contains the following sections:


Using XSLTVM

XSLT Virtual Machine is the software implementation of a "CPU" designed to run compiled XSLT code. A concept of virtual machine assumes a compiler compiling XSLT stylesheets to a sequence of byte codes or machine instructions for the "XSLT CPU". The byte-code program is a platform-independent sequence of 2-byte units. It can be stored, cached and run on different XSLTVM. The XSLTVM uses the bytecode programs to transform instance XML documents. This approach clearly separates compile (design)-time from run-time computations and specifies a uniform way of exchanging data between instructions.

A typical scenario of using the package APIs has the following steps:

  1. Create/Use an XML meta context object.

    xctx = XmlCreate(,...);

  2. Create/Use an XSLT Compiler object.

    comp = XmlXvmCreateComp(xctx);

  3. Compile an XSLT stylesheets and cache the result bytecode.

    code = XmlXvmCompileFile(comp, xslFile, baseuri, flags, );

  4. Create/Use an XSLTVM object. The explicit stack size setting are needed when XSLTVM terminates with "... Stack Overflow" message or when smaller memory footprints are required (see XmlXvmCreate).

    vm = XmlXvmCreate(xctx, "StringStack", 32, "NodeStack", 24, NULL);

  5. Set a stylesheet bytecode to the XSLTVM object.

    len = XmlXvmGetBytecodeLength(code, ); err = XmlXvmSetBytecodeBuffer(vm, code, len);

  6. Transform an instance XML document.

    err = XmlXvmTransformFile(vm, xmlFile, baseuri);

  7. Clean.

    XmlXvmDestroy(vm);

    XmlXvmDestroyComp(comp);

    XmlDestroy(xctx);


XSLTC Interface

Table 16-1 summarizes the methods available through the XSLTVM Interface.

Table 16-1 Summary of XSLTC Methods; XSLTVM Package

FunctionSummary

XmlXvmCompileBuffer()


Compile an XSLT stylesheet from buffer into bytecode.

XmlXvmCompileDom()


Compile an XSLT stylesheet from DOM into bytecode.

XmlXvmCompileFile()


Compile an XSLT stylesheet from file into bytecode.

XmlXvmCompileURI()


Compile XSLT stylesheet from URI into byte code.

XmlXvmCompileXPath()


Compile an XPath expression.

XmlXvmCreateComp()


Create an XSLT compiler.

XmlXvmDestroyComp()


Destroy an XSLT compiler object.

XmlXvmGetBytecodeLength()


Returns the bytecode length.



XmlXvmCompileBuffer()

Compile an XSLT stylesheet from buffer into bytecode. Compiler flags could be one or more of the following:

The generated bytecode resides in a compiler buffer which is freed when next stylesheet is compiled or when compiler object is deleted. Hence, if the bytecode is to be reused it should be copied into another location.

Syntax

ub2 *XmlXvmCompileBuffer(
   xmlxvmcomp *comp,
   oratext *buffer,
   ub4 length, 
   oratext *baseURI,
   xmlxvmflag flags,
   xmlerr *error);
ParameterIn/OutDescription
comp
IN
compiler object
buffer
IN
pointer to buffer containing stylesheet document
length
IN
length of the stylesheet document in bytes
baseuri
IN
base URI of the document
flags
IN
flags for the current compilation
error
OUT
returned error code

Returns

(ub2 *) bytecode or NULL on error


XmlXvmCompileDom()

Compile an XSLT stylesheet from DOM into bytecode. Compiler flags could be one or more of the following:

The generated bytecode resides in a compiler buffer which is freed when next stylesheet is compiled or when compiler object is deleted. Hence, if the bytecode is to be reused it should be copied into another location.

Syntax

ub2 *XmlXvmCompileDom(
   xmlxvmcomp *comp,
   xmldocnode *root,
   xmlxvmflag flags,
   xmlerr *error);
ParameterIn/OutDescription
comp
IN
compiler object
rooot
IN
root element of the stylesheet DOM
flags
IN
flags for the current compilation
error
OUT
returned error code

Returns

(ub2 *) bytecode or NULL on error


XmlXvmCompileFile()

Compile XSLT stylesheet from file into bytecode. Compiler flags could be one or more of the following:

The generated bytecode resides in a compiler buffer which is freed when next stylesheet is compiled or when compiler object is deleted. Hence, if the bytecode is to be reused it should be copied into another location.

Syntax

ub2 *XmlXvmCompileFile(
   xmlxvmcomp *comp, 
   oratext *path,
   oratext *baseURI,
   xmlxvmflag flags,
   xmlerr *error);
ParameterIn/OutDescription
comp
IN
compiler object
path
IN
path of XSL stylesheet file
baseuri
IN
base URI of the document
flags
IN
flags for the current compilation
error
OUT
returned error code

Returns

(ub2 *) bytecode or NULL on error


XmlXvmCompileURI()

Compile XSLT stylesheet from URI into bytecode. Compiler flags could be one or more of the following:

The generated bytecode resides in a compiler buffer which is freed when next stylesheet is compiled or when compiler object is deleted. Hence, if the bytecode is to be reused it should be copied into another location.

Syntax

ub2 *XmlXvmCompileURI(
   xmlxvmcomp *comp, 
   oratext *uri, 
   xmlxvmflag flags, 
   xmlerr *error);
ParameterIn/OutDescription
comp
IN
compiler object
uri
IN
URI of the file that contains the XSL stylesheet
flags
IN
flags for the current compilation
error
OUT
returned error code

Returns

(ub2 *) bytecode or NULL on error


XmlXvmCompileXPath()

Compiles an XPath expression. The optional pfxmap is used to map namespace prefixes to URIs in the XPath expression. It is an array of prefix, URI values, ending in NULL, and so on.

Syntax

ub2 *XmlXvmCompileXPath(
   xmlxvmcomp *comp, 
   oratext *xpath,
   oratext **pfxmap,
   xmlerr *error);
ParameterIn/OutDescription
comp
IN
compiler object
xpath
IN
XPath expression
pfxmap
IN
array of prefix-URI mappings
error
OUT
returned error code

Returns

(ub2 *) XPath expression bytecode or NULL on error


XmlXvmCreateComp()

Create an XSLT compiler object. The XSLT compiler is used to compile XSLT stylesheets into bytecode.

Syntax

xmlxvmcomp *XmlXvmCreateComp(
   xmlctx *xctx);
ParameterIn/OutDescription
xctx
IN
XML context

Returns

(xmlxvmcomp *) XSLT compiler object, or NULL on error


XmlXvmDestroyComp()

Destroys an XSLT compiler object

Syntax

void XmlXvmDestroyComp(
   xmlxvmcomp *comp);
ParameterIn/OutDescription
comp
IN
XSLT compiler object


See Also:

XmlXvmCreateComp()


XmlXvmGetBytecodeLength()

The bytecode length is needed when the bytecode is to be copied or when it is set into XSLTVM.

Syntax

ub4 XmlXvmGetBytecodeLength(
   ub2 *bytecode,
   xmlerr *error);
ParameterIn/OutDescription
bytecode
IN
bytecode buffer
error
OUT
returned error code

Returns

(ub4) The bytecode length in bytes.


XSLTVM Interface

Table 16-2 summarizes the methods available through the XSLTVM Interface.

Table 16-2 Summary of XSLTVM Methods; Package XSLTVM

FunctionSummary

XMLXVM_DEBUG_F()


XMLXSLTVM debug function.

XmlXvmCreate()


Create an XSLT virtual machine.

XmlXvmDestroy()


Destroys an XSLT virtual machine.

XmlXvmEvaluateXPath()


Evaluate already-compiled XPath expression.

XmlXvmGetObjectBoolean()


Get boolean value of XPath object.

XmlXvmGetObjectNSetNode()


Get node from nodeset type XPathobject.

XmlXvmGetObjectNSetNum()


Get number of nodes in nodeset type XPathobject.

XmlXvmGetObjectNumber()


Get number from XPath object.

XmlXvmGetObjectString()


Get string from XPath object.

XmlXvmGetObjectType()


Get XPath object type.

XmlXvmGetOutputDom()


Returns the output DOM.

XmlXvmResetParams()


Resets the stylesheet top level text parameters.

XmlXvmSetBaseURI()


Sets the base URI for the XLTVM.

XmlXvmSetBytecodeBuffer()


Set the compiled bytecode.

XmlXvmSetBytecodeFile()


Set the compiled byte code from file.

XmlXvmSetBytecodeURI()


Set the compiled bytecode.

XmlXvmSetDebugFunc()


Set a callback function for debugging.

XmlXvmSetOutputDom()


Sets the XSLTVM to output document node.

XmlXvmSetOutputEncoding()


Sets the encoding for the XSLTVM output.

XmlXvmSetOutputSax()


Sets XSLTVM to output SAX.

XmlXvmSetOutputStream()


Set the XSLTVM output to a user-defined stream.

XmlXvmSetTextParam()


Set the stylesheet top-level text parameter.

XmlXvmTransformBuffer()


Run compiled XSLT stylesheet on XML document in memory.

XmlXvmTransformDom()


Run compiled XSLT stylesheet on XML document as DOM.

XmlXvmTransformFile()


Run compiled XSLT stylesheet on XML document in file.

XmlXvmTransformURI()


Run compiled XSLT stylesheet on XML document from URI.



XMLXVM_DEBUG_F()

Debug callback function for XSLT VM.

Syntax

#define XMLXVM_DEBUG_F(func, line, file, obj, n)
void func(
   ub2 line,
   oratext *file,
   xvmobj *obj,
   ub4 n)
ParameterIn/OutDescription
line
IN
source stylesheet line number
file
IN
stylesheet filename
obj
IN
current VM object
n
IN
index of current node


XmlXvmCreate()

Create an XSLT virtual machine. Zero or more of the following XSLTVM properties could be set by using this API:

If the stack size is not specified the default size is used. The explicit stack size setting is needed when XSLTVM terminates with "Stack Overflow" message or when smaller memory footprints are required.

Syntax

xmlxvm *XmlXvmCreate(
   xmlctx *xctx, 
   list);
ParameterIn/OutDescription
xctx
IN
XML context
list
IN
NULL-terminated list of properties to set; can be empty

Returns

(xmlxvm *) XSLT virtual machine object, or NULL on error


See Also:

XmlXvmDestroy()


XmlXvmDestroy()

Destroys an XSLT virtual machine

Syntax

void XmlXvmDestroy(
   xmlxvm *vm);
ParameterIn/OutDescription
vm
IN
VM object


See Also:

XmlXvmCreate()


XmlXvmEvaluateXPath()

Evaluate already-compiled XPath expression

Syntax

xvmobj *XmlXvmEvaluateXPath(
   xmlxvm *vm, 
   ub2 *bytecode, 
   ub4 ctxpos,
   ub4 ctxsize,
   xmlnode *ctxnode);
ParameterIn/OutDescription
vm
IN
XSLTVM object
bytecode
IN
XPath expression bytecode
ctxpos
IN
current context position
ctxsize
IN
current context size
ctxnode
IN
current context node

Returns

(xvmobj *) XPath object


XmlXvmGetObjectBoolean()

Get boolean value of XPath object

Syntax

boolean XmlXvmGetObjectBoolean(
   xvmobj *obj);
ParameterIn/OutDescription
obj
IN
object

Returns

(boolean) value of an XPath object


XmlXvmGetObjectNSetNode()

Get node from nodeset-type XPath object

Syntax

xmlnode *XmlXvmGetObjectNSetNode(
   xvmobj *obj,
   ub4 i);
ParameterIn/OutDescription
obj
IN
object
i
IN
node index in nodeset

Returns

(xmlnode *) The object type or values.


XmlXvmGetObjectNSetNum()

Get number of nodes in nodeset-type XPath object

Syntax

ub4 XmlXvmGetObjectNSetNum(
   xvmobj *obj);
ParameterIn/OutDescription
obj
IN
object

Returns

(ub4) number of nodes in nodeset


XmlXvmGetObjectNumber()

Get number from XPath object.

Syntax

double XmlXvmGetObjectNumber(
   xvmobj *obj);
ParameterIn/OutDescription
obj
IN
object

Returns

(double) number


XmlXvmGetObjectString()

Get string from XPath object.

Syntax

oratext *XmlXvmGetObjectString(
   xvmobj *obj);
ParameterIn/OutDescription
obj
IN
object

Returns

(oratext *) string


XmlXvmGetObjectType()

Get XPath object type

Syntax

xmlxvmobjtype XmlXvmGetObjectType(
   xvmobj *obj);
ParameterIn/OutDescription
obj
IN
object

Returns

(xmlxvmobjtype) type-code for object


XmlXvmGetOutputDom()

Returns the root node of the result DOM tree (if any). XmlXvmSetOutputDom has to be used before transformation to set the VM to output a DOM tree (the default VM output is a stream).

Syntax

xmlfragnode *XmlXvmGetOutputDom(
   xmlxvm *vm);
ParameterIn/OutDescription
vm
IN
VM object

Returns

(xmlfragnode *) output DOM, or NULL in a case of SAX or Stream output.


XmlXvmResetParams()

Resets the stylesheet top-level parameters with their default values.

Syntax

void XmlXvmResetParams(
   xmlxvm *vm);
ParameterIn/OutDescription
vm
IN
VM object


XmlXvmSetBaseURI()

Sets the base URI for the XSLTVM. The baseuri is used by VM to the compose the path XML documents to be loaded for transformation using document or XmlXvmTransformFile.

Syntax

xmlerr XmlXvmSetBaseURI(
   xmlxvm *vm, 
   oratext *baseuri);
ParameterIn/OutDescription
vm
IN
VM object
baseuri
IN
VM base URI for reading and writing documents

Returns

(xmlerr) error code.


XmlXvmSetBytecodeBuffer()

Set the compiled bytecode from buffer. Any previously set bytecode is replaced. An XML transformation can't be performed if the stylesheet bytecode is not set. The VM doesn't copy the bytecode into internal buffer, hence the it shouldn't be freed before VM finishes using it.

Syntax

xmlerr XmlXvmSetBytecodeBuffer(
   xmlxvm *vm, 
   ub2 *buffer, 
   size_t buflen);
ParameterIn/OutDescription
vm
IN
XSLT VM context
buffer
IN
user's buffer
buflen
IN
size of buffer, in bytes

Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success


XmlXvmSetBytecodeFile()

Set the compiled bytecode from file. Any previously set bytecode is replaced. An XML transformation can't be performed if the stylesheet bytecode is not set.

Syntax

xmlerr XmlXvmSetBytecodeFile(
   xmlxvm *vm,
   oratext *path);
ParameterIn/OutDescription
vm
IN
XSLT VM context
path
IN
path of bytecode file

Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success


XmlXvmSetBytecodeURI()

Set the compiled bytecode from URI. Any previously set bytecode is replaced. An XML transformation can't be performed if the stylesheet bytecode is not set.

Syntax

xmlerr XmlXvmSetBytecodeURI(
   xmlxvm *vm,
   oratext *uri);
ParameterIn/OutDescription
vm
IN
XSLT VM context
uri
IN
path of bytecode file

Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success


XmlXvmSetDebugFunc()

The user callback function is invoked by VM every time the execution reaches a new line in the XSLT stylesheet. The VM passes to the user the stylesheet file name, the line number, the current context nodes-set and the current node index in the node-set. IMPORTANT - the stylesheet has to be compiled with flag XMLXVM_DEBUG.

Syntax

#define XMLXVM_DEBUG_FUNC(func)
void func (ub2 line, oratext *filename, xvmobj *obj, ub4 n)
xmlerr XmlXvmSetDebugFunc(
   xmlxvm *vm,
   XMLXVM_DEBUG_FUNC(debugcallback));
ParameterIn/OutDescription
vm
IN
XSLT VM context
func
IN
callback function

Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success


XmlXvmSetOutputDom()

Sets the XSLTVM to output DOM. If xmldocnode==NULL, then the result DOM tree belongs to the VM object and is deleted when a new transformation is performed or when the VM object is deleted. If the result DOM tree is to be used for longer period of time then an xmldocnode has to be created and set to the VM object.

Syntax

xmlerr XmlXvmSetOutputDom(
   xmlxvm *vm,
   xmldocnode *doc);
ParameterIn/OutDescription
vm
IN
VM object
doc
IN
empty document

Returns

(xmlerr) error code


XmlXvmSetOutputEncoding()

Sets the encoding for the XSLTVM stream output. If the input (data) encoding is different from the one set by this APIs then encoding conversion is performed. This APIs overrides the encoding set in the XSLT stylesheet (if any).

Syntax

xmlerr XmlXvmSetOutputEncoding(
   xmlxvm *vm, 
   oratext *encoding);
ParameterIn/OutDescription
vm
IN
VM object
encoding
IN
output encoding

Returns

(xmlerr) error code.


XmlXvmSetOutputSax()

Set XSLTVM to output SAX. If the SAX callback interface object is provided the VM outputs the result document in a form of SAX events using the user specified callback functions.

Syntax

xmlerr XmlXvmSetOutputSax(
   xmlxvm *vm,
   xmlsaxcb *saxcb, 
   void *saxctx);
ParameterIn/OutDescription
vm
IN
VM object
saxcb
IN
SAX callback object
saxctx
IN
SAX context

Returns

(xmlerr) error code


XmlXvmSetOutputStream()

Set the XSLTVM output to a user-defined stream. The default XSLTVM output is a stream. This APIs overrides the default stream with user specified APIs for writing.

Syntax

xmlerr XmlXvmSetOutputStream(
   xmlxvm *vm,
   xmlostream *ostream);
ParameterIn/OutDescription
vm
IN
VM object
ostream
IN
stream object

Returns

(xmlerr) error code.


XmlXvmSetTextParam()

Set the stylesheet top-level text parameter. The parameter value set in the XSLT stylesheet is overwritten. Since the top-level parameters are reset with stylesheet values after each transformation, this APIs has to be called again.

Syntax

xmlerr XmlXvmSetTextParam(
   xmlxvm *vm,
   oratext *name,
   oratext *value);
ParameterIn/OutDescription
vm
IN
VM object
name
IN
name of top-level parameter
value
IN
value of top-level parameter

Returns

(xmlerr) error code, XMLERR_SUCC [0] on success.


XmlXvmTransformBuffer()

Run compiled XSLT stylesheet on XML document in memory. The compiled XSLT stylesheet (bytecode) should be set using XmlXvmSetBytecodeXXX prior to this call.

Syntax

xmlerr XmlXvmTransformBuffer(
   xmlxvm *vm,
   oratext *buffer,
   ub4 length,
   oratext *baseURI);
ParameterIn/OutDescription
vm
IN
VM object
buffer
IN
NULL-terminated buffer that contains the XML document
length
IN
length of the XML document
baseURI
IN
base URI of XML document

Returns

(xmlerr) error code.


XmlXvmTransformDom()

Run compiled XSLT stylesheet on XML document as DOM. The compiled XSLT stylesheet (bytecode) should be set using XmlXvmSetBytecodeXXX prior to this call.

Syntax

xmlerr XmlXvmTransformDom(
   xmlxvm *vm,
   xmldocnode *root);
ParameterIn/OutDescription
vm
IN
VM object
root
IN
root element of XML document's DOM

Returns

(xmlerr) error code.


XmlXvmTransformFile()

Run compiled XSLT stylesheet on XML document in file. The compiled XSLT stylesheet (bytecode) should be set using XmlXvmSetBytecodeXXX prior to this call.

Syntax

xmlerr XmlXvmTransformFile(
   xmlxvm *vm,
   oratext *path,
   oratext *baseURI);
ParameterIn/OutDescription
vm
IN
VM object
path
IN
path of XML document to transform
baseURI
IN
base URI of XML document

Returns

(xmlerr) error code


XmlXvmTransformURI()

Run compiled XSLT stylesheet on XML document from URI. The compiled XSLT stylesheet (bytecode) should be set using XmlXvmSetBytecodeXXX prior to this call.

Syntax

xmlerr XmlXvmTransformURI(
   xmlxvm *vm, 
   oratext *uri);
ParameterIn/OutDescription
vm
IN
VM object
uri
IN
URI of XML document to transform

Returns

(xmlerr) error code.

PKoPKnFJOEBPS/callback.htm Package Callback APIs for C

2 Package Callback APIs for C

This package defines macros which declare functions (or function pointers) for XML callbacks. Callbacks are used for error-message handling, memory allocation and freeing, and stream operations.

This chapter contains the following section:


Callback Methods

Table 2-1 summarizes the methods available through the Callback interface.

Table 2-1 Summary of Callback Methods

FunctionSummary

XML_ACCESS_CLOSE_F()


User-defined access method close callback.

XML_ACCESS_OPEN_F()


User-defined access method open callback.

XML_ACCESS_READ_F()


User-defined access method read callback.

XML_ALLOC_F()


Low-level memory allocation.

XML_ERRMSG_F()


Handles error message.

XML_FREE_F()


Low-level memory freeing.

XML_STREAM_CLOSE_F()


User-defined stream close callback.

XML_STREAM_OPEN_F()


User-defined stream open callback.

XML_STREAM_READ_F()


User-defined stream read callback.

XML_STREAM_WRITE_F()


User-defined stream write callback.



XML_ACCESS_CLOSE_F()

This macro defines a prototype for the close function callback used to access a URL.

Syntax

#define XML_ACCESS_CLOSE_F(func, ctx, uh)
xmlerr func(
   void *ctx,
    xmlurlhdl *uh);
ParameterIn/OutDescription
ctx
IN
user-defined context
uh
IN
URL handle(s)

Returns

(xmlerr) numeric error code, 0 on success


XML_ACCESS_OPEN_F()

This macro defines a prototype for the open function callback used to access a URL.

Syntax

#define XML_ACCESS_OPEN_F(func, ctx, uri, parts, length, uh)
xmlerr func(
   void *ctx,
   oratext *uri, 
   xmlurlpart *parts,
   ubig_ora *length, 
   xmlurlhdl *uh);
ParameterIn/OutDescription
ctx
IN
user-defined context
uri
IN
URI to be opened
parts
IN
URI broken into components
length
OUT
total length of input data if known, 0 otherwise
uh
IN
URL handle(s)

Returns

(xmlerr) numeric error code, 0 on success


XML_ACCESS_READ_F()

This macro defines a prototype for the read function callback used to access a URL.

Syntax

#define XML_ACCESS_READ_F(func, ctx, uh, data, nraw, eoi)
xmlerr func(
   void *ctx, 
   xmlurlhdl *uh, 
   oratext **data, 
   ubig_ora *nraw,
   ub1 *eoi);
ParameterIn/OutDescription
ctx
IN
user-defined context
uh
IN
URL handle(s)
data
IN/OUT
recipient data buffer; reset to start of data
nraw
OUT
number of real data bytes read
eoi
OUT
signal to end of information; last chunk

Returns

(xmlerr) numeric error code, 0 on success


XML_ALLOC_F()

This macro defines a prototype for the low-level memory alloc function provided by the user. If no allocator is provided, malloc is used. Memory should not be zeroed by this function. Matches XML_FREE_F().

Syntax

#define XML_ALLOC_F(func, mctx, size)
void *func(
   void *mctx,
   size_t size);
ParameterIn/OutDescription
mctx
IN
low-level memory context
size
IN
number of bytes to allocated

Returns

(void *) allocated memory


See Also:

XML_FREE_F()


XML_ERRMSG_F()

This macro defines a prototype for the error message handling function. If no error message callback is provided at XML initialization time, errors will be printed to stderr. If a handler is provided, it will be invoked instead of printing to stderr.

Syntax

#define XML_ERRMSG_F(func, ectx, msg, err)
void func(
   void *ectx,
   oratext *msg,
   xmlerr err);
ParameterIn/OutDescription
ectx
IN
error message context
msg
IN
text of error message
err
IN
numeric error code


XML_FREE_F()

This macro defines a prototype for the low-level memory free function provided by the user. If no allocator is provided, free() is used. Matches XML_ALLOC_F().

Syntax

#define XML_FREE_F(func, mctx, ptr)
void func(
   void *mctx,
   void *ptr);
ParameterIn/OutDescription
mctx
IN
low-level memory context
ptr
IN
memory to be freed


XML_STREAM_CLOSE_F()

This macro defines a prototype for the close function callback, called to close an open source and free its resources.

Syntax

#define XML_STREAM_CLOSE_F(func, xctx, sctx)
void func(
   xmlctx *xctx,
   void *sctx);
ParameterIn/OutDescription
xctx
IN
XML context
sctx
IN
user-defined stream context


XML_STREAM_OPEN_F()

This macro defines a prototype for the open function callback, which is called once to open the input source. This function should return XMLERR_OK on success.

Syntax

#define XML_STREAM_OPEN_F(func, xctx, sctx, path, parts, length)
xmlerr func(
   xmlctx *xctx,
   void *sctx,
   oratext *path,
   void *parts,
   ubig_ora *length);
ParameterIn/OutDescription
xctx
IN
XML context
sctx
IN
user-defined stream context
path
IN
full path of the URI to be opened
parts
IN
URI broken down into components (opaque pointer)
length
(OUT)
total length of input data if known, 0 if not known

Returns

(xmlerr) numeric error code, 0 on success


XML_STREAM_READ_F()

This macro defines a prototype for the read function callback, called to read data from an open source into a buffer, returning the number of bytes read (< 0 on error). The eoi flag determines if this is the final block of data.

On EOI, the close function will be called automatically.

Syntax

#define XML_STREAM_READ_F(func, xctx, sctx, path, dest, size, nraw, eoi)
xmlerr func(
   xmlctx *xctx,
   void *sctx,
   oratext *path,
   oratext *dest,
   size_t size,
   sbig_ora *nraw,
   boolean *eoi);
ParameterIn/OutDescription
xctx
IN
XML context
sctx
IN
user-defined stream context
path
IN
full URI of the open source (for error messages)
dest
(OUT)
destination buffer to read data into
size
IN
size of destination buffer
nraw
(OUT)
number of bytes read
eoi
(OUT)
signal to end of information; last chunk

Returns

(xmlerr) numeric error code, 0 on success


XML_STREAM_WRITE_F()

This macro defines a prototype for the write function callback, called to write data to a user-defined stream.

Syntax

#define XML_STREAM_WRITE_F(func, xctx, sctx, path, src, size)
xmlerr func(
   xmlctx *xctx,
   void *sctx,
   oratext *path,
   oratext *src,
   size_t size);
ParameterIn/OutDescription
xctx
IN
XML context
sctx
IN
user-defined stream context
path
IN
full URI of the open source (for error messages)
src
IN
source buffer to read data from
size
IN
size of source in bytes

Returns

(xmlerr) numeric error code, 0 on success

PK\wPKnFJOEBPS/preface.htm Preface

Preface

The Oracle Database XML C API Reference describes Oracle XML Developer's Kits (XDK) and Oracle XML DB APIs for the C programming language. It primarily lists the syntax of functions, methods, and procedures associated with these APIs.

Audience

Oracle Database XML C API Reference is intended for developers who are building XML applications in Oracle.

To use this document, you need a basic understanding of object-oriented programming concepts, familiarity with Structured Query Language (SQL), and working knowledge of application development using the C programming language.

Documentation Accessibility

Our goal is to make Oracle products, services, and supporting documentation accessible to all users, including users that are disabled. To that end, our documentation includes features that make information available to users of assistive technology. This documentation is available in HTML format, and contains markup to facilitate access by the disabled community. Accessibility standards will continue to evolve over time, and Oracle is actively engaged with other market-leading technology vendors to address technical obstacles so that our documentation can be accessible to all of our customers. For more information, visit the Oracle Accessibility Program Web site at http://www.oracle.com/accessibility/.

Accessibility of Code Examples in Documentation

Screen readers may not always correctly read the code examples in this document. The conventions for writing code require that closing braces should appear on an otherwise empty line; however, some screen readers may not always read a line of text that consists solely of a bracket or brace.

Accessibility of Links to External Web Sites in Documentation

This documentation may contain links to Web sites of other companies or organizations that Oracle does not own or control. Oracle neither evaluates nor makes any representations regarding the accessibility of these Web sites.

Deaf/Hard of Hearing Access to Oracle Support Services

To reach Oracle Support Services, use a telecommunications relay service (TRS) to call Oracle Support at 1.800.223.1711. An Oracle Support Services engineer will handle technical issues and provide customer support according to the Oracle service request process. Information about TRS is available at http://www.fcc.gov/cgb/consumerfacts/trs.html, and a list of phone numbers is available at http://www.fcc.gov/cgb/dro/trsphonebk.html.

Related Documents

For more information, see the following documents in the Oracle Database 11g Release 2 (11.2) documentation set:

Conventions

The following text conventions are used in this document:

ConventionMeaning
boldfaceBoldface type indicates graphical user interface elements associated with an action, or terms defined in text or the glossary.
italicItalic type indicates book titles, emphasis, or placeholder variables for which you supply particular values.
monospaceMonospace type indicates commands within a paragraph, URLs, code in examples, text that appears on the screen, or text that you enter.

PKPKnFJOEBPS/xslt.htm Package XSLT APIs for C

15 Package XSLT APIs for C

Package XSLT implements types and methods related to XSL processing.

This chapter contains this section:


XSLT Interface

Table 15-1 summarizes the methods available through the XSLT interface.

Table 15-1 Summary of XSLT Methods

FunctionSummary

XmlXslCreate()


Create an XSL context.

XmlXslDestroy()


Destroy an XSL context.

XmlXslGetBaseURI()


Get the XSL processor base URI.

XmlXslGetOutput()


Get the XSL result fragment.

XmlXslGetStylesheetDom()


Get the XSL stylesheet document.

XmlXslGetTextParam()


Get the XSL text parameter value.

XmlXslProcess()


Perform XSL processing on an instance document.

XmlXslResetAllParams()


Reset XSL processor parameters.

XmlXslSetOutputDom()


Set the XSL context output DOM.

XmlXslSetOutputEncoding()


Set the XSL context output encoding.

XmlXslSetOutputMethod()


Set the XSL context output method.

XmlXslSetOutputSax()


Set the XSL context output SAX.

XmlXslSetOutputStream()


Set the XSL context output stream.

XmlXslSetTextParam()


Set the XSL context output text parameter.



XmlXslCreate()

Create an XSLT context

Syntax

xslctx *XmlXslCreate(
   xmlctx *ctx,
   xmldocnode *xsl,
   oratext *baseuri,
   xmlerr *err);
ParameterIn/OutDescription
ctx
IN
XSL context object
xsl
IN
XSL stylesheet document object
baseuri
IN
base URI for including and importing documents
err
IN/OUT
returned error code

Returns

(xslctx *) XSLT context


See Also:

XmlXslDestroy()


XmlXslDestroy()

Destroy an XSL context

Syntax

xmlerr XmlXslDestroy(
   xslctx *ctx);
ParameterIn/OutDescription
ctx
IN
XSL context

Returns

(xmlerr) error code


See Also:

XmlXslCreate()


XmlXslGetBaseURI()

Get the XSL processor base URI

Syntax

oratext *XmlXslGetBaseURI(
   xslctx *ctx);
ParameterIn/OutDescription
ctx
IN
XSL context object

Returns

(oratext *) base URI


XmlXslGetOutput()

Get the XSL result fragment

Syntax

xmlfragnode *XmlXslGetOutput(
   xslctx *ctx);
ParameterIn/OutDescription
ctx
IN
XSL context object

Returns

(xmlfragnode *) result fragment


XmlXslGetStylesheetDom()

Get the XSL stylesheet document

Syntax

xmldocnode *XmlXslGetStylesheetDom(
   xslctx *ctx);
ParameterIn/OutDescription
ctx
IN
XSL context object

Returns

(xmldocnode *) stylesheet document


XmlXslGetTextParam()

Get the XSL text parameter value

Syntax

oratext *XmlXslGetTextParam(
   xslctx *ctx,
   oratext *name);
ParameterIn/OutDescription
ctx
IN
XML context object
name
IN
name of the top-level parameter value

Returns

(oratext *) parameter value


XmlXslProcess()

Do XSL processing on an instance document

Syntax

xmlerr XmlXslProcess(
   xslctx *ctx,
   xmldocnode *xml,
   boolean normalize);
ParameterIn/OutDescription
ctx
IN
XSL context object
xml
IN
instance document to process
normalize
IN
if TRUE, force the XSL processor to normalize the document

Returns

(xmlerr) error code


XmlXslResetAllParams()

Reset all the top level parameters added

Syntax

xmlerr XmlXslResetAllParams(
   xslctx *ctx);
ParameterIn/OutDescription
ctx
IN
XSL context object

Returns

(xmlerr) error code, XMLERR_SUCC [0] on success.


XmlXslSetOutputDom()

Set the xslctx output DOM

Syntax

xmlerr XmlXslSetOutputDom(
   xslctx *ctx,
   xmldocnode *doc);
ParameterIn/OutDescription
ctx
IN
XSL context object
doc
IN
output node

Returns

(xmlerr) error code, XMLERR_SUCC [0] on success.


XmlXslSetOutputEncoding()

Set the xslctx output encoding

Syntax

xmlerr XmlXslSetOutputEncoding(
   xslctx *ctx,
   oratext* encoding);
ParameterIn/OutDescription
ctx
IN
XML context object
encoding
IN
output encoding

Returns

(xmlerr) error code, XMLERR_SUCC [0] on success.


XmlXslSetOutputMethod()

Set the xslctx output method

Syntax

xmlerr XmlXslSetOutputMethod(
   xslctx *ctx,
   xmlxslomethod method);
ParameterIn/OutDescription
ctx
IN
XML context object
encoding
IN
XSL output method

Returns

(xmlerr) error code, XMLERR_SUCC [0] on success.


XmlXslSetOutputSax()

Set the xslctx output SAX

Syntax

xmlerr XmlXslSetOutputSax(
   xslctx *ctx,
   xmlsaxcb* saxcb,
   void *saxctx);
ParameterIn/OutDescription
ctx
IN
XSL context object
saxcb
IN
SAX callback object
saxctx
IN
SAX callback context

Returns

(xmlerr) error code, XMLERR_SUCC [0] on success.


XmlXslSetOutputStream()

Syntax

xmlerr XmlXslSetOutputStream(
   xslctx *ctx,
   xmlostream *stream);
ParameterIn/OutDescription
ctx
IN
XSL context object
stream
IN
output stream object

Returns

(xmlxsl) error code, XMLXSL_SUCC [0] on success.


XmlXslSetTextParam()

Set the xslctx output text parameter.

Syntax

xmlerr XmlXslSetTextParam(
   xslctx *ctx,
   oratext *name,
   oratext *value);
ParameterIn/OutDescription
ctx
IN
XSL context object
name
IN
name of top level parameter
value
IN
value of top level parameter

Returns

(xmlerr) error code, XMLERR_SUCC [0] on success.

PKY(aV|PKnFJOEBPS/xpointer.htm[ Package XPointer APIs for C

14 Package XPointer APIs for C

Package XPointer contains APIs for three interfaces.

This chapter contains these sections:


XPointer Interface

Table 14-1 summarizes the methods available through the XPointer interface.

Table 14-1 Summary of XPointer Methods; Package XPointer

FunctionSummary

XmlXPointerEval()


Evaluates xpointer string.



XmlXPointerEval()

Parses and evaluates xpointer string and calculates locations in the document.

Syntax

xmlxptrlocset* XmlXPointerEval(
   xmldocnode* doc,
   oratext* xptrstr);
ParameterIn/OutDescription
doc
IN
document node of the corresponding DOM tree
xptrstr
IN
xpointer string

Returns

(xmlxptrlocset *) calculated location set


XPtrLoc Interface

Table 14-2 summarizes the methods available through the XPtrLoc interface.

Table 14-2 Summary of XPtrLoc Methods; Package XPointer

FunctionSummary

XmlXPtrLocGetNode()


Returns Xml node from XPtrLoc.

XmlXPtrLocGetPoint()


Returns Xml point from XPtrLoc.

XmlXPtrLocGetRange()


Returns Xml range from XPtrLoc.

XmlXPtrLocGetType()


Returns type of XPtrLoc.

XmlXPtrLocToString()


Returns string for a location.



XmlXPtrLocGetNode()

Returns node from location

Syntax

xmlnode* XmlXPtrLocGetNode(
   xmlxptrloc* loc);
ParameterIn/OutDescription
loc
IN
location

Returns

(xmlnode *) Node from location


XmlXPtrLocGetPoint()

Returns point from location

Syntax

xmlpoint* XmlXPtrLocGetPoint(
   xmlxptrloc* loc);
ParameterIn/OutDescription
loc
IN
location

Returns

(xmlpoint *) Point from location


XmlXPtrLocGetRange()

Returns range from location.

Syntax

xmlrange* XmlXPtrLocGetRange(
   xmlxptrloc* loc);
ParameterIn/OutDescription
loc
IN
location

Returns

(xmlrange *) Range from location


XmlXPtrLocGetType()

Returns type of location

Syntax

xmlxptrloctype XmlXPtrLocGetType(
   xmlxptrloc* loc);
ParameterIn/OutDescription
loc
IN
location

Returns

(xmlxptrloctype) Type of location


XmlXPtrLocToString()

Returns string for a location:

- node name: name of the container node

- names of container nodes: "not a location" otherwise

Syntax

oratext* XmlXPtrLocToString(
   xmlxptrloc* loc);
ParameterIn/OutDescription
loc
IN
location

Returns

(oratext *) string


XPtrLocSet Interface

Table 14-3 summarizes the methods available through the XPtrLocSet interface.

Table 14-3 Summary of XPtrLocSet Methods; Package XPointer

FunctionSummary

XmlXPtrLocSetFree()


Free a location set

XmlXPtrLocSetGetItem()


Returns location with idx position in XPtrLocSet

XmlXPtrLocSetGetLength()


Returns length of XPtrLocSet.



XmlXPtrLocSetFree()

It is user's responsibility to call this function on every location set returned by XPointer or XPtrLocSet interfaces

Syntax

void XmlXPtrLocSetFree(
   xmlxptrlocset* locset);
ParameterIn/OutDescription
locset
IN
location set


XmlXPtrLocSetGetItem()

Returns location with idx position in the location set. First position is 1.

Syntax

xmlxptrloc* XmlXPtrLocSetGetItem(
   xmlxptrlocset* locset, 
   ub4 idx);
ParameterIn/OutDescription
locset
IN
location set
idx
IN
location index

Returns

(xmlxptrloc *) location with the position idx


XmlXPtrLocSetGetLength()

Returns the number of locations in the location set

Syntax

ub4 XmlXPtrLocSetGetLength(
   xmlxptrlocset* locset);
ParameterIn/OutDescription
locset
IN
location set

Returns

(ub4) number of nodes in locset

PKP E[[PKnFJOEBPS/range.htm Package Range APIs for C

6 Package Range APIs for C

Package Range contains APIs for two interfaces.

This chapter contains the following sections:


DocumentRange Interface

Table 6-1 summarizes the methods available through the DocumentRange interface.

Table 6-1 Summary of DocumentRange Methods; Package Range

FunctionSummary

XmlDomCreateRange()


Create Range object.



XmlDomCreateRange()

The only one method of DocumentRange interface, used to create a Range object.

Syntax

xmlrange* XmlDomCreateRange(
   xmlctx *xctx, 
   xmlrange *range, 
   xmldocnode *doc);
ParameterIn/OutDescription
xctx
IN
XML context
range
IN
existing NodeIterator, or NULL to allocate new
doc
IN
document to which the new Range is attached

Returns

(xmlrange *) original or new Range object.


Range Interface

Table 6-2 summarizes the methods available through the Range interface.

Table 6-2 Summary of Range Methods; Package Range

FunctionSummary

XmlDomRangeClone()


Clone a range.

XmlDomRangeCloneContents()


Clone contents selected by a range.

XmlDomRangeCollapse()


Collapse range to either start point or end point.

XmlDomRangeCompareBoundaryPoints()


Compare boundary points of two ranges.

XmlDomRangeDeleteContents()


Delete content selected by a range.

XmlDomRangeDetach()


Detach a range.

XmlDomRangeExtractContents()


Extract contents selected by a range.

XmlDomRangeGetCollapsed()


Return whether the range is collapsed.

XmlDomRangeGetCommonAncestor()


Return deepest common ancestor node of two boundary points.

XmlDomRangeGetDetached()


Return whether the range is detached.

XmlDomRangeGetEndContainer()


Return range end container node.

XmlDomRangeGetEndOffset()


Return range end offset.

XmlDomRangeGetStartContainer()


Return range start container node.

XmlDomRangeGetStartOffset()


Return range start offset.

XmlDomRangeIsConsistent()


Return whether the range is consistent.

XmlDomRangeSelectNode()


Select a node as a range.

XmlDomRangeSelectNodeContents()


Define range to select node contents.

XmlDomRangeSetEnd()


Set the end point.

XmlDomRangeSetEndBefore()


Set the end point before a node.

XmlDomRangeSetStart()


Set the start point.

XmlDomRangeSetStartAfter()


Set the start point after a node.

XmlDomRangeSetStartBefore()


Set the start point before a node.



XmlDomRangeClone()

Clone a Range. Clones the range without affecting the content selected by the original range. Returns NULL if an error.

Syntax

xmlrange* XmlDomRangeClone(
   xmlctx *xctx, 
   xmlrange *range, 
   xmlerr *xerr);
ParameterIn/OutDescription
xctx
IN
XML context
range
IN
range object
xerr
OUT
numeric return code

Returns

(xmlrange *) new range that clones the old one


XmlDomRangeCloneContents()

Clone contents selected by a range. Clones but does not delete contents selected by a range. Performs the range consistency check and sets retval to an error code if an error.

Syntax

xmlnode* XmlDomRangeCloneContents(
   xmlctx *xctx, 
   xmlrange *range, 
   xmlerr *xerr);
ParameterIn/OutDescription
xctx
IN
XML context
range
IN
range object
xerr
OUT
numeric return code

Returns

(xmlnode *) cloned contents


XmlDomRangeCollapse()

Collapses the range to either start point or end point. The point where it is collapsed to is assumed to be a valid point in the document which this range is attached to.

Syntax

xmlerr XmlDomRangeCollapse(
   xmlctx *xctx, 
   xmlrange *range, 
   boolean tostart);
ParameterIn/OutDescription
xctx
IN
XML context
range
IN
range object
tostart
IN
indicates whether to collapse to start (TRUE) or to end (FALSE)

Returns

(xmlerr) numeric return code


XmlDomRangeCompareBoundaryPoints()

Compares two boundary points of two different ranges. Returns -1,0,1 depending on whether the corresponding boundary point of the range (range) is before, equal, or after the corresponding boundary point of the second range (srange). It returns ~(int)0 if two ranges are attached to two different documents or if one of them is detached.

Syntax

sb4 XmlDomRangeCompareBoundaryPoints(
   xmlctx *xctx, 
   xmlrange *range, 
   xmlcmphow how, 
   xmlrange *srange, 
   xmlerr *xerr);
ParameterIn/OutDescription
xctx
IN
XML context
range
IN
range object
how
IN
xmlcmphow value; how to compare
srange
IN
range object with which to compare
xerr
OUT
numeric return code

Returns

(sb4) strcmp-like comparison result


XmlDomRangeDeleteContents()

Deletes content selected by a range. Performs the range consistency check and sets retval to an error code if an error.

Syntax

xmlerr XmlDomRangeDeleteContents(
   xmlctx *xctx, 
   xmlrange *range);
ParameterIn/OutDescription
xctx
IN
XML context
range
IN
range object

Returns

(xmlerr) numeric return code


XmlDomRangeDetach()

Detaches the range from the document and places it (range) in invalid state.

Syntax

xmlerr XmlDomRangeDetach(
   xmlctx *xctx, 
   xmlrange *range);
ParameterIn/OutDescription
xctx
IN
XML context
range
IN
range object

Returns

(xmlerr) numeric return code


XmlDomRangeExtractContents()

Extract contents selected by a range. Clones and deletes contents selected by a range. Performs the range consistency check and sets retval to an error code if an error.

Syntax

xmlnode* XmlDomRangeExtractContents(
   xmlctx *xctx, 
   xmlrange *range,
   xmlerr *xerr);
ParameterIn/OutDescription
xctx
IN
XML context
range
IN
range object
xerr
OUT
numeric return code

Returns

(xmlnode *) extracted


XmlDomRangeGetCollapsed()

Returns TRUE if the range is collapsed and is not detached, otherwise returns FALSE.

Syntax

boolean XmlDomRangeGetCollapsed(
   xmlctx *xctx, 
   xmlrange *range, 
   xmlerr *xerr);
ParameterIn/OutDescription
xctx
IN
XML context
range
IN
range object
xerr
OUT
numeric return code

Returns

(boolean) TRUE if the range is collapsed, FALSE otherwise


XmlDomRangeGetCommonAncestor()

Returns deepest common ancestor node of two boundary points of the range if the range is not detached, otherwise returns NULL. It is assumed that the range is in a consistent state.

Syntax

xmlnode* XmlDomRangeGetCommonAncestor(
   xmlctx *xctx, 
   xmlrange *range, 
   xmlerr *xerr);
ParameterIn/OutDescription
xctx
IN
XML context
range
IN
range object
xerr
OUT
numeric return code

Returns

(xmlnode *) deepest common ancestor node [or NULL]


XmlDomRangeGetDetached()

Return whether the range is detached. Returns TRUE if the range is detached and is not NULL. Otherwise returns FALSE.

Syntax

ub1 XmlDomRangeGetDetached(
   xmlctx *xctx, 
   xmlrange *range);
ParameterIn/OutDescription
xctx
IN
XML context
range
IN
range object

Returns

(ub1) TRUE if the range is detached, FALSE otherwise


XmlDomRangeGetEndContainer()

Returns range end container node if the range is not detached, otherwise returns NULL.

Syntax

xmlnode* XmlDomRangeGetEndContainer(
   xmlctx *xctx, 
   xmlrange *range,
   xmlerr *xerr);
ParameterIn/OutDescription
xctx
IN
XML context
range
IN
range object
xerr
OUT
numeric return code

Returns

(xmlnode *) range end container node [or NULL]


XmlDomRangeGetEndOffset()

Returns range end offset if the range is not detached, otherwise returns ~(ub4)0 [the maximum ub4 value].

Syntax

ub4 XmlDomRangeGetEndOffset(
   xmlctx *xctx, 
   xmlrange *range, 
   xmlerr *xerr);
ParameterIn/OutDescription
xctx
IN
XML context
range
IN
range object
xerr
OUT
numeric return code

Returns

(ub4) range end offset [or ub4 maximum]


XmlDomRangeGetStartContainer()

Returns range start container node if the range is valid and is not detached, otherwise returns NULL.

Syntax

xmlnode* XmlDomRangeGetStartContainer(
   xmlctx *xctx, 
   xmlrange *range, 
   xmlerr *xerr);
ParameterIn/OutDescription
xctx
IN
XML context
range
IN
range object
xerr
OUT
numeric return code

Returns

(xmlnode *) range start container node


XmlDomRangeGetStartOffset()

Returns range start offset if the range is not detached, otherwise returns ~(ub4)0 [the maximum ub4 value].

Syntax

ub4 XmlDomRangeGetStartOffset(
   xmlctx *xctx, 
   xmlrange *range, 
   xmlerr *xerr);
ParameterIn/OutDescription
xctx
IN
XML context
range
IN
range object
xerr
OUT
numeric return code

Returns

(ub4) range start offset [or ub4 maximum]


XmlDomRangeIsConsistent()

Return whether the range is consistent. Returns TRUE if the range is consistent: both points are under the same root and the start point is before or equal to the end point. Otherwise returns FALSE.

Syntax

boolean XmlDomRangeIsConsistent(
   xmlctx *xctx, 
   xmlrange *range, 
   xmlerr *xerr);
ParameterIn/OutDescription
xctx
IN
XML context
range
IN
range object
xerr
OUT
numeric return code

Returns

(ub1) TRUE if the range is consistent, FALSE otherwise


XmlDomRangeSelectNode()

Sets the range end point and start point so that the parent node of this node becomes the container node, and the offset is the offset of this node among the children of its parent. The range becomes collapsed. It is assumed that the node is a valid node of its document. If the range is detached, it is ignored, and the range becomes attached.

Syntax

xmlerr XmlDomRangeSelectNode(
   xmlctx *xctx, 
   xmlrange *range, 
   xmlnode *node);
ParameterIn/OutDescription
xctx
IN
XML context
range
IN
range object
node
IN
XML node

Returns

(xmlerr) numeric return code


XmlDomRangeSelectNodeContents()

Sets the range start point to the start of the node contents and the end point to the end of the node contents. It is assumed that the node is a valid document node. If the range is detached, it is ignored, and the range becomes attached.

Syntax

xmlerr XmlDomRangeSelectNodeContents(
   xmlctx *xctx, 
   xmlrange *range, 
   xmlnode *node);
ParameterIn/OutDescription
xctx
IN
XML context
range
IN
range object
node
IN
XML node

Returns

(xmlerr) numeric return code


XmlDomRangeSetEnd()

Sets the range end point. If it has a root container other than the current one for the range, the range is collapsed to the new position. If the end is set to be at a position before the start, the range is collapsed to that position. Returns xmlerr value. according to the description where this type is defined. It is assumed that the start point of the range is a valid start point.

Syntax

xmlerr XmlDomRangeSetEnd(
   xmlctx *xctx, 
   xmlrange *range, 
   xmlnode *node, 
   ub4 offset);
ParameterIn/OutDescription
xctx
IN
XML context
range
IN
range object
node
IN
XML node
offset
IN
ending offset

Returns

(xmlerr) numeric return code


XmlDomRangeSetEndBefore()

Sets the range end point before a node. If it has a root container other than the current one for the range, the range is collapsed to the new position. If the before node sets the end to be at a position before the start, the range is collapsed to new position. Returns xmlerr value according to the description where this type is defined. It is assumed that the start point of the range is a valid start point.

Syntax

xmlerr XmlDomRangeSetEndBefore(
   xmlctx *xctx, 
   xmlrange *range, 
   xmlnode *node);
ParameterIn/OutDescription
xctx
IN
XML context
range
IN
range object
node
IN
XML node

Returns

(xmlerr) numeric return code


XmlDomRangeSetStart()

Sets the range start point. If it has a root container other than the current one for the range, the range is collapsed to the new position. If the start is set to be at a position after the end, the range is collapsed to that position. Returns xmlerr value according to the description where this type is defined. It is assumed that the end point of the range is a valid end point.

Syntax

xmlerr XmlDomRangeSetStart(
   xmlctx *xctx, 
   xmlrange *range, 
   xmlnode *node, 
   ub4 offset);
ParameterIn/OutDescription
xctx
IN
XML context
range
IN
range object
node
IN
XML node
offset
IN
starting offset

Returns

(xmlerr) numeric return code


XmlDomRangeSetStartAfter()

Sets the range start point after a node. If it has a root container other than the current one, the range is collapsed to the new position. If the previous node sets the start after the end, the range is collapsed to a new position. It is assumed that the end point of the range is a valid end point.

Syntax

xmlerr XmlDomRangeSetStartAfter(
   xmlctx *xctx, 
   xmlrange *range, 
   xmlnode *node);
ParameterIn/OutDescription
xctx
IN
XML context
range
IN
range object
node
IN
XML node

Returns

(xmlerr) numeric return code


XmlDomRangeSetStartBefore()

Sets the range start point before a node. If it has a root container other than the current one, the range is collapsed to the new position with offset 0. If the previous node sets the start after the end, the range is collapsed to a new position. It is assumed that the end point of the range is a valid end point.

Syntax

xmlerr XmlDomRangeSetStartBefore(
   xmlctx *xctx, 
   xmlrange *range, 
   xmlnode *node);
ParameterIn/OutDescription
xctx
IN
XML context
range
IN
range object
node
IN
XML node

Returns

(xmlerr) numeric return code

PK\c[ PKnFJOEBPS/dcommon/blafdoc.cssc@charset "utf-8"; /* Copyright 2002, 2011, Oracle and/or its affiliates. All rights reserved. Author: Robert Crews Version: 2011.8.12 */ body { font-family: Tahoma, sans-serif; /* line-height: 125%; */ color: black; background-color: white; font-size: small; } * html body { /* http://www.info.com.ph/~etan/w3pantheon/style/modifiedsbmh.html */ font-size: x-small; /* for IE5.x/win */ f\ont-size: small; /* for other IE versions */ } h1 { font-size: 165%; font-weight: bold; border-bottom: 1px solid #ddd; width: 100%; text-align: left; } h2 { font-size: 152%; font-weight: bold; text-align: left; } h3 { font-size: 139%; font-weight: bold; text-align: left; } h4 { font-size: 126%; font-weight: bold; text-align: left; } h5 { font-size: 113%; font-weight: bold; display: inline; text-align: left; } h6 { font-size: 100%; font-weight: bold; font-style: italic; display: inline; text-align: left; } a:link { color: #039; background: inherit; } a:visited { color: #72007C; background: inherit; } a:hover { text-decoration: underline; } a img, img[usemap] { border-style: none; } code, pre, samp, tt { font-family: monospace; font-size: 110%; } caption { text-align: center; font-weight: bold; width: auto; } dt { font-weight: bold; } table { font-size: small; /* for ICEBrowser */ } td { vertical-align: top; } th { font-weight: bold; text-align: left; vertical-align: bottom; } li { text-align: left; } dd { text-align: left; } ol ol { list-style-type: lower-alpha; } ol ol ol { list-style-type: lower-roman; } td p:first-child, td pre:first-child { margin-top: 0px; margin-bottom: 0px; } table.table-border { border-collapse: collapse; border-top: 1px solid #ccc; border-left: 1px solid #ccc; } table.table-border th { padding: 0.5ex 0.25em; color: black; background-color: #f7f7ea; border-right: 1px solid #ccc; border-bottom: 1px solid #ccc; } table.table-border td { padding: 0.5ex 0.25em; border-right: 1px solid #ccc; border-bottom: 1px solid #ccc; } span.gui-object, span.gui-object-action { font-weight: bold; } span.gui-object-title { } p.horizontal-rule { width: 100%; border: solid #cc9; border-width: 0px 0px 1px 0px; margin-bottom: 4ex; } div.zz-skip-header { display: none; } td.zz-nav-header-cell { text-align: left; font-size: 95%; width: 99%; color: black; background: inherit; font-weight: normal; vertical-align: top; margin-top: 0ex; padding-top: 0ex; } a.zz-nav-header-link { font-size: 95%; } td.zz-nav-button-cell { white-space: nowrap; text-align: center; width: 1%; vertical-align: top; padding-left: 4px; padding-right: 4px; margin-top: 0ex; padding-top: 0ex; } a.zz-nav-button-link { font-size: 90%; } div.zz-nav-footer-menu { width: 100%; text-align: center; margin-top: 2ex; margin-bottom: 4ex; } p.zz-legal-notice, a.zz-legal-notice-link { font-size: 85%; /* display: none; */ /* Uncomment to hide legal notice */ } /*************************************/ /* Begin DARB Formats */ /*************************************/ .bold, .codeinlinebold, .syntaxinlinebold, .term, .glossterm, .seghead, .glossaryterm, .keyword, .msg, .msgexplankw, .msgactionkw, .notep1, .xreftitlebold { font-weight: bold; } .italic, .codeinlineitalic, .syntaxinlineitalic, .variable, .xreftitleitalic { font-style: italic; } .bolditalic, .codeinlineboldital, .syntaxinlineboldital, .titleinfigure, .titleinexample, .titleintable, .titleinequation, .xreftitleboldital { font-weight: bold; font-style: italic; } .itemizedlisttitle, .orderedlisttitle, .segmentedlisttitle, .variablelisttitle { font-weight: bold; } .bridgehead, .titleinrefsubsect3 { font-weight: bold; } .titleinrefsubsect { font-size: 126%; font-weight: bold; } .titleinrefsubsect2 { font-size: 113%; font-weight: bold; } .subhead1 { display: block; font-size: 139%; font-weight: bold; } .subhead2 { display: block; font-weight: bold; } .subhead3 { font-weight: bold; } .underline { text-decoration: underline; } .superscript { vertical-align: super; } .subscript { vertical-align: sub; } .listofeft { border: none; } .betadraft, .alphabetanotice, .revenuerecognitionnotice { color: #f00; background: inherit; } .betadraftsubtitle { text-align: center; font-weight: bold; color: #f00; background: inherit; } .comment { color: #080; background: inherit; font-weight: bold; } .copyrightlogo { text-align: center; font-size: 85%; } .tocsubheader { list-style-type: none; } table.icons td { padding-left: 6px; padding-right: 6px; } .l1ix dd, dd dl.l2ix, dd dl.l3ix { margin-top: 0ex; margin-bottom: 0ex; } div.infoboxnote, div.infoboxnotewarn, div.infoboxnotealso { margin-top: 4ex; margin-right: 10%; margin-left: 10%; margin-bottom: 4ex; padding: 0.25em; border-top: 1pt solid gray; border-bottom: 1pt solid gray; } p.notep1 { margin-top: 0px; margin-bottom: 0px; } .tahiti-highlight-example { background: #ff9; text-decoration: inherit; } .tahiti-highlight-search { background: #9cf; text-decoration: inherit; } .tahiti-sidebar-heading { font-size: 110%; margin-bottom: 0px; padding-bottom: 0px; } /*************************************/ /* End DARB Formats */ /*************************************/ @media all { /* * * { line-height: 120%; } */ dd { margin-bottom: 2ex; } dl:first-child { margin-top: 2ex; } } @media print { body { font-size: 11pt; padding: 0px !important; } a:link, a:visited { color: black; background: inherit; } code, pre, samp, tt { font-size: 10pt; } #nav, #search_this_book, #comment_form, #comment_announcement, #flipNav, .noprint { display: none !important; } body#left-nav-present { overflow: visible !important; } } PKr.hcPKnFJOEBPS/dcommon/oracle.gifJGIF87aiyDT2F'G;Q_oKTC[ 3-Bq{ttsoGc4I)GvmLZ).1)!ꑈ53=Z]'yuLG*)g^!8C?-6(29K"Ĩ0Яl;U+K9^u2,@@ (\Ȱ Ë $P`lj 8x I$4H *(@͉0dа8tA  DсSP v"TUH PhP"Y1bxDǕ̧_=$I /& .)+ 60D)bB~=0#'& *D+l1MG CL1&+D`.1qVG ( "D2QL,p.;u. |r$p+5qBNl<TzB"\9e0u )@D,¹ 2@C~KU 'L6a9 /;<`P!D#Tal6XTYhn[p]݅ 7}B a&AƮe{EɲƮiEp#G}D#xTIzGFǂEc^q}) Y# (tۮNeGL*@/%UB:&k0{ &SdDnBQ^("@q #` @1B4i@ aNȅ@[\B >e007V[N(vpyFe Gb/&|aHZj@""~ӎ)t ? $ EQ.սJ$C,l]A `8A o B C?8cyA @Nz|`:`~7-G|yQ AqA6OzPbZ`>~#8=./edGA2nrBYR@ W h'j4p'!k 00 MT RNF6̙ m` (7%ꑀ;PKl-OJPKnFJOEBPS/dcommon/cpyr.htmd Oracle Legal Notices

Oracle Legal Notices

Copyright Notice

Copyright © 1994-2017, Oracle and/or its affiliates. All rights reserved.

License Restrictions Warranty/Consequential Damages Disclaimer

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

Warranty Disclaimer

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

Restricted Rights Notice

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, then the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.

Hazardous Applications Notice

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.

Trademark Notice

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

Third-Party Content, Products, and Services Disclaimer

This software or hardware and documentation may provide access to or information about content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services unless otherwise set forth in an applicable agreement between you and Oracle. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services, except as set forth in an applicable agreement between you and Oracle.

Alpha and Beta Draft Documentation Notice

If this document is in preproduction status:

This documentation is in preproduction status and is intended for demonstration and preliminary use only. It may not be specific to the hardware on which you are using the software. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to this documentation and will not be responsible for any loss, costs, or damages incurred due to the use of this documentation.

Private Alpha and Beta Draft Documentation Notice

If this document is in private preproduction status:

The information contained in this document is for informational sharing purposes only and should be considered in your capacity as a customer advisory board member or pursuant to your beta trial agreement only. It is not a commitment to deliver any material, code, or functionality, and should not be relied upon in making purchasing decisions. The development, release, and timing of any features or functionality described in this document remains at the sole discretion of Oracle.

This document in any form, software or printed matter, contains proprietary information that is the exclusive property of Oracle. Your access to and use of this confidential material is subject to the terms and conditions of your Oracle Master Agreement, Oracle License and Services Agreement, Oracle PartnerNetwork Agreement, Oracle distribution agreement, or other license agreement which has been executed by you and Oracle and with which you agree to comply. This document and information contained herein may not be disclosed, copied, reproduced, or distributed to anyone outside Oracle without prior written consent of Oracle. This document is not part of your license agreement nor can it be incorporated into any contractual agreement with Oracle or its subsidiaries or affiliates.

Documentation Accessibility

For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.

Access to Oracle Support

Oracle customers that have purchased support have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.

Oracle Logo

PKKPKnFJOEBPS/dcommon/oracle-logo.jpgqvJFIFC    $.' ",#(7),01444'9=82<.342C  2!!22222222222222222222222222222222222222222222222222'7" }!1AQa"q2#BR$3br %&'()*456789:CDEFGHIJSTUVWXYZcdefghijstuvwxyz w!1AQaq"2B #3Rbr $4%&'()*56789:CDEFGHIJSTUVWXYZcdefghijstuvwxyz ?( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( (QEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQE!KEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEzE7V%ȣOΏ9??:a"\fSrğjAsKJ:nOzO=}E1-I)3(QEQEQEQEQEQEQE֝Hza<["2"pO#f8M[RL(,?g93QSZ uy"lx4h`O!LŏʨXZvq& c՚]+: ǵ@+J]tQ]~[[eϸ (]6A&>ܫ~+כzmZ^(<57KsHf妬Ϧmnẁ&F!:-`b\/(tF*Bֳ ~V{WxxfCnMvF=;5_,6%S>}cQQjsOO5=)Ot [W9 /{^tyNg#ЄGsֿ1-4ooTZ?K Gc+oyڙoNuh^iSo5{\ܹ3Yos}$.nQ-~n,-zr~-|K4R"8a{]^;I<ȤL5"EԤP7_j>OoK;*U.at*K[fym3ii^#wcC'IIkIp$󿉵|CtĈpW¹l{9>⪦׺*ͯj.LfGߍԁw] |WW18>w.ӯ! VӃ :#1~ +މ=;5c__b@W@ +^]ևՃ7 n&g2I8Lw7uҭ$"&"b eZ":8)D'%{}5{; w]iu;_dLʳ4R-,2H6>½HLKܹR ~foZKZ࿷1[oZ7׫Z7R¢?«'y?A}C_iG5s_~^ J5?œ tp]X/c'r%eܺA|4ծ-Ե+ْe1M38Ǯ `|Kյ OVڅu;"d56, X5kYR<̭CiطXԮ];Oy)OcWj֩}=܅s۸QZ*<~%뺃ȶp f~Bðzb\ݳzW*y{=[ C/Ak oXCkt_s}{'y?AmCjޓ{ WRV7r. g~Q"7&͹+c<=,dJ1V߁=T)TR՜*N4 ^Bڥ%B+=@fE5ka}ędܤFH^i1k\Sgdk> ֤aOM\_\T)8靠㡮3ģR: jj,pk/K!t,=ϯZ6(((((((49 xn_kLk&f9sK`zx{{y8H 8b4>ÇНE|7v(z/]k7IxM}8!ycZRQ pKVr(RPEr?^}'ðh{x+ՀLW154cK@Ng C)rr9+c:׹b Жf*s^ fKS7^} *{zq_@8# pF~ [VPe(nw0MW=3#kȵz晨cy PpG#W:%drMh]3HH<\]ԁ|_W HHҡb}P>k {ZErxMX@8C&qskLۙOnO^sCk7ql2XCw5VG.S~H8=(s1~cV5z %v|U2QF=NoW]ո?<`~׮}=ӬfԵ,=;"~Iy7K#g{ñJ?5$y` zz@-~m7mG宝Gٱ>G&K#]؃y1$$t>wqjstX.b̐{Wej)Dxfc:8)=$y|L`xV8ߙ~E)HkwW$J0uʟk>6Sgp~;4֌W+חc"=|ř9bc5> *rg {~cj1rnI#G|8v4wĿhFb><^ pJLm[Dl1;Vx5IZ:1*p)إ1ZbAK(1ׅ|S&5{^ KG^5r>;X׻K^? s fk^8O/"J)3K]N)iL?5!ƾq:G_=X- i,vi2N3 |03Qas ! 7}kZU781M,->e;@Qz T(GK(ah(((((((Y[×j2F}o־oYYq $+]%$ v^rϭ`nax,ZEuWSܽ,g%~"MrsrY~Ҿ"Fت;8{ѰxYEfP^;WPwqbB:c?zp<7;SBfZ)dϛ; 7s^>}⍱x?Bix^#hf,*P9S{w[]GF?1Z_nG~]kk)9Sc5Ո<<6J-ϛ}xUi>ux#ţc'{ᛲq?Oo?x&mѱ'#^t)ϲbb0 F«kIVmVsv@}kҡ!ˍUTtxO̧]ORb|2yԵk܊{sPIc_?ħ:Ig)=Z~' "\M2VSSMyLsl⺿U~"C7\hz_ Rs$~? TAi<lO*>U}+'f>7_K N s8g1^CeКÿE ;{+Y\ O5|Y{/o+ LVcO;7Zx-Ek&dpzbӱ+TaB0gNy׭ 3^c T\$⫫?F33?t._Q~Nln:U/Ceb1-im WʸQM+VpafR3d׫é|Aү-q*I P7:y&]hX^Fbtpܩ?|Wu󭏤ʫxJ3ߴm"(uqA}j.+?S wV ~ [B&<^U?rϜ_OH\'.;|.%pw/ZZG'1j(#0UT` Wzw}>_*9m>󑓀F?EL3"zpubzΕ$+0܉&3zڶ+jyr1QE ( ( ( ( ( ( ( (UIdC0EZm+]Y6^![ ԯsmܶ捆?+me+ZE29)B[;я*wGxsK7;5w)}gH~.Ɣx?X\ߚ}A@tQ(:ͧ|Iq(CT?v[sKG+*רqҍck <#Ljα5݈`8cXP6T5i.K!xX*p&ќZǓϘ7 *oƽ:wlຈ:Q5yIEA/2*2jAҐe}k%K$N9R2?7ýKMV!{W9\PA+c4w` Wx=Ze\X{}yXI Ү!aOÎ{]Qx)#D@9E:*NJ}b|Z>_k7:d$z >&Vv󃏽WlR:RqJfGإd9Tm(ҝEtO}1O[xxEYt8,3v bFF )ǙrPNE8=O#V*Cc𹾾&l&cmCh<.P{ʦ&ۣY+Gxs~k5$> ӥPquŽўZt~Tl>Q.g> %k#ú:Kn'&{[yWQGqF}AЅ׮/}<;VYZa$wQg!$;_ $NKS}“_{MY|w7G!"\JtRy+贾d|o/;5jz_6fHwk<ѰJ#]kAȎ J =YNu%dxRwwbEQEQEQEQEQEQEQEQEQE'fLQZ(1F)hQ@X1KEQE-Q@ 1KE3h=iPb(((1GjZ(-ʹRPbR@ 1KE7`bڒyS0(-&)P+ ڎԴP11F)h&:LRmQ@Q@Š(((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((,RmuM. I-nBvskƭON%I4/# WW@|i9Q3|뜨9>~.y8en'Qf A QEQEW|@ֶ>GDu39((:c:u}oc?hn#u˫nPpr=E{Q@Q@Q@Q@Q@Q@W#['/.ln~As3G7!F獹9p@; +g|xGo[89= :4e/u^'a!8FF8U$$(cPAEyŸ\εoVoo*13rŝ{~*M6h%Kkݘ1w\ Aր= Ȃ-NVF9FU,ʹ=Y_+xmm常8` $Q@$Ww?n+>kIyy;w\n33_KEykk~ydG\31޽B ( *9[cHU I9xUO˭#ΏZÔU[ 8 !ـ Q^?'m<~9ٟ%q^GZ k\׮5IkVsLMld3z%Q@WXxNҮtk3 ,$ x-h%@WR2#5]JmºnVS\FT!`8Ex?%|Zv%9L,10j>9Fvyd#3$~ONowo ltݞGց1ߦӨ xk6:/d@^7o#NO^/iO_@P__]}Lf[(l}Ew-AM|I]%4<ݰنv.`9MlM&.4χXeEMrT,dS.o jѠe9TDPa\h<X|a; z y-\Q07)#u?Oռ;6>V\HsqyVOs"h%K$92x 1@v> ;8s&=6'A DȘnO  G࿈#W<ɧ+ @.¦X ȎG~` gW]F\6>aY${'^85x d UwMǡ>W#q-V ,q2= hD(@.ddJoM4k7gO8o3>^GzOg.@%X:r23@?5;I YopeAbqX6Wzՙ/Y `I۸`$⸍S&dX\3h3ohN# l89 En}g&;0)O]Rp r@ƞ,W|$0H Ĝd pqI:sP4$B֐X+8!@ml >kUi[ [] v()# 3{n>+{~"@\`8cZ?O ?qp"LfCV#,K!!.`+,/=:O2$F` FAkR]˽:Tv[7]\`ꣵzGQÍ'Iխ}E_n靇*H<x4QEf_|[H|/z-pC'%jka[n<(LWrH'{! Q5}]v PI%US$#Gs3/tԾרIʯ@c ͻbih3OjiO_@PEPZibiKaTE'wDc<KO!%7MHr|NH=(oxR`5!h*!_nB5ruU9Kˏly  #|Ođj(<-ב $@w(Sn]A>/34k =w˵!>rvdNh?(o>Hޒc :1 LTm\d*E5xi>yey+ZژPAu?#;y_]覠?jEE]lge$Lbd<#0&sq^!Uc[7P봒H*3*q)T@:v4 [ٰrOt84:4nYdtS"VbB/a}cܓ޹p5+Jh> ۙ%,IW,ZPQEQEQEQEQEQEQEQEQEx$O*Z<O %ѡ-2$KJ AWIO h.ӣ,keO5À@9BF?rнrdwl0j/2k'dPQy99x~Ky~%x9-^TlQQgv䲢de+n<σ NHiGWs.0ֺOJ-N i$yUDdn*Fzg+gum. $[/fFCYV-BLmQwD,9;I2cu x76luK4 iuy#`p>}(ï^k$#9\qYI<)?@HRW~!|/Mjm"񬮋wTݎdxgׄu;;kc}H_ Qtzw]ɍ<@jqC)#|Or#rt9Ҽ3$/|yx:-jT1OfC$1%T6o |>war#s«j4xsȫVRۈi.8z 6&o9ny'42`K`Hd +t$5Wq{ÚlZ; ZbM*Vb ݝ7T_?#yhOt:̌;Aln;b#Ծ'x#JY;#Ð< d9rO^㎽kmmⷷ8`GjQ@P@񍿁%sK\6aa$I@# '8^^<R nE@NN\ 2q(:Sn~"kVup7;YdQJMl|w -yԴȏ Cڮl$dv +{x$qơU 8I@x_2M͆ql|Nq0n|/J޽cGw_돬WدxfUB^s5_w[ vc:Eٱ˯)y,x+𾣡6(nQ qqq ~[=oSѺa o`ۈOs^E|M̭oF ~Ig;Wt'$ڭo/w y3ס*R_?^ۏ9G)//Lt}oloydIvg8q+ǂ|;`icV;Inv8]r:uƐGںi,gRvpH~);O.Mmoq"a *p0"OWx{e~|Gok:]tC4A0 8@Ambv@TOjxM,g:E-ѕ/G]7a9"<;x:.fu$0 ޻K =2;; H--c`FIŽI' ^LӮo$mby}EҬU=WKִ6${K*$e7!d MDψc}JDf|* :.{? SCt?MX߅oXhvdS3'e'ʶ(:x"Cxr=2{;o<))Xcv2K<^5]rvGw\L帉æHq28UҬu.LM0Ar`Ӽ!^흤Β#5Į60K1*OI=I4C²訫+~Ѽ#IaIL̞kɗ r䞊?*ؠY' _~Ҵ+Ҽ7:~)b, ((((((((((oƾ5|Cj] nj6NQ!\4w߈{S<[p--$gM/* RIl9 ( (sY{߾[HW:*X3 Pzoo,mW ]Bn4\uk4/Ѭe! Ak9TޣlhQ@Q@Q@Q@Q@Q@Q@Q@Q@Q@W?Oxk>X5x-$aI!8m mH݌dc9CmYjIuv 8Un_pSy\xP}gYywx4r@c ~5Xy_fԷw-Jx3s2V?IgZk:kHꧽlPEPEPEPEPEPEPEPEPEPEPEPEPEPEPEPEPEPO4 @' *E-y$O*Z?i,7[Cw1v̪3h4  -7+%/ckapXc08\{) ƳCq"P΁$'ϓjڧզ,HqӇp1nN!($ qUE81@&hoZ$n r~'|mmN1XG zC*6dȮƺmǭW^\wpiw[Aj FY#0z4w߈tckۭ*M:K֬ўq(Wp eR `g>D?u~r={*.|kׇ|C.ŵѺE#3yN@U ^InQyÿ$| 5]Z7eMWcDÂHzW:/t%_d6xH@KIoQ%yGYKxKbC39w;*Lf:?|ZGRb$`C*${!d灾-u3hz?lB9HX>bH ;^a?>z=;;Dk mFsx_kcg|y^*}cvzv7۪x =?^<ŋu͟ص{hKG2 N>_Ӝ0[v'>m_WʷUswcH?Y>:8~Euۀz=h5 On|ܠ&Ź 6мt?3sl[Ld_m!xmEfnV2"i-ȭ ǫ- ^=C" F>\ecʒ՘wr8 +{x$qơU 8I@'>m_WʷUswcH>"Y/<H^#QlfAr+w@tHK˄8vnGkoH8㶅U (//m1}}YC !0pI!I ω~ŦjQjw[UQ)ޣk w/wt;<˫>ihROJآ(=KuյMmŲy#[+c2-웶aʐG  yŭ G>'J}"ߋvd5KIoQ%zy/$:DxRF𮯪[m=,X2=Eyߋ0\Zx# []K¯$%6$U|)yj~"^ 2Q_X>'z|8ʜ+ٻFOj{vF8~yڼq^h~!tkwDF\8 |My_߿6{@f_kWQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEw?±k< $_ KY O<|78G]ܿsں Lwm"v߱N3&<|;_+k)QnvR@Mۇ̌A9 :YCei̼8I?0k)=krSӮl/#-nxfMnF0dҸ/>}H?ln֦/.A>cG qm7+_:MRk͐L09'n%@r>Ş мk-i[#aUprp+'imtz͆ dW5,N>YT$({ ’<ϲ%fm-;U`Oj6!J#~?OOZƵY«)Æ.@'p1=g1 /}^_3nFs{?KIoQ%y!7>>h0HB:"UA wC}>;:>_3Wtw'ݎ#:[iՌwvbTYH*z8$t&4 x-h%@WR2#4M<6yc v 3Qr;xu-)ß+Ow-1;K'v09jO jjܾ.J+}x$](_Ht/x҉+?1ϱm"vz<C!c}e?y{Hrqڀ+ENJ=bh0>wFY9 B3Ϟ'<xMC!;tr9y h^#[Xn'5(햙*eNn ʕ;ɠHdX}%hl7p{{׏gWV|TfT)$r$` 1^iѦ[fuf UWjv#?_@W² _w޽>?R|{|UKW /ʲ,y1y² _w޻MWJ43S6Ka (ҵ[sK˘l|RFr<8"I<0),"V` _SXv#[񞫠Z`oЕn#NkS¿ &|YoMkŚZ!KfJm䏜\q/_xo69Rd򬱻KplLcg^E{]\sgp:0`AAjUiw6w X8 A^W7%=W@-ϒ 7+*`G<O<6\K0DF dOjJmZ>9u"FʴlH #H0@3Tzl(G$5[u['g.]3g rvz&)p_ fa6gE{EQ\x>->ydq'z|n?Vx}-bQQ}q}&kWy#w.3d`F:<-Ě5;zkS6Ke̬8$zEy$:Dujsj:5ܖs[w1t,@qA9:uw|Ig;U$FeL8 €:_Ht/x҉+tjzO[o7nЮdg2+~LvikvC2FI‰2I?zg6X\]y=qIs&wLʠ9$䑞S@'<-WMMn(%^C,U;F308oe?}^4XGxŬ o|΁ uHx(((((((((((((((jnnic8EeK` cY?0TQT[MmK-/W(Z̲lTq*QEQ\ߍ|kFT nV1VḷCҀ:J*C:Ȱ^q`8$g(((((((ƯXHQ# *$`s@W7@"<L"N9f@{]gvgdH$F P}aggiݬ ASb!($ qUE81RQ\~Gs{=:k3aM+rX1Ð)矻vQYztmMoM:ut1\3hR ặXTeu# 8 sRPEW,伿d7N<ϲ\$3gi8_C@QEy}g=ڟ.2Ɓ*|H Ma1YWsݎqzoů m tn4zg=} vQ\~#tmjaϗw #Ƹ 6IœN@(((((((((((((((h'cRՏ &B.y7;FdҫO4 M3Z̟duC q<~w<w%G&i,>}/y2 }IԡtkRdX/m㸍d0WP3k> 0k<mXRʭC2@Qw:l:6c۴v*p=G_ವ\>7 ڣ6ŒyWa$gDr,vp P+B%u,<;y8p $nymƃpt5 Ed6unlNF9ɠ OxB]8/c_7!.vd #;IaXTG7ݍޓpM>@v0mO4 @' *E-GxsF8);Hy᱄Js"kRFGj #AeCq"bbH >&/j3]pVBFYrQT&I UHho]GjQs=XE3P3h7 ڣ6ŒyWa$gDr,vp P+B%u,<;y8p $nymƃpt5 Ed6unlNF9ɠ OxB]8/c_7!.vd #د#AiJI|&Dhc auYp6B > O^"{/6(  ?! ['9z|8Vg%Ғ7L xtNǞ+>}zK.1!!G倌'^~yxU^^W=v8?$ !cG(-V #[͂MΠv%!\ CwqbVw%, 6<0sڔhqq-ñphU@ĭ;Lӭ,mbHaME(ր0kYaCw@nԐõ< 0eMxşmn]M#k0` q8^q}'^?G<+=O<5`_W?O'UZ(~R^GxWu<I*d}8_e?}_?̿4ۧ֠(+1G.BJ E6$ Fz zE0GowX:~?'AnC7e89oyECGI y]DNpI<0En|ao XZmu[$d JH `|q M^ϕ2F0X81x+PQ;?xMw_Ee?|~0,'v{V7~Ciq$fIw&*6|rNqS~{I/2~-9*캂W9Ԁ(.l_F/t'H`#u$`c нr|4W7s;IwO. X,Um#*s)y|`Η>CxrWE-,UPJng _ %G|wy{9xKm7Zи}JaЫ)OQGד*ox3^wqc$z)Iv|(HSJzåu:GKxRm2vG'\dRB?[4׷ݠpΨe#c)A0XIy B³#'#Ե&öNS*p|0Ұg# ؇+J}3L6EtQ'$$kόoil$prI9$I$]'~#ľҬK m_ƀ="( ٥Ѵ QZ?"[wRN*1<{{e[_ZDBH܌S#s|./AmyMi5=+m.$/2@FߐuϖNI=2yV?-zGn5O](/uux' #6Ie軏Qǚ4:^=6"[k[Ջe; aoJ?<RA^'tmK~Y[oI:*3+(f_kWYkao'Oċk,g1㒸=W _ [ /]M/\oW+Ѧe X`bڸc~w{=y?7uoB徏Km{3]W3e4#֮[Bx&9nFBW?[|OG$_:DeYWaF m:O csÉ7G"SpA׏C/$Wa]G7oFvyd#3~q#zu={v|S-~K 1) collapsible = false; for (var k = 0; k < p.length; k++) { if ( getTextContent(p[k]).split(" ").length > 12 ) collapsible = false; c.push(p[k]); } } if (collapsible) { for (var j = 0; j < c.length; j++) { c[j].style.margin = "0"; } } } function getTextContent(e) { if (e.textContent) return e.textContent; if (e.innerText) return e.innerText; } } addLoadEvent(compactLists); function processIndex() { try { if (!/\/index.htm(?:|#.*)$/.test(window.location.href)) return false; } catch(e) {} var shortcut = []; lastPrefix = ""; var dd = document.getElementsByTagName("dd"); for (var i = 0; i < dd.length; i++) { if (dd[i].className != 'l1ix') continue; var prefix = getTextContent(dd[i]).substring(0, 2).toUpperCase(); if (!prefix.match(/^([A-Z0-9]{2})/)) continue; if (prefix == lastPrefix) continue; dd[i].id = prefix; var s = document.createElement("a"); s.href = "#" + prefix; s.appendChild(document.createTextNode(prefix)); shortcut.push(s); lastPrefix = prefix; } var h2 = document.getElementsByTagName("h2"); for (var i = 0; i < h2.length; i++) { var nav = document.createElement("div"); nav.style.position = "relative"; nav.style.top = "-1.5ex"; nav.style.left = "1.5em"; nav.style.width = "90%"; while (shortcut[0] && shortcut[0].toString().charAt(shortcut[0].toString().length - 2) == getTextContent(h2[i])) { nav.appendChild(shortcut.shift()); nav.appendChild(document.createTextNode("\u00A0 ")); } h2[i].parentNode.insertBefore(nav, h2[i].nextSibling); } function getTextContent(e) { if (e.textContent) return e.textContent; if (e.innerText) return e.innerText; } } addLoadEvent(processIndex); PKo"nR M PKnFJ OEBPS/loe.htmT List of Examples PKPKnFJOEBPS/schema.htm Package Schema APIs for C

8 Package Schema APIs for C

This C implementation of the XML schema validator follows the W3C XML Schema specification, rev REC-xmlschema-1-20010502. It implements the required behavior of a schema validator for multiple schema documents to be assembled into a schema. This resulting schema can be used to validate a specific instance document.

For event-based schema validation, see the methods documented in Chapter 4, "Package Event APIs for C".

This chapter contains the following section:


Schema Interface

Table 8-1 summarizes the methods available through the Schema interface.

Table 8-1 Summary of Schema Methods

FunctionSummary

XmlSchemaClean()


Cleans up loaded schemas in a schema context and recycle the schema context.

XmlSchemaCreate()


Creates and returns a schema context.

XmlSchemaDestroy()


Destroys a schema context.

XmlSchemaErrorWhere()


Returns the location where an error occurred.

XmlSchemaLoad()


Loads a schema document.

XmlSchemaLoadedList()


Returns the size and/or list of loaded schema documents.

XmlSchemaSetErrorHandler()


Sets an error message handler and its associated context in a schema context

XmlSchemaSetValidateOptions()


Sets option(s) to be used in the next validation session.

XmlSchemaTargetNamespace()


Returns target namespace of a given schema document.

XmlSchemaUnload()


Unloads a schema document.

XmlSchemaValidate()


Validates an element node against a schema.

XmlSchemaVersion()


Returns the version of this schema implementation.



XmlSchemaClean()

Clean up loaded schemas in a schema context and recycle the schema context.

Syntax

void XmlSchemaClean(
   xsdctx *sctx);
ParameterIn/OutDescription
sctx
IN
schema context to be cleaned


XmlSchemaCreate()

Return a schema context to be used in other validator APIs. This needs to be paired with an XmlSchemaDestroy.

Syntax

xsdctx *XmlSchemaCreate(
   xmlctx *xctx, 
   xmlerr *err, 
   list);
ParameterIn/OutDescription
xctx
IN
XML context
err
OUT
returned error code
list
IN
NULL-terminated list of variable arguments

Returns

(xsdctx *) schema context


XmlSchemaDestroy()

Destroy a schema context and free up all its resources.

Syntax

void XmlSchemaDestroy(
   xsdctx *sctx);
ParameterIn/OutDescription
sctx
IN
schema context to be freed


See Also:

XmlSchemaCreate()


XmlSchemaErrorWhere()

Returns the location (line#, path) where an error occurred.

Syntax

xmlerr XmlSchemaErrorWhere(
   xsdctx *sctx, 
   ub4 *line, 
   oratext **path);
ParameterIn/OutDescription
sctx
IN
schema context
line
IN/OUT
line number where error occurred
path
IN/OUT
URL or filespace where error occurred

Returns

(xmlerr) error code


XmlSchemaLoad()

Load up a schema document to be used in the next validation session. Schema documents can be incrementally loaded into a schema context as long as every loaded schema document is valid. When the last loaded schema turns out to be invalid, you need to clean up the schema context by calling XmlSchemaClean() and reload everything all over again including the last schema with appropriate correction.

Given a schema document, this function converts the DOM representation into an internal schema representation. The schema document can be provided as a URI or directly a DOM representation. In the URI case, this function reads the input stream and builds a DOM representation of the schema before converting it into internal representation. In the DOM case, the application can provide a DOM representation of the schema, which will be used to create the internal schema representation.

Syntax

xmlerr XmlSchemaLoad(
   xsdctx *sctx, 
   oratext *uri, 
   list);
ParameterIn/OutDescription
sxctx
IN
schema context
uri
IN
URL of schema document; compiler encoding
list
IN
NULL-terminated list of variable arguments

Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success


XmlSchemaLoadedList()

Return only the size of loaded schema documents if list is NULL. If list is not NULL, a list of URL pointers are returned in the user-provided pointer buffer. Note that its user's responsibility to provide a buffer with big enough size.

Syntax

ub4 XmlSchemaLoadedList(
   xsdctx *sctx, 
   oratext **list);
ParameterIn/OutDescription
sctx
IN
schema context
list
IN
address of pointer buffer

Returns

(ub4) list size


XmlSchemaSetErrorHandler()

Sets an error message handler and its associated context in a schema context. To retrieve useful location information on errors, the address of the schema context must be provided in the error handler context.

Syntax

xmlerr XmlSchemaSetErrorHandler(
   xsdctx *sctx, 
   XML_ERRMSG_F(
      (*errhdl), 
      ectx, 
      msg, 
      err), 
   void *errctx);
ParameterIn/OutDescription
sctx
IN
schema context
errhdl
IN
error message handler
errctx
IN
error handler context

Returns

(xmlerr) error code


XmlSchemaSetValidateOptions()

Set options to be used in the next validation session. Previously set options will remain effective until they are overwritten or reset.

Syntax

xmlerr XmlSchemaSetValidateOptions(
   xsdctx *sctx, 
   list);
ParameterIn/OutDescription
sctx
IN
schema context
list
IN
NULL-terminated list of variable argument

Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success


XmlSchemaTargetNamespace()

Return target namespace of a given schema document identified by its URI. All currently loaded schema documents can be queried. Currently loaded schema documents include the ones loaded through XmlSchemaLoads and the ones loaded through schemaLocation or noNamespaceSchemaLocation hints.

Syntax

oratext *XmlSchemaTargetNamespace(
   xsdctx *sctx, 
   oratext *uri);
ParameterIn/OutDescription
sctx
IN
XML context
uri
IN
URL of the schema document to be queried

Returns

(oratext *) target namespace string; NULL if given document not


XmlSchemaUnload()

Unload a schema document from the validator. All previously loaded schema documents will remain loaded until they are unloaded. To unload all loaded schema documents, set URI to be NULL (this is equivalent to XmlSchemaClean). Note that all children schemas associated with the given schema are also unloaded. In this implementation, it only support the following scenarios:

  • load, load, ...

  • load, load, load, unload, unload, unload, clean, and then repeat.

It doesn't not support: load, load, unload, load, ....

Syntax

xmlerr XmlSchemaUnload(
   xsdctx *sctx, 
   oratext *uri, 
   list);
ParameterIn/OutDescription
sctx
IN
schema context
uri
IN
URL of the schema document; compiler encoding
list
IN
NULL-terminated list of variable argument

Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success


XmlSchemaValidate()

Validates an element node against a schema. Schemas used in current session consists of all schema documents specified through XmlSchemaLoad and provided as hint(s) through schemaLocation or noNamespaceSchemaLocation in the instance document. After the invocation of this routine, all loaded schema documents remain loaded and can be queried by XmlSchemaLoadedList. However, they will remain inactive. In the next validation session, inactive schema documents can be activated by specifying them through XmlSchemaLoad or providing them as hint(s) through schemaLocation or noNamespaceSchemaLocation in the new instance document. To unload a schema document and all its descendants (documents included or imported in a nested manner), use XmlSchemaUnload.

Syntax

xmlerr XmlSchemaValidate(
   xsdctx *sctx,
   xmlctx *xctx, 
   xmlelemnode *elem);
ParameterIn/OutDescription
sctx
IN
schema context
xctx
IN
XML top-level context
elem
IN
element node in the doc, to be validated

Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success


XmlSchemaVersion()

Return the version of this schema implementation.

Syntax

oratext *XmlSchemaVersion();

Returns

(oratext *) version string [compiler encoding]

PKt\PKnFJOEBPS/whatsnew.htm, What's New in the XML C APIs?

What's New in the XML C APIs?

This section describes new features in Oracle Database XML C API Reference and supplies pointers to additional information.

New Features for Oracle Database 11g Release 2 (11.2)

The following features are new to the Oracle Database 11g Release 2:

Orastream Interface

The orastream package handles large (over 64K) text and binary nodes in XML documents.

Information about this feature is in Chapter Chapter 5, "Package Orastream APIs for C" . Additionally, these new datatypes have been documented in Chapter 1, "Datatypes for C":

New Features for Oracle Database 11g Release 1 (11.1)

The following features are new to the Oracle Database 11g Release 1:

DOM Stream Access to XML Nodes and Attributes

Information about this feature is in the chapter Chapter 3, "Package DOM APIs for C". In includes support for the following functions:

Node Management

The following functions update the name of the specified node.

XML Diff Support

Information about this feature is in the new Chapter 12, "Package XmlDiff APIs for C". It includes support for the following functions:

Event-based XML Pull Parsing and Scalable and High Performance XML Validation

Information about this feature is in the new Chapter 4, "Package Event APIs for C".

PKb1,PKnFJ OEBPS/xml.htm Package XML APIs for C

11 Package XML APIs for C

This C implementation of the XML processor (or parser) follows the W3C XML specification (rev REC-xml-19980210) and implements the required behavior of an XML processor in terms of how it must read XML data and the information it must provide to the application.

This chapter contains the following section:


XML Interface

Table 11-1 summarizes the methods available through the XML interface.

Table 11-1 Summary of XML Methods

FunctionSummary

XmlAccess()


Set access method callbacks for URL.

XmlCreate()


Create an XML Developer's Toolkit xmlctx.

XmlCreateDTD()


Create DTD.

XmlCreateDocument()


Create Document (node).

XmlDestroy()


Destroy an xmlctx.

XmlDiff()


Compares two XML documents.

XmlFreeDocument()


Free a document (releases all resources).

XmlGetEncoding()


Returns data encoding in use by XML context.

XmlHasFeature()


Determine if DOM feature is implemented.

XmlIsSimple()


Returns single-byte (simple) characterset flag.

XmlIsUnicode()


Returns XmlIsUnicode (simple) characterset flag.

XmlLoadDom()


Load (parse) an XML document and produce a DOM.

XmlLoadSax()


Load (parse) an XML document from and produce SAX events.

XmlLoadSaxVA()


Load (parse) an XML document from and produce SAX events [varargs].

XmlSaveDom()


Saves (serializes, formats) an XML document.

XmlVersion()


Returns version string for XDK.



XmlAccess()

Sets the open/read/close callbacks used to load data for a specific URL access method. Overrides the built-in data loading functions for HTTP, FTP, and so on, or provides functions to handle new types, such as UNKNOWN.

Syntax

xmlerr XmlAccess(
   xmlctx *xctx, 
   xmlurlacc access, 
   void *userctx,
   XML_ACCESS_OPEN_F(
      (*openf),
      ctx,
      uri,
      parts,
      length,
      uh),
   XML_ACCESS_READ_F(
      (*readf),
      ctx,
      uh,
      data,
      nraw,
      eoi),
   XML_ACCESS_CLOSE_F(
      (*closef), 
      ctx,
      uh));
ParameterIn/OutDescription
xctx
IN
XML context
access
IN
URL access method
userctx
IN
user-defined context passed to callbacks
openf
IN
open-access callback function
readf
IN
read-access callback function
closef
IN
close-access callback function

Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success


XmlCreate()

Create an XML Developer's Toolkit xmlctx.

Syntax

xmlctx *XmlCreate(
   xmlerr *err, 
   oratext *name,
   list);
ParameterIn/OutDescription
err
OUT
returned error code
access
IN
name of context, for debugging
list
IN
NULL-terminated list of variable arguments. Properties common to all xmlctx's, both XDK and XMLType, are:
  • data_encoding is the data encoding in which XML data will be presented through DOM and SAX. Default is UTF-8 and UTF-E on EBCDIC platforms. Single-byte encodings are substantially faster than multibyte encodings; Unicode (UTF-16) uses more memory but has better performance than multibyte.

  • default_input_encoding is the default input encoding). If the encoding of an input document cannot be automatically determined through other methods, this encoding will be the default.

  • error_language is the language (and optional encoding) in which error messages are created. Default is American with UTF-8 encoding. To specify only the language, give the name of the language ("American"). To also specify the encoding, add the period and the Oracle name of the encoding ("American.WE8ISO8859P1").

  • error_handler is the function pointer; see XML_ERRMSG_F. By default, errors output the formatted message to stderr. If an error handler is provided, message will be passed to it, and not printed.

  • error_context is user-defined context for error handler, a context pointer to be passed to the error handler function. It is user-defined; it is just specified here and passed along when an error occurs.

  • input_encoding is the name of a forced input encoding for input documents. Use it to override a document's XMLDecl, and always interpret it in the given encoding. It should be not necessary in normal use, as existing BOMs and XMLDecls should be correct.

  • memory_alloc is a low-level memory allocation function, if not using malloc. If used, the matching free function must also be given. See XML_ALLOC_F.

  • memory_free is a low-level memory freeing function, if not using free. Matches the memory_alloc function.

  • memory_context is a user-defined memory context passed to the alloc and free functions. Its definition and use is entirely up to the user; it is just set here and passed to the callbacks.

The XDK has additional properties:

  • input_buffer_size is the basic I/O buffer size. Default is 256K; the range is 4K to 4MB. Depending on the encoding, 1, 2 or 3 of these buffers may be needed. Note that size is in characters, not bytes. If the buffer holds Unicode data, it will be twice as large.

  • memory_block_size is the size of chunk the high-level memory package will request from the low-level allocator; it is the basic unit of memory allocation. Default is 64K; the range is 16K to 256K.

These optional parameters should be used in the following manner:

xmlctx *XmlCreate(
   xmlerr *err, 
   oratext *name,
   ("data_encoding", dataEncoding),
   ("default_data_encoding", defaultDataEncoding),
   ("error_language", errorLanguage),
   ("error_handler", errorHandler),
   ("error_context", errorContext)
   ("input_encoding", inputEncoding),
   ("memory_alloc", memAlloc),
   ("memory_free", memFree),
   ("memory_context", memContext),
   ("input_buffer_seize", inputBufSize),
   ("memory_block_size", memBlockSize) );

Returns

(xmlctx *) created xmlctx [or NULL on error with err set]


XmlCreateDTD()

Create DTD.

Syntax

xmldocnode* XmlCreateDTD(
   xmlctx *xctx
   oratext *qname,
   oratext *pubid,
   oratext *sysid,
   xmlerr *err);
ParameterIn/OutDescription
xctx
IN
XML context
qname
IN
qualified name
pubid
IN
external subset public identifier
sysid
IN
external subset system identifier
err
OUT
returned error code

Returns

(xmldtdnode *) new DTD node


XmlCreateDocument()

Creates the initial top-level DOCUMENT node and its supporting infrastructure. If a qualified name is provided, a an element with that name is created and set as the document's root element.

Syntax

xmldocnode* XmlCreateDocument(
   xmlctx *xctx,
   oratext *uri,
   oratext *qname, 
   xmldtdnode *dtd,
   xmlerr *err);
ParameterIn/OutDescription
xctx
IN
XML context
uri
IN
namespace URI of root element to create, or NULL
qname
IN
qualified name of root element, or NULL if none
dtd
IN
associated DTD node
err
OUT
returned error code

Returns

(xmldocnode *) new Document object.


XmlDestroy()

Destroys an XML context.

Syntax

void XmlDestroy(
   xmlctx *xctx);
ParameterIn/OutDescription
xctx
IN
XML context


See Also:

XmlCreate()


XmlDiff()

Compares two XML documents, specified either as DOM Trees, files, URIs, orastreams, and so on, and returns its document node. If input documents are not supplied as DOM trees, DOM trees will be created for them.

If the inputs are DOMs, that memory will not be freed when the call completes.

Data(DOM) encoding of both the documents must be the same as the data encoding in the XML context. The DOM for the diff will be created in the data encoding specified by the XML context.

Syntax

xmldocnode *XmlDiff(
   xmlctx *xctx, 
   xmlerr *err,
   ub4  flags,
   xmldfsrct firstSourceType,
   void *firstSource,
   void *firstSourceExtra,
   xmldfsrct secondSourceType,
   void *secondSource,
   void *secondSourceExtra,
   uword hashLevel);
ParameterIn/OutDescription
xctx
IN
XML context
err
OUT
numeric error code, XMLERR_OK [0] on success
flags
IN
Comparison options. By default, global algorithm and snapshot model are used.
  • XMLDF_FL_DEFAULTS(=0) chooses defaults

  • XMLDF_FL_ALGORITHM_GLOBAL is the global algorithm; it will generate the minimal diff using INSERT, APPEND, DELETE and UPDATE, and needs more memory and time than XMLDF_FL_ALGORITHM_LOCAL

  • XMLDF_FL_ALGORITHM_LOCAL is the local algorithm; it may not generate the minimal diff, but it is faster and uses less space than XMLDF_FL_ALGORITHM_GLOBAL

  • XMLDF_FL_DISABLE_UPDATE disables update operations with global algorithms

  • XMLDF_FL_OUTPUT_SNAPSHOT uses the snapshot model

firstSourceType
IN
Source type for the first document. If 0, assumed to be a DOM document node.
firstSource
IN
Pointer to the first document source
firstSourceExtra
IN
An additional pointer to the first document source; used for the buffer length pointer.
secondSourceType
IN
Source type for the second document. If 0, assumed to be a DOM document node.
secondSource
IN
Pointer to the second document source
secondSourceExtra
IN
An additional pointer to the second document source; used for the buffer length pointer.
hashLevel
IN
1-based depth (counting from the root), where hashing should be used for subtrees. Values less than or equal to 1 indicate no hashing. This value must be specified programmatically.

The hash value for every element node is associated with the entire subtree rooted at that node. During the computation of the diff, there is no further drilling down into the tree beyond hash level depth.

  • If hashing is used with XMLDF_FL_ALGORITHM_GLOBAL, it will speed up diff computation significantly, but may reduce the quality of the diff.

  • With XMLDF_FL_ALGORITHM_LOCAL, it improves the quality of the diff



XmlFreeDocument()

Destroys a document created by XmlCreateDocument or through one of the Load functions. Releases all resources associated with the document, which is then invalid.

Syntax

void XmlFreeDocument(
   xmlctx *xctx,
   xmldocnode *doc);
ParameterIn/OutDescription
xctx
IN
XML context
doc
IN
document to free


XmlGetEncoding()

Returns data encoding in use by XML context. Ordinarily, the data encoding is chosen by the user, so this function is not needed. However, if the data encoding is not specified, and allowed to default, this function can be used to return the name of that default encoding.

Syntax

oratext *XmlGetEncoding(
   xmlctx *xctx);
ParameterIn/OutDescription
xctx
IN
XML context

Returns

(oratext *) name of data encoding


XmlHasFeature()

Determine if a DOM feature is implemented. Returns TRUE if the feature is implemented in the specified version, FALSE otherwise.

In level 1, the legal values for package are 'HTML' and 'XML' (case-insensitive), and the version is the string "1.0". If the version is not specified, supporting any version of the feature will cause the method to return TRUE.

  • DOM 1.0 features are "XML" and "HTML".

  • DOM 2.0 features are "Core", "XML", "HTML", "Views", "StyleSheets", "CSS", "CSS2", "Events", "UIEvents", "MouseEvents", "MutationEvents", "HTMLEvents", "Range", "Traversal"

Syntax

boolean XmlHasFeature(
   xmlctx *xctx,
   oratext *feature,
   oratext *version);
ParameterIn/OutDescription
xctx
IN
XML context
feature
IN
package name of the feature to test
version
IN
version number of the package name to test

Returns

(boolean) feature is implemented?


XmlIsSimple()

Returns a flag saying whether the context's data encoding is "simple", single-byte for each character, like ASCII or EBCDIC.

Syntax

boolean XmlIsSimple(
   xmlctx *xctx);
ParameterIn/OutDescription
xctx
IN
XML context

Returns

(boolean) TRUE of data encoding is "simple", FALSE otherwise


XmlIsUnicode()

Returns a flag saying whether the context's data encoding is Unicode, UTF-16, with two-byte for each character.

Syntax

boolean XmlIsUnicode(
   xmlctx *xctx);
ParameterIn/OutDescription
xctx
IN
XML context

Returns

(boolean) TRUE of data encoding is Unicode, FALSE otherwise


XmlLoadDom()

Loads (parses) an XML document from an input source and creates a DOM. The root document node is returned on success, or NULL on failure (with err set).

The function takes two fixed arguments, the xmlctx and an error return code, then zero or more (property, value) pairs, then NULL.

SOURCE Input source is set by one of the following mutually exclusive properties (choose one):

  • ("uri", document URI) [compiler encoding]

  • ("file", document filesystem path) [compiler encoding]

  • ("buffer", address of buffer, "buffer_length", # bytes in buffer)

  • ("stream", address of stream object, "stream_context", pointer to stream object's context)

  • ("stdio", FILE* stream)

PROPERTIES Additional properties:

  • ("dtd", DTD node) DTD for document

  • ("base_uri", document base URI) for documents loaded from other sources than a URI, sets the effective base URI. the document's base URI is needed in order to resolve relative URI include, import, and so on.

  • ("input_encoding", encoding name) forced input encoding [name]

  • ("default_input_encoding", encoding_name) default input encoding to assume if document is not self-describing (no BOM, protocol header, XMLDecl, and so on)

  • ("schema_location", string) schemaLocation of schema for this document. used to figure optimal layout when loading documents into a database

  • ("validate", boolean) when TRUE, turns on DTD validation; by default, only well-formedness is checked. note that schema validation is a separate beast.

  • ("discard_whitespace", boolean) when TRUE, formatting whitespace between elements (newlines and indentation) in input documents is discarded. by default, ALL input characters are preserved.

  • ("dtd_only", boolean) when TRUE, parses an external DTD, not a complete XML document.

  • ("stop_on_warning", boolean) when TRUE, warnings are treated the same as errors and cause parsing, validation, and so on, to stop immediately. by default, warnings are issued but the game continues.

  • ("warn_duplicate_entity", boolean) when TRUE, entities which are declared more than once will cause warnings to be issued. the default is to accept the first declaration and silently ignore the rest.

  • ("no_expand_char_ref", boolean) when TRUE, causes character references to be left unexpanded in the DOM data. ordinarily, character references are replaced by the character they represent. however, when a document is saved those characters entities do not reappear. to way to ensure they remain through load and save is to not expand them.

  • ("no_check_chars", boolean) when TRUE, omits the test of XML [2] Char production: all input characters will be accepted as valid

Syntax

xmldocnode *XmlLoadDom(
   xmlctx *xctx, 
   xmlerr *err, 
   list);
ParameterIn/OutDescription
xctx
IN
XML context
err
OUT
returned error code
list
IN
NULL-terminated list of variable arguments

Returns

(xmldocnode *) document node on success [NULL on failure with err set]


See Also:

XmlSaveDom()


XmlLoadSax()

Loads (parses) an XML document from an input source and generates a set of SAX events (as user callbacks). Input sources and basic set of properties is the same as for XmlLoadDom.

Syntax

xmlerr XmlLoadSax(
   xmlctx *xctx,
   xmlsaxcb *saxcb,
   void *saxctx, 
   list);
ParameterIn/OutDescription
xctx
IN
XML context
saxcb
IN
SAX callback structure
saxctx
IN
context passed to SAX callbacks
list
IN
NULL-terminated list of variable arguments

Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success


XmlLoadSaxVA()

Loads (parses) an XML document from an input source and generates a set of SAX events (as user callbacks). Input sources and basic set of properties is the same as for XmlLoadDom.

Syntax

xmlerr XmlLoadSaxVA(
   xmlctx *xctx, 
   xmlsaxcb *saxcb, 
   void *saxctx, 
   va_list va);
ParameterIn/OutDescription
xctx
IN
XML context
saxcb
IN
SAX callback structure
saxctx
IN
context passed to SAX callbacks
va
IN
NULL-terminated list of variable arguments

Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success


XmlSaveDom()

Serializes document or subtree to the given destination and returns the number of bytes written; if no destination is provided, just returns formatted size but does not output.

If an output encoding is specified, the document will be re-encoded on output; otherwise, it will be in its existing encoding.

The top level is indented step*level spaces, the next level step*(level+1) spaces, and so on.

When saving to a buffer, if the buffer overflows, 0 is returned and err is set to XMLERR_SAVE_OVERFLOW.

DESTINATION Output destination is set by one of the following mutually exclusive properties (choose one):

  • ("uri", document URI) POST, PUT? [compiler encoding]

  • ("file", document filesystem path) [compiler encoding]

  • ("buffer", address of buffer, "buffer_length", # bytes in buffer)

  • ("stream", address of stream object, "stream_context", pointer to stream object's context)

PROPERTIES Additional properties:

  • ("output_encoding", encoding name) name of final encoding for document. unless specified, saved document will be in same encoding as xmlctx.

  • ("indent_step", unsigned) spaces to indent each level of output. default is 4, 0 means no indentation.

  • ("indent_level", unsigned) initial indentation level. default is 0, which means no indentation, flush left.

  • ("xmldecl", boolean) include an XMLDecl in the output document. ordinarily an XMLDecl is output for a compete document (root node is DOC).

  • ("bom", boolean) input a BOM in the output document. usually the BOM is only needed for certain encodings (UTF-16), and optional for others (UTF-8). causes optional BOMs to be output.

  • ("prune", boolean) prunes the output like the unix 'find' command; does not not descend to children, just prints the one node given.

Syntax

ubig_ora XmlSaveDom(
   xmlctx *xctx,
   xmlerr *err,
   xmlnode *root,
   list);
ParameterIn/OutDescription
xctx
IN
XML context
err
OUT
error code on failure
root
IN
root node or subtree to save
list
IN
NULL-terminated list of variable arguments

Returns

(ubig_ora) number of bytes written to destination


See Also:

XmlLoadDom()


XmlVersion()

Returns the version string for the XDK

Syntax

oratext *XmlVersion();

Returns

(oratext *) version string

PKd xPKnFJ OEBPS/dom.htm Package DOM APIs for C

3 Package DOM APIs for C

This implementation follows REC-DOM-Level-1-19981001. Because the DOM standard is object-oriented, some changes were made for C language adaptation.

  • Reused function names have to be expanded; getValue in the Attr interface has the unique name XmlDomGetAttrValue that matches the pattern established by DOM 2's getNodeValue.

  • Functions were added to extend the DOM beyond the standard; one example is XmlDomNumChildNodes, which returns the number of children of a node.

This chapter contains the following sections:


Attr Interface

Table 3-1 summarizes the methods available through the Attr interface.

Table 3-1 Summary of Attr Methods; DOM Package

FunctionSummary

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);
ParameterIn/OutDescription
xctx
IN
XML context
attr
IN
attribute node

Returns

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


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 GetXXX 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);
ParameterIn/OutDescription
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]


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);
ParameterIn/OutDescription
xctx
IN
XML context
attr
IN
attribute node

Returns

(oratext *) name of attribute [data encoding]


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 GetXXX() 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);
ParameterIn/OutDescription
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]


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);
ParameterIn/OutDescription
xctx
IN
XML context
attr
IN
attribute node

Returns

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


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);
ParameterIn/OutDescription
xctx
IN
XML context
attr
IN
attribute node

Returns

(boolean) attribute's "specified" flag


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);
ParameterIn/OutDescription
xctx
IN
XML context
attr
IN
attribute node

Returns

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


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);
ParameterIn/OutDescription
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


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);
ParameterIn/OutDescription
xctx
IN
XML context
attr
IN
attribute node

Returns

(oratext *) attribute's value


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 GetXXX() 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);
ParameterIn/OutDescription
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


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);
ParameterIn/OutDescription
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);
ParameterIn/OutDescription
xctx
IN
XML context
attr
IN
attribute node

Returns

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


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);
ParameterIn/OutDescription
xctx
IN
XML context
attr
IN
attribute node
value
IN
new value of attribute; data encoding


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);
ParameterIn/OutDescription
xctx
IN
XML context
attr
IN
attribute node
isream
IN
input stream

Returns

(xmlerr) numeric error code, 0 on success


CharacterData Interface

Table 3-2 summarizes the methods available through the CharacterData interface.

Table 3-2 Summary of CharacterData Method; DOM Package

FunctionSummary

XmlDomAppendData()


Append data to end of node's current data.

XmlDomDeleteData()


Remove part of node's data.

XmlDomGetCharData()


Return data for node.

XmlDomGetCharDataLength()


Return length of data for node.

XmlDomInsertData()


Insert string into node's current data.

XmlDomReplaceData()


Replace part of node's data.

XmlDomSetCharData()


Set data for node.

XmlDomSubstringData()


Return substring of node's data.



XmlDomAppendData()

Append a string to the end of a CharacterData node's data. If the node is not Text, Comment or CDATA, or if the string to append is NULL, does nothing. The appended data should be in the data encoding. It will not be verified, converted, or checked.

The new node data will be allocated and managed by DOM, but if the previous node value was allocated and manager by the user, they are responsible for freeing it, which is why it is returned.

Syntax

void XmlDomAppendData(
   xmlctx *xctx,
   xmlnode *node,
   oratext *data, 
   oratext **old);
ParameterIn/OutDescription
xctx
IN
XML context
node
IN
CharacterData node
data
IN
data to append; data encoding
old
OUT
previous data for node; data encoding


XmlDomDeleteData()

Remove a range of characters from a CharacterData node's data. If the node is not text, comment or CDATA, or if the offset is outside of the original data, does nothing. The offset is zero-based, so offset zero refers to the start of the data. Both offset and count are in characters, not bytes. If the sum of offset and count exceeds the data length then all characters from offset to the end of the data are deleted.

The new node data will be allocated and managed by DOM, but if the previous node value was allocated and managed by the user, they are responsible for freeing it, which is why it is returned.

Syntax

void XmlDomDeleteData(
   xmlctx *xctx,
   xmlnode *node,
   ub4 offset, 
   ub4 count,
   oratext **old);
ParameterIn/OutDescription
xctx
IN
XML context
node
IN
CharacterData node
offset
IN
character offset where to start removing
count
IN
number of characters to delete
old
OUT
previous data for node; data encoding


See Also:

XmlDomGetCharData(), XmlDomAppendData(), XmlDomInsertData(), <a href="#Xmldomreplacedata">XmlDomReplaceData(), XmlDomSplitText()


XmlDomGetCharData()

Returns the data for a CharacterData node (type text, comment or CDATA) in the data encoding. For other node types, or if there is no data, returns NULL.

Syntax

oratext* XmlDomGetCharData(
   xmlctx *xctx,
   xmlnode *node);
ParameterIn/OutDescription
xctx
IN
XML context
node
IN
CharacterData node; Text, Comment or CDATA

Returns

(oratext *) character data of node [data encoding]


XmlDomGetCharDataLength()

Returns the length of the data for a CharacterData node, type Text, Comment or CDATA) in characters, not bytes. For other node types, returns 0.

Syntax

ub4 XmlDomGetCharDataLength(
   xmlctx *xctx,
   xmlnode *cdata);
ParameterIn/OutDescription
xctx
IN
XML context
node
IN
CharacterData node; Text, Comment or CDATA

Returns

(ub4) length in characters, not bytes, of node's data


XmlDomInsertData()

Insert a string into a CharacterData node's data at the specified position. If the node is not Text, Comment or CDATA, or if the data to be inserted is NULL, or the offset is outside the original data, does nothing. The inserted data must be in the data encoding. It will not be verified, converted, or checked. The offset is specified as characters, not bytes. The offset is zero-based, so inserting at offset zero prepends the data.

The new node data will be allocated and managed by DOM, but if the previous node value was allocated and managed by the user, they are responsible for freeing it (which is why it's returned).

Syntax

void XmlDomInsertData(
   xmlctx *xctx,
   xmlnode *node,
   ub4 offset, 
   oratext *arg,
   oratext **old);
ParameterIn/OutDescription
xctx
IN
XML context
node
IN
CharacterData node; Text, Comment, or CDATA
offset
IN
character offset where to start inserting
arg
IN
data to insert
old
OUT
previous data for node; data encoding


XmlDomReplaceData()

Replaces a range of characters in a CharacterData node's data with a new string. If the node is not text, comment or CDATA, or if the offset is outside of the original data, or if the replacement string is NULL, does nothing. If the count is zero, acts just as XmlDomInsertData. The offset is zero-based, so offset zero refers to the start of the data. The replacement data must be in the data encoding. It will not be verified, converted, or checked. The offset and count are both in characters, not bytes. If the sum of offset and count exceeds length, then all characters to the end of the data are replaced.

The new node data will be allocated and managed by DOM, but if the previous node value was allocated and managed by the user, they are responsible for freeing it, which is why it is returned.

Syntax

void XmlDomReplaceData(
   xmlctx *xctx,
   xmlnode *node,
   ub4 offset, 
   ub4 count,
   oratext *arg,
   oratext **old);
ParameterIn/OutDescription
xctx
IN
XML context
node
IN
CharacterData node; Text, Comment, or CDATA
offset
IN
character offset where to start replacing
count
IN
number of characters to replace
arg
IN
replacement substring; data encoding
old
OUT
previous data for node; data encoding


XmlDomSetCharData()

Sets data for a CharacterData node (type text, comment or CDATA), replacing the old data. For other node types, does nothing. The new data is not verified, converted, or checked; it should be in the data encoding.

Syntax

void XmlDomSetCharData(
   xmlctx *xctx,
   xmlnode *node,
   oratext *data);
ParameterIn/OutDescription
xctx
IN
XML context
node
IN
CharacterData node; Text, Comment, or CDATA
data
IN
new data for node


XmlDomSubstringData()

Returns a range of character data from a CharacterData node, type Text, Comment or CDATA. For other node types, or if count is zero, returns NULL. Since the data is in the data encoding, offset and count are in characters, not bytes. The beginning of the string is offset 0. If the sum of offset and count exceeds the length, then all characters to the end of the data are returned.

The substring is permanently allocated in the node's document's memory pool. To free the substring, use XmlDomFreeString.

Syntax

oratext* XmlDomSubstringData(
   xmlctx *xctx,
   xmlnode *node,
   ub4 offset,
   ub4 count);
ParameterIn/OutDescription
xctx
IN
XML context
node
IN
CharacterData node; Text, Comment, or CDATA
offset
IN
character offset where to start extraction of substring
count
IN
number of characters to extract

Returns

(oratext *) specified substring.


Document Interface

Table 3-3 summarizes the methods available through the Document interface.

Table 3-3 Summary of Document Methods; DOM Package

FunctionSummary

XmlDomCreateAttr()


Create attribute node.

XmlDomCreateAttrNS()


Create attribute node with namespace information.

XmlDomCreateCDATA()


Create CDATA node.

XmlDomCreateComment()


Create comment node.

XmlDomCreateElem()


Create an element node.

XmlDomCreateElemNS()


Create an element node with namespace information.

XmlDomCreateEntityRef()


Create entity reference node.

XmlDomCreateFragment()


Create a document fragment.

XmlDomCreatePI()


Create PI node.

XmlDomCreateText()


Create text node.

XmlDomFreeString()


Frees a string allocate by XmlDomSubstringData, and others.

XmlDomGetBaseURI()


Returns the base URI for a document.

XmlDomGetDTD()


Get DTD for document.

XmlDomGetDecl()


Returns a document's XMLDecl information.

XmlDomGetDocElem()


Get top-level element for document.

XmlDomGetDocElemByID()


Get document element given ID.

XmlDomGetDocElemsByTag()


Obtain document elements.

XmlDomGetDocElemsByTagNS()


Obtain document elements (namespace aware version).

XmlDomGetLastError()


Return last error code for document.

XmlDomGetSchema()


Returns URI of schema associated with document.

XmlDomImportNode()


Import a node from another DOM.

XmlDomIsSchemaBased()


Indicate whether a schema is associated with a document.

XmlDomSaveString()


Saves a string permanently in a document's memory pool.

XmlDomSaveString2()


Saves a Unicode string permanently in a document's memory pool.

XmlDomSetDTD()


Sets DTD for document.

XmlDomSetDocOrder()


Set document order for all nodes.

XmlDomSetLastError()


Sets last error code for document.

XmlDomSync()


Synchronizes the persistent version of a document with its DOM.



XmlDomCreateAttr()

Creates an attribute node with the given name and value (in the data encoding). Note this function differs from the DOM specification, which does not allow the initial value of the attribute to be set (see XmlDomSetAttrValue). The name is required, but the value may be NULL; neither is verified, converted, or checked.

This is the non-namespace aware function (see XmlDomCreateAttrNS): the new attribute will have NULL namespace URI and prefix, and its local name will be the same as its name, even if the name specified is a qualified name.

If given an initial value, the attribute's specified flag will be TRUE.

The new node is an orphan with no parent; it must be added to the DOM tree with XmlDomAppendChild, and so on.

See XmlDomSetAttr which creates and adds an attribute in a single operation.

The name and value are not copied, their pointers are just stored. The user is responsible for persistence and freeing of that data.

Syntax

xmlattrnode* XmlDomCreateAttr(
   xmlctx *xctx,
   xmldocnode *doc, 
   oratext *name, 
   oratext *value);
ParameterIn/OutDescription
xctx
IN
XML context
doc
IN
XML document node
name
IN
new node's name; data encoding; user control
value
IN
new node's value; data encoding; user control

Returns

(xmlattrnode *) new Attr node.


XmlDomCreateAttrNS()

Creates an attribute node with the given namespace URI and qualified name; this is the namespace-aware version of XmlDomCreateAttr. Note this function differs from the DOM specification, which does not allow the initial value of the attribute to be set (see XmlDomSetAttrValue). The name is required, but the value may be NULL; neither is verified, converted, or checked.

If given an initial value, the attribute's specified flag will be TRUE.

The new node is an orphan with no parent; it must be added to the DOM tree with XmlDomAppendChild, and so on. See XmlDomSetAttr which creates and adds an attribute in a single operation.

The URI, qualified name and value are not copied, their pointers are just stored. The user is responsible for persistence and freeing of that data.

Syntax

xmlattrnode* XmlDomCreateAttrNS(
   xmlctx *xctx, 
   xmldocnode *doc, 
   oratext *uri, 
   oratext *qname,
   oratext *value);
ParameterIn/OutDescription
xctx
IN
XML context
doc
IN
XML document node
uri
IN
node's namespace URI; data encoding; user control
qname
IN
node's qualified name; data encoding; user control
value
IN
new node's value; data encoding; user control

Returns

(xmlattrnode *) new Attr node.


XmlDomCreateCDATA()

Creates a CDATASection node with the given initial data (which should be in the data encoding). A CDATASection is considered verbatim and is never parsed; it will not be joined with adjacent Text nodes by the normalize operation. The initial data may be NULL; if provided, it is not verified, converted, or checked. The name of a CDATA node is always "#cdata-section".

The new node is an orphan with no parent; it must be added to the DOM tree with XmlDomAppendChild and so on.

The CDATA is not copied, its pointer is just stored. The user is responsible for persistence and freeing of that data.

Syntax

xmlcdatanode* XmlDomCreateCDATA(
   xmlctx *xctx, 
   xmldocnode *doc, 
   oratext *data);
ParameterIn/OutDescription
xctx
IN
XML context
doc
IN
XML document node
data
IN
new node's CDATA; data encoding; user control

Returns

(xmlcdatanode *) new CDATA node.


XmlDomCreateComment()

Creates a Comment node with the given initial data (which must be in the data encoding). The data may be NULL; if provided, it is not verified, converted, or checked. The name of a Comment node is always "#comment".

The new node is an orphan with no parent; it must be added to the DOM tree with XmlDomAppendChild and so on.

The comment data is not copied, its pointer is just stored. The user is responsible for persistence and freeing of that data.

Syntax

xmlcommentnode* XmlDomCreateComment(
   xmlctx *xctx,
   xmldocnode *doc,
   oratext *data);
ParameterIn/OutDescription
xctx
IN
XML context
doc
IN
XML document node
data
IN
new node's comment; data encoding; user control

Returns

(xmlcommentnode *) new Comment node.


XmlDomCreateElem()

Creates an element node with the given tag name (which should be in the data encoding). Note that the tag name of an element is case sensitive. This is the non-namespace aware function: the new node will have NULL namespace URI and prefix, and its local name will be the same as its tag name, even if the tag name specified is a qualified name.

The new node is an orphan with no parent; it must be added to the DOM tree with XmlDomAppendChild and so on.

The tagname is not copied, its pointer is just stored. The user is responsible for persistence and freeing of that data.

Syntax

xmlelemnode* XmlDomCreateElem(
   xmlctx *xctx, 
   xmldocnode *doc,
   oratext *tagname);
ParameterIn/OutDescription
xctx
IN
XML context
doc
IN
XML document node
tagname
IN
new node's name; data encoding; user control

Returns

(xmlelemnode *) new Element node.


XmlDomCreateElemNS()

Creates an element with the given namespace URI and qualified name. Note that element names are case sensitive, and the qualified name is required though the URI may be NULL. The qualified name will be split into prefix and local parts, retrievable with XmlDomGetNodePrefix, XmlDomGetNodeLocal, and so on; the tagName will be the full qualified name.

The new node is an orphan with no parent; it must be added to the DOM tree with XmlDomAppendChild and so on.

The URI and qualified name are not copied, their pointers are just stored. The user is responsible for persistence and freeing of that data.

Syntax

xmlelemnode* XmlDomCreateElemNS(
   xmlctx *xctx,
   xmldocnode *doc, 
   oratext *uri,
   oratext *qname);
ParameterIn/OutDescription
xctx
IN
XML context
doc
IN
XML document node
uri
IN
new node's namespace URI; data encoding, user control
qname
IN
new node's qualified name; data encoding; user control

Returns

(xmlelemnode *) new Element node.


XmlDomCreateEntityRef()

Creates an EntityReference node; the name (which should be in the data encoding) is the name of the entity to be referenced. The named entity does not have to exist. The name is not verified, converted, or checked.

EntityReference nodes are never generated by the parser; instead, entity references are expanded as encountered. On output, an entity reference node will turn into a "&name;" style reference.

The new node is an orphan with no parent; it must be added to the DOM tree with XmlDomAppendChild, and so on.

The entity reference name is not copied, its pointer is just stored. The user is responsible for persistence and freeing of that data.

Syntax

xmlentrefnode* XmlDomCreateEntityRef(
   xmlctx *xctx,
   xmldocnode *doc,
   oratext *name);
ParameterIn/OutDescription
xctx
IN
XML context
doc
IN
XML document node
name
IN
name of referenced entity; data encoding; user control

Returns

(xmlentrefnode *) new EntityReference node.


XmlDomCreateFragment()

Creates an empty DocumentFragment node. A document fragment is treated specially when it is inserted into a DOM tree: the children of the fragment are inserted in order instead of the fragment node itself. After insertion, the fragment node will still exist, but have no children. See XmlDomInsertBefore, XmlDomReplaceChild, XmlDomAppendChild, and so on. The name of a fragment node is always "#document-fragment".

Syntax

xmlfragnode* XmlDomCreateFragment(
   xmlctx *xctx,
   xmldocnode *doc);
ParameterIn/OutDescription
xctx
IN
XML context
doc
IN
XML document node

Returns

(xmlfragnode *) new empty DocumentFragment node


XmlDomCreatePI()

Creates a ProcessingInstruction node with the given target and data (which should be in the data encoding). The data may be NULL initially, and may be changed later (with XmlDomSetPIData), but the target is required and cannot be changed. Note the target and data are not verified, converted, or checked. The name of a PI node is the same as the target.

The new node is an orphan with no parent; it must be added to the DOM tree with XmlDomAppendChild and so on.

The PI's target and data are not copied, their pointers are just stored. The user is responsible for persistence and freeing of that data.

Syntax

xmlpinode* XmlDomCreatePI(
   xmlctx *xctx
   xmldocnode *doc, 
   oratext *target,
   oratext *data);
ParameterIn/OutDescription
xctx
IN
XML context
doc
IN
XML document node
target
IN
new node's target; data encoding; user control
data
IN
new node's data; data encoding; user control

Returns

(xmlpinode *) new PI node.


XmlDomCreateText()

Creates a Text node with the given initial data (which must be non-NULL and in the data encoding). The data may be NULL; if provided, it is not verified, converted, checked, or parsed (entities will not be expanded). The name of a fragment node is always "#text". New data for a Text node can be set; see the CharacterData interface for editing methods.

The new node is an orphan with no parent; it must be added to the DOM tree with XmlDomAppendChild and so on.

The text data is not copied, its pointer is just stored. The user is responsible for persistence and freeing of that data.

Syntax

xmltextnode* XmlDomCreateText(
   xmlctx *xctx, 
   xmldocnode *doc,
   oratext *data);
ParameterIn/OutDescription
xctx
IN
XML context
doc
IN
XML document node
data
IN
new node's text; data encoding; user control

Returns

(xmltextnode *) new Text node.


XmlDomFreeString()

Frees the string allocated by XmlDomSubstringData or similar functions. Note that strings explicitly saved with XmlDomSaveString are not freeable individually.

Syntax

void XmlDomFreeString(
   xmlctx *xctx,
   xmldocnode *doc,
   oratext *str);
ParameterIn/OutDescription
xctx
IN
XML context
doc
IN
document where the string belongs
str
IN
string to free


XmlDomGetBaseURI()

Returns the base URI for a document. Usually only documents that were loaded from a URI will automatically have a base URI; documents loaded from other sources (stdin, buffer, and so on) will not naturally have a base URI, but a base URI may have been set for them using XmlDomSetBaseURI, for the purposes of resolving relative URIs in inclusion.

Syntax

oratext *XmlDomGetBaseURI(
   xmlctx *xctx,
   xmldocnode *doc);
ParameterIn/OutDescription
xctx
IN
XML context
doc
IN
XML document node

Returns

(oratext *) document's base URI [or NULL]


See Also:

XmlDomSetBaseURI()


XmlDomGetDTD()

Returns the DTD node associated with current document; if there is no DTD, returns NULL. The DTD cannot be edited, but its children may be retrieved with XmlDomGetChildNodes as for other node types.

Syntax

xmldtdnode* XmlDomGetDTD(
   xmlctx *xctx,
   xmldocnode *doc);
ParameterIn/OutDescription
xctx
IN
XML context
doc
IN
XML document node

Returns

(xmldtdnode *) DTD node for document [or NULL]


XmlDomGetDecl()

Returns the information from a document's XMLDecl. If there is no XMLDecl, returns XMLERR_NO_DECL. Returned are the XML version# ("1.0" or "2.0"), the specified encoding, and the standalone value. If encoding is not specified, NULL will be set. The standalone flag is three-state: < 0 if standalone was not specified, 0 if it was specified and FALSE, > 0 if it was specified and TRUE.

Syntax

xmlerr XmlDomGetDecl(
   xmlctx *xctx,
   xmldocnode *doc,
   oratext **ver, 
   oratext **enc,
   sb4 *std);
ParameterIn/OutDescription
xctx
IN
XML context
doc
IN
XML document node
ver
OUT
XML version
enc
OUT
encoding specification
std
OUT
standalone specification

Returns

(xmlerr) XML error code, perhaps version/encoding/standalone set


XmlDomGetDocElem()

Returns the root element (node) of the DOM tree, or NULL if there is none. Each document has only one uppermost Element node, called the root element. It is created after a document is parsed successfully, or manually by XmlDomCreateElem then XmlDomAppendChild, and so on.

Syntax

xmlelemnode* XmlDomGetDocElem(
   xmlctx *xctx,
   xmldocnode *doc);
ParameterIn/OutDescription
xctx
IN
XML context
doc
IN
XML document node

Returns

(xmlelemnode *) root element [or NULL]


See Also:

XmlDomCreateElem()


XmlDomGetDocElemByID()

Returns the element node which has the given ID. If no such ID is defined, returns NULL. Note that attributes named "ID" are not automatically of type ID; ID attributes (which can have any name) must be declared as type ID in the DTD.

The given ID should be in the data encoding or it might not match.

Syntax

xmlelemnode* XmlDomGetDocElemByID(
   xmlctx *xctx,
   xmldocnode *doc,
   oratext *id);
ParameterIn/OutDescription
xctx
IN
XML context
doc
IN
XML document node
id
IN
element's unique ID; data encoding

Returns

(xmlelemnode *) matching element.


XmlDomGetDocElemsByTag()

Returns a list of all elements in the document tree rooted at the root node with a given tag name, in document order (the order in which they would be encountered in a preorder traversal of the tree). If root is NULL, the entire document is searched.

The special name "*" matches all tag names; a NULL name matches nothing. Note that tag names are case sensitive, and should be in the data encoding or a mismatch might occur.

This function is not namespace aware; the full tag names are compared. If two qualified names with two different prefixes both of which map to the same URI are compared, the comparison will fail. See XmlDomGetElemsByTagNS for the namespace-aware version.

The list should be freed with XmlDomFreeNodeList when it is no longer needed.

The list is not live, it is a snapshot. That is, if a new node which matched the tag name were added to the DOM after the list was returned, the list would not automatically be updated to include the node.

Syntax

xmlnodelist* XmlDomGetDocElemsByTag(
   xmlctx *xctx,
   xmldocnode *doc,
   oratext *name);
ParameterIn/OutDescription
xctx
IN
XML context
doc
IN
XML document node
name
IN
tagname to match; data encoding; * for all

Returns

(xmlnodelist *) new NodeList containing all matched Elements.


XmlDomGetDocElemsByTagNS()

Returns a list of all elements (in the document tree rooted at the given node) with a given namespace URI and local name, in the order in which they would be encountered in a preorder traversal of the tree. If root is NULL, the entire document is searched.

The URI and local name should be in the data encoding. The special local name "*" matches all local names; a NULL local name matches nothing. Namespace URIs must always match, however, no wildcard is allowed. Note that comparisons are case sensitive. See XmlDomGetDocElemsByTag for the non-namespace aware version.

The list should be freed with XmlDomFreeNodeList when it is no longer needed.

The list is not live, it is a snapshot. That is, if a new node which matched the tag name were added to the DOM after the list was returned, the list would not automatically be updated to include the node.

Syntax

xmlnodelist* XmlDomGetDocElemsByTagNS(
   xmlctx *xctx,
   xmldocnode *doc, 
   oratext *uri,
   oratext *local);
ParameterIn/OutDescription
xctx
IN
XML context
doc
IN
XML document node
uri
IN
namespace URI to match; data encoding; * matches all
local
IN
local name to match; data encoding; * matches all

Returns

(xmlnodelist *) new NodeList containing all matched Elements.


XmlDomGetLastError()

Returns the error code of the last error which occurred in the given document.

Syntax

xmlerr XmlDomGetLastError(
   xmlctx *xctx,
   xmldocnode *doc);
ParameterIn/OutDescription
xctx
IN
XML context
doc
IN
XML document node

Returns

(xmlerr) numeric error code, 0 if no error


XmlDomGetSchema()

Returns URI of schema associated with document, if there is one, else returns NULL. The XmlLoadDom functions take a schema location hint (URI); the schema is used for efficient layout of XMLType data. If a schema was provided at load time, this function returns TRUE.

Syntax

oratext* XmlDomGetSchema(
   xmlctx *xctx,
   xmldocnode *doc);
ParameterIn/OutDescription
xctx
IN
XML context
doc
IN
XML document node

Returns

(oratext *) Schema URI or NULL


XmlDomImportNode()

Imports a node from one Document to another. The new node is an orphan and has no parent; it must be added to the DOM tree with XmlDomAppendChild, and so on. The original node is not modified in any way or removed from its document; instead, a new node is created with copies of all the original node's qualified name, prefix, namespace URI, and local name.

As with XmlDomCloneNode, the deep controls whether the children of the node are recursively imported. If FALSE, only the node itself is imported, and it will have no children. If TRUE, all descendents of the node will be imported as well, and an entire new subtree created.

Document and DocumentType nodes cannot be imported. Imported attributes will have their specified flags set to TRUE. Elements will have only their specified attributes imported; non-specified (default) attributes are omitted. New default attributes (for the destination document) are then added.

Syntax

xmlnode* XmlDomImportNode(
   xmlctx *xctx,
   xmldocnode *doc, 
   xmlctx *nctx,
   xmlnode *node,
   boolean deep);
ParameterIn/OutDescription
xctx
IN
XML context
doc
IN
XML document node
nctx
IN
XML context of imported node
node
IN
node to import
deep
IN
TRUE to import the subtree recursively

Returns

(xmlnode *) newly imported node (in this Document).


See Also:

XmlDomCloneNode()


XmlDomIsSchemaBased()

Returns flag specifying whether there is a schema associated with this document. The XmlLoadDom functions take a schema location hint (URI); the schema is used for efficient layout of XMLType data. If a schema was provided at load time, this function returns TRUE.

Syntax

boolean XmlDomIsSchemaBased(
   xmlctx *xctx,
   xmldocnode *doc);
ParameterIn/OutDescription
xctx
IN
XML context
doc
IN
XML document node

Returns

(boolean) TRUE if there is a schema associated with the document


XmlDomSaveString()

Copies the given string into the document's memory pool, so that it persists for the life of the document. The individual string will not be freeable, and the storage will be returned only when the entire document is freed. Works on single-byte or multibyte encodings; for Unicode strings, use XmlDomSaveString2.

Syntax

oratext* XmlDomSaveString(
   xmlctx *xctx,
   xmldocnode *doc,
   oratext *str);
ParameterIn/OutDescription
xctx
IN
XML context
doc
IN
XML document node
str
IN
string to save; data encoding; single- or multi-byte only

Returns

(oratext *) saved copy of string


XmlDomSaveString2()

Copies the given string into the document's memory pool, so that it persists for the life of the document. The individual string will not be freeable, and the storage will be returned only when the entire document is free. Works on Unicode strings only; for single-byte or multibyte strings, use XmlDomSaveString.

Syntax

ub2* XmlDomSaveString2(
   xmlctx *xctx,
   xmldocnode *doc,
   ub2 *ustr);
ParameterIn/OutDescription
xctx
IN
XML context
doc
IN
XML document node
ustr
IN
string to save; data encoding; Unicode only

Returns

(ub2 *) saved copy of string


XmlDomSetBaseURI()

Only documents that were loaded from a URI will automatically have a base URI; documents loaded from other sources (stdin, buffer, and so on) will not naturally have a base URI, so this API is used to set a base URI, for the purposes of relative URI resolution in includes. The base URI should be in the data encoding, and a copy will be made.

Syntax

xmlerr XmlDomSetBaseURI(
   xmlctx *xctx, 
   xmldocnode *doc, 
   oratext *uri);
ParameterIn/OutDescription
xctx
IN
XML context
doc
IN
XML document node
uri
IN
base URI to set; data encoding

Returns

(xmlerr) XML error code


See Also:

XmlDomGetBaseURI()


XmlDomSetDTD()

Sets the DTD for document. Note this call may only be used for a blank document, before any parsing has taken place. A single DTD can be set for multiple documents, so when a document with a set DTD is freed, the set DTD is not also freed.

Syntax

xmlerr XmlDomSetDTD(
   xmlctx *xctx, 
   xmldocnode *doc, 
   xmldtdnode *dtdnode);
ParameterIn/OutDescription
xctx
IN
XML context
doc
IN
XML document node
dtdnode
IN
DocumentType node to set

Returns

(xmlerr) numeric error code, 0 on success


XmlDomSetDocOrder()

Sets the document order for each node in the current document. Must be called once on the final document before XSLT processing can occur. Note this is called automatically by the XSLT processor, so ordinarily the user need not make this call.

Syntax

ub4 XmlDomSetDocOrder(
   xmlctx *xctx, 
   xmldocnode *doc,
   ub4 start_id);
ParameterIn/OutDescription
xctx
IN
XML context
doc
IN
XML document node
start_id
IN
string ID number

Returns

(ub4) highest ordinal assigned


XmlDomSetLastError()

Sets the Last Error code for the given document. If doc is NULL, sets the error code for the XML context.

Syntax

xmlerr XmlDomSetLastError(
   xmlctx *xctx, 
   xmldocnode *doc,
   xmlerr errcode);
ParameterIn/OutDescription
xctx
IN
XML context
doc
IN
XML document node
errcode
IN
error code to set, 0 to clear error

Returns

(xmlerr) original error code


XmlDomSync()

Causes a modified DOM to be written back out to its original source, synchronizing the persistent store and in-memory versions.

Syntax

xmlerr XmlDomSync(
   xmlctx *xctx, 
   xmldocnode *doc);
ParameterIn/OutDescription
xctx
IN
XML context
doc
IN
XML document node

Returns

(xmlerr) numeric error code, 0 on success


DocumentType Interface

Table 3-4 summarizes the methods available through the DocumentType interface.

Table 3-4 Summary of DocumentType Methods; DOM Package

FunctionSummary

XmlDomGetDTDEntities()


Get entities of DTD.

XmlDomGetDTDInternalSubset()


Get DTD's internal subset.

XmlDomGetDTDName()


Get name of DTD.

XmlDomGetDTDNotations()


Get notations of DTD.

XmlDomGetDTDPubID()


Get DTD's public ID.

XmlDomGetDTDSysID()


Get DTD's system ID.



XmlDomGetDTDEntities()

Returns a named node map of general entities defined by the DTD. If the node is not a DTD, or has no general entities, returns NULL.

Syntax

xmlnamedmap* XmlDomGetDTDEntities(
   xmlctx *xctx,
   xmldtdnode *dtd);
ParameterIn/OutDescription
xctx
IN
XML context
dtd
IN
DTD node

Returns

(xmlnamedmap *) named node map containing entities declared in DTD


XmlDomGetDTDInternalSubset()

Returns the content model for an element. If there is no DTD, returns NULL.

Syntax

xmlnode* XmlDomGetDTDInternalSubset(
   xmlctx *xctx,
   xmldtdnode *dtd,
   oratext *name);
ParameterIn/OutDescription
xctx
IN
XML context
dtd
IN
DTD node
name
IN
name of Element; data encoding

Returns

(xmlnode *) content model subtree


XmlDomGetDTDName()

Returns a DTD's name (specified immediately after the DOCTYPE keyword), or NULL if the node is not type DTD.

Syntax

oratext* XmlDomGetDTDName(
   xmlctx *xctx,
   xmldtdnode *dtd);
ParameterIn/OutDescription
xctx
IN
XML context
dtd
IN
DTD node

Returns

(oratext *) name of DTD


XmlDomGetDTDNotations()

Returns named node map of notations declared by the DTD. If the node is not a DTD or has no Notations, returns NULL.

Syntax

xmlnamedmap* XmlDomGetDTDNotations(
   xmlctx *xctx,
   xmldtdnode *dtd);
ParameterIn/OutDescription
xctx
IN
XML context
dtd
IN
DTD node

Returns

(xmlnamedmap *) named node map containing notations declared in DTD


XmlDomGetDTDPubID()

Returns a DTD's public identifier.

Syntax

oratext* XmlDomGetDTDPubID(
   xmlctx *xctx,
   xmldtdnode *dtd);
ParameterIn/OutDescription
xctx
IN
XML context
dtd
IN
DTD node

Returns

(oratext *) DTD's public identifier [data encoding]


XmlDomGetDTDSysID()

Returns a DTD's system identifier.

Syntax

oratext* XmlDomGetDTDSysID(
   xmlctx *xctx,
   xmldtdnode *dtd);
ParameterIn/OutDescription
xctx
IN
XML context
dtd
IN
DTD node

Returns

(oratext *) DTD's system identifier [data encoding]


Element Interface

Table 3-5 summarizes the methods available through the Element Interface.

Table 3-5 Summary of Element Methods; DOM Package

FunctionSummary

XmlDomGetAttr()


Return attribute's value given its name.

XmlDomGetAttrNS()


Return attribute's value given its URI and local name.

XmlDomGetAttrNode()


Get attribute by name.

XmlDomGetAttrNodeNS()


Get attribute by name (namespace aware version).

XmlDomGetChildrenByTag()


Get children of element with given tag name (non-namespace aware).

XmlDomGetChildrenByTagNS()


Get children of element with tag name (namespace aware version).

XmlDomGetDocElemsByTag()


Obtain doc elements.

XmlDomGetDocElemsByTagNS()


Obtain doc elements (namespace aware version).

XmlDomGetTag()


Return an element node's tag name.

XmlDomHasAttr()


Does named attribute exist?

XmlDomHasAttrNS()


Does named attribute exist (namespace aware version)?

XmlDomRemoveAttr()


Remove attribute with specified name.

XmlDomRemoveAttrNS()


Remove attribute with specified URI and local name.

XmlDomRemoveAttrNode()


Remove attribute node.

XmlDomSetAttr()


Set new attribute for element.

XmlDomSetAttrNS()


Set new attribute for element (namespace aware version).

XmlDomSetAttrNode()


Set attribute node.

XmlDomSetAttrNodeNS()


Set attribute node (namespace aware version).



XmlDomGetAttr()

Returns the value of an element's attribute (specified by name). Note that an attribute may have the empty string as its value, but cannot be NULL. If the element does not have an attribute with the given name, NULL is returned.

Syntax

oratext* XmlDomGetAttr(
   xmlctx *xctx,
   xmlelemnode *elem,
   oratext *name);
ParameterIn/OutDescription
xctx
IN
XML context
elem
IN
element node
name
IN
attribute's name

Returns

(oratext *) named attribute's value [data encoding; may be NULL]


XmlDomGetAttrNS()

Returns the value of an element's attribute (specified by URI and local name). Note that an attribute may have the empty string as its value, but cannot be NULL. If the element does not have an attribute with the given name, NULL is returned.

Syntax

oratext* XmlDomGetAttrNS(
   xmlctx *xctx,
   xmlelemnode *elem, 
   oratext *uri,
   oratext *local);
ParameterIn/OutDescription
xctx
IN
XML context
elem
IN
element node
uri
IN
attribute's namespace URI; data encoding
local
IN
attribute's local name; data encoding

Returns

(oratext *) named attribute's value [data encoding; may be NULL]


XmlDomGetAttrNode()

Returns an element's attribute specified by name. If the node is not an element or the named attribute does not exist, returns NULL.

Syntax

xmlattrnode* XmlDomGetAttrNode(
   xmlctx *xctx,
   xmlelemnode *elem,
   oratext *name);
ParameterIn/OutDescription
xctx
IN
XML context
elem
IN
element node
name
IN
attribute's name; data encoding

Returns

(xmlattrnode *) attribute with the specified name [or NULL]


XmlDomGetAttrNodeNS()

Returns an element's attribute specified by URI and localname. If the node is not an element or the named attribute does not exist, returns NULL.

Syntax

xmlattrnode* XmlDomGetAttrNodeNS(
   xmlctx *xctx,
   xmlelemnode *elem, 
   oratext *uri,
   oratext *local);
ParameterIn/OutDescription
xctx
IN
XML context
elem
IN
element node
uri
IN
attribute's namespace URI; data encoding
local
IN
attribute's local name; data encoding

Returns

(xmlattrnode *) attribute node with the given URI/local name [or NULL]


XmlDomGetChildrenByTag()

Returns a list of children of an element with the given tag name, in the order in which they would be encountered in a preorder traversal of the tree. The tag name should be in the data encoding. The special name "*" matches all tag names; a NULL name matches nothing. Note that tag names are case sensitive. This function is not namespace aware; the full tag names are compared. If two prefixes which map to the same URI are compared, the comparison will fail. See XmlDomGetChildrenByTagNS for the namespace-aware version. The returned list can be freed with XmlDomFreeNodeList.

Syntax

xmlnodelist* XmlDomGetChildrenByTag(
   xmlctx *xctx, 
   xmlelemnode *elem,
   oratext *name);
ParameterIn/OutDescription
xctx
IN
XML context
elem
IN
element node
name
IN
tag name to match; data encoding; * for all

Returns

(xmlnodelist *) node list of matching children


XmlDomGetChildrenByTagNS()

Returns a list of children of an element with the given URI and local name, in the order in which they would be encountered in a preorder traversal of the tree. The URI and local name should be in the data encoding. The special name "*" matches all URIs or tag names; a NULL name matches nothing. Note that names are case sensitive. See XmlDomGetChildrenByTag for the non-namespace version. The returned list can be freed with XmlDomFreeNodeList.

Syntax

xmlnodelist* XmlDomGetChildrenByTagNS(
   xmlctx *xctx,
   xmlelemnode *elem, 
   oratext *uri,
   oratext *local);
ParameterIn/OutDescription
xctx
IN
XML context
elem
IN
element node
uri
IN
namespace URI to match; data encoding; * matches all
local
IN
local name to match; data encoding; * matches all

Returns

(xmlnodelist *) node list of matching children


XmlDomGetElemsByTag()

Returns a list of all elements (in the document tree rooted at the root node) with a given tag name, in the order in which they would be encountered in a preorder traversal of the tree. If root is NULL, the entire document is searched. The tag name should be in the data encoding. The special name "*" matches all tag names; a NULL name matches nothing. Note that tag names are case sensitive. This function is not namespace aware; the full tag names are compared. If two prefixes which map to the same URI are compared, the comparison will fail. See XmlDomGetElemsByTagNS for the namespace-aware version. The returned list can be freed with XmlDomFreeNodeList.

Syntax

xmlnodelist* XmlDomGetElemsByTag(
   xmlctx *xctx,
   xmlelemnode *elem,
   oratext *name);
ParameterIn/OutDescription
xctx
IN
XML context
elem
IN
element node
name
IN
tag name to match; data encoding; * for all

Returns

(xmlnodelist *) node list of matching elements


XmlDomGetElemsByTagNS()

Returns a list of all elements (in the document tree rooted at the root node) with a given URI and localname, in the order in which they would be encountered in a preorder traversal of the tree. If root is NULL, the entire document is searched. The tag name should be in the data encoding. The special name "*" matches all tag names; a NULL name matches nothing. Note that tag names are case sensitive. This function is not namespace aware; the full tag names are compared. If two prefixes which map to the same URI are compared, the comparison will fail. The returned list can be freed with XmlDomFreeNodeList.

Syntax

xmlnodelist* XmlDomGetElemsByTagNS(
   xmlctx *xctx,
   xmlelemnode *elem, 
   oratext *uri,
   oratext *local);
ParameterIn/OutDescription
xctx
IN
XML context
elem
IN
element node
uri
IN
namespace URI to match; data encoding; * for all
local
IN
local name to match; data encoding; * for all

Returns

(xmlnodelist *) node list of matching elements


XmlDomGetTag()

Returns the tagName of a node, which is the same as its name. DOM 1.0 states "...even though there is a generic nodeName attribute on the Node interface, there is still a tagName attribute on the Element interface; these two attributes must contain the same value, but the Working Group considers it worthwhile to support both, given the different constituencies the DOM API must satisfy."

Syntax

oratext* XmlDomGetTag(
   xmlctx *xctx,
   xmlelemnode *elem);
ParameterIn/OutDescription
xctx
IN
XML context
elem
IN
Element node

Returns

(oratext *) element's name [data encoding]


XmlDomHasAttr()

Determines if an element has an attribute with the given name. Returns TRUE if so, FALSE if not.

Syntax

boolean XmlDomHasAttr(
   xmlctx *xctx,
   xmlelemnode *elem,
   oratext *name);
ParameterIn/OutDescription
xctx
IN
XML context
elem
IN
Element node
name
IN
attribute's name; data encoding

Returns

(boolean) TRUE if element has attribute with given name


See Also:

XmlDomHasAttrNS()


XmlDomHasAttrNS()

Determines if an element has an attribute with the given URI and localname. Returns TRUE if so, FALSE if not.

Syntax

boolean XmlDomHasAttrNS(
   xmlctx *xctx,
   xmlelemnode *elem,
   oratext *uri,
   oratext *local);
ParameterIn/OutDescription
xctx
IN
XML context
elem
IN
Element node
uri
IN
attribute's namespace URI; data encoding
local
IN
attribute's local name; data encoding

Returns

(boolean) TRUE if element has attribute with given URI/localname


See Also:

XmlDomHasAttr()


XmlDomRemoveAttr()

Removes an attribute (specified by name). If the removed attribute has a default value it is immediately re-created with that default. Note that the attribute is removed from the element's list of attributes, but the attribute node itself is not destroyed.

Syntax

void XmlDomRemoveAttr(
   xmlctx *xctx,
   xmlelemnode *elem,
   oratext *name);
ParameterIn/OutDescription
xctx
IN
XML context
elem
IN
element node
name
IN
attribute's name; data encoding


XmlDomRemoveAttrNS()

Removes an attribute (specified by URI and local name). If the removed attribute has a default value it is immediately re-created with that default. Note that the attribute is removed from the element's list of attributes, but the attribute node itself is not destroyed.

Syntax

void XmlDomRemoveAttrNS(
   xmlctx *xctx,
   xmlelemnode *elem,
   oratext *uri,
   oratext *local);
ParameterIn/OutDescription
xctx
IN
XML context
elem
IN
element node
uri
IN
attribute's namespace URI
local
IN
attribute's local name


XmlDomRemoveAttrNode()

Removes an attribute from an element. If the attribute has a default value, it is immediately re-created with that value (Specified set to FALSE). Returns the removed attribute on success, else NULL.

Syntax

xmlattrnode* XmlDomRemoveAttrNode(
   xmlctx *xctx,
   xmlelemnode *elem,
   xmlattrnode *oldAttr);
ParameterIn/OutDescription
xctx
IN
XML context
elem
IN
element node
oldAtrr
IN
attribute node to remove

Returns

(xmlattrnode *) replaced attribute node [or NULL]


See Also:

XmlDomRemoveAttr()


XmlDomSetAttr()

Creates a new attribute for an element with the given name and value (which should be in the data encoding). If the named attribute already exists, its value is simply replaced. The name and value are not verified, converted, or checked. The value is not parsed, so entity references will not be expanded. The attribute's specified flag will be set.

Syntax

void XmlDomSetAttr(
   xmlctx *xctx,
   xmlelemnode *elem,
   oratext *name,
   oratext *value);
ParameterIn/OutDescription
xctx
IN
XML context
elem
IN
element node
name
IN
attribute's name; data encoding
value
IN
attribute's value; data encoding


XmlDomSetAttrNS()

Creates a new attribute for an element with the given URI, localname and value (which should be in the data encoding). If the named attribute already exists, its value is simply replaced. The name and value are not verified, converted, or checked.

The value is not parsed, so entity references will not be expanded.

The attribute's specified flag will be set.

Syntax

void XmlDomSetAttrNS(
   xmlctx *xctx,
   xmlelemnode *elem,
   oratext *uri, 
   oratext *qname,
   oratext *value);
ParameterIn/OutDescription
xctx
IN
XML context
elem
IN
element node
uri
IN
attribute's namespace URI; data encoding
qname
IN
attribute's qualified name; data encoding
value
IN
attribute's value; data encoding


XmlDomSetAttrNode()

Adds a new attribute to an element. If an attribute with the given name already exists, it is replaced and the old attribute returned through oldNode. If the attribute is new, it is added to the element's list and oldNode set to NULL.

Syntax

xmlattrnode* XmlDomSetAttrNode(
   xmlctx *xctx,
   xmlelemnode *elem,
   xmlattrnode *newAttr);
ParameterIn/OutDescription
xctx
IN
XML context
elem
IN
element node
newAttr
IN
attribute node to add

Returns

(xmlattrnode *) replaced attribute node (or NULL)


XmlDomSetAttrNodeNS()

Adds a new attribute to an element. If an attribute with newNode's URI and localname already exists, it is replaced and the old attribute returned through oldNode. If the attribute is new, it is added to the element's list and oldNode set to NULL.

Syntax

xmlattrnode* XmlDomSetAttrNodeNS(
   xmlctx *xctx,
   xmlelemnode *elem,
   xmlattrnode *newAttr);
ParameterIn/OutDescription
xctx
IN
XML context
elem
IN
element node
newAttr
IN
attribute node to add

Returns

(xmlattrnode *) replaced attribute node [or NULL]


Entity Interface

Table 3-6 summarizes the methods available through the Entity interface.

Table 3-6 Summary of Entity Methods; DOM Package

FunctionSummary

XmlDomGetEntityNotation()


Get entity's notation.

XmlDomGetEntityPubID()


Get entity's public ID.

XmlDomGetEntitySysID()


Get entity's system ID.

XmlDomGetEntityType()


Get entity's type.



XmlDomGetEntityNotation()

For unparsed entities, returns the name of its notation (in the data encoding). For parsed entities and other node types, returns NULL.

Syntax

oratext* XmlDomGetEntityNotation(
   xmlctx *xctx,
   xmlentnode *ent);
ParameterIn/OutDescription
xctx
IN
XML context
ent
IN
entity node

Returns

(oratext *) entity's notation [data encoding; may be NULL]


XmlDomGetEntityPubID()

Returns an entity's public identifier (in the data encoding). If the node is not an entity, or has no defined public ID, returns NULL.

Syntax

oratext* XmlDomGetEntityPubID(
   xmlctx *xctx,
   xmlentnode *ent);
ParameterIn/OutDescription
xctx
IN
XML context
ent
IN
entity node

Returns

(oratext *) entity's public identifier [data encoding; may be NULL]


XmlDomGetEntitySysID()

Returns an entity's system identifier (in the data encoding). If the node is not an entity, or has no defined system ID, returns NULL.

Syntax

oratext* XmlDomGetEntitySysID(
   xmlctx *xctx, 
   xmlentnode *ent);
ParameterIn/OutDescription
xctx
IN
XML context
ent
IN
entity node

Returns

(oratext *) entity's system identifier [data encoding; may be NULL]


XmlDomGetEntityType()

Returns a boolean for an entity describing whether it is general (TRUE) or parameter (FALSE).

Syntax

boolean XmlDomGetEntityType(
   xmlctx *xctx,
   xmlentnode *ent);
ParameterIn/OutDescription
xctx
IN
XML context
ent
IN
entity node

Returns

(boolean) TRUE for general entity, FALSE for parameter entity


NamedNodeMap Interface

Table 3-7 summarizes the methods available through the NamedNodeMap interface.

Table 3-7 Summary of NamedNodeMap Methods; DOM Package

FunctionSummary

XmlDomGetNamedItem()


Return named node from list.

XmlDomGetNamedItemNS()


Return named node from list (namespace aware version).

XmlDomGetNodeMapItem()


Return nth node in list.

XmlDomGetNodeMapLength()


Return length of named node map.

XmlDomRemoveNamedItem()


Remove node from named node map.

XmlDomRemoveNamedItemNS()


Remove node from named node map (namespace aware version).

XmlDomSetNamedItem()


Set node in named node list.

XmlDomSetNamedItemNS()


Set node in named node list (namespace aware version).



XmlDomGetNamedItem()

Retrieves an item from a NamedNodeMap, specified by name (which should be in the data encoding). This is a non-namespace-aware function; it just matches (case sensitively) on the whole qualified name. Note this function differs from the DOM spec in that the index of the matching item is also returned.

Syntax

xmlnode* XmlDomGetNamedItem(
   xmlctx *xctx,
   xmlnamedmap *map,
   oratext *name);
ParameterIn/OutDescription
xctx
IN
XML context
map
IN
NamedNodeMap
name
IN
name of the node to retrieve

Returns

(xmlnode *) Node with the specified name [or NULL]


XmlDomGetNamedItemNS()

Retrieves an item from a NamedNodeMap, specified by URI and localname (which should be in the data encoding). Note this function differs from the DOM spec in that the index of the matching item is also returned.

Syntax

xmlnode* XmlDomGetNamedItemNS(
   xmlctx *xctx,
   xmlnamedmap *map, 
   oratext *uri,
   oratext *local);
ParameterIn/OutDescription
xctx
IN
XML context
map
IN
NamedNodeMap
uri
IN
namespace URI of the node to retrieve; data encoding
local
IN
local name of the node to retrieve; data encoding

Returns

(xmlnode *) node with given local name and namespace URI [or NULL]


XmlDomGetNodeMapItem()

Retrieves an item from a NamedNodeMap, specified by name (which should be in the data encoding). This is a non-namespace-aware function; it just matches (case sensitively) on the whole qualified name. Note this function differs from the DOM specification in that the index of the matching item is also returned. Named "item" in W3C specification.

Syntax

xmlnode* XmlDomGetNodeMapItem(
   xmlctx *xctx, 
   xmlnamedmap *map, 
   ub4 index);
ParameterIn/OutDescription
xctx
IN
XML context
map
IN
NamedNodeMap
index
IN
0-based index for the map

Returns

(xmlnode *) node at the nth position in the map (or NULL)


XmlDomGetNodeMapLength()

Returns the number of nodes in a NamedNodeMap (the length). Note that nodes are referred to by index, and the range of valid indexes is 0 through length-1.

Syntax

ub4 XmlDomGetNodeMapLength(
   xmlctx *xctx,
   xmlnamedmap *map);
ParameterIn/OutDescription
xctx
IN
XML context
map
IN
NamedNodeMap

Returns

(ub4) number of nodes in NamedNodeMap


XmlDomRemoveNamedItem()

Removes a node from a NamedNodeMap, specified by name. This is a non-namespace-aware function; it just matches (case sensitively) on the whole qualified name. If the removed node is an attribute with default value (not specified), it is immediately replaced. The removed node is returned; if no removal took place, NULL is returned.

Syntax

xmlnode* XmlDomRemoveNamedItem(
   xmlctx *xctx,
   xmlnamedmap *map,
   oratext *name);
ParameterIn/OutDescription
xctx
IN
XML context
map
IN
NamedNodeMap
name
IN
name of node to remove

Returns

(xmlnode *) node removed from this map


XmlDomRemoveNamedItemNS()

Removes a node from a NamedNodeMap, specified by URI and localname. If the removed node is an attribute with default value (not specified), it is immediately replaced. The removed node is returned; if no removal took place, NULL is returned.

Syntax

xmlnode* XmlDomRemoveNamedItemNS(
   xmlctx *xctx,
   xmlnamedmap *map, 
   oratext *uri,
   oratext *local);
ParameterIn/OutDescription
xctx
IN
XML context
map
IN
NamedNodeMap
uri
IN
namespace URI of the node to remove; data encoding
local
IN
local name of the node to remove; data encoding

Returns

(xmlnode *) node removed from this map


XmlDomSetNamedItem()

Adds a new node to a NamedNodeMap. If a node already exists with the given name, replaces the old node and returns it. If no such named node exists, adds the new node to the map and sets old to NULL. This is a non-namespace-aware function; it just matches (case sensitively) on the whole qualified name. Since some node types have fixed names (Text, Comment, and so on), trying to set another of the same type will always cause replacement.

Syntax

xmlnode* XmlDomSetNamedItem(
   xmlctx *xctx,
   xmlnamedmap *map,
   xmlnode *newNode);
ParameterIn/OutDescription
xctx
IN
XML context
map
IN
NamedNodeMap
newNode
IN
new node to store in map

Returns

(xmlnode *) the replaced node (or NULL)


XmlDomSetNamedItemNS()

Adds a new node to a NamedNodeMap. If a node already exists with the given URI and localname, replaces the old node and returns it. If no such named node exists, adds the new node to the map and sets old to NULL. Since some node types have fixed names (Text, Comment, and so on), trying to set another of the same type will always cause replacement.

Syntax

xmlnode* XmlDomSetNamedItemNS(
   xmlctx *xctx, 
   xmlnamedmap *map, 
   xmlnode *newNode);
ParameterIn/OutDescription
xctx
IN
XML context
map
IN
NamedNodeMap
newNode
IN
new node to store in map

Returns

(xmlnode *) replaced Node [or NULL]


Node Interface

Table 3-8 summarizes the methods available through the Node interface.

Table 3-8 Summary of Node Methods; DOM Package

FunctionSummary

XmlDomAppendChild()


Append new child to node's list of children.

XmlDomCleanNode()


Clean a node (free DOM allocations).

XmlDomCloneNode()


Clone a node.

XmlDomFreeNode()


Free a node allocated with XmlDomCreateXXX.

XmlDomGetAttrs()


Return attributes of node.

XmlDomGetChildNodes()


Return children of node.

XmlDomGetDefaultNS()


Get default namespace for node.

XmlDomGetFirstChild()


Returns first child of node.

XmlDomGetFirstPfnsPair()


Get first prefix namespace pair.

XmlDomGetLastChild()


Returns last child of node.

XmlDomGetNextPfnsPair()


Get subsequent prefix namespace pair.

XmlDomGetNextSibling()


Return next sibling of node.

XmlDomGetNodeLocal()


Get local part of node's qualified name as NULL-terminated string.

XmlDomGetNodeLocalLen()


Get local part of node's qualified name as length-encoded string.

XmlDomGetNodeName()


Get node's name as NULL-terminated string.

XmlDomGetNodeNameLen()


Get node's name as length-encoded string.

XmlDomGetNodePrefix()


Return namespace prefix of node.

XmlDomGetNodeType()


Get node's numeric type code.

XmlDomGetNodeURI()


Return namespace URI of node as a NULL-terminated string.

XmlDomGetNodeURILen()


Return namespace URI of node as length-encoded string.

XmlDomGetNodeValue()


Get node's value as NULL-terminated string.

XmlDomGetNodeValueLen()


Get node value as length-encoded string.

XmlDomGetNodeValueStream()


Returns the large data for a node and sends it in pieces to the user's output stream.

XmlDomGetOwnerDocument()


Get the owner document of node.

XmlDomGetParentNode()


Get parent node.

XmlDomGetPrevSibling()


Return previous sibling of node.

XmlDomGetPullNodeAsBinaryStream()


Returns the address of a binary stream using the pull paradigm.

XmlDomGetPullNodeAsCharacterStream()


Returns the address of a character stream using the pull paradigm.

XmlDomGetPushNodeAsBinaryStream()


Returns the address of a binary stream, as an OUT ostream parameter, using the push paradigm.

XmlDomGetPushNodeAsCharacterStream()


Returns the address of a character stream, as an OUT ostream parameter, using the push paradigm.

XmlDomGetSourceEntity()


Return the entity node if the input file is an external entity.

XmlDomGetSourceLine()


Return source line number of node.

XmlDomGetSourceLocation()


Return source location (path, URI, and so on) of node.

XmlDomHasAttr()


Does named attribute exist?

XmlDomHasChildNodes()


Test if node has children.

XmlDomInsertBefore()


Insert new child in to node's list of children.

XmlDomNormalize()


Normalize a node by merging adjacent text nodes.

XmlDomNumAttrs()


Return number of attributes of element.

XmlDomNumChildNodes()


Return number of children of node.

XmlDomPrefixToURI()


Get namespace URI for prefix.

XmlDomRemoveChild()


Remove an existing child node.

XmlDomRenameNode()


Updates the name of a node, for element and attribute nodes only.

XmlDomRenameNodeNS()


Updates the name and URI of a node, for element and attribute nodes only.

XmlDomReplaceChild()


Replace an existing child of a node.

XmlDomSetDefaultNS()


Set default namespace for node.

XmlDomSetNodePrefix()


Set namespace prefix of node.

XmlDomSetNodeValue()


Set node value.