OS2.GURU - Using XObject for Configuration Files

This report covers certain aspects of working with configuration files (ini-files, profiles, registry, etc). Against the background of common ways of organizing such files, we’ll review the language for informational (non-executable) objects description (as well as its OS/2 API), that has been developed for specific task (drilling training simulator for OS/2), but is pretty universal.

The most primitive description method "parameter"="value" is commonly used and well known.

This method has a drawback: there's no way to syntactically separate different objects' descriptions within one file. Still, it's easy to implement and in many cases suitable. But not always possible.

Windows ini-files (Windows 3.11) introduced a slight improvement: sections. Named sections allow using structured descriptions and query description elements using two parameters "section name"-"parameter name", which is more convenient.

The disadvantages here are: syntactical indifference when dealing with variable number of entries within one section, and no nesting for section (which may be useful, since not all informational objects are linear). Of course, this may be implemented, but particular implementation will be a developer's quick wit, rather than the result of syntactical structure.

The next step in the evolution of description scripts is registry (Windows 9x or higher), and OS/2 ini-files. Both allow tree structure (nesting) and storing objects of any type by using binary objects (defined by those who use them).

To criticize existing implementations of such resource (it’s WINPRF.DLL in OS/2), we have to take into account requirements to the configuration files syntax in general.

As mentioned before, the views expressed here are the result of working on scenario maintenance subsystem for drilling training simulator. A scenario for such training simulator contains all parameters, that define the initial state of the drill and borehole. It describes numerous independent parameters — hardware descriptors, rock and geological section descriptors as well as possible anomalies, scattered all over the borehole (to entertain the trainee) etc.

The scenarios are to be created by the end users of the product. Therefore the descriptions and tools to create them have to be intuitive enough for non-programmer to use. Since the same hardware descriptions may be used in many scenarios, they has to be defined separately and linked from within the scenario. There are means provided for printing scenarios in good-looking readable form, to use them as operating instructions.

These requirements resulted the creation of informationally associated software tools:

Change in the description of any object required correcting the software implementation of interconnected objects, which is not very convenient. This problem became obvious when developers have realized that simplifying a number of descriptions was a mistake and it would be nice to complement them.

Problems described above serve as a good criticism when it comes to using Profile API for maintaining complex configurations.

These requirements are fulfilled in our configuration files subsystem. It offers syntax, base objects, WPS-object for visualization and printing and an API for their software-based writing and reading.

Any configuration file is rendered as a number of fields of certain types. Types are either simple or compound. Thus, configuration file itself is an object of a certain compound type (class).

A syntax we offer for describing such classes operates with keywords, literals and comments.

DoubleField = .

string title = "" // name, displayed in the edit dialog or when printing
double value = 0 // field value
double min = 0    // minimum available double value
double max = 0    // maximum available double value
double coef = 0   // conversion factor (useful when editing certain
                  // units of measuring, and using other)
double delta = 0 // auto-change pitch in the edit dialog
int decimals = 0 // number of symbols after decimal point,
// displayed when editing and printing
.

ReferenceField class allows using multiple settings in one if, for example, software product consists of multiple tasks, and each has own configuration with individual and shared part. And vice versa, if the settings of one object are used by many others.

ObjectListField class allows creating lists of reference objects if, for example, list of persons in the group or list of different network connections has specific settings.

When displaying dialog ObjectListField in the list there are values of element "string title" objects' descriptions, or value of element "name|value", is there's StringField name element in the description of reference object.

For example, that's how class definition of the bottom-hole engine description looks like (on russian):

DEngine drill=.
string title="........ ........."
DoubleField diam_zd =. title="....... ............." coef=0.001 decimals=1 delta=0.1 min=30 max=400.
DoubleField leng_zd =. title="..... ............." coef=1 decimals=2 delta=0.01 max=50.
DoubleField q_zd =. title="...... ............." coef=1000 decimals=1 delta=0.1 min=30 max=400.
DoubleField dens_zd =. title="......... ........" coef=1000 decimals=2 delta=0.01 min=0.8 max=2.5.
DoubleField loss_px_zd =. title="...... ........ .. ........ ...." coef=98100 min=1 max=200.
DoubleField freq_nx_zd =. title="....... ........ .. ........ ...." coef=0.01666 min=10 max=999.
DoubleField loss_pt_zd =. title="...... ........ ... .........." coef=98100 min=1 max=200.
DoubleField moment_t_zd=. title="......... ......" coef=10 min=1 max=1500.
ComboToggleField drop =.

