Table Of Contents

DIST Configuration Databases

Introduction

The System database

The Listeners database

The Agents database

Schemata of the databases of DIST

The system database schema

Example system database configuration

The listeners database schema

Example listener database configuration

The agents database schema

Example agents database configuration

Prerequisites to starting DIST

Starting the adaptors

Location of adaptor executables

Requirements

Conclusion

DIST Configuration Databases

---

This chapter provides in-depth information on how to configure the NMOS component DIST, which acts as the interface between the NMOS and any third party legacy applications that can benefit from the NMOS' information about the network and its connectivity.

Introduction

You configure an NMOS application adaptor by appending the appropriate inserts to the DIST configuration file DistSchema.cfg. DIST then uses the adaptor to communicate with a particular application as necessary. Familiarize yourself with the functionality of DIST as described in Chapter 21 before reading further.

In particular, you must be familiar with the following terms:

•Subjects

•Snoopers

•Adaptors

The DIST configuration file DistSchema.cfg defines three databases, which DIST uses for its configuration and operation; these databases are the system database, the listeners database, and the agents database.

The System database

The System database (system) is used to define the initial mappings from subjects to listeners as well as define the records that are listened to. It contains two tables, the subjects table (systems.subjects) and the records table (systems.records).

The subjects table

The subjects table is used to define the complete mapping between the source, the subject, and the tag name used by the application adaptor to uniquely identify the source subject. The information contained in this table is shown below:

•The unique name of the source to listen on.

•The name of the subject to listen on.

•A serial number that will be used by the adaptor to identify the source kind, i.e., differentiate it from other adaptors.

The records table

The records table is a table populated by DIST with information that shows information about all records that pass through DIST to other domains or applications; this table is essentially for informative purposes and should never be manipulated via OQL. The information it contains is:

•The name of the domain that forwarded the received record.

•The name of the application adaptor that forwarded the received record.

•The identification number of the received record.

•The received record classification, i.e., topology or event record.

•The identification number assigned to the received record by the remote application.

The Listeners database

The listeners database (listeners) defines one table - the snoopers table (listeners.snoopers).

The snoopers table

The snoopers table adapts DIST to consume records on a defined subject. The information contained in the snoopers table is shown below:

•The unique name, which identifies the presently defined snooper.

•The name of the source subject of the records, which this snooper will listen for. It must be a valid source name defined in the system.subjects.infoName field.

•The domain on which to listen. The present snooper adapts DIST to consume records from a domain with this name.

•A preliminary filter applied to records before they are consumed by DIST.

•The name of the destination for records received by the presently defined snooper.

•A list of user-defined tags that will be appended to each record before it is sent to its final destination.

• A list of fields within the incoming record that will have the source domain added to their values. i.e. new value becomes "<value>.<domain name>", thus if EntityName field of the incoming record has a value of "minotaur.kazeem.san.com" and the source domain is "TEST", the forwarded record will have an EntityName equal to "minotaur.kazeem.san.com.TEST".

The Agents database

The agents database (agents) defines the adaptors table (agents.adaptors).

The adaptors table

The adaptors table is a complex table that defines, in totality, the name of the adaptor and its functionality. The adaptors table sequentially maps uniquely-defined serial numbers to definitions of actions sets. These define the instruction sets that will be performed at the destination for every record source type DIST is configured to listen to. A received record can be categorized as one of the following:

•Event addition—corresponds to an addition of a new event or topology element.

•Event change—corresponds to an update of an existing event or topology element.

•Event deletion—corresponds to a deletion of an existing event or topology element.

Each action set is preceded by a filter condition that must be satisfied before the corresponding action is embarked upon. The actions sets are evaluated from top to bottom. If you do not set up the filters correctly, more than one action may be performed accidentally.

---

Note That the absence of a filter condition will result in a default to the adaptor, sending an insert/add as defined in the schema.

---

The information contained in the adaptors table is shown below:

•The name of the adaptor, also used for the client IDs.

•A table map field which contains:

–A sequential list of serial numbers that will be used to map each action set object specified by the next entry in the table.

