NAME

ExampleRanCollector - Simple example implementation of a collector for Radio Area Network (RAN) data


SYNOPSIS

    #
    # Run using:
    # perl $NCHOME/precision/collectors/perlCollectors/ExampleRan/main.pl 
    #       -port <portNumberToBeQueried>
    #       [-file <optionalExampleCsvFile> ]
    #
    # This is instantiated in ExampleRan/main.pl using the calls below.
    # For details of associated functions, see that file.
    # Instantiate an instance of this Collector, using options 
    # provided earlier
    $g_Collector = new ExampleRanCollector(
                debug => $options{debug},
                file => $options{file}
    );
    # Set up an XML RPC server, g_XmlRpcServer 
    CreateXmlRpcServer( $options{port} );
    # Load data into the collector
    $g_Collector->LoadData( 1 );   # data source 1
    # Kick off the XML RPC Server to listen for queries from ITNM
    $g_XmlRpcServer->handle();     # listen for RPC calls. never returns


DESCRIPTION

This provides a simple example RAN collector implementation. The expectation is that genuine collector implementations will either query an EMS directly, or load a CSV or XML file in a format defined by the EMS vendor or user. The purpose of this example collector is to demonstrate how to use the collector framework to import such data.

Two distinct illustrations are supplied - the collector can be run with or without an input CSV file (such as the supplied ExampleData.csv file).

To use a configurable input CSV file as the data source, run this collector using:

    cd $NCHOME/precision/collectors/perlCollectors/ExampleRan/
    #
    # The port number is the port to be specified in either the ITNM
    # DiscoCollectorFinderSeeds.cfg file or when using the 
    # ncp_query_collector.pl tool
    #
    perl main.pl -port 8081 -file ExampleData.csv

The format expected for each type is illustrated both in the ExampleData.csv file and in the brief documentation for the methods of this module.

To use a very simple hard-coded example, supplied to demonstrate the basics, instead of using an input source, run without the '-file' argument:

    perl main.pl -port 8081 -file ExampleData.csv

new()

Instantiates the module.

Arguments

This accepts an optional hash with the fields below.

file Input CSV file to use as the data source.

debug Turn debug on or off by setting this to 0 or 1

LoadData()

Parses the input file, if one was supplied when this module was instantiated, or loads hard-coded data.

This delegates to either parseFile() or HardCodedExample().

This is called from main.pl both at initialisation and if the UpdateData() XML RPC call is received.

GetRanData()

Returns the RAN content of the store for a single device as an ITNM XML-RPC compatible XML response string.

This is called from main.pl if the GetRanData() XML RPC call is received.

HardCodedExample()

Set up a very simple data store containing a single GSM cell, a single base station controller and 2 associated base stations.

parseFile()

Parse the input file. Note that for simplicity and clarity, this does not use the NCP::XSV.pm parsing capabilities, but that could provide greater flexibility in a full collector implementation.

This uses the following rules:

The following relationships are implicit from the format of the data:

The following are requirements based upon the simplistic parsing:

parseBsc()

Parse a line from the input file with an initial 'BSC' token, followed by:

IP | DNS | BSCID | TechnologyType | MCC | MNC | LOCATION | LAT | LONG | REGION

RAN location data is associated with the device if data is given in the MCC and MNC fields.

parseBts()

Parse a line from the input file with an initial 'BTS' token, followed by:

IP | DNS | BTSID | TechnologyType | LOCATION | LAT | LONG | REGION

The BTS is associated with the BSC that was last defined above it (and no RNC can be defined between the 2).

parsePcu()

Parse a line from the input file with an initial 'PCU' token, followed by:

IP | DNS | PCUID | TechnologyType | LOCATION | LAT | LONG | REGION

The PCU is associated with the BSC that was last defined above it (and no RNC can be defined between the 2).

parseRnc()

Parse a line from the input file with an initial 'RNC' token, followed by:

IP | DNS | RNCID | TechnologyType | MCC | MNC | LOCATION | LAT | LONG | REGION

RAN location data is associated with the device if data is given in the MCC and MNC fields.

parseNodeB()

Parse a line from the input file with an initial 'NODEB' token, followed by:

IP | DNS | NODEBID | TechnologyType | LOCATION | LAT | LONG | REGION

The BTS is associated with the RNC that was last defined above it (and no BSC can be defined between the 2).

parseSgsn()

Parse a line from the input file with an initial 'SGSN' token, followed by:

IP | DNS | SGSNID | TechnologyType | MCC | MNC | LOCATION | LAT | LONG | REGION

RAN location data is associated with the device if data is given in the MCC and MNC fields.

