Purpose
Returns a data stream containing highlighting information for the text document described by a document handle. See Data stream syntax. The highlight information comprises the text context (at least one paragraph) and information for highlighting text in that context.
DesGetMatches returns only a portion of the data stream, indicating the length of the portion in the output structure.
A sequence of calls to DesGetMatches gets the entire text document content. When the end of the text document is reached, RC_SE_END_OF_INFORMATION is returned.
Syntax
DESRETURN DesGetMatches (DESBROWSESESSION BrowseSession, DESHANDLE DocumentHandle, DESMATCHINFO *pMatchInfo, DESULONG *pMatchInfoLength, DESMESSAGE *pErrorMessage);
Function arguments
Table 11. DesGetMatches arguments
Data Type | Argument | Use | Description |
---|---|---|---|
DESBROWSESESSION | BrowseSession | input | Browse session handle. |
DESHANDLE | DocumentHandle | input | Document handle returned by DesOpenDocument. |
DESMATCHINFO * | pMatchInfo | output | Pointer to a buffer containing the data stream portion received. DesGetMatches allocates that buffer. |
DESULONG * | pMatchInfoLength | output | The length of the data stream portion pointed to by pMatchInfo. |
DESMESSAGE * | pErrorMessage | output | Implementation-defined message text. If an error occurs, Text Extender returns an error code and an error message. The application program allocates the buffer of size DES_MAX_MESSAGE_LENGTH. If pErrorMessage is the null pointer, no error message is returned. |
>>- --05-- --DB2TX_DOC-- --DB2TX_START-- -----------------------> >-----+-------------------------------------------------------------+> '- --ll-- --DB2TX_DNAM-- --DB2TX_ATOMIC-- --document_name-- --' .----------------. V | >--------| Section |---+-- --05-- --DB2TX_DOC-- --DB2TX_END-- -->< Section |--- --05-- --DB2TX_DEL-- --DB2TX_START-- ----------------------> >-----+------------------------------------------------------------+> '- --ll-- --DB2TX_SNAM-- --DB2TX_ATOMIC-- --section_name-- --' .-------------------------------------------. | .------------------. | V V | | >--------| Text encoding |-----| Paragraph |---+--+-------------> >---- --05-- --DB2TX_DEL-- --DB2TX_END-- -----------------------| Text encoding |--- --07-- --DB2TX_CCSID-- --DB2TX_ATOMIC-- --coded_character_set_identifier-- --> >--- --07-- --DB2TX_LANG-- --DB2TX_ATOMIC-- --language_identifier-- --> >---------------------------------------------------------------| Paragraph |--- --05-- --DB2TX_PAR-- --DB2TX_START-- ----------------------> .-----------------------. V | >--------| Paragraph text |---+---------------------------------> >---- --05-- --DB2TX_PAR-- --DB2TX_END-- -----------------------| Paragraph text |---+- --ll-- --DB2TX_TEXT-- --DB2TX_ATOMIC-- --text_unit-- --+-> '- --ll-- --DB2TX_LINK-- --DB2TX_ATOMIC-- --media_ref-- --' .-----------------------------------------------. V | >--------+-----------------------------------------+--+---------> '- --05-- --DB2TX_NL-- --DB2TX_ATOMIC-- --' .------------------------------------------------------------------------. V | >--------+------------------------------------------------------------------+--+> '- --ll-- --DB2TX_MATCH-- --DB2TX_ATOMIC-- --match_information-- --' >---------------------------------------------------------------|
Each segment in the syntax diagram, such as 05 DB2TX_DOC DB2TX_START begins with a length field of type integer, which in the diagram is either an explicit number, such as 05, or a variable ll. The length of the segment includes the 2-byte length field.
Note: | The length is in big-endian format. |
Each segment includes one of the following 1-byte type identifiers:
The data stream items are each two bytes long. They are:
The text uses the CCSID and language associated with the current paragraph.
These symbolic names for CCSIDs are defined in the file DES_EXT.H provided with the Text Extender. The two-byte binary values are specified in big-endian format.
Usage
DesGetMatches returns RC_SE_END_OF_INFORMATION when the end of the text document is reached.
Return codes
Restrictions
This function can be called only after you have opened a text document by calling DesOpenDocument.