–A BaseTable field that specifies the table from which the records are being retrieved.

–A QuerySubj field that specifies the query subject used to retrieve records from the BaseTable.

•A sequential list of action sets (add, change, delete) that will be mapped with the sequential list of serial numbers previously specified.

•The complete definition of the record destinations. A sequential list of objects mapped to the appropriate serial numbers and actions sets that fully define the destinations for their corresponding received records.

Schemata of the databases of DIST

The system database schema

The schemata of the subjects and records table of the System database are shown below.

Table 23-1 Synopsis of the system database and its tables

Database name	system database: system
Database definition location	$RIV_HOME/etc/DistSchema.cfg
Fully qualified database table names	subjects table: system.subjects records table: system.records

Table 23-2 The subjects table: system.subjects 

Table column name	Properties (column constraints)	Column data type	Description
InfoName	PRIMARY KEY NOT NULL UNIQUE	Text	The unique name of the source on which to listen.
Subject	PRIMARY KEY NOT NULL	Text	The name of the subject on which to listen.
Serial		Integer	A serial number that will be used by the adaptor to identify the source kind, i.e., differentiate it from other adaptors.

Table 23-3 The records table: system.records 

Table column name	Properties (column constraints)	Column data type	Description
Domain	PRIMARY KEY NOT NULL	Text	The name of the domain that forwarded the received record.
AdaptorName	PRIMARY KEY NOT NULL	Text	The name of the application adaptor that forwarded the received record.
ItemId	PRIMARY KEY NOT NULL	Text	The identification number of the received record.
RecordType	PRIMARY KEY NOT NULL	Text	The received record classification, i.e., a topology or event record will be a reference to subjects.InfoName.
RemoteId		Long Integer	The identification number assigned to the received record by the remote application.

Example system database configuration

The following are example OQL inserts into the System database tables that are appended to the DistSchema.cfg.

Example configuration of the system.subjects table

Example inserts are shown and explained below:

insert into system.subjects values ( 'Topology','RIVERSOFT.3.0.MODEL.NOTIFY',100001 ); insert into system.subjects values ( 'Events','RIVERSOFT.3.0.EVENT.NOTIFY',100002 );

•The first insert defines a "Topology" source, identifiable by the "'RIVERSOFT.3.0.MODEL.NOTIFY" subject name, with an adaptor serial number 100001.

•The second insert defines an "Event" source, identifiable by the "'RIVERSOFT.3.0.EVENT.NOTIFY" subject name, with an adaptor serial number 100002.

The listeners database schema

The schema of the snoopers tables of the Listeners database is shown below.

Table 23-4 Synopsis of the listeners database and its tables

Database name	listeners database: snoopers
Database definition location	$RIV_HOME/etc/DistSchema.cfg
Fully qualified database table names	snoopers table: listeners.snoopers

Table 23-5 The snoopers table: listeners.snoopers 

Table column name	Properties (column constraints)	Column data type	Description
Name	PRIMARY KEY NOT NULL UNIQUE	Text	The unique name which identifies the snooper presently being defined.
Source	NOT NULL	Text	The name of the source of the records which this snooper will listen for. It must be a valid source name defined in the snoopers field of the sending domain.
Domain	NOT NULL	Text	The present snooper adapts DIST to consume records from a domain with this name.
Filter	NOT NULL	Text	A preliminary filter applied to records before they are consumed by DIST.
Destination	NOT NULL	Text	The name of the destination for records received by the presently defined snooper.
TagList		list of externally-defined object type tags	A list of user-defined tags that will be appended to each record before it is sent to its final destination.
SuffixList		list of text data type	A list of fields within the incoming record that will have the source domain added to their values. i.e. new value becomes <value>.<domain name>

Example listener database configuration

The following are example OQL inserts into the Listener database tables that are appended to the DistSchema.cfg.

Example configuration of the listener.snoopers table

Example inserts into the listeners.snoopers table for different applications are shown below:

insert into listeners.snoopers values ( 'LogTopology','Topology','JAMES','','LogFile',[{ }] ); insert into listeners.snoopers values ( 'LogEvents','Events','JAMES','','LogFile',[{ }] ); insert into listeners.snoopers values ( 'TestTopology','Topology','JAMES','', 'NocDomain', [ { Source="eval(text,'$DOMAIN')"} ] );

