Format

XML$PARSE ctx ,buffer, final

Arguments

ctx

VMS usage:	context
type:	longword (unsigned)
access:	read only
mechanism:	by reference

A longword containing an XML parser context that has previously been allocated by a call to XML$CREATE_PARSER.

buffer

VMS usage:	char_string
type:	character-coded text string
access:	read only
mechanism:	by descriptor

A string descriptor containing the XML buffer to be parsed.

final

VMS usage:	boolean
type:	longword (unsigned)
access:	read only
mechanism:	by reference

A boolean value, set if the buffer is the final buffer in the input stream.

Description

This routine parses some (or all) of the XML document. The SAX API is stream oriented, so it is not required to have the complete document at any one point. Some small XML documents will parse in a single call. However, Parse some more of the document. The string s is a buffer containing part (or perhaps all) of the document. The number of bytes of s that are part of the document is indicated by len. This means that s doesn't have to be null terminated. It also means that if len is larger than the number of bytes in the block of memory that s points at, then a memory fault is likely. The isFinal parameter informs the parser that this is the last piece of the document. Frequently, the last piece is empty (i.e. len is zero.) If a parse error occurred, it returns XML_STATUS_ERROR. Otherwise it returns XML_STATUS_OK value.

Return Values

SS$_NORMAL	Normal successful completion
SS$_INSFARG	Insufficient arguments. Check that all required arguments are present
SS$_BADPARAM	A required argument is not present. Check the passing mechanism

Format

XML$SET_BASE ctx ,base

Arguments

ctx

VMS usage:	context
type:	longword (unsigned)
access:	read only
mechanism:	by reference

A longword containing an XML parser context that has previously been allocated by a call to XML$CREATE_PARSER.

base

VMS usage:	char_string
type:	character-coded text string
access:	write only
mechanism:	by descriptor

Base to be used when resolving realtive URIs.

Description

Set the base to be used for resolving relative URIs in system identifiers.

Return Values

SS$_NORMAL	Normal successful completion
SS$_INSFARG	Insufficient arguments. Check that all required arguments are present
SS$_BADPARAM	A required argument is not present. Check the passing mechanism

Format

XML$SET_CDATA_HANDLER ctx ,start-routine ,end-routine

Arguments

ctx

VMS usage:	context
type:	longword (unsigned)
access:	read only
mechanism:	by reference

A longword containing an XML parser context that has previously been allocated by a call to XML$CREATE_PARSER.

start-routine

VMS usage:	procedure
type:	procedure value
access:	read only
mechanism:	by value

A routine to handle start CDATA section events. See XML$SET_START_CDATA_HANDLER for handler call format.

end-routine

VMS usage:	procedure
type:	procedure value
access:	read only
mechanism:	by value

A routine to handle end CDATA section events. See XML$SET_END_CDATA_HANDLER for handler call format.

Description

Set handlers for start and end CDATA section events with one call.

Return Values

SS$_NORMAL	Normal successful completion
SS$_INSFARG	Insufficient arguments. Check that all required arguments are present
SS$_BADPARAM	A required argument is not present. Check the passing mechanism

Format

XML$SET_CHARACTER_DATA_HANDLER ctx ,data-routine

Arguments

ctx

VMS usage:	context
type:	longword (unsigned)
access:	read only
mechanism:	by reference

A longword containing an XML parser context that has previously been allocated by a call to XML$CREATE_PARSER.

data-routine

VMS usage:	procedure
type:	procedure value
access:	read only
mechanism:	by value

A routine to receive character data events.

The call format for a character data handler routine is as follows:

data-routine user-data ,data

The character data is returned in the string descriptor data.

user-data is the user data pointer set by XML$SET_USER_DATA.

Description

