TSL_GetLogMessage function

The TSL_GetLogMessage function retrieves the specified number of messages from the loader message queue. The messages do not include message text.

Syntax

TSL_GetLogMessage(
           handle          LVARCHAR)
returns LVARCHAR;

TSL_GetLogMessage(
           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_GetLogMessage 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_GetLogMessage function in the context of a loader session that was initialized by the TSL_Init function.

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

The TSL_GetLogMessage function returns the message ID number, but not the message text. To obtain the message text, you can use one of the following methods:

Run the TSL_MessageSet function. The TSL_MessageSet() function returns the message text in English. You can reduce processing on the database server by retrieving all message texts in a table, copying the table to your client computers, and then querying the table on the clients.
You can provide your own message text either on the database server or on clients, in any language and format that you want and then querying for your message text.

The TSL_GetFmtMessage function is an alternative to the TSL_GetLogMessage function. The TSL_GetFmtMessage function returns the message text in English instead of the message ID number.

Returns

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

The messages have the following format:

TSL|message_id|message_level|message_parameters

message_id: A number that indicates the message number.
message_level: The level of severity of the message:; 1 = Information; 2 = Warning; 4 = Error
message_parameters: One or more values, which are separated by | characters, that provide specific information about the issue that generated the message. For example, a primary key value.

If multiple messages are returned, messages are separated by a ? character.

Examples

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

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

TSL|110|4|6?TSL|110|4|7?TSL|110|4|8

The three messages have the same message number: 110. The following statement returns the text for message 110:

SELECT * FROM TABLE(TSL_MessageSet()) AS m WHERE message_id =110;

message_id           msg
110                  No entry for id <%s>

These messages indicate problems with the primary key column. The messages indicate that the primary key values of 6, 7, and 8 were not found in the time series table. The data for these primary key values was not loaded.

If the primary key is a composite of more than one column, the values for the primary key columns are separated by | characters, for example:

TSL|110|4|001|abc

This example has two primary key columns. The first column in the primary key has a value of 001 and the second column has a value of abc.