Script to monitor life of known Teleporters. More...

Functions
	rdWriteStatusNotercard ()
	Write a Scan's results to the Status Notecard.
integer	rdConvertTrueFalse (string TrueFalseString)
	Convert "True/False" string into an integer.
integer	rdCalcCommsChannel ()
	rdReadConfigNotecard (string NotecardName)
	rdsScanDestinationDatabase ()
	Scan the Teleporters in the database.
	rdStateEntry ()
	Routine to call to initialise the Script.

Variables
string	VERSION_STRING = "1.0.0"
string	CONFIG_NOTECARD_NAME = "teleport_destination_monitor.conf"
string	STATUS_NOTECARD_NAME = "teleport_monitor.txt"
	The name of the notcard holding the results.
string	DATABASE_INTERFACE = "DATABASE_INTERFACE"
	The Identifier for the Database Interface URL.
string	MONITOR_INTERVAL = "MONITOR_INTERVAL"
	The configuration prompt for the monitoring interval.
string	LIFE_TIME = "LIFE_TIME"
	The configuration prompt for the Teleporer LifeTime in the database.
string	SCAN_ONLY = "SCAN_ONLY"
	The configuratin prompt for the Scan-only or delete if expired flag.
string	IN_WORLD_ONLY = "IN_WORLD_ONLY"
	Configuration Setting Flag.
string	COMMENT_PREAMBLE = "//"
integer	COMMENT_PREAMBLE_LENGTH = 2
float	SECONDS_PER_HOUR = 3600.0
	The number of seconds in an hour.
float	MINIMUM_INTERVAL = 1800.0
	Minimum internval between scans.
float	MINIMUM_LIFETIME = 0.5
	Minimum time before a telepoter is off-line.
vector	WHITE_COLOUR = <1.0, 1.0, 1.0>
	The RGB values for the colour white.
float	SOLID_ALPHA = 1.0
	Alhpa valid for non-transparent text.
float	monitor_interval = 7200
	Interval between scans in seconds.
float	lifetime = 24
	This is maximum time between heartbeats for a working teleporter.
string	location_world
integer	in_world_scan_only = FALSE
string	database_interface
	The HTTP address for invoking the php script to do the scanning & deleting.
key	scan_key
	The key to link the HTTP Request to the HTTP Response.
list	scan_list
integer	scan_only = TRUE
	A flag to request a scan for dead teleporter but without deleteing them.

Detailed Description

Script to monitor life of known Teleporters.

Version: 1.0.0

Date: 05-January-2025

Author: River Drifter @ little-sense.au:9000 \email river.nosp@m._dri.nosp@m.fter@.nosp@m.auss.nosp@m.iebro.nosp@m.adba.nosp@m.nd.co.nosp@m.m.au

NOTE: The file extension ".osl" indicates the script uses the Open Simulator Script language (OSSL) and will not function in the Second Life environment. If the script will function using just the Linden Scripting Language (LSL), it will have a a file extension of ".lsl".

Definition in file teleport_destination_monitor.osl.

Function Documentation

◆ rdCalcCommsChannel()

integer rdCalcCommsChannel ( )

Definition at line 265 of file teleport_destination_monitor.osl.

{
    integer random_value = 0x80000000 | (integer)llFrand(65536) | ((integer)llFrand(65536) << 16);
    return(random_value);
}

◆ rdConvertTrueFalse()

integer rdConvertTrueFalse ( string TrueFalseString )

Convert "True/False" string into an integer.

Parameters

The	String to convert

Returns: TRUE or FALSE value

This routine is case insensitive when converting the string into a TRUE or FALSE value. For simplicity, only a "true" string will be converted into TRUE, while any other string or null string will default to FALSE. The string is trimmed or leading and trailing spaces and folded to upper case before testing.

Definition at line 252 of file teleport_destination_monitor.osl.

{
    string temp = llToUpper(llStringTrim(TrueFalseString, STRING_TRIM));
    if (temp == "TRUE") return TRUE; else return FALSE;
}

Referenced by rdReadConfigNotecard().

Here is the caller graph for this function:

◆ rdReadConfigNotecard()

