Verifying and Initializing Settings
Initialization is the process of making setting values "sane". To be considered sane, the setting value must have correct checksum, and its members must conform to the constraints of P1 and P2 parameters.
Non-volatile settings are never initialized automatically — it is your responsibility as the developer to decide just when and how this happens. If you load a settings-using application onto a device that has never run this application before, then each non-volatile setting will be invalid because all setting checksums will be wrong. Volatile settings are always initialized when you call stg_start().
Any setting can be "repaired" by writing a valid value into it. You can do this using stg_sg() or stg_set() — see Writing and Reading Settings.
A more "automatic" way is to use stg_restore_multiple(). This will restore all settings to their default values as defined in the setting descriptor file. In the following example, settings are initialized if the MD button is kept pressed for more than 2 seconds and then released:
** Tibbo Basic **
sub on_button_released() if button.time>4 then if stg_restore_multiple(EN_STG_INIT_MODE_NORMAL)<>EN_STG_STATUS_OK then sys.halt end if end sub
You can also verify the sanity of each setting in your project by calling stg_check_all(). Here is some code you can place in on_sys_init() — it verifies all settings and performs initialization if any setting is found to be invalid. Notice how we check the code returned by stg_check_all(). EN_STG_STATUS_INVALID is a "good" error, that is, we expect it to happen. There are other errors, however, that are "fatal", for example, EN_STG_STATUS_FAILURE. We halt on those.
** Tibbo Basic **
sub on_sys_init() dim x as en_stg_status_codes dim stg_name as string(STG_MAX_SETTING_NAME_LEN) if stg_start()<>EN_STG_STATUS_OK then sys.halt x=stg_check_all(stg_name) select case x case EN_STG_STATUS_OK: '--- all good --- case EN_STG_STATUS_INVALID, EN_STG_STATUS_FAILURE: if stg_restore_multiple(EN_STG_INIT_MODE_NORMAL)<>EN_STG_STATUS_OK then sys.halt case else: 'some other trouble sys.halt end select comms_init() end sub
There is also a library procedure to restore a single member of a single setting — stg_restore_member(). The default value for any member of any setting can be obtained by calling stg_get_def().