NAME

DtSearchMessages — Access and manipulate messages on the DtSearch MessageList

SYNOPSIS

#include &<Dt/Search.h>
int DtSearchHasMessages(
,
void DtSearchAddMessage(
const char *msg,
char *DtSearchGetMessages(
,
void DtSearchFreeMessages(
);

DESCRIPTION

The DtSearch online search engine may assemble detailed user messages to explain various errors and failures. These messages are designed to provide a user with enough information to correct the error. Often more than one message is assembled onto the MessageList as the result of a single API call. The calling code may also append messages to the MessageList prior to display to the user. All messages remain on the MessageList and new messages are appended to the preexisting list until the list is specifically freed by the calling code.

DtSearchHasMessages returns zero if the MessageList is empty, and returns nonzero if there are any information or error messages currently on the MessageList.

DtSearchAddMessage appends a message to the end of the MessageList. A message is defined as a zero-terminated C string.

DtSearchGetMessages returns a static text buffer containing all current messages on the MessageList. The messages are returned as a single flat, zero-terminated C string, with two ASCII linefeed characters between messages (giving the appearance of a blank line between messages). It is expected that the calling code will display the text in a message dialog box or its equivalent. The returned buffer address is valid until the next call. If the MessageList is currently empty, this function returns a pointer to an empty string.

DtSearchFreeMessages clears all messages on the MessageList. It is usually called after the user has dismissed a dialog box displaying the current messages.

SEE ALSO

DtSrAPI(3)