rdReadConfigNotecard ( string NotecardName )

Definition at line 278 of file teleport_destination_monitor.osl.

{
    // Read the Configuration File into a List of Lines
    string config = osGetNotecard(NotecardName);
    list config_data = llParseString2List(config, ["\n"], []);
    
    // Process each line in the Configuration Data
    integer index = 0;
    integer list_length = llGetListLength(config_data);
    for (; index < list_length; ++index)
    {
        // Trim line of  Leading and Trailing Spaces
        string trimmed_line = llStringTrim(llList2String(config_data, index), STRING_TRIM);
        
        // Only Process lines that are not a comment line or blank
        if ( (llGetSubString(trimmed_line, 0, COMMENT_PREAMBLE_LENGTH - 1) != COMMENT_PREAMBLE) && (trimmed_line != "") )
        {
            // Parse Line for a Configuration Field.
            list key_value = llParseString2List(trimmed_line, ["="], []);
             
            // Fold the Trimmed Key into upper case, to eliminate errors where the case is wrong in the config file.
            string key_object = llToUpper(llStringTrim(llList2String(key_value, 0), STRING_TRIM));
       
            // Trim the Value to remove leading and training spaces
            string value_object = llStringTrim(llList2String(key_value, 1), STRING_TRIM);
             
            // Process the Key-Value Pairs to Set Configuration
            if (key_object == DATABASE_INTERFACE)    database_interface = value_object;
            else if (key_object == MONITOR_INTERVAL) monitor_interval = (float)value_object * SECONDS_PER_HOUR; // Convert hours to seconds
            else if (key_object == LIFE_TIME)        lifetime = (float)value_object; // Time in Hours
            else if (key_object == SCAN_ONLY)        scan_only = rdConvertTrueFalse(value_object);
            else if (key_object == IN_WORLD_ONLY)   in_world_only = rdConvertTrueFalse(value_object);
        }
    }
    
    // Make sure the time is at least 30 minutes
    if (monitor_interval < MINIMUM_INTERVAL) monitor_interval = MINIMUM_INTERVAL;
    if (lifetime < MINIMUM_LIFETIME) lifetime = MINIMUM_LIFETIME;
}

References COMMENT_PREAMBLE, COMMENT_PREAMBLE_LENGTH, DATABASE_INTERFACE, database_interface, IN_WORLD_ONLY, LIFE_TIME, lifetime, MINIMUM_INTERVAL, MINIMUM_LIFETIME, MONITOR_INTERVAL, monitor_interval, rdConvertTrueFalse(), SCAN_ONLY, scan_only, and SECONDS_PER_HOUR.

Referenced by rdStateEntry().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ rdsScanDestinationDatabase()

rdsScanDestinationDatabase ( )

Scan the Teleporters in the database.

This routine send a trigger message the php script telling it to scan the teleporter table to see if any of the teleporters have timed out due to missed heartbeat messages from the teleporter. The routine also tells the php script whether to just report that a time-out hac occured, or to also delete timed out entries from the database table.

It should be noted that the php routine is also used to register and update teleporters that send their own heartbeat messages. Thw action taken by the php routine depend on the type of command sent to it.

If a teleporter was deleted as having timed out and is restored to operation, it will be treated as a new database and automatically put back in the database for inclusion in the destination lists sent to each teleporter when it next sends a heartbeat message.

Definition at line 334 of file teleport_destination_monitor.osl.

{
        // If only the world in which this script is located is to be scanned, include the world,
        // otherwise, show a false world to indicate all teleporters should be included.
        if (in_world_only == TRUE) world_state = location_world; else world_state = "###";
         
        // Find out the information about the object requesting a scan from the php script
        key controller_key = llGetKey();
        list details = llGetObjectDetails(controller_key, [OBJECT_OWNER, OBJECT_GROUP]);
 
        // Create the Heartbeat message that this object sends out
        string heartbeat_message = database_interface + "?command=scan"
                                + "&key="        + controller_key
                                + "&owner="      + llList2String(details, 0)
                                + "&group="      + llList2String(details, 1)
                                + "&onlyscan="   + (string)scan_only
                                + "&lifetime="   + (string)lifetime
                                + "&version="    + VERSION_STRING
                                + "&world="      + world_state;
                                
        // Send the heartbeat message to the php routine on the web server
        scan_key = llHTTPRequest(heartbeat_message, [], [""]);
}

