Settings.putValue Action

Format

CS.Settings.putValue(key := ..., value := ...ʃ, source := ...ʅ)

Argument	Description	Types / Required
key	The key that uniquely identifies the setting.	string required
value	The value to associate with the key.	string, number, boolean, array, object required
source	The name of the settings database. The default value is "UserSettings".	string not required

Description

The Settings.putValue action sets a value in a settings database, associating the value with the unique identifier key. The setting is stored in a table of attribute-value pairs and can be retrieved using Settings.getValue. If the value is a blank string, the setting is removed from the database.

The default source database, "UserSettings", corresponds to the User Settings database used by the savesetting function. These settings can be viewed and modified in the CSPro Designer using the User and Configuration Settings dialog. You can use a custom settings database by specifying the name of a database, which will be created automatically if it does not exist.

The file from which settings are retrieved can be modified by altering the CommonStore attribute of a PFF file. The settings are stored in a SQLite database and the settings should not be considered secure as they can accessed by other applications.

Settings from the User Settings database, but not custom databases, can also be set using the savesetting function. Only string and numeric values can be set in this database, but custom databases also support boolean values, arrays, and objects.

Return Value

The action returns undefined.

Exceptions

The action throws an exception if any of its arguments are not specified in a valid form, or a non-supported value is provided for the User Settings database.

Example (CSPro Logic)

PROC FRESHWATER_BIRDS_FF

preproc

string SettingsSource = "FreshwaterBirdsSurvey";
string LanguageKey = "language";

// restore the language that was in use when the user last ran this survey, defaulting to English
string language = CS.Settings.getValue(source := SettingsSource,
key := LanguageKey,
value := "EN");
setlanguage(language);

postproc

// save the language in use
CS.Settings.putValue(source := SettingsSource,
key := LanguageKey,
value := getlanguage());

Example (JavaScript)

// save the user credentials for later use
CS.Settings.putValue({
source: "FreshwaterBirdsSurvey",
key: "credentials",
value: {
username: "GBH",
lastAccessTimestamp: new Date().getTime()
}
});

// ... at a later point, query for the saved user credentials
const credentials = CS.Settings.getValue({
source: "FreshwaterBirdsSurvey",
key: "credentials",
value: {}
});

// only use the user credentials if the date is within a day of the last access
const secondsBetweenAccess = new Date().getTime() - credentials.lastAccessTimestamp;

if( secondsBetweenAccess <= ( 24 * 60 * 60 ) ) {
// use the credentials
}