Set a handler routine to be called when the parser encounters character data. This includes both CDATA sections and PCDATA (parsed character data). For CDATA sections the CDATA section handlers (set by XML$SET_CDATA_HANDLER will be called immediately before and after calling the handler set by this routine.

Return Values

SS$_NORMAL	Normal successful completion
SS$_INSFARG	Insufficient arguments. Check that all required arguments are present
SS$_BADPARAM	A required argument is not present. Check the passing mechanism

Format

XML$SET_COMMENT_HANDLER ctx ,comment-routine

Arguments

ctx

VMS usage:	context
type:	longword (unsigned)
access:	read only
mechanism:	by reference

A longword containing an XML parser context that has previously been allocated by a call to XML$CREATE_PARSER.

comment-routine

VMS usage:	procedure
type:	procedure value
access:	read only
mechanism:	by value

User-supplied routine to be called when the parser encounters a comment section.

The call format for a comment handler routine is as follows:

comment-routine user-data ,comment

The comment data is returned in the string descriptor comment.

user-data is the user data pointer set by XML$SET_USER_DATA.

Description

Set a handler routine to be called when the parser encounters a comment section.

Return Values

SS$_NORMAL	Normal successful completion
SS$_INSFARG	Insufficient arguments. Check that all required arguments are present
SS$_BADPARAM	A required argument is not present. Check the passing mechanism

Format

XML$SET_DEFAULT_HANDLER ctx ,default-routine ,expand

Arguments

ctx

VMS usage:	context
type:	longword (unsigned)
access:	read only
mechanism:	by reference

A longword containing an XML parser context that has previously been allocated by a call to XML$CREATE_PARSER.

default-routine

VMS usage:	procedure
type:	procedure value
access:	read only
mechanism:	by value

User-supplied routine to be called when the parser encounters which otherwise cannot be, or are not, handled, by a callback.

The call format for a comment handler routine is as follows:

default-routine user-data ,data

The argument data contains the unparse character daya.

user-data is the user data pointer set by XML$SET_USER_DATA.

expand

VMS usage:	boolean
type:	longword (unsigned)
access:	read only
mechanism:	by reference

By default, specifying the default handler inhibits the expansion of external entity references. Passing a value of 1 will ensure that external entity references continue to be expanded.

Description

Set a handler for any characters in the document which would not otherwise by handled. This includes both data for which no handlers can be set (like some kinds of DTD declarations) and data which could be reported but currently has no handler set.

The characters are passed exactly as they were present in the XML document, except that whey will be encoded in UTF-8 or UTF-16. Line boundaries are not normalized.

There is no guarantee about how characters are divided between calls to the default handler. For example, a comment might be split between multiple calls. Setting the handler with this call has the side effect of turning off expansion of references to internally defined general entities. Instead these references are passed to the default handler.

Note A byte order mark character is not passed to the default handler.

Return Values

SS$_NORMAL	Normal successful completion
SS$_INSFARG	Insufficient arguments. Check that all required arguments are present
SS$_BADPARAM	A required argument is not present. Check the passing mechanism

Format

XML$SET_DOCTYPE_HANDLER ctx ,start-routine ,end-routine

Arguments

ctx

VMS usage:	context
type:	longword (unsigned)
access:	read only
mechanism:	by reference

A longword containing an XML parser context that has previously been allocated by a call to XML$CREATE_PARSER.

start-routine

VMS usage:	procedure
type:	procedure value
access:	read only
mechanism:	by value

A routine to handle start DOCTYPE events. See XML$SET_START_DOCTYPE_HANDLER for handler call format.

end-routine

VMS usage:	procedure
type:	procedure value
access:	read only
mechanism:	by value

A routine to handle end DOCTYPE events. See XML$SET_END_DOCTYPE_HANDLER for handler call format.

Description

Set handlers for start and end DOCTYPE events with one call.

Return Values

SS$_NORMAL	Normal successful completion
SS$_INSFARG	Insufficient arguments. Check that all required arguments are present
SS$_BADPARAM	A required argument is not present. Check the passing mechanism

Format

XML$SET_ELEMENT_HANDLER ctx ,start-routine ,end-routine

Arguments

ctx

VMS usage:	context
type:	longword (unsigned)
access:	read only
mechanism:	by reference

A longword containing an XML parser context that has previously been allocated by a call to XML$CREATE_PARSER.

start-routine

VMS usage:	procedure
type:	procedure value
access:	read only
mechanism:	by value

A routine to handle start element events. See XML$SET_START_ELEMENT_HANDLER for handler call format.

end-routine

VMS usage:	procedure
type:	procedure value
access:	read only
mechanism:	by value

A routine to handle end element events. See XML$SET_END_ELEMENT_HANDLER for handler call format.

Description

Set handlers for start and end tags with one call.

Note An empty tag will generate a call to both start and end handlers (in that order).

Return Values

SS$_NORMAL	Normal successful completion
SS$_INSFARG	Insufficient arguments. Check that all required arguments are present
SS$_BADPARAM	A required argument is not present. Check the passing mechanism

Format

XML$SET_END_CDATA_HANDLER ctx ,end-routine

Arguments

ctx

VMS usage:	context
type:	longword (unsigned)
access:	read only
mechanism:	by reference

A longword containing an XML parser context that has previously been allocated by a call to XML$CREATE_PARSER.

start-routine

VMS usage:	procedure
type:	procedure value
access:	read only
mechanism:	by value

A routine to handle end CDATA section events.

The call format for an end CDATA section handler routine is as follows:

end-routine user-data

user-data is the user data pointer set by XML$SET_USER_DATA.

Description

Set a handler that is called at theend of a CDATA section.

Return Values

SS$_NORMAL	Normal successful completion
SS$_INSFARG	Insufficient arguments. Check that all required arguments are present
SS$_BADPARAM	A required argument is not present. Check the passing mechanism

Format

XML$SET_END_DOCTYPE_HANDLER ctx ,end-routine

Arguments

ctx

VMS usage:	context
type:	longword (unsigned)
access:	read only
mechanism:	by reference

A longword containing an XML parser context that has previously been allocated by a call to XML$CREATE_PARSER.

end-routine

VMS usage:	procedure
type:	procedure value
access:	read only
mechanism:	by value

Handler to be called on encountering the end of a DOCTYPE declaration.

The call format for an end DOCTYPE handler routine is as follows:

end-routine user-data

The user-data argument is the user data pointer set by XML$SET_USER_DATA.

Description

Set a handler that is called at the end of a DOCTYPE declaration, after parsing any external subset.

Return Values

SS$_NORMAL	Normal successful completion
SS$_INSFARG	Insufficient arguments. Check that all required arguments are present
SS$_BADPARAM	A required argument is not present. Check the passing mechanism

Format

XML$SET_END_ELEMENT_HANDLER ctx ,end-routine

Arguments

ctx

VMS usage:	context
type:	longword (unsigned)
access:	read only
mechanism:	by reference

A longword containing an XML parser context that has previously been allocated by a call to XML$CREATE_PARSER.

end-routine

VMS usage:	procedure
type:	procedure value
access:	read only
mechanism:	by value

A routine to handle end element events.

The call format for an end element handler routine is as follows:

end-routine user-data [,prefix] ,tag-name [,uri]

The arguments prefix, tag-name and uri constitute the qualified name of the element. If namespace processing has not been enabled then tag-name contains the complete element name and both prefix and uri are zero-length strings. If namespace processing was enabled in the call to XML$CREATE_PARSER then the element name is parsed and each part is returned in the appropriate argument. user-data is the user data pointer set by XML$SET_USER_DATA.

Description

Set handler for end (and empty) tags.

Note An empty tag will generate a call to both start and end handlers (in that order).

Return Values

SS$_NORMAL	Normal successful completion
SS$_INSFARG	Insufficient arguments. Check that all required arguments are present
SS$_BADPARAM	A required argument is not present. Check the passing mechanism