Characters

Syntax

Invoked when the XML parser detects character data.

Procedure

PROCEDURE Characters:
  DEFINE INPUT PARAMETER charData AS { MEMPTR | LONGCHAR}.
  DEFINE INPUT PARAMETER numChars AS INTEGER.
  ...
END PROCEDURE.

Method

METHOD PUBLIC VOID Characters(INPUT charData AS LONGCHAR, 
                              INPUT numChars AS INTEGER): 
  ... 
END METHOD.

charData

A MEMPTR or LONGCHAR that contains a chunk of character data.

numChars

The number of characters contained in the MEMPTR.

Note: If a character requires more than one byte to encode, the value of numChars might not match the value returned by MEMPTR:GETSIZE( ).

The parser calls Characters to report each chunk of character data. It might report contiguous character data in one chunk, or split it into several chunks. If validation is enabled, whitespace is reported by the IgnorableWhitespace callback.

Although this callback is intended to be called by the parser, the application can call Characters directly. Whoever calls Characters must free the charData MEMPTR. When ABL calls Characters, the AVM is responsible for freeing the charData MEMPTR (although if the application frees it, no harm results). If the application calls Characters, the application is responsible for freeing the charData MEMPTR.

To copy the charData MEMPTR such that the memory used by the copy is completely separate from the memory used by the original, use ABL assignment, which performs a deep copy. The following fragment demonstrates this:

memptrA = memptrB

For more information on ABL assignment, see ABL Reference.