•The first OQL insert defines a "LogTopology"snooper that will adapt DIST to consume "Topology" records generated by the "JAMES" domain. No preliminary filter is applied to the records received from the "JAMES" domain, and no additional tags are appended to each record before it is sent to the "Logfile" destination.

•The second OQL insert defines a "LogEvents"snooper that will adapt DIST to consume "Events" records generated by the "JAMES" domain. No preliminary filter is applied to the records received from the "JAMES" domain, and no additional tags are appended to each record before it is sent to the "Logfile" destination.

•The third OQL insert defines a "TestTopology" snooper that will adapt DIST to consume "Topology" records generated by the "JAMES" domain. No preliminary filter is applied to the records received from the "JAMES" domain; however, before the record is sent to its destination, an additional field called `source' is evaluated and appended to the record.

The listeners.snoopers database schema

The schemata of the adaptors table of the Agents database is shown below.

:

Table 23-6 Synopsis of the agents database and its tables

Database name	agents database: agents
Database definition location	$RIV_HOME/etc/DistSchema.cfg
Fully qualified database table names	adaptors table: agents.adaptors

Table 23-7 The adaptors table: agents.adaptors 

Table column name	Properties (column constraints)	Column data type	Description
AdaptorName	PRIMARY KEY NOT NULL UNIQUE	Text	The name of the adaptor, is also used for client ID's.
TableMap		list of object type tags	A sequential list of serial numbers that will be used to map each action set object specified by the next entry in the table. This field includes the BaseTable field and the QuerySubj field.
FeedbackTags		list of External object type fbd	A sequential list of action sets (add, change, delete) that will be mapped with the sequential list of serial numbers previously specified.
AgentConfig		object of type config	The complete definition of the record destinations. A sequential list of objects mapped to the appropriate serial numbers and actions sets that fully define the destinations for their corresponding received records.

Example agents database configuration

The following are example OQL inserts into the Agents database tables that are appended to the DistSchema.cfg.

Example configuration of the agents.adaptors table

The structure of an insertion into the agents.adaptors table is shown below.

However, you must bear in mind a couple of rules when configuring the agents.adaptors table.

•Rule1—the number of items in each of the lists, i.e., list of tablemaps, the list of actions sets, and the list of destination definitions, must be identical.

•Rule2—the mapping of the list items is in order of position; thus, the first item of the tablemap list will be mapped with the first item of the actions set list, and they will in turn be mapped to the first item of the destination definitions list; the same applies with the second and every subsequent list item of the serial ID list.

Each item of the insertion list will now be described in order:

Insert into agents.adaptors ( AdaptorName, TableMap, FeedbackTags, AgentConfig ) values ( "AdaptorName", [ list of tablemaps (number of items in list = n ) ], [ list of action sets (number of items in list = n ). ], [ list of destination definitions (number of items in list = n ). ] );

AdaptorName

The AdaptorName is the name of the adaptor currently being defined and it must correspond with the value of the listeners.snoopers.destination field; for example if you were adapting DIST to write events to a log file then it could be called "LogFile".

List of tablemaps

The list of tablemaps consists of comma-separated list elements, where each list element is a comma-separated list of identification tags which the destination application can understand. It usually consists of an ID tag assignment that is identical to the serial number assigned in the Serial field of the system.subjects table; a BaseTable tag assignment, which defines the source table from which data is being received; and the QuerySubj field containing the subject to query in order to retrieve records from the BaseTable.

The entire list is enclosed within square brackets (which define the list), and the last item of the list does not have a terminating comma, as shown below:

[ {Id=100001}, {Id=100002}, {Id=100003}, {Id=100004} ] [ {BaseTable='MODEL', Id=100001}, {BaseTable='EVENTS', Id=100002} ]

It also follows that the number of elements in this list must equal the number of records in the systems.subjects table with unique serial numbers.

List of action sets

Similar to the serial ID list, the action set list is composed of curly bracket-enclosed list elements; the list elements are comma separated and enclosed within square brackets that effectively define the list, as shown below:

[ {list_element }, {list_element } , {list_element } ]

Each list element defines three actions:

•Add action

•Change action

•Delete action

A further structure definition of an element list, consisting of a filter and a send string, is given below:

{list_element} = { adds={ <filter>, <send_string>}, changes={ <filter>, <send_string>}, deletes={ <filter>, <send_string>} }

The filter

The filter, identifiable by the <filter> keyword, is a comparison statement enclosed in quotes that returns true or false after evaluating a specific condition. If the filter returns true, the <send_string> section is evaluated and the resulting actions are carried out. If the filter evaluates to false, then the <send_string> section is ignored and no actions are carried out.

Ideally, it follows that each section should have a different filter condition that only evaluates to true when the consumed records correspond to that section, e.g., if a topology deletion record is received, your filter conditions should be such that only the condition specified in the deletes action evaluates to true.

The filter is constructed around the attributes of the record you are trying to consume, e.g., if you are listening for topology updates, you should filter based on attributes of the master.entityByName table, while if you are listening for events you should construct your filter based on the attributes of the event record.

Example filters are shown below:

Filter="ActionType=0" Filter="ActionType=1" Filter="ActionType=2"

The example filters above determine whether a received record is an add, change, or delete by evaluating the ActionType field of the standard topology record, i.e., master.entityByName. Thus you would place the first filter in the add section, the second filter in the change section, and the third filter in the delete section.

The send string

The send string section is identified by the <send_string> keyword. In the send string section, you are effectively constructing the commands or strings that will be sent to the destination application. If the destination is a database application, you should construct SQL statements, if the destination were a log file, you would construct a message with appropriate information to write to the log file.

The send string section gives you full flexibility to construct the syntax for any destination application; however, it is your responsibility to ensure that the resulting syntax is correct.

The send string section allows you to use eval statements (see "Language Prerequisites") to extract data from various fields of the incoming record and use them in the resulting syntax that you are constructing.

Examples of the send string section are described below.

Constructing a send string to send to another NMOS domain

The following send string shows the construction of an insert statement and belongs in the add section within an element of the actions set list:

SendString="insert into master.entityByName ( RemoteId, ChangeTime, ObjectId, EntityName, PartOfName, Description, EntityType, ClassName, EntityOID, Status, Security, IsActive, CreateTime, ActionType ) values ( eval(long,'&ObjectId'), eval(time,'$TIME'), 0, eval(text, '&EntityName'), eval(text, '&PartOfName'), eval(text, '&Description'), eval(int type entityTypes, '&EntityType'), eval(text, '&ClassName'), eval(text, '&EntityOID'), eval(int type status, '&Status'), eval(text, '&Security'), eval(int type boolean, '&IsActive'), eval(time, '&CreateTime'), eval(int type actions, '&ActionType') );"

The following shows the construction of an update statement and belongs in the change section within an element of the actions set list:

SendString="update master.entityByName set ChangeTime = eval(time, '$TIME'), ObjectId = eval(long,'&ObjectId'), Address = eval(list type text, '&Address'), Description = eval(text, '&Description'), EntityType = eval(int type entityTypes, '&EntityType'), ClassName = eval(text, '&ClassName'), EntityOID = eval(text, '&EntityOID'), Status = eval(int type status, '&Status'), Security = eval(text, '&Security'), RelatedTo = eval(list type text, '&RelatedTo'), Contains = eval(list type text, '&Contains'), IsActive = eval(int type boolean, '&IsActive'), CreateTime = eval(time, '&CreateTime'), ActionType = eval(int type actions, '&ActionType') where ObjectId = eval(long,'&ObjectId');"

The corresponding send string for the construction of a delete statement (that belongs in the delete section within an element of the actions set list) is:

SendString="delete from master.entityByName where ObjectId = eval(long,'&ObjectId');"

Constructing a send string to send to a database application

Send strings for database applications are almost identical to send strings constructed for NMOS domain destinations.

The following example demonstrates a typical send string in a change action for a database destination

---

Note That for some adaptors this may be a sendlist of items to send to a destination application.

---

SendString="update MODEL set ChangeTime = eval(time, '$TIME'), Description = eval(text, '&Description'), EntityType = eval(int type entityTypes, '&EntityType'), ClassName = eval(text, '&ClassName'), EntityOID = eval(text, '&EntityOID'), Status = eval(int type status, '&Status'), Security = eval(text, '&Security'), IsActive = eval(int type boolean, '&IsActive'), ActionType = eval(int type actions, '&ActionType') where ObjectId = eval(long,'&ObjectId');"

List of destination definitions

The list of destination definitions consists of a comma-separated list of name/value pairs that defines the destinations for the corresponding tablemaps and actions sets. They must always be sufficient to define the final destination for the records it refers to.

Like the other lists, the whole destination definition list is enclosed within square brackets (which define the list) and the last item of the list does not have a terminating comma as shown below.

Examples of list destination definitions are shown for example serial IDs 100001 and 1000002 below:

[ { LogFile="eval(text,'$RIV_HOME')/logs/distLog.top" }, { LogFile="eval(text,'$RIV_HOME')/logs/distLog.events" } ]

For more information on the eval syntax see"Language Prerequisites."

Another example of a list definition for NOC domain, for example serial IDs 100001 and 1000002, is shown below:

[ { Domain='NOC', SendSubject='RIVERSOFT.3.0.MODEL.QUERY' }, { Domain='NOC', SendSubject='RIVERSOFT.3.0.EVENT.QUERY' } ]

Prerequisites to starting DIST

You must perform the following steps before you can successfully utilize DIST to communicate with an external application:

---

Step 1 Configure the activities of DIST for every application you wish to communicate with by appending the necessary inserts to DistSchema.cfg.

Step 2 Start riv_dist from the command-line, which enables the configuration specified by step one to be read in.

Step 3 Execute the necessary adaptor from the command line, ensuring that the parameters are correctly specified.

---

Starting the adaptors

To start the adaptors use the following syntax (currently, there is a different executable for each adaptor):

<ADAPTOR> -domain <DOMAIN_NAME> -id <ADAPTOR_ID>

system.subjects.infoName	The adaptor executable; in the syntax shown above the agents is the riv_da_riv2riv executable responsible for enabling communication with other NMOS domains. The executables currently available are shown below.
agents	The name of the NMOS domain that you wish the adaptor to run under. It is possible to have multiple adaptors components running for every running domain.
agents.adaptors	The unique name assigned to the adaptor during the configuration of DistSchema.cfg. The <ADAPTOR> must be identical to the destination field of the <ADAPTOR>teners.snoopers table which is itself identical to the AdaptorName field of the agents.adaptors table. In the above syntax the <ADAPTOR_ID> is equal to `NocDomain'.

