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

 select case x
         '--- all good ---

         if stg_restore_multiple(EN_STG_INIT_MODE_NORMAL)<>EN_STG_STATUS_OK then sys.halt

 case else:
         'some other trouble
 end select

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().