And that's the description for specific bottom-hole engine (/* comment */ in the first line is needed to interpret text as XObject):

This syntax demonstrates the possibility to make changes to each object and additional fields: min, max etc.

We've created WPS-object that renders specifically organized parts of class descriptions as its property pages. To do so, we add special descriptors to class description: "group" with names "pages" (for dialog) and "sections" for printing.

group pages = .

namedgroup = . // dialog page description

title = "%MajorTab" // symbol % means MajorTab
status = "Subtitle"
elements = .

string = "name 1" // element of the class
string = "name 2"
...
string = "name N"
.

namedgroup = . // second page of the dialog

title = "MinorTab pages"
status = "Subtitle"
elements = .

string = "name 1"
string = "name 2"
...
string = "name N"
.

... // other pages of the dialog
.

This is the part of description of bottom-hole engine (DEngine) class that refers to dialog and it's result:

Note the second tab — "Type". It is always created and allows choosing way (text/binary) of saving. The last one allows easily edit any field of object using text editor. And vice versa, any object may be created in the text editor and then saved as binary. When saving in binary, object saves only differences from base description. The other elements of description are inherited, that's why the size of binary XObject file is much less than the text one.

To describe object printing we use similarly organized group sections, and that's what we get when printing:

To print the object use the menu, or simply drag its icon onto printer's icon (folder). Here's the example output after printing one object. The same object, as ReferenceField inside the scenario, looks as follows:

To use this configuring system, in the root or in the AMT_PATH environment variable directory one has to create file config.ini of the following content (we use our training simulator configuration as an example here):

/* AMT */
group Config = .

string customer = "Customer Corp" // for (C)Copyright printout
int loglevel = 0                             // -1 full debug output to \xobject.log
                                                   // 0 no error messages output
                                                   // 1 output warnings and error messages
group classes = .

string = "common.ini" // description of the common classes
string = "DSTclass.ini" // drilling training simulator classes description
string = "KRSclass.ini" // borehole extensive repairs training simulator classes description
.

This file is used by WPS-object AMTWPSXObject that implements dialogs and configuration objects printing. This object is associated with AMT extension.

Copy all XObject support dynamic libraries into LIBPATH available in environment variable. And using this Rexx script, perform the registration:

/*********************************************************************/
/* XObject registration utility */
/*********************************************************************/
Call RxFuncAdd 'SysLoadFuncs', 'REXXUTIL', 'SysLoadFuncs'
Call SysLoadFuncs
Say 'AMT XObjects to be registered'
rc=SysRegisterObjectClass('AMTWpsObject', 'amtwpso')
if rc then say 'AMTWpsObject registered'
else say 'AMTWpsObject cannot be registered'

When programming, it is required to read descriptions of used classes - for example, all config.ini and all files mentioned there, or only required for specific task. The following text gives and example of reading all classes libraries, described in config.ini:

#include "common.h"

XObject *o_config; // for the script
// function initializes XObject predefined classes subsystem
// and returns number of classes in the library
int InitXClasses(void)
.
char buf[256]="", *str;
char *amtPath = getenv(AMT_PATH);
int num=0;

XOBJECT_INITIALIZE

// loading classes libraries
buf[0] = 0;
if (amtPath) strcat(buf, amtPath);
strcat(buf, "\\");
strcat(buf, AMT_CONFIG);
o_config = XObject::loadObject(buf);
if (!o_config)
return 0;

o_config = o_config->getGroupElement("classes");
for (int i = 0; igetGroupSize(); i++ )

.
str = o_config->getGroupElement(i)->getStringValue();
if (str)

.
buf[0] = 0;
if (amtPath)
strcat(buf, amtPath);
strcat(buf, "\\");
strcat(buf, str);
num += XObject::loadClasses(buf);
.

