All ARES components and programs use Linkset Data for non-volatile memory. This is a new form of secondary script memory added by Linden Lab to Second Life in late 2022, which is is attached to the root link of an object. At present it holds 128 kilobytes of text, and can be accessed synchronously (that is, without waiting for a response from the asset server or another script), making it more convenient than traditional data solutions like memory scripts, read-only notecard parsing, or an external web server. (It is also considerably more flexible than the key-value store offered with Experiences, since Experiences are still land-scope only.)
JSON
Linkset Data is a key-value store, which means a programmer can create numerous entries, each of which must have a unique name, or key. Since storing the names themselves takes space, ARES groups related settings into single entries using JSON. For example, an unstructured database might look like this:
| interface.compass.enabled | 1 |
|---|---|
| interface.compass.offset | <0, 0, 470> |
| interface.gauges.offset | <0, 0, -468> |
| interface.height | 1008 |
Storing each entry separately would take up valuable memory repeating "interface" and "compass" unnecessarily. Using JSON, ARES stores this, instead:
| interface | {"compass":{"enabled":1,"offset":"<0, 0, 470>"},"gauges":{"offset":"<0, 0, -468>"},"height":1008} |
|---|
These bundles of settings are referred to as database sections in ARES terminology.
This takes around 108 bytes rather than 125 bytes as with separate storage. For very small tables this is not always more compact, but in practice the savings (and uniform access) tend to justify the data structure—the actual interface section contains dozens of entries.
Data encoded in a JSON string consists of objects, which are groups of "key":<value> pairs wrapped in braces { }, and arrays, which are groups of stand-alone <value> entries wrapped in square brackets [ ]. Objects are indexed by their keys, and arrays are indexed by implicit integers that start at 0. For example, in the JSON array:
["apple","banana","cherry"]
The string apple is entry 0, the string banana is entry 1, and the string cherry is entry 2. Objects and arrays can be nested inside each other:
{"fruits":["apple","banana","cherry"],"vegetables":["onion","lettuce","tomato"]}
Now, banana is entry 1 of the array stored under the fruits key, and lettuce is entry 1 of the array stored under the lettuce key. This kind of nesting is very common when storing configuration settings. We can refer to them more succinctly as fruits.1 and vegetables.1.
Programmers may be annoyed to see the dot operator used this way with numeric array subscripts instead of square brackets, but this is the convention used throughout ARES. It is much simpler to parse, and the main benefit of bracketed subscript notation (substituting an arbitrary expression that returns a valid index) is not generally applicable.
Programmer beware! LSL's JSON functions do make a type distinction between array and object subscripts. Simply splitting a variable name on periods is insufficient, as the numeric portions must be converted in-place to integers to be valid array indices. More tips can be found in The Operating System: The Database.
Naming conventions
As of ARES Beta 1, there are four different kinds of LSD entries in use:
- Pipe buffers have names starting with p:, followed by a UUID (a 32-bit hexadecimal string broken up by hyphens). These are temporary values that are used to pass text between programs, and are not usually encoded in JSON. (See The Operating System: Pipes for more detail.) If you encounter a pipe buffer, it is most likely a stray message that was never received due to a event queue overflow. The command input purge will delete such "stuck" buffers.
- Filesystem tables have names starting with fs:. These contain lists of filenames that match certain criteria. For example, fs:package contains a list of all .pkg files currently on the system. The fs:all table is the master index of all files from both local (inside your ARES inventory) and remote sources (on connected web servers). It is formatted as an object rather than an array, where each entry's key is the name of a file and its value is either the name of the corresponding remote source (e.g. system.info is usually on ns-info) or, for local files, the file type (inventory item type.) For more information, see Operating ARES: Filesystem Introduction and The Operating System: Files.
- Menus start with m: and follow a standard structure, containing the fields
title,desc,p,e, and sometimesd. These are explained more in The Operating System: Interface Architecture. - All other entries are settings sections, the main topic of this chapter.
You may occasionally see settings referred to with the LSD: prefix, e.g. LSD:interface.compass.enabled to refer to the compass.enabled field inside of the interface section. The LSD: prefix is not actually recognized by any program in the system and only serves to alert the reader that the topic of conversation is something stored inside Linkset Data.
Accessing settings storage
For the user, the main tool of database access is the db utility. This is a powerful program that can completely trash all settings in your ARES installation if used recklessly, so it requires its own security permission, called database, to use.