Notecards

Notecards are text in the object’s inventory. Scripts can read them but not write them, which makes them good for configuration that users edit by hand. Part of the Data Storage feature.

Concepts

llGetNotecardLine requests a line, which arrives in dataserver; lines start at 0
- A line past the end returns EOF
llGetNotecardLineSync returns a line immediately if the region has the notecard cached
- It returns NAK when the notecard is not cached; fall back to llGetNotecardLine, or read the line count first to load it into the cache
- The cache drops the least recently read notecards first, so never assume a notecard is still cached
- No dataserver event is raised, and memory is not garbage-collected inside a tight read loop
llGetNumberOfNotecardLines returns the line count through dataserver
llFindNotecardTextSync searches a cached notecard with a regular expression, returning up to 64 matches as row, column and length
Lines longer than 1024 bytes are truncated
A notecard with embedded inventory items, such as landmarks, returns EOF for every line
When a user edits the notecard, changed reports CHANGED_INVENTORY; reload the configuration then

Functions and events

`key`	`llGetNotecardLine(string name, integer line)`
`string`	`llGetNotecardLineSync(string name, integer line)`
`key`	`llGetNumberOfNotecardLines(string name)`
`list`	`llFindNotecardTextSync(string name, string pattern, integer start, integer count, list options)`
`event`	`dataserver(key queryid, string data)`

Scripting Details

`string`	`llGetNotecardLineSync(string name, integer line)` Synchronously reads the line index line of the notecard name from the region's cache, immediately returning its text without raising a dataserver event. Returns 'NAK' if not cached or 'EOF' if out of bounds.
`key`	`llGetNotecardLine(string name, integer line)` Asynchronously requests the line index line of the notecard name from the dataserver. Returns a key query handle for the dataserver event, which will return 'EOF' when reaching past the end of the notecard.
`key`	`llGetNumberOfNotecardLines(string name)` Asynchronously requests the total line count of the notecard name. Returns a key query handle for the dataserver event.
`list`	`llFindNotecardTextSync(string name, string pattern, integer start, integer count, list options)` Synchronously searches a cached notecard name for lines containing pattern, returning a list of line and column numbers. Returns a list containing 'NAK' if the notecard is not cached, or an empty list if no matches are found.
`key`	`llFindNotecardTextCount(string notecardname, string pattern, list options)` Searches the text of a cached notecard for lines containing the given pattern and returns the number of matches found through a dataserver event.
`event`	`dataserver(key queryid, string data)` Triggered when requested data is returned to the script (e.g., from llRequestAgentData, llRequestInventoryData, or llGetNotecardLine).
`event`	`changed(integer changes)` Triggered when various properties of the object change. The parameter changes is a bitfield of CHANGED_* flags.

Example

Reads a whole notecard, using the cache where possible.

string NOTECARD = "config";
integer line;
key request;

readLines()
{
    string data = llGetNotecardLineSync(NOTECARD, line);
    while (data != NAK && data != EOF)
    {
        llOwnerSay((string)line + ": " + data);
        data = llGetNotecardLineSync(NOTECARD, ++line);
    }
    if (data == NAK)
        request = llGetNotecardLine(NOTECARD, line);  // not cached: ask the dataserver
}

default
{
    state_entry()
    {
        line = 0;
        readLines();
    }

    dataserver(key id, string data)
    {
        if (id != request || data == EOF) return;
        llOwnerSay((string)line + ": " + data);
        ++line;
        readLines();
    }

    changed(integer change)
    {
        if (change & CHANGED_INVENTORY) llResetScript();
    }
}

See also Feature Data Storage Category Notecard Feature Inventory SL Wiki LSL NotecardPlanned Guide: reading a configuration notecard