TSL_GetFmtMessage function

The TSL_GetFmtMessage function retrieves the specified number of messages from the loader message queue. The formatted messages include message text in English.

Syntax

TSL_GetFmtMessage(
           handle          LVARCHAR)
returns LVARCHAR;

TSL_GetFmtMessage(
           handle          LVARCHAR,
           max_messages    INTEGER)
returns LVARCHAR;

handle: The table and column name combination that is returned by the TSL_Attach function.
max_messages (Optional): The number of messages to retrieve. Default is 1.; A positive integer = The number of messages to retrieve. If the number is greater than the total number of messages in the queue, all messages are retrieved.

Usage

Use the TSL_GetFmtMessage function to retrieve loader messages as part of a loader program. To retrieve messages, the log mode must be set to 2 so that messages are sent to the loader program. The log mode is set by the TSL_Init function or reset by the TSL_SetLogMode function. You must run the TSL_GetFmtMessage function in the context of a loader session that was initialized by the TSL_Init function.

In your loader program, code the TSL_GetFmtMessage function to run until the return value is NULL, which indicates that all messages are retrieved. Run the TSL_GetFmtMessage function periodically while data is being saved to disk. The TSL_GetFmtMessage function is an iterator function. You can retrieve the messages with an SQL cursor through a virtual table.

The TSL_GetFmtMessage function returns the message text in English. The TSL_GetLogMessage function is an alternative to the TSL_GetFmtMessage function. The TSL_GetLogMessage function returns the message number and is useful if you want to provide your own message text or retrieve the message text on the client.

Returns

The specified number of messages from the loader message queue. NULL is returned when the loader message queue is empty.

The messages contain the message severity and the message text. If multiple messages are returned, messages are separated by a newline character.

Example

In the context of a loader program, the following statement retrieves three messages from the loader message queue:

EXECUTE FUNCTION TSL_GetFmtMessage('ts_data-raw_reads',3);

Info: NULL value found in the primary value <001|abc> 
Error: No entry for id <001|abc>
Info: NULL value found in the primary value <001|001>

These messages indicate problems with the values of the primary key columns. In all three messages, the primary key is a composite of three columns, but only two primary key values are supplied. The values for the two primary key columns are surrounded by brackets and separated by a | character.