TSL_Init function

Syntax

TSL_Init(
         table_name     VARCHAR(128),
         column_name    VARCHAR(128))
returns LVARCHAR;

TSL_Init(
         table_name     VARCHAR(128),
         column_name    VARCHAR(128)
         tstamp_format  VARCHAR(25))
returns LVARCHAR;

TSL_Init(
         table_name     VARCHAR(128),
         column_name    VARCHAR(128),
         tstamp_format  VARCHAR(25),
         reject_file    VARCHAR(255))
returns LVARCHAR;

TSL_Init(
         table_name     VARCHAR(128),
         column_name    VARCHAR(128),
         log_type       INTEGER,
         log_level      INTEGER,
         logfile        LVARCHAR)
returns LVARCHAR;

TSL_Init(
         table_name     VARCHAR(128),
         column_name    VARCHAR(128),
         log_type       INTEGER,
         log_level      INTEGER,
         logfile        LVARCHAR,
         tstamp_format  LVARCHAR)
returns LVARCHAR;

TSL_Init(
         table_name     VARCHAR(128),
         column_name    VARCHAR(128),
         log_type       INTEGER,
         log_level      INTEGER,
         logfile        LVARCHAR,
         tstamp_format  LVARCHAR,
         reject_file    LVARCHAR)
returns LVARCHAR;

TSL_Init(
         table_name     VARCHAR(128),
         column_name    VARCHAR(128),
         log_type       INTEGER,
         log_level      INTEGER,
         logfile        LVARCHAR,
         tstamp_format  LVARCHAR,
         reject_file    LVARCHAR,
         where_clause   LVARCHAR)
returns LVARCHAR;

table_name

The name of the time series table. Must not contain uppercase letters. The table must contain a TimeSeries column and have a primary key.

column_name

The name of the TimeSeries column. Must not contain uppercase letters.

log_type (Optional)

The type of message log:

0 = No message log.

1 = Log all messages to the specified file.

2 = Log all messages in a queue for the loader program for retrieval by the TSL_GetFmtMessage or the TSL_GetLogMessage function.

3 = Default. Log all messages to the database server message log.

log_level (Optional)

The severity of information that is included in the message log file:

1 = Informational messages, warning messages, and error messages.

2 = Warning messages and error messages.

4 = Default. Error messages.

logfile (Optional)

If the value of the log_type argument is set to 1, the path and file name of the loader message log file. If the log_type argument is set to a value other than 1, the logfile argument is ignored.

tstamp_format (Optional)

The string that describes the format of the time stamp. The default format is: %Y-%m-%d %H:%M:%S. The string must conform to the format specified by the DBTIME environment variable, but can include a pipe character (|) between the date portion and the time portion. The pipe character indicates that the date and the time are in separate fields. For example, you can use a two-field format: %Y-%m-%d|%H:%M:%S.

reject_file (Optional)

The path and file name for storing records that were not applied. For example, records with an incorrect number of fields or a formatting error are not applied. By default, only the number of rejected records is recorded.

where_clause (Optional)

Extra predicate to append to the WHERE clause that is generated by loader. The predicate can identify a subset of time series data to load. Because the WHERE clause limits the entire loader session to a subset of time series data, use caution when you include the WHERE clause. The predicate must start with the keyword AND. For example: AND meter_id = "A100"

Usage

Use the TSL_Init function to initialize a session as part of a loader program. The TSL_Init function must be the first function that you run in your loader program. The TSL_Init function creates a global context for the loader and opens a database session. You can open more database sessions by running the TSL_Attach function. You can close a database session by running the TSL_SessionClose function. The global context remains in effect until you run the TSL_Shutdown procedure, restart the database server, drop the base table, or drop the database.

You must run the TSL_Init function within an EXECUTE FUNCTION statement. You cannot run the TSL_Init function in a SELECT statement.

If you log the loader messages to a queue, you prevent locking contention on a message log file, but you must code your loader program to run the TSL_GetFmtMessage or the TSL_GetLogMessage function to retrieve the messages.

You can view active loader sessions by running the TSL_ActiveHandles function.

Returns

• A session handle that consists of a table name and a TimeSeries column name.
• An exception or NULL if the session was not initialized.