Difference between revisions of "LlGetNotecardLineSync"

From Second Life Wiki
Jump to navigation Jump to search
m (added +1 to the count in the for loop, as the current example would never allow it to read pasted the last line of the notecard to trigger the EOF condition.)
(Added an example to fall back to the old dataserver event and use llGetNotecardLine if the NAK is returned because the notecard left the simulator cache.)
Line 56: Line 56:
                     llOwnerSay(line);
                     llOwnerSay(line);
                 }
                 }
            }
        }
    }
}
</syntaxhighlight>
Following example to call a normal [[dataserver]] notecard read using [[llGetNotecardLine]] if llGetNotecardlineSync fails with a NAK.
<syntaxhighlight lang="lsl2">
// llGetNotecardLineSync example with fall back to the old dataserver read
// if llGetNotecardLineSync fails with a NAK.
string  NOTECARD_NAME = "notecard";
key    READ_KEY = NULL_KEY;
key    noteCard_qry;
integer noteCard_line;
default
{
    state_entry()
    {
        // read the notecards number of lines to the
        // simulators cache memory
        READ_KEY = llGetNumberOfNotecardLines(NOTECARD_NAME);
    }
   
    dataserver(key request, string data)
    {
        // read notecards using the new llGetNotecardLineSync function
        // from simulator cache.
        if (request == READ_KEY)
        {
            integer count = (integer)data;
            integer index;
           
            for (index = 0; index < (count+1); ++index)
            {
                string line = llGetNotecardLineSync(NOTECARD_NAME, index);
                if (line == NAK)
                {
                    // Got a notecard NAK meaning llGetNotecardLineSync had and error.
                    // falling back to the old dataserver event to read notecards.
                    llOwnerSay("---NAK---");
                    noteCard_qry = llGetNotecardLine(NOTECARD_NAME, noteCard_line);
                    return;
                }
                else if (line == EOF)
                {
                    // End of notecard.
                    llOwnerSay("---EOF---");
                }
                else
                {
                    // do work here.
                    llOwnerSay(line);
                }
            }
        }
        // old system takes over if a NAK is encountered.
        if(request == noteCard_qry)
        {
            if(data == EOF)
            {
                // End of notecard encountered.
                llOwnerSay("EOF encountered");
            }
            else
            {
                // process normal notecard line, then read the next line
                // of the notecard.
                llOwnerSay(data);
                noteCard_qry = llGetNotecardLine(NOTECARD_NAME, ++noteCard_line);
             }
             }
         }
         }

Revision as of 10:08, 21 April 2024

Summary

Function: string llGetNotecardLineSync( string name, integer line );
0.0 Forced Delay
10.0 Energy

Gets the line of the notecard name from the region's notecard cache immediately without raising a dataserver event.
Returns the string containing the text of the requested line from the notecard.

• string name – a notecard in the inventory of the prim this script is in or a UUID of a notecard
• integer line – Line number in a notecard (the index starts at zero).

line does not support negative indexes. Returns EOF if line is past the end of the notecard.

Specification

This function returns a string containing the requested line from a notecard in prim inventory, without the need for an asynchronous dataserver event, if the notecard is cached/known in its entirety by the simulator. This speeds up acessing notecard lines tremendously, and allows for near instantaneous random access.

If the notecard does not exist it returns the constant NAK and will shout a message to the debug channel. If the notecard has not been previously cached on the simulator it will return the NAK constant.

Notecards are cached into a fixed-size buffer, with the oldest (least-recently read) notecard getting removed first. It is not safe to assume a notecard has been previously cached. Data for a previously cached notecard may be dropped from the cache at any time, especially on a busy server.

Caveats

  • If line is out of bounds the script continues to execute without an error message.
  • If name is missing from the prim's inventory and it is not a UUID or it is not a notecard then an error is shouted on DEBUG_CHANNEL.
  • If name is a UUID then there are no new asset permissions consequences for the object.
    • The resulting object develops no new usage restrictions that might have occurred if the asset had been placed in the prims inventory.
  • If name is a new empty notecard (never saved) then an error "Couldn't find notecard ~NAME~" (~NAME~ being the value of name) will be shouted on the DEBUG_CHANNEL. This is because until a notecard is saved for the first time, it does not exist as an asset only as an inventory placeholder.
  • If notecard contains embedded inventory items (such as textures and landmarks), EOF will be returned, regardless of the line requested.
  • If the requested line is longer than 1024 bytes the returned string will be truncated to the first 1024 bytes of the line.
  • A dataserver event does not get raised. Therefore, other scripts in the linkset are unaware of the processed notecard lines.

Examples

string NOTECARD_NAME = "notecard";
key READ_KEY = NULL_KEY;

default
{

    touch_start(integer total_number)
    {
        READ_KEY = llGetNumberOfNotecardLines(NOTECARD_NAME);
    }
    
    dataserver(key request, string data)
    {
        if (request == READ_KEY)
        {
            integer count = (integer)data;
            integer index;
            
            for (index = 0; index < (count+1); ++index)
            {
                string line = llGetNotecardLineSync(NOTECARD_NAME, index);
                if (line == NAK)
                {
                    llOwnerSay("---NAK---");
                }
                else if (line == EOF)
                {
                    llOwnerSay("---EOF---");
                }
                else
                {
                    llOwnerSay(line);
                }
            }
        }
    }
}

Following example to call a normal dataserver notecard read using llGetNotecardLine if llGetNotecardlineSync fails with a NAK. 

// llGetNotecardLineSync example with fall back to the old dataserver read
// if llGetNotecardLineSync fails with a NAK.

string  NOTECARD_NAME = "notecard";
key     READ_KEY = NULL_KEY;

key     noteCard_qry;
integer noteCard_line;

default
{

    state_entry()
    {
        // read the notecards number of lines to the
        // simulators cache memory
        READ_KEY = llGetNumberOfNotecardLines(NOTECARD_NAME);
    }
    
    dataserver(key request, string data)
    {
        // read notecards using the new llGetNotecardLineSync function
        // from simulator cache.
        if (request == READ_KEY)
        {
            integer count = (integer)data;
            integer index;
            
            for (index = 0; index < (count+1); ++index)
            {
                string line = llGetNotecardLineSync(NOTECARD_NAME, index);
                if (line == NAK)
                {
                    // Got a notecard NAK meaning llGetNotecardLineSync had and error.
                    // falling back to the old dataserver event to read notecards.
                    llOwnerSay("---NAK---");
                    noteCard_qry = llGetNotecardLine(NOTECARD_NAME, noteCard_line);
                    return;
                }
                else if (line == EOF)
                {
                    // End of notecard.
                    llOwnerSay("---EOF---");
                }
                else
                {
                    // do work here.
                    llOwnerSay(line);
                }
            }
        }

        // old system takes over if a NAK is encountered.
        if(request == noteCard_qry)
        {
            if(data == EOF)
            {
                // End of notecard encountered.
                llOwnerSay("EOF encountered");
            }
            else 
            {
                // process normal notecard line, then read the next line
                // of the notecard.
                llOwnerSay(data);
                noteCard_qry = llGetNotecardLine(NOTECARD_NAME, ++noteCard_line);
            }
        }
    }
}

See Also

Deep Notes

Signature

function string llGetNotecardLineSync( string name, integer line );
Retrieved from "https://wiki.secondlife.com/w/index.php?title=LlGetNotecardLineSync&oldid=1216503"