References database_interface, lifetime, location_world, scan_key, scan_only, and VERSION_STRING.

Referenced by rdStateEntry().

Here is the caller graph for this function:

◆ rdStateEntry()

rdStateEntry ( )

Routine to call to initialise the Script.

Definition at line 363 of file teleport_destination_monitor.osl.

{
    // Get the Name of the World
    location_world = llGetSubString(osGetGridHomeURI(), 7, -1);
 
    // Load the Configuration Notecard
    rdReadConfigNotecard(CONFIG_NOTECARD_NAME);
 
    // Trigger a Scan & Purge of the Destinations Database
    rdsScanDestinationDatabase();
 
    // Set the Timer Event to Trigger a check of the Database for expired Teleporters.
    llSetTimerEvent(monitor_interval); 
}

References CONFIG_NOTECARD_NAME, location_world, monitor_interval, rdReadConfigNotecard(), and rdsScanDestinationDatabase().

Here is the call graph for this function:

◆ rdWriteStatusNotercard()

rdWriteStatusNotercard ( )

Write a Scan's results to the Status Notecard.

If there is not an existing Status Notecard, it will create a new one and including the results. If there is an existing Status Notecard, it wil append the new results to the end of the existing Notecard.

Definition at line 194 of file teleport_destination_monitor.osl.

{
    string header_string;
    list ScanList;
    
    // Check to see if there already is a Status Notecard
    integer result = llGetInventoryType(STATUS_NOTECARD_NAME);
    
    // If there is no Notecard, Start a new one with this Header
    if (result == INVENTORY_NONE)
    {
        header_string  = "//###################################################################\n";
        header_string += "//###################################################################\n";
        header_string += "//## File: Teleport_Monitor.txt\n";
        header_string += "//## Author: River Drifter (river_drifter@aussiebroadband.com.au\n";
        header_string += "//## Contact: river_drifter@aussiebroadband.com.au\n";
        header_string += "//###################################################################\n";
        header_string += "//## This notecard contains a list of Teleporters that have\n";
        header_string += "//## exceeded their LIFE_TIME which indicates that the Teleporter\n";
        header_string += "//## may have failed and has been removed from the Teleport table.\n";
        header_string += "//## It the teleporter was restarted, the teleporter will be\n";
        header_string += "//## restored to the table.\n";
        header_string += "//## Monitor Version:" + VERSION_STRING + "\n";
        header_string += "//## Started: " + llGetTimestamp() + "\n";
        header_string += "//###################################################################\n";
        header_string += "//###################################################################\n";
    }
    
    // Otherwise Read the existing Status Notecard and prepend it to the new list
    else
    {
        // Read the Existing Status Notecard into the Header String
        header_string = osGetNotecard(STATUS_NOTECARD_NAME);
        
        // Delete the Existing Notecard 
        llRemoveInventory(STATUS_NOTECARD_NAME);
        llSleep(0.1);
    }
    
    // Prepend the Header to the List of Teleporters
    ScanList = [header_string] + scan_list;
            
    // Write the Teleport List to a New Notecard
    osMakeNotecard(STATUS_NOTECARD_NAME, ScanList);
}

References scan_list, STATUS_NOTECARD_NAME, and VERSION_STRING.

Variable Documentation

◆ COMMENT_PREAMBLE

string COMMENT_PREAMBLE = "//"

Definition at line 68 of file teleport_destination_monitor.osl.

◆ COMMENT_PREAMBLE_LENGTH

integer COMMENT_PREAMBLE_LENGTH = 2

Definition at line 74 of file teleport_destination_monitor.osl.

◆ CONFIG_NOTECARD_NAME

string CONFIG_NOTECARD_NAME = "teleport_destination_monitor.conf"

Definition at line 26 of file teleport_destination_monitor.osl.

◆ DATABASE_INTERFACE

string DATABASE_INTERFACE = "DATABASE_INTERFACE"

The Identifier for the Database Interface URL.