return num;
.

The following lines represent the idea of getting certain class elements of training simulator scenario:

.


...


o_main=XObject::loadObject(file_name);          
//
loading required scenario file


   if
(!o_main)


     
return
1;                               
//
error reading scenario - running in the test mode


...


 o_sub
= o_main->getGroupElement("title");


Name=strdup(o_sub->getStringValue());




 o_sub
= o_main->getGroupElement("model_type");


model_type=o_sub->getIntValue();               
//
training simulator model type (number)




 o_sub
= o_main->getGroupElement2("mode|value"); // using
compound name here


mode=o_sub->getIntValue();
                 
   //
training simulator model type (number)




//
if the element is link, using method GetValue(name),


//
it will load link script


o_ref=o_main->getValue("derrik");              
// load drill description


//
or, in such a way


//
o_ref=XObject::loadObject(o_main->getGroupElement2("derrik|value")->getStringValue();




//
calculate g_kv parameter value using CI units of measurement


g_kv=o_ref->getGroupElement2("g_kv|value")->getDoubleValue()
* o_ref->getGroupElement2("g_kv|coef")->getDoubleValue();


.

XObject methods also allow saving information, obtained by software. This simplifies visualization, printing and maintenance.

class
_Export XObject .


public:


 static
void setLogLevel(int);


 static
int log(char*, ...);


 static
int log(int, char*, ...);


 static
int logObject(XObject*, char* = NULL);


 static
void logClasses();




 static
void initClass();


 static
void unInitClass();


 static
int loadFile(char*, char**, int*);


 static
int saveFile(char*, char*, int);


 static
XObject* getInstance(char*, char*, int = FLAGS_NORMAL, int =-1);


 static
XObject* getInstanceText(char*, int*, int =-1);


 static
XObject* getInstanceBin(char*, int*, int = -1);


 static
int loadClasses(char*);


 static
XObject* loadObject(char*);


 static
int saveObject(char*, XObject*);


...


public:


 static
int getClassNum();


 static
char* getClassName(int);


...


public:


 virtual
~XObject();


 int isVoid();


 int isInteger();


 int isDouble();


 int isString();


 int isComplex();


 int isGroup();


 int isObject();


 int isObject(char*);


 int isBasic();




 virtual
XObject* clone();


 int initFrom(XObject*);




 char* getName();


 int setName(char* n);


 char* getClassName();


 int getClassVersion();




 int getFlags();


 int setFlags(int);


 void flagSet(int);


 void flagClear(int);


 int flagIsSet(int);




 int getSizeBin();


 int getSizeText();




 int getIntValue();


 int setIntValue(int);




 double getDoubleValue();


 int setDoubleValue(double);




 char* getStringValue();


 int getStringSize();


 int getStringLength();


 int setStringSize(int);


 int setStringValue(int, char*);


 int setStringValue(char*);




 int getGroupSize();


 XObject* getGroupElement(int);


 XObject* getGroupElement(char*);


 XObject* getGroupElement2(char*);


 int addGroupElement(XObject*);


 int removeGroupElement(int);


 int removeGroup();




 int loadBinFile(char*);


 int readText(char*, int);


 int readBin(char*, int);


 int writeBin(char*, int);


 int writeText(char*, int, int = 0);




 virtual
XObject* getValue();


 virtual
int show(int);


 virtual
int print(int);


 virtual
int html(int);


//
misc


 static
char* strPrintInteger(char*, int, int);


 static
char* strPrintDouble(char*, double, int, int);


 static
char* strPrintString(char*, char*, int, int*);


 static
char* strPrintStringEsc(char*, char*, int, int*);


...


.;

Welcome to OS2.GURU site! (eComStation.RU)

eComStation.RU

How to buy
russian OS/2 apps?

The concept of
OS/2 development

Using XObject for Configuration Files

Artikel

eComStation.RU ru · en · de · es · it · pt · cz · pl · fr	OS/2 is a greatly different operating system for PC (ArcaOS, eComStation, IBM OS/2 Warp) Applications, news, reviews, support of users, hardware, questions and answers.