Difference between revisions of "XMREngine.scriptdb"

From Dreamnation
Jump to: navigation, search
(Created page with "These methods are available as an alternative to using the OpenSim notecard access methods. These methods access persistent storage as lists of lines, similar to the OpenSim...")
 
 
(3 intermediate revisions by the same user not shown)
Line 1: Line 1:
These methods are available as an alternative to using the OpenSim notecard access methods.
+
These API methods are available as an alternative to using the OpenSim notecard API methods.  They provide access to persistent storage that scripts can use to save information.  The information is stored and retrieved as name/value pairs.  The name is a string up to 233 characters and the value can be up to 65535 characters.  Name/value pairs written by one script in an object can be accessed by any script in the same object (including other linked prims).  They cannot be accessed by other objects.
  
These methods access persistent storage as lists of lines, similar to the OpenSim notecard methods.
+
These methods access persistent storage as lists of lines, similar to the OpenSim notecard API methods.
  
void xmrScriptDBWriteLines (string name, list contents)
+
  Write the list as a series of lines to the named persistent data element.
 +
    xmrScriptDBWriteLines (string name, list contents)
 +
      Input:
 +
        name = name of persistent element
 +
        contents = list of lines to write to element
 +
      Note:
 +
        If persistent element with same name already exists, it is overwritten
  
string xmrScriptDBReadLine (string name, integer line, string notfound, string endoffile)
+
  Read a single line from an element written by xmrScriptDBWriteLines()
 +
    string xmrScriptDBReadLine (string name, integer line, string notfound, string endoffile)
 +
      Input:
 +
        name = name as passed to xmrScriptDBWriteLines()
 +
        line = line number (starting with 0)
 +
        notfound = what string to return if there is no persistent element name found
 +
        endoffile = what string to return if line is beyond end of list written
 +
      Output:
 +
        returns notfound, endoffile, or list element line from persistent element name
  
integer xmrScriptDBNumLines (string name)
+
  Get the number of lines in an element written by xmrScriptDBWriteLines()
 
+
    integer xmrScriptDBNumLines (string name)
list xmrScriptDBReadLines (string name, list notfound)
+
      Input:
 +
        name = name as passed to xmrScriptDBWriteLines()
 +
      Output:
 +
        returns -1 if not found or number of lines if found
  
 +
  Get list of all lines in an element written by xmrScriptDBWriteLines()
 +
    list xmrScriptDBReadLines (string name, list notfound)
 +
      Input:
 +
        name = name as passwd to xmrScriptDBWriteLines()
 +
        notfound = list to return if not found
 +
      Output:
 +
        returns notfound or list of lines in element
  
 
These methods access persistent storage as a single (possibly long and/or multi-lined) string
 
These methods access persistent storage as a single (possibly long and/or multi-lined) string
  
xmrScriptDBWrite (string name, string value)
+
  Write a string to a persistent element:
 +
    xmrScriptDBWrite (string name, string value)
 +
      Input:
 +
        name = name of persistent element to write
 +
        value = string to write to persistent element
 +
      Note:
 +
        If persistent element with same name already exists, it is overwritten
 +
 
 +
  Read a single persistent element as one whole string:
 +
    string xmrScriptDBReadOne (string name, string notfound)
 +
      Input:
 +
        name = as passed to xmrScriptDBWrite()
 +
        notfound = what to return if element not found
 +
      Output:
 +
        returns notfound or value as passed to xmrScriptDBWrite()
 +
 
 +
  Number of element that match the given key
 +
    integer xmrScriptDBCount (string keylike)
 +
      Input:
 +
        keylike = search key to match persistent element names
 +
      Output:
 +
        returns number of matching elements
 +
 
 +
  List of elements that match the given key
 +
    list xmrScriptDBList (string keylike, integer limit, integer offset)
 +
      Input:
 +
        keylike = search key to match persistent element names
 +
        limit = maximum number of element names to return
 +
        offset = number of element names to skip before returning any
 +
      Output:
 +
        returns list of matching names (might be empty list)
 +
 
 +
  Read multiple elements that match the given key
 +
    array xmrScriptDBReadMany (string keylike, integer limit, integer offset)
 +
      Input:
 +
        keylike = search key to match persistent element names
 +
        limit = maximum number of elements to return
 +
        offset = number of elements to skip before returning any
 +
      Output:
 +
        returns array of elements found as name/value pairs (might be empty array)
 +
 
 +
  Delete elements that match the given key
 +
    integer xmrScriptDBDelete (string keylike)
 +
      Input:
 +
        keylike = search key to match persistent element names
 +
      Output:
 +
        returns number of elements deleted (might be zero)
 +
 
 +
In the above, keylike is a MySql style LIKE parameter.  Use % to indicate matching any number of characters in the element name, use _ to indicate matching exactly one character of the element name.  For example, "%" matches all names, "1.%" matches all names beginning with "1.".
 +
 
 +
Examples of how to use them to replace OpenSim notecard API methods:
  
string xmrScriptDBReadOne (string name, string notfound)
+
    osMakeNotecard (name, contents)  =>  xmrScriptDBWriteLines (xmrUUIDToBase64 (llGetKey ()) + name, contents)
  
