martin2k

ForumsVB6GamesSoftwareDirectoryHTMLArticlesBlogContact

Configuration File


 

Home

Read and add posts to the Visual Basic 6.0 Forums

Download some of my programs and OCXs

Read the Tips here

The old style forum is still available here

Contact


 

ActiveX Control

The Configuration File ActiveX control is another one that was written by me.  Its main purpose is to store data either in memory or on disk that can be accessed easily.  Data is retrieved and edited by a reference to the name of the data.  I.e. if one item of data is called 'Name1', which holds the string "Barney", using the argument "Name1" in the function that gets the data will return the string "Barney".  Another good thing about this control is the way you can group items together in sets; see below for details.  This control can be very useful as a way of storing your program's data.

You can download the control here (12.6 KB).

An example project demonstrating some of the Methods of this control can be downloaded here:


vb_40_cfexample.zip
(2.72 KB)

One of the most useful aspects of this control is Sets, which allow you to manipulate related data.  See the Sets box for more information.

The term 'ConfigFile space' mentioned throughout this article refers to the space in memory that contains all the ConfigFile entries for the control you are working on.  Unlike INI files, ConfigFile loads entries from a file and then stores them in memory until you are ready to save them.  The examples in the article assume you are working with the following data (except for Sets):

People=4
Person1=Charlie
Person2=José
Person3=Victoria
Person4=José

Methods

ConfigLoad

FileName As String

Loads data from a file into the ConfigFile space.  The file must be in this format:

Data1=Value1
Data2=Value2

Etc...

The equals (=) sign must be used to separate data with its reference (key).  The entries to not need to be in any particular order.

The file can have empty lines.

ConfigSave

FileName As String

Creates a file containing the contents of the ConfigFile space.  Unfortunately this process can take quite a while when there are a huge number of entries.

DelAll

Removes all data from the ConfigFile space.

DelKey

KeyName As String

Deletes a key and its associated data e.g. if 'DelKey "Person2"' is executed, the ConfigFile space would end up as:

People=4
Person1=Charlie
Person3=Victoria
Person4=José

GetAll

Returns all the data in the ConfigFile space as a string.  This might be useful if you want to save the data in a different way to how ConfigSave does.

GetName

KeyValue As String

Searches through the ConfigFile space and returns the KeyName associated with the data (value) specified as a string.  The problem with this is that although two KeyNames cannot be the same, values can.  This means that only the first match encountered will return the KeyName.  E.g.

s = GetName("José") 'returns "Person2"

GetName should not be generally be used unless there are exceptional circumstances.

If the KeyValue is not found, the string "[NOT FOUND]" is returned.

GetValue

KeyName As String, [DefValue As String]

This method returns the value associated with the specified KeyName as a string.  E.g.:

s = GetValue("People") 'returns "4"

DefValue refers to the default value to be returned if the KeyName is not found.  If DefValue is not used and the KeyName is still not found, the string "[NOT FOUND]" is returned.

WriteAll

NewConfig As String

Replaces the data in the ConfigFile space with the NewConfig string.  The new data must be in this format:

KeyName1=Value
KeyName2=Value
etc...

WriteValue

KeyName As String, KeyValue As String

Writes data (the KeyValue) to a KeyName.  If the KeyName already exists, it will be overwritten with the new data otherwise a new KeyName is created.

WriteValue "LastSaved", Now

WriteValueNoCheck

KeyName As String, KeyValue As String

Works in the same way as WriteValue but does not check to see if the KeyName already exists.  This method should only be used when you are writing a lot of KeyNames at a time (e.g. when saving files) and you know that the KeyName is unique.  As no check needs to be made, the writing of KeyNames is takes less time.

Sets

Sets in the ConfigFile control are groups of related data.  Here is an example set as it would appear in the ConfigFile space:

People=4
Person1=Charlie
Age1=39
Country1=Scotland
Person2=José
Age2=48
Country2=USA
Person3=Victoria
Age3=82
Country3=Australia
Person4=José
Age4=17
Country4=Portugal