Table 23-8 Adaptor executables currently available with the NMOS

Adaptor executable	Description
riv_da_riv2riv	Adaptor that enables multiple NMOS domains to listen to each other.
riv_da_riv2sybase	Adaptor that enables the NMOS to communicate and send consumed subjects to a SYBASE database.
riv_da_riv2oracle	Adaptor that enables the NMOS to communicate and send consumed subjects to an ORACLE database.
riv_da_riv2log	Adaptor that enables the NMOS to send consumed subjects to a log file.
riv_da_riv2trap	Adaptor that sends fields tagged on to a SNMP V1 trap to a specified IP address on the network.

Location of adaptor executables

Like all NMOS executables with the exception of the discovery subsystem executables, the adaptor executables are located in the $RIV_HOME/bin directory.

Requirements

You are required to run one adaptor for each database, NMOS domain, application etc., that you wish to communicate with. For example if you wish to communicate with two domains, you will need to run two riv_da_riv2riv adaptors, one for each domain. The same applies to all other applications.

You can run many adaptors simultaneously, each adapting DIST to communicate with a different application.

Conclusion

This chapter has explained how to configure DIST, the distribution engine, so that it launches external processes.

The next chapter provides you with very useful information that should be considered when interpreting the language syntax in the remaining chapters of this guide.