integer xmrScriptDBCount (string keylike)
+
    osGetNotecardLine (name, line)  =>  xmrScriptDBReadLine (xmrUUIDToBase64 (llGetKey ()) + name, line, "ERROR!", "\n\n\n")
  
list xmrScriptDBList (string keylike, integer limit, integer offset)
+
    osGetNotecard (name)  =>  xmrScriptDBReadOne (xmrUUIDToBase64 (llGetKey ()) + name, "ERROR!")
  
array xmrScriptDBReadMany (string keylike, integer limit, integer offset)
+
    osGetNumberOfNotecardLines (name)  =>  xmrScriptDBNumLines (xmrUUIDToBase64 (llGetKey ()) + name)
  
integer xmrScriptDBDelete (string keylike)
+
In the above, xmrUUIDToBase64 (llGetKey ()) provides a 22-char string that is unique to the prim, needed so the keys given to the xmrScriptDB...() functions are unique to the prim.

Latest revision as of 08:29, 9 April 2018

These API methods are available as an alternative to using the OpenSim notecard API methods. They provide access to persistent storage that scripts can use to save information. The information is stored and retrieved as name/value pairs. The name is a string up to 233 characters and the value can be up to 65535 characters. Name/value pairs written by one script in an object can be accessed by any script in the same object (including other linked prims). They cannot be accessed by other objects.

These methods access persistent storage as lists of lines, similar to the OpenSim notecard API methods.

 Write the list as a series of lines to the named persistent data element.
   xmrScriptDBWriteLines (string name, list contents)
     Input:
       name = name of persistent element
       contents = list of lines to write to element
     Note:
       If persistent element with same name already exists, it is overwritten
 Read a single line from an element written by xmrScriptDBWriteLines()
   string xmrScriptDBReadLine (string name, integer line, string notfound, string endoffile)
     Input:
       name = name as passed to xmrScriptDBWriteLines()
       line = line number (starting with 0)
       notfound = what string to return if there is no persistent element name found
       endoffile = what string to return if line is beyond end of list written
     Output:
       returns notfound, endoffile, or list element line from persistent element name
 Get the number of lines in an element written by xmrScriptDBWriteLines()
   integer xmrScriptDBNumLines (string name)
     Input:
       name = name as passed to xmrScriptDBWriteLines()
     Output:
       returns -1 if not found or number of lines if found
 Get list of all lines in an element written by xmrScriptDBWriteLines()
   list xmrScriptDBReadLines (string name, list notfound)
     Input:
       name = name as passwd to xmrScriptDBWriteLines()
       notfound = list to return if not found
     Output:
       returns notfound or list of lines in element

These methods access persistent storage as a single (possibly long and/or multi-lined) string

 Write a string to a persistent element:
   xmrScriptDBWrite (string name, string value)
     Input:
       name = name of persistent element to write
       value = string to write to persistent element
     Note:
       If persistent element with same name already exists, it is overwritten
 Read a single persistent element as one whole string:
   string xmrScriptDBReadOne (string name, string notfound)
     Input:
       name = as passed to xmrScriptDBWrite()
       notfound = what to return if element not found
     Output:
       returns notfound or value as passed to xmrScriptDBWrite()
 Number of element that match the given key
   integer xmrScriptDBCount (string keylike)
     Input:
       keylike = search key to match persistent element names
     Output:
       returns number of matching elements
 List of elements that match the given key
   list xmrScriptDBList (string keylike, integer limit, integer offset)
     Input:
       keylike = search key to match persistent element names
       limit = maximum number of element names to return
       offset = number of element names to skip before returning any
     Output:
       returns list of matching names (might be empty list)
 Read multiple elements that match the given key
   array xmrScriptDBReadMany (string keylike, integer limit, integer offset)
     Input:
       keylike = search key to match persistent element names
       limit = maximum number of elements to return
       offset = number of elements to skip before returning any
     Output:
       returns array of elements found as name/value pairs (might be empty array)
 Delete elements that match the given key
   integer xmrScriptDBDelete (string keylike)
     Input:
       keylike = search key to match persistent element names
     Output:
       returns number of elements deleted (might be zero)

In the above, keylike is a MySql style LIKE parameter. Use % to indicate matching any number of characters in the element name, use _ to indicate matching exactly one character of the element name. For example, "%" matches all names, "1.%" matches all names beginning with "1.".

Examples of how to use them to replace OpenSim notecard API methods:

   osMakeNotecard (name, contents)  =>  xmrScriptDBWriteLines (xmrUUIDToBase64 (llGetKey ()) + name, contents)
   osGetNotecardLine (name, line)  =>  xmrScriptDBReadLine (xmrUUIDToBase64 (llGetKey ()) + name, line, "ERROR!", "\n\n\n")
   osGetNotecard (name)  =>  xmrScriptDBReadOne (xmrUUIDToBase64 (llGetKey ()) + name, "ERROR!")
   osGetNumberOfNotecardLines (name)  =>  xmrScriptDBNumLines (xmrUUIDToBase64 (llGetKey ()) + name)

In the above, xmrUUIDToBase64 (llGetKey ()) provides a 22-char string that is unique to the prim, needed so the keys given to the xmrScriptDB...() functions are unique to the prim.