2.9 Parsing DTDs

• Supporting the XInclude specification.
• Delaying further processing until additional information is available from another source.
• Adjusting processor load as task priorities shift within an application.
• Stopping parsing completely (simply free the parser instead of resuming in the outer parsing loop). This can be useful if an application-domain error is found in the XML being parsed or if the result of the parse is determined not to be useful after all.

To take advantage of this feature, the main parsing loop of an application needs to support it specifically. An application that uses this feature for a single parser will have a similar appearance to the the BASIC code in Example 2-6.

Example 2-6 Resumable Parse Loop

...the above code is reached by going XML$STOP_PARSER... 

The routines described in this section are the native programming interface. All these routines adhere to the OpenVMS Calling Standard by using reference arguments, descriptors and other OpenVMS specific features.

3.1 Retrieving message text

Unlike the portable parser API, there is no routine to retrieve the error string associated with a parser status code. Instead, all native API calls return status codes that conform to the OpenVMS condition value format. The $GETMSG or $PUTMSG system services can then be used to retrieve and display message text associated with these condition values.

Format

XML$CALL_DEFAULT_HANDLER ctx

Arguments

ctx

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

Longword into which the newly created XML parser context is written. Once finished with the XML parser context, it must be freed using the routine XML$FREE_PARSER.

Description

This routine can only be called from any of the following even handlers:

• start element;
• end element;
• processing instruction; and
• character data.

Calling this routine causes the corresponding markup to be passed to the default handler set by XML$SET_DEFAULT_HANDLER. If no handler is set, no action is performed.

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$CREATE_PARSER ctx ,[encoding] ,[separator] ,[flags] ,[malloc] ,[realloc] ,[free]

Arguments

ctx

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

Longword into which the newly created XML parser context is written. Once finished with the XML parser context, it must be freed using the routine XML$FREE_PARSER.

encoding

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

Optional. The character encoding for to use when processing this document. XMLRTL includes builtin support for the encodings shown below.

• US-ASCII
• UTF-8
• UTF-16
• ISO-8859-1

Any other value will invoke a call to the handler configured by <REFERENCE>(nat_set_unknown_encoding_handler).

separator

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

Optional. A single character that specifies the namespace separator. Specifying this argument causes the new parser to enable namespace processing. Namespace expanded element names are returned as a concatenation of the namespace URI, separator, and the local part of the name. This means that separator should be a character that can not be part of a URI. Since XMLRTL does does not check namespace URIs for conformance, the only safe choice for a namespace separator is a character that is illegal in XML. For instance, %xFF is not legal in UTF-8 and %xFFFF is not legal in UTF-16. There exists a special case when separator is a null string (has a length of 0). The namespace URI and the local part will be concatenated without and separator - this is intended to support RDF processors. It is a programming error to use the null separator with namespace triplets.

flags

VMS usage:
type:
access:	read only
mechanism:	by reference

* * flags * XML$M_CTX_AS_HANDLER_ARG

Description

This routine creates a new XML parser context.

Format

XML$GET_BASE ctx ,base [,length]

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 used when resolving realtive URIs.

length

VMS usage:	word_unsigned
type:	word (unsigned)
access:	write only
mechanism:	by reference

Optional. Address of an unsigned word to receive the length of the string in base.

Description

Get the base 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$GET_USER_DATA ctx ,user_data

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.

user_data

VMS usage:	user_arg
type:	unspecified
access:	unspecified
mechanism:	by reference

Address of a longword to receive the user data pointer.

Description

This routine retrieves the user data pointer maintained within the parser instance context.

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$FREE_PARSER ctx

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.

Description

This routine frees all memory used by the parser, including any memory allocated using the functions XML$MALLOC, XML$REALLOC and XML$FREE. It is the responsibility of the caller to free any memory associated with user specified context, configured by XML$SET_USER_DATA.

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$FREE ctx ,ptr

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.

ptr

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

Address of a memory region to be returned to the heap.

Description

Free a block of memory pointed to by ptr. The block must have been allocated by XML$MALLOC or XML$REALLOC using the same value for ctx.

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$GET_PARSING_STATUS ctx ,code ,[resultant-value] ,[resultant-string] ,[resultant-length]

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.

code

VMS usage:	longword_signed
type:	longword (signed)
access:	read only
mechanism:	by reference

Item code specifying the item of information being requested. The code arguments is the address of a signed longword containing the item code.

resultant-value

VMS usage:	varying_arg
type:	unspecified
access:	write only
mechanism:	by reference

Numeric value of the information requested. The resultant-value argument is the address of a longword or quadword into which XML$GET_PARSING_STATUS writes the numeric value of this information.

resultant-string

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

String representation of the information requested. The resultant-string argument is the address of a character string descriptor to receive the string representation,

If this argument is not included and the requested information requires it, the condition code SS$_BADPARAM will be returned.

resultant-length

VMS usage:	word_unsigned
type:	word (unsigned)
access:	write only
mechanism:	by reference

Number of characters written to resultant-string. This is particularly useful when passing a fixed length string descriptor.

Description

This routine retrieves information about the current status of the parser instance specified by ctx. Table 3-1 details possible values for code and where to exprect the results.

Table 3-1 XML$GET_PARSING_STATUS Item Codes

Item Code	Description	resultant-value	resultant-string
XML$_BUFFER	Returns a copy of the parser input buffer		x
XML$_OFFSET	A byte offset in the data buffer returned by XML$_BUFFER referring to the parsers position. This can be misleading in multi-buffer parses as offset may point outside of the buffer.	x	x
XML$_COLUMN	The offset from the beginning of the current line	x	x
XML$_BYTE_COUNT
XML$_BYTE_INDEX
XML$_LINE	The current line number position.	x	x
XML$_STATE	The current parser state. The following table indicates possible value. Constant Description XML$_K_STATE_INITIALIZED The parser instance has not begun parsing. XML$K_STATE_PARING	x
XML$_FINAL	The buffer being parsed is the last as indicated by the final argument of XML$CREATE_PARSER.	x	x

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$MALLOC ctx ,ptr

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.

ptr

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

Address of a memory region to be returned to the heap.

Description

Allocate size bytes of memory using the allocator configured by the parser context, ctx.

Note Storage allocated using this routine must be freed or reallocated using either XML$FREE or XML$REALLOC, respectively.

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.
XML$_NO_MEMORY	Insufficient virtual memory.

Format

XML$REALLOC ctx ,optr ,size ,nptr

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.

ptr

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

Address of a memory region to be returned to the heap.

Description

Re-size the virtual memory region pointed at by optr to size bytes. It is possible this call will result in a new region being allocated. Whether re-allocated or not the address in nptr is what the caller should use to reference this region following a successful call.

Note The virtual addresses passed to this routine must have all been freed and allocated using XML$MALLOC, XML$REALLOC and XML$FREE.

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.
XML$_NO_MEMORY	Insufficient virtual memory.