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:

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

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.

VALUE_TRUNCATED

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

OK

Return value indicating that function was performed successfully.

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=TRUE] )

Returns a Fileprefs object associated with the given file path.

Refresh( Fileprefs theFileprefs )

Forces a reread of the preference file.

 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 VALUE_TRUNCATED

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

 Integer OK

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

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

 Integer Close(
            Fileprefs theFileprefs )

 Integer Create(
             String prefFilePath )

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

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

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

 List ListSections(
             Fileprefs theFileprefs )

 Assoc ListValues(
             Fileprefs theFileprefs,
             String sectionName )

 Fileprefs Open(
              String prefFilePath, 
              [Boolean cache=TRUE] )

 Integer Refresh(
             Fileprefs theFileprefs )