The Configuration File Identifier for the Database Interface URL.

The configuration prompt for the database URL.

Definition at line 38 of file teleport_destination_monitor.osl.

Referenced by rdReadConfigNotecard().

◆ database_interface

string database_interface

The HTTP address for invoking the php script to do the scanning & deleting.

The address of the database interface.

Definition at line 160 of file teleport_destination_monitor.osl.

Referenced by rdReadConfigNotecard(), rdSendHeartbeatMessage(), and rdsScanDestinationDatabase().

◆ IN_WORLD_ONLY

string IN_WORLD_ONLY = "IN_WORLD_ONLY"

Configuration Setting Flag.

Definition at line 62 of file teleport_destination_monitor.osl.

Referenced by rdReadConfigNotecard().

◆ in_world_scan_only

integer in_world_scan_only = FALSE

Definition at line 153 of file teleport_destination_monitor.osl.

◆ LIFE_TIME

string LIFE_TIME = "LIFE_TIME"

The configuration prompt for the Teleporer LifeTime in the database.

Definition at line 50 of file teleport_destination_monitor.osl.

Referenced by rdReadConfigNotecard().

◆ lifetime

float lifetime = 24

This is maximum time between heartbeats for a working teleporter.

If the last heartbeat was detected more than this time in the past, the teleporter is considered to be off-line.

Definition at line 135 of file teleport_destination_monitor.osl.

Referenced by rdReadConfigNotecard(), and rdsScanDestinationDatabase().

◆ location_world

string location_world

Definition at line 144 of file teleport_destination_monitor.osl.

◆ MINIMUM_INTERVAL

float MINIMUM_INTERVAL = 1800.0

Minimum internval between scans.

Definition at line 87 of file teleport_destination_monitor.osl.

Referenced by rdReadConfigNotecard().

◆ MINIMUM_LIFETIME

float MINIMUM_LIFETIME = 0.5

Minimum time before a telepoter is off-line.

The minimum time that can be set is 30 minutes (0.5 hours), but so short a duration should only be used when teleporters are being removed by the owner to ensure that the database is updated quickly.

If the simulation does not run continuously, the minimum lifetime should at least be the longest period that the simulator does not run, plus two times the monitor interval to ensure that working teleporters are not temporarily removed when the system starts.

Definition at line 101 of file teleport_destination_monitor.osl.

Referenced by rdReadConfigNotecard().

◆ MONITOR_INTERVAL

string MONITOR_INTERVAL = "MONITOR_INTERVAL"

The configuration prompt for the monitoring interval.

Definition at line 44 of file teleport_destination_monitor.osl.

Referenced by rdReadConfigNotecard().

◆ monitor_interval

float monitor_interval = 7200

Interval between scans in seconds.

This parameter is initially set at 2 hours, but this can be overwritten by the configuration parameters.

Initially this period is set at 2 hours, but can be changed by the configuration parameters. The accuracy of long term timers is low, but this is not considered important as the exact interval is not critical.

Definition at line 126 of file teleport_destination_monitor.osl.

Referenced by rdReadConfigNotecard(), and rdStateEntry().

◆ scan_key

key scan_key

The key to link the HTTP Request to the HTTP Response.

Definition at line 166 of file teleport_destination_monitor.osl.

Referenced by rdsScanDestinationDatabase().

◆ scan_list

list scan_list

Definition at line 175 of file teleport_destination_monitor.osl.

Referenced by rdWriteStatusNotercard().

◆ SCAN_ONLY

string SCAN_ONLY = "SCAN_ONLY"

The configuratin prompt for the Scan-only or delete if expired flag.

Definition at line 56 of file teleport_destination_monitor.osl.

Referenced by rdReadConfigNotecard().

◆ scan_only

integer scan_only = TRUE

A flag to request a scan for dead teleporter but without deleteing them.

This flag will scan the teleporter database for teleporters who have not been reporting for longer than the set LIFE_TIME. It will report theses teleporters, but it will not remove them from the database.

Definition at line 185 of file teleport_destination_monitor.osl.

Referenced by rdReadConfigNotecard(), and rdsScanDestinationDatabase().