Kednos' XML Support Run-Time Library
User Guide & Release Notes
Previous Contents

XML$SET_END_NAMESPACE_HANDLER

Format

XML$SET_END_NAMESPACE_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 namespace declaration events.

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


end-routine  user-data ,prefix

prefix is the namespace prefix of the terminating tag. user-data is the user data pointer set by XML$SET_USER_DATA.

Description

Set a handler to be called when leaving the scope of a namespace declaration. This will be called, for each namespace declaration, after the handler for the end tag of the element in which the namespace was declared.

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$SET_NAMESPACE_HANDLER

Format

XML$SET_NAMESPACE_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 namespace events. See XML$SET_START_NAMESPACE_HANDLER for handler call format.

end-routine


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

A routine to handle end namespace events. See XML$SET_END_NAMESPACE_HANDLER for handler call format.

Description

Set handlers for start and end namespace 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

XML$SET_START_CDATA_HANDLER

Format

XML$SET_START_CDATA_HANDLER ctx ,start-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.

The call format for a start CDATA section handler routine is as follows: 


start-routine  user-data

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

Description

Set a handler that is called at the beginning of a CDATA section. Between this event and the ending CDATA section event (the handler can be set using <REFERENCE>(nat_set_cdata_end_handler)) all data returned by the handler set by <REFERENCE>(nat_xml_set_character_data) is unparsed character 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

XML$SET_START_DOCTYPE_HANDLER

Format

XML$SET_START_DOCTYPE_HANDLER ctx ,start-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.

The call format for a start DOCTYPE handler routine is as follows: 


start-routine  user-data ,name ,sysid ,pubid ,has-subset

The name is passed by string descriptor and contains the DOCTYPE name. sysid and pubid contain the system and public identifiers, respectively and can both be null strings. If has-subset is set the DOCTYPE declaration has an internal subset. user-daya is the user data pointer set by XML$SET_USER_DATA.

Description

Set a handler that is called at the start of a DOCTYPE declaration, before any external or internal subset is parsed.

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$SET_START_ELEMENT_HANDLER

Format

XML$SET_START_ELEMENT_HANDLER ctx ,start-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.

The call format for a start element handler routine is as follows: 


start-routine  user-data [,prefix] ,tag-name [,uri] ,attribute-list ,id ,default

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. Any attributes associated with this element are returned in attribute-list. This array is passed by Non-Contiguous Array (NCA) descriptor. The examples below demonstrate declaring this argument in different languages. The id argument is the address of a longword containing the position of the id attribute in attribute-list. If this attribute is not present the value is -1. specified contains the the index in attributes-list at which attributes are supplied by any ATTLIST declarations. Lastly, user-data is the user data pointer set by XML$SET_USER_DATA.

The following examples show stub routines that could be used as start element handlers in a number of languages. 


        subroutine start_element(userdata, prefix, name, uri, atts, id, specified) 
 
        integer*4 userdata 
        character*(*) prefix 
        character*(*) name 
        character*(*) uri 
        character*(*) atts(*) 
        integer*4 id 
        integer*4 specified 
 
        end

Fortran 


sub start_element(long userdata by value,      & 
                  string prefix by desc,       & 
                  string name by desc,         & 
                  string uri by desc,          & 
                  string atts() by desc,       & 
                  long id by ref,              & 
                  long specified by ref) 
 
end sub

BASIC 


start_element: procedure(userdata, prefix, name, uri, atts, id, specified) 
    declare userdata pointer; 
    declare (prefix, name, uri) character(*); 
    declare atts(*) character(*); 
    declare id fixed binary(31); 
    declare specified fixed binary(31); 
 
end start_element;

PL/I

Pascal

Description

Set handler for start (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

XML$SET_START_NAMESPACE_HANDLER

Format

XML$SET_START_NAMESPACE_HANDLER ctx ,start-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 namespace declaration events.

The call format for a start namespace declaration handler routine is as follows: 


start-routine  user-data ,prefix ,uri

The arguments prefix and uri consist of the prefix applied to the start tag and the URI extraced from the attribute named prefix in the attribute list of the start tag. Lastly, user-data is the user data pointer set by XML$SET_USER_DATA.

Description

Set a handler to be called when a namespace is declared. Namespace declarations occur inside start tags. The namespace declaration start handler is called before the start tag handler for each namespace declared in that start tag.

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$SET_USER_DATA

Format

XML$SET_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 value

Longword contains the value to be passed to all callback handler routines. It is entirely up to the user what this longword contains.

Description

This routine sets 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

XML$SET_XML_DECL_HANDLER

Format

XML$SET_XML_DECL_HANDLER ctx ,decl-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.

decl-routine


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

A handler routine to be called when the parser encounters an XML declaration.

The call format for an XML declaration handler routine is as follows: 


decl-routine  user-data ,version ,encoding ,standalone

user-data is the user data pointer set by XML$SET_USER_DATA. The version, encoding and standalone arguments correspond to the XML declaration parameters of the same names. The standalone may be one of the values described in the table below.

Table 3-2 standalone argument values
Value Description
-1 No standalone parameter in the declaration.
0 Standalone parameter was present and set to "no".
1 Standalone parameter was present and set to "yes".

The way to distinguish between XML and text declarations is the version parameter will be a null string for text declarations. The encoding parameter may be NULL for an XML declaration.

The following example demonstrates a handler routine, written in PL/I, that writes information about the XML declaration to SYS$OUTPUT. 


xmldecl_handler: procedure(userData, 
                           version, 
                           encoding, 
                           standalone); 
/*++ 
 * Functional Description: 
 *      This handler is called by the XML parser as a result of encountering 
 *      an XML document declaration, similar to: 
 * 
 *          <?xml version="1.0" encoding="UTF-8"?> 
-*/ 
 
%include $stsdef; 
 
    declare userData            pointer value; 
    declare version             character(*); 
    declare encoding            character(*); 
    declare standalone          bit(1) aligned; 
 
    put skip list('XML Declaration: version = ' || version || '; ' || 
                                   'encoding = ' || encoding || '; ' || 
                                   'standalone ' || standalone); 
    if (version ^= '1.0') then do; 
        put skip list('Error: XML version is not 1.0'); 
 
        sts$value = xml$stop_parser(parser); 
    end; 
 
end xmldecl_handler;

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

XML$STOP_PARSER

Format

XML$STOP_PARSER ctx ,[resumable]

Description

Stops parsing, causing XML$PARSE to return. This routine must be * called from within a call-back handler, except when aborting (when * resumable is clear) an already suspended parser. Some * call-backs may still follow because they would otherwise get lost, * including: *

This can be called from most handlers, including DTD-related callbacks, except when parsing an external entity and resumable is set.

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

Previous Next Contents