When the XML parser encounters an XML token, ABL invokes the callback corresponding to that token—if that callback is provided by the developer. If not, the parser continues.

An ABL SAX application or a driver routine implements callbacks as internal procedures or methods coded by the ABL developer using signatures specified by ABL. An application procedure or a driver routine is the one that calls the SAX-PARSE( ) or SAX-PARSE-FIRST( ) method to start parsing the XML document.

You can place the callbacks for the SAX-Reader events in one of the following:
  • Callback procedures in a procedure (.p) file, that the application runs persistently. Your application then assigns the containing procedure's callback handle to the SAX-reader's HANDLER attribute for the SAX-Reader callback events.
  • Methods in a object-oriented ABL class (.cls) file. The object instance of the class is then created by your application and sets the SAX-Reader's EVENT-HANDLER-OBJECT attribute to the ABL object reference as the callback handle for the SAX-Reader callback events.
Note: Although there are many callbacks in the interface specified by the SAX 2.0 standard, most applications use just a few, such as StartElement, Characters, and EndElement.
The following code fragment shows an example of using a procedure in a callback context:
VAR HANDLE hHandler.
VAR HANDLE hParser.

CREATE SAX-READER hParser.

/* Run the persistent procedure that contains the callbacks */
RUN "i-sax2h.p" PERSISTENT SET hHandler.

/* Give the SAX-READER the handle to the persistent procedure */
hParser:HANDLER =  hHandler.

hParser:SET-INPUT-SOURCE("FILE", "sample.xml").

/* Parse the XML document */
hParser:SAX-PARSE( ) NO-ERROR.
The following code fragment shows an example of using an object in a callback context:
VAR HANDLE hParser. 
VAR saxcallbacksclass SaxCallbackObj.

CREATE sax-reader hParser.  

/* Instantiate the object that contains the callbacks */
SaxCallbackObj = NEW saxcallbacksclass(). 

/* Give the SAX-READER the handle to the callback object */
hParser:EVENT-HANDLER-OBJECT = SaxCallbackObj. 

hParser:SET-INPUT-SOURCE("FILE", "sample.xml").

/* Parse the XML document */
hParser:sax-parse() .
Within a callback, to get a handle to the SAX-reader object that invoked the callback, use the SELF system handle.

The following fragment uses SELF within a callback to call the SAX-reader STOP-PARSING( ) method:

SELF:STOP-PARSING( ).

The following fragment uses SELF within a callback to store data in the SAX-reader PRIVATE-DATA attribute:

SELF:PRIVATE-DATA = "xyz123".

For information on the SAX parser's current location in the XML source, use the following attributes of SAX-reader:

  • LOCATOR-COLUMN-NUMBER
  • LOCATOR-LINE-NUMBER
  • LOCATOR-PUBLIC-ID
  • LOCATOR-SYSTEM-ID
Note: These attributes are valid only within a callback.

The following table summarizes the ABL SAX callbacks. For a complete description, see SAX callback reference.

Table 1. SAX callback summary
This callback . . . Lets you . . .
ResolveEntity Tell the parser where to find an external entity
StartDocument

ProcessingInstruction

StartPrefixMapping

EndPrefixMapping

StartElement

Characters

IgnorableWhitespace

EndElement

EndDocument 		Process various XML tokens
NotationDecl

UnparsedEntityDecl 		Process notations and unparsed entities
Warning

Error

FatalError 		Handle errors