In the above example, 'People' is the name of the set.  The rest of the keys have a reference number as their suffix.  Each key that has the same number is in the same record e.g. from the above data, you can tell that the person called Charlie is aged 39 and lives in the country called Scotland.  There is no limit to the number of items, which can be related to each record e.g. you could also include the person's surname, address, telephone number etc., each with the same numerical suffix.

Furthermore, each Person could have a set of their own - a subset.  E.g. there could be sets, which contain data about what cars they own:

Cars1=2
1Make1=Lamborghini
1Model1=Murciélago
1Make2=Ford
1Model2=GT

The above example shows that person 1 has two cars.  The set name of Cars1 indicates that is related to person 1 due to the suffix being the same.

The set methods in the ConfigFile control allow you to easily manipulate the data in Sets.

From now on, the examples assume you are using the data from the Sets box, on the left.

Set2List

lst As Object, SetName As String, KeyName As String, [EqualReplace As String]

This method takes data from a set and adds it to a ListBox.  It will only add items associated with the specified KeyName.  E.g. the following code will add all the people's names to a ListBox called List1:

ConfigFile1.Set2List List1, "People", "Person"

You do not specify the numerical suffix for the KeyName.  EqualReplace replaces the specified string with an equals (=) sign.

SetCheckDup

SetName As String, KeyName As String, CheckString As String, [UseCaps As Boolean]

This method goes through the specified KeyNames of a set and returns the record number (as a Long integer) if it finds the CheckString string.  E.g.:

l = ConfigFile1.SetCheckDup("People", "Person", "Victoria") 'l would contain the number 3.

UseCaps is a way of making the search not case sensitive.  The CheckString must also be in uppercase for this to work.

SetCopy

This method copies one a set and to another.  You also specify the old KeyName to copy from.  The new KeyName can be different from the old KeyName.  E.g.:

ConfigFile1.SetCopy "People", "Person", "Employees", "Employee"

The following additional data will now be in the ConfigFile space:

Employees=4
Employee1=Charlie
Employee2=José
Employee3=Victoria
Employee4=José

To copy the whole set, you will need to run SetCopy for each different KeyName i.e.:

ConfigFile1.SetCopy "People", "Person", "Employees", "Employee"
ConfigFile1.SetCopy "People", "Age", "Employees", "Age"
ConfigFile1.SetCopy "People", "Country", "Employees", "Country"

 

SetCountAdd

SetName As String

When adding a new record to a set (by using SetItemAdd), you need to use this method to add to the count, before adding the new record.  If this method is not used, the new record will overwrite the last record in the set.  E.g. to add a new person to the 'People' set:

ConfigFile1.SetCountAdd "People"
ConfigFile1.SetItemAdd "People", "Person", "Bev"
ConfigFile1.SetItemAdd "People", "Age", "23"
ConfigFile1.SetItemAdd "People", "Country", "Sweden"

SetCountSub

SetName As String

When deleting a record from a set (by using SetItemDel), you need to use this method, before deleting the record.  If this method is not used, SetItemDel will act in the normal way except that set will contain an extra record at the end with '[NOT FOUND]' as the values for all the KeyNames.

ConfigFile1.SetCountSub "People"
ConfigFile1.SetItemDel "People", "Person", "2"
ConfigFile1.SetItemDel "People", "Age", "2"
ConfigFile1.SetItemDel "People", "Country", "2"
 

The Reason for SetCountAdd and SetCountSub

The reason why SetItemAdd (explained later on) does not add to the number of records in the set itself is that if you add more than one KeyName to a record, you do not want the number of records to increase with each KeyName addition.  Similarly with SetItemSub, you do not want the number of records to decrease with each deletion.

SetDel

SetName As String, KeyName As String

Deletes all KeyNames (the one specified) in a set.  If you want to delete a whole set, you would use SetDel to delete all KeyNames and then use DelKey to delete the SetName.  E.g.:

ConfigFile1.SetDel "People", "Person"
ConfigFile1.SetDel "People", "Age"
ConfigFile1.SetDel "People", "Country"
ConfigFile1.DelKey "People"

SetDel will not work if the set name is deleted first.

SetItemAdd

SetName As String, KeyName As String, KeyValue As String

This method adds a record to a set.  Before adding a new record, you must use SetCountAdd to increase the number of records in the set (as described above).  You must then use SetItemAdd for each new KeyName in the new record.  E.g.:

ConfigFile1.SetCountAdd "People"
ConfigFile1.SetItemAdd "People", "Person", "Bev"
ConfigFile1.SetItemAdd "People", "Age", "23"
ConfigFile1.SetItemAdd "People", "Country", "Sweden"

SetItemDel

SetName As String, KeyName As String, Pos As Long

This method is used to delete a record from a set.  You must first use SetCountSub to decrease the number of records (as described above).  You must then use SetItemDel for each KeyName in the record specifying the record's position.

ConfigFile1.SetCountSub "People"
ConfigFile1.SetItemDel "People", "Person", "2"
ConfigFile1.SetItemDel "People", "Age", "2"
ConfigFile1.SetItemDel "People", "Country", "2"

SetItemDown

KeyName As String, Pos As Long

This method swaps the value of the KeyName in any set with the data in the next position i.e. moving it down.  E.g.:

ConfigFile1.SetItemDown "Person", 2
ConfigFile1.SetItemDown "Country", 2
ConfigFile1.SetItemDown "Age", 2

In the above example, the data in position 2 would move to position 3 and the data that was in position 3 would move to position 2.  See also SetItemUp.

SetItemEdit

KeyName As String, Pos As Long, KeyValue As String

Allows you to edit a record in a set.

ConfigFile1.SetItemEdit "Person", 1, "Charles"

Another way to do this is to use the WriteValue method i.e.:

ConfigFile1.WriteValue "Person1", "Charles"

SetItemUp

KeyName As String, Pos As Long

This method swaps the value of the KeyName in any set with the data in the previous position i.e. moving it up.  E.g.:

ConfigFile1.SetItemUp "Person", 2
ConfigFile1.SetItemUp "Country", 2
ConfigFile1.SetItemUp "Age", 2

In the above example, the data in position 2 would move to position 1 and the data that was in position 1 would move to position 2.  See also SetItemDown.

SetJoin

SetName As String, KeyName As String

Returns a string made up of all the records specified by the KeyName e.g.:

s = ConfigFile1.SetJoin("People", "Person") 'returns CharlieJoséVictoriaJosé

This method is most useful to join KeyNames together that were split using the SetSplit method.

SetSplit

SetName As String, KeyName As String, Text As String, Length As Integer

Creates a set where the KeyNames include a single piece of data.  If you have a very long record, you might want to split it using this method.  The length of each record is determined with the Length method.  You should not use this method to add data to an existing set.  E.g.:  the following example will use this text:

This is an example of using the SetSplit method. This string will be split into a set with records, which are ten (10) characters in length. It can even handle carriage returns e.g.:

This text appears two lines on.

ConfigFile1.SetSplit "Example", "Line", s, 10

The data will appear like this in the ConfigFile space:

Example=22
Line1=This is an
Line2= example o
Line3=f using th
Line4=e SetSplit
Line5= method. 
Line6=This strin
Line7=g will be 
Line8=split into
Line9= a set wit
Line10=h records,
Line11= which are
Line12= ten (10) 
Line13=characters
Line14= in length
Line15=. It can 
Line16=even handl
Line17=e carriage
Line18= returns e
Line19=.g.:&ç;&ç;Th
Line20=is text ap
Line21=pears two 
Line22=lines on.

Use the SetJoin method to join the text back together.


blog comments powered by Disqus
Martin Allen 1999 - 2011.  Last updated Wednesday 10 August 2011 07:44:06 PM +0100.