A good examples for the case are the SFMain.GetOSInfo and
SFMain.GetVersionInfo methods (see SFMain
for more information about the method details). They extract a lot of
information about the OS or a file and it is unpractical to create
special objects to represent that information. For example
GetVersionInfo returns basic version numbers and also one or more sets
of language dependent values. The actual number of the values may vary
and in some cases it can be quite big and complicated. A special
object will only make the pack1 DLL bigger without any considerable
advantage for the developers. In contrary having the information in
UDS tree allows the programmer in turn to collect and store it alone
or together with other information to all the supported formats (text,
binary, registry).
Consider also that sometimes it is convenient to write a code that
inspects such information (for example OS information) and saves the
results of its work together with the original information - as
additional values or sub-sections for example. Following such pattern
will give in the end a data structure that contains the original data
together with all the conclusions made by the application up to this
point. The freedom to pack it in permanent storages or hold it in
Application/Session variables opens many opportunities for the
application and allows it to avoid repeating some operations.
Read also the Structured configurations.
If you want to create UDS compatible trees of data or do anything more
than inspect values in a UDS returned by some method - then you will
need one ConfigFile object:
Set cf = Server.CreateObject("newObjects.utilctls.ConfigFile")
The representation of the UDS for the scripts is implemented
using two objects - VarDictionary
and NodeInfo attached to
the VarDictionary objects' Info properties. the NodeInfo
object is responsible to indicate the role of the node (the
particular VarDictionary collection in the tree) and to hold the Class
name (it can be used for any desired purpose as any other value).
Also the VarDicitonary objects used as nodes are configured to fit
the best behavior for the case - to avoid any complications when
creating UDS you should use the ConfigFile.CreateSection and
CreateRecord methods to create new VarDictionary nodes instead of
creating VarDicitonary objects directly. These methods will attach
the appropriate NodeInfo to the object and configure its behavior.
So creating a new UDS with a few values and one subsection will look
like this:
Set root = cf.CreateSection
root.Add "Record1", cf.CreateRecord
root("Record1").Add "Value1", CStr(some_var_or_expression)
root("Record1").Add "Value2", CLng(some_var_or_expression)
root.Add "Record2",cf.CreateRecord
root("Record2").Add "", CStr(esxpression)
root.Add "SubSection", cf.CreateSection
root("SubSection").Add "Record1", cf.CreateRecord
root("SubSection")("Record1").Add "A value", CStr(expression)
Although it is possible to skip the record creation in many cases
it is not recommended. For example you can add the unnamed value of
the "Record2" using this code:
root.Add "Record2", CStr(expression)
This will add the value in the section - not packing it in a
record sub-collection. This will work correctly if you are going to
save this data but may cause usage problems if you need to add more
values to the same record later. Then they will appear as several
values all named "Record2" in the root collection.
Then indexing the root("Record2")(index) will be an error
while root("Record2") is not a collection.
When data is loaded or obtained form a method that returns UDS
all the values are packed in records so such a technique as the
above one may cause mistakes and is to be avoided unless you are not
absolutely sure what are you doing.
The above sample will result in the following text file if saved
in text format:
(string)Record1[Value1]=something
(int)Record1[Value2]=something
(string)Record2=something
{ SubSection:
(string)A value=something
} SubSection;
The text format is very convenient when you need to describe the
UDS structure expected or returned by some routine in your
application or by some object. The same structure can be saved to
binary stream but of course the binary format is effective but not
suitable for human reading. So the standard binary format of the UDS
is intended for data exchange purposes between the applications
while the text format is to be used when human reading/editing is a
must (configurations for example).