parseGgsn()

Parse a line from the input file with an initial 'GGSN' token, followed by:

IP | DNS | GGSNID | TechnologyType | AccessPointName | MCC | MNC | LOCATION | LAT | LONG | REGION

RAN location data is associated with the device if data is given in the MCC and MNC fields.

parseMgw()

Parse a line from the input file with an initial 'MGW' token, followed by:

IP | DNS | MGWID | MCC | MNC | LOCATION | LAT | LONG | REGION

RAN location data is associated with the device if data is given in the MCC and MNC fields.

parseMsc()

Parse a line from the input file with an initial 'MSC' token, followed by:

IP | DNS | MGWID | TechnologyType | MSCType | MCC | MNC | LOCATION | LAT | LONG | REGION

RAN location data is associated with the device if data is given in the MCC and MNC fields.

parseMss()

Parse a line from the input file with an initial 'MSS' token, followed by:

IP | DNS | MGWID | MCC | MNC | LOCATION | LAT | LONG | REGION

RAN location data is associated with the device if data is given in the MCC and MNC fields.

parseTransceiver()

Parse a line from the input file with an initial 'TRX' token, followed by:

TRXID | TransceiverType | CellId

The TRX is contained by the device that was last defined above it (which is expected, but not mandated, to be a NODEB or BTS).

parseNodeBLocalCell()

Parse a line from the input file with an initial 'NBLC' token, followed by:

LOCALCELLID | TechnologyType | UtranCellId

The NBLC is contained by the device that was last defined above it (which is expected, but not mandated, to be a NODEB).

parseInterface()

Parse a line from the input file with an initial 'IFACE' token, followed by:

IfType | IP | InterfaceId | RemoteDeviceName | RemoteInterfaceId | Topology | NSEI

The IFACE is contained by the device that was last defined above it.

If remote data exists, and refers to a known device, a connection is generated at the specified topology (or Layer2 if no topology is listed)

parseSector()

Parse a line from the input file with an initial 'IFACE' token, followed by:

SECTORID | BeamDirection | SectorHeight

The SECTOR is hosted by the TRX that was last defined above it.

parseGsmCell()

Parse a line from the input file with an initial 'GSMCELL' token, followed by:

CELLID | TechnologyType | broadcastPower | broadcastScramblingCode | NCC | BCC | msTxPower | rxLevAccessMin | TSC | hopSeqNum | RACC | MCC | MNC | LAC | RAC

RAN location data is associated with the cell if data is given in the MCC, MNC, LAC and RAC fields.

parseUtranCell()

Parse a line from the input file with an initial 'UTRANCELL' token, followed by:

CELLID | broadcastPower | broadcastScramblingCode | primaryScramblingCode | primarySchPower | secondarySchPower | maxTransmissionPower | uarfcnDL | uarfcnUL | MCC | MNC | LAC | RAC

RAN location data is associated with the cell if data is given in the MCC, MNC, LAC and RAC fields.


See also:

Collector::Store::RanDataStore.pm
Collector::Store.pm
Collector::Collector.pm


AUTHOR

Stephane Millar


COPYRIGHT AND LICENSE

Licensed Materials - Property of IBM

"Restricted Materials of IBM"

5724-S45

(C) Copyright IBM Corp. 1997, 2012

IBM Tivoli Network Manager for Optical

THE SAMPLE IS PROVIDED "AS IS," WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT OF PATENTS, COPYRIGHTS OR OTHER PROPRIETARY RIGHTS OF OTHERS. NEITHER THE AUTHOR NOR IBM WARRANT THAT THE FUNCTIONS, ROUTINES, AND DATA CONTAINED IN, OR GENERATED AS A RESULT OF THE SAMPLES, WILL MEET YOUR REQUIREMENTS OR BE ERROR-FREE. The entire risk related to the quality and performance of the Samples is with you. In the event that there is any defect, you assume the entire cost of all necessary services, repair or correction. IN NO EVENT WILL THE AUTHOR OR IBM BE LIABLE TO YOU OR TO ANY THIRD PARTY FOR ANY DIRECT OR INDIRECT DAMAGES (INCLUDING, WITHOUT LIMITATION, LOST PROFITS, LOST SAVINGS OR OTHER INCIDENTAL OR CONSEQUENTIAL DAMAGES) ARISING OUT OF THE USE OR INABILITY TO USE THE SAMPLE, EVEN IF THE AUTHOR OR IBM HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Some jurisdictions do not allow the exclusion of implied warranties or the limitation or exclusion of liability for incidental or consequential damages, so some of the above may not apply to you.