The built-in functions in the Fileprefs Package allow the creation and manipulation of Fileprefs values. The Fileprefs type encapsulates a preferences file with unique named sections each having name value pairs. The format of a Fileprefs file is similar to a windows INI file. The functions described below are used to manipulate the values in the preferences file. In a multithreaded server environment the preferences in any individual file are managed so that all threads using the same file always have access to the same consistent preferences. All of the Fileprefs built-in functions are thread-safe. Values are currently limited to being no longer than 254 characters in length. For additional information please see the OScript Language Reference.

The major functionalities offered in the Fileprefs Package are the following:

Create() to create a preferences file.
Open() to open a preference file and Close() to close one.
AddPref() to add a preference and DelPref() to remove one.
GetPref() to retrieve the value of a preference, or GetPath() to retrieve the value of a file path preference.
ListSections() to list the sections within a preferences file and ListValues() to return an Assoc containing all the preferences in a section.
Refresh() to reload a Fileprefs object from file if needed.

Here is an example which demonstrates how easily Fileprefs are created and used:

String      fname = "c:\tmp\s.prefs"
List        names = { "color", "name", "date", "count", "somepath" }
List        values = { "blue", "Joe", Date.Now(), 4, "c:\tmp\s.txt" }
List        sections = { "colors", "misc", "agents", "misc", "misc" }
Integer     i
Fileprefs   f
String      name
String      section
Dynamic     value
Assoc       readvals

if ( !IsError( Fileprefs.Create( fname ) ) )
    if (!IsError( f = Fileprefs.Open( fname ) ) )
        for ( i = 1; i <= Length( names ); i += 1 )
            value = values[ i ]

            if ( Type( value ) != StringType )
                value = Str.ValueToString( value )
            end

            Fileprefs.AddPref( f, sections[ i ], names[ i ], value )
        end

        Fileprefs.Close( f )
        f = Fileprefs.Open( fname )
        sections = Fileprefs.ListSections( f )

        for section in sections
            readvals = Fileprefs.ListValues( f, section )

            for name in Assoc.Keys( readvals )
                value = Str.StringToValue( readvals.( name ) )

                if ( IsUndefined( value ) )
                   value = readvals.( name )
                end

                Echo( "[", section, "] ", name, '=', Str.String( value ) )
            end
        end

        Fileprefs.Close( f )

    else
        Echo( "Could not open " + fname )
    end
else
    Echo( "Could not create " + fname )
end

The output of the example is:

[colors] color=blue
[misc] count=4
[misc] name=Joe
[misc] somepath=c:\tmp\s.txt
[agents] date=Fri Sep 11 16:42:15 1998

The contents of the preferences file is (note that this should not be absolutely relied upon as it may be subject to change in the future, however it is included here for purposes of demonstration and clarification):

[colors]
color=blue

[misc]
somepath=c:\tmp\s.txt
count=4
name=Joe

[agents]
date=D/1998/9/11:16:53:31

Class Attributes

NO_FILE

Error return value indicating that the Fileprefs parameter passed was not open or did not have an associated preferences file.

NO_SECTION

Error return value indicating that no section was found for the given section name.

NO_VALUE

Error return value indicating that no value was found for the given name.

NO_WRITE

Error return value indicating that the write to the preferences file failed.

Return value indicating that function was performed successfully.

VALUE_TRUNCATED

Error return value indicating that buffer used to get a preference was too small.

Class Methods

AddPref( Fileprefs theFileprefs, String sectionName, String prefName, String prefValue )

Adds a preference of the form prefName=prefValue to the section sectionName.

Close( Fileprefs theFileprefs )

Closes the associated preference object.

Create( String prefFilePath )

Creates a new preferences file if one does not already exist as specified by the given path.

DelPref( Fileprefs theFileprefs, String sectionName, String prefName )

Removes the preference of the given name and its associated value from the given section.

GetPath( Fileprefs theFileprefs, String sectionName, String prefName )

Returns a string of the value associated with a given named preference as a file path specification, meaning that all file separators are translated properly based on the current platform.

GetPref( Fileprefs theFileprefs, String sectionName, String prefName )

Returns the String value associated with the given preference in the given section.

ListSections( Fileprefs theFileprefs )

Returns a List of all the section names in the given preference file.

ListValues( Fileprefs theFileprefs, String sectionName )

Returns an Assoc of all the preference name/value pairs in a given named section of the preference file.

Open( String prefFilePath, Boolean cache )

Returns a Fileprefs object associated with the given file path.

Refresh( Fileprefs theFileprefs )

Forces a reread of the preference file.

Class Attributes

