Property Bag Functions

The property bag functions allow a UJML application to persist settings and other small data sets.

A property bag is a named set of data values stored on a supported device. The property bag functions allow you to load a property bag, retrieve values, set values, remove values, and store the modified property bag. See Using Functions.

Accessing property bags

Before you can use a property bag, you must bring it into device memory using the _x_loadBag() function. You can save changes to a property bag using the _x_storeBag() function. The _x_closeBag() function removes the property bag from memory. The _x_removeBag() function deletes the property bag from the device.

Accessing property bag values

Values in a property bag are indexed using an integer key value, which you must supply when you get, set or remove values from the property bag using data type appropriate get and set functions. The key value may be any small, positive integer. Key values do not have to be sequential, unlike an array index.

Property bag value types

Allowed property bag value types are boolean, int, and string. See Data Types.

Property bag names

Property bag names are string expressions. Most characters are valid in property bag names, but some devices may have restrictions on file names. For example, you should avoid using the backslash character ("\") as some devices may interpret that as a path separator. It is probably best to follow the standard UJML naming recommendations. See Names.

What can go wrong

Many property bag functions return true if they succeed or false if they fail. Reasons why a property bag function might fail include:

The device does not support property bags.
The bag does not exist, or already exists (depending on the operation).
Not enough space is available on the device.
Not enough memory is available on the device.
An invalid index was provided.
The property bag was not prepared for the operation (for example the property bag was not opened successfully).

Remarks

Not all devices support property bags. You can determine device support for property bags by calling the _isSupported() function with the &_X_PROPERTY_BAG; feature support information entity. See _isSupported() function, Feature Support Information Entities.

Note: The amount of storage available for property bags is device dependent and cannot be determined programmatically.

Topics

Topic	Description
_x_closeBag()	The _x_closeBag() function closes a property bag and returns a boolean value indicating success or failure.
_x_getBagBoolean()	The _x_getBagBoolean() function returns a boolean value from a property bag, or an optional default value.
_x_getBagInt()	The _x_getBagInt() function returns an int value from a property bag, or an optional default value.
_x_getBagString()	The _x_getBagString() function returns a string value from a property bag, or an optional default value.
_x_loadBag()	The _x_loadBag() function loads a property bag and returns a boolean value indicating success or failure.
_x_removeBag()	The _x_removeBag() function permanently removes a property bag and returns a boolean value indicating success or failure.
_x_removeBagKey()	The _x_removeBagKey() removes a key from a property bag and returns a boolean value indicating success or failure.
_x_setBagBoolean()	The _x_setBagBoolean() function stores a boolean value into a property bag.
_x_setBagInt()	The _x_setBagInt() function stores an int value into a property bag.
_x_setBagString()	The _x_setBagString() function stores a string value into a property bag.
_x_storeBag()	The _x_storeBag() function stores a property bag and returns a boolean value indicating success or failure.