Difference between revisions of "LlCreateKeyValue"

From Second Life Wiki
Jump to: navigation, search
m
m (minor change)
 
(2 intermediate revisions by 2 users not shown)
Line 3: Line 3:
 
|inject-2={{LSL Function/KeyValue|k|v|dataserver|value=value|d2_type=string|d2_name=value}}{{LSL Function/Experience|true}}
 
|inject-2={{LSL Function/KeyValue|k|v|dataserver|value=value|d2_type=string|d2_name=value}}{{LSL Function/Experience|true}}
 
|func=llCreateKeyValue
 
|func=llCreateKeyValue
|func_desc=Start an asynchronous transaction to create a key-value pair associated with the script's Experience using the given key ({{LSLPT|k}}) and value ({{LSLPT|v}}).
+
|func_desc=Start an asynchronous transaction to create a key-value pair associated with the script's {{LSLGC|Experience}} using the given key ({{LSLPT|k}}) and value ({{LSLPT|v}}).
|func_footnote=If the key already exists the [[dataserver]] will return a failure along with the error [[XP_ERROR_STORAGE_EXCEPTION]].
+
|func_footnote=If the key already exists the [[dataserver]] will return a failure along with the error [[XP_ERROR_STORAGE_EXCEPTION]].<br/>
 +
<br/>
 +
As of Jan 1, 2016 maximum bytes is 1011 for key and 4095 for value for both LSO and Mono scripts.
 
|return_type=key|return_subtype=handle
 
|return_type=key|return_subtype=handle
 
|return_text=that can be used to identify the corresponding [[dataserver]] event to determine if this command succeeded or failed.
 
|return_text=that can be used to identify the corresponding [[dataserver]] event to determine if this command succeeded or failed.
Line 50: Line 52:
 
|cat2=Experience/Data
 
|cat2=Experience/Data
 
|cat3=Dataserver
 
|cat3=Dataserver
 +
|caveats=* It is recommended that keys do not contain commas due to [[llKeysKeyValue]] returning keys in CSV format.
 
}}
 
}}

Latest revision as of 17:49, 1 January 2016

Summary

Function: key llCreateKeyValue( string k, string v );

Start an asynchronous transaction to create a key-value pair associated with the script's Experience using the given key (k) and value (v).
Returns a handle (a key) that can be used to identify the corresponding dataserver event to determine if this command succeeded or failed.

• string k The key for the key-value pair
• string v The value for the key-value pair. Maximum 2047 characters, or 4095 if using Mono.

If the key already exists the dataserver will return a failure along with the error XP_ERROR_STORAGE_EXCEPTION.

As of Jan 1, 2016 maximum bytes is 1011 for key and 4095 for value for both LSO and Mono scripts.

For this function to work, the script must be compiled into an Experience.

Specification

Dataserver

The dataserver callback parameters are:

  • A key containing the handle returned from llCreateKeyValue
  • A string containing a comma-delimited list (cdl). llDumpList2String([ integer success ] + components);
String Components
• integer success A boolean specifying if the transaction succeeded (1) or not (0).
• integer error An XP_ERROR_* flag that describes why the operation failed.
• string value The value for the key-value pair. Maximum 2047 characters, or 4095 if using Mono. Note! This value may contain commas.

Caveats

  • If you recompile a script that was previously associated with an Experience but do so with a client that lacks the ability to compile scripts into an experience the script will loose the associated Experience.
  • It is recommended that keys do not contain commas due to llKeysKeyValue returning keys in CSV format.
All Issues ~ Search JIRA for related Bugs

Examples

key trans;
default
{
    touch_start(integer total_number)
    {
        trans = llCreateKeyValue("FOO", "BAR");
    }
 
 
 
    dataserver(key t, string value)
    {
        if (t == trans)
        {
            // our llCreateKeyValue transaction is done
            integer result = (integer)llGetSubString(value, 0, 0);
            if (result == 1)
            {
                // the key-value pair was successfully created
                llSay(0, "New key-value pair was created");
            }
            else
            {
                // the key-value pair was not created
                integer error = (integer)(llGetSubString(value, 2, -1));
                llSay(0, "Key-value failed to create: " + llGetExperienceErrorMessage(error));
            }
        }
    } 
}

Notes

Compiling

For a script to be associated with an Experience...

  • It must be compiled with a client that is Experience aware,
  • The "Use Experience" checkbox must be checked,
  • And one of the users Experience keys selected.
KBcaution.png Important: Not all TPVs have this functionality.

Deep Notes

Search JIRA for related Issues

Signature

function key llCreateKeyValue( string k, string v );