CASL Preferences

Preferences
Stores and retrieves user defined strings in the saved_preferences database

Download

09/16/2002:
Functions optionally with CreatorID as parameter.

09/16/2002:
Bug in GetPreferences removed, that has crashed the palm with a "MemMove to NULL" error.

Functions definition

external "CASL_Preferences";
#--------------------------------------------------------------------------------
# Stores an entry in a preferences database
function SetPreferences (numeric PrefID, string PreferenceStr, numeric Saved);
#
# PrefID = identfication number of the preference string,
# PreferenceStr: String that should be stored in the preferences Database
# Saved = true: stores the preference strng in the saved_preferences database
#         false: stores the preference strng in the unsaved_preferences database
# Remarks:
# - use "Saved = true" only for such data that should survive a hard reset!
#   (the saved_preferences database is hotsynced, the unsaved_preferences is not)
# - hold the size of the system databases "saved_preferences" and
#   "unsaved_preferences" small
# - the creator id of the application is used internal as an identifier. Please note,
#   that applications with same creator id can influence each other.

#--------------------------------------------------------------------------------
# Retrieves an entry from a preferences database
function GetPreferences (numeric PrefID, numeric Saved) as string;
#
# PrefID = identfication number of the preference string,
#          as defined in SetPreferences
# Saved = true: gets the preference strng out of the saved_preferences database
#         false: gets the preference strng out of the unsaved_preferences database
# Remarks:
# - Use the same parameter setting as in the corresponding SetPreferences call
# - if the specified PrefID does not exist, the function returns an empty string

#--------------------------------------------------------------------------------
# Deletes an entry in the preferences database
function DelPreferences (numeric PrefID, numeric Saved);
#
# PrefID = identfication number of the preference string,
#          as defined in SetPreferences
# Saved = true: deletes the preference string in the saved_preferences database
#         false: deletes the preference strng in the unsaved_preferences database

#--------------------------------------------------------------------------------
# Use the following functions only if your are familiar with CreatorID's!
#--------------------------------------------------------------------------------

# Stores an entry in a preferences database
function SetPreferencesByCreator (numeric PrefID, string CreatorID, string PreferenceStr, numeric Saved);
#
# same as SetPreferences, but with user defined CreatorID
# PrefID = identfication number of the preference string,
# CreatorID: decimal string representation of the CreatorID
# PreferenceStr: String that should be stored in the preferences Database
# Saved = true: stores the preference strng in the saved_preferences database
# false: stores the preference strng in the unsaved_preferences database
#--------------------------------------------------------------------------------
# Retrieves an entry from a preferences database
function GetPreferencesByCreator (numeric PrefID, string CreatorID, numeric Saved) as string;
#
# same as GetPreferences, but with user defined CreatorID
# PrefID = identfication number of the preference string,
# as defined in SetPreferences
# CreatorID: decimal string representation of the CreatorID
# Saved = true: gets the preference strng out of the saved_preferences database
# false: gets the preference strng out of the unsaved_preferences database
# Remarks:
# - Use the same parameter setting as in the corresponding SetPreferences call
# - if the specified PrefID does not exist, the function returns an empty string

#--------------------------------------------------------------------------------
# Deletes an entry in the preferences database
function DelPreferencesByCreator (numeric PrefID, string CreatorID, numeric Saved);
#
# same as DelPreferences, but with user defined CreatorID
# PrefID = identfication number of the preference string,
# as defined in SetPreferences
# CreatorID: decimal string representation of the CreatorID
# Saved = true: deletes the preference string in the saved_preferences database
# false: deletes the preference strng in the unsaved_preferences database

#--------------------------------------------------------------------------------
function GetCreatorID as string;
# this function is a test function and retrieves the current creator id
# of the application in a decimal string representation.
# Is was left here for everybody who may need it.
end_external;