Release 10.1A: OpenEdge Development:
Programming Interfaces

> ## Progress SAX callbacks

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

> Progress SAX implements callbacks as internal procedures coded by the 4GL SAX developer using signatures specified by Progress. Normally, callbacks are placed in a procedure (`.p`) file that the application runs persistently. But callbacks can also be placed in the driver routine. A driver routine is one that calls the `SAX-PARSE()` or `SAX-PARSE-FIRST()` method. In whichever procedure callbacks are placed, the application assigns that procedure’s handle to the `SAX-reader`’s `HANDLER` attribute. (`HANDLER` defaults to a handle to the driver routine). Then, the application starts the parse.

> Note: Although there are many callbacks in the SAX2 interface, most applications use just a few. These are `StartElement`, `Characters`, and `EndElement`.

> 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`’s `STOP-PARSING()` method:

>     SELF:STOP-PARSING().

> The following fragment uses `SELF` within a callback to store data in the `SAX-reader`’s `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.

> Table 20–2 summarizes the callbacks. For complete descriptions, see the "SAX callback reference" section.

> Table 20–2: 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.

Copyright © 2005 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095