Integer NO_FILE

Error return value indicating that the Fileprefs parameter passed was not open or did not have an associated preference file.

Integer NO_SECTION

Error return value indicating that no section was found for the given section name.

Integer NO_VALUE

Error return value indicating that no value was found for the given preference name.

Integer NO_WRITE

Error return value indicating that the file could not be written.

Integer OK

Return value (defined as zero) indicating that a fileprefs function was performed successfully.

Integer VALUE_TRUNCATED

Error return value indicating that the buffer used to get the preference was too small to hold the full value.

Class Methods

AddPref

Integer AddPref( Fileprefs theFileprefs,
                 String sectionName,
                 String prefName,
                 String prefValue )

Adds a preference of the form prefName=prefValue in the section sectionName. If the section does not yet exist then a new section with the proper sectionName will be created. If a preference already exists in the given section as prefName=someOtherValue then it will be replaced with the new value.

Parameters

theFileprefs

The Fileprefs object.

sectionName

The preference file section name.

prefName

The name of the preference to add.

prefValue

The value to associate with the named preference.

Returns:

Error with value NO_FILE if the provided Fileprefs object is not valid, or Integer OK if the operation was successful.

Close

Integer Close( Fileprefs theFileprefs )

Closes the associated preference object. In a multithreaded application this call may have no direct relationship to the "openness" of the actual preference file, since multiple threads may be accessing the Fileprefs object at once.

Parameters

theFileprefs

The Fileprefs object.

Returns:

Integer OK if the operation was successful.

Create

Integer Create( String prefFilePath )

Creates a new preference file if one does not already exist with the given prefFilePath. Open must be called with the same path to open the new Fileprefs object and perform other operations on it.

Parameters

prefFilePath

The file path specification of the preference file, including path and file name.

Returns:

Error with value NO_FILE if the specified file could not be created, otherwise Integer OK if the operation was successful.

DelPref

Integer DelPref( Fileprefs theFileprefs,
String sectionName,
String prefName )

Removes the preference named prefName and its associated value from section sectionName.

Parameters

theFileprefs

The Fileprefs object.

sectionName

The preference file section name.

prefName

The name of the preference to delete.

Returns:

Error with value NO_FILE if the provided Fileprefs object is not valid, otherwise Integer OK if successful.

GetPath

String GetPath( Fileprefs theFileprefs,
String sectionName,
String prefName )

Returns the string value associated with preference prefName in section sectionName, except, unlike Fileprefs.GetPref(), the string is returned as a file path specification, meaning that all file separators are translated properly for the current platform. Only the first 254 characters of the value will be returned.

Parameters

theFileprefs

The Fileprefs object.

sectionName

The preference file section name.

prefName

The name of the preference to retrieve.

Returns:

String result or Error if unsuccessful.

GetPref

String GetPref( Fileprefs theFileprefs,
String sectionName,
String prefName )

Returns the string value associated with the preference prefName in section sectionName. Only the first 254 characters of the value will be returned.

Parameters

theFileprefs

The Fileprefs object.

sectionName

The file preference section name.

prefName

The name of the preference name to retrieve.

Returns:

String result if successful; Error otherwise.

Example

Use Fileprefs.GetPath() to retrieve values which are file paths, and Fileprefs.AddPref() to add a preference.

ListSections

List ListSections( Fileprefs theFileprefs )

Returns a List of all the section names in the given preference file.

Parameters

theFileprefs

The Fileprefs object.

Returns:

List if successful; Error otherwise.

ListValues

Assoc ListValues( Fileprefs theFileprefs,
String sectionName )

Returns an Assoc containing a map of all preference name/value pairs in a given section of the preference file.

Parameters

theFileprefs

The Fileprefs object.

sectionName

The name of the preference section for which all preferences are returned..

Returns:

An Assoc containing all the preferences in the given section, mapping each String preference name to its String value.

Open

Fileprefs Open( String prefFilePath,
Boolean cache )

Returns a Fileprefs object associated with the file specified by the prefFilePath.

Parameters

prefFilePath

The file path specification of the preference file to open.

cache

True if the file prefs data should be cached by the system, false if not. Default is TRUE.

If FALSE, the prefs data will be released from memory when the FilePrefs object goes out of scope.

Returns:

Valid Fileprefs object if successful; otherwise Error.

Refresh

Integer Refresh( Fileprefs theFileprefs )

Forces a reread of the preference file. It is expensive and should be avoided.

Parameters

theFileprefs

The Fileprefs object.

Returns:

Error with value NO_FILE if the preference file is not valid or does not exist, or Integer OK if the operation was successful.